@openclaw/twitch 2026.2.21

package/src/resolver.ts

@@ -0,0 +1,137 @@
+/**
+ * Twitch resolver adapter for channel/user name resolution.
+ *
+ * This module implements the ChannelResolverAdapter interface to resolve
+ * Twitch usernames to user IDs via the Twitch Helix API.
+ */
+
+import { ApiClient } from "@twurple/api";
+import { StaticAuthProvider } from "@twurple/auth";
+import type { ChannelResolveKind, ChannelResolveResult } from "./types.js";
+import type { ChannelLogSink, TwitchAccountConfig } from "./types.js";
+import { normalizeToken } from "./utils/twitch.js";
+
+/**
+ * Normalize a Twitch username - strip @ prefix and convert to lowercase
+ */
+function normalizeUsername(input: string): string {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("@")) {
+    return trimmed.slice(1).toLowerCase();
+  }
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Create a logger that includes the Twitch prefix
+ */
+function createLogger(logger?: ChannelLogSink): ChannelLogSink {
+  return {
+    info: (msg: string) => logger?.info(msg),
+    warn: (msg: string) => logger?.warn(msg),
+    error: (msg: string) => logger?.error(msg),
+    debug: (msg: string) => logger?.debug?.(msg) ?? (() => {}),
+  };
+}
+
+/**
+ * Resolve Twitch usernames to user IDs via the Helix API
+ *
+ * @param inputs - Array of usernames or user IDs to resolve
+ * @param account - Twitch account configuration with auth credentials
+ * @param kind - Type of target to resolve ("user" or "group")
+ * @param logger - Optional logger
+ * @returns Promise resolving to array of ChannelResolveResult
+ */
+export async function resolveTwitchTargets(
+  inputs: string[],
+  account: TwitchAccountConfig,
+  kind: ChannelResolveKind,
+  logger?: ChannelLogSink,
+): Promise<ChannelResolveResult[]> {
+  const log = createLogger(logger);
+
+  if (!account.clientId || !account.accessToken) {
+    log.error("Missing Twitch client ID or accessToken");
+    return inputs.map((input) => ({
+      input,
+      resolved: false,
+      note: "missing Twitch credentials",
+    }));
+  }
+
+  const normalizedToken = normalizeToken(account.accessToken);
+
+  const authProvider = new StaticAuthProvider(account.clientId, normalizedToken);
+  const apiClient = new ApiClient({ authProvider });
+
+  const results: ChannelResolveResult[] = [];
+
+  for (const input of inputs) {
+    const normalized = normalizeUsername(input);
+
+    if (!normalized) {
+      results.push({
+        input,
+        resolved: false,
+        note: "empty input",
+      });
+      continue;
+    }
+
+    const looksLikeUserId = /^\d+$/.test(normalized);
+
+    try {
+      if (looksLikeUserId) {
+        const user = await apiClient.users.getUserById(normalized);
+
+        if (user) {
+          results.push({
+            input,
+            resolved: true,
+            id: user.id,
+            name: user.name,
+          });
+          log.debug?.(`Resolved user ID ${normalized} -> ${user.name}`);
+        } else {
+          results.push({
+            input,
+            resolved: false,
+            note: "user ID not found",
+          });
+          log.warn(`User ID ${normalized} not found`);
+        }
+      } else {
+        const user = await apiClient.users.getUserByName(normalized);
+
+        if (user) {
+          results.push({
+            input,
+            resolved: true,
+            id: user.id,
+            name: user.name,
+            note: user.displayName !== user.name ? `display: ${user.displayName}` : undefined,
+          });
+          log.debug?.(`Resolved username ${normalized} -> ${user.id} (${user.name})`);
+        } else {
+          results.push({
+            input,
+            resolved: false,
+            note: "username not found",
+          });
+          log.warn(`Username ${normalized} not found`);
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      results.push({
+        input,
+        resolved: false,
+        note: `API error: ${errorMessage}`,
+      });
+      log.error(`Failed to resolve ${input}: ${errorMessage}`);
+    }
+  }
+
+  return results;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setTwitchRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getTwitchRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Twitch runtime not initialized");
+  }
+  return runtime;
+}

package/src/send.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Tests for send.ts module
+ *
+ * Tests cover:
+ * - Message sending with valid configuration
+ * - Account resolution and validation
+ * - Channel normalization
+ * - Markdown stripping
+ * - Error handling for missing/invalid accounts
+ * - Registry integration
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { sendMessageTwitchInternal } from "./send.js";
+import {
+  BASE_TWITCH_TEST_ACCOUNT,
+  installTwitchTestHooks,
+  makeTwitchTestConfig,
+} from "./test-fixtures.js";
+
+// Mock dependencies
+vi.mock("./config.js", () => ({
+  DEFAULT_ACCOUNT_ID: "default",
+  getAccountConfig: vi.fn(),
+}));
+
+vi.mock("./utils/twitch.js", () => ({
+  generateMessageId: vi.fn(() => "test-msg-id"),
+  isAccountConfigured: vi.fn(() => true),
+  normalizeTwitchChannel: (channel: string) => channel.toLowerCase().replace(/^#/, ""),
+}));
+
+vi.mock("./utils/markdown.js", () => ({
+  stripMarkdownForTwitch: vi.fn((text: string) => text.replace(/\*\*/g, "")),
+}));
+
+vi.mock("./client-manager-registry.js", () => ({
+  getClientManager: vi.fn(),
+}));
+
+describe("send", () => {
+  const mockLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+
+  const mockAccount = {
+    ...BASE_TWITCH_TEST_ACCOUNT,
+    accessToken: "test123",
+  };
+
+  const mockConfig = makeTwitchTestConfig(mockAccount);
+  installTwitchTestHooks();
+
+  describe("sendMessageTwitchInternal", () => {
+    it("should send a message successfully", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { getClientManager } = await import("./client-manager-registry.js");
+      const { stripMarkdownForTwitch } = await import("./utils/markdown.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(getClientManager).mockReturnValue({
+        sendMessage: vi.fn().mockResolvedValue({
+          ok: true,
+          messageId: "twitch-msg-123",
+        }),
+      } as unknown as ReturnType<typeof getClientManager>);
+      vi.mocked(stripMarkdownForTwitch).mockImplementation((text) => text);
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "Hello Twitch!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.messageId).toBe("twitch-msg-123");
+    });
+
+    it("should strip markdown when enabled", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { getClientManager } = await import("./client-manager-registry.js");
+      const { stripMarkdownForTwitch } = await import("./utils/markdown.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(getClientManager).mockReturnValue({
+        sendMessage: vi.fn().mockResolvedValue({
+          ok: true,
+          messageId: "twitch-msg-456",
+        }),
+      } as unknown as ReturnType<typeof getClientManager>);
+      vi.mocked(stripMarkdownForTwitch).mockImplementation((text) => text.replace(/\*\*/g, ""));
+
+      await sendMessageTwitchInternal(
+        "#testchannel",
+        "**Bold** text",
+        mockConfig,
+        "default",
+        true,
+        mockLogger as unknown as Console,
+      );
+
+      expect(stripMarkdownForTwitch).toHaveBeenCalledWith("**Bold** text");
+    });
+
+    it("should return error when account not found", async () => {
+      const { getAccountConfig } = await import("./config.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(null);
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "Hello!",
+        mockConfig,
+        "nonexistent",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toContain("Account not found: nonexistent");
+    });
+
+    it("should return error when account not configured", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(isAccountConfigured).mockReturnValue(false);
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "Hello!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toContain("not properly configured");
+    });
+
+    it("should return error when no channel specified", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+
+      // Set channel to undefined to trigger the error (bypassing type check)
+      const accountWithoutChannel = {
+        ...mockAccount,
+        channel: undefined as unknown as string,
+      };
+      vi.mocked(getAccountConfig).mockReturnValue(accountWithoutChannel);
+      vi.mocked(isAccountConfigured).mockReturnValue(true);
+
+      const result = await sendMessageTwitchInternal(
+        "",
+        "Hello!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toContain("No channel specified");
+    });
+
+    it("should skip sending empty message after markdown stripping", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+      const { stripMarkdownForTwitch } = await import("./utils/markdown.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(isAccountConfigured).mockReturnValue(true);
+      vi.mocked(stripMarkdownForTwitch).mockReturnValue("");
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "**Only markdown**",
+        mockConfig,
+        "default",
+        true,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.messageId).toBe("skipped");
+    });
+
+    it("should return error when client manager not found", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+      const { getClientManager } = await import("./client-manager-registry.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(isAccountConfigured).mockReturnValue(true);
+      vi.mocked(getClientManager).mockReturnValue(undefined);
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "Hello!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toContain("Client manager not found");
+    });
+
+    it("should handle send errors gracefully", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+      const { getClientManager } = await import("./client-manager-registry.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(isAccountConfigured).mockReturnValue(true);
+      vi.mocked(getClientManager).mockReturnValue({
+        sendMessage: vi.fn().mockRejectedValue(new Error("Connection lost")),
+      } as unknown as ReturnType<typeof getClientManager>);
+
+      const result = await sendMessageTwitchInternal(
+        "#testchannel",
+        "Hello!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toBe("Connection lost");
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+
+    it("should use account channel when channel parameter is empty", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { isAccountConfigured } = await import("./utils/twitch.js");
+      const { getClientManager } = await import("./client-manager-registry.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(isAccountConfigured).mockReturnValue(true);
+      const mockSend = vi.fn().mockResolvedValue({
+        ok: true,
+        messageId: "twitch-msg-789",
+      });
+      vi.mocked(getClientManager).mockReturnValue({
+        sendMessage: mockSend,
+      } as unknown as ReturnType<typeof getClientManager>);
+
+      await sendMessageTwitchInternal(
+        "",
+        "Hello!",
+        mockConfig,
+        "default",
+        false,
+        mockLogger as unknown as Console,
+      );
+
+      expect(mockSend).toHaveBeenCalledWith(
+        mockAccount,
+        "testchannel", // normalized account channel
+        "Hello!",
+        mockConfig,
+        "default",
+      );
+    });
+  });
+});

package/src/send.ts

@@ -0,0 +1,136 @@
+/**
+ * Twitch message sending functions with dependency injection support.
+ *
+ * These functions are the primary interface for sending messages to Twitch.
+ * They support dependency injection via the `deps` parameter for testability.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { getClientManager as getRegistryClientManager } from "./client-manager-registry.js";
+import { DEFAULT_ACCOUNT_ID, getAccountConfig } from "./config.js";
+import { resolveTwitchToken } from "./token.js";
+import { stripMarkdownForTwitch } from "./utils/markdown.js";
+import { generateMessageId, isAccountConfigured, normalizeTwitchChannel } from "./utils/twitch.js";
+
+/**
+ * Result from sending a message to Twitch.
+ */
+export interface SendMessageResult {
+  /** Whether the send was successful */
+  ok: boolean;
+  /** The message ID (generated for tracking) */
+  messageId: string;
+  /** Error message if the send failed */
+  error?: string;
+}
+
+/**
+ * Internal send function used by the outbound adapter.
+ *
+ * This function has access to the full OpenClaw config and handles
+ * account resolution, markdown stripping, and actual message sending.
+ *
+ * @param channel - The channel name
+ * @param text - The message text
+ * @param cfg - Full OpenClaw configuration
+ * @param accountId - Account ID to use
+ * @param stripMarkdown - Whether to strip markdown (default: true)
+ * @param logger - Logger instance
+ * @returns Result with message ID and status
+ *
+ * @example
+ * const result = await sendMessageTwitchInternal(
+ *   "#mychannel",
+ *   "Hello Twitch!",
+ *   openclawConfig,
+ *   "default",
+ *   true,
+ *   console,
+ * );
+ */
+export async function sendMessageTwitchInternal(
+  channel: string,
+  text: string,
+  cfg: OpenClawConfig,
+  accountId: string = DEFAULT_ACCOUNT_ID,
+  stripMarkdown: boolean = true,
+  logger: Console = console,
+): Promise<SendMessageResult> {
+  const account = getAccountConfig(cfg, accountId);
+  if (!account) {
+    const availableIds = Object.keys(cfg.channels?.twitch?.accounts ?? {});
+    return {
+      ok: false,
+      messageId: generateMessageId(),
+      error: `Account not found: ${accountId}. Available accounts: ${availableIds.join(", ") || "none"}`,
+    };
+  }
+
+  const tokenResolution = resolveTwitchToken(cfg, { accountId });
+  if (!isAccountConfigured(account, tokenResolution.token)) {
+    return {
+      ok: false,
+      messageId: generateMessageId(),
+      error:
+        `Account ${accountId} is not properly configured. ` +
+        "Required: username, clientId, and token (config or env for default account).",
+    };
+  }
+
+  const normalizedChannel = channel || account.channel;
+  if (!normalizedChannel) {
+    return {
+      ok: false,
+      messageId: generateMessageId(),
+      error: "No channel specified and no default channel in account config",
+    };
+  }
+
+  const cleanedText = stripMarkdown ? stripMarkdownForTwitch(text) : text;
+  if (!cleanedText) {
+    return {
+      ok: true,
+      messageId: "skipped",
+    };
+  }
+
+  const clientManager = getRegistryClientManager(accountId);
+  if (!clientManager) {
+    return {
+      ok: false,
+      messageId: generateMessageId(),
+      error: `Client manager not found for account: ${accountId}. Please start the Twitch gateway first.`,
+    };
+  }
+
+  try {
+    const result = await clientManager.sendMessage(
+      account,
+      normalizeTwitchChannel(normalizedChannel),
+      cleanedText,
+      cfg,
+      accountId,
+    );
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        messageId: result.messageId ?? generateMessageId(),
+        error: result.error ?? "Send failed",
+      };
+    }
+
+    return {
+      ok: true,
+      messageId: result.messageId ?? generateMessageId(),
+    };
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to send message: ${errorMsg}`);
+    return {
+      ok: false,
+      messageId: generateMessageId(),
+      error: errorMsg,
+    };
+  }
+}