@stream-io/video-client 2.0.0-beta.0 → 2.0.0-beta.1

package/src/store/ClientState.ts

@@ -0,0 +1,101 @@
+import { getCurrentValue, type Patch, setCurrentValue } from './rxUtils';
+import { subject } from './subjects';
+import type { Call } from '../Call';
+import type { OwnUserResponse } from '../gen/coordinator';
+import { videoLoggerSystem } from '../logger';
+
+/**
+ * Holds the state of the client, and the calls it created or tracks.
+ * You can subscribe to the exposed observables to get notified about changes.
+ */
+export class ClientState {
+  readonly logger = videoLoggerSystem.getLogger('ClientState');
+
+  private connectedUserSubject = subject<OwnUserResponse>();
+  private callsSubject = subject<Call[]>([]);
+
+  /** Data describing a user successfully connected over WS to the coordinator. */
+  connectedUser$ = this.connectedUserSubject.asObservable();
+
+  /** A list of {@link Call} objects created/tracked by this client. */
+  calls$ = this.callsSubject.asObservable();
+
+  /** The currently connected user. */
+  get connectedUser() {
+    return getCurrentValue(this.connectedUserSubject);
+  }
+
+  /** A list of {@link Call} objects created/tracked by this client. */
+  get calls() {
+    return getCurrentValue(this.callsSubject);
+  }
+
+  /**
+   * Sets the currently connected user.
+   *
+   * @internal
+   * @param user the user to set as connected.
+   */
+  setConnectedUser = (user: Patch<OwnUserResponse | undefined>) => {
+    return setCurrentValue(this.connectedUserSubject, user);
+  };
+
+  /**
+   * Sets the list of {@link Call} objects created/tracked by this client.
+   *
+   * @internal
+   * @param calls the calls to set.
+   */
+  setCalls = (calls: Patch<Call[]>) => {
+    return setCurrentValue(this.callsSubject, calls);
+  };
+
+  /**
+   * Adds a {@link Call} object to the list of calls tracked by this client.
+   *
+   * @internal
+   * @param call the call to add.
+   */
+  registerCall = (call: Call) => {
+    if (!this.calls.find((c) => c.cid === call.cid)) {
+      this.setCalls((calls) => [...calls, call]);
+    }
+  };
+
+  /**
+   * Registers a {@link Call} object if it doesn't exist, otherwise updates it.
+   *
+   * @internal
+   * @param call the call to register or update.
+   */
+  registerOrUpdateCall = (call: Call) => {
+    if (this.calls.find((c) => c.cid === call.cid)) {
+      return this.setCalls((calls) =>
+        calls.map((c) => (c.cid === call.cid ? call : c)),
+      );
+    } else {
+      return this.registerCall(call);
+    }
+  };
+
+  /**
+   * Removes a {@link Call} object from the list of calls tracked by this client.
+   *
+   * @internal
+   * @param call the call to remove.
+   */
+  unregisterCall = (call: Call) => {
+    this.logger.trace(`Unregistering call: ${call.cid}`);
+    return this.setCalls((calls) => calls.filter((c) => c !== call));
+  };
+
+  /**
+   * Finds a {@link Call} object in the list of calls tracked by this client.
+   *
+   * @param type the type of call to find.
+   * @param id the id of the call to find.
+   */
+  findCall = (type: string, id: string) => {
+    return this.calls.find((c) => c.type === type && c.id === id);
+  };
+}

package/src/store/__tests__/CallState.test.ts

@@ -24,6 +24,7 @@ import {
   CallAcceptedEvent,
   CallEndedEvent,
   CallUpdatedEvent,
+  type GetCallRingStateResponse,
   MemberResponse,
   OwnCapability,
 } from '../../gen/coordinator';
@@ -47,7 +48,7 @@ describe('CallState', () => {
           getter,
           `A getter for ${observable} is missing. Please define it like this:
           get ${key}() {
-            return this.getCurrentValue(this.${observable});
+            return getCurrentValue(this.${observable});
           }
           `,
         ).toBeDefined();
@@ -1474,4 +1475,62 @@ describe('CallState', () => {
       expect(state['closedCaptionsTasks'].size).toBe(0);
     });
   });
