@elizaos/plugin-twitch 2.0.0-alpha.7 → 2.0.0-beta.1

package/README.md

@@ -0,0 +1,132 @@
+# @elizaos/plugin-twitch
+
+Twitch chat integration plugin for ElizaOS agents.
+
+## Features
+
+- **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
+
+```bash
+npm install @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/)
+
+## Configuration
+
+Set the following environment variables:
+
+### 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) |
+
+### 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
+
+### Basic Setup
+
+```typescript
+import twitchPlugin from "@elizaos/plugin-twitch";
+
+const agent = new Agent({
+  plugins: [twitchPlugin],
+});
+```
+
+### 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
+
+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
+
+## 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/dist/accounts.d.ts

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

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

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

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

@@ -4,16 +4,9 @@
  * 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";
-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.
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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"}