@mastra/discord 1.0.0 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @mastra/discord
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Added `@mastra/discord` for connecting Mastra agents to Discord. One Discord app serves many servers, and agents respond to slash commands, DMs, and @mentions. Set `encryptionKey` or `MASTRA_ENCRYPTION_KEY` to encrypt the stored bot token at rest. ([#25002](https://github.com/mastra-ai/mastra/pull/25002))
+
+  ```ts
+  import { Mastra } from '@mastra/core';
+  import { DiscordProvider } from '@mastra/discord';
+
+  // App credentials from the Discord Developer Portal (or the DISCORD_BOT_TOKEN /
+  // DISCORD_PUBLIC_KEY / DISCORD_APPLICATION_ID env vars):
+  const discord = new DiscordProvider({
+    app: {
+      botToken: process.env.DISCORD_BOT_TOKEN!,
+      publicKey: process.env.DISCORD_PUBLIC_KEY!,
+      applicationId: process.env.DISCORD_APPLICATION_ID!,
+    },
+  });
+
+  export const mastra = new Mastra({
+    agents: { support },
+    channels: { discord },
+  });
+
+  // Bind an agent. If the bot is already in DISCORD_GUILD_ID, this binds the
+  // agent to that guild and registers its slash commands immediately. Otherwise
+  // it returns an OAuth2 bot-invite URL and the install stays pending until the
+  // bot joins a guild — the first interaction from that guild activates it.
+  const result = await discord.connect('support', { guildId: process.env.DISCORD_GUILD_ID });
+  // → { type: 'immediate' }  OR  { type: 'oauth', authorizationUrl, installationId }
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`fc7d2c1`](https://github.com/mastra-ai/mastra/commit/fc7d2c102e911f43f70f425e67c970231ea19363), [`4607046`](https://github.com/mastra-ai/mastra/commit/460704663e2869183e7dfff7efec49a4f2f47503), [`1e435dc`](https://github.com/mastra-ai/mastra/commit/1e435dc84a9c1b35aa58d0ab9b14ff39fe13aab0), [`9ba23a2`](https://github.com/mastra-ai/mastra/commit/9ba23a23893622b72c76189199d02432590606c1)]:
+  - @mastra/core@1.71.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,32 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named `ee/` within this
+  repository, including but not limited to:
+  - `@mastra/core/auth/ee`
+  - `@mastra/core/agent-builder/ee`
+  - `@mastra/editor/ee`
+
+  is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,175 @@
+# @mastra/discord
+
+Discord channel wrapper for Mastra — a `ChannelProvider` (`@mastra/core/channels`) over **[`@chat-adapter/discord`](https://www.npmjs.com/package/@chat-adapter/discord)** (pinned to `4.40.0`), to parity with `@mastra/slack`.
+
+The adapter already handles the Discord protocol (Ed25519 request verification, PING/PONG, deferrals, embeds + action-row buttons, the Gateway bridge, post-and-edit streaming). This package adds the install/lifecycle layer: the app-config + guild-keyed install store, an OAuth2 bot-invite `connect()`, guild/global slash-command registration, and Mastra route/stream wiring.
+
+**Shape (how Discord differs from Slack/Telegram):** Discord has **no programmatic app creation** — apps are made in the Developer Portal. So there is no per-agent app factory: it's **one app, many guilds**. "Installing" is a **bot invite** (an OAuth2 authorize URL), not a token exchange — there is no per-install token to store. One bot token per application is reused across every guild, and tenancy is keyed by `guildId` per interaction.
+
+## Installation
+
+```bash
+npm install @mastra/discord
+```
+
+Peer: `@mastra/core >= 1.22`.
+
+## Usage
+
+```ts
+import { Mastra } from '@mastra/core';
+import { DiscordProvider } from '@mastra/discord';
+
+const discord = new DiscordProvider({
+  // From the Developer Portal. Or set DISCORD_BOT_TOKEN / DISCORD_PUBLIC_KEY /
+  // DISCORD_APPLICATION_ID in the environment and omit this.
+  app: {
+    botToken: process.env.DISCORD_BOT_TOKEN!,
+    publicKey: process.env.DISCORD_PUBLIC_KEY!,
+    applicationId: process.env.DISCORD_APPLICATION_ID!,
+  },
+  baseUrl: 'https://your-app.example.com', // for the interactions endpoint; auto-detected from the Mastra server if omitted
+});
+
+export const mastra = new Mastra({
+  agents: { support },
+  channels: { discord },
+});
+
+// If the bot is already in DISCORD_GUILD_ID, this binds the agent to that
+// guild and registers its commands immediately. Otherwise it returns an
+// OAuth2 bot-invite URL and the install stays pending until the bot joins a
+// guild — at which point the first interaction from that guild activates it.
+const result = await discord.connect('support', {
+  ...(process.env.DISCORD_GUILD_ID ? { guildId: process.env.DISCORD_GUILD_ID } : {}),
+});
+// → { type: 'immediate' }  OR  { type: 'oauth', authorizationUrl, installationId }
+```
+
+See [`example/discord-agent.ts`](./example/discord-agent.ts) for a full runnable sketch.
+
+### Developer Portal setup
+
+Discord apps are created in the [Developer Portal](https://discord.com/developers/applications), not via API. Once:
+
+1. **Application** → copy the **Application ID** and **Public Key** (General Information).
+2. **Bot** → add a bot, copy its **token**. Enable the **Message Content** / **Server Members** intents if you use DMs/mentions over the Gateway.
+3. **Interactions Endpoint URL** → set it to `${baseUrl}/discord/events/<webhookId>`. After calling `connect(agentId)`, retrieve the `webhookId` by calling `getInstallation(agentId)` — it returns the full `DiscordInstallation` including `webhookId`. (`connect()` returns `installationId`, and `listInstallations()` returns public info without `webhookId`.) Discord sends a signed test PING on save; the adapter answers it — don't rewrite the response.
+
+## Documentation
+
+### The connect flow
+
+`connect(agentId, options?)` returns a discriminated `ChannelConnectResult`:
+
+| Call                                                                 | Result                                                | Meaning                                                                               |
+| -------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `connect(id)`                                                        | `{ type: 'oauth', authorizationUrl, installationId }` | Open the URL, pick a server, authorize. The guild activates on the first interaction. |
+| `connect(id, { guildId })` where the bot is **already** in `guildId` | `{ type: 'immediate' }`                               | Bound instantly; the guild's commands are registered.                                 |
+| `connect(id, { guildId })` where it is **not**                       | `{ type: 'oauth', authorizationUrl, installationId }` | Falls back to the invite URL.                                                         |
+
+The bot-invite URL _is_ an OAuth2 authorize URL (`scope=bot applications.commands` + a `permissions` bitfield), so completion is a browser redirect — hence the `oauth` variant. Re-connecting an already-active agent throws (disconnect first). To add another server, invite the bot with the existing URL — **new guilds activate on their first interaction** off the interaction's authoritative `guild_id`.
+
+Credentials are validated (`GET /applications/@me`) **before** anything is persisted, so a bad token leaves no config or install behind. The bot token is the only secret; with an `encryptionKey` set it is AES-256-GCM encrypted at rest.
+
+### Routing & the raw-body contract
+
+The provider mounts **one** route, `POST /discord/events/:webhookId` (`requiresAuth: false` — Discord authenticates with Ed25519, not a bearer token). The handler passes the **raw request bytes** straight to `adapter.handleWebhook`; Ed25519 verification and PING/PONG live in the adapter.
+
+> ⚠️ The Ed25519 signature is over `timestamp + raw body bytes`. Any middleware that parses and re-serializes the body (a JSON body-parser, `c.req.json()` then re-stringify) mutates the bytes and **every** signature fails. Don't put one in front of this route.
+
+The mounted route only ever receives HTTP **Interactions** (PING, slash commands, buttons). DMs, @mentions and reactions arrive over the **Gateway**.
+
+### The Gateway is core's job
+
+For each adapter with `gateway !== false` (default `true`), `@mastra/core` owns the persistent Gateway WebSocket + its reconnection loop (`AgentChannels` → `startGatewayLoop`). This wrapper just sets `gateway: true` on the adapter entry — it never calls `startGatewayListener` and never runs a reconnect loop. Set `gateway: false` for serverless deployments that only need slash commands over HTTP.
+
+Because core owns the loop (there is no `stopGatewayListener`), `disconnect()` removes the install row and drops the adapter entry but **cannot** kill an in-flight Gateway window — it lapses at the next duration boundary.
+
+### Known caveat: reactions on a thread's starter message
+
+An @mention in a channel opens a **new thread**, and Discord gives that thread an id equal to the starter message's id. `@chat-adapter/discord@4.40.0` handles this: when a reaction `PUT` against `/channels/{threadId}/messages/{messageId}/reactions/…` answers **404 `Unknown Message` (code 10008)** — the starter message is not a message _inside_ the thread, it is the message the thread hangs off — the adapter retries against the parent channel automatically. Replies were never affected: `AgentChannels` suppresses `tool-error` chunks for its own channel tools, so the agent's response still posts.
+
+### Commands
+
+Slash commands default to a single `/help` seed. Override per agent or provider-wide:
+
+```ts
+await discord.connect('support', {
+  commands: ['/help', { name: 'ask', description: 'Ask a question' }],
+});
+```
+
+Names are normalized to Discord's constraints (lowercase `[a-z0-9_-]`, 1-32 chars; description 1-100). Registration is scoped by `commandScope`:
+
+- `'guild'` (default) — `PUT …/guilds/{id}/commands`, updates **instantly**, registered on each first-seen guild.
+- `'global'` — `PUT …/commands`, eventually consistent, registered **once**.
+
+Discord allows only **200 command creates per day, per guild**, so a per-scope content hash is tracked on the install and an unchanged command set is **not** re-registered.
+
+### Streaming & ephemeral
+
+Discord has no native token streaming. With `streaming: true` (default) the reply chunk-edits the interaction followup via the adapter's `editMessage` loop — throttle it with `streaming: { updateIntervalMs }` (Discord rate-limits edits). `typingStatus: true` (default) keeps a typing indicator alive. `toolDisplay` defaults to `'cards'` (Discord has native embeds + action-row buttons).
+
+The deferred type-5 ACK is sent synchronously inside the 3-second window; the agent then runs in the background (under `waitUntil`) and posts into the 15-minute followup window. Ephemeral replies (flag 64) are locked at defer time — decide them via the `interactionFlags` callback (fired on the initial deferred response).
+
+### Configuration
+
+`new DiscordProvider(config)`:
+
+| Option             | Default                                 | Notes                                                                                                  |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `app`              | `DISCORD_*` env                         | `{ botToken, publicKey, applicationId }`. Persisted once to channels storage.                          |
+| `baseUrl`          | Mastra server config                    | Public HTTPS base for the interactions endpoint.                                                       |
+| `storage`          | Mastra channels storage, else in-memory | Install persistence (`ChannelsStorage`).                                                               |
+| `encryptionKey`    | `MASTRA_ENCRYPTION_KEY` env             | Encrypts the stored `botToken` at rest with AES-256-GCM when set; otherwise it is stored in plaintext. |
+| `apiBaseUrl`       | `https://discord.com/api/v10`           | Override the REST origin (e.g. a test mock).                                                           |
+| `permissions`      | read/reply/embed/react bitfield         | Invite-URL permissions (`bigint` or decimal string).                                                   |
+| `commands`         | `/help`                                 | Default command seed.                                                                                  |
+| `commandScope`     | `'guild'`                               | `'guild'` \| `'global'`.                                                                               |
+| `gateway`          | `true`                                  | Start the core-owned Gateway loop (DMs/@mentions/reactions).                                           |
+| `streaming`        | `true`                                  | Post-and-edit reply streaming (`{ updateIntervalMs }` to tune).                                        |
+| `typingStatus`     | `true`                                  | Typing keepalive.                                                                                      |
+| `toolDisplay`      | `'cards'`                               | How tool calls render (Discord has native embeds/buttons).                                             |
+| `mentionRoleIds`   | `DISCORD_MENTION_ROLE_IDS` env          | Roles that trigger mention handlers.                                                                   |
+| `interactionFlags` | —                                       | Return flags (e.g. ephemeral) for the initial deferred response.                                       |
+| `waitUntil`        | —                                       | Keep serverless invocations alive (Vercel/Lambda).                                                     |
+
+### AgentChannels passthrough
+
+These forward to the agent's `AgentChannels` (the same curated subset `@mastra/slack` exposes); each falls back to anything the agent author already configured:
+
+| Option                            | Notes                                                                 |
+| --------------------------------- | --------------------------------------------------------------------- |
+| `handlers`                        | Override `onDirectMessage` / `onMention` / `onSubscribedMessage`.     |
+| `inlineMedia`                     | Which media types are sent inline to the model.                       |
+| `inlineLinks`                     | Promote URLs in messages to file parts.                               |
+| `tools`                           | Expose reaction tools (`add_reaction`/`remove_reaction`). Default on. |
+| `state`                           | State adapter for dedup, locking, subscriptions.                      |
+| `threadContext`                   | Fetch recent messages when joining a thread mid-conversation.         |
+| `chatOptions`                     | Passthrough to the underlying Chat SDK.                               |
+| `resolveResourceId`               | Choose memory ownership for a thread.                                 |
+| `cors` / `formatError` / `logger` | Interactions-route CORS, error rendering, adapter logger.             |
+| `resolveWaitUntil`                | Resolve `waitUntil` from the request context.                         |
+| `onInstall`                       | Called after an agent connects and the install is persisted.          |
+
+### Module format
+
+Dual **ESM + CJS**, mirroring `@mastra/slack`. The ESM-only `@chat-adapter/discord` is kept external in the ESM build but bundled into the CJS output, so both `import` and `require('@mastra/discord')` work.
+
+### Development
+
+```bash
+npm install
+npm run typecheck
+npm test        # vitest, undici-mocked Discord REST + a signed Ed25519 PING→PONG
+npm run build   # tsdown → dist (ESM + CJS + d.ts + d.cts)
+```
+
+## Changelog
+
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/channels/discord/CHANGELOG.md) for version history and release notes.
+
+## Support
+
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.