+
+  describe('updateFromRingState', () => {
+    const ringState = fromPartial<GetCallRingStateResponse>({
+      session_id: 'session-1',
+      accepted_by: { bob: '2026-08-24T10:00:04Z' },
+      rejected_by: { carol: '2026-08-24T10:00:09Z' },
+      missed_by: { dave: '2026-08-24T10:00:35Z' },
+    });
+
+    const withSession = (id: string) => {
+      const state = new CallState();
+      state['sessionSubject'].next(
+        fromPartial({
+          id,
+          accepted_by: {},
+          rejected_by: {},
+          missed_by: {},
+          participants: [fromPartial({ user_session_id: 'p1' })],
+        }),
+      );
+      return state;
+    };
+
+    it('merges the ring maps into the current session', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.accepted_by).toEqual(ringState.accepted_by);
+      expect(state.session?.rejected_by).toEqual(ringState.rejected_by);
+      expect(state.session?.missed_by).toEqual(ringState.missed_by);
+    });
+
+    it('leaves the session roster untouched', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.participants).toHaveLength(1);
+    });
+
+    it('ignores a ring state that belongs to another session', () => {
+      const state = withSession('session-2');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.accepted_by).toEqual({});
+    });
+
+    it('applies the end timestamps', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState({
+        ...ringState,
+        session_ended_at: '2026-08-24T10:01:00Z',
+        call_ended_at: '2026-08-24T10:01:00Z',
+      });
+
+      expect(state.session?.ended_at).toBe('2026-08-24T10:01:00Z');
+      expect(state.endedAt).toEqual(new Date('2026-08-24T10:01:00Z'));
+    });
+  });
 });

package/src/store/__tests__/ClientState.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { ClientState } from '../ClientState';
+
+describe('ClientState', () => {
+  describe('API assertions', () => {
+    it('every exposed observable$ should have a getter', () => {
+      const state = new ClientState();
+      const observables = Object.keys(
+        Object.getOwnPropertyDescriptors(state),
+      ).filter((key) => key.endsWith('$'));
+
+      // the observables must stay own enumerable properties: consumers walk
+      // `Object.entries(client.state)` to collect the current state.
+      expect(observables).toContain('connectedUser$');
+      expect(observables).toContain('calls$');
+
+      // @ts-expect-error - __proto__
+      const getters = Object.getOwnPropertyDescriptors(state.__proto__);
+
+      for (const observable of observables) {
+        const key = observable.slice(0, -1); // remove $
+        const getter = getters[key];
+        expect(
+          getter,
+          `A getter for ${observable} is missing. Please define it like this:
+          get ${key}() {
+            return getCurrentValue(this.${key}Subject);
+          }
+          `,
+        ).toBeDefined();
+        expect(typeof getter.get).toEqual('function');
+      }
+    });
+  });
+});

