@openclaw/twitch 2026.2.21 → 2026.5.1-beta.1

package/README.md

@@ -5,7 +5,7 @@ Twitch channel plugin for OpenClaw.
 ## Install (local checkout)
 
 ```bash
-openclaw plugins install ./extensions/twitch
+openclaw plugins install ./path/to/local/twitch-plugin
 ```
 
 ## Install (npm)
@@ -31,7 +31,7 @@ Minimal config (simplified single-account):
       accessToken: "oauth:abc123...", // OAuth Access Token (add oauth: prefix)
       clientId: "xyz789...", // Client ID from Token Generator
       channel: "vevisk", // Channel to join (required)
-      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only (Convert your twitch username to ID at https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/)
+      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only (Convert your twitch username to ID at https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
     },
   },
 }

package/api.ts

@@ -0,0 +1,21 @@
+export {
+  type ChannelAccountSnapshot,
+  type ChannelCapabilities,
+  type ChannelGatewayContext,
+  type ChannelLogSink,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionContext,
+  type ChannelMeta,
+  type ChannelOutboundAdapter,
+  type ChannelOutboundContext,
+  type ChannelPlugin,
+  type ChannelResolveKind,
+  type ChannelResolveResult,
+  type ChannelStatusAdapter,
+  type OpenClawConfig,
+  type OutboundDeliveryResult,
+  type RuntimeEnv,
+  type WizardPrompter,
+} from "./runtime-api.js";
+export { twitchPlugin } from "./src/plugin.js";
+export { setTwitchRuntime } from "./src/runtime.js";

package/channel-plugin-api.ts

@@ -0,0 +1 @@
+export { twitchPlugin } from "./src/plugin.js";

package/index.test.ts

@@ -0,0 +1,13 @@
+import { assertBundledChannelEntries } from "openclaw/plugin-sdk/channel-test-helpers";
+import { describe } from "vitest";
+import entry from "./index.js";
+import setupEntry from "./setup-entry.js";
+
+describe("twitch bundled entries", () => {
+  assertBundledChannelEntries({
+    entry,
+    expectedId: "twitch",
+    expectedName: "Twitch",
+    setupEntry,
+  });
+});

package/index.ts

@@ -1,20 +1,16 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-import { twitchPlugin } from "./src/plugin.js";
-import { setTwitchRuntime } from "./src/runtime.js";
+import { defineBundledChannelEntry } from "openclaw/plugin-sdk/channel-entry-contract";
 
-export { monitorTwitchProvider } from "./src/monitor.js";
-
-const plugin = {
+export default defineBundledChannelEntry({
   id: "twitch",
   name: "Twitch",
-  description: "Twitch channel plugin",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: OpenClawPluginApi) {
-    setTwitchRuntime(api.runtime);
-    // oxlint-disable-next-line typescript/no-explicit-any
-    api.registerChannel({ plugin: twitchPlugin as any });
+  description: "Twitch IRC chat channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "twitchPlugin",
   },
-};
-
-export default plugin;
+  runtime: {
+    specifier: "./api.js",
+    exportName: "setTwitchRuntime",
+  },
+});

package/openclaw.plugin.json

