@overlaysymphony/twitch 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# `@overlaysymphony/obs`
+
+This module enables [Twitch](https://dev.twitch.tv/docs/) integrations for the [OverlaySymphony interactive streaming framework](https://github.com/OverlaySymphony/overlaysymphony), including authentication, chat, eventsub, helix, and several helpers.
+
+# OverlaySymphony
+
+An interactive streaming framework for orchestrating overlays, bots, and other services.
+
+> Note: This project is still very much under development. I use it actively on my own stream, so all releases should be fully functional. I will do my best to follow semver, though I cannot make any guarantees about release timelines or stability at this time.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@overlaysymphony/twitch",
+  "version": "0.1.0",
+  "description": "Twitch module for the OverlaySymphony interactive streaming framework.",
+  "homepage": "https://github.com/OverlaySymphony/overlaysymphony",
+  "type": "module",
+  "exports": {
+    "./authentication": "./src/authentication/index.js",
+    "./chat": "./src/chat/index.js",
+    "./eventsub": "./src/eventsub/index.js",
+    "./helix/*": "./src/helix/*/index.js",
+    "./helpers/*": "./src/helpers/*/index.js",
+    "./ui/*": "./src/ui/*.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "lint": "pnpm run \"/^lint-.*/\"",
+    "lint-typecheck": "tsc --noEmit",
+    "lint-eslint": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx .",
+    "lint-prettier": "prettier --check .",
+    "lint-depcheck": "depcheck .",
+    "test": "vitest",
+    "dev": "echo TODO",
+    "clean": "rm -rf node_modules/.cache tsconfig.tsbuildinfo dist",
+    "build": "echo TODO"
+  },
+  "dependencies": {
+    "@overlaysymphony/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@overlaysymphony/eslint-config": "workspace:*",
+    "@overlaysymphony/tooling": "workspace:*",
+    "@vitest/coverage-v8": "^2.1.2",
+    "depcheck": "catalog:",
+    "eslint": "catalog:",
+    "prettier": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "^2.1.2"
+  }
+}

package/src/authentication/authentication.ts

