@elizaos/plugin-twitch 2.0.0-beta.1 → 2.0.3-beta.3

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

@@ -1,131 +1,125 @@
 # @elizaos/plugin-twitch
 
-Twitch chat integration plugin for ElizaOS agents.
+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.
 
-## Features
+Node-only (`"runtime": "node"` in package.json). Not compatible with browser or
+mobile runtimes.
 
-- **Real-time Chat**: Connect to Twitch channels and participate in chat
-- **Multi-channel Support**: Join and monitor multiple channels simultaneously
-- **Role-based Access Control**: Filter interactions by user roles (broadcaster, moderator, VIP, subscriber)
-- **Mention Detection**: Optionally only respond when @mentioned
-- **Token Refresh**: Automatic OAuth token refresh (when configured)
-- **Markdown Stripping**: Automatically converts markdown to plain text for Twitch
-
-## Installation
+## Install
 
 ```bash
-npm install @elizaos/plugin-twitch
+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. **Twitch Developer Account**: Register your application at [Twitch Developer Console](https://dev.twitch.tv/console)
-2. **OAuth Token**: Generate a token with `chat:read` and `chat:edit` scopes at [Twitch Token Generator](https://twitchtokengenerator.com/)
+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
 
-Set the following environment variables:
+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 username |
-| `TWITCH_CLIENT_ID` | Application client ID from Twitch Developer Console |
-| `TWITCH_ACCESS_TOKEN` | OAuth access token with chat:read and chat:edit scopes |
-| `TWITCH_CHANNEL` | Primary channel to join (without # prefix) |
+| `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` | Application client secret (for token refresh) | - |
-| `TWITCH_REFRESH_TOKEN` | OAuth refresh token (for automatic refresh) | - |
-| `TWITCH_CHANNELS` | Comma-separated list of additional channels | - |
-| `TWITCH_REQUIRE_MENTION` | Only respond when @mentioned | `false` |
-| `TWITCH_ALLOWED_ROLES` | Comma-separated roles allowed to interact | `all` |
-
-### Allowed Roles
-
-- `all` - Anyone can interact
-- `owner` / `broadcaster` - Channel owner only
-- `moderator` - Moderators
-- `vip` - VIP users
-- `subscriber` - Subscribers
-
-## Usage
+| `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
 
-### Basic Setup
-
-```typescript
-import twitchPlugin from "@elizaos/plugin-twitch";
-
-const agent = new Agent({
-  plugins: [twitchPlugin],
-});
+```
+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
 ```
 
-### Actions
-
-Twitch chat operations route through the canonical `MESSAGE` action using
-`source: "twitch"`.
-
-| Primary action | Operation | Description |
-|----------------|-----------|-------------|
-| `MESSAGE` | `send` | Send a message to a Twitch channel |
-| `MESSAGE` | `join_channel` | Join a Twitch channel |
-| `MESSAGE` | `leave_channel` | Leave a Twitch channel |
-| `MESSAGE` | `list_channels` | List joined Twitch channels |
-
-### Providers
-
-Twitch does not register standalone planner providers. Channel and user context
-is exposed through the Twitch message connector hooks.
-
-### Events
-
-The plugin emits the following events:
-
-| Event | Description |
-|-------|-------------|
-| `TWITCH_MESSAGE_RECEIVED` | A chat message was received |
-| `TWITCH_MESSAGE_SENT` | A message was sent |
-| `TWITCH_JOIN_CHANNEL` | Bot joined a channel |
-| `TWITCH_LEAVE_CHANNEL` | Bot left a channel |
-| `TWITCH_CONNECTION_READY` | Connected to Twitch |
-| `TWITCH_CONNECTION_LOST` | Connection lost |
-
-## Message Limits
-
-- Maximum message length: 500 characters
-- Messages longer than 500 characters are automatically split
-
-## Security Considerations
-
-1. **Token Security**: Never expose your access token in client-side code
-2. **Scope Limitation**: Only request necessary OAuth scopes
-3. **Role Filtering**: Use `TWITCH_ALLOWED_ROLES` to restrict who can interact
-4. **Mention Requirement**: Enable `TWITCH_REQUIRE_MENTION` in busy channels
-
-## Troubleshooting
-
-### Connection Issues
-
-1. Verify your OAuth token is valid and not expired
-2. Check that the username matches the token owner
-3. Ensure the client ID is correct
-
-### Authentication Errors
-
-1. Regenerate your OAuth token
-2. Verify scopes include `chat:read` and `chat:edit`
-3. Check for typos in environment variables
-
-### Message Not Sending
+## Commands
 
-1. Verify you have joined the target channel
-2. Check that the channel name is correct (no # prefix)
-3. Ensure your token has `chat:edit` scope
+```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
 

