@openclaw/twitch 2026.2.21

package/src/access-control.ts

@@ -0,0 +1,166 @@
+import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+
+/**
+ * Result of checking access control for a Twitch message
+ */
+export type TwitchAccessControlResult = {
+  allowed: boolean;
+  reason?: string;
+  matchKey?: string;
+  matchSource?: string;
+};
+
+/**
+ * Check if a Twitch message should be allowed based on account configuration
+ *
+ * This function implements the access control logic for incoming Twitch messages,
+ * checking allowlists, role-based restrictions, and mention requirements.
+ *
+ * Priority order:
+ * 1. If `requireMention` is true, message must mention the bot
+ * 2. If `allowFrom` is set, sender must be in the allowlist (by user ID)
+ * 3. If `allowedRoles` is set (and `allowFrom` is not), sender must have at least one role
+ *
+ * Note: `allowFrom` is a hard allowlist. When set, only those user IDs are allowed.
+ * Use `allowedRoles` as an alternative when you don't want to maintain an allowlist.
+ *
+ * Available roles:
+ * - "moderator": Moderators
+ * - "owner": Channel owner/broadcaster
+ * - "vip": VIPs
+ * - "subscriber": Subscribers
+ * - "all": Anyone in the chat
+ */
+export function checkTwitchAccessControl(params: {
+  message: TwitchChatMessage;
+  account: TwitchAccountConfig;
+  botUsername: string;
+}): TwitchAccessControlResult {
+  const { message, account, botUsername } = params;
+
+  if (account.requireMention ?? true) {
+    const mentions = extractMentions(message.message);
+    if (!mentions.includes(botUsername.toLowerCase())) {
+      return {
+        allowed: false,
+        reason: "message does not mention the bot (requireMention is enabled)",
+      };
+    }
+  }
+
+  if (account.allowFrom && account.allowFrom.length > 0) {
+    const allowFrom = account.allowFrom;
+    const senderId = message.userId;
+
+    if (!senderId) {
+      return {
+        allowed: false,
+        reason: "sender user ID not available for allowlist check",
+      };
+    }
+
+    if (allowFrom.includes(senderId)) {
+      return {
+        allowed: true,
+        matchKey: senderId,
+        matchSource: "allowlist",
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: "sender is not in allowFrom allowlist",
+    };
+  }
+
+  if (account.allowedRoles && account.allowedRoles.length > 0) {
+    const allowedRoles = account.allowedRoles;
+
+    // "all" grants access to everyone
+    if (allowedRoles.includes("all")) {
+      return {
+        allowed: true,
+        matchKey: "all",
+        matchSource: "role",
+      };
+    }
+
+    const hasAllowedRole = checkSenderRoles({
+      message,
+      allowedRoles,
+    });
+
+    if (!hasAllowedRole) {
+      return {
+        allowed: false,
+        reason: `sender does not have any of the required roles: ${allowedRoles.join(", ")}`,
+      };
+    }
+
+    return {
+      allowed: true,
+      matchKey: allowedRoles.join(","),
+      matchSource: "role",
+    };
+  }
+
+  return {
+    allowed: true,
+  };
+}
+
+/**
+ * Check if the sender has any of the allowed roles
+ */
+function checkSenderRoles(params: { message: TwitchChatMessage; allowedRoles: string[] }): boolean {
+  const { message, allowedRoles } = params;
+  const { isMod, isOwner, isVip, isSub } = message;
+
+  for (const role of allowedRoles) {
+    switch (role) {
+      case "moderator":
+        if (isMod) {
+          return true;
+        }
+        break;
+      case "owner":
+        if (isOwner) {
+          return true;
+        }
+        break;
+      case "vip":
+        if (isVip) {
+          return true;
+        }
+        break;
+      case "subscriber":
+        if (isSub) {
+          return true;
+        }
+        break;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract @mentions from a Twitch chat message
+ *
+ * Returns a list of lowercase usernames that were mentioned in the message.
+ * Twitch mentions are in the format @username.
+ */
+export function extractMentions(message: string): string[] {
+  const mentionRegex = /@(\w+)/g;
+  const mentions: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = mentionRegex.exec(message)) !== null) {
+    const username = match[1];
+    if (username) {
+      mentions.push(username.toLowerCase());
+    }
+  }
+
+  return mentions;
+}

package/src/actions.ts

@@ -0,0 +1,174 @@
+/**
+ * Twitch message actions adapter.
+ *
+ * Handles tool-based actions for Twitch, such as sending messages.
+ */
+
+import { DEFAULT_ACCOUNT_ID, getAccountConfig } from "./config.js";
+import { twitchOutbound } from "./outbound.js";
+import type { ChannelMessageActionAdapter, ChannelMessageActionContext } from "./types.js";
+
+/**
+ * Create a tool result with error content.
+ */
+function errorResponse(error: string) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ ok: false, error }),
+      },
+    ],
+    details: { ok: false },
+  };
+}
+
+/**
+ * Read a string parameter from action arguments.
+ *
+ * @param args - Action arguments
+ * @param key - Parameter key
+ * @param options - Options for reading the parameter
+ * @returns The parameter value or undefined if not found
+ */
+function readStringParam(
+  args: Record<string, unknown>,
+  key: string,
+  options: { required?: boolean; trim?: boolean } = {},
+): string | undefined {
+  const value = args[key];
+  if (value === undefined || value === null) {
+    if (options.required) {
+      throw new Error(`Missing required parameter: ${key}`);
+    }
+    return undefined;
+  }
+
+  // Convert value to string safely
+  if (typeof value === "string") {
+    return options.trim !== false ? value.trim() : value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    const str = String(value);
+    return options.trim !== false ? str.trim() : str;
+  }
+
+  throw new Error(`Parameter ${key} must be a string, number, or boolean`);
+}
+
+/** Supported Twitch actions */
+const TWITCH_ACTIONS = new Set(["send" as const]);
+type TwitchAction = typeof TWITCH_ACTIONS extends Set<infer U> ? U : never;
+
+/**
+ * Twitch message actions adapter.
+ */
+export const twitchMessageActions: ChannelMessageActionAdapter = {
+  /**
+   * List available actions for this channel.
+   */
+  listActions: () => [...TWITCH_ACTIONS],
+
+  /**
+   * Check if an action is supported.
+   */
+  supportsAction: ({ action }) => TWITCH_ACTIONS.has(action as TwitchAction),
+
+  /**
+   * Extract tool send parameters from action arguments.
+   *
+   * Parses and validates the "to" and "message" parameters for sending.
+   *
+   * @param params - Arguments from the tool call
+   * @returns Parsed send parameters or null if invalid
+   *
+   * @example
+   * const result = twitchMessageActions.extractToolSend!({
+   *   args: { to: "#mychannel", message: "Hello!" }
+   * });
+   * // Returns: { to: "#mychannel", message: "Hello!" }
+   */
+  extractToolSend: ({ args }) => {
+    try {
+      const to = readStringParam(args, "to", { required: true });
+      const message = readStringParam(args, "message", { required: true });
+
+      if (!to || !message) {
+        return null;
+      }
+
+      return { to, message };
+    } catch {
+      return null;
+    }
+  },
+
+  /**
+   * Handle an action execution.
+   *
+   * Processes the "send" action to send messages to Twitch.
+   *
+   * @param ctx - Action context including action type, parameters, and config
+   * @returns Tool result with content or null if action not supported
+   *
+   * @example
+   * const result = await twitchMessageActions.handleAction!({
+   *   action: "send",
+   *   params: { message: "Hello Twitch!", to: "#mychannel" },
+   *   cfg: openclawConfig,
+   *   accountId: "default",
+   * });
+   */
+  handleAction: async (ctx: ChannelMessageActionContext) => {
+    if (ctx.action !== "send") {
+      return {
+        content: [{ type: "text" as const, text: "Unsupported action" }],
+        details: { ok: false, error: "Unsupported action" },
+      };
+    }
+
+    const message = readStringParam(ctx.params, "message", { required: true });
+    const to = readStringParam(ctx.params, "to", { required: false });
+    const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
+
+    const account = getAccountConfig(ctx.cfg, accountId);
+    if (!account) {
+      return errorResponse(
+        `Account not found: ${accountId}. Available accounts: ${Object.keys(ctx.cfg.channels?.twitch?.accounts ?? {}).join(", ") || "none"}`,
+      );
+    }
+
+    // Use the channel from account config (or override with `to` parameter)
+    const targetChannel = to || account.channel;
+    if (!targetChannel) {
+      return errorResponse("No channel specified and no default channel in account config");
+    }
+
+    if (!twitchOutbound.sendText) {
+      return errorResponse("sendText not implemented");
+    }
+
+    try {
+      const result = await twitchOutbound.sendText({
+        cfg: ctx.cfg,
+        to: targetChannel,
+        text: message ?? "",
+        accountId,
+      });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result),
+          },
+        ],
+        details: { ok: true },
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return errorResponse(errorMsg);
+    }
+  },
+};

