chat 4.28.1 → 4.29.0

package/docs/meta.json

@@ -9,6 +9,9 @@
     "handling-events",
     "posting-messages",
     "error-handling",
+    "testing",
+    "---AI---",
+    "...ai",
     "---Adapters---",
     "adapters",
     "state",

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/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

@@ -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();

package/docs/usage.mdx

@@ -34,7 +34,7 @@ bot.onNewMention(async (thread) => {
 ```
 
 <Callout type="info">
-  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/postgres) and [ioredis](/adapters/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
+  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/official/postgres) and [ioredis](/adapters/official/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
 </Callout>
 
 Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
@@ -72,6 +72,7 @@ Your event handlers work identically across all registered adapters — the SDK
 | `state` | `StateAdapter` | *required* | State adapter for subscriptions and locking |
 | `logger` | `Logger \| LogLevel` | `"info"` | Logger instance or log level (`"debug"`, `"info"`, `"warn"`, `"error"`, `"silent"`) |
 | `dedupeTtlMs` | `number` | `300000` | TTL in ms for message deduplication (5 minutes) |
+| `concurrency` | `"drop" \| "queue" \| "debounce" \| "burst" \| "concurrent" \| ConcurrencyConfig` | `"drop"` | Strategy for overlapping messages on the same thread |
 | `streamingUpdateIntervalMs` | `number` | `500` | Update interval in ms for post+edit streaming |
 | `fallbackStreamingPlaceholderText` | `string \| null` | `"..."` | Placeholder text while streaming starts. Set to `null` to skip |
 | `onLockConflict` | `'drop' \| 'force' \| (threadId, message) => 'drop' \| 'force'` | `"drop"` | Behavior when a thread lock is already held. `'force'` releases the existing lock and re-acquires it, enabling interrupt/steerability for long-running handlers |
@@ -89,13 +90,16 @@ await slack.setSuggestedPrompts(channelId, threadTs, [
 ]);
 ```
 
-For typed access to the platform's native API client (Linear, GitHub), use `.client`:
+For typed access to the platform's native API client, use the SDK-named getter on each adapter:
 
 ```typescript title="lib/bot.ts" lineNumbers
-const linear = bot.getAdapter("linear").client; // LinearClient
-const github = bot.getAdapter("github").client; // Octokit
+const slack = bot.getAdapter("slack").webClient; // WebClient
+const linear = bot.getAdapter("linear").linearClient; // LinearClient
+const github = bot.getAdapter("github").octokit; // Octokit
 ```
 
+The previous `.client` getter still works as a deprecated alias on all three adapters.
+
 See [`getAdapter`](/docs/api/chat#getadapter) for multi-tenant constraints.
 
 ## Webhook routing

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "chat",
-  "version": "4.28.1",
+  "version": "4.29.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,6 +14,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "import": "./dist/ai/index.js"
+    },
     "./jsx-runtime": {
       "types": "./dist/jsx-runtime.d.ts",
       "import": "./dist/jsx-runtime.js"
@@ -37,9 +44,23 @@
   "devDependencies": {
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.3.2",
+    "ai": "^6.0.182",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.182",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",

package/resources/guides/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk.md

@@ -86,7 +86,7 @@ Each tool has a `description` (which tells the model when to use it), an `inputS
 
 Create `lib/bot.ts` with a `ToolLoopAgent` and a `Chat` instance:
 
-`import { Chat } from "chat"; import { toAiMessages } from "chat"; import { createSlackAdapter } from "@chat-adapter/slack"; import { createRedisState } from "@chat-adapter/state-redis"; import { ToolLoopAgent } from "ai"; import { tools } from "./tools"; const agent = new ToolLoopAgent({ model: "anthropic/claude-sonnet-4.6", instructions: "You are a helpful AI assistant in a Slack workspace. " + "Answer questions clearly and use your tools when you need " + "real-time data. Keep responses concise and well-formatted for chat.", tools, }); export const bot = new Chat({ userName: "ai-agent", adapters: { slack: createSlackAdapter(), }, state: createRedisState(), }); // Handle first-time mentions bot.onNewMention(async (thread, message) => { await thread.subscribe(); const result = await agent.stream({ prompt: message.text }); await thread.post(result.fullStream); }); // Handle follow-up messages in subscribed threads bot.onSubscribedMessage(async (thread, message) => { const allMessages = []; for await (const msg of thread.allMessages) { allMessages.push(msg); } const history = await toAiMessages(allMessages); const result = await agent.stream({ messages: history }); await thread.post(result.fullStream); });`
+`import { Chat } from "chat"; import { toAiMessages } from "chat/ai"; import { createSlackAdapter } from "@chat-adapter/slack"; import { createRedisState } from "@chat-adapter/state-redis"; import { ToolLoopAgent } from "ai"; import { tools } from "./tools"; const agent = new ToolLoopAgent({ model: "anthropic/claude-sonnet-4.6", instructions: "You are a helpful AI assistant in a Slack workspace. " + "Answer questions clearly and use your tools when you need " + "real-time data. Keep responses concise and well-formatted for chat.", tools, }); export const bot = new Chat({ userName: "ai-agent", adapters: { slack: createSlackAdapter(), }, state: createRedisState(), }); // Handle first-time mentions bot.onNewMention(async (thread, message) => { await thread.subscribe(); const result = await agent.stream({ prompt: message.text }); await thread.post(result.fullStream); }); // Handle follow-up messages in subscribed threads bot.onSubscribedMessage(async (thread, message) => { const allMessages = []; for await (const msg of thread.allMessages) { allMessages.push(msg); } const history = await toAiMessages(allMessages); const result = await agent.stream({ messages: history }); await thread.post(result.fullStream); });`
 
 When someone @mentions the bot, `onNewMention` fires. The handler subscribes to the thread (to track future messages in that thread) and streams the agent's response. For follow-up messages, `onSubscribedMessage` retrieves the full thread history using `thread.allMessages`, converts it to the AI SDK message format with `toAiMessages`and passes it to the agent so it has a complete conversation context.