@soniox/node 1.1.2 → 2.0.1

package/dist/index.cjs

@@ -1,37 +1,16 @@
+let node_fs_promises = require("node:fs/promises");
 
 //#region src/constants.ts
 const SONIOX_API_BASE_URL = "https://api.soniox.com";
 const SONIOX_API_WS_URL = "wss://stt-rt.soniox.com/transcribe-websocket";
+const SONIOX_TTS_API_BASE_URL = "https://tts-rt.soniox.com";
+const SONIOX_TTS_WS_URL = "wss://tts-rt.soniox.com/tts-websocket";
 const SONIOX_TMP_API_KEY_USAGE_TYPE = "transcribe_websocket";
 const SONIOX_TMP_API_KEY_DURATION_MIN = 1;
 const SONIOX_TMP_API_KEY_DURATION_MAX = 3600;
 const SONIOX_API_WEBHOOK_HEADER_ENV = "SONIOX_API_WEBHOOK_HEADER";
 const SONIOX_API_WEBHOOK_SECRET_ENV = "SONIOX_API_WEBHOOK_SECRET";
 
-//#endregion
-//#region src/async/auth.ts
-var SonioxAuthAPI = class {
-	constructor(http) {
-		this.http = http;
-	}
-	/**
-	* Creates a temporary API key for client-side use.
-	*
-	* @param request - Request parameters for the temporary key
-	* @param signal - Optional AbortSignal for cancellation
-	* @returns The temporary API key response
-	*/
-	async createTemporaryKey(request, signal) {
-		if (!Number.isFinite(request.expires_in_seconds) || request.expires_in_seconds < 1 || request.expires_in_seconds > 3600) throw new Error("expires_in_seconds must be a finite number between 1 and 3600");
-		return (await this.http.request({
-			method: "POST",
-			path: "/v1/auth/temporary-api-key",
-			body: request,
-			...signal && { signal }
-		})).data;
-	}
-};
-
 //#endregion
 //#region ../core/src/errors.ts
 var SonioxError = class extends Error {
@@ -79,6 +58,208 @@ var SonioxError = class extends Error {
 	}
 };
 
