chat 4.27.0 → 4.28.1

package/docs/index.mdx

@@ -4,7 +4,7 @@ description: A unified SDK for building chat bots across Slack, Microsoft Teams,
 type: overview
 ---
 
-Chat SDK is a TypeScript library for building chat bots that work across multiple platforms with a single codebase. Write your bot logic once and deploy it to Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp.
+Chat SDK is a TypeScript library for building chat bots that work across multiple platforms with a single codebase. Write your bot logic once and deploy it to Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear, WhatsApp, and Messenger.
 
 ## Why Chat SDK?
 
@@ -52,13 +52,14 @@ Each adapter factory auto-detects credentials from environment variables (`SLACK
 | Platform | Package | Mentions | Reactions | Cards | Modals | Streaming | DMs |
 |----------|---------|----------|-----------|-------|--------|-----------|-----|
 | Slack | `@chat-adapter/slack` | Yes | Yes | Yes | Yes | Native | Yes |
-| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | No | Post+Edit | Yes |
+| Microsoft Teams | `@chat-adapter/teams` | Yes | Read-only | Yes | Yes | Native (DMs) / Buffered | Yes |
 | Google Chat | `@chat-adapter/gchat` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Discord | `@chat-adapter/discord` | Yes | Yes | Yes | No | Post+Edit | Yes |
 | Telegram | `@chat-adapter/telegram` | Yes | Yes | Partial | No | Post+Edit | Yes |
-| GitHub | `@chat-adapter/github` | Yes | Yes | No | No | No | No |
-| Linear | `@chat-adapter/linear` | Yes | Yes | No | No | No | No |
-| WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | No | Yes |
+| GitHub | `@chat-adapter/github` | Yes | Yes | No | No | Buffered | No |
+| Linear | `@chat-adapter/linear` | Yes | Yes | No | No | Agent sessions / Post+Edit | No |
+| WhatsApp | `@chat-adapter/whatsapp` | N/A | Yes | Partial | No | Buffered | Yes |
+| Messenger | `@chat-adapter/messenger` | Yes | Receive-only | Partial | No | Buffered | Yes |
 
 ## AI coding agent support
 
@@ -85,6 +86,7 @@ The SDK is distributed as a set of packages you install based on your needs:
 | `@chat-adapter/github` | GitHub Issues adapter |
 | `@chat-adapter/linear` | Linear Issues adapter |
 | `@chat-adapter/whatsapp` | WhatsApp Business adapter |
+| `@chat-adapter/messenger` | Facebook Messenger adapter |
 | `@chat-adapter/state-redis` | Redis state adapter (production) |
 | `@chat-adapter/state-ioredis` | ioredis state adapter (alternative) |
 | `@chat-adapter/state-pg` | PostgreSQL state adapter (production) |

package/docs/meta.json

@@ -8,13 +8,24 @@
     "threads-messages-channels",
     "handling-events",
     "posting-messages",
+    "error-handling",
     "---Adapters---",
     "adapters",
     "state",
-    "---Features---",
+    "---Messaging---",
+    "streaming",
+    "direct-messages",
+    "ephemeral-messages",
+    "files",
+    "conversation-history",
+    "subject",
     "concurrency",
-    "...",
-    "error-handling",
+    "---Interactivity---",
+    "cards",
+    "modals",
+    "actions",
+    "slash-commands",
+    "emoji",
     "---API Reference---",
     "...api",
     "---Contributing---",

package/docs/modals.mdx

@@ -59,6 +59,7 @@ The top-level container for the form.
 | `submitLabel` | `string` (optional) | Submit button text (defaults to "Submit") |
 | `closeLabel` | `string` (optional) | Cancel button text (defaults to "Cancel") |
 | `notifyOnClose` | `boolean` (optional) | Fire `onModalClose` when user cancels |
+| `callbackUrl` | `string` (optional) | URL to POST form values to on submit |
 | `privateMetadata` | `string` (optional) | Custom context passed through to handlers |
 
 ### TextInput
@@ -248,6 +249,29 @@ bot.onModalClose("feedback_form", async (event) => {
 });
 ```
 
+## Callback URLs
+
+Like buttons, modals accept a `callbackUrl`. When the modal is submitted, the form values are POSTed to the URL:
+
+```tsx title="lib/bot.tsx" lineNumbers
+await event.openModal(
+  <Modal callbackUrl={webhook.url} callbackId="intake" title="Request Access" submitLabel="Submit">
+    <TextInput id="reason" label="Reason" multiline />
+  </Modal>
+);
+```
+
+The POST body for modal submissions:
+
+```json
+{
+  "type": "modal_submit",
+  "callbackId": "intake",
+  "values": { "reason": "Need access to production logs" },
+  "user": { "id": "U123", "name": "alice" }
+}
+```
+
 ## Pass context with privateMetadata
 
 Use `privateMetadata` to carry context from the button click through to the submit handler:

package/docs/posting-messages.mdx

@@ -24,7 +24,7 @@ This sends the string directly without any formatting conversion.
 
 ## Markdown
 
-Pass a `{ markdown }` object to have the SDK convert standard markdown to each platform's native format — mrkdwn for Slack, HTML for Teams, and so on.
+Pass a `{ markdown }` object to have the SDK render standard markdown on each platform — passed through to Slack's native `markdown_text` field, converted to HTML for Teams, and so on.
 
 ```typescript title="lib/bot.ts" lineNumbers
 await thread.post({
@@ -32,7 +32,7 @@ await thread.post({
 });
 ```
 
-Under the hood, the SDK parses the markdown into an mdast AST, then each adapter converts it to the platform's format.
+Under the hood, the SDK parses the markdown into an mdast AST, then each adapter handles it natively or converts it to the platform's format.
 
 ## AST builders
 
@@ -139,7 +139,7 @@ See the [Cards](/docs/cards) page for the full list of card components.
 
 ## Streaming
 
-Pass an AI SDK stream to `thread.post()` to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit on other platforms.
+Pass an AI SDK stream to `thread.post()` to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit or buffered delivery depending on the platform.
 
 ```typescript title="lib/bot.ts" lineNumbers
 import { ToolLoopAgent } from "ai";
@@ -153,6 +153,8 @@ Both `fullStream` and `textStream` are supported. Use `fullStream` with multi-st
 
 For multi-turn conversations, use [`toAiMessages()`](/docs/api/to-ai-messages) to convert thread history into the `{ role, content }[]` format expected by AI SDKs.
 
+To pass platform-specific streaming options (e.g. Slack task grouping or stop blocks), wrap the stream in a [`StreamingPlan`](/docs/streaming#streaming-with-options) and post that.
+
 See the [Streaming](/docs/streaming) page for details on platform behavior and configuration.
 
 ## Attachments and files
@@ -178,5 +180,7 @@ See the [Files](/docs/files) page for more on attachments.
 | Card (function) | You need buttons, fields, or structured layouts | Approval flows, dashboards |
 | Card (JSX) | Same as above, with JSX syntax preference | Same use cases as function cards |
 | `AsyncIterable` | Streaming AI responses | Chat with LLMs |
+| [`Plan`](/docs/streaming#plan-api) | Step-by-step tasks that mutate after posting | Multi-step agents, deploy progress |
+| [`StreamingPlan`](/docs/streaming#streaming-with-options) | Streaming with platform-specific options | Slack streaming with grouped tasks or stop blocks |
 
 For most cases, **AST builders** give the best balance of control and simplicity. Reach for **cards** when you need interactive elements like buttons or dropdowns.

package/docs/streaming.mdx

@@ -6,7 +6,7 @@ prerequisites:
   - /docs/usage
 ---
 
-Chat SDK accepts any `AsyncIterable<string>` as a message, enabling real-time streaming of AI responses and other incremental content to chat platforms. For platforms with native streaming support (Slack), you can also stream structured `StreamChunk` objects for rich content like task progress cards and plan updates.
+Chat SDK accepts any `AsyncIterable<string>` as a message, enabling real-time streaming of AI responses and other incremental content to chat platforms. For platforms with native or structured streaming support, you can also stream `StreamChunk` objects for rich content like task progress cards and plan updates.
 
 ## AI SDK integration
 
@@ -59,9 +59,14 @@ await thread.post(stream);
 | Platform | Method | Description |
 |----------|--------|-------------|
 | Slack | Native streaming API | Uses Slack's `chatStream` for smooth, real-time updates |
-| Teams | Post + Edit | Posts a message then edits it as chunks arrive |
+| Teams | Native (DMs) / Buffered (group chats) | Uses the Teams SDK's native `stream.emit()` for direct messages; accumulates chunks and posts one final message when no native streamer is active |
 | Google Chat | Post + Edit | Posts a message then edits it as chunks arrive |
 | Discord | Post + Edit | Posts a message then edits it as chunks arrive |
+| Telegram | Post + Edit | Posts a message then edits it as chunks arrive |
+| GitHub | Buffered | Accumulates chunks and posts one final comment |
+| Linear | Agent sessions / Post + Edit | Uses agent session activities in agent-session threads; falls back to post+edit comments in issue threads |
+| WhatsApp | Buffered | Accumulates chunks and sends one final message |
+| Messenger | Buffered | Accumulates chunks and sends one final message |
 
 The post+edit fallback throttles edits to avoid rate limits. Configure the update interval when creating your `Chat` instance:
 
@@ -104,9 +109,9 @@ When streaming content that contains GFM tables (e.g. from an LLM), the SDK auto
 
 This happens transparently — no configuration needed.
 
-## Structured streaming chunks (Slack only)
+## Structured streaming chunks
 
-For Slack's native streaming API, you can yield `StreamChunk` objects alongside plain text for rich content:
+For Slack native streams and Linear agent-session streams, you can yield `StreamChunk` objects alongside plain text for rich progress updates:
 
 ```typescript title="lib/bot.ts" lineNumbers
 import type { StreamChunk } from "chat";
@@ -144,39 +149,42 @@ await thread.post(stream);
 | Type | Fields | Description |
 |------|--------|-------------|
 | `markdown_text` | `text` | Streamed text content |
-| `task_update` | `id`, `title`, `status`, `details?`, `output?` | Tool/step progress cards (`pending`, `in_progress`, `complete`, `error`) with optional extra task context |
-| `plan_update` | `title` | Plan title updates |
+| `task_update` | `id`, `title`, `status`, `details?`, `output?` | Tool/step progress updates (`pending`, `in_progress`, `complete`, `error`) with optional extra task context |
+| `plan_update` | `title` | Plan title updates on supported platforms |
 
-### Task display mode
+### Streaming with options
 
-Control how `task_update` chunks render in Slack by passing `taskDisplayMode` via the adapter's streaming API. These options are currently only available through `adapter.stream()` directly:
+Wrap a stream in a `StreamingPlan` to pass platform-specific options through `thread.post()` without dropping down to `adapter.stream()` directly:
 
 ```typescript
-const raw = message.raw as { team_id?: string; team?: string };
-await thread.adapter.stream(thread.id, stream, {
-  recipientUserId: message.author.userId,
-  recipientTeamId: raw.team_id ?? raw.team,
-  taskDisplayMode: "plan",
+import { StreamingPlan } from "chat";
+
+const planned = new StreamingPlan(stream, {
+  groupTasks: "plan",         // Slack: render task cards as a single grouped block
+  endWith: [feedbackBlock],   // Slack: Block Kit elements appended after stream stops
+  updateIntervalMs: 750,      // Post+edit cadence on supported adapters
 });
+
+await thread.post(planned);
 ```
 
-| Mode | Description |
-|------|-------------|
-| `"timeline"` | Individual task cards shown inline with text (default) |
-| `"plan"` | All tasks grouped into a single plan block |
+| Option | Platform | Description |
+|--------|----------|-------------|
+| `groupTasks` | Slack | `"timeline"` (default) renders task cards inline; `"plan"` groups them into one plan block |
+| `endWith` | Slack | Block Kit elements attached when the stream stops (e.g. retry / feedback buttons) |
+| `updateIntervalMs` | Post+edit adapters | Minimum interval between post+edit cycles in ms (default `500`) |
 
-Adapters without structured chunk support extract text from `markdown_text` chunks and ignore other types.
+Adapters without structured chunk support extract text from `markdown_text` chunks and ignore other types. Slack-only options are silently ignored on other platforms.
 
 ## Stop blocks (Slack only)
 
-When streaming in Slack, you can attach Block Kit elements to the final message using `stopBlocks`. This is useful for adding action buttons after a streamed response completes:
+Use `endWith` on `StreamingPlan` to attach Block Kit elements to the final message. This is useful for adding action buttons after a streamed response completes:
 
 ```typescript title="lib/bot.ts" lineNumbers
-const raw = message.raw as { team_id?: string; team?: string };
-await thread.adapter.stream(thread.id, textStream, {
-  recipientUserId: message.author.userId,
-  recipientTeamId: raw.team_id ?? raw.team,
-  stopBlocks: [
+import { StreamingPlan } from "chat";
+
+const planned = new StreamingPlan(textStream, {
+  endWith: [
     {
       type: "actions",
       elements: [{
@@ -187,8 +195,48 @@ await thread.adapter.stream(thread.id, textStream, {
     },
   ],
 });
+
+await thread.post(planned);
 ```
 
+## Plan API
+
+For step-by-step task progress that lives outside an LLM stream, post a `Plan` directly. `Plan` is a `PostableObject` you can mutate after posting — every mutation re-renders the block in place.
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Plan } from "chat";
+
+const plan = new Plan({ initialMessage: "Researching options..." });
+await thread.post(plan);
+
+const lookup = await plan.addTask({ title: "Look up customer record" });
+// ...do work...
+await plan.updateTask("Found 3 matches");
+
+await plan.addTask({ title: "Summarize findings" });
+await plan.complete({ completeMessage: "Done!" });
+```
+
+By default `updateTask()` mutates the most recent `in_progress` task. Pass `{ id }` to target a specific task — useful when work runs in parallel or out of order:
+
+```typescript
+const fetchTask = await plan.addTask({ title: "Fetch data" });
+const transformTask = await plan.addTask({ title: "Transform" });
+
+// Update a specific task by id, even if it isn't the most recent in_progress one.
+await plan.updateTask({ id: fetchTask.id, output: "Got 42 rows" });
+await plan.updateTask({ id: transformTask.id, status: "complete" });
+```
+
+Adapters that don't support PostableObject editing (e.g. WhatsApp) render the plan as a fallback emoji-list message; the plan still posts, but mutations are no-ops.
+
+| Method | Description |
+|--------|-------------|
+| `addTask({ title, children? })` | Append a new task. The previous in-progress task is auto-completed |
+| `updateTask(input)` | Mutate the current (or `{ id }`-targeted) task's `output`, `status`, or `title` |
+| `complete({ completeMessage })` | Mark all in-progress tasks complete and update the plan title |
+| `reset({ initialMessage })` | Discard all tasks and start fresh with a new initial message — useful when re-using a plan handle for a new run |
+
 ## Streaming with conversation history
 
 Combine message history with streaming for multi-turn AI conversations.

package/docs/subject.mdx

@@ -0,0 +1,53 @@
+---
+title: Message Subject
+description: Fetch the parent resource that a message is about.
+type: guide
+prerequisites:
+  - /docs/handling-events
+related:
+  - /docs/conversation-history
+---
+
+When your bot receives a comment on a Linear issue or GitHub PR, `message.subject` resolves the parent resource so your handler knows what the conversation is about.
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  const subject = await message.subject;
+
+  if (subject) {
+    await thread.post(
+      `This is about: ${subject.title} (${subject.status})\n${subject.url}`
+    );
+  }
+});
+```
+
+On Linear and GitHub, comment webhooks deliver the comment text but not the parent issue or pull request — `message.subject` fetches it from the platform API on first access. The result is cached on the message instance. On chat platforms (which have no parent-resource concept), or if the API call fails, it returns `null`.
+
+See [`MessageSubject`](/docs/api/message#messagesubject) for the full type shape.
+
+### Platform support
+
+| Platform | `message.subject` returns |
+|----------|--------------------------|
+| Linear | Parent issue (from comment webhooks) |
+| GitHub | Parent issue or PR (from comment webhooks) |
+
+All other platforms return `null`.
+
+## User info
+
+For user profile details, use [`bot.getUser`](/docs/api/chat#getuser):
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  const user = await bot.getUser(message.author);
+  if (user) {
+    await thread.post(`Hi ${user.fullName} (${user.email})`);
+  }
+});
+```
+
+For anything beyond `message.subject`, access the platform's typed API client via [`bot.getAdapter(...).client`](/docs/api/chat#getadapter).

package/docs/threads-messages-channels.mdx

@@ -13,6 +13,15 @@ related:
 
 A `Thread` represents a conversation thread on any platform. It provides methods for posting messages, managing subscriptions, and accessing message history.
 
+Thread instances are most often supplied by the SDK to your event handlers. You can also construct one explicitly from a thread ID — useful for cron jobs, workflow steps, or any other context outside an inbound webhook:
+
+```typescript title="lib/bot.ts" lineNumbers
+const thread = bot.thread("slack:C123ABC:1234567890.123456");
+await thread.post("Reminder from a cron job");
+```
+
+For DM-style conversations, use [`bot.openDM(userIdOrAuthor)`](/docs/direct-messages) instead. It resolves the right channel and thread for user ID formats the SDK can infer.
+
 ### Post a message
 
 ```typescript title="lib/bot.ts" lineNumbers

