digital-workers 2.1.3 → 2.4.0

package/dist/transports/slack.js

@@ -0,0 +1,844 @@
+/**
+ * Slack Transport Adapter for Digital Workers
+ *
+ * Provides Slack-based communication for worker notifications, questions,
+ * and approval workflows using the Slack Web API and Block Kit.
+ *
+ * Features:
+ * - Send notifications to channels (#channel) and DMs (@user)
+ * - Rich message formatting with Block Kit
+ * - Interactive button components for approvals
+ * - Webhook handling for button interactions
+ * - Request signature verification
+ *
+ * @packageDocumentation
+ */
+import { registerTransport } from '../transports.js';
+import { noopLogger } from '../logger.js';
+import { generateRequestId } from '../utils/id.js';
+// =============================================================================
+// Crypto Functions for Signature Verification
+// =============================================================================
+/**
+ * Compute HMAC-SHA256 and return the result as a hex string.
+ * Uses the Web Crypto API which works in both Node.js and Cloudflare Workers.
+ *
+ * @param data - The data to sign
+ * @param secret - The signing secret
+ * @returns A hex-encoded HMAC-SHA256 hash
+ */
+export async function computeHmacSha256Hex(data, secret) {
+    const encoder = new TextEncoder();
+    // Import the secret as a crypto key
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    // Sign the data
+    const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+    // Convert to hex string
+    return Array.from(new Uint8Array(signature))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Verify a Slack request signature using HMAC-SHA256.
+ * Uses the Web Crypto API which works in both Node.js and Cloudflare Workers.
+ *
+ * @param signature - The x-slack-signature header value (v0=...)
+ * @param timestamp - The x-slack-request-timestamp header value
+ * @param body - The raw request body
+ * @param signingSecret - The Slack signing secret
+ * @returns true if the signature is valid, false otherwise
+ */
+export async function verifySlackSignature(signature, timestamp, body, signingSecret) {
+    // Slack signatures have the format "v0=<hex>"
+    if (!signature.startsWith('v0=')) {
+        return false;
+    }
+    // Compute the expected signature
+    const baseString = `v0:${timestamp}:${body}`;
+    const expectedHmac = await computeHmacSha256Hex(baseString, signingSecret);
+    const expectedSignature = `v0=${expectedHmac}`;
+    // Constant-time comparison to prevent timing attacks
+    return secureCompare(signature, expectedSignature);
+}
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Returns true if both strings are equal, false otherwise.
+ */
+function secureCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+// =============================================================================
+// SlackTransport Class
+// =============================================================================
+/**
+ * Slack Transport for digital-workers communication
+ *
+ * @example
+ * ```ts
+ * const slack = new SlackTransport({
+ *   botToken: process.env.SLACK_BOT_TOKEN!,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ * })
+ *
+ * // Send notification to a channel
+ * await slack.sendNotification('#engineering', 'Deployment complete!')
+ *
+ * // Send approval request
+ * const result = await slack.sendApprovalRequest('@alice', 'Approve deployment?', {
+ *   context: { version: '2.1.0' },
+ * })
+ *
+ * // Handle webhook
+ * app.post('/slack/events', async (req, res) => {
+ *   const result = await slack.handleWebhook(req)
+ *   res.json({ ok: result.success })
+ * })
+ * ```
+ */
+export class SlackTransport {
+    config;
+    apiBaseUrl;
+    logger;
+    constructor(config) {
+        this.config = {
+            ...config,
+            transport: 'slack',
+        };
+        this.apiBaseUrl = config.apiUrl || 'https://slack.com/api';
+        this.logger = config.logger ?? noopLogger;
+    }
+    // ===========================================================================
+    // Public Methods
+    // ===========================================================================
+    /**
+     * Send a notification message
+     *
+     * @param target - Channel (#channel) or user (@user or user ID)
+     * @param message - Message text
+     * @param options - Additional message options
+     */
+    async sendNotification(target, message, options = {}) {
+        try {
+            const channel = await this.resolveTarget(target);
+            const blocks = this.formatNotificationBlocks(message, options);
+            const thread_ts = options.threadTs;
+            const metadata = options.metadata
+                ? {
+                    event_type: 'notification',
+                    event_payload: options.metadata,
+                }
+                : undefined;
+            const response = await this.postMessage({
+                channel,
+                text: message,
+                blocks,
+                ...(thread_ts !== undefined && { thread_ts }),
+                ...(metadata !== undefined && { metadata }),
+            });
+            return {
+                success: response.ok,
+                transport: 'slack',
+                messageId: response.ts,
+                metadata: {
+                    channel: response.channel,
+                    ts: response.ts,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                transport: 'slack',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Send an approval request with interactive buttons
+     *
+     * @param target - Channel (#channel) or user (@user or user ID)
+     * @param request - Approval request text
+     * @param options - Additional options
+     */
+    async sendApprovalRequest(target, request, options = {}) {
+        try {
+            const channel = await this.resolveTarget(target);
+            const requestId = options.requestId || this.generateRequestId();
+            const blocks = this.formatApprovalBlocks(request, {
+                ...options,
+                requestId,
+            });
+            const response = await this.postMessage({
+                channel,
+                text: `Approval Request: ${request}`,
+                blocks,
+                metadata: {
+                    event_type: 'approval_request',
+                    event_payload: {
+                        requestId,
+                        context: options.context,
+                        timeout: options.timeout,
+                    },
+                },
+            });
+            return {
+                success: response.ok,
+                transport: 'slack',
+                messageId: response.ts,
+                metadata: {
+                    channel: response.channel,
+                    ts: response.ts,
+                    requestId,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                transport: 'slack',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Send a question with optional response options
+     *
+     * @param target - Channel (#channel) or user (@user or user ID)
+     * @param question - Question text
+     * @param options - Additional options
+     */
+    async sendQuestion(target, question, options = {}) {
+        try {
+            const channel = await this.resolveTarget(target);
+            const requestId = options.requestId || this.generateRequestId();
+            const blocks = this.formatQuestionBlocks(question, {
+                ...options,
+                requestId,
+            });
+            const thread_ts = options.threadTs;
+            const choices = options.choices;
+            const metadata = {
+                event_type: 'question',
+                event_payload: {
+                    requestId,
+                    ...(choices !== undefined && { choices }),
+                },
+            };
+            const response = await this.postMessage({
+                channel,
+                text: question,
+                blocks,
+                ...(thread_ts !== undefined && { thread_ts }),
+                ...(metadata !== undefined && { metadata }),
+            });
+            return {
+                success: response.ok,
+                transport: 'slack',
+                messageId: response.ts,
+                metadata: {
+                    channel: response.channel,
+                    ts: response.ts,
+                    requestId,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                transport: 'slack',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Handle incoming webhook from Slack (button interactions, etc.)
+     *
+     * @param request - Webhook request with headers and body
+     */
+    async handleWebhook(request) {
+        // Verify signature using async Web Crypto API
+        try {
+            const isValid = await this.verifySignatureAsync(request);
+            if (!isValid) {
+                return {
+                    success: false,
+                    error: 'Invalid request signature',
+                };
+            }
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Signature verification failed',
+            };
+        }
+        // Parse payload
+        const payload = this.parseWebhookPayload(request);
+        if (!payload) {
+            return {
+                success: false,
+                error: 'Invalid webhook payload',
+            };
+        }
+        // Handle block actions (button clicks)
+        if (payload.type === 'block_actions' && payload.actions?.length) {
+            const action = payload.actions[0];
+            if (!action) {
+                return {
+                    success: false,
+                    error: 'No action found in payload',
+                };
+            }
+            const channelId = payload.channel?.id;
+            const messageTs = payload.message?.ts;
+            return {
+                success: true,
+                actionId: action.action_id,
+                userId: payload.user.id,
+                ...(channelId !== undefined && { channelId }),
+                ...(messageTs !== undefined && { messageTs }),
+                value: this.parseActionValue(action.value),
+            };
+        }
+        return {
+            success: false,
+            error: `Unsupported interaction type: ${payload.type}`,
+        };
+    }
+    /**
+     * Update an existing message (for approval status updates, etc.)
+     *
+     * @param channel - Channel ID
+     * @param ts - Message timestamp
+     * @param text - New text
+     * @param blocks - New blocks
+     */
+    async updateMessage(channel, ts, text, blocks) {
+        return this.callApi('chat.update', {
+            channel,
+            ts,
+            text,
+            blocks,
+        });
+    }
+    /**
+     * Open a DM channel with a user
+     *
+     * @param userId - User ID to open DM with
+     */
+    async openDM(userId) {
+        const response = await this.callApi('conversations.open', {
+            users: userId,
+        });
+        if (!response.ok || !response.channel?.id) {
+            throw new Error(response.error || 'Failed to open DM');
+        }
+        return response.channel.id;
+    }
+    /**
+     * Look up user by email
+     *
+     * @param email - User email address
+     */
+    async lookupUserByEmail(email) {
+        try {
+            const response = await this.callApi('users.lookupByEmail', {
+                email,
+            });
+            if (!response.ok) {
+                return null;
+            }
+            return response.user?.id || null;
+        }
+        catch (error) {
+            // User not found or other API error - log for debugging
+            this.logger.error('lookupUserByEmail failed', error instanceof Error ? error : undefined, {
+                email,
+                operation: 'lookupUserByEmail',
+            });
+            return null;
+        }
+    }
+    /**
+     * Get the transport handler for registration
+     */
+    getHandler() {
+        return async (payload, config) => {
+            const target = Array.isArray(payload.to) ? payload.to[0] : payload.to;
+            if (!target) {
+                return {
+                    success: false,
+                    transport: 'slack',
+                    error: 'No target specified',
+                };
+            }
+            if (payload.type === 'approval') {
+                const context = payload.metadata;
+                return this.sendApprovalRequest(target, payload.body, {
+                    ...(context !== undefined && { context }),
+                });
+            }
+            if (payload.type === 'question') {
+                const choices = payload.actions?.map((a) => a.label);
+                return this.sendQuestion(target, payload.body, {
+                    ...(choices !== undefined && { choices }),
+                });
+            }
+            const priority = payload.priority;
+            const metadata = payload.metadata;
+            return this.sendNotification(target, payload.body, {
+                ...(priority !== undefined && { priority }),
+                ...(metadata !== undefined && { metadata }),
+            });
+        };
+    }
+    /**
+     * Register this transport with the transport registry
+     */
+    register() {
+        registerTransport('slack', this.getHandler());
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Resolve target to channel ID
+     * - #channel -> channel name lookup
+     * - @user -> DM with user
+     * - C/U/D ID -> direct use
+     */
+    async resolveTarget(target) {
+        // Already a channel/user ID
+        if (/^[CUD][A-Z0-9]+$/.test(target)) {
+            return target;
+        }
+        // Channel reference (#channel)
+        if (target.startsWith('#')) {
+            // Return channel name, Slack API accepts this
+            return target.slice(1);
+        }
+        // User reference (@user)
+        if (target.startsWith('@')) {
+            const username = target.slice(1);
+            // Try to find user and open DM
+            const userId = await this.findUserByName(username);
+            if (userId) {
+                return this.openDM(userId);
+            }
+            throw new Error(`User not found: ${username}`);
+        }
+        // Assume it's a channel name or ID
+        return target;
+    }
+    /**
+     * Find user by display name (limited functionality)
+     */
+    async findUserByName(name) {
+        // Note: This would require users:read scope and iterating through users
+        // For production, you'd want to implement proper user lookup
+        // or use users.lookupByEmail if you have the email
+        return null;
+    }
+    /**
+     * Format notification message blocks
+     */
+    formatNotificationBlocks(message, options) {
+        const blocks = [];
+        // Add priority indicator for high/urgent
+        if (options.priority === 'urgent' || options.priority === 'high') {
+            const emoji = options.priority === 'urgent' ? ':rotating_light:' : ':warning:';
+            blocks.push({
+                type: 'header',
+                text: {
+                    type: 'plain_text',
+                    text: `${emoji} ${options.priority.toUpperCase()}`,
+                    emoji: true,
+                },
+            });
+        }
+        // Main message
+        blocks.push({
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: message,
+            },
+        });
+        // Add context if metadata provided
+        if (options.metadata && Object.keys(options.metadata).length > 0) {
+            blocks.push({
+                type: 'divider',
+            });
+            blocks.push({
+                type: 'context',
+                elements: [
+                    {
+                        type: 'mrkdwn',
+                        text: Object.entries(options.metadata)
+                            .map(([k, v]) => `*${k}:* ${v}`)
+                            .join(' | '),
+                    },
+                ],
+            });
+        }
+        return blocks;
+    }
+    /**
+     * Format approval request blocks with buttons
+     */
+    formatApprovalBlocks(request, options) {
+        const blocks = [];
+        // Header
+        blocks.push({
+            type: 'header',
+            text: {
+                type: 'plain_text',
+                text: 'Approval Request',
+                emoji: true,
+            },
+        });
+        // Request text
+        blocks.push({
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: request,
+            },
+        });
+        // Context information
+        if (options.context && Object.keys(options.context).length > 0) {
+            blocks.push({
+                type: 'divider',
+            });
+            const contextFields = Object.entries(options.context).map(([k, v]) => ({
+                type: 'mrkdwn',
+                text: `*${k}:*\n${v}`,
+            }));
+            // Split into chunks of 10 (Slack's limit for fields)
+            for (let i = 0; i < contextFields.length; i += 10) {
+                blocks.push({
+                    type: 'section',
+                    fields: contextFields.slice(i, i + 10),
+                });
+            }
+        }
+        // Action buttons
+        blocks.push({
+            type: 'divider',
+        });
+        blocks.push({
+            type: 'actions',
+            block_id: `approval_actions_${options.requestId}`,
+            elements: [
+                {
+                    type: 'button',
+                    text: {
+                        type: 'plain_text',
+                        text: options.approveLabel || 'Approve',
+                        emoji: true,
+                    },
+                    style: 'primary',
+                    action_id: `approve_${options.requestId}`,
+                    value: JSON.stringify({ action: 'approve', requestId: options.requestId }),
+                    confirm: {
+                        title: { type: 'plain_text', text: 'Confirm Approval' },
+                        text: { type: 'mrkdwn', text: 'Are you sure you want to approve this request?' },
+                        confirm: { type: 'plain_text', text: 'Approve' },
+                        deny: { type: 'plain_text', text: 'Cancel' },
+                    },
+                },
+                {
+                    type: 'button',
+                    text: {
+                        type: 'plain_text',
+                        text: options.rejectLabel || 'Reject',
+                        emoji: true,
+                    },
+                    style: 'danger',
+                    action_id: `reject_${options.requestId}`,
+                    value: JSON.stringify({ action: 'reject', requestId: options.requestId }),
+                    confirm: {
+                        title: { type: 'plain_text', text: 'Confirm Rejection' },
+                        text: { type: 'mrkdwn', text: 'Are you sure you want to reject this request?' },
+                        confirm: { type: 'plain_text', text: 'Reject' },
+                        deny: { type: 'plain_text', text: 'Cancel' },
+                        style: 'danger',
+                    },
+                },
+            ],
+        });
+        return blocks;
+    }
+    /**
+     * Format question blocks with optional choice buttons
+     */
+    formatQuestionBlocks(question, options) {
+        const blocks = [];
+        // Question text
+        blocks.push({
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: question,
+            },
+        });
+        // Choice buttons if provided
+        if (options.choices && options.choices.length > 0) {
+            blocks.push({
+                type: 'actions',
+                block_id: `question_choices_${options.requestId}`,
+                elements: options.choices.slice(0, 5).map((choice, index) => ({
+                    type: 'button',
+                    text: {
+                        type: 'plain_text',
+                        text: choice,
+                        emoji: true,
+                    },
+                    action_id: `choice_${options.requestId}_${index}`,
+                    value: JSON.stringify({ choice, requestId: options.requestId }),
+                })),
+            });
+        }
+        return blocks;
+    }
+    /**
+     * Post a message to Slack
+     */
+    async postMessage(message) {
+        return this.callApi('chat.postMessage', message);
+    }
+    /**
+     * Call Slack API
+     */
+    async callApi(method, body) {
+        const response = await fetch(`${this.apiBaseUrl}/${method}`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.config.botToken}`,
+                'Content-Type': 'application/json; charset=utf-8',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Slack API error: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (!data.ok) {
+            throw new Error(`Slack API error: ${data.error}`);
+        }
+        return data;
+    }
+    /**
+     * Verify Slack request signature using Web Crypto API.
+     * Works in both Node.js and Cloudflare Workers environments.
+     */
+    async verifySignatureAsync(request) {
+        const signature = request.headers['x-slack-signature'];
+        const timestamp = request.headers['x-slack-request-timestamp'];
+        if (!signature || !timestamp) {
+            return false;
+        }
+        // Check timestamp to prevent replay attacks (5 minutes)
+        const now = Math.floor(Date.now() / 1000);
+        const requestTimestamp = parseInt(timestamp, 10);
+        if (Math.abs(now - requestTimestamp) > 300) {
+            return false;
+        }
+        // Get raw body for verification
+        const rawBody = request.rawBody ||
+            (typeof request.body === 'string' ? request.body : JSON.stringify(request.body));
+        // Use the exported async signature verification function
+        return verifySlackSignature(signature, timestamp, rawBody, this.config.signingSecret);
+    }
+    /**
+     * Parse webhook payload
+     */
+    parseWebhookPayload(request) {
+        try {
+            if (typeof request.body === 'string') {
+                // URL-encoded payload (application/x-www-form-urlencoded)
+                if (request.body.startsWith('payload=')) {
+                    const decoded = decodeURIComponent(request.body.slice(8));
+                    return JSON.parse(decoded);
+                }
+                // JSON payload
+                return JSON.parse(request.body);
+            }
+            return request.body;
+        }
+        catch (error) {
+            // Parse error - log for debugging
+            this.logger.error('parseWebhookPayload failed', error instanceof Error ? error : undefined, {
+                operation: 'parseWebhookPayload',
+                bodyType: typeof request.body,
+                bodyPreview: typeof request.body === 'string' ? request.body.slice(0, 100) : '[object]',
+            });
+            return null;
+        }
+    }
+    /**
+     * Parse action value (JSON or string)
+     */
+    parseActionValue(value) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            // Non-JSON value - this is expected for string values, log at debug level
+            this.logger.debug('parseActionValue: value is not JSON, returning as string', {
+                operation: 'parseActionValue',
+                valuePreview: value.slice(0, 50),
+            });
+            return value;
+        }
+    }
+    /**
+     * Generate unique request ID
+     */
+    generateRequestId() {
+        return generateRequestId('req');
+    }
+    // ===========================================================================
+    // Testing Utilities
+    // ===========================================================================
+    /**
+     * Expose parseWebhookPayload for testing
+     * @internal
+     */
+    parseWebhookPayloadForTesting(request) {
+        return this.parseWebhookPayload(request);
+    }
+    /**
+     * Expose parseActionValue for testing
+     * @internal
+     */
+    parseActionValueForTesting(value) {
+        return this.parseActionValue(value);
+    }
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a Slack transport instance
+ *
+ * @example
+ * ```ts
+ * const slack = createSlackTransport({
+ *   botToken: process.env.SLACK_BOT_TOKEN!,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ * })
+ *
+ * await slack.sendNotification('#engineering', 'Hello!')
+ * ```
+ */
+export function createSlackTransport(config) {
+    return new SlackTransport(config);
+}
+/**
+ * Create and register a Slack transport handler
+ *
+ * @example
+ * ```ts
+ * registerSlackTransport({
+ *   botToken: process.env.SLACK_BOT_TOKEN!,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET!,
+ * })
+ *
+ * // Now 'slack' transport is available via sendViaTransport
+ * await sendViaTransport('slack', payload)
+ * ```
+ */
+export function registerSlackTransport(config) {
+    const transport = createSlackTransport(config);
+    transport.register();
+    return transport;
+}
+// =============================================================================
+// Block Kit Helpers
+// =============================================================================
+/**
+ * Create a section block
+ */
+export function slackSection(text, options) {
+    const block = {
+        type: 'section',
+        text: {
+            type: 'mrkdwn',
+            text,
+        },
+    };
+    if (options?.fields) {
+        block.fields = options.fields.map((f) => ({
+            type: 'mrkdwn',
+            text: f,
+        }));
+    }
+    return block;
+}
+/**
+ * Create a header block
+ */
+export function slackHeader(text) {
+    return {
+        type: 'header',
+        text: {
+            type: 'plain_text',
+            text,
+            emoji: true,
+        },
+    };
+}
+/**
+ * Create a divider block
+ */
+export function slackDivider() {
+    return { type: 'divider' };
+}
+/**
+ * Create a context block
+ */
+export function slackContext(...texts) {
+    return {
+        type: 'context',
+        elements: texts.map((text) => ({
+            type: 'mrkdwn',
+            text,
+        })),
+    };
+}
+/**
+ * Create a button element
+ */
+export function slackButton(text, actionId, options) {
+    return {
+        type: 'button',
+        text: {
+            type: 'plain_text',
+            text,
+            emoji: true,
+        },
+        action_id: actionId,
+        ...(options?.value !== undefined && { value: options.value }),
+        ...(options?.style !== undefined && { style: options.style }),
+        ...(options?.url !== undefined && { url: options.url }),
+    };
+}
+/**
+ * Create an actions block with buttons
+ */
+export function slackActions(blockId, ...buttons) {
+    return {
+        type: 'actions',
+        block_id: blockId,
+        elements: buttons,
+    };
+}
+//# sourceMappingURL=slack.js.map