@signalwire/js 4.0.0-dev-20260714201720 → 4.0.0-dev-20260721161304

package/dist/index.d.cts

@@ -1173,6 +1173,14 @@ declare class CallCreateError extends Error {
   direction: 'inbound' | 'outbound';
   constructor(message: string, error?: unknown, direction?: 'inbound' | 'outbound', options?: ErrorOptions);
 }
+declare class CallNotReadyError extends Error {
+  callId: string;
+  constructor(callId: string, options?: ErrorOptions);
+}
+declare class ParticipantNotReadyError extends Error {
+  memberId: string;
+  constructor(memberId: string, options?: ErrorOptions);
+}
 declare class VertoPongError extends Error {
   originalError: unknown;
   constructor(originalError: unknown);
@@ -1789,12 +1797,12 @@ type ParticipantState = Member & {
  * the local participant with additional device control.
  */
 declare class Participant extends Destroyable implements CallParticipant {
-  protected executeMethod: ExecuteMethod;
+  private callExecuteMethod;
   protected deviceController: DeviceController;
   /** Unique member ID of this participant. */
   readonly id: string;
   private _state$;
-  constructor(id: string, executeMethod: ExecuteMethod, deviceController: DeviceController);
+  constructor(id: string, callExecuteMethod: ExecuteMethod, deviceController: DeviceController);
   /** @internal */
   upnext(data: Partial<ParticipantState>): void;
   /** Observable of the participant's display name. */
@@ -1917,6 +1925,30 @@ declare class Participant extends Destroyable implements CallParticipant {
   get callId(): string | undefined;
   /** @internal */
   get value(): Partial<Member>;
+  /**
+   * Target triple for member RPCs, built from the participant's own state.
+   * The backend locates the member's session by the target `call_id`/`node_id`,
+   * so this must always be the participant's own call context — never the
+   * local call's id (issue #19400).
+   *
+   * Reading it doubles as a readiness probe: it throws until the first full
+   * member event (`member.joined`/`member.updated` or the `call.joined`
+   * roster) arrives, and never regresses afterwards.
+   *
+   * @throws {ParticipantNotReadyError} If the member state has not been
+   * received yet (e.g. a participant first seen via `member.talking`) — an
+   * empty call context can never address the member, so fail fast instead of
+   * sending a doomed RPC.
+   */
+  get target(): MemberTarget;
+  /**
+   * Executes a member RPC against this participant, injecting its own
+   * {@link target} as the target.
+   *
+   * @throws {ParticipantNotReadyError} Via {@link target}, when the
+   * member state has not been received yet.
+   */
+  protected executeMethod(method: string, args: Record<string, unknown>): Promise<JSONRPCResponse>;
   /** Toggles the deafened state (mutes/unmutes incoming audio). */
   toggleDeaf(): Promise<void>;
   /** Toggles the hand-raised state. */
@@ -1981,12 +2013,10 @@ declare class Participant extends Destroyable implements CallParticipant {
   /**
    * 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.
+   * Requires the `member.position` capability. The gateway requires a
+   * `targets` array of `{ target, position }` entries (issue #19400). 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'`).
    */
@@ -2030,7 +2060,7 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
    */
   private _studioAudio$;
   /** @internal */
-  constructor(id: string, executeMethod: ExecuteMethod, vertoManager: VertoManager, deviceController: DeviceController);
+  constructor(id: string, callExecuteMethod: ExecuteMethod, vertoManager: VertoManager, deviceController: DeviceController);
   destroy(): void;
   /** Observable indicating whether studio audio (raw/unprocessed audio) mode is enabled. */
   get studioAudio$(): Observable<boolean>;
@@ -2177,6 +2207,9 @@ interface CallParticipant {
   readonly addressId: string | undefined;
   readonly nodeId: string | undefined;
   readonly callId: string | undefined;
+  /** The member's own RPC target triple. Throws `ParticipantNotReadyError`
+   *  until the member's call context has been received. */
+  readonly target: MemberTarget;
   readonly isTalking: boolean;
   readonly position: LayoutLayer | undefined;
   readonly isAudience: boolean;
@@ -3635,6 +3668,59 @@ declare class SignalWire extends Destroyable implements DeviceController {
    */
   private resolveCredentials;
   private validateCredentials;
+  /**
+   * Reauthenticate the currently-open session with a freshly obtained
+   * credential so the new token takes effect on the live socket immediately —
+   * not just on the next reconnect. No-op when the session is not
+   * connected/authenticated or the credential carries no token (e.g. an
+   * authorization-state-only refresh). Non-fatal: reauth failures surface on
+   * `errors$` without aborting the refresh that triggered this.
+   */
+  private reauthenticateLiveSession;
+  /**
+   * One-shot recovery for a live session that failed with a recoverable auth
+   * error (`-32002`/`-32003`) because its token went stale — e.g. a refresh
+   * timer that was throttled while the tab was backgrounded.
+   *
+   * Two steps, first that succeeds wins:
+   *   1. Reauthenticate with the in-memory token (a fresh DPoP proof is
+   *      generated automatically). Heals a session whose token was already
+   *      refreshed by the coordinator but never applied to the open socket,
+   *      and a client-bound session whose server-side auth merely drifted.
+   *   2. Re-mint via the developer provider's `refresh()` and reauthenticate.
+   *      Skipped for client-bound sessions (the DeviceTokenManager owns their
+   *      refresh; re-minting a base SAT here would drop the DPoP binding).
+   *
+   * @param allowRemint - Whether step 2 (provider re-mint) may run. Callers
+   *   pass `false` for non-auth failures so a transient network error never
+   *   escalates to a token re-mint; step 1 (in-memory reauth) always runs.
+   * @returns `true` if the session was reauthenticated, `false` otherwise.
+   */
+  private recoverStaleCredential;
+  /**
+   * Re-mint a credential via `provider.refresh()`, routed through the
+   * coordinator's shared in-flight guard so concurrent re-mint paths (a
+   * scheduled/resume refresh, -32003 recovery, and reconnect) never fire a
+   * second `provider.refresh()` in parallel — which rotating one-time-use
+   * refresh tokens reject. Falls back to a direct call only if the coordinator
+   * has not been constructed yet.
+   */
+  private remintCredential;
+  /**
+   * Re-mint credentials before a fresh (re)connect (`onBeforeReconnect` hook).
+   * The session invokes this only when it is client-bound OR the in-memory
+   * token is expired. The re-mint mechanism depends on the binding:
+   *   - Client-bound: `authenticate()` with the DPoP fingerprint to obtain a
+   *     fresh base SAT the upcoming reconnect can re-bind (the
+   *     DeviceTokenManager re-activates afterwards).
+   *   - Unbound: the developer's non-interactive `refresh()` handler.
+   *     `authenticate()` is deliberately NOT used here — it may be interactive
+   *     (a login prompt) and must not fire on a background reconnect.
+   *
+   * Rejects on failure so the session aborts the reconnect rather than
+   * replaying a stale token.
+   */
+  private refreshCredentialForReconnect;
   /** Persist credential to localStorage when persistSession is enabled. */
   private persistCredential;
   private init;
@@ -4602,14 +4688,27 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    *
    * Constructs call context (node_id, call_id, member_id) and sends the RPC request.
    *
-   * @param target - Target member ID string, or a {@link MemberTarget} object.
+   * @param target - Target {@link MemberTarget} triple, or the local member's
+   *   ID string for self-operations (any other string is rejected — a bare
+   *   member id cannot carry the remote member's own call context).
    * @param method - Verto method name (e.g. `'call.mute'`, `'call.member.remove'`).
    * @param args - Parameters for the RPC method.
    * @returns The RPC response.
+   * @throws {CallNotReadyError} If the call has no self member context yet.
+   * @throws {InvalidParams} If a string target is not the local member's ID.
    * @throws {JSONRPCError} If the RPC call returns an error.
    */
   executeMethod<T extends JSONRPCResponse = JSONRPCResponse>(target: string | MemberTarget, method: string, args: Record<string, unknown>): Promise<T>;
-  private buildMethodParams;
+  /**
+   * The local leg's member triple — sent as `self` in every member RPC
+   * envelope, and as the `target` of call-scoped self-operations (e.g. lock,
+   * layout).
+   *
+   * @throws {CallNotReadyError} Before `call.joined` delivers the self member
+   * context (`selfId`/`nodeId`) — an RPC without it cannot be routed, so fail
+   * fast instead of sending a doomed request.
+   */
+  private get callSelf();
   /** Observable of the current call status (e.g. `'ringing'`, `'connected'`). */
   get status$(): Observable<CallStatus>;
   /** Observable of the participants list, emits on join/leave/update. */
@@ -4853,12 +4952,17 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    *
    * **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.
+   * default slots before being moved to the requested positions. Targeted
+   * members are validated upfront, though: when any of them has no
+   * {@link Participant.target | member call context} yet, the whole call
+   * rejects before any request is sent and the layout is left unchanged.
    *
    * @param layout - Layout name (must be one of {@link layouts}).
    * @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}.
+   * @throws {ParticipantNotReadyError} If a targeted member's call context has
+   *   not been received yet — thrown before any request is sent.
    *
    * @example
    * ```ts
@@ -4971,5 +5075,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, 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 };
+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, CallNotReadyError, 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, ParticipantNotReadyError, 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