@elizaos/plugin-twitch 2.0.0-alpha.8 → 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @elizaos/plugin-twitch
+
+Twitch chat integration for elizaOS agents. Connects to one or more Twitch
+channels over IRC (via [@twurple](https://twurple.js.org)), receives chat
+messages with role-based filtering and optional @mention gating, and sends
+replies. Outbound send/join/leave operations route through the runtime
+`MESSAGE` action via a registered `MessageConnector` — this plugin registers no
+actions or providers of its own.
+
+Node-only (`"runtime": "node"` in package.json). Not compatible with browser or
+mobile runtimes.
+
+## Install
+
+```bash
+bun add @elizaos/plugin-twitch
+```
+
+Add the plugin name to a character's `plugins` array, or rely on auto-enable: a
+`twitch` connector block under agent config activates the plugin automatically
+unless `enabled: false` is set.
+
+```ts
+import type { Character } from "@elizaos/core";
+
+const character: Character = {
+  name: "my-agent",
+  plugins: ["@elizaos/plugin-twitch"],
+};
+```
+
+## Prerequisites
+
+1. A Twitch application registered at the
+   [Twitch Developer Console](https://dev.twitch.tv/console) (provides the
+   client ID, and a client secret if you want token refresh).
+2. An OAuth access token with `chat:read` and `chat:edit` scopes.
+
+## Configuration
+
+Settings resolve in priority order: a per-account object in `TWITCH_ACCOUNTS`
+JSON > `character.settings.twitch` > top-level env vars (default account only).
+See `src/accounts.ts` (`resolveTwitchAccountSettings`).
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `TWITCH_USERNAME` | Bot's Twitch login name |
+| `TWITCH_CLIENT_ID` | Application client ID |
+| `TWITCH_ACCESS_TOKEN` | OAuth token (`oauth:` prefix stripped automatically) |
+| `TWITCH_CHANNEL` | Primary channel to join (no `#` prefix) |
+
+### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TWITCH_CLIENT_SECRET` | Enables `RefreshingAuthProvider`; without it a `StaticAuthProvider` is used | - |
+| `TWITCH_REFRESH_TOKEN` | Passed to `RefreshingAuthProvider` when the client secret is also set | - |
+| `TWITCH_CHANNELS` | Comma-separated additional channels to join at startup | - |
+| `TWITCH_REQUIRE_MENTION` | `"true"` only processes messages that @mention the bot | `false` |
+| `TWITCH_ALLOWED_ROLES` | Comma-separated: `all`, `owner`, `moderator`, `vip`, `subscriber` | `all` |
+| `TWITCH_ACCOUNTS` | JSON array/object for multi-account mode | - |
+| `TWITCH_ACCOUNT_ID` / `TWITCH_DEFAULT_ACCOUNT_ID` | Select the default account when several are configured | - |
+
+The same settings can live under `character.settings.twitch` as camelCase
+fields (`username`, `clientId`, `accessToken`, `channel`, `additionalChannels`,
+`requireMention`, `allowedRoles`, `allowedUserIds`), with a nested `accounts`
+map for multi-account configs.
+
+## Messaging operations
+
+Twitch chat operations route through the canonical `MESSAGE` action with
+`source: "twitch"`. The connector exposes these operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `send` | Send a message to a Twitch channel |
+| `join` | Join a Twitch channel |
+| `leave` | Leave a Twitch channel (the primary channel cannot be left) |
+| `list_channels` | List the configured/joined Twitch channels |
+
+Messages over 500 characters are split at sentence/word boundaries with a 300 ms
+delay between chunks (`splitMessageForTwitch`). LLM markdown is converted to
+plain text before sending (`stripMarkdownForTwitch`); Twitch does not render
+markdown.
+
+## Events
+
+`TwitchService` emits these runtime events (string constants on
+`TwitchEventTypes`):
+
+| Constant | String value |
+|----------|--------------|
+| `MESSAGE_RECEIVED` | `TWITCH_MESSAGE_RECEIVED` |
+| `MESSAGE_SENT` | `TWITCH_MESSAGE_SENT` |
+| `JOIN_CHANNEL` | `TWITCH_JOIN_CHANNEL` |
+| `LEAVE_CHANNEL` | `TWITCH_LEAVE_CHANNEL` |
+| `CONNECTION_READY` | `TWITCH_CONNECTION_READY` |
+| `CONNECTION_LOST` | `TWITCH_CONNECTION_LOST` |
+
+## Source layout
+
+```
+src/
+  index.ts                        Plugin entry (default export)
+  service.ts                      TwitchService — IRC lifecycle, connector handlers
+  accounts.ts                     Multi-account config resolution
+  connector-account-provider.ts   ConnectorAccountProvider adapter
+  workflow-credential-provider.ts TwitchWorkflowCredentialProvider service
+  types.ts                        Interfaces, enums, constants, utils, errors
+auto-enable.ts                    Lightweight shouldEnable() for the auto-enable engine
+```
+
+## Commands
+
+```bash
+bun run --cwd plugins/plugin-twitch build         # compile dist/
+bun run --cwd plugins/plugin-twitch test          # bun test
+bun run --cwd plugins/plugin-twitch format        # biome format --write
+bun run --cwd plugins/plugin-twitch format:check  # biome format (check only)
+```
+
+## License
+
+MIT

package/auto-enable.ts

@@ -0,0 +1,21 @@
+// Auto-enable check for @elizaos/plugin-twitch.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+/** Enable when a `twitch` connector block is present and not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)
+    ?.twitch;
+  if (!c || typeof c !== "object") return false;
+  const config = c as Record<string, unknown>;
+  if (config.enabled === false) return false;
+  // The full per-connector field check (clientId/oauth token/channel) lives
+  // in the central engine's isConnectorConfigured. We delegate to a simple
+  // "block present + not explicitly disabled" check here; the central
+  // engine's stricter check remains as a fallback during migration.
+  return true;
+}

package/package.json

@@ -1,19 +1,45 @@
 {
   "name": "@elizaos/plugin-twitch",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.3-beta.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "auto-enable.ts"
   ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "messaging",
+        "live-streaming"
+      ]
+    }
+  },
   "scripts": {
     "build": "bun run build.ts",
     "test": "bun test",
@@ -24,19 +50,18 @@
     "typecheck": "echo \"Typecheck skipped for release\""
   },
   "dependencies": {
-    "@twurple/auth": "^7.2.0",
-    "@twurple/chat": "^7.2.0",
-    "zod": "^4.3.6"
+    "@twurple/auth": "^8.0.0",
+    "@twurple/chat": "^8.0.0"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-alpha.3"
+    "@elizaos/core": "2.0.3-beta.2"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
     "@types/bun": "^1.1.0",
-    "typescript": "^5.3.0",
-    "@biomejs/biome": "^2.3.11"
+    "typescript": "^6.0.3"
   },