@@ -0,0 +1,107 @@
+import querystring from "@overlaysymphony/core/libs/querystring"
+
+import { TwitchUser, getUsers } from "../helix/users/index.js"
+
+export interface Authentication {
+  clientId: string
+  tokenType: "bearer"
+  accessToken: string
+  scope: string[]
+  expires: Date
+  user: TwitchUser
+}
+
+export type BareAuthentication = Omit<Authentication, "user">
+
+interface TAValidation {
+  client_id: string
+  login: string
+  scope: string[]
+  user_id: string
+  expires_in: number
+}
+
+interface TAResult {
+  token_type: "bearer"
+  access_token: string
+  scope: string
+}
+
+const localStorageKey = "overlaysymphony:service:twitch"
+
+export async function getAuthentication(): Promise<Authentication> {
+  const raw = localStorage.getItem(localStorageKey)
+  if (!raw) {
+    throw new Error("Twitch authentication missing!")
+  }
+
+  const cached = JSON.parse(raw) as BareAuthentication
+  cached.expires = new Date(cached.expires)
+
+  const [user] = await getUsers(cached as Authentication)
+
+  const authentication: Authentication = {
+    ...cached,
+    user,
+  }
+
+  return authentication
+}
+
+export function initiateAuthentication(
+  clientId: string,
+  redirect: string,
+  scope: string[],
+): string {
+  return `https://id.twitch.tv/oauth2/authorize?${querystring.stringify({
+    response_type: "token",
+    client_id: clientId,
+    redirect_uri: redirect,
+    scope: scope.join("+"),
+    state: clientId,
+  })}`
+}
+
+export async function validateAuthentication(
+  authentication: Omit<BareAuthentication, "expires">,
+): Promise<BareAuthentication> {
+  const response = await fetch("https://id.twitch.tv/oauth2/validate", {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${authentication.accessToken}`,
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(await response.text())
+  }
+
+  const validated = (await response.json()) as TAValidation
+
+  if (validated.client_id !== authentication.clientId) {
+    throw new Error("ClientId mismatch.")
+  }
+
+  return {
+    ...authentication,
+    expires: new Date(Date.now() + validated.expires_in * 1000),
+  }
+}
+
+export async function authenticateResult(
+  clientId: string,
+  result: TAResult,
+): Promise<BareAuthentication> {
+  if (!result.token_type || !result.access_token || !result.scope) {
+    throw new Error("Invalid result.")
+  }
+
+  const authentication = await validateAuthentication({
+    clientId,
+    tokenType: result.token_type,
+    accessToken: result.access_token,
+    scope: result.scope.split("+"),
+  })
+
+  return authentication
+}

package/src/authentication/index.ts

@@ -0,0 +1 @@
+export * from "./authentication.js"

package/src/chat/chat.ts

@@ -0,0 +1,160 @@
+import createDefer from "@overlaysymphony/core/libs/defer"
+import createPubSub from "@overlaysymphony/core/libs/pubsub"
+
+import { Authentication } from "../authentication/index.js"
+
+import { TwitchChatEvent, TwitchChatEventType } from "./interfaces/index.js"
+import parseCommand from "./parser.js"
+
+type ChatListener = (callback: (event: TwitchChatEvent) => void) => () => void
+
+type ChatSubscriber = <
+  EventType extends TwitchChatEventType,
+  Event extends TwitchChatEvent<EventType>,
+>(
+  types: EventType[],
+  callback: (event: Event) => void,
+) => () => void
+
+type ChatSender = (message: string) => void
+
+type ChatMessageSubscriber = (
+  callback: (event: TwitchChatEvent<"PRIVMSG">) => void,
+) => () => void
+
+type ChatCommandSubscriber = {
+  (
+    callback: (event: TwitchChatEvent<"PRIVMSG-COMMAND">) => void,
+    name?: never,
+  ): () => void
+  (
+    name: string,
+    callback: (event: TwitchChatEvent<"PRIVMSG-COMMAND">) => void,
+  ): () => void
+}
+
+export interface TwitchChat {
+  listen: ChatListener
+  subscribe: ChatSubscriber
+  send: ChatSender
+  onMessage: ChatMessageSubscriber
+  onCommand: ChatCommandSubscriber
+}
+
+export async function createChat(
+  authentication: Authentication,
+  channel: string = authentication.user.login,
+): Promise<TwitchChat> {
+  const { promise, resolve } = createDefer()
+
+  const pubsub = createPubSub<TwitchChatEvent>()
+  const socket = new WebSocket("wss://irc-ws.chat.twitch.tv:443")
+
+  socket.addEventListener("open", (connection) => {
+    socket.send("CAP REQ :twitch.tv/tags twitch.tv/commands")
+  })
+
+  socket.addEventListener("message", ({ data }: { data: string }) => {
+    const messages = data.split("\r\n").filter(Boolean)
+    for (const input of messages) {
+      const command = parseCommand(input)
+      if (!command) {
+        continue
+      }
+
+      if (
+        command.type === "001" ||
+        command.type === "JOIN" ||
+        command.type === "USERSTATE" ||
+        command.type === "HOSTTARGET" ||
+        command.type === "NOTICE" ||
+        false
+      ) {
+        continue
+      }
+
+      if (command.type === "PING") {
+        socket.send(`PONG :${command.message}`)
+        continue
+      }
+
+      if (command.type === "CAP") {
+        socket.send(`PASS oauth:${authentication.accessToken}`)
+        socket.send(`NICK ${authentication.user.login}`)
+        continue
+      }
+
+      if (command.type === "RECONNECT") {
+        console.warn("The server is about to terminate for maintenance.")
+        continue
+      }
+
+      if (command.type === "GLOBALUSERSTATE") {
+        socket.send(`JOIN #${channel}`)
+        continue
+      }
+
+      if (command.type === "ROOMSTATE") {
+        resolve()
+        continue
+      }
+
+      pubsub.dispatch(command)
+    }
+  })
+
+  return promise.then(() => {
+    const listen: ChatListener = (callback) => {
+      return pubsub.subscribe((event) => {
+        // @ts-ignore
+        callback(event)
+      })
+    }
+
+    const subscribe: ChatSubscriber = (types, callback) => {
+      return pubsub.subscribe((event) => {
+        // @ts-ignore
+        if (types.includes(event.type)) {
+          // @ts-ignore
+          callback(event)
+        }
+      })
+    }
+
+    const send: ChatSender = (message) => {
+      socket.send(`PRIVMSG #${authentication.user.login} :${message}`)
+    }
+
+    const onMessage: ChatMessageSubscriber = (callback) => {
+      return pubsub.subscribe((event) => {
+        if (event.type === "PRIVMSG") {
+          callback(event)
+        }
+      })
+    }
+
+    const onCommand: ChatCommandSubscriber = (...args) => {
+      const name = typeof args[0] === "string" ? args[0] : undefined
+      const callback = typeof args[0] === "function" ? args[0] : args[1]
+      if (!callback) {
+        throw new Error("onCommand: Missing callback.")
+      }
+
+      return pubsub.subscribe((event) => {
+        if (event.type === "PRIVMSG-COMMAND") {
+          if (typeof name === "undefined" || event.command === name) {
+            callback(event)
+          }
+        }
+      })
+    }
+
+    return {
+      listen,
+      subscribe,
+      send,
+      onMessage,
+      onCommand,
+    }
+  })
+}

