@stream-io/video-client 1.59.1 → 1.60.0

package/dist/src/Call.d.ts

@@ -2,11 +2,11 @@ import { type CallMediaEngine, Publisher, Subscriber, TrackPublishOptions } from
 import type { E2EEManager } from './rtc/e2ee/E2EEManager';
 import { CallState } from './store';
 import { ScopedLogger } from './logger';
-import { AcceptCallResponse, BlockUserResponse, CallRingEvent, CallSettingsResponse, CallStateResponseFields, CollectUserFeedbackRequest, CollectUserFeedbackResponse, DeleteCallRequest, DeleteCallResponse, DeleteRecordingResponse, DeleteTranscriptionResponse, EndCallResponse, GetCallReportResponse, GetCallResponse, GetCallSessionParticipantStatsDetailsResponse, GetOrCreateCallRequest, GetOrCreateCallResponse, GoLiveRequest, GoLiveResponse, JoinCallResponse, KickUserRequest, KickUserResponse, ListRecordingsResponse, ListTranscriptionsResponse, MuteUsersResponse, PinRequest, PinResponse, QueryCallMembersRequest, QueryCallMembersResponse, QueryCallParticipantsRequest, QueryCallParticipantsResponse, QueryCallSessionParticipantStatsResponse, QueryCallSessionParticipantStatsTimelineResponse, QueryCallStatsMapResponse, RejectCallResponse, RequestPermissionRequest, RequestPermissionResponse, RingCallRequest, RingCallResponse, SendCallEventResponse, SendVideoReactionRequest, SendVideoReactionResponse, StartClosedCaptionsRequest, StartClosedCaptionsResponse, StartFrameRecordingRequest, StartFrameRecordingResponse, StartHLSBroadcastingResponse, StartRTMPBroadcastsRequest, StartRTMPBroadcastsResponse, StartTranscriptionRequest, StartTranscriptionResponse, StopAllRTMPBroadcastsResponse, StopClosedCaptionsRequest, StopClosedCaptionsResponse, StopFrameRecordingResponse, StopHLSBroadcastingResponse, StopLiveRequest, StopLiveResponse, StopRecordingResponse, StopRTMPBroadcastsResponse, StopTranscriptionResponse, UnblockUserResponse, UnpinRequest, UnpinResponse, UpdateCallMembersRequest, UpdateCallMembersResponse, UpdateCallRequest, UpdateCallResponse, UpdateUserPermissionsRequest, UpdateUserPermissionsRequestGrantPermissionsEnum, UpdateUserPermissionsRequestRevokePermissionsEnum, UpdateUserPermissionsResponse } from './gen/coordinator';
+import { AcceptCallResponse, BlockUserResponse, CallRingEvent, CallSettingsResponse, CallStateResponseFields, CollectUserFeedbackRequest, CollectUserFeedbackResponse, DeleteCallRequest, DeleteCallResponse, DeleteRecordingResponse, DeleteTranscriptionResponse, EndCallResponse, GetCallReportResponse, GetCallResponse, GetCallRingStateResponse, GetCallSessionParticipantStatsDetailsResponse, GetOrCreateCallRequest, GetOrCreateCallResponse, GoLiveRequest, GoLiveResponse, JoinCallResponse, KickUserRequest, KickUserResponse, ListRecordingsResponse, ListTranscriptionsResponse, MuteUsersResponse, PinRequest, PinResponse, QueryCallMembersRequest, QueryCallMembersResponse, QueryCallParticipantsRequest, QueryCallParticipantsResponse, QueryCallSessionParticipantStatsResponse, QueryCallSessionParticipantStatsTimelineResponse, QueryCallStatsMapResponse, RejectCallResponse, RequestPermissionRequest, RequestPermissionResponse, RingCallRequest, RingCallResponse, SendCallEventResponse, SendVideoReactionRequest, SendVideoReactionResponse, StartClosedCaptionsRequest, StartClosedCaptionsResponse, StartFrameRecordingRequest, StartFrameRecordingResponse, StartHLSBroadcastingResponse, StartRTMPBroadcastsRequest, StartRTMPBroadcastsResponse, StartTranscriptionRequest, StartTranscriptionResponse, StopAllRTMPBroadcastsResponse, StopClosedCaptionsRequest, StopClosedCaptionsResponse, StopFrameRecordingResponse, StopHLSBroadcastingResponse, StopLiveRequest, StopLiveResponse, StopRecordingResponse, StopRTMPBroadcastsResponse, StopTranscriptionResponse, UnblockUserResponse, UnpinRequest, UnpinResponse, UpdateCallMembersRequest, UpdateCallMembersResponse, UpdateCallRequest, UpdateCallResponse, UpdateUserPermissionsRequest, UpdateUserPermissionsRequestGrantPermissionsEnum, UpdateUserPermissionsRequestRevokePermissionsEnum, UpdateUserPermissionsResponse } from './gen/coordinator';
 import { AudioTrackType, CallConstructor, CallLeaveOptions, CallRecordingType, ClientPublishOptions, ClosedCaptionsSettings, JoinCallData, StartCallRecordingFnType, TrackMuteType, VideoTrackType } from './types';
 import { ClientCapability, TrackType, VideoDimension } from './gen/video/sfu/models/models';
 import { Tracer } from './stats';
-import type { ClientEventReporter } from './reporting';
+import type { ClientEventReporter, JoinSource } from './reporting';
 import { AudioBindingsWatchdog } from './helpers/AudioBindingsWatchdog';
 import { BlockedAudioTracker } from './helpers/BlockedAudioTracker';
 import { TrackSubscriptionManager } from './helpers/TrackSubscriptionManager';
@@ -107,7 +107,8 @@ export declare class Call {
     private statsReporter?;
     private sfuStatsReporter?;
     private lastStatsOptions?;
-    private dropTimeout;
+    private ringTimeout;
+    private ringStatePoller;
     private readonly clientStore;
     readonly streamClient: StreamClient;
     readonly clientEventReporter: ClientEventReporter;
@@ -265,6 +266,15 @@ export declare class Call {
      * All users should be members of the call.
      */
     ring: (data?: RingCallRequest) => Promise<RingCallResponse>;
+    /**
+     * 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: (callSessionId?: string) => Promise<GetCallRingStateResponse>;
     /**
      * A shortcut for {@link Call.get} with `notify` parameter set to `true`.
      * Will send a `call.notification` event to the call members.
@@ -298,6 +308,7 @@ export declare class Call {
         joinResponseTimeout?: number;
         rpcRequestTimeout?: number;
         allowOwnTracksLoopback?: boolean;
+        joinSource?: JoinSource;
     }) | undefined) => Promise<void>;
     /**
      * Will make a single attempt to watch for call related WebSocket events
@@ -769,6 +780,15 @@ export declare class Call {
      * Cancels a scheduled auto-drop timeout.
      */
     private cancelAutoDrop;
+    /**
+     * Starts polling for the ring outcome. Applicable only to ringing calls the
+     * current user created.
+     */
+    private scheduleRingStatePolling;
+    /**
+     * Cancels the ring state polling.
+     */
+    private cancelRingStatePolling;
     /**
      * Retrieves the list of recordings for the current call or call session.
      *

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

@@ -136,6 +136,16 @@ export type AllClientCallEvents = {
 export type AllCallEvents = AllClientCallEvents & AllSfuEvents;
 export type CallEventListener<E extends keyof AllCallEvents> = (event: AllCallEvents[E]) => void;
 export type Logger = (logLevel: LogLevel, message: string, ...args: unknown[]) => void;
+export type RingStatePollingOptions = {
+    /**
+     * Quiet time after the ring starts, before the first poll. Defaults to 15_000.
+     */
+    startAfterMs?: number;
+    /**
+     * The interval between polls. Defaults to 5_000.
+     */
+    intervalMs?: number;
+};
 export type StreamClientOptions = Partial<AxiosRequestConfig> & {
     /**
      * Used to disable warnings that are triggered by using connectUser or connectAnonymousUser server-side.
@@ -227,6 +237,12 @@ export type StreamClientOptions = Partial<AxiosRequestConfig> & {
      * When set to true, the incoming calls are rejected when the user is busy in an another call.
      */
     rejectCallWhenBusy?: boolean;
+    /**
+     * Caller-side polling for the ring outcome, used when the `call.accepted`,
+     * `call.rejected` or `call.missed` event never arrives. Enabled by default;
+     * set to `false` to disable, or pass an object to tune the timings.
+     */
+    ringStatePolling?: false | RingStatePollingOptions;
     /**
      * Device persistence preference options (web only).
      */

package/dist/src/events/call.d.ts

@@ -1,15 +1,4 @@
 import { Call } from '../Call';
-import { CallAcceptedEvent, CallRejectedEvent } from '../gen/coordinator';
-/**
- * Event handler that watched the delivery of `call.accepted`.
- * Once the event is received, the call is joined.
- */
-export declare const watchCallAccepted: (call: Call) => (event: CallAcceptedEvent) => Promise<void>;
-/**
- * Event handler that watches delivery of `call.rejected` Websocket event.
- * Once the event is received, the call is left.
- */
-export declare const watchCallRejected: (call: Call) => (event: CallRejectedEvent) => Promise<void>;
 /**
  * Event handler that watches the delivery of `call.ended` Websocket event.
  */

package/dist/src/gen/coordinator/index.d.ts

@@ -5133,6 +5133,79 @@ export interface GetCallResponse {
      */
     own_capabilities: Array<OwnCapability>;
 }
+/**
+ * The ring state of a call session: who accepted, rejected, or missed the ring.
+ * @export
+ * @interface GetCallRingStateResponse
+ */
+export interface GetCallRingStateResponse {
+    /**
+     * Users that accepted the call, mapped to when they accepted
+     * @type {{ [key: string]: string; }}
+     * @memberof GetCallRingStateResponse
+     */
+    accepted_by: {
+        [key: string]: string;
+    };
+    /**
+     * The CID of the call
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    call_cid: string;
+    /**
+     * When the call ended
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    call_ended_at?: string;
+    /**
+     * The user that created the call, i.e. the caller
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    created_by_user_id: string;
+    /**
+     * Duration of the request in milliseconds
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    duration: string;
+    /**
+     * Users that missed the call, mapped to when they were marked as missed
+     * @type {{ [key: string]: string; }}
+     * @memberof GetCallRingStateResponse
+     */
+    missed_by: {
+        [key: string]: string;
+    };
+    /**
+     * Users that rejected the call, mapped to when they rejected
+     * @type {{ [key: string]: string; }}
+     * @memberof GetCallRingStateResponse
+     */
+    rejected_by: {
+        [key: string]: string;
+    };
+    /**
+     * When the call session ended
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    session_ended_at?: string;
+    /**
+     * The call session this state belongs to, empty when the call has never rung
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    session_id: string;
+    /**
+     * When the call session started
+     * @type {string}
+     * @memberof GetCallRingStateResponse
+     */
+    session_started_at?: string;
+}
 /**
  * Basic response information
  * @export

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

@@ -6,6 +6,12 @@ export type ClientEventStage = 'JoinInitiated' | 'CoordinatorWS' | 'MediaDeviceP
 export type MediaPermissionState = 'INITIATED' | 'FAILED' | 'GRANTED' | 'NOT_INITIATED';
 export type ReportedIceState = 'CONNECTED' | 'FAILED' | 'NOT_CONNECTED';
 export type JoinReason = 'first-attempt' | 'network-available' | 'migration' | 'full-rejoin';
+/**
+ * What triggered an automatic join, reported as `source` on the call's
+ * CoordinatorJoin events. `ring-ws` is a ring WebSocket event, `ring-poll-api`
+ * is the ring state poller.
+ */
+export type JoinSource = 'ring-ws' | 'ring-poll-api';
 export type ClientEventStandardCode = 'CLIENT_ABORTED' | 'BACKEND_LEAVE' | 'REQUEST_TIMEOUT' | 'NETWORK_ERROR' | 'SFU_ERROR' | 'SFU_GO_AWAY' | 'ICE_CONNECTIVITY_FAILED' | 'DTLS_CONNECTIVITY_FAILED';
 export type CallReportContext = {
     callType: string;
@@ -27,6 +33,7 @@ export declare class ClientEventReporter {
     private callContexts;
     private joinAttemptIds;
     private joinReasons;
+    private joinSources;
     private coordinatorPairs;
     private wsPairs;
     private peerConnectionPairs;
@@ -50,7 +57,10 @@ export declare class ClientEventReporter {
     registerCall: (cid: string, ctx: CallReportContext) => void;
     unregisterCall: (cid: string) => void;
     startCorrelation: (cid: string, joinReason: JoinReason) => void;
-    withJoinLifecycle: <T>(cid: string, joinReason: JoinReason, op: () => Promise<T>) => Promise<T>;
+    withJoinLifecycle: <T>(cid: string, options: {
+        joinReason: JoinReason;
+        joinSource?: JoinSource;
+    }, op: () => Promise<T>) => Promise<T>;
     track: <T>(cid: string, stage: "CoordinatorJoin" | "WSJoin", op: () => Promise<T>) => Promise<T>;
     reportFirstFrame: (cid: string, trackType: TrackType, trackId: string) => void;
     captureWsError: (cid: string, opts: {

package/dist/src/ringing/RingStatePoller.d.ts

@@ -0,0 +1,46 @@
+import type { Call } from '../Call';
+import { type RingStatePollingOptions } from '../coordinator/connection/types';
+/**
+ * Polls the coordinator for the outcome of a ring the current user started.
+ *
+ * `call.accepted`, `call.rejected` and `call.missed` are delivered best-effort,
+ * with no store-and-forward, so a caller that drops one is left on a ringing
+ * screen while the callee is already in the call. After a quiet period this
+ * reads the ring state until a terminal outcome or the end of the ring window.
+ */
+export declare class RingStatePoller {
+    private readonly logger;
+    private readonly call;
+    private readonly startAfterMs;
+    private readonly intervalMs;
+    private sessionId;
+    private deadlineAt;
+    private idleTimeoutId;
+    private intervalId;
+    private stopped;
+    private wasPolling;
+    private inFlight;
+    private unsubscribe;
+    constructor(call: Call, options?: RingStatePollingOptions);
+    /**
+     * Starts polling. Does nothing when the call has no session yet.
+     */
+    start: () => void;
+    /**
+     * Pauses polling, keeping the captured session, the deadline and the event
+     * subscriptions. Resuming does not extend the ring window.
+     */
+    pause: () => void;
+    /**
+     * Resumes a paused poller. Goes straight back to polling if it was already
+     * past the quiet period, so a pause does not buy the ring another one.
+     */
+    resume: () => void;
+    /**
+     * Stops polling. The poller cannot be restarted.
+     */
+    stop: () => void;
+    private armIdleWindow;
+    private runTick;
+    private tick;
+}

package/dist/src/ringing/RingTimeout.d.ts

@@ -0,0 +1,27 @@
+import type { Call } from '../Call';
+/**
+ * Drops a call that has been ringing for too long: the caller cancels after
+ * `auto_cancel_timeout_ms`, a callee after `incoming_call_timeout_ms`.
+ *
+ * Either timeout being `0` means the call rings until something else settles it.
+ */
+export declare class RingTimeout {
+    private readonly call;
+    private timeoutId;
+    private deadlineAt;
+    private stopped;
+    constructor(call: Call);
+    /**
+     * Schedules an auto-drop timeout based on the call settings.
+     * Applicable only for ringing calls.
+     */
+    start: () => void;
+    /**
+     * Pauses the timeout while preserving its original deadline.
+     */
+    pause: () => void;
+    /**
+     * Cancels a scheduled auto-drop timeout. It cannot be armed again.
+     */
+    stop: () => void;
+}

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

@@ -0,0 +1,4 @@
+export * from './RingStatePoller';
+export * from './RingTimeout';
+export * from './reconcileRingState';
+export * from './resolveOwnRingOutcome';

package/dist/src/ringing/reconcileRingState.d.ts

@@ -0,0 +1,18 @@
+import type { Call } from '../Call';
+import type { JoinSource } from '../reporting';
+/**
+ * Decides what a ringing call should do next, based on the current call state.
+ *
+ * The `call.accepted`, `call.rejected` and `call.missed` handlers and the ring
+ * state poller both run this. They differ only in how the state got there: the
+ * handlers rely on `CallState.updateFromEvent`, which runs before them, and the
+ * poller applies the polled ring state itself.
+ *
+ * @param call the call to reconcile.
+ * @param joinSource which of the two triggered this run, reported on the
+ * caller's join: `ring-ws` for the event handlers, `ring-poll-api` for the
+ * poller.
+ * @returns whether the ring reached a terminal state. A failed join is not
+ * terminal: the caller should keep trying while the ring is open.
+ */
+export declare const reconcileRingState: (call: Call, joinSource: JoinSource) => Promise<boolean>;

package/dist/src/ringing/resolveOwnRingOutcome.d.ts

@@ -0,0 +1,32 @@
+import { CallingState } from '../store';
+import type { CallSessionResponse } from '../gen/coordinator';
+export type OwnRingOutcome = {
+    /**
+     * Whether the current user accepted or rejected the ring, on this device or
+     * on another one. Either way the ring no longer needs to time out.
+     */
+    settledByMe: boolean;
+    /**
+     * Set when this device should stop ringing and leave, carrying the reason to
+     * report to the native call UI.
+     */
+    leaveReason?: 'answeredElsewhere' | 'rejected';
+};
+export type OwnRingOutcomeInput = {
+    /** The call session to read the accept and reject maps from. */
+    session: CallSessionResponse | undefined;
+    /** The connected user, or `undefined` when there is none. */
+    currentUserId: string | undefined;
+    /** The current calling state. */
+    callingState: CallingState;
+};
+/**
+ * Decides what a ringing call should do about the current user's own accept or
+ * reject, which may have happened on another device.
+ *
+ * Accepting on *this* device also lands in `accepted_by`, so an acceptance only
+ * means another device took the call when this one is still ringing.
+ *
+ * Only meaningful for a ringing call; the caller checks that.
+ */
+export declare const resolveOwnRingOutcome: ({ session, currentUserId, callingState, }: OwnRingOutcomeInput) => OwnRingOutcome;

package/dist/src/stats/utils.d.ts

@@ -29,3 +29,9 @@ export declare const getSdkSignature: (clientDetails: ClientDetails) => {
 };
 export declare const getSdkName: (sdk: Sdk | undefined) => "stream-react" | "stream-react-native" | "stream-js";
 export declare const getSdkVersion: (sdk: Sdk | undefined) => string;
+/**
+ * Returns the identifier the SFU receives in the `X-Stream-Client` header,
+ * e.g. `stream-video-react-v1.43.1`. Matches the format the coordinator
+ * already gets through the client's user agent.
+ */
+export declare const getStreamClientId: (sdk: Sdk | undefined) => string;

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

@@ -3,7 +3,7 @@ import type { Patch } from './rxUtils';
 import { CallingState } from './CallingState';
 import { type ClosedCaptionsSettings, type StreamVideoParticipant, type StreamVideoParticipantPatch, type StreamVideoParticipantPatches, type SubscriptionChanges, VideoTrackType } from '../types';
 import { CallStatsReport } from '../stats';
-import { CallClosedCaption, CallIngressResponse, CallResponse, CallSessionResponse, CallSettingsResponse, EgressResponse, MemberResponse, OwnCapability, ThumbnailResponse, UserResponse, VideoEvent } from '../gen/coordinator';
+import { CallClosedCaption, CallIngressResponse, CallResponse, CallSessionResponse, CallSettingsResponse, GetCallRingStateResponse, EgressResponse, MemberResponse, OwnCapability, ThumbnailResponse, UserResponse, VideoEvent } from '../gen/coordinator';
 import { ReconnectDetails } from '../gen/video/sfu/event/events';
 import { CallGrants, CallState as SfuCallState, Pin, TrackType } from '../gen/video/sfu/models/models';
 import { Comparator } from '../sorting';
@@ -615,6 +615,15 @@ export declare class CallState {
      * @param call the call response from the server.
      */
     updateFromCallResponse: (call: CallResponse) => void;
+    /**
+     * Merges a polled ring state into the current session. Only the ring fields
+     * are touched: the endpoint does not return the session roster.
+     *
+     * @internal
+     *
+     * @param ringState the ring state as returned by the coordinator.
+     */
+    updateFromRingState: (ringState: GetCallRingStateResponse) => void;
     /**
      * Updates the call state with the data received from the SFU server.
      *

package/package.json

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