@signalwire/js 4.0.0-dev-20260515133934 → 4.0.0-rc.1

package/dist/index.d.cts

@@ -134,8 +134,25 @@ interface AuthenticateContext {
  * - Setting `expiry_at` when the credential has a known expiration so the SDK can schedule refresh.
  * - Handling errors and never leaking sensitive data through error messages.
  *
- * The SDK owns the credential lifecycle: it calls `authenticate` once during initialization
- * and, if `refresh` is provided and `expiry_at` is set, schedules automatic refresh before expiry.
+ * ## Refresh precedence
+ *
+ * The SDK selects exactly one refresh mechanism per session, evaluated at connect
+ * time (and re-evaluated on reconnect):
+ *
+ * | `refresh` provided | SAT carries `sat:refresh` scope | Active mechanism                     |
+ * | ------------------ | -------------------------------- | ------------------------------------ |
+ * | yes                | yes                              | Client Bound SAT (DPoP, internal)    |
+ * | yes                | no                               | Developer-provided `refresh()`       |
+ * | no                 | yes                              | Client Bound SAT (DPoP, internal)    |
+ * | no                 | no                               | None — session ends at `expiry_at`   |
+ *
+ * When the SDK falls back to the developer-provided `refresh()` because the SAT
+ * lacked `sat:refresh` scope, a `credential_refresh_fallback` event is emitted on
+ * `SignalWire.warnings$` so application code can observe the transition.
+ *
+ * Mint a SAT via `POST /api/fabric/subscribers/tokens` with `fingerprint` and
+ * `scope: ["sat:refresh"]` (both currently optional on that endpoint) to enable
+ * the Client Bound SAT path; otherwise provide `refresh()` here.
  */
 interface CredentialProvider {
   /**
@@ -146,6 +163,8 @@ interface CredentialProvider {
    * - Reject (throw) on failure — this will cause client initialization to fail.
    * - When `context.fingerprint` is provided, forward it to the server-side token
    *   endpoint with `scope: "sat:refresh"` to enable automatic token refresh.
+   *   Ignoring `context.fingerprint` causes the SDK to fall back to `refresh()`
+   *   (if provided) or end the session at expiry.
    *
    * SDK behavior:
    * - Awaits this method before establishing the WebSocket connection.
@@ -160,14 +179,12 @@ interface CredentialProvider {
    * - Reject (throw) if refresh is not possible — the SDK will stop the refresh schedule.
    *
    * SDK behavior:
-   * - Only called when `expiry_at` was set on the previous credential.
+   * - Only called when `expiry_at` was set on the previous credential AND the
+   *   SAT does not carry `sat:refresh` scope (otherwise the SDK refreshes
+   *   internally via Client Bound SAT). See the precedence table above.
    * - Scheduled automatically before expiry; implementors do not need to manage timing.
    * - On rejection, the refresh schedule stops and the session continues with the
    *   current credentials until they expire.
-   * - When not provided and the SAT includes a `sat:refresh` scope, the SDK
-   *   automatically refreshes via Client Bound SAT (DPoP) without developer intervention.
-   * - When not provided and no refresh scope is present, the SDK uses the initial
-   *   credentials for the entire session lifetime.
    */
   refresh?: () => Promise<SDKCredential>;
 }
@@ -795,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;
@@ -803,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[];
@@ -935,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;
@@ -942,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;
@@ -1491,6 +1526,8 @@ interface MemberCapabilities {
   readonly meta: boolean;
   readonly remove: boolean;
   readonly audioFlags: boolean;
+  readonly denoise: boolean;
+  readonly lowbitrate: boolean;
 }
 /**
  * Call-level capabilities state
@@ -1844,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). */
@@ -1868,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
@@ -1908,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>;
@@ -2081,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;
@@ -3095,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;
@@ -3280,6 +3356,60 @@ declare class ClientSessionWrapper implements SessionState {
   get calls(): Call[];
 }
 //#endregion
+//#region src/core/types/warnings.types.d.ts
+/**
+ * Non-fatal warning emitted via {@link SignalWire.warnings$ | client.warnings$}.
+ *
+ * Use to detect SDK behaviors that affect session liveness or developer-facing
+ * contracts but do not warrant disconnection. Discriminated by `code`.
+ *
+ * Existing consumers of `errors$` are NOT notified — `warnings$` is a separate
+ * channel so application code can react to warnings without triggering
+ * error-handling code paths (e.g., disconnect cascades, user-facing toasts).
+ */
+type SDKWarning = CredentialRefreshFallbackWarning | CredentialNoRefreshHandlerWarning;
+/**
+ * Diagnostic detail for {@link CredentialRefreshFallbackWarning}. Stable
+ * values, but treat unknown strings as "fell back for an unspecified cause" —
+ * do not branch on this value for control flow. New values may be added in
+ * future releases.
+ */
+type CredentialRefreshFallbackReason = 'no-scope' | 'no-dpop-support' | 'endpoint-failed' | 'activation-timeout' | (string & {});
+/**
+ * Emitted when the SDK falls back to the developer-provided
+ * {@link CredentialProvider.refresh} because the Client Bound SAT path
+ * could not take over.
+ *
+ * Common causes:
+ * - The minted SAT lacks `sat:refresh` scope (`reason: 'no-scope'`).
+ * - The `/devices/token` exchange failed transiently (`reason: 'endpoint-failed'`).
+ *
+ * Subscribe to this warning to detect:
+ * - SDKs running with plain SATs that rely on developer-managed refresh
+ * - Deployments expected to use bound tokens that silently downgraded to bearer
+ *   (a security-relevant signal for fleet observability)
+ */
+interface CredentialRefreshFallbackWarning {
+  code: 'credential_refresh_fallback';
+  source: 'CredentialProvider';
+  reason: CredentialRefreshFallbackReason;
+  message: string;
+}
+/**
+ * Emitted when a credential has an `expiry_at` but the provider supplies no
+ * `refresh()` handler. The session will terminate at expiry with no fallback.
+ *
+ * Implementors who want long-lived sessions must provide a `refresh()` handler
+ * or mint tokens with the `sat:refresh` scope (Client Bound SAT path).
+ */
+interface CredentialNoRefreshHandlerWarning {
+  code: 'credential_no_refresh_handler';
+  source: 'CredentialProvider';
+  message: string;
+  /** Token expiry timestamp (epoch milliseconds). */
+  expiresAt: number;
+}
+//#endregion
 //#region src/utils/logger.d.ts
 /** Log level names supported by the SDK. */
 type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
@@ -3353,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. */
@@ -3423,10 +3557,10 @@ declare class SignalWire extends Destroyable implements DeviceController {
   private _isConnected$;
   private _isRegistered$;
   private _errors$;
+  private _warnings$;
   private _options;
-  private _refreshTimerId?;
   private _dpopManager?;
-  private _deviceTokenManager?;
+  private _refreshCoordinator?;
   private _credentialProvider?;
   private _deps;
   private _networkMonitor?;
@@ -3454,12 +3588,6 @@ declare class SignalWire extends Destroyable implements DeviceController {
    */
   private resolveCredentials;
   private validateCredentials;
-  /**
-   * Schedules credential refresh with exponential backoff retry on failure.
-   * On success, resets attempt counter and schedules the next refresh.
-   * After exhausting retries, emits TokenRefreshError and disconnects.
-   */
-  private scheduleCredentialRefresh;
   /** Persist credential to localStorage when persistSession is enabled. */
   private persistCredential;
   private init;
@@ -3546,6 +3674,17 @@ declare class SignalWire extends Destroyable implements DeviceController {
   get ready$(): Observable<boolean>;
   /** Observable stream of errors from transport, authentication, and devices. */
   get errors$(): Observable<Error>;
+  /**
+   * Observable stream of non-fatal SDK warnings.
+   *
+   * Subscribe to detect SDK behaviors that affect session liveness or developer-facing
+   * contracts but do not warrant disconnection — e.g., a fallback from Client Bound SAT
+   * refresh to the developer-provided `refresh()` because the SAT lacks `sat:refresh`
+   * scope. Discriminated by `code`.
+   *
+   * Independent from {@link errors$}: existing error consumers are not notified.
+   */
+  get warnings$(): Observable<SDKWarning>;
   /** Platform WebRTC capabilities detected at construction time. */
   get platformCapabilities(): PlatformCapabilities;
   /** Observable that emits when the SDK auto-switches a device. */
@@ -3563,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.
    */
@@ -3744,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
@@ -4622,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
@@ -4635,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.
    *
@@ -4739,5 +4905,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 CredentialProvider, 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 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, 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.cts.map