@chat-adapter/discord 4.3.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+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,231 @@
+# @chat-adapter/discord
+
+Discord adapter for the [chat](https://github.com/vercel-labs/chat) SDK.
+
+## Installation
+
+```bash
+npm install chat @chat-adapter/discord
+```
+
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createDiscordAdapter } from "@chat-adapter/discord";
+
+const chat = new Chat({
+  userName: "mybot",
+  adapters: {
+    discord: createDiscordAdapter({
+      botToken: process.env.DISCORD_BOT_TOKEN!,
+      publicKey: process.env.DISCORD_PUBLIC_KEY!,
+      applicationId: process.env.DISCORD_APPLICATION_ID!,
+      // Optional: trigger on role mentions too
+      mentionRoleIds: process.env.DISCORD_MENTION_ROLE_IDS?.split(","),
+    }),
+  },
+});
+
+// Handle @mentions
+chat.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Discord!");
+});
+```
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `botToken` | Yes | Discord bot token |
+| `publicKey` | Yes | Discord application public key (for webhook signature verification) |
+| `applicationId` | Yes | Discord application ID |
+| `mentionRoleIds` | No | Array of role IDs that should trigger mention handlers |
+
+## Discord Application Setup
+
+### 1. Create Application
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click **New Application** and give it a name
+3. Note the **Application ID** from the General Information page
+4. Copy the **Public Key** from the General Information page
+
+### 2. Create Bot
+
+1. Go to the **Bot** section in the left sidebar
+2. Click **Reset Token** to generate a new bot token
+3. Copy and save the token (you won't see it again)
+4. Enable these **Privileged Gateway Intents**:
+   - Message Content Intent
+   - Server Members Intent (if needed)
+
+### 3. Configure Interactions Endpoint
+
+1. Go to **General Information**
+2. Set **Interactions Endpoint URL** to: `https://your-domain.com/api/webhooks/discord`
+3. Discord will send a PING request to verify the endpoint
+
+### 4. Add Bot to Server
+
+1. Go to **OAuth2 > URL Generator**
+2. Select scopes: `bot`, `applications.commands`
+3. Select bot permissions:
+   - Send Messages
+   - Send Messages in Threads
+   - Create Public Threads
+   - Read Message History
+   - Add Reactions
+   - Attach Files
+4. Copy the generated URL and open it to add the bot to your server
+
+## Environment Variables
+
+```bash
+# Required
+DISCORD_BOT_TOKEN=your-bot-token
+DISCORD_PUBLIC_KEY=your-application-public-key
+DISCORD_APPLICATION_ID=your-application-id
+
+# Optional: trigger on role mentions (comma-separated)
+DISCORD_MENTION_ROLE_IDS=1234567890,0987654321
+
+# For Gateway mode with Vercel Cron
+CRON_SECRET=your-random-secret
+```
+
+## Architecture: HTTP Interactions vs Gateway
+
+Discord has two ways to receive events:
+
+### HTTP Interactions (Default)
+- Receives button clicks, slash commands, and verification pings
+- Works out of the box with serverless
+- **Does NOT receive regular messages** - only interactions
+
+### Gateway WebSocket (Required for Messages)
+- Required to receive regular messages and reactions
+- Requires a persistent connection
+- In serverless environments, use a cron job to maintain the connection
+
+## Gateway Setup for Serverless
+
+For Vercel/serverless deployments, set up a cron job to maintain the Gateway connection:
+
+### 1. Create Gateway Route
+
+```typescript
+// app/api/discord/gateway/route.ts
+import { NextResponse } from "next/server";
+import { after } from "next/server";
+import { discord } from "@/lib/bot";
+
+export const maxDuration = 800; // Maximum Vercel function duration
+
+export async function GET(request: Request): Promise<Response> {
+  // Validate cron secret
+  const cronSecret = process.env.CRON_SECRET;
+  if (!cronSecret) {
+    return new Response("CRON_SECRET not configured", { status: 500 });
+  }
+  const authHeader = request.headers.get("authorization");
+  if (authHeader !== `Bearer ${cronSecret}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  // Start Gateway listener (runs for 10 minutes)
+  const durationMs = 600 * 1000;
+  const webhookUrl = `https://${process.env.VERCEL_URL}/api/webhooks/discord`;
+
+  return discord.startGatewayListener(
+    { waitUntil: (task) => after(() => task) },
+    durationMs,
+    undefined,
+    webhookUrl
+  );
+}
+```
+
+### 2. Configure Vercel Cron
+
+Create `vercel.json`:
+
+```json
+{
+  "crons": [
+    {
+      "path": "/api/discord/gateway",
+      "schedule": "*/9 * * * *"
+    }
+  ]
+}
+```
+
+This runs every 9 minutes, ensuring overlap with the 10-minute listener duration.
+
+### 3. Add Environment Variables
+
+Add `CRON_SECRET` to your Vercel project settings.
+
+## Role Mentions
+
+By default, only direct user mentions (`@BotName`) trigger `onNewMention` handlers. To also trigger on role mentions (e.g., `@AI`):
+
+1. Create a role in your Discord server (e.g., "AI")
+2. Assign the role to your bot
+3. Copy the role ID (right-click role in server settings with Developer Mode enabled)
+4. Add the role ID to `DISCORD_MENTION_ROLE_IDS`
+
+```typescript
+createDiscordAdapter({
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  publicKey: process.env.DISCORD_PUBLIC_KEY!,
+  applicationId: process.env.DISCORD_APPLICATION_ID!,
+  mentionRoleIds: ["1457473602180878604"], // Your role ID
+});
+```
+
+## Features
+
+- Message posting and editing
+- Thread creation and management
+- Reaction handling (add/remove/events)
+- File attachments
+- Rich embeds (cards with buttons)
+- Action callbacks (button interactions)
+- Direct messages
+- Role mention support
+
+## Testing
+
+Run a local tunnel (e.g., ngrok) to test webhooks:
+
+```bash
+ngrok http 3000
+```
+
+Update the Interactions Endpoint URL in the Discord Developer Portal to your ngrok URL.
+
+## Troubleshooting
+
+### Bot not responding to messages
+
+1. **Check Gateway connection**: Messages require the Gateway WebSocket, not just HTTP interactions
+2. **Verify Message Content Intent**: Enable this in the Bot settings
+3. **Check bot permissions**: Ensure the bot can read messages in the channel
+
+### Role mentions not triggering
+
+1. **Verify role ID**: Enable Developer Mode in Discord settings, then right-click the role
+2. **Check mentionRoleIds config**: Ensure the role ID is in the array
+3. **Confirm bot has the role**: The bot must have the role assigned to be mentioned via that role
+
+### Signature verification failing
+
+1. **Check public key format**: Should be a 64-character hex string (lowercase)
+2. **Verify endpoint URL**: Must exactly match what's configured in Discord Developer Portal
+3. **Check for body parsing**: Don't parse the request body before verification
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { CardElement, BaseFormatConverter, AdapterPostableMessage, Root, Adapter, Logger, ChatInstance, WebhookOptions, RawMessage, EmojiValue, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
+import { ButtonStyle, APIEmbed } from 'discord-api-types/v10';
+
+/**
+ * Discord adapter types.
+ */
+
+/**
+ * Discord adapter configuration.
+ */
+interface DiscordAdapterConfig {
+    /** Discord bot token */
+    botToken: string;
+    /** Discord application public key for webhook signature verification */
+    publicKey: string;
+    /** Discord application ID */
+    applicationId: string;
+    /** Role IDs that should trigger mention handlers (in addition to direct user mentions) */
+    mentionRoleIds?: string[];
+}
+/**
+ * Discord thread ID components.
+ * Used for encoding/decoding thread IDs.
+ */
+interface DiscordThreadId {
+    /** Guild ID, or "@me" for DMs */
+    guildId: string;
+    /** Channel ID */
+    channelId: string;
+    /** Thread ID (if message is in a thread) */
+    threadId?: string;
+}
+/**
+ * Discord emoji.
+ */
+interface DiscordEmoji {
+    id?: string;
+    name: string;
+    animated?: boolean;
+}
+/**
+ * Discord button component.
+ */
+interface DiscordButton {
+    type: 2;
+    style: ButtonStyle;
+    label?: string;
+    emoji?: DiscordEmoji;
+    custom_id?: string;
+    url?: string;
+    disabled?: boolean;
+}
+/**
+ * Discord action row component.
+ */
+interface DiscordActionRow {
+    type: 1;
+    components: DiscordButton[];
+}
+
+/**
+ * Discord Embed and Component converter for cross-platform cards.
+ *
+ * Converts CardElement to Discord Embeds and Action Row Components.
+ * @see https://discord.com/developers/docs/resources/message#embed-object
+ * @see https://discord.com/developers/docs/interactions/message-components
+ */
+
+/**
+ * Convert a CardElement to Discord message payload (embeds + components).
+ */
+declare function cardToDiscordPayload(card: CardElement): {
+    embeds: APIEmbed[];
+    components: DiscordActionRow[];
+};
+/**
+ * Generate fallback text from a card element.
+ * Used when embeds aren't supported or for notifications.
+ */
+declare function cardToFallbackText(card: CardElement): string;
+
+/**
+ * Discord-specific format conversion using AST-based parsing.
+ *
+ * Discord uses standard markdown with some extensions:
+ * - Bold: **text** (standard)
+ * - Italic: *text* or _text_ (standard)
+ * - Strikethrough: ~~text~~ (standard GFM)
+ * - Links: [text](url) (standard)
+ * - User mentions: <@userId>
+ * - Channel mentions: <#channelId>
+ * - Role mentions: <@&roleId>
+ * - Custom emoji: <:name:id> or <a:name:id> (animated)
+ * - Spoiler: ||text||
+ */
+
+declare class DiscordFormatConverter extends BaseFormatConverter {
+    /**
+     * Convert @mentions to Discord format in plain text.
+     * @name → <@name>
+     */
+    private convertMentionsToDiscord;
+    /**
+     * Override renderPostable to convert @mentions in plain strings.
+     */
+    renderPostable(message: AdapterPostableMessage): string;
+    /**
+     * Render an AST to Discord markdown format.
+     */
+    fromAst(ast: Root): string;
+    /**
+     * Parse Discord markdown into an AST.
+     */
+    toAst(discordMarkdown: string): Root;
+    private nodeToDiscordMarkdown;
+}
+
+/**
+ * Discord adapter for chat-sdk.
+ *
+ * Uses Discord's HTTP Interactions API (not Gateway WebSocket) for
+ * serverless compatibility. Webhook signature verification uses Ed25519.
+ */
+
+declare class DiscordAdapter implements Adapter<DiscordThreadId, unknown> {
+    readonly name = "discord";
+    readonly userName: string;
+    readonly botUserId?: string;
+    private botToken;
+    private publicKey;
+    private applicationId;
+    private mentionRoleIds;
+    private chat;
+    private logger;
+    private formatConverter;
+    constructor(config: DiscordAdapterConfig & {
+        logger: Logger;
+        userName?: string;
+    });
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Handle incoming Discord webhook (HTTP Interactions or forwarded Gateway events).
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Verify Discord's Ed25519 signature using official discord-interactions library.
+     */
+    private verifySignature;
+    /**
+     * Create a JSON response for Discord interactions.
+     */
+    private respondToInteraction;
+    /**
+     * Handle MESSAGE_COMPONENT interactions (button clicks).
+     */
+    private handleComponentInteraction;
+    /**
+     * Handle a forwarded Gateway event received via webhook.
+     */
+    private handleForwardedGatewayEvent;
+    /**
+     * Handle a forwarded MESSAGE_CREATE event.
+     */
+    private handleForwardedMessage;
+    /**
+     * Handle a forwarded REACTION_ADD or REACTION_REMOVE event.
+     */
+    private handleForwardedReaction;
+    /**
+     * Post a message to a Discord channel or thread.
+     */
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<unknown>>;
+    /**
+     * Create a Discord thread from a message.
+     */
+    private createDiscordThread;
+    /**
+     * Truncate content to Discord's maximum length.
+     */
+    private truncateContent;
+    /**
+     * Post a message with file attachments.
+     */
+    private postMessageWithFiles;
+    /**
+     * Edit an existing Discord message.
+     */
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<unknown>>;
+    /**
+     * Delete a Discord message.
+     */
+    deleteMessage(threadId: string, messageId: string): Promise<void>;
+    /**
+     * Add a reaction to a Discord message.
+     */
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Remove a reaction from a Discord message.
+     */
+    removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Encode an emoji for use in Discord API URLs.
+     */
+    private encodeEmoji;
+    /**
+     * Start typing indicator in a Discord channel or thread.
+     */
+    startTyping(threadId: string): Promise<void>;
+    /**
+     * Fetch messages from a Discord channel or thread.
+     * If threadId includes a Discord thread ID, fetches from that thread channel.
+     */
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<unknown>>;
+    /**
+     * Fetch thread/channel information.
+     */
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /**
+     * Open a DM with a user.
+     */
+    openDM(userId: string): Promise<string>;
+    /**
+     * Check if a thread is a DM.
+     */
+    isDM(threadId: string): boolean;
+    /**
+     * Encode platform data into a thread ID string.
+     */
+    encodeThreadId(platformData: DiscordThreadId): string;
+    /**
+     * Decode thread ID string back to platform data.
+     */
+    decodeThreadId(threadId: string): DiscordThreadId;
+    /**
+     * Parse a Discord message into normalized format.
+     */
+    parseMessage(raw: unknown): Message<unknown>;
+    /**
+     * Parse a Discord API message into normalized format.
+     */
+    private parseDiscordMessage;
+    /**
+     * Determine attachment type from MIME type.
+     */
+    private getAttachmentType;
+    /**
+     * Render formatted content to Discord markdown.
+     */
+    renderFormatted(content: FormattedContent): string;
+    /**
+     * Make a request to the Discord API.
+     */
+    private discordFetch;
+    /**
+     * Start Gateway WebSocket listener for receiving messages/mentions.
+     * Uses waitUntil to keep the connection alive for the specified duration.
+     *
+     * This is a workaround for serverless environments - the Gateway connection
+     * will stay alive for the duration, listening for messages.
+     *
+     * @param options - Webhook options with waitUntil function
+     * @param durationMs - How long to keep listening (default: 180000ms = 3 minutes)
+     * @param abortSignal - Optional AbortSignal to stop the listener early (e.g., when a new listener starts)
+     * @param webhookUrl - URL to forward Gateway events to (required for webhook forwarding mode)
+     * @returns Response indicating the listener was started
+     */
+    startGatewayListener(options: WebhookOptions, durationMs?: number, abortSignal?: AbortSignal, webhookUrl?: string): Promise<Response>;
+    /**
+     * Run the Gateway listener for a specified duration.
+     */
+    private runGatewayListener;
+    /**
+     * Set up legacy Gateway handlers for direct processing (when webhookUrl is not provided).
+     */
+    private setupLegacyGatewayHandlers;
+    /**
+     * Forward a Gateway event to the webhook endpoint.
+     */
+    private forwardGatewayEvent;
+    /**
+     * Handle a message received via the Gateway WebSocket.
+     */
+    private handleGatewayMessage;
+    /**
+     * Handle a reaction received via the Gateway WebSocket.
+     */
+    private handleGatewayReaction;
+    /**
+     * Normalize a Discord emoji to our standard EmojiValue format.
+     */
+    private normalizeDiscordEmoji;
+}
+/**
+ * Create a Discord adapter instance.
+ */
+declare function createDiscordAdapter(config: DiscordAdapterConfig & {
+    logger: Logger;
+    userName?: string;
+}): DiscordAdapter;
+
+export { DiscordAdapter, type DiscordAdapterConfig, DiscordFormatConverter, DiscordFormatConverter as DiscordMarkdownConverter, type DiscordThreadId, cardToDiscordPayload, cardToFallbackText, createDiscordAdapter };