feat(realtime): add generating lifecycle state and event buffering

[AdirAmsalem]

Summary

Adds "generating" ConnectionState and event buffering to the realtime client.

• "generating" state: Emitted when the server sends a generation_started signaling message, letting consumers know the session is live and frames are incoming. connect() now resolves on either "connected" or "generating" (whichever arrives first).
• Event buffering: Events fired during connect() are buffered and replayed after the client is returned, so listeners registered on the returned client never miss early state transitions.

What Changed

New: "generating" ConnectionState

• ConnectionState type now includes "generating" (type moved from webrtc-connection.ts to types.ts for shared use)
• WebRTCConnection handles generation_started signaling messages → sets state to "generating"
• "generating" is sticky in onconnectionstatechange — only "disconnected" can override it
• isConnected() and assertConnected() accept "generating" as a writable state
• connect() resolves on "connected" or "generating"

Usage

// Subscribe to connection state changes
realtimeClient.on("connectionChange", (state) => {
  switch (state) {
    case "connecting":
      console.log("Connecting to server...");
      break;
    case "connected":
      console.log("Connected! Streaming active.");
      break;
    case "generating":
      console.log("Generation started! Frames incoming.");
      break;
    case "reconnecting":
      console.log("Connection lost, reconnecting...");
      break;
    case "disconnected":
      console.log("Disconnected from server.");
      break;
  }
});

New: Event Buffering

• connectionChange and error events emitted during connect() are buffered
• After connect() resolves and returns the client, buffered events replay via a macrotask (setTimeout(0))
• buffering = false is set inside the macrotask to prevent ordering issues
• disconnect() clears the event buffer to prevent re-entrant replay

Public API Changes

• ConnectionState type: added "generating" — additive, non-breaking for most consumers
  • ⚠️ Consumers with exhaustive switch on ConnectionState will get a compile error (intentional)
• Events["connectionChange"]: now typed as ConnectionState instead of a hardcoded string union
• No new methods, no removed methods, no changed method signatures

Tests

4 new unit tests:

• connect() resolves when state reaches "generating"
• "generating" → "disconnected" transition works correctly
• "generating" triggers reconnect flow
• Event replay delivers buffered events after connect() returns

All 80 tests pass. Typecheck and build clean.

---

Note

Medium Risk
Changes core realtime connection state handling and reconnect decisions; while additive, consumers with exhaustive ConnectionState handling or reliance on event timing could see behavior changes.

Overview
Adds a new realtime lifecycle state, generating, surfaced via the exported ConnectionState type and emitted when the server sends a generation_started signaling message; connect() now treats generating as an established state (handshake completion, isConnected(), reconnect gating, and method send preconditions).

Updates the realtime client to buffer connectionChange/error events during connect() and replay them asynchronously after the client is returned, preventing missed early state transitions; includes new unit tests covering generating transitions/reconnect behavior and event replay ordering.

^{Written by Cursor Bugbot for commit 6c2565b. This will update automatically on new commits. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/DecartAI/sdk/@decartai/sdk@79

commit: 87b6fe3

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[tomershlasky]

LGTM, letf 1 comment

[tomershlasky]

maybe some better if else for more readbility