@signalwire/js 4.0.0-rc.0 → 4.0.0-rc.2

package/dist/index.d.mts

@@ -342,6 +342,12 @@ interface MediaOptions {
   receiveAudio?: boolean;
   /** Whether to receive remote video. */
   receiveVideo?: boolean;
+  /**
+   * When local media can't be acquired (permission denied or device
+   * unavailable), continue the call in receive-only mode instead of failing.
+   * Defaults to `true`. Ignored when the call is not set to receive any media.
+   */
+  fallbackToReceiveOnly?: boolean;
 }
 //#endregion
 //#region src/containers/PreferencesContainer.d.ts
@@ -812,7 +818,7 @@ interface Member {
   member_id: string;
   call_id: string;
   name: string;
-  type: 'member' | 'screen';
+  type: 'member' | 'screen' | 'device' | (string & {});
   parent_id?: string;
   requested_position?: string;
   handraised: boolean;
@@ -820,17 +826,17 @@ interface Member {
   audio_muted: boolean;
   video_muted: boolean;
   deaf: boolean;
-  input_volume: number;
-  output_volume: number;
-  input_sensitivity: number;
+  input_volume?: number;
+  output_volume?: number;
+  input_sensitivity?: number;
   echo_cancellation: boolean;
   auto_gain: boolean;
   noise_suppression: boolean;
   lowbitrate: boolean;
   denoise: boolean;
-  talking: boolean;
-  isAudience: boolean;
-  meta: Record<string, unknown>;
+  talking?: boolean;
+  isAudience?: boolean;
+  meta?: Record<string, unknown>;
   subscriber_id: string;
   address_id: string;
   updated?: string[];
@@ -952,6 +958,15 @@ interface RoomUpdatedPayload {
   room_id: string;
   room_session_id: string;
 }
+/**
+ * Describes the peer (remote) call referenced from a call.state event.
+ *
+ * Mirrors the backend (relay.c) `peer` shape.
+ */
+interface CallStateRelatedCall {
+  call_id?: string;
+  node_id?: string;
+}
 interface CallStatePayload {
   call_id: string;
   node_id: string;
@@ -959,10 +974,19 @@ interface CallStatePayload {
   call_state: SignalingCallStates;
   direction: CallDirection;
   device: CallDevice;
-  start_time: number;
-  answer_time: number;
-  end_time: number;
+  /**
+   * Epoch timestamps for the call lifecycle. Optional because pre-answer
+   * states (e.g. `created`, `ringing`) do not have an `answer_time`/`end_time`
+   * and the backend reports them as `0` or omits them.
+   */
+  start_time?: number;
+  answer_time?: number;
+  end_time?: number;
   room_session_id: string;
+  /** The peer (remote) call this call is connected to, if any. */
+  peer?: CallStateRelatedCall;
+  /** Application-defined tag associated with the call. */
+  tag?: string;
 }
 interface CallPlayPayload {
   control_id: string;
@@ -1168,6 +1192,32 @@ declare class MediaTrackError extends Error {
   originalError: unknown;
   constructor(operation: string, kind: string, originalError: unknown);
 }
+/**
+ * Failure to acquire local media (camera, microphone, or screen capture)
+ * via `getUserMedia`/`getDisplayMedia`.
+ *
+ * Non-fatal by default: screenshare and additional-device failures never
+ * end the call, and main-connection failures degrade to receive-only when
+ * possible. The wrapping site sets `fatal` to `true` only when the call
+ * cannot continue (receive-only fallback disabled or no receive intent).
+ */
+declare class MediaAccessError extends Error {
+  /** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
+  operation: string;
+  /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
+  media: string;
+  /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
+  originalError: unknown;
+  /** Whether this failure terminates the call. */
+  readonly fatal: boolean;
+  constructor(/** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
+  operation: string, /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
+  media: string, /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
+  originalError: unknown, /** Whether this failure terminates the call. */
+  fatal?: boolean);
+  /** True when the underlying failure is a permission denial (user or policy). */
+  get denied(): boolean;
+}
 declare class DPoPInitError extends Error {
   originalError: unknown;
   constructor(originalError: unknown, message?: string);
@@ -1508,6 +1558,8 @@ interface MemberCapabilities {
   readonly meta: boolean;
   readonly remove: boolean;
   readonly audioFlags: boolean;
+  readonly denoise: boolean;
+  readonly lowbitrate: boolean;
 }
 /**
  * Call-level capabilities state
@@ -1861,6 +1913,8 @@ declare class Participant extends Destroyable implements CallParticipant {
   get addressId(): string | undefined;
   /** Server node ID for this participant, or `undefined` if not available. */
   get nodeId(): string | undefined;
+  /** Call ID for this participant's leg, or `undefined` if not available. */
+  get callId(): string | undefined;
   /** @internal */
   get value(): Partial<Member>;
   /** Toggles the deafened state (mutes/unmutes incoming audio). */
@@ -1885,6 +1939,7 @@ declare class Participant extends Destroyable implements CallParticipant {
   toggleAudioInputAutoGain(): Promise<void>;
   /** Toggles noise suppression on the audio input. */
   toggleNoiseSuppression(): Promise<void>;
+  /** Toggles low-bitrate mode for this participant's media. */
   toggleLowbitrate(): Promise<void>;
   /**
    * Adjusts the **conference-only** microphone energy gate / sensitivity level
@@ -1925,6 +1980,14 @@ declare class Participant extends Destroyable implements CallParticipant {
   setAudioOutputVolume(value: number): Promise<void>;
   /**
    * Sets the participant's position in the video layout.
+   *
+   * Requires the `member.position` capability. The gateway keys positions by the
+   * **target member's own** `call_id`/`node_id` (see issue #19400 and the legacy
+   * `setPositions` implementation), so this sends the participant's own call
+   * context — matching {@link Participant.remove}. A resolved promise does not
+   * guarantee a visible change: the backend silently returns `200` (no-op) for
+   * non-conference targets.
+   *
    * @param value - The {@link VideoPosition} to assign (e.g. `'auto'`, `'reserved-0'`).
    */
   setPosition(value: VideoPosition): Promise<void>;
@@ -1983,7 +2046,15 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
    * Sets echoCancellation, noiseSuppression, and autoGainControl to true.
    */
   disableStudioAudio(): Promise<void>;
-  /** Starts sharing the local screen. */
+  /**
+   * Starts sharing the local screen.
+   *
+   * The call is unaffected when acquisition fails.
+   *
+   * @throws The raw `getDisplayMedia` error. A dismissed picker or a
+   * permission denial rejects with a `NotAllowedError` `DOMException` —
+   * inspect `error.name` to tell benign cancels apart from real failures.
+   */
   startScreenShare(): Promise<void>;
   /** Observable of the current screen share status. */
   get screenShareStatus$(): Observable<ScreenShareStatus>;
@@ -1991,7 +2062,14 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
   get screenShareStatus(): ScreenShareStatus;
   /** Stops the current screen share. */
   stopScreenShare(): Promise<void>;
-  /** Adds an additional media input device to the call. */
+  /**
+   * Adds an additional media input device to the call.
+   *
+   * The call is unaffected when acquisition fails.
+   *
+   * @throws The raw `getUserMedia` error (e.g. `NotAllowedError` on
+   * permission denial) — inspect `error.name` to decide how to react.
+   */
   addAdditionalDevice(options: MediaOptions): Promise<void>;
   /** Removes an additional media input device by ID. */
   removeAdditionalDevice(id: string): Promise<void>;
@@ -2098,6 +2176,7 @@ interface CallParticipant {
   readonly userId: string | undefined;
   readonly addressId: string | undefined;
   readonly nodeId: string | undefined;
+  readonly callId: string | undefined;
   readonly isTalking: boolean;
   readonly position: LayoutLayer | undefined;
   readonly isAudience: boolean;
@@ -3112,7 +3191,34 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   private get authentication();
   connect(): Promise<void>;
   private handleAuthenticationError;
+  /**
+   * Clear the resume state (authorization_state + protocol) only.
+   *
+   * This is the stale-auth-state recovery helper used by handleAuthError:
+   * the server rejected a reconnect, so the resume state is discarded and a
+   * fresh connect follows. Attach records are deliberately preserved — the
+   * session lives on through the reconnect and reattachCalls() needs the
+   * stored call references afterwards. Do NOT add detachAll() here.
+   *
+   * For public teardown (disconnect/destroy), use {@link teardownSessionState}
+   * instead, which clears the attach records as well.
+   */
   cleanupStoredConnectionParams(): Promise<void>;
+  /**
+   * Public-teardown helper for disconnect()/destroy(). Clears the resume
+   * state (authorization_state + protocol) AND the attach records as one
+   * atomic unit.
+   *
+   * The two stores are coupled: the backend only honors attach records
+   * within the session identified by the resume state, so ending the
+   * session must clear both. Clearing one without the other strands records
+   * no future session can honor (disconnect) or revives a session the
+   * developer explicitly ended (destroy).
+   *
+   * Distinct from {@link cleanupStoredConnectionParams}, which keeps the
+   * attach records for the stale-auth-state recovery path.
+   */
+  teardownSessionState(): Promise<void>;
   protected updateAuthState(authorization_state: string): Promise<void>;
   reauthenticate(token: string, dpopToken?: string, options?: {
     clientBound?: boolean;
@@ -3424,8 +3530,12 @@ interface SignalWireOptions {
    * When `false` (default), session data lives in `sessionStorage` and is
    * lost on reload.
    *
-   * Call {@link SignalWire.destroy | destroy()} to clear all persisted state
-   * (explicit logout).
+   * Both {@link SignalWire.disconnect | disconnect()} and
+   * {@link SignalWire.destroy | destroy()} end the session and clear the
+   * persisted resume state and attach records; credentials and device
+   * preferences survive. Use `resetToDefaults()` for a full wipe, or
+   * `unregister()` to temporarily stop receiving inbound calls while keeping
+   * the session alive.
    */
   persistSession?: boolean;
   /** Custom storage implementation for persistence. */
@@ -3639,6 +3749,14 @@ declare class SignalWire extends Destroyable implements DeviceController {
   /**
    * Disconnects the WebSocket and tears down the current session.
    *
+   * Ends the session identified by the protocol and clears its persisted
+   * resume state (`authorization_state` + protocol) and attach records
+   * together — a later {@link connect} with the same credentials starts a
+   * fresh session and cannot reattach to the ended session's calls.
+   * Credentials and device preferences are preserved. To temporarily stop
+   * receiving inbound calls while keeping the session alive, use
+   * `unregister()` instead.
+   *
    * The client can be reconnected by calling {@link connect} again,
    * which creates a fresh transport and session.
    */
@@ -3820,7 +3938,15 @@ declare class SignalWire extends Destroyable implements DeviceController {
    * attached call IDs, and all SDK storage keys, then re-enumerates devices.
    */
   resetToDefaults(): Promise<void>;
-  /** Destroys the client, clearing timers and releasing all resources. */
+  /**
+   * Destroys the client, clearing timers and releasing all resources.
+   *
+   * Intentionally destroying the client ends its session: the resume state
+   * (`authorization_state` + protocol) and the attach records are both
+   * cleared. Credentials and device preferences are preserved — use
+   * {@link resetToDefaults} for a full wipe. To temporarily stop receiving
+   * inbound calls while keeping the session alive, use `unregister()`.
+   */
   destroy(): void;
 }
 //#endregion
@@ -4153,6 +4279,25 @@ declare class RTCPeerConnectionController extends Destroyable {
    */
   private setupTrackHandling;
   private setupLocalTracks;
+  /** True for a main connection with no local media to send. */
+  private hasNoLocalMediaToSend;
+  /** The media kinds this connection wants to send: 'audiovideo' | 'video' | 'audio'. */
+  private get requestedMediaKinds();
+  /**
+   * Handle a local media acquisition failure with a typed, semantically
+   * accurate MediaAccessError created at the acquisition site:
+   * - Auxiliary connections (screenshare / additional-device) throw a
+   *   non-fatal error — VertoManager surfaces it and the call is unaffected.
+   * - The main connection degrades to receive-only when allowed (default),
+   *   otherwise fails with a fatal error.
+   */
+  private handleLocalMediaFailure;
+  /**
+   * Negotiate receive-only m-lines when there are no local tracks to send.
+   * Only offer-type connections add transceivers — answer-type connections
+   * reuse the transceivers created from the remote offer.
+   */
+  private setupReceiveOnlyTransceivers;
   private getUserMedia;
   private getDisplayMedia;
   private setupRemoteTracks;
@@ -4698,10 +4843,21 @@ declare class WebRTCCall extends Destroyable implements CallManager {
   /** Observable that emits `true` when answered, `false` when rejected. */
   get answered$(): Observable<boolean>;
   /**
-   * Sets the call layout and participant positions.
+   * Sets the call layout and, optionally, individual participant positions.
+   *
+   * The gateway `call.layout.set` DTO has **no** `positions` member, so when
+   * `positions` is provided this method issues a `call.member.position.set`
+   * request per member (via {@link Participant.setPosition}, which keys each
+   * position by that member's own call context) alongside `call.layout.set`
+   * (issue #19400, Flag #6).
+   *
+   * **These operations are NOT atomic.** The layout is applied first, then each
+   * member position sequentially, so members may briefly flash into their
+   * default slots before being moved to the requested positions.
    *
    * @param layout - Layout name (must be one of {@link layouts}).
-   * @param positions - Map of member IDs to {@link VideoPosition} values.
+   * @param positions - Optional map of member IDs to {@link VideoPosition} values.
+   *   When omitted or empty, only the layout is changed.
    * @throws {InvalidParams} If the layout is not in the available {@link layouts}.
    *
    * @example
@@ -4711,7 +4867,7 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    * });
    * ```
    */
-  setLayout(layout: string, positions: Record<string, VideoPosition>): Promise<void>;
+  setLayout(layout: string, positions?: Record<string, VideoPosition>): Promise<void>;
   /**
    * Transfers the call to another destination.
    *
@@ -4815,5 +4971,5 @@ declare const version: string;
  */
 declare const ready: boolean;
 //#endregion
-export { Address, type AddressHistory, type AudioConstraintsEvent, type AuthenticateContext, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallDiagnosticSummary, type CallDirection, type CallError, type CallErrorKind, type NetworkIssue as CallNetworkIssue, type NetworkIssue, type NetworkMetrics as CallNetworkMetrics, type NetworkMetrics, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, type Capability, ClientPreferences, CollectionFetchError, type ConstraintFallbackEvent, type CredentialNoRefreshHandlerWarning, type CredentialProvider, type CredentialRefreshFallbackReason, type CredentialRefreshFallbackWarning, DPoPInitError, type DebugOptions, type DeviceController, type DeviceRecoveryEvent, DeviceTokenError, type DiagnosticEvent, type DialOptions, type Directory, EmbedTokenCredentialProvider, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type LogLevel, type MediaDirection, type MediaDirections, type MediaOptions, type MediaParamsEvent, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, OverconstrainedFallbackError, Participant, type PendingRPCOptions, type PermissionResult, type PlatformCapabilities, PreflightError, type PreflightOptions, type PreflightResult, type QualityLevel, RecoveryError, type RecoveryEvent, type RecoveryState, type ResilienceCallStatus, type SATClaims, type SDKCredential, type SDKLogger, type SDKWarning, type ScreenShareStatus, type SelectDeviceOptions, SelfCapabilities, SelfParticipant, type SessionDiagnostics, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, type StoredDevicePreference, type TextMessage, TokenRefreshError, type TransferOptions, UnexpectedError, User, type UserPresence, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, getLogger, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
+export { Address, type AddressHistory, type AudioConstraintsEvent, type AuthenticateContext, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallDiagnosticSummary, type CallDirection, type CallError, type CallErrorKind, type NetworkIssue as CallNetworkIssue, type NetworkIssue, type NetworkMetrics as CallNetworkMetrics, type NetworkMetrics, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, type Capability, ClientPreferences, CollectionFetchError, type ConstraintFallbackEvent, type CredentialNoRefreshHandlerWarning, type CredentialProvider, type CredentialRefreshFallbackReason, type CredentialRefreshFallbackWarning, DPoPInitError, type DebugOptions, type DeviceController, type DeviceRecoveryEvent, DeviceTokenError, type DiagnosticEvent, type DialOptions, type Directory, EmbedTokenCredentialProvider, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type LogLevel, MediaAccessError, type MediaDirection, type MediaDirections, type MediaOptions, type MediaParamsEvent, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, OverconstrainedFallbackError, Participant, type PendingRPCOptions, type PermissionResult, type PlatformCapabilities, PreflightError, type PreflightOptions, type PreflightResult, type QualityLevel, RecoveryError, type RecoveryEvent, type RecoveryState, type ResilienceCallStatus, type SATClaims, type SDKCredential, type SDKLogger, type SDKWarning, type ScreenShareStatus, type SelectDeviceOptions, SelfCapabilities, SelfParticipant, type SessionDiagnostics, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, type StoredDevicePreference, type TextMessage, TokenRefreshError, type TransferOptions, UnexpectedError, User, type UserPresence, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, getLogger, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
 //# sourceMappingURL=index.d.mts.map