feat(webhook): add WebhookTrigger class for Workflow Builder triggers

.changeset/webhook-trigger-class.md

@@ -0,0 +1,5 @@
+---
+"@slack/webhook": minor
+---
+
+feat: add `WebhookTrigger` class for Workflow Builder webhook triggers

packages/webhook/README.md

@@ -1,11 +1,11 @@
-# Slack Incoming Webhooks
+# Slack Webhook
 
 [![codecov](https://codecov.io/gh/slackapi/node-slack-sdk/graph/badge.svg?token=OcQREPvC7r&flag=webhook)](https://codecov.io/gh/slackapi/node-slack-sdk)
 
-The `@slack/webhook` package contains a helper for making requests to Slack's [Incoming
-Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). Use it in your app to send a notification to a channel.
+The `@slack/webhook` package contains a helper for making requests to Slack's [Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) or [Workflow Builder](https://slack.com/features/workflow-automation). Use it in your app to send a notification to a channel or start a workflow.
 
 ## Requirements
+
 This package supports Node v18 and higher. It's highly recommended to use [the latest LTS version of
 node](https://github.com/nodejs/Release#release-schedule), and the documentation is written using syntax and features
 from that version.
@@ -82,6 +82,27 @@ const webhook = new IncomingWebhook(url);
 
 ---
 
+### Trigger a Workflow Builder workflow
+
+The package also exports a `WebhookTrigger` class for [Workflow Builder webhook triggers](https://slack.com/help/articles/360041352714-Build-a-workflow--Create-a-workflow-that-starts-outside-of-Slack) which accepts an optional, flattened, stringified JSON payload sent to start a workflow.
+
+```javascript
+const { WebhookTrigger } = require('@slack/webhook');
+const url = process.env.SLACK_WEBHOOK_TRIGGER_URL;
+
+const trigger = new WebhookTrigger(url);
+
+(async () => {
+  // Keys should match the variables your workflow expects
+  await trigger.send({
+    customer_name: 'Ada Lovelace',
+    order_id: '1024',
+  });
+})();
+```
+
+---
+
 ### Proxy requests with a custom agent
 
 The webhook allows you to customize the HTTP

packages/webhook/package.json

@@ -37,8 +37,8 @@
     "build:clean": "shx rm -rf ./dist",
     "docs": "npx typedoc --plugin typedoc-plugin-markdown",
     "prepack": "npm run build",
-    "test": "npm run build && node --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-results.xml --import tsx --test src/IncomingWebhook.test.ts src/instrument.test.ts",
-    "test:coverage": "npm run build && node --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info --test-reporter=junit --test-reporter-destination=test-results.xml --import tsx --test src/IncomingWebhook.test.ts src/instrument.test.ts"
+    "test": "npm run build && node --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-results.xml --import tsx --test src/IncomingWebhook.test.ts src/WebhookTrigger.test.ts src/instrument.test.ts",
+    "test:coverage": "npm run build && node --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info --test-reporter=junit --test-reporter-destination=test-results.xml --import tsx --test src/IncomingWebhook.test.ts src/WebhookTrigger.test.ts src/instrument.test.ts"
   },
   "dependencies": {
     "@slack/types": "^2.20.1",

packages/webhook/src/WebhookTrigger.test.ts

@@ -0,0 +1,158 @@
+import assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import nock from 'nock';
+
+import type { CodedError, WebhookTriggerHTTPError } from './errors';
+import { ErrorCode } from './errors';
+import { addAppMetadata } from './instrument';
+import { WebhookTrigger } from './WebhookTrigger';
+
+const url = 'https://hooks.slack.com/triggers/FAKETRIGGER';
+
+describe('WebhookTrigger', () => {
+  afterEach(() => {
+    nock.cleanAll();
+  });
+
+  describe('constructor()', () => {
+    it('should build a default webhook trigger given a URL', () => {
+      const trigger = new WebhookTrigger(url);
+      assert.ok(trigger instanceof WebhookTrigger);
+    });
+
+    it('should create a default webhook trigger with a default timeout', () => {
+      const trigger = new WebhookTrigger(url);
+      // biome-ignore lint/suspicious/noExplicitAny: accessing private property for test assertion
+      assert.strictEqual((trigger as any).defaults.timeout, 0);
+    });
+
+    it('should create an axios instance that has the timeout passed by the user', () => {
+      const givenTimeout = 100;
+      const trigger = new WebhookTrigger(url, { timeout: givenTimeout });
+      // biome-ignore lint/suspicious/noExplicitAny: accessing private property for test assertion
+      assert.strictEqual((trigger as any).axios.defaults.timeout, givenTimeout);
+    });
+
+    it('should throw when the URL is missing or empty', () => {
+      // biome-ignore lint/suspicious/noExplicitAny: exercising the runtime guard with invalid input
+      assert.throws(() => new WebhookTrigger(undefined as any), /URL is required/);
+      assert.throws(() => new WebhookTrigger(''), /URL is required/);
+    });
+  });
+
+  describe('send()', () => {
+    let trigger: WebhookTrigger;
+    beforeEach(() => {
+      trigger = new WebhookTrigger(url);
+    });
+
+    describe('on success', () => {
+      it('should return results in a Promise', async () => {
+        const scope = nock('https://hooks.slack.com')
+          .post(/triggers/, (body) => {
+            assert.deepStrictEqual(body, { key: 'value' });
+            return true;
+          })
+          .reply(200, { ok: true });
+        const result = await trigger.send({ key: 'value' });
+        assert.deepStrictEqual(result, { ok: true });
+        scope.done();
+      });
+
+      it('should send an empty body and resolve when called without a payload', async () => {
+        const scope = nock('https://hooks.slack.com')
+          .post(/triggers/, (body) => {
+            assert.deepStrictEqual(body, {});
+            return true;
+          })
+          .reply(200, { ok: true });
+        const result = await trigger.send();
+        assert.strictEqual(result.ok, true);
+        scope.done();
+      });
+    });
+
+    describe('on failure', () => {
+      it('should reject on an HTTP error status', async () => {
+        const statusCode = 500;
+        const scope = nock('https://hooks.slack.com')
+          .post(/triggers/)
+          .reply(statusCode);
+        try {
+          await trigger.send({ key: 'value' });
+          assert.fail('expected rejection');
+        } catch (error) {
+          assert.ok(error instanceof Error);
+          assert.match((error as Error).message, new RegExp(String(statusCode)));
+        }
+        scope.done();
+      });
+
+      it('should fail with RequestError when the API request fails', async () => {
+        const trigger = new WebhookTrigger('https://localhost:8999/api/');
+        try {
+          await trigger.send({ key: 'value' });
+          assert.fail('expected rejection');
+        } catch (error) {
+          assert.ok(error instanceof Error);
+          assert.strictEqual((error as CodedError).code, ErrorCode.RequestError);
+        }
+      });
+
+      it('should reject with an HTTPError carrying the response body on a 401', async () => {
+        const scope = nock('https://hooks.slack.com')
+          .post(/triggers/)
+          .reply(401, { ok: false, error: 'invalid_auth' });
+        try {
+          await trigger.send({ key: 'value' });
+          assert.fail('expected rejection');
+        } catch (error) {
+          const httpError = error as WebhookTriggerHTTPError;
+          assert.strictEqual(httpError.code, ErrorCode.HTTPError);
+          // biome-ignore lint/suspicious/noExplicitAny: reading the wrapped axios response body
+          const response = (httpError.original as any).response;
+          assert.strictEqual(response.status, 401);
+          assert.deepStrictEqual(response.data, { ok: false, error: 'invalid_auth' });
+        }
+        scope.done();
+      });
+    });
+
+    describe('User-Agent header', () => {
+      it('should send the User-Agent header with every request', async () => {
+        const scope = nock('https://hooks.slack.com', {
+          reqheaders: {
+            'User-Agent': (value) => {
+              return /@slack:webhook/.test(value);
+            },
+          },
+        })
+          .post(/triggers/)
+          .reply(200, { ok: true });
+        try {
+          const trigger = new WebhookTrigger(url);
+          await trigger.send({ key: 'value' });
+        } finally {
+          scope.done();
+        }
+      });
+
+      it('should send app metadata added via addAppMetadata in the User-Agent header', async () => {
+        const scope = nock('https://hooks.slack.com', {
+          reqheaders: {
+            'User-Agent': (value) => value.includes('my-tool/1.2.3') && /@slack:webhook/.test(value),
+          },
+        })
+          .post(/triggers/)
+          .reply(200, { ok: true });
+        try {
+          addAppMetadata({ name: 'my-tool', version: '1.2.3' });
+          const trigger = new WebhookTrigger(url);
+          await trigger.send({ key: 'value' });
+        } finally {
+          scope.done();
+        }
+      });
+    });
+  });
+});

packages/webhook/src/WebhookTrigger.ts

@@ -0,0 +1,94 @@
+import type { Agent } from 'node:http';
+
+import axios, { type AxiosInstance } from 'axios';
+
+import { httpErrorWithOriginal, requestErrorWithOriginal } from './errors';
+import { getUserAgent } from './instrument';
+
+/**
+ * A client for Slack's Workflow Builder webhook triggers
+ * @see {@link https://slack.com/help/articles/360041352714-Build-a-workflow--Create-a-workflow-that-starts-outside-of-Slack}
+ */
+export class WebhookTrigger {
+  /**
+   * The webhook trigger URL
+   */
+  private url: string;
+
+  /**
+   * Default arguments for sending to this webhook trigger
+   */
+  private defaults: WebhookTriggerDefaultArguments;
+
+  /**
+   * Axios HTTP client instance used by this client
+   */
+  private axios: AxiosInstance;
+
+  public constructor(
+    url: string,
+    defaults: WebhookTriggerDefaultArguments = {
+      timeout: 0,
+    },
+  ) {
+    if (!url) {
+      throw new Error('Webhook trigger URL is required');
+    }
+
+    this.url = url;
+    this.defaults = defaults;
+
+    this.axios = axios.create({
+      baseURL: url,
+      httpAgent: defaults.agent,
+      httpsAgent: defaults.agent,
+      maxRedirects: 0,
+      proxy: false,
+      timeout: defaults.timeout,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': getUserAgent(),
+      },
+    });
+
+    this.defaults.agent = undefined;
+  }
+
+  /**
+   * Send a payload to the webhook trigger
+   * @param payload - arbitrary key-value data to send to the trigger
+   */
+  public async send(payload: WebhookTriggerSendArguments = {}): Promise<WebhookTriggerResult> {
+    try {
+      const response = await this.axios.post(this.url, payload);
+      return response.data;
+      // biome-ignore lint/suspicious/noExplicitAny: errors can be anything
+    } catch (error: any) {
+      if (error.response !== undefined) {
+        throw httpErrorWithOriginal(error);
+      }
+      if (error.request !== undefined) {
+        throw requestErrorWithOriginal(error);
+      }
+      throw error;
+    }
+  }
+}
+
+/*
+ * Exported types
+ */
+
+export interface WebhookTriggerDefaultArguments {
+  agent?: Agent;
+  timeout?: number;
+}
+
+export interface WebhookTriggerSendArguments {
+  [key: string]: string;
+}
+
+export interface WebhookTriggerResult {
+  ok: boolean;
+  error?: string;
+}

packages/webhook/src/errors.ts

@@ -16,16 +16,19 @@ export enum ErrorCode {
 }
 
 export type IncomingWebhookSendError = IncomingWebhookRequestError | IncomingWebhookHTTPError;
+export type WebhookTriggerSendError = WebhookTriggerRequestError | WebhookTriggerHTTPError;
 
 export interface IncomingWebhookRequestError extends CodedError {
   code: ErrorCode.RequestError;
   original: Error;
 }
+export type WebhookTriggerRequestError = IncomingWebhookRequestError;
 
 export interface IncomingWebhookHTTPError extends CodedError {
   code: ErrorCode.HTTPError;
   original: Error;
 }
+export type WebhookTriggerHTTPError = IncomingWebhookHTTPError;
 
 /**
  * Factory for producing a {@link CodedError} from a generic error

packages/webhook/src/index.ts

@@ -6,6 +6,9 @@ export {
   IncomingWebhookHTTPError,
   IncomingWebhookRequestError,
   IncomingWebhookSendError,
+  WebhookTriggerHTTPError,
+  WebhookTriggerRequestError,
+  WebhookTriggerSendError,
 } from './errors';
 
 export {
@@ -16,3 +19,10 @@ export {
 } from './IncomingWebhook';
 
 export { addAppMetadata } from './instrument';
+
+export {
+  WebhookTrigger,
+  WebhookTriggerDefaultArguments,
+  WebhookTriggerResult,
+  WebhookTriggerSendArguments,
+} from './WebhookTrigger';