@chat-adapter/slack 4.13.0 → 4.13.2

package/README.md

@@ -1,6 +1,9 @@
 # @chat-adapter/slack
 
-Slack adapter for the [chat](https://github.com/vercel-labs/chat) SDK.
+[![npm version](https://img.shields.io/npm/v/@chat-adapter/slack)](https://www.npmjs.com/package/@chat-adapter/slack)
+[![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/slack)](https://www.npmjs.com/package/@chat-adapter/slack)
+
+Slack adapter for [Chat SDK](https://chat-sdk.dev/docs). Supports single-workspace and multi-workspace OAuth deployments.
 
 ## Installation
 
@@ -8,13 +11,13 @@ Slack adapter for the [chat](https://github.com/vercel-labs/chat) SDK.
 npm install chat @chat-adapter/slack
 ```
 
-## Usage (Single Workspace)
+## Usage
 
 ```typescript
 import { Chat } from "chat";
 import { createSlackAdapter } from "@chat-adapter/slack";
 
-const chat = new Chat({
+const bot = new Chat({
   userName: "mybot",
   adapters: {
     slack: createSlackAdapter({
@@ -24,203 +27,14 @@ const chat = new Chat({
   },
 });
 
-// Handle @mentions
-chat.onNewMention(async (thread, message) => {
+bot.onNewMention(async (thread, message) => {
   await thread.post("Hello from Slack!");
 });
 ```
 
-## Multi-Workspace Mode
-
-For apps installed across multiple Slack workspaces, omit `botToken` and let the adapter resolve tokens dynamically from your state adapter (e.g. Redis) using the `team_id` from incoming webhooks.
-
-```typescript
-import { Chat } from "chat";
-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!,
-  logger: logger,
-  encryptionKey: process.env.SLACK_ENCRYPTION_KEY, // optional, encrypts tokens at rest
-});
-
-const chat = new Chat({
-  userName: "mybot",
-  adapters: { slack: slackAdapter },
-  state: createRedisState({ url: process.env.REDIS_URL! }),
-  // notice that there is no bot token
-});
-```
-
-### OAuth callback
-
-The adapter handles the full Slack OAuth V2 exchange. Pass `clientId` and `clientSecret` in the config, then point your OAuth redirect URL to a route that calls `handleOAuthCallback`:
-
-```typescript
-import { slackAdapter } from "@/lib/chat"; // your adapter instance
-
-export async function GET(request: Request) {
-  const { teamId } = await slackAdapter.handleOAuthCallback(request);
-  return new Response(`Installed for team ${teamId}!`);
-}
-```
-
-### Webhook handling
-
-No changes needed — the adapter extracts `team_id` from incoming webhooks and resolves the token automatically:
-
-```typescript
-export async function POST(request: Request) {
-  return chat.webhooks.slack(request, { waitUntil });
-}
-```
-
-### Using the adapter outside a webhook (cron jobs, workflows)
-
-During webhook handling, the adapter resolves the token automatically from `team_id`. Outside that context (e.g. a cron job), use `getInstallation` to retrieve the token and `withBotToken` to scope it:
-
-```typescript
-import { Chat } from "chat";
-
-// In a cron job or background worker:
-const install = await slackAdapter.getInstallation(teamId);
-if (!install) throw new Error("Workspace not installed");
-
-await slackAdapter.withBotToken(install.botToken, async () => {
-  // All adapter calls inside this callback use the provided token.
-  // You can use thread.post(), thread.subscribe(), etc. normally.
-  const thread = chat.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 from each other.
-
-### Removing installations
-
-```typescript
-await slackAdapter.deleteInstallation(teamId);
-```
-
-### Encryption
-
-Pass a base64-encoded 32-byte key as `encryptionKey` to encrypt bot tokens at rest using AES-256-GCM. You can generate a key with:
-
-```bash
-openssl rand -base64 32
-```
-
-When `encryptionKey` is set, `setInstallation()` encrypts the token before storing it and `getInstallation()` decrypts it transparently.
-
-## Configuration
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `botToken` | No | Slack bot token (`xoxb-...`). Required for single-workspace mode. Omit for multi-workspace. |
-| `signingSecret` | Yes | Slack signing secret for webhook verification |
-| `clientId` | No | Slack app client ID (required for OAuth / multi-workspace) |
-| `clientSecret` | No | Slack app client secret (required for OAuth / multi-workspace) |
-| `encryptionKey` | No | Base64-encoded 32-byte AES-256-GCM key for encrypting stored tokens |
-
-## Environment Variables
-
-```bash
-SLACK_BOT_TOKEN=xoxb-...           # single-workspace only
-SLACK_SIGNING_SECRET=...
-SLACK_CLIENT_ID=...                # required for multi-workspace OAuth
-SLACK_CLIENT_SECRET=...            # required for multi-workspace OAuth
-SLACK_ENCRYPTION_KEY=...           # optional, for multi-workspace token encryption
-```
-
-## Slack App Setup
-
-### 1. Create a Slack App
-
-1. Go to [api.slack.com/apps](https://api.slack.com/apps)
-2. Click **Create New App** → **From scratch**
-3. Enter app name and select workspace
-4. Click **Create App**
-
-### 2. Configure Bot Token Scopes
-
-1. Go to **OAuth & Permissions** in the sidebar
-2. Under **Scopes** → **Bot Token Scopes**, add:
-   - `app_mentions:read` - Receive @mention events
-   - `channels:history` - Read messages in public channels
-   - `channels:read` - View basic channel info
-   - `chat:write` - Send messages
-   - `groups:history` - Read messages in private channels
-   - `groups:read` - View basic private channel info
-   - `im:history` - Read direct messages
-   - `im:read` - View basic DM info
-   - `reactions:read` - View emoji reactions
-   - `reactions:write` - Add/remove emoji reactions
-   - `users:read` - View user info (for display names)
-
-### 3. Install App to Workspace
-
-**Single workspace:** Install directly from the Slack dashboard.
-
-1. Go to **OAuth & Permissions**
-2. Click **Install to Workspace**
-3. Authorize the app
-4. Copy the **Bot User OAuth Token** (starts with `xoxb-`) → `SLACK_BOT_TOKEN`
-
-**Multi-workspace:** Enable **Manage Distribution** under **Basic Information**, then set up an [OAuth redirect URL](https://api.slack.com/authentication/oauth-v2) pointing to your callback route. The adapter handles the token exchange via `handleOAuthCallback()` (see [Multi-Workspace Mode](#multi-workspace-mode) above).
-
-### 4. Get Signing Secret and OAuth Credentials
-
-1. Go to **Basic Information**
-2. Under **App Credentials**, copy:
-   - **Signing Secret** → `SLACK_SIGNING_SECRET`
-   - **Client ID** → `SLACK_CLIENT_ID` (multi-workspace only)
-   - **Client Secret** → `SLACK_CLIENT_SECRET` (multi-workspace only)
-
-### 5. Configure Event Subscriptions
-
-1. Go to **Event Subscriptions**
-2. Toggle **Enable Events** to On
-3. Set **Request URL** to: `https://your-domain.com/api/webhooks/slack`
-   - Slack will verify the URL immediately
-4. Under **Subscribe to bot events**, add:
-   - `app_mention` - When someone @mentions your bot
-   - `message.channels` - Messages in public channels
-   - `message.groups` - Messages in private channels
-   - `message.im` - Direct messages
-5. Click **Save Changes**
-
-### 6. (Optional) Enable Interactivity
-
-If you want to use buttons, modals, or other interactive components:
-
-1. Go to **Interactivity & Shortcuts**
-2. Toggle **Interactivity** to On
-3. Set **Request URL** to: `https://your-domain.com/api/webhooks/slack`
-
-## Features
-
-- Multi-workspace support with OAuth V2 and encrypted token storage
-- Message posting and editing
-- Thread subscriptions
-- Reaction handling (add/remove/events)
-- File attachments
-- Rich cards (Block Kit)
-- Action callbacks (interactive components)
-- Direct messages
-
-## Troubleshooting
-
-### "Invalid signature" error
-- Verify `SLACK_SIGNING_SECRET` is correct
-- Check that the request timestamp is within 5 minutes (clock sync issue)
+## Documentation
 
-### 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
+Full setup instructions, configuration reference, and features at [chat-sdk.dev/docs/adapters/slack](https://chat-sdk.dev/docs/adapters/slack).
 
 ## License
 

package/dist/index.d.ts

@@ -8,8 +8,8 @@ import { CardElement, BaseFormatConverter, AdapterPostableMessage, Root, Logger,
  */
 
 interface SlackBlock {
-    type: string;
     block_id?: string;
+    type: string;
     [key: string]: unknown;
 }
 /**
@@ -23,8 +23,8 @@ declare function cardToBlockKit(card: CardElement): SlackBlock[];
 declare function cardToFallbackText(card: CardElement): string;
 
 interface EncryptedTokenData {
-    iv: string;
     data: string;
+    iv: string;
     tag: string;
 }
 declare function decodeKey(rawKey: string): Buffer;
@@ -65,23 +65,23 @@ declare class SlackFormatConverter extends BaseFormatConverter {
 interface SlackAdapterConfig {
     /** Bot token (xoxb-...). Required for single-workspace mode. Omit for multi-workspace. */
     botToken?: string;
-    /** Signing secret for webhook verification */
-    signingSecret: string;
-    /** Logger instance for error reporting */
-    logger: Logger;
-    /** Override bot username (optional) */
-    userName?: string;
     /** Bot user ID (will be fetched if not provided) */
     botUserId?: string;
+    /** Slack app client ID (required for OAuth / multi-workspace) */
+    clientId?: string;
+    /** Slack app client secret (required for OAuth / multi-workspace) */
+    clientSecret?: string;
     /**
      * Base64-encoded 32-byte AES-256-GCM encryption key.
      * If provided, bot tokens stored via setInstallation() will be encrypted at rest.
      */
     encryptionKey?: string;
-    /** Slack app client ID (required for OAuth / multi-workspace) */
-    clientId?: string;
-    /** Slack app client secret (required for OAuth / multi-workspace) */
-    clientSecret?: string;
+    /** Logger instance for error reporting */
+    logger: Logger;
+    /** Signing secret for webhook verification */
+    signingSecret: string;
+    /** Override bot username (optional) */
+    userName?: string;
 }
 /** Data stored per Slack workspace installation */
 interface SlackInstallation {
@@ -96,20 +96,13 @@ interface SlackThreadId {
 }
 /** Slack event payload (raw message format) */
 interface SlackEvent {
-    type: string;
-    user?: string;
     bot_id?: string;
     channel?: string;
-    text?: string;
-    ts?: string;
-    thread_ts?: string;
-    subtype?: string;
-    username?: string;
+    /** Channel type: "channel", "group", "mpim", or "im" (DM) */
+    channel_type?: string;
     edited?: {
         ts: string;
     };
-    /** Channel type: "channel", "group", "mpim", or "im" (DM) */
-    channel_type?: string;
     files?: Array<{
         id?: string;
         mimetype?: string;
@@ -119,42 +112,49 @@ interface SlackEvent {
         original_w?: number;
         original_h?: number;
     }>;
-    team?: string;
-    team_id?: string;
-    /** Number of replies in the thread (present on thread parent messages) */
-    reply_count?: number;
     /** Timestamp of the latest reply (present on thread parent messages) */
     latest_reply?: string;
+    /** Number of replies in the thread (present on thread parent messages) */
+    reply_count?: number;
+    subtype?: string;
+    team?: string;
+    team_id?: string;
+    text?: string;
+    thread_ts?: string;
+    ts?: string;
+    type: string;
+    user?: string;
+    username?: string;
 }
 /** Slack reaction event payload */
 interface SlackReactionEvent {
-    type: "reaction_added" | "reaction_removed";
-    user: string;
-    reaction: string;
-    item_user?: string;
+    event_ts: string;
     item: {
         type: string;
         channel: string;
         ts: string;
     };
-    event_ts: string;
+    item_user?: string;
+    reaction: string;
+    type: "reaction_added" | "reaction_removed";
+    user: string;
 }
 declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
     readonly name = "slack";
     readonly userName: string;
-    private client;
-    private signingSecret;
-    private defaultBotToken;
+    private readonly client;
+    private readonly signingSecret;
+    private readonly defaultBotToken;
     private chat;
-    private logger;
+    private readonly logger;
     private _botUserId;
     private _botId;
-    private formatConverter;
+    private readonly formatConverter;
     private static USER_CACHE_TTL_MS;
-    private clientId;
-    private clientSecret;
-    private encryptionKey;
-    private requestContext;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly encryptionKey;
+    private readonly requestContext;
     /** Bot user ID (e.g., U_BOT_123) used for mention detection */
     get botUserId(): string | undefined;
     constructor(config: SlackAdapterConfig);