@single-studio/plugin-twitch 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Shaun Delaney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @single-studio/plugin-twitch
+
+Twitch EventSub for
+[Single Studio](https://fourcourtjester.github.io/Single-Studio/): chat, follows,
+subs, gifts, cheers and raids, straight into a studio with no backend.
+
+```bash
+npm i @single-studio/plugin-twitch
+```
+
+```js
+import { twitch, TwitchHandler } from '@single-studio/plugin-twitch'
+
+class MyShow extends TwitchHandler {
+  onFollow({ from }) {
+    this.mutate('set', { 'variables.alert.name': from.name, 'variables.alert.kind': 'follow' })
+  }
+}
+
+createVelcroHost({ name: STUDIO_ID, mutations, plugins: [twitch(MyShow)] })
+```
+
+## What it tells you
+
+`onChat`, `onFollow`, `onSubscribe`, `onResubscribe`, `onGift`, `onCheer`, `onRaid`.
+
+## What the operator sets
+
+A client id, the channel's numeric user id, their own user id, and an access token.
+All four are facts about that person and their app, so they belong on the board rather
+than in a build.
+
+`Events` is a comma-separated list, blank for all of them. Subscribing to less than
+everything is worth doing: each type is a separate subscription created at connect
+time, and the ones you do not read still cost a round trip.
+
+## Two things worth knowing
+
+**A reconnect is a handover, not a drop.** Twitch hands over a URL rather than closing,
+and the old socket keeps delivering until the new one has welcomed — so nothing is
+missed and no graphic flickers. The plugin does that for you.
+
+**Some subscriptions can be refused while others succeed**, usually because a scope is
+missing. The plugin keeps going with what it got and says which were refused on the
+board, rather than treating a partial success as a failed connection.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@single-studio/plugin-twitch",
+  "version": "0.6.0",
+  "description": "Twitch EventSub for Single Studio: chat, follows, subs, gifts, cheers and raids, straight into a studio with no backend.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FourCourtJester/Single-Studio.git",
+    "directory": "packages/plugin-twitch"
+  },
+  "homepage": "https://github.com/FourCourtJester/Single-Studio#readme",
+  "bugs": "https://github.com/FourCourtJester/Single-Studio/issues",
+  "type": "module",
+  "keywords": [
+    "single-studio",
+    "single-studio-plugin",
+    "obs",
+    "broadcast"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@single-studio/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@single-studio/core": "workspace:*",
+    "vitest": "^3.2.6"
+  }
+}

package/src/events.js

