@streaming-cdn/rtc-web 1.4.0 → 1.5.0

package/README.md

@@ -1,4 +1,4 @@
-# RTC Web SDK 1.3.28
+# RTC Web SDK 1.5.0
 
 The customer package contains compiled ESM/UMD JavaScript and TypeScript declarations. It intentionally excludes implementation source and source maps. Example source remains available under `examples/`.
 
@@ -140,7 +140,65 @@ origin. In practice:
 so existing integrations keep working.
 
 
-For outgoing UI, show `contacting` while mobile push is being delivered, move to `ringing` on `call.delivery`, and show `connected` only after both `call.updated: accepted` and the media client's `connected` event. Do not call `join()` before acceptance. Cancel unanswered calls at the invitation `expiresAt` timestamp (45 seconds by default).
+For outgoing UI, show `contacting` while mobile push is being delivered, move to `ringing` on `call.delivery`, and show `connected` only after `call.updated: accepted` **and the media client's `mediaconnected` event**. The media client's `connected` event means the signaling room was joined — it says nothing about media; a call marked connected on it can have zero media flowing. Do not call `join()` before acceptance. Cancel unanswered calls at the invitation `expiresAt` timestamp (45 seconds by default).
+
+## Connect phase: what fires when, and how long to wait
+
+`join()` resolves when the signaling room accepts this participant. Media
+comes up afterwards, and the media client narrates every step of it:
+
+| Event | Detail | Meaning |
+| --- | --- | --- |
+| `connected` | `{ participantId, resumed }` | Signaling room joined. **Not** media. |
+| `participantjoined` | participant, plus `initial: true` for peers that were already in the room when you joined | The other side is in the room. This is the moment to anchor your connect budget. |
+| `negotiation` | `{ participantId, phase, at }` — `at` is ms since `join()` | One negotiation step: `offer-created`, `offer-sent`, `offer-received`, `answer-created`, `answer-sent`, `answer-received`, `remote-description-set`, `ice-gathering-complete`, `ice-candidate-sent`, `ice-candidate-received`. Never SDP or candidate bodies. |
+| `icestate` | `{ participantId, state }` | `iceConnectionState` changed (`peerconnectionstate` carries `connectionState`). |
+| `mediaconnected` | `{ participantId, elapsedMs, first }` | Media reached this peer — its connection became `connected` or its first remote track arrived, whichever came first. Once per peer; `first` is true for the first peer of the session. **This is "call connected".** |
+| `connecttimeout` | `{ elapsedMs, peers: [{ participantId, connectionState, iceState, signalingState, lastNegotiationPhase }], participantCount }` | `connectTimeoutMs` (default 30 000; `0` disables) elapsed after `join()` with no `mediaconnected`. Fired once. The client does **not** leave — decide that yourself. |
+| `signalingerror` | `{ code: "send_dropped", messageType }` | A signaling frame was dropped because the socket was not open. Reconnect rebuilds every peer; the loss is reported, never thrown. |
+
+On the SFU transport, negotiation is with the platform SFU, so `negotiation`,
+`icestate` and `peerconnectionstate` are attributed to your own participant
+id. `mediaconnected` fires for your own id once the SFU connection is up
+(that is the `first` one), then per remote participant as their tracks
+arrive.
+
+`getConnectPhase()` returns `{ joinedAt, mediaConnected, mediaConnectedElapsedMs, timedOut, lastConnectTimeout }`
+for code that attaches late.
+
+### The staged connect budget
+
+Measured on the platform (2026-09): a call that connects does so within a
+few seconds of both sides being in the room, but *getting* both sides into
+the room takes as long as the slower device's ring, wake and accept. The
+budget is therefore staged, and **the timer for negotiation starts when the
+other side is in the room (`participantCount === 2` in `stats`, or
+`participantjoined`), not at `join()`**:
+
+| Stage | Budget | Signal that ends it |
+| --- | --- | --- |
+| Join the signaling room | 20 s | `connected` (or `join()` rejects) |
+| Wait for the other side to arrive | **at least 20 s, without hanging up** | `participantjoined` / `participantCount === 2` |
+| Negotiation | 15 s from that moment | `mediaconnected` |
+| Give up | **no earlier than 45 s after `join()`** | `connecttimeout`, or your own timer |
+
+A callee who joined first spends the "wait for the other side" stage
+watching the caller's `accepted` notification travel; a caller whose callee
+was woken by push spends it watching the ring. Neither is a negotiation
+failure. Set `connectTimeoutMs` at or above 45 000 unless your product has
+its own staging, and treat `connecttimeout` as the diagnostic it is: its
+`peers` snapshot says whether the other side never arrived
+(`peers: []`), arrived and never answered (`lastNegotiationPhase:
+"offer-sent"`), or exchanged descriptions and never found a route
+(`iceState: "checking"` after `remote-description-set`).
+
+The incoming-call client follows the same rule: `attachMediaClient()` no
+longer disarms its call watchdog. The watchdog is disarmed by the media
+client's `mediaconnected`; if that never comes, `callexpired` fires and the
+call is released, media client included. The media client's join, media
+establishment and connect timeout are also reported to the platform
+through the existing bounded diagnostics channel (the same one that
+carries signaling outages; no SDP, media, tokens or chat).
 
 ## Complete managed integration
 