package/src/client-manager-registry.ts

@@ -0,0 +1,115 @@
+/**
+ * Client manager registry for Twitch plugin.
+ *
+ * Manages the lifecycle of TwitchClientManager instances across the plugin,
+ * ensuring proper cleanup when accounts are stopped or reconfigured.
+ */
+
+import { TwitchClientManager } from "./twitch-client.js";
+import type { ChannelLogSink } from "./types.js";
+
+/**
+ * Registry entry tracking a client manager and its associated account.
+ */
+type RegistryEntry = {
+  /** The client manager instance */
+  manager: TwitchClientManager;
+  /** The account ID this manager is for */
+  accountId: string;
+  /** Logger for this entry */
+  logger: ChannelLogSink;
+  /** When this entry was created */
+  createdAt: number;
+};
+
+/**
+ * Global registry of client managers.
+ * Keyed by account ID.
+ */
+const registry = new Map<string, RegistryEntry>();
+
+/**
+ * Get or create a client manager for an account.
+ *
+ * @param accountId - The account ID
+ * @param logger - Logger instance
+ * @returns The client manager
+ */
+export function getOrCreateClientManager(
+  accountId: string,
+  logger: ChannelLogSink,
+): TwitchClientManager {
+  const existing = registry.get(accountId);
+  if (existing) {
+    return existing.manager;
+  }
+
+  const manager = new TwitchClientManager(logger);
+  registry.set(accountId, {
+    manager,
+    accountId,
+    logger,
+    createdAt: Date.now(),
+  });
+
+  logger.info(`Registered client manager for account: ${accountId}`);
+  return manager;
+}
+
+/**
+ * Get an existing client manager for an account.
+ *
+ * @param accountId - The account ID
+ * @returns The client manager, or undefined if not registered
+ */
+export function getClientManager(accountId: string): TwitchClientManager | undefined {
+  return registry.get(accountId)?.manager;
+}
+
+/**
+ * Disconnect and remove a client manager from the registry.
+ *
+ * @param accountId - The account ID
+ * @returns Promise that resolves when cleanup is complete
+ */
+export async function removeClientManager(accountId: string): Promise<void> {
+  const entry = registry.get(accountId);
+  if (!entry) {
+    return;
+  }
+
+  // Disconnect the client manager
+  await entry.manager.disconnectAll();
+
+  // Remove from registry
+  registry.delete(accountId);
+  entry.logger.info(`Unregistered client manager for account: ${accountId}`);
+}
+
+/**
+ * Disconnect and remove all client managers from the registry.
+ *
+ * @returns Promise that resolves when all cleanup is complete
+ */
+export async function removeAllClientManagers(): Promise<void> {
+  const promises = [...registry.keys()].map((accountId) => removeClientManager(accountId));
+  await Promise.all(promises);
+}
+
+/**
+ * Get the number of registered client managers.
+ *
+ * @returns The count of registered managers
+ */
+export function getRegisteredClientManagerCount(): number {
+  return registry.size;
+}
+
+/**
+ * Clear all client managers without disconnecting.
+ *
+ * This is primarily for testing purposes.
+ */
+export function _clearAllClientManagersForTest(): void {
+  registry.clear();
+}

