chat 4.27.0 → 4.28.1

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.
@@ -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.
 

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

@@ -124,6 +124,10 @@ const bot = new Chat({
 | `debounceMs` | debounce | `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.

package/docs/contributing/building.mdx

@@ -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/conversation-history.mdx

@@ -0,0 +1,137 @@
+---
+title: Conversation History
+description: Persist messages per user across every platform — for LLM context, audit, or compliance.
+type: guide
+prerequisites:
+  - /docs/state
+related:
+  - /docs/handling-events
+  - /docs/api/transcripts
+---
+
+Bots that hold context across a user's conversations need somewhere to store it. The platform's own message history won't do — a user might talk to your bot in Slack today and Discord tomorrow, and you want the same memory to follow them.
+
+`bot.transcripts` keeps a per-user transcript in your state adapter, keyed by a stable identifier you choose (an email, an internal user ID, anything that's the same person no matter where they are).
+
+## Setup
+
+You opt in by setting two fields on `ChatConfig`:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createDiscordAdapter } from "@chat-adapter/discord";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    discord: createDiscordAdapter(),
+  },
+  state: createRedisState({ url: process.env.REDIS_URL! }),
+
+  // Resolve the cross-platform identifier for an inbound message.
+  // Return null for messages you don't want to remember.
+  identity: ({ author }) => author.email ?? null,
+
+  // Storage tuning. retention is the list TTL, refreshed on every append.
+  transcripts: {
+    retention: "30d",
+    maxPerUser: 200,
+  },
+});
+```
+
+`transcripts` and `identity` are paired — set one without the other and the constructor throws. This keeps the API loud rather than silently no-op'ing on every call.
+
+## Building LLM context
+
+The most common pattern: append the user's message, build a prompt from recent transcript entries, post the reply, append the reply too.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, msg) => {
+  await bot.transcripts.append(thread, msg);
+
+  const recent = await bot.transcripts.list({
+    userKey: msg.userKey!,
+    limit: 20,
+  });
+
+  const reply = await generateReply(recent, msg);
+  await thread.post(reply);
+
+  await bot.transcripts.append(
+    thread,
+    { role: "assistant", text: reply },
+    { userKey: msg.userKey! }
+  );
+});
+```
+
+A few things worth knowing:
+
+- **`msg.userKey`** is set automatically from your `identity` resolver before your handler runs. If the resolver returned `null`, it stays `undefined` and the `append` call no-ops.
+- **Bot replies are explicit.** The SDK doesn't auto-capture `thread.post()` output — you decide what gets remembered. That's important for retries, intermediate streaming chunks, and anything you don't want feeding back into the model later.
+- **Order is chronological.** `list` returns oldest-first, ready to feed into a model. Set `limit` to keep prompts bounded.
+
+## Identity resolution
+
+`identity` runs once per inbound message during dispatch. The `author`, `message`, and `adapter` name are all available:
+
+```typescript
+identity: async ({ adapter, author, message }) => {
+  // Look up by email when the platform exposes it
+  if (author.email) {
+    return author.email;
+  }
+  // Or map a platform user to an internal ID
+  return await lookupUser(adapter, author.userId);
+}
+```
+
+Return `null` when you can't resolve a key. The SDK won't fall back to a platform-specific ID — that would silently fragment a user's transcript across platforms, which is exactly what this feature is here to prevent.
+
+If your resolver throws, the SDK logs a warning and dispatches the message without a `userKey`. Handlers still run; only the persistence is skipped.
+
+## Filtering entries
+
+`list` accepts a few filters. They compose, and they're applied after `getList` — useful for narrowing prompts without restructuring storage.
+
+```typescript
+// Recent N across all platforms
+await bot.transcripts.list({ userKey: "mike@acme.com", limit: 50 });
+
+// Single platform
+await bot.transcripts.list({ userKey: "mike@acme.com", platforms: ["slack"] });
+
+// Single thread
+await bot.transcripts.list({
+  userKey: "mike@acme.com",
+  threadId: "slack:C123:1234.5678",
+});
+
+// Only the user's own messages
+await bot.transcripts.list({ userKey: "mike@acme.com", roles: ["user"] });
+```
+
+## Deleting a user's transcript
+
+For data-subject requests or simple "forget me" flows:
+
+```typescript
+await bot.transcripts.delete({ userKey: "mike@acme.com" });
+// → { deleted: 47 }
+```
+
+This wipes every entry stored under the key. Single-entry and time-range deletes aren't part of the API — `appendToList` doesn't support them safely under concurrent writes.
+
+## Where it's stored
+
+`bot.transcripts` is backed by `StateAdapter.appendToList` / `getList` / `delete`. Every built-in state adapter (`memory`, `redis`, `ioredis`, `pg`) supports these primitives, so this works on whichever one you've already configured.
+
+Entries are written under the key `transcripts:user:{userKey}` as a capped list. `appendToList` is atomic, so concurrent inbound messages on the same user don't race.
+
+## Reference
+
+See [Transcripts](/docs/api/transcripts) for full type signatures, configuration options, and the entry shape.

package/docs/direct-messages.mdx

@@ -1,12 +1,12 @@
 ---
-title: Direct messages
+title: Direct Messages
 description: Initiate DM conversations with users programmatically.
 type: guide
 prerequisites:
   - /docs/usage
 ---
 
-Open direct message conversations with users using `bot.openDM()`. The adapter is automatically inferred from the user ID format.
+Open direct message conversations with users using `bot.openDM()`. For globally recognizable user IDs, the adapter is automatically inferred from the ID format.
 
 ## DM behavior
 
@@ -40,10 +40,19 @@ const dmThread = await bot.openDM("U1234567890"); // Slack
 
 | Format | Platform |
 |--------|----------|
-| `U...` | Slack |
+| `U...` / `W...` | Slack |
 | `29:...` | Teams |
 | `users/...` | Google Chat |
-| Snowflake (numeric) | Discord |
+| Numeric ID | Discord or Telegram |
+
+<Callout type="info">
+  Numeric IDs can be ambiguous when multiple numeric-ID adapters are registered. For platforms whose user IDs are not globally distinguishable, call the adapter directly and wrap the returned thread ID with `bot.thread()`.
+</Callout>
+
+```typescript title="lib/bot.ts"
+const threadId = await bot.getAdapter("whatsapp").openDM("15551234567");
+const dmThread = bot.thread(threadId);
+```
 
 ## Check if a thread is a DM
 

package/docs/ephemeral-messages.mdx

@@ -1,5 +1,5 @@
 ---
-title: Ephemeral messages
+title: Ephemeral Messages
 description: Send messages visible only to a specific user.
 type: guide
 prerequisites:

package/docs/error-handling.mdx

@@ -1,5 +1,5 @@
 ---
-title: Error handling
+title: Error Handling
 description: Handle rate limits, unsupported features, and other errors from adapters.
 type: guide
 prerequisites:
@@ -16,7 +16,19 @@ import { ChatError, RateLimitError, NotImplementedError, LockError } from "chat"
 
 ### ChatError
 
-Base error class for all SDK errors. Every error below extends `ChatError`.
+Base error class for all SDK errors. Every error below extends `ChatError`. The `code` property carries a machine-readable identifier you can branch on:
+
+| Code | Thrown by | Meaning |
+|------|-----------|---------|
+| `NOT_SUPPORTED` | `bot.openDM`, `bot.getUser` | The resolved adapter doesn't implement this method |
+| `INVALID_THREAD_ID` | `bot.thread`, internal routing | Thread ID does not match the `adapter:channel:thread` shape |
+| `INVALID_CHANNEL_ID` | `bot.channel` | Channel ID does not match the `adapter:channel` shape |
+| `ADAPTER_NOT_FOUND` | `bot.thread`, `bot.channel` | Thread/channel ID references an adapter that wasn't registered on this `Chat` instance |
+| `AMBIGUOUS_USER_ID` | `bot.getUser`, `bot.openDM` | Numeric user ID could match more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | `bot.getUser`, `bot.openDM` | The `userId` doesn't match any platform's known ID format |
+| `RATE_LIMITED` | Any platform call | Platform returned 429; see `RateLimitError` below |
+| `NOT_IMPLEMENTED` | Any platform call | The adapter doesn't implement this feature; see `NotImplementedError` below |
+| `LOCK_FAILED` | Inbound message routing | Distributed lock was busy; see `LockError` below |
 
 <TypeTable
   type={{
@@ -25,7 +37,7 @@ Base error class for all SDK errors. Every error below extends `ChatError`.
       type: 'string',
     },
     code: {
-      description: 'Machine-readable error code.',
+      description: 'Machine-readable error code (see table above).',
       type: 'string',
     },
     cause: {

package/docs/files.mdx

@@ -1,5 +1,5 @@
 ---
-title: File uploads
+title: File Uploads
 description: Send and receive files across chat platforms.
 type: guide
 prerequisites: