@kodelyth/twitch 2026.5.42 → 2026.6.2

package/src/actions.ts

@@ -1,175 +0,0 @@
-/**
- * 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

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

@@ -1,46 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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]);

package/src/config.test.ts

@@ -1,233 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getAccountConfig,
-  listAccountIds,
-  resolveDefaultTwitchAccountId,
-  resolveTwitchAccountContext,
-} 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?.username).toBe("testbot");
-  });
-
-  it("returns account config for default account (simplified config)", () => {
-    const result = getAccountConfig(mockSimplifiedConfig, "default");
-
-    expect(result?.username).toBe("testbot");
-  });
-
-  it("returns non-default account from multi-account config", () => {
-    const result = getAccountConfig(mockMultiAccountConfig, "secondary");
-
-    expect(result?.username).toBe("secondbot");
-  });
-
-  it("normalizes account ids without reading inherited account properties", () => {
-    const accounts = Object.create({
-      inherited: {
-        username: "inherited-bot",
-        accessToken: "oauth:inherited",
-      },
-    }) as Record<string, unknown>;
-    accounts.Secondary = {
-      username: "secondbot",
-      accessToken: "oauth:secondary",
-    };
-
-    const cfg = {
-      channels: {
-        twitch: {
-          accounts,
-        },
-      },
-    };
-
-    expect(getAccountConfig(cfg, "SECONDARY\r\n")).toEqual({
-      username: "secondbot",
-      accessToken: "oauth:secondary",
-    });
-    expect(getAccountConfig(cfg, "inherited")).toBeNull();
-  });
-
-  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();
-  });
-});
-
-describe("listAccountIds", () => {
-  it("includes the implicit default account from simplified config", () => {
-    expect(
-      listAccountIds({
-        channels: {
-          twitch: {
-            username: "testbot",
-            accessToken: "oauth:test123",
-          },
-        },
-      } as Parameters<typeof listAccountIds>[0]),
-    ).toEqual(["default"]);
-  });
-
-  it("combines explicit accounts with the implicit default account once", () => {
-    expect(
-      listAccountIds({
-        channels: {
-          twitch: {
-            username: "testbot",
-            accounts: {
-              default: { username: "testbot" },
-              secondary: { username: "secondbot" },
-            },
-          },
-        },
-      } as Parameters<typeof listAccountIds>[0]),
-    ).toEqual(["default", "secondary"]);
-  });
-
-  it("normalizes configured account ids", () => {
-    expect(
-      listAccountIds({
-        channels: {
-          twitch: {
-            accounts: {
-              Secondary: { username: "secondbot" },
-              "Alerts\r\n\u001b[31m": { username: "alerts" },
-            },
-          },
-        },
-      } as Parameters<typeof listAccountIds>[0]),
-    ).toEqual(["alerts-31m", "secondary"]);
-  });
-});
-
-describe("resolveDefaultTwitchAccountId", () => {
-  it("prefers channels.twitch.defaultAccount when configured", () => {
-    expect(
-      resolveDefaultTwitchAccountId({
-        channels: {
-          twitch: {
-            defaultAccount: "secondary",
-            accounts: {
-              default: { username: "default" },
-              secondary: { username: "secondary" },
-            },
-          },
-        },
-      } as Parameters<typeof resolveDefaultTwitchAccountId>[0]),
-    ).toBe("secondary");
-  });
-});
-
-describe("resolveTwitchAccountContext", () => {
-  it("uses configured defaultAccount when accountId is omitted", () => {
-    const context = resolveTwitchAccountContext({
-      channels: {
-        twitch: {
-          defaultAccount: "secondary",
-          accounts: {
-            default: {
-              username: "default-bot",
-              accessToken: "oauth:default-token",
-            },
-            secondary: {
-              username: "second-bot",
-              accessToken: "oauth:second-token",
-            },
-          },
-        },
-      },
-    } as Parameters<typeof resolveTwitchAccountContext>[0]);
-
-    expect(context.accountId).toBe("secondary");
-    expect(context.account?.username).toBe("second-bot");
-  });
-
-  it("keeps account and token lookup aligned after account id normalization", () => {
-    const context = resolveTwitchAccountContext(
-      {
-        channels: {
-          twitch: {
-            accounts: {
-              Secondary: {
-                username: "second-bot",
-                accessToken: "oauth:second-token",
-                clientId: "second-client",
-                channel: "#second",
-              },
-            },
-          },
-        },
-      } as Parameters<typeof resolveTwitchAccountContext>[0],
-      "secondary",
-    );
-
-    expect(context.accountId).toBe("secondary");
-    expect(context.account?.username).toBe("second-bot");
-    expect(context.tokenResolution).toEqual({
-      token: "oauth:second-token",
-      source: "config",
-    });
-    expect(context.configured).toBe(true);
-  });
-});