package/src/config-schema.ts

@@ -0,0 +1,84 @@
+import { MarkdownConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+/**
+ * Twitch user roles that can be allowed to interact with the bot
+ */
+const TwitchRoleSchema = z.enum(["moderator", "owner", "vip", "subscriber", "all"]);
+
+/**
+ * Twitch account configuration schema
+ */
+const TwitchAccountSchema = z.object({
+  /** Twitch username */
+  username: z.string(),
+  /** Twitch OAuth access token (requires chat:read and chat:write scopes) */
+  accessToken: z.string(),
+  /** Twitch client ID (from Twitch Developer Portal or twitchtokengenerator.com) */
+  clientId: z.string().optional(),
+  /** Channel name to join */
+  channel: z.string().min(1),
+  /** Enable this account */
+  enabled: z.boolean().optional(),
+  /** Allowlist of Twitch user IDs who can interact with the bot (use IDs for safety, not usernames) */
+  allowFrom: z.array(z.string()).optional(),
+  /** Roles allowed to interact with the bot (e.g., ["moderator", "vip", "subscriber"]) */
+  allowedRoles: z.array(TwitchRoleSchema).optional(),
+  /** Require @mention to trigger bot responses */
+  requireMention: z.boolean().optional(),
+  /** Outbound response prefix override for this channel/account. */
+  responsePrefix: z.string().optional(),
+  /** Twitch client secret (required for token refresh via RefreshingAuthProvider) */
+  clientSecret: z.string().optional(),
+  /** Refresh token (required for automatic token refresh) */
+  refreshToken: z.string().optional(),
+  /** Token expiry time in seconds (optional, for token refresh tracking) */
+  expiresIn: z.number().nullable().optional(),
+  /** Timestamp when token was obtained (optional, for token refresh tracking) */
+  obtainmentTimestamp: z.number().optional(),
+});
+
+/**
+ * Base configuration properties shared by both single and multi-account modes
+ */
+const TwitchConfigBaseSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema.optional(),
+});
+
+/**
+ * Simplified single-account configuration schema
+ *
+ * Use this for single-account setups. Properties are at the top level,
+ * creating an implicit "default" account.
+ */
+const SimplifiedSchema = z.intersection(TwitchConfigBaseSchema, TwitchAccountSchema);
+
+/**
+ * Multi-account configuration schema
+ *
+ * Use this for multi-account setups. Each key is an account ID (e.g., "default", "secondary").
+ */
+const MultiAccountSchema = z.intersection(
+  TwitchConfigBaseSchema,
+  z
+    .object({
+      /** Per-account configuration (for multi-account setups) */
+      accounts: z.record(z.string(), TwitchAccountSchema),
+    })
+    .refine((val) => Object.keys(val.accounts || {}).length > 0, {
+      message: "accounts must contain at least one entry",
+    }),
+);
+
+/**
+ * Twitch plugin configuration schema
+ *
+ * Supports two mutually exclusive patterns:
+ * 1. Simplified single-account: username, accessToken, clientId, channel at top level
+ * 2. Multi-account: accounts object with named account configs
+ *
+ * The union ensures clear discrimination between the two modes.
+ */
+export const TwitchConfigSchema = z.union([SimplifiedSchema, MultiAccountSchema]);

package/src/config.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { getAccountConfig } from "./config.js";
+
+describe("getAccountConfig", () => {
+  const mockMultiAccountConfig = {
+    channels: {
+      twitch: {
+        accounts: {
+          default: {
+            username: "testbot",
+            accessToken: "oauth:test123",
+          },
+          secondary: {
+            username: "secondbot",
+            accessToken: "oauth:secondary",
+          },
+        },
+      },
+    },
+  };
+
+  const mockSimplifiedConfig = {
+    channels: {
+      twitch: {
+        username: "testbot",
+        accessToken: "oauth:test123",
+      },
+    },
+  };
+
+  it("returns account config for valid account ID (multi-account)", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "default");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("testbot");
+  });
+
+  it("returns account config for default account (simplified config)", () => {
+    const result = getAccountConfig(mockSimplifiedConfig, "default");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("testbot");
+  });
+
+  it("returns non-default account from multi-account config", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "secondary");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("secondbot");
+  });
+
+  it("returns null for non-existent account ID", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "nonexistent");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when core config is null", () => {
+    const result = getAccountConfig(null, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when core config is undefined", () => {
+    const result = getAccountConfig(undefined, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when channels are not defined", () => {
+    const result = getAccountConfig({}, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when twitch is not defined", () => {
+    const result = getAccountConfig({ channels: {} }, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when accounts are not defined", () => {
+    const result = getAccountConfig({ channels: { twitch: {} } }, "default");
+
+    expect(result).toBeNull();
+  });
+});