+//#endregion
+//#region ../core/src/http-errors.ts
+/**
+* HTTP error handling for the Soniox SDK.
+*
+* Lives in `@soniox/core` so it can be shared by the browser-safe
+* `TtsRestClient` and the Node `HttpClient`. `@soniox/node` re-exports
+* these symbols for backwards compatibility.
+*/
+/** Maximum body text length to include in error details (4KB) */
+const MAX_BODY_TEXT_LENGTH = 4096;
+/**
+* HTTP error class for all HTTP-related failures (REST API).
+*
+* Thrown when HTTP requests fail due to network issues, timeouts,
+* server errors, or response parsing failures.
+*/
+var SonioxHttpError = class extends SonioxError {
+	/** Request URL */
+	url;
+	/** HTTP method */
+	method;
+	/** Response headers (only for http_error) */
+	headers;
+	/** Response body text, capped at 4KB (only for http_error/parse_error) */
+	bodyText;
+	constructor(details) {
+		super(details.message, details.code, details.statusCode, details.cause);
+		this.name = "SonioxHttpError";
+		this.url = details.url;
+		this.method = details.method;
+		this.headers = details.headers;
+		this.bodyText = details.bodyText;
+	}
+	/**
+	* Creates a human-readable string representation
+	*/
+	toString() {
+		const parts = [`SonioxHttpError [${this.code}]: ${this.message}`];
+		parts.push(`  Method: ${this.method}`);
+		parts.push(`  URL: ${this.url}`);
+		if (this.statusCode !== void 0) parts.push(`  Status: ${this.statusCode}`);
+		return parts.join("\n");
+	}
+	/**
+	* Converts to a plain object for logging/serialization
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			url: this.url,
+			method: this.method,
+			...this.statusCode !== void 0 && { statusCode: this.statusCode },
+			...this.headers !== void 0 && { headers: this.headers },
+			...this.bodyText !== void 0 && { bodyText: this.bodyText }
+		};
+	}
+};
+/**
+* Creates a network error
+*/
+function createNetworkError(url, method, cause) {
+	return new SonioxHttpError({
+		code: "network_error",
+		message: `Network error: ${cause instanceof Error ? cause.message : "Network request failed"}`,
+		url,
+		method,
+		cause
+	});
+}
+/**
+* Creates a timeout error
+*/
+function createTimeoutError(url, method, timeoutMs) {
+	return new SonioxHttpError({
+		code: "timeout",
+		message: `Request timed out after ${timeoutMs}ms`,
+		url,
+		method
+	});
+}
+/**
+* Creates an abort error
+*/
+function createAbortError(url, method, cause) {
+	return new SonioxHttpError({
+		code: "aborted",
+		message: "Request was aborted",
+		url,
+		method,
+		cause
+	});
+}
+/**
+* Creates an HTTP error (non-2xx status)
+*/
+function createHttpError(url, method, statusCode, headers, bodyText) {
+	const cappedBody = truncateBodyText(bodyText);
+	return new SonioxHttpError({
+		code: "http_error",
+		message: `HTTP ${statusCode}`,
+		url,
+		method,
+		statusCode,
+		headers,
+		bodyText: cappedBody
+	});
+}
+/**
+* Creates a parse error (invalid JSON, etc.)
+*/
+function createParseError(url, method, bodyText, cause) {
+	const message = cause instanceof Error ? cause.message : "Failed to parse response";
+	const cappedBody = truncateBodyText(bodyText);
+	return new SonioxHttpError({
+		code: "parse_error",
+		message: `Parse error: ${message}`,
+		url,
+		method,
+		bodyText: cappedBody,
+		cause
+	});
+}
+/**
+* Truncates body text to the maximum allowed length
+*/
+function truncateBodyText(text) {
+	if (text.length <= MAX_BODY_TEXT_LENGTH) return text;
+	return text.slice(0, MAX_BODY_TEXT_LENGTH) + "... [truncated]";
+}
+/**
+* Type guard to check if an error is an AbortError
+*/
+function isAbortError(error) {
+	if (error instanceof Error) return error.name === "AbortError" || error.name === "TimeoutError";
+	return false;
+}
+/**
+* Type guard to check if an error is any SonioxError (base class).
+* This catches all SDK errors including HTTP and real-time errors.
+*/
+function isSonioxError(error) {
+	return error instanceof SonioxError;
+}
+/**
+* Type guard to check if an error is a SonioxHttpError
+*/
+function isSonioxHttpError(error) {
+	return error instanceof SonioxHttpError;
+}
+/**
+* Checks if an error is a 404 Not Found error
+*/
+function isNotFoundError(error) {
+	return isSonioxHttpError(error) && error.statusCode === 404;
+}
+
+//#endregion
+//#region ../core/src/connection.ts
+/** Root domain used for the default (US) deployment. */
+const DEFAULT_BASE_DOMAIN = "soniox.com";
+/**
+* Derives the four Soniox service URLs from a base domain.
+* All Soniox deployments follow the same subdomain pattern:
+*   api.{base}  /  stt-rt.{base}  /  tts-rt.{base}
+*/
+function urlsFromBase(base) {
+	return {
+		api_domain: `https://api.${base}`,
+		stt_ws_url: `wss://stt-rt.${base}/transcribe-websocket`,
+		tts_api_url: `https://tts-rt.${base}`,
+		tts_ws_url: `wss://tts-rt.${base}/tts-websocket`
+	};
+}
+/**
+* Resolve a {@link SonioxConnectionConfig} into fully qualified URLs.
+*
+* Resolution priority (highest → lowest) for each URL:
+* 1. Explicit field (`api_domain`, `stt_ws_url`, `tts_api_url`, `tts_ws_url`)
+* 2. Derived from `base_domain`
+* 3. Derived from `region` → `{region}.soniox.com`
+* 4. Default US base domain (`soniox.com`)
+*/
+function resolveConnectionConfig(config) {
+	const { region, base_domain, api_domain, stt_ws_url, tts_api_url, tts_ws_url } = config;
+	const normalizedRegion = region !== void 0 && region.toLowerCase() !== "us" ? region : void 0;
+	const derived = urlsFromBase(base_domain ?? (normalizedRegion !== void 0 ? `${normalizedRegion}.soniox.com` : DEFAULT_BASE_DOMAIN));
+	const sttDefaults = config.stt_defaults ?? config.session_defaults ?? {};
+	return {
+		api_key: config.api_key,
+		api_domain: api_domain ?? derived.api_domain,
+		stt_ws_url: stt_ws_url ?? derived.stt_ws_url,
+		tts_api_url: tts_api_url ?? derived.tts_api_url,
+		tts_ws_url: tts_ws_url ?? derived.tts_ws_url,
+		stt_defaults: sttDefaults,
+		tts_defaults: config.tts_defaults ?? {},
+		session_defaults: sttDefaults
+	};
+}
+
 //#endregion
 //#region ../core/src/segments.ts
 const DEFAULT_GROUP_BY = ["speaker", "language"];
@@ -161,10 +342,34 @@ var AsyncEventQueue = class {
 		return this.done;
 	}
 	/**
+	* Drop buffered events without ending the queue.
+	*
+	* Intended for owners that know their consumer has gone away (e.g. an
+	* async-iterator consumer broke out of its `for await` loop). The queue
+	* remains active and accepts future pushes. Callers must ensure no other
+	* iterator is concurrently consuming this queue, since this also drops
+	* events those consumers would have observed.
+	*/
+	clear() {
+		this.queue = [];
+	}
+	/**
 	* Async iterator implementation.
+	*
+	* The returned iterator implements `return()` so consumers that exit
+	* `for await` early (via `break`, `throw`, or an outer `return`) cleanly
+	* release the iteration without further work. The queue itself is left
+	* in place — call {@link clear} or {@link end}/{@link abort} if buffered
+	* events should also be dropped.
 	*/
 	[Symbol.asyncIterator]() {
-		return { next: () => this.next() };
+		return {
+			next: () => this.next(),
+			return: (value) => Promise.resolve({
+				value,
+				done: true
+			})
+		};
 	}
 	/**
 	* Get the next event from the queue.
@@ -422,8 +627,9 @@ function mapErrorResponse(response) {
 
 //#endregion
 //#region ../core/src/realtime/stt.ts
-const DEFAULT_KEEPALIVE_INTERVAL_MS = 5e3;
-const MIN_KEEPALIVE_INTERVAL_MS = 1e3;
+const DEFAULT_KEEPALIVE_INTERVAL_MS$1 = 5e3;
+const MIN_KEEPALIVE_INTERVAL_MS$1 = 1e3;
+const DEFAULT_CONNECT_TIMEOUT_MS$1 = 2e4;
 /**
 * Convert audio data to Uint8Array
 * Handles Uint8Array and ArrayBuffer
@@ -513,10 +719,12 @@ function filterSpecialTokens(tokens) {
 var RealtimeSttSession = class {
 	emitter = new TypedEmitter();
 	eventQueue = new AsyncEventQueue();
+	iteratorAttached = false;
 	apiKey;
 	wsBaseUrl;
 	config;
 	keepaliveIntervalMs;
+	connectTimeoutMs;
 	signal;
 	ws = null;
 	_state = "idle";
@@ -530,8 +738,10 @@ var RealtimeSttSession = class {
 		this.apiKey = apiKey;
 		this.wsBaseUrl = wsBaseUrl;
 		this.config = config;
-		const keepaliveMs = options?.keepalive_interval_ms ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
-		this.keepaliveIntervalMs = Number.isFinite(keepaliveMs) && keepaliveMs > 0 ? Math.max(keepaliveMs, MIN_KEEPALIVE_INTERVAL_MS) : DEFAULT_KEEPALIVE_INTERVAL_MS;
+		const keepaliveMs = options?.keepalive_interval_ms ?? DEFAULT_KEEPALIVE_INTERVAL_MS$1;
+		this.keepaliveIntervalMs = Number.isFinite(keepaliveMs) && keepaliveMs > 0 ? Math.max(keepaliveMs, MIN_KEEPALIVE_INTERVAL_MS$1) : DEFAULT_KEEPALIVE_INTERVAL_MS$1;
+		const connectMs = options?.connect_timeout_ms ?? DEFAULT_CONNECT_TIMEOUT_MS$1;
+		this.connectTimeoutMs = Number.isFinite(connectMs) && connectMs > 0 ? connectMs : DEFAULT_CONNECT_TIMEOUT_MS$1;
 		this.signal = options?.signal;
 		if (this.signal) {
 			this.abortHandler = () => this.handleAbort();
@@ -560,16 +770,26 @@ var RealtimeSttSession = class {
 	async connect() {
 		if (this._state !== "idle") throw new StateError(`Cannot connect: session is in "${this._state}" state`);
 		this.checkAborted();
-		this.setState("connecting");
+		this.setState("connecting", "user_action");
+		let connectTimer;
 		try {
-			await this.createWebSocket();
-			this.setState("connected");
+			await Promise.race([this.createWebSocket().then((v) => {
+				clearTimeout(connectTimer);
+				return v;
+			}), new Promise((_resolve, reject) => {
+				connectTimer = setTimeout(() => {
+					if (this.ws) this.ws.close();
+					reject(new ConnectionError("Connection timed out"));
+				}, this.connectTimeoutMs);
+			})]);
+			this.setState("connected", "connected");
 			this.emitter.emit("connected");
 			this.updateKeepalive();
 		} catch (error) {
+			clearTimeout(connectTimer);
 			if (!this.isTerminalState(this._state)) {
 				const err = error instanceof Error ? error : new ConnectionError("Connection failed", error);
-				this.cleanup("error", err);
+				this.cleanup("error", err, "error");
 			}
 			throw error;
 		}
@@ -647,7 +867,7 @@ var RealtimeSttSession = class {
 		this.checkAborted();
 		if (this._state !== "connected") throw new StateError(`Cannot finish: session is in "${this._state}" state`);
 		if (this._paused) this.resume();
-		this.setState("finishing");
+		this.setState("finishing", "user_action");
 		this.updateKeepalive();
 		const finishPromise = new Promise((resolve, reject) => {
 			this.finishResolver = resolve;
@@ -663,7 +883,7 @@ var RealtimeSttSession = class {
 		if (this.isTerminalState(this._state)) return;
 		this.emitter.emit("disconnected", "client_closed");
 		this.settleFinish(new StateError("Session canceled"));
-		this.cleanup("canceled");
+		this.cleanup("canceled", void 0, "user_action");
 	}
 	/**
 	* Register an event handler
@@ -688,9 +908,42 @@ var RealtimeSttSession = class {
 	}
 	/**
 	* Async iterator for consuming events.
+	*
+	* The returned iterator's `return()` resets the internal iterator-attach
+	* flag and drops any buffered events, so consumers that exit `for await`
+	* early (via `break` etc.) stop accruing memory while the session keeps
+	* running.
 	*/
 	[Symbol.asyncIterator]() {
-		return this.eventQueue[Symbol.asyncIterator]();
+		this.iteratorAttached = true;
+		const inner = this.eventQueue[Symbol.asyncIterator]();
+		return {
+			next: () => inner.next(),
+			return: (value) => {
+				this.iteratorAttached = false;
+				this.eventQueue.clear();
+				return inner.return?.(value) ?? Promise.resolve({
+					value,
+					done: true
+				});
+			}
+		};
+	}
+	/**
+	* @internal Debug-only: forcefully close the underlying WebSocket to
+	* simulate an unexpected network disconnection.
+	*/
+	__debugForceDisconnect() {
+		this.ws?.close(4999, "debug: simulated disconnect");
+	}
+	/**
+	* Push an event to the async iterator queue only when a consumer has
+	* attached via `[Symbol.asyncIterator]()`. Listener-only consumers
+	* (the documented `.on()` pattern) never drain the queue, so pushing
+	* unconditionally would leak buffered events on long-running sessions.
+	*/
+	enqueueIfIterating(event) {
+		if (this.iteratorAttached) this.eventQueue.push(event);
 	}
 	async createWebSocket() {
 		return new Promise((resolve, reject) => {
@@ -741,66 +994,70 @@ var RealtimeSttSession = class {
 				tokens: userTokens
 			};
 			this.emitter.emit("result", filteredResult);
-			this.eventQueue.push({
+			this.enqueueIfIterating({
 				kind: "result",
 				data: filteredResult
 			});
 			if (hasEndpoint) {
 				this.emitter.emit("endpoint");
-				this.eventQueue.push({ kind: "endpoint" });
+				this.enqueueIfIterating({ kind: "endpoint" });
 			}
 			if (hasFinalized) {
 				this.emitter.emit("finalized");
-				this.eventQueue.push({ kind: "finalized" });
+				this.enqueueIfIterating({ kind: "finalized" });
 			}
 			if (result.finished) {
 				this.emitter.emit("finished");
-				this.eventQueue.push({ kind: "finished" });
+				this.enqueueIfIterating({ kind: "finished" });
 				this.settleFinish();
-				this.cleanup("finished");
+				this.cleanup("finished", void 0, "finished");
 			}
 		} catch (error) {
 			const err = error;
 			this.emitter.emit("error", err);
 			this.settleFinish(err);
-			this.cleanup("error", err);
+			this.cleanup("error", err, "error");
 		}
 	}
 	handleClose(event) {
 		if (this.isTerminalState(this._state)) return;
 		this.emitter.emit("disconnected", event.reason || void 0);
 		if (this._state === "finishing") {
-			const error = new ConnectionError("WebSocket closed before finished response", event);
-			this.emitter.emit("error", error);
-			this.settleFinish(error);
-			this.cleanup("error", error);
+			const error$1 = new ConnectionError("WebSocket closed before finished response", event);
+			this.emitter.emit("error", error$1);
+			this.settleFinish(error$1);
+			this.cleanup("error", error$1, "connection_lost");
 			return;
 		}
-		this.cleanup("closed");
+		const error = new ConnectionError("WebSocket closed unexpectedly", event);
+		this.emitter.emit("error", error);
+		this.cleanup("closed", error, "connection_lost");
 	}
 	handleError(event) {
 		const error = new ConnectionError("WebSocket error", event);
 		this.emitter.emit("error", error);
 		this.settleFinish(error);
-		this.cleanup("error", error);
+		this.cleanup("error", error, "error");
 	}
 	handleAbort() {
 		const error = new AbortError();
 		this.emitter.emit("error", error);
 		this.settleFinish(error);
-		this.cleanup("canceled", error);
+		this.cleanup("canceled", error, "user_action");
 	}
-	setState(newState) {
+	setState(newState, reason) {
 		if (this._state === newState) return;
 		const oldState = this._state;
 		this._state = newState;
-		this.emitter.emit("state_change", {
+		const update = {
 			old_state: oldState,
 			new_state: newState
-		});
+		};
+		if (reason !== void 0) update.reason = reason;
+		this.emitter.emit("state_change", update);
 	}
-	cleanup(finalState, error) {
-		this.setState(finalState);
+	cleanup(finalState, error, reason) {
+		this.setState(finalState, reason);
 		this.stopKeepalive();
 		if (this.signal && this.abortHandler) {
 			this.signal.removeEventListener("abort", this.abortHandler);
@@ -834,7 +1091,7 @@ var RealtimeSttSession = class {
 			const error = new ConnectionError("WebSocket is not open");
 			this.emitter.emit("error", error);
 			this.settleFinish(error);
-			this.cleanup("error", error);
+			this.cleanup("error", error, "error");
 			if (shouldThrow) throw error;
 			return;
 		}
@@ -844,7 +1101,7 @@ var RealtimeSttSession = class {
 			const error = new ConnectionError("WebSocket send failed", err);
 			this.emitter.emit("error", error);
 			this.settleFinish(error);
-			this.cleanup("error", error);
+			this.cleanup("error", error, "error");
 			if (shouldThrow) throw error;
 		}
 	}
@@ -866,6 +1123,412 @@ var RealtimeSttSession = class {
 	}
 };
 
+//#endregion
+//#region ../core/src/realtime/tts.ts
+const MAX_STREAMS_PER_CONNECTION = 5;
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 5e3;
+const MIN_KEEPALIVE_INTERVAL_MS = 1e3;
+const DEFAULT_CONNECT_TIMEOUT_MS = 2e4;
+function generateStreamId() {
+	return globalThis.crypto.randomUUID();
+}
+function decodeBase64ToUint8Array(base64) {
+	const binaryString = atob(base64);
+	const bytes = new Uint8Array(binaryString.length);
+	for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+	return bytes;
+}
+/**
+* Merge a partial TTS stream input with defaults, validate required fields,
+* and return a fully resolved config ready for the WebSocket.
+*/
+function resolveStreamConfig(input, defaults) {
+	const merged = {
+		...defaults,
+		...input
+	};
+	const model = merged.model;
+	const language = merged.language;
+	const voice = merged.voice;
+	const audio_format = merged.audio_format;
+	const missing = [];
+	if (!model) missing.push("model");
+	if (!language) missing.push("language");
+	if (!voice) missing.push("voice");
+	if (!audio_format) missing.push("audio_format");
+	if (missing.length > 0) throw new Error(`Missing required TTS stream fields: ${missing.join(", ")}. Provide them directly or via tts_defaults in your connection config.`);
+	return {
+		model,
+		language,
+		voice,
+		audio_format,
+		...merged.sample_rate !== void 0 && { sample_rate: merged.sample_rate },
+		...merged.bitrate !== void 0 && { bitrate: merged.bitrate },
+		stream_id: merged.stream_id ?? generateStreamId()
+	};
+}
+/**
+* Handle for one TTS stream on a WebSocket connection.
+*
+* Emits typed events and supports async iteration over decoded audio chunks.
+*
+* @example Event-based
+* ```typescript
+* stream.on('audio', (chunk) => process(chunk));
+* stream.on('terminated', () => console.log('done'));
+* stream.sendText("Hello world");
+* stream.finish();
+* ```
+*
+* @example Async iteration
+* ```typescript
+* stream.sendText("Hello world");
+* stream.finish();
+* for await (const chunk of stream) {
+*   process(chunk);
+* }
+* ```
+*/
+var RealtimeTtsStream = class extends TypedEmitter {
+	streamId;
+	_state = "active";
+	audioQueue = new AsyncEventQueue();
+	iteratorAttached = false;
+	connection;
+	ownsConnection;
+	/** @internal */
+	constructor(streamId, connection, ownsConnection) {
+		super();
+		this.streamId = streamId;
+		this.connection = connection;
+		this.ownsConnection = ownsConnection;
+	}
+	/** Current stream lifecycle state. */
+	get state() {
+		return this._state;
+	}
+	/**
+	* Send one text chunk to the TTS stream.
+	*
+	* @param text - Text to synthesize
+	* @param options.end - If true, signals this is the final text chunk
+	*/
+	sendText(text, options) {
+		if (this._state !== "active") throw new StateError(`Cannot send text in state '${this._state}'`);
+		const payload = {
+			text,
+			text_end: options?.end ?? false,
+			stream_id: this.streamId
+		};
+		this.connection._sendJson(payload);
+		if (options?.end) this._state = "finishing";
+	}
+	/**
+	* Pipe an async iterable of text chunks into the stream.
+	* Automatically calls {@link finish} when the iterable completes.
+	*
+	* Designed for concurrent use: call `sendStream()` and consume audio
+	* via `for await` or events simultaneously.
+	*
+	* @example LLM token piping
+	* ```typescript
+	* stream.sendStream(llmTokenStream);
+	* for await (const audio of stream) { forward(audio); }
+	* ```
+	*/
+	async sendStream(source) {
+		for await (const chunk of source) {
+			if (this._state !== "active") break;
+			this.sendText(chunk);
+		}
+		if (this._state === "active") this.finish();
+	}
+	/**
+	* Signal that no more text will be sent for this stream.
+	* The server will finish generating audio and send `terminated`.
+	*/
+	finish() {
+		if (this._state !== "active") throw new StateError(`Cannot finish in state '${this._state}'`);
+		this.sendText("", { end: true });
+	}
+	/**
+	* Cancel this stream. The server will stop generating and send `terminated`.
+	*/
+	cancel() {
+		if (this._state === "ended" || this._state === "error") return;
+		const payload = {
+			stream_id: this.streamId,
+			cancel: true
+		};
+		try {
+			this.connection._sendJson(payload);
+		} catch {}
+	}
+	/**
+	* Close this stream. For single-stream usage (created via `tts(input)`),
+	* also closes the underlying WebSocket connection.
+	*/
+	close() {
+		this._endStream();
+		if (this.ownsConnection) this.connection.close();
+	}
+	/**
+	* Async iterator that yields decoded audio chunks.
+	*
+	* The returned iterator's `return()` resets the internal iterator-attach
+	* flag and drops any buffered audio, so consumers that exit `for await`
+	* early (via `break` etc.) stop accruing memory while the stream keeps
+	* receiving server audio.
+	*/
+	[Symbol.asyncIterator]() {
+		this.iteratorAttached = true;
+		const inner = this.audioQueue[Symbol.asyncIterator]();
+		return {
+			next: () => inner.next(),
+			return: (value) => {
+				this.iteratorAttached = false;
+				this.audioQueue.clear();
+				return inner.return?.(value) ?? Promise.resolve({
+					value,
+					done: true
+				});
+			}
+		};
+	}
+	/**
+	* Push an audio chunk to the async iterator queue only when a consumer
+	* has attached via `[Symbol.asyncIterator]()`. Listener-only consumers
+	* (the documented `.on('audio', ...)` pattern) never drain the queue,
+	* so pushing unconditionally would leak buffered chunks.
+	*/
+	enqueueIfIterating(chunk) {
+		if (this.iteratorAttached) this.audioQueue.push(chunk);
+	}
+	/** @internal Dispatch a server event to this stream. */
+	_handleEvent(event) {
+		if (event.error_code !== void 0) {
+			const errPayload = { error_code: event.error_code };
+			if (event.error_message !== void 0) errPayload.error_message = event.error_message;
+			const error = mapErrorResponse(errPayload);
+			this._state = "error";
+			this.emit("error", error);
+			this.audioQueue.abort(error);
+			this.connection._deactivateStream(this.streamId);
+			return;
+		}
+		if (event.audio !== void 0) {
+			const chunk = decodeBase64ToUint8Array(event.audio);
+			this.emit("audio", chunk);
+			this.enqueueIfIterating(chunk);
+		}
+		if (event.audio_end) this.emit("audioEnd");
+		if (event.terminated) this._endStream();
+	}
+	/** @internal Force-end this stream (connection closing). */
+	_forceEnd() {
+		if (this._state === "ended" || this._state === "error") return;
+		this._state = "ended";
+		this.audioQueue.end();
+	}
+	_endStream() {
+		if (this._state === "ended") return;
+		this._state = "ended";
+		this.emit("terminated");
+		this.audioQueue.end();
+		this.connection._deactivateStream(this.streamId);
+	}
+};
+/**
+* WebSocket connection for real-time Text-to-Speech.
+*
+* Supports up to 5 concurrent streams multiplexed by `stream_id`.
+* The connection automatically sends keepalive messages while open.
+*
+* @example Multi-stream
+* ```typescript
+* const conn = new RealtimeTtsConnection(apiKey, wsUrl, ttsDefaults);
+* await conn.connect();
+*
+* const s1 = conn.stream({ model, voice, language, audio_format });
+* s1.sendText("Hello");
+* s1.finish();
+* for await (const chunk of s1) { ... }
+*
+* conn.close();
+* ```
+*/
+var RealtimeTtsConnection = class extends TypedEmitter {
+	apiKey;
+	wsUrl;
+	ttsDefaults;
+	keepaliveIntervalMs;
+	connectTimeoutMs;
+	ws = null;
+	connected = false;
+	connecting = false;
+	keepaliveTimer = null;
+	activeStreams = /* @__PURE__ */ new Map();
+	constructor(apiKey, wsUrl, ttsDefaults = {}, options) {
+		super();
+		this.apiKey = apiKey;
+		this.wsUrl = wsUrl;
+		this.ttsDefaults = ttsDefaults;
+		const keepaliveMs = options?.keepalive_interval_ms ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
+		this.keepaliveIntervalMs = Number.isFinite(keepaliveMs) && keepaliveMs > 0 ? Math.max(keepaliveMs, MIN_KEEPALIVE_INTERVAL_MS) : DEFAULT_KEEPALIVE_INTERVAL_MS;
+		const connectMs = options?.connect_timeout_ms ?? DEFAULT_CONNECT_TIMEOUT_MS;
+		this.connectTimeoutMs = Number.isFinite(connectMs) && connectMs > 0 ? connectMs : DEFAULT_CONNECT_TIMEOUT_MS;
+	}
+	/** Whether the WebSocket is connected. */
+	get isConnected() {
+		return this.connected;
+	}
+	/**
+	* Open the WebSocket connection and start keepalive.
+	* Called automatically by {@link stream} if not yet connected.
+	*/
+	async connect() {
+		if (this.connected) return;
+		if (this.connecting) throw new StateError("Connection is already being established");
+		this.connecting = true;
+		try {
+			await this.createWebSocket();
+			this.connected = true;
+			this.startKeepalive();
+		} finally {
+			this.connecting = false;
+		}
+	}
+	/**
+	* Open a new TTS stream on this connection.
+	* Auto-connects if the WebSocket is not yet open.
+	*
+	* @param input - Stream configuration (merged with tts_defaults)
+	* @returns A ready-to-use stream handle
+	*/
+	async stream(input = {}) {
+		return this._openStream(input, false);
+	}
+	/** @internal Open a stream, optionally marking it as connection-owning. */
+	async _openStream(input, ownsConnection) {
+		if (!this.connected) await this.connect();
+		if (this.activeStreams.size >= MAX_STREAMS_PER_CONNECTION) throw new StateError(`Maximum concurrent streams (${MAX_STREAMS_PER_CONNECTION}) reached`);
+		const config = resolveStreamConfig(input, this.ttsDefaults);
+		if (this.activeStreams.has(config.stream_id)) throw new StateError(`Stream '${config.stream_id}' is already active on this connection`);
+		const stream = new RealtimeTtsStream(config.stream_id, this, ownsConnection);
+		this.activeStreams.set(config.stream_id, stream);
+		const configPayload = {
+			api_key: this.apiKey,
+			...config
+		};
+		this._sendJson(configPayload);
+		return stream;
+	}
+	/**
+	* Close the WebSocket connection and terminate all active streams.
+	*/
+	close() {
+		this.stopKeepalive();
+		for (const stream of this.activeStreams.values()) stream._forceEnd();
+		this.activeStreams.clear();
+		if (this.ws) {
+			try {
+				this.ws.close();
+			} catch {}
+			this.ws = null;
+		}
+		this.connected = false;
+		this.emit("close");
+	}
+	/** @internal Send a JSON payload on the WebSocket. */
+	_sendJson(payload) {
+		if (!this.ws || !this.connected) throw new StateError("TTS connection is not open");
+		this.ws.send(JSON.stringify(payload));
+	}
+	/** @internal Remove a stream from the active set. */
+	_deactivateStream(streamId) {
+		this.activeStreams.delete(streamId);
+	}
+	async createWebSocket() {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				try {
+					ws.close();
+				} catch {}
+				reject(new ConnectionError("TTS WebSocket connection timed out"));
+			}, this.connectTimeoutMs);
+			let ws;
+			try {
+				ws = new WebSocket(this.wsUrl);
+				ws.binaryType = "arraybuffer";
+			} catch (err) {
+				clearTimeout(timer);
+				reject(new ConnectionError(`Failed to create TTS WebSocket: ${err instanceof Error ? err.message : String(err)}`));
+				return;
+			}
+			const onOpen = () => {
+				clearTimeout(timer);
+				ws.removeEventListener("error", onError);
+				this.ws = ws;
+				ws.addEventListener("message", (event) => {
+					this.handleMessage(event);
+				});
+				ws.addEventListener("close", () => {
+					if (this.connected) {
+						this.connected = false;
+						this.stopKeepalive();
+						for (const stream of this.activeStreams.values()) stream._forceEnd();
+						this.activeStreams.clear();
+						this.emit("close");
+					}
+				});
+				resolve();
+			};
+			const onError = () => {
+				clearTimeout(timer);
+				ws.removeEventListener("open", onOpen);
+				reject(new ConnectionError("TTS WebSocket connection failed"));
+			};
+			ws.addEventListener("open", onOpen);
+			ws.addEventListener("error", onError);
+		});
+	}
+	handleMessage(event) {
+		if (typeof event.data !== "string") return;
+		let parsed;
+		try {
+			parsed = JSON.parse(event.data);
+		} catch {
+			return;
+		}
+		const streamId = parsed.stream_id;
+		if (streamId !== void 0) {
+			const stream = this.activeStreams.get(streamId);
+			if (stream) stream._handleEvent(parsed);
+			return;
+		}
+		if (parsed.error_code !== void 0) {
+			const errPayload = { error_code: parsed.error_code };
+			if (parsed.error_message !== void 0) errPayload.error_message = parsed.error_message;
+			const error = mapErrorResponse(errPayload);
+			this.emit("error", error);
+		}
+	}
+	startKeepalive() {
+		if (this.keepaliveTimer) return;
+		this.keepaliveTimer = setInterval(() => {
+			if (this.connected && this.ws) try {
+				this.ws.send(JSON.stringify({ keep_alive: true }));
+			} catch {}
+		}, this.keepaliveIntervalMs);
+	}
+	stopKeepalive() {
+		if (this.keepaliveTimer) {
+			clearInterval(this.keepaliveTimer);
+			this.keepaliveTimer = null;
+		}
+	}
+};
+
 //#endregion
 //#region ../core/src/realtime/segments.ts
 /**
@@ -1021,199 +1684,210 @@ var RealtimeUtteranceBuffer = class {
 	markEndpoint() {
 		const trailingSegments = this.segmentBuffer.flushAll();
 		const segments = [...this.pendingSegments, ...trailingSegments];
-		this.pendingSegments = [];
-		if (segments.length === 0) return;
-		return buildUtterance(segments, this.lastFinalAudioProcMs, this.lastTotalAudioProcMs);
-	}
-	/**
-	* Clear buffered segments and tokens.
-	*/
-	reset() {
-		this.pendingSegments = [];
-		this.segmentBuffer.reset();
-	}
-};
-function buildUtterance(segments, finalAudioProcMs, totalAudioProcMs) {
-	const tokens = segments.flatMap((segment) => segment.tokens);
-	return {
-		text: segments.map((segment) => segment.text).join(""),
-		segments,
-		tokens,
-		start_ms: segments[0]?.start_ms,
-		end_ms: segments[segments.length - 1]?.end_ms,
-		speaker: getCommonValue(segments.map((segment) => segment.speaker)),
-		language: getCommonValue(segments.map((segment) => segment.language)),
-		final_audio_proc_ms: finalAudioProcMs,
-		total_audio_proc_ms: totalAudioProcMs
-	};
-}
-function getCommonValue(values) {
-	let common;
-	for (const value of values) {
-		if (value === void 0) return;
-		if (common === void 0) {
-			common = value;
-			continue;
-		}
-		if (value !== common) return;
-	}
-	return common;
-}
-
-//#endregion
-//#region src/http/errors.ts
-/**
-* HTTP error handling for the Soniox SDK
-*/
-/** Maximum body text length to include in error details (4KB) */
-const MAX_BODY_TEXT_LENGTH = 4096;
-/**
-* HTTP error class for all HTTP-related failures (REST API).
-*
-* Thrown when HTTP requests fail due to network issues, timeouts,
-* server errors, or response parsing failures.
-*/
-var SonioxHttpError = class extends SonioxError {
-	/** Request URL */
-	url;
-	/** HTTP method */
-	method;
-	/** Response headers (only for http_error) */
-	headers;
-	/** Response body text, capped at 4KB (only for http_error/parse_error) */
-	bodyText;
-	constructor(details) {
-		super(details.message, details.code, details.statusCode, details.cause);
-		this.name = "SonioxHttpError";
-		this.url = details.url;
-		this.method = details.method;
-		this.headers = details.headers;
-		this.bodyText = details.bodyText;
-	}
-	/**
-	* Creates a human-readable string representation
-	*/
-	toString() {
-		const parts = [`SonioxHttpError [${this.code}]: ${this.message}`];
-		parts.push(`  Method: ${this.method}`);
-		parts.push(`  URL: ${this.url}`);
-		if (this.statusCode !== void 0) parts.push(`  Status: ${this.statusCode}`);
-		return parts.join("\n");
+		this.pendingSegments = [];
+		if (segments.length === 0) return;
+		return buildUtterance(segments, this.lastFinalAudioProcMs, this.lastTotalAudioProcMs);
 	}
 	/**
-	* Converts to a plain object for logging/serialization
+	* Clear buffered segments and tokens.
 	*/
-	toJSON() {
-		return {
-			name: this.name,
-			code: this.code,
-			message: this.message,
-			url: this.url,
-			method: this.method,
-			...this.statusCode !== void 0 && { statusCode: this.statusCode },
-			...this.headers !== void 0 && { headers: this.headers },
-			...this.bodyText !== void 0 && { bodyText: this.bodyText }
-		};
+	reset() {
+		this.pendingSegments = [];
+		this.segmentBuffer.reset();
 	}
 };
-/**
-* Creates a network error
-*/
-function createNetworkError(url, method, cause) {
-	return new SonioxHttpError({
-		code: "network_error",
-		message: `Network error: ${cause instanceof Error ? cause.message : "Network request failed"}`,
-		url,
-		method,
-		cause
-	});
-}
-/**
-* Creates a timeout error
-*/
-function createTimeoutError(url, method, timeoutMs) {
-	return new SonioxHttpError({
-		code: "timeout",
-		message: `Request timed out after ${timeoutMs}ms`,
-		url,
-		method
-	});
+function buildUtterance(segments, finalAudioProcMs, totalAudioProcMs) {
+	const tokens = segments.flatMap((segment) => segment.tokens);
+	return {
+		text: segments.map((segment) => segment.text).join(""),
+		segments,
+		tokens,
+		start_ms: segments[0]?.start_ms,
+		end_ms: segments[segments.length - 1]?.end_ms,
+		speaker: getCommonValue(segments.map((segment) => segment.speaker)),
+		language: getCommonValue(segments.map((segment) => segment.language)),
+		final_audio_proc_ms: finalAudioProcMs,
+		total_audio_proc_ms: totalAudioProcMs
+	};
 }
-/**
-* Creates an abort error
-*/
-function createAbortError(url, method, cause) {
-	return new SonioxHttpError({
-		code: "aborted",
-		message: "Request was aborted",
-		url,
-		method,
-		cause
-	});
+function getCommonValue(values) {
+	let common;
+	for (const value of values) {
+		if (value === void 0) return;
+		if (common === void 0) {
+			common = value;
+			continue;
+		}
+		if (value !== common) return;
+	}
+	return common;
 }
+
+//#endregion
+//#region ../core/src/tts-rest.ts
 /**
-* Creates an HTTP error (non-2xx status)
+* Browser-safe REST TTS client.
+*
+* Uses only `globalThis.fetch` — no Node-specific dependencies.
+* Shared by both `@soniox/node` and `@soniox/client`.
 */
-function createHttpError(url, method, statusCode, headers, bodyText) {
-	const cappedBody = truncateBodyText(bodyText);
-	return new SonioxHttpError({
-		code: "http_error",
-		message: `HTTP ${statusCode}`,
-		url,
-		method,
-		statusCode,
-		headers,
-		bodyText: cappedBody
-	});
+const DEFAULT_MODEL = "tts-rt-v1-preview";
+const DEFAULT_LANGUAGE = "en";
+const DEFAULT_AUDIO_FORMAT = "wav";
+function buildPayload(options) {
+	const payload = {
+		model: options.model ?? DEFAULT_MODEL,
+		language: options.language ?? DEFAULT_LANGUAGE,
+		voice: options.voice,
+		audio_format: options.audio_format ?? DEFAULT_AUDIO_FORMAT,
+		text: options.text
+	};
+	if (options.sample_rate !== void 0) payload.sample_rate = options.sample_rate;
+	if (options.bitrate !== void 0) payload.bitrate = options.bitrate;
+	return payload;
 }
 /**
-* Creates a parse error (invalid JSON, etc.)
+* Normalizes fetch Headers to a plain object with lowercase keys.
+* Duplicated here (rather than imported from `@soniox/node`) to keep
+* this module browser-safe.
 */
-function createParseError(url, method, bodyText, cause) {
-	const message = cause instanceof Error ? cause.message : "Failed to parse response";
-	const cappedBody = truncateBodyText(bodyText);
-	return new SonioxHttpError({
-		code: "parse_error",
-		message: `Parse error: ${message}`,
-		url,
-		method,
-		bodyText: cappedBody,
-		cause
+function headersToObject(headers) {
+	const result = {};
+	headers.forEach((value, key) => {
+		result[key.toLowerCase()] = value;
 	});
+	return result;
 }
-/**
-* Truncates body text to the maximum allowed length
-*/
-function truncateBodyText(text) {
-	if (text.length <= MAX_BODY_TEXT_LENGTH) return text;
-	return text.slice(0, MAX_BODY_TEXT_LENGTH) + "... [truncated]";
-}
-/**
-* Type guard to check if an error is an AbortError
-*/
-function isAbortError(error) {
+function isAbortLikeError(error) {
 	if (error instanceof Error) return error.name === "AbortError" || error.name === "TimeoutError";
 	return false;
 }
 /**
-* Type guard to check if an error is any SonioxError (base class).
-* This catches all SDK errors including HTTP and real-time errors.
-*/
-function isSonioxError(error) {
-	return error instanceof SonioxError;
-}
-/**
-* Type guard to check if an error is a SonioxHttpError
-*/
-function isSonioxHttpError(error) {
-	return error instanceof SonioxHttpError;
-}
-/**
-* Checks if an error is a 404 Not Found error
+* Browser-safe REST client for TTS generation.
+*
+* Provides `generate()` (buffered) and `generateStream()` (streaming)
+* using only `globalThis.fetch`. HTTP failures are surfaced as
+* {@link SonioxHttpError}, matching the rest of the Soniox SDK.
+*
+* Authentication uses the `Authorization: Bearer <api_key>` header.
+*
+* @example
+* ```typescript
+* const client = new TtsRestClient(apiKey, 'https://tts-rt.soniox.com');
+* const audio = await client.generate({ text: 'Hello', voice: 'Adrian' });
+* ```
 */
-function isNotFoundError(error) {
-	return isSonioxHttpError(error) && error.statusCode === 404;
-}
+var TtsRestClient = class {
+	apiKey;
+	ttsApiUrl;
+	constructor(apiKey, ttsApiUrl) {
+		this.apiKey = apiKey;
+		this.ttsApiUrl = ttsApiUrl;
+	}
+	/**
+	* Generate speech audio from text. Returns the full audio as a `Uint8Array`.
+	*
+	* @throws {@link SonioxHttpError} on non-2xx responses, network failures,
+	* or aborted requests.
+	*/
+	async generate(options) {
+		const url = `${this.ttsApiUrl}/tts`;
+		const buffer = await (await this.sendRequest(url, options)).arrayBuffer();
+		return new Uint8Array(buffer);
+	}
+	/**
+	* Generate speech audio from text as a streaming async iterable.
+	*
+	* Yields `Uint8Array` chunks as they arrive from the server response body.
+	* Lower time-to-first-audio than {@link generate}.
+	*
+	* **Known limitation:** Mid-stream server errors (reported via HTTP trailers)
+	* cannot be detected through the `fetch` API. The iterator may end early
+	* without an explicit error. Use WebSocket TTS for reliable error detection.
+	*
+	* @throws {@link SonioxHttpError} on non-2xx responses, network failures,
+	* or aborted requests (before the stream starts).
+	*/
+	async *generateStream(options) {
+		const url = `${this.ttsApiUrl}/tts`;
+		const response = await this.sendRequest(url, options);
+		if (!response.body) throw createHttpError(url, "POST", response.status, headersToObject(response.headers), "Response has no body stream");
+		const reader = response.body.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				yield value;
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	/**
+	* Internal request helper. Performs the fetch, maps network/abort failures
+	* to {@link SonioxHttpError}, and throws on non-2xx responses.
+	*/
+	async sendRequest(url, options) {
+		const payload = buildPayload(options);
+		let response;
+		try {
+			response = await globalThis.fetch(url, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(payload),
+				...options.signal && { signal: options.signal }
+			});
+		} catch (cause) {
+			if (isAbortLikeError(cause)) throw createAbortError(url, "POST", cause);
+			throw createNetworkError(url, "POST", cause);
+		}
+		if (!response.ok) {
+			const bodyText = await response.text().catch(() => "");
+			throw createHttpError(url, "POST", response.status, headersToObject(response.headers), bodyText);
+		}
+		return response;
+	}
+};
+
+//#endregion
+//#region src/async/auth.ts
+var SonioxAuthAPI = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Creates a temporary API key for client-side use.
+	*
+	* @param request - Request parameters for the temporary key
+	* @param signal - Optional AbortSignal for cancellation
+	* @returns The temporary API key response
+	*
+	* @example
+	* ```typescript
+	* const sttKey = await client.auth.createTemporaryKey({
+	*   usage_type: 'transcribe_websocket',
+	*   expires_in_seconds: 300,
+	* });
+	*
+	* const ttsKey = await client.auth.createTemporaryKey({
+	*   usage_type: 'tts_rt',
+	*   expires_in_seconds: 300,
+	* });
+	* ```
+	*/
+	async createTemporaryKey(request, signal) {
+		if (!Number.isFinite(request.expires_in_seconds) || request.expires_in_seconds < 1 || request.expires_in_seconds > 3600) throw new Error("expires_in_seconds must be a finite number between 1 and 3600");
+		return (await this.http.request({
+			method: "POST",
+			path: "/v1/auth/temporary-api-key",
+			body: request,
+			...signal && { signal }
+		})).data;
+	}
+};
 
 //#endregion
 //#region src/async/files.ts
@@ -2687,6 +3361,86 @@ var SonioxSttApi = class {
 	}
 };
 
+//#endregion
+//#region src/async/tts.ts
+/**
+* REST API for Text-to-Speech generation and TTS model listing.
+*
+* Accessed via `client.tts` on {@link SonioxNodeClient}.
+*
+* Inherits browser-safe `generate()` and `generateStream()` from
+* `TtsRestClient` in `@soniox/core`, and adds Node-specific methods
+* `generateToFile()` and `listModels()`.
+*/
+var SonioxTtsApi = class extends TtsRestClient {
+	http;
+	constructor(apiKey, ttsApiUrl, http) {
+		super(apiKey, ttsApiUrl);
+		this.http = http;
+	}
+	/**
+	* Generate speech audio and write to a file or writable stream.
+	*
+	* @param output - File path (string) or a `WritableStream<Uint8Array>`
+	* @param options - Generation options
+	* @returns Number of bytes written
+	*
+	* @example Write to file
+	* ```typescript
+	* const bytes = await client.tts.generateToFile('output.wav', {
+	*   text: 'Hello world',
+	*   voice: 'Adrian',
+	*   language: 'en',
+	* });
+	* ```
+	*
+	* @example Write to a writable stream
+	* ```typescript
+	* const bytes = await client.tts.generateToFile(writableStream, {
+	*   text: 'Hello world',
+	*   voice: 'Adrian',
+	*   language: 'en',
+	* });
+	* ```
+	*/
+	async generateToFile(output, options) {
+		if (typeof output === "string") {
+			const audio = await this.generate(options);
+			await (0, node_fs_promises.writeFile)(output, audio);
+			return audio.byteLength;
+		}
+		let bytesWritten = 0;
+		const writer = output.getWriter();
+		try {
+			for await (const chunk of this.generateStream(options)) {
+				await writer.write(chunk);
+				bytesWritten += chunk.byteLength;
+			}
+		} finally {
+			writer.releaseLock();
+		}
+		return bytesWritten;
+	}
+	/**
+	* List available TTS models and their voices.
+	*
+	* @example
+	* ```typescript
+	* const models = await client.tts.listModels();
+	* for (const model of models) {
+	*   console.log(model.id, model.voices.map(v => v.id));
+	* }
+	* ```
+	*/
+	async listModels(signal) {
+		return (await this.http.request({
+			method: "GET",
+			path: "/v1/tts-models",
+			...signal && { signal }
+		})).data.models;
+	}
+};
+
 //#endregion
 //#region src/async/webhooks.ts
 const VALID_STATUSES = ["completed", "error"];
@@ -3509,36 +4263,75 @@ function combineAbortSignals(...signals) {
 //#endregion
 //#region src/realtime/index.ts
 /**
-* Real-time API factory for creating STT sessions.
+* Real-time API factory for creating STT sessions and TTS connections.
 *
-* @example
+* @example STT
+* ```typescript
+* const session = client.realtime.stt({ model: 'stt-rt-v4' });
+* await session.connect();
+* ```
+*
+* @example TTS (single stream)
 * ```typescript
-* const session = client.realtime.stt({
-*   model: 'stt-rt-v4',
-*   enable_endpoint_detection: true,
+* const stream = await client.realtime.tts({
+*   model: 'tts-rt-v1-preview',
+*   voice: 'Adrian',
+*   language: 'en',
+*   audio_format: 'wav',
 * });
+* stream.sendText("Hello");
+* stream.finish();
+* for await (const chunk of stream) { ... }
+* ```
 *
-* await session.connect();
+* @example TTS (multi-stream)
+* ```typescript
+* const conn = await client.realtime.tts.multiStream();
+* const stream = await conn.stream({
+*   model: 'tts-rt-v1-preview',
+*   voice: 'Adrian',
+*   language: 'en',
+*   audio_format: 'wav',
+* });
 * ```
 */
 var SonioxRealtimeApi = class {
 	options;
+	tts;
 	constructor(options) {
 		this.options = options;
+		const ttsCall = (input) => {
+			return this.createSingleTtsStream(input ?? {});
+		};
+		ttsCall.multiStream = () => {
+			return this.createTtsConnection();
+		};
+		this.tts = ttsCall;
 	}
 	/**
 	* Create a new Speech-to-Text session.
 	*
-	* @param config - Session configuration (sent to server)
-	* @param options - Session options (SDK-level settings)
-	* @returns New STT session instance
+	* `config` is shallow-merged on top of `stt_defaults` from the client
+	* options; caller-provided fields override the defaults.
 	*/
 	stt(config, options) {
 		const mergedOptions = {
 			...this.options.default_session_options,
 			...options
 		};
-		return new RealtimeSttSession(this.options.api_key, this.options.ws_base_url, config, mergedOptions);
+		const mergedConfig = {
+			...this.options.stt_defaults,
+			...config
+		};
+		return new RealtimeSttSession(this.options.api_key, this.options.ws_base_url, mergedConfig, mergedOptions);
+	}
+	async createSingleTtsStream(input) {
+		return new RealtimeTtsConnection(this.options.api_key, this.options.tts_ws_url, this.options.tts_defaults ?? {}, this.options.tts_connection_options)._openStream(input, true);
+	}
+	async createTtsConnection() {
+		const connection = new RealtimeTtsConnection(this.options.api_key, this.options.tts_ws_url, this.options.tts_defaults ?? {}, this.options.tts_connection_options);
+		await connection.connect();
+		return connection;
 	}
 };
 
@@ -3546,20 +4339,37 @@ var SonioxRealtimeApi = class {
 //#region src/client.ts
 /**
 * Soniox Node Client
-* @returns {SonioxNodeClient}
 *
 * @example
 * ```typescript
 * import { SonioxNodeClient } from '@soniox/node';
 *
-* const client = new SonioxNodeClient({
-*   api_key: 'your-api-key',
+* // Default (US) region
+* const client = new SonioxNodeClient({ api_key: 'your-api-key' });
+*
+* // EU region
+* const client = new SonioxNodeClient({ api_key: 'your-api-key', region: 'eu' });
+*
+* // REST TTS
+* const audio = await client.tts.generate({
+*   text: 'Hello',
+*   voice: 'Adrian',
+*   language: 'en',
+* });
+*
+* // WebSocket TTS
+* const stream = await client.realtime.tts({
+*   model: 'tts-rt-v1-preview',
+*   voice: 'Adrian',
+*   language: 'en',
+*   audio_format: 'wav',
 * });
 * ```
 */
 var SonioxNodeClient = class {
 	files;
 	stt;
+	tts;
 	models;
 	webhooks;
 	auth;
@@ -3567,7 +4377,14 @@ var SonioxNodeClient = class {
 	constructor(options = {}) {
 		const apiKey = options.api_key ?? process.env["SONIOX_API_KEY"];
 		if (!apiKey) throw new Error("Missing API key. Provide it via options.api_key or set the SONIOX_API_KEY environment variable.");
-		const baseURL = options.base_url ?? process.env["SONIOX_API_BASE_URL"] ?? SONIOX_API_BASE_URL;
+		const regionDefaults = resolveConnectionConfig({
+			api_key: apiKey,
+			region: options.region ?? process.env["SONIOX_REGION"],
+			base_domain: options.base_domain ?? process.env["SONIOX_BASE_DOMAIN"],
+			stt_defaults: options.stt_defaults,
+			tts_defaults: options.tts_defaults
+		});
+		const baseURL = options.base_url ?? process.env["SONIOX_API_BASE_URL"] ?? regionDefaults.api_domain;
 		const http = options.http_client ?? new FetchHttpClient({
 			base_url: baseURL,
 			default_headers: {
@@ -3580,9 +4397,14 @@ var SonioxNodeClient = class {
 		this.models = new SonioxModelsAPI(http);
 		this.webhooks = new SonioxWebhooksAPI(this.stt);
 		this.auth = new SonioxAuthAPI(http);
+		this.tts = new SonioxTtsApi(apiKey, options.tts_api_url ?? process.env["SONIOX_TTS_API_URL"] ?? regionDefaults.tts_api_url, http);
 		this.realtime = new SonioxRealtimeApi({
 			api_key: apiKey,
-			ws_base_url: options.realtime?.ws_base_url ?? process.env["SONIOX_WS_URL"] ?? SONIOX_API_WS_URL,
+			ws_base_url: options.realtime?.ws_base_url ?? process.env["SONIOX_WS_URL"] ?? regionDefaults.stt_ws_url,
+			tts_ws_url: options.realtime?.tts_ws_url ?? process.env["SONIOX_TTS_WS_URL"] ?? regionDefaults.tts_ws_url,
+			stt_defaults: regionDefaults.stt_defaults,
+			tts_defaults: regionDefaults.tts_defaults,
+			tts_connection_options: options.realtime?.tts_connection_options,
 			default_session_options: options.realtime?.default_session_options
 		});
 	}
@@ -3600,6 +4422,8 @@ exports.QuotaError = QuotaError;
 exports.RealtimeError = RealtimeError;
 exports.RealtimeSegmentBuffer = RealtimeSegmentBuffer;
 exports.RealtimeSttSession = RealtimeSttSession;
+exports.RealtimeTtsConnection = RealtimeTtsConnection;
+exports.RealtimeTtsStream = RealtimeTtsStream;
 exports.RealtimeUtteranceBuffer = RealtimeUtteranceBuffer;
 exports.SONIOX_API_BASE_URL = SONIOX_API_BASE_URL;
 exports.SONIOX_API_WEBHOOK_HEADER_ENV = SONIOX_API_WEBHOOK_HEADER_ENV;
@@ -3608,6 +4432,8 @@ exports.SONIOX_API_WS_URL = SONIOX_API_WS_URL;
 exports.SONIOX_TMP_API_KEY_DURATION_MAX = SONIOX_TMP_API_KEY_DURATION_MAX;
 exports.SONIOX_TMP_API_KEY_DURATION_MIN = SONIOX_TMP_API_KEY_DURATION_MIN;
 exports.SONIOX_TMP_API_KEY_USAGE_TYPE = SONIOX_TMP_API_KEY_USAGE_TYPE;
+exports.SONIOX_TTS_API_BASE_URL = SONIOX_TTS_API_BASE_URL;
+exports.SONIOX_TTS_WS_URL = SONIOX_TTS_WS_URL;
 exports.SonioxError = SonioxError;
 exports.SonioxFile = SonioxFile;
 exports.SonioxHttpError = SonioxHttpError;
@@ -3615,6 +4441,7 @@ exports.SonioxNodeClient = SonioxNodeClient;
 exports.SonioxRealtimeApi = SonioxRealtimeApi;
 exports.SonioxTranscript = SonioxTranscript;
 exports.SonioxTranscription = SonioxTranscription;
+exports.SonioxTtsApi = SonioxTtsApi;
 exports.StateError = StateError;
 exports.TranscriptionListResult = TranscriptionListResult;
 exports.buildUrl = buildUrl;
@@ -3628,6 +4455,7 @@ exports.isSonioxError = isSonioxError;
 exports.isSonioxHttpError = isSonioxHttpError;
 exports.mergeHeaders = mergeHeaders;
 exports.normalizeHeaders = normalizeHeaders;
+exports.resolveConnectionConfig = resolveConnectionConfig;
 exports.segmentRealtimeTokens = segmentRealtimeTokens;
 exports.segmentTranscript = segmentTranscript;
 //# sourceMappingURL=index.cjs.map