@stream-io/video-client 1.58.0 → 1.59.0

package/src/__tests__/StreamVideoClient.rewatch.test.ts

@@ -0,0 +1,213 @@
+import '../rtc/__tests__/mocks/webrtc.mocks';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { StreamVideoClient } from '../StreamVideoClient';
+import { Call } from '../Call';
+import { CallRingPayload } from './data';
+import { settled, withoutConcurrency } from '../helpers/concurrency';
+import { getCallInitConcurrencyTag } from '../helpers/clientUtils';
+import { CallingState } from '../store';
+import type { StreamVideoEvent } from '../coordinator/connection/types';
+import type {
+  CallResponse,
+  ConnectedEvent,
+  GetCallResponse,
+  QueryCallsResponse,
+} from '../gen/coordinator';
+
+const apiKey = 'mock-api-key';
+// the receiver of the CallRingPayload fixture
+const userId = 'marcelo';
+
+const queryCallsResponse = (call: CallResponse): QueryCallsResponse => ({
+  duration: '1ms',
+  calls: [{ call, members: CallRingPayload.members, own_capabilities: [] }],
+});
+
+const countListeners = (client: StreamVideoClient) =>
+  Object.values(client.streamClient.listeners).reduce(
+    (count, listeners) => count + (listeners?.length ?? 0),
+    0,
+  );
+
+describe('StreamVideoClient re-watching calls on reconnect', () => {
+  let client: StreamVideoClient;
+
+  beforeEach(async () => {
+    client = new StreamVideoClient(apiKey, {
+      // tests run in node, so we have to fake being in browser env
+      browser: true,
+    });
+    client.streamClient.connectUser = vi.fn().mockResolvedValue({
+      me: { id: userId },
+    } as ConnectedEvent);
+    await client.connectUser({ id: userId }, 'mock-token');
+  });
+
+  afterEach(() => {
+    for (const call of client.state.calls) {
+      call['cancelAutoDrop']();
+    }
+    vi.restoreAllMocks();
+  });
+
+  const setupRingingCall = async () => {
+    vi.spyOn(client.streamClient, 'get').mockResolvedValue({
+      duration: '1ms',
+      call: CallRingPayload.call,
+      members: CallRingPayload.members,
+      own_capabilities: [],
+    } as GetCallResponse);
+
+    client.streamClient.dispatchEvent(CallRingPayload as StreamVideoEvent);
+    await settled(getCallInitConcurrencyTag(CallRingPayload.call_cid));
+
+    const [call] = client.state.calls;
+    expect(call).toBeDefined();
+    expect(call.watching).toBe(true);
+    expect(call.state.callingState).toBe(CallingState.RINGING);
+    return call;
+  };
+
+  const reconnect = () => {
+    client.streamClient.dispatchEvent({
+      type: 'connection.changed',
+      online: true,
+    });
+  };
+
+  it('reuses the registered instance and refreshes its state', async () => {
+    const call = await setupRingingCall();
+    const listenerCountBeforeReconnect = countListeners(client);
+
+    const post = vi
+      .spyOn(client.streamClient, 'post')
+      .mockResolvedValue(
+        queryCallsResponse({ ...CallRingPayload.call, recording: true }),
+      );
+
+    reconnect();
+
+    await vi.waitFor(() => expect(post).toHaveBeenCalled());
+    expect(post).toHaveBeenCalledWith('/calls', {
+      watch: true,
+      filter_conditions: { cid: { $in: [call.cid] } },
+    });
+
+    // the refreshed state must reach the instance the integrator holds
+    await vi.waitFor(() => expect(call.state.recording).toBe(true));
+    expect(client.state.calls).toHaveLength(1);
+    expect(client.state.calls[0]).toBe(call);
+    expect(call.watching).toBe(true);
+
+    // re-watching must not leak event handlers (one orphaned Call
+    // used to register its handlers on every reconnect)
+    expect(countListeners(client)).toBe(listenerCountBeforeReconnect);
+  });
+
+  it('drops a ringing call accepted elsewhere while the socket was down', async () => {
+    const call = await setupRingingCall();
+    const leave = vi.spyOn(call, 'leave').mockResolvedValue(undefined);
+
+    const session = CallRingPayload.call.session!;
+    vi.spyOn(client.streamClient, 'post').mockResolvedValue(
+      queryCallsResponse({
+        ...CallRingPayload.call,
+        session: {
+          ...session,
+          accepted_by: { [userId]: '2025-08-14T14:49:00Z' },
+        },
+      }),
+    );
+
+    reconnect();
+
+    // accepted on another device -> this device should stop ringing
+    await vi.waitFor(() => expect(leave).toHaveBeenCalled());
+  });
+
+  it('queryCalls returns an independent instance for registered calls', async () => {
+    // e.g. being on a call while watching a dashboard of calls:
+    // leaving the joined instance must not silence the dashboard instance
+    const joinedCall = await setupRingingCall();
+    vi.spyOn(client.streamClient, 'post').mockResolvedValue(
+      queryCallsResponse(CallRingPayload.call),
+    );
+
+    const result = await client.queryCalls({ watch: true });
+    const [dashboardCall] = result.calls;
+    expect(dashboardCall).not.toBe(joinedCall);
+    expect(client.state.calls[0]).toBe(joinedCall);
+
+    await joinedCall.leave({ reject: false });
+
+    client.streamClient.dispatchEvent({
+      type: 'call.updated',
+      call_cid: joinedCall.cid,
+      created_at: '2025-08-14T14:50:00Z',
+      call: { ...CallRingPayload.call, recording: true },
+    } as StreamVideoEvent);
+
+    await vi.waitFor(() => expect(dashboardCall.state.recording).toBe(true));
+  });
+
+  it('creates and registers a new instance for unknown cids', async () => {
+    vi.spyOn(client.streamClient, 'post').mockResolvedValue(
+      queryCallsResponse(CallRingPayload.call),
+    );
+
+    const result = await client.queryCalls({ watch: true });
+
+    expect(result.calls).toHaveLength(1);
+    const [call] = result.calls;
+    expect(call).toBeInstanceOf(Call);
+    expect(call.watching).toBe(true);
+    expect(client.state.calls[0]).toBe(call);
+  });
+
+  it('does not resurrect a call that leaves during a re-watch', async () => {
+    const listenersBeforeRing = countListeners(client);
+    const call = await setupRingingCall();
+    const post = vi
+      .spyOn(client.streamClient, 'post')
+      .mockResolvedValue(queryCallsResponse(CallRingPayload.call));
+
+    // hold the call's join/leave queue so leave() is still in flight
+    // while the re-watch response is being processed
+    let releaseGate!: () => void;
+    const gate = new Promise<void>((resolve) => (releaseGate = resolve));
+    withoutConcurrency(call['joinLeaveConcurrencyTag'], () => gate);
+    const leavePromise = call.leave({ reject: false });
+
+    reconnect();
+    await vi.waitFor(() => expect(post).toHaveBeenCalled());
+    await Promise.resolve();
+
+    releaseGate();
+    await leavePromise;
+
+    // the left call must stay dead: not re-registered, not re-initialized,
+    // and all of its event handlers released
+    expect(client.state.calls).toHaveLength(0);
+    expect(call.state.callingState).toBe(CallingState.LEFT);
+    expect(countListeners(client)).toBe(listenersBeforeRing);
+  });
+
+  it('creates a fresh instance when the previous one has left', async () => {
+    const call = await setupRingingCall();
+    const post = vi
+      .spyOn(client.streamClient, 'post')
+      .mockResolvedValue(queryCallsResponse(CallRingPayload.call));
+
+    // leaving unregisters the call from the client store
+    await call.leave({ reject: false });
+    expect(client.state.calls).toHaveLength(0);
+
+    const result = await client.queryCalls({ watch: true });
+    expect(post).toHaveBeenCalled();
+    expect(result.calls).toHaveLength(1);
+    expect(result.calls[0]).not.toBe(call);
+    expect(client.state.calls[0]).toBe(result.calls[0]);
+    expect(result.calls[0].watching).toBe(true);
+  });
+});

