@gakr-gakr/twitch 0.1.0

package/src/client-manager-registry.ts

@@ -0,0 +1,109 @@
+/**
+ * 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}`);
+}
+
+/**
+ * Test-only: clear the module-level registry of all client manager entries.
+ *
+ * Mirrors the `clearForTest` escape hatch on `TwitchClientManager`. Without
+ * this, the module-level `registry` Map survives across tests when vitest
+ * is run with `--isolate=false` (or any harness that does not tear the
+ * module graph down between cases), and a stale entry from one test will
+ * shadow `getOrCreateClientManager` calls in subsequent tests, silently
+ * handing back another test's mocked logger/manager. See #83887.
+ *
+ * Production code MUST NOT call this. It disconnects cached managers before
+ * clearing the registry so tests do not leave handlers or clients behind.
+ */
+export async function clearRegistryForTest(): Promise<void> {
+  const entries = [...registry.values()];
+  try {
+    await Promise.all(entries.map((entry) => entry.manager.disconnectAll()));
+  } finally {
+    registry.clear();
+  }
+}

package/src/config-schema.ts

@@ -0,0 +1,88 @@
+import { MarkdownConfigSchema } from "autobot/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.ts

@@ -0,0 +1,177 @@
+import {
+  listCombinedAccountIds,
+  normalizeAccountId,
+  resolveNormalizedAccountEntry,
+} from "autobot/plugin-sdk/account-resolution";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveTwitchToken, type TwitchTokenResolution } from "./token.js";
+import type { TwitchAccountConfig } from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+/**
+ * Default account ID for Twitch
+ */
+export const DEFAULT_ACCOUNT_ID = "default";
+
+export type ResolvedTwitchAccountContext = {
+  accountId: string;
+  account: TwitchAccountConfig | null;
+  tokenResolution: TwitchTokenResolution;
+  configured: boolean;
+  availableAccountIds: string[];
+};
+
+/**
+ * Get account config from core config
+ *
+ * Handles two patterns:
+ * 1. Simplified single-account: base-level properties create implicit "default" account
+ * 2. Multi-account: explicit accounts object
+ *
+ * For "default" account, base-level properties take precedence over accounts.default
+ * For other accounts, only the accounts object is checked
+ */
+export function getAccountConfig(
+  coreConfig: unknown,
+  accountId: string,
+): TwitchAccountConfig | null {
+  if (!coreConfig || typeof coreConfig !== "object") {
+    return null;
+  }
+
+  const cfg = coreConfig as AutoBotConfig;
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const twitch = cfg.channels?.twitch;
+  // Access accounts via unknown to handle union type (single-account vs multi-account)
+  const twitchRaw = twitch as Record<string, unknown> | undefined;
+  const accounts = twitchRaw?.accounts as Record<string, TwitchAccountConfig> | undefined;
+
+  // For default account, check base-level config first
+  if (normalizedAccountId === DEFAULT_ACCOUNT_ID) {
+    const accountFromAccounts = resolveNormalizedAccountEntry(
+      accounts,
+      DEFAULT_ACCOUNT_ID,
+      normalizeAccountId,
+    );
+
+    // Base-level properties that can form an implicit default account
+    const baseLevel = {
+      username: typeof twitchRaw?.username === "string" ? twitchRaw.username : undefined,
+      accessToken: typeof twitchRaw?.accessToken === "string" ? twitchRaw.accessToken : undefined,
+      clientId: typeof twitchRaw?.clientId === "string" ? twitchRaw.clientId : undefined,
+      channel: typeof twitchRaw?.channel === "string" ? twitchRaw.channel : undefined,
+      enabled: typeof twitchRaw?.enabled === "boolean" ? twitchRaw.enabled : undefined,
+      allowFrom: Array.isArray(twitchRaw?.allowFrom) ? twitchRaw.allowFrom : undefined,
+      allowedRoles: Array.isArray(twitchRaw?.allowedRoles) ? twitchRaw.allowedRoles : undefined,
+      requireMention:
+        typeof twitchRaw?.requireMention === "boolean" ? twitchRaw.requireMention : undefined,
+      clientSecret:
+        typeof twitchRaw?.clientSecret === "string" ? twitchRaw.clientSecret : undefined,
+      refreshToken:
+        typeof twitchRaw?.refreshToken === "string" ? twitchRaw.refreshToken : undefined,
+      expiresIn: typeof twitchRaw?.expiresIn === "number" ? twitchRaw.expiresIn : undefined,
+      obtainmentTimestamp:
+        typeof twitchRaw?.obtainmentTimestamp === "number"
+          ? twitchRaw.obtainmentTimestamp
+          : undefined,
+    };
+
+    // Merge: base-level takes precedence over accounts.default
+    const merged: Partial<TwitchAccountConfig> = {
+      ...accountFromAccounts,
+      ...baseLevel,
+    } as Partial<TwitchAccountConfig>;
+
+    // Only return if we have at least username
+    if (merged.username) {
+      return merged as TwitchAccountConfig;
+    }
+
+    // Fall through to accounts.default if no base-level username
+    if (accountFromAccounts) {
+      return accountFromAccounts;
+    }
+
+    return null;
+  }
+
+  // For non-default accounts, only check accounts object
+  const account = resolveNormalizedAccountEntry(accounts, normalizedAccountId, normalizeAccountId);
+  if (!account) {
+    return null;
+  }
+
+  return account;
+}
+
+/**
+ * List all configured account IDs
+ *
+ * Includes both explicit accounts and implicit "default" from base-level config
+ */
+export function listAccountIds(cfg: AutoBotConfig): string[] {
+  const twitch = cfg.channels?.twitch;
+  // Access accounts via unknown to handle union type (single-account vs multi-account)
+  const twitchRaw = twitch as Record<string, unknown> | undefined;
+  const accountMap = twitchRaw?.accounts as Record<string, unknown> | undefined;
+
+  // Add implicit "default" if base-level config exists and "default" not already present
+  const hasBaseLevelConfig =
+    twitchRaw &&
+    (typeof twitchRaw.username === "string" ||
+      typeof twitchRaw.accessToken === "string" ||
+      typeof twitchRaw.channel === "string");
+
+  return listCombinedAccountIds({
+    configuredAccountIds: Object.keys(accountMap ?? {}).map((accountId) =>
+      normalizeAccountId(accountId),
+    ),
+    implicitAccountId: hasBaseLevelConfig ? DEFAULT_ACCOUNT_ID : undefined,
+  });
+}
+
+export function resolveDefaultTwitchAccountId(cfg: AutoBotConfig): string {
+  const preferredRaw =
+    typeof cfg.channels?.twitch?.defaultAccount === "string"
+      ? cfg.channels.twitch.defaultAccount.trim()
+      : "";
+  const preferred = preferredRaw ? normalizeAccountId(preferredRaw) : "";
+  const ids = listAccountIds(cfg);
+  if (preferred && ids.includes(preferred)) {
+    return preferred;
+  }
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveTwitchAccountContext(
+  cfg: AutoBotConfig,
+  accountId?: string | null,
+): ResolvedTwitchAccountContext {
+  const resolvedAccountId = accountId?.trim()
+    ? normalizeAccountId(accountId)
+    : resolveDefaultTwitchAccountId(cfg);
+  const account = getAccountConfig(cfg, resolvedAccountId);
+  const tokenResolution = resolveTwitchToken(cfg, { accountId: resolvedAccountId });
+  return {
+    accountId: resolvedAccountId,
+    account,
+    tokenResolution,
+    configured: account ? isAccountConfigured(account, tokenResolution.token) : false,
+    availableAccountIds: listAccountIds(cfg),
+  };
+}
+
+export function resolveTwitchSnapshotAccountId(
+  cfg: AutoBotConfig,
+  account: TwitchAccountConfig,
+): string {
+  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) ?? {};
+  return (
+    Object.entries(accountMap).find(([, value]) => value === account)?.[0] ?? DEFAULT_ACCOUNT_ID
+  );
+}