package/src/chat/index.ts

@@ -0,0 +1,6 @@
+export type {
+  TwitchChatEventType,
+  TwitchChatEvent,
+} from "./interfaces/index.js"
+
+export * from "./chat.js"

package/src/chat/interfaces/events.ts

@@ -0,0 +1,269 @@
+export interface ChatEventSource {
+  host: string
+  user?: string
+}
+
+type AllOrNothing<T> = T | Partial<Record<keyof T, undefined>>
+
+type TagUserType = "staff" | "global_mod" | "admin" | undefined
+type TagBadges = Record<string, number>
+type TagBadgeInfo = Record<string, number>
+type TagEmotes = Record<
+  string,
+  Array<[startPosition: string, endPosition: string]>
+>
+
+export type PingEvent = {
+  type: "PING"
+  message: string
+  source?: ChatEventSource
+}
+
+export type WelcomeEvent = {
+  type: "001" // Logged in (successfully authenticated)
+  channel: string
+  message: string
+  source?: ChatEventSource
+}
+
+export type CapabilitiesEvent = {
+  type: "CAP"
+  enabled: boolean
+  nickname: string
+  capabilities: string[]
+  source?: ChatEventSource
+}
+
+export type JoinEvent = {
+  type: "JOIN"
+  channel: string
+  source?: ChatEventSource
+}
+
+export type PartEvent = {
+  type: "PART"
+  channel: string
+  source?: ChatEventSource
+}
+
+export type GlobalUserStateEvent = {
+  type: "GLOBALUSERSTATE"
+  tags: {
+    userId: string
+    userType: TagUserType
+    displayName?: string
+    color?: string
+    badges?: TagBadges
+    badgeInfo?: TagBadgeInfo
+    emoteSets?: string[]
+  }
+  source?: ChatEventSource
+}
+
+export type ReconnectEvent = {
+  type: "RECONNECT"
+  source?: ChatEventSource
+}
+
+export type ClearChatEvent = {
+  type: "CLEARCHAT"
+  channel: string
+  tags: {
+    roomId: string
+    targetUserId: string
+    banDuration: number
+  }
+  source?: ChatEventSource
+}
+
+export type HostTargetEvent = {
+  type: "HOSTTARGET"
+  channel: string
+  source?: ChatEventSource
+}
+
+export type NoticeEvent = {
+  type: "NOTICE"
+  channel: string
+  tags: {
+    msgId: string
+    targetUserId: string
+  }
+  source?: ChatEventSource
+}
+
+export type RoomStateEvent = {
+  type: "ROOMSTATE"
+  channel: string
+  tags: {
+    roomId: string
+    slow: number
+    emoteOnly: boolean
+    followersOnly: boolean
+    subsOnly: boolean
+  }
+  source?: ChatEventSource
+}
+
+export type UserStateEvent = {
+  type: "USERSTATE"
+  channel: string
+  tags: {
+    id: string
+    userId: string
+    userType: TagUserType
+    displayName?: string
+    color?: string
+    badges?: TagBadges
+    badgeInfo?: TagBadgeInfo
+    emoteSets?: string[]
+
+    mod: boolean
+    subscriber: boolean
+    vip: boolean
+    turbo: boolean
+  }
+  source?: ChatEventSource
+}
+
+export type ClearMessageEvent = {
+  type: "CLEARMSG"
+  channel: string
+  tags: {
+    login: string
+    roomId: string
+    targetMsgId?: string
+  }
+  source?: ChatEventSource
+}
+
+export type UserNoticeEvent = {
+  type: "USERNOTICE"
+  channel: string
+  tags: {
+    id: string
+    userId: string
+    userType: TagUserType
+    displayName?: string
+    login: string
+    color?: string
+    badges?: TagBadges
+    badgeInfo?: TagBadgeInfo
+    emotes?: TagEmotes
+    roomId: string
+    systemMsg: string
+    msgId:
+      | "sub"
+      | "resub"
+      | "subgift"
+      | "submysterygift"
+      | "giftpaidupgrade"
+      | "rewardgift"
+      | "anongiftpaidupgrade"
+      | "raid"
+      | "unraid"
+      | "ritual"
+      | "bitsbadgetier"
+
+    mod: boolean
+    subscriber: boolean
+    vip: boolean
+    turbo: boolean
+  }
+  source?: ChatEventSource
+}
+
+export type ChatMessageEvent = {
+  type: "PRIVMSG"
+  channel: string
+  message: string
+  tags: {
+    id: string
+    userId: string
+    userType: TagUserType
+    displayName?: string
+    color?: string
+    badges?: TagBadges
+    badgeInfo?: TagBadgeInfo
+    emotes?: TagEmotes
+    roomId: string
+
+    firstMsg: boolean
+    mod: boolean
+    subscriber: boolean
+    vip: boolean
+    turbo: boolean
+  } & AllOrNothing<{
+    replyThreadParentMsgId: string
+    replyThreadParentUserLogin: string
+    replyParentMsgId: string
+    replyParentUserId: string
+    replyParentUserLogin: string
+    replyParentDisplayName: string
+    replyParentMsgBody: string
+  }> &
+    AllOrNothing<{
+      pinnedChatPaidIsSystemMessage: boolean
+      pinnedChatPaidLevel: string
+      pinnedChatPaidAmount: number
+      pinnedChatPaidExponent: number
+      pinnedChatPaidCurrency: string
+    }>
+  source?: ChatEventSource
+}
+
+export type WhisperMessageEvent = {
+  type: "WHISPER"
+  channel: string
+  message: string
+  tags: {
+    messageId: string
+    threadId: string
+    userId: string
+    userType: TagUserType
+    displayName?: string
+    color?: string
+    badges?: TagBadges
+    emotes?: TagEmotes
+    turbo: boolean
+  }
+  source?: ChatEventSource
+}
+
+export type ChatCommandEvent = {
+  type: "PRIVMSG-COMMAND"
+  channel: string
+  command: string
+  parameters?: string
+  tags: ChatMessageEvent["tags"]
+  source?: ChatEventSource
+}
+
+export type WhisperCommandEvent = {
+  type: "WHISPER-COMMAND"
+  channel: string
+  command: string
+  parameters?: string
+  tags: WhisperMessageEvent["tags"]
+  source?: ChatEventSource
+}
+
+export type ChatEvent =
+  | PingEvent
+  | WelcomeEvent
+  | CapabilitiesEvent
+  | JoinEvent
+  | PartEvent
+  | GlobalUserStateEvent
+  | ReconnectEvent
+  | ClearChatEvent
+  | HostTargetEvent
+  | NoticeEvent
+  | RoomStateEvent
+  | UserStateEvent
+  | ClearMessageEvent
+  | UserNoticeEvent
+  | ChatMessageEvent
+  | WhisperMessageEvent
+  | ChatCommandEvent
+  | WhisperCommandEvent

package/src/chat/interfaces/index.ts

@@ -0,0 +1,9 @@
+import { ChatEvent } from "./events.js"
+
+export type { ChatEvent, ChatEventSource } from "./events.js"
+
+export type TwitchChatEventType = ChatEvent["type"]
+
+export type TwitchChatEvent<
+  Type extends TwitchChatEventType = TwitchChatEventType,
+> = Extract<ChatEvent, { type: Type }>