@chat-adapter/slack 4.2.0 → 4.4.0

package/README.md

@@ -37,29 +37,70 @@ chat.onNewMention(async (thread, message) => {
 | `botToken` | Yes | Slack bot token (starts with `xoxb-`) |
 | `signingSecret` | Yes | Slack signing secret for webhook verification |
 
-## Required Slack Scopes
-
-Your Slack app needs these OAuth scopes:
-
-**Bot Token Scopes:**
-- `chat:write` - Send messages
-- `channels:history` - Read channel messages
-- `groups:history` - Read private channel messages
-- `im:history` - Read DM messages
-- `mpim:history` - Read group DM messages
-- `reactions:read` - Read reactions
-- `reactions:write` - Add reactions
-- `files:read` - Read file attachments
-- `users:read` - Read user info
-
-**Event Subscriptions:**
-- `message.channels` - Channel messages
-- `message.groups` - Private channel messages
-- `message.im` - Direct messages
-- `message.mpim` - Group DMs
-- `app_mention` - @mentions
-- `reaction_added` - Reaction events
-- `reaction_removed` - Reaction events
+## Environment Variables
+
+```bash
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_SIGNING_SECRET=...
+```
+
+## 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
+
+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
+
+1. Go to **Basic Information**
+2. Under **App Credentials**, copy **Signing Secret** → `SLACK_SIGNING_SECRET`
+
+### 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
 
@@ -71,6 +112,17 @@ Your Slack app needs these OAuth scopes:
 - 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)
+
+### 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
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CardElement, BaseFormatConverter, AdapterPostableMessage, Root, Adapter, ChatInstance, WebhookOptions, RawMessage, EmojiValue, StreamOptions, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
+import { CardElement, BaseFormatConverter, AdapterPostableMessage, Root, Logger, Adapter, ChatInstance, WebhookOptions, RawMessage, ModalElement, EmojiValue, StreamOptions, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
 
 /**
  * Slack Block Kit converter for cross-platform cards.
@@ -60,6 +60,8 @@ interface SlackAdapterConfig {
     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) */
@@ -132,7 +134,7 @@ declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
     private lookupUser;
     handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
     /**
-     * Handle Slack interactive payloads (button clicks, etc.).
+     * Handle Slack interactive payloads (button clicks, view submissions, etc.).
      * These are sent as form-urlencoded with a `payload` JSON field.
      */
     private handleInteractivePayload;
@@ -140,6 +142,9 @@ declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
      * Handle block_actions payload (button clicks in Block Kit).
      */
     private handleBlockActions;
+    private handleViewSubmission;
+    private handleViewClosed;
+    private modalResponseToSlack;
     private verifySignature;
     /**
      * Handle message events from Slack.
@@ -157,14 +162,12 @@ declare class SlackAdapter implements Adapter<SlackThreadId, unknown> {
      */
     private createAttachment;
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<unknown>>;
-    /**
-     * Extract card element from a AdapterPostableMessage if present.
-     */
-    private extractCard;
-    /**
-     * Extract files from a AdapterPostableMessage if present.
-     */
-    private extractFiles;
+    openModal(triggerId: string, modal: ModalElement): Promise<{
+        viewId: string;
+    }>;
+    updateModal(viewId: string, modal: ModalElement): Promise<{
+        viewId: string;
+    }>;
     /**
      * Upload files to Slack and share them to a channel.
      * Returns the file IDs of uploaded files.