@chat-adapter/slack 4.8.0 → 4.9.0

package/README.md

@@ -8,7 +8,7 @@ Slack adapter for the [chat](https://github.com/vercel-labs/chat) SDK.
 npm install chat @chat-adapter/slack
 ```
 
-## Usage
+## Usage (Single Workspace)
 
 ```typescript
 import { Chat } from "chat";
@@ -30,18 +30,109 @@ chat.onNewMention(async (thread, message) => {
 });
 ```
 
+## 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` | Yes | Slack bot token (starts with `xoxb-`) |
+| `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-...
+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
@@ -71,15 +162,22 @@ SLACK_SIGNING_SECRET=...
 
 ### 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`
 
-### 4. Get Signing Secret
+**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`
+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
 
@@ -104,6 +202,7 @@ If you want to use buttons, modals, or other interactive components:
 
 ## Features
 
+- Multi-workspace support with OAuth V2 and encrypted token storage
 - Message posting and editing
 - Thread subscriptions
 - Reaction handling (add/remove/events)

package/dist/index.d.ts

@@ -22,6 +22,13 @@ declare function cardToBlockKit(card: CardElement): SlackBlock[];
  */
 declare function cardToFallbackText(card: CardElement): string;
 
+interface EncryptedTokenData {
+    iv: string;
+    data: string;
+    tag: string;
+}
+declare function decodeKey(rawKey: string): Buffer;
+
 /**
  * Slack-specific format conversion using AST-based parsing.
  *
@@ -56,8 +63,8 @@ declare class SlackFormatConverter extends BaseFormatConverter {
 }
 
 interface SlackAdapterConfig {
-    /** Bot token (xoxb-...) */
-    botToken: string;
+    /** 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 */
@@ -66,6 +73,21 @@ interface SlackAdapterConfig {
     userName?: string;
     /** Bot user ID (will be fetched if not provided) */
     botUserId?: 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;
+}
+/** Data stored per Slack workspace installation */
+interface SlackInstallation {
+    botToken: string;
+    botUserId?: string;
+    teamName?: string;
 }
 /** Slack-specific thread ID data */
 interface SlackThreadId {
@@ -118,23 +140,75 @@ declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
     readonly userName: string;
     private client;
     private signingSecret;
-    private botToken;
+    private defaultBotToken;
     private chat;
     private logger;
     private _botUserId;
     private _botId;
     private formatConverter;
     private static USER_CACHE_TTL_MS;
+    private clientId;
+    private clientSecret;
+    private encryptionKey;
+    private requestContext;
     /** Bot user ID (e.g., U_BOT_123) used for mention detection */
     get botUserId(): string | undefined;
     constructor(config: SlackAdapterConfig);
+    /**
+     * Get the current bot token for API calls.
+     * Checks request context (multi-workspace) → default token (single-workspace) → throws.
+     */
+    private getToken;
+    /**
+     * Add the current token to API call options.
+     * Workaround for Slack WebClient types not including `token` in per-method args.
+     */
+    private withToken;
     initialize(chat: ChatInstance): Promise<void>;
+    private installationKey;
+    /**
+     * Save a Slack workspace installation.
+     * Call this from your OAuth callback route after a successful installation.
+     */
+    setInstallation(teamId: string, installation: SlackInstallation): Promise<void>;
+    /**
+     * Retrieve a Slack workspace installation.
+     */
+    getInstallation(teamId: string): Promise<SlackInstallation | null>;
+    /**
+     * Handle the Slack OAuth V2 callback.
+     * Accepts the incoming request, extracts the authorization code,
+     * exchanges it for tokens, and saves the installation.
+     */
+    handleOAuthCallback(request: Request): Promise<{
+        teamId: string;
+        installation: SlackInstallation;
+    }>;
+    /**
+     * Remove a Slack workspace installation.
+     */
+    deleteInstallation(teamId: string): Promise<void>;
+    /**
+     * Run a function with a specific bot token in context.
+     * Use this for operations outside webhook handling (cron jobs, workflows).
+     */
+    withBotToken<T>(token: string, fn: () => T): T;
+    /**
+     * Resolve the bot token for a team from the state adapter.
+     */
+    private resolveTokenForTeam;
+    /**
+     * Extract team_id from an interactive payload (form-urlencoded).
+     */
+    private extractTeamIdFromInteractive;
     /**
      * Look up user info from Slack API with caching via state adapter.
      * Returns display name and real name, or falls back to user ID.
      */
     private lookupUser;
     handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /** Extract and dispatch events from a validated payload */
+    private processEventPayload;
     /**
      * Handle Slack interactive payloads (button clicks, view submissions, etc.).
      * These are sent as form-urlencoded with a `payload` JSON field.
@@ -247,4 +321,4 @@ declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
 }
 declare function createSlackAdapter(config: SlackAdapterConfig): SlackAdapter;
 
-export { SlackAdapter, type SlackAdapterConfig, type SlackEvent, SlackFormatConverter, SlackFormatConverter as SlackMarkdownConverter, type SlackReactionEvent, type SlackThreadId, cardToBlockKit, cardToFallbackText, createSlackAdapter };
+export { type EncryptedTokenData, SlackAdapter, type SlackAdapterConfig, type SlackEvent, SlackFormatConverter, type SlackInstallation, SlackFormatConverter as SlackMarkdownConverter, type SlackReactionEvent, type SlackThreadId, cardToBlockKit, cardToFallbackText, createSlackAdapter, decodeKey };