chat 4.28.1 → 4.30.0

package/docs/handling-events.mdx

@@ -16,9 +16,10 @@ Chat SDK uses an event-driven architecture. You register handlers for different
 
 When a message arrives, the SDK evaluates handlers in this order:
 
-1. **Subscribed threads** — if the thread is subscribed, `onSubscribedMessage` fires and no other message handler runs.
-2. **Mentions** — if the bot is @-mentioned in an unsubscribed thread, `onNewMention` fires.
-3. **Pattern matches** — if the message text matches any `onNewMessage` regex patterns, those handlers fire.
+1. **Direct messages** — if the thread is a DM and any `onDirectMessage` handlers are registered, they fire before `onSubscribedMessage`, `onNewMention`, and pattern handlers.
+2. **Subscribed threads** — if the thread is subscribed, `onSubscribedMessage` fires and no other message handler runs. DMs only reach this step when no `onDirectMessage` handlers are registered.
+3. **Mentions** — if the bot is @-mentioned in an unsubscribed thread, `onNewMention` fires. Unsubscribed DMs without direct handlers are treated as mentions for backward compatibility.
+4. **Pattern matches** — if the message text matches any `onNewMessage` regex patterns, those handlers fire.
 
 Reactions, slash commands, actions, and modals have their own dedicated routing and are not affected by subscription state.
 
