@openclaw/twitch 2026.5.2 → 2026.5.3-beta.1

package/setup-entry.ts

@@ -1,9 +0,0 @@
-import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
-
-export default defineBundledChannelSetupEntry({
-  importMetaUrl: import.meta.url,
-  plugin: {
-    specifier: "./setup-plugin-api.js",
-    exportName: "twitchSetupPlugin",
-  },
-});

package/setup-plugin-api.ts

@@ -1,3 +0,0 @@
-// Keep bundled setup entry imports narrow so setup loads do not pull the
-// broader Twitch channel plugin surface.
-export { twitchSetupPlugin } from "./src/setup-surface.js";

package/src/access-control.test.ts

@@ -1,388 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { checkTwitchAccessControl, extractMentions } from "./access-control.js";
-import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
-
-describe("checkTwitchAccessControl", () => {
-  const mockAccount: TwitchAccountConfig = {
-    username: "testbot",
-    accessToken: "test",
-    clientId: "test-client-id",
-    channel: "testchannel",
-  };
-
-  const mockMessage: TwitchChatMessage = {
-    username: "testuser",
-    userId: "123456",
-    message: "hello bot",
-    channel: "testchannel",
-  };
-
-  function runAccessCheck(params: {
-    account?: Partial<TwitchAccountConfig>;
-    message?: Partial<TwitchChatMessage>;
-  }) {
-    return checkTwitchAccessControl({
-      message: {
-        ...mockMessage,
-        ...params.message,
-      },
-      account: {
-        ...mockAccount,
-        ...params.account,
-      },
-      botUsername: "testbot",
-    });
-  }
-
-  function expectSingleRoleAllowed(params: {
-    role: NonNullable<TwitchAccountConfig["allowedRoles"]>[number];
-    message: Partial<TwitchChatMessage>;
-  }) {
-    const result = runAccessCheck({
-      account: { allowedRoles: [params.role] },
-      message: {
-        message: "@testbot hello",
-        ...params.message,
-      },
-    });
-    expect(result.allowed).toBe(true);
-    return result;
-  }
-
-  function expectAllowedAccessCheck(params: {
-    account?: Partial<TwitchAccountConfig>;
-    message?: Partial<TwitchChatMessage>;
-  }) {
-    const result = runAccessCheck({
-      account: params.account,
-      message: {
-        message: "@testbot hello",
-        ...params.message,
-      },
-    });
-    expect(result.allowed).toBe(true);
-    return result;
-  }
-
-  function expectAllowFromBlocked(params: {
-    allowFrom: string[];
-    allowedRoles?: NonNullable<TwitchAccountConfig["allowedRoles"]>;
-    message?: Partial<TwitchChatMessage>;
-    reason: string;
-  }) {
-    const result = runAccessCheck({
-      account: {
-        allowFrom: params.allowFrom,
-        allowedRoles: params.allowedRoles,
-      },
-      message: {
-        message: "@testbot hello",
-        ...params.message,
-      },
-    });
-    expect(result.allowed).toBe(false);
-    expect(result.reason).toContain(params.reason);
-  }
-
-  describe("when no restrictions are configured", () => {
-    it("allows messages that mention the bot (default requireMention)", () => {
-      const result = runAccessCheck({
-        message: {
-          message: "@testbot hello",
-        },
-      });
-      expect(result.allowed).toBe(true);
-    });
-  });
-
-  describe("requireMention default", () => {
-    it("defaults to true when undefined", () => {
-      const result = runAccessCheck({
-        message: {
-          message: "hello bot",
-        },
-      });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("does not mention the bot");
-    });
-
-    it("allows mention when requireMention is undefined", () => {
-      const result = runAccessCheck({
-        message: {
-          message: "@testbot hello",
-        },
-      });
-      expect(result.allowed).toBe(true);
-    });
-  });
-
-  describe("requireMention", () => {
-    it("allows messages that mention the bot", () => {
-      const result = runAccessCheck({
-        account: { requireMention: true },
-        message: { message: "@testbot hello" },
-      });
-      expect(result.allowed).toBe(true);
-    });
-
-    it("blocks messages that don't mention the bot", () => {
-      const result = runAccessCheck({
-        account: { requireMention: true },
-      });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("does not mention the bot");
-    });
-
-    it("is case-insensitive for bot username", () => {
-      const result = runAccessCheck({
-        account: { requireMention: true },
-        message: { message: "@TestBot hello" },
-      });
-      expect(result.allowed).toBe(true);
-    });
-  });
-
-  describe("allowFrom allowlist", () => {
-    it("allows users in the allowlist", () => {
-      const result = expectAllowedAccessCheck({
-        account: {
-          allowFrom: ["123456", "789012"],
-        },
-      });
-      expect(result.matchKey).toBe("123456");
-      expect(result.matchSource).toBe("allowlist");
-    });
-
-    it("blocks users not in allowlist when allowFrom is set", () => {
-      expectAllowFromBlocked({
-        allowFrom: ["789012"],
-        reason: "allowFrom",
-      });
-    });
-
-    it("blocks everyone when allowFrom is explicitly empty", () => {
-      expectAllowFromBlocked({
-        allowFrom: [],
-        reason: "allowFrom",
-      });
-    });
-
-    it("blocks messages without userId", () => {
-      expectAllowFromBlocked({
-        allowFrom: ["123456"],
-        message: { userId: undefined },
-        reason: "user ID not available",
-      });
-    });
-
-    it("bypasses role checks when user is in allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowFrom: ["123456"],
-        allowedRoles: ["owner"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isOwner: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
-      });
-      expect(result.allowed).toBe(true);
-    });
-
-    it("blocks user with role when not in allowlist", () => {
-      expectAllowFromBlocked({
-        allowFrom: ["789012"],
-        allowedRoles: ["moderator"],
-        message: { userId: "123456", isMod: true },
-        reason: "allowFrom",
-      });
-    });
-
-    it("blocks user not in allowlist even when roles configured", () => {
-      expectAllowFromBlocked({
-        allowFrom: ["789012"],
-        allowedRoles: ["moderator"],
-        message: { userId: "123456", isMod: false },
-        reason: "allowFrom",
-      });
-    });
-  });
-
-  describe("allowedRoles", () => {
-    it("allows users with matching role", () => {
-      const result = expectSingleRoleAllowed({
-        role: "moderator",
-        message: { isMod: true },
-      });
-      expect(result.matchSource).toBe("role");
-    });
-
-    it("allows users with any of multiple roles", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator", "vip", "subscriber"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isVip: true,
-        isMod: false,
-        isSub: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
-      });
-      expect(result.allowed).toBe(true);
-    });
-
-    it("blocks users without matching role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isMod: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
-      });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("does not have any of the required roles");
-    });
-
-    it("allows all users when role is 'all'", () => {
-      const result = expectAllowedAccessCheck({
-        account: {
-          allowedRoles: ["all"],
-        },
-      });
-      expect(result.matchKey).toBe("all");
-    });
-
-    it("handles moderator role", () => {
-      expectSingleRoleAllowed({
-        role: "moderator",
-        message: { isMod: true },
-      });
-    });
-
-    it("handles subscriber role", () => {
-      expectSingleRoleAllowed({
-        role: "subscriber",
-        message: { isSub: true },
-      });
-    });
-
-    it("handles owner role", () => {
-      expectSingleRoleAllowed({
-        role: "owner",
-        message: { isOwner: true },
-      });
-    });
-
-    it("handles vip role", () => {
-      expectSingleRoleAllowed({
-        role: "vip",
-        message: { isVip: true },
-      });
-    });
-  });
-
-  describe("combined restrictions", () => {
-    it("checks requireMention before allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-        allowFrom: ["123456"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "hello", // No mention
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
-      });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("does not mention the bot");
-    });
-
-    it("checks allowlist before allowedRoles", () => {
-      const result = runAccessCheck({
-        account: {
-          allowFrom: ["123456"],
-          allowedRoles: ["owner"],
-        },
-        message: {
-          message: "@testbot hello",
-          isOwner: false,
-        },
-      });
-      expect(result.allowed).toBe(true);
-      expect(result.matchSource).toBe("allowlist");
-    });
-  });
-});
-
-describe("extractMentions", () => {
-  it("extracts single mention", () => {
-    const mentions = extractMentions("hello @testbot");
-    expect(mentions).toEqual(["testbot"]);
-  });
-
-  it("extracts multiple mentions", () => {
-    const mentions = extractMentions("hello @testbot and @otheruser");
-    expect(mentions).toEqual(["testbot", "otheruser"]);
-  });
-
-  it("returns empty array when no mentions", () => {
-    const mentions = extractMentions("hello everyone");
-    expect(mentions).toEqual([]);
-  });
-
-  it("handles mentions at start of message", () => {
-    const mentions = extractMentions("@testbot hello");
-    expect(mentions).toEqual(["testbot"]);
-  });
-
-  it("handles mentions at end of message", () => {
-    const mentions = extractMentions("hello @testbot");
-    expect(mentions).toEqual(["testbot"]);
-  });
-
-  it("converts mentions to lowercase", () => {
-    const mentions = extractMentions("hello @TestBot");
-    expect(mentions).toEqual(["testbot"]);
-  });
-
-  it("extracts alphanumeric usernames", () => {
-    const mentions = extractMentions("hello @user123");
-    expect(mentions).toEqual(["user123"]);
-  });
-
-  it("handles underscores in usernames", () => {
-    const mentions = extractMentions("hello @test_user");
-    expect(mentions).toEqual(["test_user"]);
-  });
-
-  it("handles empty string", () => {
-    const mentions = extractMentions("");
-    expect(mentions).toEqual([]);
-  });
-});

