@stream-io/video-client 1.59.0 → 1.60.0

package/src/Call.ts

@@ -50,6 +50,7 @@ import {
   EndCallResponse,
   GetCallReportResponse,
   GetCallResponse,
+  GetCallRingStateResponse,
   GetCallSessionParticipantStatsDetailsResponse,
   GetOrCreateCallRequest,
   GetOrCreateCallResponse,
@@ -152,7 +153,7 @@ import {
   StatsReporter,
   Tracer,
 } from './stats';
-import type { ClientEventReporter, JoinReason } from './reporting';
+import type { ClientEventReporter, JoinReason, JoinSource } from './reporting';
 import { AudioBindingsWatchdog } from './helpers/AudioBindingsWatchdog';
 import { BlockedAudioTracker } from './helpers/BlockedAudioTracker';
 import { TrackSubscriptionManager } from './helpers/TrackSubscriptionManager';
@@ -160,6 +161,7 @@ import { DynascaleManager } from './helpers/DynascaleManager';
 import { createFirstVideoFrameDetector } from './helpers/firstVideoFrame';
 import { ViewportTracker } from './helpers/ViewportTracker';
 import { PermissionsContext } from './permissions';
+import { RingStatePoller, RingTimeout, resolveOwnRingOutcome } from './ringing';
 import { CallTypes } from './CallType';
 import { StreamClient } from './coordinator/connection/client';
 import { retryInterval, sleep } from './coordinator/connection/utils';
@@ -302,7 +304,8 @@ export class Call {
   private statsReporter?: StatsReporter;
   private sfuStatsReporter?: SfuStatsReporter;
   private lastStatsOptions?: StatsOptions;
-  private dropTimeout: ReturnType<typeof setTimeout> | undefined;
+  private ringTimeout: RingTimeout | undefined;
+  private ringStatePoller: RingStatePoller | undefined;
 
   private readonly clientStore: StreamVideoWriteableStateStore;
   public readonly streamClient: StreamClient;
@@ -537,33 +540,20 @@ export class Call {
       createSubscription(this.state.session$, (session) => {
         if (!this.ringing) return;
 
-        const receiverId = this.clientStore.connectedUser?.id;
-        if (!receiverId) return;
-
-        const isAcceptedByMe = Boolean(session?.accepted_by[receiverId]);
-        const isRejectedByMe = Boolean(session?.rejected_by[receiverId]);
-
-        if (isAcceptedByMe || isRejectedByMe) {
-          this.cancelAutoDrop();
-        }
-
-        const isAcceptedElsewhere =
-          isAcceptedByMe && this.state.callingState === CallingState.RINGING;
+        const { settledByMe, leaveReason } = resolveOwnRingOutcome({
+          session,
+          currentUserId: this.currentUserId,
+          callingState: this.state.callingState,
+        });
+        if (settledByMe) this.cancelAutoDrop();
+        if (!leaveReason || hasPending(this.joinLeaveConcurrencyTag)) return;
 
-        if (
-          (isAcceptedElsewhere || isRejectedByMe) &&
-          !hasPending(this.joinLeaveConcurrencyTag)
-        ) {
-          globalThis.streamRNVideoSDK?.callingX?.endCall(
-            this,
-            isAcceptedElsewhere ? 'answeredElsewhere' : 'rejected',
+        globalThis.streamRNVideoSDK?.callingX?.endCall(this, leaveReason);
+        this.leave().catch(() => {
+          this.logger.error(
+            'Could not leave a call that was accepted or rejected elsewhere',
           );
-          this.leave().catch(() => {
-            this.logger.error(
-              'Could not leave a call that was accepted or rejected elsewhere',
-            );
-          });
-        }
+        });
       }),
     );
   };
@@ -608,6 +598,7 @@ export class Call {
         this.state.setCallingState(CallingState.RINGING);
       }
       this.scheduleAutoDrop();
+      this.scheduleRingStatePolling();
       this.leaveCallHooks.add(registerRingingCallEventHandlers(this));
     }
   };