@@ -68,7 +69,9 @@ bot.onNewMention(async (thread, message) => {
 
 ## Handling subscribed messages
 
-`onSubscribedMessage` fires for every new message in a thread your bot has subscribed to. Once subscribed, all messages (including @-mentions) route here instead of `onNewMention`.
+`onSubscribedMessage` fires for every new message in a non-DM thread your bot has subscribed to. Once subscribed, messages (including @-mentions) route here instead of `onNewMention`.
+
+If an `onDirectMessage` handler is registered, DM messages route there before subscription routing. Without a direct handler, subscribed DMs route to `onSubscribedMessage`.
 
 ```typescript title="lib/bot.ts" lineNumbers
 bot.onSubscribedMessage(async (thread, message) => {
@@ -94,7 +97,7 @@ Messages sent by the bot itself do not trigger this handler. You don't need to f
 ### Example: Conversational AI with history
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 
 bot.onSubscribedMessage(async (thread, message) => {
   await thread.startTyping();
@@ -111,7 +114,7 @@ bot.onSubscribedMessage(async (thread, message) => {
 });
 ```
 
-See [`toAiMessages`](/docs/api/to-ai-messages) for all options including multi-user name prefixing, message transforms, and attachment handling.
+See [`toAiMessages`](/docs/ai/to-ai-messages) for all options including multi-user name prefixing, message transforms, and attachment handling.
 
 ### Example: Unsubscribe on keyword
 
@@ -299,7 +302,7 @@ These handlers are specific to the Slack platform and require the Slack adapter.
 
 ### Handling assistant threads
 
-`onAssistantThreadStarted` fires when a user opens a new assistant thread in Slack. Use it with the [Slack Assistants API](/adapters/slack#slack-assistants-api) to set suggested prompts and status indicators.
+`onAssistantThreadStarted` fires when a user opens a new assistant thread in Slack. Use it with the [Slack Assistants API](/adapters/official/slack#slack-assistants-api) to set suggested prompts and status indicators.
 
 ```typescript title="lib/bot.ts" lineNumbers
 bot.onAssistantThreadStarted(async (event) => {

package/docs/index.mdx

@@ -55,10 +55,11 @@ 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 | Post+Edit | Yes |
+| Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Private chat 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 |
+| Twilio | `@chat-adapter/twilio` | N/A | No | Fallback | No | Buffered | Yes |
 | Messenger | `@chat-adapter/messenger` | Yes | Receive-only | Partial | No | Buffered | Yes |
 
 ## AI coding agent support
@@ -78,6 +79,7 @@ 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/ai` | [AI utilities](/docs/ai) — [`createChatTools`](/docs/ai/ai-sdk-tools) for agent operations and [`toAiMessages`](/docs/ai/to-ai-messages) for converting chat history into AI SDK prompts |
 | `@chat-adapter/slack` | Slack adapter |
 | `@chat-adapter/teams` | Microsoft Teams adapter |
 | `@chat-adapter/gchat` | Google Chat adapter |
@@ -86,6 +88,7 @@ The SDK is distributed as a set of packages you install based on your needs:
 | `@chat-adapter/github` | GitHub Issues adapter |
 | `@chat-adapter/linear` | Linear Issues adapter |
 | `@chat-adapter/whatsapp` | WhatsApp Business adapter |
+| `@chat-adapter/twilio` | Twilio SMS and MMS adapter |
 | `@chat-adapter/messenger` | Facebook Messenger adapter |
 | `@chat-adapter/state-redis` | Redis state adapter (production) |
 | `@chat-adapter/state-ioredis` | ioredis state adapter (alternative) |

package/docs/meta.json

@@ -9,8 +9,12 @@
     "handling-events",
     "posting-messages",
     "error-handling",
+    "testing",
+    "---AI---",
+    "...ai",
     "---Adapters---",
     "adapters",
+    "slack-primitives",
     "state",
     "---Messaging---",
     "streaming",

package/docs/posting-messages.mdx

@@ -151,7 +151,7 @@ await thread.post(result.fullStream);
 
 Both `fullStream` and `textStream` are supported. Use `fullStream` with multi-step agents — it preserves paragraph breaks between steps. Any `AsyncIterable<string>` also works for custom streams.
 
-For multi-turn conversations, use [`toAiMessages()`](/docs/api/to-ai-messages) to convert thread history into the `{ role, content }[]` format expected by AI SDKs.
+For multi-turn conversations, use [`toAiMessages()`](/docs/ai/to-ai-messages) to convert thread history into the `{ role, content }[]` format expected by AI SDKs.
 
 To pass platform-specific streaming options (e.g. Slack task grouping or stop blocks), wrap the stream in a [`StreamingPlan`](/docs/streaming#streaming-with-options) and post that.
 
@@ -168,6 +168,8 @@ await thread.post({
 });
 ```
 
+Use `attachments` on `{ raw }`, `{ markdown }`, or `{ ast }` when an adapter supports typed media uploads, such as Telegram's single image/audio/video/file upload support.
+
 See the [Files](/docs/files) page for more on attachments.
 
 ## Choosing a format

package/docs/slack-primitives.mdx

@@ -0,0 +1,320 @@
+---
+title: Slack Low-Level APIs
+description: Use Slack request verification, formatting, Web API, and Block Kit helpers without the full Chat runtime.
+type: guide
+prerequisites:
+  - /adapters/official/slack
+related:
+  - /docs/handling-events
+  - /docs/cards
+  - /docs/slash-commands
+---
+
+The Slack adapter is the right default for most bots. It verifies requests, resolves tokens, parses Slack payloads, stores thread state, and routes events through `Chat`.
+
+Use the low-level Slack subpaths when your app already owns routing, state, sessions, or workflow execution and only needs the Slack-specific primitives.
+
+| Subpath | Use for |
+|---------|---------|
+| `@chat-adapter/slack/webhook` | Request verification, body parsing, Events API payloads, slash commands, interactions, and continuation data |
+| `@chat-adapter/slack/format` | Slack mrkdwn tokens, text objects, dates, links, mentions, and simple mrkdwn to Markdown conversion |
+| `@chat-adapter/slack/api` | Fetch-based Slack Web API calls, thread replies, views, and files without `@slack/web-api` |
+| `@chat-adapter/slack/blocks` | Runtime-free conversion from simple card objects and input requests to Slack Block Kit |
+
+<Callout type="info">
+  These subpaths are for custom runtimes. If you want Chat SDK to handle webhook routing, state, subscriptions, and platform normalization, use `createSlackAdapter` from `@chat-adapter/slack`.
+</Callout>
+
+## Webhooks
+
+[Slack signs incoming HTTP requests](https://docs.slack.dev/authentication/verifying-requests-from-slack/) with `x-slack-signature` and `x-slack-request-timestamp`. `verifySlackRequest` reads the request body, verifies the signature with your signing secret, and returns the raw body so you can parse it once.
+
+```typescript title="app/api/slack/route.ts" lineNumbers
+import {
+  parseSlackWebhookBody,
+  verifySlackRequest,
+} from "@chat-adapter/slack/webhook";
+import { postSlackMessage } from "@chat-adapter/slack/api";
+
+export async function POST(request: Request) {
+  const body = await verifySlackRequest(request, {
+    signingSecret: process.env.SLACK_SIGNING_SECRET!,
+  });
+
+  const payload = parseSlackWebhookBody(body, {
+    contentType: request.headers.get("content-type"),
+    headers: request.headers,
+  });
+
+  if (payload.kind === "url_verification") {
+    return Response.json({ challenge: payload.challenge });
+  }
+
+  if (payload.kind === "app_mention") {
+    await postSlackMessage({
+      channel: payload.continuation.channelId,
+      markdownText: `received: ${payload.text}`,
+      threadTs: payload.continuation.threadTs,
+      token: process.env.SLACK_BOT_TOKEN!,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+[Slack slash commands](https://docs.slack.dev/interactivity/implementing-slash-commands/) and interactions should be acknowledged quickly. Slack documents a 3000 ms acknowledgement window for slash commands, so do slow work in your queue or workflow runtime after returning a 2xx response.
+
+If you do not need direct access to the verified raw body, `readSlackWebhook` combines verification and parsing:
+
+```typescript
+import { readSlackWebhook } from "@chat-adapter/slack/webhook";
+
+const payload = await readSlackWebhook(request, {
+  signingSecret: process.env.SLACK_SIGNING_SECRET!,
+});
+```
+
+If your framework already buffered the request body, use `verifySlackSignature` with the raw body and headers, then pass that same body to `parseSlackWebhookBody`.
+
+### Payloads
+
+`parseSlackWebhookBody` returns typed payloads:
+
+| Kind | Slack surface |
+|------|---------------|
+| `url_verification` | Events API URL verification |
+| `app_mention` | App mention events |
+| `direct_message` | Direct message events |
+| `slash_command` | Slash command form posts |
+| `block_actions` | Button, select, and Block Kit action payloads |
+| `block_suggestion` | External select suggestion payloads |
+| `view_submission` | Modal submissions |
+| `view_closed` | Modal close events |
+| `unsupported` | Valid Slack payloads not normalized by this helper yet |
+
+Message-like payloads include `continuation`, which contains provider-native reply context:
+
+```typescript
+type SlackContinuation = {
+  channelId: string;
+  enterpriseId?: string;
+  teamId?: string;
+  threadTs: string;
+};
+```
+
+This is not a Chat SDK `Thread`. It is the durable Slack data you need to reply later with `@chat-adapter/slack/api`.
+
+App mention and direct message payloads also include typed `files` parsed from Slack file objects. Each file keeps the raw Slack object plus common fields like `id`, `name`, `mimeType`, `size`, `url`, and `downloadUrl`.
+
+Interaction payloads expose convenience fields from Slack's raw payload:
+
+- `block_actions` includes `actions`, `messageBlocks`, `messagePromptBlock`, `messagePromptText`, `messageTs`, `triggerId`, `responseUrl`, `user`, and `continuation`
+- `view_submission` includes `callbackId`, `privateMetadata`, `values`, `responseUrls`, and `user`
+
+## Formatting
+
+Slack uses mrkdwn and special tokens for mentions, channels, dates, and links. The format subpath gives you small helpers for those strings.
+
+The helper surface includes `escapeSlackText`, `unescapeSlackText`, `createSlackPlainText`, `createSlackMrkdwn`, `formatSlackUser`, `formatSlackChannel`, `formatSlackUserGroup`, `formatSlackSpecialMention`, `formatSlackLink`, `formatSlackDate`, and simple mrkdwn to Markdown normalization.
+
+```typescript title="format.ts" lineNumbers
+import {
+  createSlackMrkdwn,
+  formatSlackDate,
+  formatSlackLink,
+  formatSlackUser,
+  slackMrkdwnToMarkdown,
+} from "@chat-adapter/slack/format";
+
+const text = createSlackMrkdwn(
+  `${formatSlackUser("U123")} approved ${formatSlackLink("https://example.com", "the deploy")}`
+);
+
+const when = formatSlackDate(
+  new Date("2026-05-27T12:00:00Z"),
+  "{date_short_pretty} at {time}",
+  "May 27 at 12:00"
+);
+
+const markdown = slackMrkdwnToMarkdown("hello <@U123|jane>, see <https://example.com|this>");
+```
+
+`linkBareSlackMentions` only links Slack user IDs like `@U123`. It does not resolve display names, because Slack mentions are ID-based.
+
+## Web API
+
+The API subpath calls [Slack Web API](https://docs.slack.dev/apis/web-api/) methods with `fetch`. It does not import `@slack/web-api`.
+
+```typescript title="slack.ts" lineNumbers
+import {
+  postSlackMessage,
+  sendSlackResponseUrl,
+  updateSlackMessage,
+} from "@chat-adapter/slack/api";
+
+const posted = await postSlackMessage({
+  channel: "C123",
+  markdownText: "**hello**",
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+
+await updateSlackMessage({
+  channel: "C123",
+  text: "updated",
+  token: process.env.SLACK_BOT_TOKEN!,
+  ts: posted.id,
+});
+
+await sendSlackResponseUrl("https://hooks.slack.com/actions/T/1/abc", {
+  replaceOriginal: true,
+  text: "done",
+});
+```
+
+Use `callSlackApi` when you need a Slack method that does not have a helper yet:
+
+```typescript
+import { callSlackApi } from "@chat-adapter/slack/api";
+
+const result = await callSlackApi(
+  "reactions.add",
+  { channel: "C123", name: "white_check_mark", timestamp: "1710000000.000001" },
+  { token: process.env.SLACK_BOT_TOKEN! }
+);
+```
+
+`markdownText` maps to the `markdown_text` field on [`chat.postMessage`](https://docs.slack.dev/reference/methods/chat.postMessage/) and cannot be combined with `text` or `blocks`. Use `text` with `blocks` when you need fallback text.
+
+The subpath also includes `postSlackEphemeral`, `deleteSlackMessage`, `resolveSlackBotToken`, `encodeSlackApiBody`, and `assertSlackOk`.
+
+Use `fetchSlackThreadReplies` when a custom runtime needs to refresh a thread with [`conversations.replies`](https://docs.slack.dev/reference/methods/conversations.replies/):
+
+```typescript
+import { fetchSlackThreadReplies } from "@chat-adapter/slack/api";
+
+const replies = await fetchSlackThreadReplies({
+  channel: payload.continuation.channelId,
+  limit: 50,
+  token: process.env.SLACK_BOT_TOKEN!,
+  ts: payload.continuation.threadTs,
+});
+```
+
+Use `openSlackView` to open a modal from an interaction `trigger_id`:
+
+```typescript
+import { openSlackView } from "@chat-adapter/slack/api";
+
+await openSlackView({
+  token: process.env.SLACK_BOT_TOKEN!,
+  triggerId: payload.triggerId,
+  view: {
+    type: "modal",
+    title: { type: "plain_text", text: "Answer" },
+    blocks: [],
+  },
+});
+```
+
+### Files
+
+[Slack's current external upload flow](https://docs.slack.dev/changelog/2024-04-a-better-way-to-upload-files-is-here-to-stay) uses `files.getUploadURLExternal`, then uploads bytes to the returned URL, then calls `files.completeUploadExternal`.
+
+```typescript
+import { uploadSlackFiles } from "@chat-adapter/slack/api";
+
+await uploadSlackFiles(
+  [{ data: new Uint8Array([1, 2, 3]), filename: "report.txt" }],
+  {
+    channelId: "C123",
+    initialComment: "report attached",
+    token: process.env.SLACK_BOT_TOKEN!,
+  }
+);
+```
+
+Use `fetchSlackFile` for private Slack file URLs that require bearer token authorization.
+
+## Blocks
+
+The blocks subpath converts simple card objects into Slack Block Kit without importing the full `chat` JSX runtime.
+
+It exports `cardToSlackBlocks`, `cardToBlockKit`, `cardToSlackFallbackText`, `cardToFallbackText`, and `convertSlackEmojiPlaceholders`.
+
+```typescript title="blocks.ts" lineNumbers
+import {
+  cardToSlackBlocks,
+  cardToSlackFallbackText,
+} from "@chat-adapter/slack/blocks";
+import { postSlackMessage } from "@chat-adapter/slack/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 postSlackMessage({
+  blocks: cardToSlackBlocks(card),
+  channel: "C123",
+  text: cardToSlackFallbackText(card),
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+```
+
+Use the full Chat SDK card JSX when you want cross-platform rendering. Use `@chat-adapter/slack/blocks` when you are building a Slack-only runtime and want Block Kit output directly.
+
+The blocks subpath also includes small input request helpers for Slack-only runtimes:
+
+```typescript
+import {
+  inputRequestToSlackBlocks,
+  parseSlackInputResponse,
+} from "@chat-adapter/slack/blocks";
+import { postSlackMessage } from "@chat-adapter/slack/api";
+
+await postSlackMessage({
+  blocks: inputRequestToSlackBlocks({
+    options: [
+      { id: "approve", label: "Approve", style: "primary" },
+      { id: "deny", label: "Deny", style: "danger" },
+    ],
+    prompt: "Approve deploy?",
+    requestId: "deploy-1",
+  }),
+  channel: "C123",
+  text: "Approve deploy?",
+  token: process.env.SLACK_BOT_TOKEN!,
+});
+
+if (payload.kind === "block_actions") {
+  const action = payload.actions[0];
+  const response = action ? parseSlackInputResponse(action) : null;
+}
+```
+
+Set `display: "radio"` for radio buttons, or `display: "select"` for a static select menu. Set `allowFreeform: true` to add a "Type your answer" button next to the provided options.
+
+For freeform answers, use `buildSlackFreeformView` with `openSlackView`, then read the submitted value from `payload.values` with `parseSlackFreeformValue`.
+
+## Import boundaries
+
+The low-level Slack subpaths are designed to avoid the full runtime import graph:
+
+- no `chat` import
+- no `@chat-adapter/shared` import
+- no `@slack/web-api` import
+- no `@slack/socket-mode` import
+
+The package still installs the full Slack adapter dependencies. The subpaths keep your source and bundle imports clean, but they are not a package-size split.

package/docs/slash-commands.mdx

@@ -6,13 +6,13 @@ prerequisites:
   - /docs/getting-started
 related:
   - /docs/modals
-  - /adapters/slack
-  - /adapters/discord
+  - /adapters/official/slack
+  - /adapters/official/discord
 ---
 
 Slash commands let users invoke your bot with `/command` syntax. Register handlers with `onSlashCommand` to respond.
 
-Slash commands are supported on [Slack](/adapters/slack) and [Discord](/adapters/discord).
+Slash commands are supported on [Slack](/adapters/official/slack) and [Discord](/adapters/official/discord).
 
 ## Handle a specific command
 
@@ -114,7 +114,7 @@ bot.onModalSubmit("feedback_form", async (event) => {
 
 ## Discord
 
-Discord slash commands are received via [HTTP Interactions](/adapters/discord#architecture-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()`.
+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()`.
 
 ### Subcommands
 

package/docs/streaming.mdx

@@ -59,10 +59,10 @@ 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 |
 | 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 |
-| Telegram | Post + Edit | Posts a message then edits it as chunks arrive |
 | GitHub | Buffered | Accumulates chunks and posts one final comment |
 | Linear | Agent sessions / Post + Edit | Uses agent session activities in agent-session threads; falls back to post+edit comments in issue threads |
 | WhatsApp | Buffered | Accumulates chunks and sends one final message |
@@ -240,10 +240,10 @@ Adapters that don't support PostableObject editing (e.g. WhatsApp) render the pl
 ## Streaming with conversation history
 
 Combine message history with streaming for multi-turn AI conversations.
-Use [`toAiMessages()`](/docs/api/to-ai-messages) to convert chat messages into the `{ role, content }` format expected by AI SDKs:
+Use [`toAiMessages()`](/docs/ai/to-ai-messages) to convert chat messages into the `{ role, content }` format expected by AI SDKs:
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { toAiMessages } from "chat";
+import { toAiMessages } from "chat/ai";
 
 bot.onSubscribedMessage(async (thread, message) => {
   // Fetch recent messages for context
@@ -256,4 +256,4 @@ bot.onSubscribedMessage(async (thread, message) => {
 });
 ```
 
-See the [`toAiMessages` API reference](/docs/api/to-ai-messages) for all options including `includeNames`, `transformMessage`, and attachment handling.
+See the [`toAiMessages` reference](/docs/ai/to-ai-messages) for all options including `includeNames`, `transformMessage`, and attachment handling.

package/docs/subject.mdx

@@ -50,4 +50,4 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-For anything beyond `message.subject`, access the platform's typed API client via [`bot.getAdapter(...).client`](/docs/api/chat#getadapter).
+For anything beyond `message.subject`, access the platform's typed API client via [`bot.getAdapter("github").octokit`](/docs/api/chat#getadapter) or [`bot.getAdapter("linear").linearClient`](/docs/api/chat#getadapter).

package/docs/testing.mdx

@@ -0,0 +1,142 @@
+---
+title: Testing
+description: Test your bot handlers and custom adapters with @chat-adapter/tests — Vitest factories, custom matchers, and a setup file.
+type: guide
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/state
+  - /docs/handling-events
+  - /docs/contributing/testing
+---
+
+The [`@chat-adapter/tests`](https://www.npmjs.com/package/@chat-adapter/tests) package gives you Vitest factories, custom matchers, and a setup file for testing bots and custom adapters built on Chat SDK.
+
+## Install
+
+```bash
+pnpm add -D @chat-adapter/tests
+```
+
+`chat` and `vitest` are peer dependencies — they should already be in your project.
+
+## Setup file (recommended)
+
+Auto-register all matchers by adding the package's setup file to your Vitest config:
+
+```typescript title="vitest.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["@chat-adapter/tests/setup"],
+  },
+});
+```
+
+Without the setup file, register matchers manually:
+
+```typescript
+import { matchers } from "@chat-adapter/tests/matchers";
+expect.extend(matchers);
+```
+
+## Mock factories
+
+```typescript
+import {
+  createMockAdapter,
+  createMockChatInstance,
+  createMockState,
+  createTestMessage,
+  mockLogger,
+} from "@chat-adapter/tests";
+```
+
+| Factory | Returns | Notes |
+|---|---|---|
+| `createMockAdapter(name?, overrides?)` | `Adapter` | Every method is `vi.fn()` with sensible defaults |
+| `createMockChatInstance(options?)` | `ChatInstance` | Every `process*` handler is `vi.fn()`; `getState`/`getUserName`/`getLogger` wired up |
+| `createMockState()` | `MockStateAdapter` | In-memory `Map`s for subscriptions, locks, KV, lists, queues; `cache` exposes the underlying map |
+| `createTestMessage(id, text, overrides?)` | `Message` | Markdown text is parsed into the formatted AST |
+| `mockLogger` / `createMockLogger()` | `Logger` | Shared default vs fresh-per-call |
+
+## Matchers
+
+| Matcher | Asserts |
+|---|---|
+| `expect(adapter).toHavePosted(threadId, textPattern?)` | `adapter.postMessage` was called for this thread |
+| `expect(adapter).toHaveEdited(threadId, messageId, textPattern?)` | `adapter.editMessage` was called for this message |
+| `expect(adapter).toHaveDeleted(threadId, messageId)` | `adapter.deleteMessage` was called for this message |
+| `expect(adapter).toHaveReactedWith(threadId, messageId, emoji)` | `adapter.addReaction` was called with the emoji (string or `EmojiValue.name`) |
+| `expect(adapter).toHaveStartedTyping(threadId)` | `adapter.startTyping` was called for this thread |
+| `expect(adapter).toHavePostedToChannel(channelId, textPattern?)` | `adapter.postChannelMessage` was called for this channel |
+| `expect(chat).toHaveDispatched(handler)` | The named `process*` handler on the mock `ChatInstance` was called |
+| `expect(state).toBeSubscribedTo(threadId)` | `state.isSubscribed(threadId)` resolves to `true` (async — `await expect(...)`) |
+
+Text-pattern matchers extract a comparable string from `AdapterPostableMessage` — strings directly, `PostableMarkdown.markdown`, `PostableRaw.raw`, and `PostableCard.fallbackText`. AST-shaped messages and cards without `fallbackText` aren't text-matchable; assert without `textPattern` and inspect `mock.calls` directly.
+
+## Bot authors: test your handlers
+
+When you're building a bot on top of Chat SDK, the kit lets you exercise your handlers without a real Slack/Teams/etc. webhook on the wire:
+
+```typescript title="bot.test.ts"
+import { describe, expect, it } from "vitest";
+import { Chat } from "chat";
+import { createMockAdapter, createMockState } from "@chat-adapter/tests";
+
+describe("bot handlers", () => {
+  it("replies with a greeting on mention", async () => {
+    const slack = createMockAdapter("slack");
+    const state = createMockState();
+    const bot = new Chat({
+      userName: "mybot",
+      adapters: { slack },
+      state,
+    });
+
+    bot.onNewMention(async (thread) => {
+      await thread.post("hello there");
+    });
+
+    // Drive a synthesized mention through the bot…
+    // (use your adapter's webhook path or a thread-level call)
+
+    expect(slack).toHavePosted("slack:C1:t1", /hello there/);
+  });
+});
+```
+
+## Adapter authors: test webhook → dispatch
+
+When you're building a custom `Adapter`, the kit gives you a `ChatInstance` mock you can hand to your adapter and assert that webhooks route through the right `process*` hook with the right normalized payload:
+
+```typescript title="adapter.test.ts"
+import { describe, expect, it } from "vitest";
+import { createMockChatInstance } from "@chat-adapter/tests";
+import { MyAdapter } from "./adapter";
+
+describe("MyAdapter.handleWebhook", () => {
+  it("dispatches incoming messages through processMessage", async () => {
+    const chat = createMockChatInstance();
+    const adapter = new MyAdapter({ /* config */ });
+    await adapter.initialize(chat);
+
+    const request = new Request("https://example.com/webhook", {
+      method: "POST",
+      body: JSON.stringify({ /* platform-specific payload */ }),
+      headers: { "content-type": "application/json" },
+    });
+    const response = await adapter.handleWebhook(request);
+
+    expect(response.status).toBe(200);
+    expect(chat).toHaveDispatched("processMessage");
+  });
+});
+```
+
+## Adapter-specific helpers
+
+Helpers that depend on a specific platform's wire format (signed Slack webhooks, Teams claim builders, etc.) live in each adapter's own `/testing` subpath rather than in this kit, so adopting `@chat-adapter/tests` doesn't pull in adapter dependencies you don't use.
+
+If you're contributing adapters or core to this repo, see the [Testing adapters contributing guide](/docs/contributing/testing) for hand-rolled patterns used inside `packages/`.

package/docs/threads-messages-channels.mdx

@@ -40,7 +40,7 @@ await thread.post({
 
 ### Subscribe and unsubscribe
 
-Subscriptions persist across restarts (stored in your state adapter). When a thread is subscribed, all messages route to `onSubscribedMessage`.
+Subscriptions persist across restarts (stored in your state adapter). When a non-DM thread is subscribed, all messages route to `onSubscribedMessage`. DM threads route to `onDirectMessage` first when a direct message handler is registered.
 
 ```typescript title="lib/bot.ts" lineNumbers
 await thread.subscribe();