package/src/store/__tests__/rxUtils.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it, vi } from 'vitest';
-import { BehaviorSubject, Subject, throwError } from 'rxjs';
+import {
+  AsyncSubject,
+  BehaviorSubject,
+  EMPTY,
+  of,
+  ReplaySubject,
+  Subject,
+  throwError,
+} from 'rxjs';
 import { promiseWithResolvers } from '../../helpers/promise';
 import {
   createSafeAsyncSubscription,
@@ -26,6 +34,64 @@ describe('getCurrentValue', () => {
     const err = new Error('observable failed');
     expect(() => getCurrentValue(throwError(() => err))).toThrow(err);
   });
+
+  it('rethrows the error of an errored BehaviorSubject', () => {
+    const err = new Error('subject failed');
+    const subject = new BehaviorSubject(7);
+    subject.error(err);
+    expect(() => getCurrentValue(subject)).toThrow(err);
+  });
+
+  it('throws when the BehaviorSubject has been unsubscribed', () => {
+    const subject = new BehaviorSubject(7);
+    subject.unsubscribe();
+    expect(() => getCurrentValue(subject)).toThrow(/unsubscribed/);
+  });
+
+  it('still reads the value of a completed BehaviorSubject', () => {
+    // A completed BehaviorSubject keeps holding its value, and we read that
+    // value directly. Subscribing instead would yield nothing, because RxJS
+    // doesn't replay to subscribers of a stopped subject.
+    const subject = new BehaviorSubject(7);
+    subject.complete();
+    expect(getCurrentValue(subject)).toBe(7);
+  });
+
+  it('returns undefined for a Subject that has not emitted', () => {
+    expect(getCurrentValue(new Subject<number>())).toBeUndefined();
+    expect(getCurrentValue(EMPTY)).toBeUndefined();
+  });
+
+  it('returns the last buffered value of a ReplaySubject', () => {
+    const subject = new ReplaySubject<string>(1);
+    subject.next('a');
+    subject.next('b');
+    expect(getCurrentValue(subject)).toBe('b');
+
+    const buffered = new ReplaySubject<string>(2);
+    buffered.next('a');
+    buffered.next('b');
+    expect(getCurrentValue(buffered)).toBe('b');
+  });
+
+  it('still reads a completed ReplaySubject, which does replay', () => {
+    const subject = new ReplaySubject<string>(1);
+    subject.next('z');
+    subject.complete();
+    expect(getCurrentValue(subject)).toBe('z');
+  });
+
+  it('reads the value an AsyncSubject emitted on completion', () => {
+    const pending = new AsyncSubject<string>();
+    pending.next('q');
+    expect(getCurrentValue(pending)).toBeUndefined();
+    pending.complete();
+    expect(getCurrentValue(pending)).toBe('q');
+  });
+
+  it('returns the last synchronous emission, not the first', () => {
+    expect(getCurrentValue(of(1, 2, 3))).toBe(3);
+  });
 });
 
 describe('setCurrentValue', () => {

package/src/store/index.ts

@@ -1,4 +1,4 @@
 export * as RxUtils from './rxUtils';
 export * from './CallingState';
-export * from './stateStore';
+export * from './ClientState';
 export * from './CallState';

package/src/store/rxUtils.ts

@@ -1,4 +1,4 @@
-import { BehaviorSubject, combineLatest, Observable, Subject } from 'rxjs';
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
 import { withoutConcurrency } from '../helpers/concurrency';
 import { videoLoggerSystem } from '../logger';
 
@@ -39,12 +39,16 @@ const isFunctionPatch = <T>(update: Patch<T>): update is FunctionPatch<T> =>
  *
  * @param observable$ the observable to get the value from.
  */
-export const getCurrentValue = <T>(observable$: Observable<T>) => {
+export const getCurrentValue = <T>(observable$: Observable<T>): T => {
+  if (observable$ instanceof BehaviorSubject) {
+    return (observable$ as BehaviorSubject<T>).getValue();
+  }
+
   let value!: T;
   let err: Error | undefined = undefined;
-  combineLatest([observable$])
+  observable$
     .subscribe({
-      next: ([v]) => {
+      next: (v) => {
         value = v;
       },
       error: (e) => {

package/src/store/subjects.ts

@@ -0,0 +1,30 @@
+import {
+  BehaviorSubject,
+  distinctUntilChanged,
+  Observable,
+  shareReplay,
+} from 'rxjs';
+
+/** Creates a BehaviorSubject seeded with the given value. */
+export function subject<T>(initialValue: T): BehaviorSubject<T>;
+/** Creates a BehaviorSubject which starts out holding `undefined`. */
+export function subject<T>(): BehaviorSubject<T | undefined>;
+export function subject<T>(initialValue?: T) {
+  return new BehaviorSubject(initialValue);
+}
+
+/**
+ * Creates an Observable from the given subject by piping it to the
+ * `distinctUntilChanged()` operator.
+ */
+export const duc = <T>(
+  source: BehaviorSubject<T>,
+  comparator?: (a: T, b: T) => boolean,
+): Observable<T> => source.pipe(distinctUntilChanged(comparator));
+
+/**
+ * Multicasts the given Observable, replaying the latest computed value to
+ * every new subscriber instead of re-running the pipeline for each of them.
+ */
+export const shared = <T>(source: Observable<T>): Observable<T> =>
+  source.pipe(shareReplay({ bufferSize: 1, refCount: true }));

package/src/store/types.ts

@@ -0,0 +1,45 @@
+import type { VideoEvent } from '../gen/coordinator';
+
+/** Handles a single video event of the given type. */
+export type EventHandler<T extends VideoEvent['type']> = (
+  event: Extract<VideoEvent, { type: T }>,
+) => void;
+
+/**
+ * Identity type constrained to real event names, so that a name which no
+ * longer exists in `VideoEvent` fails to compile instead of being ignored.
+ */
+type EventTypes<T extends VideoEvent['type']> = T;
+
+/**
+ * Events that intentionally leave the call state untouched. Listing a name
+ * here excuses it from `CallStateEventHandlers`, which is what makes a newly
+ * introduced event fail to compile until it has been triaged.
+ */
+type UnhandledEventType = EventTypes<
+  | 'call.frame_recording_ready'
+  | 'call.kicked_user'
+  | 'call.moderation_blur'
+  | 'call.moderation_warning'
+  | 'call.permission_request'
+  | 'call.recording_ready'
+  | 'call.rtmp_broadcast_failed'
+  | 'call.rtmp_broadcast_started'
+  | 'call.rtmp_broadcast_stopped'
+  | 'call.stats_report_ready'
+  | 'call.transcription_ready'
+  | 'call.user_feedback_submitted'
+  | 'call.user_muted'
+  | 'connection.error'
+  | 'connection.ok'
+  | 'health.check'
+  | 'user.updated'
+  | 'custom'
+>;
+
+export type AllEventHandlers = {
+  [T in VideoEvent['type']]: EventHandler<T>;
+};
+
+/** A handler for every event that does update the call state. */
+export type CallStateEventHandlers = Omit<AllEventHandlers, UnhandledEventType>;

package/src/types.ts

@@ -22,7 +22,7 @@ import type {
   User,
 } from './coordinator/connection/types';
 import type { Comparator } from './sorting';
-import type { StreamVideoWriteableStateStore } from './store';
+import type { ClientState } from './store';
 import { AxiosError } from 'axios';
 import type { Call } from './Call';
 
@@ -357,9 +357,9 @@ export type CallConstructor = {
   sortParticipantsBy?: Comparator<StreamVideoParticipant>;
 
   /**
-   * The state store of the client
+   * The state of the client.
    */
-  clientStore: StreamVideoWriteableStateStore;
+  clientState: ClientState;
 };
 
 type StreamVideoClientBaseOptions = {
@@ -458,7 +458,17 @@ type StreamRNVideoSDKEndCallReason =
   | 'unknown';
 
 type StreamRNVideoSDKCallingX = {
-  joinCall: (call: Call, activeCalls: Call[]) => Promise<void>;
+  /**
+   * @param isCancelled - polled around the bridge's waits: registration is
+   *   skipped, or undone, when it returns true. Supplied by the join attempt
+   *   because the call's own state cannot distinguish a fresh join starting
+   *   from `LEFT` from an abandoned one that reached `LEFT` while waiting.
+   */
+  joinCall: (
+    call: Call,
+    activeCalls: Call[],
+    isCancelled?: () => boolean,
+  ) => Promise<void>;
   endCall: (
     call: Call,
     reason?: StreamRNVideoSDKEndCallReason,
@@ -468,8 +478,34 @@ type StreamRNVideoSDKCallingX = {
   unwireAudioEngineSubscription: () => void;
 };
 
+/**
+ * React Native's preparation and cleanup for a ringing call's join.
+ *
+ * A ringing call is joined by the SDK rather than by app code, so there is no
+ * point at which the app holds the call and can still set it up. These are that
+ * point, and the matching release.
+ */
+type StreamRNVideoSDKRingingCallLifecycle = {
+  /**
+   * Runs the app's pre-join setup and resolves once it is done, bounded by a
+   * deadline. Rejecting fails the join closed rather than joining with nothing
+   * installed.
+   */
+  beforeJoin: (call: Call) => Promise<void>;
+
+  /**
+   * The join failed terminally. Ends the ringing flow and releases what the
+   * setup installed. Never rejects, so the original join error survives.
+   */
+  onJoinFailed: (call: Call) => Promise<void>;
+
+  /** The call has ended; release whatever the pre-join hook installed. */
+  onLeave: (call: Call) => void;
+};
+
 export type StreamRNVideoSDKGlobals = {
   callingX: StreamRNVideoSDKCallingX;
+  ringingCallLifecycle: StreamRNVideoSDKRingingCallLifecycle;
   callManager: {
     /**
      * Sets up the in call manager.

package/dist/src/store/stateStore.d.ts

@@ -1,84 +0,0 @@
-import { BehaviorSubject, Observable } from 'rxjs';
-import type { Patch } from './rxUtils';
-import { Call } from '../Call';
-import type { OwnUserResponse } from '../gen/coordinator';
-export declare class StreamVideoWriteableStateStore {
-    /**
-     * A store keeping data of a successfully connected user over WS to the coordinator server.
-     */
-    connectedUserSubject: BehaviorSubject<OwnUserResponse | undefined>;
-    /**
-     * A list of {@link Call} objects created/tracked by this client.
-     */
-    callsSubject: BehaviorSubject<Call[]>;
-    constructor();
-    /**
-     * The currently connected user.
-     */
-    get connectedUser(): OwnUserResponse | undefined;
-    /**
-     * Sets the currently connected user.
-     *
-     * @internal
-     * @param user the user to set as connected.
-     */
-    setConnectedUser: (user: Patch<OwnUserResponse | undefined>) => OwnUserResponse | undefined;
-    /**
-     * A list of {@link Call} objects created/tracked by this client.
-     */
-    get calls(): Call[];
-    /**
-     * Sets the list of {@link Call} objects created/tracked by this client.
-     * @param calls
-     */
-    setCalls: (calls: Patch<Call[]>) => Call[];
-    /**
-     * Adds a {@link Call} object to the list of {@link Call} objects created/tracked by this client.
-     *
-     * @param call the call to add.
-     */
-    registerCall: (call: Call) => void;
-    /**
-     * Registers a {@link Call} object if it doesn't exist, otherwise updates it.
-     *
-     * @param call the call to register or update.
-     */
-    registerOrUpdateCall: (call: Call) => void | Call[];
-    /**
-     * Removes a {@link Call} object from the list of {@link Call} objects created/tracked by this client.
-     *
-     * @param call the call to remove
-     */
-    unregisterCall: (call: Call) => Call[];
-    /**
-     * Finds a {@link Call} object in the list of {@link Call} objects created/tracked by this client.
-     *
-     * @param type the type of call to find.
-     * @param id the id of the call to find.
-     */
-    findCall: (type: string, id: string) => Call | undefined;
-}
-/**
- * A reactive store that exposes state variables in a reactive manner.
- * You can subscribe to changes of the different state variables.
- * This central store contains all the state variables related to [`StreamVideoClient`](./StreamVideClient.md) and [`Call`](./Call.md).
- */
-export declare class StreamVideoReadOnlyStateStore {
-    /**
-     * Data describing a user successfully connected over WS to coordinator server.
-     */
-    connectedUser$: Observable<OwnUserResponse | undefined>;
-    /**
-     * A list of {@link Call} objects created/tracked by this client.
-     */
-    calls$: Observable<Call[]>;
-    constructor(store: StreamVideoWriteableStateStore);
-    /**
-     * The current user connected over WS to the backend.
-     */
-    get connectedUser(): OwnUserResponse | undefined;
-    /**
-     * A list of {@link Call} objects created/tracked by this client.
-     */
-    get calls(): Call[];
-}