@stream-io/video-client 1.52.0 → 1.53.0

package/dist/src/Call.d.ts

@@ -5,6 +5,7 @@ import type { AcceptCallResponse, BlockUserResponse, CallRingEvent, CallSettings
 import { AudioTrackType, CallConstructor, CallLeaveOptions, CallRecordingType, ClientPublishOptions, ClosedCaptionsSettings, JoinCallData, StartCallRecordingFnType, TrackMuteType, VideoTrackType } from './types';
 import { ClientCapability, TrackType, VideoDimension } from './gen/video/sfu/models/models';
 import { Tracer } from './stats';
+import type { ClientEventReporter } from './reporting';
 import { AudioBindingsWatchdog } from './helpers/AudioBindingsWatchdog';
 import { BlockedAudioTracker } from './helpers/BlockedAudioTracker';
 import { TrackSubscriptionManager } from './helpers/TrackSubscriptionManager';
@@ -107,6 +108,7 @@ export declare class Call {
     private dropTimeout;
     private readonly clientStore;
     readonly streamClient: StreamClient;
+    readonly clientEventReporter: ClientEventReporter;
     private sfuClient?;
     private sfuClientTag;
     private unifiedSessionId?;
@@ -152,7 +154,7 @@ export declare class Call {
      * Use the [`StreamVideoClient.call`](./StreamVideoClient.md/#call)
      * method to construct a `Call` instance.
      */
-    constructor({ type, id, streamClient, members, ownCapabilities, sortParticipantsBy, clientStore, ringing, watching, }: CallConstructor);
+    constructor({ type, id, streamClient, clientEventReporter, members, ownCapabilities, sortParticipantsBy, clientStore, ringing, watching, }: CallConstructor);
     /**
      * Sets up the call instance.
      *
@@ -836,6 +838,8 @@ export declare class Call {
      * @param trackType the kind of video.
      */
     bindVideoElement: (videoElement: HTMLVideoElement, sessionId: string, trackType: VideoTrackType) => (() => void) | undefined;
+    private bindFirstVideoFrameDetector;
+    private reportFirstRenderedVideoFrame;
     /**
      * Binds a DOM <audio> element to the given session id.
      *

package/dist/src/StreamVideoClient.d.ts

@@ -5,6 +5,7 @@ import type { ConnectedEvent, CreateDeviceRequest, CreateGuestRequest, CreateGue
 import { AllClientEvents, ClientEventListener, StreamClientOptions, TokenOrProvider, User } from './coordinator/connection/types';
 import type { StreamVideoClientOptions } from './types';
 import { ScopedLogger } from './logger';
+import { ClientEventReporter } from './reporting';
 /**
  * A `StreamVideoClient` instance lets you communicate with our API, and authenticate users.
  */
@@ -21,6 +22,7 @@ export declare class StreamVideoClient {
     readonly logger: ScopedLogger;
     protected readonly writeableStateStore: StreamVideoWriteableStateStore;
     streamClient: StreamClient;
+    readonly clientEventReporter: ClientEventReporter;
     private effectsRegistered;
     private eventHandlersToUnregister;
     private readonly connectionConcurrencyTag;

package/dist/src/coordinator/connection/client.d.ts

@@ -137,6 +137,7 @@ export declare class StreamClient {
      * @private
      */
     connect: () => Promise<ConnectedEvent | undefined>;
+    getSdkVersion: () => string;
     getUserAgent: () => string;
     _enrichAxiosOptions: (options?: AxiosRequestConfig & {
         config?: AxiosRequestConfig;

package/dist/src/errors/SfuTimeoutError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An error thrown when a client-side SFU deadline (e.g., waiting for the
+ * signaling WS to open or for the `joinResponse` to arrive) fires before
+ * the awaited operation resolves. Allows consumers (e.g., the client event
+ * reporter) to classify timeouts without relying on message wording.
+ */
+export declare class SfuTimeoutError extends Error {
+}

package/dist/src/errors/index.d.ts

@@ -1 +1,2 @@
 export * from './SfuJoinError';
+export * from './SfuTimeoutError';

package/dist/src/helpers/firstVideoFrame.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Invokes `onFirstFrame` once when the video element renders a frame.
+ *
+ * Uses `requestVideoFrameCallback` when available, falling back to `loadeddata`
+ * for browsers that don't support it.
+ */
+export declare const createFirstVideoFrameDetector: (videoElement: HTMLVideoElement, onFirstFrame: () => void) => () => void;

package/dist/src/reporting/ClientEventReporter.d.ts

@@ -0,0 +1,84 @@
+import { TrackType } from '../gen/video/sfu/models/models';
+import type { StreamClient } from '../coordinator/connection/client';
+import type { PeerConnectionStateChangeEvent } from '../rtc';
+export type ClientEventPeerConnection = 'publish' | 'subscribe';
+export type ClientEventStage = 'JoinInitiated' | 'CoordinatorWS' | 'MediaDevicePermission' | 'CoordinatorJoin' | 'WSJoin' | 'PeerConnectionConnect' | 'FirstVideoFrame' | 'FirstAudioFrame';
+export type MediaPermissionState = 'INITIATED' | 'FAILED' | 'GRANTED' | 'NOT_INITIATED';
+export type JoinReason = 'first-attempt' | 'network-available' | 'migration' | 'full-rejoin';
+export type ClientEventStandardCode = 'CLIENT_ABORTED' | 'BACKEND_LEAVE' | 'REQUEST_TIMEOUT' | 'NETWORK_ERROR' | 'SFU_ERROR' | 'SFU_GO_AWAY' | 'ICE_CONNECTIVITY_FAILED' | 'DTLS_CONNECTIVITY_FAILED';
+export type CallReportContext = {
+    callType: string;
+    callId: string;
+    getSfuId: () => string;
+    getCallSessionId: () => string;
+    getUserSessionId: () => string;
+};
+export type ClientEventReporterOptions = {
+    streamClient: StreamClient;
+};
+export declare class ClientEventReporter {
+    private readonly logger;
+    private streamClient;
+    private coordinatorConnectId?;
+    private coordinatorConnectUserId?;
+    private coordinatorWsPair?;
+    private callContexts;
+    private joinAttemptIds;
+    private joinReasons;
+    private coordinatorPairs;
+    private wsPairs;
+    private peerConnectionPairs;
+    private pcEverConnected;
+    private firstFrameReported;
+    constructor(options: ClientEventReporterOptions);
+    /**
+     * Starts a new coordinator connection correlation scope.
+     *
+     * @param userId the id of the user being connected. Captured here because
+     * the `CoordinatorWS` stage emits before the connection flow assigns
+     * the user to the client, so it can't be read from the client yet.
+     */
+    startCoordinatorConnection: (userId?: string) => string;
+    trackCoordinatorWs: <T>(op: () => Promise<T>) => Promise<T>;
+    private beginCoordinatorWs;
+    private succeedCoordinatorWs;
+    closeCoordinatorWs: () => void;
+    private buildCoordinatorWsCommon;
+    private emitMediaPermission;
+    registerCall: (cid: string, ctx: CallReportContext) => void;
+    unregisterCall: (cid: string) => void;
+    startCorrelation: (cid: string, joinReason: JoinReason) => void;
+    withJoinLifecycle: <T>(cid: string, joinReason: JoinReason, op: () => Promise<T>) => Promise<T>;
+    track: <T>(cid: string, stage: "CoordinatorJoin" | "WSJoin", op: () => Promise<T>) => Promise<T>;
+    reportFirstFrame: (cid: string, trackType: TrackType, trackId: string) => void;
+    captureWsError: (cid: string, opts: {
+        code: string;
+        reason: string;
+    }) => void;
+    close: (cid: string) => void;
+    abort: (cid: string, opts: {
+        code: "CLIENT_ABORTED" | "BACKEND_LEAVE";
+        reason: string;
+    }) => void;
+    private closeCallPairs;
+    private emitJoinInitiated;
+    private beginAttempt;
+    private succeedAttempt;
+    private applyStageError;
+    private beginCoordinatorAttempt;
+    private succeedCoordinator;
+    private failCoordinator;
+    private beginWsAttempt;
+    private succeedWs;
+    private failWs;
+    onPeerConnectionStateChange: (cid: string, event: PeerConnectionStateChangeEvent) => void;
+    private openPeerConnectionPair;
+    private emitPeerConnectionSuccess;
+    private emitPeerConnectionFailure;
+    private getSfuId;
+    private getUserSessionId;
+    private sessionIdField;
+    private buildCommon;
+    private send;
+    private sendWithRetry;
+}

package/dist/src/reporting/index.d.ts

@@ -0,0 +1 @@
+export * from './ClientEventReporter';

package/dist/src/rtc/BasePeerConnection.d.ts

@@ -5,7 +5,7 @@ import { PeerType, TrackType } from '../gen/video/sfu/models/models';
 import { StreamSfuClient } from '../StreamSfuClient';
 import { AllSfuEvents, Dispatcher } from './Dispatcher';
 import { StatsTracer, Tracer } from '../stats';
-import { BasePeerConnectionOpts } from './types';
+import { BasePeerConnectionOpts, OnRemoteTrackUnmute } from './types';
 import type { ClientPublishOptions } from '../types';
 /**
  * A base class for the `Publisher` and `Subscriber` classes.
@@ -22,6 +22,8 @@ export declare abstract class BasePeerConnection {
     protected sfuClient: StreamSfuClient;
     private onReconnectionNeeded?;
     private onIceConnected?;
+    private onPeerConnectionStateChange?;
+    protected onRemoteTrackUnmute?: OnRemoteTrackUnmute;
     private readonly iceRestartDelay;
     private iceHasEverConnected;
     private iceRestartTimeout?;
@@ -37,7 +39,7 @@ export declare abstract class BasePeerConnection {
     /**
      * Constructs a new `BasePeerConnection` instance.
      */
-    protected constructor(peerType: PeerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, onIceConnected, tag, enableTracing, clientPublishOptions, iceRestartDelay, statsTimestampDriftThresholdMs, }: BasePeerConnectionOpts);
+    protected constructor(peerType: PeerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, onIceConnected, onPeerConnectionStateChange, onRemoteTrackUnmute, tag, enableTracing, clientPublishOptions, iceRestartDelay, statsTimestampDriftThresholdMs, }: BasePeerConnectionOpts);
     private createPeerConnection;
     /**
      * Disposes the `RTCPeerConnection` instance.
@@ -116,6 +118,7 @@ export declare abstract class BasePeerConnection {
      * Handles the ICE connection state change event.
      */
     private onIceConnectionStateChange;
+    private fireOnPeerConnectionStateChange;
     private handleConnectionStateUpdate;
     /**
      * Handles the ICE candidate error event.

package/dist/src/rtc/types.d.ts

@@ -1,4 +1,4 @@
-import { AudioBitrateProfile, PeerType, PublishOption, WebsocketReconnectStrategy } from '../gen/video/sfu/models/models';
+import { AudioBitrateProfile, PeerType, PublishOption, TrackType, WebsocketReconnectStrategy } from '../gen/video/sfu/models/models';
 import { StreamSfuClient } from '../StreamSfuClient';
 import { CallState } from '../store';
 import { Dispatcher } from './Dispatcher';
@@ -37,6 +37,27 @@ export type OnReconnectionNeeded = (kind: WebsocketReconnectStrategy, reason: Re
  * recovered, not merely when the SFU join handshake succeeded.
  */
 export type OnIceConnected = (peerType: PeerType) => void;
+/**
+ * Snapshot of the peer connection's ICE and DTLS state surfaced to telemetry
+ * consumers (e.g. `ClientEventReporter`). Fired on every transition of
+ * either `iceConnectionState` or `peerConnectionState`.
+ */
+export type PeerConnectionStateChangeEvent = {
+    peerType: PeerType;
+    stateType: 'ice';
+    state: RTCIceConnectionState;
+} | {
+    peerType: PeerType;
+    stateType: 'peerConnection';
+    state: RTCPeerConnectionState;
+};
+export type OnPeerConnectionStateChange = (event: PeerConnectionStateChangeEvent) => void;
+/**
+ * Fired when a remote track starts receiving media (`unmute`). Used by
+ * telemetry to report the `FirstVideoFrame` / `FirstAudioFrame` stage; the
+ * consumer decides which track types are relevant.
+ */
+export type OnRemoteTrackUnmute = (trackType: TrackType, trackId: string) => void;
 export type BasePeerConnectionOpts = {
     sfuClient: StreamSfuClient;
     state: CallState;
@@ -44,6 +65,8 @@ export type BasePeerConnectionOpts = {
     dispatcher: Dispatcher;
     onReconnectionNeeded?: OnReconnectionNeeded;
     onIceConnected?: OnIceConnected;
+    onPeerConnectionStateChange?: OnPeerConnectionStateChange;
+    onRemoteTrackUnmute?: OnRemoteTrackUnmute;
     tag: string;
     enableTracing: boolean;
     iceRestartDelay?: number;

package/dist/src/types.d.ts

@@ -1,6 +1,7 @@
 import type { Participant, TrackType, VideoDimension } from './gen/video/sfu/models/models';
 import type { AudioSettingsRequestDefaultDeviceEnum, CallRecordingStartedEventRecordingTypeEnum, JoinCallRequest, MemberResponse, OwnCapability, ReactionResponse, StartRecordingRequest, StartRecordingResponse } from './gen/coordinator';
 import type { StreamClient } from './coordinator/connection/client';
+import type { ClientEventReporter } from './reporting';
 import type { RejectReason, StreamClientOptions, TokenProvider, User } from './coordinator/connection/types';
 import type { Comparator } from './sorting';
 import type { StreamVideoWriteableStateStore } from './store';
@@ -252,6 +253,10 @@ export type CallConstructor = {
      * The streamClient instance to use.
      */
     streamClient: StreamClient;
+    /**
+     * The shared client event reporter, owned by `StreamVideoClient`.
+     */
+    clientEventReporter: ClientEventReporter;
     /**
      * The Call type.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-client",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "browser": "dist/index.browser.es.js",