@single-studio/plugin-twitch 0.7.0 → 0.9.0

package/README.md

@@ -17,32 +17,81 @@ class MyShow extends TwitchHandler {
   }
 }
 
-createVelcroHost({ name: STUDIO_ID, mutations, plugins: [twitch(MyShow)] })
+createVelcroHost({
+  name: STUDIO_ID,
+  mutations,
+  plugins: [twitch(MyShow, { clientId: 'your-client-id' })],
+})
 ```
 
+## Once, as the studio's author: a Client ID
+
+Register one application at [dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps)
+and pass its Client ID to `twitch()`. Nobody who runs your studio ever sees Twitch's
+developer console.
+
+- **Client Type: Public.** A studio is static files with nowhere to keep a secret,
+  and a public client is what lets it sign in without one.
+- **OAuth Redirect URL:** anything, such as `http://localhost:5173`. The form needs
+  one; the sign-in never uses it.
+- The Client ID is **not a secret**. It belongs in the build.
+- Its name is what operators see on Twitch's approval screen.
+
+## Every operator: Sign in with Twitch
+
+On the board's plugin panel, press **Sign in with Twitch**. A code appears. Go to
+twitch.tv/activate on any device, sign in as the channel, type the code, and approve.
+The panel changes to "Signed in as …" and the plugin connects.
+
+The machine stays signed in: tokens are refreshed in the background, and only Sign
+out, a reset, or thirty days unused ask for the code again. Nobody types a user id or a
+token.
+
+A moderator running a board for somebody else's channel signs in as themselves and
+types that channel's name under **Channel**.
+
 ## What it tells you
 
-`onChat`, `onFollow`, `onSubscribe`, `onResubscribe`, `onGift`, `onCheer`, `onRaid`.
+`onChat`, `onFollow`, `onSubscribe`, `onResub`, `onGift`, `onCheer`, `onRaid`, and
+`onRevoked` for a subscription Twitch withdrew.
 
-## What the operator sets
+Every one of them, unless you narrow it. Narrowing is yours, as the author, rather
+than the operator's, because it decides what Twitch asks a streamer to approve at
+sign-in:
 
-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.
+```js
+twitch(MyShow, { clientId: 'your-client-id', events: ['chat', 'raid'] })
+```
+
+Names are the handler's (`chat`, `follow`, `subscribe`, `resub`, `gift`, `cheer`,
+`raid`) or Twitch's (`channel.raid`). A chat-only studio then asks only to read
+chat.
+
+Some events depend on who signed in. A moderator watching somebody else's channel
+gets chat, follows and raids; subs, gifts and cheers only go to the channel's own
+sign-in. The plugin carries on with whatever Twitch will send and names the rest on
+the panel, since a graphic that never shows a sub otherwise looks like a quiet night.
+
+## Trying it without Twitch
+
+```js
+twitch(MyShow, { mock: true })
+```
 
