feat(web-api): add support for AbortSignal

.changeset/web-api-abort-signal.md

@@ -0,0 +1,5 @@
+---
+"@slack/web-api": minor
+---
+
+Add support for [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).

packages/web-api/src/WebClient.test.ts

@@ -2048,6 +2048,62 @@ describe('WebClient', () => {
       }
     });
   });
+
+  describe('accepts an AbortSignal to cancel requests', () => {
+    let scope: nock.Scope;
+    beforeEach(() => {
+      scope = nock('https://slack.com').post(/api/).delay(50).reply(200, { ok: true });
+    });
+
+    it('cancels the request when the signal is aborted', async () => {
+      const client = new WebClient(token);
+      const controller = new AbortController();
+      const { signal } = controller;
+
+      setTimeout(() => {
+        controller.abort();
+      }, 1);
+
+      try {
+        await client.conversations.list({}, { signal });
+        assert.fail('Expected error to be thrown');
+      } catch (error) {
+        scope.done();
+      }
+    });
+
+    it('completes the request when the signal is not aborted', async () => {
+      const client = new WebClient(token);
+      const controller = new AbortController();
+      const { signal } = controller;
+
+      try {
+        const response = await client.conversations.list({}, { signal });
+        assert.equal(response.ok, true);
+        scope.done();
+      } catch (error) {
+        assert.fail(`Did not expect an error to be thrown: ${(error as Error).message}`);
+      }
+    });
+
+    it('uses the AbortSignal reason', async () => {
+      const client = new WebClient(token);
+      const controller = new AbortController();
+      const { signal } = controller;
+      const abortReason = new Error('Abort reason');
+      setTimeout(() => {
+        controller.abort(abortReason);
+      }, 1);
+
+      try {
+        await client.conversations.list({}, { signal });
+        assert.fail('Expected error to be thrown');
+      } catch (error) {
+        assert.equal(error, abortReason);
+        scope.done();
+      }
+    });
+  });
 });
 
 // Helpers

packages/web-api/src/WebClient.ts

@@ -343,7 +343,11 @@ export class WebClient extends Methods {
    * @param method - the Web API method to call {@link https://docs.slack.dev/reference/methods}
    * @param options - options
    */
-  public async apiCall(method: string, options: Record<string, unknown> = {}): Promise<WebAPICallResult> {
+  public async apiCall(
+    method: string,
+    options: Record<string, unknown> = {},
+    config?: { signal?: AbortSignal },
+  ): Promise<WebAPICallResult> {
     this.logger.debug(`apiCall('${method}') start`);
 
     warnDeprecations(method, this.logger);
@@ -369,6 +373,7 @@ export class WebClient extends Methods {
         ...options,
       },
       headers,
+      config,
     );
     const result = await this.buildResult(response);
     this.logger.debug(`http request result: ${JSON.stringify(result)}`);
@@ -678,6 +683,7 @@ export class WebClient extends Methods {
     url: string,
     body: Record<string, unknown>,
     headers: Record<string, string> = {},
+    options?: { signal?: AbortSignal },
   ): Promise<AxiosResponse> {
     // TODO: better input types - remove any
     const task = () =>
@@ -686,6 +692,7 @@ export class WebClient extends Methods {
           // biome-ignore lint/suspicious/noExplicitAny: TODO: type this
           const config: any = {
             headers,
+            signal: options?.signal,
             ...this.tlsConfig,
           };
           // admin.analytics.getFile returns a binary response
@@ -763,6 +770,9 @@ export class WebClient extends Methods {
           // biome-ignore lint/suspicious/noExplicitAny: errors can be anything
           const e = error as any;
           this.logger.warn('http request failed', e.message);
+          if (e.name === 'CanceledError' && options?.signal?.reason) {
+            throw new AbortError(options.signal.reason);
+          }
           if (e.request) {
             throw requestErrorWithOriginal(e, this.attachOriginalToWebAPIRequestError);
           }

packages/web-api/src/methods.ts

@@ -557,9 +557,11 @@ import { type WebAPICallResult, WebClient, type WebClientEvent } from './WebClie
  */
 type MethodWithRequiredArgument<MethodArguments, MethodResult extends WebAPICallResult = WebAPICallResult> = (
   options: MethodArguments,
+  config?: { signal?: AbortSignal },
 ) => Promise<MethodResult>;
 type MethodWithOptionalArgument<MethodArguments, MethodResult extends WebAPICallResult = WebAPICallResult> = (
   options?: MethodArguments,
+  config?: { signal?: AbortSignal },
 ) => Promise<MethodResult>;
 
 export default MethodWithOptionalArgument;
@@ -606,7 +608,11 @@ export abstract class Methods extends EventEmitter<WebClientEvent> {
     }
   }
 
-  public abstract apiCall(method: string, options?: Record<string, unknown>): Promise<WebAPICallResult>;
+  public abstract apiCall(
+    method: string,
+    options?: Record<string, unknown>,
+    config?: { signal?: AbortSignal },
+  ): Promise<WebAPICallResult>;
   public abstract filesUploadV2(options: FilesUploadV2Arguments): Promise<WebAPICallResult>;
 
   public readonly admin = {