@kodelyth/twitch 2026.5.39 → 2026.5.42

package/src/twitch-client.ts

@@ -0,0 +1,276 @@
+import { RefreshingAuthProvider, StaticAuthProvider } from "@twurple/auth";
+import { ChatClient, LogLevel } from "@twurple/chat";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { resolveTwitchToken } from "./token.js";
+import type { ChannelLogSink, TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Manages Twitch chat client connections
+ */
+export class TwitchClientManager {
+  private clients = new Map<string, ChatClient>();
+  private messageHandlers = new Map<string, (message: TwitchChatMessage) => void>();
+
+  constructor(private logger: ChannelLogSink) {}
+
+  /**
+   * Create an auth provider for the account.
+   */
+  private async createAuthProvider(
+    account: TwitchAccountConfig,
+    normalizedToken: string,
+  ): Promise<StaticAuthProvider | RefreshingAuthProvider> {
+    if (!account.clientId) {
+      throw new Error("Missing Twitch client ID");
+    }
+
+    if (account.clientSecret) {
+      const authProvider = new RefreshingAuthProvider({
+        clientId: account.clientId,
+        clientSecret: account.clientSecret,
+      });
+
+      await authProvider
+        .addUserForToken({
+          accessToken: normalizedToken,
+          refreshToken: account.refreshToken ?? null,
+          expiresIn: account.expiresIn ?? null,
+          obtainmentTimestamp: account.obtainmentTimestamp ?? Date.now(),
+        })
+        .then((userId) => {
+          this.logger.info(
+            `Added user ${userId} to RefreshingAuthProvider for ${account.username}`,
+          );
+        })
+        .catch((err) => {
+          this.logger.error(
+            `Failed to add user to RefreshingAuthProvider: ${formatErrorMessage(err)}`,
+          );
+        });
+
+      authProvider.onRefresh((userId, token) => {
+        this.logger.info(
+          `Access token refreshed for user ${userId} (expires in ${token.expiresIn ? `${token.expiresIn}s` : "unknown"})`,
+        );
+      });
+
+      authProvider.onRefreshFailure((userId, error) => {
+        this.logger.error(`Failed to refresh access token for user ${userId}: ${error.message}`);
+      });
+
+      const refreshStatus = account.refreshToken
+        ? "automatic token refresh enabled"
+        : "token refresh disabled (no refresh token)";
+      this.logger.info(`Using RefreshingAuthProvider for ${account.username} (${refreshStatus})`);
+
+      return authProvider;
+    }
+
+    this.logger.info(`Using StaticAuthProvider for ${account.username} (no clientSecret provided)`);
+    return new StaticAuthProvider(account.clientId, normalizedToken);
+  }
+
+  /**
+   * Get or create a chat client for an account
+   */
+  async getClient(
+    account: TwitchAccountConfig,
+    cfg?: KlawConfig,
+    accountId?: string,
+  ): Promise<ChatClient> {
+    const key = this.getAccountKey(account);
+
+    const existing = this.clients.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const tokenResolution = resolveTwitchToken(cfg, {
+      accountId,
+    });
+
+    if (!tokenResolution.token) {
+      this.logger.error(
+        `Missing Twitch token for account ${account.username} (set channels.twitch.accounts.${account.username}.token or KLAW_TWITCH_ACCESS_TOKEN for default)`,
+      );
+      throw new Error("Missing Twitch token");
+    }
+
+    this.logger.debug?.(`Using ${tokenResolution.source} token source for ${account.username}`);
+
+    if (!account.clientId) {
+      this.logger.error(`Missing Twitch client ID for account ${account.username}`);
+      throw new Error("Missing Twitch client ID");
+    }
+
+    const normalizedToken = normalizeToken(tokenResolution.token);
+
+    const authProvider = await this.createAuthProvider(account, normalizedToken);
+
+    const client = new ChatClient({
+      authProvider,
+      channels: [account.channel],
+      rejoinChannelsOnReconnect: true,
+      requestMembershipEvents: true,
+      logger: {
+        minLevel: LogLevel.WARNING,
+        custom: {
+          log: (level, message) => {
+            switch (level) {
+              case LogLevel.CRITICAL:
+                this.logger.error(message);
+                break;
+              case LogLevel.ERROR:
+                this.logger.error(message);
+                break;
+              case LogLevel.WARNING:
+                this.logger.warn(message);
+                break;
+              case LogLevel.INFO:
+                this.logger.info(message);
+                break;
+              case LogLevel.DEBUG:
+                this.logger.debug?.(message);
+                break;
+              case LogLevel.TRACE:
+                this.logger.debug?.(message);
+                break;
+            }
+          },
+        },
+      },
+    });
+
+    this.setupClientHandlers(client, account);
+
+    client.connect();
+
+    this.clients.set(key, client);
+    this.logger.info(`Connected to Twitch as ${account.username}`);
+
+    return client;
+  }
+
+  /**
+   * Set up message and event handlers for a client
+   */
+  private setupClientHandlers(client: ChatClient, account: TwitchAccountConfig): void {
+    const key = this.getAccountKey(account);
+
+    // Handle incoming messages
+    client.onMessage((channelName, _user, messageText, msg) => {
+      const handler = this.messageHandlers.get(key);
+      if (handler) {
+        const normalizedChannel = channelName.startsWith("#") ? channelName.slice(1) : channelName;
+        const from = `twitch:${msg.userInfo.userName}`;
+        const preview = messageText.slice(0, 100).replace(/\n/g, "\\n");
+        this.logger.debug?.(
+          `twitch inbound: channel=${normalizedChannel} from=${from} len=${messageText.length} preview="${preview}"`,
+        );
+
+        handler({
+          username: msg.userInfo.userName,
+          displayName: msg.userInfo.displayName,
+          userId: msg.userInfo.userId,
+          message: messageText,
+          channel: normalizedChannel,
+          id: msg.id,
+          timestamp: new Date(),
+          isMod: msg.userInfo.isMod,
+          isOwner: msg.userInfo.isBroadcaster,
+          isVip: msg.userInfo.isVip,
+          isSub: msg.userInfo.isSubscriber,
+          chatType: "group",
+        });
+      }
+    });
+
+    this.logger.info(`Set up handlers for ${key}`);
+  }
+
+  /**
+   * Set a message handler for an account
+   * @returns A function that removes the handler when called
+   */
+  onMessage(
+    account: TwitchAccountConfig,
+    handler: (message: TwitchChatMessage) => void,
+  ): () => void {
+    const key = this.getAccountKey(account);
+    this.messageHandlers.set(key, handler);
+    return () => {
+      this.messageHandlers.delete(key);
+    };
+  }
+
+  /**
+   * Disconnect a client
+   */
+  async disconnect(account: TwitchAccountConfig): Promise<void> {
+    const key = this.getAccountKey(account);
+    const client = this.clients.get(key);
+
+    if (client) {
+      client.quit();
+      this.clients.delete(key);
+      this.messageHandlers.delete(key);
+      this.logger.info(`Disconnected ${key}`);
+    }
+  }
+
+  /**
+   * Disconnect all clients
+   */
+  async disconnectAll(): Promise<void> {
+    this.clients.forEach((client) => client.quit());
+    this.clients.clear();
+    this.messageHandlers.clear();
+    this.logger.info(" Disconnected all clients");
+  }
+
+  /**
+   * Send a message to a channel
+   */
+  async sendMessage(
+    account: TwitchAccountConfig,
+    channel: string,
+    message: string,
+    cfg?: KlawConfig,
+    accountId?: string,
+  ): Promise<{ ok: boolean; error?: string; messageId?: string }> {
+    try {
+      const client = await this.getClient(account, cfg, accountId);
+
+      // Generate a message ID (Twurple's say() doesn't return the message ID, so we generate one)
+      const messageId = crypto.randomUUID();
+
+      // Send message (Twurple handles rate limiting)
+      await client.say(channel, message);
+
+      return { ok: true, messageId };
+    } catch (error) {
+      this.logger.error(`Failed to send message: ${formatErrorMessage(error)}`);
+      return {
+        ok: false,
+        error: formatErrorMessage(error),
+      };
+    }
+  }
+
+  /**
+   * Generate a unique key for an account
+   */
+  public getAccountKey(account: TwitchAccountConfig): string {
+    return `${account.username}:${account.channel}`;
+  }
+
+  /**
+   * Clear all clients and handlers (for testing)
+   */
+  clearForTest(): void {
+    this.clients.clear();
+    this.messageHandlers.clear();
+  }
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Twitch channel plugin types.
+ *
+ * This file defines Twitch-specific types. Generic channel types are imported
+ * from Klaw core.
+ */
+
+import type {
+  ChannelAccountSnapshot,
+  ChannelLogSink,
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelOutboundAdapter,
+  ChannelOutboundContext,
+  ChannelPlugin,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  OutboundDeliveryResult,
+} from "../runtime-api.js";
+
+// ============================================================================
+// Twitch-Specific Types
+// ============================================================================
+
+/**
+ * Twitch user roles that can be allowed to interact with the bot
+ */
+export type TwitchRole = "moderator" | "owner" | "vip" | "subscriber" | "all";
+
+/**
+ * Account configuration for a Twitch channel
+ */
+export interface TwitchAccountConfig {
+  /** Twitch username */
+  username: string;
+  /** Twitch OAuth access token (requires chat:read and chat:write scopes) */
+  accessToken: string;
+  /** Twitch client ID (from Twitch Developer Portal or twitchtokengenerator.com) */
+  clientId: string;
+  /** Channel name to join (required) */
+  channel: string;
+  /** Enable this account */
+  enabled?: boolean;
+  /** Allowlist of Twitch user IDs who can interact with the bot (use IDs for safety, not usernames) */
+  allowFrom?: Array<string>;
+  /** Roles allowed to interact with the bot (e.g., ["mod", "vip", "sub"]) */
+  allowedRoles?: TwitchRole[];
+  /** Require @mention to trigger bot responses */
+  requireMention?: boolean;
+  /** Outbound response prefix override for this channel/account. */
+  responsePrefix?: string;
+  /** Twitch client secret (required for token refresh via RefreshingAuthProvider) */
+  clientSecret?: string;
+  /** Refresh token (required for automatic token refresh) */
+  refreshToken?: string;
+  /** Token expiry time in seconds (optional, for token refresh tracking) */
+  expiresIn?: number | null;
+  /** Timestamp when token was obtained (optional, for token refresh tracking) */
+  obtainmentTimestamp?: number;
+}
+
+/**
+ * Twitch message from chat
+ */
+export interface TwitchChatMessage {
+  /** Username of sender */
+  username: string;
+  /** Twitch user ID of sender (unique, persistent identifier) */
+  userId?: string;
+  /** Message text */
+  message: string;
+  /** Channel name */
+  channel: string;
+  /** Display name (may include special characters) */
+  displayName?: string;
+  /** Message ID */
+  id?: string;
+  /** Timestamp */
+  timestamp?: Date;
+  /** Whether the sender is a moderator */
+  isMod?: boolean;
+  /** Whether the sender is the channel owner/broadcaster */
+  isOwner?: boolean;
+  /** Whether the sender is a VIP */
+  isVip?: boolean;
+  /** Whether the sender is a subscriber */
+  isSub?: boolean;
+  /** Chat type */
+  chatType?: "group";
+}
+
+// Re-export core types for convenience
+export type {
+  ChannelAccountSnapshot,
+  ChannelLogSink,
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelOutboundAdapter,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  ChannelPlugin,
+  ChannelOutboundContext,
+  OutboundDeliveryResult,
+};

package/src/utils/markdown.ts

@@ -0,0 +1,98 @@
+/**
+ * Markdown utilities for Twitch chat
+ *
+ * Twitch chat doesn't support markdown formatting, so we strip it before sending.
+ * Based on Klaw's markdownToText in src/agents/tools/web-fetch-utils.ts.
+ */
+
+/**
+ * Strip markdown formatting from text for Twitch compatibility.
+ *
+ * Removes images, links, bold, italic, strikethrough, code blocks, inline code,
+ * headers, and list formatting. Replaces newlines with spaces since Twitch
+ * is a single-line chat medium.
+ *
+ * @param markdown - The markdown text to strip
+ * @returns Plain text with markdown removed
+ */
+export function stripMarkdownForTwitch(markdown: string): string {
+  return (
+    markdown
+      // Images
+      .replace(/!\[[^\]]*]\([^)]+\)/g, "")
+      // Links
+      .replace(/\[([^\]]+)]\([^)]+\)/g, "$1")
+      // Bold (**text**)
+      .replace(/\*\*([^*]+)\*\*/g, "$1")
+      // Bold (__text__)
+      .replace(/__([^_]+)__/g, "$1")
+      // Italic (*text*)
+      .replace(/\*([^*]+)\*/g, "$1")
+      // Italic (_text_)
+      .replace(/_([^_]+)_/g, "$1")
+      // Strikethrough (~~text~~)
+      .replace(/~~([^~]+)~~/g, "$1")
+      // Code blocks
+      .replace(/```[\s\S]*?```/g, (block) => block.replace(/```[^\n]*\n?/g, "").replace(/```/g, ""))
+      // Inline code
+      .replace(/`([^`]+)`/g, "$1")
+      // Headers
+      .replace(/^#{1,6}\s+/gm, "")
+      // Lists
+      .replace(/^\s*[-*+]\s+/gm, "")
+      .replace(/^\s*\d+\.\s+/gm, "")
+      // Normalize whitespace
+      .replace(/\r/g, "") // Remove carriage returns
+      .replace(/[ \t]+\n/g, "\n") // Remove trailing spaces before newlines
+      .replace(/\n/g, " ") // Replace newlines with spaces (for Twitch)
+      .replace(/[ \t]{2,}/g, " ") // Reduce multiple spaces to single
+      .trim()
+  );
+}
+
+/**
+ * Simple word-boundary chunker for Twitch (500 char limit).
+ * Strips markdown before chunking to avoid breaking markdown patterns.
+ *
+ * @param text - The text to chunk
+ * @param limit - Maximum characters per chunk (Twitch limit is 500)
+ * @returns Array of text chunks
+ */
+export function chunkTextForTwitch(text: string, limit: number): string[] {
+  // First, strip markdown
+  const cleaned = stripMarkdownForTwitch(text);
+  if (!cleaned) {
+    return [];
+  }
+  if (limit <= 0) {
+    return [cleaned];
+  }
+  if (cleaned.length <= limit) {
+    return [cleaned];
+  }
+
+  const chunks: string[] = [];
+  let remaining = cleaned;
+
+  while (remaining.length > limit) {
+    // Find the last space before the limit
+    const window = remaining.slice(0, limit);
+    const lastSpaceIndex = window.lastIndexOf(" ");
+
+    if (lastSpaceIndex === -1) {
+      // No space found, hard split at limit
+      chunks.push(window);
+      remaining = remaining.slice(limit);
+    } else {
+      // Split at the last space
+      chunks.push(window.slice(0, lastSpaceIndex));
+      remaining = remaining.slice(lastSpaceIndex + 1);
+    }
+  }
+
+  if (remaining) {
+    chunks.push(remaining);
+  }
+
+  return chunks;
+}

package/src/utils/twitch.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+
+/**
+ * Twitch-specific utility functions
+ */
+
+/**
+ * Normalize Twitch channel names.
+ *
+ * Removes the '#' prefix if present, converts to lowercase, and trims whitespace.
+ * Twitch channel names are case-insensitive and don't use the '#' prefix in the API.
+ *
+ * @param channel - The channel name to normalize
+ * @returns Normalized channel name
+ *
+ * @example
+ * normalizeTwitchChannel("#TwitchChannel") // "twitchchannel"
+ * normalizeTwitchChannel("MyChannel") // "mychannel"
+ */
+export function normalizeTwitchChannel(channel: string): string {
+  const trimmed = normalizeLowercaseStringOrEmpty(channel);
+  return trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+}
+
+/**
+ * Create a standardized error message for missing target.
+ *
+ * @param provider - The provider name (e.g., "Twitch")
+ * @param hint - Optional hint for how to fix the issue
+ * @returns Error object with descriptive message
+ */
+export function missingTargetError(provider: string, hint?: string): Error {
+  return new Error(`Delivering to ${provider} requires target${hint ? ` ${hint}` : ""}`);
+}
+
+/**
+ * Generate a unique message ID for Twitch messages.
+ *
+ * Twurple's say() doesn't return the message ID, so we generate one
+ * for tracking purposes.
+ *
+ * @returns A unique message ID
+ */
+export function generateMessageId(): string {
+  return `${Date.now()}-${randomUUID()}`;
+}
+
+/**
+ * Normalize OAuth token by removing the "oauth:" prefix if present.
+ *
+ * Twurple doesn't require the "oauth:" prefix, so we strip it for consistency.
+ *
+ * @param token - The OAuth token to normalize
+ * @returns Normalized token without "oauth:" prefix
+ *
+ * @example
+ * normalizeToken("oauth:abc123") // "abc123"
+ * normalizeToken("abc123") // "abc123"
+ */
+export function normalizeToken(token: string): string {
+  return token.startsWith("oauth:") ? token.slice(6) : token;
+}
+
+/**
+ * Check if an account is properly configured with required credentials.
+ *
+ * @param account - The Twitch account config to check
+ * @returns true if the account has required credentials
+ */
+export function isAccountConfigured(
+  account: {
+    username?: string;
+    accessToken?: string;
+    clientId?: string;
+  },
+  resolvedToken?: string | null,
+): boolean {
+  const token = resolvedToken ?? account?.accessToken;
+  return Boolean(account?.username && token && account?.clientId);
+}

package/test/setup.ts

@@ -0,0 +1,7 @@
+/**
+ * Vitest setup file for Twitch plugin tests.
+ *
+ * Re-exports the root test setup to avoid duplication.
+ */
+
+export * from "../../../test/setup.js";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/api.js";
-import * as module from "../../../dist/extensions/twitch/api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/channel-plugin-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/channel-plugin-api.js";
-import * as module from "../../../dist/extensions/twitch/channel-plugin-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/index.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/index.js";
-import defaultModule from "../../../dist/extensions/twitch/index.js";
-let defaultExport = defaultModule;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/runtime-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/runtime-api.js";
-import * as module from "../../../dist/extensions/twitch/runtime-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/setup-entry.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/setup-entry.js";
-import defaultModule from "../../../dist/extensions/twitch/setup-entry.js";
-let defaultExport = defaultModule;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };

package/setup-plugin-api.js

@@ -1,7 +0,0 @@
-export * from "../../../dist/extensions/twitch/setup-plugin-api.js";
-import * as module from "../../../dist/extensions/twitch/setup-plugin-api.js";
-let defaultExport = "default" in module ? module.default : module;
-for (let index = 0; index < 4 && defaultExport && typeof defaultExport === "object" && "default" in defaultExport; index += 1) {
-  defaultExport = defaultExport.default;
-}
-export { defaultExport as default };