@kodelyth/twitch 2026.5.42 → 2026.6.2

package/src/outbound.ts

@@ -1,242 +0,0 @@
-/**
- * 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 "klaw/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: klawConfig,
-   *   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: klawConfig,
-   *   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.lifecycle.test.ts

@@ -1,86 +0,0 @@
-import {
-  createStartAccountContext,
-  expectStopPendingUntilAbort,
-  startAccountAndTrackLifecycle,
-  waitForStartedMocks,
-} from "klaw/plugin-sdk/channel-test-helpers";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { TwitchAccountConfig } from "./types.js";
-
-const hoisted = vi.hoisted(() => ({
-  monitorTwitchProvider: vi.fn(),
-}));
-
-vi.mock("./monitor.js", () => ({
-  monitorTwitchProvider: hoisted.monitorTwitchProvider,
-}));
-
-const { twitchPlugin } = await import("./plugin.js");
-
-type TwitchStartAccount = NonNullable<NonNullable<typeof twitchPlugin.gateway>["startAccount"]>;
-
-function requireStartAccount(): TwitchStartAccount {
-  const startAccount = twitchPlugin.gateway?.startAccount;
-  if (!startAccount) {
-    throw new Error("Expected Twitch gateway startAccount");
-  }
-  return startAccount;
-}
-
-function buildAccount(): TwitchAccountConfig & { accountId: string } {
-  return {
-    accountId: "default",
-    username: "testbot",
-    accessToken: "oauth:test-token",
-    clientId: "test-client-id",
-    channel: "#testchannel",
-    enabled: true,
-  };
-}
-
-function mockStartedMonitor() {
-  const stop = vi.fn();
-  hoisted.monitorTwitchProvider.mockResolvedValue({ stop });
-  return stop;
-}
-
-function startTwitchAccount(abortSignal?: AbortSignal) {
-  return requireStartAccount()(
-    createStartAccountContext({
-      account: buildAccount(),
-      abortSignal,
-    }),
-  );
-}
-
-describe("twitch startAccount lifecycle", () => {
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("keeps startAccount pending until abort, then stops the monitor", async () => {
-    const stop = mockStartedMonitor();
-    const { abort, task, isSettled } = startAccountAndTrackLifecycle({
-      startAccount: requireStartAccount(),
-      account: buildAccount(),
-    });
-    await expectStopPendingUntilAbort({
-      waitForStarted: waitForStartedMocks(hoisted.monitorTwitchProvider),
-      isSettled,
-      abort,
-      task,
-      stop,
-    });
-  });
-
-  it("stops immediately when startAccount receives an already-aborted signal", async () => {
-    const stop = mockStartedMonitor();
-    const abort = new AbortController();
-    abort.abort();
-
-    await startTwitchAccount(abort.signal);
-
-    expect(hoisted.monitorTwitchProvider).toHaveBeenCalledOnce();
-    expect(stop).toHaveBeenCalledOnce();
-  });
-});

package/src/plugin.live.test.ts

@@ -1,120 +0,0 @@
-/**
- * Live Twitch IRC verification for the runStoppablePassiveMonitor lifecycle
- * pattern used by the Twitch gateway.
- *
- * This test connects to irc.chat.twitch.tv using the same twurple stack the
- * Twitch plugin uses, then drives that connection through the helper this PR
- * wires into twitchPlugin.gateway.startAccount. It asserts the post-fix
- * invariant — startAccount-shaped task stays pending after a successful
- * connection and only resolves when the abort signal fires — using real
- * network rather than mocks.
- *
- * Skipped by default. Enable with:
- *   TWITCH_LIVE_TEST=1
- *   TWITCH_USERNAME=<bot username>
- *   TWITCH_ACCESS_TOKEN=<oauth:token without the "oauth:" prefix>
- *   TWITCH_CLIENT_ID=<client id>
- *   TWITCH_CHANNEL=<channel name to join>
- */
-
-import { StaticAuthProvider } from "@twurple/auth";
-import { ChatClient } from "@twurple/chat";
-import { runStoppablePassiveMonitor } from "klaw/plugin-sdk/extension-shared";
-import { describe, expect, it } from "vitest";
-
-const LIVE = process.env.TWITCH_LIVE_TEST === "1";
-const HAS_CREDS = Boolean(
-  process.env.TWITCH_USERNAME &&
-  process.env.TWITCH_ACCESS_TOKEN &&
-  process.env.TWITCH_CLIENT_ID &&
-  process.env.TWITCH_CHANNEL,
-);
-
-const maybeDescribe = LIVE && HAS_CREDS ? describe : describe.skip;
-
-maybeDescribe("twitch live IRC lifecycle (skipped unless TWITCH_LIVE_TEST=1)", () => {
-  it("real twurple connection + runStoppablePassiveMonitor stays pending until abort, then stops cleanly", async () => {
-    const accessTokenRaw = process.env.TWITCH_ACCESS_TOKEN!.replace(/^oauth:/, "");
-    const clientId = process.env.TWITCH_CLIENT_ID!;
-    const channel = process.env.TWITCH_CHANNEL!;
-    const username = process.env.TWITCH_USERNAME!;
-
-    const start = Date.now();
-    const log = (msg: string) => {
-      console.log(`[T+${Date.now() - start}ms] ${msg}`);
-    };
-
-    log(`username=${username} channel=#${channel}`);
-
-    const authProvider = new StaticAuthProvider(clientId, accessTokenRaw, [
-      "chat:read",
-      "chat:edit",
-    ]);
-
-    const abort = new AbortController();
-    let connectedAt: number | null = null;
-    let settled = false;
-    let stopCalled = false;
-
-    const task = runStoppablePassiveMonitor({
-      abortSignal: abort.signal,
-      start: async () => {
-        const chat = new ChatClient({
-          authProvider,
-          channels: [channel],
-          authIntents: ["chat"],
-        });
-
-        chat.onConnect(() => {
-          connectedAt = Date.now() - start;
-          log(`Connected to Twitch as ${username}`);
-        });
-        chat.onJoin((joinedChannel: string, joinedUser: string) => {
-          log(`Joined #${joinedChannel} as ${joinedUser}`);
-        });
-        chat.onDisconnect((manually: boolean, reason?: Error) => {
-          log(`Disconnected (manual=${manually}, reason=${reason?.message ?? "n/a"})`);
-        });
-
-        chat.connect();
-
-        return {
-          stop: () => {
-            stopCalled = true;
-            log(`stop() invoked`);
-            chat.quit();
-          },
-        };
-      },
-    })
-      .then(() => {
-        settled = true;
-        log(`task RESOLVED`);
-      })
-      .catch((err: unknown) => {
-        settled = true;
-        log(`task REJECTED: ${err instanceof Error ? err.message : String(err)}`);
-        throw err;
-      });
-
-    // Wait long enough that the original bug would have manifested.
-    // The reported time-to-restart in #60071 is ~2ms after connect.
-    const WATCH_MS = 15_000;
-    await new Promise((resolve) => setTimeout(resolve, WATCH_MS));
-
-    expect(connectedAt, "expected onConnect within the watch window").not.toBeNull();
-    expect(settled, "task must not have settled before abort").toBe(false);
-    log(
-      `--- t+${WATCH_MS}ms checkpoint: connected=${connectedAt}ms, settled=${settled}, stopCalled=${stopCalled}`,
-    );
-
-    abort.abort();
-    log(`abort() called`);
-
-    await task;
-
-    expect(settled).toBe(true);
-    expect(stopCalled, "stop hook must run on abort").toBe(true);
-    log(`PASS — promise pending for ${WATCH_MS}ms after connect, then stopped on abort`);
-  }, 60_000);
-});

