@vercel/slack-bolt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @vercel/slack-bolt
+
+A custom [Slack Bolt](https://slack.dev/bolt-js/) receiver built for Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute).
+
+- **Vercel Fluid Compute** Fully compabatible with Vercel Fluid Compute and [Active CPU Pricing](https://vercel.com/changelog/lower-pricing-with-active-cpu-pricing-for-fluid-compute)
+- **Easy integration:** Use with your existing Bolt app code
+- **Customizable:** Supports custom response handlers and property extraction
+- **TypeScript ready:** Fully typed for modern development
+
+## Installation
+
+```bash
+pnpm add @vercel/slack-bolt
+```
+
+## Quick Start
+
+### 1. Environment Setup
+
+Add your `SLACK_SIGNING_SECRET` and `SLACK_BOT_TOKEN` to your environment variables:
+
+```bash
+SLACK_SIGNING_SECRET=your_slack_signing_secret_here
+SLACK_BOT_TOKEN=your_slack_bot_token
+```
+
+### 2. Add the Vercel Receiver to your Bolt app
+
+```typescript
+// app.ts
+
+import { App } from "@slack/bolt";
+import { VercelReceiver } from "@vercel/slack-bolt";
+
+const receiver = new VercelReceiver();
+
+const app = new App({
+  token: process.env.SLACK_BOT_TOKEN,
+  signingSecret: process.env.SLACK_SIGNING_SECRET,
+  receiver,
+  deferInitialization: true,
+});
+
+app.message(/^(hi|hello|hey).*/, async ({ say }) => {
+  await say("Hello, world!");
+});
+
+export { app, receiver };
+```
+
+### 3. Create an API folder and events.ts route
+
+Your project structure should look like this:
+
+```
+root/
+├── api/
+│   └── events.ts        # Vercel API endpoint to handle requests
+├── app.ts               # Bolt app
+├── package.json
+└── .env                 # Environment variables
+```
+
+### 4. Create a POST request handler using `createHandler` from `@vercel/slack-bolt`
+
+```typescript
+// api/events.ts
+
+import { createHandler } from "@vercel/slack-bolt";
+import { app, receiver } from "../app";
+
+const handler = createHandler(app, receiver);
+
+export const POST = async (req: Request) => {
+  return handler(req);
+};
+```
+
+> **Note:**  
+> The `handler` returned by `createHandler` works with standard `WebRequest` objects.  
+> You can use it directly in your Vercel API routes or with any framework that provides compatible request objects.
+
+### 5. Update your Slack App Manifest
+
+- Disable socket mode on your app
+- Update your `request_url` to match your Vercel deployment
+- If using features such as `commands`, `shortcuts`, and `interactivity` you must update their `urls` as well.
+
+See the [example](./manifest.example.json) for reference.
+
+## Local Development
+
+This package is compatible with the Slack CLI and can be used with the `slack run` command.
+
+### 1. Update the `start` command in your `./slack/hooks.json` file
+
+```json
+// ./slack/hooks.json
+{
+  "hooks": {
+    "get-hooks": "npx -q --no-install -p @slack/cli-hooks slack-cli-get-hooks",
+    "start": "vc dev"
+  }
+}
+```
+
+### 2. If you'd like to use your local `manifest.json`, update your `config.json` file. (optional)
+
+```json
+{
+  // ./slack/config.json
+  "manifest": {
+    "source": "local" // remote pulls the manifest from your Slack's remote manifest
+  },
+  "project_id": "<your-project-id>"
+}
+```
+
+### 3. Expose your local server with `ngrok` or a similar tunneling tool
+
+```bash
+ngrok http 3000
+```
+
+### 4. Update your app manifest to use your tunnel URL
+
+Example: https://slack-agent.ngrok.dev/api/events
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions:
+
+- Check the [Slack Bolt documentation](https://slack.dev/bolt-js/)
+- Review [Vercel Functions documentation](https://vercel.com/docs/functions)
+- Open an issue in this repository

package/dist/index.d.mts

@@ -0,0 +1,156 @@
+import { StringIndexed, ReceiverEvent, Receiver, App } from '@slack/bolt';
+import { Logger, LogLevel } from '@slack/logger';
+
+/**
+ * A function to handle the request from the Slack app.
+ * @param req - The request from the Slack app.
+ * @returns A response object.
+ */
+type VercelHandler = (req: Request) => Promise<Response>;
+/**
+ * Configuration options for the VercelReceiver.
+ * @property signingSecret - The signing secret for the Slack app.
+ * @property signatureVerification - If true, verifies the Slack request signature.
+ * @property logger - The logger to use for the VercelReceiver.
+ * @property logLevel - The log level to use for the VercelReceiver.
+ * @property customPropertiesExtractor - A function to extract custom properties from the request.
+ * @property customResponseHandler - A function to handle the response from the Slack app.
+ */
+interface VercelReceiverOptions {
+    /**
+     * The signing secret for the Slack app.
+     * @default process.env.SLACK_SIGNING_SECRET
+     */
+    signingSecret?: string;
+    /**
+     * If true, verifies the Slack request signature.
+     * @default true
+     */
+    signatureVerification?: boolean;
+    /**
+     * The logger to use for the VercelReceiver.
+     * @default new ConsoleLogger()
+     */
+    logger?: Logger;
+    /**
+     * The log level to use for the VercelReceiver.
+     * @default LogLevel.INFO
+     */
+    logLevel?: LogLevel;
+    /**
+     * A function to extract custom properties from incoming events.
+     * @default undefined
+     * @returns An object with custom properties.
+     */
+    customPropertiesExtractor?: (req: Request) => StringIndexed;
+    /**
+     * A function to handle the response from the Slack app.
+     * @default undefined
+     * @returns A response object.
+     */
+    customResponseHandler?: (event: ReceiverEvent) => Promise<Response>;
+}
+/**
+ * A Slack Bolt receiver implementation designed for Vercel's serverless environment.
+ * Handles Slack events, interactions, and slash commands with automatic request verification,
+ * background processing, and timeout management.
+ *
+ * @example
+ * ```typescript
+ * import { App } from '@slack/bolt';
+ * import { VercelReceiver, createHandler } from '@vercel/slack-bolt';
+ *
+ * const receiver = new VercelReceiver();
+ *
+ * const app = new App({
+ *   receiver,
+ *   token: process.env.SLACK_BOT_TOKEN,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET,
+ * });
+ * ```
+ *
+ */
+declare class VercelReceiver implements Receiver {
+    private readonly signingSecret;
+    private readonly signatureVerification;
+    private readonly logger;
+    private readonly customPropertiesExtractor?;
+    private readonly customResponseHandler?;
+    private app?;
+    /**
+     * Gets the logger instance used by this receiver.
+     * @returns The logger instance
+     */
+    getLogger(): Logger;
+    /**
+     * Creates a new VercelReceiver instance.
+     *
+     * @param options - Configuration options for the receiver
+     * @throws {VercelReceiverError} When signing secret is not provided
+     *
+     * @example
+     * ```typescript
+     * const receiver = new VercelReceiver();
+     * ```
+     */
+    constructor({ signingSecret, signatureVerification, logger, logLevel, customPropertiesExtractor, customResponseHandler, }?: VercelReceiverOptions);
+    /**
+     * Initializes the receiver with a Slack Bolt app instance.
+     * This method is called automatically by the Bolt framework.
+     *
+     * @param app - The Slack Bolt app instance
+     */
+    init(app: App): void;
+    /**
+     * Starts the receiver and returns a handler function for processing requests.
+     * This method is called automatically by the Bolt framework.
+     *
+     * @returns A handler function that processes incoming Slack requests
+     */
+    start(): Promise<VercelHandler>;
+    /**
+     * Stops the receiver. This method is called automatically by the Bolt framework.
+     */
+    stop(): Promise<void>;
+    /**
+     * Creates a handler function that processes incoming Slack requests.
+     * This is the main entry point for handling Slack events in Vercel.
+     * It is called automatically by the Bolt framework in the start() method.
+     *
+     * @returns A handler function compatible with Vercel's function signature
+     */
+    toHandler(): VercelHandler;
+    private parseRequestBody;
+    private handleSlackEvent;
+    private verifySlackRequest;
+    private createSlackReceiverEvent;
+    private handleError;
+    private createScopedLogger;
+}
+/**
+ * Creates a Vercel-compatible handler function for a Slack Bolt app.
+ * This is the recommended way to create handlers for deployment on Vercel.
+ *
+ * @param {App} app - The initialized Slack Bolt app instance.
+ * @param {VercelReceiver} receiver - The VercelReceiver instance.
+ * @returns {VercelHandler} A handler function compatible with Vercel's function signature.
+ *
+ * @example
+ * ```typescript
+ * // api/events.ts
+ * import { createHandler } from '@vercel/slack-bolt';
+ * import { app, receiver } from '../app';
+ *
+ * const handler = createHandler(app, receiver);
+ *
+ * export const POST = async (req: Request) => {
+ *   return handler(req);
+ * };
+ * ```
+ *
+ * @throws {Error} If app initialization fails.
+ * @throws {VercelReceiverError} If request processing fails.
+ */
+declare function createHandler(app: App, receiver: VercelReceiver): VercelHandler;
+
+export { type VercelHandler, VercelReceiver, type VercelReceiverOptions, createHandler };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { StringIndexed, ReceiverEvent, Receiver, App } from '@slack/bolt';
+import { Logger, LogLevel } from '@slack/logger';
+
+/**
+ * A function to handle the request from the Slack app.
+ * @param req - The request from the Slack app.
+ * @returns A response object.
+ */
+type VercelHandler = (req: Request) => Promise<Response>;
+/**
+ * Configuration options for the VercelReceiver.
+ * @property signingSecret - The signing secret for the Slack app.
+ * @property signatureVerification - If true, verifies the Slack request signature.
+ * @property logger - The logger to use for the VercelReceiver.
+ * @property logLevel - The log level to use for the VercelReceiver.
+ * @property customPropertiesExtractor - A function to extract custom properties from the request.
+ * @property customResponseHandler - A function to handle the response from the Slack app.
+ */
+interface VercelReceiverOptions {
+    /**
+     * The signing secret for the Slack app.
+     * @default process.env.SLACK_SIGNING_SECRET
+     */
+    signingSecret?: string;
+    /**
+     * If true, verifies the Slack request signature.
+     * @default true
+     */
+    signatureVerification?: boolean;
+    /**
+     * The logger to use for the VercelReceiver.
+     * @default new ConsoleLogger()
+     */
+    logger?: Logger;
+    /**
+     * The log level to use for the VercelReceiver.
+     * @default LogLevel.INFO
+     */
+    logLevel?: LogLevel;
+    /**
+     * A function to extract custom properties from incoming events.
+     * @default undefined
+     * @returns An object with custom properties.
+     */
+    customPropertiesExtractor?: (req: Request) => StringIndexed;
+    /**
+     * A function to handle the response from the Slack app.
+     * @default undefined
+     * @returns A response object.
+     */
+    customResponseHandler?: (event: ReceiverEvent) => Promise<Response>;
+}
+/**
+ * A Slack Bolt receiver implementation designed for Vercel's serverless environment.
+ * Handles Slack events, interactions, and slash commands with automatic request verification,
+ * background processing, and timeout management.
+ *
+ * @example
+ * ```typescript
+ * import { App } from '@slack/bolt';
+ * import { VercelReceiver, createHandler } from '@vercel/slack-bolt';
+ *
+ * const receiver = new VercelReceiver();
+ *
+ * const app = new App({
+ *   receiver,
+ *   token: process.env.SLACK_BOT_TOKEN,
+ *   signingSecret: process.env.SLACK_SIGNING_SECRET,
+ * });
+ * ```
+ *
+ */
+declare class VercelReceiver implements Receiver {
+    private readonly signingSecret;
+    private readonly signatureVerification;
+    private readonly logger;
+    private readonly customPropertiesExtractor?;
+    private readonly customResponseHandler?;
+    private app?;
+    /**
+     * Gets the logger instance used by this receiver.
+     * @returns The logger instance
+     */
+    getLogger(): Logger;
+    /**
+     * Creates a new VercelReceiver instance.
+     *
+     * @param options - Configuration options for the receiver
+     * @throws {VercelReceiverError} When signing secret is not provided
+     *
+     * @example
+     * ```typescript
+     * const receiver = new VercelReceiver();
+     * ```
+     */
+    constructor({ signingSecret, signatureVerification, logger, logLevel, customPropertiesExtractor, customResponseHandler, }?: VercelReceiverOptions);
+    /**
+     * Initializes the receiver with a Slack Bolt app instance.
+     * This method is called automatically by the Bolt framework.
+     *
+     * @param app - The Slack Bolt app instance
+     */
+    init(app: App): void;
+    /**
+     * Starts the receiver and returns a handler function for processing requests.
+     * This method is called automatically by the Bolt framework.
+     *
+     * @returns A handler function that processes incoming Slack requests
+     */
+    start(): Promise<VercelHandler>;
+    /**
+     * Stops the receiver. This method is called automatically by the Bolt framework.
+     */
+    stop(): Promise<void>;
+    /**
+     * Creates a handler function that processes incoming Slack requests.
+     * This is the main entry point for handling Slack events in Vercel.
+     * It is called automatically by the Bolt framework in the start() method.
+     *
+     * @returns A handler function compatible with Vercel's function signature
+     */
+    toHandler(): VercelHandler;
+    private parseRequestBody;
+    private handleSlackEvent;
+    private verifySlackRequest;
+    private createSlackReceiverEvent;
+    private handleError;
+    private createScopedLogger;
+}
+/**
+ * Creates a Vercel-compatible handler function for a Slack Bolt app.
+ * This is the recommended way to create handlers for deployment on Vercel.
+ *
+ * @param {App} app - The initialized Slack Bolt app instance.
+ * @param {VercelReceiver} receiver - The VercelReceiver instance.
+ * @returns {VercelHandler} A handler function compatible with Vercel's function signature.
+ *
+ * @example
+ * ```typescript
+ * // api/events.ts
+ * import { createHandler } from '@vercel/slack-bolt';
+ * import { app, receiver } from '../app';
+ *
+ * const handler = createHandler(app, receiver);
+ *
+ * export const POST = async (req: Request) => {
+ *   return handler(req);
+ * };
+ * ```
+ *
+ * @throws {Error} If app initialization fails.
+ * @throws {VercelReceiverError} If request processing fails.
+ */
+declare function createHandler(app: App, receiver: VercelReceiver): VercelHandler;
+
+export { type VercelHandler, VercelReceiver, type VercelReceiverOptions, createHandler };