chat 4.13.1 → 4.13.2

package/docs/guides/discord-nuxt.mdx

@@ -0,0 +1,237 @@
+---
+title: Discord support bot with Nuxt and Redis
+description: This guide walks through building a Discord support bot with Nuxt, covering project setup, Discord app configuration, Gateway forwarding, AI-powered responses, and deployment.
+type: guide
+prerequisites: []
+related:
+  - /docs/adapters/discord
+  - /docs/cards
+  - /docs/actions
+---
+
+## Prerequisites
+
+- Node.js 18+
+- [pnpm](https://pnpm.io) (or npm/yarn)
+- A Discord server where you have admin access
+- A Redis instance for state management
+
+## Create a Nuxt app
+
+Scaffold a new Nuxt project and install Chat SDK dependencies:
+
+```sh title="Terminal"
+npx nuxi@latest init my-discord-bot
+cd my-discord-bot
+pnpm add chat @chat-adapter/discord @chat-adapter/state-redis ai @ai-sdk/anthropic
+```
+
+## Create a Discord app
+
+1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
+2. Click **New Application**, give it a name, and click **Create**
+3. Go to **Bot** in the sidebar and click **Reset Token** — copy the token, you'll need this as `DISCORD_BOT_TOKEN`
+4. Under **Privileged Gateway Intents**, enable **Message Content Intent**
+5. Go to **General Information** and copy the **Application ID** and **Public Key** — you'll need these as `DISCORD_APPLICATION_ID` and `DISCORD_PUBLIC_KEY`
+
+### Set up the Interactions endpoint
+
+1. In **General Information**, set the **Interactions Endpoint URL** to `https://your-domain.com/api/webhooks/discord`
+2. Discord will send a PING to verify the endpoint — you'll need to deploy first or use a tunnel
+
+### Invite the bot to your server
+
+1. Go to **OAuth2** in the sidebar
+2. Under **OAuth2 URL Generator**, select the `bot` scope
+3. Under **Bot Permissions**, select:
+   - Send Messages
+   - Create Public Threads
+   - Send Messages in Threads
+   - Read Message History
+   - Add Reactions
+   - Use Slash Commands
+4. Copy the generated URL and open it in your browser to invite the bot
+
+## Configure environment variables
+
+Create a `.env` file in your project root:
+
+```bash title=".env"
+DISCORD_BOT_TOKEN=your_bot_token
+DISCORD_PUBLIC_KEY=your_public_key
+DISCORD_APPLICATION_ID=your_application_id
+REDIS_URL=redis://localhost:6379
+ANTHROPIC_API_KEY=your_anthropic_api_key
+```
+
+## Create the bot
+
+Create `server/lib/bot.ts` with a `Chat` instance configured with the Discord adapter. This bot uses AI SDK to answer support questions:
+
+```typescript title="server/lib/bot.tsx" lineNumbers
+import { Chat, ConsoleLogger, Card, CardText as Text, Actions, Button, Divider } from "chat";
+import { createDiscordAdapter } from "@chat-adapter/discord";
+import { createRedisState } from "@chat-adapter/state-redis";
+import { generateText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const logger = new ConsoleLogger();
+
+export const bot = new Chat({
+  userName: "support-bot",
+  adapters: {
+    discord: createDiscordAdapter({
+      botToken: process.env.DISCORD_BOT_TOKEN!,
+      publicKey: process.env.DISCORD_PUBLIC_KEY!,
+      applicationId: process.env.DISCORD_APPLICATION_ID!,
+      logger,
+    }),
+  },
+  state: createRedisState({
+    url: process.env.REDIS_URL!,
+    logger,
+  }),
+  logger,
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post(
+    <Card title="Support">
+      <Text>Hey! I'm here to help. Ask your question in this thread and I'll do my best to answer it.</Text>
+      <Divider />
+      <Actions>
+        <Button id="escalate" style="danger">Escalate to Human</Button>
+      </Actions>
+    </Card>
+  );
+});
+
+bot.onSubscribedMessage(async (thread, message) => {
+  await thread.startTyping();
+
+  const { text } = await generateText({
+    model: anthropic("claude-sonnet-4-5-20250514"),
+    system: "You are a friendly support bot. Answer questions concisely. If you don't know the answer, say so and suggest the user click 'Escalate to Human'.",
+    prompt: message.text,
+  });
+
+  await thread.post(text);
+});
+
+bot.onAction("escalate", async (event) => {
+  await event.thread.post(
+    `${event.user.fullName} requested human support. A team member will follow up shortly.`
+  );
+});
+```
+
+<Callout type="info">
+  The file extension must be `.tsx` (not `.ts`) when using JSX components like `Card` and `Button`. Make sure your `tsconfig.json` has `"jsx": "react-jsx"` and `"jsxImportSource": "chat"`.
+</Callout>
+
+`onNewMention` fires when a user @mentions the bot. Calling `thread.subscribe()` tells the SDK to track that thread, so subsequent messages trigger `onSubscribedMessage` where AI SDK generates a response.
+
+## Create the webhook route
+
+Create a server route that handles incoming Discord webhooks:
+
+```typescript title="server/api/webhooks/[platform].post.ts" lineNumbers
+import { bot } from "../lib/bot";
+
+type Platform = keyof typeof bot.webhooks;
+
+export default defineEventHandler(async (event) => {
+  const platform = getRouterParam(event, "platform") as Platform;
+
+  const handler = bot.webhooks[platform];
+  if (!handler) {
+    throw createError({ statusCode: 404, message: `Unknown platform: ${platform}` });
+  }
+
+  const request = toWebRequest(event);
+
+  return handler(request, {
+    waitUntil: (task) => event.waitUntil(task),
+  });
+});
+```
+
+This creates a `POST /api/webhooks/discord` endpoint. The `waitUntil` option ensures message processing completes after the HTTP response is sent.
+
+## Set up the Gateway forwarder
+
+Discord doesn't push messages to webhooks like Slack does. Instead, messages arrive through the Gateway WebSocket. The Discord adapter includes a built-in Gateway listener that connects to the WebSocket and forwards events to your webhook endpoint.
+
+Create a route that starts the Gateway listener:
+
+```typescript title="server/api/discord/gateway.get.ts" lineNumbers
+import { bot } from "../../lib/bot";
+
+export default defineEventHandler(async (event) => {
+  await bot.initialize();
+
+  const discord = bot.getAdapter("discord");
+  if (!discord) {
+    throw createError({ statusCode: 404, message: "Discord adapter not configured" });
+  }
+
+  const baseUrl = process.env.NUXT_PUBLIC_SITE_URL || "http://localhost:3000";
+  const webhookUrl = `${baseUrl}/api/webhooks/discord`;
+
+  const durationMs = 10 * 60 * 1000; // 10 minutes
+
+  return discord.startGatewayListener(
+    { waitUntil: (task: Promise<unknown>) => event.waitUntil(task) },
+    durationMs,
+    undefined,
+    webhookUrl,
+  );
+});
+```
+
+The Gateway listener connects to Discord's WebSocket, receives messages, and forwards them to your webhook endpoint for processing. In production, you'll want a cron job to restart it periodically.
+
+## Test locally
+
+1. Start your development server (`pnpm dev`)
+2. Trigger the Gateway listener by visiting `http://localhost:3000/api/discord/gateway` in your browser
+3. Expose your server with a tunnel (e.g. `ngrok http 3000`)
+4. Update the **Interactions Endpoint URL** in your Discord app settings to your tunnel URL (e.g. `https://abc123.ngrok.io/api/webhooks/discord`)
+5. @mention the bot in your Discord server — it should respond with a support card
+6. Reply in the thread — AI SDK should generate a response
+7. Click **Escalate to Human** — the bot should post an escalation message
+
+## Add a cron job for production
+
+The Gateway listener runs for a fixed duration. In production, set up a cron job to restart it automatically. If you're deploying to Vercel, add a `vercel.json`:
+
+```json title="vercel.json"
+{
+  "crons": [
+    {
+      "path": "/api/discord/gateway",
+      "schedule": "*/9 * * * *"
+    }
+  ]
+}
+```
+
+This restarts the Gateway listener every 9 minutes, ensuring continuous connectivity. Protect the endpoint with a `CRON_SECRET` environment variable in production.
+
+## Deploy to Vercel
+
+Deploy your bot to Vercel:
+
+```sh title="Terminal"
+vercel deploy
+```
+
+After deployment, set your environment variables in the Vercel dashboard (`DISCORD_BOT_TOKEN`, `DISCORD_PUBLIC_KEY`, `DISCORD_APPLICATION_ID`, `REDIS_URL`, `ANTHROPIC_API_KEY`). Update the **Interactions Endpoint URL** in your Discord app settings to your production URL.
+
+## Next steps
+
+- [Cards](/docs/cards) — Build rich interactive messages with buttons, fields, and selects
+- [Actions](/docs/actions) — Handle button clicks, select menus, and other interactions
+- [Streaming](/docs/streaming) — Stream AI-generated responses to chat
+- [Discord adapter](/docs/adapters/discord) — Full configuration reference and Gateway setup

package/docs/guides/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Guides",
+  "pages": ["slack-nextjs", "code-review-hono", "discord-nuxt"]
+}