package/src/plugin.test.ts

@@ -1,77 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { KlawConfig } from "../api.js";
-import { twitchPlugin } from "./plugin.js";
-
-describe("twitchPlugin pairing", () => {
-  it("normalizes trimmed twitch user prefixes in allow entries", () => {
-    expect(twitchPlugin.pairing?.normalizeAllowEntry?.("  twitch:user:123456  ")).toBe("123456");
-    expect(twitchPlugin.pairing?.normalizeAllowEntry?.("  user789012  ")).toBe("789012");
-  });
-});
-
-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 KlawConfig;
-
-    const snapshot = await twitchPlugin.status?.buildAccountSnapshot?.({
-      account: secondary,
-      cfg,
-    });
-
-    expect(snapshot?.accountId).toBe("secondary");
-  });
-});
-
-describe("twitchPlugin.config", () => {
-  it("uses configured defaultAccount for omitted-account plugin resolution", () => {
-    const cfg = {
-      channels: {
-        twitch: {
-          defaultAccount: "secondary",
-          accounts: {
-            default: {
-              channel: "default-channel",
-              username: "default",
-              accessToken: "oauth:default-token",
-              clientId: "default-client",
-              enabled: true,
-            },
-            secondary: {
-              channel: "secondary-channel",
-              username: "secondary",
-              accessToken: "oauth:secondary-token",
-              clientId: "secondary-client",
-              enabled: true,
-            },
-          },
-        },
-      },
-    } as KlawConfig;
-
-    expect(twitchPlugin.config.defaultAccountId?.(cfg)).toBe("secondary");
-    expect(twitchPlugin.config.resolveAccount(cfg).accountId).toBe("secondary");
-  });
-});