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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -134,8 +134,25 @@ interface AuthenticateContext {
134
134
  * - Setting `expiry_at` when the credential has a known expiration so the SDK can schedule refresh.
135
135
  * - Handling errors and never leaking sensitive data through error messages.
136
136
  *
137
- * The SDK owns the credential lifecycle: it calls `authenticate` once during initialization
138
- * and, if `refresh` is provided and `expiry_at` is set, schedules automatic refresh before expiry.
137
+ * ## Refresh precedence
138
+ *
139
+ * The SDK selects exactly one refresh mechanism per session, evaluated at connect
140
+ * time (and re-evaluated on reconnect):
141
+ *
142
+ * | `refresh` provided | SAT carries `sat:refresh` scope | Active mechanism |
143
+ * | ------------------ | -------------------------------- | ------------------------------------ |
144
+ * | yes | yes | Client Bound SAT (DPoP, internal) |
145
+ * | yes | no | Developer-provided `refresh()` |
146
+ * | no | yes | Client Bound SAT (DPoP, internal) |
147
+ * | no | no | None — session ends at `expiry_at` |
148
+ *
149
+ * When the SDK falls back to the developer-provided `refresh()` because the SAT
150
+ * lacked `sat:refresh` scope, a `credential_refresh_fallback` event is emitted on
151
+ * `SignalWire.warnings$` so application code can observe the transition.
152
+ *
153
+ * Mint a SAT via `POST /api/fabric/subscribers/tokens` with `fingerprint` and
154
+ * `scope: ["sat:refresh"]` (both currently optional on that endpoint) to enable
155
+ * the Client Bound SAT path; otherwise provide `refresh()` here.
139
156
  */
140
157
  interface CredentialProvider {
141
158
  /**
@@ -146,6 +163,8 @@ interface CredentialProvider {
146
163
  * - Reject (throw) on failure — this will cause client initialization to fail.
147
164
  * - When `context.fingerprint` is provided, forward it to the server-side token
148
165
  * endpoint with `scope: "sat:refresh"` to enable automatic token refresh.
166
+ * Ignoring `context.fingerprint` causes the SDK to fall back to `refresh()`
167
+ * (if provided) or end the session at expiry.
149
168
  *
150
169
  * SDK behavior:
151
170
  * - Awaits this method before establishing the WebSocket connection.
@@ -160,14 +179,12 @@ interface CredentialProvider {
160
179
  * - Reject (throw) if refresh is not possible — the SDK will stop the refresh schedule.
161
180
  *
162
181
  * SDK behavior:
163
- * - Only called when `expiry_at` was set on the previous credential.
182
+ * - Only called when `expiry_at` was set on the previous credential AND the
183
+ * SAT does not carry `sat:refresh` scope (otherwise the SDK refreshes
184
+ * internally via Client Bound SAT). See the precedence table above.
164
185
  * - Scheduled automatically before expiry; implementors do not need to manage timing.
165
186
  * - On rejection, the refresh schedule stops and the session continues with the
166
187
  * current credentials until they expire.
167
- * - When not provided and the SAT includes a `sat:refresh` scope, the SDK
168
- * automatically refreshes via Client Bound SAT (DPoP) without developer intervention.
169
- * - When not provided and no refresh scope is present, the SDK uses the initial
170
- * credentials for the entire session lifetime.
171
188
  */
172
189
  refresh?: () => Promise<SDKCredential>;
173
190
  }
@@ -325,6 +342,12 @@ interface MediaOptions {
325
342
  receiveAudio?: boolean;
326
343
  /** Whether to receive remote video. */
327
344
  receiveVideo?: boolean;
345
+ /**
346
+ * When local media can't be acquired (permission denied or device
347
+ * unavailable), continue the call in receive-only mode instead of failing.
348
+ * Defaults to `true`. Ignored when the call is not set to receive any media.
349
+ */
350
+ fallbackToReceiveOnly?: boolean;
328
351
  }
329
352
  //#endregion
330
353
  //#region src/containers/PreferencesContainer.d.ts
@@ -795,7 +818,7 @@ interface Member {
795
818
  member_id: string;
796
819
  call_id: string;
797
820
  name: string;
798
- type: 'member' | 'screen';
821
+ type: 'member' | 'screen' | 'device' | (string & {});
799
822
  parent_id?: string;
800
823
  requested_position?: string;
801
824
  handraised: boolean;
@@ -803,17 +826,17 @@ interface Member {
803
826
  audio_muted: boolean;
804
827
  video_muted: boolean;
805
828
  deaf: boolean;
806
- input_volume: number;
807
- output_volume: number;
808
- input_sensitivity: number;
829
+ input_volume?: number;
830
+ output_volume?: number;
831
+ input_sensitivity?: number;
809
832
  echo_cancellation: boolean;
810
833
  auto_gain: boolean;
811
834
  noise_suppression: boolean;
812
835
  lowbitrate: boolean;
813
836
  denoise: boolean;
814
- talking: boolean;
815
- isAudience: boolean;
816
- meta: Record<string, unknown>;
837
+ talking?: boolean;
838
+ isAudience?: boolean;
839
+ meta?: Record<string, unknown>;
817
840
  subscriber_id: string;
818
841
  address_id: string;
819
842
  updated?: string[];
@@ -935,6 +958,15 @@ interface RoomUpdatedPayload {
935
958
  room_id: string;
936
959
  room_session_id: string;
937
960
  }
961
+ /**
962
+ * Describes the peer (remote) call referenced from a call.state event.
963
+ *
964
+ * Mirrors the backend (relay.c) `peer` shape.
965
+ */
966
+ interface CallStateRelatedCall {
967
+ call_id?: string;
968
+ node_id?: string;
969
+ }
938
970
  interface CallStatePayload {
939
971
  call_id: string;
940
972
  node_id: string;
@@ -942,10 +974,19 @@ interface CallStatePayload {
942
974
  call_state: SignalingCallStates;
943
975
  direction: CallDirection;
944
976
  device: CallDevice;
945
- start_time: number;
946
- answer_time: number;
947
- end_time: number;
977
+ /**
978
+ * Epoch timestamps for the call lifecycle. Optional because pre-answer
979
+ * states (e.g. `created`, `ringing`) do not have an `answer_time`/`end_time`
980
+ * and the backend reports them as `0` or omits them.
981
+ */
982
+ start_time?: number;
983
+ answer_time?: number;
984
+ end_time?: number;
948
985
  room_session_id: string;
986
+ /** The peer (remote) call this call is connected to, if any. */
987
+ peer?: CallStateRelatedCall;
988
+ /** Application-defined tag associated with the call. */
989
+ tag?: string;
949
990
  }
950
991
  interface CallPlayPayload {
951
992
  control_id: string;
@@ -1151,6 +1192,32 @@ declare class MediaTrackError extends Error {
1151
1192
  originalError: unknown;
1152
1193
  constructor(operation: string, kind: string, originalError: unknown);
1153
1194
  }
1195
+ /**
1196
+ * Failure to acquire local media (camera, microphone, or screen capture)
1197
+ * via `getUserMedia`/`getDisplayMedia`.
1198
+ *
1199
+ * Non-fatal by default: screenshare and additional-device failures never
1200
+ * end the call, and main-connection failures degrade to receive-only when
1201
+ * possible. The wrapping site sets `fatal` to `true` only when the call
1202
+ * cannot continue (receive-only fallback disabled or no receive intent).
1203
+ */
1204
+ declare class MediaAccessError extends Error {
1205
+ /** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
1206
+ operation: string;
1207
+ /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
1208
+ media: string;
1209
+ /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
1210
+ originalError: unknown;
1211
+ /** Whether this failure terminates the call. */
1212
+ readonly fatal: boolean;
1213
+ constructor(/** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
1214
+ operation: string, /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
1215
+ media: string, /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
1216
+ originalError: unknown, /** Whether this failure terminates the call. */
1217
+ fatal?: boolean);
1218
+ /** True when the underlying failure is a permission denial (user or policy). */
1219
+ get denied(): boolean;
1220
+ }
1154
1221
  declare class DPoPInitError extends Error {
1155
1222
  originalError: unknown;
1156
1223
  constructor(originalError: unknown, message?: string);
@@ -1491,6 +1558,8 @@ interface MemberCapabilities {
1491
1558
  readonly meta: boolean;
1492
1559
  readonly remove: boolean;
1493
1560
  readonly audioFlags: boolean;
1561
+ readonly denoise: boolean;
1562
+ readonly lowbitrate: boolean;
1494
1563
  }
1495
1564
  /**
1496
1565
  * Call-level capabilities state
@@ -1844,6 +1913,8 @@ declare class Participant extends Destroyable implements CallParticipant {
1844
1913
  get addressId(): string | undefined;
1845
1914
  /** Server node ID for this participant, or `undefined` if not available. */
1846
1915
  get nodeId(): string | undefined;
1916
+ /** Call ID for this participant's leg, or `undefined` if not available. */
1917
+ get callId(): string | undefined;
1847
1918
  /** @internal */
1848
1919
  get value(): Partial<Member>;
1849
1920
  /** Toggles the deafened state (mutes/unmutes incoming audio). */
@@ -1868,6 +1939,7 @@ declare class Participant extends Destroyable implements CallParticipant {
1868
1939
  toggleAudioInputAutoGain(): Promise<void>;
1869
1940
  /** Toggles noise suppression on the audio input. */
1870
1941
  toggleNoiseSuppression(): Promise<void>;
1942
+ /** Toggles low-bitrate mode for this participant's media. */
1871
1943
  toggleLowbitrate(): Promise<void>;
1872
1944
  /**
1873
1945
  * Adjusts the **conference-only** microphone energy gate / sensitivity level
@@ -1908,6 +1980,14 @@ declare class Participant extends Destroyable implements CallParticipant {
1908
1980
  setAudioOutputVolume(value: number): Promise<void>;
1909
1981
  /**
1910
1982
  * Sets the participant's position in the video layout.
1983
+ *
1984
+ * Requires the `member.position` capability. The gateway keys positions by the
1985
+ * **target member's own** `call_id`/`node_id` (see issue #19400 and the legacy
1986
+ * `setPositions` implementation), so this sends the participant's own call
1987
+ * context — matching {@link Participant.remove}. A resolved promise does not
1988
+ * guarantee a visible change: the backend silently returns `200` (no-op) for
1989
+ * non-conference targets.
1990
+ *
1911
1991
  * @param value - The {@link VideoPosition} to assign (e.g. `'auto'`, `'reserved-0'`).
1912
1992
  */
1913
1993
  setPosition(value: VideoPosition): Promise<void>;
@@ -1966,7 +2046,15 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
1966
2046
  * Sets echoCancellation, noiseSuppression, and autoGainControl to true.
1967
2047
  */
1968
2048
  disableStudioAudio(): Promise<void>;
1969
- /** Starts sharing the local screen. */
2049
+ /**
2050
+ * Starts sharing the local screen.
2051
+ *
2052
+ * The call is unaffected when acquisition fails.
2053
+ *
2054
+ * @throws The raw `getDisplayMedia` error. A dismissed picker or a
2055
+ * permission denial rejects with a `NotAllowedError` `DOMException` —
2056
+ * inspect `error.name` to tell benign cancels apart from real failures.
2057
+ */
1970
2058
  startScreenShare(): Promise<void>;
1971
2059
  /** Observable of the current screen share status. */
1972
2060
  get screenShareStatus$(): Observable<ScreenShareStatus>;
@@ -1974,7 +2062,14 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
1974
2062
  get screenShareStatus(): ScreenShareStatus;
1975
2063
  /** Stops the current screen share. */
1976
2064
  stopScreenShare(): Promise<void>;
1977
- /** Adds an additional media input device to the call. */
2065
+ /**
2066
+ * Adds an additional media input device to the call.
2067
+ *
2068
+ * The call is unaffected when acquisition fails.
2069
+ *
2070
+ * @throws The raw `getUserMedia` error (e.g. `NotAllowedError` on
2071
+ * permission denial) — inspect `error.name` to decide how to react.
2072
+ */
1978
2073
  addAdditionalDevice(options: MediaOptions): Promise<void>;
1979
2074
  /** Removes an additional media input device by ID. */
1980
2075
  removeAdditionalDevice(id: string): Promise<void>;
@@ -2081,6 +2176,7 @@ interface CallParticipant {
2081
2176
  readonly userId: string | undefined;
2082
2177
  readonly addressId: string | undefined;
2083
2178
  readonly nodeId: string | undefined;
2179
+ readonly callId: string | undefined;
2084
2180
  readonly isTalking: boolean;
2085
2181
  readonly position: LayoutLayer | undefined;
2086
2182
  readonly isAudience: boolean;
@@ -3095,7 +3191,34 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
3095
3191
  private get authentication();
3096
3192
  connect(): Promise<void>;
3097
3193
  private handleAuthenticationError;
3194
+ /**
3195
+ * Clear the resume state (authorization_state + protocol) only.
3196
+ *
3197
+ * This is the stale-auth-state recovery helper used by handleAuthError:
3198
+ * the server rejected a reconnect, so the resume state is discarded and a
3199
+ * fresh connect follows. Attach records are deliberately preserved — the
3200
+ * session lives on through the reconnect and reattachCalls() needs the
3201
+ * stored call references afterwards. Do NOT add detachAll() here.
3202
+ *
3203
+ * For public teardown (disconnect/destroy), use {@link teardownSessionState}
3204
+ * instead, which clears the attach records as well.
3205
+ */
3098
3206
  cleanupStoredConnectionParams(): Promise<void>;
3207
+ /**
3208
+ * Public-teardown helper for disconnect()/destroy(). Clears the resume
3209
+ * state (authorization_state + protocol) AND the attach records as one
3210
+ * atomic unit.
3211
+ *
3212
+ * The two stores are coupled: the backend only honors attach records
3213
+ * within the session identified by the resume state, so ending the
3214
+ * session must clear both. Clearing one without the other strands records
3215
+ * no future session can honor (disconnect) or revives a session the
3216
+ * developer explicitly ended (destroy).
3217
+ *
3218
+ * Distinct from {@link cleanupStoredConnectionParams}, which keeps the
3219
+ * attach records for the stale-auth-state recovery path.
3220
+ */
3221
+ teardownSessionState(): Promise<void>;
3099
3222
  protected updateAuthState(authorization_state: string): Promise<void>;
3100
3223
  reauthenticate(token: string, dpopToken?: string, options?: {
3101
3224
  clientBound?: boolean;
@@ -3280,6 +3403,60 @@ declare class ClientSessionWrapper implements SessionState {
3280
3403
  get calls(): Call[];
3281
3404
  }
3282
3405
  //#endregion
3406
+ //#region src/core/types/warnings.types.d.ts
3407
+ /**
3408
+ * Non-fatal warning emitted via {@link SignalWire.warnings$ | client.warnings$}.
3409
+ *
3410
+ * Use to detect SDK behaviors that affect session liveness or developer-facing
3411
+ * contracts but do not warrant disconnection. Discriminated by `code`.
3412
+ *
3413
+ * Existing consumers of `errors$` are NOT notified — `warnings$` is a separate
3414
+ * channel so application code can react to warnings without triggering
3415
+ * error-handling code paths (e.g., disconnect cascades, user-facing toasts).
3416
+ */
3417
+ type SDKWarning = CredentialRefreshFallbackWarning | CredentialNoRefreshHandlerWarning;
3418
+ /**
3419
+ * Diagnostic detail for {@link CredentialRefreshFallbackWarning}. Stable
3420
+ * values, but treat unknown strings as "fell back for an unspecified cause" —
3421
+ * do not branch on this value for control flow. New values may be added in
3422
+ * future releases.
3423
+ */
3424
+ type CredentialRefreshFallbackReason = 'no-scope' | 'no-dpop-support' | 'endpoint-failed' | 'activation-timeout' | (string & {});
3425
+ /**
3426
+ * Emitted when the SDK falls back to the developer-provided
3427
+ * {@link CredentialProvider.refresh} because the Client Bound SAT path
3428
+ * could not take over.
3429
+ *
3430
+ * Common causes:
3431
+ * - The minted SAT lacks `sat:refresh` scope (`reason: 'no-scope'`).
3432
+ * - The `/devices/token` exchange failed transiently (`reason: 'endpoint-failed'`).
3433
+ *
3434
+ * Subscribe to this warning to detect:
3435
+ * - SDKs running with plain SATs that rely on developer-managed refresh
3436
+ * - Deployments expected to use bound tokens that silently downgraded to bearer
3437
+ * (a security-relevant signal for fleet observability)
3438
+ */
3439
+ interface CredentialRefreshFallbackWarning {
3440
+ code: 'credential_refresh_fallback';
3441
+ source: 'CredentialProvider';
3442
+ reason: CredentialRefreshFallbackReason;
3443
+ message: string;
3444
+ }
3445
+ /**
3446
+ * Emitted when a credential has an `expiry_at` but the provider supplies no
3447
+ * `refresh()` handler. The session will terminate at expiry with no fallback.
3448
+ *
3449
+ * Implementors who want long-lived sessions must provide a `refresh()` handler
3450
+ * or mint tokens with the `sat:refresh` scope (Client Bound SAT path).
3451
+ */
3452
+ interface CredentialNoRefreshHandlerWarning {
3453
+ code: 'credential_no_refresh_handler';
3454
+ source: 'CredentialProvider';
3455
+ message: string;
3456
+ /** Token expiry timestamp (epoch milliseconds). */
3457
+ expiresAt: number;
3458
+ }
3459
+ //#endregion
3283
3460
  //#region src/utils/logger.d.ts
3284
3461
  /** Log level names supported by the SDK. */
3285
3462
  type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
@@ -3353,8 +3530,12 @@ interface SignalWireOptions {
3353
3530
  * When `false` (default), session data lives in `sessionStorage` and is
3354
3531
  * lost on reload.
3355
3532
  *
3356
- * Call {@link SignalWire.destroy | destroy()} to clear all persisted state
3357
- * (explicit logout).
3533
+ * Both {@link SignalWire.disconnect | disconnect()} and
3534
+ * {@link SignalWire.destroy | destroy()} end the session and clear the
3535
+ * persisted resume state and attach records; credentials and device
3536
+ * preferences survive. Use `resetToDefaults()` for a full wipe, or
3537
+ * `unregister()` to temporarily stop receiving inbound calls while keeping
3538
+ * the session alive.
3358
3539
  */
3359
3540
  persistSession?: boolean;
3360
3541
  /** Custom storage implementation for persistence. */
@@ -3423,10 +3604,10 @@ declare class SignalWire extends Destroyable implements DeviceController {
3423
3604
  private _isConnected$;
3424
3605
  private _isRegistered$;
3425
3606
  private _errors$;
3607
+ private _warnings$;
3426
3608
  private _options;
3427
- private _refreshTimerId?;
3428
3609
  private _dpopManager?;
3429
- private _deviceTokenManager?;
3610
+ private _refreshCoordinator?;
3430
3611
  private _credentialProvider?;
3431
3612
  private _deps;
3432
3613
  private _networkMonitor?;
@@ -3454,12 +3635,6 @@ declare class SignalWire extends Destroyable implements DeviceController {
3454
3635
  */
3455
3636
  private resolveCredentials;
3456
3637
  private validateCredentials;
3457
- /**
3458
- * Schedules credential refresh with exponential backoff retry on failure.
3459
- * On success, resets attempt counter and schedules the next refresh.
3460
- * After exhausting retries, emits TokenRefreshError and disconnects.
3461
- */
3462
- private scheduleCredentialRefresh;
3463
3638
  /** Persist credential to localStorage when persistSession is enabled. */
3464
3639
  private persistCredential;
3465
3640
  private init;
@@ -3546,6 +3721,17 @@ declare class SignalWire extends Destroyable implements DeviceController {
3546
3721
  get ready$(): Observable<boolean>;
3547
3722
  /** Observable stream of errors from transport, authentication, and devices. */
3548
3723
  get errors$(): Observable<Error>;
3724
+ /**
3725
+ * Observable stream of non-fatal SDK warnings.
3726
+ *
3727
+ * Subscribe to detect SDK behaviors that affect session liveness or developer-facing
3728
+ * contracts but do not warrant disconnection — e.g., a fallback from Client Bound SAT
3729
+ * refresh to the developer-provided `refresh()` because the SAT lacks `sat:refresh`
3730
+ * scope. Discriminated by `code`.
3731
+ *
3732
+ * Independent from {@link errors$}: existing error consumers are not notified.
3733
+ */
3734
+ get warnings$(): Observable<SDKWarning>;
3549
3735
  /** Platform WebRTC capabilities detected at construction time. */
3550
3736
  get platformCapabilities(): PlatformCapabilities;
3551
3737
  /** Observable that emits when the SDK auto-switches a device. */
@@ -3563,6 +3749,14 @@ declare class SignalWire extends Destroyable implements DeviceController {
3563
3749
  /**
3564
3750
  * Disconnects the WebSocket and tears down the current session.
3565
3751
  *
3752
+ * Ends the session identified by the protocol and clears its persisted
3753
+ * resume state (`authorization_state` + protocol) and attach records
3754
+ * together — a later {@link connect} with the same credentials starts a
3755
+ * fresh session and cannot reattach to the ended session's calls.
3756
+ * Credentials and device preferences are preserved. To temporarily stop
3757
+ * receiving inbound calls while keeping the session alive, use
3758
+ * `unregister()` instead.
3759
+ *
3566
3760
  * The client can be reconnected by calling {@link connect} again,
3567
3761
  * which creates a fresh transport and session.
3568
3762
  */
@@ -3744,7 +3938,15 @@ declare class SignalWire extends Destroyable implements DeviceController {
3744
3938
  * attached call IDs, and all SDK storage keys, then re-enumerates devices.
3745
3939
  */
3746
3940
  resetToDefaults(): Promise<void>;
3747
- /** Destroys the client, clearing timers and releasing all resources. */
3941
+ /**
3942
+ * Destroys the client, clearing timers and releasing all resources.
3943
+ *
3944
+ * Intentionally destroying the client ends its session: the resume state
3945
+ * (`authorization_state` + protocol) and the attach records are both
3946
+ * cleared. Credentials and device preferences are preserved — use
3947
+ * {@link resetToDefaults} for a full wipe. To temporarily stop receiving
3948
+ * inbound calls while keeping the session alive, use `unregister()`.
3949
+ */
3748
3950
  destroy(): void;
3749
3951
  }
3750
3952
  //#endregion
@@ -4077,6 +4279,25 @@ declare class RTCPeerConnectionController extends Destroyable {
4077
4279
  */
4078
4280
  private setupTrackHandling;
4079
4281
  private setupLocalTracks;
4282
+ /** True for a main connection with no local media to send. */
4283
+ private hasNoLocalMediaToSend;
4284
+ /** The media kinds this connection wants to send: 'audiovideo' | 'video' | 'audio'. */
4285
+ private get requestedMediaKinds();
4286
+ /**
4287
+ * Handle a local media acquisition failure with a typed, semantically
4288
+ * accurate MediaAccessError created at the acquisition site:
4289
+ * - Auxiliary connections (screenshare / additional-device) throw a
4290
+ * non-fatal error — VertoManager surfaces it and the call is unaffected.
4291
+ * - The main connection degrades to receive-only when allowed (default),
4292
+ * otherwise fails with a fatal error.
4293
+ */
4294
+ private handleLocalMediaFailure;
4295
+ /**
4296
+ * Negotiate receive-only m-lines when there are no local tracks to send.
4297
+ * Only offer-type connections add transceivers — answer-type connections
4298
+ * reuse the transceivers created from the remote offer.
4299
+ */
4300
+ private setupReceiveOnlyTransceivers;
4080
4301
  private getUserMedia;
4081
4302
  private getDisplayMedia;
4082
4303
  private setupRemoteTracks;
@@ -4622,10 +4843,21 @@ declare class WebRTCCall extends Destroyable implements CallManager {
4622
4843
  /** Observable that emits `true` when answered, `false` when rejected. */
4623
4844
  get answered$(): Observable<boolean>;
4624
4845
  /**
4625
- * Sets the call layout and participant positions.
4846
+ * Sets the call layout and, optionally, individual participant positions.
4847
+ *
4848
+ * The gateway `call.layout.set` DTO has **no** `positions` member, so when
4849
+ * `positions` is provided this method issues a `call.member.position.set`
4850
+ * request per member (via {@link Participant.setPosition}, which keys each
4851
+ * position by that member's own call context) alongside `call.layout.set`
4852
+ * (issue #19400, Flag #6).
4853
+ *
4854
+ * **These operations are NOT atomic.** The layout is applied first, then each
4855
+ * member position sequentially, so members may briefly flash into their
4856
+ * default slots before being moved to the requested positions.
4626
4857
  *
4627
4858
  * @param layout - Layout name (must be one of {@link layouts}).
4628
- * @param positions - Map of member IDs to {@link VideoPosition} values.
4859
+ * @param positions - Optional map of member IDs to {@link VideoPosition} values.
4860
+ * When omitted or empty, only the layout is changed.
4629
4861
  * @throws {InvalidParams} If the layout is not in the available {@link layouts}.
4630
4862
  *
4631
4863
  * @example
@@ -4635,7 +4867,7 @@ declare class WebRTCCall extends Destroyable implements CallManager {
4635
4867
  * });
4636
4868
  * ```
4637
4869
  */
4638
- setLayout(layout: string, positions: Record<string, VideoPosition>): Promise<void>;
4870
+ setLayout(layout: string, positions?: Record<string, VideoPosition>): Promise<void>;
4639
4871
  /**
4640
4872
  * Transfers the call to another destination.
4641
4873
  *
@@ -4739,5 +4971,5 @@ declare const version: string;
4739
4971
  */
4740
4972
  declare const ready: boolean;
4741
4973
  //#endregion
4742
- 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 };
4974
+ 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 };
4743
4975
  //# sourceMappingURL=index.d.cts.map