-  "milady": {
+  "eliza": {
     "platforms": [
       "node"
     ],
@@ -105,5 +130,6 @@
         "sensitive": false
       }
     }
-  }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
 }

package/dist/actions/joinChannel.d.ts

@@ -1,6 +0,0 @@
-/**
- * Join channel action for Twitch plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const joinChannel: Action;
-//# sourceMappingURL=joinChannel.d.ts.map

package/dist/actions/joinChannel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"joinChannel.d.ts","sourceRoot":"","sources":["../../src/actions/joinChannel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAKP,MAAM,eAAe,CAAC;AAyBvB,eAAO,MAAM,WAAW,EAAE,MA+IzB,CAAC"}

package/dist/actions/leaveChannel.d.ts

@@ -1,6 +0,0 @@
-/**
- * Leave channel action for Twitch plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const leaveChannel: Action;
-//# sourceMappingURL=leaveChannel.d.ts.map

package/dist/actions/leaveChannel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"leaveChannel.d.ts","sourceRoot":"","sources":["../../src/actions/leaveChannel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAKP,MAAM,eAAe,CAAC;AA2BvB,eAAO,MAAM,YAAY,EAAE,MAsK1B,CAAC"}

package/dist/actions/listChannels.d.ts

@@ -1,6 +0,0 @@
-/**
- * List channels action for Twitch plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const listChannels: Action;
-//# sourceMappingURL=listChannels.d.ts.map

package/dist/actions/listChannels.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listChannels.d.ts","sourceRoot":"","sources":["../../src/actions/listChannels.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAKP,MAAM,eAAe,CAAC;AAIvB,eAAO,MAAM,YAAY,EAAE,MAqH1B,CAAC"}

package/dist/actions/sendMessage.d.ts

@@ -1,6 +0,0 @@
-/**
- * Send message action for Twitch plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const sendMessage: Action;
-//# sourceMappingURL=sendMessage.d.ts.map

package/dist/actions/sendMessage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sendMessage.d.ts","sourceRoot":"","sources":["../../src/actions/sendMessage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAKP,MAAM,eAAe,CAAC;AAiCvB,eAAO,MAAM,WAAW,EAAE,MAqKzB,CAAC"}

package/dist/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * Twitch chat integration plugin for ElizaOS.
- *
- * This plugin provides Twitch chat integration using the @twurple library.
- */
-import type { Plugin } from "@elizaos/core";
-export { TwitchService } from "./service.js";
-export * from "./types.js";
-import { joinChannel } from "./actions/joinChannel.js";
-import { leaveChannel } from "./actions/leaveChannel.js";
-import { listChannels } from "./actions/listChannels.js";
-import { sendMessage } from "./actions/sendMessage.js";
-export { sendMessage, joinChannel, leaveChannel, listChannels };
-import { channelStateProvider } from "./providers/channelState.js";
-import { userContextProvider } from "./providers/userContext.js";
-export { channelStateProvider, userContextProvider };
-/**
- * Twitch plugin definition.
- */
-declare const twitchPlugin: Plugin;
-export default twitchPlugin;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,eAAe,CAAC;AAI3D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,cAAc,YAAY,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAGhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;AAKrD;;GAEG;AACH,QAAA,MAAM,YAAY,EAAE,MA+EnB,CAAC;AAEF,eAAe,YAAY,CAAC"}