@gakr-gakr/twitch 0.1.0

package/src/outbound.ts

@@ -0,0 +1,242 @@
+/**
+ * Twitch outbound adapter for sending messages.
+ *
+ * Implements the ChannelOutboundAdapter interface for Twitch chat.
+ * Supports text and media (URL) sending with markdown stripping and chunking.
+ */
+
+import {
+  createMessageReceiptFromOutboundResults,
+  defineChannelMessageAdapter,
+  type ChannelMessageSendResult,
+  type MessageReceiptPartKind,
+} from "autobot/plugin-sdk/channel-message";
+import { resolveTwitchAccountContext } from "./config.js";
+import { sendMessageTwitchInternal } from "./send.js";
+import type {
+  ChannelOutboundAdapter,
+  ChannelOutboundContext,
+  OutboundDeliveryResult,
+} from "./types.js";
+import { chunkTextForTwitch } from "./utils/markdown.js";
+import { missingTargetError, normalizeTwitchChannel } from "./utils/twitch.js";
+
+/**
+ * Twitch outbound adapter.
+ *
+ * Handles sending text and media to Twitch channels with automatic
+ * markdown stripping and message chunking.
+ */
+export const twitchOutbound: ChannelOutboundAdapter = {
+  /** Direct delivery mode - messages are sent immediately */
+  deliveryMode: "direct",
+
+  deliveryCapabilities: {
+    durableFinal: {
+      text: true,
+      media: true,
+      messageSendingHooks: true,
+    },
+  },
+
+  /** Twitch chat message limit is 500 characters */
+  textChunkLimit: 500,
+
+  /** Word-boundary chunker with markdown stripping */
+  chunker: chunkTextForTwitch,
+
+  /**
+   * Resolve target from context.
+   *
+   * Handles target resolution with allowlist support for implicit/heartbeat modes.
+   * For explicit mode, accepts any valid channel name.
+   *
+   * @param params - Resolution parameters
+   * @returns Resolved target or error
+   */
+  resolveTarget: ({ to, allowFrom, mode }) => {
+    const trimmed = to?.trim() ?? "";
+    const allowListRaw = (allowFrom ?? [])
+      .map((entry: unknown) => String(entry).trim())
+      .filter(Boolean);
+    const hasWildcard = allowListRaw.includes("*");
+    const allowList = allowListRaw
+      .filter((entry: string) => entry !== "*")
+      .map((entry: string) => normalizeTwitchChannel(entry))
+      .filter((entry): entry is string => entry.length > 0);
+
+    // If target is provided, normalize and validate it
+    if (trimmed) {
+      const normalizedTo = normalizeTwitchChannel(trimmed);
+      if (!normalizedTo) {
+        return {
+          ok: false,
+          error: missingTargetError("Twitch", "<channel-name>"),
+        };
+      }
+
+      // For implicit/heartbeat modes with allowList, check against allowlist
+      if (mode === "implicit" || mode === "heartbeat") {
+        if (hasWildcard || allowList.length === 0) {
+          return { ok: true, to: normalizedTo };
+        }
+        if (allowList.includes(normalizedTo)) {
+          return { ok: true, to: normalizedTo };
+        }
+        return {
+          ok: false,
+          error: missingTargetError("Twitch", "<channel-name>"),
+        };
+      }
+
+      // For explicit mode, accept any valid channel name
+      return { ok: true, to: normalizedTo };
+    }
+
+    // No target provided - error
+
+    // No target and no allowFrom - error
+    return {
+      ok: false,
+      error: missingTargetError("Twitch", "<channel-name>"),
+    };
+  },
+
+  /**
+   * Send a text message to a Twitch channel.
+   *
+   * Strips markdown if enabled, validates account configuration,
+   * and sends the message via the Twitch client.
+   *
+   * @param params - Send parameters including target, text, and config
+   * @returns Delivery result with message ID and status
+   *
+   * @example
+   * const result = await twitchOutbound.sendText({
+   *   cfg: autobotConfig,
+   *   to: "#mychannel",
+   *   text: "Hello Twitch!",
+   *   accountId: "default",
+   * });
+   */
+  sendText: async (params: ChannelOutboundContext): Promise<OutboundDeliveryResult> => {
+    const { cfg, to, text, accountId } = params;
+    const signal = (params as { signal?: AbortSignal }).signal;
+
+    if (signal?.aborted) {
+      throw new Error("Outbound delivery aborted");
+    }
+
+    const resolvedAccountId = accountId ?? resolveTwitchAccountContext(cfg).accountId;
+    const { account, availableAccountIds } = resolveTwitchAccountContext(cfg, resolvedAccountId);
+    if (!account) {
+      throw new Error(
+        `Twitch account not found: ${resolvedAccountId}. ` +
+          `Available accounts: ${availableAccountIds.join(", ") || "none"}`,
+      );
+    }
+
+    const channel = to || account.channel;
+    if (!channel) {
+      throw new Error("No channel specified and no default channel in account config");
+    }
+
+    const result = await sendMessageTwitchInternal(
+      normalizeTwitchChannel(channel),
+      text,
+      cfg,
+      resolvedAccountId,
+      true, // stripMarkdown
+      console,
+    );
+
+    if (!result.ok) {
+      throw new Error(result.error ?? "Send failed");
+    }
+
+    return {
+      channel: "twitch",
+      messageId: result.messageId,
+      receipt: result.receipt,
+      timestamp: Date.now(),
+    };
+  },
+
+  /**
+   * Send media to a Twitch channel.
+   *
+   * Note: Twitch chat doesn't support direct media uploads.
+   * This sends the media URL as text instead.
+   *
+   * @param params - Send parameters including media URL
+   * @returns Delivery result with message ID and status
+   *
+   * @example
+   * const result = await twitchOutbound.sendMedia({
+   *   cfg: autobotConfig,
+   *   to: "#mychannel",
+   *   text: "Check this out!",
+   *   mediaUrl: "https://example.com/image.png",
+   *   accountId: "default",
+   * });
+   */
+  sendMedia: async (params: ChannelOutboundContext): Promise<OutboundDeliveryResult> => {
+    const { text, mediaUrl } = params;
+    const signal = (params as { signal?: AbortSignal }).signal;
+
+    if (signal?.aborted) {
+      throw new Error("Outbound delivery aborted");
+    }
+
+    const message = mediaUrl ? `${text || ""} ${mediaUrl}`.trim() : text;
+
+    if (!twitchOutbound.sendText) {
+      throw new Error("sendText not implemented");
+    }
+    return twitchOutbound.sendText({
+      ...params,
+      text: message,
+    });
+  },
+};
+
+function toTwitchMessageSendResult(
+  result: OutboundDeliveryResult,
+  kind: MessageReceiptPartKind,
+): ChannelMessageSendResult {
+  const receipt =
+    result.receipt ??
+    createMessageReceiptFromOutboundResults({
+      results: result.messageId ? [{ channel: "twitch", messageId: result.messageId }] : [],
+      kind,
+    });
+  return {
+    messageId: result.messageId || receipt.primaryPlatformMessageId,
+    receipt,
+  };
+}
+
+export const twitchMessageAdapter = defineChannelMessageAdapter({
+  id: "twitch",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      messageSendingHooks: true,
+    },
+  },
+  send: {
+    text: async (ctx) => {
+      if (!twitchOutbound.sendText) {
+        throw new Error("Twitch text sending is not available.");
+      }
+      return toTwitchMessageSendResult(await twitchOutbound.sendText(ctx), "text");
+    },
+    media: async (ctx) => {
+      if (!twitchOutbound.sendMedia) {
+        throw new Error("Twitch media sending is not available.");
+      }
+      return toTwitchMessageSendResult(await twitchOutbound.sendMedia(ctx), "media");
+    },
+  },
+});

