mirror of
https://github.com/FrankerFaceZ/FrankerFaceZ.git
synced 2025-08-06 22:30:57 +00:00
Documents public interfaces for class TwitchData in JSDoc format (#772)
This commit is contained in:
LukeBoland
GitHub
parent
8e73b6fb87
commit
4876f2748f
1 changed files with 280 additions and 2 deletions
|
|
@ -41,6 +41,18 @@ const ALGOLIA_LANGUAGES = {
|
|||
'zh-tw': 'zh-tw'
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the Algolia Language code for a given locale
|
||||
* @function getAlgoliaLanguage
|
||||
*
|
||||
* @param {string} locale - a string representation of a locale
|
||||
* @returns {string} the Algolia Language code for the given locale
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(getAlgoliaLanguage('en'));
|
||||
*/
|
||||
|
||||
function getAlgoliaLanguage(locale) {
|
||||
if ( ! locale )
|
||||
return ALGOLIA_LANGUAGES.en;
|
||||
|
|
@ -53,6 +65,12 @@ function getAlgoliaLanguage(locale) {
|
|||
return ALGOLIA_LANGUAGES[locale] || ALGOLIA_LANGUAGES.en;
|
||||
}
|
||||
|
||||
/**
|
||||
* TwitchData is a container for getting different types of Twitch data
|
||||
* @class TwitchData
|
||||
* @extends Module
|
||||
*/
|
||||
|
||||
export default class TwitchData extends Module {
|
||||
constructor(...args) {
|
||||
super(...args);
|
||||
|
|
@ -145,6 +163,20 @@ export default class TwitchData extends Module {
|
|||
// Categories
|
||||
// ========================================================================
|
||||
|
||||
/**
|
||||
* Queries Apollo for categories matching the search argument
|
||||
* @function getMatchingCategories
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {string} query - query text to match to a category
|
||||
* @returns {Object} a collection of matches for the query string
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getMatchingCategories("siege"));
|
||||
*/
|
||||
|
||||
async getMatchingCategories(query) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/search-category.gql'),
|
||||
|
|
@ -158,6 +190,21 @@ export default class TwitchData extends Module {
|
|||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries Apollo for category details given the id or name. One of (id, name) MUST be specified
|
||||
* @function getCategory
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the category id number (can be an integer string)
|
||||
* @param {string|null|undefined} name - the category name
|
||||
* @returns {Object} information about the requested stream
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getCategory(null, 'Just Chatting'));
|
||||
*/
|
||||
|
||||
async getCategory(id, name) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/category-fetch.gql'),
|
||||
|
|
@ -172,6 +219,20 @@ export default class TwitchData extends Module {
|
|||
// Users
|
||||
// ========================================================================
|
||||
|
||||
/**
|
||||
* Queries Apollo for users matching the search argument
|
||||
* @function getMatchingUsers
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {string} query - query text to match to a username
|
||||
* @returns {Object} a collection of matches for the query string
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getMatchingUsers("ninja"));
|
||||
*/
|
||||
|
||||
async getMatchingUsers(query) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/search-user.gql'),
|
||||
|
|
@ -185,6 +246,21 @@ export default class TwitchData extends Module {
|
|||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries Apollo for user details given the id or name. One of (id, login) MUST be specified
|
||||
* @function getUser
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the user id number (can be an integer string)
|
||||
* @param {string|null|undefined} login - the username
|
||||
* @returns {Object} information about the requested user
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getUser(19571641, null));
|
||||
*/
|
||||
|
||||
async getUser(id, login) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/user-fetch.gql'),
|
||||
|
|
@ -194,6 +270,21 @@ export default class TwitchData extends Module {
|
|||
return get('data.user', data);
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries Apollo for the logged in user's relationship to the channel with given the id or name. One of (id, login) MUST be specified
|
||||
* @function getUserSelf
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the channel id number (can be an integer string)
|
||||
* @param {string|null|undefined} login - the channel username
|
||||
* @returns {Object} information about your status in the channel
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getUserSelf(null, "ninja"));
|
||||
*/
|
||||
|
||||
async getUserSelf(id, login) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/user-self.gql'),
|
||||
|
|
@ -203,6 +294,21 @@ export default class TwitchData extends Module {
|
|||
return get('data.user.self', data);
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries Apollo for the requested user's latest broadcast. One of (id, login) MUST be specified
|
||||
* @function getLastBroadcast
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the channel id number (can be an integer string)
|
||||
* @param {string|null|undefined} login - the channel username
|
||||
* @returns {Object} information about the requested user's latest broadcast
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getLastBroadcast(19571641, null));
|
||||
*/
|
||||
|
||||
async getLastBroadcast(id, login) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/last-broadcast.gql'),
|
||||
|
|
@ -216,6 +322,21 @@ export default class TwitchData extends Module {
|
|||
// Broadcast ID
|
||||
// ========================================================================
|
||||
|
||||
/**
|
||||
* Queries Apollo for the ID of the specified user's current broadcast. This ID will become the VOD ID. One of (id, login) MUST be specified
|
||||
* @function getBroadcastID
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the channel id number (can be an integer string)
|
||||
* @param {string|null|undefined} login - the channel username
|
||||
* @returns {Object} information about the current broadcast
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getBroadcastID(null, "ninja"));
|
||||
*/
|
||||
|
||||
async getBroadcastID(id, login) {
|
||||
const data = await this.queryApollo({
|
||||
query: await import(/* webpackChunkName: 'queries' */ './data/broadcast-id.gql'),
|
||||
|
|
@ -233,6 +354,20 @@ export default class TwitchData extends Module {
|
|||
// Polls
|
||||
// ========================================================================
|
||||
|
||||
/**
|
||||
* Queries Apollo for information about the specified poll.
|
||||
* @function getPoll
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string} poll_id - the poll id number (can be an integer string)
|
||||
* @returns {Object} information about the specified poll
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getPoll(1337));
|
||||
*/
|
||||
|
||||
async getPoll(poll_id) {
|
||||
const data = await this.queryApollo({
|
||||
query: await import(/* webpackChunkName: 'queries' */ './data/poll-get.gql'),
|
||||
|
|
@ -244,6 +379,27 @@ export default class TwitchData extends Module {
|
|||
return get('data.poll', data);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new poll
|
||||
* @function createPoll
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string} channel_id - the channel id number (can be an integer string)
|
||||
* @param {string} title - the poll title
|
||||
* @param {string[]} choices - an array of poll choices
|
||||
* @param {Object} [options] - an object containing poll options
|
||||
* @param {int} [options.bits=0] - how many bits it costs to vote
|
||||
* @param {int} [options.duration=60] - how long the poll will be held for, in seconds
|
||||
* @param {bool} [options.subscriberMultiplier=false] - whether to activate subsriber 2x multiplier
|
||||
* @param {bool} [options.subscriberOnly=false] - whether only subscribers may vote
|
||||
* @returns {Object} poll data
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.createPoll(19571641, "Pick an option:", ["One", "Two", "Three"], {bits: 10, duration: 120, subscriberMultiplier: false, subscriberOnly: true}));
|
||||
*/
|
||||
|
||||
async createPoll(channel_id, title, choices, options = {}) {
|
||||
if ( typeof title !== 'string' )
|
||||
throw new TypeError('title must be string');
|
||||
|
|
@ -277,6 +433,20 @@ export default class TwitchData extends Module {
|
|||
return get('data.createPoll.poll', data);
|
||||
}
|
||||
|
||||
/**
|
||||
* Place specified poll into archive
|
||||
* @function archivePoll
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} poll_id - the poll id number (can be an integer string)
|
||||
* @returns {Object} information about the specified poll
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.archivePoll(1337));
|
||||
*/
|
||||
|
||||
async archivePoll(poll_id) {
|
||||
const data = await this.mutate({
|
||||
mutation: await import(/* webpackChunkName: 'queries' */ './data/poll-archive.gql'),
|
||||
|
|
@ -288,6 +458,20 @@ export default class TwitchData extends Module {
|
|||
return get('data.archivePoll.poll', data);
|
||||
}
|
||||
|
||||
/**
|
||||
* Terminate specified poll
|
||||
* @function terminatePoll
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string|null|undefined} poll_id - the poll id number (can be an integer string)
|
||||
* @returns {Object} information about the specified poll
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.archivePoll(1337));
|
||||
*/
|
||||
|
||||
async terminatePoll(poll_id) {
|
||||
const data = await this.mutate({
|
||||
mutation: await import(/* webpackChunkName: 'queries' */ './data/poll-terminate.gql'),
|
||||
|
|
@ -304,6 +488,20 @@ export default class TwitchData extends Module {
|
|||
// Stream Up-Type (Uptime and Type, for Directory Purposes)
|
||||
// ========================================================================
|
||||
|
||||
/**
|
||||
* Queries Apollo for stream metadata. One of (id, login) MUST be specified
|
||||
* @function getStreamMeta
|
||||
* @memberof TwitchData
|
||||
*
|
||||
* @param {int|string|null|undefined} id - the channel id number (can be an integer string)
|
||||
* @param {string|null|undefined} login - the channel name
|
||||
* @returns {Promise} information about the requested stream
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* this.twitch_data.getStreamMeta(19571641, null).then(function(returnObj){console.log(returnObj);});
|
||||
*/
|
||||
|
||||
getStreamMeta(id, login) {
|
||||
return new Promise((s, f) => {
|
||||
if ( id ) {
|
||||
|
|
@ -522,6 +720,20 @@ export default class TwitchData extends Module {
|
|||
this._loadTags();
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries Apollo for tag information
|
||||
* @function getTag
|
||||
* @memberof TwitchData
|
||||
*
|
||||
* @param {int|string} id - the tag id
|
||||
* @param {bool} [want_description=false] - whether the description is also required
|
||||
* @returns {Promise} tag information
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* this.twitch_data.getTag(50).then(function(returnObj){console.log(returnObj);});
|
||||
*/
|
||||
|
||||
getTag(id, want_description = false) {
|
||||
// Make sure we weren't accidentally handed a tag object.
|
||||
if ( id && id.id )
|
||||
|
|
@ -544,6 +756,21 @@ export default class TwitchData extends Module {
|
|||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Queries the tag cache for tag information, queries Apollo on cache miss
|
||||
* @function getTagImmediate
|
||||
* @memberof TwitchData
|
||||
*
|
||||
* @param {int|string} id - the tag id
|
||||
* @param {getTagImmediateCallback} callback - callback function for use when requested tag information is not cached
|
||||
* @param {bool} [want_description=false] - whether the tag description is required
|
||||
* @returns {Object|null} tag information object, or on null, expect callback
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getTagImmediate(50));
|
||||
*/
|
||||
|
||||
getTagImmediate(id, callback, want_description = false) {
|
||||
// Make sure we weren't accidentally handed a tag object.
|
||||
if ( id && id.id )
|
||||
|
|
@ -562,6 +789,28 @@ export default class TwitchData extends Module {
|
|||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Callback function used when getTagImmediate experiences a cache miss
|
||||
* @callback getTagImmediateCallback
|
||||
* @param {int} tag_id - The tag ID number
|
||||
* @param {Object} tag_object - the object containing tag data
|
||||
* @param {Object} [error_object] - returned error information on tag data fetch failure
|
||||
*/
|
||||
|
||||
/**
|
||||
* Get top [n] tags
|
||||
* @function getTopTags
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {int|string} limit=50 - the number of tags to return (can be an integer string)
|
||||
* @returns {string[]} an array containing the top tags up to the limit requested
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getTopTags(20));
|
||||
*/
|
||||
|
||||
async getTopTags(limit = 50) {
|
||||
const data = await this.queryApollo(
|
||||
await import(/* webpackChunkName: 'queries' */ './data/tags-top.gql'),
|
||||
|
|
@ -584,7 +833,20 @@ export default class TwitchData extends Module {
|
|||
return out;
|
||||
}
|
||||
|
||||
getLanguagesFromTags(tags, callback) {
|
||||
/**
|
||||
* Queries tag languages
|
||||
* @function getLanguagesFromTags
|
||||
* @memberof TwitchData
|
||||
*
|
||||
* @param {int[]} tags - an array of tag IDs
|
||||
* @returns {string[]} tag information
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getLanguagesFromTags([50, 53, 58, 84]));
|
||||
*/
|
||||
|
||||
getLanguagesFromTags(tags, callback) { // TODO: actually use the callback
|
||||
const out = [],
|
||||
fn = callback ? debounce(() => {
|
||||
this.getLanguagesFromTags(tags, callback);
|
||||
|
|
@ -603,6 +865,22 @@ export default class TwitchData extends Module {
|
|||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Search tags
|
||||
* @function getMatchingTags
|
||||
* @memberof TwitchData
|
||||
* @async
|
||||
*
|
||||
* @param {string} query - the search string
|
||||
* @param {string} [locale] - the locale to return tags from
|
||||
* @param {string} [category=null] - the category to return tags from
|
||||
* @returns {string[]} an array containing tags that match the query string
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* console.log(this.twitch_data.getMatchingTags("Rainbo"));
|
||||
*/
|
||||
|
||||
async getMatchingTags(query, locale, category = null) {
|
||||
if ( ! locale )
|
||||
locale = this.locale;
|
||||
|
|
@ -691,4 +969,4 @@ export default class TwitchData extends Module {
|
|||
|
||||
return out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue