@openclaw/twitch 2026.2.21

package/src/outbound.test.ts

@@ -0,0 +1,403 @@
+/**
+ * Tests for outbound.ts module
+ *
+ * Tests cover:
+ * - resolveTarget with various modes (explicit, implicit, heartbeat)
+ * - sendText with markdown stripping
+ * - sendMedia delegation to sendText
+ * - Error handling for missing accounts/channels
+ * - Abort signal handling
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { twitchOutbound } from "./outbound.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("./send.js", () => ({
+  sendMessageTwitchInternal: vi.fn(),
+}));
+
+vi.mock("./utils/markdown.js", () => ({
+  chunkTextForTwitch: vi.fn((text) => text.split(/(.{500})/).filter(Boolean)),
+}));
+
+vi.mock("./utils/twitch.js", () => ({
+  normalizeTwitchChannel: (channel: string) => channel.toLowerCase().replace(/^#/, ""),
+  missingTargetError: (channel: string, hint: string) =>
+    new Error(`Missing target for ${channel}. Provide ${hint}`),
+}));
+
+function assertResolvedTarget(
+  result: ReturnType<NonNullable<typeof twitchOutbound.resolveTarget>>,
+): string {
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.to;
+}
+
+describe("outbound", () => {
+  const mockAccount = {
+    ...BASE_TWITCH_TEST_ACCOUNT,
+    accessToken: "oauth:test123",
+  };
+  const resolveTarget = twitchOutbound.resolveTarget!;
+
+  const mockConfig = makeTwitchTestConfig(mockAccount);
+  installTwitchTestHooks();
+
+  describe("metadata", () => {
+    it("should have direct delivery mode", () => {
+      expect(twitchOutbound.deliveryMode).toBe("direct");
+    });
+
+    it("should have 500 character text chunk limit", () => {
+      expect(twitchOutbound.textChunkLimit).toBe(500);
+    });
+
+    it("should have chunker function", () => {
+      expect(twitchOutbound.chunker).toBeDefined();
+      expect(typeof twitchOutbound.chunker).toBe("function");
+    });
+  });
+
+  describe("resolveTarget", () => {
+    it("should normalize and return target in explicit mode", () => {
+      const result = resolveTarget({
+        to: "#MyChannel",
+        mode: "explicit",
+        allowFrom: [],
+      });
+
+      expect(result.ok).toBe(true);
+      expect(assertResolvedTarget(result)).toBe("mychannel");
+    });
+
+    it("should return target in implicit mode with wildcard allowlist", () => {
+      const result = resolveTarget({
+        to: "#AnyChannel",
+        mode: "implicit",
+        allowFrom: ["*"],
+      });
+
+      expect(result.ok).toBe(true);
+      expect(assertResolvedTarget(result)).toBe("anychannel");
+    });
+
+    it("should return target in implicit mode when in allowlist", () => {
+      const result = resolveTarget({
+        to: "#allowed",
+        mode: "implicit",
+        allowFrom: ["#allowed", "#other"],
+      });
+
+      expect(result.ok).toBe(true);
+      expect(assertResolvedTarget(result)).toBe("allowed");
+    });
+
+    it("should error when target not in allowlist (implicit mode)", () => {
+      const result = resolveTarget({
+        to: "#notallowed",
+        mode: "implicit",
+        allowFrom: ["#primary", "#secondary"],
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error("expected resolveTarget to fail");
+      }
+      expect(result.error.message).toContain("Twitch");
+    });
+
+    it("should accept any target when allowlist is empty", () => {
+      const result = resolveTarget({
+        to: "#anychannel",
+        mode: "heartbeat",
+        allowFrom: [],
+      });
+
+      expect(result.ok).toBe(true);
+      expect(assertResolvedTarget(result)).toBe("anychannel");
+    });
+
+    it("should error when no target provided with allowlist", () => {
+      const result = resolveTarget({
+        to: undefined,
+        mode: "implicit",
+        allowFrom: ["#fallback", "#other"],
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error("expected resolveTarget to fail");
+      }
+      expect(result.error.message).toContain("Twitch");
+    });
+
+    it("should return error when no target and no allowlist", () => {
+      const result = resolveTarget({
+        to: undefined,
+        mode: "explicit",
+        allowFrom: [],
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error("expected resolveTarget to fail");
+      }
+      expect(result.error.message).toContain("Missing target");
+    });
+
+    it("should handle whitespace-only target", () => {
+      const result = resolveTarget({
+        to: "   ",
+        mode: "explicit",
+        allowFrom: [],
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error("expected resolveTarget to fail");
+      }
+      expect(result.error.message).toContain("Missing target");
+    });
+
+    it("should error when target normalizes to empty string", () => {
+      const result = resolveTarget({
+        to: "#",
+        mode: "explicit",
+        allowFrom: [],
+      });
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error("expected resolveTarget to fail");
+      }
+      expect(result.error.message).toContain("Twitch");
+    });
+
+    it("should filter wildcard from allowlist when checking membership", () => {
+      const result = resolveTarget({
+        to: "#mychannel",
+        mode: "implicit",
+        allowFrom: ["*", "#specific"],
+      });
+
+      // With wildcard, any target is accepted
+      expect(result.ok).toBe(true);
+      expect(assertResolvedTarget(result)).toBe("mychannel");
+    });
+  });
+
+  describe("sendText", () => {
+    it("should send message successfully", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { sendMessageTwitchInternal } = await import("./send.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(sendMessageTwitchInternal).mockResolvedValue({
+        ok: true,
+        messageId: "twitch-msg-123",
+      });
+
+      const result = await twitchOutbound.sendText!({
+        cfg: mockConfig,
+        to: "#testchannel",
+        text: "Hello Twitch!",
+        accountId: "default",
+      });
+
+      expect(result.channel).toBe("twitch");
+      expect(result.messageId).toBe("twitch-msg-123");
+      expect(sendMessageTwitchInternal).toHaveBeenCalledWith(
+        "testchannel",
+        "Hello Twitch!",
+        mockConfig,
+        "default",
+        true,
+        console,
+      );
+      expect(result.timestamp).toBeGreaterThan(0);
+    });
+
+    it("should throw when account not found", async () => {
+      const { getAccountConfig } = await import("./config.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(null);
+
+      await expect(
+        twitchOutbound.sendText!({
+          cfg: mockConfig,
+          to: "#testchannel",
+          text: "Hello!",
+          accountId: "nonexistent",
+        }),
+      ).rejects.toThrow("Twitch account not found: nonexistent");
+    });
+
+    it("should throw when no channel specified", async () => {
+      const { getAccountConfig } = await import("./config.js");
+
+      const accountWithoutChannel = { ...mockAccount, channel: undefined as unknown as string };
+      vi.mocked(getAccountConfig).mockReturnValue(accountWithoutChannel);
+
+      await expect(
+        twitchOutbound.sendText!({
+          cfg: mockConfig,
+          to: "",
+          text: "Hello!",
+          accountId: "default",
+        }),
+      ).rejects.toThrow("No channel specified");
+    });
+
+    it("should use account channel when target not provided", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { sendMessageTwitchInternal } = await import("./send.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(sendMessageTwitchInternal).mockResolvedValue({
+        ok: true,
+        messageId: "msg-456",
+      });
+
+      await twitchOutbound.sendText!({
+        cfg: mockConfig,
+        to: "",
+        text: "Hello!",
+        accountId: "default",
+      });
+
+      expect(sendMessageTwitchInternal).toHaveBeenCalledWith(
+        "testchannel",
+        "Hello!",
+        mockConfig,
+        "default",
+        true,
+        console,
+      );
+    });
+
+    it("should handle abort signal", async () => {
+      const abortController = new AbortController();
+      abortController.abort();
+
+      await expect(
+        twitchOutbound.sendText!({
+          cfg: mockConfig,
+          to: "#testchannel",
+          text: "Hello!",
+          accountId: "default",
+          signal: abortController.signal,
+        } as Parameters<NonNullable<typeof twitchOutbound.sendText>>[0]),
+      ).rejects.toThrow("Outbound delivery aborted");
+    });
+
+    it("should throw on send failure", async () => {
+      const { getAccountConfig } = await import("./config.js");
+      const { sendMessageTwitchInternal } = await import("./send.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(sendMessageTwitchInternal).mockResolvedValue({
+        ok: false,
+        messageId: "failed-msg",
+        error: "Connection lost",
+      });
+
+      await expect(
+        twitchOutbound.sendText!({
+          cfg: mockConfig,
+          to: "#testchannel",
+          text: "Hello!",
+          accountId: "default",
+        }),
+      ).rejects.toThrow("Connection lost");
+    });
+  });
+
+  describe("sendMedia", () => {
+    it("should combine text and media URL", async () => {
+      const { sendMessageTwitchInternal } = await import("./send.js");
+      const { getAccountConfig } = await import("./config.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(sendMessageTwitchInternal).mockResolvedValue({
+        ok: true,
+        messageId: "media-msg-123",
+      });
+
+      const result = await twitchOutbound.sendMedia!({
+        cfg: mockConfig,
+        to: "#testchannel",
+        text: "Check this:",
+        mediaUrl: "https://example.com/image.png",
+        accountId: "default",
+      });
+
+      expect(result.channel).toBe("twitch");
+      expect(result.messageId).toBe("media-msg-123");
+      expect(sendMessageTwitchInternal).toHaveBeenCalledWith(
+        expect.anything(),
+        "Check this: https://example.com/image.png",
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it("should send media URL only when no text", async () => {
+      const { sendMessageTwitchInternal } = await import("./send.js");
+      const { getAccountConfig } = await import("./config.js");
+
+      vi.mocked(getAccountConfig).mockReturnValue(mockAccount);
+      vi.mocked(sendMessageTwitchInternal).mockResolvedValue({
+        ok: true,
+        messageId: "media-only-msg",
+      });
+
+      await twitchOutbound.sendMedia!({
+        cfg: mockConfig,
+        to: "#testchannel",
+        text: "",
+        mediaUrl: "https://example.com/image.png",
+        accountId: "default",
+      });
+
+      expect(sendMessageTwitchInternal).toHaveBeenCalledWith(
+        expect.anything(),
+        "https://example.com/image.png",
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it("should handle abort signal", async () => {
+      const abortController = new AbortController();
+      abortController.abort();
+
+      await expect(
+        twitchOutbound.sendMedia!({
+          cfg: mockConfig,
+          to: "#testchannel",
+          text: "Check this:",
+          mediaUrl: "https://example.com/image.png",
+          accountId: "default",
+          signal: abortController.signal,
+        } as Parameters<NonNullable<typeof twitchOutbound.sendMedia>>[0]),
+      ).rejects.toThrow("Outbound delivery aborted");
+    });
+  });
+});

package/src/outbound.ts

@@ -0,0 +1,187 @@
+/**
+ * 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 { DEFAULT_ACCOUNT_ID, getAccountConfig } 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",
+
+  /** 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: openclawConfig,
+   *   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 ?? DEFAULT_ACCOUNT_ID;
+    const account = getAccountConfig(cfg, resolvedAccountId);
+    if (!account) {
+      const availableIds = Object.keys(cfg.channels?.twitch?.accounts ?? {});
+      throw new Error(
+        `Twitch account not found: ${resolvedAccountId}. ` +
+          `Available accounts: ${availableIds.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,
+      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: openclawConfig,
+   *   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,
+    });
+  },
+};

package/src/plugin.test.ts

@@ -0,0 +1,39 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { describe, expect, it } from "vitest";
+import { twitchPlugin } from "./plugin.js";
+
+describe("twitchPlugin.status.buildAccountSnapshot", () => {
+  it("uses the resolved account ID for multi-account configs", async () => {
+    const secondary = {
+      channel: "secondary-channel",
+      username: "secondary",
+      accessToken: "oauth:secondary-token",
+      clientId: "secondary-client",
+      enabled: true,
+    };
+
+    const cfg = {
+      channels: {
+        twitch: {
+          accounts: {
+            default: {
+              channel: "default-channel",
+              username: "default",
+              accessToken: "oauth:default-token",
+              clientId: "default-client",
+              enabled: true,
+            },
+            secondary,
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const snapshot = await twitchPlugin.status?.buildAccountSnapshot?.({
+      account: secondary,
+      cfg,
+    });
+
+    expect(snapshot?.accountId).toBe("secondary");
+  });
+});