feat(realtime): add IVS transport support

[nagar-decart]

Summary

Add IVS (Interactive Video Service) as an alternative transport for real-time inference, alongside the existing WebRTC transport. Users select transport via transport: "ivs" option on realtime.connect().

New files

• ivs-connection.ts — Low-level IVS connection using AWS IVS Web Broadcast SDK (publish + subscribe stages)
• ivs-manager.ts — Manager with retry/reconnect logic (parallel to webrtc-manager.ts)
• transport-manager.ts — Shared interface implemented by both WebRTC and IVS managers

Modified files

• client.ts — transport?: "webrtc" | "ivs" option on connect, routes to appropriate manager
• methods.ts — Accept RealtimeTransportManager interface instead of WebRTCManager directly
• types.ts — Add IvsStageReadyMessage, IvsJoinedMessage message types
• diagnostics.ts — Add ivs-stage-setup connection phase
• webrtc-connection.ts / webrtc-manager.ts — Implement RealtimeTransportManager interface
• package.json — Add @aws/ivs-web-broadcast as optional peer dependency

Usage

const client = createDecartClient({ apiKey });
const rt = await client.realtime.connect(stream, {
  model: models.realtime("mirage_v2"),
  transport: "ivs", // defaults to "webrtc"
  onRemoteStream: (stream) => { video.srcObject = stream; },
});

IVS SDK can be loaded via npm (@aws/ivs-web-broadcast) or CDN script tag (falls back to globalThis.IVSBroadcastClient).

Test plan

• Existing WebRTC tests still pass (npm test)
• Type checking passes (npx tsc --noEmit)
• Manual test with IVS transport using demo page (index.html)

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new realtime transport path and refactors the connect/subscribe flow to route through transport managers, which can affect connection setup, error handling, and token compatibility. WebRTC remains default, but the new IVS dependency loading and stage setup introduces additional runtime paths to validate.

Overview
Adds IVS (AWS Interactive Video Service) as an alternative to WebRTC for realtime.connect(), controlled via a new transport: "webrtc" | "ivs" option (defaulting to WebRTC).

Introduces an IVS transport implementation (IVSConnection/IVSManager) with dynamic loading of @aws/ivs-web-broadcast, updates realtime methods to use a shared RealtimeTransportManager interface, and extends subscribe token encoding/decoding to carry the selected transport (plus an IVS subscribe path).

Updates the SDK test page and the React Vite example to allow selecting transport (including loading the IVS SDK from CDN in the test page), and marks @aws/ivs-web-broadcast as an optional peer dependency.

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

[cursor]

Race condition: ivs_stage_ready lost during SDK loading

High Severity

In setupIVSStages, await getIVSBroadcastClient() is called first (line 241), and only after it resolves is the addEventListener("message", handler) registered to listen for ivs_stage_ready (line 268). During SDK loading, ws.onmessage is already active and routes messages to handleMessage(), which silently drops ivs_stage_ready (it has no handler for it, as noted in the comment on line 388). If the server sends ivs_stage_ready before the SDK finishes loading, the message is consumed and lost, causing the connection to hang until the "IVS stage ready timeout" fires.

Additional Locations (1)

• packages/sdk/src/realtime/ivs-connection.ts#L345-L393

 

[cursor]

WebRTC error classifier misclassifies IVS transport errors

Medium Severity

The onError callback passes IVS transport errors through classifyWebrtcError, which maps unrecognized errors to WEBRTC_SIGNALING_ERROR by default. IVS-specific errors (e.g., from stage setup failures) have nothing to do with WebRTC signaling, producing misleading error codes that could confuse consumers relying on the code field for error handling logic.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[cursor]

Token validation rejects valid IVS subscribe tokens

High Severity

decodeSubscribeToken validates !payload.ip || !payload.port for all tokens, but IVS subscribe tokens don't need ip or port (only sid is used by subscribeIVS). If the IVS server sends server_port: 0 or server_ip: "" in its session_id message (reasonable since these WebRTC-specific fields are irrelevant for IVS), the truthiness check fails (!0 and !"" are both true), throwing "Invalid subscribe token" and completely breaking the IVS subscribe flow.

Additional Locations (1)

• packages/sdk/src/realtime/client.ts#L535-L543

 

[cursor]

Duplicated connection logic across IVS and WebRTC classes

Medium Severity

IVSConnection and WebRTCConnection contain near-identical implementations of setImageBase64, sendInitialPrompt, send, setState, and common handleMessage logic (error, prompt_ack, set_image_ack, generation_started, generation_tick, generation_ended, session_id handling). These are copied line-for-line with only the message type parameter differing. A shared base class or extracted utility functions would reduce the maintenance burden and risk of divergence during future bug fixes.

Additional Locations (1)

• packages/sdk/src/realtime/webrtc-connection.ts#L304-L388