chat 4.26.0 → 4.28.1

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>',
+    },
   }}
 />
 
@@ -149,6 +153,10 @@ All adapters return `false` if the bot ID isn't known yet. This is a safe defaul
       description: 'Fetch the attachment data. Handles platform auth automatically.',
       type: '() => Promise<Buffer> | undefined',
     },
+    fetchMetadata: {
+      description: 'Platform-specific IDs for reconstructing fetchData after serialization (e.g. WhatsApp mediaId, Telegram fileId).',
+      type: 'Record<string, string> | undefined',
+    },
   }}
 />
 
@@ -196,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.
@@ -208,4 +265,4 @@ const json = message.toJSON();
 const restored = Message.fromJSON(json);
 ```
 
-The serialized format converts `Date` fields to ISO strings and omits non-serializable fields like `data` buffers and `fetchData` functions.
+The serialized format converts `Date` fields to ISO strings and omits non-serializable fields like `data` buffers and `fetchData` functions. The `fetchMetadata` field is preserved so that adapters can reconstruct `fetchData` when the message is rehydrated from a queue.

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.

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

@@ -4,7 +4,7 @@ description: Represents a conversation thread with methods for posting, subscrib
 type: reference
 ---
 
-A `Thread` is provided to your event handlers and represents a conversation thread on any platform. You don't create threads directly — they come from handler callbacks or `chat.openDM()`.
+A `Thread` is provided to your event handlers and represents a conversation thread on any platform. You can also create thread handles directly using `chat.thread()` or `chat.openDM()`.
 
 ## Properties
 
@@ -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.
 
@@ -114,6 +122,28 @@ await scheduled.cancel();
 Streaming and file uploads are not supported in scheduled messages.
 </Callout>
 
+## getParticipants
+
+Get the unique human participants in a thread. Returns deduplicated authors, excluding all bots. Useful for subscribing only to 1:1 conversations and unsubscribing when others join.
+
+```typescript
+const participants = await thread.getParticipants();
+
+// Subscribe only when one person is talking to the bot
+if (participants.length === 1) {
+  await thread.subscribe();
+}
+
+// Unsubscribe when the thread becomes a group conversation
+if (participants.length > 1) {
+  await thread.unsubscribe();
+}
+```
+
+<Callout type="warn">
+  Each call fetches the full message history to find all participants. On threads with long history this makes multiple API calls to the platform. Consider checking `message.author` against a known set before calling `getParticipants()` on every incoming message.
+</Callout>
+
 ## subscribe / unsubscribe
 
 Manage thread subscriptions. Subscribed threads route all messages to `onSubscribedMessage` handlers.

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.