chat 4.30.0 → 4.31.0

package/docs/create-chat-sdk.mdx

@@ -0,0 +1,143 @@
+---
+title: CLI
+description: Scaffold a Chat SDK bot app with a single command.
+---
+
+`create-chat-sdk` creates a minimal Next.js app for Chat SDK bots.
+
+The CLI will generate your `Chat` configuration, webhook route, `.env.example` file, dependencies, and optional Web adapter route from the adapter catalog.
+
+## Quick start
+
+<CodeBlockTabs defaultValue="npm">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="npm">npm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="pnpm">pnpm</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="yarn">yarn</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="bun">bun</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="npm">
+```bash
+npm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="pnpm">
+```bash
+pnpm create chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="yarn">
+```bash
+yarn create chat-sdk my-bot
+```
+  </CodeBlockTab>
+  <CodeBlockTab value="bun">
+```bash
+bunx create-chat-sdk@latest my-bot
+```
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+<Callout type="info">
+  `create-chat-sdk` automatically detects when it is being run by Cursor, Claude Code, or another coding agent. In agent environments, pass at least one platform adapter with `--adapter`; the state adapter defaults to `memory`. The CLI runs non-interactively and uses `my-bot` when no project name is provided. Pass `--interactive` to force prompts.
+</Callout>
+
+## Non-interactive usage
+
+Pass platform and state adapters with `--adapter`:
+
+```bash
+npm create chat-sdk@latest -- my-bot --adapter slack redis -y
+```
+
+<Callout type="warn">
+  With npm, the `--` separator is required because npm consumes flags before it (`-y` is npm's own `--yes`) instead of forwarding them to the CLI. `pnpm create` and `yarn create` forward flags without it.
+</Callout>
+
+The interactive prompt lists official adapters by default. Pass `--vendor` to list only vendor-official adapters instead. Automation and coding agents can install any CLI-supported official or vendor adapter directly with `--adapter`.
+
+Adapters that require a long-running process, including Matrix and Lark, cannot run on the webhook-only serverless runtime and are not available through the CLI. Add them to an existing project manually instead.
+
+<AdapterSlugList />
+
+Examples:
+
+```bash
+npm create chat-sdk@latest -- slack-bot --adapter slack memory -y --skip-install
+npm create chat-sdk@latest -- gchat-bot --adapter gchat redis -y --pm pnpm
+npm create chat-sdk@latest -- email-bot --adapter resend postgres -y --no-git
+npm create chat-sdk@latest -- my-bot --adapter slack memory -y --force
+```
+
+## What gets generated
+
+The scaffolded app is webhook-only. It does not include pages, layouts, or a client UI.
+
+```txt
+src/
+  lib/bot.ts                              Bot configuration and handlers
+  app/api/webhooks/[platform]/route.ts    Dynamic platform webhook route
+  app/api/chat/route.ts                   Web adapter route, only when selected
+  app/api/discord/gateway/route.ts        Discord Gateway listener, only when selected
+.env.example                              Required environment variables
+next.config.ts                            Next.js server config
+vercel.json                               Cron schedules, only when needed
+.chat-sdk.json                            Generated file ownership for safe reruns
+package.json                              Adapter dependencies
+```
+
+Webhook endpoints use the selected adapter slug:
+
+```txt
+/api/webhooks/slack
+/api/webhooks/gchat
+/api/webhooks/discord
+```
+
+When the [Web adapter](/adapters/official/web) is selected, the CLI also creates `/api/chat` for browser chat requests and a small `getUser` auth stub. Replace the stub with your app's real authentication logic so each web conversation can be associated with the correct user.
+
+When the [Discord adapter](/adapters/official/discord) is selected, the CLI also creates a Gateway listener at `/api/discord/gateway` and a `vercel.json` cron that calls it. Discord delivers slash commands and button clicks to the webhook route, but regular messages and reactions only arrive over the Gateway WebSocket, so the cron keeps that connection alive and forwards events to `/api/webhooks/discord`. Set a `CRON_SECRET` environment variable to authenticate the cron requests. The generated serverless Gateway cron requires [Vercel Pro or Enterprise](https://vercel.com/docs/cron-jobs/usage-and-pricing) because it runs every nine minutes.
+
+## Reference
+
+| Option | Description |
+| --- | --- |
+| `[name]` | Name of the project. |
+| `-d, --description <text>` | Project description. |
+| `--adapter <values...>` | Platform or state adapters to include. |
+| `--vendor` | List only vendor-official adapters in the interactive prompt. |
+| `--pm <manager>` | Package manager to use: `npm`, `yarn`, `pnpm`, or `bun`. |
+| `-y, --yes` | Skip prompts and accept defaults. |
+| `--interactive` | Always prompt, even when a coding agent environment is detected. |
+| `-f, --force` | Overwrite generated files in an existing directory. |
+| `-s, --skip-install` | Skip dependency installation. |
+| `--no-git` | Skip git repository initialization. |
+| `-q, --quiet` | Suppress non-essential output. |
+
+Color output follows the [NO_COLOR standard](https://no-color.org/) — set `NO_COLOR=1` to disable colors.
+
+## Customize your bot
+
+Most bot behavior lives in `src/lib/bot.ts`. Start there when you want to:
+
+- Add or change handlers like `onNewMention`, `onSubscribedMessage`, `onNewMessage`, reactions, actions, or slash commands.
+- Adjust adapter configuration, for example passing explicit credentials or platform-specific options instead of relying only on environment variables.
+- If you selected the memory state adapter, switch to Redis, ioredis, or PostgreSQL before deploying to production.
+
+The generated file includes starter handlers for mentions and subscribed thread replies.
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd my-bot
+cp .env.example .env.local
+npm run dev
+```
+
+Fill in the generated environment variables, expose your local server, and configure each selected platform to call its `/api/webhooks/{adapter}` endpoint.
+
+## Resources
+
+See guides, templates, and examples on the [resources](/resources) page.

package/docs/error-handling.mdx

@@ -105,7 +105,7 @@ try {
   }}
 />
 
-See the [feature matrix](/docs/adapters) for which features are supported on each platform.
+See the [feature matrix](/docs/platform-adapters) for which features are supported on each platform.
 
 ### LockError
 

package/docs/getting-started.mdx

@@ -19,14 +19,14 @@ Learn the core patterns for handling incoming events and posting messages back t
 Connect your bot to chat platforms and persist state across restarts.
 
 <Cards>
-  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/adapters" />
-  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state" />
+  <Card title="Platform Adapters" description="Platform-specific adapters for Slack, Teams, Google Chat, Discord, Telegram, GitHub, and Linear." href="/docs/platform-adapters" />
+  <Card title="State Adapters" description="Pluggable state adapters for thread subscriptions, distributed locking, and caching." href="/docs/state-adapters" />
 </Cards>
 
 Browse all official and community adapters on the [Adapters](/adapters) page.
 
 ## Resources
 
-- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
+- [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=the-complete-guide-to-chat-sdk) — End-to-end walkthrough that takes you from zero to a deployed multi-platform bot, covering adapters, state, handlers, cards, and streaming.
 
-See all guides and templates on the [resources](/resources) page.
+See all guides and templates on the [resources](/resources?utm_source=chat-sdk_site&utm_medium=docs&utm_campaign=getting-started&utm_content=resources) page.

package/docs/index.mdx

@@ -55,7 +55,7 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | Yes | Native (DMs) / Buffered | Yes |
 | Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
-| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Private chat drafts / Post+Edit | Yes |
+| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Rich drafts / Post+Edit | Yes |
 | GitHub | `@chat-adapter/github` | Yes | Yes | No | No | Buffered | No |
 | Linear | `@chat-adapter/linear` | Yes | Yes | No | No | Agent sessions / Post+Edit | No |
 | WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | Buffered | Yes |

package/docs/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "getting-started",
+    "create-chat-sdk",
     "---Usage---",
     "usage",
     "threads-messages-channels",
@@ -14,8 +15,10 @@
     "...ai",
     "---Adapters---",
     "adapters",
+    "platform-adapters",
     "slack-primitives",
-    "state",
+    "teams-primitives",
+    "state-adapters",
     "---Messaging---",
     "streaming",
     "direct-messages",

package/docs/platform-adapters.mdx

@@ -0,0 +1,148 @@
+---
+title: Platform Adapters
+description: Platform-specific adapters that connect your bot to any messaging platform.
+type: overview
+prerequisites:
+  - /docs/getting-started
+  - /docs/adapters
+---
+
+Platform adapters handle webhook verification, message parsing, and API calls for each messaging platform. Install only the adapters you need. Browse all available adapters, including community-built ones, on the [Adapters](/adapters) page.
+
+Need a browser chat UI? See the [Web adapter](/adapters/official/web). It speaks the AI SDK UI stream protocol and works with React (`@ai-sdk/react`), Vue (`@ai-sdk/vue`), and Svelte (`@ai-sdk/svelte`), so the same bot serves Slack, Teams, and any browser framework out of the box.
+
+Ready to build your own? Follow the [building](/docs/contributing/building) guide.
+
+## Feature matrix
+
+<GlobalFeatureMatrix type="platform" />
+
+### Messaging
+
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/gchat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|-----------|
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file/media | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Rich drafts / Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Rich content
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates | Generic/Button Templates |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies | <Warn /> Max 3, postback |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> | <Check /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> Native messages / ASCII cards | <Check /> GFM | <Check /> GFM | <Cross /> | <Warn /> ASCII |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables | <Warn /> ASCII |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+
+### Conversations
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Check /> | <Cross /> |
+| Typing indicator | <Check /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Warn /> Agent sessions | <Warn /> | <Check /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.webClient` / `.octokit` / `.linearClient`](/docs/api/chat#getadapter)) | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+
+### Message history
+
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+
+<Callout type="info">
+<Warn /> indicates partial support. The feature works with limitations. See individual adapter pages for details.
+</Callout>
+
+## How adapters work
+
+Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
+
+1. The adapter verifies the request signature
+2. Parses the platform-specific payload into a normalized `Message`
+3. Routes to your handlers via the `Chat` class
+4. Converts outgoing messages from markdown/AST/cards to the platform's native format
+
+## Using multiple adapters
+
+Register multiple [adapters](/adapters) and your event handlers work across all of them:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+import { createGoogleChatAdapter } from "@chat-adapter/gchat";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    teams: createTeamsAdapter(),
+    gchat: createGoogleChatAdapter(),
+  },
+  state: createRedisState(),
+});
+
+// This handler fires for mentions on any platform
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello!");
+});
+```
+
+Each adapter auto-detects credentials from environment variables, so you only need to pass config when overriding defaults.
+
+<Callout type="info">
+  The examples above use Redis for state. See [State Adapters](/docs/state-adapters) for all available options.
+</Callout>
+
+Each adapter creates a webhook handler accessible via `bot.webhooks.<name>`.
+
+## Customizing an adapter via subclassing
+
+Each official adapter exposes its extension surface as `protected` members so you can subclass it to override or extend platform-specific behavior without forking the package. Use this when you need to handle a payload type the built-in adapter doesn't cover, intercept verification, or wrap an existing handler.
+
+```typescript title="lib/custom-telegram.ts" lineNumbers
+import { TelegramAdapter, type TelegramUpdate } from "@chat-adapter/telegram";
+import type { WebhookOptions } from "chat";
+
+export class CustomTelegramAdapter extends TelegramAdapter {
+  protected override processUpdate(
+    update: TelegramUpdate,
+    options?: WebhookOptions
+  ): void {
+    // Handle a payload type the base adapter doesn't, e.g. chat_join_request.
+    if ("chat_join_request" in update) {
+      this.logger.info("Received chat_join_request", { update });
+      return;
+    }
+    super.processUpdate(update, options);
+  }
+}
+```
+
+Construct your subclass anywhere you'd construct the base adapter, for example, `adapters: { telegram: new CustomTelegramAdapter({ ... }) }`. Members marked `private` intentionally remain inaccessible. If you find a hook you need that isn't `protected`, please open an issue.
+
+<Callout type="warn">
+  The `protected` extension surface is intentionally broader than the public API but is not yet considered fully stable. Method signatures may evolve in minor releases as we learn from real-world subclasses. Pin the adapter version you build against, watch the changelog for the affected adapter, and prefer overriding the smallest hook that solves your problem so upgrades stay easy. If you rely on a particular hook, please open an issue so we can promote it to a stable, documented extension point.
+</Callout>

package/docs/slash-commands.mdx

@@ -8,11 +8,12 @@ related:
   - /docs/modals
   - /adapters/official/slack
   - /adapters/official/discord
+  - /adapters/official/telegram
 ---
 
 Slash commands let users invoke your bot with `/command` syntax. Register handlers with `onSlashCommand` to respond.
 
-Slash commands are supported on [Slack](/adapters/official/slack) and [Discord](/adapters/official/discord).
+Slash commands are supported on [Slack](/adapters/official/slack), [Discord](/adapters/official/discord), and [Telegram](/adapters/official/telegram).
 
 ## Handle a specific command
 
@@ -112,6 +113,10 @@ bot.onModalSubmit("feedback_form", async (event) => {
 });
 ```
 