@@ -357,6 +415,48 @@ operational diagnostics. Tokens, SDP, media, and chat content are never part of
 that report. Set `reportSignalingDiagnostics: false` only when replacing this
 with an application-owned diagnostics pipeline.
 
+## 1.5.0 notes
+
+New events and one option on the media client; nothing existing changes shape.
+
+- **`mediaconnected` is the "call connected" signal.** `connected` was
+  documented as it, and it only ever meant the signaling room was joined.
+  Two calls on 2026-09-11 were marked connected with no media; the docs
+  were the defect.
+- **`negotiation`, `icestate`** narrate the connect phase step by step —
+  message types and timing only, never SDP or candidate bodies.
+- **`connectTimeoutMs`** (default 30 000; `0` disables) and the
+  **`connecttimeout`** event, which lists every peer's connection, ICE and
+  signaling state plus the last negotiation phase. The client does not
+  leave on its own.
+- **`participantjoined` fires for peers already in the room**, marked
+  `initial: true`. The later arrival used to get no notice at all that
+  the other side was there.
+- **`signalingerror { code: "send_dropped" }`** when a signaling frame is
+  dropped because the socket is not open. Still no throw.
+- **The final quality sample is taken from a snapshot made before any
+  connection is closed**, so it describes the call rather than the
+  teardown; a final sample that lands on a running runtime sample now
+  waits its turn instead of being skipped. Samples also carry `statsTransport`,
+  `statsConnectionCount`, `statsRowCount` and `statsRowTypes`.
+- **`attachMediaClient()` keeps the call watchdog armed** until the media
+  client reports `mediaconnected`. Attaching happened exactly when the
+  unguarded media phase began, so attaching used to end the only watch.
+  Media join, media establishment and connect timeout are reported to the
+  platform through the existing diagnostics channel, with the call id.
+- **Staged connect budget published** above: join 20 s, wait for the other
+  side at least 20 s without hanging up, negotiation 15 s, give up no
+  earlier than 45 s — anchored at the moment the other side is in the room.
+
+## 1.4.0 notes
+
+- **Call-slot hardening ported from React Native.** Every path that could
+  leave a call id in the active set for the life of the page — hang-up
+  failing on the server, an unanswered outgoing call, an accepted call
+  whose media never came up, the `accepted` broadcast reaching a session
+  holding no media, a `startCall` in flight across `disconnect()` — now
+  releases the slot, so the next call always works.
+
 ## 1.3.28 notes
 
 - **The idle pose measures which way is down.** 1.3.27 lowered the arms out

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type NativeRoomNegotiationPhase } from "./native-room";
 export { createPictureInPictureController } from "./picture-in-picture";
 export type { PictureInPictureController, PictureInPictureOptions } from "./picture-in-picture";
 export { pickActiveSpeaker, SPEAKER_NOISE_FLOOR, SPEAKER_TAKEOVER_RATIO } from "./active-speaker";
@@ -26,6 +27,65 @@ export type RtcQuality = "auto" | "audio" | "low" | "medium" | "high";
 export type RtcVideoCodec = "auto" | "vp8" | "h264";
 export type RtcIceTransportPolicy = "all" | "relay";
 export type RtcConnectionState = "initialized" | "joining" | "connected" | "reconnecting" | "disconnected" | "failed";
