@stream-io/video-client 1.52.0 → 1.53.0

package/dist/index.cjs.js

@@ -6660,7 +6660,7 @@ const getSdkVersion = (sdk) => {
     return sdk ? `${sdk.major}.${sdk.minor}.${sdk.patch}` : '0.0.0-development';
 };
 
-const version = "1.52.0";
+const version = "1.53.0";
 const [major, minor, patch] = version.split('.');
 let sdkInfo = {
     type: SdkType.PLAIN_JAVASCRIPT,
@@ -7754,7 +7754,7 @@ class BasePeerConnection {
     /**
      * Constructs a new `BasePeerConnection` instance.
      */
-    constructor(peerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, onIceConnected, tag, enableTracing, clientPublishOptions, iceRestartDelay = 2500, statsTimestampDriftThresholdMs = 0, }) {
+    constructor(peerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, onIceConnected, onPeerConnectionStateChange, onRemoteTrackUnmute, tag, enableTracing, clientPublishOptions, iceRestartDelay = 2500, statsTimestampDriftThresholdMs = 0, }) {
         this.iceHasEverConnected = false;
         this.isIceRestarting = false;
         this.isDisposed = false;
@@ -7908,6 +7908,10 @@ class BasePeerConnection {
         this.onConnectionStateChange = async () => {
             const state = this.pc.connectionState;
             this.logger.debug(`Connection state changed`, state);
+            this.fireOnPeerConnectionStateChange({
+                stateType: 'peerConnection',
+                state,
+            });
             if (this.tracer && (state === 'connected' || state === 'failed')) {
                 try {
                     const stats = await this.stats.get();
@@ -7930,8 +7934,20 @@ class BasePeerConnection {
         this.onIceConnectionStateChange = () => {
             const state = this.pc.iceConnectionState;
             this.logger.debug(`ICE connection state changed`, state);
+            this.fireOnPeerConnectionStateChange({ stateType: 'ice', state });
             this.handleConnectionStateUpdate(state);
         };
+        this.fireOnPeerConnectionStateChange = (event) => {
+            try {
+                this.onPeerConnectionStateChange?.({
+                    peerType: this.peerType,
+                    ...event,
+                });
+            }
+            catch (err) {
+                this.logger.warn('onPeerConnectionStateChange listener threw', err);
+            }
+        };
         this.handleConnectionStateUpdate = (state) => {
             const { callingState } = this.state;
             if (callingState === exports.CallingState.OFFLINE)
@@ -8046,6 +8062,8 @@ class BasePeerConnection {
         this.tag = tag;
         this.onReconnectionNeeded = onReconnectionNeeded;
         this.onIceConnected = onIceConnected;
+        this.onPeerConnectionStateChange = onPeerConnectionStateChange;
+        this.onRemoteTrackUnmute = onRemoteTrackUnmute;
         this.logger = videoLoggerSystem.getLogger(peerType === PeerType.SUBSCRIBER ? 'Subscriber' : 'Publisher', { tags: [tag] });
         this.pc = this.createPeerConnection(connectionConfig);
         this.stats = new StatsTracer(this.pc, peerType, this.trackIdToTrackType, statsTimestampDriftThresholdMs);
@@ -8068,6 +8086,8 @@ class BasePeerConnection {
         this.preConnectStuckTimeout = undefined;
         this.onReconnectionNeeded = undefined;
         this.onIceConnected = undefined;
+        this.onPeerConnectionStateChange = undefined;
+        this.onRemoteTrackUnmute = undefined;
         this.isDisposed = true;
         this.detachEventHandlers();
         this.pc.close();
@@ -9057,6 +9077,7 @@ class Subscriber extends BasePeerConnection {
             track.addEventListener('unmute', () => {
                 this.logger.info(`[onTrack]: Track unmuted: ${trackDebugInfo}`);
                 this.setRemoteTrackInterrupted(trackId, trackType, false);
+                this.onRemoteTrackUnmute?.(trackType, track.id);
             });
             track.addEventListener('ended', () => {
                 this.logger.info(`[onTrack]: Track ended: ${trackDebugInfo}`);
@@ -9296,6 +9317,15 @@ class SfuJoinError extends Error {
     }
 }
 
+/**
+ * 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.
+ */
+class SfuTimeoutError extends Error {
+}
+
 /**
  * Creates a fresh `joinResponseTask` with a no-op rejection handler attached
  * to the underlying promise. The handler marks the rejection path as handled
@@ -9401,7 +9431,7 @@ class StreamSfuClient {
                     timeoutId = setTimeout(() => {
                         const message = `SFU WS connection failed to open after ${this.joinResponseTimeout}ms`;
                         this.tracer?.trace('signal.timeout', message);
-                        reject(new Error(message));
+                        reject(new SfuTimeoutError(message));
                     }, this.joinResponseTimeout);
                 }),
             ]));
@@ -9571,7 +9601,7 @@ class StreamSfuClient {
                 cleanupJoinSubscriptions();
                 const message = `Waiting for "joinResponse" has timed out after ${this.joinResponseTimeout}ms`;
                 this.tracer?.trace('joinRequestTimeout', message);
-                current.reject(new Error(message));
+                current.reject(new SfuTimeoutError(message));
             }, this.joinResponseTimeout);
             const joinRequest = SfuRequest.create({
                 requestPayload: {
@@ -9788,6 +9818,10 @@ const watchCallEnded = (call) => {
         const { callingState } = call.state;
         if (callingState !== exports.CallingState.IDLE &&
             callingState !== exports.CallingState.LEFT) {
+            call.clientEventReporter.abort(call.cid, {
+                code: 'BACKEND_LEAVE',
+                reason: 'call.ended event received',
+            });
             call
                 .leave({ message: 'call.ended event received', reject: false })
                 .catch((err) => {
@@ -9817,6 +9851,10 @@ const watchSfuCallEnded = (call) => {
             call.state.setEndedAt(new Date());
             const reason = CallEndedReason[e.reason];
             globalThis.streamRNVideoSDK?.callingX?.endCall(call, 'remote');
+            call.clientEventReporter.abort(call.cid, {
+                code: 'BACKEND_LEAVE',
+                reason: `callEnded received: ${reason}`,
+            });
             await call.leave({ message: `callEnded received: ${reason}` });
         }
         catch (err) {
@@ -10969,6 +11007,40 @@ class DynascaleManager {
     }
 }
 
+/**
+ * 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.
+ */
+const createFirstVideoFrameDetector = (videoElement, onFirstFrame) => {
+    let done = false;
+    const notify = () => {
+        if (done)
+            return;
+        done = true;
+        onFirstFrame();
+    };
+    if (typeof videoElement.requestVideoFrameCallback === 'function') {
+        const handle = videoElement.requestVideoFrameCallback(notify);
+        return () => {
+            done = true;
+            videoElement.cancelVideoFrameCallback(handle);
+        };
+    }
+    if (videoElement.readyState >= videoElement.HAVE_CURRENT_DATA) {
+        queueMicrotask(notify);
+        return () => {
+            done = true;
+        };
+    }
+    videoElement.addEventListener('loadeddata', notify, { once: true });
+    return () => {
+        done = true;
+        videoElement.removeEventListener('loadeddata', notify);
+    };
+};
+
 const DEFAULT_THRESHOLD = 0.35;
 const DEFAULT_VIEWPORT_VISIBILITY_STATE = {
     videoTrack: exports.VisibilityState.UNKNOWN,
@@ -13812,7 +13884,7 @@ class Call {
      * Use the [`StreamVideoClient.call`](./StreamVideoClient.md/#call)
      * method to construct a `Call` instance.
      */
-    constructor({ type, id, streamClient, members, ownCapabilities, sortParticipantsBy, clientStore, ringing = false, watching = false, }) {
+    constructor({ type, id, streamClient, clientEventReporter, members, ownCapabilities, sortParticipantsBy, clientStore, ringing = false, watching = false, }) {
         /**
          * The state of this call.
          */
@@ -14139,9 +14211,14 @@ class Call {
                 this.sfuStatsReporter = undefined;
                 this.lastStatsOptions = undefined;
                 await this.subscriber?.dispose();
+                this.clientEventReporter.abort(this.cid, {
+                    code: 'CLIENT_ABORTED',
+                    reason: leaveReason,
+                });
                 this.subscriber = undefined;
                 await this.publisher?.dispose();
                 this.publisher = undefined;
+                this.clientEventReporter.unregisterCall(this.cid);
                 await this.sfuClient?.leaveAndClose(leaveReason);
                 this.sfuClient = undefined;
                 this.trackSubscriptionManager.setSfuClient(undefined);
@@ -14353,6 +14430,13 @@ class Call {
                 await callingX.joinCall(this, this.clientStore.calls);
             }
             await this.setup();
+            this.clientEventReporter.registerCall(this.cid, {
+                callType: this.type,
+                callId: this.id,
+                getCallSessionId: () => this.state.session?.id ?? '',
+                getSfuId: () => this.credentials?.server.edge_name ?? '',
+                getUserSessionId: () => this.sfuClient?.sessionId ?? '',
+            });
             this.joinResponseTimeout = joinResponseTimeout;
             this.rpcRequestTimeout = rpcRequestTimeout;
             // we will count the number of join failures per SFU.
@@ -14362,39 +14446,42 @@ class Call {
             const joinData = data;
             maxJoinRetries = Math.max(maxJoinRetries, 1);
             try {
-                for (let attempt = 0; attempt < maxJoinRetries; attempt++) {
-                    try {
-                        this.logger.trace(`Joining call (${attempt})`, this.cid);
-                        await this.doJoin(data);
-                        delete joinData.migrating_from;
-                        delete joinData.migrating_from_list;
-                        break;
-                    }
-                    catch (err) {
-                        this.logger.warn(`Failed to join call (${attempt})`, this.cid);
-                        if ((err instanceof ErrorFromResponse && err.unrecoverable) ||
-                            (err instanceof SfuJoinError && err.unrecoverable)) {
-                            // if the error is unrecoverable, we should not retry as that signals
-                            // that connectivity is good, but the coordinator doesn't allow the user
-                            // to join the call due to some reason (e.g., ended call, expired token...)
-                            throw err;
-                        }
-                        // immediately switch to a different SFU in case of recoverable join error
-                        const switchSfu = err instanceof SfuJoinError &&
-                            SfuJoinError.isJoinErrorCode(err.errorEvent);
-                        const sfuId = this.credentials?.server.edge_name || '';
-                        const failures = (sfuJoinFailures.get(sfuId) || 0) + 1;
-                        sfuJoinFailures.set(sfuId, failures);
-                        if (switchSfu || failures >= 2) {
-                            joinData.migrating_from = sfuId;
-                            joinData.migrating_from_list = Array.from(sfuJoinFailures.keys());
+                await this.clientEventReporter.withJoinLifecycle(this.cid, 'first-attempt', async () => {
+                    for (let attempt = 0; attempt < maxJoinRetries; attempt++) {
+                        try {
+                            this.logger.trace(`Joining call (${attempt})`, this.cid);
+                            await this.doJoin(data);
+                            delete joinData.migrating_from;
+                            delete joinData.migrating_from_list;
+                            return;
                         }
-                        if (attempt === maxJoinRetries - 1) {
-                            throw err;
+                        catch (err) {
+                            this.logger.warn(`Failed to join call (${attempt})`, this.cid);
+                            if ((err instanceof ErrorFromResponse && err.unrecoverable) ||
+                                (err instanceof SfuJoinError && err.unrecoverable)) {
+                                throw err;
+                            }
+                            const switchSfu = err instanceof SfuJoinError &&
+                                SfuJoinError.isJoinErrorCode(err.errorEvent);
+                            const sfuId = this.credentials?.server.edge_name;
+                            if (sfuId) {
+                                const failures = (sfuJoinFailures.get(sfuId) || 0) + 1;
+                                sfuJoinFailures.set(sfuId, failures);
+                                if (switchSfu || failures >= 2) {
+                                    joinData.migrating_from = sfuId;
+                                    joinData.migrating_from_list = Array.from(sfuJoinFailures.keys());
+                                    if (attempt < maxJoinRetries - 1) {
+                                        this.clientEventReporter.startCorrelation(this.cid, 'first-attempt');
+                                    }
+                                }
+                            }
+                            if (attempt === maxJoinRetries - 1) {
+                                throw err;
+                            }
                         }
+                        await sleep(retryInterval(attempt));
                     }
-                    await sleep(retryInterval(attempt));
-                }
+                });
             }
             catch (error) {
                 callingX?.endCall(this, 'error');
@@ -14423,7 +14510,7 @@ class Call {
                 performingMigration ||
                 data?.migrating_from) {
                 try {
-                    const joinResponse = await this.doJoinRequest(data);
+                    const joinResponse = await this.clientEventReporter.track(this.cid, 'CoordinatorJoin', () => this.doJoinRequest(data));
                     this.credentials = joinResponse.credentials;
                     statsOptions = joinResponse.stats_options;
                     this.lastStatsOptions = statsOptions;
@@ -14481,9 +14568,11 @@ class Call {
                 const preferredSubscribeOptions = !isReconnecting
                     ? this.getPreferredSubscribeOptions()
                     : [];
+                const unifiedSessionId = this.unifiedSessionId;
+                const capabilities = Array.from(this.clientCapabilities);
                 try {
-                    const { callState, fastReconnectDeadlineSeconds, publishOptions } = await sfuClient.join({
-                        unifiedSessionId: this.unifiedSessionId,
+                    const { callState, fastReconnectDeadlineSeconds, publishOptions } = await this.clientEventReporter.track(this.cid, 'WSJoin', () => sfuClient.join({
+                        unifiedSessionId,
                         subscriberSdp,
                         publisherSdp,
                         clientDetails,
@@ -14491,9 +14580,9 @@ class Call {
                         reconnectDetails,
                         preferredPublishOptions,
                         preferredSubscribeOptions,
-                        capabilities: Array.from(this.clientCapabilities),
+                        capabilities,
                         source: ParticipantSource.WEBRTC_UNSPECIFIED,
-                    });
+                    }));
                     this.currentPublishOptions = publishOptions;
                     this.fastReconnectDeadlineSeconds = fastReconnectDeadlineSeconds;
                     if (callState) {
@@ -14705,6 +14794,16 @@ class Call {
                     // "ICE never connected" failure budget can be cleared.
                     this.iceFailuresWithoutConnect = 0;
                 },
+                onPeerConnectionStateChange: (event) => {
+                    this.clientEventReporter.onPeerConnectionStateChange(this.cid, event);
+                },
+                onRemoteTrackUnmute: (trackType, trackId) => {
+                    const reportable = trackType === TrackType.AUDIO ||
+                        (isReactNative() && trackType === TrackType.VIDEO);
+                    if (!reportable)
+                        return;
+                    this.clientEventReporter.reportFirstFrame(this.cid, trackType, trackId);
+                },
             };
             this.subscriber = new Subscriber(basePeerConnectionOptions);
             // anonymous users can't publish anything hence, there is no need
@@ -14981,7 +15080,10 @@ class Call {
             const reconnectStartTime = Date.now();
             this.reconnectStrategy = WebsocketReconnectStrategy.REJOIN;
             this.state.setCallingState(exports.CallingState.RECONNECTING);
-            await this.doJoin(this.joinCallData);
+            const joinReason = this.reconnectReason === ReconnectReason.NETWORK_BACK_ONLINE
+                ? 'network-available'
+                : 'full-rejoin';
+            await this.clientEventReporter.withJoinLifecycle(this.cid, joinReason, () => this.doJoin(this.joinCallData));
             await this.restorePublishedTracks();
             this.restoreSubscribedTracks();
             this.sfuStatsReporter?.sendReconnectionTime(WebsocketReconnectStrategy.REJOIN, (Date.now() - reconnectStartTime) / 1000);
@@ -15005,11 +15107,11 @@ class Call {
             const migrationTask = makeSafePromise(currentSfuClient.enterMigration());
             try {
                 const currentSfu = currentSfuClient.edgeName;
-                await this.doJoin({
+                await this.clientEventReporter.withJoinLifecycle(this.cid, 'migration', () => this.doJoin({
                     ...this.joinCallData,
                     migrating_from: currentSfu,
                     migrating_from_list: [currentSfu],
-                });
+                }));
             }
             finally {
                 // cleanup the migration_from field after the migration is complete or failed
@@ -15045,11 +15147,22 @@ class Call {
         this.registerReconnectHandlers = () => {
             // handles the legacy "goAway" event
             const unregisterGoAway = this.on('goAway', () => {
+                this.clientEventReporter.captureWsError(this.cid, {
+                    code: 'SFU_GO_AWAY',
+                    reason: 'SFU goAway received during WS join',
+                });
                 this.reconnect(WebsocketReconnectStrategy.MIGRATE, ReconnectReason.GO_AWAY).catch((err) => this.logger.warn('[Reconnect] Error reconnecting', err));
             });
             // handles the "error" event, through which the SFU can request a reconnect
             const unregisterOnError = this.on('error', (e) => {
                 const { reconnectStrategy: strategy, error } = e;
+                if (!SfuJoinError.isJoinErrorCode(e)) {
+                    const code = error?.code ? ErrorCode[error.code] : undefined;
+                    this.clientEventReporter.captureWsError(this.cid, {
+                        code: code ?? 'SFU_ERROR',
+                        reason: error?.message || 'SFU error during WS join',
+                    });
+                }
                 // SFU_FULL is a join error, and when emitted, although it specifies a
                 // `migrate` strategy, we should actually perform a REJOIN to a new SFU.
                 // This is now handled separately in the `call.join()` method.
@@ -15744,7 +15857,9 @@ class Call {
                 this.leave({
                     reject: true,
                     reason: 'timeout',
-                    message: `ringing timeout - ${this.isCreatedByMe ? 'no one accepted' : `user didn't interact with incoming call screen`}`,
+                    message: `ringing timeout - ${this.isCreatedByMe
+                        ? 'no one accepted'
+                        : `user didn't interact with incoming call screen`}`,
                 }).catch((err) => {
                     this.logger.error('Failed to drop call', err);
                 });
@@ -15950,15 +16065,36 @@ class Call {
          * @param trackType the kind of video.
          */
         this.bindVideoElement = (videoElement, sessionId, trackType) => {
-            const unbind = this.dynascaleManager?.bindVideoElement(videoElement, sessionId, trackType);
-            if (!unbind)
+            const unbindDynascale = this.dynascaleManager?.bindVideoElement(videoElement, sessionId, trackType);
+            const stopFirstFrameDetector = this.bindFirstVideoFrameDetector(videoElement, sessionId, trackType);
+            if (!unbindDynascale && !stopFirstFrameDetector)
                 return;
+            const unbind = () => {
+                stopFirstFrameDetector?.();
+                unbindDynascale?.();
+            };
             this.leaveCallHooks.add(unbind);
             return () => {
                 this.leaveCallHooks.delete(unbind);
                 unbind();
             };
         };
+        this.bindFirstVideoFrameDetector = (videoElement, sessionId, trackType) => {
+            if (trackType !== 'videoTrack')
+                return;
+            return createFirstVideoFrameDetector(videoElement, () => {
+                this.reportFirstRenderedVideoFrame(sessionId);
+            });
+        };
+        this.reportFirstRenderedVideoFrame = (sessionId) => {
+            const participant = this.state.findParticipantBySessionId(sessionId);
+            if (participant?.isLocalParticipant)
+                return;
+            const trackId = participant?.videoStream?.getVideoTracks()[0]?.id;
+            if (!trackId)
+                return;
+            this.clientEventReporter.reportFirstFrame(this.cid, TrackType.VIDEO, trackId);
+        };
         /**
          * Binds a DOM <audio> element to the given session id.
          *
@@ -16108,6 +16244,7 @@ class Call {
         this.ringingSubject = new rxjs.BehaviorSubject(ringing);
         this.watching = watching;
         this.streamClient = streamClient;
+        this.clientEventReporter = clientEventReporter;
         this.clientStore = clientStore;
         this.streamClientBasePath = `/call/${this.type}/${this.id}`;
         this.logger = videoLoggerSystem.getLogger('Call');
@@ -17330,10 +17467,12 @@ class StreamClient {
             this.logger.info('StreamClient.connect: this.wsConnection.connect()');
             return await this.wsConnection.connect(this.defaultWSTimeout);
         };
+        this.getSdkVersion = () => this.options.clientAppIdentifier?.sdkVersion ||
+            "1.53.0";
         this.getUserAgent = () => {
             if (!this.cachedUserAgent) {
                 const { clientAppIdentifier = {} } = this.options;
-                const { sdkName = 'js', sdkVersion = "1.52.0", ...extras } = clientAppIdentifier;
+                const { sdkName = 'js', sdkVersion = "1.53.0", ...extras } = clientAppIdentifier;
                 this.cachedUserAgent = [
                     `stream-video-${sdkName}-v${sdkVersion}`,
                     ...Object.entries(extras).map(([key, value]) => `${key}=${value}`),
@@ -17510,6 +17649,602 @@ const createTokenOrProvider = (options) => {
     return token || tokenProvider;
 };
 
+const pcKey = (cid, role) => `${cid}:${role}`;
+class ClientEventReporter {
+    constructor(options) {
+        this.logger = videoLoggerSystem.getLogger('ClientEventReporter');
+        this.callContexts = new Map();
+        this.joinAttemptIds = new Map();
+        this.joinReasons = new Map();
+        this.coordinatorPairs = new Map();
+        this.wsPairs = new Map();
+        this.peerConnectionPairs = new Map();
+        this.pcEverConnected = new Map();
+        this.firstFrameReported = new Set();
+        /**
+         * 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.
+         */
+        this.startCoordinatorConnection = (userId) => {
+            this.coordinatorConnectId = generateUUIDv4();
+            this.coordinatorConnectUserId = userId;
+            return this.coordinatorConnectId;
+        };
+        this.trackCoordinatorWs = async (op) => {
+            this.beginCoordinatorWs();
+            try {
+                const result = await op();
+                this.succeedCoordinatorWs();
+                return result;
+            }
+            catch (err) {
+                applyError(this.coordinatorWsPair, mapCoordinatorWsError(err));
+                throw err;
+            }
+        };
+        this.beginCoordinatorWs = () => {
+            if (!this.coordinatorWsPair) {
+                this.coordinatorWsPair = {
+                    sid: generateUUIDv4(),
+                    attempts: 0,
+                    startedAt: Date.now(),
+                    userIdSnapshot: this.coordinatorConnectUserId,
+                };
+                this.send({
+                    ...this.buildCoordinatorWsCommon(this.coordinatorWsPair),
+                    event_type: 'initiated',
+                });
+            }
+            this.coordinatorWsPair.attempts++;
+        };
+        this.succeedCoordinatorWs = () => {
+            const pair = this.coordinatorWsPair;
+            if (!pair)
+                return;
+            this.send({
+                ...this.buildCoordinatorWsCommon(pair),
+                event_type: 'completed',
+                outcome: 'success',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+            });
+            this.coordinatorWsPair = undefined;
+        };
+        this.closeCoordinatorWs = () => {
+            const pair = this.coordinatorWsPair;
+            if (!pair || !pair.lastError) {
+                this.coordinatorWsPair = undefined;
+                return;
+            }
+            const { reason, code } = pair.lastError;
+            this.send({
+                ...this.buildCoordinatorWsCommon(pair),
+                event_type: 'completed',
+                outcome: 'failure',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+                retry_failure_reason: reason,
+                retry_failure_code: code,
+            });
+            this.coordinatorWsPair = undefined;
+        };
+        this.buildCoordinatorWsCommon = (pair) => ({
+            user_id: pair.userIdSnapshot ?? this.streamClient.userID,
+            stage: 'CoordinatorWS',
+            stage_id: pair.sid,
+            ...(this.coordinatorConnectId && {
+                coordinator_connect_id: this.coordinatorConnectId,
+            }),
+            timestamp: new Date().toISOString(),
+            user_agent: this.streamClient.getUserAgent(),
+            sdk_version: this.streamClient.getSdkVersion(),
+        });
+        this.emitMediaPermission = (cid) => {
+            if (isReactNative() || !this.callContexts.has(cid))
+                return;
+            const pair = {
+                sid: generateUUIDv4(),
+                attempts: 0,
+                startedAt: Date.now(),
+                joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
+            };
+            this.send({
+                ...this.buildCommon(cid, 'MediaDevicePermission', pair),
+                ...this.sessionIdField(cid),
+                microphone_permission_status: readPermissionStatus(getAudioBrowserPermission()),
+                camera_permission_status: readPermissionStatus(getVideoBrowserPermission()),
+                event_type: 'initiated',
+            });
+        };
+        this.registerCall = (cid, ctx) => {
+            this.callContexts.set(cid, ctx);
+        };
+        this.unregisterCall = (cid) => {
+            this.callContexts.delete(cid);
+            this.joinAttemptIds.delete(cid);
+            this.joinReasons.delete(cid);
+            this.coordinatorPairs.delete(cid);
+            this.wsPairs.delete(cid);
+            this.firstFrameReported.delete(`${cid}:FirstVideoFrame`);
+            this.firstFrameReported.delete(`${cid}:FirstAudioFrame`);
+            for (const role of ['publish', 'subscribe']) {
+                const key = pcKey(cid, role);
+                this.peerConnectionPairs.delete(key);
+                this.pcEverConnected.delete(key);
+            }
+        };
+        this.startCorrelation = (cid, joinReason) => {
+            try {
+                this.closeCallPairs(cid);
+                this.joinAttemptIds.set(cid, generateUUIDv4());
+                this.joinReasons.set(cid, joinReason);
+                this.firstFrameReported.delete(`${cid}:FirstVideoFrame`);
+                this.firstFrameReported.delete(`${cid}:FirstAudioFrame`);
+                this.emitJoinInitiated(cid);
+                this.emitMediaPermission(cid);
+            }
+            catch (err) {
+                this.logger.warn('Failed to start join correlation', err);
+            }
+        };
+        this.withJoinLifecycle = async (cid, joinReason, op) => {
+            this.startCorrelation(cid, joinReason);
+            try {
+                return await op();
+            }
+            catch (err) {
+                this.closeCallPairs(cid);
+                throw err;
+            }
+        };
+        this.track = async (cid, stage, op) => {
+            this.beginAttempt(cid, stage);
+            try {
+                const result = await op();
+                this.succeedAttempt(cid, stage);
+                return result;
+            }
+            catch (err) {
+                this.applyStageError(cid, stage, err);
+                throw err;
+            }
+        };
+        this.reportFirstFrame = (cid, trackType, trackId) => {
+            const stage = trackType === TrackType.VIDEO
+                ? 'FirstVideoFrame'
+                : trackType === TrackType.AUDIO
+                    ? 'FirstAudioFrame'
+                    : undefined;
+            if (!stage)
+                return;
+            const key = `${cid}:${stage}`;
+            if (this.firstFrameReported.has(key))
+                return;
+            this.firstFrameReported.add(key);
+            const pair = {
+                sid: generateUUIDv4(),
+                attempts: 0,
+                startedAt: Date.now(),
+                joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
+            };
+            const resolvedSfuId = this.getSfuId(cid);
+            this.send({
+                ...this.buildCommon(cid, stage, pair),
+                ...this.sessionIdField(cid),
+                ...(resolvedSfuId && { sfu_id: resolvedSfuId }),
+                track_id: trackId,
+                event_type: 'initiated',
+            });
+        };
+        this.captureWsError = (cid, opts) => {
+            const pair = this.wsPairs.get(cid);
+            if (!pair)
+                return;
+            applyError(pair, { reason: opts.reason, code: opts.code });
+        };
+        this.close = (cid) => {
+            this.closeCallPairs(cid);
+        };
+        this.abort = (cid, opts) => {
+            try {
+                const { code, reason } = opts;
+                const stageError = { code, reason };
+                applyErrorIfAbsent(this.coordinatorPairs.get(cid), stageError);
+                applyErrorIfAbsent(this.wsPairs.get(cid), stageError);
+                this.failCoordinator(cid);
+                this.failWs(cid);
+                this.emitPeerConnectionFailure(cid, 'publish', code, reason, 'NOT_CONNECTED');
+                this.emitPeerConnectionFailure(cid, 'subscribe', code, reason, 'NOT_CONNECTED');
+            }
+            catch (err) {
+                this.logger.warn('Failed to report abort', err);
+            }
+        };
+        this.closeCallPairs = (cid) => {
+            if (this.coordinatorPairs.get(cid))
+                this.failCoordinator(cid);
+            if (this.wsPairs.get(cid))
+                this.failWs(cid);
+            for (const role of ['publish', 'subscribe']) {
+                this.emitPeerConnectionFailure(cid, role, 'CLIENT_ABORTED', 'superseded by a new join attempt', 'NOT_CONNECTED');
+            }
+        };
+        this.emitJoinInitiated = (cid) => {
+            const joinAttemptId = this.joinAttemptIds.get(cid);
+            if (!joinAttemptId)
+                return;
+            const coordinatorConnectId = this.coordinatorConnectId;
+            this.send({
+                user_id: this.streamClient.userID,
+                stage: 'JoinInitiated',
+                join_attempt_id: joinAttemptId,
+                ...(coordinatorConnectId && {
+                    coordinator_connect_id: coordinatorConnectId,
+                }),
+                timestamp: new Date().toISOString(),
+                user_agent: this.streamClient.getUserAgent(),
+                sdk_version: this.streamClient.getSdkVersion(),
+                event_type: 'initiated',
+            });
+        };
+        this.beginAttempt = (cid, stage) => {
+            if (stage === 'CoordinatorJoin')
+                this.beginCoordinatorAttempt(cid);
+            else
+                this.beginWsAttempt(cid);
+        };
+        this.succeedAttempt = (cid, stage) => {
+            if (stage === 'CoordinatorJoin')
+                this.succeedCoordinator(cid);
+            else
+                this.succeedWs(cid);
+        };
+        this.applyStageError = (cid, stage, err) => {
+            const pair = stage === 'CoordinatorJoin'
+                ? this.coordinatorPairs.get(cid)
+                : this.wsPairs.get(cid);
+            applyErrorIfAbsent(pair, stage === 'CoordinatorJoin'
+                ? mapCoordinatorHttpError(err)
+                : mapWsJoinError(err));
+        };
+        this.beginCoordinatorAttempt = (cid) => {
+            let pair = this.coordinatorPairs.get(cid);
+            if (!pair) {
+                pair = {
+                    sid: generateUUIDv4(),
+                    attempts: 0,
+                    startedAt: Date.now(),
+                    joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
+                    joinReasonSnapshot: this.joinReasons.get(cid),
+                };
+                this.coordinatorPairs.set(cid, pair);
+                this.send({
+                    ...this.buildCommon(cid, 'CoordinatorJoin', pair),
+                    ...(pair.joinReasonSnapshot && {
+                        join_reason: pair.joinReasonSnapshot,
+                    }),
+                    event_type: 'initiated',
+                });
+            }
+            pair.lastError = undefined;
+            pair.attempts++;
+        };
+        this.succeedCoordinator = (cid) => {
+            const pair = this.coordinatorPairs.get(cid);
+            if (!pair)
+                return;
+            this.send({
+                ...this.buildCommon(cid, 'CoordinatorJoin', pair),
+                ...this.sessionIdField(cid),
+                ...(pair.joinReasonSnapshot && { join_reason: pair.joinReasonSnapshot }),
+                event_type: 'completed',
+                outcome: 'success',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+            });
+            this.coordinatorPairs.delete(cid);
+        };
+        this.failCoordinator = (cid) => {
+            const pair = this.coordinatorPairs.get(cid);
+            if (!pair || !pair.lastError) {
+                this.coordinatorPairs.delete(cid);
+                return;
+            }
+            const { reason, code } = pair.lastError;
+            this.send({
+                ...this.buildCommon(cid, 'CoordinatorJoin', pair),
+                ...this.sessionIdField(cid),
+                ...(pair.joinReasonSnapshot && { join_reason: pair.joinReasonSnapshot }),
+                event_type: 'completed',
+                outcome: 'failure',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+                retry_failure_reason: reason,
+                retry_failure_code: code,
+            });
+            this.coordinatorPairs.delete(cid);
+        };
+        this.beginWsAttempt = (cid) => {
+            let pair = this.wsPairs.get(cid);
+            if (!pair) {
+                pair = {
+                    sid: generateUUIDv4(),
+                    attempts: 0,
+                    startedAt: Date.now(),
+                    joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
+                };
+                this.wsPairs.set(cid, pair);
+                const sfuId = this.getSfuId(cid);
+                this.send({
+                    ...this.buildCommon(cid, 'WSJoin', pair),
+                    ...this.sessionIdField(cid),
+                    ...(sfuId && { sfu_id: sfuId }),
+                    event_type: 'initiated',
+                });
+            }
+            pair.lastError = undefined;
+            pair.attempts++;
+        };
+        this.succeedWs = (cid) => {
+            const pair = this.wsPairs.get(cid);
+            if (!pair)
+                return;
+            const sfuId = this.getSfuId(cid);
+            this.send({
+                ...this.buildCommon(cid, 'WSJoin', pair),
+                ...this.sessionIdField(cid),
+                ...(sfuId && { sfu_id: sfuId }),
+                event_type: 'completed',
+                outcome: 'success',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+            });
+            this.wsPairs.delete(cid);
+        };
+        this.failWs = (cid) => {
+            const pair = this.wsPairs.get(cid);
+            if (!pair || !pair.lastError) {
+                this.wsPairs.delete(cid);
+                return;
+            }
+            const { reason, code } = pair.lastError;
+            const sfuId = this.getSfuId(cid);
+            this.send({
+                ...this.buildCommon(cid, 'WSJoin', pair),
+                ...this.sessionIdField(cid),
+                event_type: 'completed',
+                outcome: 'failure',
+                retry_count_attempt: pair.attempts - 1,
+                elapsed_time: Date.now() - pair.startedAt,
+                ...(sfuId && { sfu_id: sfuId }),
+                retry_failure_reason: reason,
+                retry_failure_code: code,
+            });
+            this.wsPairs.delete(cid);
+        };
+        this.onPeerConnectionStateChange = (cid, event) => {
+            const role = event.peerType === PeerType.SUBSCRIBER ? 'subscribe' : 'publish';
+            if (event.stateType === 'ice' && event.state === 'failed') {
+                this.emitPeerConnectionFailure(cid, role, 'ICE_CONNECTIVITY_FAILED', 'ICE connectivity checks failed', 'FAILED');
+                return;
+            }
+            if (event.stateType === 'peerConnection' && event.state === 'failed') {
+                this.emitPeerConnectionFailure(cid, role, 'DTLS_CONNECTIVITY_FAILED', 'DTLS connectivity checks failed', 'CONNECTED');
+                return;
+            }
+            if (event.stateType !== 'peerConnection')
+                return;
+            switch (event.state) {
+                case 'connecting':
+                    if (this.peerConnectionPairs.has(pcKey(cid, role)))
+                        return;
+                    this.openPeerConnectionPair(cid, role);
+                    break;
+                case 'connected':
+                    this.emitPeerConnectionSuccess(cid, role);
+                    this.pcEverConnected.set(pcKey(cid, role), true);
+                    break;
+            }
+        };
+        this.openPeerConnectionPair = (cid, role) => {
+            const key = pcKey(cid, role);
+            const pair = {
+                sid: generateUUIDv4(),
+                attempts: 0,
+                startedAt: Date.now(),
+                joinAttemptIdSnapshot: this.joinAttemptIds.get(cid),
+                sfuId: this.getSfuId(cid),
+                userSessionId: this.getUserSessionId(cid),
+                wasPreviouslyConnected: this.pcEverConnected.get(key) === true,
+            };
+            this.peerConnectionPairs.set(key, pair);
+            this.send({
+                ...this.buildCommon(cid, 'PeerConnectionConnect', pair),
+                ...this.sessionIdField(cid),
+                peer_connection: role,
+                was_previously_connected: pair.wasPreviouslyConnected,
+                ...(pair.sfuId && { sfu_id: pair.sfuId }),
+                ...(pair.userSessionId && {
+                    user_session_id: pair.userSessionId,
+                }),
+                event_type: 'initiated',
+            });
+        };
+        this.emitPeerConnectionSuccess = (cid, role) => {
+            const key = pcKey(cid, role);
+            const pair = this.peerConnectionPairs.get(key);
+            if (!pair)
+                return;
+            this.send({
+                ...this.buildCommon(cid, 'PeerConnectionConnect', pair),
+                ...this.sessionIdField(cid),
+                peer_connection: role,
+                was_previously_connected: pair.wasPreviouslyConnected,
+                ...(pair.sfuId && { sfu_id: pair.sfuId }),
+                ...(pair.userSessionId && {
+                    user_session_id: pair.userSessionId,
+                }),
+                event_type: 'completed',
+                outcome: 'success',
+                retry_count_attempt: 0,
+                elapsed_time: Date.now() - pair.startedAt,
+            });
+            this.peerConnectionPairs.delete(key);
+        };
+        this.emitPeerConnectionFailure = (cid, role, code, reason, iceState) => {
+            const key = pcKey(cid, role);
+            const pair = this.peerConnectionPairs.get(key);
+            if (!pair)
+                return;
+            this.send({
+                ...this.buildCommon(cid, 'PeerConnectionConnect', pair),
+                ...this.sessionIdField(cid),
+                peer_connection: role,
+                was_previously_connected: pair.wasPreviouslyConnected,
+                ...(pair.userSessionId && {
+                    user_session_id: pair.userSessionId,
+                }),
+                ...(pair.sfuId && { sfu_id: pair.sfuId }),
+                event_type: 'completed',
+                outcome: 'failure',
+                retry_count_attempt: 0,
+                elapsed_time: Date.now() - pair.startedAt,
+                ice_state: iceState,
+                retry_failure_reason: reason,
+                retry_failure_code: code,
+            });
+            this.peerConnectionPairs.delete(key);
+        };
+        this.getSfuId = (cid) => this.callContexts.get(cid)?.getSfuId() ?? '';
+        this.getUserSessionId = (cid) => this.callContexts.get(cid)?.getUserSessionId() ?? '';
+        this.sessionIdField = (cid) => {
+            const callSessionId = this.callContexts.get(cid)?.getCallSessionId() ?? '';
+            return callSessionId ? { call_session_id: callSessionId } : {};
+        };
+        this.buildCommon = (cid, stage, pair) => {
+            const ctx = this.callContexts.get(cid);
+            const coordinatorConnectId = this.coordinatorConnectId;
+            return {
+                user_id: this.streamClient.userID,
+                type: ctx?.callType ?? '',
+                id: ctx?.callId ?? '',
+                call_cid: cid,
+                stage,
+                stage_id: pair.sid,
+                ...(pair.joinAttemptIdSnapshot && {
+                    join_attempt_id: pair.joinAttemptIdSnapshot,
+                }),
+                ...(coordinatorConnectId && {
+                    coordinator_connect_id: coordinatorConnectId,
+                }),
+                timestamp: new Date().toISOString(),
+                user_agent: this.streamClient.getUserAgent(),
+                sdk_version: this.streamClient.getSdkVersion(),
+            };
+        };
+        this.send = (body) => {
+            void this.sendWithRetry(body);
+        };
+        this.sendWithRetry = async (body) => {
+            for (let attempt = 0; attempt < 5; attempt++) {
+                try {
+                    await this.streamClient.doAxiosRequest('post', '/call_client_event', { events: [body] }, { publicEndpoint: true });
+                    return true;
+                }
+                catch (err) {
+                    const status = err?.response
+                        ?.status;
+                    if (typeof status === 'number' && status >= 400 && status < 500) {
+                        this.logger.debug(`Client event rejected (${status}), not retrying`, body.stage, body.event_type);
+                        return false;
+                    }
+                    if (attempt === 4) {
+                        this.logger.debug('Client event delivery failed after retries', body.stage, body.event_type, err);
+                        return false;
+                    }
+                    await sleep(retryInterval(attempt));
+                }
+            }
+            return false;
+        };
+        this.streamClient = options.streamClient;
+    }
+}
+const readPermissionStatus = (permission) => {
+    const state = getCurrentValue(permission.asStateObservable());
+    switch (state) {
+        case 'granted':
+            return 'GRANTED';
+        case 'denied':
+            return 'FAILED';
+        case 'prompting':
+            return 'INITIATED';
+        case 'prompt':
+        default:
+            return 'NOT_INITIATED';
+    }
+};
+const errorMessage = (err) => err instanceof Error ? err.message : String(err);
+const applyError = (pair, next) => {
+    if (!pair)
+        return;
+    pair.lastError = next;
+};
+const applyErrorIfAbsent = (pair, next) => {
+    if (!pair || pair.lastError)
+        return;
+    pair.lastError = next;
+};
+const mapCoordinatorHttpError = (err) => {
+    if (err instanceof ErrorFromResponse) {
+        return {
+            reason: err.message,
+            code: err.code != null ? String(err.code) : 'SERVER_ERROR',
+        };
+    }
+    return { reason: errorMessage(err), code: 'SERVER_ERROR' };
+};
+const mapCoordinatorWsError = (err) => {
+    if (err instanceof ErrorFromResponse) {
+        return {
+            reason: err.message,
+            code: err.code != null ? String(err.code) : 'SERVER_ERROR',
+        };
+    }
+    if (err instanceof Error) {
+        try {
+            const parsed = JSON.parse(err.message);
+            if (typeof parsed.isWSFailure === 'boolean') {
+                return {
+                    reason: parsed.message || err.message,
+                    code: !parsed.isWSFailure && parsed.code
+                        ? String(parsed.code)
+                        : 'SERVER_ERROR',
+                };
+            }
+        }
+        catch { }
+    }
+    return { reason: errorMessage(err), code: 'SERVER_ERROR' };
+};
+const mapWsJoinError = (err) => {
+    if (err instanceof SfuJoinError) {
+        const sfuError = err.errorEvent.error;
+        return {
+            reason: sfuError?.message || err.message,
+            code: (sfuError && ErrorCode[sfuError.code]) || 'SFU_ERROR',
+        };
+    }
+    const reason = errorMessage(err);
+    if (err instanceof SfuTimeoutError) {
+        return { reason, code: 'REQUEST_TIMEOUT' };
+    }
+    return { reason, code: 'SFU_ERROR' };
+};
+
 /**
  * A `StreamVideoClient` instance lets you communicate with our API, and authenticate users.
  */
@@ -17573,6 +18308,7 @@ class StreamVideoClient {
                     }
                     call = new Call({
                         streamClient: this.streamClient,
+                        clientEventReporter: this.clientEventReporter,
                         type: e.call.type,
                         id: e.call.id,
                         members: e.members,
@@ -17642,6 +18378,8 @@ class StreamVideoClient {
                 user.id = '!anon';
                 return this.connectAnonymousUser(user, tokenOrProvider);
             }
+            const reporter = this.clientEventReporter;
+            reporter.startCoordinatorConnection(user.id);
             const connectUserResponse = await withoutConcurrency(this.connectionConcurrencyTag, async () => {
                 const client = this.streamClient;
                 const { onConnectUserError, persistUserOnConnectionFailure } = client.options;
@@ -17651,14 +18389,15 @@ class StreamVideoClient {
                 for (let attempt = 0; attempt < maxConnectUserRetries; attempt++) {
                     try {
                         this.logger.trace(`Connecting user (${attempt})`, user);
-                        return user.type === 'guest'
-                            ? await client.connectGuestUser(user)
-                            : await client.connectUser(user, tokenOrProvider);
+                        return await reporter.trackCoordinatorWs(() => user.type === 'guest'
+                            ? client.connectGuestUser(user)
+                            : client.connectUser(user, tokenOrProvider));
                     }
                     catch (err) {
                         this.logger.warn(`Failed to connect a user (${attempt})`, err);
                         errorQueue.push(err);
                         if (attempt === maxConnectUserRetries - 1) {
+                            reporter.closeCoordinatorWs();
                             onConnectUserError?.(err, errorQueue);
                             throw err;
                         }
@@ -17736,6 +18475,7 @@ class StreamVideoClient {
             return (call ??
                 new Call({
                     streamClient: this.streamClient,
+                    clientEventReporter: this.clientEventReporter,
                     id: id,
                     type: type,
                     clientStore: this.writeableStateStore,
@@ -17760,6 +18500,7 @@ class StreamVideoClient {
             for (const c of response.calls) {
                 const call = new Call({
                     streamClient: this.streamClient,
+                    clientEventReporter: this.clientEventReporter,
                     id: c.call.id,
                     type: c.call.type,
                     members: c.members,
@@ -17867,6 +18608,7 @@ class StreamVideoClient {
                     const [callType, callId] = call_cid.split(':');
                     call = new Call({
                         streamClient: this.streamClient,
+                        clientEventReporter: this.clientEventReporter,
                         type: callType,
                         id: callId,
                         clientStore: this.writeableStateStore,
@@ -17907,6 +18649,9 @@ class StreamVideoClient {
         this.logger = videoLoggerSystem.getLogger('client');
         this.rejectCallWhenBusy = clientOptions?.rejectCallWhenBusy ?? false;
         this.streamClient = createCoordinatorClient(apiKey, clientOptions);
+        this.clientEventReporter = new ClientEventReporter({
+            streamClient: this.streamClient,
+        });
         this.writeableStateStore = new StreamVideoWriteableStateStore();
         this.readOnlyStateStore = new StreamVideoReadOnlyStateStore(this.writeableStateStore);
         if (typeof apiKeyOrArgs !== 'string' && apiKeyOrArgs.user) {
@@ -18020,6 +18765,7 @@ exports.ScreenShareState = ScreenShareState;
 exports.SfuEvents = events;
 exports.SfuJoinError = SfuJoinError;
 exports.SfuModels = models;
+exports.SfuTimeoutError = SfuTimeoutError;
 exports.SpeakerManager = SpeakerManager;
 exports.SpeakerState = SpeakerState;
 exports.StartClosedCaptionsRequestLanguageEnum = StartClosedCaptionsRequestLanguageEnum;