feat(realtime): add subscribe client for receive-only session viewing

[AdirAmsalem]

Summary

Add subscribe functionality allowing viewers to watch existing realtime sessions.

How it works

1. Producer connects normally → server sends session_id message → SDK encodes it into an opaque subscribeToken (base64 JSON of {sid, ip, port})
2. Subscriber calls client.realtime.subscribe({ token, onRemoteStream }) → SDK decodes the token, builds the subscribe URL, connects with receive-only WebRTC transceivers

// Producer side
const producer = await client.realtime.connect(stream, { model, onRemoteStream });
const token = producer.subscribeToken;

// Subscriber side
const viewer = await client.realtime.subscribe({
  token,
  onRemoteStream: (stream) => { videoElement.srcObject = stream; },
});

What's included

• subscribe-client.ts — Token encode/decode functions + RealTimeSubscribeClient type (read-only: no set, setPrompt, setImage)
• event-buffer.ts — Extracted shared createEventBuffer<E>() utility used by both connect and subscribe flows
• client.ts — subscribeToken getter on producer client, subscribe() method on realtime client
• webrtc-connection.ts — Handles session_id messages from server, adds recvonly video+audio transceivers when localStream is null
• webrtc-manager.ts — subscribeMode flag enabling reconnection for subscribers even without a local stream
• types.ts — SessionIdMessage type matching server's {"type":"session_id",...} format
• index.ts — Re-exports RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions

Tests

87/87 passing — includes subscribe-specific tests for:

• Token encode/decode round-trip
• Invalid token handling (bad base64, missing fields)
• Recvonly transceiver setup
• Reconnect with null stream in subscribe mode
• session_id message → subscribeToken population
• Subscribe event buffering

---

Note

Medium Risk
Touches core WebRTC connection and reconnect behavior and introduces a new public realtime API surface (subscribeToken/subscribe()), which could affect existing streaming sessions if regressions slip in.

Overview
Adds a new realtime subscriber flow to the SDK: producer connections now expose a subscribeToken derived from a server-sent session_id, and a new realtime.subscribe({ token, onRemoteStream }) API connects in receive-only mode.

Refactors realtime event buffering into a shared createEventBuffer, extends WebRTC signaling/types to handle session_id, and updates WebRTC connection/manager logic to support subscribe mode (recvonly audio/video transceivers, reconnection without a local stream, and more robust remote-stream handling).

Includes a new examples/tanstack-streamer TanStack Start app demonstrating producer webcam streaming + shareable viewer link, and adds unit tests covering token encoding/validation, subscribe-mode transceivers/reconnect, event buffering, and subscribeToken population. Also removes the SDK’s uuid dependency.

^{Written by Cursor Bugbot for commit be6ae66. 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@80

commit: be6ae66

[cursor]

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