Skip to content

Latest commit

 

History

History
374 lines (284 loc) · 15.2 KB

tesjs.md

File metadata and controls

374 lines (284 loc) · 15.2 KB

TES

Kind: global class
License: Copyright (c) 2020-2023 Mitchell Adair

This software is released under the MIT License. https://opensource.org/licenses/MIT

new TES(config)

Returns: TES - The TESjs instance

Param Type Description
config Config The TES configuration

Example
Minimum websocket config

const config = {
    identity: {
        id: YOUR_CLIENT_ID,
        accessToken: YOUR_USER_ACCESS_TOKEN,
    }
    listener: { type: "websocket" },
};
const tes = new TES(config);

Example
Minimum webhook config

const config = {
    identity: {
        id: YOUR_CLIENT_ID,
        secret: YOUR_CLIENT_SECRET,
    },
    listener: {
        type: "webhook",
        baseURL: "https://example.com",
        secret: YOUR_WEBHOOKS_SECRET,
    },
};
const tes = new TES(config);

tes.getSubscriptions([cursor]) ⇒ Promise

Get a list of your event subscriptions

Kind: instance method of TES
Returns: Promise - Subscription data. See Twitch doc for details

Param Type Description
[cursor] string The pagination cursor

Example

const subs = await tes.getSubscriptions();
console.log(`I have ${subs.total} event subscriptions`);

tes.getSubscriptionsByType(type, [cursor]) ⇒ Promise

Get a list of your event subscriptions by type

Kind: instance method of TES
Returns: Promise - Subscription data. See Twitch doc for details

Param Type Description
type string The type of subscription. See Twitch doc for details
[cursor] string The pagination cursor

Example

const subs = await tes.getSubscriptionsByType("channel.update");
console.log(`I have ${subs.total} "channel.update" event subscriptions`);

tes.getSubscriptionsByStatus(status, [cursor]) ⇒ Promise

Get a list of your event subscriptions by status

Kind: instance method of TES
Returns: Promise - Subscription data. See Twitch doc for details

Param Type Description
status string The subscription status. See Twitch doc for details
[cursor] string The pagination cursor

Example

const subs = await tes.getSubscriptionsByStatus("enabled");
console.log(`I have ${subs.total} "enabled" event subscriptions`);

tes.getSubscription(idOrType, [condition]) ⇒ Promise

Get subscription data for an individual subscription. Search either by id or by type and condition

Kind: instance method of TES
Returns: Promise - The subscription data
Signature: getSubscription(id)
Signature: getSubscription(type, condition)

Param Type Description
idOrType string The subscription id or type
[condition] Object The subscription condition, required when finding by type. See Twitch doc for details

Example
Find a subscription by id

const sub = await tes.getSubscription("2d9e9f1f-39c3-426d-88f5-9f0251c9bfef");
console.log(`The status for subscription ${sub.id} is ${sub.status}`);

Example
Find a subscription by type and condition

const condition = { broadcaster_user_id: "1337" };
const sub = await tes.getSubscription("channel.update", condition);
console.log(`The status for subscription ${sub.id} is ${sub.status}`);

tes.subscribe(type, condition, [version]) ⇒ Promise

Subscribe to an event

Kind: instance method of TES
Returns: Promise - A Promise that resolves when subscribing is complete with the subscription data

Param Type Default Description
type string The subscription type. See Twitch doc for details
condition Object The subscription condition. See Twitch doc for details
[version] string "1" The subscription version. See Twitch doc for details

Example

const condition = { broadcaster_user_id: "1337" };
const sub = tes.subscribe("channel.update", condition);
console.log(`Created subscription to ${sub.type}, subscription id ${sub.id}`);

tes.unsubscribe(idOrType, [condition]) ⇒ Promise

Unsubscribe from an event. Unsubscribe either by id, or by type and condition

Kind: instance method of TES
Returns: Promise - Resolves when unsubscribed
Signature: unsubscribe(id)
Signature: unsubscribe(type, condition)

Param Type Description
idOrType string The subscription id or type
[condition] Object The subscription condition, required when finding by type. See Twitch doc for details

Example
Unsubscribe by id

await tes.unsubscribe("2d9e9f1f-39c3-426d-88f5-9f0251c9bfef");
console.log("Successfully unsubscribed");

Example
Unsubscribe by type and condition

const condition = { broadcaster_user_id: "1337" };
await tes.unsubscribe("channel.update", condition);
console.log("Successfully unsubscribed");

tes.on(type, callback) ⇒ void

Add an event handler. This will handle ALL events of the type

Kind: instance method of TES

Param Type Description
type string | "revocation" | "connection_lost" The subscription type. See Twitch doc for details. See the examples for details on revocation and connection_lost
callback onEventCallback The function to call when the event happens

Example

tes.on("channel.update", (event, subscription) => {
    console.log(`Event triggered for subscription ${subscription.id}`);
    console.log(`${event.broadcaster_user_id}'s title is now "${event.title}"`);
});

Example
The revocation event is fired when Twitch revokes a subscription. This can happen for various reasons according to Twitch. The "event" argument is the subscription data. This means that for this, the first and second arguments are basically identical

NOTE: No explicit subscription is needed for this event to be fired

tes.on("revocation", (subscriptionData) => {
    console.log(`Subscription ${subscriptionData.id} has been revoked`);
    // perform necessary cleanup here
});

Example
The connection_lost event is fired when a WebSocket connection is lost. All related subscriptions should be considered stale if this happens. You can read more about this case in the Twitch doc. The "event" argument is an Object which has subscription ids as keys and type and condition as the values

NOTE: No explicit subscription is needed for this event to be fired

tes.on("connection_lost", (subscriptions) => {
    // if your subscriptions are important to you, resubscribe to them
    Object.values(subscriptions).forEach((subscription) => {
        tes.subscribe(subscription.type, subscription.condition);
    });
});

TES~Config : Object

Kind: inner typedef of TES

Param Type Description
[options] Options Basic configuration options
identity Identity Identity information
listener Listener Your notification listener details

Config~Options : Object

Basic configuration options

Kind: inner typedef of Config

Param Type Default Description
[debug] boolean false Set to true for in-depth logging
[logging] boolean true Set to false for no logging

Config~Identity : Object

Identity configuration

Kind: inner typedef of Config

Param Type Description
id string Your client ID
[secret] string Your client secret, required for webhook transport or when not using onAuthenticationFailure in server-side websocket applications
[onAuthenticationFailure] onAuthenticationFailure Callback function called when API requests get an auth failure. If you already have an authentication solution for your app elsewhere use this to avoid token conflicts
[accessToken] string If you already have an access token, put it here. Must be user access token for websocket transport, must be app access token for webhook transport. Should usually be paired with onAuthenticationFailure on server-side applications
[refreshToken] string The refresh token to use if using websocket transport server-side. Required when not using onAuthenticationFailure in server-side websocket applications

Identity~onAuthenticationFailure ⇒ Promise

Callback function called when API requests get an auth failure. If you already have an authentication solution for your app elsewhere use this to avoid token conflicts

Kind: inner typedef of Identity
Returns: Promise - Promise that resolves a new access token
Example

async function onAuthenticationFailure() {
    const res = await getNewAccessToken(); // your token refresh logic
    return res.access_token;
}

Config~Listener : Object

Listener configuration

Kind: inner typedef of Config

Param Type Default Description
type "webhook" | "websocket" The type of transport to use
[baseURL] string Required for webhook transport. The base URL where your app is hosted. See Twitch doc for details on local development
[websocketURL] string "wss://eventsub.wss.twitch.tv/ws" A custom websocket URL to use for websocket transport. Useful for local testing with Twitch CLI
[secret] string Required for webhook transport. The secret to use for your webhook subscriptions. Should be different from your client secret
[server] Express The Express app object. Use if integrating with an existing Express app
[port] number process.env.PORT,8080 A custom port to use
[ignoreDuplicateMessages] boolean true Ignore event messages with IDs that have already been seen. Only used in webhook transport
[ignoreOldMessages] boolean true Ignore event messages with timestamps older than ten minutes. Only used in webhook transport

TES~onEventCallback ⇒ void

Called when an event TES is listening for is triggered. See TES.on for examples

Kind: inner typedef of TES

Param Type Description
[event] Object The event data. See Twitch doc for details. See the TES.on examples for details on revocation and connection_lost
[subscription] Object The subscription data corresponding to the event. See Twitch doc for details