@openclaw/twitch 2026.2.21

package/src/plugin.ts

@@ -0,0 +1,274 @@
+/**
+ * Twitch channel plugin for OpenClaw.
+ *
+ * Main plugin export combining all adapters (outbound, actions, status, gateway).
+ * This is the primary entry point for the Twitch channel integration.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { twitchMessageActions } from "./actions.js";
+import { removeClientManager } from "./client-manager-registry.js";
+import { TwitchConfigSchema } from "./config-schema.js";
+import { DEFAULT_ACCOUNT_ID, getAccountConfig, listAccountIds } from "./config.js";
+import { twitchOnboardingAdapter } from "./onboarding.js";
+import { twitchOutbound } from "./outbound.js";
+import { probeTwitch } from "./probe.js";
+import { resolveTwitchTargets } from "./resolver.js";
+import { collectTwitchStatusIssues } from "./status.js";
+import { resolveTwitchToken } from "./token.js";
+import type {
+  ChannelAccountSnapshot,
+  ChannelCapabilities,
+  ChannelLogSink,
+  ChannelMeta,
+  ChannelPlugin,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  TwitchAccountConfig,
+} from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+/**
+ * Twitch channel plugin.
+ *
+ * Implements the ChannelPlugin interface to provide Twitch chat integration
+ * for OpenClaw. Supports message sending, receiving, access control, and
+ * status monitoring.
+ */
+export const twitchPlugin: ChannelPlugin<TwitchAccountConfig> = {
+  /** Plugin identifier */
+  id: "twitch",
+
+  /** Plugin metadata */
+  meta: {
+    id: "twitch",
+    label: "Twitch",
+    selectionLabel: "Twitch (Chat)",
+    docsPath: "/channels/twitch",
+    blurb: "Twitch chat integration",
+    aliases: ["twitch-chat"],
+  } satisfies ChannelMeta,
+
+  /** Onboarding adapter */
+  onboarding: twitchOnboardingAdapter,
+
+  /** Pairing configuration */
+  pairing: {
+    idLabel: "twitchUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(twitch:)?user:?/i, ""),
+    notifyApproval: async ({ id }) => {
+      // Note: Twitch doesn't support DMs from bots, so pairing approval is limited
+      // We'll log the approval instead
+      console.warn(`Pairing approved for user ${id} (notification sent via chat if possible)`);
+    },
+  },
+
+  /** Supported chat capabilities */
+  capabilities: {
+    chatTypes: ["group"],
+  } satisfies ChannelCapabilities,
+
+  /** Configuration schema for Twitch channel */
+  configSchema: buildChannelConfigSchema(TwitchConfigSchema),
+
+  /** Account configuration management */
+  config: {
+    /** List all configured account IDs */
+    listAccountIds: (cfg: OpenClawConfig): string[] => listAccountIds(cfg),
+
+    /** Resolve an account config by ID */
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string | null): TwitchAccountConfig => {
+      const account = getAccountConfig(cfg, accountId ?? DEFAULT_ACCOUNT_ID);
+      if (!account) {
+        // Return a default/empty account if not configured
+        return {
+          username: "",
+          accessToken: "",
+          clientId: "",
+          enabled: false,
+        } as TwitchAccountConfig;
+      }
+      return account;
+    },
+
+    /** Get the default account ID */
+    defaultAccountId: (): string => DEFAULT_ACCOUNT_ID,
+
+    /** Check if an account is configured */
+    isConfigured: (_account: unknown, cfg: OpenClawConfig): boolean => {
+      const account = getAccountConfig(cfg, DEFAULT_ACCOUNT_ID);
+      const tokenResolution = resolveTwitchToken(cfg, { accountId: DEFAULT_ACCOUNT_ID });
+      return account ? isAccountConfigured(account, tokenResolution.token) : false;
+    },
+
+    /** Check if an account is enabled */
+    isEnabled: (account: TwitchAccountConfig | undefined): boolean => account?.enabled !== false,
+
+    /** Describe account status */
+    describeAccount: (account: TwitchAccountConfig | undefined) => {
+      return {
+        accountId: DEFAULT_ACCOUNT_ID,
+        enabled: account?.enabled !== false,
+        configured: account ? isAccountConfigured(account, account?.accessToken) : false,
+      };
+    },
+  },
+
+  /** Outbound message adapter */
+  outbound: twitchOutbound,
+
+  /** Message actions adapter */
+  actions: twitchMessageActions,
+
+  /** Resolver adapter for username -> user ID resolution */
+  resolver: {
+    resolveTargets: async ({
+      cfg,
+      accountId,
+      inputs,
+      kind,
+      runtime,
+    }: {
+      cfg: OpenClawConfig;
+      accountId?: string | null;
+      inputs: string[];
+      kind: ChannelResolveKind;
+      runtime: import("../../../src/runtime.js").RuntimeEnv;
+    }): Promise<ChannelResolveResult[]> => {
+      const account = getAccountConfig(cfg, accountId ?? DEFAULT_ACCOUNT_ID);
+
+      if (!account) {
+        return inputs.map((input) => ({
+          input,
+          resolved: false,
+          note: "account not configured",
+        }));
+      }
+
+      // Adapt RuntimeEnv.log to ChannelLogSink
+      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 monitoring adapter */
+  status: {
+    /** Default runtime state */
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+
+    /** Build channel summary from snapshot */
+    buildChannelSummary: ({ snapshot }: { snapshot: ChannelAccountSnapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+
+    /** Probe account connection */
+    probeAccount: async ({
+      account,
+      timeoutMs,
+    }: {
+      account: TwitchAccountConfig;
+      timeoutMs: number;
+    }): Promise<unknown> => {
+      return await probeTwitch(account, timeoutMs);
+    },
+
+    /** Build account snapshot with current status */
+    buildAccountSnapshot: ({
+      account,
+      cfg,
+      runtime,
+      probe,
+    }: {
+      account: TwitchAccountConfig;
+      cfg: OpenClawConfig;
+      runtime?: ChannelAccountSnapshot;
+      probe?: unknown;
+    }): ChannelAccountSnapshot => {
+      const twitch = (cfg as Record<string, unknown>).channels as
+        | Record<string, unknown>
+        | undefined;
+      const twitchCfg = twitch?.twitch as Record<string, unknown> | undefined;
+      const accountMap = (twitchCfg?.accounts as Record<string, unknown> | undefined) ?? {};
+      const resolvedAccountId =
+        Object.entries(accountMap).find(([, value]) => value === account)?.[0] ??
+        DEFAULT_ACCOUNT_ID;
+      const tokenResolution = resolveTwitchToken(cfg, { accountId: resolvedAccountId });
+      return {
+        accountId: resolvedAccountId,
+        enabled: account?.enabled !== false,
+        configured: isAccountConfigured(account, tokenResolution.token),
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        probe,
+      };
+    },
+
+    /** Collect status issues for all accounts */
+    collectStatusIssues: collectTwitchStatusIssues,
+  },
+
+  /** Gateway adapter for connection lifecycle */
+  gateway: {
+    /** Start an account connection */
+    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}`);
+
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorTwitchProvider } = await import("./monitor.js");
+      await monitorTwitchProvider({
+        account,
+        accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+      });
+    },
+
+    /** Stop an account connection */
+    stopAccount: async (ctx): Promise<void> => {
+      const account = ctx.account;
+      const accountId = ctx.accountId;
+
+      // Disconnect and remove client manager from registry
+      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: class {},
+}));
+
+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,119 @@
+import { StaticAuthProvider } from "@twurple/auth";
+import { ChatClient } from "@twurple/chat";
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
+import type { TwitchAccountConfig } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Result of probing a Twitch account
+ */
+export 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"));
+      });
+    });
+
+    const timeout = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+
+    client.connect();
+    await Promise.race([connectionPromise, timeout]);
+
+    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: error instanceof Error ? error.message : String(error),
+      username: account.username,
+      channel: account.channel,
+      elapsedMs: Date.now() - started,
+    };
+  } finally {
+    if (client) {
+      try {
+        client.quit();
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}