-`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.
+connects to the [Twitch CLI](https://github.com/twitchdev/twitch-cli)'s mock EventSub
+server on this machine, with no sign-in. From this repository,
+`pnpm --filter @single-studio/plugin-twitch mock` starts it and turns single keys into
+test events. See [dev/README.md](dev/README.md).
 
 ## 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
+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.
+missing. The plugin keeps going with what it got rather than treating a partial
+success as a failed connection.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@single-studio/plugin-twitch",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Twitch EventSub for Single Studio: chat, follows, subs, gifts, cheers and raids, straight into a studio with no backend.",
   "license": "MIT",
   "author": {
@@ -30,10 +30,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "mock": "node dev/mock.mjs"
   },
   "peerDependencies": {
-    "@single-studio/core": "^0.7.0"
+    "@single-studio/core": "^0.9.0"
   },
   "devDependencies": {
     "@single-studio/core": "workspace:*",

package/src/auth.js

@@ -0,0 +1,129 @@
+// Signing in to Twitch from a page with nowhere to keep a secret.
+//
+// A studio is static files, so it is what Twitch calls a *public client*, and a
+// public client gets exactly one way to sign in: the Device Code Flow. The plugin
+// asks for a code, the operator types it at twitch.tv/activate on any device, and the
+// plugin asks until Twitch says yes. That suits an OBS dock better than a redirect
+// would anyway: nothing has to find its way back into the dock.
+//
+// Kept apart from the socket so every step is testable with a fake `fetch`, and so
+// the part of this plugin that depends on Twitch's wording is in one place.
+//
+// Confirmed from a browser page against real Twitch, before any of this was built:
+// the device endpoint, the token endpoint and Helix all answer a cross-origin call,
+// so this needs no backend. Two properties of the refresh token are built around
+// below: it is single use, and it expires after thirty days unused.
+
+const ID = 'https://id.twitch.tv/oauth2'
+
+const GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
+const form = (fields) => ({ method: 'POST', body: new URLSearchParams(fields) })
+
+/** What Twitch says went wrong, whichever field it put it in. */
+const reasonOf = (body, status) => String(body?.message ?? body?.error_description ?? body?.error ?? `Twitch answered ${status}`)
+
+async function read(response) {
+  return response.json().catch(() => ({}))
+}
+
+/** A token response, in the shape the plugin stores. */
+const tokensOf = (body, now) => ({
+  token: body.access_token,
+  refresh: body.refresh_token ?? '',
+  expiresAt: now + Number(body.expires_in ?? 0) * 1000,
+})
+
+/**
+ * Ask for a code to show the operator.
+ *
+ * @returns {Promise<{ deviceCode: string, userCode: string, uri: string, interval: number, expiresAt: number }>}
+ */
+export async function requestCode({ clientId, scopes, fetch = globalThis.fetch, now = Date.now() }) {
+  const response = await fetch(`${ID}/device`, form({ client_id: clientId, scopes: scopes.join(' ') }))
+  const body = await read(response)
+
+  if (!response.ok) throw new Error(`Twitch would not start a sign-in: ${reasonOf(body, response.status)}`)
+
+  return {
+    deviceCode: body.device_code,
+    userCode: body.user_code,
+    uri: body.verification_uri ?? 'https://www.twitch.tv/activate',
+    interval: Number(body.interval ?? 5),
+    expiresAt: now + Number(body.expires_in ?? 1800) * 1000,
+  }
+}
+
+/**
+ * Ask once whether the operator has approved the code yet.
+ *
+ * Three answers, because two of Twitch's refusals are not failures: "not yet" and
+ * "slower", which the caller turns into waiting. Anything else -- denied, expired,
+ * a code Twitch no longer recognises -- ends the sign-in, with Twitch's reason.
+ *
+ * @returns {Promise<{ pending?: boolean, slowDown?: boolean, token?: string, refresh?: string, expiresAt?: number }>}
+ *   `pending` or `slowDown`, or the three token fields. One shape rather than a union,
+ *   so a caller can test for each without narrowing first.
+ */
+export async function pollToken({ clientId, scopes, deviceCode, fetch = globalThis.fetch, now = Date.now() }) {
+  const response = await fetch(`${ID}/token`, form({ client_id: clientId, scopes: scopes.join(' '), device_code: deviceCode, grant_type: GRANT }))
+  const body = await read(response)
+
+  if (response.ok && body.access_token) return tokensOf(body, now)
+
+  const reason = reasonOf(body, response.status)
+
+  if (/authorization_pending/i.test(reason)) return { pending: true }
+  if (/slow_down/i.test(reason)) return { slowDown: true }
+
+  throw new Error(`Sign-in did not complete: ${reason}`)
+}
+
+/**
+ * Swap a refresh token for a fresh pair.
+ *
+ * The old refresh token stops working the moment this succeeds, so the caller has
+ * to store the new one before anything else can go wrong. A refusal means the
+ * operator is signed out -- thirty days unused, a password change, access revoked on
+ * Twitch -- and is marked so, because the answer to it is a button, not a retry.
+ */
+export async function refreshTokens({ clientId, refresh, fetch = globalThis.fetch, now = Date.now() }) {
+  const response = await fetch(`${ID}/token`, form({ client_id: clientId, grant_type: 'refresh_token', refresh_token: refresh }))
+  const body = await read(response)
+
+  if (response.ok && body.access_token) return tokensOf(body, now)
+
+  /** @type {Error & { signedOut?: boolean }} */
+  const problem = new Error(`Twitch has signed this machine out (${reasonOf(body, response.status)}). Sign in again.`)
+
+  problem.signedOut = response.status === 400 || response.status === 401
+
+  throw problem
+}
+
+/**
+ * Who a token belongs to, which is how the plugin learns the operator's user id
+ * without asking them for a number nobody knows.
+ *
+ * @returns {Promise<{ userId: string, login: string } | null>} null for a token Twitch no longer accepts
+ */
+export async function whoIs({ token, fetch = globalThis.fetch }) {
+  const response = await fetch(`${ID}/validate`, { headers: { Authorization: `OAuth ${token}` } })
+
+  if (response.status === 401) return null
+
+  const body = await read(response)
+
+  if (!response.ok) throw new Error(`Twitch would not say who this is: ${reasonOf(body, response.status)}`)
+
+  return { userId: String(body.user_id), login: String(body.login ?? '') }
+}
+
+/** Tell Twitch the token is finished with. Best effort: signing out locally does not wait on it. */
+export async function revoke({ clientId, token, fetch = globalThis.fetch }) {
+  try {
+    await fetch(`${ID}/revoke`, form({ client_id: clientId, token }))
+  } catch {
+    // Offline, or Twitch unreachable. The token expires on its own.
+  }
+}

package/src/index.js

@@ -1,13 +1,58 @@
 import { definePlugin, PluginHandler, SocketService } from '@single-studio/core/worker'
 
-import { EVENTS, normalise } from './events.js'
+import { pollToken, refreshTokens, requestCode, revoke, whoIs } from './auth.js'
+import { EVENTS, normalise, scopesFor } 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'
+/** Where Twitch is. */
+const TWITCH = { eventsub: 'wss://eventsub.wss.twitch.tv/ws', helix: 'https://api.twitch.tv/helix' }
+
+/**
+ * Where the Twitch CLI's mock EventSub server is, by default.
+ *
+ * `twitch event websocket start-server` -- see dev/README.md. Written from the CLI's
+ * documentation rather than run from here, so both halves can be overridden.
+ */
+const MOCK = { eventsub: 'ws://127.0.0.1:8080/ws', helix: 'http://127.0.0.1:8080' }
+
+/** Refresh a token this long before it runs out, rather than finding out from a 401. */
+const EARLY = 5 * 60 * 1000
+
+/** What signing out, or being signed out, clears. */
+const SIGNED_OUT = { token: '', refresh: '', expiresAt: 0, userId: '', login: '' }
+
+/** What the panel calls each event when it has to say one is missing. */
+const WORDS = {
+  'channel.chat.message': 'chat',
+  'channel.follow': 'follows',
+  'channel.subscribe': 'subs',
+  'channel.subscription.message': 'resubs',
+  'channel.subscription.gift': 'gifts',
+  'channel.cheer': 'cheers',
+  'channel.raid': 'raids',
+}
+
+/** "a", "a and b", "a, b and c". */
+const list = (words) => (words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`)
+
+/**
+ * The wire types for what an author listed, by the name their handler uses
+ * (`'chat'`, `'cheer'`) or by Twitch's (`'channel.cheer'`). Nothing listed is all.
+ *
+ * @param {string[]} [events]
+ */
+const typesFor = (events) => {
+  if (!events?.length) return Object.keys(EVENTS)
+
+  const byName = Object.fromEntries(Object.entries(EVENTS).map(([type, known]) => [known.emit, type]))
+
+  return [...new Set(events.map((event) => byName[event] ?? event))]
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
 /**
  * Twitch chat, follows, subs, gifts, cheers and raids, in the SharedWorker.
@@ -30,6 +75,234 @@ class Twitch extends SocketService {
 
   #protocol = new Protocol()
 
+  /** What the studio author passed to `twitch()`: the Client ID, and where Twitch is. */
+  #options
+
+  /** The host's way to store into this plugin's own config. */
+  #save
+
+  /** The sign-in in progress, if there is one. Compared by identity, so a cancel ends it. */
+  #signing = null
+
+  /** The code the operator is typing somewhere, while a sign-in waits on them. */
+  #waiting = null
+
+  /** The last thing a sign-in had to say that was not "done": a denial, an expiry. */
+  #said = null
+
+  /** The channel's numeric id, resolved at connect time from what the operator typed. */
+  #broadcaster = ''
+
+  /** The events Twitch would not send on this connection, by wire name. */
+  #refused = []
+
+  constructor(context, options = {}) {
+    super(context)
+
+    this.#options = options
+    this.#save = context.save ?? (async () => ({ ok: false }))
+  }
+
+  /** The author's, when they gave one; otherwise whatever the operator typed. */
+  get clientId() {
+    return this.#options.clientId || this.config.clientId || ''
+  }
+
+  get #mock() {
+    return Boolean(this.#options.mock)
+  }
+
+  /** Which buttons make sense right now. Never both "Sign in" and "Sign out". */
+  get offers() {
+    if (this.#mock) return []
+    if (this.#signing) return ['cancel']
+
+    return this.config.token ? ['signOut'] : ['signIn']
+  }
+
+  /** What the panel shows: the code while waiting, then who is signed in. */
+  get notice() {
+    if (this.#waiting) return this.#waiting
+    if (this.#said) return this.#said
+    if (this.#mock) return { text: 'Mock mode: talking to the Twitch CLI on this machine, not to Twitch.' }
+    if (this.config.token && this.config.login) {
+      const missing = this.#refused.map((type) => WORDS[type] ?? type)
+
+      if (!missing.length) return { text: `Signed in as ${this.config.login}.` }
+
+      // Said, because the plugin carries on without them and a graphic that never
+      // shows a sub looks exactly like a quiet night. On somebody else's channel it is
+      // usually not a fault: Twitch only gives those to the channel's own sign-in.
+      const why = String(this.config.channel ?? '').trim() ? ' On somebody else’s channel, only its owner’s sign-in gets those.' : ''
+
+      return { text: `Signed in as ${this.config.login}. Twitch will not send ${list(missing)} to this sign-in.${why}` }
+    }
+
+    return null
+  }
+
+  async act(key) {
+    if (key === 'signIn') return this.#signIn()
+
+    if (key === 'cancel') {
+      this.#signing = null
+      this.#waiting = null
+
+      return undefined
+    }
+
+    if (key === 'signOut') {
+      await revoke({ clientId: this.clientId, token: this.config.token })
+
+      return this.#save(SIGNED_OUT)
+    }
+
+    throw new Error(`Twitch has no action "${key}"`)
+  }
+
+  /**
+   * Start a sign-in, and return once there is a code to show.
+   *
+   * Returns early on purpose: the operator is about to spend a minute on another
+   * device, and the panel's button should not sit on "Working…" for all of it. The
+   * rest happens in `#await`, and the panel follows it through the notice.
+   */
+  async #signIn() {
+    if (!this.clientId) throw new Error('This studio has no Twitch Client ID. Its author sets one when adding the plugin.')
+
+    const device = await requestCode({ clientId: this.clientId, scopes: scopesFor(this.types) })
+    const ticket = {}
+
+    this.#signing = ticket
+    this.#said = null
+    this.#waiting = {
+      text: 'Go to twitch.tv/activate on any device, sign in, and enter this code.',
+      code: device.userCode,
+      href: device.uri,
+      label: 'Open twitch.tv/activate',
+    }
+
+    this.#await(device, ticket).catch((error) => {
+      if (this.#signing !== ticket) return
+
+      this.#signing = null
+      this.#waiting = null
+      this.#said = { text: error?.message ?? String(error) }
+    })
+  }
+
+  /** Ask Twitch at the pace it set until the operator approves, refuses, or the code runs out. */
+  async #await(device, ticket) {
+    let interval = device.interval
+
+    while (this.#signing === ticket) {
+      await sleep(interval * 1000)
+
+      if (this.#signing !== ticket) return
+
+      if (Date.now() > device.expiresAt) throw new Error('That code ran out before it was entered. Press Sign in with Twitch for a new one.')
+
+      const answer = await pollToken({ clientId: this.clientId, scopes: scopesFor(this.types), deviceCode: device.deviceCode })
+
+      if (answer.pending) continue
+
+      // Twitch asking for less: back off by its own step and keep going.
+      if (answer.slowDown) {
+        interval += 5
+        continue
+      }
+
+      const who = await whoIs({ token: answer.token })
+
+      if (this.#signing !== ticket) return
+
+      this.#signing = null
+      this.#waiting = null
+
+      // Stored, then restarted on it: the Save button's own path, so what comes back
+      // is a plugin that connects as the person who just signed in.
+      await this.#save({ ...answer, userId: who?.userId ?? '', login: who?.login ?? '' })
+
+      return
+    }
+  }
+
+  /**
+   * A token that is about to run out, swapped before it does.
+   *
+   * The refresh token is single use, so the new pair is stored before anything else
+   * can go wrong -- losing it would sign the machine out. Stored without a restart:
+   * this runs inside a connect, and the running plugin already has the new values.
+   */
+  async #fresh({ force = false } = {}) {
+    const { refresh, expiresAt } = this.config
+
+    if (!refresh) return
+    if (!force && (!expiresAt || Number(expiresAt) - Date.now() > EARLY)) return
+
+    try {
+      const tokens = await refreshTokens({ clientId: this.clientId, refresh })
+
+      Object.assign(this.config, tokens)
+      await this.#save(tokens, { restart: false })
+    } catch (error) {
+      if (error?.signedOut) {
+        Object.assign(this.config, SIGNED_OUT)
+        await this.#save(SIGNED_OUT, { restart: false })
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * The numeric id of the channel to watch.
+   *
+   * Nobody knows their numeric id, so nobody is asked for it. Blank means the
+   * account that signed in; a name means that channel, looked up -- which is what a
+   * moderator running somebody else's board types.
+   */
+  async #channel() {
+    const typed = String(this.config.channel ?? '').trim()
+
+    if (this.#mock) return /^\d+$/.test(typed) ? typed : '12345'
+    if (/^\d+$/.test(typed)) return typed
+
+    if (!typed) {
+      if (this.config.userId) return String(this.config.userId)
+
+      const who = await whoIs({ token: this.config.token })
+
+      if (!who) throw new Error('Twitch no longer accepts this sign-in. Sign in again.')
+
+      Object.assign(this.config, who)
+      await this.#save(who, { restart: false })
+
+      return who.userId
+    }
+
+    const response = await fetch(`${this.#helix}/users?login=${encodeURIComponent(typed.toLowerCase())}`, { headers: this.#headers })
+    const body = await response.json().catch(() => ({}))
+    const id = body?.data?.[0]?.id
+
+    if (!response.ok) throw new Error(`Twitch would not look up the channel "${typed}" (${response.status}).`)
+    if (!id) throw new Error(`There is no Twitch channel called "${typed}".`)
+
+    return String(id)
+  }
+
+  get #helix() {
+    return this.#options.helix ?? (this.#mock ? MOCK.helix : TWITCH.helix)
+  }
+
+  get #headers() {
+    return {
+      Authorization: `Bearer ${this.config.token || 'mock'}`,
+      'Client-Id': this.clientId || 'mock',
+      'Content-Type': 'application/json',
+    }
+  }
+
   /** Not usable until subscribed, so `open()` waits for that rather than the socket. */
   get readyOnOpen() {
     return false
@@ -52,7 +325,7 @@ class Twitch extends SocketService {
   }
 
   get url() {
-    return EVENTSUB
+    return this.#options.eventsub ?? (this.#mock ? MOCK.eventsub : TWITCH.eventsub)
   }
 
   /** Sized by what Twitch said in the welcome rather than by a guess. */
@@ -60,20 +333,33 @@ class Twitch extends SocketService {
     return this.#protocol.silenceBudgetMs
   }
 
-  /** The events this studio asked for, or all of them. */
+  /**
+   * Every event, unless the studio's author narrowed it.
+   *
+   * The author's choice rather than the operator's. It decides which permissions
+   * Twitch asks for at sign-in, which is the author's to weigh -- a chat-only studio
+   * should not ask a streamer to approve subscription access -- and a free-text box
+   * on the panel was a way for anybody at the board to switch events off by typo.
+   * What this sign-in cannot have is found out by asking, and the panel says.
+   */
   get types() {
-    const asked = String(this.config.events ?? '')
-      .split(',')
-      .map((type) => type.trim())
-      .filter(Boolean)
-
-    return asked.length ? asked : Object.keys(EVENTS)
+    return typesFor(this.#options.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.'))
+  /** @param {AbortSignal} [signal] */
+  async open(signal) {
+    if (!this.#mock) {
+      if (!this.clientId) throw new Error('This studio has no Twitch Client ID. Its author sets one when adding the plugin.')
+      if (!this.config.token) throw new Error('Not signed in to Twitch yet. Press Sign in with Twitch.')
+
+      await this.#fresh()
+    }
+
+    this.#broadcaster = await this.#channel()
+
+    // Two round trips to Twitch above, and a restart or a stand-down can land during
+    // either. A socket dialled after that would subscribe for a plugin nobody holds.
+    if (signal?.aborted) return undefined
 
     return super.open()
   }
@@ -146,29 +432,27 @@ class Twitch extends SocketService {
    * 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) {
+  async #subscribe(session, retried = false) {
     const failures = []
+    const broadcaster = this.#broadcaster
+    const me = String(this.config.userId || broadcaster)
 
     for (const type of this.types) {
       const known = EVENTS[type]
-      const condition = { broadcaster_user_id: String(this.config.broadcasterId) }
+      const condition = { broadcaster_user_id: broadcaster }
 
       // 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.chat.message') condition.user_id = me
+      if (type === 'channel.follow') condition.moderator_user_id = me
       if (type === 'channel.raid') {
         delete condition.broadcaster_user_id
-        condition.to_broadcaster_user_id = String(this.config.broadcasterId)
+        condition.to_broadcaster_user_id = broadcaster
       }
 
-      const response = await fetch(HELIX, {
+      const response = await fetch(`${this.#helix}/eventsub/subscriptions`, {
         method: 'POST',
-        headers: {
-          Authorization: `Bearer ${this.config.token}`,
-          'Client-Id': this.config.clientId,
-          'Content-Type': 'application/json',
-        },
+        headers: this.#headers,
         body: JSON.stringify({
           type,
           version: known?.version ?? '1',
@@ -177,16 +461,33 @@ class Twitch extends SocketService {
         }),
       })
 
-      if (!response.ok) failures.push(`${type} (${response.status})`)
+      if (!response.ok) failures.push({ type, status: response.status })
     }
 
+    // Every one refused as unauthorised is a token that died between the refresh
+    // check and now. One refresh and one more go, not a loop.
+    if (!retried && !this.#mock && failures.length === this.types.length && failures.every((failure) => failure.status === 401) && this.config.refresh) {
+      await this.#fresh({ force: true })
+
+      return this.#subscribe(session, true)
+    }
+
+    const said = failures.map((failure) => `${failure.type} (${failure.status})`).join(', ')
+
+    this.#refused = failures.length < this.types.length ? failures.map((failure) => failure.type) : []
+
     // 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(', ')}`)
+    if (failures.length === this.types.length) throw new Error(`Twitch refused every subscription: ${said}`)
+    if (failures.length) console.warn(`[twitch] some subscriptions were refused: ${said}`)
+
+    return undefined
   }
 
   async close() {
+    // A sign-in waiting on the operator ends with the plugin that started it.
+    this.#signing = null
+    this.#waiting = null
     this.#next?.close()
     this.#next = null
     await super.close()
@@ -223,48 +524,76 @@ export class TwitchHandler extends PluginHandler {
   onRevoked() {}
 }
 
+/**
+ * @typedef {object} TwitchOptions
+ * @property {string} [clientId] Your Twitch application's Client ID. Public, not a
+ *   secret, so it belongs in the build: register one app, as a *Public* client, and
+ *   every operator of the studio signs in through it without ever seeing Twitch's
+ *   developer console. Leave it out and the panel asks each operator for one.
+ * @property {string[]} [events] Only these events, by handler name (`'chat'`,
+ *   `'follow'`, `'subscribe'`, `'resub'`, `'gift'`, `'cheer'`, `'raid'`) or by
+ *   Twitch's type. All of them if left out. Twitch asks for the permissions these
+ *   need at sign-in, so a chat-only studio asks only to read chat.
+ * @property {boolean} [mock] Talk to the Twitch CLI's mock server on this machine
+ *   instead of Twitch. No sign-in. See dev/README.md in this package.
+ * @property {string} [eventsub] Override the EventSub WebSocket address.
+ * @property {string} [helix] Override the Helix API base, without a trailing slash.
+ */
+
 /**
  * @param {typeof TwitchHandler} [Handler] The studio's subclass.
+ * @param {TwitchOptions} [options]
  */
-export const twitch = (Handler = TwitchHandler) =>
+export const twitch = (Handler = TwitchHandler, options = {}) =>
   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.',
+          'Press Sign in with Twitch.',
+          'Go to twitch.tv/activate on any device — your phone is fine — and sign in as the channel.',
+          'Type the code shown here, and approve.',
+          'That is all. This machine stays signed in until you sign out.',
         ],
       },
-      { 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: 'text',
+        text: `Once you are signed in, this studio gets ${list(typesFor(options.events).map((type) => WORDS[type] ?? type))}. If Twitch will not send some of them to your sign-in, this panel says which.`,
       },
-      { 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.',
+        text: 'Running a board for somebody else’s channel as their moderator? Sign in as yourself and type their channel name under Channel. You get chat, follows and raids; subs, gifts and cheers only go to the channel’s own sign-in.',
       },
     ],
+    actions: [
+      { key: 'signIn', label: 'Sign in with Twitch' },
+      { key: 'cancel', label: 'Cancel sign-in' },
+      { key: 'signOut', label: 'Sign out' },
+    ],
     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.' },
+      // Only when the studio did not bring one. An operator should never have to
+      // visit Twitch's developer console; the author does it once for everybody.
+      ...(options.clientId || options.mock
+        ? []
+        : [
+            {
+              key: 'clientId',
+              label: 'Client ID',
+              help: 'This studio does not come with one. From an app registered as a Public client at dev.twitch.tv/console/apps.',
+            },
+          ]),
+      {
+        key: 'channel',
+        label: 'Channel',
+        placeholder: 'The one you signed in as',
+        help: 'Blank for your own. A moderator types the channel’s name.',
+      },
     ],
     create: (context) => {
-      const plugin = new Twitch(context)
+      const plugin = new Twitch(context, options)
 
       new Handler({ ...context, plugin }).attach(plugin.events)
 

package/src/protocol.js

@@ -70,7 +70,7 @@ export class Protocol {
   /**
    * Decide what a raw message means.
    *
-   * @param {unknown} raw Already JSON.parse'd.
+   * @param {any} raw Already JSON.parse'd, from a socket -- so nothing about its shape is known yet.
    * @returns {Action}
    */
   handle(raw) {