package/docs/guides/slack-nextjs.mdx

@@ -0,0 +1,245 @@
+---
+title: Slack bot with Next.js and Redis
+description: This guide walks through building a Slack bot with Next.js, covering project setup, Slack app configuration, event handling, interactive features, and deployment.
+type: guide
+prerequisites: []
+related:
+  - /docs/adapters/slack
+  - /docs/cards
+  - /docs/modals
+  - /docs/streaming
+---
+
+## Prerequisites
+
+- Node.js 18+
+- [pnpm](https://pnpm.io) (or npm/yarn)
+- A Slack workspace where you can install apps
+- A Redis instance for state management
+
+## Create a Next.js app
+
+Scaffold a new Next.js project and install Chat SDK dependencies:
+
+```sh title="Terminal"
+npx create-next-app@latest my-slack-bot --typescript --app
+cd my-slack-bot
+pnpm add chat @chat-adapter/slack @chat-adapter/state-redis
+```
+
+## Create a Slack app
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** then **From an app manifest**
+3. Select your workspace and paste the following manifest:
+
+```yaml title="slack-manifest.yml"
+display_information:
+  name: My Bot
+  description: A bot built with Chat SDK
+
+features:
+  bot_user:
+    display_name: My Bot
+    always_online: true
+
+oauth_config:
+  scopes:
+    bot:
+      - app_mentions:read
+      - channels:history
+      - channels:read
+      - chat:write
+      - groups:history
+      - groups:read
+      - im:history
+      - im:read
+      - mpim:history
+      - mpim:read
+      - reactions:read
+      - reactions:write
+      - users:read
+
+settings:
+  event_subscriptions:
+    request_url: https://your-domain.com/api/webhooks/slack
+    bot_events:
+      - app_mention
+      - message.channels
+      - message.groups
+      - message.im
+      - message.mpim
+  interactivity:
+    is_enabled: true
+    request_url: https://your-domain.com/api/webhooks/slack
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+```
+
+4. Replace `https://your-domain.com/api/webhooks/slack` with your deployed webhook URL
+5. Click **Create**
+
+### Get credentials
+
+After creating the app:
+
+1. Go to **OAuth & Permissions**, click **Install to Workspace**, and copy the **Bot User OAuth Token** (`xoxb-...`) — you'll need this as `SLACK_BOT_TOKEN`
+2. Go to **Basic Information** → **App Credentials** and copy the **Signing Secret** — you'll need this as `SLACK_SIGNING_SECRET`
+
+## Configure environment variables
+
+Create a `.env.local` file in your project root:
+
+```bash title=".env.local"
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_SIGNING_SECRET=your-signing-secret
+REDIS_URL=redis://localhost:6379
+```
+
+## Create the bot
+
+Create `lib/bot.ts` with a `Chat` instance configured with the Slack adapter:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+export const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      signingSecret: process.env.SLACK_SIGNING_SECRET!,
+      logger: new ConsoleLogger(),
+    }),
+  },
+  state: createRedisState({
+    url: process.env.REDIS_URL!,
+    logger: new ConsoleLogger(),
+  }),
+  logger: new ConsoleLogger(),
+});
+
+// Respond when someone @mentions the bot
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm listening to this thread now.");
+});
+
+// Respond to follow-up messages in subscribed threads
+bot.onSubscribedMessage(async (thread, message) => {
+  await thread.post(`You said: ${message.text}`);
+});
+```
+
+`onNewMention` fires when a user @mentions your bot. Calling `thread.subscribe()` tells the SDK to track that thread, so subsequent messages trigger `onSubscribedMessage`.
+
+## Create the webhook route
+
+Create a dynamic API route that handles incoming webhooks:
+
+```typescript title="app/api/webhooks/[platform]/route.ts" lineNumbers
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+
+type Platform = keyof typeof bot.webhooks;
+
+export async function POST(
+  request: Request,
+  context: RouteContext<"/api/webhooks/[platform]">
+) {
+  const { platform } = await context.params;
+
+  const handler = bot.webhooks[platform as Platform];
+  if (!handler) {
+    return new Response(`Unknown platform: ${platform}`, { status: 404 });
+  }
+
+  return handler(request, {
+    waitUntil: (task) => after(() => task),
+  });
+}
+```
+
+This creates a `POST /api/webhooks/slack` endpoint. The `waitUntil` option ensures message processing completes after the HTTP response is sent — required on serverless platforms where the function would otherwise terminate before your handlers finish.
+
+## Test locally
+
+1. Start your development server (`pnpm dev`)
+2. Expose it with a tunnel (e.g. `ngrok http 3000`)
+3. Update the Slack Event Subscriptions **Request URL** to your tunnel URL
+4. Invite your bot to a Slack channel (`/invite @mybot`)
+5. @mention the bot — it should respond with "Hello! I'm listening to this thread now."
+6. Reply in the thread — it should echo your message back
+
+## Add interactive features
+
+Chat SDK supports rich interactive messages using a JSX-like syntax. Update your bot to send cards with buttons:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat, Card, CardText as Text, Actions, Button, Divider } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+export const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      signingSecret: process.env.SLACK_SIGNING_SECRET!,
+      logger: new ConsoleLogger(),
+    }),
+  },
+  state: createRedisState({
+    url: process.env.REDIS_URL!,
+    logger: new ConsoleLogger(),
+  }),
+  logger: new ConsoleLogger(),
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post(
+    <Card title="Welcome!">
+      <Text>I'm now listening to this thread. Try clicking a button:</Text>
+      <Divider />
+      <Actions>
+        <Button id="hello" style="primary">Say Hello</Button>
+        <Button id="info">Show Info</Button>
+      </Actions>
+    </Card>
+  );
+});
+
+bot.onAction("hello", async (event) => {
+  await event.thread.post(`Hello, ${event.user.fullName}!`);
+});
+
+bot.onAction("info", async (event) => {
+  await event.thread.post(`You're on ${event.thread.adapter.name}.`);
+});
+```
+
+<Callout type="info">
+  The file extension must be `.tsx` (not `.ts`) when using JSX components like `Card` and `Button`. Make sure your `tsconfig.json` has `"jsx": "react-jsx"` and `"jsxImportSource": "chat"`.
+</Callout>
+
+## Deploy to Vercel
+
+Deploy your bot to Vercel:
+
+```sh title="Terminal"
+vercel deploy
+```
+
+After deployment, set your environment variables in the Vercel dashboard (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`). If your manifest used a placeholder URL, update the **Event Subscriptions** and **Interactivity** Request URLs in your [Slack app settings](https://api.slack.com/apps) to your production URL.
+
+## Next steps
+
+- [Cards](/docs/cards) — Build rich interactive messages with buttons, fields, and selects
+- [Modals](/docs/modals) — Open forms and dialogs from button clicks
+- [Streaming](/docs/streaming) — Stream AI-generated responses to chat
+- [Actions](/docs/actions) — Handle button clicks, select menus, and other interactions
+- [Slack adapter](/docs/adapters/slack) — Multi-workspace OAuth, token encryption, and full configuration reference

package/docs/index.mdx

@@ -0,0 +1,92 @@
+---
+title: Introduction
+description: A unified SDK for building chat bots across Slack, Microsoft Teams, Google Chat, Discord, and more.
+type: overview
+---
+
+Chat SDK is a TypeScript library for building chat bots that work across multiple platforms with a single codebase. Write your bot logic once and deploy it to Slack, Microsoft Teams, Google Chat, Discord, GitHub, and Linear.
+
+## Why Chat SDK?
+
+Building a chat bot that works across multiple platforms typically means maintaining separate codebases, learning different APIs, and handling platform-specific quirks individually. Chat SDK abstracts these differences behind a unified interface.
+
+- **Single codebase** for all platforms
+- **Type-safe** adapters and event handlers with full TypeScript support
+- **Event-driven** architecture with handlers for mentions, messages, reactions, button clicks, slash commands, and modals
+- **Thread subscriptions** for multi-turn conversations
+- **Rich UI** with JSX cards, buttons, and modals that render natively on each platform
+- **AI streaming** with first-class support for streaming LLM responses
+- **Serverless-ready** with distributed state via Redis and message deduplication
+
+## How it works
+
+Chat SDK has three core concepts:
+
+1. **Chat** — the main entry point that coordinates adapters and routes events to your handlers
+2. **Adapters** — platform-specific implementations that handle webhook parsing, message formatting, and API calls
+3. **State** — a pluggable persistence layer for thread subscriptions and distributed locking
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      signingSecret: process.env.SLACK_SIGNING_SECRET!,
+      logger: new ConsoleLogger(),
+    }),
+  },
+  state: createRedisState({
+    url: process.env.REDIS_URL!,
+    logger: new ConsoleLogger(),
+  }),
+  logger: new ConsoleLogger(),
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm listening to this thread.");
+});
+```
+
+## Supported platforms
+
+| Platform | Package | Mentions | Reactions | Cards | Modals | Streaming | DMs |
+|----------|---------|----------|-----------|-------|--------|-----------|-----|
+| Slack | `@chat-adapter/slack` | Yes | Yes | Yes | Yes | Native | Yes |
+| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Post+Edit | Yes |
+| Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
+| Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
+| GitHub | `@chat-adapter/github` | Yes | Yes | No | No | No | No |
+| Linear | `@chat-adapter/linear` | Yes | Yes | No | No | No | No |
+
+## AI coding agent support
+
+If you use an AI coding agent like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), you can teach it about Chat SDK by installing the skill:
+
+```bash
+npx skills add vercel/chat
+```
+
+This gives your agent access to Chat SDK's documentation, patterns, and best practices so it can help you build bots more effectively.
+
+## Packages
+
+The SDK is distributed as a set of packages you install based on your needs:
+
+| Package | Description |
+|---------|-------------|
+| `chat` | Core SDK with `Chat` class, types, JSX runtime, and utilities |
+| `@chat-adapter/slack` | Slack adapter |
+| `@chat-adapter/teams` | Microsoft Teams adapter |
+| `@chat-adapter/gchat` | Google Chat adapter |
+| `@chat-adapter/discord` | Discord adapter |
+| `@chat-adapter/github` | GitHub Issues adapter |
+| `@chat-adapter/linear` | Linear Issues adapter |
+| `@chat-adapter/state-redis` | Redis state adapter (production) |
+| `@chat-adapter/state-ioredis` | ioredis state adapter (alternative) |
+| `@chat-adapter/state-memory` | In-memory state adapter (development) |

package/docs/meta.json

@@ -0,0 +1,20 @@
+{
+  "title": "Documentation",
+  "pages": [
+    "index",
+    "getting-started",
+    "usage",
+    "posting-messages",
+    "---Features---",
+    "...",
+    "error-handling",
+    "---Platform Adapters---",
+    "...adapters",
+    "---State Adapters---",
+    "...state",
+    "---Guides---",
+    "...guides",
+    "---API Reference---",
+    "...api"
+  ]
+}