+## Telegram
+
+Telegram supports bot commands such as `/status` and `/status@mybot`. Register handlers with `onSlashCommand`; commands addressed to another bot are ignored as slash commands and continue through the normal message path.
+
 ## Discord
 
 Discord slash commands are received via [HTTP Interactions](/adapters/official/discord#http-interactions-vs-gateway) — no Gateway connection is needed. The adapter automatically sends a deferred response to Discord, then resolves it when your handler calls `event.channel.post()`.

package/docs/streaming.mdx

@@ -59,7 +59,7 @@ await thread.post(stream);
 | Platform | Method | Description |
 |----------|--------|-------------|
 | Slack | Native streaming API | Uses Slack's `chatStream` for smooth, real-time updates |
-| Telegram | Private chat draft previews | Uses Telegram's `sendMessageDraft` in private chats and falls back to post + edit elsewhere |
+| Telegram | Private chat rich draft previews | Uses Telegram's `sendRichMessageDraft` in private chats, persists the final response with `sendRichMessage`, and falls back to post + edit elsewhere |
 | Teams | Native (DMs) / Buffered (group chats) | Uses the Teams SDK's native `stream.emit()` for direct messages; accumulates chunks and posts one final message when no native streamer is active |
 | Google Chat | Post + Edit | Posts a message then edits it as chunks arrive |
 | Discord | Post + Edit | Posts a message then edits it as chunks arrive |

package/docs/teams-primitives.mdx

@@ -0,0 +1,255 @@
+---
+title: Teams Low-Level APIs
+description: Use Teams Activity parsing, Bot Connector calls, Graph reads, formatting, Adaptive Cards, and Task Module helpers without the full Chat runtime.
+type: guide
+prerequisites:
+  - /adapters/official/teams
+related:
+  - /docs/handling-events
+  - /docs/cards
+  - /docs/modals
+---
+
+The Teams adapter is the right default for most bots. It validates Bot Framework requests through the Microsoft Teams SDK, parses Activities, stores conversation context, renders Adaptive Cards, reads Graph history, and routes events through `Chat`.
+
+Use the low-level Teams subpaths when your app already owns routing, state, sessions, or workflow execution and only needs Teams-specific primitives.
+
+| Subpath | Use for |
+|---------|---------|
+| `@chat-adapter/teams/webhook` | Parse Bot Framework Activity JSON, classify common payloads, and extract continuation data |
+| `@chat-adapter/teams/api` | Fetch-based Bot Connector calls for messages, updates, deletes, typing, and conversations |
+| `@chat-adapter/teams/graph` | Fetch-based Microsoft Graph reads for chats, channels, channel messages, and replies |
+| `@chat-adapter/teams/format` | Teams HTML, mention, Markdown-ish, and emoji string helpers |
+| `@chat-adapter/teams/cards` | Runtime-free conversion from simple card objects and input requests to Adaptive Cards |
+| `@chat-adapter/teams/modals` | Runtime-free Task Module Adaptive Card helpers and submit parsing |
+
+<Callout type="warning">
+  The webhook subpath parses Activities only. It does not verify Microsoft Bot Framework JWTs. For production request validation, use `createTeamsAdapter` or the Microsoft Teams SDK request pipeline before handing the Activity to these helpers.
+</Callout>
+
+## Webhooks
+
+Teams sends Bot Framework Activity JSON. `readTeamsWebhook` reads the request body and classifies the Activity, but it intentionally does not perform JWT validation.
+
+```typescript title="app/api/teams/route.ts" lineNumbers
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+import { readTeamsWebhook } from "@chat-adapter/teams/webhook";
+
+export async function POST(request: Request) {
+  const payload = await readTeamsWebhook(request, {
+    botAppId: process.env.TEAMS_APP_ID,
+  });
+
+  if (payload.kind === "message") {
+    await postTeamsMessage({
+      conversationId: payload.continuation.conversationId,
+      credentials: {
+        appId: process.env.TEAMS_APP_ID!,
+        appPassword: process.env.TEAMS_APP_PASSWORD!,
+        tenantId: payload.continuation.tenantId,
+      },
+      markdownText: `received: ${payload.text}`,
+      serviceUrl: payload.continuation.serviceUrl,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+`parseTeamsWebhookBody` returns typed payloads:
+
+| Kind | Teams surface |
+|------|---------------|
+| `message` | Message activities |
+| `message_reaction` | Reaction activities |
+| `card_action` | Adaptive Card actions and `Action.Submit` message activities |
+| `dialog_open` | Task Module `task/fetch` invokes |
+| `dialog_submit` | Task Module `task/submit` invokes |
+| `conversation_update` | Conversation membership and install context updates |
+| `installation_update` | App installation updates |
+| `unsupported` | Valid Activities not normalized by this helper yet |
+
+Message-like payloads include `continuation`, which contains provider-native reply context:
+
+```typescript
+type TeamsContinuation = {
+  activityId?: string;
+  channelId?: string;
+  conversationId: string;
+  replyToId?: string;
+  serviceUrl: string;
+  teamId?: string;
+  tenantId?: string;
+};
+```
+
+This is not a Chat SDK `Thread`. It is the durable Teams data you need to reply later with `@chat-adapter/teams/api`.
+
+## Bot Connector API
+
+The API subpath calls the Bot Framework Connector REST API with `fetch`. It does not import `@microsoft/teams.apps`.
+
+```typescript title="teams.ts" lineNumbers
+import {
+  deleteTeamsMessage,
+  postTeamsMessage,
+  sendTeamsTyping,
+  updateTeamsMessage,
+} from "@chat-adapter/teams/api";
+
+const credentials = {
+  appId: process.env.TEAMS_APP_ID!,
+  appPassword: process.env.TEAMS_APP_PASSWORD!,
+  tenantId: process.env.TEAMS_APP_TENANT_ID!,
+};
+
+const posted = await postTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  markdownText: "**hello**",
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await updateTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+  text: "updated",
+});
+
+await sendTeamsTyping({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await deleteTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+```
+
+Use `accessToken` in `credentials` when your runtime already owns Microsoft token acquisition. A direct `accessToken` must be scoped for the API you call it against — the Bot Connector subpath (`/api`) needs a `https://api.botframework.com/.default` token, while the Graph subpath (`/graph`) needs a `https://graph.microsoft.com/.default` token. Passing the same token to both will fail against one of them. When you supply `appId`/`appPassword` instead, each subpath requests the correct scope for you.
+
+## Graph
+
+The Graph subpath reads Teams history with explicit Graph IDs. Unlike `TeamsAdapter`, it does not use the adapter state cache to infer `teamId`, `channelId`, or `chatId`.
+
+```typescript
+import { listTeamsChannelMessages } from "@chat-adapter/teams/graph";
+
+const messages = await listTeamsChannelMessages({
+  channelId: "19:channel@thread.tacv2",
+  credentials: {
+    appId: process.env.TEAMS_APP_ID!,
+    appPassword: process.env.TEAMS_APP_PASSWORD!,
+    tenantId: process.env.TEAMS_APP_TENANT_ID!,
+  },
+  limit: 25,
+  teamId: "19:team@thread.tacv2",
+});
+
+const latestText = messages.items[0]?.text;
+```
+
+Graph reads require the same Microsoft Graph permissions as the full adapter. Channel and group-chat reads can use RSC permissions; DM reads require Azure AD application permissions such as `Chat.Read.All`.
+
+## Formatting
+
+Teams renders message text as HTML. The format subpath provides small helpers for custom runtimes:
+
+```typescript
+import {
+  formatTeamsMention,
+  markdownToTeamsHtml,
+  teamsHtmlToMarkdown,
+} from "@chat-adapter/teams/format";
+
+const html = markdownToTeamsHtml(
+  `${formatTeamsMention("Ada")} approved **deploy v2.4.1**`
+);
+const markdown = teamsHtmlToMarkdown("<p>Hello <strong>world</strong></p>");
+```
+
+Use the full `TeamsFormatConverter` from `@chat-adapter/teams` when you need mdast conversion inside Chat SDK.
+
+## Cards
+
+The cards subpath converts simple card objects into Adaptive Card JSON without importing the full `chat` JSX runtime.
+
+```typescript title="cards.ts" lineNumbers
+import {
+  cardToAdaptiveCard,
+  cardToTeamsFallbackText,
+} from "@chat-adapter/teams/cards";
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+
+const card = {
+  children: [
+    { content: "deploy v2.4.1?", type: "text" },
+    {
+      children: [
+        { id: "approve", label: "Approve", style: "primary", type: "button" },
+        { id: "deny", label: "Deny", style: "danger", type: "button" },
+      ],
+      type: "actions",
+    },
+  ],
+  title: "Deployment",
+  type: "card",
+} as const;
+
+await postTeamsMessage({
+  adaptiveCard: cardToAdaptiveCard(card),
+  conversationId: payload.continuation.conversationId,
+  credentials,
+  serviceUrl: payload.continuation.serviceUrl,
+  text: cardToTeamsFallbackText(card),
+});
+```
+
+Use the full Chat SDK card JSX when you want cross-platform rendering. Use `@chat-adapter/teams/cards` when you are building a Teams-only runtime and want Adaptive Card output directly.
+
+## Modals
+
+Teams Task Modules are invoke-based dialogs backed by Adaptive Cards. The modals subpath builds those cards and parses submit data.
+
+```typescript
+import {
+  modalToAdaptiveCard,
+  parseTeamsDialogSubmitValues,
+  toTeamsTaskModuleResponse,
+} from "@chat-adapter/teams/modals";
+
+const modal = {
+  callbackId: "deploy",
+  children: [
+    { content: "Why deploy now?", type: "text" },
+    { id: "reason", label: "Reason", type: "text_input" },
+  ],
+  title: "Deploy",
+  type: "modal",
+} as const;
+
+const card = modalToAdaptiveCard(modal, { contextId: "deploy-1" });
+const values = parseTeamsDialogSubmitValues(payload.value);
+
+return Response.json(
+  toTeamsTaskModuleResponse({ action: "update", modal }, { contextId: "deploy-1" })
+);
+```
+
+## Import Boundaries
+
+The low-level Teams subpaths are designed to avoid the full runtime import graph:
+
+- no `chat` import
+- no `@chat-adapter/shared` import
+- no `@microsoft/teams.apps` import
+- no full adapter import
+
+The package still installs the full Teams adapter dependencies. The subpaths keep your source and bundle imports clean, but they are not a package-size split.

package/docs/testing.mdx

@@ -5,7 +5,7 @@ type: guide
 prerequisites:
   - /docs/getting-started
 related:
-  - /docs/state
+  - /docs/state-adapters
   - /docs/handling-events
   - /docs/contributing/testing
 ---