docs: update package READMEs for v8 (#2660)

Co-authored-by: Claude <svc-devxp-claude@slack-corp.com>

Author: WilliamBergamin

AGENTS.md

@@ -107,6 +107,10 @@ Individual packages have their own `AGENTS.md` with package-specific guidance:
 
 Block Kit types are defined in the `@slack/types` package. See `packages/types/AGENTS.md` for detailed steps covering interface definition, discriminated union registration, barrel exports, and type tests.
 
+## Pull Requests
+
+When opening a pull request, use the repository's PR template at `.github/pull_request_template.md` as the PR body — the `gh` CLI does not populate it automatically, so pass the filled-in template explicitly (e.g. via `gh pr create --body-file`). Fill in every section.
+
 ## Common Pitfalls
 
 - **Build in dependency order** — see the dependency graph above.

README.md

@@ -21,7 +21,7 @@ walk you through building your first Slack app using Node.js.
 
 | Slack API    | Use | NPM Package      |
 |--------------|--------------|-------------------|
-| Web API      | Send data to or query data from Slack using any of [over 220 methods](https://docs.slack.dev/reference/methods). | [`@slack/web-api`](https://docs.slack.dev/tools/node-slack-sdk/web-api) |
+| Web API      | Send data to or query data from Slack using any of [over 270 methods](https://docs.slack.dev/reference/methods). | [`@slack/web-api`](https://docs.slack.dev/tools/node-slack-sdk/web-api) |
 | OAuth        | Set up the authentication flow using V2 OAuth for Slack apps as well as V1 OAuth for classic Slack apps. | [`@slack/oauth`](https://docs.slack.dev/tools/node-slack-sdk/oauth) |
 | Incoming Webhooks | Send notifications to a single channel which the user picks on installation. | [`@slack/webhook`](https://docs.slack.dev/tools/node-slack-sdk/webhook) |
 | Socket Mode  | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | [`@slack/socket-mode`](https://docs.slack.dev/tools/node-slack-sdk/socket-mode) |
@@ -51,11 +51,11 @@ package's documentation, linked in the table above.
 
 Your app will interact with the Web API through the `WebClient` object, which is an export from `@slack/web-api`. You
 typically instantiate a client with a token you received from Slack. The example below shows how to post a message into
-a channel, DM, MPDM, or group. The `WebClient` object makes it simple to call any of the [**over 130 Web API
+a channel, DM, MPDM, or group. The `WebClient` object makes it simple to call any of the [**over 270 Web API
 methods**](https://docs.slack.dev/reference/methods).
 
 ```javascript
-const { WebClient } = require('@slack/web-api');
+import { WebClient } from '@slack/web-api';
 
 // An access token (from your Slack app or custom integration - xoxp, xoxb)
 const token = process.env.SLACK_TOKEN;
@@ -94,7 +94,7 @@ Refer to [the module document page](https://docs.slack.dev/tools/node-slack-sdk/
 
 ## Requirements
 
-This package supports Node v18 and higher. It's highly recommended to use [the latest LTS version of
+This package supports Node v20 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.
 

packages/oauth/README.md

@@ -31,7 +31,7 @@ It may be helpful to read the tutorials on [getting started](https://docs.slack.
 This package exposes an `InstallProvider` class, which sets up the required configuration and exposes methods such as `generateInstallUrl`, `handleCallback`, `authorize` for use within your apps. At a minimum, `InstallProvider` takes a `clientId` and `clientSecret` (both which can be obtained under the **Basic Information** of your app configuration). `InstallProvider` also requires a `stateSecret`, which is used to encode the generated state, and later used to decode that same state to verify it wasn't tampered with during the OAuth flow. **Note**: This example is not ready for production because it only stores installations (tokens) in memory. Please go to the [storing installations in a database](#storing-installations-in-a-database) section to learn how to plug in your own database.
 
 ```javascript
-const { InstallProvider } = require('@slack/oauth');
+import { InstallProvider } from '@slack/oauth';
 
 // initialize the installProvider
 const installer = new InstallProvider({
@@ -47,7 +47,7 @@ const installer = new InstallProvider({
 </summary>
 
   ```javascript
-  const { InstallProvider } = require('@slack/oauth');
+  import { InstallProvider } from '@slack/oauth';
 
   // initialize the installProvider
   const installer = new InstallProvider({
@@ -98,7 +98,7 @@ installer.generateInstallUrl({
 After the user approves the request to install your app (and grants access to the required permissions), Slack will redirect the user to your specified **redirect url**. You can either set the redirect url in the app’s **OAuth and Permissions** page or pass a `redirectUri` when calling `installProvider.generateInstallUrl`. Your HTTP server should handle requests to the redirect URL by calling the `installProvider.handleCallback()` method. The first two arguments (`req`, `res`) to `installProvider.handleCallback` are required. By default, if the installation is successful the user will be redirected back to your App Home in Slack (or redirected back to the last open workspace in your slack app for classic Slack apps). If the installation is not successful the user will be shown an error page.
 
 ```javascript
-const { createServer } = require('http');
+import { createServer } from 'node:http';
 
 const server = createServer((req, res) =>  {
   // our redirect_uri is /slack/oauth_redirect
@@ -291,6 +291,41 @@ const installer = new InstallProvider({
 ```
 ---
 
+### Handle errors
+
+Methods on `InstallProvider` reject with an `Error` when something goes wrong. Each kind of error is its own class, all extending the `SlackOAuthError` base class, so you can use an `instanceof` check to decide how to respond. For example, `authorize()` throws an `AuthorizationError` when it can't fetch an installation.
+
+```javascript
+import { AuthorizationError } from '@slack/oauth';
+
+try {
+  await installer.authorize({ teamId, enterpriseId });
+} catch (error) {
+  if (error instanceof AuthorizationError) {
+    // The underlying error is in `cause`.
+    console.log(error.cause);
+  }
+}
+```
+
+To catch any error thrown by this package, check against the `SlackOAuthError` base class:
+
+```javascript
+import { SlackOAuthError } from '@slack/oauth';
+
+try {
+  const installUrl = await installer.generateInstallUrl({ scopes: ['channels:read'] });
+} catch (error) {
+  if (error instanceof SlackOAuthError) {
+    console.log(error.code, error.message);
+  }
+}
+```
+
+Other error classes include `InstallerInitializationError`, `GenerateInstallUrlError`, `MissingStateError`, `InvalidStateError`, `MissingCodeError`, and `UnknownError`. They all extend `SlackOAuthError`, so an `instanceof SlackOAuthError` check catches any of them.
+
+---
+
 ### Setting the log level and using a custom logger
 
 The `InstallProvider` will log interesting information to the console by default. You can use the `logLevel` to decide how
@@ -300,7 +335,7 @@ in development, it's sometimes helpful to set this to the most verbose: `LogLeve
 
 ```javascript
 // Import LogLevel from the package
-const { InstallProvider, LogLevel } = require('@slack/oauth');
+import { InstallProvider, LogLevel } from '@slack/oauth';
 
 // Log level is one of the options you can set in the constructor
 const installer = new InstallProvider({
@@ -333,7 +368,7 @@ specific methods (known as the `Logger` interface):
 A very simple custom logger might ignore the name and level, and write all messages to a file.
 
 ```javascript
-const { createWriteStream } = require('fs');
+import { createWriteStream } from 'node:fs';
 const logWritable = createWriteStream('/var/my_log_file'); // Not shown: close this stream
 
 const installer = new InstallProvider({

packages/socket-mode/README.md

@@ -25,7 +25,7 @@ Note: **Socket Mode** requires the `connections:write` scope. Navigate to your [
 
 
 ```javascript
-const { SocketModeClient } = require('@slack/socket-mode');
+import { SocketModeClient } from '@slack/socket-mode';
 
 // Read a token from the environment variables
 const appToken = process.env.SLACK_APP_TOKEN;
@@ -39,7 +39,7 @@ const client = new SocketModeClient({appToken});
 Connecting is as easy as calling the `.start()` method.
 
 ```javascript
-const { SocketModeClient } = require('@slack/socket-mode');
+import { SocketModeClient } from '@slack/socket-mode';
 const appToken = process.env.SLACK_APP_TOKEN;
 
 const socketModeClient = new SocketModeClient({appToken});
@@ -59,7 +59,7 @@ The `event` argument passed to the listener is an object. Its contents correspon
 event](https://docs.slack.dev/reference/events) it's registered for.
 
 ```javascript
-const { SocketModeClient } = require('@slack/socket-mode');
+import { SocketModeClient } from '@slack/socket-mode';
 const appToken = process.env.SLACK_APP_TOKEN;
 
 const socketModeClient = new SocketModeClient({appToken});
@@ -79,10 +79,10 @@ socketModeClient.on('message', (event) => {
 To respond to events and send messages back into Slack, we recommend using the `@slack/web-api` package with a [bot token](https://docs.slack.dev/authentication/tokens#bot).
 
 ```javascript
-const { SocketModeClient } = require('@slack/socket-mode');
-const { WebClient } = require('@slack/web-api');
+import { SocketModeClient } from '@slack/socket-mode';
+import { WebClient } from '@slack/web-api';
 
-const socketModeClient = new SocketModeClient(process.env.SLACK_APP_TOKEN);
+const socketModeClient = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });
 const webClient = new WebClient(process.env.BOT_TOKEN);
 
 // Attach listeners to events by type. See: https://docs.slack.dev/reference/events/message
@@ -144,13 +144,49 @@ The client also emits events that are part of its lifecycle, but aren't states.
 
 ---
 
+### Handle errors
+
+Because the client is an `EventEmitter`, errors are delivered to your `error` listener rather than thrown. Each kind of error is its own class, all extending the `SlackSocketModeError` base class, so you can use an `instanceof` check to decide how to respond.
+
+```javascript
+import {
+  SocketModeClient,
+  SMWebsocketError,
+  SMPlatformError,
+  SMSendWhileDisconnectedError,
+} from '@slack/socket-mode';
+
+const client = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });
+
+client.on('error', (error) => {
+  if (error instanceof SMWebsocketError) {
+    // A WebSocket connection or protocol failure. The underlying error is on `cause`.
+    console.log('WebSocket issue:', error.cause);
+  } else if (error instanceof SMPlatformError) {
+    // Slack returned an API error. The response is on `data`.
+    console.log('Platform error:', error.data);
+  } else if (error instanceof SMSendWhileDisconnectedError) {
+    // Tried to send a message while the client was disconnected.
+    console.log('Not connected, will retry...');
+  }
+});
+
+(async () => {
+  await client.start();
+})();
+```
+
+Other error classes you might encounter include `SMNoReplyReceivedError` (the server didn't acknowledge a sent message in time) and `SMSendWhileNotReadyError` (a message was sent before the client was fully ready). They all extend `SlackSocketModeError`, so an `instanceof SlackSocketModeError` check catches any of them.
+
+---
+
 ### Logging
 
 The `SocketModeClient` will log information to the console by default. You can use the `logLevel` to decide how much or what kind of information should be output. There are a few possible log levels, which you can find in the `LogLevel` export. By default, the value is set to `LogLevel.INFO`. While you're in development, it's sometimes helpful to set this to the most verbose: `LogLevel.DEBUG`.
 
 ```javascript
 // Import LogLevel from the package
-const { SocketModeClient, LogLevel } = require('@slack/socket-mode');
+import { SocketModeClient, LogLevel } from '@slack/socket-mode';
 const appToken = process.env.SLACK_APP_TOKEN;
 
 // Log level is one of the options you can set in the constructor
@@ -186,7 +222,7 @@ You can also choose to have logs sent to a custom logger using the `logger` opti
 A very simple custom logger might ignore the name and level, and write all messages to a file.
 
 ```javascript
-const { createWriteStream } = require('fs');
+import { createWriteStream } from 'node:fs';
 const logWritable = createWriteStream('/var/my_log_file'); // Not shown: close this stream
 
 const socketModeClient = new SocketModeClient({

packages/web-api/README.md

@@ -3,7 +3,7 @@
 [![codecov](https://codecov.io/gh/slackapi/node-slack-sdk/graph/badge.svg?token=OcQREPvC7r&flag=web-api)](https://codecov.io/gh/slackapi/node-slack-sdk)
 
 The `@slack/web-api` package contains a simple, convenient, and configurable HTTP client for making requests to Slack's
-[Web API](https://docs.slack.dev/apis/web-api). Use it in your app to call any of the over 130
+[Web API](https://docs.slack.dev/apis/web-api). Use it in your app to call any of the over 270
 [methods](https://docs.slack.dev/reference/methods), and let it handle formatting, queuing, retrying, pagination, and more.
 
 ## Requirements
@@ -37,7 +37,7 @@ begins with `xoxb` or `xoxp`. You get them from each workspace an app is install
 help you get your first token for your development workspace.
 
 ```javascript
-const { WebClient } = require('@slack/web-api');
+import { WebClient } from '@slack/web-api';
 
 // Read a token from the environment variables
 const token = process.env.SLACK_TOKEN;
@@ -55,7 +55,7 @@ Alternatively, you can create a client without a token, and use it with multiple
 `token` when you call a method.
 
 ```javascript
-const { WebClient } = require('@slack/web-api');
+import { WebClient } from '@slack/web-api';
 
 // Initialize a single instance for the whole app
 const web = new WebClient();
@@ -137,22 +137,22 @@ call a method, maybe it's been revoked by a user, or maybe you just used a bad a
 `Promise` will reject with an `Error`. You should catch the error and use the information it contains to decide how your
 app can proceed.
 
-Each error contains a `code` property, which you can check against the `ErrorCode` export to understand the kind of
-error you're dealing with. For example, when Slack responds to your app with an error, that is an
-`ErrorCode.PlatformError`. These types of errors provide Slack's response body as the `data` property.
+Each kind of error is its own class, all extending the `SlackError` base class. Use an `instanceof` check to understand
+what kind of error you're dealing with. For example, when Slack responds to your app with an error, that's a
+`WebAPIPlatformError`, which provides Slack's response body as the `data` property.
 
 ```javascript
-// Import ErrorCode from the package
-const { WebClient, ErrorCode } = require('@slack/web-api');
+// Import the error classes from the package
+import { WebClient, WebAPIPlatformError } from '@slack/web-api';
 
 (async () => {
 
   try {
     // This method call should fail because we're giving it a bogus user ID to lookup.
     const response = await web.users.info({ user: '...' });
   } catch (error) {
-    // Check the code property, and when it's a PlatformError, log the whole response.
-    if (error.code === ErrorCode.PlatformError) {
+    // When it's a platform error, log the response Slack sent back.
+    if (error instanceof WebAPIPlatformError) {
       console.log(error.data);
     } else {
       // Some other error, oh no!
@@ -167,20 +167,14 @@ const { WebClient, ErrorCode } = require('@slack/web-api');
 <strong><i>More error types</i></strong>
 </summary>
 
-There are a few more types of errors that you might encounter, each with one of these `code`s:
+Other error classes you might encounter include the following, though this isn't a complete list. They all extend `SlackError`, so an `instanceof SlackError` check catches any error this package throws.
 
-* `ErrorCode.RequestError`: A request could not be sent. A common reason for this is that your network connection is
-  not available, or `api.slack.com` could not be reached. This error has an `original` property with more details.
+* `WebAPIRequestError`: A request could not be sent. A common reason for this is that your network connection is not available, or `api.slack.com` could not be reached. The underlying error is available on both the standard [`cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) property and the `original` property.
 
-* `ErrorCode.RateLimitedError`: The Web API cannot fulfill the API method call because your app has made too many
-  requests too quickly. This error has a `retryAfter` property with the number of seconds you should wait before trying
-  again. See [the documentation on rate limit handling](https://docs.slack.dev/tools/node-slack-sdk/web-api/#rate-limits) to
-  understand how the client will automatically deal with these problems for you.
+* `WebAPIRateLimitedError`: The Web API cannot fulfill the API method call because your app has made too many requests too quickly. This error has a `retryAfter` property with the number of seconds you should wait before trying again. See [the documentation on rate limit handling](https://docs.slack.dev/tools/node-slack-sdk/web-api/#rate-limits) to understand how the client will automatically deal with these problems for you.
+
+* `WebAPIHTTPError`: The HTTP response contained an unfamiliar status code. The Web API only responds with `200` (yes, even for errors) or `429` (rate limiting). If you receive this error, it's likely due to a problem with a custom `fetch` implementation or a custom API URL. This error has the `statusCode`, `statusMessage`, `headers`, and `body` properties containing more details.
 
-* `ErrorCode.HTTPError`: The HTTP response contained an unfamiliar status code. The Web API only responds with `200`
-  (yes, even for errors) or `429` (rate limiting). If you receive this error, it's likely due to a problem with a proxy,
-  a custom TLS configuration, or a custom API URL. This error has the `statusCode`, `statusMessage`, `headers`, and
-  `body` properties containing more details.
 </details>
 
 ---
@@ -262,7 +256,7 @@ in development, it's sometimes helpful to set this to the most verbose: `LogLeve
 
 ```javascript
 // Import LogLevel from the package
-const { WebClient, LogLevel } = require('@slack/web-api');
+import { WebClient, LogLevel } from '@slack/web-api';
 
 // Log level is one of the options you can set in the constructor
 const web = new WebClient(token, {
@@ -292,7 +286,7 @@ specific methods (known as the `Logger` interface):
 A very simple custom logger might ignore the name and level, and write all messages to a file.
 
 ```javascript
-const { createWriteStream } = require('fs');
+import { createWriteStream } from 'node:fs';
 const logWritable = createWriteStream('/var/my_log_file'); // Not shown: close this stream
 
 const web = new WebClient(token, {
@@ -321,7 +315,7 @@ You can observe each of the retries in your logs by [setting the log level to DE
 following code with your network disconnected, and then re-connect after you see a couple of log messages:
 
 ```javascript
-const { WebClient, LogLevel } = require('@slack/web-api');
+import { WebClient, LogLevel } from '@slack/web-api';
 
 const web = new WebClient('bogus token');
 
@@ -343,7 +337,7 @@ one that works better for you. The `retryPolicies` export contains a few well kn
 your own.
 
 ```javascript
-const { WebClient, retryPolicies } = require('@slack/web-api');
+import { WebClient, retryPolicies } from '@slack/web-api';
 
 const web = new WebClient(token, {
   retryConfig: retryPolicies.fiveRetriesInFiveMinutes,
@@ -370,10 +364,8 @@ The [documentation website](https://docs.slack.dev/tools/node-slack-sdk/web-api/
 the `WebClient`:
 
 *  Upload a file with a `Buffer` or a `ReadableStream`.
-*  Using a custom agent for proxying
 *  Rate limit handling
 *  Request concurrency
-*  Custom TLS configuration
 *  Custom API URL
 *  Exchange an OAuth grant for a token