@cometchat/calls-sdk-react-native 5.0.1 → 5.0.2

package/dist/index.d.ts

@@ -114,6 +114,8 @@ declare const EVENT_LISTENER_METHODS: {
     readonly onSessionLeft: "onSessionLeft";
     readonly onConnectionLost: "onConnectionLost";
     readonly onConnectionRestored: "onConnectionRestored";
+    readonly onRemoteConnectionLost: "onRemoteConnectionLost";
+    readonly onRemoteConnectionRestored: "onRemoteConnectionRestored";
     readonly onConnectionClosed: "onConnectionClosed";
     readonly onConnectionFailed: "onConnectionFailed";
     readonly onSessionTimedOut: "onSessionTimedOut";
@@ -184,6 +186,8 @@ declare const EVENT_LISTENER_METHODS_WEB: {
     readonly onSessionLeft: "onSessionLeft";
     readonly onConnectionLost: "onConnectionLost";
     readonly onConnectionRestored: "onConnectionRestored";
+    readonly onRemoteConnectionLost: "onRemoteConnectionLost";
+    readonly onRemoteConnectionRestored: "onRemoteConnectionRestored";
     readonly onConnectionClosed: "onConnectionClosed";
     readonly onConnectionFailed: "onConnectionFailed";
     readonly onSessionTimedOut: "onSessionTimedOut";
@@ -225,6 +229,7 @@ declare const EVENT_LISTENER_METHODS_WEB: {
 declare const EVENT_LISTENER_METHODS_MOBILE: {
   readonly MediaEventsListener: {
     readonly onAudioModeChanged: "onAudioModeChanged";
+    readonly onAudioModesChanged: "onAudioModesChanged";
     readonly onCameraFacingChanged: "onCameraFacingChanged";
     readonly onAudioMuted: "onAudioMuted";
     readonly onAudioUnMuted: "onAudioUnMuted";
@@ -260,6 +265,8 @@ declare const EVENT_LISTENER_METHODS_MOBILE: {
     readonly onSessionLeft: "onSessionLeft";
     readonly onConnectionLost: "onConnectionLost";
     readonly onConnectionRestored: "onConnectionRestored";
+    readonly onRemoteConnectionLost: "onRemoteConnectionLost";
+    readonly onRemoteConnectionRestored: "onRemoteConnectionRestored";
     readonly onConnectionClosed: "onConnectionClosed";
     readonly onConnectionFailed: "onConnectionFailed";
     readonly onSessionTimedOut: "onSessionTimedOut";
@@ -310,6 +317,7 @@ type VideoInputDevice = MediaDeviceInfo & {
 type Subscription = (() => void) | {
   remove: () => void;
 };
+type SettingsDialogTab = 'audio' | 'video';
 type BaseState = {
   participantListVisible: boolean;
   moreMenuVisible: boolean;
@@ -334,6 +342,7 @@ type BaseState = {
   cameraFacing: CameraFacingInternal;
   connectionRetryCount: number;
   settingsDialogVisible: boolean;
+  settingsDialogTab: SettingsDialogTab;
   virtualBackgroundDialogVisible: boolean;
   idealTimeoutTimer?: NodeJS.Timeout;
   idleTimeoutModalVisible: boolean;
@@ -420,7 +429,7 @@ declare const setLayout: (layout: Layout, sidebarLayoutSetProgrammatically?: boo
 declare const hideAllBottomSheets: () => void;
 declare const enablePictureInPictureLayout: () => void;
 declare const disablePictureInPictureLayout: () => void;
-declare const showSettingsDialog: () => void;
+declare const showSettingsDialog: (tab?: SettingsDialogTab) => void;
 declare const hideSettingsDialog: () => void;
 declare const toggleSettingsDialog: () => void;
 declare const showVirtualBackgroundDialog: () => void;
@@ -428,7 +437,7 @@ declare const hideVirtualBackgroundDialog: () => void;
 declare const toggleMirrorLocalVideo: () => void;
 declare const toggleEnableNoiseReduction: () => void;
 declare const setChatButtonUnreadCount: (count: number) => void;
-declare const setAudioMode: (mode: AudioMode["type"]) => void;
+declare const setAudioModes: (modes: AudioMode[]) => void;
 declare const getLayout: () => Layout;
 declare function initBaseStoreSubscriptions(): void;
 //#endregion
@@ -442,6 +451,12 @@ type ConferenceState = {
   p2p: boolean;
   conferenceStatus: 'initial' | 'joining' | 'joined' | 'error' | 'interrupted' | 'left' | 'restored' | 'reconnecting';
   connectionQuality: Map<string, number>;
+  /**
+   * pid → epoch ms of that participant's last remote stats update. Seeded
+   * when the participant joins; in peer calls, used to detect the remote
+   * peer's connection being lost (onRemoteConnectionLost).
+   */
+  remoteStatsTimestamps: Map<string, number>;
   raiseHandMap: Map<string, number>;
   recording: {
     status: ValueOf<typeof JitsiMeetJS.constants.recording.status>;
@@ -490,57 +505,329 @@ type ConfigStateInternal = {
   enableCompanionMode: boolean;
   sdkPlatform?: SDKPlatform;
 };
+/**
+ * Configuration that only applies on mobile platforms
+ * (native iOS / Android and React Native). These options are ignored on the web.
+ */
 type ConfigStateMobile = {
+  /**
+   * The audio output route the call should use. One of:
+   * - `'SPEAKER'` — the loudspeaker.
+   * - `'EARPIECE'` — the phone's earpiece.
+   * - `'HEADPHONES'` — wired headphones.
+   * - `'BLUETOOTH'` — a connected Bluetooth audio device.
+   *
+   * When omitted, the SDK chooses a route automatically based on the devices
+   * currently connected and updates it as devices are plugged in or removed.
+   *
+   * @default undefined — chosen automatically by the SDK
+   */
   audioMode?: AudioMode['type'];
+  /**
+   * Hides the audio-output (route) selector button from the call controls,
+   * preventing the user from switching between speaker, earpiece, headphones,
+   * and Bluetooth from within the SDK UI.
+   *
+   * @default false
+   */
   hideAudioModeButton: boolean;
+  /**
+   * Allows the user to tap the picture-in-picture tile to swap who is shown in
+   * the main spotlight. Only applies when `layout` is `'SPOTLIGHT'`.
+   *
+   * @default true
+   */
+  enableSpotlightSwap: boolean;
 };
+/**
+ * Configuration that only applies on the web platform.
+ * These options are ignored on mobile.
+ */
 type ConfigStateWeb = {
+  /**
+   * Applies background-noise suppression to the local microphone so that
+   * keyboard clicks, fans, and other ambient sounds are filtered out before
+   * your audio is sent to other participants.
+   *
+   * @default false
+   */
   enableNoiseReduction: boolean;
+  /**
+   * The `deviceId` of the microphone to capture audio from when the call
+   * starts. Use this to pre-select a specific input device instead of the
+   * system default. Device IDs come from the browser's
+   * `navigator.mediaDevices.enumerateDevices()`.
+   *
+   * @default undefined — uses the system default microphone
+   */
   audioInputDeviceId?: string;
+  /**
+   * The `deviceId` of the speaker / output device used to play remote
+   * participants' audio. Use this to pre-select a specific output device
+   * instead of the system default.
+   *
+   * @default undefined — uses the system default speaker
+   */
   audioOutputDeviceId?: string;
+  /**
+   * The `deviceId` of the camera to capture video from when the call starts.
+   * Use this to pre-select a specific camera instead of the system default.
+   *
+   * @default undefined — uses the system default camera
+   */
   videoInputDeviceId?: string;
+  /**
+   * Hides the screen-sharing button from the call controls, preventing the
+   * user from starting a screen share from within the SDK UI.
+   *
+   * @default false
+   */
   hideScreenSharingButton: boolean;
-  hideVirtualBackgroundButton: boolean;
   /**
-   * @unstable This API may change or be removed in a future release.
-   * When enabled, the SDK renders only remote audio elements without any
-   * visual UI (no video tiles, controls, or overlays). This allows the
-   * host app to provide its own custom UI while the SDK handles the
-   * underlying call connection and audio playback.
+   * Hides the virtual-background button from the call controls, preventing the
+   * user from blurring or replacing their camera background from within the
+   * SDK UI.
+   *
+   * @default false
    */
-  unstable_renderAudioOnly: boolean;
+  hideVirtualBackgroundButton: boolean;
 };
+/**
+ * Configuration that applies on both web and mobile platforms.
+ */
 type ConfigStateBoth = {
+  /**
+   * Whether the call starts as an audio-only (`'VOICE'`) call or a video
+   * (`'VIDEO'`) call. In a voice call no camera is acquired and no video
+   * tiles are shown.
+   *
+   * @default 'VIDEO'
+   */
   sessionType: SessionType;
+  /**
+   * The arrangement used to display participant video tiles:
+   * - `'TILE'` — an equal grid of all participants.
+   * - `'SIDEBAR'` — one main participant with the rest in a side strip.
+   * - `'SPOTLIGHT'` — a single full-screen participant with the local user
+   *   shown in a small picture-in-picture tile.
+   *
+   * @default 'TILE'
+   */
   layout: Layout;
+  /**
+   * Which camera to use when the call starts: `'FRONT'` (selfie) or `'REAR'`
+   * (back). Primarily relevant on mobile devices with multiple cameras; the
+   * user can still switch afterwards.
+   *
+   * @default undefined — uses the SDK's current camera (front by default)
+   */
   initialCameraFacing?: CameraFacing;
+  /**
+   * Automatically starts recording the session as soon as the call begins,
+   * without the user pressing the record button. Recording must be enabled
+   * for your app for this to take effect.
+   *
+   * @default false
+   */
   autoStartRecording: boolean;
+  /**
+   * Hides the recording button from the call controls, preventing the user
+   * from manually starting or stopping recording from within the SDK UI.
+   *
+   * @default true
+   */
   hideRecordingButton: boolean;
+  /**
+   * Hides the entire bottom control bar (mic, camera, leave, and every other
+   * call control). Useful when the host app provides its own controls.
+   *
+   * @default false
+   */
   hideControlPanel: boolean;
+  /**
+   * Hides the "leave call" button from the call controls. The host app is
+   * then responsible for providing its own way to leave the session.
+   *
+   * @default false
+   */
   hideLeaveSessionButton: boolean;
+  /**
+   * Hides the top header bar of the call UI (which shows the call title,
+   * session timer, and similar information).
+   *
+   * @default false
+   */
   hideHeaderPanel: boolean;
+  /**
+   * Hides the "raise hand" button from the call controls.
+   *
+   * @default false
+   */
   hideRaiseHandButton: boolean;
+  /**
+   * Hides the "share / invite" button that lets the user invite others to
+   * join the call.
+   *
+   * @default true
+   */
   hideShareInviteButton: boolean;
+  /**
+   * Hides the layout-switcher button, preventing the user from changing
+   * between the tile, sidebar, and spotlight layouts at runtime.
+   *
+   * @default false
+   */
   hideChangeLayoutButton: boolean;
+  /**
+   * Hides the microphone mute/unmute button from the call controls.
+   *
+   * @default false
+   */
   hideToggleAudioButton: boolean;
+  /**
+   * Hides the camera on/off button from the call controls.
+   *
+   * @default false
+   */
   hideToggleVideoButton: boolean;
+  /**
+   * Hides the button that opens the participant list panel.
+   *
+   * @default false
+   */
   hideParticipantListButton: boolean;
+  /**
+   * Hides the in-call chat button.
+   *
+   * @default true
+   */
   hideChatButton: boolean;
+  /**
+   * Hides the elapsed-time timer that shows how long the call has been
+   * running.
+   *
+   * @default false
+   */
   hideSessionTimer: boolean;
+  /**
+   * Hides the network-quality indicator that reflects each participant's
+   * connection strength.
+   *
+   * @default true
+   */
   hideNetworkIndicator: boolean;
+  /**
+   * Hides the "recording in progress" badge shown while the session is being
+   * recorded. The recording itself is unaffected.
+   *
+   * @default false
+   */
   hideRecordingStatusIndicator: boolean;
+  /**
+   * Hides the button that switches between the front and rear cameras.
+   * Mainly relevant on mobile devices with more than one camera.
+   *
+   * @default false
+   */
   hideSwitchCameraButton: boolean;
+  /**
+   * Enables the per-participant context menu — opened by right-clicking (web)
+   * or long-pressing (mobile) a participant's tile — that exposes actions such
+   * as pinning a participant.
+   *
+   * Note: this menu is automatically unavailable in the `'SPOTLIGHT'` and
+   * picture-in-picture layouts regardless of this setting.
+   *
+   * @default true
+   */
   enableParticipantContextMenu: boolean;
+  /**
+   * The display name to show for the local user in the call (participant
+   * tiles, participant list, etc.). When left empty, the name associated with
+   * the logged-in user is used.
+   *
+   * @default '' — falls back to the logged-in user's name
+   */
   displayName: string;
+  /**
+   * Joins the call with the microphone muted. The user can unmute manually
+   * afterwards (unless the toggle-audio button is hidden).
+   *
+   * @default false
+   */
   startAudioMuted: boolean;
+  /**
+   * Joins the call with the camera off. The user can turn the camera on
+   * manually afterwards (unless the toggle-video button is hidden).
+   *
+   * @default false
+   */
   startVideoPaused: boolean;
+  /**
+   * Title text shown in the call's header panel (for example, the meeting or
+   * room name).
+   *
+   * @default '' — no title shown
+   */
   title: string;
+  /**
+   * How long, in milliseconds, the local user may remain alone in the call
+   * (no other participants) before an "are you still there?" idle prompt is
+   * shown. The countdown only runs while you are the only participant.
+   *
+   * @default 60000 — 60 seconds
+   */
   idleTimeoutPeriodBeforePrompt: number;
+  /**
+   * How long, in milliseconds, the idle prompt stays on screen waiting for a
+   * response before the SDK automatically leaves the call on the user's behalf.
+   *
+   * @default 180000 — 3 minutes
+   */
   idleTimeoutPeriodAfterPrompt: number;
+  /**
+   * Allows the user to drag the local picture-in-picture tile to reposition
+   * it. Only applies when `layout` is `'SPOTLIGHT'`.
+   *
+   * @default true
+   */
   enableSpotlightDrag: boolean;
-  enableSpotlightSwap: boolean;
+  /**
+   * Marks this as a one-to-one (peer) call. In a peer call, when one
+   * participant leaves the session ends for everyone rather than continuing
+   * without them (unless `forceLeave` is passed when leaving). The remote
+   * peer's connectivity is also watched: if no remote stats arrive for 10
+   * seconds onRemoteConnectionLost is published, and
+   * onRemoteConnectionRestored once they resume.
+   *
+   * @default false
+   */
   isPeerCall: boolean;
+  /**
+   * Enables the in-call toast notifications surfaced by the SDK (for example
+   * "X joined the call" or error messages). Set to `false` to suppress all
+   * SDK toasts.
+   *
+   * @default true
+   */
   enableNotifications: boolean;
+  /**
+   * @unstable This API may change or be removed in a future release.
+   * When enabled in a voice call (`sessionType: 'VOICE'`), the SDK renders
+   * no visible UI at all — no controls, header, modals, or toast
+   * notifications — while the call connection, media, and events continue
+   * to work normally. Remote participants' audio keeps playing. The host
+   * app is responsible for providing its own UI, including reacting to
+   * session end (the SDK's "session has ended" view and the idle-timeout
+   * prompt/auto-leave are not shown in this mode).
+   *
+   * Only supported in voice calls: for video calls (`sessionType:
+   * 'VIDEO'`) the flag is ignored with a console warning and the default
+   * UI is rendered.
+   *
+   * @default false
+   */
+  unstable_headlessMode: boolean;
 };
 type ConfigState = ConfigStateInternal & ConfigStateMobile & ConfigStateWeb & ConfigStateBoth;
 type Actions$3 = {
@@ -668,6 +955,7 @@ declare const InternalSettingSchema: v.ObjectSchema<{
         readonly minHeightForQualityLvl: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
         readonly mobileCodecPreferenceOrder: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
       }, undefined>, undefined>;
+      readonly pcStatsInterval: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>;
   }, undefined>;
   readonly sessionId: v.StringSchema<undefined>;
@@ -1098,6 +1386,13 @@ type SDKEvents = Omit<_SDKEvents, 'onParticipantListChanged' | 'onConnectionFail
 };
 type MobileSDKEvents = SDKEvents & {
   onAudioModeChanged: (payload: AudioMode['type']) => void;
+  /**
+   * Fired when the list of available audio modes changes,
+   * e.g. a Bluetooth device or headphones are connected/disconnected.
+   *
+   * @param payload - The updated list of available audio modes.
+   */
+  onAudioModesChanged: (payload: AudioMode[]) => void;
   onCameraFacingChanged: (payload: CameraFacing) => void;
   onSwitchCameraButtonClicked: () => void;
   onPictureInPictureLayoutEnabled: () => void;
@@ -4178,9 +4473,19 @@ declare class CometChatCalls extends SessionMethodsCore {
   }): () => void;
   /**
    * Sets the audio output mode (mobile only).
+   *
+   * The returned promise rejects with a `{ errorCode, errorDescription }`
+   * object when the mode is 'EARPIECE' during a video call
+   * (ERROR_INVALID_AUDIO_MODE), when the mode is not currently available —
+   * including when no call is active (ERROR_AUDIO_MODE_UNAVAILABLE), or when
+   * the native route switch fails.
+   *
+   * The `onAudioModeChanged` event fires only after the audio route actually
+   * changes, not when this method is called.
    * @param mode - The audio mode to set (e.g., 'SPEAKER', 'EARPIECE', 'BLUETOOTH', 'HEADPHONES').
+   * @returns A Promise that resolves once the route change has been dispatched.
    */
-  static setAudioMode(mode: AudioMode['type']): void;
+  static setAudioMode(mode: AudioMode['type']): Promise<void>;
   /**
    * Enables Picture-in-Picture (PIP) layout during the call.
    */