chat 4.27.0 → 4.28.1

package/dist/{jsx-runtime-Co9uV6l7.d.ts → jsx-runtime-DxGwoLu2.d.ts}

@@ -52,6 +52,8 @@ type TextStyle = "plain" | "bold" | "muted";
 interface ButtonElement {
     /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */
     actionType?: "action" | "modal";
+    /** URL to POST action data to when this button is clicked */
+    callbackUrl?: string;
     /** If true, the button is displayed in an inactive state and doesn't respond to user actions */
     disabled?: boolean;
     /** Unique action ID for callback routing */
@@ -241,6 +243,8 @@ declare function Actions(children: (ButtonElement | LinkButtonElement | SelectEl
 interface ButtonOptions {
     /** Whether this button triggers a regular action or opens a modal dialog. Default: "action" */
     actionType?: "action" | "modal";
+    /** URL to POST action data to when this button is clicked */
+    callbackUrl?: string;
     /** If true, the button is displayed in an inactive state and doesn't respond to user actions */
     disabled?: boolean;
     /** Unique action ID for callback routing */
@@ -374,6 +378,8 @@ declare function cardChildToFallbackText(child: CardChild): string | null;
 type ModalChild = TextInputElement | SelectElement | ExternalSelectElement | RadioSelectElement | TextElement | FieldsElement;
 interface ModalElement {
     callbackId: string;
+    /** URL to POST form values to when this modal is submitted */
+    callbackUrl?: string;
     children: ModalChild[];
     closeLabel?: string;
     notifyOnClose?: boolean;
@@ -427,6 +433,8 @@ interface RadioSelectElement {
 declare function isModalElement(value: unknown): value is ModalElement;
 interface ModalOptions {
     callbackId: string;
+    /** URL to POST form values to when this modal is submitted */
+    callbackUrl?: string;
     children?: ModalChild[];
     closeLabel?: string;
     notifyOnClose?: boolean;
@@ -527,6 +535,7 @@ interface TextProps {
 /** Props for Button component in JSX */
 interface ButtonProps {
     actionType?: "action" | "modal";
+    callbackUrl?: string;
     children?: string | number | (string | number | undefined)[];
     disabled?: boolean;
     id: string;
@@ -566,6 +575,7 @@ type DividerProps = Record<string, never>;
 /** Props for Modal component in JSX */
 interface ModalProps {
     callbackId: string;
+    callbackUrl?: string;
     children?: unknown;
     closeLabel?: string;
     notifyOnClose?: boolean;

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { A as ActionsComponent, B as ButtonComponent, X as ButtonProps, c as CardComponent, Y as CardJSXElement, Z as CardJSXProps, e as CardLinkComponent, _ as CardLinkProps, $ as CardProps, C as ChatElement, a0 as ContainerProps, D as DividerComponent, a1 as DividerProps, E as ExternalSelectComponent, a2 as ExternalSelectProps, F as FieldComponent, a3 as FieldProps, f as FieldsComponent, ar as Fragment, I as ImageComponent, a4 as ImageProps, as as JSX, L as LinkButtonComponent, a5 as LinkButtonProps, o as ModalComponent, a6 as ModalProps, R as RadioSelectComponent, j as SectionComponent, p as SelectComponent, q as SelectOptionComponent, a7 as SelectOptionProps, a8 as SelectProps, am as TableComponent, al as TableProps, T as TextComponent, r as TextInputComponent, a9 as TextInputProps, aa as TextProps, an as isCardLinkProps, h as isJSX, ao as jsx, aq as jsxDEV, ap as jsxs, t as toCardElement, l as toModalElement } from './jsx-runtime-Co9uV6l7.js';
+export { A as ActionsComponent, B as ButtonComponent, X as ButtonProps, c as CardComponent, Y as CardJSXElement, Z as CardJSXProps, e as CardLinkComponent, _ as CardLinkProps, $ as CardProps, C as ChatElement, a0 as ContainerProps, D as DividerComponent, a1 as DividerProps, E as ExternalSelectComponent, a2 as ExternalSelectProps, F as FieldComponent, a3 as FieldProps, f as FieldsComponent, ar as Fragment, I as ImageComponent, a4 as ImageProps, as as JSX, L as LinkButtonComponent, a5 as LinkButtonProps, o as ModalComponent, a6 as ModalProps, R as RadioSelectComponent, j as SectionComponent, p as SelectComponent, q as SelectOptionComponent, a7 as SelectOptionProps, a8 as SelectProps, am as TableComponent, al as TableProps, T as TextComponent, r as TextInputComponent, a9 as TextInputProps, aa as TextProps, an as isCardLinkProps, h as isJSX, ao as jsx, aq as jsxDEV, ap as jsxs, t as toCardElement, l as toModalElement } from './jsx-runtime-DxGwoLu2.js';

package/dist/jsx-runtime.js

@@ -7,7 +7,7 @@ import {
   jsxs,
   toCardElement,
   toModalElement
-} from "./chunk-AN7MRAVW.js";
+} from "./chunk-V25FKIIL.js";
 export {
   Fragment,
   isCardLinkProps,

package/docs/actions.mdx

@@ -94,5 +94,56 @@ bot.onAction("feedback", async (event) => {
 ```
 
 <Callout type="info">
-Modals are currently supported on Slack. Other platforms will receive a no-op or fallback behavior.
+  Modals are currently supported on Slack and Teams. Other platforms will receive a no-op
+  or fallback behavior.
 </Callout>
+
+## Callback URLs
+
+Buttons accept a `callbackUrl` prop. When clicked, the action data is POSTed to that URL in addition to firing any `onAction` handler. This pairs naturally with webhook-based workflow engines to build approval flows without any `onAction` handler at all:
+
+```tsx title="lib/bot.tsx" lineNumbers
+bot.onNewMention(async (thread) => {
+  const approveUrl = "https://example.com/webhook/approve";
+  const denyUrl = "https://example.com/webhook/deny";
+
+  await thread.post(
+    <Card title="Deploy v2.4.1?">
+      <Actions>
+        <Button callbackUrl={approveUrl} id="approve" style="primary">
+          Approve
+        </Button>
+        <Button callbackUrl={denyUrl} id="deny" style="danger">
+          Deny
+        </Button>
+      </Actions>
+    </Card>
+  );
+});
+```
+
+### Callback payload
+
+The POST body sent to the `callbackUrl`:
+
+```json
+{
+  "type": "action",
+  "actionId": "approve",
+  "user": { "id": "U123", "name": "alice" },
+  "threadId": "slack:C123:1234567890.123",
+  "messageId": "1234567890.456"
+}
+```
+
+If the button also has a `value` prop, it is included in the payload as `"value"`.
+
+<Callout type="info">
+  Platform limits apply to encoded button data. Discord's `custom_id` has a 100
+  character limit - if the action ID plus callback token exceed this, posting
+  the card throws a `ValidationError`. Telegram's `callback_data` has a 64 byte
+  limit - buttons that exceed this will throw a `ValidationError`. Keep action
+  IDs short when using `callbackUrl` on these platforms.
+</Callout>
+
+For modals, see [callbackUrl on modals](/docs/modals#callback-urls).

package/docs/adapters.mdx

@@ -8,57 +8,63 @@ prerequisites:
 
 Adapters handle webhook verification, message parsing, and API calls for each platform. Install only the adapters you need. Browse all available adapters — including community-built ones — on the [Adapters](/adapters) page.
 
+Need a browser chat UI? See the [Web adapter](/adapters/web) — it speaks the AI SDK `useChat` protocol so the same bot serves Slack, Teams, **and** a `<Conversation>` from `ai-elements` out of the box.
+
 Ready to build your own? Follow the [building](/docs/contributing/building) guide.
 
 ## Feature matrix
 
 ### Messaging
 
-| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) |
-|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|
-| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
-| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
-| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
-| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs |
-| Streaming | <Check /> Native | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Cross /> | <Cross /> | <Cross /> |
-| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Feature | [Slack](/adapters/slack) | [Teams](/adapters/teams) | [Google Chat](/adapters/google-chat) | [Discord](/adapters/discord) | [Telegram](/adapters/telegram) | [GitHub](/adapters/github) | [Linear](/adapters/linear) | [WhatsApp](/adapters/whatsapp) | [Messenger](/adapters/messenger) |
+|---------|-------|-------|-------------|---------|---------|--------|--------|-----------|-----------|
+| Post message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Edit message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| Delete message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Partial | <Cross /> | <Cross /> |
+| File uploads | <Check /> | <Check /> | <Cross /> | <Check /> | <Warn /> Single file | <Cross /> | <Cross /> | <Check /> Images, audio, docs | <Cross /> |
+| Streaming | <Check /> Native | <Warn /> Native (DMs) / Buffered | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Post+Edit | <Warn /> Buffered | <Warn /> Agent sessions / Post+Edit | <Warn /> Buffered | <Warn /> Buffered |
+| Scheduled messages | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Rich content
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates |
-| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies |
-| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> |
-| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
-| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Check /> GFM | <Cross /> |
-| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables |
-| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> |
-| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | Markdown + inline keyboard buttons | GFM Markdown | Markdown | WhatsApp templates | Generic/Button Templates |
+| Buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard callbacks | <Cross /> | <Cross /> | <Check /> Interactive replies | <Warn /> Max 3, postback |
+| Link buttons | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Inline keyboard URLs | <Cross /> | <Cross /> | <Cross /> | <Check /> |
+| Select menus | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Tables | <Check /> Block Kit | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Warn /> ASCII | <Check /> GFM | <Check /> GFM | <Cross /> | <Warn /> ASCII |
+| Fields | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Template variables | <Warn /> ASCII |
+| Images in cards | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> |
+| Modals | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
 
 ### Conversations
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
-| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
-| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
-| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Cross /> |
-| Typing indicator | <Cross /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
-| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
-| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Slash commands | <Check /> | <Cross /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| Mentions | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> |
+| Add reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
+| Remove reactions | <Check /> | <Cross /> | <Check /> | <Check /> | <Check /> | <Warn /> | <Warn /> | <Check /> | <Cross /> |
+| Typing indicator | <Check /> | <Check /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Warn /> Agent sessions | <Cross /> | <Check /> |
+| DMs | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
+| Ephemeral messages | <Check /> Native | <Cross /> | <Check /> Native | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> |
+| User lookup ([`getUser`](/docs/api/chat#getuser)) | <Check /> | <Warn /> Cached | <Warn /> Cached | <Check /> | <Warn /> Seen users | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Parent subject ([`message.subject`](/docs/subject)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Native client ([`.client`](/docs/api/chat#getadapter)) | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Cross /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
+| Custom API endpoint (`apiUrl`) | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
 
 ### Message history
 
-| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp |
-|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|
-| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only |
-| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Warn /> Cached sent messages only |
-| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> |
-| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Warn /> Cached sent messages only |
-| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> |
-| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> |
-| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Feature | Slack | Teams | Google Chat | Discord | Telegram | GitHub | Linear | WhatsApp | Messenger |
+|---------|-------|-------|-------------|---------|----------|--------|--------|-----------|-----------|
+| Fetch messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Check /> | <Warn /> Cached sent messages only | <Warn /> Cached sent messages only |
+| Fetch single message | <Check /> | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached | <Cross /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| Fetch thread info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> |
+| Fetch channel messages | <Check /> | <Check /> | <Check /> | <Check /> | <Warn /> Cached | <Check /> | <Cross /> | <Cross /> | <Warn /> Cached |
+| List threads | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Check /> | <Cross /> | <Cross /> | <Cross /> |
+| Fetch channel info | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> |
+| Post channel message | <Check /> | <Check /> | <Check /> | <Check /> | <Check /> | <Cross /> | <Cross /> | <Check /> | <Check /> |
 
 <Callout type="info">
 <Warn /> indicates partial support — the feature works with limitations. See individual adapter pages for details.

package/docs/api/cards.mdx

@@ -100,6 +100,10 @@ Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
       type: '"action" | "modal"',
       default: '"action"',
     },
+    callbackUrl: {
+      description: 'URL to POST action data to when this button is clicked.',
+      type: 'string',
+    },
   }}
 />
 

package/docs/api/chat.mdx

@@ -168,7 +168,9 @@ Fires when a user clicks a button or selects an option in a card.
 ```typescript
 // Single action
 bot.onAction("approve", async (event) => {
-  await event.thread.post("Approved!");
+  if (event.thread) {
+    await event.thread.post("Approved!");
+  }
 });
 
 // Multiple actions
@@ -193,8 +195,8 @@ bot.onAction(async (event) => { /* ... */ });
       type: 'Author',
     },
     'event.thread': {
-      description: 'The thread containing the card.',
-      type: 'Thread',
+      description: 'The thread containing the card, or null for view-based actions.',
+      type: 'Thread | null',
     },
     'event.triggerId': {
       description: 'Trigger ID for opening modals (platform-specific, may expire quickly).',
@@ -261,9 +263,47 @@ Returns `ModalResponse | undefined` to control the modal after submission:
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack
 
+### onOptionsLoad
+
+Fires when an `ExternalSelect` requests options dynamically. The handler is keyed on the select's `id` and must return options synchronously enough for Slack's 3-second budget (the adapter caps the loader at ~2.5s and substitutes an empty result on timeout). Slack-only.
+
+```typescript
+bot.onOptionsLoad("assignee", async (event) => {
+  const people = await peopleService.search(event.query);
+  return people.map((p) => ({ label: p.fullName, value: p.id }));
+});
+```
+
+Return an array of `OptionsLoadGroup` (`{ label, options }[]`) instead of a flat array to render grouped headers (e.g. "Recent" / "All"). Slack limits: max 100 groups, max 100 options per group.
+
+<TypeTable
+  type={{
+    'event.actionId': {
+      description: 'The id of the select requesting options (matches the id passed to bot.onOptionsLoad).',
+      type: 'string',
+    },
+    'event.query': {
+      description: 'The text the user has typed so far.',
+      type: 'string',
+    },
+    'event.user': {
+      description: 'The user requesting options.',
+      type: 'Author',
+    },
+    'event.adapter': {
+      description: 'The adapter that received this event.',
+      type: 'Adapter',
+    },
+    'event.raw': {
+      description: 'Raw platform-specific payload.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ### onSlashCommand
 
-Fires when a user invokes a `/command` in the message composer. Currently supported on Slack.
+Fires when a user invokes a `/command` in the message composer. Currently supported on Slack and Discord.
 
 ```typescript
 // Specific command
@@ -426,12 +466,42 @@ bot.webhooks.teams(request, { waitUntil });
 
 ### getAdapter
 
-Get an adapter instance by name.
+Get a typed adapter instance by name.
 
 ```typescript
 const slack = bot.getAdapter("slack");
 ```
 
+#### Direct client access
+
+Use `.client` to access the platform's typed native API client directly — available on Linear and GitHub:
+
+```typescript
+// Linear - full LinearClient from @linear/sdk
+const linear = bot.getAdapter("linear").client;
+const issue = await linear.issue("ENG-123");
+const project = await issue.project;
+
+// GitHub - full Octokit from @octokit/rest
+const github = bot.getAdapter("github").client;
+const { data: pulls } = await github.rest.pulls.list({
+  owner: "vercel",
+  repo: "chat",
+  state: "open",
+});
+```
+
+The client uses the credentials from your adapter config. For multi-tenant adapters (Linear, GitHub), it returns the client for the current webhook request context.
+
+<Callout type="warn">
+  For multi-tenant adapters (GitHub App without a fixed installation ID, Linear with per-org OAuth), `client` requires webhook handler context to resolve credentials. Calling it outside a handler throws. Single-tenant adapters (PAT, API key) work anywhere.
+</Callout>
+
+| Adapter | `client` type |
+|---------|---------------|
+| Linear | `LinearClient` from `@linear/sdk` |
+| GitHub | `Octokit` from `@octokit/rest` |
+
 ### openDM
 
 Open a direct message thread with a user.
@@ -498,10 +568,16 @@ const user = await bot.getUser(message.author);
   - **GitHub** — `email` is `null` unless the user made it public, or you authenticated with the `user:email` scope.
   - **Linear** — full profile (incl. email + avatar) for any active workspace member.
 
-  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — call the platform's adapter directly (`adapter.getUser(userId)`) in that case.
+  Fields that aren't available return `undefined`. Numeric user IDs (Discord/Telegram/GitHub) can be ambiguous when multiple of those adapters are registered — `bot.getUser` throws a `ChatError` with code `AMBIGUOUS_USER_ID` in that case. Pass an `Author` from a message handler (which already carries the adapter), or call the adapter directly (`adapter.getUser(userId)`).
 </Callout>
 
-Adapters that don't support user lookups will throw a `ChatError` with code `NOT_SUPPORTED`. Handle both cases if your bot runs on multiple platforms:
+`bot.getUser` throws a `ChatError` in three cases. Handle them if your bot runs on multiple platforms:
+
+| Code | When |
+|------|------|
+| `NOT_SUPPORTED` | The resolved adapter doesn't implement `getUser` (e.g. WhatsApp) |
+| `AMBIGUOUS_USER_ID` | A numeric user ID could belong to more than one registered adapter (Discord/Telegram/GitHub) |
+| `UNKNOWN_USER_ID_FORMAT` | The `userId` string doesn't match any registered platform's ID format |
 
 ```typescript
 import { ChatError } from "chat";
@@ -512,8 +588,14 @@ try {
     // User not found on this platform
   }
 } catch (error) {
-  if (error instanceof ChatError && error.code === "NOT_SUPPORTED") {
-    // This adapter doesn't support user lookups
+  if (error instanceof ChatError) {
+    if (error.code === "NOT_SUPPORTED") {
+      // This adapter doesn't support user lookups
+    } else if (error.code === "AMBIGUOUS_USER_ID") {
+      // Pass message.author or call adapter.getUser(userId) directly
+    } else if (error.code === "UNKNOWN_USER_ID_FORMAT") {
+      // userId doesn't match any known platform format
+    }
   }
 }
 ```

package/docs/api/index.mdx

@@ -31,6 +31,8 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | Export | Description |
 |--------|-------------|
 | [`PostableMessage`](/docs/api/postable-message) | Union type accepted by `thread.post()` |
+| [`Plan`](/docs/api/postable-message#plan) | Step-by-step task list that mutates after posting |
+| [`StreamingPlan`](/docs/api/postable-message#streamingplan) | Wraps an async iterable with platform-specific streaming options |
 | [`Cards`](/docs/api/cards) | Rich card components — `Card`, `Text`, `Button`, `Actions`, etc. |
 | [`Markdown`](/docs/api/markdown) | AST builder functions — `root`, `paragraph`, `text`, `strong`, etc. |
 | [`Modals`](/docs/api/modals) | Modal form components — `Modal`, `TextInput`, `Select`, etc. |

package/docs/api/markdown.mdx

@@ -15,6 +15,25 @@ import {
 } from "chat";
 ```
 
+## Type re-exports
+
+The chat package re-exports mdast's union and content types so adapters and downstream code can build exhaustively-typed AST walkers without depending on `mdast` directly:
+
+```typescript
+import type { Nodes, Root, Content } from "chat";
+
+function render(node: Nodes): string {
+  switch (node.type) {
+    case "text": return node.value;
+    case "strong": return node.children.map(render).join("");
+    // ...
+    default: throw new Error(`Unhandled: ${node satisfies never}`);
+  }
+}
+```
+
+Adapters use this pattern to make the type checker reject the build when a new mdast node type is introduced upstream.
+
 ## Node builders
 
 ### root
@@ -222,7 +241,7 @@ const value = getNodeValue(node);       // string | undefined
 
 ### tableToAscii
 
-Render an mdast `Table` node as a padded ASCII table string. Used by adapters that lack native table support (Slack, Google Chat, Discord, Telegram).
+Render an mdast `Table` node as a padded ASCII table string. Used by adapters that lack native table support (Google Chat, Discord, Telegram).
 
 ```typescript
 import { parseMarkdown, tableToAscii, isTableNode } from "chat";
@@ -261,17 +280,21 @@ The SDK uses mdast as the canonical format and each adapter converts it to the p
 
 | Feature | Slack | Teams | Google Chat |
 |---------|-------|-------|-------------|
-| Bold | `*text*` | `**text**` | `*text*` |
+| Bold | `**text**` | `**text**` | `*text*` |
 | Italic | `_text_` | `_text_` | `_text_` |
-| Strikethrough | `~text~` | `~~text~~` | `~text~` |
+| Strikethrough | `~~text~~` | `~~text~~` | `~text~` |
 | Code | `` `code` `` | `` `code` `` | `` `code` `` |
 | Code blocks | ```` ``` ```` | ```` ``` ```` | ```` ``` ```` |
-| Links | `<url\|text>` | `[text](url)` | `[text](url)` |
+| Links | `[text](url)` | `[text](url)` | `[text](url)` |
 | Lists | Supported | Supported | Supported |
 | Blockquotes | `>` | `>` | Simulated with `>` prefix |
-| Tables | ASCII fallback | Native GFM | ASCII fallback |
+| Tables | Native (markdown_text) | Native GFM | ASCII fallback |
 | Mentions | `<@USER>` | `<at>name</at>` | `<users/{id}>` |
 
+<Callout type="info">
+Slack accepts standard markdown via the `markdown_text` field on `chat.postMessage` and friends, so the SDK passes markdown through directly. Incoming Slack messages still arrive as legacy mrkdwn (`*bold*`, `<url|text>`) and are parsed transparently. If you need to send mrkdwn yourself, use `{ raw: "..." }`.
+</Callout>
+
 <Callout type="info">
 You don't need to worry about these differences when using the SDK — the AST builders and `parseMarkdown` handle conversion automatically. This table is useful if you're working with `raw` platform payloads or debugging formatting issues.
 </Callout>

package/docs/api/message.mdx

@@ -54,6 +54,10 @@ import { Message } from "chat";
       description: 'Whether the bot was @-mentioned in this message.',
       type: 'boolean | undefined',
     },
+    subject: {
+      description: 'Resolves the parent resource (issue, PR) this message is about. Returns null on chat platforms. See [Message Subject](/docs/subject).',
+      type: 'Promise<MessageSubject | null>',
+    },
   }}
 />
 
@@ -200,6 +204,55 @@ When using [`toAiMessages()`](/docs/api/to-ai-messages), link metadata is automa
 | Slack | URLs from `rich_text` blocks or `<url>` text patterns | Slack message links (`*.slack.com/archives/...`) |
 | Others | Not yet — `links` is always `[]` | — |
 
+## MessageSubject
+
+Returned by `message.subject` on platforms with parent resources. See [Message Subject](/docs/subject) for usage.
+
+<TypeTable
+  type={{
+    type: {
+      description: 'Resource kind, e.g. "issue" or "pull_request".',
+      type: 'string',
+    },
+    id: {
+      description: 'Resource identifier (e.g. "ENG-123" or "42").',
+      type: 'string',
+    },
+    title: {
+      description: 'Resource title.',
+      type: 'string | undefined',
+    },
+    description: {
+      description: 'Full description/body in markdown.',
+      type: 'string | undefined',
+    },
+    status: {
+      description: 'Current status (e.g. "In Progress", "open").',
+      type: 'string | undefined',
+    },
+    url: {
+      description: 'Web URL to the resource.',
+      type: 'string | undefined',
+    },
+    author: {
+      description: 'Resource creator.',
+      type: '{ id: string; name: string } | undefined',
+    },
+    assignee: {
+      description: 'Current assignee.',
+      type: '{ id: string; name: string } | undefined',
+    },
+    labels: {
+      description: 'Labels/tags.',
+      type: 'string[] | undefined',
+    },
+    raw: {
+      description: 'Full platform API response.',
+      type: 'unknown',
+    },
+  }}
+/>
+
 ## Serialization
 
 Messages can be serialized for workflow engines and external systems.

package/docs/api/meta.json

@@ -6,7 +6,9 @@
     "thread",
     "channel",
     "message",
+    "to-ai-messages",
     "postable-message",
+    "transcripts",
     "cards",
     "markdown",
     "modals"

package/docs/api/modals.mdx

@@ -54,6 +54,10 @@ bot.onAction("open-form", async (event) => {
       type: 'boolean',
       default: 'false',
     },
+    callbackUrl: {
+      description: 'URL to POST form values to when the modal is submitted.',
+      type: 'string',
+    },
     privateMetadata: {
       description: 'Arbitrary string passed through the modal lifecycle (e.g., JSON context).',
       type: 'string',
@@ -167,6 +171,52 @@ Select({
   }}
 />
 
+## ExternalSelect
+
+Dropdown that loads options dynamically from a handler as the user types. Slack-only. Pair with [`bot.onOptionsLoad`](/docs/api/chat#onoptionsload) to supply options. See [Modals → ExternalSelect](/docs/modals#externalselect) for a full example, grouped-options support, and Slack setup notes.
+
+```typescript
+ExternalSelect({
+  id: "assignee",
+  label: "Assignee",
+  placeholder: "Search people",
+  minQueryLength: 1,
+  initialOption: { label: "Alice", value: "U123" },
+})
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Input ID — used as the key in event.values.',
+      type: 'string',
+    },
+    label: {
+      description: 'Label displayed above the select.',
+      type: 'string',
+    },
+    placeholder: {
+      description: 'Placeholder text.',
+      type: 'string',
+    },
+    minQueryLength: {
+      description: 'Minimum characters before the loader fires (Slack default: 3).',
+      type: 'number',
+    },
+    initialOption: {
+      description: 'Pre-selected option when the modal opens. Unlike static Select where initialOption is a value string, ExternalSelect needs the full label/value object since the loader has not run yet.',
+      type: '{ label: string, value: string }',
+    },
+    optional: {
+      description: 'Whether the field can be left empty.',
+      type: 'boolean',
+      default: 'false',
+    },
+  }}
+/>
+
+The loader registered via `bot.onOptionsLoad("assignee", handler)` returns either a flat `SelectOptionElement[]` or `OptionsLoadGroup[]` (`{ label, options }[]`) for grouped options.
+
 ## RadioSelect
 
 Radio button group for mutually exclusive choices.