feat(socket-mode): emit a hello event with the connection handshake payload

[deepunyk]

Summary

Closes #2253.

Slack sends a hello message once it finalizes the Socket Mode handshake. SocketModeClient parses that message, logs it at debug level, then discards it and emits only the connected state — so num_connections, debug_info and connection_info were reachable only by scraping debug logs.

This takes the first option suggested in the issue: emit the parsed message as its own hello event.

What changed

• SocketModeClient emits hello with the parsed handshake message. It fires just before the connected state, because start() resolves on connected and a listener attached after that would miss the first connection's handshake.
• New exported HelloMessage type, along with HelloMessageDebugInfo and HelloMessageConnectionInfo, following the payload documented in Using Socket Mode. type and num_connections are required; the nested objects and their fields are optional.
• The lifecycle events table in packages/socket-mode/README.md gains a hello row and a short example.

Existing behaviour is unchanged: connected still fires with the same argument, and hello still returns early rather than reaching slack_event listeners, since it carries no envelope_id to ack.

How users can take advantage of these changes

Detecting that a second instance of an app is holding the same app-level token:

client.on('hello', ({ num_connections }) => {
  if (num_connections > 1) {
    console.warn(`This app token has ${num_connections} open connections.`);
  }
});

Estimating when Slack will refresh the connection:

import type { HelloMessage } from '@slack/socket-mode';

client.on('hello', (message: HelloMessage) => {
  console.log(`Refresh expected in ~${message.debug_info?.approximate_connection_time}s`);
});

Testing

Three unit tests were added under the onWebSocketMessage describe in SocketModeClient.test.ts, alongside the existing slash_commands, events_api and interactivity groups: the payload reaching a hello listener, the hello-then-connected ordering, and hello not leaking into slack_event listeners.

One integration test covers the same ordering against the WebSocket server double, asserting the payload has arrived by the time start() resolves. The double's handshake message now includes num_connections, so it matches what Slack actually sends.

$ npm run build --workspace=@slack/socket-mode
$ npm run test:unit --workspace=@slack/socket-mode         # 31 pass, 0 fail
$ npm run test:integration --workspace=@slack/socket-mode  # 29 pass, 0 fail
$ npm run lint

Test app.ts

import { SocketModeClient } from '@slack/socket-mode';

const client = new SocketModeClient({ appToken: process.env.SLACK_APP_TOKEN });

client.on('hello', (message) => {
  console.log('hello:', JSON.stringify(message));
  if (message.num_connections > 1) {
    console.warn(`This app token has ${message.num_connections} open connections.`);
  }
});

client.on('connected', () => console.log('connected'));

await client.start();

Start a second copy against the same app-level token to see num_connections climb.

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3341305

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@slack/socket-mode	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR