buzz-me-in 2.2.0 → 2.2.2-beta.0

package/README.md

@@ -1,3 +1,5 @@
+![buzz-me-in: answer your apartment intercom from Apple Home](https://raw.githubusercontent.com/atdr/buzz-me-in/main/docs/assets/banner.png)
+
 # buzz-me-in
 
 [![npm](https://img.shields.io/npm/v/buzz-me-in.svg?style=flat-square)](https://www.npmjs.com/package/buzz-me-in)

package/homekit.js

@@ -26,6 +26,7 @@ const { spawn } = require('child_process');
 const config = require('./src/core/config');
 const state = require('./src/core/state');
 const { sendDtmfSequence, sendMulawAudio } = require('./src/core/mulaw-audio');
+const { buildInboundFfmpegArgs } = require('./src/core/inbound-ffmpeg-args');
 const {
   removeReturnAudioSdp,
   removeSdpDir,
@@ -281,127 +282,23 @@ function _startSession(sessionID, s, request, callback) {
   // Reopening the live view inside the grace window means the user is not
   // finished after all.
   cancelPendingHangUp('homekit-session-restarted');
-  const videoParams = srtpParams(s.hkVideoKey, s.hkVideoSalt);
-  const audioParams = srtpParams(s.hkAudioKey, s.hkAudioSalt);
-  const video = request.video;
   const audio = request.audio;
-  const videoBitrate = Math.max(64, video.max_bit_rate || 200);
-  const videoBufferSize = Math.max(videoBitrate * 2, 128);
-  const mtu = video.mtu || 1316;
 
-  // -------------------------------------------------------------------------
-  // Inbound ffmpeg
-  //
-  // Input 0  – raw mulaw/8kHz from Twilio via stdin
-  //   Let the raw audio demuxer derive PTS from sample count. Using wall-clock
-  //   timestamps breaks when ffmpeg drains the buffered startup audio burst.
-  //   -ch_layout declares mono rather than -ac counting one channel: a count
-  //   leaves the layout unset, so the decoder guesses it and logs "Guessed
-  //   Channel Layout: mono" on every call. Our stderr handler is a warn, so
-  //   that guess looked like a fault in the journal. Needs ffmpeg >= 5.1.
-  //
-  // Input 1  – synthetic black video (lavfi color source)
-  //   Generates H.264 Baseline/3.1 frames at 15 fps.
-  //   HomeKit requires a video track; there is no real camera feed.
-  //   keyint_min=15 / -g 15 forces an IDR frame every second — HomeKit
-  //   requests it when the live view is first opened; without frequent IDRs
-  //   the video stays blank until the next natural keyframe.
-  //
-  // Two separate SRTP outputs — no muxing, no pts coupling between streams.
-  // -------------------------------------------------------------------------
-  const ffIn = spawn('ffmpeg', [
-    '-y',
-    '-loglevel',
-    'warning',
-
-    // ---- Input 0: raw mulaw from Twilio ----
-    '-thread_queue_size',
-    '512',
-    '-f',
-    'mulaw',
-    '-ar',
-    '8000',
-    '-ch_layout',
-    'mono',
-    '-i',
-    'pipe:0',
-
-    // ---- Input 1: blank video ----
-    '-f',
-    'lavfi',
-    '-i',
-    'color=black:s=1280x720:r=15',
-
-    // ---- Video output → HomeKit SRTP ----
-    '-map',
-    '1:v',
-    '-c:v',
-    'libx264',
-    '-profile:v',
-    'baseline',
-    '-level:v',
-    '3.1',
-    '-preset',
-    'ultrafast',
-    '-tune',
-    'zerolatency',
-    '-pix_fmt',
-    'yuv420p',
-    '-b:v',
-    `${videoBitrate}k`,
-    '-maxrate',
-    `${videoBitrate}k`,
-    '-bufsize',
-    `${videoBufferSize}k`,
-    '-g',
-    String(video.fps || 15),
-    '-keyint_min',
-    String(video.fps || 15),
-    '-payload_type',
-    String(video.pt),
-    '-ssrc',
-    String(s.videoSsrc),
-    '-f',
-    'rtp',
-    '-srtp_out_suite',
-    'AES_CM_128_HMAC_SHA1_80',
-    '-srtp_out_params',
-    videoParams,
-    `srtp://${s.targetAddress}:${s.hkVideoPort}?rtcpport=${s.hkVideoPort}&localrtcpport=${s.hkVideoPort}&pkt_size=${mtu}`,
-
-    // ---- Audio output → HomeKit SRTP (Opus/16kHz) ----
-    //
-    // Note on codec choice: libopus is in every standard ffmpeg build.
-    // If you prefer AAC-ELD (required by some older HomeKit devices), compile
-    // ffmpeg with --enable-libfdk-aac --enable-nonfree and change:
-    //   '-c:a', 'libfdk_aac', '-profile:a', 'aac_eld',
-    // and update streamingOptions.audio.codecs below to AAC_ELD.
-    '-map',
-    '0:a',
-    '-c:a',
-    'libopus',
-    '-ar',
-    '16000',
-    '-ac',
-    '1',
-    '-b:a',
-    '24k',
-    '-application',
-    'voip',
-    '-frame_duration',
-    '20',
-    '-payload_type',
-    String(audio.pt),
-    '-ssrc',
-    String(s.audioSsrc),
-    '-f',
-    'rtp',
-    '-srtp_out_suite',
-    'AES_CM_128_HMAC_SHA1_80',
-    '-srtp_out_params',
-    audioParams,
-    `srtp://${s.targetAddress}:${s.hkAudioPort}?rtcpport=${s.hkAudioPort}&localrtcpport=${s.hkAudioPort}`,
-  ]);
+  // Inbound ffmpeg: see src/core/inbound-ffmpeg-args.js for the pipeline.
+  const ffIn = spawn(
+    'ffmpeg',
+    buildInboundFfmpegArgs({
+      video: request.video,
+      audio,
+      videoParams: srtpParams(s.hkVideoKey, s.hkVideoSalt),
+      audioParams: srtpParams(s.hkAudioKey, s.hkAudioSalt),
+      targetAddress: s.targetAddress,
+      hkVideoPort: s.hkVideoPort,
+      hkAudioPort: s.hkAudioPort,
+      videoSsrc: s.videoSsrc,
+      audioSsrc: s.audioSsrc,
+    })
+  );
 
   ffIn.stderr.on('data', (d) => {
     logger.warn('Inbound ffmpeg stderr', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.2.0",
+  "version": "2.2.2-beta.0",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "keywords": [
     "homekit",
@@ -15,7 +15,7 @@
   ],
   "main": "server.js",
   "bin": {
-    "buzz-me-in": "./server.js"
+    "buzz-me-in": "server.js"
   },
   "files": [
     "server.js",
@@ -57,14 +57,14 @@
     "hap-nodejs": "^0.14.2",
     "qrcode-terminal": "^0.12.0",
     "twilio": "^6.1.0",
-    "websocket": "^1.0.35",
+    "ws": "^8.22.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@eslint/js": "^10.0.1",
-    "@types/websocket": "^1.0.10",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.11.0",

package/server.js

@@ -29,7 +29,7 @@ if (require.main === module) {
 
 const http = require('http');
 const twilio = require('twilio');
-const WebSocketServer = require('websocket').server;
+const { WebSocketServer } = require('ws');
 
 const config = require('./src/core/config');
 const state = require('./src/core/state');
@@ -45,7 +45,7 @@ const homekit = require('./homekit');
 const { createLogger } = require('./src/core/log');
 const { safeEqualString } = require('./src/core/safe-equal');
 const { MediaStream } = require('./src/core/media-stream');
-/** @import { request as WebSocketRequest } from 'websocket' */
+/** @import { Duplex } from 'stream' */
 /** @import { HandshakeVerificationError } from './src/core/types' */
 
 const HTTP_SERVER_PORT = config.port;
@@ -82,17 +82,19 @@ const RINGTONE_WAV = createRingbackWav();
 
 const wsserver = http.createServer(handleRequest);
 
-// Enforce message bounds in the websocket library itself so oversized
-// frames are rejected before assembly, instead of relying only on the
-// per-message check in MediaStream (library defaults allow 1 MiB).
+// Enforce message bounds in the ws library itself so oversized frames are
+// rejected before assembly, instead of relying only on the per-message check
+// in MediaStream (the library default allows 100 MiB).
 const WS_LIBRARY_MAX_BYTES = MAX_WS_UTF8_BYTES * 4;
 const MAX_CONCURRENT_WS_CONNECTIONS = config.wsMaxConnections;
 
+// noServer: the upgrade handler below runs the handshake checks and only then
+// hands the socket to ws. Sockets are tracked in activeWsConnections instead of
+// by the library.
 const mediaws = new WebSocketServer({
-  httpServer: wsserver,
-  autoAcceptConnections: false,
-  maxReceivedFrameSize: WS_LIBRARY_MAX_BYTES,
-  maxReceivedMessageSize: WS_LIBRARY_MAX_BYTES,
+  noServer: true,
+  clientTracking: false,
+  maxPayload: WS_LIBRARY_MAX_BYTES,
 });
 
 state.setOnSessionStale((session) => {
@@ -294,28 +296,64 @@ GET_ROUTES.set('/readyz', function (_req, res) {
 // WebSocket media stream
 // ---------------------------------------------------------------------------
 
-mediaws.on('request', function (request) {
-  /** @type {WebSocketRequest} */
-  const wsRequest = request;
+/**
+ * Refuse a WebSocket upgrade with a plain HTTP response, before any WebSocket
+ * handshake is written, then drop the socket.
+ *
+ * @param {Duplex} socket
+ * @param {number} status
+ * @param {string} reason
+ * @returns {void}
+ */
+function rejectUpgrade(socket, status, reason) {
+  socket.end(
+    `HTTP/1.1 ${status} ${http.STATUS_CODES[status]}\r\n` +
+      'Connection: close\r\n' +
+      'Content-Type: text/plain\r\n' +
+      `Content-Length: ${Buffer.byteLength(reason)}\r\n` +
+      '\r\n' +
+      reason
+  );
+}
+
+/**
+ * Handshake checks for the `/media` WebSocket, run before ws takes the socket.
+ * Exported so tests can mount it on their own HTTP server.
+ *
+ * @param {import('http').IncomingMessage} request
+ * @param {Duplex} socket
+ * @param {Buffer} head
+ * @returns {void}
+ */
+function handleMediaUpgrade(request, socket, head) {
+  // A client that resets mid-handshake would otherwise raise an unhandled
+  // 'error' and take the process down via the uncaughtException handler.
+  socket.on('error', () => socket.destroy());
   if (shuttingDown) {
-    wsRequest.reject(503, 'Server shutting down');
+    rejectUpgrade(socket, 503, 'Server shutting down');
+    return;
+  }
+  // Node accepts an absolute-form target such as `http://[`, which URL cannot
+  // parse. Thrown here, it would exit the process via uncaughtException.
+  let path;
+  try {
+    path = new URL(request.url || '/', 'http://localhost').pathname;
+  } catch {
+    rejectUpgrade(socket, 400, 'Bad request');
     return;
   }
-  const path = wsRequest.resourceURL && wsRequest.resourceURL.pathname;
   if (path !== STREAM_PATH) {
-    wsRequest.reject(404, 'Not found');
+    rejectUpgrade(socket, 404, 'Not found');
     return;
   }
   // Twilio signs the Media Streams handshake, so an unauthenticated socket can
-  // be refused here rather than after accept(). Without this the server accepts
-  // the connection and allocates a MediaStream before any auth runs, because
-  // the stream token only arrives later in the `start` frame. Defence in depth:
-  // the one-time token below remains the authority, since this signature is an
-  // HMAC over a constant URL and so never varies between calls.
+  // be refused here rather than after the upgrade. Without this the server
+  // accepts the connection and allocates a MediaStream before any auth runs,
+  // because the stream token only arrives later in the `start` frame. Defence
+  // in depth: the one-time token below remains the authority, since this
+  // signature is an HMAC over a constant URL and so never varies between calls.
   if (MEDIA_SIGNATURE_MODE !== 'off') {
-    const handshake = verifyStreamHandshakeSignature(
-      wsRequest.httpRequest.headers['x-twilio-signature']
-    );
+    const handshake = verifyStreamHandshakeSignature(request.headers['x-twilio-signature']);
     if (!handshake.ok) {
       // strict:false disables discriminated-union narrowing; cast as elsewhere.
       const handshakeError = /** @type {HandshakeVerificationError} */ (handshake);
@@ -325,7 +363,7 @@ mediaws.on('request', function (request) {
         enforced: MEDIA_SIGNATURE_MODE === 'enforce',
       });
       if (MEDIA_SIGNATURE_MODE === 'enforce') {
-        wsRequest.reject(403, 'Forbidden');
+        rejectUpgrade(socket, 403, 'Forbidden');
         return;
       }
     } else {
@@ -348,18 +386,31 @@ mediaws.on('request', function (request) {
       event: 'media-ws-rejected',
       reason: 'too-many-connections',
     });
-    wsRequest.reject(503, 'Too many connections');
+    rejectUpgrade(socket, 503, 'Too many connections');
     return;
   }
 
-  const connection = wsRequest.accept(null, wsRequest.origin);
-  activeWsConnections.add(connection);
-  connection.on('close', () => activeWsConnections.delete(connection));
-  mediaWsLogger.info('Media websocket connection accepted', {
-    event: 'media-ws-accepted',
+  mediaws.handleUpgrade(request, socket, head, function (connection) {
+    activeWsConnections.add(connection);
+    connection.on('close', () => activeWsConnections.delete(connection));
+    // ws emits 'error' for protocol violations and frames over maxPayload, then
+    // closes the socket itself; 'close' still fires, so MediaStream tears down.
+    // Unhandled, the error would exit the process.
+    connection.on('error', (err) => {
+      mediaWsLogger.warn('Media websocket protocol error', {
+        event: 'media-ws-error',
+        reason: /** @type {NodeJS.ErrnoException} */ (err).code || 'ws-error',
+        error: err,
+      });
+    });
+    mediaWsLogger.info('Media websocket connection accepted', {
+      event: 'media-ws-accepted',
+    });
+    new MediaStream(connection, mediaStreamDeps);
   });
-  new MediaStream(connection, mediaStreamDeps);
-});
+}
+
+wsserver.on('upgrade', handleMediaUpgrade);
 
 /** @type {import('./src/core/media-stream').MediaStreamDeps} */
 const mediaStreamDeps = {
@@ -543,6 +594,7 @@ module.exports = {
   beginShutdown,
   buildTwiml,
   describeCaller,
+  handleMediaUpgrade,
   handleRequest,
   isAuthorizedForStatus,
   isValidTwilioRequest,

package/src/core/inbound-ffmpeg-args.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * Argument list for the inbound ffmpeg process: Twilio mu-law on stdin →
+ * Opus/SRTP audio plus a synthetic H.264/SRTP video track to the controller.
+ * Kept apart from homekit.js so the arguments can be tested without spawning
+ * ffmpeg or standing up a HomeKit session.
+ */
+
+/**
+ * @param {{
+ *   video: { max_bit_rate?: number, mtu?: number, fps?: number, pt: number },
+ *   audio: { pt: number },
+ *   videoParams: string,
+ *   audioParams: string,
+ *   targetAddress: string,
+ *   hkVideoPort: number,
+ *   hkAudioPort: number,
+ *   videoSsrc: number,
+ *   audioSsrc: number,
+ * }} input
+ * @returns {string[]}
+ */
+function buildInboundFfmpegArgs(input) {
+  const { video, audio, videoParams, audioParams } = input;
+  const videoBitrate = Math.max(64, video.max_bit_rate || 200);
+  const videoBufferSize = Math.max(videoBitrate * 2, 128);
+  const mtu = video.mtu || 1316;
+
+  // -------------------------------------------------------------------------
+  // Inbound ffmpeg
+  //
+  // Input 0  – raw mulaw/8kHz from Twilio via stdin
+  //   Let the raw audio demuxer derive PTS from sample count. Using wall-clock
+  //   timestamps breaks when ffmpeg drains the buffered startup audio burst.
+  //   -ch_layout declares mono rather than -ac counting one channel: a count
+  //   leaves the layout unset, so the decoder guesses it and logs "Guessed
+  //   Channel Layout: mono" on every call. Our stderr handler is a warn, so
+  //   that guess looked like a fault in the journal. Needs ffmpeg >= 5.1.
+  //   -probesize 32 / -analyzeduration 0 skip stream probing: format, rate
+  //   and layout are all declared, but by default ffmpeg still reads ~3 s of
+  //   stdin before it outputs anything, then sends that backlog to the
+  //   controller in one burst, and the caller's first words are lost (#102).
+  //
+  // Input 1  – synthetic black video (lavfi color source)
+  //   Generates H.264 Baseline/3.1 frames at 15 fps.
+  //   HomeKit requires a video track; there is no real camera feed.
+  //   keyint_min=15 / -g 15 forces an IDR frame every second — HomeKit
+  //   requests it when the live view is first opened; without frequent IDRs
+  //   the video stays blank until the next natural keyframe.
+  //
+  // Two separate SRTP outputs — no muxing, no pts coupling between streams.
+  // -------------------------------------------------------------------------
+  return [
+    '-y',
+    '-loglevel',
+    'warning',
+
+    // ---- Input 0: raw mulaw from Twilio ----
+    '-thread_queue_size',
+    '512',
+    '-probesize',
+    '32',
+    '-analyzeduration',
+    '0',
+    '-f',
+    'mulaw',
+    '-ar',
+    '8000',
+    '-ch_layout',
+    'mono',
+    '-i',
+    'pipe:0',
+
+    // ---- Input 1: blank video ----
+    '-f',
+    'lavfi',
+    '-i',
+    'color=black:s=1280x720:r=15',
+
+    // ---- Video output → HomeKit SRTP ----
+    '-map',
+    '1:v',
+    '-c:v',
+    'libx264',
+    '-profile:v',
+    'baseline',
+    '-level:v',
+    '3.1',
+    '-preset',
+    'ultrafast',
+    '-tune',
+    'zerolatency',
+    '-pix_fmt',
+    'yuv420p',
+    '-b:v',
+    `${videoBitrate}k`,
+    '-maxrate',
+    `${videoBitrate}k`,
+    '-bufsize',
+    `${videoBufferSize}k`,
+    '-g',
+    String(video.fps || 15),
+    '-keyint_min',
+    String(video.fps || 15),
+    '-payload_type',
+    String(video.pt),
+    '-ssrc',
+    String(input.videoSsrc),
+    '-f',
+    'rtp',
+    '-srtp_out_suite',
+    'AES_CM_128_HMAC_SHA1_80',
+    '-srtp_out_params',
+    videoParams,
+    `srtp://${input.targetAddress}:${input.hkVideoPort}?rtcpport=${input.hkVideoPort}&localrtcpport=${input.hkVideoPort}&pkt_size=${mtu}`,
+
+    // ---- Audio output → HomeKit SRTP (Opus/16kHz) ----
+    //
+    // Note on codec choice: libopus is in every standard ffmpeg build.
+    // If you prefer AAC-ELD (required by some older HomeKit devices), compile
+    // ffmpeg with --enable-libfdk-aac --enable-nonfree and change:
+    //   '-c:a', 'libfdk_aac', '-profile:a', 'aac_eld',
+    // and update streamingOptions.audio.codecs below to AAC_ELD.
+    //
+    // RTP clock: HomeKit clocks Opus RTP timestamps at the negotiated sample
+    // rate (16 kHz, 320 ticks per 20 ms packet), which is also what the iPhone
+    // sends on the return leg. ffmpeg's RTP muxer always uses RFC 7587's
+    // 48 kHz for Opus (960 ticks), so the controller saw audio arriving three
+    // times slower than its timestamps said, and dropped words (#102).
+    // libopus stamps packets in 1/16000; relabelling that time base as
+    // 1/48000 stops the muxer rescaling, so each packet advances by 320.
+    '-map',
+    '0:a',
+    '-c:a',
+    'libopus',
+    '-ar',
+    '16000',
+    '-ac',
+    '1',
+    '-b:a',
+    '24k',
+    '-application',
+    'voip',
+    '-frame_duration',
+    '20',
+    '-bsf:a',
+    'setts=time_base=1/48000',
+    '-payload_type',
+    String(audio.pt),
+    '-ssrc',
+    String(input.audioSsrc),
+    '-f',
+    'rtp',
+    '-srtp_out_suite',
+    'AES_CM_128_HMAC_SHA1_80',
+    '-srtp_out_params',
+    audioParams,
+    `srtp://${input.targetAddress}:${input.hkAudioPort}?rtcpport=${input.hkAudioPort}&localrtcpport=${input.hkAudioPort}`,
+  ];
+}
+
+module.exports = { buildInboundFfmpegArgs };

package/src/core/media-stream.js

@@ -13,7 +13,7 @@ const { PassThrough } = require('stream');
 const { parseTwilioWsEvent, parseTwilioMediaPayload } = require('./ws-events-schema');
 const { createRingbackMulawCycle, sendMulawAudio } = require('./mulaw-audio');
 
-/** @import { connection, Message } from 'websocket' */
+/** @import { WebSocket } from 'ws' */
 /** @import { WsEventParseOkSupported, StreamTokenVerificationResult, TokenVerificationError, WsEventParseError, MediaPayloadParseError } from './types' */
 
 /**
@@ -31,7 +31,7 @@ const { createRingbackMulawCycle, sendMulawAudio } = require('./mulaw-audio');
 
 class MediaStream {
   /**
-   * @param {connection} connection
+   * @param {WebSocket} connection
    * @param {MediaStreamDeps} deps
    */
   constructor(connection, deps) {
@@ -67,11 +67,12 @@ class MediaStream {
   }
 
   /**
-   * @param {Message} message
+   * @param {Buffer} data
+   * @param {boolean} isBinary
    */
-  processMessage(message) {
-    if (message.type !== 'utf8') return;
-    if (message.utf8Data.length > this.deps.maxUtf8Bytes) {
+  processMessage(data, isBinary) {
+    if (isBinary) return;
+    if (data.length > this.deps.maxUtf8Bytes) {
       this.logger.warn('Media websocket message too large', {
         event: 'media-ws-message-too-large',
         reason: 'max-message-bytes-exceeded',
@@ -82,7 +83,7 @@ class MediaStream {
 
     let rawData;
     try {
-      rawData = JSON.parse(message.utf8Data);
+      rawData = JSON.parse(data.toString('utf8'));
     } catch {
       this.logger.warn('Media websocket invalid JSON', {
         event: 'media-ws-invalid-json',

package/src/core/mulaw-audio.js

@@ -174,14 +174,14 @@ function createDualToneMulaw(lowFrequency, highFrequency, durationMs, amplitude)
 }
 
 /**
- * @param {{ streamSid: string, wsConnection: { sendUTF: (message: string) => void } }} activeCall
+ * @param {{ streamSid: string, wsConnection: { send: (message: string) => void } }} activeCall
  * @param {Buffer} payload
  */
 function sendMulawAudio(activeCall, payload) {
   if (!activeCall || !activeCall.streamSid || !activeCall.wsConnection) {
     throw new Error('Cannot send audio without an active media stream');
   }
-  activeCall.wsConnection.sendUTF(
+  activeCall.wsConnection.send(
     JSON.stringify({
       event: 'media',
       streamSid: activeCall.streamSid,
@@ -191,7 +191,7 @@ function sendMulawAudio(activeCall, payload) {
 }
 
 /**
- * @param {{ streamSid: string, wsConnection: { sendUTF: (message: string) => void } }} activeCall
+ * @param {{ streamSid: string, wsConnection: { send: (message: string) => void } }} activeCall
  * @param {string} digits
  * @param {{ chunkMs?: number, toneMs?: number, trailingSilenceMs?: number }} [options]
  */

package/src/core/state.js

@@ -4,7 +4,7 @@ const config = require('./config');
 const { createLogger } = require('./log');
 const logger = createLogger({ component: 'state' });
 
-/** @import { connection as WebSocketConnection } from 'websocket' */
+/** @import { WebSocket as WebSocketConnection } from 'ws' */
 /** @import { CallSession, CallStatus, StartCallResult, ClearCallResult, ClearedCallSession } from './types.js' */
 
 class CallSessionManager {

package/src/core/types.js

@@ -118,7 +118,7 @@
  * @typedef {{
  *   callSid: string,
  *   streamSid: string,
- *   wsConnection: import('websocket').connection,
+ *   wsConnection: import('ws').WebSocket,
  *   createdAtMs: number,
  *   lastEventAtMs: number,
  *   lastEvent: string