@kodelyth/twitch 2026.5.39 → 2026.5.42

package/src/access-control.ts

@@ -0,0 +1,195 @@
+import {
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+  type ChannelIngressIdentitySubjectInput,
+  type IngressReasonCode,
+} from "klaw/plugin-sdk/channel-ingress-runtime";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+
+type TwitchAccessControlResult = {
+  allowed: boolean;
+  reason?: string;
+  matchKey?: string;
+  matchSource?: string;
+};
+
+type TwitchPolicyKind = "open" | "allowFrom" | "role";
+
+const twitchUserIdentity = defineStableChannelIngressIdentity({
+  key: "sender-id",
+  entryIdPrefix: "twitch-user-entry",
+});
+
+const twitchRoleIdentity = defineStableChannelIngressIdentity({
+  key: "role-moderator",
+  kind: "role",
+  normalizeEntry: normalizeTwitchRole,
+  normalizeSubject: normalizeTwitchRole,
+  aliases: ["owner", "vip", "subscriber"].map((role) => ({
+    key: `role-${role}`,
+    kind: "role",
+    normalizeEntry: () => null,
+    normalizeSubject: normalizeTwitchRole,
+  })),
+  isWildcardEntry: (entry) => normalizeTwitchRole(entry) === "all",
+  resolveEntryId: ({ entryIndex }) => `twitch-role-entry-${entryIndex + 1}`,
+});
+
+export async function checkTwitchAccessControl(params: {
+  message: TwitchChatMessage;
+  account: TwitchAccountConfig;
+  botUsername: string;
+}): Promise<TwitchAccessControlResult> {
+  const { message, account, botUsername } = params;
+  const policyKind = resolveTwitchPolicyKind(account);
+  const resolved = await createChannelIngressResolver({
+    channelId: "twitch",
+    accountId: "default",
+    identity: policyKind === "role" ? twitchRoleIdentity : twitchUserIdentity,
+  }).message({
+    subject:
+      policyKind === "role"
+        ? twitchRoleSubject(message)
+        : ({ stableId: message.userId } satisfies ChannelIngressIdentitySubjectInput),
+    conversation: {
+      kind: "group",
+      id: message.channel,
+    },
+    event: { mayPair: false },
+    mentionFacts: {
+      canDetectMention: true,
+      wasMentioned: mentionsBot(message.message, botUsername),
+    },
+    dmPolicy: "open",
+    groupPolicy: policyKind === "open" ? "open" : "allowlist",
+    policy: {
+      activation: {
+        requireMention: account.requireMention ?? true,
+        allowTextCommands: false,
+        order: "before-sender",
+      },
+    },
+    groupAllowFrom:
+      policyKind === "allowFrom"
+        ? account.allowFrom
+        : policyKind === "role"
+          ? account.allowedRoles
+          : undefined,
+  });
+  const decision = resolved.ingress;
+
+  if (decision.decisiveGateId === "activation" && decision.admission !== "dispatch") {
+    return {
+      allowed: false,
+      reason: "message does not mention the bot (requireMention is enabled)",
+    };
+  }
+
+  if (decision.admission === "dispatch") {
+    if (policyKind === "allowFrom") {
+      return {
+        allowed: true,
+        matchKey: params.message.userId,
+        matchSource: "allowlist",
+      };
+    }
+    if (policyKind === "role") {
+      return {
+        allowed: true,
+        matchKey: params.account.allowedRoles?.join(","),
+        matchSource: "role",
+      };
+    }
+    return {
+      allowed: true,
+    };
+  }
+
+  if (policyKind === "allowFrom") {
+    if (!params.message.userId) {
+      return {
+        allowed: false,
+        reason: "sender user ID not available for allowlist check",
+      };
+    }
+    return {
+      allowed: false,
+      reason: "sender is not in allowFrom allowlist",
+    };
+  }
+
+  if (policyKind === "role") {
+    return {
+      allowed: false,
+      reason: `sender does not have any of the required roles: ${params.account.allowedRoles?.join(", ") ?? ""}`,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: reasonForTwitchIngressDecision(decision),
+  };
+}
+
+function resolveTwitchPolicyKind(account: TwitchAccountConfig): TwitchPolicyKind {
+  if (account.allowFrom !== undefined) {
+    return "allowFrom";
+  }
+  if (account.allowedRoles && account.allowedRoles.length > 0) {
+    return "role";
+  }
+  return "open";
+}
+
+function twitchRoleSubject(message: TwitchChatMessage): ChannelIngressIdentitySubjectInput {
+  return {
+    stableId: message.isMod ? "moderator" : undefined,
+    aliases: {
+      "role-owner": message.isOwner ? "owner" : undefined,
+      "role-vip": message.isVip ? "vip" : undefined,
+      "role-subscriber": message.isSub ? "subscriber" : undefined,
+    },
+  };
+}
+
+function normalizeTwitchRole(value: string): string | null {
+  const role = normalizeLowercaseStringOrEmpty(value);
+  if (role === "*") {
+    return "all";
+  }
+  return role === "moderator" ||
+    role === "owner" ||
+    role === "vip" ||
+    role === "subscriber" ||
+    role === "all"
+    ? role
+    : null;
+}
+
+function reasonForTwitchIngressDecision(decision: { reasonCode: IngressReasonCode }): string {
+  switch (decision.reasonCode) {
+    case "activation_skipped":
+      return "message does not mention the bot (requireMention is enabled)";
+    case "group_policy_empty_allowlist":
+    case "group_policy_not_allowlisted":
+      return "sender is not in allowFrom allowlist";
+    default:
+      return decision.reasonCode;
+  }
+}
+
+function mentionsBot(message: string, botUsername: string): boolean {
+  const expected = normalizeLowercaseStringOrEmpty(botUsername);
+  const mentionRegex = /@(\w+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = mentionRegex.exec(message)) !== null) {
+    const username = match[1] ? normalizeLowercaseStringOrEmpty(match[1]) : "";
+    if (username === expected) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/actions.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { twitchMessageActions } from "./actions.js";
+import type { ResolvedTwitchAccountContext } from "./config.js";
+import { resolveTwitchAccountContext } from "./config.js";
+import { twitchOutbound } from "./outbound.js";
+
+vi.mock("./config.js", () => ({
+  DEFAULT_ACCOUNT_ID: "default",
+  resolveTwitchAccountContext: vi.fn(),
+}));
+
+vi.mock("./outbound.js", () => ({
+  twitchOutbound: {
+    sendText: vi.fn(),
+  },
+}));
+
+function createSecondaryAccountContext(accountId = "secondary"): ResolvedTwitchAccountContext {
+  return {
+    accountId,
+    account: {
+      channel: "secondary-channel",
+      username: "secondary",
+      accessToken: "oauth:secondary-token",
+      clientId: "secondary-client",
+      enabled: true,
+    },
+    tokenResolution: { source: "config", token: "oauth:secondary-token" },
+    configured: true,
+    availableAccountIds: ["default", "secondary"],
+  };
+}
+
+describe("twitchMessageActions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses configured defaultAccount when action accountId is omitted", async () => {
+    vi.mocked(resolveTwitchAccountContext)
+      .mockImplementationOnce(() => createSecondaryAccountContext())
+      .mockImplementation((_cfg, accountId) =>
+        createSecondaryAccountContext(accountId?.trim() || "secondary"),
+      );
+    const sendText = twitchOutbound.sendText;
+    if (!sendText) {
+      throw new Error("twitchOutbound.sendText is unavailable");
+    }
+    vi.mocked(sendText).mockResolvedValue({
+      channel: "twitch",
+      messageId: "msg-1",
+      timestamp: 1,
+    });
+    const cfg = {
+      channels: {
+        twitch: {
+          defaultAccount: "secondary",
+        },
+      },
+    };
+
+    await twitchMessageActions.handleAction!({
+      action: "send",
+      params: { message: "Hello!" },
+      cfg,
+    } as never);
+
+    expect(twitchOutbound.sendText).toHaveBeenCalledWith({
+      cfg,
+      to: "secondary-channel",
+      text: "Hello!",
+      accountId: "secondary",
+    });
+  });
+});

package/src/actions.ts

@@ -0,0 +1,175 @@
+/**
+ * Twitch message actions adapter.
+ *
+ * Handles tool-based actions for Twitch, such as sending messages.
+ */
+
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { resolveTwitchAccountContext } 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.
+   */
+  describeMessageTool: () => ({ actions: [...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: klawConfig,
+   *   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 ?? resolveTwitchAccountContext(ctx.cfg).accountId;
+
+    const { account, availableAccountIds } = resolveTwitchAccountContext(ctx.cfg, accountId);
+    if (!account) {
+      return errorResponse(
+        `Account not found: ${accountId}. Available accounts: ${availableAccountIds.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 = formatErrorMessage(error);
+      return errorResponse(errorMsg);
+    }
+  },
+};

package/src/client-manager-registry.ts

@@ -0,0 +1,87 @@
+/**
+ * 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}`);
+}

package/src/config-schema.test.ts

@@ -0,0 +1,46 @@
+import AjvPkg from "ajv";
+import { buildChannelConfigSchema } from "klaw/plugin-sdk/channel-config-schema";
+import { describe, expect, it } from "vitest";
+import { TwitchConfigSchema } from "./config-schema.js";
+
+function validateTwitchConfig(value: unknown): boolean {
+  const Ajv = AjvPkg as unknown as new (opts?: object) => import("ajv").default;
+  const schema = buildChannelConfigSchema(TwitchConfigSchema).schema;
+  const validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+  const ok = validate(value);
+  if (!ok) {
+    throw new Error(`expected valid Twitch config: ${JSON.stringify(validate.errors)}`);
+  }
+  return true;
+}
+
+describe("TwitchConfigSchema JSON schema", () => {
+  it("accepts single-account channel config with base fields", () => {
+    expect(
+      validateTwitchConfig({
+        enabled: false,
+        username: "klaw",
+        accessToken: "oauth:test",
+        clientId: "test-client-id",
+        channel: "klaw-test",
+      }),
+    ).toBe(true);
+  });
+
+  it("accepts multi-account channel config with defaultAccount", () => {
+    expect(
+      validateTwitchConfig({
+        enabled: true,
+        defaultAccount: "stream",
+        accounts: {
+          stream: {
+            username: "klaw",
+            accessToken: "oauth:test",
+            clientId: "test-client-id",
+            channel: "klaw-test",
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,88 @@
+import { MarkdownConfigSchema } from "klaw/plugin-sdk/channel-config-primitives";
+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"]);
+
+const TwitchAccountShape = {
+  /** 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(),
+};
+
+/**
+ * Twitch account configuration schema
+ */
+const TwitchAccountSchema = z.object(TwitchAccountShape);
+
+/**
+ * Base configuration properties shared by both single and multi-account modes
+ */
+const TwitchConfigBaseShape = {
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema.optional(),
+  defaultAccount: z.string().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.object({
+  ...TwitchConfigBaseShape,
+  ...TwitchAccountShape,
+});
+
+/**
+ * Multi-account configuration schema
+ *
+ * Use this for multi-account setups. Each key is an account ID (e.g., "default", "secondary").
+ */
+const MultiAccountSchema = z
+  .object({
+    ...TwitchConfigBaseShape,
+    /** 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]);