@kodelyth/twitch 2026.5.39 → 2026.5.42

package/src/plugin.ts

@@ -0,0 +1,220 @@
+/**
+ * Twitch channel plugin for Klaw.
+ *
+ * Main plugin export combining all adapters (outbound, actions, status, gateway).
+ * This is the primary entry point for the Twitch channel integration.
+ */
+
+import { describeAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
+import { buildChannelConfigSchema } from "klaw/plugin-sdk/channel-config-schema";
+import { createChatChannelPlugin } from "klaw/plugin-sdk/channel-core";
+import {
+  createLoggedPairingApprovalNotifier,
+  createPairingPrefixStripper,
+} from "klaw/plugin-sdk/channel-pairing";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import {
+  buildPassiveProbedChannelStatusSummary,
+  runStoppablePassiveMonitor,
+} from "klaw/plugin-sdk/extension-shared";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "klaw/plugin-sdk/status-helpers";
+import { twitchMessageActions } from "./actions.js";
+import { removeClientManager } from "./client-manager-registry.js";
+import { TwitchConfigSchema } from "./config-schema.js";
+import {
+  DEFAULT_ACCOUNT_ID,
+  getAccountConfig,
+  listAccountIds,
+  resolveDefaultTwitchAccountId,
+  resolveTwitchAccountContext,
+  resolveTwitchSnapshotAccountId,
+} from "./config.js";
+import { twitchMessageAdapter, twitchOutbound } from "./outbound.js";
+import { probeTwitch } from "./probe.js";
+import { resolveTwitchTargets } from "./resolver.js";
+import { twitchSetupAdapter, twitchSetupWizard } from "./setup-surface.js";
+import { collectTwitchStatusIssues } from "./status.js";
+import type {
+  ChannelLogSink,
+  ChannelPlugin,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  TwitchAccountConfig,
+} from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+type ResolvedTwitchAccount = TwitchAccountConfig & { accountId?: string | null };
+
+/**
+ * Twitch channel plugin.
+ *
+ * Implements the ChannelPlugin interface to provide Twitch chat integration
+ * for Klaw. Supports message sending, receiving, access control, and
+ * status monitoring.
+ */
+export const twitchPlugin: ChannelPlugin<ResolvedTwitchAccount> =
+  createChatChannelPlugin<ResolvedTwitchAccount>({
+    pairing: {
+      idLabel: "twitchUserId",
+      normalizeAllowEntry: createPairingPrefixStripper(/^(twitch:)?user:?/i),
+      notifyApproval: createLoggedPairingApprovalNotifier(
+        ({ id }) => `Pairing approved for user ${id} (notification sent via chat if possible)`,
+        console.warn,
+      ),
+    },
+    outbound: twitchOutbound,
+    base: {
+      id: "twitch",
+      meta: {
+        id: "twitch",
+        label: "Twitch",
+        selectionLabel: "Twitch (Chat)",
+        docsPath: "/channels/twitch",
+        blurb: "Twitch chat integration",
+        aliases: ["twitch-chat"],
+      },
+      setup: twitchSetupAdapter,
+      setupWizard: twitchSetupWizard,
+      capabilities: {
+        chatTypes: ["group"],
+      },
+      message: twitchMessageAdapter,
+      configSchema: buildChannelConfigSchema(TwitchConfigSchema),
+      config: {
+        listAccountIds: (cfg: KlawConfig): string[] => listAccountIds(cfg),
+        resolveAccount: (cfg: KlawConfig, accountId?: string | null): ResolvedTwitchAccount => {
+          const resolvedAccountId = accountId ?? resolveDefaultTwitchAccountId(cfg);
+          const account = getAccountConfig(cfg, resolvedAccountId);
+          if (!account) {
+            return {
+              accountId: resolvedAccountId,
+              channel: "",
+              username: "",
+              accessToken: "",
+              clientId: "",
+              enabled: false,
+            };
+          }
+          return {
+            accountId: resolvedAccountId,
+            ...account,
+          };
+        },
+        defaultAccountId: (cfg: KlawConfig): string => resolveDefaultTwitchAccountId(cfg),
+        isConfigured: (_account: unknown, cfg: KlawConfig): boolean =>
+          resolveTwitchAccountContext(cfg).configured,
+        isEnabled: (account: ResolvedTwitchAccount | undefined): boolean =>
+          account?.enabled !== false,
+        describeAccount: (account: TwitchAccountConfig | undefined) =>
+          account
+            ? describeAccountSnapshot({
+                account,
+                configured: isAccountConfigured(account, account.accessToken),
+              })
+            : {
+                accountId: DEFAULT_ACCOUNT_ID,
+                enabled: false,
+                configured: false,
+              },
+      },
+      actions: twitchMessageActions,
+      resolver: {
+        resolveTargets: async ({
+          cfg,
+          accountId,
+          inputs,
+          kind,
+          runtime,
+        }: {
+          cfg: KlawConfig;
+          accountId?: string | null;
+          inputs: string[];
+          kind: ChannelResolveKind;
+          runtime: import("klaw/plugin-sdk/runtime-env").RuntimeEnv;
+        }): Promise<ChannelResolveResult[]> => {
+          const account = getAccountConfig(cfg, accountId ?? resolveDefaultTwitchAccountId(cfg));
+          if (!account) {
+            return inputs.map((input) => ({
+              input,
+              resolved: false,
+              note: "account not configured",
+            }));
+          }
+
+          const log: ChannelLogSink = {
+            info: (msg) => runtime.log(msg),
+            warn: (msg) => runtime.log(msg),
+            error: (msg) => runtime.error(msg),
+            debug: (msg) => runtime.log(msg),
+          };
+          return await resolveTwitchTargets(inputs, account, kind, log);
+        },
+      },
+      status: createComputedAccountStatusAdapter<ResolvedTwitchAccount>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+        buildChannelSummary: ({ snapshot }) => buildPassiveProbedChannelStatusSummary(snapshot),
+        probeAccount: async ({ account, timeoutMs }) => await probeTwitch(account, timeoutMs),
+        collectStatusIssues: collectTwitchStatusIssues,
+        resolveAccountSnapshot: ({ account, cfg }) => {
+          const resolvedAccountId =
+            account.accountId || resolveTwitchSnapshotAccountId(cfg, account);
+          const { configured } = resolveTwitchAccountContext(cfg, resolvedAccountId);
+          return {
+            accountId: resolvedAccountId,
+            enabled: account.enabled !== false,
+            configured,
+          };
+        },
+      }),
+      gateway: {
+        startAccount: async (ctx): Promise<void> => {
+          const account = ctx.account;
+          const accountId = ctx.accountId;
+
+          ctx.setStatus?.({
+            accountId,
+            running: true,
+            lastStartAt: Date.now(),
+            lastError: null,
+          });
+
+          ctx.log?.info(`Starting Twitch connection for ${account.username}`);
+
+          // Keep startAccount pending until abort fires; otherwise the channel
+          // supervisor reads the settled task as `channel exited without an
+          // error` and triggers a restart loop. See #60071.
+          await runStoppablePassiveMonitor({
+            abortSignal: ctx.abortSignal,
+            start: async () => {
+              // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+              const { monitorTwitchProvider } = await import("./monitor.js");
+              return monitorTwitchProvider({
+                account,
+                accountId,
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+              });
+            },
+          });
+        },
+        stopAccount: async (ctx): Promise<void> => {
+          const account = ctx.account;
+          const accountId = ctx.accountId;
+
+          await removeClientManager(accountId);
+
+          ctx.setStatus?.({
+            accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+
+          ctx.log?.info(`Stopped Twitch connection for ${account.username}`);
+        },
+      },
+    },
+  });

package/src/probe.test.ts

@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { probeTwitch } from "./probe.js";
+import type { TwitchAccountConfig } from "./types.js";
+
+// Mock Twurple modules - Vitest v4 compatible mocking
+const mockUnbind = vi.fn();
+
+// Event handler storage
+let connectHandler: (() => void) | null = null;
+let disconnectHandler: ((manually: boolean, reason?: Error) => void) | null = null;
+
+// Event listener mocks that store handlers and return unbind function
+const mockOnConnect = vi.fn((handler: () => void) => {
+  connectHandler = handler;
+  return { unbind: mockUnbind };
+});
+
+const mockOnDisconnect = vi.fn((handler: (manually: boolean, reason?: Error) => void) => {
+  disconnectHandler = handler;
+  return { unbind: mockUnbind };
+});
+
+const mockOnAuthenticationFailure = vi.fn((_handler: () => void) => {
+  return { unbind: mockUnbind };
+});
+
+// Connect mock that triggers the registered handler
+const defaultConnectImpl = async () => {
+  // Simulate successful connection by calling the handler immediately.
+  if (connectHandler) {
+    connectHandler();
+  }
+};
+
+const mockConnect = vi.fn().mockImplementation(defaultConnectImpl);
+
+const mockQuit = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("@twurple/chat", () => ({
+  ChatClient: class {
+    connect = mockConnect;
+    quit = mockQuit;
+    onConnect = mockOnConnect;
+    onDisconnect = mockOnDisconnect;
+    onAuthenticationFailure = mockOnAuthenticationFailure;
+  },
+}));
+
+vi.mock("@twurple/auth", () => ({
+  StaticAuthProvider: function StaticAuthProvider() {},
+}));
+
+describe("probeTwitch", () => {
+  const mockAccount: TwitchAccountConfig = {
+    username: "testbot",
+    accessToken: "oauth:test123456789",
+    clientId: "test-client-id",
+    channel: "testchannel",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset handlers
+    connectHandler = null;
+    disconnectHandler = null;
+  });
+
+  it("returns error when username is missing", async () => {
+    const account = { ...mockAccount, username: "" };
+    const result = await probeTwitch(account, 5000);
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("missing credentials");
+  });
+
+  it("returns error when token is missing", async () => {
+    const account = { ...mockAccount, accessToken: "" };
+    const result = await probeTwitch(account, 5000);
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("missing credentials");
+  });
+
+  it("attempts connection regardless of token prefix", async () => {
+    // Note: probeTwitch doesn't validate token format - it tries to connect with whatever token is provided
+    // The actual connection would fail in production with an invalid token
+    const account = { ...mockAccount, accessToken: "raw_token_no_prefix" };
+    const result = await probeTwitch(account, 5000);
+
+    // With mock, connection succeeds even without oauth: prefix
+    expect(result.ok).toBe(true);
+  });
+
+  it("successfully connects with valid credentials", async () => {
+    const result = await probeTwitch(mockAccount, 5000);
+
+    expect(result.ok).toBe(true);
+    expect(result.connected).toBe(true);
+    expect(result.username).toBe("testbot");
+    expect(result.channel).toBe("testchannel"); // uses account's configured channel
+  });
+
+  it("uses custom channel when specified", async () => {
+    const account: TwitchAccountConfig = {
+      ...mockAccount,
+      channel: "customchannel",
+    };
+
+    const result = await probeTwitch(account, 5000);
+
+    expect(result.ok).toBe(true);
+    expect(result.channel).toBe("customchannel");
+  });
+
+  it("times out when connection takes too long", async () => {
+    vi.useFakeTimers();
+    try {
+      mockConnect.mockImplementationOnce(() => new Promise(() => {})); // Never resolves
+      const resultPromise = probeTwitch(mockAccount, 100);
+      await vi.advanceTimersByTimeAsync(100);
+      const result = await resultPromise;
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toContain("timeout");
+    } finally {
+      vi.useRealTimers();
+      mockConnect.mockImplementation(defaultConnectImpl);
+    }
+  });
+
+  it("cleans up client even on failure", async () => {
+    mockConnect.mockImplementationOnce(async () => {
+      // Simulate connection failure by calling disconnect handler
+      // onDisconnect signature: (manually: boolean, reason?: Error) => void
+      if (disconnectHandler) {
+        disconnectHandler(false, new Error("Connection failed"));
+      }
+    });
+
+    const result = await probeTwitch(mockAccount, 5000);
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("Connection failed");
+    expect(mockQuit).toHaveBeenCalled();
+
+    // Reset mocks
+    mockConnect.mockImplementation(defaultConnectImpl);
+  });
+
+  it("handles connection errors gracefully", async () => {
+    mockConnect.mockImplementationOnce(async () => {
+      // Simulate connection failure by calling disconnect handler
+      // onDisconnect signature: (manually: boolean, reason?: Error) => void
+      if (disconnectHandler) {
+        disconnectHandler(false, new Error("Network error"));
+      }
+    });
+
+    const result = await probeTwitch(mockAccount, 5000);
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("Network error");
+
+    // Reset mock
+    mockConnect.mockImplementation(defaultConnectImpl);
+  });
+
+  it("trims token before validation", async () => {
+    const account: TwitchAccountConfig = {
+      ...mockAccount,
+      accessToken: "  oauth:test123456789  ",
+    };
+
+    const result = await probeTwitch(account, 5000);
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("handles non-Error objects in catch block", async () => {
+    mockConnect.mockImplementationOnce(async () => {
+      // Simulate connection failure by calling disconnect handler
+      // onDisconnect signature: (manually: boolean, reason?: Error) => void
+      if (disconnectHandler) {
+        disconnectHandler(false, "String error" as unknown as Error);
+      }
+    });
+
+    const result = await probeTwitch(mockAccount, 5000);
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe("String error");
+
+    // Reset mock
+    mockConnect.mockImplementation(defaultConnectImpl);
+  });
+});

package/src/probe.ts

@@ -0,0 +1,130 @@
+import { StaticAuthProvider } from "@twurple/auth";
+import { ChatClient } from "@twurple/chat";
+import type { BaseProbeResult } from "klaw/plugin-sdk/channel-contract";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import type { TwitchAccountConfig } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Result of probing a Twitch account
+ */
+type ProbeTwitchResult = BaseProbeResult<string> & {
+  username?: string;
+  elapsedMs: number;
+  connected?: boolean;
+  channel?: string;
+};
+
+/**
+ * Probe a Twitch account to verify the connection is working
+ *
+ * This tests the Twitch OAuth token by attempting to connect
+ * to the chat server and verify the bot's username.
+ */
+export async function probeTwitch(
+  account: TwitchAccountConfig,
+  timeoutMs: number,
+): Promise<ProbeTwitchResult> {
+  const started = Date.now();
+
+  if (!account.accessToken || !account.username) {
+    return {
+      ok: false,
+      error: "missing credentials (accessToken, username)",
+      username: account.username,
+      elapsedMs: Date.now() - started,
+    };
+  }
+
+  const rawToken = normalizeToken(account.accessToken.trim());
+
+  let client: ChatClient | undefined;
+
+  try {
+    const authProvider = new StaticAuthProvider(account.clientId ?? "", rawToken);
+
+    client = new ChatClient({
+      authProvider,
+    });
+
+    // Create a promise that resolves when connected
+    const connectionPromise = new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let connectListener: ReturnType<ChatClient["onConnect"]> | undefined;
+      let disconnectListener: ReturnType<ChatClient["onDisconnect"]> | undefined;
+      let authFailListener: ReturnType<ChatClient["onAuthenticationFailure"]> | undefined;
+
+      const cleanup = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        connectListener?.unbind();
+        disconnectListener?.unbind();
+        authFailListener?.unbind();
+      };
+
+      // Success: connection established
+      connectListener = client?.onConnect(() => {
+        cleanup();
+        resolve();
+      });
+
+      // Failure: disconnected (e.g., auth failed)
+      disconnectListener = client?.onDisconnect((_manually, reason) => {
+        cleanup();
+        reject(reason || new Error("Disconnected"));
+      });
+
+      // Failure: authentication failed
+      authFailListener = client?.onAuthenticationFailure(() => {
+        cleanup();
+        reject(new Error("Authentication failed"));
+      });
+    });
+
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(
+        () => reject(new Error(`timeout after ${timeoutMs}ms`)),
+        timeoutMs,
+      );
+    });
+
+    client.connect();
+    try {
+      await Promise.race([connectionPromise, timeout]);
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+
+    client.quit();
+    client = undefined;
+
+    return {
+      ok: true,
+      connected: true,
+      username: account.username,
+      channel: account.channel,
+      elapsedMs: Date.now() - started,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: formatErrorMessage(error),
+      username: account.username,
+      channel: account.channel,
+      elapsedMs: Date.now() - started,
+    };
+  } finally {
+    if (client) {
+      try {
+        client.quit();
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}

package/src/resolver.ts

@@ -0,0 +1,139 @@
+/**
+ * Twitch resolver adapter for channel/user name resolution.
+ *
+ * This module implements the ChannelResolverAdapter interface to resolve
+ * Twitch usernames to user IDs via the Twitch Helix API.
+ */
+
+import { ApiClient } from "@twurple/api";
+import { StaticAuthProvider } from "@twurple/auth";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { ChannelResolveKind, ChannelResolveResult } from "./types.js";
+import type { ChannelLogSink, TwitchAccountConfig } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Normalize a Twitch username - strip @ prefix and convert to lowercase
+ */
+function normalizeUsername(input: string): string {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("@")) {
+    return normalizeLowercaseStringOrEmpty(trimmed.slice(1));
+  }
+  return normalizeLowercaseStringOrEmpty(trimmed);
+}
+
+/**
+ * Create a logger that includes the Twitch prefix
+ */
+function createLogger(logger?: ChannelLogSink): ChannelLogSink {
+  return {
+    info: (msg: string) => logger?.info(msg),
+    warn: (msg: string) => logger?.warn(msg),
+    error: (msg: string) => logger?.error(msg),
+    debug: (msg: string) => logger?.debug?.(msg) ?? (() => {}),
+  };
+}
+
+/**
+ * Resolve Twitch usernames to user IDs via the Helix API
+ *
+ * @param inputs - Array of usernames or user IDs to resolve
+ * @param account - Twitch account configuration with auth credentials
+ * @param kind - Type of target to resolve ("user" or "group")
+ * @param logger - Optional logger
+ * @returns Promise resolving to array of ChannelResolveResult
+ */
+export async function resolveTwitchTargets(
+  inputs: string[],
+  account: TwitchAccountConfig,
+  _kind: ChannelResolveKind,
+  logger?: ChannelLogSink,
+): Promise<ChannelResolveResult[]> {
+  const log = createLogger(logger);
+
+  if (!account.clientId || !account.accessToken) {
+    log.error("Missing Twitch client ID or accessToken");
+    return inputs.map((input) => ({
+      input,
+      resolved: false,
+      note: "missing Twitch credentials",
+    }));
+  }
+
+  const normalizedToken = normalizeToken(account.accessToken);
+
+  const authProvider = new StaticAuthProvider(account.clientId, normalizedToken);
+  const apiClient = new ApiClient({ authProvider });
+
+  const results: ChannelResolveResult[] = [];
+
+  for (const input of inputs) {
+    const normalized = normalizeUsername(input);
+
+    if (!normalized) {
+      results.push({
+        input,
+        resolved: false,
+        note: "empty input",
+      });
+      continue;
+    }
+
+    const looksLikeUserId = /^\d+$/.test(normalized);
+
+    try {
+      if (looksLikeUserId) {
+        const user = await apiClient.users.getUserById(normalized);
+
+        if (user) {
+          results.push({
+            input,
+            resolved: true,
+            id: user.id,
+            name: user.name,
+          });
+          log.debug?.(`Resolved user ID ${normalized} -> ${user.name}`);
+        } else {
+          results.push({
+            input,
+            resolved: false,
+            note: "user ID not found",
+          });
+          log.warn(`User ID ${normalized} not found`);
+        }
+      } else {
+        const user = await apiClient.users.getUserByName(normalized);
+
+        if (user) {
+          results.push({
+            input,
+            resolved: true,
+            id: user.id,
+            name: user.name,
+            note: user.displayName !== user.name ? `display: ${user.displayName}` : undefined,
+          });
+          log.debug?.(`Resolved username ${normalized} -> ${user.id} (${user.name})`);
+        } else {
+          results.push({
+            input,
+            resolved: false,
+            note: "username not found",
+          });
+          log.warn(`Username ${normalized} not found`);
+        }
+      }
+    } catch (error) {
+      const errorMessage = formatErrorMessage(error);
+      results.push({
+        input,
+        resolved: false,
+        note: `API error: ${errorMessage}`,
+      });
+      log.error(`Failed to resolve ${input}: ${errorMessage}`);
+    }
+  }
+
+  return results;
+}

package/src/runtime.ts

@@ -0,0 +1,9 @@
+import type { PluginRuntime } from "klaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "klaw/plugin-sdk/runtime-store";
+
+const { setRuntime: setTwitchRuntime, getRuntime: getTwitchRuntime } =
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "twitch",
+    errorMessage: "Twitch runtime not initialized",
+  });
+export { getTwitchRuntime, setTwitchRuntime };