feat: Node Slack SDK major version release candidate

.changeset/drop-node18-cli-hooks.md

@@ -0,0 +1,5 @@
+---
+"@slack/cli-hooks": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-cli-test.md

@@ -0,0 +1,5 @@
+---
+"@slack/cli-test": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-logger.md

@@ -0,0 +1,5 @@
+---
+"@slack/logger": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-oauth.md

@@ -0,0 +1,5 @@
+---
+"@slack/oauth": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-socket-mode.md

@@ -0,0 +1,5 @@
+---
+"@slack/socket-mode": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-types.md

@@ -0,0 +1,5 @@
+---
+"@slack/types": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-web-api.md

@@ -0,0 +1,5 @@
+---
+"@slack/web-api": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/drop-node18-webhook.md

@@ -0,0 +1,5 @@
+---
+"@slack/webhook": major
+---
+
+Drop Node.js 18 support. The minimum supported Node.js version is now 20.

.changeset/oauth-web-api-v8-dependency.md

@@ -0,0 +1,24 @@
+---
+"@slack/oauth": major
+---
+
+Updated the internal `@slack/web-api` dependency from `^7` to `^8`. If you pass `clientOptions` to `InstallProvider`, the following options are no longer available:
+
+- **`clientOptions.agent`** — Use `clientOptions.fetch` with a custom fetch implementation instead.
+- **`clientOptions.tls`** — Configure TLS via `clientOptions.fetch` or the `NODE_EXTRA_CA_CERTS` environment variable.
+
+```js
+import { InstallProvider } from '@slack/oauth';
+import { fetch, Agent } from 'undici';
+
+const installer = new InstallProvider({
+  clientId: process.env.SLACK_CLIENT_ID,
+  clientSecret: process.env.SLACK_CLIENT_SECRET,
+  stateSecret: 'my-secret',
+  clientOptions: {
+    fetch: (url, init) => fetch(url, { ...init, dispatcher: new Agent({ connect: { ca: myCA } }) }),
+  },
+});
+```
+
+See the `@slack/web-api` v8 changelog for the full list of breaking changes that affect `clientOptions`.

.changeset/socket-mode-error-classes.md

@@ -0,0 +1,23 @@
+---
+"@slack/socket-mode": major
+---
+
+Redesigned error handling to use proper `Error` subclasses instead of plain objects with a `code` property.
+
+**Migration:** Replace `if (error.code === ErrorCode.WebsocketError)` with `if (error instanceof SMWebsocketError)`.
+
+**New error classes:**
+- `SMPlatformError` — Slack platform returned an error event
+- `SMWebsocketError` — WebSocket connection failure (original error in `cause`)
+- `SMNoReplyReceivedError` — Timed out waiting for a reply to an acknowledgement
+- `SMSendWhileDisconnectedError` — Attempted to send while not connected
+- `SMSendWhileNotReadyError` — Attempted to send before the connection was ready
+
+**Removed factory functions** (use `new` with the corresponding class instead):
+- `websocketErrorWithOriginal()` → `new SMWebsocketError(original)`
+- `platformErrorFromEvent()` → `new SMPlatformError(event)`
+- `noReplyReceivedError()` → `new SMNoReplyReceivedError()`
+- `sendWhileDisconnectedError()` → `new SMSendWhileDisconnectedError()`
+- `sendWhileNotReadyError()` → `new SMSendWhileNotReadyError()`
+
+The `CodedError` interface is deprecated — use `instanceof` checks with specific error classes instead. The `error.code` property still exists for backward-compatible checks, but `error.name` values changed from generic `'Error'` to descriptive class names (e.g., `'SMWebsocketError'`).

.changeset/socket-mode-undici-migration.md