@@ -1,6 +1,12 @@
 {
   "id": "twitch",
+  "activation": {
+    "onStartup": false
+  },
   "channels": ["twitch"],
+  "channelEnvVars": {
+    "twitch": ["OPENCLAW_TWITCH_ACCESS_TOKEN"]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,20 +1,42 @@
 {
   "name": "@openclaw/twitch",
-  "version": "2026.2.21",
+  "version": "2026.5.1-beta.1",
   "description": "OpenClaw Twitch channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
   "type": "module",
   "dependencies": {
-    "@twurple/api": "^8.0.3",
-    "@twurple/auth": "^8.0.3",
-    "@twurple/chat": "^8.0.3",
-    "zod": "^4.3.6"
+    "@twurple/api": "^8.1.3",
+    "@twurple/auth": "^8.1.3",
+    "@twurple/chat": "^8.1.3"
   },
   "devDependencies": {
-    "openclaw": "workspace:*"
+    "@openclaw/plugin-sdk": "workspace:*"
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "install": {
+      "npmSpec": "@openclaw/twitch",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "channel": {
+      "id": "twitch",
+      "label": "Twitch",
+      "selectionLabel": "Twitch (Chat)",
+      "docsPath": "/channels/twitch",
+      "blurb": "Twitch chat integration",
+      "aliases": [
+        "twitch-chat"
+      ]
+    },
+    "release": {
+      "publishToNpm": true
+    }
   }
 }

package/runtime-api.ts

@@ -0,0 +1,22 @@
+// Private runtime barrel for the bundled Twitch extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export type {
+  ChannelAccountSnapshot,
+  ChannelCapabilities,
+  ChannelGatewayContext,
+  ChannelLogSink,
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelMeta,
+  ChannelOutboundAdapter,
+  ChannelOutboundContext,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  ChannelStatusAdapter,
+} from "openclaw/plugin-sdk/channel-contract";
+export type { ChannelPlugin } from "openclaw/plugin-sdk/channel-core";
+export type { OutboundDeliveryResult } from "openclaw/plugin-sdk/channel-send-result";
+export type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+export type { RuntimeEnv } from "openclaw/plugin-sdk/runtime";
+export type { WizardPrompter } from "openclaw/plugin-sdk/setup";

package/setup-entry.ts

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,3 @@
+// 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

@@ -17,16 +17,79 @@ describe("checkTwitchAccessControl", () => {
     channel: "testchannel",
   };
 
-  describe("when no restrictions are configured", () => {
-    it("allows messages that mention the bot (default requireMention)", () => {
-      const message: TwitchChatMessage = {
+  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",
-      };
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+        ...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);
     });
@@ -34,30 +97,20 @@ describe("checkTwitchAccessControl", () => {
 
   describe("requireMention default", () => {
     it("defaults to true when undefined", () => {
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "hello bot",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+      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 message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        message: {
+          message: "@testbot hello",
+        },
       });
       expect(result.allowed).toBe(true);
     });
@@ -65,52 +118,25 @@ describe("checkTwitchAccessControl", () => {
 
   describe("requireMention", () => {
     it("allows messages that mention the bot", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      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 account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message: mockMessage,
-        account,
-        botUsername: "testbot",
+      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 account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@TestBot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: { requireMention: true },
+        message: { message: "@TestBot hello" },
       });
       expect(result.allowed).toBe(true);
     });
@@ -118,62 +144,35 @@ describe("checkTwitchAccessControl", () => {
 
   describe("allowFrom allowlist", () => {
     it("allows users in the allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowFrom: ["123456", "789012"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectAllowedAccessCheck({
+        account: {
+          allowFrom: ["123456", "789012"],
+        },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchKey).toBe("123456");
       expect(result.matchSource).toBe("allowlist");
     });
 
     it("blocks users not in allowlist when allowFrom is set", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
+        reason: "allowFrom",
+      });
+    });
 
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+    it("blocks everyone when allowFrom is explicitly empty", () => {
+      expectAllowFromBlocked({
+        allowFrom: [],
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
 
     it("blocks messages without userId", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["123456"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: undefined,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: undefined },
+        reason: "user ID not available",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("user ID not available");
     });
 
     it("bypasses role checks when user is in allowlist", () => {
@@ -197,68 +196,30 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("blocks user with role when not in allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
         allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: "123456",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: "123456", isMod: true },
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
 
     it("blocks user not in allowlist even when roles configured", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
         allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: "123456",
-        isMod: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: "123456", isMod: false },
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
   });
 
   describe("allowedRoles", () => {
     it("allows users with matching role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectSingleRoleAllowed({
+        role: "moderator",
+        message: { isMod: true },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchSource).toBe("role");
     });
 
@@ -304,98 +265,40 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("allows all users when role is 'all'", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["all"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectAllowedAccessCheck({
+        account: {
+          allowedRoles: ["all"],
+        },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchKey).toBe("all");
     });
 
     it("handles moderator role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "moderator",
+        message: { isMod: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles subscriber role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["subscriber"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isSub: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "subscriber",
+        message: { isSub: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles owner role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["owner"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isOwner: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "owner",
+        message: { isOwner: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles vip role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["vip"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isVip: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "vip",
+        message: { isVip: true },
       });
-      expect(result.allowed).toBe(true);
     });
   });
 
@@ -421,21 +324,15 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("checks allowlist before allowedRoles", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowFrom: ["123456"],
-        allowedRoles: ["owner"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isOwner: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: {
+          allowFrom: ["123456"],
+          allowedRoles: ["owner"],
+        },
+        message: {
+          message: "@testbot hello",
+          isOwner: false,
+        },
       });
       expect(result.allowed).toBe(true);
       expect(result.matchSource).toBe("allowlist");