@@ -0,0 +1,133 @@
+// Twitch's payloads, turned into something a studio author would have written.
+//
+// The wire format is snake_case with the broadcaster's name repeated in three
+// fields on every event, and a subscription tier of "1000". None of that is wrong,
+// and all of it is Twitch's shape rather than a show's. A studio should write
+// `onCheer({ bits, from })`, not reach through `event.user_name` and remember that
+// anonymous cheers set it to null.
+//
+// Each of these is a pure function from one payload to one object, which is what
+// makes the whole module testable against a recorded sample and nothing else.
+
+/** Twitch sends tiers as "1000" | "2000" | "3000". Nobody says "tier one thousand". */
+const tierOf = (raw) => (raw === '2000' ? 2 : raw === '3000' ? 3 : 1)
+
+/**
+ * Who did it, in one shape, whoever they are.
+ *
+ * The prefix is the whole field stem, not a role: chat calls its author
+ * `chatter_user_id`, so the prefix is `chatter_user` rather than `chatter`. Getting
+ * that wrong reads every field as undefined and puts a nameless chatter on air,
+ * which is what happened the first time this was written.
+ */
+const actor = (event, prefix = 'user') => ({
+  id: event?.[`${prefix}_id`] ?? null,
+  login: event?.[`${prefix}_login`] ?? null,
+  name: event?.[`${prefix}_name`] ?? event?.[`${prefix}_login`] ?? null,
+})
+
+/**
+ * The subset of `channel.chat.message` a graphic actually shows.
+ *
+ * `fragments` is kept because it is the only way to render emotes, and a chat
+ * overlay that cannot show emotes is not a chat overlay. Everything else about the
+ * message -- badges as ids, the source room for shared chat -- stays on `raw`.
+ */
+const chat = (event) => ({
+  id: event?.message_id ?? null,
+  text: event?.message?.text ?? '',
+  fragments: event?.message?.fragments ?? [],
+  from: actor(event, 'chatter_user'),
+  colour: event?.color || null,
+  badges: (event?.badges ?? []).map((badge) => badge.set_id),
+  // A first message from somebody is worth greeting, and it is the sort of thing a
+  // studio wants without having to work out what "message_type" means.
+  first: event?.message_type === 'user_intro' || Boolean(event?.is_first_message),
+  reply: event?.reply ? { to: event.reply.parent_user_name ?? null, text: event.reply.parent_message_body ?? null } : null,
+})
+
+const follow = (event) => ({ from: actor(event), at: event?.followed_at ?? null })
+
+const subscribe = (event) => ({
+  from: actor(event),
+  tier: tierOf(event?.tier),
+  gifted: Boolean(event?.is_gift),
+})
+
+/** A resub, where the point is the message the viewer wrote with it. */
+const resub = (event) => ({
+  from: actor(event),
+  tier: tierOf(event?.tier),
+  months: event?.cumulative_months ?? null,
+  streak: event?.streak_months ?? null,
+  text: event?.message?.text ?? '',
+  fragments: event?.message?.fragments ?? [],
+})
+
+const gift = (event) => ({
+  // Anonymous gifts arrive with the user fields null rather than absent, which is
+  // the one case that will put "null" on air if nobody looks for it.
+  from: event?.is_anonymous ? null : actor(event),
+  anonymous: Boolean(event?.is_anonymous),
+  count: event?.total ?? 1,
+  tier: tierOf(event?.tier),
+  lifetime: event?.cumulative_total ?? null,
+})
+
+const cheer = (event) => ({
+  from: event?.is_anonymous ? null : actor(event),
+  anonymous: Boolean(event?.is_anonymous),
+  bits: event?.bits ?? 0,
+  text: event?.message ?? '',
+})
+
+const raid = (event) => ({
+  from: {
+    id: event?.from_broadcaster_user_id ?? null,
+    login: event?.from_broadcaster_user_login ?? null,
+    name: event?.from_broadcaster_user_name ?? event?.from_broadcaster_user_login ?? null,
+  },
+  viewers: event?.viewers ?? 0,
+})
+
+/**
+ * Twitch's subscription type, the event this plugin emits, and how to shape it.
+ *
+ * Keyed by the wire name so a notification is one lookup, and exported so the
+ * plugin can turn it into the subscription requests it has to create -- the same
+ * list doing both jobs, rather than two that can disagree.
+ */
+export const EVENTS = {
+  'channel.chat.message': { emit: 'chat', shape: chat, scope: 'user:read:chat' },
+  'channel.follow': { emit: 'follow', shape: follow, scope: 'moderator:read:followers', version: '2' },
+  'channel.subscribe': { emit: 'subscribe', shape: subscribe, scope: 'channel:read:subscriptions' },
+  'channel.subscription.message': { emit: 'resub', shape: resub, scope: 'channel:read:subscriptions' },
+  'channel.subscription.gift': { emit: 'gift', shape: gift, scope: 'channel:read:subscriptions' },
+  'channel.cheer': { emit: 'cheer', shape: cheer, scope: 'bits:read' },
+  'channel.raid': { emit: 'raid', shape: raid, scope: null },
+}
+
+/** Every scope the configured events need, deduped. */
+export const scopesFor = (types = Object.keys(EVENTS)) => [...new Set(types.map((type) => EVENTS[type]?.scope).filter(Boolean))]
+
+/**
+ * Turn one notification into the event a studio hears.
+ *
+ * Unknown types still come through, under their wire name and unshaped, rather than
+ * being dropped: Twitch adds subscription types faster than any plugin tracks them,
+ * and a studio that wants a new one should not have to wait for a release.
+ *
+ * @param {string} type
+ * @param {unknown} event
+ * @returns {{ name: string, payload: object }}
+ */
+export function normalise(type, event) {
+  const known = EVENTS[type]
+
+  return {
+    name: known?.emit ?? type,
+    // `raw` on everything, always. The shaped fields are the ones a show usually
+    // wants; the escape hatch is what stops a missing field being a blocker.
+    payload: { ...(known ? known.shape(event) : {}), raw: event },
+  }
+}