package/package.json

@@ -1,17 +1,34 @@
 {
   "name": "@elizaos/plugin-twitch",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.3",
   "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": [
+    "registry-entry.json",
     "dist",
     "auto-enable.ts"
   ],
@@ -35,11 +52,10 @@
   },
   "dependencies": {
     "@twurple/auth": "^8.0.0",
-    "@twurple/chat": "^8.0.0",
-    "zod": "^4.4.3"
+    "@twurple/chat": "^8.0.0"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1"
+    "@elizaos/core": "2.0.3-beta.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
@@ -115,5 +131,6 @@
         "sensitive": false
       }
     }
-  }
+  },
+  "gitHead": "f54b0f4eaed317d59fa7dbcdce20f4cdb0734420"
 }

package/registry-entry.json

@@ -0,0 +1,111 @@
+{
+  "id": "twitch",
+  "name": "Twitch",
+  "description": "Twitch connector for live chat, channel events, and audience interactions.",
+  "npmName": "@elizaos/plugin-twitch",
+  "version": "2.0.0-beta.0",
+  "source": "bundled",
+  "tags": [
+    "connector",
+    "streaming",
+    "twitch",
+    "chat",
+    "social",
+    "social-chat",
+    "messaging"
+  ],
+  "config": {
+    "TWITCH_CHANNEL": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Channel",
+      "help": "Channel name",
+      "advanced": false
+    },
+    "TWITCH_CHANNELS": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Channels",
+      "help": "Comma-separated room/channel list",
+      "advanced": false
+    },
+    "TWITCH_USERNAME": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Username",
+      "help": "Username for authentication",
+      "advanced": false
+    },
+    "TWITCH_CLIENT_ID": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Client Id",
+      "help": "Application/client ID",
+      "advanced": false
+    },
+    "TWITCH_ACCESS_TOKEN": {
+      "type": "secret",
+      "required": true,
+      "sensitive": true,
+      "label": "Access Token",
+      "help": "Access token for Twitch",
+      "advanced": false
+    },
+    "TWITCH_ALLOWED_ROLES": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Allowed Roles",
+      "help": "Comma-separated allowed roles",
+      "advanced": false
+    },
+    "TWITCH_CLIENT_SECRET": {
+      "type": "secret",
+      "required": false,
+      "sensitive": true,
+      "label": "Client Secret",
+      "help": "Client secret for Twitch",
+      "advanced": false
+    },
+    "TWITCH_REFRESH_TOKEN": {
+      "type": "secret",
+      "required": false,
+      "sensitive": true,
+      "label": "Refresh Token",
+      "help": "Refresh token for Twitch",
+      "advanced": false
+    },
+    "TWITCH_REQUIRE_MENTION": {
+      "type": "boolean",
+      "required": false,
+      "sensitive": false,
+      "label": "Require Mention",
+      "help": "Only respond when mentioned",
+      "advanced": false
+    }
+  },
+  "render": {
+    "visible": false,
+    "pinTo": [],
+    "style": "setup-panel",
+    "icon": "Gamepad2",
+    "group": "connector",
+    "groupOrder": 1,
+    "actions": ["enable", "configure", "setup-guide"]
+  },
+  "resources": {
+    "setupGuideUrl": "https://docs.eliza.ai/plugin-setup-guide#twitch"
+  },
+  "dependsOn": [],
+  "kind": "connector",
+  "subtype": "messaging",
+  "auth": {
+    "kind": "token",
+    "credentialKeys": ["TWITCH_ACCESS_TOKEN"]
+  },
+  "channels": ["twitch"]
+}

