@signalwire/js 4.0.0-dev-20260324190414 → 4.0.0-dev-20260401142150

package/dist/browser.mjs

@@ -10167,6 +10167,7 @@ var NavigatorDeviceController = class extends Destroyable {
 
 //#endregion
 //#region src/dependencies/DefaultLocalStorage.ts
+/** Default storage implementation backed by browser `localStorage` and `sessionStorage`. */
 var DefaultLocalStorage = class {
 	constructor() {
 		if (typeof localStorage === "undefined") throw new StorageNotAvailableError("localStorage");
@@ -11961,54 +11962,71 @@ var Participant = class extends Destroyable {
 	get type() {
 		return this._state$.value.type;
 	}
+	/** Whether the participant has raised their hand. */
 	get handraised() {
 		return this._state$.value.handraised ?? false;
 	}
+	/** Whether the participant is visible in the layout. */
 	get visible() {
 		return this._state$.value.visible ?? false;
 	}
+	/** Whether the participant's audio is muted. */
 	get audioMuted() {
 		return this._state$.value.audio_muted ?? false;
 	}
+	/** Whether the participant's video is muted. */
 	get videoMuted() {
 		return this._state$.value.video_muted ?? false;
 	}
+	/** Whether the participant is deafened (incoming audio muted). */
 	get deaf() {
 		return this._state$.value.deaf ?? false;
 	}
+	/** Current microphone input volume level, or `undefined` if not set. */
 	get inputVolume() {
 		return this._state$.value.input_volume;
 	}
+	/** Current speaker output volume level, or `undefined` if not set. */
 	get outputVolume() {
 		return this._state$.value.output_volume;
 	}
+	/** Current microphone input sensitivity level, or `undefined` if not set. */
 	get inputSensitivity() {
 		return this._state$.value.input_sensitivity;
 	}
+	/** Whether echo cancellation is enabled. */
 	get echoCancellation() {
 		return this._state$.value.echo_cancellation ?? false;
 	}
+	/** Whether automatic gain control is enabled. */
 	get autoGain() {
 		return this._state$.value.auto_gain ?? false;
 	}
+	/** Whether noise suppression is enabled. */
 	get noiseSuppression() {
 		return this._state$.value.noise_suppression ?? false;
 	}
+	/** Whether low-bitrate mode is active. */
 	get lowbitrate() {
 		return this._state$.value.lowbitrate ?? false;
 	}
+	/** Whether noise reduction (denoise) is active. */
 	get denoise() {
 		return this._state$.value.denoise ?? false;
 	}
+	/** Custom metadata for this participant, or `undefined` if not set. */
 	get meta() {
 		return this._state$.value.meta;
 	}
+	/** Subscriber ID of this participant, or `undefined` if not available. */
 	get subscriberId() {
 		return this._state$.value.subscriber_id;
 	}
+	/** Address ID of this participant, or `undefined` if not available. */
 	get addressId() {
 		return this._state$.value.address_id;
 	}
+	/** Server node ID for this participant, or `undefined` if not available. */
 	get nodeId() {
 		return this._state$.value.node_id;
 	}
@@ -12080,15 +12098,24 @@ var Participant = class extends Destroyable {
 	async setAudioInputSensitivity(value) {
 		await this.executeMethod(this.id, "call.microphone.sensitivity.set", { sensitivity: value });
 	}
-	/** Sets the microphone input volume level. */
+	/**
+	* Sets the microphone input volume level.
+	* @param value - Volume level (0-100).
+	*/
 	async setAudioInputVolume(value) {
 		await this.executeMethod(this.id, "call.microphone.volume.set", { volume: value });
 	}
-	/** Sets the speaker output volume level. */
+	/**
+	* Sets the speaker output volume level.
+	* @param value - Volume level (0-100).
+	*/
 	async setAudioOutputVolume(value) {
 		await this.executeMethod(this.id, "call.speaker.volume.set", { volume: value });
 	}
-	/** Sets the participant's position in the video layout. */
+	/**
+	* Sets the participant's position in the video layout.
+	* @param value - The {@link VideoPosition} to assign (e.g. `'auto'`, `'reserved-0'`).
+	*/
 	async setPosition(value) {
 		await this.executeMethod(this.id, "call.member.position.set", { position: value });
 	}
@@ -12106,12 +12133,23 @@ var Participant = class extends Destroyable {
 	async end() {
 		await this.executeMethod(this.id, "call.end", {});
 	}
+	/**
+	* Replaces custom metadata for this participant.
+	* @param _meta - Metadata object to set.
+	* @throws {UnimplementedError} Not yet implemented.
+	*/
 	async setMeta(_meta) {
 		throw new UnimplementedError();
 	}
+	/**
+	* Merges values into custom metadata (unlike {@link setMeta} which replaces).
+	* @param _meta - Metadata to merge.
+	* @throws {UnimplementedError} Not yet implemented.
+	*/
 	async updateMeta(_meta) {
 		throw new UnimplementedError();
 	}
+	/** Destroys the participant, releasing all subscriptions and references. */
 	destroy() {
 		this.executeMethod = void 0;
 		super.destroy();
@@ -12124,6 +12162,7 @@ var Participant = class extends Destroyable {
 * and local media stream management.
 */
 var SelfParticipant = class extends Participant {
+	/** @internal */
 	constructor(id, executeMethod, vertoManager, deviceController) {
 		super(id, executeMethod, deviceController);
 		this.vertoManager = vertoManager;
@@ -12214,6 +12253,7 @@ var SelfParticipant = class extends Participant {
 		this.deviceController.selectAudioOutputDevice(device);
 		if (options.savePreference) PreferencesContainer.instance.preferredAudioOutput = device;
 	}
+	/** Mutes local audio. Falls back to local device mute if the server RPC fails. */
 	async mute() {
 		try {
 			await super.mute();
@@ -12223,6 +12263,7 @@ var SelfParticipant = class extends Participant {
 			this.vertoManager.muteMainAudioInputDevice();
 		}
 	}
+	/** Unmutes local audio. Falls back to local device unmute if the server RPC fails. */
 	async unmute() {
 		try {
 			await super.unmute();
@@ -12232,6 +12273,7 @@ var SelfParticipant = class extends Participant {
 			await this.vertoManager.unmuteMainAudioInputDevice();
 		}
 	}
+	/** Mutes local video. Falls back to local device mute if the server RPC fails. */
 	async muteVideo() {
 		try {
 			await super.muteVideo();
@@ -12241,6 +12283,7 @@ var SelfParticipant = class extends Participant {
 			this.vertoManager.muteMainVideoInputDevice();
 		}
 	}
+	/** Unmutes local video. Falls back to local device unmute if the server RPC fails. */
 	async unmuteVideo() {
 		try {
 			await super.unmuteVideo();
@@ -12276,6 +12319,7 @@ function isJSONRPCErrorResponse(value) {
 
 //#endregion
 //#region src/core/RPCMessages/guards/events.guards.ts
+/** @internal @packageDocumentation */
 /**
 * Factory function to create Request-level type guards.
 */
@@ -12299,6 +12343,7 @@ const isCallUpdatedRequest = createEventRequestGuard("call.updated");
 const isCallStateRequest = createEventRequestGuard("call.state");
 const isCallPlayRequest = createEventRequestGuard("call.play");
 const isCallConnectRequest = createEventRequestGuard("call.connect");
+const isRoomUpdatedRequest = createEventRequestGuard("room.updated");
 const isMemberUpdatedRequest = createEventRequestGuard("member.updated");
 const isMemberJoinedRequest = createEventRequestGuard("member.joined");
 const isMemberLeftRequest = createEventRequestGuard("member.left");
@@ -12310,7 +12355,7 @@ function isSignalwireMetadata(value) {
 	return isObject(value) && hasProperty(value, "event_type") && typeof value.event_type === "string" && hasProperty(value, "params");
 }
 function isSignalwireCallMetadata(value) {
-	return isSignalwireMetadata(value) && (isCallJoinedMetadata(value) || isCallLeftMetadata(value) || isCallUpdatedMetadata(value) || isCallStateMetadata(value) || isCallPlayMetadata(value) || isCallConnectMetadata(value) || isMemberUpdatedMetadata(value) || isMemberJoinedMetadata(value) || isMemberLeftMetadata(value) || isMemberTalkingMetadata(value) || isLayoutChangedMetadata(value) || isWebrtcMessageMetadata(value) || isConversationMessageMetadata(value) || isConversationMessageUpdatedMetadata(value));
+	return isSignalwireMetadata(value) && (isCallJoinedMetadata(value) || isCallLeftMetadata(value) || isCallUpdatedMetadata(value) || isCallStateMetadata(value) || isCallPlayMetadata(value) || isCallConnectMetadata(value) || isRoomUpdatedMetadata(value) || isMemberUpdatedMetadata(value) || isMemberJoinedMetadata(value) || isMemberLeftMetadata(value) || isMemberTalkingMetadata(value) || isLayoutChangedMetadata(value) || isWebrtcMessageMetadata(value) || isConversationMessageMetadata(value) || isConversationMessageUpdatedMetadata(value));
 }
 const isSignalwireAuthorizationStateMetadata = createEventMetadataGuard("signalwire.authorization.state");
 const isWebrtcMessageMetadata = createEventMetadataGuard("webrtc.message");
@@ -12320,6 +12365,7 @@ const isCallUpdatedMetadata = createEventMetadataGuard("call.updated");
 const isCallStateMetadata = createEventMetadataGuard("call.state");
 const isCallPlayMetadata = createEventMetadataGuard("call.play");
 const isCallConnectMetadata = createEventMetadataGuard("call.connect");
+const isRoomUpdatedMetadata = createEventMetadataGuard("room.updated");
 const isMemberUpdatedMetadata = createEventMetadataGuard("member.updated");
 const isMemberJoinedMetadata = createEventMetadataGuard("member.joined");
 const isMemberLeftMetadata = createEventMetadataGuard("member.left");
@@ -12455,6 +12501,7 @@ function throwOnRPCError() {
 var import_cjs$14 = require_cjs();
 const logger$15 = getLogger();
 const initialSessionState = {};
+/** @internal */
 var CallEventsManager = class extends Destroyable {
 	constructor(webRtcCallSession, options = {}) {
 		super();
@@ -12594,6 +12641,21 @@ var CallEventsManager = class extends Destroyable {
 				this._participants$.next(participants);
 			} else logger$15.warn(`[CallEventsManager] Received member.left event for unknown member ID: ${memberLeftEvent.member.member_id}`);
 		});
+		this.subscribeTo(this.webRtcCallSession.callUpdated$, (callUpdatedEvent) => {
+			logger$15.debug("[CallEventsManager] Handling call.updated event:", callUpdatedEvent);
+			const roomSession = callUpdatedEvent.room_session;
+			this._sessionState$.next({
+				...this._sessionState$.value,
+				recording: roomSession.recording,
+				recordings: roomSession.recordings,
+				streaming: roomSession.streaming,
+				streams: roomSession.streams,
+				playbacks: roomSession.playbacks,
+				prioritize_handraise: roomSession.prioritize_handraise,
+				locked: roomSession.locked,
+				meta: roomSession.meta
+			});
+		});
 		this.subscribeTo(this.layoutChangedEvent$, (layoutChangedEvent) => {
 			logger$15.debug("[CallEventsManager] Handling layout.changed event:", layoutChangedEvent);
 			this._sessionState$.next({
@@ -14505,7 +14567,7 @@ var WebRTCVertoManager = class extends VertoManager {
 	*
 	* @see selectAudioInputDevice
 	* @see selectVideoInputDevice
-	* @param options
+	* @param options - Media options specifying which input devices to add (defaults to audio only).
 	*/
 	async addMainInputDevices(options = { audio: true }) {
 		let deviceKind = void 0;
@@ -14589,7 +14651,7 @@ var WebRTCVertoManager = class extends VertoManager {
 		try {
 			const causeParams = cause ? {
 				cause,
-				cause_code: VertoByeCauseCodes[cause]
+				causeCode: VertoByeCauseCodes[cause]
 			} : {};
 			await this.executeVerto(VertoBye({
 				...causeParams,
@@ -14788,24 +14850,42 @@ var WebRTCCall = class extends Destroyable {
 	get self() {
 		return this.callEventsManager.self;
 	}
+	/** Toggles the call lock state, preventing or allowing new participants from joining. */
 	async toggleLock() {
 		const method = this.locked ? "call.unlock" : "call.lock";
 		await this.executeMethod(this.selfId ?? "", method, {});
 	}
+	/**
+	* Toggles the hold state of the call (pauses/resumes local media transmission).
+	*
+	* Distinct from {@link Participant.toggleMute} which mutes individual tracks.
+	*/
 	async toggleHold() {
 		if (this._holdState) await this.vertoManager.unhold();
 		else await this.vertoManager.hold();
 		this._holdState = !this._holdState;
 	}
+	/** @throws {UnimplementedError} Not yet implemented. Status tracked via {@link recording$}. */
 	async startRecording() {
 		throw new UnimplementedError();
 	}
+	/** @throws {UnimplementedError} Not yet implemented. Status tracked via {@link streaming$}. */
 	async startStreaming() {
 		throw new UnimplementedError();
 	}
+	/**
+	* Replaces the call's custom metadata.
+	* @param _meta - Metadata object to set.
+	* @throws {UnimplementedError} Not yet implemented.
+	*/
 	async setMeta(_meta) {
 		throw new UnimplementedError();
 	}
+	/**
+	* Merges values into the call's custom metadata (unlike {@link setMeta} which replaces).
+	* @param _meta - Metadata to merge.
+	* @throws {UnimplementedError} Not yet implemented.
+	*/
 	async updateMeta(_meta) {
 		throw new UnimplementedError();
 	}
@@ -14817,7 +14897,17 @@ var WebRTCCall = class extends Destroyable {
 	get layoutLayers() {
 		return this.callEventsManager.layoutLayers;
 	}
-	/** Executes a Verto RPC method targeting a specific participant. */
+	/**
+	* Executes a Verto RPC method targeting a specific participant.
+	*
+	* 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 method - Verto method name (e.g. `'call.mute'`, `'call.member.remove'`).
+	* @param args - Parameters for the RPC method.
+	* @returns The RPC response.
+	* @throws {JSONRPCError} If the RPC call returns an error.
+	*/
 	async executeMethod(target, method, args) {
 		const params = this.buildMethodParams(target, args);
 		const request = buildRPCRequest({
@@ -14979,7 +15069,16 @@ var WebRTCCall = class extends Destroyable {
 	get participantsId$() {
 		return this.cachedObservable("participantsId$", () => this.participants$.pipe((0, import_cjs$9.map)((participants) => participants.map((participant) => participant.id))));
 	}
-	/** Executes a raw JSON-RPC request on the client session. */
+	/**
+	* Executes a raw JSON-RPC request on the client session.
+	*
+	* Lower-level than {@link executeMethod} — allows full control over the RPC request structure.
+	*
+	* @param request - Complete JSON-RPC request object.
+	* @param options - Optional RPC execution options (timeout, etc.).
+	* @returns The RPC response.
+	* @throws {JSONRPCError} If the RPC call returns an error response.
+	*/
 	async execute(request, options) {
 		return this.clientSession.execute(request, options);
 	}
@@ -15012,17 +15111,19 @@ var WebRTCCall = class extends Destroyable {
 		}
 	}
 	get callSessionEvents$() {
-		return this.cachedObservable("callSessionEvents$", () => this.clientSession.signalingEvent$.pipe((0, import_cjs$9.filter)((event) => this.isCallSessionEvent(event)), (0, import_cjs$9.tap)((event) => logger$9.debug("[Call] Received call session event:", event)), (0, import_cjs$9.takeUntil)(this.destroyed$), (0, import_cjs$9.share)()));
+		return this.cachedObservable("callSessionEvents$", () => this.clientSession.signalingEvent$.pipe((0, import_cjs$9.filter)((event) => this.isCallSessionEvent(event)), (0, import_cjs$9.tap)((event) => {
+			logger$9.debug("[Call] Received call session event:", event);
+		}), (0, import_cjs$9.takeUntil)(this.destroyed$), (0, import_cjs$9.share)()));
 	}
 	/** Observable of call-updated events. */
 	get callUpdated$() {
 		return this.publicCachedObservable("callUpdated$", () => this.callSessionEvents$.pipe(filterAs(isCallUpdatedMetadata, "params"), (0, import_cjs$9.takeUntil)(this.destroyed$)));
 	}
-	/** Observable of member-joined events. */
+	/** Observable of member-joined events, emitted when a remote participant joins the call. */
 	get memberJoined$() {
 		return this.publicCachedObservable("memberJoined$", () => this.callSessionEvents$.pipe(filterAs(isMemberJoinedMetadata, "params"), (0, import_cjs$9.takeUntil)(this.destroyed$)));
 	}
-	/** Observable of member-left events. */
+	/** Observable of member-left events, emitted when a participant leaves the call. */
 	get memberLeft$() {
 		return this.publicCachedObservable("memberLeft$", () => this.callSessionEvents$.pipe(filterAs(isMemberLeftMetadata, "params"), (0, import_cjs$9.takeUntil)(this.destroyed$)));
 	}
@@ -15062,7 +15163,17 @@ var WebRTCCall = class extends Destroyable {
 	get layoutEvent$() {
 		return this.cachedObservable("layoutEvent$", () => this.callEvent$.pipe(filterAs(isLayoutChangedMetadata, "params")));
 	}
-	/** Hangs up the call and releases all resources. */
+	/**
+	* Hangs up the call and releases all resources.
+	*
+	* Sends a Verto `bye` to the server, transitions status to `'disconnecting'`,
+	* then destroys the call. After this, the call instance is no longer usable.
+	*
+	* @example
+	* ```ts
+	* await call.hangup();
+	* ```
+	*/
 	async hangup() {
 		this._status$.next("disconnecting");
 		try {
@@ -15071,11 +15182,35 @@ var WebRTCCall = class extends Destroyable {
 			this.destroy();
 		}
 	}
-	/** Sends DTMF digits (e.g. `'1234#'`) on the call. */
+	/**
+	* Sends DTMF digits on the call.
+	*
+	* @param dtmf - The digit string to send (e.g. `'1234#'`).
+	*
+	* @example
+	* ```ts
+	* await call.sendDigits('1234#');
+	* ```
+	*/
 	async sendDigits(dtmf) {
 		return this.vertoManager.sendDigits(dtmf);
 	}
-	/** Accepts an inbound call, optionally overriding media options for the answer. */
+	/**
+	* Accepts an inbound call, optionally overriding media options for the answer.
+	*
+	* @param options - Optional media constraints for the answer (audio/video).
+	*
+	* @example
+	* ```ts
+	* // Accept with defaults
+	* call.answer();
+	*
+	* // Accept audio-only
+	* call.answer({ audio: true, video: false });
+	* ```
+	* @see {@link reject} to decline the call instead.
+	* @see {@link answered$} to observe the acceptance state.
+	*/
 	answer(options) {
 		this._answerMediaOptions = options;
 		this._answered$.next(true);
@@ -15084,7 +15219,12 @@ var WebRTCCall = class extends Destroyable {
 	get answerMediaOptions() {
 		return this._answerMediaOptions;
 	}
-	/** Rejects an inbound call. */
+	/**
+	* Rejects an inbound call, preventing media negotiation.
+	*
+	* @see {@link answer} to accept the call instead.
+	* @see {@link answered$} to observe the rejection state.
+	*/
 	reject() {
 		this._answered$.next(false);
 	}
@@ -15094,8 +15234,17 @@ var WebRTCCall = class extends Destroyable {
 	}
 	/**
 	* Sets the call layout and participant positions.
+	*
 	* @param layout - Layout name (must be one of {@link layouts}).
-	* @param positions - Map of member IDs to video positions.
+	* @param positions - Map of member IDs to {@link VideoPosition} values.
+	* @throws {InvalidParams} If the layout is not in the available {@link layouts}.
+	*
+	* @example
+	* ```ts
+	* await call.setLayout('grid-responsive', {
+	*   [participantId]: 'reserved-0',
+	* });
+	* ```
 	*/
 	async setLayout(layout, positions) {
 		if (!this.layouts.includes(layout)) throw new InvalidParams(`Layout ${layout} is not available in the current call layouts: ${this.layouts.join(", ")}`);
@@ -15105,7 +15254,12 @@ var WebRTCCall = class extends Destroyable {
 			positions
 		});
 	}
-	/** Transfers the call to other participants. */
+	/**
+	* Transfers the call to another destination.
+	*
+	* @param options - Transfer configuration including the target destination.
+	* @see {@link status$} to observe the transfer progress.
+	*/
 	async transfer(options) {
 		return this.vertoManager.transfer(options);
 	}
@@ -15466,11 +15620,28 @@ var Address = class extends Destroyable {
 	get locked$() {
 		return this.cachedObservable("locked$", () => this._state$.pipe(filterNull(), (0, import_cjs$7.shareReplay)(1), (0, import_cjs$7.map)((state) => state.locked), (0, import_cjs$7.takeUntil)(this.destroyed$)));
 	}
-	/** Sends a text message to this address. */
+	/**
+	* Sends a text message to this address.
+	*
+	* @param text - The message text to send.
+	*
+	* @example
+	* ```ts
+	* await address.sendText('Hello!');
+	* ```
+	*/
 	async sendText(text) {
 		return this.conversationManager.sendText(text, this.id);
 	}
-	/** Collection of text messages for this address, with pagination support. */
+	/**
+	* Collection of text messages for this address, with pagination support.
+	*
+	* Returns `undefined` until {@link textMessages$} has been subscribed to (lazy-loaded).
+	* Filters to `'chat'` subtype messages from the conversation.
+	*
+	* @see {@link textMessages$} to trigger lazy loading.
+	* @see {@link sendText} to send a new message.
+	*/
 	get textMessage() {
 		if (!this._conversationMessages) return;
 		this._textMessages$ = this._textMessages$ ?? new EntityCollectionTransformed(this._conversationMessages, (item) => item.subtype === "chat", (item) => ({
@@ -15481,7 +15652,14 @@ var Address = class extends Destroyable {
 		}));
 		return this._textMessages$;
 	}
-	/** Collection of call history entries for this address, with pagination support. */
+	/**
+	* Collection of call history entries for this address, with pagination support.
+	*
+	* Returns `undefined` until {@link history$} has been subscribed to (lazy-loaded).
+	* Filters to `'log'` subtype messages including kind, status, start/end times.
+	*
+	* @see {@link history$} to trigger lazy loading.
+	*/
 	get history() {
 		if (!this._conversationMessages) return;
 		this._history$ = this._history$ ?? new EntityCollectionTransformed(this._conversationMessages, (item) => item.subtype === "log", (item) => ({
@@ -16071,11 +16249,18 @@ var AddressFetcher = class extends Fetcher {
 		logger$4.error("Failed to fetch addresses");
 	}
 };
+/** Collection of address states with reactive updates and pagination. */
 var AddressStateCollection = class extends EntityCollection {
 	constructor(update$, http, onError) {
 		super(new AddressFetcher(http), update$, onError);
 	}
 };
+/**
+* Manages the directory of {@link Address} entries with paginated loading.
+*
+* Implements the {@link Directory} interface and provides reactive access to
+* addresses via observables, along with pagination and lookup methods.
+*/
 var DirectoryManager = class extends Destroyable {
 	constructor(http, clientSession, conversationManager, onError) {
 		super();
@@ -16100,6 +16285,7 @@ var DirectoryManager = class extends Destroyable {
 		this._statesCollection = new AddressStateCollection(clientSession.signalingEvent$.pipe(filterAs(isConversationMessageUpdatedMetadata, "params"), (0, import_cjs$2.map)((_) => ({}))), this.http, this.onError);
 		this.initSubscriptions();
 	}
+	/** Whether addresses are currently being loaded from the server. */
 	get loading() {
 		return this._statesCollection.loading;
 	}
@@ -16113,28 +16299,57 @@ var DirectoryManager = class extends Destroyable {
 			}
 		});
 	}
+	/** Observable stream of all addresses in the directory. */
 	get addresses$() {
 		return this._addresses$.asObservable();
 	}
+	/** Current snapshot of all loaded addresses. */
 	get addresses() {
 		return this._addresses$.value;
 	}
+	/** Observable indicating whether more addresses can be loaded. */
 	get hasMore$() {
 		return this._statesCollection.hasMore$;
 	}
+	/** Observable of the current loading state. */
 	get loading$() {
 		return this._statesCollection.loading$;
 	}
+	/**
+	* Loads the next page of addresses from the server.
+	*
+	* No-op if {@link hasMore$} is `false`. Loading state is observable via {@link loading$}.
+	* New addresses are appended to {@link addresses$} when the page loads.
+	*/
 	loadMore() {
 		if (this._statesCollection.hasMore) this._statesCollection.loadMore();
 	}
+	/**
+	* Returns a reactive observable for a specific address by ID.
+	* @param id - The address ID to observe.
+	* @returns An observable of the address, or `undefined` if not found.
+	*/
 	get$(id) {
 		if (!this._observableRegistry.has(id)) this.addNewAddress(id);
 		return this._observableRegistry.get(id);
 	}
+	/**
+	* Returns an address by ID from the local cache.
+	* @param addressId - The address ID to look up.
+	* @returns The address, or `undefined` if not found.
+	*/
 	get(addressId) {
 		return this._addressesInstances.get(addressId);
 	}
+	/**
+	* Finds an address ID by its resource name (URI).
+	*
+	* Searches locally loaded addresses first, then queries the server if not found.
+	* The resource name is the {@link Address.name} identifier, distinct from display name.
+	*
+	* @param name - The resource name to search for (exact match, e.g. `'/public/conference'`).
+	* @returns The address ID, or `undefined` if no match is found locally or on server.
+	*/
 	async findAddressIdByURI(name) {
 		let addressId = this._addressesInstances.values().find((addr) => addr.name === name)?.id;
 		if (!addressId) {
@@ -16569,6 +16784,12 @@ const buildOptionsFromDestination = (destination) => {
 * ```
 */
 var SignalWire = class extends Destroyable {
+	/**
+	* Creates a new SignalWire client and begins connecting.
+	*
+	* @param credentialProvider - Provider that supplies authentication credentials.
+	* @param options - Configuration options (connection, device monitoring, preferences).
+	*/
 	constructor(credentialProvider, options = {}) {
 		super();
 		this.preferences = new ClientPreferences();
@@ -16802,7 +17023,12 @@ var SignalWire = class extends Destroyable {
 	get errors$() {
 		return this.deferEmission(this._errors$.asObservable());
 	}
-	/** Disconnects the WebSocket and tears down the session. */
+	/**
+	* Disconnects the WebSocket and tears down the current session.
+	*
+	* The client can be reconnected by calling {@link connect} again,
+	* which creates a fresh transport and session.
+	*/
 	async disconnect() {
 		await this._clientSession.disconnect();
 		this._clientSession.destroy();
@@ -16811,7 +17037,14 @@ var SignalWire = class extends Destroyable {
 	async waitAuthentication() {
 		await (0, import_cjs.firstValueFrom)(this.ready$.pipe((0, import_cjs.filter)((ready$1) => ready$1 === true)));
 	}
-	/** Registers the subscriber as online to receive inbound calls and events. */
+	/**
+	* Registers the subscriber as online to receive inbound calls and events.
+	*
+	* Waits for authentication to complete before sending the registration.
+	* If the initial attempt fails, reauthentication is attempted automatically.
+	*
+	* @throws {InvalidCredentialsError} If registration and reauthentication both fail.
+	*/
 	async register() {
 		try {
 			await this.waitAuthentication();
@@ -16839,7 +17072,11 @@ var SignalWire = class extends Destroyable {
 			throw error;
 		}
 	}
-	/** Unregisters the subscriber, going offline for inbound calls. */
+	/**
+	* Unregisters the subscriber, going offline for inbound calls.
+	*
+	* The WebSocket connection remains open; use {@link disconnect} to fully close it.
+	*/
 	async unregister() {
 		try {
 			await this._transport.execute(RPCExecute({
@@ -16855,9 +17092,27 @@ var SignalWire = class extends Destroyable {
 	}
 	/**
 	* Places an outbound call to the given destination.
-	* @param destination - Address URI string or {@link Address} instance to call.
-	* @param options - Media and dial options (audio/video, constraints).
+	*
+	* Waits for authentication before dialing. Media options are merged from
+	* saved preferences, destination query parameters (e.g. `?channel=video`),
+	* and the provided `options` (highest priority).
+	*
+	* Returns a {@link Call} in `'ringing'` state. Subscribe to {@link Call.status$}
+	* to track progression through `'connected'` → `'disconnected'`.
+	*
+	* @param destination - Address URI string (e.g. `'/public/my-room'`) or {@link Address} instance.
+	* @param options - Media and dial options (audio/video, device constraints). Overrides defaults.
 	* @returns The created {@link Call} instance.
+	* @throws {Error} If authentication is not complete or call creation fails.
+	*
+	* @example
+	* ```ts
+	* const call = await client.dial('/public/conference', {
+	*   audio: true,
+	*   video: true,
+	* });
+	* call.status$.subscribe(status => console.log('Call:', status));
+	* ```
 	*/
 	async dial(destination, options = {}) {
 		const computed_options = {
@@ -16953,12 +17208,23 @@ var SignalWire = class extends Destroyable {
 	disableDeviceMonitoring() {
 		this._deviceController.disableDeviceMonitoring();
 	}
+	/**
+	* Returns the capabilities of a media device.
+	* @param deviceInfo - The device to query.
+	* @returns The device capabilities, or `null` if unavailable.
+	*/
 	async getDeviceCapabilities(deviceInfo) {
 		return this._deviceController.getDeviceCapabilities(deviceInfo);
 	}
+	/**
+	* Checks whether a device is still available and usable.
+	* @param deviceInfo - The device to validate, or `null`.
+	* @returns `true` if the device is valid and available. Returns `false` for `null`, audio output devices, or unavailable devices.
+	*/
 	async isValidDevice(deviceInfo) {
 		return this._deviceController.isValidDevice(deviceInfo);
 	}
+	/** Destroys the client, clearing timers and releasing all resources. */
 	destroy() {
 		if (this._refreshTimerId) {
 			clearTimeout(this._refreshTimerId);
@@ -16971,6 +17237,7 @@ var SignalWire = class extends Destroyable {
 //#endregion
 //#region src/dependencies/EmbedTokenCredentialProvider.ts
 const logger = getLogger();
+/** Credential provider that exchanges an embed token for a SAT via the host's token endpoint. */
 var EmbedTokenCredentialProvider = class {
 	constructor(host, embedToken) {
 		this.host = host;