package/src/index.js

@@ -0,0 +1,273 @@
+import { definePlugin, PluginHandler, SocketService } from '@single-studio/core/worker'
+
+import { EVENTS, normalise } from './events.js'
+import { Protocol } from './protocol.js'
+
+export { EVENTS, normalise, scopesFor } from './events.js'
+export { Protocol } from './protocol.js'
+
+const EVENTSUB = 'wss://eventsub.wss.twitch.tv/ws'
+const HELIX = 'https://api.twitch.tv/helix/eventsub/subscriptions'
+
+/**
+ * Twitch chat, follows, subs, gifts, cheers and raids, in the SharedWorker.
+ *
+ * In the worker rather than on a page for the reason every ingress is: one socket
+ * for the whole studio. A chat overlay, a board, and an alert graphic are three
+ * pages, and three sockets would be three copies of every message and three sets of
+ * Twitch's rate limits to spend.
+ *
+ * Extends `Service`, so reconnection, exponential backoff and the ownership
+ * predicate come from the framework. What is here is the part that is Twitch's:
+ * the session handshake, the keepalive watchdog, and the subscriptions that have to
+ * be created after connecting rather than before.
+ */
+class Twitch extends SocketService {
+  static serviceName = 'twitch'
+
+  /** The socket being handed over to, during a reconnect. */
+  #next = null
+
+  #protocol = new Protocol()
+
+  /** Not usable until subscribed, so `open()` waits for that rather than the socket. */
+  get readyOnOpen() {
+    return false
+  }
+
+  /**
+   * Longer than the default, because `ready()` here is much further away than a
+   * socket coming up.
+   *
+   * Between the two are a welcome frame and then one HTTP round trip per event
+   * type, in a row -- seven by default. Ten seconds is comfortable for a handshake
+   * and is not obviously comfortable for that, and being wrong is not a slow
+   * connection but a retry loop that fails at the same place every time. The
+   * deadline is still worth having: it is bounded, and the failure it exists for
+   * -- a socket accepted and then abandoned -- is not made likelier by a bigger
+   * number.
+   */
+  get connectBudgetMs() {
+    return 30_000
+  }
+
+  get url() {
+    return EVENTSUB
+  }
+
+  /** Sized by what Twitch said in the welcome rather than by a guess. */
+  get silenceBudgetMs() {
+    return this.#protocol.silenceBudgetMs
+  }
+
+  /** The events this studio asked for, or all of them. */
+  get types() {
+    const asked = String(this.config.events ?? '')
+      .split(',')
+      .map((type) => type.trim())
+      .filter(Boolean)
+
+    return asked.length ? asked : Object.keys(EVENTS)
+  }
+
+  open() {
+    if (!this.config.token) return Promise.reject(new Error('Not signed in to Twitch yet.'))
+    if (!this.config.clientId) return Promise.reject(new Error('A Twitch application Client ID is needed.'))
+    if (!this.config.broadcasterId) return Promise.reject(new Error('The broadcaster user id is needed.'))
+
+    return super.open()
+  }
+
+  async receive(raw, socket) {
+    const action = this.#protocol.handle(raw)
+
+    switch (action.do) {
+      case 'subscribe': {
+        // A welcome on the incoming socket during a handover: that one is now the
+        // live one, and the old can go.
+        if (socket === this.#next) {
+          // Subscriptions belong to the session, and the new session already has
+          // them -- Twitch carries them across a reconnect. Nothing to create.
+          this.adopt(socket)
+          this.#next = null
+
+          return
+        }
+
+        try {
+          await this.#subscribe(action.session)
+          this.ready()
+        } catch (error) {
+          this.fail(error)
+        }
+
+        return
+      }
+
+      case 'deliver': {
+        const { name, payload } = normalise(action.type, action.event)
+
+        this.emit(name, payload)
+        this.emit('*', name, payload)
+
+        return
+      }
+
+      case 'reconnect':
+        // Twitch hands over a URL rather than closing, so the old socket keeps
+        // delivering until the new one has welcomed. Nothing is missed.
+        this.#next = this.connect(action.url)
+        this.#next.addEventListener('message', (event) => {
+          this.pet()
+
+          try {
+            this.receive(JSON.parse(event.data), this.#next)
+          } catch {
+            // Not JSON, so not this protocol.
+          }
+        })
+
+        return
+
+      case 'revoked':
+        // Otherwise the events simply stop and the overlay looks fine.
+        this.emit('revoked', { type: action.type, reason: action.reason })
+        console.warn(`[twitch] ${action.type} was revoked: ${action.reason}`)
+
+        return
+
+      default:
+    }
+  }
+
+  /**
+   * Create the subscriptions for this session.
+   *
+   * After the welcome rather than before it: the session id is what ties a
+   * subscription to this socket, and it does not exist until Twitch says so.
+   */
+  async #subscribe(session) {
+    const failures = []
+
+    for (const type of this.types) {
+      const known = EVENTS[type]
+      const condition = { broadcaster_user_id: String(this.config.broadcasterId) }
+
+      // Each type words its condition differently, and a wrong one is rejected as a
+      // 400 that reads like a scope problem.
+      if (type === 'channel.chat.message') condition.user_id = String(this.config.userId || this.config.broadcasterId)
+      if (type === 'channel.follow') condition.moderator_user_id = String(this.config.userId || this.config.broadcasterId)
+      if (type === 'channel.raid') {
+        delete condition.broadcaster_user_id
+        condition.to_broadcaster_user_id = String(this.config.broadcasterId)
+      }
+
+      const response = await fetch(HELIX, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.config.token}`,
+          'Client-Id': this.config.clientId,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          type,
+          version: known?.version ?? '1',
+          condition,
+          transport: { method: 'websocket', session_id: session },
+        }),
+      })
+
+      if (!response.ok) failures.push(`${type} (${response.status})`)
+    }
+
+    // Some working is better than none: a studio missing `bits:read` should still
+    // get chat rather than a dead plugin.
+    if (failures.length === this.types.length) throw new Error(`Twitch refused every subscription: ${failures.join(', ')}`)
+    if (failures.length) console.warn(`[twitch] some subscriptions were refused: ${failures.join(', ')}`)
+  }
+
+  async close() {
+    this.#next?.close()
+    this.#next = null
+    await super.close()
+  }
+}
+
+/** The skeleton a studio fills in. One method per event, all no-ops. */
+export class TwitchHandler extends PluginHandler {
+  static handles = {
+    chat: 'onChat',
+    follow: 'onFollow',
+    subscribe: 'onSubscribe',
+    resub: 'onResub',
+    gift: 'onGift',
+    cheer: 'onCheer',
+    raid: 'onRaid',
+    revoked: 'onRevoked',
+  }
+
+  onChat() {}
+
+  onFollow() {}
+
+  onSubscribe() {}
+
+  onResub() {}
+
+  onGift() {}
+
+  onCheer() {}
+
+  onRaid() {}
+
+  onRevoked() {}
+}
+
+/**
+ * @param {typeof TwitchHandler} [Handler] The studio's subclass.
+ */
+export const twitch = (Handler = TwitchHandler) =>
+  definePlugin({
+    name: 'twitch',
+    label: 'Twitch',
+    summary: 'Chat, follows, subs, gifts, cheers and raids, straight into the show.',
+    help: [
+      {
+        type: 'note',
+        text: 'Signing in properly is not built yet, so for now this needs an access token pasted in by hand. Tokens expire, so expect to redo this.',
+      },
+      {
+        type: 'steps',
+        items: [
+          'Register an application at dev.twitch.tv/console/apps. The Client ID it gives you is public — paste it above.',
+          'Find your channel’s numeric user id (any "Twitch username to user id" tool will do) and paste it into both id fields.',
+          'Generate a user access token with the scopes below and paste it into Access token.',
+          'Save and reconnect.',
+        ],
+      },
+      { type: 'text', text: 'Scopes needed, depending on which events you want:' },
+      {
+        type: 'code',
+        text: 'user:read:chat            chat messages\nmoderator:read:followers  follows\nchannel:read:subscriptions subs, resubs and gifts\nbits:read                 cheers',
+      },
+      { type: 'link', href: 'https://dev.twitch.tv/console/apps', label: 'Twitch developer console' },
+      {
+        type: 'text',
+        text: 'Leave Events blank for all of them, or list the ones you want — a studio that only shows chat need not ask for subscription scopes at all.',
+      },
+    ],
+    config: [
+      { key: 'clientId', label: 'Client ID', help: 'From your app at dev.twitch.tv/console/apps. Public, not a secret.' },
+      { key: 'broadcasterId', label: 'Channel user id', help: 'The numeric id of the channel to watch.' },
+      { key: 'userId', label: 'Your user id', help: 'Usually the same as the channel. Differs when a moderator runs the board.' },
+      { key: 'token', label: 'Access token', type: 'secret' },
+      { key: 'events', label: 'Events', help: 'Comma separated. Blank for all of them.' },
+    ],
+    create: (context) => {
+      const plugin = new Twitch(context)
+
+      new Handler({ ...context, plugin }).attach(plugin.events)
+
+      return plugin
+    },
+  })

package/src/protocol.js

@@ -0,0 +1,144 @@
+// The EventSub WebSocket protocol, as a state machine with no socket in it.
+//
+// Twitch's transport has four behaviours that are easy to get subtly wrong and
+// impossible to notice until a show: a keepalive watchdog, a reconnect that hands
+// you a new URL and expects an overlap, replay protection, and revocation. Each is
+// a rule about *when* to act rather than about parsing, so all four are here,
+// away from the socket, where a test can drive them by hand.
+//
+// The socket wrapper feeds messages in and does what `handle` says. That split is
+// what lets the whole protocol be tested in Node with no network, no credentials,
+// and no waiting.
+
+/** How long a message id is worth remembering, and how many. */
+const SEEN_LIMIT = 600
+
+/**
+ * Twitch asks clients to ignore anything older than ten minutes, because a replayed
+ * notification is indistinguishable from a real one to everything downstream -- a
+ * subscriber alert firing again an hour later is on air before anybody can stop it.
+ */
+const MAX_AGE_MS = 10 * 60 * 1000
+
+export const WELCOME = 'session_welcome'
+export const KEEPALIVE = 'session_keepalive'
+export const NOTIFICATION = 'notification'
+export const RECONNECT = 'session_reconnect'
+export const REVOCATION = 'revocation'
+
+/**
+ * What the caller should do about a message.
+ *
+ * @typedef {object} Action
+ * @property {'ignore'|'subscribe'|'alive'|'deliver'|'reconnect'|'revoked'} do
+ * @property {string} [session] Session id, on `subscribe`.
+ * @property {number} [keepalive] Seconds, on `subscribe`.
+ * @property {string} [url] Where to reconnect, on `reconnect`.
+ * @property {string} [type] Subscription type, on `deliver` and `revoked`.
+ * @property {unknown} [event] The payload, on `deliver`.
+ * @property {string} [reason] Why, on `revoked` and on an ignore worth explaining.
+ */
+
+export class Protocol {
+  /** Message ids already handled, oldest first. */
+  #seen = new Set()
+
+  /** @param {() => number} [now] Injectable so a test can move time without waiting. */
+  constructor(now = () => Date.now()) {
+    this.now = now
+    this.sessionId = null
+    this.keepaliveSeconds = null
+  }
+
+  /**
+   * Has this id been handled before?
+   *
+   * Twitch may redeliver, and a bounded set is the right shape: unbounded would
+   * grow for the length of a stream, and a stream is measured in hours.
+   */
+  #fresh(id) {
+    if (this.#seen.has(id)) return false
+
+    this.#seen.add(id)
+
+    // Sets iterate in insertion order, so the first key is the oldest.
+    if (this.#seen.size > SEEN_LIMIT) this.#seen.delete(this.#seen.values().next().value)
+
+    return true
+  }
+
+  /**
+   * Decide what a raw message means.
+   *
+   * @param {unknown} raw Already JSON.parse'd.
+   * @returns {Action}
+   */
+  handle(raw) {
+    const metadata = raw?.metadata
+    const payload = raw?.payload
+
+    if (!metadata?.message_type) return { do: 'ignore', reason: 'not an EventSub message' }
+
+    const id = metadata.message_id
+    const type = metadata.message_type
+
+    // Replay protection before anything else, so a duplicate reconnect or
+    // revocation is dropped as surely as a duplicate notification.
+    if (id && !this.#fresh(id)) return { do: 'ignore', reason: 'already handled' }
+
+    const at = Date.parse(metadata.message_timestamp ?? '')
+
+    if (Number.isFinite(at) && this.now() - at > MAX_AGE_MS) {
+      return { do: 'ignore', reason: 'older than ten minutes' }
+    }
+
+    switch (type) {
+      case WELCOME: {
+        this.sessionId = payload?.session?.id ?? null
+        // Twitch closes the connection if nothing is subscribed inside this
+        // window, which is short: ten seconds unless asked for otherwise.
+        this.keepaliveSeconds = payload?.session?.keepalive_timeout_seconds ?? null
+
+        return { do: 'subscribe', session: this.sessionId, keepalive: this.keepaliveSeconds }
+      }
+
+      case KEEPALIVE:
+        return { do: 'alive' }
+
+      case NOTIFICATION:
+        return {
+          do: 'deliver',
+          type: payload?.subscription?.type ?? metadata.subscription_type ?? null,
+          event: payload?.event ?? null,
+        }
+
+      case RECONNECT:
+        // The old socket keeps delivering until the new one has welcomed, which is
+        // the whole point of Twitch handing over a URL rather than just closing.
+        return { do: 'reconnect', url: payload?.session?.reconnect_url ?? null }
+
+      case REVOCATION:
+        return {
+          do: 'revoked',
+          type: payload?.subscription?.type ?? null,
+          reason: payload?.subscription?.status ?? 'revoked',
+        }
+
+      default:
+        return { do: 'ignore', reason: `unknown message type "${type}"` }
+    }
+  }
+
+  /**
+   * How long to wait for *anything* before deciding the connection is dead.
+   *
+   * Twitch sends a keepalive whenever it has sent nothing else, so silence past
+   * this is the connection being gone without a close frame -- which is the
+   * failure that leaves a chat overlay looking fine and frozen.
+   *
+   * A margin, because a keepalive that arrives exactly on time is on time.
+   */
+  get silenceBudgetMs() {
+    return ((this.keepaliveSeconds ?? 10) + 5) * 1000
+  }
+}