@@ -713,6 +704,13 @@ export class Call {
       throw new Error('Cannot leave call that has already been left.');
     }
 
+    // before the first await: the calling state stays RINGING well into the
+    // teardown, so pause both watchdogs before they can race this leave. They
+    // keep their deadlines, so a failed leave resumes them without handing the
+    // ring another window.
+    this.ringTimeout?.pause();
+    this.ringStatePoller?.pause();
+
     await withoutConcurrency(this.joinLeaveConcurrencyTag, async () => {
       const callingState = this.state.callingState;
 
@@ -821,6 +819,7 @@ export class Call {
       this.unifiedSessionId = undefined;
       this.ringingSubject.next(false);
       this.cancelAutoDrop();
+      this.cancelRingStatePolling();
       this.clientStore.unregisterCall(this);
 
       globalThis.streamRNVideoSDK?.callManager.stop({
@@ -863,6 +862,17 @@ export class Call {
             this.logger.warn('Failed to dispose media engine', err);
           });
       }
+    }).catch((err) => {
+      if (
+        !hasPending(this.joinLeaveConcurrencyTag) &&
+        this.state.callingState === CallingState.RINGING
+      ) {
+        // resume, never re-arm: a fresh watchdog would restart the ring
+        // window this leave was already most of the way through
+        this.ringTimeout?.start();
+        this.ringStatePoller?.resume();
+      }
+      throw err;
     });
   };
 
@@ -1056,6 +1066,27 @@ export class Call {
     );
   };
 
