chat 4.14.0 → 4.16.0

package/docs/threads-messages-channels.mdx

@@ -0,0 +1,237 @@
+---
+title: Threads, Messages, and Channels
+description: Work with threads, messages, and channels across platforms.
+type: guide
+prerequisites:
+  - /docs/usage
+related:
+  - /docs/handling-events
+  - /docs/posting-messages
+---
+
+## 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. Pass a generic type parameter to `Chat` to get typed thread state across all handlers:
+
+```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
+
+The `logger` option is optional — if omitted, Chat SDK uses `ConsoleLogger("info")` by default. Each adapter also creates its own child logger automatically.
+
+```typescript title="lib/bot.ts" lineNumbers
+// Use defaults (ConsoleLogger at "info" level)
+const bot = new Chat({
+  // ...
+});
+
+// Or set a specific log level
+const bot = new Chat({
+  // ...
+  logger: "debug", // "debug" | "info" | "warn" | "error" | "silent"
+});
+
+// Or use a custom ConsoleLogger for child loggers
+import { ConsoleLogger } from "chat";
+
+const logger = new ConsoleLogger("info");
+const bot = new Chat({
+  // ...
+  logger,
+});
+```
+
+You can pass child loggers to adapters for prefixed log output, but adapters create their own child loggers by default:
+
+```typescript title="lib/bot.ts"
+createSlackAdapter({
+  logger: logger.child("slack"), // optional — auto-created if omitted
+});
+```

package/docs/usage.mdx

@@ -1,342 +1,148 @@
 ---
-title: Usage
-description: Event handlers, threads, channels, messages, and the core patterns of Chat SDK.
+title: Creating a Chat Instance
+description: Initialize the Chat class with adapters, state, and configuration options.
 type: guide
 prerequisites:
   - /docs/getting-started
+related:
+  - /docs/handling-events
+  - /docs/adapters
+  - /docs/state
 ---
 
-Chat SDK uses an event-driven architecture. You register handlers for different event types, and the SDK routes incoming webhooks to the appropriate handler.
+The `Chat` class is the main entry point for your bot. It coordinates adapters, routes events to your handlers, and manages thread state.
 
-## 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.
+## Basic setup
 
 ```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
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
 
-`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}`);
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+  },
+  state: createRedisState(),
 });
-```
-
-### 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...");
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm listening to this thread.");
 });
 ```
 
-### Slash command handler
+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.
 
-`onSlashCommand` fires when a user invokes a `/command` in the message composer. See [Slash Commands](/docs/slash-commands) for the full guide.
+## Multiple adapters
 
-```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.
+Register multiple adapters to deploy your bot across platforms simultaneously:
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { emoji } from "chat";
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+import { createDiscordAdapter } from "@chat-adapter/discord";
+import { createRedisState } from "@chat-adapter/state-redis";
 
-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?" },
-  ]);
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+    teams: createTeamsAdapter(),
+    discord: createDiscordAdapter(),
+  },
+  state: createRedisState(),
 });
 ```
 
-### App Home handler
+Your event handlers work identically across all registered adapters — the SDK normalizes messages, threads, and reactions into a consistent format.
 
-`onAppHomeOpened` fires when a user opens your bot's Home tab in Slack. Use it to publish a dynamic view.
+## Configuration options
 
-```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!" } }],
-  });
-});
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `userName` | `string` | *required* | Default bot username across all adapters |
+| `adapters` | `Record<string, Adapter>` | *required* | Map of adapter name to adapter instance |
+| `state` | `StateAdapter` | *required* | State adapter for subscriptions and locking |
+| `logger` | `Logger \| LogLevel` | `"info"` | Logger instance or log level (`"debug"`, `"info"`, `"warn"`, `"error"`, `"silent"`) |
+| `dedupeTtlMs` | `number` | `300000` | TTL in ms for message deduplication (5 minutes) |
+| `streamingUpdateIntervalMs` | `number` | `500` | Update interval in ms for post+edit streaming |
+| `fallbackStreamingPlaceholderText` | `string \| null` | `"..."` | Placeholder text while streaming starts. Set to `null` to skip |
 
-## Threads
+## Accessing adapters
 
-A `Thread` represents a conversation thread on any platform. It provides methods for posting messages, managing subscriptions, and accessing message history.
-
-### Post a message
+Use `getAdapter` to access platform-specific APIs when you need functionality beyond the unified interface:
 
 ```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");
