@gakr-gakr/twitch 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @gakr-gakr/twitch
+
+Twitch channel plugin for AutoBot.
+
+## Install (local checkout)
+
+```bash
+autobot plugins install ./path/to/local/twitch-plugin
+```
+
+## Install (npm)
+
+```bash
+autobot plugins install @gakr-gakr/twitch
+```
+
+Onboarding: select Twitch and confirm the install prompt to fetch the plugin automatically.
+
+## Config
+
+Minimal config (simplified single-account):
+
+**⚠️ Important:** `requireMention` defaults to `true`. Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot.
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      username: "autobot",
+      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-to-user-id/)
+    },
+  },
+}
+```
+
+**Access control options:**
+
+- `requireMention: false` - Disable the default mention requirement to respond to all messages
+- `allowFrom: ["your_user_id"]` - Restrict to your Twitch user ID only (find your ID at https://www.twitchangles.com/xqc or similar)
+- `allowedRoles: ["moderator", "vip", "subscriber"]` - Restrict to specific roles
+
+Multi-account config (advanced):
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      accounts: {
+        default: {
+          username: "autobot",
+          accessToken: "oauth:abc123...",
+          clientId: "xyz789...",
+          channel: "vevisk",
+        },
+        channel2: {
+          username: "autobot",
+          accessToken: "oauth:def456...",
+          clientId: "uvw012...",
+          channel: "secondchannel",
+        },
+      },
+    },
+  },
+}
+```
+
+## Setup
+
+1. Create a dedicated Twitch account for the bot, then generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
+   - Select **Bot Token**
+   - Verify scopes `chat:read` and `chat:write` are selected
+   - Copy the **Access Token** to `token` property
+   - Copy the **Client ID** to `clientId` property
+2. Start the gateway
+
+## Full documentation
+
+See https://docs.openclaw.ai/channels/twitch for:
+
+- Token refresh setup
+- Access control patterns
+- Multi-account configuration
+- Troubleshooting
+- Capabilities & limits

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 AutoBotConfig,
+  type OutboundDeliveryResult,
+  type RuntimeEnv,
+  type WizardPrompter,
+} from "./runtime-api.js";
+export { twitchPlugin } from "./src/plugin.js";
+export { setTwitchRuntime } from "./src/runtime.js";