package/dist/accounts.d.ts

@@ -1,17 +0,0 @@
-import type { IAgentRuntime } from "@elizaos/core";
-import type { TwitchRole, TwitchSettings } from "./types.js";
-export declare const DEFAULT_TWITCH_ACCOUNT_ID = "default";
-export type TwitchAccountConfig = Partial<Omit<TwitchSettings, "additionalChannels" | "allowedRoles" | "allowedUserIds" | "accountId">> & {
-    accountId?: string;
-    id?: string;
-    additionalChannels?: string[] | string;
-    channels?: string[] | string;
-    allowedRoles?: TwitchRole[] | string;
-    allowedUserIds?: string[] | string;
-};
-export declare function normalizeTwitchAccountId(accountId?: unknown): string;
-export declare function listTwitchAccountIds(runtime: IAgentRuntime): string[];
-export declare function resolveDefaultTwitchAccountId(runtime: IAgentRuntime): string;
-export declare function readTwitchAccountId(...sources: unknown[]): string | undefined;
-export declare function resolveTwitchAccountSettings(runtime: IAgentRuntime, requestedAccountId?: string | null): TwitchSettings;
-//# sourceMappingURL=accounts.d.ts.map

package/dist/accounts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,IAAI,CACF,cAAc,EACd,oBAAoB,GAAG,cAAc,GAAG,gBAAgB,GAAG,WAAW,CACvE,CACF,GAAG;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAiGF,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAIpE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAerE;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAU5E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,SAAS,CA8B7E;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,aAAa,EACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GACjC,cAAc,CA4DhB"}

package/dist/connector-account-provider.d.ts

@@ -1,18 +0,0 @@
-/**
- * Twitch ConnectorAccountManager provider.
- *
- * Adapts the multi-account scaffolding in `accounts.ts` to the
- * `ConnectorAccountProvider` contract from
- * `@elizaos/core/connectors/account-manager`.
- *
- * Source of truth for accounts is character settings (`character.settings.twitch`)
- * + TWITCH_ACCOUNTS JSON env var + single-account env vars (TWITCH_USERNAME,
- * TWITCH_CLIENT_ID, TWITCH_ACCESS_TOKEN, TWITCH_REFRESH_TOKEN, TWITCH_CHANNEL).
- *
- * AccountKey is the twitch user id (or username when only that's available).
- * Role is `OWNER` since twitch OAuth tokens authenticate the user/channel.
- */
-import type { ConnectorAccountProvider, IAgentRuntime } from "@elizaos/core";
-export declare const TWITCH_PROVIDER_ID = "twitch";
-export declare function createTwitchConnectorAccountProvider(runtime: IAgentRuntime): ConnectorAccountProvider;
-//# sourceMappingURL=connector-account-provider.d.ts.map

package/dist/connector-account-provider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"connector-account-provider.d.ts","sourceRoot":"","sources":["../src/connector-account-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAIV,wBAAwB,EACxB,aAAa,EACd,MAAM,eAAe,CAAC;AASvB,eAAO,MAAM,kBAAkB,WAAW,CAAC;AA4B3C,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,aAAa,GACrB,wBAAwB,CA+C1B"}

package/dist/index.d.ts

@@ -1,15 +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 * from "./accounts.js";
-export { TwitchService } from "./service.js";
-export * from "./types.js";
-/**
- * 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;AAG3D,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,cAAc,YAAY,CAAC;AAW3B;;GAEG;AACH,QAAA,MAAM,YAAY,EAAE,MAmGnB,CAAC;AAEF,eAAe,YAAY,CAAC"}