chat 4.18.0 → 4.19.0

package/docs/adapters/linear.mdx

@@ -1,206 +0,0 @@
----
-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
-
-The adapter auto-detects credentials from `LINEAR_API_KEY` (or `LINEAR_CLIENT_ID`/`LINEAR_CLIENT_SECRET`), `LINEAR_WEBHOOK_SECRET`, and `LINEAR_BOT_USERNAME` environment variables:
-
-```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(),
-  },
-});
-
-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!,
-});
-```
-
-### 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!,
-});
-```
-
-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
-
-All options are auto-detected from environment variables when not provided.
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `apiKey` | No* | Personal API key. Auto-detected from `LINEAR_API_KEY` |
-| `clientId` | No* | OAuth app client ID. Auto-detected from `LINEAR_CLIENT_ID` |
-| `clientSecret` | No* | OAuth app client secret. Auto-detected from `LINEAR_CLIENT_SECRET` |
-| `accessToken` | No* | Pre-obtained OAuth access token. Auto-detected from `LINEAR_ACCESS_TOKEN` |
-| `webhookSecret` | No** | Webhook signing secret. Auto-detected from `LINEAR_WEBHOOK_SECRET` |
-| `userName` | No | Bot display name. Auto-detected from `LINEAR_BOT_USERNAME` (default: `"linear-bot"`) |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*One of `apiKey`, `clientId`/`clientSecret`, or `accessToken` is required (via config or env vars).
-
-**`webhookSecret` is required — either via config or `LINEAR_WEBHOOK_SECRET` env var.
-
-## 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

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

package/docs/adapters/slack.mdx

@@ -1,314 +0,0 @@
----
-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. The adapter auto-detects `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` from environment variables:
-
-```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(),
-  },
-});
-
-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.
-
-When you pass any auth-related config (like `clientId`), the adapter won't fall back to env vars for other auth fields, preventing accidental mixing of auth modes.
-
-```typescript title="lib/bot.ts" lineNumbers
-import { createSlackAdapter } from "@chat-adapter/slack";
-import { createRedisState } from "@chat-adapter/state-redis";
-
-const slackAdapter = createSlackAdapter({
-  clientId: process.env.SLACK_CLIENT_ID!,
-  clientSecret: process.env.SLACK_CLIENT_SECRET!,
-});
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { slack: slackAdapter },
-  state: createRedisState(),
-});
-```
-
-### 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
-      - member_joined_channel
-      - 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
-
-All options are auto-detected from environment variables when not provided. You can call `createSlackAdapter()` with no arguments if the env vars are set.
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `botToken` | No | Bot token (`xoxb-...`). Auto-detected from `SLACK_BOT_TOKEN` |
-| `signingSecret` | No* | Signing secret for webhook verification. Auto-detected from `SLACK_SIGNING_SECRET` |
-| `clientId` | No | App client ID for multi-workspace OAuth. Auto-detected from `SLACK_CLIENT_ID` |
-| `clientSecret` | No | App client secret for multi-workspace OAuth. Auto-detected from `SLACK_CLIENT_SECRET` |
-| `encryptionKey` | No | AES-256-GCM key for encrypting stored tokens. Auto-detected from `SLACK_ENCRYPTION_KEY` |
-| `installationKeyPrefix` | No | Prefix for the state key used to store workspace installations. Defaults to `slack:installation`. The full key is `{prefix}:{teamId}` |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*`signingSecret` is required — either via config or `SLACK_SIGNING_SECRET` env var.
-
-## 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 |
-| Member joined channel | 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 |
-| `startTyping(threadId, status)` | Show a custom loading status (requires `assistant:write` scope) |
-
-### 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
-
-### `handleOAuthCallback` throws "Adapter not initialized"
-
-- Call `await bot.initialize()` before `handleOAuthCallback()` in your callback route.
-- In a Next.js app, this ensures:
-  - state adapter is connected
-  - the Slack adapter is attached to Chat
-  - installation writes succeed
-
-```typescript title="app/api/slack/install/callback/route.ts" lineNumbers
-const slackAdapter = bot.getAdapter("slack");
-
-await bot.initialize();
-await slackAdapter.handleOAuthCallback(request);
-```
-
-### "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