chat 4.27.0 → 4.29.0

package/docs/api/postable-message.mdx

@@ -7,9 +7,14 @@ type: reference
 `PostableMessage` is the union of all message formats accepted by `thread.post()` and `sent.edit()`.
 
 ```typescript
-type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent>;
+type PostableMessage =
+  | AdapterPostableMessage
+  | AsyncIterable<string | StreamChunk | StreamEvent>
+  | PostableObject;
 ```
 
+`PostableObject` covers `Plan` (mutable task lists) and `StreamingPlan` (streams with platform-specific options) — both documented below.
+
 ## String
 
 Raw text passed through as-is to the platform.
@@ -33,7 +38,7 @@ await thread.post({ raw: "Hello world" });
       type: 'string',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {
@@ -58,7 +63,7 @@ await thread.post({ markdown: "**Bold** and _italic_" });
       type: 'string',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {
@@ -87,7 +92,7 @@ await thread.post({
       type: 'Root',
     },
     attachments: {
-      description: 'File/image attachments.',
+      description: 'Typed media attachments for adapters that support outgoing attachments.',
       type: 'Attachment[]',
     },
     files: {
@@ -133,6 +138,55 @@ await thread.post({
   }}
 />
 
+## Plan
+
+A `Plan` is a step-by-step task list that mutates after posting. Each `addTask` / `updateTask` / `complete` call re-renders the same message in place. See [Plan API](/docs/streaming#plan-api) for full usage.
+
+```typescript
+import { Plan } from "chat";
+
+const plan = new Plan({ initialMessage: "Researching options..." });
+await thread.post(plan);
+await plan.addTask({ title: "Look up records" });
+await plan.complete({ completeMessage: "Done!" });
+```
+
+Adapters that don't support `PostableObject` editing render the plan as fallback text and ignore subsequent mutations.
+
+## StreamingPlan
+
+Wraps an async iterable with platform-specific streaming options. Use this when you need to pass options like task grouping or stop blocks through `thread.post()`. See [Streaming with options](/docs/streaming#streaming-with-options).
+
+```typescript
+import { StreamingPlan } from "chat";
+
+const planned = new StreamingPlan(stream, {
+  groupTasks: "plan",
+  endWith: [feedbackBlock],
+  updateIntervalMs: 750,
+});
+
+await thread.post(planned);
+```
+
+<TypeTable
+  type={{
+    groupTasks: {
+      description: 'Slack: render task_update chunks as `"plan"` (single grouped block) or `"timeline"` (inline cards, default).',
+      type: '"plan" | "timeline" | undefined',
+    },
+    endWith: {
+      description: 'Slack: Block Kit elements appended when the stream stops (e.g. retry / feedback buttons).',
+      type: 'unknown[] | undefined',
+    },
+    updateIntervalMs: {
+      description: 'Post+edit adapters: minimum interval between update cycles in ms.',
+      type: 'number | undefined',
+      default: '500',
+    },
+  }}
+/>
+
 ## AsyncIterable (streaming)
 
 An async iterable of strings, `StreamChunk` objects, or stream events. The SDK streams the message in real time using platform-native APIs where available.

package/docs/api/thread.mdx

@@ -39,7 +39,7 @@ A `Thread` is provided to your event handlers and represents a conversation thre
 
 ## post
 
-Post a message to the thread. Accepts strings, structured messages, cards, and streams.
+Post a message to the thread. Accepts strings, structured messages, cards, streams, and `PostableObject` instances (`Plan`, `StreamingPlan`).
 
 ```typescript
 // Plain text
@@ -56,11 +56,19 @@ await thread.post(Card({ title: "Hi", children: [Text("Hello")] }));
 
 // Stream (fullStream recommended for multi-step agents)
 await thread.post(result.fullStream);
+
+// Plan (mutable task list)
+const plan = new Plan({ initialMessage: "Working..." });
+await thread.post(plan);
+await plan.addTask({ title: "Step 1" });
+
+// Streaming with platform options
+await thread.post(new StreamingPlan(stream, { groupTasks: "plan" }));
 ```
 
 **Parameters:** `message: string | PostableMessage | CardJSXElement`
 
-**Returns:** `Promise<SentMessage>` — the sent message with `edit()`, `delete()`, `addReaction()`, and `removeReaction()` methods.
+**Returns:** `Promise<SentMessage | PostableObject>` — for plain messages and streams, a `SentMessage` with `edit()`, `delete()`, `addReaction()`, and `removeReaction()` methods; for `Plan` / `StreamingPlan` inputs, the same object is returned so you can keep mutating it.
 
 See [Posting Messages](/docs/posting-messages) for details on each format.
 
@@ -138,7 +146,7 @@ if (participants.length > 1) {
 
 ## subscribe / unsubscribe
 
-Manage thread subscriptions. Subscribed threads route all messages to `onSubscribedMessage` handlers.
+Manage thread subscriptions. Subscribed non-DM threads route all messages to `onSubscribedMessage` handlers. DM threads route to `onDirectMessage` first when a direct message handler is registered.
 
 ```typescript
 await thread.subscribe();

package/docs/api/transcripts.mdx

@@ -0,0 +1,220 @@
+---
+title: Transcripts
+description: Cross-platform per-user transcript persistence — configuration, methods, and entry shape.
+type: reference
+---
+
+`bot.transcripts` provides per-user message persistence keyed by a stable cross-platform identifier. See the [Conversation history](/docs/conversation-history) guide for usage patterns.
+
+```typescript
+import { Chat } from "chat";
+```
+
+## Configuration
+
+`transcripts` and `identity` are configured on `ChatConfig`. Both must be set together — passing `transcripts` without `identity` throws at construction.
+
+### ChatConfig.transcripts
+
+<TypeTable
+  type={{
+    retention: {
+      description: 'List TTL, refreshed on every append. Accepts ms or a duration string ("45s", "30m", "6h", "7d"). Omit for no expiry.',
+      type: 'number | DurationString | undefined',
+    },
+    maxPerUser: {
+      description: 'Hard cap per user. Older entries are evicted on append.',
+      type: 'number',
+      default: '200',
+    },
+    storeFormatted: {
+      description: 'Persist the mdast `formatted` field alongside `text`. Off by default to keep storage small.',
+      type: 'boolean',
+      default: 'false',
+    },
+  }}
+/>
+
+### ChatConfig.identity
+
+```typescript
+identity: (context: IdentityContext) => string | null | Promise<string | null>;
+```
+
+Called once per inbound message during dispatch. The result is attached to the `Message` instance as `message.userKey`. Return `null` to skip persistence for an event.
+
+#### IdentityContext
+
+<TypeTable
+  type={{
+    adapter: {
+      description: 'Adapter name (e.g. "slack", "discord").',
+      type: 'string',
+    },
+    author: {
+      description: 'Message author info.',
+      type: 'Author',
+    },
+    message: {
+      description: 'The inbound message.',
+      type: 'Message',
+    },
+  }}
+/>
+
+## Methods
+
+Access via `bot.transcripts`. Throws if `transcripts` was not configured on the `Chat` instance.
+
+### append
+
+Persist a `Message` (typically the inbound user message) or an `AppendInput` (typically a bot reply you just posted).
+
+```typescript
+append(
+  thread: Postable,
+  message: Message | AppendInput,
+  options?: AppendOptions,
+): Promise<TranscriptEntry | null>;
+```
+
+When `message` is a `Message`, `userKey` is read from the instance. If it's `undefined` (the resolver returned `null`), the call is a no-op and returns `null`. When `message` is an `AppendInput`, `options.userKey` is required.
+
+#### AppendInput
+
+<TypeTable
+  type={{
+    role: {
+      description: 'Role tag for the entry.',
+      type: '"user" | "assistant" | "system"',
+    },
+    text: {
+      description: 'Plain-text body.',
+      type: 'string',
+    },
+    formatted: {
+      description: 'Optional mdast AST. Only stored when `transcripts.storeFormatted` is true.',
+      type: 'FormattedContent | undefined',
+    },
+    platformMessageId: {
+      description: 'Platform-native message ID, when known.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+#### AppendOptions
+
+<TypeTable
+  type={{
+    userKey: {
+      description: 'Required when appending an `AppendInput` (assistant or system role); ignored when appending a `Message`.',
+      type: 'string | undefined',
+    },
+  }}
+/>
+
+### list
+
+Returns entries in chronological order (oldest first). When `limit` is set, returns the newest `N` entries — still chronologically.
+
+```typescript
+list(query: ListQuery): Promise<TranscriptEntry[]>;
+```
+
+#### ListQuery
+
+<TypeTable
+  type={{
+    userKey: {
+      description: 'Cross-platform user key.',
+      type: 'string',
+    },
+    limit: {
+      description: 'Maximum entries returned. Cannot exceed `maxPerUser` because that is the storage cap.',
+      type: 'number',
+      default: '50',
+    },
+    platforms: {
+      description: 'Filter to a subset of adapter names.',
+      type: 'string[] | undefined',
+    },
+    threadId: {
+      description: 'Filter to a single thread.',
+      type: 'string | undefined',
+    },
+    roles: {
+      description: 'Filter to specific roles.',
+      type: '("user" | "assistant" | "system")[] | undefined',
+    },
+  }}
+/>
+
+### count
+
+```typescript
+count(query: CountQuery): Promise<number>;
+```
+
+Returns the total number of entries stored under the user key. `CountQuery` has a single field, `userKey: string`.
+
+### delete
+
+```typescript
+delete(target: { userKey: string }): Promise<{ deleted: number }>;
+```
+
+Wipes every entry stored under the user key. Returns the count that was removed. Single-entry and time-range deletes are not supported — the underlying `appendToList` primitive can't support them safely under concurrent writes.
+
+## TranscriptEntry
+
+Returned by `append` and `list`.
+
+<TypeTable
+  type={{
+    id: {
+      description: 'UUID assigned by the SDK at append time.',
+      type: 'string',
+    },
+    userKey: {
+      description: 'Cross-platform user key from the IdentityResolver.',
+      type: 'string',
+    },
+    role: {
+      description: 'Role tag.',
+      type: '"user" | "assistant" | "system"',
+    },
+    text: {
+      description: 'Plain-text body — canonical for prompt building.',
+      type: 'string',
+    },
+    formatted: {
+      description: 'mdast AST. Only present when `transcripts.storeFormatted` is true.',
+      type: 'FormattedContent | undefined',
+    },
+    platform: {
+      description: 'Originating adapter name.',
+      type: 'string',
+    },
+    threadId: {
+      description: 'Originating thread ID.',
+      type: 'string',
+    },
+    platformMessageId: {
+      description: 'Platform-native message ID, when known.',
+      type: 'string | undefined',
+    },
+    timestamp: {
+      description: 'ms-since-epoch, set at append time on the SDK side.',
+      type: 'number',
+    },
+  }}
+/>
+
+## Storage
+
+Backed by `StateAdapter.appendToList` / `getList` / `delete`. Every built-in state adapter (`memory`, `redis`, `ioredis`, `pg`) supports these primitives.
+
+Entries are stored under `transcripts:user:{userKey}` as a capped list. `appendToList` is atomic, so concurrent inbound messages don't race.
+
+The `retention` value is applied as the list TTL and refreshed on every append. With `retention: "30d"`, a user who hasn't talked to the bot in 30 days has their transcript expire automatically.

package/docs/cards.mdx

@@ -115,6 +115,12 @@ Set `actionType="modal"` to indicate the button opens a [modal](/docs/modals). T
 <Button id="open-feedback" actionType="modal">Give Feedback</Button>
 ```
 
+Optional `callbackUrl` causes the action data to be POSTed to a URL when clicked. See [Callback URLs](/docs/actions#callback-urls) for details.
+
+```tsx title="lib/bot.tsx"
+<Button callbackUrl={webhook.url} id="approve" style="primary">Approve</Button>
+```
+
 ### CardLink
 
 Inline hyperlink rendered as text. Unlike `LinkButton` (which must be inside `Actions`), `CardLink` can be placed directly in a card alongside other content.

package/docs/concurrency.mdx

@@ -1,6 +1,6 @@
 ---
 title: Overlapping Messages
-description: Control how overlapping messages on the same thread are handled — queue, debounce, drop, or process concurrently.
+description: Control how overlapping messages on the same thread are handled - burst, queue, debounce, drop, or process concurrently.
 type: guide
 prerequisites:
   - /docs/handling-events
@@ -57,11 +57,49 @@ A done     → drain: [B, C, D] → handler(D, { skipped: [B, C] })
 D done     → queue empty → release lock
 ```
 
+### Burst
+
+Waits for `debounceMs` before the first handler on an idle thread, then drains the collected burst like `queue`. The latest message is dispatched, and earlier messages in the burst are available as `context.skipped`.
+
+Use this for assistant-style bots where users often send one logical turn as several short messages inside a small window and you want one response with full context. Compared to `debounce`, `burst` keeps the earlier messages in `context.skipped` instead of dropping them, and it flushes queued messages that arrive while the handler is running.
+
+Choose `debounce` when the latest message replaces earlier ones, like rapid corrections. Choose `burst` when earlier messages still matter, like "hey", "quick question", and then the actual question. The tradeoff is that even a lone message waits for `debounceMs` before the handler runs.
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  concurrency: { strategy: "burst", debounceMs: 1000 },
+  // ...
+});
+
+bot.onNewMention(async (thread, message, context) => {
+  const turn = [...(context?.skipped ?? []), message]
+    .map((m) => m.text)
+    .join("\n\n");
+
+  const response = await generateAIResponse(turn);
+  await thread.post(response);
+});
+```
+
+**Flow:**
+
+```
+A arrives  → acquire lock → enqueue A → sleep(debounceMs)
+B arrives  → lock busy → enqueue B
+C arrives  → lock busy → enqueue C
+             ... debounceMs elapses ...
+           → drain: [A, B, C] → handler(C, { skipped: [A, B] })
+D arrives while C is running → lock busy → enqueue D
+E arrives while C is running → lock busy → enqueue E
+C done     → drain: [D, E] → handler(E, { skipped: [D] })
+E done     → queue empty → release lock
+```
+
 ### Debounce
 
-Every message starts or resets a debounce timer. Only the **final message in a burst** is processed.
+The first message waits for `debounceMs`. Messages that arrive during that window replace the pending message, so only the **final message in the burst window** is processed.
 
-This is particularly useful for platforms like **WhatsApp** and **Telegram** where users tend to send a flurry of short messages in quick succession instead of composing a single message — "hey", "quick question", "how do I reset my password?" arriving as three separate webhooks within a few seconds. Without debounce, the bot would respond to "hey" before the actual question even arrives. With debounce, the SDK waits for a pause in the conversation and processes only the final message.
+This is particularly useful for platforms like **WhatsApp** and **Telegram** where users tend to send a flurry of short messages in quick succession instead of composing a single message - "hey", "quick question", "how do I reset my password?" arriving as three separate webhooks within a few seconds. Without debounce, the bot would respond to "hey" before the actual question even arrives. With debounce, the SDK waits briefly and processes only the final message in the window.
 
 ```typescript title="lib/bot.ts" lineNumbers
 const bot = new Chat({
@@ -118,15 +156,19 @@ const bot = new Chat({
 | Option | Strategies | Default | Description |
 |--------|-----------|---------|-------------|
 | `strategy` | all | `"drop"` | The concurrency strategy to use |
-| `maxQueueSize` | queue, debounce | `10` | Maximum queued messages per thread |
-| `onQueueFull` | queue, debounce | `"drop-oldest"` | Whether to evict the oldest or reject the newest message when the queue is full |
-| `queueEntryTtlMs` | queue, debounce | `90000` | TTL for queued entries in milliseconds. Expired entries are discarded on dequeue |
-| `debounceMs` | debounce | `1500` | Debounce window in milliseconds |
+| `maxQueueSize` | queue, burst | `10` | Maximum queued messages per thread |
+| `onQueueFull` | queue, burst | `"drop-oldest"` | Whether to evict the oldest or reject the newest message when the queue is full |
+| `queueEntryTtlMs` | queue, debounce, burst | `90000` | TTL for queued entries in milliseconds. Expired entries are discarded on dequeue |
+| `debounceMs` | debounce, burst | `1500` | Debounce window in milliseconds |
 | `maxConcurrent` | concurrent | `Infinity` | Max concurrent handlers per thread |
 
+<Callout type="warn">
+`maxConcurrent` only applies to the `concurrent` strategy. Pairing it with any other strategy logs a warning and the value is ignored. Setting `maxConcurrent` to a value less than `1` throws at construction time — `0` would deadlock the strategy and is rejected up front.
+</Callout>
+
 ## MessageContext
 
-All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is only populated when using the `queue` strategy and messages were skipped.
+All handler types (`onNewMention`, `onSubscribedMessage`, `onNewMessage`) accept an optional `MessageContext` as their last parameter. It is populated when using the `queue` strategy for queued messages, and when using `burst` for a collapsed turn. A lone `burst` message receives `skipped: []` and `totalSinceLastHandler: 1`.
 
 ```typescript
 interface MessageContext {
@@ -182,7 +224,7 @@ const bot = new Chat({
 
 ## State adapter requirements
 
-The `queue` and `debounce` strategies require three additional methods on your state adapter:
+The `queue`, `debounce`, and `burst` strategies require three additional methods on your state adapter:
 
 | Method | Description |
 |--------|-------------|
@@ -198,12 +240,12 @@ All strategies emit structured log events at `info` level:
 
 | Event | Strategy | Data |
 |-------|----------|------|
-| `message-queued` | queue | threadId, messageId, queueDepth |
-| `message-dequeued` | queue, debounce | threadId, messageId, skippedCount |
-| `message-dropped` | drop, queue | threadId, messageId, reason |
-| `message-expired` | queue, debounce | threadId, messageId |
+| `message-queued` | queue, burst | threadId, messageId, queueDepth |
+| `message-dequeued` | queue, debounce, burst | threadId, messageId, skippedCount for queue/burst |
+| `message-dropped` | drop, queue, burst | threadId, messageId, reason |
+| `message-expired` | queue, debounce, burst | threadId, messageId |
 | `message-superseded` | debounce | threadId, droppedId |
-| `message-debouncing` | debounce | threadId, messageId, debounceMs |
+| `message-debouncing` | debounce, burst | threadId, messageId, debounceMs |
 | `message-debounce-reset` | debounce | threadId, messageId |
 
 ## Choosing a strategy
@@ -212,7 +254,8 @@ All strategies emit structured log events at `info` level:
 |----------|----------|-----|
 | Simple bots, one-shot commands | `drop` | No complexity, no queue overhead |
 | AI chatbots, customer support | `queue` | Never lose messages; handler sees full conversation context |
-| WhatsApp/Telegram bots, rapid corrections | `debounce` | Users send many short messages in quick succession; wait for a pause before responding |
+| AI chatbots with multi-message user turns | `burst` | Wait for the idle burst window, then respond once with every message in that window |
+| WhatsApp/Telegram bots, rapid corrections | `debounce` | Users send many short messages in quick succession; wait briefly and keep only the latest |
 | Stateless lookups, translations | `concurrent` | Maximum throughput, no ordering needed |
 
 ## Backward compatibility

package/docs/contributing/building.mdx

@@ -370,7 +370,7 @@ parseMessage(raw: unknown): Message<unknown> {
 
 ### Sending messages
 
-Use `extractCard()` and `extractFiles()` from `@chat-adapter/shared` to check for rich content. Use your format converter's `renderPostable()` to convert the message to platform format.
+Use `extractCard()` and `extractFiles()` from `@chat-adapter/shared` to check for rich content. Use `extractPostableAttachments()` if your adapter maps normalized `Attachment` objects to platform-native media uploads. Use your format converter's `renderPostable()` to convert the message to platform format.
 
 ```typescript title="src/adapter.ts" lineNumbers
 async postMessage(
@@ -414,6 +414,62 @@ async deleteMessage(threadId: string, messageId: string): Promise<void> {
 }
 ```
 
+### Buttons and callback URLs
+
+When the host app passes a `Card` with `<Button callbackUrl={...}>`, the SDK rewrites each such button **before** your adapter sees the postable: the `callbackUrl` is stored in the state adapter under a short token, and the button's `value` field is replaced with `__cb:<16-hex-chars>` (21 characters total). Your adapter does not need to know this happens — just round-trip `button.value` through your platform's button payload.
+
+What this means in practice:
+
+1. **Send side**: when rendering a `ButtonElement` to your platform's button payload, encode both `button.id` (the action ID) and `button.value` (which may be `undefined`, a user-supplied value, or a callback token). Pick a delimiter that cannot appear in either, and validate the encoded string fits the platform's limit.
+2. **Receive side**: when the user clicks a button, decode the platform payload back into `actionId` and `value`, and pass them to `chat.processAction({ actionId, value, ... })`. The SDK will detect the `__cb:` prefix, look up the stored callback URL, POST to it, and pass the original value (if any) to user `onAction` handlers.
+
+Discord's adapter is a good reference — it joins the action ID and value with `\n` and validates against Discord's 100-character `custom_id` limit:
+
+```typescript title="src/cards.ts (discord)" lineNumbers
+const DISCORD_CUSTOM_ID_DELIMITER = "\n";
+const DISCORD_CUSTOM_ID_MAX_LENGTH = 100;
+
+export function encodeDiscordCustomId(
+  actionId: string,
+  value?: string
+): string {
+  if (value == null || value === "") {
+    validateLength(actionId);
+    return actionId;
+  }
+  const encoded = `${actionId}${DISCORD_CUSTOM_ID_DELIMITER}${value}`;
+  validateLength(encoded);
+  return encoded;
+}
+
+export function decodeDiscordCustomId(customId: string): {
+  actionId: string;
+  value: string | undefined;
+} {
+  const idx = customId.indexOf(DISCORD_CUSTOM_ID_DELIMITER);
+  if (idx === -1) {
+    return { actionId: customId, value: undefined };
+  }
+  // Use the FIRST delimiter only — values may legitimately contain "\n".
+  return {
+    actionId: customId.slice(0, idx),
+    value: customId.slice(idx + 1),
+  };
+}
+```
+
+<Callout type="info">
+  Platform button-data limits are the main constraint to plan for. Discord's
+  `custom_id` is 100 chars; Telegram's `callback_data` is 64 bytes. The SDK's
+  callback token is fixed at 21 chars (`__cb:` + 16 hex), so the worst-case
+  payload your encoding must fit is `actionId + delimiter + 21`. If the
+  encoded string exceeds the platform limit, throw a `ValidationError` from
+  `@chat-adapter/shared` so the host app fails fast at post time rather than
+  silently truncating.
+</Callout>
+
+Modals with `callbackUrl` are handled entirely inside the SDK via stored modal context — your adapter does not need any special handling. Just call `chat.processModalSubmit(event, contextId, { waitUntil })` from your webhook handler and the SDK will POST to the modal's `callbackUrl` (using `waitUntil` if you provide it, so the response is not blocked).
+
 ### Reactions
 
 Handle both `EmojiValue` objects and plain strings. `EmojiValue` has a `name` property and `toString()` method — there is no `unicode` field.
@@ -535,7 +591,7 @@ export class MatrixFormatConverter extends BaseFormatConverter {
 }
 ```
 
-For platforms with non-standard formatting (e.g., Slack's `mrkdwn`), implement custom parsing in `toAst()` and rendering in `fromAst()`. See the [Discord adapter](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts) for an example of handling platform-specific mention syntax.
+For platforms with non-standard formatting, implement custom parsing in `toAst()` and rendering in `fromAst()`. See the [Discord adapter](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts) for an example of handling platform-specific mention syntax.
 
 ## Optional methods
 
@@ -639,3 +695,19 @@ import {
   cardToFallbackText, // Convert card to plain text
 } from "@chat-adapter/shared";
 ```
+
+### Token encryption
+
+If your adapter persists OAuth tokens to a `StateAdapter`, encrypt them at rest with the shared AES-256-GCM helpers instead of rolling your own:
+
+```typescript
+import {
+  encryptToken,         // Encrypt a string into an EncryptedTokenData envelope
+  decryptToken,         // Decrypt an envelope back to the original string
+  decodeKey,            // Decode a hex-64 or base64-44 32-byte key (throws on wrong length)
+  isEncryptedTokenData, // Type guard for tolerating legacy plaintext records
+  type EncryptedTokenData,
+} from "@chat-adapter/shared";
+```
+
+Accept the key as an optional `encryptionKey` config field (auto-detected from a `*_ENCRYPTION_KEY` env var), encrypt on `setInstallation()`, decrypt on `getInstallation()`, and use `isEncryptedTokenData` to keep accepting plaintext records so operators can roll the key in without flushing existing installs. See `@chat-adapter/slack` and `@chat-adapter/linear` for reference implementations.

package/docs/contributing/testing.mdx

@@ -14,6 +14,10 @@ Chat SDK adapters are the trust boundary between your application and a platform
 
 All adapters in this repo use [vitest](https://vitest.dev) with `@vitest/coverage-v8`. Community adapters should follow the same convention.
 
+<Callout type="info">
+This page covers the hand-rolled patterns used inside this repo's `packages/`. If you're testing a bot or a custom adapter as a **consumer** of Chat SDK, use [`@chat-adapter/tests`](/docs/testing) — it ships factories and Vitest matchers that cover most of these patterns in a few lines.
+</Callout>
+
 ## Unit tests
 
 ### Factory function