chat 4.13.1 → 4.13.2

package/docs/modals.mdx

@@ -0,0 +1,208 @@
+---
+title: Modals
+description: Collect structured user input through modal dialogs with text fields, dropdowns, and validation.
+type: guide
+prerequisites:
+  - /docs/actions
+---
+
+Modals open form dialogs in response to button clicks or [slash commands](/docs/slash-commands). They support text inputs, dropdowns, radio buttons, and server-side validation. Currently supported on Slack.
+
+## Open a modal
+
+Modals are opened from [action handlers](/docs/actions) or [slash command handlers](/docs/slash-commands) using `event.openModal()`:
+
+```tsx title="lib/bot.tsx" lineNumbers
+import { Modal, TextInput, Select, SelectOption } from "chat";
+
+bot.onAction("feedback", async (event) => {
+  await event.openModal(
+    <Modal
+      callbackId="feedback_form"
+      title="Send Feedback"
+      submitLabel="Send"
+      closeLabel="Cancel"
+      notifyOnClose
+    >
+      <TextInput
+        id="message"
+        label="Your Feedback"
+        placeholder="Tell us what you think..."
+        multiline
+      />
+      <Select id="category" label="Category" placeholder="Select a category">
+        <SelectOption label="Bug Report" value="bug" />
+        <SelectOption label="Feature Request" value="feature" />
+        <SelectOption label="General" value="general" />
+      </Select>
+      <TextInput
+        id="email"
+        label="Email (optional)"
+        placeholder="your@email.com"
+        optional
+      />
+    </Modal>
+  );
+});
+```
+
+## Components
+
+### Modal
+
+The top-level container for the form.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `callbackId` | `string` | Identifier for matching submit/close handlers |
+| `title` | `string` | Modal title |
+| `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 |
+| `privateMetadata` | `string` (optional) | Custom context passed through to handlers |
+
+### TextInput
+
+A text field for user input.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Field identifier (key in `event.values`) |
+| `label` | `string` | Field label |
+| `placeholder` | `string` (optional) | Placeholder text |
+| `initialValue` | `string` (optional) | Pre-filled value |
+| `multiline` | `boolean` (optional) | Render as textarea |
+| `optional` | `boolean` (optional) | Allow empty submission |
+| `maxLength` | `number` (optional) | Maximum character count |
+
+### Select
+
+A dropdown for selecting a single option.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Field identifier |
+| `label` | `string` | Field label |
+| `placeholder` | `string` (optional) | Placeholder text |
+| `initialOption` | `string` (optional) | Pre-selected value |
+| `optional` | `boolean` (optional) | Allow empty submission |
+
+### RadioSelect
+
+A radio button group for mutually exclusive options.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Field identifier |
+| `label` | `string` | Field label |
+| `initialOption` | `string` (optional) | Pre-selected value |
+| `optional` | `boolean` (optional) | Allow empty submission |
+
+### SelectOption
+
+An option for `Select` or `RadioSelect`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Display text |
+| `value` | `string` | Value passed to handler |
+| `description` | `string` (optional) | Help text below the label |
+
+## Handle submissions
+
+Register a handler with `onModalSubmit` using the same `callbackId`:
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onModalSubmit("feedback_form", async (event) => {
+  const { message, category, email } = event.values;
+
+  // Validate input — return errors to show in the modal
+  if (!message || message.length < 5) {
+    return {
+      action: "errors",
+      errors: { message: "Feedback must be at least 5 characters" },
+    };
+  }
+
+  // Post confirmation to the original thread
+  if (event.relatedThread) {
+    await event.relatedThread.post(`Feedback received! Category: ${category}`);
+  }
+
+  // Update the message that triggered the modal
+  if (event.relatedMessage) {
+    await event.relatedMessage.edit("Feedback submitted!");
+  }
+
+  // Return nothing (or { action: "close" }) to close the modal
+});
+```
+
+### Response types
+
+| Response | Description |
+|----------|-------------|
+| `undefined` or `{ action: "close" }` | Close the modal |
+| `{ action: "errors", errors: { fieldId: "message" } }` | Show validation errors on specific fields |
+| `{ action: "update", modal: ModalElement }` | Replace the modal content |
+| `{ action: "push", modal: ModalElement }` | Push a new modal view onto the stack |
+
+### ModalSubmitEvent
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `callbackId` | `string` | Modal identifier |
+| `viewId` | `string` | Platform view ID |
+| `values` | `Record<string, string>` | Form field values keyed by input `id` |
+| `user` | `Author` | The user who submitted |
+| `privateMetadata` | `string` (optional) | Custom context from the Modal component |
+| `relatedThread` | `Thread` (optional) | Thread where the modal was triggered |
+| `relatedMessage` | `SentMessage` (optional) | Message with the button that opened the modal |
+| `relatedChannel` | `Channel` (optional) | Channel where the modal was triggered (from [slash commands](/docs/slash-commands)) |
+| `adapter` | `Adapter` | The platform adapter |
+| `raw` | `unknown` | Platform-specific payload |
+
+## Handle cancellation
+
+Optionally handle when users cancel a modal. Requires `notifyOnClose` on the `Modal` component:
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onModalClose("feedback_form", async (event) => {
+  console.log(`${event.user.userName} cancelled the feedback form`);
+
+  if (event.relatedThread) {
+    await event.relatedThread.post("No worries, let us know if you change your mind!");
+  }
+});
+```
+
+## Pass context with privateMetadata
+
+Use `privateMetadata` to carry context from the button click through to the submit handler:
+
+```tsx title="lib/bot.tsx" lineNumbers
+bot.onAction("report", async (event) => {
+  await event.openModal(
+    <Modal
+      callbackId="report_form"
+      title="Report Bug"
+      submitLabel="Submit"
+      privateMetadata={JSON.stringify({
+        reportType: event.value,
+        threadId: event.threadId,
+      })}
+    >
+      <TextInput id="title" label="Bug Title" />
+      <TextInput id="steps" label="Steps to Reproduce" multiline />
+    </Modal>
+  );
+});
+
+bot.onModalSubmit("report_form", async (event) => {
+  const metadata = event.privateMetadata
+    ? JSON.parse(event.privateMetadata)
+    : {};
+
+  console.log(metadata.reportType); // "bug"
+});
+```

package/docs/posting-messages.mdx

@@ -0,0 +1,177 @@
+---
+title: Posting Messages
+description: Different ways to render and send messages with thread.post().
+type: guide
+prerequisites:
+  - /docs/usage
+related:
+  - /docs/cards
+  - /docs/streaming
+  - /docs/files
+---
+
+`thread.post()` accepts several message formats, each suited to different use cases. Choose the format that best fits your content — from plain strings to structured AST to rich interactive cards.
+
+## Plain text
+
+The simplest option. Pass a string and it goes through as-is to the platform.
+
+```typescript title="lib/bot.ts"
+await thread.post("Hello world");
+```
+
+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.
+
+```typescript title="lib/bot.ts"
+await thread.post({
+  markdown: "**Bold**, _italic_, and `code`",
+});
+```
+
+Under the hood, the SDK parses the markdown into an mdast AST, then each adapter converts it to the platform's format.
+
+## AST builders
+
+For programmatic control over message formatting, use the mdast AST builder functions exported from `chat`. This is the recommended approach for most use cases — it gives you fine-grained control without the overhead of card rendering.
+
+```typescript title="lib/bot.ts"
+import { root, paragraph, text, strong, link } from "chat";
+
+await thread.post({
+  ast: root([
+    paragraph([
+      strong([text("Deployment complete")]),
+      text(" — "),
+      link("https://example.com", [text("View site")]),
+    ]),
+  ]),
+});
+```
+
+### Available builders
+
+| Builder | Description | Example |
+|---------|-------------|---------|
+| `root(children)` | Root node (required wrapper) | `root([paragraph([...])])` |
+| `paragraph(children)` | Paragraph block | `paragraph([text("Hello")])` |
+| `text(value)` | Plain text | `text("Hello")` |
+| `strong(children)` | **Bold** text | `strong([text("bold")])` |
+| `emphasis(children)` | _Italic_ text | `emphasis([text("italic")])` |
+| `strikethrough(children)` | ~~Strikethrough~~ text | `strikethrough([text("done")])` |
+| `inlineCode(value)` | `Inline code` | `inlineCode("const x = 1")` |
+| `codeBlock(value, lang?)` | Fenced code block | `codeBlock("const x = 1", "ts")` |
+| `link(url, children, title?)` | Hyperlink | `link("https://...", [text("click")])` |
+| `blockquote(children)` | Block quote | `blockquote([paragraph([text("...")])])` |
+
+### Parsing markdown to AST
+
+You can also parse a markdown string into an AST, manipulate it, then send it:
+
+```typescript title="lib/bot.ts"
+import { parseMarkdown, stringifyMarkdown } from "chat";
+
+const ast = parseMarkdown("**Hello** world");
+// Manipulate the AST...
+await thread.post({ ast });
+```
+
+## Cards
+
+When you need interactive elements like buttons, dropdowns, or structured layouts, use cards. Cards render natively on each platform — Block Kit on Slack, Adaptive Cards on Teams, and Google Chat Cards.
+
+### Function syntax
+
+Use the function-call API for type-safe card construction:
+
+```typescript title="lib/bot.ts"
+import { Card, Text, Actions, Button } from "chat";
+
+await thread.post(
+  Card({
+    title: "Order #1234",
+    children: [
+      Text("Your order has been received!"),
+      Actions([
+        Button({ id: "approve", label: "Approve", style: "primary" }),
+        Button({ id: "reject", label: "Reject", style: "danger" }),
+      ]),
+    ],
+  })
+);
+```
+
+### JSX syntax
+
+You can also use JSX if you configure the `chat` JSX runtime:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "chat"
+  }
+}
+```
+
+```tsx title="lib/bot.tsx"
+import { Card, CardText, Actions, Button } from "chat";
+
+await thread.post(
+  <Card title="Order #1234">
+    <CardText>Your order has been received!</CardText>
+    <Actions>
+      <Button id="approve" style="primary">Approve</Button>
+      <Button id="reject" style="danger">Reject</Button>
+    </Actions>
+  </Card>
+);
+```
+
+<Callout type="warn">
+The JSX syntax requires `jsxImportSource: "chat"` in your `tsconfig.json` (or a per-file `/** @jsxImportSource chat */` pragma). Without this, TypeScript won't recognize the card JSX types. If you run into type issues with JSX, use the function-call syntax instead — it produces the same output with better type inference.
+</Callout>
+
+See the [Cards](/docs/cards) page for the full list of card components.
+
+## Streaming
+
+Pass an `AsyncIterable<string>` (like the AI SDK's `textStream`) 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.
+
+```typescript title="lib/bot.ts"
+import { streamText } from "ai";
+
+const result = streamText({ model, prompt: message.text });
+await thread.post(result.textStream);
+```
+
+See the [Streaming](/docs/streaming) page for details on platform behavior and configuration.
+
+## Attachments and files
+
+Any structured message format (`markdown`, `ast`, or `card`) supports `files` for uploading attachments alongside the message:
+
+```typescript title="lib/bot.ts"
+await thread.post({
+  markdown: "Here's the report:",
+  files: [{ data: buffer, filename: "report.pdf" }],
+});
+```
+
+See the [Files](/docs/files) page for more on attachments.
+
+## Choosing a format
+
+| Format | Use when | Example |
+|--------|----------|---------|
+| Plain string | Simple, unformatted text | Status updates, acknowledgements |
+| `{ markdown }` | You have a markdown string (e.g. from a template) | Notifications with links and formatting |
+| `{ ast }` | You need programmatic formatting control | Dynamic messages built from data |
+| 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 |
+
+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/slash-commands.mdx

@@ -0,0 +1,110 @@
+---
+title: Slash Commands
+description: Handle slash command invocations and respond with messages or modals.
+type: guide
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/modals
+  - /docs/adapters/slack
+---
+
+Slash commands let users invoke your bot with `/command` syntax. Register handlers with `onSlashCommand` to respond.
+
+## Handle a specific command
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSlashCommand("/status", async (event) => {
+  await event.channel.post("All systems operational!");
+});
+```
+
+## Handle multiple commands
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSlashCommand(["/help", "/info"], async (event) => {
+  await event.channel.post(`You invoked ${event.command}`);
+});
+```
+
+## Catch-all handler
+
+Register a handler without a command to catch all slash commands:
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSlashCommand(async (event) => {
+  console.log(`Command: ${event.command}, Args: ${event.text}`);
+});
+```
+
+## SlashCommandEvent
+
+The `event` object passed to slash command handlers:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `command` | `string` | The command name (e.g., `/status`) |
+| `text` | `string` | Arguments after the command |
+| `user` | `Author` | The user who invoked the command |
+| `channel` | `Channel` | The channel where the command was invoked |
+| `adapter` | `Adapter` | The platform adapter |
+| `triggerId` | `string` (optional) | Platform trigger ID for opening modals |
+| `openModal` | `(modal) => Promise<{ viewId: string } \| undefined>` | Open a modal dialog |
+| `raw` | `unknown` | Platform-specific payload |
+
+## Respond to a command
+
+Use `event.channel` to post messages:
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSlashCommand("/greet", async (event) => {
+  // Public message to the channel
+  await event.channel.post(`Hello, ${event.user.fullName}!`);
+
+  // Ephemeral message (only visible to the user)
+  await event.channel.postEphemeral(
+    event.user,
+    "This message is just for you!",
+    { fallbackToDM: false }
+  );
+});
+```
+
+## Open a modal
+
+Use `event.openModal()` to open a [modal](/docs/modals) in response to a slash command:
+
+```tsx title="lib/bot.tsx" lineNumbers
+import { Modal, TextInput, Select, SelectOption } from "chat";
+
+bot.onSlashCommand("/feedback", async (event) => {
+  const result = await event.openModal(
+    <Modal callbackId="feedback_form" title="Send Feedback" submitLabel="Send">
+      <TextInput id="message" label="Your Feedback" multiline />
+      <Select id="category" label="Category">
+        <SelectOption label="Bug" value="bug" />
+        <SelectOption label="Feature" value="feature" />
+      </Select>
+    </Modal>
+  );
+
+  if (!result) {
+    await event.channel.post("Couldn't open the feedback form. Please try again.");
+  }
+});
+```
+
+<Callout type="info">
+When a modal is opened from a slash command, the submit handler receives `relatedChannel` instead of `relatedThread`. Use this to post back to the channel where the command was invoked.
+</Callout>
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onModalSubmit("feedback_form", async (event) => {
+  const { message, category } = event.values;
+
+  // Post to the channel where the slash command was invoked
+  if (event.relatedChannel) {
+    await event.relatedChannel.post(`Feedback received! Category: ${category}`);
+  }
+});
+```

package/docs/state/index.mdx

@@ -0,0 +1,31 @@
+---
+title: Overview
+description: Pluggable state adapters for thread subscriptions, distributed locking, and caching.
+type: overview
+prerequisites:
+  - /docs/getting-started
+---
+
+State adapters handle persistent storage for thread subscriptions, distributed locks (to prevent duplicate processing), and caching. You must provide a state adapter when creating a `Chat` instance.
+
+## Comparison
+
+| Adapter | Package | Persistence | Multi-instance | Use case |
+|---------|---------|-------------|----------------|----------|
+| [Redis](/docs/state/redis) | `@chat-adapter/state-redis` | Yes | Yes | Production (recommended) |
+| [ioredis](/docs/state/ioredis) | `@chat-adapter/state-ioredis` | Yes | Yes | Production (Cluster/Sentinel) |
+| [Memory](/docs/state/memory) | `@chat-adapter/state-memory` | No | No | Development and testing |
+
+## What state adapters manage
+
+### Thread subscriptions
+
+When your bot calls `thread.subscribe()`, the state adapter persists that subscription. On subsequent webhooks, the SDK checks subscriptions to route messages to `onSubscribedMessage` handlers. With Redis, subscriptions survive restarts and work across multiple instances.
+
+### Distributed locking
+
+When a webhook arrives, the SDK acquires a lock on the thread to prevent duplicate processing. This is critical for serverless deployments where multiple instances may receive the same event.
+
+### Caching
+
+State adapters provide key-value storage with TTL for thread state (`thread.setState()`), message deduplication, and other internal caching.

package/docs/state/ioredis.mdx

@@ -0,0 +1,81 @@
+---
+title: ioredis
+description: Alternative Redis state adapter using ioredis with Cluster and Sentinel support.
+type: reference
+prerequisites:
+  - /docs/getting-started
+---
+
+An alternative Redis state adapter using [ioredis](https://www.npmjs.com/package/ioredis). Use this if you already have ioredis in your project or need Redis Cluster/Sentinel support.
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/state-ioredis
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createIORedisState } from "@chat-adapter/state-ioredis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: { /* ... */ },
+  state: createIORedisState({
+    url: process.env.REDIS_URL!,
+  }),
+});
+```
+
+### Using an existing client
+
+```typescript title="lib/bot.ts" lineNumbers
+import Redis from "ioredis";
+
+const client = new Redis("redis://localhost:6379");
+
+const state = createIORedisState({ client });
+```
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `url` | Yes* | Redis connection URL |
+| `client` | No | Existing `ioredis` client instance |
+| `keyPrefix` | No | Prefix for all keys (default: `"chat-sdk"`) |
+
+*Either `url` or `client` is required.
+
+## When to use ioredis vs redis
+
+**Use `@chat-adapter/state-ioredis` when:**
+
+- You already use ioredis in your project
+- You need Redis Cluster support
+- You need Redis Sentinel support
+- You prefer the ioredis API
+
+**Use `@chat-adapter/state-redis` when:**
+
+- You want the official Redis client
+- You're starting a new project
+- You don't need Cluster or Sentinel
+
+## Key structure
+
+```
+{keyPrefix}:subscriptions     - SET of subscribed thread IDs
+{keyPrefix}:lock:{threadId}   - Lock key with TTL
+```
+
+## Features
+
+- Persistent subscriptions across restarts
+- Distributed locking across multiple instances
+- Automatic reconnection
+- Redis Cluster support
+- Redis Sentinel support
+- Key prefix namespacing

package/docs/state/memory.mdx

@@ -0,0 +1,52 @@
+---
+title: Memory
+description: In-memory state adapter for local development and testing.
+type: reference
+prerequisites:
+  - /docs/getting-started
+---
+
+An in-memory state adapter for development and testing. Zero configuration required.
+
+<Callout type="warn">
+Only use the memory adapter for local development and testing. State is lost on restart and locks don't work across multiple instances. For production, use [Redis](/docs/state/redis) or [ioredis](/docs/state/ioredis).
+</Callout>
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/state-memory
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createMemoryState } from "@chat-adapter/state-memory";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: { /* ... */ },
+  state: createMemoryState(),
+});
+```
+
+No configuration options are needed.
+
+## Features
+
+- Thread subscriptions (in-memory)
+- Locking (single-process only)
+- Zero configuration
+
+## Limitations
+
+- **Not suitable for production** — state is lost on restart
+- **Single process only** — locks don't work across multiple instances
+- **No persistence** — subscriptions reset when the process restarts
+
+## When to use
+
+- Local development
+- Unit testing
+- Quick prototyping

package/docs/state/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "State",
+  "pages": [
+    "index",
+    "redis",
+    "ioredis",
+    "memory"
+  ]
+}