+  /**
+   * Returns who accepted, rejected or missed the ring for a call session.
+   * Safe to poll: it performs no writes and emits no events.
+   *
+   * @param callSessionId the call session to read. Defaults to the current one.
+   * Pass it explicitly to read a session that has already ended, as ending a
+   * call clears its current session.
+   */
+  getRingState = async (
+    callSessionId?: string,
+  ): Promise<GetCallRingStateResponse> => {
+    const sessionId = callSessionId ?? this.state.session?.id;
+    if (!sessionId) {
+      throw new Error('Cannot read the ring state: the call has no session');
+    }
+    return this.streamClient.get<GetCallRingStateResponse>(
+      `${this.streamClientBasePath}/ring_state`,
+      { call_session_id: sessionId },
+    );
+  };
+
   /**
    * A shortcut for {@link Call.get} with `notify` parameter set to `true`.
    * Will send a `call.notification` event to the call members.
@@ -1112,12 +1143,14 @@ export class Call {
       joinResponseTimeout,
       rpcRequestTimeout,
       allowOwnTracksLoopback = false,
+      joinSource,
       ...data
     }: JoinCallData & {
       maxJoinRetries?: number;
       joinResponseTimeout?: number;
       rpcRequestTimeout?: number;
       allowOwnTracksLoopback?: boolean;
+      joinSource?: JoinSource;
     } = {}): Promise<void> => {
       const callingState = this.state.callingState;
 
@@ -1159,7 +1192,7 @@ export class Call {
       try {
         await this.clientEventReporter.withJoinLifecycle(
           this.cid,
-          'first-attempt',
+          { joinReason: 'first-attempt', joinSource },
           async () => {
             for (let attempt = 0; attempt < maxJoinRetries; attempt++) {
               try {
@@ -2081,8 +2114,10 @@ export class Call {
       this.reconnectReason === ReconnectReason.NETWORK_BACK_ONLINE
         ? 'network-available'
         : 'full-rejoin';
-    await this.clientEventReporter.withJoinLifecycle(this.cid, joinReason, () =>
-      this.doJoin(this.joinCallData),
+    await this.clientEventReporter.withJoinLifecycle(
+      this.cid,
+      { joinReason },
+      () => this.doJoin(this.joinCallData),
     );
     await this.restorePublishedTracks();
     this.restoreSubscribedTracks();
@@ -2117,7 +2152,7 @@ export class Call {
       const currentSfu = currentSfuClient.edgeName;
       await this.clientEventReporter.withJoinLifecycle(
         this.cid,
-        'migration',
+        { joinReason: 'migration' },
         () =>
           this.doJoin({
             ...this.joinCallData,
@@ -3114,42 +3149,39 @@ export class Call {
    */
   private scheduleAutoDrop = () => {
     this.cancelAutoDrop();
-
-    const settings = this.state.settings;
-    if (!settings) return;
-    // ignore if the call is not ringing
-    if (this.state.callingState !== CallingState.RINGING) return;
-
-    const timeoutInMs = this.isCreatedByMe
-      ? settings.ring.auto_cancel_timeout_ms
-      : settings.ring.incoming_call_timeout_ms;
-
-    // 0 means no auto-drop
-    if (timeoutInMs <= 0) return;
-    this.dropTimeout = setTimeout(() => {
-      // the call might have stopped ringing by this point,
-      // e.g. it was already accepted and joined
-      if (this.state.callingState !== CallingState.RINGING) return;
-      this.leave({
-        reject: true,
-        reason: 'timeout',
-        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);
-      });
-    }, timeoutInMs);
+    this.ringTimeout = new RingTimeout(this);
+    this.ringTimeout.start();
   };
 
   /**
    * Cancels a scheduled auto-drop timeout.
    */
   private cancelAutoDrop = () => {
-    clearTimeout(this.dropTimeout);
-    this.dropTimeout = undefined;
+    this.ringTimeout?.stop();
+    this.ringTimeout = undefined;
+  };
+
+  /**
+   * Starts polling for the ring outcome. Applicable only to ringing calls the
+   * current user created.
+   */
+  private scheduleRingStatePolling = () => {
+    this.cancelRingStatePolling();
+
+    if (!this.isCreatedByMe) return;
+    const options = this.streamClient.options.ringStatePolling;
+    if (options === false) return;
+
+    this.ringStatePoller = new RingStatePoller(this, options);
+    this.ringStatePoller.start();
+  };
+
+  /**
+   * Cancels the ring state polling.
+   */
+  private cancelRingStatePolling = () => {
+    this.ringStatePoller?.stop();
+    this.ringStatePoller = undefined;
   };
 
   /**

package/src/StreamSfuClient.ts

@@ -39,7 +39,8 @@ import {
 } from './helpers/promise';
 import { withoutConcurrency } from './helpers/concurrency';
 import { getTimers } from './timers';
-import { Tracer, TraceSlice } from './stats';
+import { getSdkInfo } from './helpers/client-details';
+import { getStreamClientId, Tracer, TraceSlice } from './stats';
 import { SfuJoinError, SfuTimeoutError } from './errors';
 
 export type StreamSfuClientConstructor = {
@@ -271,7 +272,10 @@ export class StreamSfuClient {
     this.rpc = createSignalClient({
       baseUrl: server.url,
       interceptors: [
-        withHeaders({ Authorization: `Bearer ${token}` }),
+        withHeaders({
+          Authorization: `Bearer ${token}`,
+          'X-Stream-Client': getStreamClientId(getSdkInfo()),
+        }),
         this.tracer && withRequestTracer(this.tracer.trace),
         this.logger.getLogLevel() === 'trace' && withRequestLogger(this.logger),
         withTimeout(rpcRequestTimeout, this.tracer?.trace),

package/src/__tests__/Call.autodrop.test.ts

@@ -1,104 +1,156 @@
 import '../rtc/__tests__/mocks/webrtc.mocks';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fromPartial } from '@total-typescript/shoehorn';
 import { Call } from '../Call';
 import { StreamClient } from '../coordinator/connection/client';
 import { ClientEventReporter } from '../reporting';
 import { generateUUIDv4 } from '../coordinator/connection/utils';
 import { CallingState, StreamVideoWriteableStateStore } from '../store';
+import { CallSettingsResponse } from '../gen/coordinator';
 
+const TIMEOUT_MS = 30_000;
+
+// The timeout's own behaviour is covered by `ringing/__tests__/RingTimeout`.
+// This file covers the wiring: that a ringing call arms one and that leaving
+// cancels it.
 describe('Auto drop ringing calls', () => {
-  let call: Call;
   const userId = 'jane';
+  let call: Call;
 
-  beforeEach(async () => {
-    vi.useFakeTimers();
-
+  const ringingCall = () => {
     const clientStore = new StreamVideoWriteableStateStore();
     const streamClient = new StreamClient('abc');
-    call = new Call({
+    const newCall = new Call({
       type: 'test',
       id: generateUUIDv4(),
       streamClient,
       clientEventReporter: new ClientEventReporter({ streamClient }),
-      clientStore: clientStore,
+      clientStore,
+      ringing: true,
     });
 
-    // @ts-expect-error mocking only what we need for the test
-    clientStore.connectedUserSubject.next({
-      id: userId,
-    });
-
-    call.state['callingStateSubject'].next(CallingState.RINGING);
-
-    vi.spyOn(call, 'leave').mockImplementation(async () => {
-      console.log(`TEST: leave() called`);
-    });
-  });
-
-  it('caller should drop ringing calls after a timeout if no one accepted', async () => {
-    call.state['settingsSubject'].next({
-      // @ts-expect-error mocking only what we need for the test, we use fake timers, so undefined for timeout works
-      ring: {},
-      // @ts-expect-error mocking only what we need for the test
-      screensharing: {
-        enabled: false,
-        target_resolution: {
-          width: 100,
-          height: 100,
+    clientStore.setConnectedUser(fromPartial({ id: userId }));
+    newCall.state['createdBySubject'].next(fromPartial({ id: userId }));
+    newCall.state['settingsSubject'].next(
+      fromPartial<CallSettingsResponse>({
+        ring: {
+          auto_cancel_timeout_ms: TIMEOUT_MS,
+          incoming_call_timeout_ms: TIMEOUT_MS,
+          missed_call_timeout_ms: TIMEOUT_MS,
         },
-      },
-    });
+        screensharing: {
+          enabled: false,
+          target_resolution: { width: 100, height: 100 },
+        },
+      }),
+    );
+    newCall.state['sessionSubject'].next(
+      fromPartial({
+        id: 'session-1',
+        accepted_by: {},
+        rejected_by: {},
+        missed_by: {},
+      }),
+    );
+    newCall.state['callingStateSubject'].next(CallingState.RINGING);
+
+    vi.spyOn(newCall, 'leave').mockResolvedValue(undefined);
+    return newCall;
+  };
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    call = ringingCall();
+  });
 
-    // @ts-expect-error mocking only what we need for the test
-    call.state['createdBySubject'].next({
-      id: userId,
-    });
+  afterEach(() => {
+    call['cancelAutoDrop']();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
 
-    // black-box test, calling private method
-    call['scheduleAutoDrop']();
+  it('is armed when a call starts ringing', async () => {
+    call.state['callingStateSubject'].next(CallingState.IDLE);
 
-    await vi.runAllTimersAsync();
+    call['handleRingingCall']();
 
+    expect(call['ringTimeout']).toBeDefined();
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS);
     expect(call.leave).toHaveBeenCalledWith({
       reject: true,
       reason: 'timeout',
-      message: `ringing timeout - no one accepted`,
+      message: 'ringing timeout - no one accepted',
     });
   });
 
-  it(`callee should drop ringing calls after a timeout if user didn't interact with incoming call screen`, async () => {
-    call.state['settingsSubject'].next({
-      // @ts-expect-error mocking only what we need for the test, we use fake timers, so undefined for timeout works
-      ring: {},
-      // @ts-expect-error mocking only what we need for the test
-      screensharing: {
-        enabled: false,
-        target_resolution: {
-          width: 100,
-          height: 100,
-        },
-      },
-    });
+  it('is cancelled by cancelAutoDrop', async () => {
+    call['scheduleAutoDrop']();
 
-    // @ts-expect-error mocking only what we need for the test
-    call.state['createdBySubject'].next({
-      id: 'not-' + userId,
-    });
+    call['cancelAutoDrop']();
 
-    // black-box test, calling private method
+    expect(call['ringTimeout']).toBeUndefined();
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS);
+    expect(call.leave).not.toHaveBeenCalled();
+  });
+
+  // the calling state stays RINGING well into teardown, so the watchdogs have
+  // to be paused before `leave` awaits anything
+  it('pauses the watchdogs synchronously when leave starts', async () => {
     call['scheduleAutoDrop']();
+    call['scheduleRingStatePolling']();
+    const timeout = call['ringTimeout'];
+    vi.spyOn(call, 'leave').mockRestore();
+    vi.spyOn(call, 'reject').mockResolvedValue(fromPartial({}));
 
-    await vi.runAllTimersAsync();
+    const poller = call['ringStatePoller'];
 
-    expect(call.leave).toHaveBeenCalledWith({
-      reject: true,
-      reason: 'timeout',
-      message: `ringing timeout - user didn't interact with incoming call screen`,
-    });
+    const leaving = call.leave({ reject: false });
+
+    // paused, not cancelled: both keep the window this leave is ending
+    expect(call['ringTimeout']).toBe(timeout);
+    expect(call['ringStatePoller']).toBe(poller);
+    expect(timeout!['timeoutId']).toBeUndefined();
+    expect(timeout!['stopped']).toBe(false);
+    expect(poller!['idleTimeoutId']).toBeUndefined();
+    expect(poller!['stopped']).toBe(false);
+
+    await leaving.catch(() => {});
+
+    expect(timeout!['stopped']).toBe(true);
+    expect(poller!['stopped']).toBe(true);
   });
 
-  afterEach(() => {
-    vi.useRealTimers();
+  it('restores both watchdogs when rejecting the ring fails', async () => {
+    call['scheduleAutoDrop']();
+    call['scheduleRingStatePolling']();
+    const timeout = call['ringTimeout'];
+    const deadlineAt = timeout!['deadlineAt'];
+    const poller = call['ringStatePoller'];
+    const pollDeadlineAt = poller!['deadlineAt'];
+    vi.spyOn(call, 'leave').mockRestore();
+    vi.spyOn(call, 'reject').mockRejectedValueOnce(new Error('transient'));
+
+    await expect(call.leave({ reject: true })).rejects.toThrow('transient');
+
+    expect(call.state.callingState).toBe(CallingState.RINGING);
+    expect(call['ringTimeout']).toBe(timeout);
+    expect(timeout!['timeoutId']).toBeDefined();
+    expect(timeout!['deadlineAt']).toBe(deadlineAt);
+    expect(call['ringStatePoller']).toBe(poller);
+    expect(poller!['deadlineAt']).toBe(pollDeadlineAt);
+    expect(poller!['stopped']).toBe(false);
+  });
+
+  it('replaces a previously armed timeout', async () => {
+    call['scheduleAutoDrop']();
+    const first = call['ringTimeout'];
+
+    call['scheduleAutoDrop']();
+
+    expect(call['ringTimeout']).not.toBe(first);
+    expect(first!['stopped']).toBe(true);
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS);
+    expect(call.leave).toHaveBeenCalledTimes(1);
   });
 });

package/src/__tests__/Call.getRingState.test.ts

@@ -0,0 +1,87 @@
+import '../rtc/__tests__/mocks/webrtc.mocks';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { fromPartial } from '@total-typescript/shoehorn';
+import { Call } from '../Call';
+import { StreamClient } from '../coordinator/connection/client';
+import { ClientEventReporter } from '../reporting';
+import { generateUUIDv4 } from '../coordinator/connection/utils';
+import { StreamVideoWriteableStateStore } from '../store';
+import { CallSessionResponse } from '../gen/coordinator';
+
+describe('Call.getRingState', () => {
+  const callId = generateUUIDv4();
+
+  const fakeCall = (sessionId?: string) => {
+    const streamClient = new StreamClient('abc');
+    const call = new Call({
+      type: 'test',
+      id: callId,
+      streamClient,
+      clientEventReporter: new ClientEventReporter({ streamClient }),
+      clientStore: new StreamVideoWriteableStateStore(),
+    });
+
+    if (sessionId) {
+      call.state['sessionSubject'].next(
+        fromPartial<CallSessionResponse>({ id: sessionId }),
+      );
+    }
+
+    const get = vi
+      .spyOn(streamClient, 'get')
+      .mockResolvedValue(fromPartial({ session_id: sessionId }));
+
+    return { call, get };
+  };
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('reads the ring state of the current session', async () => {
+    const { call, get } = fakeCall('session-1');
+
+    await call.getRingState();
+
+    expect(get).toHaveBeenCalledWith(`/call/test/${callId}/ring_state`, {
+      call_session_id: 'session-1',
+    });
+  });
+
+  it('reads the ring state of an explicitly named session', async () => {
+    // ending a call clears its current session, so a caller reconciling after
+    // `call.ended` has to name the session it rang on
+    const { call, get } = fakeCall('current-session');
+
+    await call.getRingState('ended-session');
+
+    expect(get).toHaveBeenCalledWith(`/call/test/${callId}/ring_state`, {
+      call_session_id: 'ended-session',
+    });
+  });
+
+  it('returns the coordinator response', async () => {
+    const { call, get } = fakeCall('session-1');
+    get.mockResolvedValue(
+      fromPartial({
+        session_id: 'session-1',
+        accepted_by: { bob: '2026-08-24T10:00:04Z' },
+      }),
+    );
+
+    await expect(call.getRingState()).resolves.toMatchObject({
+      session_id: 'session-1',
+      accepted_by: { bob: '2026-08-24T10:00:04Z' },
+    });
+  });
+
+  it('rejects when the call has no session to read', async () => {
+    const { call, get } = fakeCall();
+
+    await expect(call.getRingState()).rejects.toThrow(
+      'Cannot read the ring state: the call has no session',
+    );
+    expect(get).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/Call.lifecycle.test.ts

@@ -79,6 +79,29 @@ describe('Call lifecycle wiring', () => {
     expect(audioBindingsOrder).toBeLessThan(dynascaleOrder);
   });
 
+  // `joinSource` is reporting-only: it must reach the event reporter and never
+  // the coordinator's join request.
+  it('call.join() reports joinSource without putting it on the wire', async () => {
+    vi.spyOn(call, 'setup').mockResolvedValue(undefined);
+    const doJoin = vi
+      .spyOn(call as unknown as { doJoin: Call['join'] }, 'doJoin')
+      .mockResolvedValue(undefined);
+    const withJoinLifecycle = vi.spyOn(
+      call.clientEventReporter,
+      'withJoinLifecycle',
+    );
+
+    await call.join({ joinSource: 'ring-poll-api', ring: true });
+
+    expect(withJoinLifecycle).toHaveBeenCalledWith(
+      call.cid,
+      { joinReason: 'first-attempt', joinSource: 'ring-poll-api' },
+      expect.any(Function),
+    );
+    expect(doJoin).toHaveBeenCalledTimes(1);
+    expect('joinSource' in doJoin.mock.calls[0][0]!).toBe(false);
+  });
+
   it('call.join() shares an in-flight join flow', async () => {
     const joinTask = promiseWithResolvers<void>();
     vi.spyOn(call, 'setup').mockResolvedValue(undefined);