package/autobot.plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "twitch",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["twitch"],
+  "channelEnvVars": {
+    "twitch": ["AUTOBOT_TWITCH_ACCESS_TOKEN"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-plugin-api.ts

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

package/index.ts

@@ -0,0 +1,16 @@
+import { defineBundledChannelEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "twitch",
+  name: "Twitch",
+  description: "Twitch IRC chat channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "twitchPlugin",
+  },
+  runtime: {
+    specifier: "./api.js",
+    exportName: "setTwitchRuntime",
+  },
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gakr-gakr/twitch",
+  "version": "0.1.0",
+  "description": "AutoBot Twitch channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "@twurple/api": "8.1.4",
+    "@twurple/auth": "8.1.4",
+    "@twurple/chat": "8.1.4",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*"
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "install": {
+      "npmSpec": "@gakr-gakr/twitch",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "channel": {
+      "id": "twitch",
+      "label": "Twitch",
+      "selectionLabel": "Twitch (Chat)",
+      "docsPath": "/channels/twitch",
+      "blurb": "Twitch chat integration",
+      "aliases": [
+        "twitch-chat"
+      ]
+    },
+    "release": {
+      "publishToClawHub": true,
+      "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 "autobot/plugin-sdk/channel-contract";
+export type { ChannelPlugin } from "autobot/plugin-sdk/channel-core";
+export type { OutboundDeliveryResult } from "autobot/plugin-sdk/channel-send-result";
+export type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export type { WizardPrompter } from "autobot/plugin-sdk/setup";

package/setup-entry.ts

@@ -0,0 +1,9 @@
+import { defineBundledChannelSetupEntry } from "autobot/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.ts

@@ -0,0 +1,195 @@
+import {
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+  type ChannelIngressIdentitySubjectInput,
+  type IngressReasonCode,
+} from "autobot/plugin-sdk/channel-ingress-runtime";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+
+type TwitchAccessControlResult = {
+  allowed: boolean;
+  reason?: string;
+  matchKey?: string;
+  matchSource?: string;
+};
+
+type TwitchPolicyKind = "open" | "allowFrom" | "role";
+
+const twitchUserIdentity = defineStableChannelIngressIdentity({
+  key: "sender-id",
+  entryIdPrefix: "twitch-user-entry",
+});
+
+const twitchRoleIdentity = defineStableChannelIngressIdentity({
+  key: "role-moderator",
+  kind: "role",
+  normalizeEntry: normalizeTwitchRole,
+  normalizeSubject: normalizeTwitchRole,
+  aliases: ["owner", "vip", "subscriber"].map((role) => ({
+    key: `role-${role}`,
+    kind: "role",
+    normalizeEntry: () => null,
+    normalizeSubject: normalizeTwitchRole,
+  })),
+  isWildcardEntry: (entry) => normalizeTwitchRole(entry) === "all",
+  resolveEntryId: ({ entryIndex }) => `twitch-role-entry-${entryIndex + 1}`,
+});
+
+export async function checkTwitchAccessControl(params: {
+  message: TwitchChatMessage;
+  account: TwitchAccountConfig;
+  botUsername: string;
+}): Promise<TwitchAccessControlResult> {
+  const { message, account, botUsername } = params;
+  const policyKind = resolveTwitchPolicyKind(account);
+  const resolved = await createChannelIngressResolver({
+    channelId: "twitch",
+    accountId: "default",
+    identity: policyKind === "role" ? twitchRoleIdentity : twitchUserIdentity,
+  }).message({
+    subject:
+      policyKind === "role"
+        ? twitchRoleSubject(message)
+        : ({ stableId: message.userId } satisfies ChannelIngressIdentitySubjectInput),
+    conversation: {
+      kind: "group",
+      id: message.channel,
+    },
+    event: { mayPair: false },
+    mentionFacts: {
+      canDetectMention: true,
+      wasMentioned: mentionsBot(message.message, botUsername),
+    },
+    dmPolicy: "open",
+    groupPolicy: policyKind === "open" ? "open" : "allowlist",
+    policy: {
+      activation: {
+        requireMention: account.requireMention ?? true,
+        allowTextCommands: false,
+        order: "before-sender",
+      },
+    },
+    groupAllowFrom:
+      policyKind === "allowFrom"
+        ? account.allowFrom
+        : policyKind === "role"
+          ? account.allowedRoles
+          : undefined,
+  });
+  const decision = resolved.ingress;
+
+  if (decision.decisiveGateId === "activation" && decision.admission !== "dispatch") {
+    return {
+      allowed: false,
+      reason: "message does not mention the bot (requireMention is enabled)",
+    };
+  }
+
+  if (decision.admission === "dispatch") {
+    if (policyKind === "allowFrom") {
+      return {
+        allowed: true,
+        matchKey: params.message.userId,
+        matchSource: "allowlist",
+      };
+    }
+    if (policyKind === "role") {
+      return {
+        allowed: true,
+        matchKey: params.account.allowedRoles?.join(","),
+        matchSource: "role",
+      };
+    }
+    return {
+      allowed: true,
+    };
+  }
+
+  if (policyKind === "allowFrom") {
+    if (!params.message.userId) {
+      return {
+        allowed: false,
+        reason: "sender user ID not available for allowlist check",
+      };
+    }
+    return {
+      allowed: false,
+      reason: "sender is not in allowFrom allowlist",
+    };
+  }
+
+  if (policyKind === "role") {
+    return {
+      allowed: false,
+      reason: `sender does not have any of the required roles: ${params.account.allowedRoles?.join(", ") ?? ""}`,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: reasonForTwitchIngressDecision(decision),
+  };
+}
+
+function resolveTwitchPolicyKind(account: TwitchAccountConfig): TwitchPolicyKind {
+  if (account.allowFrom !== undefined) {
+    return "allowFrom";
+  }
+  if (account.allowedRoles && account.allowedRoles.length > 0) {
+    return "role";
+  }
+  return "open";
+}
+
+function twitchRoleSubject(message: TwitchChatMessage): ChannelIngressIdentitySubjectInput {
+  return {
+    stableId: message.isMod ? "moderator" : undefined,
+    aliases: {
+      "role-owner": message.isOwner ? "owner" : undefined,
+      "role-vip": message.isVip ? "vip" : undefined,
+      "role-subscriber": message.isSub ? "subscriber" : undefined,
+    },
+  };
+}
+
+function normalizeTwitchRole(value: string): string | null {
+  const role = normalizeLowercaseStringOrEmpty(value);
+  if (role === "*") {
+    return "all";
+  }
+  return role === "moderator" ||
+    role === "owner" ||
+    role === "vip" ||
+    role === "subscriber" ||
+    role === "all"
+    ? role
+    : null;
+}
+
+function reasonForTwitchIngressDecision(decision: { reasonCode: IngressReasonCode }): string {
+  switch (decision.reasonCode) {
+    case "activation_skipped":
+      return "message does not mention the bot (requireMention is enabled)";
+    case "group_policy_empty_allowlist":
+    case "group_policy_not_allowlisted":
+      return "sender is not in allowFrom allowlist";
+    default:
+      return decision.reasonCode;
+  }
+}
+
+function mentionsBot(message: string, botUsername: string): boolean {
+  const expected = normalizeLowercaseStringOrEmpty(botUsername);
+  const mentionRegex = /@(\w+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = mentionRegex.exec(message)) !== null) {
+    const username = match[1] ? normalizeLowercaseStringOrEmpty(match[1]) : "";
+    if (username === expected) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/actions.ts

@@ -0,0 +1,175 @@
+/**
+ * Twitch message actions adapter.
+ *
+ * Handles tool-based actions for Twitch, such as sending messages.
+ */
+
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import { resolveTwitchAccountContext } from "./config.js";
+import { twitchOutbound } from "./outbound.js";
+import type { ChannelMessageActionAdapter, ChannelMessageActionContext } from "./types.js";
+
+/**
+ * Create a tool result with error content.
+ */
+function errorResponse(error: string) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ ok: false, error }),
+      },
+    ],
+    details: { ok: false },
+  };
+}
+
+/**
+ * Read a string parameter from action arguments.
+ *
+ * @param args - Action arguments
+ * @param key - Parameter key
+ * @param options - Options for reading the parameter
+ * @returns The parameter value or undefined if not found
+ */
+function readStringParam(
+  args: Record<string, unknown>,
+  key: string,
+  options: { required?: boolean; trim?: boolean } = {},
+): string | undefined {
+  const value = args[key];
+  if (value === undefined || value === null) {
+    if (options.required) {
+      throw new Error(`Missing required parameter: ${key}`);
+    }
+    return undefined;
+  }
+
+  // Convert value to string safely
+  if (typeof value === "string") {
+    return options.trim !== false ? value.trim() : value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    const str = String(value);
+    return options.trim !== false ? str.trim() : str;
+  }
+
+  throw new Error(`Parameter ${key} must be a string, number, or boolean`);
+}
+
+/** Supported Twitch actions */
+const TWITCH_ACTIONS = new Set(["send" as const]);
+type TwitchAction = typeof TWITCH_ACTIONS extends Set<infer U> ? U : never;
+
+/**
+ * Twitch message actions adapter.
+ */
+export const twitchMessageActions: ChannelMessageActionAdapter = {
+  /**
+   * List available actions for this channel.
+   */
+  describeMessageTool: () => ({ actions: [...TWITCH_ACTIONS] }),
+
+  /**
+   * Check if an action is supported.
+   */
+  supportsAction: ({ action }) => TWITCH_ACTIONS.has(action as TwitchAction),
+
+  /**
+   * Extract tool send parameters from action arguments.
+   *
+   * Parses and validates the "to" and "message" parameters for sending.
+   *
+   * @param params - Arguments from the tool call
+   * @returns Parsed send parameters or null if invalid
+   *
+   * @example
+   * const result = twitchMessageActions.extractToolSend!({
+   *   args: { to: "#mychannel", message: "Hello!" }
+   * });
+   * // Returns: { to: "#mychannel", message: "Hello!" }
+   */
+  extractToolSend: ({ args }) => {
+    try {
+      const to = readStringParam(args, "to", { required: true });
+      const message = readStringParam(args, "message", { required: true });
+
+      if (!to || !message) {
+        return null;
+      }
+
+      return { to, message };
+    } catch {
+      return null;
+    }
+  },
+
+  /**
+   * Handle an action execution.
+   *
+   * Processes the "send" action to send messages to Twitch.
+   *
+   * @param ctx - Action context including action type, parameters, and config
+   * @returns Tool result with content or null if action not supported
+   *
+   * @example
+   * const result = await twitchMessageActions.handleAction!({
+   *   action: "send",
+   *   params: { message: "Hello Twitch!", to: "#mychannel" },
+   *   cfg: autobotConfig,
+   *   accountId: "default",
+   * });
+   */
+  handleAction: async (ctx: ChannelMessageActionContext) => {
+    if (ctx.action !== "send") {
+      return {
+        content: [{ type: "text" as const, text: "Unsupported action" }],
+        details: { ok: false, error: "Unsupported action" },
+      };
+    }
+
+    const message = readStringParam(ctx.params, "message", { required: true });
+    const to = readStringParam(ctx.params, "to", { required: false });
+    const accountId = ctx.accountId ?? resolveTwitchAccountContext(ctx.cfg).accountId;
+
+    const { account, availableAccountIds } = resolveTwitchAccountContext(ctx.cfg, accountId);
+    if (!account) {
+      return errorResponse(
+        `Account not found: ${accountId}. Available accounts: ${availableAccountIds.join(", ") || "none"}`,
+      );
+    }
+
+    // Use the channel from account config (or override with `to` parameter)
+    const targetChannel = to || account.channel;
+    if (!targetChannel) {
+      return errorResponse("No channel specified and no default channel in account config");
+    }
+
+    if (!twitchOutbound.sendText) {
+      return errorResponse("sendText not implemented");
+    }
+
+    try {
+      const result = await twitchOutbound.sendText({
+        cfg: ctx.cfg,
+        to: targetChannel,
+        text: message ?? "",
+        accountId,
+      });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result),
+          },
+        ],
+        details: { ok: true },
+      };
+    } catch (error) {
+      const errorMsg = formatErrorMessage(error);
+      return errorResponse(errorMsg);
+    }
+  },
+};