Bolt v4 Release Candidate 3

A lot! We have prepared a migration guide to help bolt-js consumers migrate their bolt v3 apps to v4.

What's Changed

Breaking Changes

Middleware Type Changes

In bolt we have a set of Slack*MiddlewareArgs types: for events, shortcuts, commands, and so on. They 'wrap' the underlying event payloads with additional middleware-relevant bits like a next() method, a context object for devs to augment, and so on.

Many of these types, for example the SlackEventMiddlewareArgs type, previously used a conditional to sometimes define particular additional helper utilities on the middleware arguments. For example, the say utility, or tacking on a convenience message property for message-event-related payloads. This was problematic in practice in TypeScript situations, not just internally (this change fixes #2135) within the bolt codebase but for developers as well: when the payload was not of a type that required the extra utility, these properties would be required to exist on the middleware arguments but have a value of undefined. Those of us trying to build generic middleware utilities would have to deal with TS compilation errors and needing to liberally type-cast to avoid these conditional mismatches with undefined.

Instead, these MiddlewareArgs types now conditionally create a type intersection when appropriate in order to provide this conditional-utility-extension mechanism. In practice that looks something like:

type SomeMiddlewareArgs<EventType extends string = string> = {
  // some type in here
} & (EventType extends 'message'
  // If this is a message event, add a `message` property
  ? { message: EventFromType<EventType> }
  : unknown
)

With the above, now when a message payload is wrapped up into middleware arguments, it will contain an appropriate message property, whereas a non-message payload will be intersected with unknown - effectively a type "noop." No more e.g. say: undefined or message: undefined to deal with!

Other Breaking Changes

• drops node v14 and v16 (are now EOL'ed)
• express to v4->v5; ExpressReceiver users will be exposed to express v4 -> v5 breaking changes
  • fixes #2242
• upgrades to @slack/socket-mode v2; SocketModeReceiver users who have attached custom event listeners to the public socketModeClient directly should read the v1 -> v2 migration guide in case the major upgrade could affect them
  • fixes #2225
• upgrades @slack/web-api v7; all users should read the web-api v6->v7 migration guide to see what the scope of breaking changes the client within listeners is affected by
• removed exported type: KnownKeys
• @slack/types now exist under a named export types.
• removed the SocketModeFunctions class that had a single static method on it and instead directly exposed the defaultProcessEventErrorHandler method from it.
• the built-in middleware functions ignoreSelf and directMention now no longer must be invoked as a method in order to return middleware; instead they are middleware to be used directly. this lines up the API for these built-in middlewares to match the other builtins.
• AWSReceiver's AwsEvent interface now models event payloads a bit differently; we now properly model AWS API Gateway v1 and v2 payloads separately.
  • This resolves #2272
• remove deprecated methods/modules/properties:
  • OptionsRequest interface
  • authed_users and authed_teams from event payload envelope
  • render-html-for-install-path module
  • verify and VerifyOptions from the verify-request module
  • src/receivers/http-utils.ts module

Non-breaking Changes

• expose the bundled @slack/web-api dependency under the webApi named export
• dependency updates:
  • upgrades raw-body to v3
  • upgrades @slack/oauth to v3
  • removes promise.allsettled since that is natively supported in node since v14
  • moves @types/tsscmp to dev dependencies since that is not exposed to developers