package/src/__tests__/StreamVideoClient.ringing.test.ts

@@ -45,12 +45,21 @@ describe('StreamVideoClient Ringing', () => {
     ]);
   };
 
+  const leaveAllCalls = async () => {
+    await Promise.all(
+      [oliverClient, sachaClient, marceloClient].flatMap((client) =>
+        client.state.calls.map((call) => call.leave().catch(() => {})),
+      ),
+    );
+  };
+
   beforeEach(async () => {
     [oliverClient, sachaClient, marceloClient] =
       await createClients(testUserIds);
   });
 
   afterEach(async () => {
+    await leaveAllCalls();
     await disconnectClients();
   });
 
@@ -275,6 +284,7 @@ describe('StreamVideoClient Ringing', () => {
     };
 
     it('should reject the call when the caller is busy', async () => {
+      await disconnectClients();
       [oliverClient, sachaClient, marceloClient] = await createClients(
         testUserIds,
         {
@@ -301,11 +311,10 @@ describe('StreamVideoClient Ringing', () => {
         marceloCall.cid,
       );
       expect(oliverClient.state.calls.length).toBe(1);
-
-      await disconnectClients();
     });
 
     it('should reject the call when the callee is busy', async () => {
+      await disconnectClients();
       [oliverClient, sachaClient, marceloClient] = await createClients(
         testUserIds,
         {
@@ -332,8 +341,6 @@ describe('StreamVideoClient Ringing', () => {
         marceloCall.cid,
       );
       expect(sachaClient.state.calls.length).toBe(1);
-
-      await disconnectClients();
     });
 
     it('should allow multiple simultaneous calls to the same caller when rejectCallWhenBusy is false', async () => {

package/src/__tests__/StreamVideoClient.test.ts

@@ -277,7 +277,7 @@ describe('StreamVideoClient.connectUser retries', () => {
 });
 
 describe('StreamVideoClient.watchCalls retries', () => {
-  it('should retry queryCalls up to 3 times after reconnecting', async () => {
+  it('should retry the re-watch request up to 3 times after reconnecting', async () => {
     vi.useFakeTimers();
     const client = new StreamVideoClient(apiKey, {
       browser: true,
@@ -290,8 +290,8 @@ describe('StreamVideoClient.watchCalls retries', () => {
     const call = client.call('default', generateUUIDv4());
     await call.getOrCreate();
 
-    const queryCallsSpy = vi
-      .spyOn(client, 'queryCalls')
+    const doQueryCalls = vi
+      .spyOn(client as any, 'doQueryCalls')
       .mockRejectedValueOnce(new Error('fail 1'))
       .mockRejectedValueOnce(new Error('fail 2'))
       .mockResolvedValue({
@@ -306,7 +306,7 @@ describe('StreamVideoClient.watchCalls retries', () => {
 
     await vi.runAllTimersAsync();
 
-    expect(queryCallsSpy).toHaveBeenCalledTimes(3);
+    expect(doQueryCalls).toHaveBeenCalledTimes(3);
 
     await client.disconnectUser();
 
@@ -327,8 +327,8 @@ describe('StreamVideoClient.watchCalls retries', () => {
     const call = client.call('default', generateUUIDv4());
     await call.getOrCreate();
 
-    const queryCallsSpy = vi
-      .spyOn(client, 'queryCalls')
+    const doQueryCalls = vi
+      .spyOn(client as any, 'doQueryCalls')
       .mockRejectedValueOnce(new Error('fail 1'))
       .mockRejectedValueOnce(new Error('fail 2'))
       .mockRejectedValueOnce(new Error('fail 3'))
@@ -344,7 +344,7 @@ describe('StreamVideoClient.watchCalls retries', () => {
 
     await vi.runAllTimersAsync();
 
-    expect(queryCallsSpy).toHaveBeenCalledTimes(3);
+    expect(doQueryCalls).toHaveBeenCalledTimes(3);
 
     await client.disconnectUser();
     vi.useRealTimers();
@@ -363,10 +363,12 @@ describe('StreamVideoClient.watchCalls retries', () => {
     const call = client.call('default', generateUUIDv4());
     await call.getOrCreate();
 
-    const queryCallsSpy = vi.spyOn(client, 'queryCalls').mockResolvedValue({
-      calls: [],
-      duration: '0ms',
-    });
+    const doQueryCalls = vi
+      .spyOn(client as any, 'doQueryCalls')
+      .mockResolvedValue({
+        calls: [],
+        duration: '0ms',
+      });
 
     client.streamClient.dispatchEvent({
       type: 'connection.changed',
@@ -375,7 +377,7 @@ describe('StreamVideoClient.watchCalls retries', () => {
 
     await vi.runAllTimersAsync();
 
-    expect(queryCallsSpy).toHaveBeenCalledTimes(1);
+    expect(doQueryCalls).toHaveBeenCalledTimes(1);
 
     await client.disconnectUser();
     vi.useRealTimers();

package/src/devices/CameraManager.ts

@@ -167,8 +167,13 @@ export class CameraManager extends DeviceManager<CameraManagerState> {
    *
    * @param settings the video settings to apply.
    * @param publish whether to publish the stream after applying the settings.
+   * @param forceDisabled whether to keep the camera disabled, regardless of server-side or local preferences.
    */
-  async apply(settings: VideoSettingsResponse, publish: boolean) {
+  async apply(
+    settings: VideoSettingsResponse,
+    publish: boolean,
+    forceDisabled: boolean = false,
+  ): Promise<void> {
     // Wait for any in progress camera operation
     await this.statusChangeSettled();
     await this.selectTargetResolution(settings.target_resolution);
@@ -186,8 +191,10 @@ export class CameraManager extends DeviceManager<CameraManagerState> {
       this.devicePersistence.enabled &&
       permissionState === 'granted'
     ) {
-      persistedPreferencesApplied =
-        await this.applyPersistedPreferences(enabledInCallType);
+      persistedPreferencesApplied = await this.applyPersistedPreferences(
+        enabledInCallType,
+        forceDisabled,
+      );
     }
 
     // apply a direction and enable the camera only if in "pristine" state,
@@ -199,7 +206,12 @@ export class CameraManager extends DeviceManager<CameraManagerState> {
         await this.selectDirection(direction, { enableCamera: false });
       }
 
-      if (canPublish && settings.camera_default_on && enabledInCallType) {
+      if (
+        !forceDisabled &&
+        canPublish &&
+        settings.camera_default_on &&
+        enabledInCallType
+      ) {
         await this.enable();
       }
     }

package/src/devices/DeviceManager.ts

@@ -842,7 +842,10 @@ export abstract class DeviceManager<
     writePreferences(currentDevice, deviceKey, muted, storageKey);
   }
 
-  protected async applyPersistedPreferences(enabledInCallType: boolean) {
+  protected async applyPersistedPreferences(
+    enabledInCallType: boolean,
+    forceDisabled = false,
+  ) {
     const deviceKey: DevicePreferenceKey =
       this.trackType === TrackType.AUDIO ? 'microphone' : 'camera';
     const preferences = readPreferences(this.devicePersistence.storageKey);
@@ -875,15 +878,15 @@ export abstract class DeviceManager<
 
     const canPublish = this.call.permissionsContext.canPublish(this.trackType);
     if (typeof muted === 'boolean' && enabledInCallType && canPublish) {
-      await this.applyMutedState(muted);
+      await this.applyMutedState(muted, forceDisabled);
       appliedMute = true;
     }
 
     return appliedDevice || appliedMute;
   }
 
-  private async applyMutedState(muted: boolean) {
-    if (this.state.status !== undefined) return;
+  private async applyMutedState(muted: boolean, forceDisabled: boolean) {
+    if (forceDisabled || this.state.status !== undefined) return;
     if (muted) {
       await this.disable();
     } else {

package/src/devices/MicrophoneManager.ts

@@ -388,8 +388,13 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
    * Applies the audio settings to the microphone.
    * @param settings the audio settings to apply.
    * @param publish whether to publish the stream after applying the settings.
+   * @param forceDisabled whether to keep the mic disabled, regardless of server-side or local preferences.
    */
-  async apply(settings: AudioSettingsResponse, publish: boolean) {
+  async apply(
+    settings: AudioSettingsResponse,
+    publish: boolean,
+    forceDisabled: boolean = false,
+  ) {
     // Wait for any in progress mic operation
     await this.statusChangeSettled();
 
@@ -407,12 +412,15 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
       this.devicePersistence.enabled &&
       permissionState === 'granted'
     ) {
-      persistedPreferencesApplied = await this.applyPersistedPreferences(true);
+      persistedPreferencesApplied = await this.applyPersistedPreferences(
+        true,
+        forceDisabled,
+      );
     }
 
     const canPublish = this.call.permissionsContext.canPublish(this.trackType);
     if (shouldApplyDefaults && !persistedPreferencesApplied) {
-      if (canPublish && settings.mic_default_on) {
+      if (!forceDisabled && canPublish && settings.mic_default_on) {
         await this.enable();
       }
     }

package/src/devices/__tests__/CameraManager.test.ts

@@ -357,11 +357,37 @@ describe('CameraManager', () => {
         true,
       );
 
-      expect(applySpy).toHaveBeenCalledWith(true);
+      expect(applySpy).toHaveBeenCalledWith(true, false);
       expect(selectDirectionSpy).not.toHaveBeenCalled();
       expect(enableSpy).not.toHaveBeenCalled();
     });
 
+    it('should apply persisted device preferences without enabling when forced disabled', async () => {
+      vi.spyOn(mockBrowserPermission, 'asStateObservable').mockReturnValue(
+        of('granted'),
+      );
+      const devicePersistence = { enabled: true, storageKey: '' };
+      const persistedManager = new CameraManager(call, devicePersistence);
+      const applySpy = vi
+        .spyOn(persistedManager as never, 'applyPersistedPreferences')
+        .mockResolvedValue(true);
+      const enableSpy = vi.spyOn(persistedManager, 'enable');
+
+      await persistedManager.apply(
+        fromPartial({
+          enabled: true,
+          target_resolution: { width: 640, height: 480 },
+          camera_facing: 'front',
+          camera_default_on: true,
+        }),
+        false,
+        true,
+      );
+
+      expect(applySpy).toHaveBeenCalledWith(true, true);
+      expect(enableSpy).not.toHaveBeenCalled();
+    });
+
     it('should skip persisted preferences when permission is not granted', async () => {
       vi.spyOn(mockBrowserPermission, 'asStateObservable').mockReturnValue(
         of('prompt'),

package/src/devices/__tests__/DeviceManager.test.ts

@@ -21,7 +21,7 @@ import { DeviceManagerState } from '../DeviceManagerState';
 import { firstValueFrom, of } from 'rxjs';
 import { TrackType } from '../../gen/video/sfu/models/models';
 import { PermissionsContext } from '../../permissions';
-import { readPreferences } from '../devicePersistence';
+import { defaultDeviceId, readPreferences } from '../devicePersistence';
 
 vi.mock('../../reporting/ClientEventReporter', () => ({
   ClientEventReporter: vi.fn(function () {
@@ -1010,6 +1010,54 @@ describe('Device Manager', () => {
       expect(selectSpy).toHaveBeenCalledWith(mockVideoDevices[1].deviceId);
     });
 
+    it('selects the device without unmuting when forced disabled', async () => {
+      localStorageMock.setItem(
+        storageKey,
+        JSON.stringify({
+          camera: [
+            {
+              selectedDeviceId: mockVideoDevices[0].deviceId,
+              selectedDeviceLabel: mockVideoDevices[0].label,
+              muted: false,
+            },
+          ],
+        }),
+      );
+
+      const selectSpy = vi.spyOn(manager, 'select');
+      const enableSpy = vi.spyOn(manager, 'enable');
+
+      // @ts-expect-error - private API
+      const result = await manager.applyPersistedPreferences(true, true);
+
+      expect(result).toBe(true);
+      expect(selectSpy).toHaveBeenCalledWith(mockVideoDevices[0].deviceId);
+      expect(enableSpy).not.toHaveBeenCalled();
+    });
+
+    it('retains a default-device mute preference when forced disabled', async () => {
+      localStorageMock.setItem(
+        storageKey,
+        JSON.stringify({
+          camera: [
+            {
+              selectedDeviceId: defaultDeviceId,
+              selectedDeviceLabel: '',
+              muted: false,
+            },
+          ],
+        }),
+      );
+
+      const enableSpy = vi.spyOn(manager, 'enable');
+
+      // @ts-expect-error - private API
+      const result = await manager.applyPersistedPreferences(true, true);
+
+      expect(result).toBe(true);
+      expect(enableSpy).not.toHaveBeenCalled();
+    });
+
     it('applies muted state without selecting when default device is stored', async () => {
       localStorageMock.setItem(
         storageKey,

package/src/devices/__tests__/MicrophoneManager.test.ts

@@ -486,7 +486,29 @@ describe('MicrophoneManager', () => {
       // @ts-expect-error - partial data
       await persistedManager.apply({ mic_default_on: true }, true);
 
-      expect(applySpy).toHaveBeenCalledWith(true);
+      expect(applySpy).toHaveBeenCalledWith(true, false);
+      expect(enableSpy).not.toHaveBeenCalled();
+    });
+
+    it('should apply persisted device preferences without enabling when forced disabled', async () => {
+      vi.spyOn(mockBrowserPermission, 'asStateObservable').mockReturnValue(
+        of('granted'),
+      );
+      const devicePersistence = { enabled: true, storageKey: '' };
+      const persistedManager = new MicrophoneManager(
+        call,
+        devicePersistence,
+        'disable-tracks',
+      );
+      const applySpy = vi
+        .spyOn(persistedManager as never, 'applyPersistedPreferences')
+        .mockResolvedValue(true);
+      const enableSpy = vi.spyOn(persistedManager, 'enable');
+
+      // @ts-expect-error - partial data
+      await persistedManager.apply({ mic_default_on: true }, false, true);
+
+      expect(applySpy).toHaveBeenCalledWith(true, true);
       expect(enableSpy).not.toHaveBeenCalled();
     });
 

package/src/events/call.ts

@@ -81,7 +81,6 @@ export const watchCallRejected = (call: Call) => {
  */
 export const watchCallEnded = (call: Call) => {
   return function onCallEnded() {
-    globalThis.streamRNVideoSDK?.callingX?.endCall(call, 'remote');
     const { callingState } = call.state;
     if (
       callingState !== CallingState.IDLE &&
@@ -92,9 +91,13 @@ export const watchCallEnded = (call: Call) => {
         reason: 'call.ended event received',
       });
       call
-        .leave({ message: 'call.ended event received', reject: false })
+        .leave({
+          message: 'call.ended event received',
+          reject: false,
+          reason: 'ended',
+        })
         .catch((err) => {
-          call.logger.error('Failed to leave call after call.ended ', err);
+          call.logger.error('Failed to leave call after call.ended', err);
         });
     }
   };

package/src/gen/coordinator/index.ts

@@ -8468,6 +8468,32 @@ export interface ReportByHistogramBucket {
    */
   upper_bound?: Bound;
 }
+/**
+ * Reports a batch of client-side telemetry events. Each event is validated and processed independently; one invalid event does not block the rest of the batch.
+ * @export
+ * @interface ReportClientEventRequest
+ */
+export interface ReportClientEventRequest {
+  /**
+   * Client-side events to report (1-100 per request)
+   * @type {Array<ClientEvent>}
+   * @memberof ReportClientEventRequest
+   */
+  events: Array<ClientEvent>;
+}
+/**
+ * Response for reporting client-side telemetry events
+ * @export
+ * @interface ReportClientEventResponse
+ */
+export interface ReportClientEventResponse {
+  /**
+   * Duration of the request in milliseconds
+   * @type {string}
+   * @memberof ReportClientEventResponse
+   */
+  duration: string;
+}
 /**
  *
  * @export