chat 4.13.0 → 4.13.2

package/docs/adapters/linear.mdx

@@ -0,0 +1,207 @@
+---
+title: Linear
+description: Configure the Linear adapter to respond to @mentions in issue comment threads.
+type: integration
+prerequisites:
+  - /docs/getting-started
+---
+
+The Linear adapter treats issue comments as messages and issues as threads.
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/linear
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createLinearAdapter } from "@chat-adapter/linear";
+
+const bot = new Chat({
+  userName: "my-bot",
+  adapters: {
+    linear: createLinearAdapter({
+      apiKey: process.env.LINEAR_API_KEY!,
+      webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+      userName: "my-bot",
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Linear!");
+});
+```
+
+## Authentication
+
+### Option A: Personal API key
+
+Best for personal projects, testing, or single-workspace bots. Actions are attributed to you as an individual.
+
+1. Go to [Settings > Security & Access](https://linear.app/settings/account/security)
+2. Under **Personal API keys**, click **Create key**
+3. Select **Only select permissions** and enable Create issues, Create comments
+4. Choose team access
+5. Click **Create** and set `LINEAR_API_KEY`
+
+```typescript title="lib/bot.ts" lineNumbers
+createLinearAdapter({
+  apiKey: process.env.LINEAR_API_KEY!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+  userName: "my-bot",
+});
+```
+
+### Option B: OAuth application (recommended)
+
+The bot gets its own identity in Linear. The adapter handles token management internally.
+
+1. Go to [Settings > API > Applications](https://linear.app/settings/api/applications/new)
+2. Create an OAuth2 application with your bot's name and icon
+3. **Enable client credentials tokens** in the app settings
+4. Note the **Client ID** and **Client Secret**
+
+```typescript title="lib/bot.ts" lineNumbers
+createLinearAdapter({
+  clientId: process.env.LINEAR_CLIENT_ID!,
+  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+  userName: "my-bot",
+});
+```
+
+The adapter uses the client credentials grant to obtain tokens automatically. Tokens are valid for 30 days and auto-refresh when expired.
+
+### Making the bot @-mentionable (optional)
+
+To make the bot appear in Linear's `@` mention dropdown as an Agent:
+
+1. In your OAuth app settings, enable **Agent session events** under webhooks
+2. Have a workspace admin install the app with `actor=app` and the `app:mentionable` scope:
+
+```
+https://linear.app/oauth/authorize?
+  client_id=your_client_id&
+  redirect_uri=https://your-domain.com/callback&
+  response_type=code&
+  scope=read,write,comments:create,app:mentionable&
+  actor=app
+```
+
+See the [Linear Agents docs](https://linear.app/developers/agents) for full details.
+
+## Webhook setup
+
+<Callout type="info">
+Webhook management requires workspace admin access. If you don't see the API settings page, ask a workspace admin to create the webhook for you.
+</Callout>
+
+1. Go to **Settings > API** and click **Create webhook**
+2. Fill in:
+   - **Label**: A descriptive name (e.g., "Chat Bot")
+   - **URL**: `https://your-domain.com/api/webhooks/linear`
+3. Copy the **Signing secret** as `LINEAR_WEBHOOK_SECRET`
+4. Under **Data change events**, select:
+   - **Comments** (required)
+   - **Issues** (recommended)
+   - **Emoji reactions** (optional)
+5. Under **Team selection**, choose **All public teams** or a specific team
+6. Click **Create webhook**
+
+## Thread model
+
+Linear has two levels of comment threading:
+
+| Type | Description | Thread ID format |
+|------|-------------|-----------------|
+| Issue-level | Top-level comments on an issue | `linear:{issueId}` |
+| Comment thread | Replies nested under a specific comment | `linear:{issueId}:c:{commentId}` |
+
+When a user writes a comment, the bot replies within the same comment thread.
+
+## Reactions
+
+| SDK emoji | Linear emoji |
+|-----------|-------------|
+| `thumbs_up` | 👍 |
+| `thumbs_down` | 👎 |
+| `heart` | ❤️ |
+| `fire` | 🔥 |
+| `rocket` | 🚀 |
+| `eyes` | 👀 |
+| `sparkles` | ✨ |
+| `wave` | 👋 |
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `apiKey` | Yes* | Personal API key |
+| `clientId` | Yes* | OAuth app client ID |
+| `clientSecret` | Yes* | OAuth app client secret |
+| `accessToken` | Yes* | Pre-obtained OAuth access token |
+| `webhookSecret` | Yes | Webhook signing secret for verification |
+| `userName` | Yes | Bot display name for @mention detection |
+
+*One of `apiKey`, `clientId`/`clientSecret`, or `accessToken` is required.
+
+## Environment variables
+
+```bash title=".env.local"
+# API Key auth
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+
+# OR OAuth app auth
+LINEAR_CLIENT_ID=your-client-id
+LINEAR_CLIENT_SECRET=your-client-secret
+
+# Required
+LINEAR_WEBHOOK_SECRET=your-webhook-secret
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | Yes |
+| Reactions (add) | Yes |
+| Cards | Markdown |
+| Modals | No |
+| Streaming | No |
+| DMs | No |
+| File uploads | No |
+| Typing indicator | No |
+| Message history | Yes |
+
+## Limitations
+
+- **No typing indicators** — Linear doesn't support typing indicators
+- **No streaming** — Messages posted in full (editing supported for updates)
+- **No DMs** — Linear doesn't have direct messages
+- **No modals** — Linear doesn't support interactive modals
+- **Action buttons** — Rendered as text; use link buttons for clickable actions
+- **Remove reaction** — Requires reaction ID lookup (not directly supported)
+
+## Troubleshooting
+
+### "Invalid signature" error
+
+- Verify `LINEAR_WEBHOOK_SECRET` matches the secret from your webhook configuration
+- The webhook secret is shown only once at creation — regenerate if lost
+
+### Bot not responding to mentions
+
+- Verify webhook events are configured with **Comments** resource type
+- Check that the webhook URL is correct and accessible
+- Ensure the `userName` config matches how users mention the bot
+- Linear may auto-disable webhooks after repeated failures
+
+### "Webhook expired" error
+
+- Webhook timestamp is too old (> 5 minutes)
+- Usually indicates a delivery delay or clock skew
+- Check that your server time is synchronized

package/docs/adapters/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Adapters",
+  "pages": [
+    "index",
+    "slack",
+    "teams",
+    "gchat",
+    "discord",
+    "github",
+    "linear"
+  ]
+}

package/docs/adapters/slack.mdx

@@ -0,0 +1,293 @@
+---
+title: Slack
+description: Configure the Slack adapter for single-workspace or multi-workspace OAuth deployments.
+type: integration
+prerequisites:
+  - /docs/getting-started
+---
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/slack
+```
+
+## Single-workspace mode
+
+For bots deployed to a single Slack workspace:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      signingSecret: process.env.SLACK_SIGNING_SECRET!,
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Slack!");
+});
+```
+
+## Multi-workspace mode
+
+For apps installed across multiple Slack workspaces via OAuth, omit `botToken` and provide OAuth credentials instead. The adapter resolves tokens dynamically from your state adapter using the `team_id` from incoming webhooks.
+
+```typescript title="lib/bot.ts" lineNumbers
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const slackAdapter = createSlackAdapter({
+  signingSecret: process.env.SLACK_SIGNING_SECRET!,
+  clientId: process.env.SLACK_CLIENT_ID!,
+  clientSecret: process.env.SLACK_CLIENT_SECRET!,
+  encryptionKey: process.env.SLACK_ENCRYPTION_KEY,
+});
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: { slack: slackAdapter },
+  state: createRedisState({ url: process.env.REDIS_URL! }),
+});
+```
+
+### OAuth callback
+
+The adapter handles the full Slack OAuth V2 exchange. Point your OAuth redirect URL to a route that calls `handleOAuthCallback`:
+
+```typescript title="app/api/slack/install/callback/route.ts"
+import { slackAdapter } from "@/lib/bot";
+
+export async function GET(request: Request) {
+  const { teamId } = await slackAdapter.handleOAuthCallback(request);
+  return new Response(`Installed for team ${teamId}!`);
+}
+```
+
+### Using the adapter outside webhooks
+
+During webhook handling, the adapter resolves tokens automatically from `team_id`. Outside that context (e.g. cron jobs or background workers), use `getInstallation` and `withBotToken`:
+
+```typescript title="lib/bot.ts" lineNumbers
+const install = await slackAdapter.getInstallation(teamId);
+if (!install) throw new Error("Workspace not installed");
+
+await slackAdapter.withBotToken(install.botToken, async () => {
+  const thread = bot.thread("slack:C12345:1234567890.123456");
+  await thread.post("Hello from a cron job!");
+});
+```
+
+`withBotToken` uses `AsyncLocalStorage` under the hood, so concurrent calls with different tokens are isolated.
+
+### Removing installations
+
+```typescript title="lib/bot.ts"
+await slackAdapter.deleteInstallation(teamId);
+```
+
+### Token encryption
+
+Pass a base64-encoded 32-byte key as `encryptionKey` to encrypt bot tokens at rest using AES-256-GCM:
+
+```sh title="Terminal"
+openssl rand -base64 32
+```
+
+When `encryptionKey` is set, `setInstallation()` encrypts the token before storing and `getInstallation()` decrypts it transparently.
+
+## Slack app setup
+
+### 1. Create a Slack app from manifest
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** then **From an app manifest**
+3. Select your workspace and paste the following manifest:
+
+```yaml title="slack-manifest.yml"
+display_information:
+  name: My Bot
+  description: A bot built with chat-sdk
+
+features:
+  bot_user:
+    display_name: My Bot
+    always_online: true
+
+oauth_config:
+  scopes:
+    bot:
+      - app_mentions:read
+      - channels:history
+      - channels:read
+      - chat:write
+      - groups:history
+      - groups:read
+      - im:history
+      - im:read
+      - mpim:history
+      - mpim:read
+      - reactions:read
+      - reactions:write
+      - users:read
+
+settings:
+  event_subscriptions:
+    request_url: https://your-domain.com/api/webhooks/slack
+    bot_events:
+      - app_mention
+      - message.channels
+      - message.groups
+      - message.im
+      - message.mpim
+      - assistant_thread_started
+      - assistant_thread_context_changed
+  interactivity:
+    is_enabled: true
+    request_url: https://your-domain.com/api/webhooks/slack
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+```
+
+4. Replace `https://your-domain.com/api/webhooks/slack` with your deployed webhook URL
+5. Click **Create**
+
+### 2. Get credentials
+
+After creating the app, go to **Basic Information** → **App Credentials** and copy:
+
+- **Signing Secret** as `SLACK_SIGNING_SECRET`
+- **Client ID** as `SLACK_CLIENT_ID` (multi-workspace only)
+- **Client Secret** as `SLACK_CLIENT_SECRET` (multi-workspace only)
+
+**Single workspace:** Go to **OAuth & Permissions**, click **Install to Workspace**, and copy the **Bot User OAuth Token** (`xoxb-...`) as `SLACK_BOT_TOKEN`.
+
+**Multi-workspace:** Enable **Manage Distribution** under **Basic Information** and set up an OAuth redirect URL pointing to your callback route.
+
+### 3. Configure slash commands (optional)
+
+1. Go to **Slash Commands** in your app settings
+2. Click **Create New Command**
+3. Set **Command** (e.g., `/feedback`)
+4. Set **Request URL** to `https://your-domain.com/api/webhooks/slack`
+5. Add a description and click **Save**
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `botToken` | No | Bot token (`xoxb-...`). Required for single-workspace, omit for multi-workspace |
+| `signingSecret` | Yes | Signing secret for webhook verification |
+| `clientId` | No | App client ID (required for multi-workspace OAuth) |
+| `clientSecret` | No | App client secret (required for multi-workspace OAuth) |
+| `encryptionKey` | No | Base64-encoded 32-byte AES-256-GCM key for encrypting stored tokens |
+
+## Environment variables
+
+```bash title=".env.local"
+SLACK_BOT_TOKEN=xoxb-...             # Single-workspace only
+SLACK_SIGNING_SECRET=...
+SLACK_CLIENT_ID=...                  # Multi-workspace only
+SLACK_CLIENT_SECRET=...              # Multi-workspace only
+SLACK_ENCRYPTION_KEY=...             # Optional, for token encryption
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | Yes |
+| Reactions (add/remove) | Yes |
+| Cards (Block Kit) | Yes |
+| Modals | Yes |
+| Slash commands | Yes |
+| Streaming | Native API |
+| DMs | Yes |
+| Ephemeral messages | Yes (native) |
+| File uploads | Yes |
+| Typing indicator | Yes |
+| Message history | Yes |
+| Assistants API | Yes |
+| App Home tab | Yes |
+
+## Slack Assistants API
+
+The adapter supports Slack's [Assistants API](https://api.slack.com/docs/apps/ai) for building AI-powered assistant experiences. This enables suggested prompts, status indicators, and thread titles in assistant DM threads.
+
+### Event handlers
+
+Register handlers on the `Chat` instance:
+
+```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: "Summarize", message: "Summarize this channel" },
+    { title: "Draft", message: "Help me draft a message" },
+  ]);
+});
+
+bot.onAssistantContextChanged(async (event) => {
+  // User navigated to a different channel with the assistant panel open
+});
+```
+
+### Adapter methods
+
+The `SlackAdapter` exposes these methods for the Assistants API:
+
+| Method | Description |
+|--------|-------------|
+| `setSuggestedPrompts(channelId, threadTs, prompts, title?)` | Show prompt suggestions in the thread |
+| `setAssistantStatus(channelId, threadTs, status)` | Show a thinking/status indicator |
+| `setAssistantTitle(channelId, threadTs, title)` | Set the thread title (shown in History) |
+| `publishHomeView(userId, view)` | Publish a Home tab view for a user |
+
+### Required scopes and events
+
+Add these to your Slack app manifest for Assistants API support:
+
+```yaml title="slack-manifest.yml"
+oauth_config:
+  scopes:
+    bot:
+      - assistant:write
+
+settings:
+  event_subscriptions:
+    bot_events:
+      - assistant_thread_started
+      - assistant_thread_context_changed
+```
+
+### Stream with stop blocks
+
+When streaming in an assistant thread, you can attach Block Kit elements to the final message:
+
+```typescript title="lib/bot.ts"
+await thread.stream(textStream, {
+  stopBlocks: [
+    { type: "actions", elements: [{ type: "button", text: { type: "plain_text", text: "Retry" }, action_id: "retry" }] },
+  ],
+});
+```
+
+## Troubleshooting
+
+### "Invalid signature" error
+
+- Verify `SLACK_SIGNING_SECRET` is correct
+- Check that the request timestamp is within 5 minutes (clock sync issue)
+
+### Bot not responding to messages
+
+- Verify event subscriptions are configured
+- Check that the bot has been added to the channel
+- Ensure the webhook URL is correct and accessible