package/src/plugin.ts

@@ -0,0 +1,220 @@
+/**
+ * Twitch channel plugin for AutoBot.
+ *
+ * Main plugin export combining all adapters (outbound, actions, status, gateway).
+ * This is the primary entry point for the Twitch channel integration.
+ */
+
+import { describeAccountSnapshot } from "autobot/plugin-sdk/account-helpers";
+import { buildChannelConfigSchema } from "autobot/plugin-sdk/channel-config-schema";
+import { createChatChannelPlugin } from "autobot/plugin-sdk/channel-core";
+import {
+  createLoggedPairingApprovalNotifier,
+  createPairingPrefixStripper,
+} from "autobot/plugin-sdk/channel-pairing";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  buildPassiveProbedChannelStatusSummary,
+  runStoppablePassiveMonitor,
+} from "autobot/plugin-sdk/extension-shared";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "autobot/plugin-sdk/status-helpers";
+import { twitchMessageActions } from "./actions.js";
+import { removeClientManager } from "./client-manager-registry.js";
+import { TwitchConfigSchema } from "./config-schema.js";
+import {
+  DEFAULT_ACCOUNT_ID,
+  getAccountConfig,
+  listAccountIds,
+  resolveDefaultTwitchAccountId,
+  resolveTwitchAccountContext,
+  resolveTwitchSnapshotAccountId,
+} from "./config.js";
+import { twitchMessageAdapter, twitchOutbound } from "./outbound.js";
+import { probeTwitch } from "./probe.js";
+import { resolveTwitchTargets } from "./resolver.js";
+import { twitchSetupAdapter, twitchSetupWizard } from "./setup-surface.js";
+import { collectTwitchStatusIssues } from "./status.js";
+import type {
+  ChannelLogSink,
+  ChannelPlugin,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  TwitchAccountConfig,
+} from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+type ResolvedTwitchAccount = TwitchAccountConfig & { accountId?: string | null };
+
+/**
+ * Twitch channel plugin.
+ *
+ * Implements the ChannelPlugin interface to provide Twitch chat integration
+ * for AutoBot. Supports message sending, receiving, access control, and
+ * status monitoring.
+ */
+export const twitchPlugin: ChannelPlugin<ResolvedTwitchAccount> =
+  createChatChannelPlugin<ResolvedTwitchAccount>({
+    pairing: {
+      idLabel: "twitchUserId",
+      normalizeAllowEntry: createPairingPrefixStripper(/^(twitch:)?user:?/i),
+      notifyApproval: createLoggedPairingApprovalNotifier(
+        ({ id }) => `Pairing approved for user ${id} (notification sent via chat if possible)`,
+        console.warn,
+      ),
+    },
+    outbound: twitchOutbound,
+    base: {
+      id: "twitch",
+      meta: {
+        id: "twitch",
+        label: "Twitch",
+        selectionLabel: "Twitch (Chat)",
+        docsPath: "/channels/twitch",
+        blurb: "Twitch chat integration",
+        aliases: ["twitch-chat"],
+      },
+      setup: twitchSetupAdapter,
+      setupWizard: twitchSetupWizard,
+      capabilities: {
+        chatTypes: ["group"],
+      },
+      message: twitchMessageAdapter,
+      configSchema: buildChannelConfigSchema(TwitchConfigSchema),
+      config: {
+        listAccountIds: (cfg: AutoBotConfig): string[] => listAccountIds(cfg),
+        resolveAccount: (cfg: AutoBotConfig, accountId?: string | null): ResolvedTwitchAccount => {
+          const resolvedAccountId = accountId ?? resolveDefaultTwitchAccountId(cfg);
+          const account = getAccountConfig(cfg, resolvedAccountId);
+          if (!account) {
+            return {
+              accountId: resolvedAccountId,
+              channel: "",
+              username: "",
+              accessToken: "",
+              clientId: "",
+              enabled: false,
+            };
+          }
+          return {
+            accountId: resolvedAccountId,
+            ...account,
+          };
+        },
+        defaultAccountId: (cfg: AutoBotConfig): string => resolveDefaultTwitchAccountId(cfg),
+        isConfigured: (_account: unknown, cfg: AutoBotConfig): boolean =>
+          resolveTwitchAccountContext(cfg).configured,
+        isEnabled: (account: ResolvedTwitchAccount | undefined): boolean =>
+          account?.enabled !== false,
+        describeAccount: (account: TwitchAccountConfig | undefined) =>
+          account
+            ? describeAccountSnapshot({
+                account,
+                configured: isAccountConfigured(account, account.accessToken),
+              })
+            : {
+                accountId: DEFAULT_ACCOUNT_ID,
+                enabled: false,
+                configured: false,
+              },
+      },
+      actions: twitchMessageActions,
+      resolver: {
+        resolveTargets: async ({
+          cfg,
+          accountId,
+          inputs,
+          kind,
+          runtime,
+        }: {
+          cfg: AutoBotConfig;
+          accountId?: string | null;
+          inputs: string[];
+          kind: ChannelResolveKind;
+          runtime: import("autobot/plugin-sdk/runtime-env").RuntimeEnv;
+        }): Promise<ChannelResolveResult[]> => {
+          const account = getAccountConfig(cfg, accountId ?? resolveDefaultTwitchAccountId(cfg));
+          if (!account) {
+            return inputs.map((input) => ({
+              input,
+              resolved: false,
+              note: "account not configured",
+            }));
+          }
+
+          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: createComputedAccountStatusAdapter<ResolvedTwitchAccount>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+        buildChannelSummary: ({ snapshot }) => buildPassiveProbedChannelStatusSummary(snapshot),
+        probeAccount: async ({ account, timeoutMs }) => await probeTwitch(account, timeoutMs),
+        collectStatusIssues: collectTwitchStatusIssues,
+        resolveAccountSnapshot: ({ account, cfg }) => {
+          const resolvedAccountId =
+            account.accountId || resolveTwitchSnapshotAccountId(cfg, account);
+          const { configured } = resolveTwitchAccountContext(cfg, resolvedAccountId);
+          return {
+            accountId: resolvedAccountId,
+            enabled: account.enabled !== false,
+            configured,
+          };
+        },
+      }),
+      gateway: {
+        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}`);
+
+          // Keep startAccount pending until abort fires; otherwise the channel
+          // supervisor reads the settled task as `channel exited without an
+          // error` and triggers a restart loop. See #60071.
+          await runStoppablePassiveMonitor({
+            abortSignal: ctx.abortSignal,
+            start: async () => {
+              // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+              const { monitorTwitchProvider } = await import("./monitor.js");
+              return monitorTwitchProvider({
+                account,
+                accountId,
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+              });
+            },
+          });
+        },
+        stopAccount: async (ctx): Promise<void> => {
+          const account = ctx.account;
+          const accountId = ctx.accountId;
+
+          await removeClientManager(accountId);
+
+          ctx.setStatus?.({
+            accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+
+          ctx.log?.info(`Stopped Twitch connection for ${account.username}`);
+        },
+      },
+    },
+  });

package/src/probe.ts

@@ -0,0 +1,130 @@
+import { StaticAuthProvider } from "@twurple/auth";
+import { ChatClient } from "@twurple/chat";
+import type { BaseProbeResult } from "autobot/plugin-sdk/channel-contract";
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import type { TwitchAccountConfig } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Result of probing a Twitch account
+ */
+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"));
+      });
+    });
+
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(
+        () => reject(new Error(`timeout after ${timeoutMs}ms`)),
+        timeoutMs,
+      );
+    });
+
+    client.connect();
+    try {
+      await Promise.race([connectionPromise, timeout]);
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+
+    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: formatErrorMessage(error),
+      username: account.username,
+      channel: account.channel,
+      elapsedMs: Date.now() - started,
+    };
+  } finally {
+    if (client) {
+      try {
+        client.quit();
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}