+/**
+ * Default for `connectTimeoutMs`: how long after `join()` the client waits for
+ * the first peer to reach media before emitting `connecttimeout`. It only
+ * reports — the client never leaves on its own.
+ */
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
+export type RtcNegotiationPhase = NativeRoomNegotiationPhase;
+/** `negotiation` event: one step of a peer's media negotiation, `at` ms after `join()`. Never SDP or candidate bodies. */
+export interface RtcNegotiationEvent {
+    participantId: string;
+    phase: RtcNegotiationPhase;
+    at: number;
+}
+/** `icestate` event: a peer connection's `iceConnectionState` changed. */
+export interface RtcIceStateEvent {
+    participantId: string;
+    state: string;
+}
+/**
+ * `mediaconnected` event: media reached this peer — its connection became
+ * `connected` or its first remote track arrived, whichever came first. Fired
+ * once per peer; `first` is true only for the first peer of the session.
+ */
+export interface RtcMediaConnectedEvent {
+    participantId: string;
+    elapsedMs: number;
+    first: boolean;
+}
+export interface RtcConnectTimeoutPeer {
+    participantId: string;
+    connectionState: string;
+    iceState: string;
+    signalingState: string;
+    lastNegotiationPhase: RtcNegotiationPhase | null;
+}
+/**
+ * `connecttimeout` event: `connectTimeoutMs` elapsed after `join()` with no
+ * `mediaconnected`. Says what state every peer was in so the failure is
+ * diagnosable from the event alone. Fired at most once per session.
+ */
+export interface RtcConnectTimeoutEvent {
+    elapsedMs: number;
+    peers: RtcConnectTimeoutPeer[];
+    participantCount: number;
+}
+/** `signalingerror` detail when a signaling frame was dropped because the socket was not open. */
+export interface RtcSignalingDropEvent {
+    code: "send_dropped";
+    messageType: string;
+}
+/** Where this session stands between `join()` and media, for integrators that attach late. */
+export interface RtcConnectPhase {
+    joinedAt: string | null;
+    mediaConnected: boolean;
+    mediaConnectedElapsedMs: number | null;
+    timedOut: boolean;
+    /** The `connecttimeout` payload once it has fired; null otherwise. */
+    lastConnectTimeout: RtcConnectTimeoutEvent | null;
+}
 export interface RtcCredential {
     signalingToken: string;
     signalingUrl: string;
@@ -71,6 +131,13 @@ export interface RtcClientOptions {
     /** Enables automatic quality changes when quality is "auto". */
     adaptiveQuality?: boolean;
     autoJoin?: boolean;
+    /**
+     * Milliseconds after `join()` before `connecttimeout` is emitted when no
+     * peer has reached media. Defaults to 30 000; `0` disables. Anchor your own
+     * budget at the moment the other side is in the room, not at `join()`: a
+     * callee who joined first waits here for the caller through the whole ring.
+     */
+    connectTimeoutMs?: number;
     statsInterval?: number;
     telemetryInterval?: number;
     autoReportStats?: boolean;
@@ -128,6 +195,16 @@ export interface RtcQualitySample {
     qualityLimitationReason: string | null;
     deviceMemoryGb: number | null;
     effectiveConnectionType: string | null;
+    /**
+     * Collection diagnostics (S5): which transport was sampled, how many peer
+     * connections existed, and what `getStats()` actually returned — so a
+     * sample whose derived fields are null still says whether there was
+     * nothing to measure or nothing measurable.
+     */
+    statsTransport: "mesh" | "sfu" | null;
+    statsConnectionCount: number | null;
+    statsRowCount: number | null;
+    statsRowTypes: string | null;
 }
 export interface RtcStats {
     state: RtcConnectionState;
@@ -169,7 +246,7 @@ export declare class RtcClient extends EventTarget {
     private latestMediaScore;
     private latestQuality;
     private statsTimer;
-    private statsRunning;
+    private statsTask;
     private previousCounters;
     private lastTelemetryAt;
     private joinPromise;
@@ -177,10 +254,20 @@ export declare class RtcClient extends EventTarget {
     private effectiveQuality;
     private poorQualitySamples;
     private goodQualitySamples;
+    private transport;
+    private joinStartedAt;
+    private connectTimer;
+    private connectTimedOut;
+    private lastConnectTimeout;
+    private readonly mediaConnectedPeers;
+    private firstMediaConnectedElapsedMs;
+    private readonly lastNegotiationPhase;
     constructor(options: RtcClientOptions);
     initialize(): Promise<this>;
     join(): Promise<void>;
     leave(): Promise<void>;
+    /** Where the session stands between `join()` and media. Lets a late `attachMediaClient` catch up. */
+    getConnectPhase(): RtcConnectPhase;
     setMuted(muted: boolean): Promise<void>;
     setCameraEnabled(enabled: boolean): Promise<void>;
     setVideoTrack(track: MediaStreamTrack): Promise<void>;
@@ -214,13 +301,22 @@ export declare class RtcClient extends EventTarget {
         requestMedia?: boolean;
         probeUrl?: string;
     }): Promise<RtcPreflightResult>;
-    collectQualitySample(sampleType?: RtcQualitySample["sampleType"]): Promise<RtcQualitySample>;
+    /**
+     * `connectionState` names the state to report instead of reading it from the
+     * connection — `leave()` passes the snapshot it took before closing anything.
+     */
+    collectQualitySample(sampleType?: RtcQualitySample["sampleType"], connectionState?: string): Promise<RtcQualitySample>;
     reportQuality(sample: Partial<RtcQualitySample>): Promise<void>;
     getStats(): RtcStats;
     /** Escape hatch for advanced integrations. Prefer the stable SDK methods when possible. */
     getNativeClient<T = unknown>(): T | null;
     destroy(): void;
     private handleNativeEvent;
+    private elapsedSinceJoin;
+    /** Fires `mediaconnected` once per peer, and disarms the connect watchdog on the first. */
+    private markMediaConnected;
+    private armConnectTimeout;
+    private clearConnectTimeout;
     private startStats;
     private sampleAndReport;
     private stopStats;
@@ -320,6 +416,7 @@ export declare class RtcIncomingClient extends EventTarget {
     private currentTokenExpiresAt?;
     private readonly callAudio;
     private readonly mediaClients;
+    private readonly mediaSubscriptions;
     private readonly activeCallIds;
     private readonly seenInvitationIds;
     private readonly invitationExpiryTimers;
@@ -330,8 +427,17 @@ export declare class RtcIncomingClient extends EventTarget {
     constructor(options: RtcIncomingClientOptions);
     connect(): this;
     setMount(target: HTMLElement | string | null): void;
-    /** Binds media lifetime to a call. Terminal call states automatically leave and destroy it. */
+    /**
+     * Binds media lifetime to a call. Terminal call states automatically leave
+     * and destroy it. The call watchdog keeps running until the media client
+     * reports `mediaconnected`; if it expires first, `callexpired` fires and the
+     * call — media included — is released. The media client's join, media
+     * establishment and connect timeout are reported to the platform through
+     * the same bounded diagnostics channel as signaling outages.
+     */
     attachMediaClient(callId: string, media: RtcClient): () => void;
+    /** True once the media client bound to this call has reached media on at least one peer. */
+    private mediaEstablished;
     /**
      * Arms the self-release timer for a call that holds the single call slot but
      * has no media attached. Every path that claims the slot arms this, so no
@@ -403,4 +509,4 @@ export declare class RtcIncomingClient extends EventTarget {
     private emit;
 }
 export declare function createRtcIncomingClient(options: RtcIncomingClientOptions): RtcIncomingClient;
-export declare const version = "1.4.0";
+export declare const version = "1.5.0";

package/dist/native-room.d.ts

@@ -30,6 +30,21 @@ export interface NativeRoomOptions {
 }
 export type NativeRoomQuality = "audio" | "low" | "medium" | "high";
 export type NativeRoomVideoCodec = "auto" | "vp8" | "h264";
+/**
+ * One step of a peer's media negotiation, as seen from this side. Emitted as
+ * `negotiation` with the peer's participant id; never the SDP or a candidate
+ * body. The phases are the same on the React Native adapter.
+ */
+export type NativeRoomNegotiationPhase = "offer-created" | "offer-sent" | "offer-received" | "answer-created" | "answer-sent" | "answer-received" | "remote-description-set" | "ice-gathering-complete" | "ice-candidate-sent" | "ice-candidate-received";
+/** Snapshot of one connection's state machines, for diagnostics. */
+export interface NativeRoomPeerState {
+    participantId: string;
+    connectionState: string;
+    iceState: string;
+    signalingState: string;
+}
+declare function peerStateOf(participantId: string, connection: RTCPeerConnection): NativeRoomPeerState;
+export { peerStateOf as readPeerState };
 export declare class NativeRoomClient {
     private readonly options;
     private socket;
@@ -71,12 +86,15 @@ export declare class NativeRoomClient {
         stream: MediaStream;
     }>;
     getPrimaryPeerConnection(): RTCPeerConnection | null;
+    /** Every peer connection's state machines at this instant, one entry per remote participant. */
+    getPeerStates(): NativeRoomPeerState[];
     sendChat(message: string, participantIds?: string[]): void;
     sendControl(action: string, detail?: Record<string, unknown>): void;
     private connect;
     private openSocket;
     private handleSignal;
     private ensurePeer;
+    private negotiation;
     private createOffer;
     private performOffer;
     private shouldInitiateOffer;