package/src/monitor.ts

@@ -0,0 +1,311 @@
+/**
+ * Twitch message monitor - processes incoming messages and routes to agents.
+ *
+ * This monitor connects to the Twitch client manager, processes incoming messages,
+ * resolves agent routes, and handles replies.
+ */
+
+import type { MarkdownTableMode, AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import type { ReplyPayload } from "autobot/plugin-sdk/reply-runtime";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import { checkTwitchAccessControl } from "./access-control.js";
+import { getOrCreateClientManager } from "./client-manager-registry.js";
+import { getTwitchRuntime } from "./runtime.js";
+import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+import { stripMarkdownForTwitch } from "./utils/markdown.js";
+
+export type TwitchRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type TwitchMonitorOptions = {
+  account: TwitchAccountConfig;
+  accountId: string;
+  config: unknown; // AutoBotConfig
+  runtime: TwitchRuntimeEnv;
+  abortSignal: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export type TwitchMonitorResult = {
+  stop: () => void;
+};
+
+type TwitchCoreRuntime = ReturnType<typeof getTwitchRuntime>;
+
+/**
+ * Process an incoming Twitch message and dispatch to agent.
+ */
+async function processTwitchMessage(params: {
+  message: TwitchChatMessage;
+  account: TwitchAccountConfig;
+  accountId: string;
+  config: unknown;
+  runtime: TwitchRuntimeEnv;
+  core: TwitchCoreRuntime;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { message, account, accountId, config, runtime, core, statusSink } = params;
+  const cfg = config as AutoBotConfig;
+
+  await core.channel.turn.run({
+    channel: "twitch",
+    accountId,
+    raw: message,
+    adapter: {
+      ingest: (incoming) => ({
+        id: incoming.id ?? `${incoming.channel}:${incoming.timestamp?.getTime() ?? Date.now()}`,
+        timestamp: incoming.timestamp?.getTime(),
+        rawText: incoming.message,
+        textForAgent: incoming.message,
+        textForCommands: incoming.message,
+        raw: incoming,
+      }),
+      resolveTurn: (input) => {
+        const route = core.channel.routing.resolveAgentRoute({
+          cfg,
+          channel: "twitch",
+          accountId,
+          peer: {
+            kind: "group",
+            id: message.channel,
+          },
+        });
+        const senderId = message.userId ?? message.username;
+        const fromLabel = message.displayName ?? message.username;
+        const body = core.channel.reply.formatAgentEnvelope({
+          channel: "Twitch",
+          from: fromLabel,
+          timestamp: input.timestamp,
+          envelope: core.channel.reply.resolveEnvelopeFormatOptions(cfg),
+          body: input.rawText,
+        });
+        const ctxPayload = core.channel.turn.buildContext({
+          channel: "twitch",
+          accountId,
+          messageId: input.id,
+          timestamp: input.timestamp,
+          from: `twitch:user:${senderId}`,
+          sender: {
+            id: senderId,
+            name: fromLabel,
+            username: message.username,
+          },
+          conversation: {
+            kind: "group",
+            id: message.channel,
+            label: message.channel,
+            routePeer: {
+              kind: "group",
+              id: message.channel,
+            },
+          },
+          route: {
+            agentId: route.agentId,
+            accountId: route.accountId,
+            routeSessionKey: route.sessionKey,
+          },
+          reply: {
+            to: `twitch:channel:${message.channel}`,
+            originatingTo: `twitch:channel:${message.channel}`,
+          },
+          message: {
+            body,
+            rawBody: input.rawText,
+            bodyForAgent: input.textForAgent,
+            commandBody: input.textForCommands,
+            envelopeFrom: fromLabel,
+          },
+        });
+        const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+          agentId: route.agentId,
+        });
+        const tableMode = core.channel.text.resolveMarkdownTableMode({
+          cfg,
+          channel: "twitch",
+          accountId,
+        });
+        return {
+          cfg,
+          channel: "twitch",
+          accountId,
+          agentId: route.agentId,
+          routeSessionKey: route.sessionKey,
+          storePath,
+          ctxPayload,
+          recordInboundSession: core.channel.session.recordInboundSession,
+          dispatchReplyWithBufferedBlockDispatcher:
+            core.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+          delivery: {
+            durable: () => ({
+              to: `twitch:channel:${message.channel}`,
+            }),
+            deliver: async (payload) => {
+              return await deliverTwitchReply({
+                payload,
+                channel: message.channel,
+                account,
+                accountId,
+                config,
+                tableMode,
+                runtime,
+              });
+            },
+            onDelivered: (_payload, _info, result) => {
+              if (result?.visibleReplySent !== false) {
+                statusSink?.({ lastOutboundAt: Date.now() });
+              }
+            },
+            onError: (err, info) => {
+              runtime.error?.(`Twitch ${info.kind} reply failed: ${String(err)}`);
+            },
+          },
+          replyPipeline: {},
+          record: {
+            onRecordError: (err) => {
+              runtime.error?.(`Failed updating session meta: ${String(err)}`);
+            },
+          },
+        };
+      },
+    },
+  });
+}
+
+/**
+ * Deliver a reply to Twitch chat.
+ */
+async function deliverTwitchReply(params: {
+  payload: ReplyPayload;
+  channel: string;
+  account: TwitchAccountConfig;
+  accountId: string;
+  config: unknown;
+  tableMode: MarkdownTableMode;
+  runtime: TwitchRuntimeEnv;
+}): Promise<{ visibleReplySent: boolean }> {
+  const { payload, channel, account, accountId, config, runtime } = params;
+
+  try {
+    const clientManager = getOrCreateClientManager(accountId, {
+      info: (msg) => runtime.log?.(msg),
+      warn: (msg) => runtime.log?.(msg),
+      error: (msg) => runtime.error?.(msg),
+      debug: (msg) => runtime.log?.(msg),
+    });
+
+    const client = await clientManager.getClient(
+      account,
+      config as Parameters<typeof clientManager.getClient>[1],
+      accountId,
+    );
+    if (!client) {
+      runtime.error?.(`No client available for sending reply`);
+      return { visibleReplySent: false };
+    }
+
+    // Send the reply
+    if (!payload.text) {
+      runtime.error?.(`No text to send in reply payload`);
+      return { visibleReplySent: false };
+    }
+
+    const textToSend = stripMarkdownForTwitch(payload.text);
+
+    await client.say(channel, textToSend);
+    return { visibleReplySent: true };
+  } catch (err) {
+    runtime.error?.(`Failed to send reply: ${String(err)}`);
+    return { visibleReplySent: false };
+  }
+}
+
+/**
+ * Main monitor provider for Twitch.
+ *
+ * Sets up message handlers and processes incoming messages.
+ */
+export async function monitorTwitchProvider(
+  options: TwitchMonitorOptions,
+): Promise<TwitchMonitorResult> {
+  const { account, accountId, config, runtime, abortSignal, statusSink } = options;
+
+  const core = getTwitchRuntime();
+  let stopped = false;
+
+  const coreLogger = core.logging.getChildLogger({ module: "twitch" });
+  const logVerboseMessage = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
+    coreLogger.debug?.(message);
+  };
+  const logger = {
+    info: (msg: string) => coreLogger.info(msg),
+    warn: (msg: string) => coreLogger.warn(msg),
+    error: (msg: string) => coreLogger.error(msg),
+    debug: logVerboseMessage,
+  };
+
+  const clientManager = getOrCreateClientManager(accountId, logger);
+
+  try {
+    await clientManager.getClient(
+      account,
+      config as Parameters<typeof clientManager.getClient>[1],
+      accountId,
+    );
+  } catch (error) {
+    const errorMsg = formatErrorMessage(error);
+    runtime.error?.(`Failed to connect: ${errorMsg}`);
+    throw error;
+  }
+
+  const unregisterHandler = clientManager.onMessage(account, (message) => {
+    if (stopped) {
+      return;
+    }
+
+    void (async () => {
+      const botUsername = normalizeLowercaseStringOrEmpty(account.username);
+      if (normalizeLowercaseStringOrEmpty(message.username) === botUsername) {
+        return;
+      }
+
+      const access = await checkTwitchAccessControl({
+        message,
+        account,
+        botUsername,
+      });
+
+      if (stopped || !access.allowed) {
+        return;
+      }
+
+      statusSink?.({ lastInboundAt: Date.now() });
+
+      await processTwitchMessage({
+        message,
+        account,
+        accountId,
+        config,
+        runtime,
+        core,
+        statusSink,
+      });
+    })().catch((err) => {
+      runtime.error?.(`Message processing failed: ${String(err)}`);
+    });
+  });
+
+  const stop = () => {
+    stopped = true;
+    unregisterHandler();
+  };
+
+  abortSignal.addEventListener("abort", stop, { once: true });
+
+  return { stop };
+}