package/src/access-control.ts

@@ -1,173 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
-import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
-
-/**
- * Result of checking access control for a Twitch message
- */
-type TwitchAccessControlResult = {
-  allowed: boolean;
-  reason?: string;
-  matchKey?: string;
-  matchSource?: string;
-};
-
-/**
- * Check if a Twitch message should be allowed based on account configuration
- *
- * This function implements the access control logic for incoming Twitch messages,
- * checking allowlists, role-based restrictions, and mention requirements.
- *
- * Priority order:
- * 1. If `requireMention` is true, message must mention the bot
- * 2. If `allowFrom` is set, sender must be in the allowlist (by user ID)
- * 3. If `allowedRoles` is set (and `allowFrom` is not), sender must have at least one role
- *
- * Note: `allowFrom` is a hard allowlist. When set, only those user IDs are allowed.
- * Use `allowedRoles` as an alternative when you don't want to maintain an allowlist.
- *
- * Available roles:
- * - "moderator": Moderators
- * - "owner": Channel owner/broadcaster
- * - "vip": VIPs
- * - "subscriber": Subscribers
- * - "all": Anyone in the chat
- */
-export function checkTwitchAccessControl(params: {
-  message: TwitchChatMessage;
-  account: TwitchAccountConfig;
-  botUsername: string;
-}): TwitchAccessControlResult {
-  const { message, account, botUsername } = params;
-
-  if (account.requireMention ?? true) {
-    const mentions = extractMentions(message.message);
-    if (!mentions.includes(normalizeLowercaseStringOrEmpty(botUsername))) {
-      return {
-        allowed: false,
-        reason: "message does not mention the bot (requireMention is enabled)",
-      };
-    }
-  }
-
-  if (account.allowFrom !== undefined) {
-    const allowFrom = account.allowFrom;
-    if (allowFrom.length === 0) {
-      return {
-        allowed: false,
-        reason: "sender is not in allowFrom allowlist",
-      };
-    }
-    const senderId = message.userId;
-
-    if (!senderId) {
-      return {
-        allowed: false,
-        reason: "sender user ID not available for allowlist check",
-      };
-    }
-
-    if (allowFrom.includes(senderId)) {
-      return {
-        allowed: true,
-        matchKey: senderId,
-        matchSource: "allowlist",
-      };
-    }
-
-    return {
-      allowed: false,
-      reason: "sender is not in allowFrom allowlist",
-    };
-  }
-
-  if (account.allowedRoles && account.allowedRoles.length > 0) {
-    const allowedRoles = account.allowedRoles;
-
-    // "all" grants access to everyone
-    if (allowedRoles.includes("all")) {
-      return {
-        allowed: true,
-        matchKey: "all",
-        matchSource: "role",
-      };
-    }
-
-    const hasAllowedRole = checkSenderRoles({
-      message,
-      allowedRoles,
-    });
-
-    if (!hasAllowedRole) {
-      return {
-        allowed: false,
-        reason: `sender does not have any of the required roles: ${allowedRoles.join(", ")}`,
-      };
-    }
-
-    return {
-      allowed: true,
-      matchKey: allowedRoles.join(","),
-      matchSource: "role",
-    };
-  }
-
-  return {
-    allowed: true,
-  };
-}
-
-/**
- * Check if the sender has any of the allowed roles
- */
-function checkSenderRoles(params: { message: TwitchChatMessage; allowedRoles: string[] }): boolean {
-  const { message, allowedRoles } = params;
-  const { isMod, isOwner, isVip, isSub } = message;
-
-  for (const role of allowedRoles) {
-    switch (role) {
-      case "moderator":
-        if (isMod) {
-          return true;
-        }
-        break;
-      case "owner":
-        if (isOwner) {
-          return true;
-        }
-        break;
-      case "vip":
-        if (isVip) {
-          return true;
-        }
-        break;
-      case "subscriber":
-        if (isSub) {
-          return true;
-        }
-        break;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Extract @mentions from a Twitch chat message
- *
- * Returns a list of lowercase usernames that were mentioned in the message.
- * Twitch mentions are in the format @username.
- */
-export function extractMentions(message: string): string[] {
-  const mentionRegex = /@(\w+)/g;
-  const mentions: string[] = [];
-  let match: RegExpExecArray | null;
-
-  while ((match = mentionRegex.exec(message)) !== null) {
-    const username = match[1];
-    if (username) {
-      mentions.push(normalizeLowercaseStringOrEmpty(username));
-    }
-  }
-
-  return mentions;
-}

package/src/actions.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-import { twitchMessageActions } from "./actions.js";
-import type { ResolvedTwitchAccountContext } from "./config.js";
-import { resolveTwitchAccountContext } from "./config.js";
-import { twitchOutbound } from "./outbound.js";
-
-vi.mock("./config.js", () => ({
-  DEFAULT_ACCOUNT_ID: "default",
-  resolveTwitchAccountContext: vi.fn(),
-}));
-
-vi.mock("./outbound.js", () => ({
-  twitchOutbound: {
-    sendText: vi.fn(),
-  },
-}));
-
-function createSecondaryAccountContext(accountId = "secondary"): ResolvedTwitchAccountContext {
-  return {
-    accountId,
-    account: {
-      channel: "secondary-channel",
-      username: "secondary",
-      accessToken: "oauth:secondary-token",
-      clientId: "secondary-client",
-      enabled: true,
-    },
-    tokenResolution: { source: "config", token: "oauth:secondary-token" },
-    configured: true,
-    availableAccountIds: ["default", "secondary"],
-  };
-}
-
-describe("twitchMessageActions", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("uses configured defaultAccount when action accountId is omitted", async () => {
-    vi.mocked(resolveTwitchAccountContext)
-      .mockImplementationOnce(() => createSecondaryAccountContext())
-      .mockImplementation((_cfg, accountId) =>
-        createSecondaryAccountContext(accountId?.trim() || "secondary"),
-      );
-    const sendText = twitchOutbound.sendText;
-    if (!sendText) {
-      throw new Error("twitchOutbound.sendText is unavailable");
-    }
-    vi.mocked(sendText).mockResolvedValue({
-      channel: "twitch",
-      messageId: "msg-1",
-      timestamp: 1,
-    });
-
-    await twitchMessageActions.handleAction!({
-      action: "send",
-      params: { message: "Hello!" },
-      cfg: {
-        channels: {
-          twitch: {
-            defaultAccount: "secondary",
-          },
-        },
-      },
-    } as never);
-
-    expect(twitchOutbound.sendText).toHaveBeenCalledWith(
-      expect.objectContaining({
-        accountId: "secondary",
-        to: "secondary-channel",
-      }),
-    );
-  });
-});