chat 4.13.1 → 4.13.2

package/docs/state/redis.mdx

@@ -0,0 +1,93 @@
+---
+title: Redis
+description: Production state adapter using the official redis package.
+type: reference
+prerequisites:
+  - /docs/getting-started
+---
+
+The recommended state adapter for production. Uses the official [redis](https://www.npmjs.com/package/redis) package.
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/state-redis
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: { /* ... */ },
+  state: createRedisState({
+    url: process.env.REDIS_URL!,
+  }),
+});
+```
+
+### Using an existing client
+
+If you already have a connected Redis client, pass it directly:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { createClient } from "redis";
+
+const client = createClient({ url: "redis://localhost:6379" });
+await client.connect();
+
+const state = createRedisState({ client });
+```
+
+### Key prefix
+
+All keys are namespaced under a configurable prefix (default: `"chat-sdk"`):
+
+```typescript title="lib/bot.ts" lineNumbers
+const state = createRedisState({
+  url: process.env.REDIS_URL!,
+  keyPrefix: "my-bot",
+});
+```
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `url` | Yes* | Redis connection URL |
+| `client` | No | Existing `redis` client instance |
+| `keyPrefix` | No | Prefix for all keys (default: `"chat-sdk"`) |
+
+*Either `url` or `client` is required.
+
+## Environment variables
+
+```bash title=".env.local"
+REDIS_URL=redis://localhost:6379
+```
+
+For serverless deployments (Vercel, AWS Lambda), use a serverless-compatible Redis provider like [Upstash](https://upstash.com).
+
+## Key structure
+
+```
+{keyPrefix}:subscriptions     - SET of subscribed thread IDs
+{keyPrefix}:lock:{threadId}   - Lock key with TTL
+```
+
+## Production recommendations
+
+- Use Redis 6.0+ for best performance
+- Enable Redis persistence (RDB or AOF)
+- Use Redis Cluster for high availability
+- Set appropriate memory limits
+
+## Features
+
+- Persistent subscriptions across restarts
+- Distributed locking across multiple instances
+- Automatic reconnection
+- Key prefix namespacing

package/docs/streaming.mdx

@@ -0,0 +1,99 @@
+---
+title: Streaming
+description: Stream real-time text responses from AI models and other async sources to chat platforms.
+type: guide
+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.
+
+## AI SDK integration
+
+Pass an AI SDK `textStream` directly to `thread.post()`:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { ToolLoopAgent } from "ai";
+
+const agent = new ToolLoopAgent({
+  model: "anthropic/claude-4.5-sonnet",
+  instructions: "You are a helpful assistant.",
+});
+
+bot.onNewMention(async (thread, message) => {
+  const result = await agent.stream({ prompt: message.text });
+  await thread.post(result.textStream);
+});
+```
+
+## Custom streams
+
+Any async iterable works:
+
+```typescript title="lib/bot.ts" lineNumbers
+const stream = (async function* () {
+  yield "Processing";
+  yield "...";
+  yield " done!";
+})();
+
+await thread.post(stream);
+```
+
+## Platform behavior
+
+| 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 |
+| 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 |
+
+The post+edit fallback throttles edits to avoid rate limits. Configure the update interval when creating your `Chat` instance:
+
+```typescript title="lib/bot.ts" lineNumbers
+const bot = new Chat({
+  // ...
+  streamingUpdateIntervalMs: 500, // Default: 500ms
+});
+```
+
+## 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:
+
+```typescript title="lib/bot.ts" lineNumbers
+await thread.stream(textStream, {
+  stopBlocks: [
+    {
+      type: "actions",
+      elements: [{
+        type: "button",
+        text: { type: "plain_text", text: "Retry" },
+        action_id: "retry",
+      }],
+    },
+  ],
+});
+```
+
+## Streaming with conversation history
+
+Combine message history with streaming for multi-turn AI conversations:
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message) => {
+  // Fetch recent messages for context
+  const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 });
+
+  const history = result.messages
+    .filter((msg) => msg.text.trim())
+    .map((msg) => ({
+      role: msg.author.isMe ? "assistant" as const : "user" as const,
+      content: msg.text,
+    }));
+
+  const response = await agent.stream({ prompt: history });
+  await thread.post(response.textStream);
+});
+```

package/docs/usage.mdx

@@ -0,0 +1,338 @@
+---
+title: Usage
+description: Event handlers, threads, channels, messages, and the core patterns of Chat SDK.
+type: guide
+prerequisites:
+  - /docs/getting-started
+---
+
+Chat SDK uses an event-driven architecture. You register handlers for different event types, and the SDK routes incoming webhooks to the appropriate handler.
+
+## Event handlers
+
+### Mention handler
+
+`onNewMention` fires when your bot is @-mentioned in a thread it hasn't subscribed to yet. This is the primary entry point for new conversations.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm now listening to this thread.");
+});
+```
+
+### Subscribed message handler
+
+`onSubscribedMessage` fires for every new message in a thread your bot has subscribed to. Once subscribed, all messages (including @mentions) route here instead of `onNewMention`.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSubscribedMessage(async (thread, message) => {
+  // Check if the bot was @-mentioned specifically
+  if (message.isMention) {
+    await thread.post("You mentioned me!");
+    return;
+  }
+
+  await thread.post(`Got your message: ${message.text}`);
+});
+```
+
+### Pattern handler
+
+`onNewMessage` fires for messages matching a regex pattern in threads the bot is **not** subscribed to. Useful for keyword-triggered responses.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onNewMessage(/^help$/i, async (thread, message) => {
+  await thread.post("Here's how I can help...");
+});
+```
+
+### Slash command handler
+
+`onSlashCommand` fires when a user invokes a `/command` in the message composer. See [Slash Commands](/docs/slash-commands) for the full guide.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onSlashCommand("/status", async (event) => {
+  await event.channel.post("All systems operational!");
+});
+```
+
+### Reaction handler
+
+`onReaction` fires when users add or remove emoji reactions to messages.
+
+```typescript title="lib/bot.ts" lineNumbers
+import { emoji } from "chat";
+
+bot.onReaction(["thumbs_up", "heart"], async (event) => {
+  if (!event.added) return;
+
+  await event.adapter.addReaction(
+    event.threadId,
+    event.messageId,
+    emoji.raised_hands
+  );
+});
+```
+
+The `event` object includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `emoji` | `EmojiValue` | Normalized emoji for comparison |
+| `rawEmoji` | `string` | Platform-specific emoji string |
+| `added` | `boolean` | `true` if added, `false` if removed |
+| `user` | `Author` | The user who reacted |
+| `message` | `Message` (optional) | The message that was reacted to |
+| `thread` | `Thread` | Thread for posting replies |
+| `adapter` | `Adapter` | The platform adapter |
+
+### Assistant thread handler
+
+`onAssistantThreadStarted` fires when a user opens a new assistant thread in Slack. Use it with the Slack Assistants API to set suggested prompts and status indicators. See [Slack Assistants API](/docs/adapters/slack#slack-assistants-api) for details.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onAssistantThreadStarted(async (event) => {
+  const slack = bot.getAdapter("slack") as SlackAdapter;
+  await slack.setSuggestedPrompts(event.channelId, event.threadTs, [
+    { title: "Get started", message: "What can you help me with?" },
+  ]);
+});
+```
+
+### App Home handler
+
+`onAppHomeOpened` fires when a user opens your bot's Home tab in Slack. Use it to publish a dynamic view.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onAppHomeOpened(async (event) => {
+  const slack = bot.getAdapter("slack") as SlackAdapter;
+  await slack.publishHomeView(event.userId, {
+    type: "home",
+    blocks: [{ type: "section", text: { type: "mrkdwn", text: "Welcome!" } }],
+  });
+});
+```
+
+## Threads
+
+A `Thread` represents a conversation thread on any platform. It provides methods for posting messages, managing subscriptions, and accessing message history.
+
+### Post a message
+
+```typescript title="lib/bot.ts" lineNumbers
+// Plain text
+await thread.post("Hello world");
+
+// Markdown (converted to each platform's format)
+await thread.post("**Bold** and _italic_ text");
+
+// Structured message with attachments
+await thread.post({
+  markdown: "Here's a file:",
+  files: [{ data: buffer, filename: "report.pdf" }],
+});
+```
+
+### Subscribe and unsubscribe
+
+Subscriptions persist across restarts (stored in your state adapter). When a thread is subscribed, all messages route to `onSubscribedMessage`.
+
+```typescript title="lib/bot.ts" lineNumbers
+await thread.subscribe();
+await thread.unsubscribe();
+
+const subscribed = await thread.isSubscribed();
+```
+
+### Typing indicator
+
+```typescript title="lib/bot.ts"
+await thread.startTyping();
+```
+
+<Callout type="info">
+Not all platforms support typing indicators. The call is a no-op on unsupported platforms. See the [adapter feature matrix](/docs/adapters) for details.
+</Callout>
+
+### Message history
+
+Access recent messages or iterate through full history:
+
+```typescript title="lib/bot.ts" lineNumbers
+// Cached messages from the webhook payload
+const recent = thread.recentMessages;
+
+// Newest first (auto-paginates)
+for await (const msg of thread.messages) {
+  console.log(msg.text);
+}
+
+// Oldest first (auto-paginates)
+for await (const msg of thread.allMessages) {
+  console.log(msg.text);
+}
+```
+
+### Thread state
+
+Store typed, per-thread state that persists across requests:
+
+```typescript title="lib/bot.ts" lineNumbers
+interface ThreadState {
+  aiMode?: boolean;
+  context?: string;
+}
+
+const bot = new Chat<typeof adapters, ThreadState>({
+  // ...config
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.setState({ aiMode: true });
+
+  const state = await thread.state; // ThreadState | null
+  if (state?.aiMode) {
+    // AI mode is enabled
+  }
+});
+```
+
+State is stored in your state adapter with a 30-day TTL. Use `{ replace: true }` to replace state entirely instead of merging:
+
+```typescript title="lib/bot.ts"
+await thread.setState({ aiMode: false }, { replace: true });
+```
+
+## Messages
+
+Incoming messages are normalized across platforms into a consistent format:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Platform message ID |
+| `threadId` | `string` | Thread ID in `adapter:channel:thread` format |
+| `text` | `string` | Plain text content |
+| `formatted` | `Root` | mdast AST representation |
+| `raw` | `unknown` | Original platform-specific payload |
+| `author` | `Author` | Message author info |
+| `metadata` | `MessageMetadata` | Timestamps and edit status |
+| `attachments` | `Attachment[]` (optional) | File attachments |
+| `isMention` | `boolean` (optional) | Whether the bot was @-mentioned |
+
+### Author
+
+```typescript lineNumbers
+interface Author {
+  userId: string;
+  userName: string;
+  fullName: string;
+  isBot: boolean | "unknown";
+  isMe: boolean; // true if message is from the bot itself
+}
+```
+
+### Sent messages
+
+When you post a message, you get back a `SentMessage` with methods to edit, delete, and react:
+
+```typescript title="lib/bot.ts" lineNumbers
+const sent = await thread.post("Processing...");
+// Do some work...
+await sent.edit("Done!");
+
+// Or delete
+await sent.delete();
+
+// Add/remove reactions
+await sent.addReaction(emoji.check);
+await sent.removeReaction(emoji.check);
+```
+
+## Channels
+
+A `Channel` represents the container that holds threads (e.g., a Slack channel, a Teams conversation). Navigate to a channel from a thread or get one directly:
+
+```typescript title="lib/bot.ts" lineNumbers
+// From a thread
+const channel = thread.channel;
+
+// Directly by ID
+const channel = bot.channel("slack:C123ABC");
+```
+
+### List threads
+
+Iterate threads in a channel, most recently active first:
+
+```typescript title="lib/bot.ts" lineNumbers
+for await (const thread of channel.threads()) {
+  console.log(thread.rootMessage.text, thread.replyCount);
+}
+```
+
+### Channel messages
+
+Iterate top-level messages (not thread replies):
+
+```typescript title="lib/bot.ts" lineNumbers
+for await (const msg of channel.messages) {
+  console.log(msg.text);
+}
+```
+
+### Post to a channel
+
+Post a top-level message (not inside a thread):
+
+```typescript title="lib/bot.ts"
+await channel.post("Hello channel!");
+```
+
+### Channel metadata
+
+```typescript title="lib/bot.ts"
+const info = await channel.fetchMetadata();
+console.log(info.name, info.memberCount);
+```
+
+## Thread ID format
+
+All thread IDs follow the pattern `{adapter}:{channel}:{thread}`:
+
+- **Slack**: `slack:C123ABC:1234567890.123456`
+- **Teams**: `teams:{base64(conversationId)}:{base64(serviceUrl)}`
+- **Google Chat**: `gchat:spaces/ABC123:{base64(threadName)}`
+- **Discord**: `discord:{guildId}:{channelId}/{messageId}`
+
+You typically don't need to construct these yourself — they're provided by the SDK in event handlers.
+
+## Logging
+
+Configure logging when creating the `Chat` instance:
+
+```typescript title="lib/bot.ts" lineNumbers
+// Use a built-in log level
+const bot = new Chat({
+  // ...
+  logger: "debug", // "debug" | "info" | "warn" | "error" | "silent"
+});
+
+// Or use ConsoleLogger for child loggers
+import { ConsoleLogger } from "chat";
+
+const logger = new ConsoleLogger("info");
+const bot = new Chat({
+  // ...
+  logger,
+});
+```
+
+Pass child loggers to adapters for prefixed log output:
+
+```typescript title="lib/bot.ts"
+createSlackAdapter({
+  // ...
+  logger: logger.child("slack"),
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.13.1",
+  "version": "4.13.2",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,10 +21,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "dependencies": {
-    "@workflow/serde": "4.0.1-beta.1",
+    "@workflow/serde": "4.1.0-beta.2",
     "mdast-util-to-string": "^4.0.0",
     "remark-gfm": "^4.0.0",
     "remark-parse": "^11.0.0",
@@ -40,12 +41,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vercel-labs/chat.git",
+    "url": "git+https://github.com/vercel/chat.git",
     "directory": "packages/chat-sdk"
   },
-  "homepage": "https://github.com/vercel-labs/chat#readme",
+  "homepage": "https://github.com/vercel/chat#readme",
   "bugs": {
-    "url": "https://github.com/vercel-labs/chat/issues"
+    "url": "https://github.com/vercel/chat/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -60,12 +61,11 @@
   ],
   "license": "MIT",
   "scripts": {
-    "build": "rm -rf dist && tsup",
+    "build": "pnpm clean && tsup && cp -r ../../apps/docs/content/docs ./docs",
     "dev": "tsup --watch",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check src",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist docs"
   }
 }