@@ -0,0 +1,29 @@
+---
+"@slack/socket-mode": major
+---
+
+Replaced the `ws` WebSocket library with a spec-compliant WebSocket implementation backed by `undici`. **`undici@^7` is now a peer dependency** that must be installed alongside `@slack/socket-mode`:
+
+```bash
+npm install @slack/socket-mode undici@^7
+```
+
+**Removed options:**
+- **`clientOptions.agent`** (the `httpAgent` passed to the underlying web-api client). Use the new top-level `dispatcher` option instead. The dispatcher handles both the WebSocket connection and HTTP API calls (unless `clientOptions.fetch` is also provided, in which case `dispatcher` only applies to WebSocket).
+
+**New `dispatcher` option:**
+```js
+import { SocketModeClient } from '@slack/socket-mode';
+import { ProxyAgent } from 'undici';
+
+const client = new SocketModeClient({
+  appToken: process.env.SLACK_APP_TOKEN,
+  dispatcher: new ProxyAgent('http://proxy:3128'),
+});
+```
+
+For simple proxy use cases, prefer the Node.js built-in proxy support: call `http.setGlobalProxyFromEnv()` at startup or set `NODE_USE_ENV_PROXY=1` (Node.js 24+) with `HTTP_PROXY`/`HTTPS_PROXY` environment variables.
+
+The `dispatcher` option accepts any object implementing the `SocketModeDispatcher` interface (structurally compatible with undici's `Agent`, `ProxyAgent`, `Client`, etc.).
+
+This package now depends on `@slack/web-api@^8` — any `clientOptions` you pass are subject to web-api v8 breaking changes (e.g., the `agent` and `tls` options are no longer available; use `clientOptions.fetch` instead).

.changeset/web-api-error-classes.md

@@ -0,0 +1,28 @@
+---
+"@slack/web-api": major
+---
+
+Redesigned error handling to use proper `Error` subclasses instead of plain objects with a `code` property.
+
+**Migration:** Replace `if (error.code === ErrorCode.PlatformError)` with `if (error instanceof WebAPIPlatformError)`. All error classes extend a common `SlackError` base class (which extends `Error`), so you can also catch all SDK errors with `if (error instanceof SlackError)`.
+
+**New error class hierarchy:**
+- `SlackError` (abstract base)
+  - `WebAPIPlatformError` — Slack API returned `ok: false`
+  - `WebAPIRequestError` — Network/transport failure (original error in `cause`)
+  - `WebAPIHTTPError` — Non-200 HTTP status from Slack
+  - `WebAPIRateLimitedError` — HTTP 429 with `retryAfter` seconds
+  - `WebAPIFileUploadInvalidArgumentsError` — Invalid file upload arguments
+  - `WebAPIFileUploadReadFileDataError` — Failed to read file data for upload
+
+**Removed factory functions** (these were internal but exported — use `new` with the corresponding class instead):
+- `errorWithCode()`
+- `platformErrorFromResult()` → `new WebAPIPlatformError(...)`
+- `requestErrorWithOriginal()` → `new WebAPIRequestError(...)`
+- `httpErrorFromResponse()` → `new WebAPIHTTPError(...)`
+- `rateLimitedErrorWithDelay()` → `new WebAPIRateLimitedError(...)`
+
+**Other breaking type changes:**
+- `WebAPIHTTPError.headers` type changed from `IncomingHttpHeaders` to `Record<string, string>`.
+- The `CodedError` interface is deprecated — use `instanceof` checks with specific error classes instead.
+- Error `.name` values changed from generic `'Error'` to descriptive class names (e.g., `'WebAPIPlatformError'`).

.changeset/web-api-fetch-migration.md

@@ -0,0 +1,22 @@
+---
+"@slack/web-api": major
+---
+
+Replaced `axios` with the standard Fetch API for all HTTP transport. The following options and types have been removed from `WebClientOptions`:
+
+- **`agent`** — Use the new `fetch` option to provide a custom fetch implementation with proxy or keep-alive support. For proxies, prefer the built-in `http.setGlobalProxyFromEnv()` or `NODE_USE_ENV_PROXY=1` (Node.js 24+). For advanced use cases:
+  ```ts
+  import { fetch, Agent } from 'undici';
+  const client = new WebClient(token, {
+    fetch: (url, init) => fetch(url, { ...init, dispatcher: new Agent({ keepAliveTimeout: 60_000 }) }),
+  });
+  ```
+- **`tls`** and **`TLSOptions`** — Configure TLS via a custom `fetch` implementation with an undici `Agent`, or use the `NODE_EXTRA_CA_CERTS` environment variable.
+- **`requestInterceptor`** and **`RequestInterceptor`** type — Wrap the `fetch` function to intercept or modify requests before they are sent.
+- **`adapter`** and **`AdapterConfig`** type — Use the `fetch` option instead.
+- **`RequestConfig`** type (was an alias for Axios' `InternalAxiosRequestConfig`) — Removed entirely.
+- **`attachOriginalToWebAPIRequestError`** option — Removed. The original error is now always available via the standard `cause` property on `WebAPIRequestError`.
+
+The dependencies `axios`, `form-data`, `is-electron`, and `is-stream` have been removed. The default `fetch` implementation is `globalThis.fetch` (available in Node.js 20+).
+
+New exported types for custom fetch implementations: `FetchFunction`, `FetchResponse`, `FetchRequestInit`, `FetchHeaders`.

.changeset/web-api-remove-deprecated-methods.md

@@ -0,0 +1,9 @@
+---
+"@slack/web-api": major
+---
+
+Removed previously-deprecated API methods and their associated request/response types:
+
+- **`files.upload`** — Use `filesUploadV2` instead (available since v6.7). The `filesUploadV2` method handles the multi-step upload process automatically.
+- **`rtm.start`** — Use `rtm.connect` instead. The `rtm.start` method was deprecated by Slack in favor of the lighter-weight `rtm.connect`.
+- **`workflows.stepCompleted`**, **`workflows.stepFailed`**, **`workflows.updateStep`** — These methods supported the retired [Steps from Apps](https://api.slack.com/changelog/2023-08-workflow-steps-from-apps-step-back) feature (deprecated August 2023, retired September 2024). The `workflows.featured.*` and `admin.workflows.*` methods for the current Workflow Builder remain available.

.changeset/webhook-error-classes.md

@@ -0,0 +1,24 @@
+---
+"@slack/webhook": major
+---
+
+Restructured error classes to use proper `Error` subclasses extending a new `SlackWebhookError` base class.
+
+**Breaking changes to `IncomingWebhookHTTPError`:**
+- The `original` property has been removed. HTTP response details are now direct properties:
+  - `statusCode: number`
+  - `statusMessage: string`
+  - `body: string`
+- Migrate from `error.original.response.status` to `error.statusCode`, `error.original.response.data` to `error.body`, etc.
+
+**Breaking changes to `IncomingWebhookRequestError`:**
+- The `original` property is now a standard `Error` (previously it was an `AxiosError`). The original error is also available via the standard `cause` property.
+
+**Removed factory functions** (use `new` with the corresponding class instead):
+- `requestErrorWithOriginal()` → `new IncomingWebhookRequestError(original)`
+- `httpErrorWithOriginal()` → `new IncomingWebhookHTTPError(statusCode, statusMessage, body)`
+- `errorWithCode()` — Use the specific error class directly.
+
+**Migration:** Replace `if (error.code === ErrorCode.HTTPError)` with `if (error instanceof IncomingWebhookHTTPError)`. You can also catch all webhook errors with `if (error instanceof SlackWebhookError)`.
+
+The `CodedError` interface is deprecated — use `instanceof` checks with the `SlackWebhookError` base class or specific error subclasses instead.

.changeset/webhook-fetch-migration.md

@@ -0,0 +1,16 @@
+---
+"@slack/webhook": major
+---
+
+Replaced `axios` with the standard Fetch API for HTTP transport.
+
+**Removed options from `IncomingWebhookDefaultArguments`:**
+- **`agent`** — Use the new `fetch` option to provide a custom fetch implementation with proxy or TLS support. For proxies, prefer the built-in `http.setGlobalProxyFromEnv()` or `NODE_USE_ENV_PROXY=1` (Node.js 24+). For advanced use cases:
+  ```ts
+  import { fetch, Agent } from 'undici';
+  const webhook = new IncomingWebhook(url, {
+    fetch: (url, init) => fetch(url, { ...init, dispatcher: new Agent({ connect: { ca: myCA } }) }),
+  });
+  ```
+
+The `axios` dependency has been removed. The default fetch implementation is `globalThis.fetch` (available in Node.js 20+). The `timeout` option remains available and is implemented via `AbortController`.

.github/workflows/ci-build.yml

@@ -19,7 +19,6 @@ jobs:
           - "ubuntu-latest"
           - "windows-latest"
         node-version:
-          - "18.x"
           - "20.x"
           - "22.x"
           - "24.x"