+import type { SlackAdapter } from "@chat-adapter/slack";
 
-// Structured message with attachments
-await thread.post({
-  markdown: "Here's a file:",
-  files: [{ data: buffer, filename: "report.pdf" }],
-});
+const slack = bot.getAdapter("slack") as SlackAdapter;
+await slack.setSuggestedPrompts(channelId, threadTs, [
+  { title: "Get started", message: "What can you help me with?" },
+]);
 ```
 
-### 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();
+## Webhook routing
 
-const subscribed = await thread.isSubscribed();
-```
+The `webhooks` property provides type-safe handlers for each registered adapter. Wire these up to your HTTP framework's routes:
 
-### Typing indicator
+```typescript title="app/api/webhooks/slack/route.ts" lineNumbers
+import { bot } from "@/lib/bot";
 
-```typescript title="lib/bot.ts"
-await thread.startTyping();
+export const POST = bot.webhooks.slack;
 ```
 
-<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
+```typescript title="app/api/webhooks/teams/route.ts" lineNumbers
+import { bot } from "@/lib/bot";
 
-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);
-}
+export const POST = bot.webhooks.teams;
 ```
 
-### Thread state
+## Lifecycle
 
-Store typed, per-thread state that persists across requests:
+The Chat instance initializes lazily on the first webhook. You can also initialize manually:
 
 ```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
-}
+await bot.initialize();
 ```
 
-### Sent messages
-
-When you post a message, you get back a `SentMessage` with methods to edit, delete, and react:
+For graceful shutdown (e.g. in serverless teardown), call `shutdown`:
 
 ```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);
+await bot.shutdown();
 ```
 
-## Channels
+## Singleton pattern
 
-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:
+Register a singleton when you need to access the Chat instance from multiple files:
 
 ```typescript title="lib/bot.ts" lineNumbers
-// From a thread
-const channel = thread.channel;
-
-// Directly by ID
-const channel = bot.channel("slack:C123ABC");
+const bot = new Chat({ /* ...config */ }).registerSingleton();
+export default bot;
 ```
 
-### List threads
-
-Iterate threads in a channel, most recently active first:
+```typescript title="lib/utils.ts" lineNumbers
+import { Chat } from "chat";
 
-```typescript title="lib/bot.ts" lineNumbers
-for await (const thread of channel.threads()) {
-  console.log(thread.rootMessage.text, thread.replyCount);
-}
+const bot = Chat.getSingleton();
 ```
 
-### Channel messages
+## Direct messaging
 
-Iterate top-level messages (not thread replies):
+Open a DM thread with a user by passing their platform user ID or an `Author` object:
 
 ```typescript title="lib/bot.ts" lineNumbers
-for await (const msg of channel.messages) {
-  console.log(msg.text);
-}
+const dm = await bot.openDM("slack:U123ABC");
+await dm.post("Hey! Just wanted to follow up on your request.");
 ```
 
-### Post to a channel
-
-Post a top-level message (not inside a thread):
+## Channel access
 
-```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
-
-The `logger` option is optional — if omitted, Chat SDK uses `ConsoleLogger("info")` by default. Each adapter also creates its own child logger automatically.
+Get a channel directly by its ID:
 
 ```typescript title="lib/bot.ts" lineNumbers
-// Use defaults (ConsoleLogger at "info" level)
-const bot = new Chat({
-  // ...
-});
-
-// Or set a specific log level
-const bot = new Chat({
-  // ...
-  logger: "debug", // "debug" | "info" | "warn" | "error" | "silent"
-});
-
-// Or use a custom ConsoleLogger for child loggers
-import { ConsoleLogger } from "chat";
-
-const logger = new ConsoleLogger("info");
-const bot = new Chat({
-  // ...
-  logger,
-});
-```
-
-You can pass child loggers to adapters for prefixed log output, but adapters create their own child loggers by default:
-
-```typescript title="lib/bot.ts"
-createSlackAdapter({
-  logger: logger.child("slack"), // optional — auto-created if omitted
-});
+const channel = bot.channel("slack:C123ABC");
+await channel.post("Announcement: deploy complete!");
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.14.0",
+  "version": "4.16.0",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,14 +30,15 @@
     "remark-gfm": "^4.0.0",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
+    "remend": "^1.2.1",
     "unified": "^11.0.5"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",
-    "@types/node": "^22.10.2",
+    "@types/node": "^25.3.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.0.18"
   },
   "repository": {
     "type": "git",