chat 4.25.0 → 4.27.0

package/docs/guides/discord-nuxt.mdx

@@ -1,227 +0,0 @@
----
-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:
-  - /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, 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";
-
-export const bot = new Chat({
-  userName: "support-bot",
-  adapters: {
-    discord: createDiscordAdapter(),
-  },
-  state: createRedisState(),
-});
-
-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](/adapters/discord) — Full configuration reference and Gateway setup
-- [State Adapters](/docs/state) — PostgreSQL, ioredis, and other state adapter options

package/docs/guides/durable-chat-sessions-nextjs.mdx

@@ -1,331 +0,0 @@
----
-title: Durable chat sessions with Next.js, Workflow, and Redis
-description: This guide walks through combining Chat SDK and Workflow so a chat thread can survive restarts, wait for follow-up messages, and keep its session state in Redis.
-type: guide
-prerequisites: []
-related:
-  - /docs/guides/slack-nextjs
-  - /docs/handling-events
-  - /docs/streaming
-  - /docs/api/thread
-  - /docs/api/chat
----
-
-Chat SDK and Workflow solve different parts of the same problem.
-
-Chat SDK normalizes incoming platform events into `thread` and `message` objects and gives you a consistent way to reply. Workflow gives you durable execution so a session can wait for the next turn without holding a request open or losing state on restart.
-
-This guide uses Slack and Next.js for a concrete example, but the same pattern works with any Chat SDK adapter.
-
-## Prerequisites
-
-- Node.js 18+
-- [pnpm](https://pnpm.io) (or npm/yarn)
-- A Next.js App Router project
-- A Slack workspace where you can install apps
-- A Redis instance for Chat SDK state
-
-<Callout type="info">
-  If you still need the Slack app manifest and webhook setup, start with [Slack bot with Next.js and Redis](/docs/guides/slack-nextjs), then come back here to add Workflow.
-</Callout>
-
-## Install the dependencies
-
-Install Chat SDK, the Slack adapter, Redis state, and Workflow:
-
-```sh title="Terminal"
-pnpm add chat @chat-adapter/slack @chat-adapter/state-redis workflow
-```
-
-## Enable Workflow in Next.js
-
-Wrap your Next.js config with `withWorkflow()` so `"use workflow"` and `"use step"` directives are compiled correctly:
-
-```typescript title="next.config.ts" lineNumbers
-import { withWorkflow } from "workflow/next";
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {
-  // ...your existing config
-};
-
-export default withWorkflow(nextConfig);
-```
-
-<Callout type="info">
-  If your app uses `proxy.ts`, exclude `.well-known/workflow/` from the matcher so Workflow's internal routes are not intercepted.
-</Callout>
-
-## Create the Chat instance
-
-Create a bot instance exactly as you would for a normal Chat SDK app, but keep the bot definition separate from the workflow code:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { createRedisState } from "@chat-adapter/state-redis";
-import { createSlackAdapter } from "@chat-adapter/slack";
-import { Chat } from "chat";
-
-const adapters = {
-  slack: createSlackAdapter(),
-};
-
-export interface ThreadState {
-  runId?: string;
-}
-
-export const bot = new Chat<typeof adapters, ThreadState>({
-  userName: "durable-bot",
-  adapters,
-  state: createRedisState(),
-}).registerSingleton();
-```
-
-`runId` will store the active workflow run for each subscribed thread.
-
-`registerSingleton()` matters here because Workflow may deserialize `Thread` objects again inside `"use step"` functions, and Chat SDK needs a registered singleton to resolve the adapter and state layer for those thread instances.
-
-## Define a hook payload type
-
-Workflow hooks are how follow-up messages get injected back into a running session. Define the payload type once so both the workflow and the webhook side stay in sync:
-
-```typescript title="workflows/chat-turn-hook.ts" lineNumbers
-import type { SerializedMessage } from "chat";
-
-export type ChatTurnPayload = {
-  message: SerializedMessage;
-};
-```
-
-## Create the durable session workflow
-
-The workflow receives the serialized thread and first message, restores them with `bot.reviver()`, and then keeps waiting for more turns through the hook.
-
-The important detail is that the workflow only orchestrates. Chat SDK side effects such as `post()`, `unsubscribe()`, and `setState()` stay inside step helpers:
-
-```typescript title="workflows/durable-chat-session.ts" lineNumbers
-import { Message, type Thread } from "chat";
-import { createHook, getWorkflowMetadata } from "workflow";
-import { bot, type ThreadState } from "@/lib/bot";
-import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
-
-async function postAssistantMessage(
-  thread: Thread<ThreadState>,
-  text: string
-) {
-  "use step";
-
-  await bot.initialize();
-  await thread.post(text);
-}
-
-async function closeSession(thread: Thread<ThreadState>) {
-  "use step";
-
-  await bot.initialize();
-  await thread.post("Session closed.");
-  await thread.unsubscribe();
-  await thread.setState({}, { replace: true });
-}
-
-async function runTurn(text: string) {
-  "use step";
-
-  // Replace this with AI SDK calls, database work, or other business logic.
-  return `You said: ${text}`;
-}
-
-async function processMessage(
-  thread: Thread<ThreadState>,
-  message: Message
-) {
-  const text = message.text.trim();
-
-  if (text.toLowerCase() === "done") {
-    await closeSession(thread);
-    return false;
-  }
-
-  const reply = await runTurn(text);
-  await postAssistantMessage(thread, reply);
-  return true;
-}
-
-export async function durableChatSession(payload: string) {
-  "use workflow";
-
-  const { workflowRunId } = getWorkflowMetadata();
-  const { thread, message } = JSON.parse(payload, bot.reviver()) as {
-    thread: Thread<ThreadState>;
-    message: Message;
-  };
-
-  using hook = createHook<ChatTurnPayload>({ token: workflowRunId });
-
-  await postAssistantMessage(
-    thread,
-    "Durable session started. Reply in this thread and send `done` when you want to stop."
-  );
-
-  const shouldContinue = await processMessage(thread, message);
-  if (!shouldContinue) {
-    return;
-  }
-
-  for await (const event of hook) {
-    const nextMessage = Message.fromJSON(event.message);
-
-    const keepRunning = await processMessage(thread, nextMessage);
-    if (!keepRunning) {
-      return;
-    }
-  }
-}
-```
-
-<Callout type="info">
-  The `using` keyword requires TypeScript 5.2+ with `"lib": ["esnext.disposable"]` in your `tsconfig.json`. If you are on an older version, call `hook.dispose()` manually when the session ends.
-</Callout>
-
-This is the core integration:
-
-- `thread.toJSON()` and `message.toJSON()` cross the workflow boundary safely
-- `bot.reviver()` restores real Chat SDK objects inside the workflow
-- `bot.registerSingleton()` lets Workflow deserialize `Thread` objects again inside step functions
-- `createHook<ChatTurnPayload>({ token: workflowRunId })` makes the workflow run itself the session identifier
-- `runTurn()`, `postAssistantMessage()`, and `closeSession()` are steps, so adapter and state side effects stay outside the workflow sandbox
-
-## Register Chat SDK event handlers
-
-Create a small side-effect module that decides whether to start a new workflow or resume the existing one:
-
-```typescript title="lib/chat-session-handlers.ts" lineNumbers
-import { type Message, type Thread } from "chat";
-import { resumeHook, start } from "workflow/api";
-import { bot, type ThreadState } from "@/lib/bot";
-import { durableChatSession } from "@/workflows/durable-chat-session";
-import type { ChatTurnPayload } from "@/workflows/chat-turn-hook";
-
-async function startSession(
-  thread: Thread<ThreadState>,
-  message: Message
-) {
-  const run = await start(durableChatSession, [
-    JSON.stringify({
-      thread: thread.toJSON(),
-      message: message.toJSON(),
-    }),
-  ]);
-
-  await thread.setState({ runId: run.runId });
-}
-
-async function routeTurn(
-  thread: Thread<ThreadState>,
-  message: Message
-) {
-  const state = await thread.state;
-
-  if (!state?.runId) {
-    await startSession(thread, message);
-    return;
-  }
-
-  await resumeHook<ChatTurnPayload>(state.runId, {
-    message: message.toJSON(),
-  });
-}
-
-bot.onNewMention(async (thread, message) => {
-  await thread.subscribe();
-  await routeTurn(thread, message);
-});
-
-bot.onSubscribedMessage(async (thread, message) => {
-  await routeTurn(thread, message);
-});
-```
-
-On the first mention, the handler subscribes the thread and starts a workflow. Every later message resumes the existing run by sending the serialized message to the hook.
-
-<Callout type="info">
-  In production, catch `resumeHook()` failures, clear stale `runId` values, and start a new session if the old workflow has already ended.
-</Callout>
-
-## Create the webhook route
-
-Import the side-effect module once so the handlers are registered before the webhook runs:
-
-```typescript title="app/api/webhooks/[platform]/route.ts" lineNumbers
-import "@/lib/chat-session-handlers";
-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),
-  });
-}
-```
-
-## Replace the step with AI
-
-The workflow pattern stays the same if you want AI responses. Replace `runTurn()` with a step that calls AI SDK:
-
-```typescript title="workflows/durable-chat-session.ts" lineNumbers
-import { anthropic } from "@ai-sdk/anthropic";
-import { generateText } from "ai";
-
-async function runTurn(text: string) {
-  "use step";
-
-  const { text: reply } = await generateText({
-    model: anthropic("claude-sonnet-4-5"),
-    system: "You are a helpful assistant in a chat thread.",
-    prompt: text,
-  });
-
-  return reply;
-}
-```
-
-Install the extra packages if you use this version:
-
-```sh title="Terminal"
-pnpm add ai @ai-sdk/anthropic
-```
-
-## How the pattern works
-
-1. A user @mentions the bot in a thread.
-2. Chat SDK subscribes the thread and starts `durableChatSession()`.
-3. The handler stores the workflow `runId` in Chat SDK thread state.
-4. Follow-up messages call `resumeHook(runId, ...)` instead of starting a new run.
-5. The workflow keeps ownership of the session until the user sends `done` or you end it some other way.
-
-This gives you a durable session boundary without moving platform-specific webhook code into your workflow layer.
-
-From here you can add:
-
-- inactivity timeouts with Workflow `sleep()`
-- escalation or approval pauses with additional hooks
-- AI-generated replies, tool calls, or human handoffs inside `"use step"` functions
-
-## Next steps
-
-- [Slack bot with Next.js and Redis](/docs/guides/slack-nextjs) — Slack app setup and basic webhook wiring
-- [Handling Events](/docs/handling-events) — Mentions, subscribed messages, and routing behavior
-- [Streaming](/docs/streaming) — Stream AI SDK responses directly to chat platforms
-- [Thread API](/docs/api/thread) — `thread.toJSON()`, `thread.setState()`, and other thread primitives
-- [Chat API](/docs/api/chat) — `bot.reviver()`, initialization, and webhook access

package/docs/guides/meta.json

@@ -1,10 +0,0 @@
-{
-  "title": "Guides",
-  "pages": [
-    "slack-nextjs",
-    "durable-chat-sessions-nextjs",
-    "scheduled-posts-neon",
-    "code-review-hono",
-    "discord-nuxt"
-  ]
-}