package/docs/usage.mdx

@@ -34,7 +34,7 @@ bot.onNewMention(async (thread) => {
 ```
 
 <Callout type="info">
-  This example uses Redis. Chat SDK also supports [PostgreSQL](/docs/state/postgres) and [ioredis](/docs/state/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
+  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/postgres) and [ioredis](/adapters/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
 </Callout>
 
 Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
@@ -89,6 +89,15 @@ await slack.setSuggestedPrompts(channelId, threadTs, [
 ]);
 ```
 
+For typed access to the platform's native API client (Linear, GitHub), use `.client`:
+
+```typescript title="lib/bot.ts" lineNumbers
+const linear = bot.getAdapter("linear").client; // LinearClient
+const github = bot.getAdapter("github").client; // Octokit
+```
+
+See [`getAdapter`](/docs/api/chat#getadapter) for multi-tenant constraints.
+
 ## Webhook routing
 
 The `webhooks` property provides type-safe handlers for each registered adapter. Wire these up to your HTTP framework's routes:
@@ -139,7 +148,7 @@ const bot = Chat.getSingleton();
 Open a DM thread with a user by passing their platform user ID or an `Author` object:
 
 ```typescript title="lib/bot.ts" lineNumbers
-const dm = await bot.openDM("slack:U123ABC");
+const dm = await bot.openDM("U123ABC");
 await dm.post("Hey! Just wanted to follow up on your request.");
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.27.0",
+  "version": "4.28.1",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",