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

package/dist/index.d.cts

@@ -812,7 +812,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 +820,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 +952,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 +968,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;
@@ -1508,6 +1526,8 @@ interface MemberCapabilities {
   readonly meta: boolean;
   readonly remove: boolean;
   readonly audioFlags: boolean;
+  readonly denoise: boolean;
+  readonly lowbitrate: boolean;
 }
 /**
  * Call-level capabilities state
@@ -1861,6 +1881,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 +1907,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 +1948,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>;
@@ -2098,6 +2129,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 +3144,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 +3483,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 +3702,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 +3891,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
@@ -4698,10 +4777,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 +4801,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.
    *