@soniox/node 1.0.0

package/dist/index.mjs

@@ -0,0 +1,3597 @@
+//#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_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 (request.expires_in_seconds < 1 || request.expires_in_seconds > 3600) throw new Error("expires_in_seconds must be 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/http/errors.ts
+/** Maximum body text length to include in error details (4KB) */
+const MAX_BODY_TEXT_LENGTH = 4096;
+/**
+* Base error class for all Soniox SDK errors.
+*
+* All SDK errors extend this class for error handling across both REST (HTTP) and WebSocket (Real-time) APIs.
+*
+* @example
+* ```typescript
+* try {
+*   await client.transcribe(file);
+*   await session.connect();
+* } catch (error) {
+*   if (error instanceof SonioxError) {
+*     console.log(error.code);       // 'auth_error', 'network_error', etc.
+*     console.log(error.statusCode); // 401, 500, etc. (when applicable)
+*     console.log(error.toJSON());   // Consistent serialization
+*   }
+* }
+* ```
+*/
+var SonioxError = class extends Error {
+	/**
+	* Error code describing the type of error
+	*/
+	code;
+	/**
+	* HTTP status code when applicable (e.g., 401 for auth errors, 500 for server errors).
+	*/
+	statusCode;
+	/**
+	* The underlying error that caused this error, if any.
+	*/
+	cause;
+	constructor(message, code = "soniox_error", statusCode, cause) {
+		super(message);
+		this.name = "SonioxError";
+		this.code = code;
+		this.statusCode = statusCode;
+		this.cause = cause;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
+	* Creates a human-readable string representation
+	*/
+	toString() {
+		const parts = [`${this.name} [${this.code}]: ${this.message}`];
+		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,
+			...this.statusCode !== void 0 && { statusCode: this.statusCode }
+		};
+	}
+};
+/**
+* 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 src/async/files.ts
+/**
+* Uploaded file
+*/
+var SonioxFile = class {
+	id;
+	filename;
+	size;
+	created_at;
+	client_reference_id;
+	constructor(data, _http) {
+		this._http = _http;
+		this.id = data.id;
+		this.filename = data.filename;
+		this.size = data.size;
+		this.created_at = data.created_at;
+		if (data.client_reference_id) {
+			if (data.client_reference_id.length > 256) throw new Error("client_reference_id exceeds maximum length of 256 characters");
+			this.client_reference_id = data.client_reference_id;
+		}
+	}
+	/**
+	* Returns the raw data for this file.
+	*/
+	toJSON() {
+		return {
+			id: this.id,
+			filename: this.filename,
+			size: this.size,
+			created_at: this.created_at,
+			client_reference_id: this.client_reference_id
+		};
+	}
+	/**
+	* Permanently deletes this file.
+	* This operation is idempotent - succeeds even if the file doesn't exist.
+	*
+	* @param signal - Optional AbortSignal for cancellation
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (file) {
+	*     await file.delete();
+	* }
+	* ```
+	*/
+	async delete(signal) {
+		try {
+			await this._http.request({
+				method: "DELETE",
+				path: `/v1/files/${this.id}`,
+				...signal && { signal }
+			});
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+};
+/**
+* Result set for file listing
+*/
+var FileListResult = class {
+	/**
+	* Files from the first page of results
+	*/
+	files;
+	/**
+	* Pagination cursor for the next page. Null if no more pages
+	*/
+	next_page_cursor;
+	constructor(initialResponse, _http, _limit, _signal = void 0) {
+		this._http = _http;
+		this._limit = _limit;
+		this._signal = _signal;
+		this.files = initialResponse.files.map((data) => new SonioxFile(data, _http));
+		this.next_page_cursor = initialResponse.next_page_cursor;
+	}
+	/**
+	* Returns the raw data for this list result.
+	* Also used by JSON.stringify() to prevent serialization of internal HTTP client.
+	*/
+	toJSON() {
+		return {
+			files: this.files.map((f) => f.toJSON()),
+			next_page_cursor: this.next_page_cursor
+		};
+	}
+	/**
+	* Returns true if there are more pages of results beyond the first page
+	*/
+	isPaged() {
+		return this.next_page_cursor !== null;
+	}
+	/**
+	* Async iterator that automatically fetches all pages
+	* Use with `for await...of` to iterate through all files
+	*/
+	async *[Symbol.asyncIterator]() {
+		for (const file of this.files) yield file;
+		let cursor = this.next_page_cursor;
+		while (cursor !== null) {
+			const response = await this._http.request({
+				method: "GET",
+				path: "/v1/files",
+				query: {
+					limit: this._limit,
+					cursor
+				},
+				...this._signal && { signal: this._signal }
+			});
+			for (const data of response.data.files) yield new SonioxFile(data, this._http);
+			cursor = response.data.next_page_cursor;
+		}
+	}
+};
+/**
+* Helper to extract file ID from a FileIdentifier
+*/
+function getFileId(file) {
+	return typeof file === "string" ? file : file.id;
+}
+/**
+* Maximum file size allowed by the API (1 GB)
+*/
+const MAX_FILE_SIZE = 1073741824;
+/**
+* Default filename when none can be inferred
+*/
+const DEFAULT_FILENAME = "file";
+/**
+* Checks if the input is an async-iterable Node.js readable stream
+*/
+function isNodeReadableStream(input) {
+	return typeof input === "object" && input !== null && "pipe" in input && typeof input.pipe === "function" && Symbol.asyncIterator in input;
+}
+/**
+* Checks if the input is a Web ReadableStream
+*/
+function isWebReadableStream(input) {
+	return typeof input === "object" && input !== null && "getReader" in input && typeof input.getReader === "function";
+}
+/**
+* Collects chunks from a Node.js readable stream into a Buffer
+* Aborts early if size exceeds MAX_FILE_SIZE to prevent OOM
+*/
+async function collectNodeStream(stream) {
+	const chunks = [];
+	let totalLength = 0;
+	for await (const chunk of stream) {
+		if (typeof chunk === "string") throw new Error("Stream returned string chunks. Use a binary stream (e.g., fs.createReadStream without encoding option).");
+		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		totalLength += buf.length;
+		if (totalLength > MAX_FILE_SIZE) throw new Error(`File size exceeds maximum allowed size (${MAX_FILE_SIZE} bytes)`);
+		chunks.push(buf);
+	}
+	return Buffer.concat(chunks);
+}
+/**
+* Collects chunks from a Web ReadableStream into a Uint8Array
+* Aborts early if size exceeds MAX_FILE_SIZE to prevent OOM
+*/
+async function collectWebStream(stream) {
+	const reader = stream.getReader();
+	const chunks = [];
+	let totalLength = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			totalLength += value.length;
+			if (totalLength > MAX_FILE_SIZE) throw new Error(`File size exceeds maximum allowed size (${MAX_FILE_SIZE} bytes)`);
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const result = new Uint8Array(totalLength);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return result;
+}
+/**
+* Resolves the file input to a Blob and filename
+*/
+async function resolveFileInput(input, filenameOverride) {
+	if (input instanceof Blob) {
+		if (input.size > MAX_FILE_SIZE) throw new Error(`File size (${input.size} bytes) exceeds maximum allowed size (${MAX_FILE_SIZE} bytes)`);
+		return {
+			blob: input,
+			filename: filenameOverride ?? ("name" in input && typeof input.name === "string" ? input.name : DEFAULT_FILENAME)
+		};
+	}
+	if (Buffer.isBuffer(input)) {
+		if (input.length > MAX_FILE_SIZE) throw new Error(`File size (${input.length} bytes) exceeds maximum allowed size (${MAX_FILE_SIZE} bytes)`);
+		return {
+			blob: new Blob([new Uint8Array(input)]),
+			filename: filenameOverride ?? DEFAULT_FILENAME
+		};
+	}
+	if (input instanceof Uint8Array) {
+		if (input.length > MAX_FILE_SIZE) throw new Error(`File size (${input.length} bytes) exceeds maximum allowed size (${MAX_FILE_SIZE} bytes)`);
+		return {
+			blob: new Blob([new Uint8Array(input)]),
+			filename: filenameOverride ?? DEFAULT_FILENAME
+		};
+	}
+	if (isWebReadableStream(input)) {
+		const data = await collectWebStream(input);
+		return {
+			blob: new Blob([new Uint8Array(data)]),
+			filename: filenameOverride ?? DEFAULT_FILENAME
+		};
+	}
+	if (isNodeReadableStream(input)) {
+		const buffer = await collectNodeStream(input);
+		return {
+			blob: new Blob([new Uint8Array(buffer)]),
+			filename: filenameOverride ?? DEFAULT_FILENAME
+		};
+	}
+	throw new Error("Invalid file input. Expected Buffer, Uint8Array, Blob, or ReadableStream.");
+}
+var SonioxFilesAPI = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Uploads a file to Soniox for transcription
+	*
+	* @param file - Buffer, Uint8Array, Blob, or ReadableStream
+	* @param options - Upload options
+	* @returns The uploaded file metadata
+	* @throws {SonioxHttpError} On API errors
+	* @throws {Error} On validation errors (file too large, invalid input)
+	*
+	* @example Upload from file path (Node.js)
+	* ```typescript
+	* import * as fs from 'node:fs';
+	*
+	* const buffer = await fs.promises.readFile('/path/to/audio.mp3');
+	* const file = await client.files.upload(buffer, { filename: 'audio.mp3' });
+	* ```
+	*
+	* @example Upload from file path (Bun)
+	* ```typescript
+	* const file = await client.files.upload(Bun.file('/path/to/audio.mp3'));
+	* ```
+	*
+	* @example Upload with tracking ID
+	* ```typescript
+	* const file = await client.files.upload(buffer, {
+	*     filename: 'audio.mp3',
+	*     client_reference_id: 'order-12345',
+	* });
+	* ```
+	*
+	* @example Upload with cancellation
+	* ```typescript
+	* const controller = new AbortController();
+	* setTimeout(() => controller.abort(), 30000);
+	*
+	* const file = await client.files.upload(buffer, {
+	*     filename: 'audio.mp3',
+	*     signal: controller.signal,
+	* });
+	* ```
+	*/
+	async upload(file, options = {}) {
+		const { filename, client_reference_id, signal, timeout_ms } = options;
+		if (client_reference_id !== void 0 && client_reference_id.length > 256) throw new Error(`client_reference_id exceeds maximum length of 256 characters (got ${client_reference_id.length})`);
+		const { blob, filename: resolvedFilename } = await resolveFileInput(file, filename);
+		const formData = new FormData();
+		formData.append("file", blob, resolvedFilename);
+		if (client_reference_id !== void 0) formData.append("client_reference_id", client_reference_id);
+		const requestOptions = {
+			method: "POST",
+			path: "/v1/files",
+			body: formData
+		};
+		if (signal !== void 0) requestOptions.signal = signal;
+		if (timeout_ms !== void 0) requestOptions.timeoutMs = timeout_ms;
+		return new SonioxFile((await this.http.request(requestOptions)).data, this.http);
+	}
+	/**
+	* Retrieves list of uploaded files
+	*
+	* The returned result is async iterable - use `for await...of`
+	*
+	* @param options - Optional pagination and cancellation parameters
+	* @returns FileListResult
+	* @throws {SonioxHttpError}
+	*
+	* @example
+	* ```typescript
+	* const result = await client.files.list();
+	*
+	* // Automatic paging - iterates through ALL files across all pages
+	* for await (const file of result) {
+	*     console.log(file.filename, file.size);
+	* }
+	*
+	* // Or access just the first page
+	* for (const file of result.files) {
+	*     console.log(file.filename);
+	* }
+	*
+	* // Check if there are more pages
+	* if (result.isPaged()) {
+	*     console.log('More pages available');
+	* }
+	*
+	* // Manual paging using cursor
+	* const page1 = await client.files.list({ limit: 10 });
+	* if (page1.next_page_cursor) {
+	*     const page2 = await client.files.list({ cursor: page1.next_page_cursor });
+	* }
+	*
+	* // With cancellation
+	* const controller = new AbortController();
+	* const result = await client.files.list({ signal: controller.signal });
+	* ```
+	*/
+	async list(options = {}) {
+		const { limit, cursor, signal } = options;
+		return new FileListResult((await this.http.request({
+			method: "GET",
+			path: "/v1/files",
+			query: {
+				limit,
+				cursor
+			},
+			...signal && { signal }
+		})).data, this.http, limit, signal);
+	}
+	/**
+	* Retrieve metadata for an uploaded file.
+	*
+	* @param file - The UUID of the file or a SonioxFile instance
+	* @param signal - Optional AbortSignal for cancellation
+	* @returns The file instance, or null if not found
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (file) {
+	*     console.log(file.filename, file.size);
+	* }
+	* ```
+	*/
+	async get(file, signal) {
+		const file_id = getFileId(file);
+		try {
+			return new SonioxFile((await this.http.request({
+				method: "GET",
+				path: `/v1/files/${file_id}`,
+				...signal && { signal }
+			})).data, this.http);
+		} catch (error) {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Permanently deletes a file.
+	* This operation is idempotent - succeeds even if the file doesn't exist.
+	*
+	* @param file - The UUID of the file or a SonioxFile instance
+	* @param signal - Optional AbortSignal for cancellation
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* // Delete by ID
+	* await client.files.delete('550e8400-e29b-41d4-a716-446655440000');
+	*
+	* // Or delete a file instance
+	* const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (file) {
+	*     await client.files.delete(file);
+	* }
+	*
+	* // Or just use the instance method
+	* await file.delete();
+	* ```
+	*/
+	async delete(file, signal) {
+		const file_id = getFileId(file);
+		try {
+			await this.http.request({
+				method: "DELETE",
+				path: `/v1/files/${file_id}`,
+				...signal && { signal }
+			});
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+	/**
+	* Permanently deletes all uploaded files.
+	* Iterates through all pages of files and deletes each one.
+	*
+	* @param options - Optional signal and progress callback.
+	* @returns The number of files deleted.
+	* @throws {SonioxHttpError} On API errors.
+	* @throws {Error} If the operation is aborted via signal.
+	*
+	* @example
+	* ```typescript
+	* // Delete all files
+	* const { deleted } = await client.files.purge();
+	* console.log(`Deleted ${deleted} files.`);
+	*
+	* // With progress logging
+	* const { deleted } = await client.files.purge({
+	*     on_progress: (file, index) => {
+	*         console.log(`Deleting file: ${file.id} (${index + 1})`);
+	*     },
+	* });
+	*
+	* // With cancellation
+	* const controller = new AbortController();
+	* const { deleted } = await client.files.purge({ signal: controller.signal });
+	* ```
+	*/
+	async purge(options = {}) {
+		const { signal, on_progress } = options;
+		const result = await this.list({ signal });
+		let deleted = 0;
+		for await (const file of result) {
+			signal?.throwIfAborted();
+			on_progress?.(file.toJSON(), deleted);
+			await this.delete(file, signal);
+			deleted++;
+		}
+		return { deleted };
+	}
+};
+
+//#endregion
+//#region src/async/models.ts
+var SonioxModelsAPI = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* List of available models and their attributes.
+	* @see https://soniox.com/docs/stt/api-reference/models/get_models
+	* @param signal - Optional AbortSignal for cancellation
+	* @returns List of available models and their attributes.
+	*/
+	async list(signal) {
+		return (await this.http.request({
+			method: "GET",
+			path: "/v1/models",
+			...signal && { signal }
+		})).data.models;
+	}
+};
+
+//#endregion
+//#region src/async/segments.ts
+const DEFAULT_GROUP_BY = ["speaker", "language"];
+function segmentTokens(tokens, options, buildSegment$2) {
+	if (tokens.length === 0) return [];
+	const groupBy = options?.group_by ?? DEFAULT_GROUP_BY;
+	const groupBySpeaker = groupBy.includes("speaker");
+	const groupByLanguage = groupBy.includes("language");
+	const segments = [];
+	let currentTokens = [];
+	let currentSpeaker;
+	let currentLanguage;
+	for (const token of tokens) {
+		const speakerChanged = groupBySpeaker && token.speaker !== currentSpeaker;
+		const languageChanged = groupByLanguage && token.language !== currentLanguage;
+		if (currentTokens.length > 0 && (speakerChanged || languageChanged)) {
+			segments.push(buildSegment$2(currentTokens, currentSpeaker, currentLanguage));
+			currentTokens = [];
+		}
+		currentTokens.push(token);
+		currentSpeaker = token.speaker;
+		currentLanguage = token.language;
+	}
+	if (currentTokens.length > 0) segments.push(buildSegment$2(currentTokens, currentSpeaker, currentLanguage));
+	return segments;
+}
+
+//#endregion
+//#region src/async/stt.ts
+/**
+* Minimum polling interval in ms
+*/
+const MIN_POLL_INTERVAL_MS = 1e3;
+/**
+* Default polling interval in ms
+*/
+const DEFAULT_POLL_INTERVAL_MS = 1e3;
+/**
+* Default timeout for waiting in ms (5 minutes)
+*/
+const DEFAULT_TIMEOUT_MS$1 = 3e5;
+/**
+* Helper to sleep for a given number of ms, interruptible by abort signal
+*/
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(/* @__PURE__ */ new Error("Transcription wait aborted"));
+			return;
+		}
+		const timeoutId = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timeoutId);
+			reject(/* @__PURE__ */ new Error("Transcription wait aborted"));
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Helper to extract transcription ID from a TranscriptionIdentifier
+*/
+function getTranscriptionId(transcription) {
+	return typeof transcription === "string" ? transcription : transcription.id;
+}
+/**
+* Creates an AbortSignal that fires when either the timeout expires or the provided signal aborts
+* Returns the signal and a cleanup function to clear the timeout
+*/
+function createTimeoutSignal(timeout_ms, signal) {
+	if (timeout_ms === void 0 && signal === void 0) return {
+		signal: void 0,
+		cleanup: () => {}
+	};
+	if (timeout_ms === void 0) return {
+		signal,
+		cleanup: () => {}
+	};
+	if (!Number.isFinite(timeout_ms) || timeout_ms <= 0) throw new Error("timeout_ms must be a finite positive number");
+	const timeoutController = new AbortController();
+	const timeoutId = setTimeout(() => {
+		timeoutController.abort(/* @__PURE__ */ new Error(`Operation timed out after ${timeout_ms}ms`));
+	}, timeout_ms);
+	const cleanup = () => clearTimeout(timeoutId);
+	if (signal === void 0) return {
+		signal: timeoutController.signal,
+		cleanup
+	};
+	const combinedController = new AbortController();
+	const onAbort = () => {
+		cleanup();
+		timeoutController.signal.removeEventListener("abort", onTimeout);
+		combinedController.abort(signal.reason ?? /* @__PURE__ */ new Error("Operation aborted"));
+	};
+	const onTimeout = () => {
+		signal.removeEventListener("abort", onAbort);
+		combinedController.abort(timeoutController.signal.reason);
+	};
+	if (signal.aborted) {
+		cleanup();
+		combinedController.abort(signal.reason ?? /* @__PURE__ */ new Error("Operation aborted"));
+	} else {
+		signal.addEventListener("abort", onAbort, { once: true });
+		timeoutController.signal.addEventListener("abort", onTimeout, { once: true });
+	}
+	return {
+		signal: combinedController.signal,
+		cleanup: () => {
+			cleanup();
+			signal.removeEventListener("abort", onAbort);
+			timeoutController.signal.removeEventListener("abort", onTimeout);
+		}
+	};
+}
+/**
+* Groups contiguous tokens into segments based on specified grouping keys.
+* A new segment starts when any of the `group_by` fields changes
+*
+* @param tokens - Array of transcript tokens to segment
+* @param options - Segmentation options
+* @param options.group_by - Fields to group by (default: ['speaker', 'language'])
+* @returns Array of segments with combined text and timing
+*
+* @example
+* ```typescript
+* const transcript = await transcription.getTranscript();
+*
+* // Group by both speaker and language (default)
+* const segments = segmentTranscript(transcript.tokens);
+*
+* // Group by speaker only
+* const bySpeaker = segmentTranscript(transcript.tokens, { group_by: ['speaker'] });
+*
+* // Group by language only
+* const byLanguage = segmentTranscript(transcript.tokens, { group_by: ['language'] });
+*
+* for (const seg of segments) {
+*     console.log(`[Speaker ${seg.speaker}] ${seg.text}`);
+* }
+* ```
+*/
+function segmentTranscript(tokens, options = {}) {
+	return segmentTokens(tokens, options, buildSegment$1);
+}
+/**
+* Helper to build a segment from a list of tokens
+*/
+function buildSegment$1(tokens, speaker, language) {
+	const firstToken = tokens[0];
+	const lastToken = tokens[tokens.length - 1];
+	if (!firstToken || !lastToken) throw new Error("Cannot build segment from an empty token array");
+	return {
+		text: tokens.map((t) => t.text).join(""),
+		start_ms: firstToken.start_ms,
+		end_ms: lastToken.end_ms,
+		...speaker != null && { speaker },
+		...language != null && { language },
+		tokens
+	};
+}
+/**
+* A Transcript result containing the transcribed text and tokens.
+*/
+var SonioxTranscript = class {
+	/**
+	* Unique identifier of the transcription this transcript belongs to.
+	*/
+	id;
+	/**
+	* Complete transcribed text content.
+	*/
+	text;
+	/**
+	* List of detailed token information with timestamps and metadata.
+	*/
+	tokens;
+	constructor(data) {
+		this.id = data.id;
+		this.text = data.text;
+		this.tokens = data.tokens;
+	}
+	/**
+	* Groups tokens into segments based on specified grouping keys.
+	*
+	* A new segment starts when any of the `group_by` fields changes.
+	*
+	* @param options - Segmentation options
+	* @param options.group_by - Fields to group by (default: ['speaker', 'language'])
+	* @returns Array of segments with combined text and timing
+	*
+	* @example
+	* ```typescript
+	* const transcript = await transcription.getTranscript();
+	*
+	* // Group by both speaker and language (default)
+	* const segments = transcript.segments();
+	*
+	* // Group by speaker only
+	* const bySpeaker = transcript.segments({ group_by: ['speaker'] });
+	*
+	* for (const s of segments) {
+	*     console.log(`[Speaker ${s.speaker}] ${s.text}`);
+	* }
+	* ```
+	*/
+	segments(options) {
+		return segmentTranscript(this.tokens, options);
+	}
+};
+/**
+* A Transcription instance
+*/
+var SonioxTranscription = class SonioxTranscription {
+	/**
+	* Unique identifier of the transcription.
+	*/
+	id;
+	/**
+	* Current status of the transcription.
+	*/
+	status;
+	/**
+	* UTC timestamp when the transcription was created.
+	*/
+	created_at;
+	/**
+	* Speech-to-text model used.
+	*/
+	model;
+	/**
+	* URL of the audio file being transcribed.
+	*/
+	audio_url;
+	/**
+	* ID of the uploaded file being transcribed.
+	*/
+	file_id;
+	/**
+	* Name of the file being transcribed.
+	*/
+	filename;
+	/**
+	* Expected languages in the audio.
+	*/
+	language_hints;
+	/**
+	* When true, speakers are identified and separated in the transcription output.
+	*/
+	enable_speaker_diarization;
+	/**
+	* When true, language is detected for each part of the transcription.
+	*/
+	enable_language_identification;
+	/**
+	* Duration of the audio in milliseconds. Only available after processing begins.
+	*/
+	audio_duration_ms;
+	/**
+	* Error type if transcription failed.
+	*/
+	error_type;
+	/**
+	* Error message if transcription failed.
+	*/
+	error_message;
+	/**
+	* URL to receive webhook notifications.
+	*/
+	webhook_url;
+	/**
+	* Name of the authentication header sent with webhook notifications.
+	*/
+	webhook_auth_header_name;
+	/**
+	* Authentication header value (masked).
+	*/
+	webhook_auth_header_value;
+	/**
+	* HTTP status code received when webhook was delivered.
+	*/
+	webhook_status_code;
+	/**
+	* Optional tracking identifier.
+	*/
+	client_reference_id;
+	/**
+	* Additional context provided for the transcription.
+	*/
+	context;
+	/**
+	* Pre-fetched transcript. Only available when using `transcribe()` with `wait: true`,
+	* `fetch_transcript !== false`, and the transcription completed successfully
+	*/
+	transcript;
+	constructor(data, _http, transcript) {
+		this._http = _http;
+		this.id = data.id;
+		this.status = data.status;
+		this.created_at = data.created_at;
+		this.model = data.model;
+		this.audio_url = data.audio_url;
+		this.file_id = data.file_id;
+		this.filename = data.filename;
+		this.language_hints = data.language_hints ?? void 0;
+		this.enable_speaker_diarization = data.enable_speaker_diarization;
+		this.enable_language_identification = data.enable_language_identification;
+		this.audio_duration_ms = data.audio_duration_ms;
+		this.error_type = data.error_type;
+		this.error_message = data.error_message;
+		this.webhook_url = data.webhook_url;
+		this.webhook_auth_header_name = data.webhook_auth_header_name;
+		this.webhook_auth_header_value = data.webhook_auth_header_value;
+		this.webhook_status_code = data.webhook_status_code;
+		this.client_reference_id = data.client_reference_id;
+		this.context = data.context;
+		this.transcript = transcript;
+	}
+	/**
+	* Returns the raw data for this transcription.
+	*/
+	toJSON() {
+		return {
+			id: this.id,
+			status: this.status,
+			created_at: this.created_at,
+			model: this.model,
+			audio_url: this.audio_url,
+			file_id: this.file_id,
+			filename: this.filename,
+			language_hints: this.language_hints,
+			enable_speaker_diarization: this.enable_speaker_diarization,
+			enable_language_identification: this.enable_language_identification,
+			audio_duration_ms: this.audio_duration_ms,
+			error_type: this.error_type,
+			error_message: this.error_message,
+			webhook_url: this.webhook_url,
+			webhook_auth_header_name: this.webhook_auth_header_name,
+			webhook_auth_header_value: this.webhook_auth_header_value,
+			webhook_status_code: this.webhook_status_code,
+			client_reference_id: this.client_reference_id,
+			context: this.context
+		};
+	}
+	/**
+	* Permanently deletes this transcription.
+	* This operation is idempotent - succeeds even if the transcription doesn't exist.
+	*
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
+	* await transcription.delete();
+	* ```
+	*/
+	async delete() {
+		try {
+			await this._http.request({
+				method: "DELETE",
+				path: `/v1/transcriptions/${this.id}`
+			});
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+	/**
+	* Permanently deletes this transcription and its associated file (if any).
+	* This operation is idempotent - succeeds even if resources don't exist.
+	*
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* // Clean up both transcription and uploaded file
+	* const transcription = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,
+	*     wait: true,
+	* });
+	* // ... use transcription ...
+	* await transcription.destroy(); // Deletes both transcription and file
+	* ```
+	*/
+	async destroy() {
+		await this.delete();
+		if (this.file_id) try {
+			await this._http.request({
+				method: "DELETE",
+				path: `/v1/files/${this.file_id}`
+			});
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+	/**
+	* Retrieves the full transcript text and tokens for this transcription.
+	* Only available for successfully completed transcriptions.
+	*
+	* Returns cached transcript if available (when using `transcribe()` with `wait: true`).
+	* Use `force: true` to bypass the cache and fetch fresh data from the API.
+	*
+	* @param options - Optional settings
+	* @param options.force - If true, bypasses cached transcript and fetches from API
+	* @param options.signal - Optional AbortSignal for request cancellation
+	* @returns The transcript with text and detailed tokens, or null if not found.
+	* @throws {SonioxHttpError} On API errors (except 404).
+	*
+	* @example
+	* ```typescript
+	* const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (transcription) {
+	*     const transcript = await transcription.getTranscript();
+	*     if (transcript) {
+	*         console.log(transcript.text);
+	*     }
+	* }
+	*
+	* // Force re-fetch from API
+	* const freshTranscript = await transcription.getTranscript({ force: true });
+	* ```
+	*/
+	async getTranscript(options) {
+		const { force, signal } = options ?? {};
+		if (!force && this.transcript !== void 0) return this.transcript;
+		try {
+			return new SonioxTranscript((await this._http.request({
+				method: "GET",
+				path: `/v1/transcriptions/${this.id}/transcript`,
+				...signal && { signal }
+			})).data);
+		} catch (error) {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Re-fetches this transcription to get the latest status.
+	* @param signal - Optional AbortSignal for request cancellation.
+	* @returns A new SonioxTranscription instance with updated data.
+	* @throws {SonioxHttpError}
+	*
+	* @example
+	* ```typescript
+	* let transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
+	* transcription = await transcription.refresh();
+	* console.log(transcription.status);
+	* ```
+	*/
+	async refresh(signal) {
+		return new SonioxTranscription((await this._http.request({
+			method: "GET",
+			path: `/v1/transcriptions/${this.id}`,
+			...signal && { signal }
+		})).data, this._http);
+	}
+	/**
+	* Waits for the transcription to complete or fail.
+	* Polls the API at the specified interval until the status is 'completed' or 'error'.
+	*
+	* @param options - Wait options including polling interval, timeout, and callbacks.
+	* @returns The completed or errored transcription.
+	* @throws {Error} If the wait times out or is aborted.
+	* @throws {SonioxHttpError} On API errors.
+	*
+	* @example
+	* ```typescript
+	* const transcription = await client.stt.create({
+	*     model: 'stt-async-v4',
+	*     audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
+	* });
+	*
+	* // Simple wait
+	* const completed = await transcription.wait();
+	*
+	* // Wait with progress callback
+	* const completed = await transcription.wait({
+	*     interval_ms: 2000,
+	*     on_status_change: (status) => console.log(`Status: ${status}`),
+	* });
+	* ```
+	*/
+	async wait(options = {}) {
+		const { interval_ms: requestedInterval = DEFAULT_POLL_INTERVAL_MS, timeout_ms = DEFAULT_TIMEOUT_MS$1, on_status_change, signal } = options;
+		const interval_ms = Math.max(requestedInterval, MIN_POLL_INTERVAL_MS);
+		if (this.status !== "queued" && this.status !== "processing") return this;
+		if (signal?.aborted) throw new Error("Transcription wait aborted");
+		const startTime = Date.now();
+		const checkTimeout = () => {
+			if (Date.now() - startTime > timeout_ms) throw new Error(`Transcription wait timed out after ${timeout_ms}ms`);
+		};
+		checkTimeout();
+		let lastStatus = this.status;
+		let current = await this.refresh(signal);
+		while (current.status === "queued" || current.status === "processing") {
+			if (current.status !== lastStatus) {
+				on_status_change?.(current.status, current.toJSON());
+				lastStatus = current.status;
+			}
+			checkTimeout();
+			await sleep(interval_ms, signal);
+			checkTimeout();
+			current = await current.refresh(signal);
+		}
+		if (current.status !== lastStatus) on_status_change?.(current.status, current.toJSON());
+		return current;
+	}
+};
+/**
+* Result set for transcription listing.
+*/
+var TranscriptionListResult = class {
+	/**
+	* Transcriptions from the first page of results.
+	*/
+	transcriptions;
+	/**
+	* Pagination cursor for the next page. Null if no more pages.
+	*/
+	next_page_cursor;
+	constructor(initialResponse, _http, _options) {
+		this._http = _http;
+		this._options = _options;
+		this.transcriptions = initialResponse.transcriptions.map((data) => new SonioxTranscription(data, _http));
+		this.next_page_cursor = initialResponse.next_page_cursor;
+	}
+	/**
+	* Returns the raw data for this list result
+	*/
+	toJSON() {
+		return {
+			transcriptions: this.transcriptions.map((t) => t.toJSON()),
+			next_page_cursor: this.next_page_cursor
+		};
+	}
+	/**
+	* Returns true if there are more pages of results beyond the first page.
+	*/
+	isPaged() {
+		return this.next_page_cursor !== null;
+	}
+	/**
+	* Async iterator that automatically fetches all pages.
+	* Use with `for await...of` to iterate through all transcriptions.
+	*/
+	async *[Symbol.asyncIterator]() {
+		for (const transcription of this.transcriptions) yield transcription;
+		let cursor = this.next_page_cursor;
+		while (cursor !== null) {
+			const response = await this._http.request({
+				method: "GET",
+				path: "/v1/transcriptions",
+				query: {
+					limit: this._options.limit,
+					cursor
+				}
+			});
+			for (const data of response.data.transcriptions) yield new SonioxTranscription(data, this._http);
+			cursor = response.data.next_page_cursor;
+		}
+	}
+};
+var SonioxSttApi = class {
+	constructor(http, filesApi) {
+		this.http = http;
+		this.filesApi = filesApi;
+	}
+	/**
+	* Creates a new transcription from audio_url or file_id
+	*
+	* @param options - Transcription options including model and audio source.
+	* @returns The created transcription.
+	* @throws {SonioxHttpError} On API errors.
+	*
+	* @example
+	* ```typescript
+	* // Transcribe from URL
+	* const transcription = await client.stt.create({
+	*     model: 'stt-async-v4',
+	*     audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
+	* });
+	*
+	* // Transcribe from uploaded file
+	* const file = await client.files.upload(buffer);
+	* const transcription = await client.stt.create({
+	*     model: 'stt-async-v4',
+	*     file_id: file.id,
+	* });
+	*
+	* // With speaker diarization
+	* const transcription = await client.stt.create({
+	*     model: 'stt-async-v4',
+	*     audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
+	*     enable_speaker_diarization: true,
+	* });
+	* ```
+	*/
+	async create(options, signal) {
+		if (options.client_reference_id !== void 0 && options.client_reference_id.length > 256) throw new Error(`client_reference_id exceeds maximum length of 256 characters (got ${options.client_reference_id.length})`);
+		return new SonioxTranscription((await this.http.request({
+			method: "POST",
+			path: "/v1/transcriptions",
+			body: options,
+			...signal && { signal }
+		})).data, this.http);
+	}
+	/**
+	* Retrieves list of transcriptions
+	*
+	* The returned result is async iterable - use `for await...of` to iterate through all pages
+	*
+	* @param options - Optional pagination and filter parameters.
+	* @returns TranscriptionListResult with async iteration support.
+	* @throws {SonioxHttpError} On API errors.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.stt.list();
+	*
+	* // Automatic paging - iterates through ALL transcriptions across all pages
+	* for await (const transcription of result) {
+	*     console.log(transcription.id, transcription.status);
+	* }
+	*
+	* // Or access just the first page
+	* for (const transcription of result.transcriptions) {
+	*     console.log(transcription.id);
+	* }
+	*
+	* // Check if there are more pages
+	* if (result.isPaged()) {
+	*     console.log('More pages available');
+	* }
+	* ```
+	*/
+	async list(options = {}) {
+		return new TranscriptionListResult((await this.http.request({
+			method: "GET",
+			path: "/v1/transcriptions",
+			query: {
+				limit: options.limit,
+				cursor: options.cursor
+			}
+		})).data, this.http, options);
+	}
+	/**
+	* Retrieves a transcription by ID
+	*
+	* @param id - The UUID of the transcription or a SonioxTranscription instance.
+	* @returns The transcription, or null if not found.
+	* @throws {SonioxHttpError} On API errors (except 404).
+	*
+	* @example
+	* ```typescript
+	* const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (transcription) {
+	*     console.log(transcription.status, transcription.model);
+	* }
+	* ```
+	*/
+	async get(id) {
+		const transcription_id = getTranscriptionId(id);
+		try {
+			return new SonioxTranscription((await this.http.request({
+				method: "GET",
+				path: `/v1/transcriptions/${transcription_id}`
+			})).data, this.http);
+		} catch (error) {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Permanently deletes a transcription.
+	* This operation is idempotent - succeeds even if the transcription doesn't exist.
+	*
+	* @param id - The UUID of the transcription or a SonioxTranscription instance
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* // Delete by ID
+	* await client.stt.delete('550e8400-e29b-41d4-a716-446655440000');
+	*
+	* // Or delete a transcription instance
+	* const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
+	* if (transcription) {
+	*     await client.stt.delete(transcription);
+	* }
+	* ```
+	*/
+	async delete(id) {
+		const transcription_id = getTranscriptionId(id);
+		try {
+			await this.http.request({
+				method: "DELETE",
+				path: `/v1/transcriptions/${transcription_id}`
+			});
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+	/**
+	* Permanently deletes a transcription and its associated file (if any).
+	* This operation is idempotent - succeeds even if resources don't exist.
+	*
+	* @param id - The UUID of the transcription or a SonioxTranscription instance
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* // Clean up both transcription and uploaded file
+	* const transcription = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,
+	*     wait: true,
+	* });
+	* // ... use transcription ...
+	* await client.stt.destroy(transcription); // Deletes both
+	*
+	* // Or by ID
+	* await client.stt.destroy('550e8400-e29b-41d4-a716-446655440000');
+	* ```
+	*/
+	async destroy(id) {
+		const transcription = await this.get(id);
+		if (!transcription) return;
+		await this.delete(transcription);
+		if (transcription.file_id) try {
+			await this.filesApi.delete(transcription.file_id);
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+	}
+	/**
+	* Retrieves the full transcript text and tokens for a completed transcription.
+	* Only available for successfully completed transcriptions.
+	*
+	* @param id - The UUID of the transcription or a SonioxTranscription instance
+	* @returns The transcript with text and detailed tokens, or null if not found
+	* @throws {SonioxHttpError} On API errors (except 404)
+	*
+	* @example
+	* ```typescript
+	* const transcript = await client.stt.getTranscript('550e8400-e29b-41d4-a716-446655440000');
+	* if (transcript) {
+	*     console.log(transcript.text);
+	*     for (const token of transcript.tokens) {
+	*         console.log(token.text, token.start_ms, token.end_ms, token.confidence);
+	*     }
+	* }
+	* ```
+	*/
+	async getTranscript(id, signal) {
+		const transcription_id = getTranscriptionId(id);
+		try {
+			return new SonioxTranscript((await this.http.request({
+				method: "GET",
+				path: `/v1/transcriptions/${transcription_id}/transcript`,
+				...signal && { signal }
+			})).data);
+		} catch (error) {
+			if (isNotFoundError(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Waits for a transcription to complete
+	*
+	* @param id - The UUID of the transcription or a SonioxTranscription instance.
+	* @param options - Wait options including polling interval, timeout, and callbacks.
+	* @returns The completed or errored transcription.
+	* @throws {Error} If the wait times out or is aborted.
+	* @throws {SonioxHttpError} On API errors.
+	*
+	* @example
+	* ```typescript
+	* const completed = await client.stt.wait('550e8400-e29b-41d4-a716-446655440000');
+	*
+	* // With progress callback
+	* const completed = await client.stt.wait('id', {
+	*     interval_ms: 2000,
+	*     on_status_change: (status) => console.log(`Status: ${status}`),
+	* });
+	* ```
+	*/
+	async wait(id, options) {
+		const transcription = await this.get(id);
+		if (!transcription) throw new Error(`Transcription not found: ${getTranscriptionId(id)}`);
+		return transcription.wait(options);
+	}
+	/**
+	* Wrapper to transcribe from a URL.
+	*
+	* @param audio_url - Publicly accessible audio URL
+	* @param options - Transcription options (excluding audio_url)
+	* @returns The transcription (completed if wait=true, otherwise in queued/processing state).
+	*/
+	async transcribeFromUrl(audio_url, options) {
+		return this.transcribe({
+			...options,
+			audio_url
+		});
+	}
+	/**
+	* Wrapper to transcribe from an uploaded file ID.
+	*
+	* @param file_id - ID of a previously uploaded file
+	* @param options - Transcription options (excluding file_id)
+	* @returns The transcription (completed if wait=true, otherwise in queued/processing state).
+	*/
+	async transcribeFromFileId(file_id, options) {
+		return this.transcribe({
+			...options,
+			file_id
+		});
+	}
+	/**
+	* Wrapper to transcribe from raw file data.
+	*
+	* @param file - Buffer, Uint8Array, Blob, or ReadableStream
+	* @param options - Transcription options (excluding file)
+	* @returns The transcription (completed if wait=true, otherwise in queued/processing state).
+	*/
+	async transcribeFromFile(file, options) {
+		return this.transcribe({
+			...options,
+			file
+		});
+	}
+	/**
+	* Unified transcribe method - supports direct file upload
+	*
+	* When `file` is provided, uploads it first then creates a transcription
+	* When `wait: true`, waits for completion before returning
+	* When `cleanup` is specified (requires `wait: true`), cleans up resources after completion or on error/timeout
+	*
+	* @param options - Transcribe options including model, audio source, and wait settings.
+	* @returns The transcription (completed if wait=true, otherwise in queued/processing state).
+	* @throws {SonioxHttpError} On API errors.
+	* @throws {Error} On validation errors or wait timeout.
+	*
+	* @example
+	* ```typescript
+	* // Transcribe from URL and wait for completion
+	* const result = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
+	*     wait: true,
+	* });
+	*
+	* // Upload file and transcribe in one call
+	* const result = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,  // or Blob, ReadableStream
+	*     filename: 'meeting.mp3',
+	*     enable_speaker_diarization: true,
+	*     wait: true,
+	* });
+	*
+	* // With wait progress callback
+	* const result = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,
+	*     wait: true,
+	*     wait_options: {
+	*         interval_ms: 2000,
+	*         on_status_change: (status) => console.log(`Status: ${status}`),
+	*     },
+	* });
+	*
+	* // Auto-cleanup uploaded file after transcription
+	* const result = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,
+	*     wait: true,
+	*     cleanup: ['file'], // Deletes uploaded file, keeps transcription record
+	* });
+	*
+	* // Auto-cleanup everything after transcription
+	* const result = await client.stt.transcribe({
+	*     model: 'stt-async-v4',
+	*     file: buffer,
+	*     wait: true,
+	*     cleanup: ['file', 'transcription'], // Deletes both file and transcription record
+	* });
+	* ```
+	*/
+	async transcribe(options) {
+		const sourceCount = [
+			options.file !== void 0,
+			options.file_id !== void 0,
+			options.audio_url !== void 0
+		].filter(Boolean).length;
+		if (sourceCount === 0) throw new Error("One of file, file_id, or audio_url must be provided");
+		if (sourceCount > 1) throw new Error("Only one of file, file_id, or audio_url can be provided");
+		if (options.audio_url !== void 0) {
+			if (!/^https?:\/\/[^\s]+$/.test(options.audio_url)) throw new Error("audio_url must be a valid HTTP or HTTPS URL");
+		}
+		if (options.webhook_auth_header_name !== void 0 !== (options.webhook_auth_header_value !== void 0)) throw new Error("webhook_auth_header_name and webhook_auth_header_value must be provided together");
+		if (options.client_reference_id !== void 0 && options.client_reference_id.length > 256) throw new Error(`client_reference_id exceeds maximum length of 256 characters (got ${options.client_reference_id.length})`);
+		if (options.cleanup?.length && !options.wait) throw new Error("cleanup can only be used when wait=true");
+		const { signal: combinedSignal, cleanup: cleanupSignal } = createTimeoutSignal(options.timeout_ms, options.signal);
+		let fileIdToCleanup;
+		let transcriptionId;
+		const performCleanup = async (finalFileId) => {
+			if (!options.cleanup?.length) return;
+			const fileId = finalFileId ?? fileIdToCleanup;
+			if (options.cleanup.includes("file") && fileId) try {
+				await this.filesApi.delete(fileId);
+			} catch {}
+			if (options.cleanup.includes("transcription") && transcriptionId) try {
+				await this.delete(transcriptionId);
+			} catch {}
+		};
+		try {
+			let file_id = options.file_id;
+			if (options.file) {
+				const uploaded = await this.filesApi.upload(options.file, {
+					filename: options.filename,
+					client_reference_id: options.client_reference_id,
+					signal: combinedSignal
+				});
+				file_id = uploaded.id;
+				fileIdToCleanup = uploaded.id;
+			} else if (options.file_id) fileIdToCleanup = options.file_id;
+			let webhook_url = options.webhook_url;
+			if (webhook_url && options.webhook_query) {
+				const url = new URL(webhook_url);
+				(options.webhook_query instanceof URLSearchParams ? options.webhook_query : typeof options.webhook_query === "string" ? new URLSearchParams(options.webhook_query) : new URLSearchParams(options.webhook_query)).forEach((value, key) => {
+					url.searchParams.append(key, value);
+				});
+				webhook_url = url.toString();
+			}
+			const createOptions = {
+				model: options.model,
+				audio_url: options.audio_url,
+				file_id,
+				language_hints: options.language_hints,
+				language_hints_strict: options.language_hints_strict,
+				enable_language_identification: options.enable_language_identification,
+				enable_speaker_diarization: options.enable_speaker_diarization,
+				context: options.context,
+				translation: options.translation,
+				webhook_url,
+				webhook_auth_header_name: options.webhook_auth_header_name,
+				webhook_auth_header_value: options.webhook_auth_header_value,
+				client_reference_id: options.client_reference_id
+			};
+			const transcription = await this.create(createOptions, combinedSignal);
+			transcriptionId = transcription.id;
+			if (transcription.file_id) fileIdToCleanup = transcription.file_id;
+			if (options.wait) {
+				const waitOptions = {
+					...options.wait_options,
+					signal: combinedSignal ?? options.wait_options?.signal
+				};
+				const completed = await transcription.wait(waitOptions);
+				const shouldFetchTranscript = options.fetch_transcript !== false;
+				let transcript;
+				if (completed.status === "completed") {
+					if (shouldFetchTranscript) transcript = await completed.getTranscript(combinedSignal ? { signal: combinedSignal } : void 0);
+				} else transcript = null;
+				const result = new SonioxTranscription(completed.toJSON(), this.http, transcript);
+				await performCleanup(completed.file_id);
+				return result;
+			}
+			return transcription;
+		} catch (error) {
+			if (options.wait) await performCleanup();
+			throw error;
+		} finally {
+			cleanupSignal();
+		}
+	}
+	/**
+	* Permanently deletes all transcriptions.
+	* Iterates through all pages of transcriptions and deletes each one.
+	*
+	* @param options - Optional signal and progress callback.
+	* @returns The number of transcriptions deleted.
+	* @throws {SonioxHttpError} On API errors.
+	* @throws {Error} If the operation is aborted via signal.
+	*
+	* @example
+	* ```typescript
+	* // Delete all transcriptions
+	* const { deleted } = await client.stt.purge();
+	* console.log(`Deleted ${deleted} transcriptions.`);
+	*
+	* // With progress logging
+	* const { deleted } = await client.stt.purge({
+	*     on_progress: (transcription, index) => {
+	*         console.log(`Deleting transcription: ${transcription.id} (${index + 1})`);
+	*     },
+	* });
+	*
+	* // With cancellation
+	* const controller = new AbortController();
+	* const { deleted } = await client.stt.purge({ signal: controller.signal });
+	* ```
+	*/
+	async purge(options = {}) {
+		const { signal, on_progress } = options;
+		const result = await this.list();
+		let deleted = 0;
+		for await (const transcription of result) {
+			signal?.throwIfAborted();
+			on_progress?.(transcription.toJSON(), deleted);
+			await this.delete(transcription);
+			deleted++;
+		}
+		return { deleted };
+	}
+};
+
+//#endregion
+//#region src/async/webhooks.ts
+const VALID_STATUSES = ["completed", "error"];
+/**
+* Get webhook authentication configuration from environment variables.
+*
+* Reads `SONIOX_API_WEBHOOK_HEADER` and `SONIOX_API_WEBHOOK_SECRET` environment variables.
+* Returns undefined if either variable is not set (both are required for authentication).
+*
+* @returns WebhookAuthConfig if both env vars are set, undefined otherwise
+*
+* @example
+* ```typescript
+* // Set environment variables:
+* // SONIOX_API_WEBHOOK_HEADER=X-Webhook-Secret
+* // SONIOX_API_WEBHOOK_SECRET=my-secret-token
+*
+* const auth = getWebhookAuthFromEnv();
+* // Returns: { name: 'X-Webhook-Secret', value: 'my-secret-token' }
+* ```
+*/
+function getWebhookAuthFromEnv() {
+	const headerName = process.env[SONIOX_API_WEBHOOK_HEADER_ENV];
+	const headerValue = process.env[SONIOX_API_WEBHOOK_SECRET_ENV];
+	if (headerName && headerValue) return {
+		name: headerName,
+		value: headerValue
+	};
+}
+/**
+* Resolve webhook authentication configuration.
+*
+* If explicit auth is provided, it is used. Otherwise, attempts to read from
+* environment variables (`SONIOX_API_WEBHOOK_HEADER` and `SONIOX_API_WEBHOOK_SECRET`).
+*
+* @param auth - Explicit authentication configuration (takes precedence)
+* @returns Resolved WebhookAuthConfig or undefined if not configured
+*/
+function resolveWebhookAuth(auth) {
+	return auth ?? getWebhookAuthFromEnv();
+}
+/**
+* Type guard to check if a value is a valid WebhookEvent
+*
+* @param payload - Value to check
+* @returns True if payload is a valid WebhookEvent
+*
+* @example
+* ```typescript
+* if (isWebhookEvent(body)) {
+*     console.log(body.id, body.status);
+* }
+* ```
+*/
+function isWebhookEvent(payload) {
+	if (typeof payload !== "object" || payload === null) return false;
+	const obj = payload;
+	if (typeof obj.id !== "string" || obj.id.length === 0) return false;
+	if (!VALID_STATUSES.includes(obj.status)) return false;
+	return true;
+}
+/**
+* Parse and validate a webhook event payload
+*
+* @param payload - Raw payload to parse (object or JSON string)
+* @returns Validated WebhookEvent
+* @throws Error with descriptive message if payload is invalid
+*
+* @example
+* ```typescript
+* try {
+*     const event = parseWebhookEvent(req.body);
+*     console.log(event.id, event.status);
+* } catch (error) {
+*     console.error('Invalid webhook payload:', error.message);
+* }
+* ```
+*/
+function parseWebhookEvent(payload) {
+	if (typeof payload === "string") try {
+		payload = JSON.parse(payload);
+	} catch {
+		throw new Error("Invalid webhook payload: not valid JSON");
+	}
+	if (typeof payload !== "object" || payload === null) throw new Error("Invalid webhook payload: expected an object");
+	const obj = payload;
+	if (typeof obj.id !== "string") throw new Error("Invalid webhook payload: missing or invalid \"id\" field");
+	if (obj.id.length === 0) throw new Error("Invalid webhook payload: \"id\" field cannot be empty");
+	if (!VALID_STATUSES.includes(obj.status)) throw new Error(`Invalid webhook payload: "status" must be "completed" or "error", got "${String(obj.status)}"`);
+	return {
+		id: obj.id,
+		status: obj.status
+	};
+}
+/**
+* Get a header value from various header formats (case-insensitive)
+*/
+function getHeaderValue(headers, name) {
+	const lowerName = name.toLowerCase();
+	if (headers instanceof Headers) return headers.get(lowerName);
+	if (typeof headers.get === "function") return headers.get(lowerName);
+	const record = headers;
+	if (lowerName in record) {
+		const value = record[lowerName];
+		return Array.isArray(value) ? value[0] ?? null : value ?? null;
+	}
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerName) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] ?? null : value ?? null;
+	}
+	return null;
+}
+/**
+* Verify webhook authentication header
+*
+* @param headers - Request headers
+* @param auth - Authentication configuration with expected header name and value
+* @returns True if authentication passes, false otherwise
+*
+* @example
+* ```typescript
+* const isValid = verifyWebhookAuth(req.headers, {
+*     name: 'X-Webhook-Secret',
+*     value: process.env.WEBHOOK_SECRET,
+* });
+*
+* if (!isValid) {
+*     return res.status(401).send('Unauthorized');
+* }
+* ```
+*/
+function verifyWebhookAuth(headers, auth) {
+	return getHeaderValue(headers, auth.name) === auth.value;
+}
+/**
+* Framework-agnostic webhook handler
+*
+* Validates the HTTP method, authentication (if configured), and parses the webhook payload.
+* Returns a result object that can be used to construct an HTTP response.
+*
+* Authentication is resolved in this order:
+* 1. Explicit `auth` option if provided
+* 2. Environment variables `SONIOX_API_WEBHOOK_HEADER` and `SONIOX_API_WEBHOOK_SECRET`
+* 3. No authentication if neither is configured
+*
+* @param options - Handler options including method, headers, body, and optional auth
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* // Option 1: Set environment variables (recommended)
+* // SONIOX_API_WEBHOOK_HEADER=X-Webhook-Secret
+* // SONIOX_API_WEBHOOK_SECRET=my-secret
+* const result = handleWebhook({
+*     method: req.method,
+*     headers: req.headers,
+*     body: req.body,
+* });
+*
+* // Option 2: Explicit auth config (overrides env vars)
+* const result = handleWebhook({
+*     method: req.method,
+*     headers: req.headers,
+*     body: req.body,
+*     auth: {
+*         name: 'X-Webhook-Secret',
+*         value: process.env.WEBHOOK_SECRET,
+*     },
+* });
+*
+* if (result.ok) {
+*     console.log('Transcription completed:', result.event.id);
+* }
+*
+* res.status(result.status).json(result.ok ? { received: true } : { error: result.error });
+* ```
+*/
+function handleWebhook(options) {
+	const { method, headers, body, auth } = options;
+	if (method.toUpperCase() !== "POST") return {
+		ok: false,
+		status: 405,
+		error: "Method not allowed"
+	};
+	const resolvedAuth = resolveWebhookAuth(auth);
+	if (resolvedAuth) {
+		if (!verifyWebhookAuth(headers, resolvedAuth)) return {
+			ok: false,
+			status: 401,
+			error: "Unauthorized"
+		};
+	}
+	try {
+		return {
+			ok: true,
+			status: 200,
+			event: parseWebhookEvent(body)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			status: 400,
+			error: error instanceof Error ? error.message : "Invalid webhook payload"
+		};
+	}
+}
+/**
+* Handle a webhook from a Fetch API Request (Bun/Deno/Node 18+)
+*
+* @param request - Fetch API Request object
+* @param auth - Optional authentication configuration
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* // Bun.serve handler
+* Bun.serve({
+*     async fetch(req) {
+*         if (new URL(req.url).pathname === '/webhook') {
+*             const result = await handleWebhookRequest(req);
+*
+*             if (result.ok) {
+*                 console.log('Received webhook:', result.event.id);
+*             }
+*
+*             return new Response(
+*                 JSON.stringify(result.ok ? { received: true } : { error: result.error }),
+*                 { status: result.status, headers: { 'Content-Type': 'application/json' } }
+*             );
+*         }
+*     },
+* });
+* ```
+*/
+async function handleWebhookRequest(request, auth) {
+	if (request.method.toUpperCase() !== "POST") return {
+		ok: false,
+		status: 405,
+		error: "Method not allowed"
+	};
+	let body;
+	try {
+		body = await request.json();
+	} catch {
+		return {
+			ok: false,
+			status: 400,
+			error: "Invalid webhook payload: not valid JSON"
+		};
+	}
+	const options = {
+		method: request.method,
+		headers: request.headers,
+		body
+	};
+	if (auth) options.auth = auth;
+	return handleWebhook(options);
+}
+/**
+* Handle a webhook from an Express-like request
+*
+* @param req - Express request object
+* @param auth - Optional authentication configuration
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* import express from 'express';
+* import { handleWebhookExpress } from '@soniox/node';
+*
+* const app = express();
+* app.use(express.json());
+*
+* app.post('/webhook', (req, res) => {
+*     const result = handleWebhookExpress(req);
+*
+*     if (result.ok) {
+*         console.log('Received webhook:', result.event.id);
+*     }
+*
+*     res.status(result.status).json(
+*         result.ok ? { received: true } : { error: result.error }
+*     );
+* });
+* ```
+*/
+function handleWebhookExpress(req, auth) {
+	const options = {
+		method: req.method,
+		headers: req.headers,
+		body: req.body
+	};
+	if (auth) options.auth = auth;
+	return handleWebhook(options);
+}
+/**
+* Handle a webhook from a Fastify request
+*
+* @param req - Fastify request object
+* @param auth - Optional authentication configuration
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* import Fastify from 'fastify';
+* import { handleWebhookFastify } from '@soniox/node';
+*
+* const fastify = Fastify();
+*
+* fastify.post('/webhook', async (req, reply) => {
+*     const result = handleWebhookFastify(req);
+*
+*     if (result.ok) {
+*         console.log('Received webhook:', result.event.id);
+*     }
+*
+*     return reply.status(result.status).send(
+*         result.ok ? { received: true } : { error: result.error }
+*     );
+* });
+* ```
+*/
+function handleWebhookFastify(req, auth) {
+	const options = {
+		method: req.method,
+		headers: req.headers,
+		body: req.body
+	};
+	if (auth) options.auth = auth;
+	return handleWebhook(options);
+}
+/**
+* Handle a webhook from a NestJS request
+*
+* Works with NestJS using either Express or Fastify adapter.
+*
+* @param req - NestJS request object (injected via @Req() decorator)
+* @param auth - Optional authentication configuration (overrides env vars)
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* import { Controller, Post, Req, Res, HttpStatus } from '@nestjs/common';
+* import { Request, Response } from 'express';
+* import { handleWebhookNestJS } from '@soniox/node';
+*
+* @Controller('webhook')
+* export class WebhookController {
+*     @Post()
+*     handleWebhook(@Req() req: Request, @Res() res: Response) {
+*         const result = handleWebhookNestJS(req);
+*
+*         if (result.ok) {
+*             console.log('Received webhook:', result.event.id);
+*         }
+*
+*         return res.status(result.status).json(
+*             result.ok ? { received: true } : { error: result.error }
+*         );
+*     }
+* }
+* ```
+*/
+function handleWebhookNestJS(req, auth) {
+	const options = {
+		method: req.method,
+		headers: req.headers,
+		body: req.body
+	};
+	if (auth) options.auth = auth;
+	return handleWebhook(options);
+}
+/**
+* Handle a webhook from a Hono context
+*
+* @param c - Hono context object
+* @param auth - Optional authentication configuration
+* @returns Result with ok status, HTTP status code, and either event or error
+*
+* @example
+* ```typescript
+* import { Hono } from 'hono';
+* import { handleWebhookHono } from '@soniox/node';
+*
+* const app = new Hono();
+*
+* app.post('/webhook', async (c) => {
+*     const result = await handleWebhookHono(c);
+*
+*     if (result.ok) {
+*         console.log('Received webhook:', result.event.id);
+*     }
+*
+*     return c.json(
+*         result.ok ? { received: true } : { error: result.error },
+*         result.status
+*     );
+* });
+* ```
+*/
+async function handleWebhookHono(c, auth) {
+	let body;
+	try {
+		body = await c.req.json();
+	} catch {
+		return {
+			ok: false,
+			status: 400,
+			error: "Invalid webhook payload: not valid JSON"
+		};
+	}
+	const options = {
+		method: c.req.method,
+		headers: { get(name) {
+			return c.req.header(name) ?? null;
+		} },
+		body
+	};
+	if (auth) options.auth = auth;
+	return handleWebhook(options);
+}
+/**
+* Webhook utilities API accessible via client.webhooks
+*
+* Provides methods for handling incoming Soniox webhook requests.
+* When used via the client, results include lazy fetch helpers for transcripts.
+*/
+var SonioxWebhooksAPI = class {
+	stt;
+	/**
+	* @internal
+	*/
+	constructor(stt) {
+		this.stt = stt;
+	}
+	/**
+	* Enhance a webhook result with fetch helpers
+	*/
+	withFetchHelpers(result) {
+		const stt = this.stt;
+		const event = result.event;
+		if (!stt || !event) return {
+			...result,
+			fetchTranscript: void 0,
+			fetchTranscription: void 0
+		};
+		const transcriptionId = event.id;
+		return {
+			...result,
+			fetchTranscript: event.status === "completed" ? () => stt.getTranscript(transcriptionId) : void 0,
+			fetchTranscription: () => stt.get(transcriptionId)
+		};
+	}
+	/**
+	* Get webhook authentication configuration from environment variables.
+	*
+	* Reads `SONIOX_API_WEBHOOK_HEADER` and `SONIOX_API_WEBHOOK_SECRET` environment variables.
+	* Returns undefined if either variable is not set (both are required for authentication).
+	*/
+	getAuthFromEnv() {
+		return getWebhookAuthFromEnv();
+	}
+	/**
+	* Type guard to check if a value is a valid WebhookEvent
+	*/
+	isEvent(payload) {
+		return isWebhookEvent(payload);
+	}
+	/**
+	* Parse and validate a webhook event payload
+	*/
+	parseEvent(payload) {
+		return parseWebhookEvent(payload);
+	}
+	/**
+	* Verify webhook authentication header
+	*/
+	verifyAuth(headers, auth) {
+		return verifyWebhookAuth(headers, auth);
+	}
+	/**
+	* Framework-agnostic webhook handler
+	*/
+	handle(options) {
+		return this.withFetchHelpers(handleWebhook(options));
+	}
+	/**
+	* Handle a webhook from a Fetch API Request
+	*/
+	async handleRequest(request, auth) {
+		const result = await handleWebhookRequest(request, auth);
+		return this.withFetchHelpers(result);
+	}
+	/**
+	* Handle a webhook from an Express-like request
+	*
+	* @example
+	* ```typescript
+	* app.post('/webhook', async (req, res) => {
+	*     const result = soniox.webhooks.handleExpress(req);
+	*
+	*     if (result.ok && result.event.status === 'completed') {
+	*         const transcript = await result.fetchTranscript();
+	*         console.log(transcript?.text);
+	*     }
+	*
+	*     res.status(result.status).json({ received: true });
+	* });
+	* ```
+	*/
+	handleExpress(req, auth) {
+		return this.withFetchHelpers(handleWebhookExpress(req, auth));
+	}
+	/**
+	* Handle a webhook from a Fastify request
+	*/
+	handleFastify(req, auth) {
+		return this.withFetchHelpers(handleWebhookFastify(req, auth));
+	}
+	/**
+	* Handle a webhook from a NestJS request
+	*/
+	handleNestJS(req, auth) {
+		return this.withFetchHelpers(handleWebhookNestJS(req, auth));
+	}
+	/**
+	* Handle a webhook from a Hono context
+	*/
+	async handleHono(c, auth) {
+		const result = await handleWebhookHono(c, auth);
+		return this.withFetchHelpers(result);
+	}
+};
+
+//#endregion
+//#region src/http/url.ts
+/**
+* Builds a complete URL from base URL, path, and query parameters
+*/
+function buildUrl(baseUrl, path, query) {
+	let url = joinUrl(baseUrl ?? "", path);
+	if (query) {
+		const params = new URLSearchParams();
+		for (const [key, value] of Object.entries(query)) if (value !== void 0) params.append(key, String(value));
+		const queryString = params.toString();
+		if (queryString) url += (url.includes("?") ? "&" : "?") + queryString;
+	}
+	return url;
+}
+/**
+* Joins a base URL with a path
+*/
+function joinUrl(baseUrl, path) {
+	if (!baseUrl) return path;
+	if (!path) return baseUrl;
+	if (/^https?:\/\//i.test(path)) return path;
+	return (baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl) + (path.startsWith("/") ? path : `/${path}`);
+}
+/**
+* Normalizes fetch Headers to a plain object with lowercase keys
+*/
+function normalizeHeaders(headers) {
+	const result = {};
+	headers.forEach((value, key) => {
+		result[key.toLowerCase()] = value;
+	});
+	return result;
+}
+/**
+* Merges header objects
+*/
+function mergeHeaders(...headerObjects) {
+	const result = {};
+	for (const headers of headerObjects) if (headers) for (const [key, value] of Object.entries(headers)) result[key.toLowerCase()] = value;
+	return result;
+}
+
+//#endregion
+//#region src/http/fetch-adapter.ts
+/** Default timeout in milliseconds (30 seconds) TODO: Move to constants? */
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Determines the Content-Type header based on the body type.
+*/
+function getContentTypeForBody(body) {
+	if (body === null || body === void 0) return;
+	if (typeof body === "string") return "text/plain; charset=utf-8";
+	if (typeof FormData !== "undefined" && body instanceof FormData) return;
+	if (body instanceof ArrayBuffer || body instanceof Uint8Array) return "application/octet-stream";
+	return "application/json";
+}
+/**
+* Prepares the request body for fetch.
+*/
+function prepareBody(body) {
+	if (body === null || body === void 0) return;
+	if (typeof body === "string") return body;
+	if (typeof FormData !== "undefined" && body instanceof FormData) return body;
+	if (body instanceof ArrayBuffer) return body;
+	if (body instanceof Uint8Array) return body;
+	return JSON.stringify(body);
+}
+/**
+* Parses the response based on the expected type.
+*/
+async function parseResponse(response, responseType, url, method) {
+	const contentLength = response.headers.get("content-length");
+	if (response.status === 204 || contentLength === "0") switch (responseType) {
+		case "arrayBuffer": return /* @__PURE__ */ new ArrayBuffer(0);
+		case "text": return "";
+		case "json":
+		default: return null;
+	}
+	switch (responseType) {
+		case "text": return await response.text();
+		case "arrayBuffer": return await response.arrayBuffer();
+		case "json":
+		default: {
+			const text = await response.text();
+			if (!text) return null;
+			try {
+				return JSON.parse(text);
+			} catch (error) {
+				throw createParseError(url, method, text, error);
+			}
+		}
+	}
+}
+/**
+* Default fetch-based HTTP client.
+*
+* @example Basic usage
+* ```typescript
+* const client = new FetchHttpClient({
+*   base_url: 'https://api.example.com/v1',
+*   default_headers: {
+*     'Authorization': 'Bearer token',
+*   },
+* });
+*
+* const response = await client.request<{ users: User[] }>({
+*   method: 'GET',
+*   path: '/users',
+*   query: { active: true },
+* });
+* ```
+*
+* @example With custom fetch (e.g., for testing)
+* ```typescript
+* const mockFetch = vi.fn().mockResolvedValue(new Response('{}'));
+* const client = new FetchHttpClient({
+*   base_url: 'https://api.example.com',
+*   fetch: mockFetch,
+* });
+* ```
+*
+* @example Sending different body types
+* ```typescript
+* // JSON body (default for objects)
+* await client.request({
+*   method: 'POST',
+*   path: '/data',
+*   body: { name: 'test', value: 123 },
+* });
+*
+* // Text body
+* await client.request({
+*   method: 'POST',
+*   path: '/text',
+*   body: 'plain text content',
+*   headers: { 'Content-Type': 'text/plain' },
+* });
+*
+* // Binary body
+* await client.request({
+*   method: 'POST',
+*   path: '/upload',
+*   body: new Uint8Array([1, 2, 3]),
+* });
+*
+* // FormData (for file uploads)
+* const formData = new FormData();
+* formData.append('file', fileBlob, 'document.pdf');
+* await client.request({
+*   method: 'POST',
+*   path: '/files',
+*   body: formData,
+* });
+* ```
+*/
+var FetchHttpClient = class {
+	baseUrl;
+	defaultHeaders;
+	defaultTimeoutMs;
+	hooks;
+	fetchImpl;
+	constructor(options = {}) {
+		this.baseUrl = options.base_url;
+		this.defaultHeaders = options.default_headers ?? {};
+		this.defaultTimeoutMs = options.default_timeout_ms ?? DEFAULT_TIMEOUT_MS;
+		this.hooks = options.hooks ?? {};
+		this.fetchImpl = options.fetch ?? globalThis.fetch;
+		if (!this.fetchImpl) throw new Error("fetch is not available. Please provide a fetch implementation via options.fetch");
+	}
+	/**
+	* Performs an HTTP request.
+	*
+	* @param request - Request configuration
+	* @returns Promise resolving to the response
+	* @throws {SonioxHttpError}
+	*/
+	async request(request) {
+		const startTime = Date.now();
+		const url = buildUrl(this.baseUrl, request.path, request.query);
+		const method = request.method;
+		const responseType = request.responseType ?? "json";
+		const contentTypeHeader = getContentTypeForBody(request.body);
+		const headers = mergeHeaders(typeof FormData !== "undefined" && request.body instanceof FormData ? Object.fromEntries(Object.entries(this.defaultHeaders).filter(([key]) => key.toLowerCase() !== "content-type")) : this.defaultHeaders, contentTypeHeader ? { "Content-Type": contentTypeHeader } : void 0, request.headers);
+		const requestMeta = {
+			startTime,
+			url,
+			method,
+			headers
+		};
+		this.hooks.onRequest?.(request, requestMeta);
+		const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
+		const timeoutController = new AbortController();
+		let timeoutId;
+		if (timeoutMs > 0) timeoutId = setTimeout(() => {
+			timeoutController.abort(/* @__PURE__ */ new Error("Request timeout"));
+		}, timeoutMs);
+		const combined = request.signal ? combineAbortSignals(timeoutController.signal, request.signal) : null;
+		const signal = combined ? combined.signal : timeoutController.signal;
+		try {
+			const preparedBody = prepareBody(request.body);
+			const response = await this.fetchImpl(url, {
+				method,
+				headers,
+				signal,
+				...preparedBody !== void 0 && { body: preparedBody }
+			});
+			if (timeoutId) clearTimeout(timeoutId);
+			const responseHeaders = normalizeHeaders(response.headers);
+			if (!response.ok) {
+				const bodyText = await response.text().catch(() => "");
+				throw createHttpError(url, method, response.status, responseHeaders, bodyText);
+			}
+			const data = await parseResponse(response, responseType, url, method);
+			const result = {
+				status: response.status,
+				headers: responseHeaders,
+				data
+			};
+			const responseMeta = {
+				...requestMeta,
+				durationMs: Date.now() - startTime,
+				status: response.status
+			};
+			this.hooks.onResponse?.(result, responseMeta);
+			return result;
+		} catch (error) {
+			if (timeoutId) clearTimeout(timeoutId);
+			const errorMeta = {
+				...requestMeta,
+				durationMs: Date.now() - startTime
+			};
+			const normalizedError = this.normalizeError(error, url, method, timeoutMs, timeoutController);
+			this.hooks.onError?.(normalizedError, errorMeta);
+			throw normalizedError;
+		} finally {
+			combined?.cleanup();
+		}
+	}
+	/**
+	* Normalizes various error types into SonioxHttpError.
+	*/
+	normalizeError(error, url, method, timeoutMs, timeoutController) {
+		if (error instanceof SonioxHttpError) return error;
+		if (timeoutController.signal.aborted && isAbortError(error)) return createTimeoutError(url, method, timeoutMs);
+		if (isAbortError(error)) return createAbortError(url, method, error);
+		if (error instanceof TypeError) return createNetworkError(url, method, error);
+		return createNetworkError(url, method, error);
+	}
+};
+/**
+* Combines multiple AbortSignals into one.
+* The resulting signal will abort if any of the input signals abort.
+* Returns the combined signal and a cleanup function to remove listeners.
+*/
+function combineAbortSignals(...signals) {
+	const controller = new AbortController();
+	const handlers = [];
+	const cleanup = () => {
+		for (const { signal, handler } of handlers) signal.removeEventListener("abort", handler);
+		handlers.length = 0;
+	};
+	for (const signal of signals) {
+		if (signal.aborted) {
+			controller.abort(signal.reason);
+			return {
+				signal: controller.signal,
+				cleanup
+			};
+		}
+		const handler = () => {
+			controller.abort(signal.reason);
+		};
+		handlers.push({
+			signal,
+			handler
+		});
+		signal.addEventListener("abort", handler, { once: true });
+	}
+	return {
+		signal: controller.signal,
+		cleanup
+	};
+}
+
+//#endregion
+//#region src/realtime/async-queue.ts
+/**
+* Generic async event queue that supports iteration with proper error propagation.
+*
+* This utility enables `for await...of` consumption of events while properly
+* surfacing errors to consumers instead of silently ending iteration.
+*/
+var AsyncEventQueue = class {
+	queue = [];
+	waiters = [];
+	done = false;
+	error = null;
+	/**
+	* Push an event to the queue.
+	* If there are waiting consumers, delivers immediately.
+	*/
+	push(event) {
+		if (this.done) return;
+		const waiter = this.waiters.shift();
+		if (waiter) waiter.resolve({
+			value: event,
+			done: false
+		});
+		else this.queue.push(event);
+	}
+	/**
+	* End the queue normally.
+	* Waiting consumers will receive `{ done: true }`.
+	*/
+	end() {
+		if (this.done) return;
+		this.done = true;
+		this.flushWaiters();
+	}
+	/**
+	* End the queue with an error.
+	* Waiting consumers will have their promises rejected.
+	* Future `next()` calls will also reject with this error.
+	* Any queued events are discarded.
+	*/
+	abort(error) {
+		if (this.done) return;
+		this.done = true;
+		this.error = error;
+		this.queue = [];
+		this.flushWaiters();
+	}
+	/**
+	* Whether the queue has ended (normally or with error).
+	*/
+	get isDone() {
+		return this.done;
+	}
+	/**
+	* Async iterator implementation.
+	*/
+	[Symbol.asyncIterator]() {
+		return { next: () => this.next() };
+	}
+	/**
+	* Get the next event from the queue.
+	*/
+	next() {
+		const error = this.error;
+		if (error) return Promise.reject(error);
+		const event = this.queue.shift();
+		if (event !== void 0) return Promise.resolve({
+			value: event,
+			done: false
+		});
+		if (this.done) return Promise.resolve({
+			value: void 0,
+			done: true
+		});
+		return new Promise((resolve, reject) => {
+			this.waiters.push({
+				resolve,
+				reject
+			});
+		});
+	}
+	/**
+	* Flush all waiting consumers when queue ends.
+	*/
+	flushWaiters() {
+		for (const { resolve, reject } of this.waiters) if (this.error) reject(this.error);
+		else resolve({
+			value: void 0,
+			done: true
+		});
+		this.waiters = [];
+	}
+};
+
+//#endregion
+//#region src/realtime/emitter.ts
+/**
+* A minimal, runtime-agnostic typed event emitter.
+* Does not depend on Node.js EventEmitter.
+*/
+var TypedEmitter = class {
+	listeners = /* @__PURE__ */ new Map();
+	errorEvent = "error";
+	/**
+	* Register an event handler.
+	*/
+	on(event, handler) {
+		let handlers = this.listeners.get(event);
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.listeners.set(event, handlers);
+		}
+		handlers.add(handler);
+		return this;
+	}
+	/**
+	* Register a one-time event handler.
+	*/
+	once(event, handler) {
+		const wrapper = ((...args) => {
+			this.off(event, wrapper);
+			handler(...args);
+		});
+		return this.on(event, wrapper);
+	}
+	/**
+	* Remove an event handler.
+	*/
+	off(event, handler) {
+		const handlers = this.listeners.get(event);
+		if (handlers) {
+			handlers.delete(handler);
+			if (handlers.size === 0) this.listeners.delete(event);
+		}
+		return this;
+	}
+	/**
+	* Emit an event to all registered handlers.
+	* Handler errors do not prevent other handlers from running.
+	* Errors are reported to an `error` event if present, otherwise rethrown async.
+	*/
+	emit(event, ...args) {
+		const handlers = this.listeners.get(event);
+		if (handlers) for (const handler of [...handlers]) try {
+			handler(...args);
+		} catch (error) {
+			if (event === this.errorEvent) this.scheduleThrow(this.normalizeError(error));
+			else this.reportListenerError(error);
+		}
+	}
+	/**
+	* Remove all event handlers.
+	*/
+	removeAllListeners(event) {
+		if (event !== void 0) this.listeners.delete(event);
+		else this.listeners.clear();
+	}
+	reportListenerError(error) {
+		const normalizedError = this.normalizeError(error);
+		const handlers = this.listeners.get(this.errorEvent);
+		if (!handlers || handlers.size === 0) {
+			this.scheduleThrow(normalizedError);
+			return;
+		}
+		for (const handler of [...handlers]) try {
+			handler(normalizedError);
+		} catch (handlerError) {
+			this.scheduleThrow(this.normalizeError(handlerError));
+		}
+	}
+	normalizeError(error) {
+		if (error instanceof Error) return error;
+		return new Error(String(error));
+	}
+	scheduleThrow(error) {
+		setTimeout(() => {
+			throw error;
+		}, 0);
+	}
+};
+
+//#endregion
+//#region src/realtime/errors.ts
+/**
+* Real-time (WebSocket) API error classes for the Soniox SDK
+* All real-time errors extend SonioxError
+*/
+/**
+* Base error class for all real-time (WebSocket) SDK errors
+*/
+var RealtimeError = class extends SonioxError {
+	/**
+	* Original response payload for debugging.
+	* Contains the raw WebSocket message that caused the error.
+	*/
+	raw;
+	constructor(message, code = "realtime_error", statusCode, raw) {
+		super(message, code, statusCode);
+		this.name = "RealtimeError";
+		this.raw = raw;
+	}
+	/**
+	* Creates a human-readable string representation
+	*/
+	toString() {
+		const parts = [`${this.name} [${this.code}]: ${this.message}`];
+		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,
+			...this.statusCode !== void 0 && { statusCode: this.statusCode },
+			...this.raw !== void 0 && { raw: this.raw }
+		};
+	}
+};
+/**
+* Authentication error (401).
+* Thrown when the API key is invalid or expired.
+*/
+var AuthError = class extends RealtimeError {
+	constructor(message, statusCode, raw) {
+		super(message, "auth_error", statusCode, raw);
+		this.name = "AuthError";
+	}
+};
+/**
+* Bad request error (400).
+* Thrown for invalid configuration or parameters.
+*/
+var BadRequestError = class extends RealtimeError {
+	constructor(message, statusCode, raw) {
+		super(message, "bad_request", statusCode, raw);
+		this.name = "BadRequestError";
+	}
+};
+/**
+* Quota error (402, 429).
+* Thrown when rate limits are exceeded or quota is exhausted.
+*/
+var QuotaError = class extends RealtimeError {
+	constructor(message, statusCode, raw) {
+		super(message, "quota_exceeded", statusCode, raw);
+		this.name = "QuotaError";
+	}
+};
+/**
+* Connection error.
+* Thrown for WebSocket connection failures and transport errors.
+*/
+var ConnectionError = class extends RealtimeError {
+	constructor(message, raw) {
+		super(message, "connection_error", void 0, raw);
+		this.name = "ConnectionError";
+	}
+};
+/**
+* Network error.
+* Thrown for server-side network issues (408, 500, 503).
+*/
+var NetworkError = class extends RealtimeError {
+	constructor(message, statusCode, raw) {
+		super(message, "network_error", statusCode, raw);
+		this.name = "NetworkError";
+	}
+};
+/**
+* Abort error.
+* Thrown when an operation is cancelled via AbortSignal.
+*/
+var AbortError = class extends RealtimeError {
+	constructor(message = "Operation aborted") {
+		super(message, "aborted");
+		this.name = "AbortError";
+	}
+};
+/**
+* State error.
+* Thrown when an operation is attempted in an invalid state.
+*/
+var StateError = class extends RealtimeError {
+	constructor(message) {
+		super(message, "state_error");
+		this.name = "StateError";
+	}
+};
+/**
+* Map a Soniox error response to a typed error class.
+*
+* @param response - Error response from the WebSocket
+* @returns Appropriate error subclass
+*/
+function mapErrorResponse(response) {
+	const { error_code, error_message } = response;
+	const message = error_message ?? "Unknown error";
+	switch (error_code) {
+		case 401: return new AuthError(message, error_code, response);
+		case 400: return new BadRequestError(message, error_code, response);
+		case 402:
+		case 429: return new QuotaError(message, error_code, response);
+		case 408:
+		case 500:
+		case 503: return new NetworkError(message, error_code, response);
+		default: return new RealtimeError(message, "realtime_error", error_code, response);
+	}
+}
+
+//#endregion
+//#region src/realtime/stt.ts
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 5e3;
+/**
+* Convert audio data to Uint8Array
+* Handles Buffer, Uint8Array, and ArrayBuffer
+*/
+function toUint8Array(data) {
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+/**
+* Build the configuration message to send after WebSocket connection
+*/
+function buildConfigMessage(config, apiKey) {
+	return {
+		api_key: apiKey,
+		model: config.model,
+		audio_format: config.audio_format ?? "auto",
+		sample_rate: config.sample_rate,
+		num_channels: config.num_channels,
+		language_hints: config.language_hints,
+		language_hints_strict: config.language_hints_strict,
+		enable_speaker_diarization: config.enable_speaker_diarization,
+		enable_language_identification: config.enable_language_identification,
+		enable_endpoint_detection: config.enable_endpoint_detection,
+		client_reference_id: config.client_reference_id,
+		context: config.context,
+		translation: config.translation
+	};
+}
+/**
+* Parse a result message from the WebSocket
+*/
+function parseResultMessage(data) {
+	const raw = JSON.parse(data);
+	if ("error_code" in raw || "error_message" in raw) throw mapErrorResponse(raw);
+	return {
+		tokens: (raw.tokens ?? []).map((t) => ({
+			text: typeof t.text === "string" ? t.text : "",
+			start_ms: typeof t.start_ms === "number" ? t.start_ms : void 0,
+			end_ms: typeof t.end_ms === "number" ? t.end_ms : void 0,
+			confidence: typeof t.confidence === "number" ? t.confidence : 0,
+			is_final: Boolean(t.is_final),
+			speaker: typeof t.speaker === "string" ? t.speaker : void 0,
+			language: typeof t.language === "string" ? t.language : void 0,
+			translation_status: t.translation_status === "none" || t.translation_status === "original" || t.translation_status === "translation" ? t.translation_status : void 0,
+			source_language: typeof t.source_language === "string" ? t.source_language : void 0
+		})),
+		final_audio_proc_ms: typeof raw.final_audio_proc_ms === "number" ? raw.final_audio_proc_ms : 0,
+		total_audio_proc_ms: typeof raw.total_audio_proc_ms === "number" ? raw.total_audio_proc_ms : 0,
+		finished: raw.finished === true,
+		raw
+	};
+}
+/**
+* Check if a token is a special control token
+*/
+function isSpecialToken(text) {
+	return text === "<end>" || text === "<fin>";
+}
+/**
+* Filter out special control tokens from tokens array
+*/
+function filterSpecialTokens(tokens) {
+	return tokens.filter((t) => !isSpecialToken(t.text));
+}
+/**
+* Real-time Speech-to-Text session
+*
+* Provides WebSocket-based streaming transcription with support for:
+* - Event-based and async iterator consumption
+* - Pause/resume with automatic keepalive
+* - AbortSignal cancellation
+*
+* @example
+* ```typescript
+* const session = client.realtime.stt({ model: 'stt-rt-preview' });
+*
+* session.on('result', (result) => {
+*   console.log(result.tokens.map(t => t.text).join(''));
+* });
+*
+* await session.connect();
+* await session.sendAudio(audioChunk);
+* await session.finish();
+* ```
+*/
+var RealtimeSttSession = class {
+	emitter = new TypedEmitter();
+	eventQueue = new AsyncEventQueue();
+	apiKey;
+	wsBaseUrl;
+	config;
+	keepaliveIntervalMs;
+	keepaliveEnabled;
+	signal;
+	ws = null;
+	_state = "idle";
+	_paused = false;
+	keepaliveInterval = null;
+	finishResolver = null;
+	finishRejecter = null;
+	abortHandler = null;
+	constructor(apiKey, wsBaseUrl, config, options) {
+		this.apiKey = apiKey;
+		this.wsBaseUrl = wsBaseUrl;
+		this.config = config;
+		this.keepaliveIntervalMs = options?.keepalive_interval_ms ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
+		this.keepaliveEnabled = options?.keepalive ?? false;
+		this.signal = options?.signal;
+		if (this.signal) {
+			this.abortHandler = () => this.handleAbort();
+			this.signal.addEventListener("abort", this.abortHandler);
+		}
+	}
+	/**
+	* Current session state.
+	*/
+	get state() {
+		return this._state;
+	}
+	/**
+	* Whether the session is currently paused.
+	*/
+	get paused() {
+		return this._paused;
+	}
+	/**
+	* Connect to the Soniox WebSocket API.
+	*
+	* @throws {AbortError} If aborted
+	* @throws {NetworkError} If connection fails
+	* @throws {StateError} If already connected
+	*/
+	async connect() {
+		if (this._state !== "idle") throw new StateError(`Cannot connect: session is in "${this._state}" state`);
+		this.checkAborted();
+		this.setState("connecting");
+		try {
+			await this.createWebSocket();
+			this.setState("connected");
+			this.emitter.emit("connected");
+			this.updateKeepalive();
+		} catch (error) {
+			this.setState("error");
+			throw error;
+		}
+	}
+	/**
+	* Send audio data to the server
+	*
+	* @param data - Audio data as Buffer, Uint8Array, or ArrayBuffer
+	* @throws {AbortError} If aborted
+	* @throws {StateError} If not connected
+	*/
+	sendAudio(data) {
+		this.checkAborted();
+		if (this._state !== "connected") throw new StateError(`Cannot send audio: session is in "${this._state}" state`);
+		if (this._paused) return;
+		const chunk = toUint8Array(data);
+		this.sendMessage(chunk, true);
+	}
+	/**
+	* Stream audio data from an async iterable source.
+	*
+	* Reads chunks from the iterable and sends each via {@link sendAudio}.
+	* Works with Node.js ReadableStreams, Web ReadableStreams, async generators,
+	* and any other `AsyncIterable<AudioData>`.
+	*
+	* @param stream - Async iterable yielding audio chunks
+	* @param options - Optional pacing and auto-finish settings
+	* @throws {AbortError} If aborted during streaming
+	* @throws {StateError} If not connected
+	*
+	* @example
+	* ```typescript
+	* // Stream from a Node.js file
+	* import fs from 'fs';
+	* await session.sendStream(fs.createReadStream('audio.mp3'), { finish: true });
+	*
+	* // Stream with simulated real-time pacing
+	* await session.sendStream(
+	*   fs.createReadStream('audio.pcm_s16le', { highWaterMark: 3840 }),
+	*   { pace_ms: 120, finish: true }
+	* );
+	*
+	* // Stream from a Web fetch response
+	* const response = await fetch('https://soniox.com/media/examples/coffee_shop.mp3');
+	* await session.sendStream(response.body, { finish: true });
+	* ```
+	*/
+	async sendStream(stream, options) {
+		for await (const chunk of stream) {
+			this.sendAudio(chunk);
+			if (options?.pace_ms) await new Promise((resolve) => setTimeout(resolve, options.pace_ms));
+		}
+		if (options?.finish) await this.finish();
+	}
+	/**
+	* Pause audio transmission and starts automatic keepalive messages
+	*/
+	pause() {
+		if (this._paused) return;
+		this._paused = true;
+		this.updateKeepalive();
+	}
+	/**
+	* Resume audio transmission
+	*/
+	resume() {
+		if (!this._paused) return;
+		this._paused = false;
+		this.updateKeepalive();
+	}
+	/**
+	* Requests the server to finalize current transcription
+	*/
+	finalize(options) {
+		if (this._state !== "connected" && this._state !== "finishing") return;
+		const message = { type: "finalize" };
+		if (options?.trailing_silence_ms !== void 0) message.trailing_silence_ms = options.trailing_silence_ms;
+		this.sendMessage(JSON.stringify(message), false);
+	}
+	/**
+	* Send a keepalive message
+	*/
+	keepAlive() {
+		if (this._state !== "connected" && this._state !== "finishing") return;
+		this.sendMessage(JSON.stringify({ type: "keepalive" }), false);
+	}
+	/**
+	* Gracefully finish the session
+	*/
+	async finish() {
+		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.updateKeepalive();
+		const finishPromise = new Promise((resolve, reject) => {
+			this.finishResolver = resolve;
+			this.finishRejecter = reject;
+		});
+		this.sendMessage("", false);
+		return finishPromise;
+	}
+	/**
+	* Close (cancel) the session immediately without waiting
+	*/
+	close() {
+		this.emitter.emit("disconnected", "client_closed");
+		this.settleFinish(new StateError("Session canceled"));
+		this.cleanup("canceled");
+	}
+	/**
+	* Register an event handler
+	*/
+	on(event, handler) {
+		this.emitter.on(event, handler);
+		return this;
+	}
+	/**
+	* Register a one-time event handler
+	*/
+	once(event, handler) {
+		this.emitter.once(event, handler);
+		return this;
+	}
+	/**
+	* Remove an event handler
+	*/
+	off(event, handler) {
+		this.emitter.off(event, handler);
+		return this;
+	}
+	/**
+	* Async iterator for consuming events.
+	*/
+	[Symbol.asyncIterator]() {
+		return this.eventQueue[Symbol.asyncIterator]();
+	}
+	async createWebSocket() {
+		return new Promise((resolve, reject) => {
+			try {
+				const ws = new WebSocket(this.wsBaseUrl);
+				this.ws = ws;
+				ws.binaryType = "arraybuffer";
+				const cleanup = () => {
+					ws.removeEventListener("open", onOpen);
+					ws.removeEventListener("error", onError);
+				};
+				const onOpen = () => {
+					cleanup();
+					const configMessage = buildConfigMessage(this.config, this.apiKey);
+					ws.send(JSON.stringify(configMessage));
+					ws.addEventListener("message", this.handleMessage.bind(this));
+					ws.addEventListener("close", this.handleClose.bind(this));
+					ws.addEventListener("error", this.handleError.bind(this));
+					resolve();
+				};
+				const onError = (event) => {
+					cleanup();
+					reject(new ConnectionError("WebSocket connection failed", event));
+				};
+				ws.addEventListener("open", onOpen);
+				ws.addEventListener("error", onError);
+				if (this.signal) this.signal.addEventListener("abort", () => {
+					cleanup();
+					ws.close();
+					reject(new AbortError());
+				}, { once: true });
+			} catch (error) {
+				reject(new ConnectionError("Failed to create WebSocket", error));
+			}
+		});
+	}
+	handleMessage(event) {
+		if (typeof event.data !== "string") return;
+		const data = event.data;
+		try {
+			const result = parseResultMessage(data);
+			const hasEndpoint = result.tokens.some((t) => t.text === "<end>");
+			const hasFinalized = result.tokens.some((t) => t.text === "<fin>");
+			const userTokens = filterSpecialTokens(result.tokens);
+			for (const token of userTokens) this.emitter.emit("token", token);
+			const filteredResult = {
+				...result,
+				tokens: userTokens
+			};
+			this.emitter.emit("result", filteredResult);
+			this.eventQueue.push({
+				kind: "result",
+				data: filteredResult
+			});
+			if (hasEndpoint) {
+				this.emitter.emit("endpoint");
+				this.eventQueue.push({ kind: "endpoint" });
+			}
+			if (hasFinalized) {
+				this.emitter.emit("finalized");
+				this.eventQueue.push({ kind: "finalized" });
+			}
+			if (result.finished) {
+				this.emitter.emit("finished");
+				this.eventQueue.push({ kind: "finished" });
+				this.settleFinish();
+				this.cleanup("finished");
+			}
+		} catch (error) {
+			const err = error;
+			this.emitter.emit("error", err);
+			this.settleFinish(err);
+			this.cleanup("error", err);
+		}
+	}
+	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);
+			return;
+		}
+		this.cleanup("closed");
+	}
+	handleError(event) {
+		const error = new ConnectionError("WebSocket error", event);
+		this.emitter.emit("error", error);
+		this.settleFinish(error);
+		this.cleanup("error", error);
+	}
+	handleAbort() {
+		const error = new AbortError();
+		this.emitter.emit("error", error);
+		this.settleFinish(error);
+		this.cleanup("canceled", error);
+	}
+	setState(newState) {
+		if (this._state === newState) return;
+		const oldState = this._state;
+		this._state = newState;
+		this.emitter.emit("state_change", {
+			old_state: oldState,
+			new_state: newState
+		});
+	}
+	cleanup(finalState, error) {
+		this.setState(finalState);
+		this.stopKeepalive();
+		if (this.signal && this.abortHandler) {
+			this.signal.removeEventListener("abort", this.abortHandler);
+			this.abortHandler = null;
+		}
+		if (this.ws) {
+			this.ws.close();
+			this.ws = null;
+		}
+		if (error) this.eventQueue.abort(error);
+		else this.eventQueue.end();
+		this.emitter.removeAllListeners();
+	}
+	isTerminalState(state) {
+		return state === "closed" || state === "error" || state === "finished" || state === "canceled";
+	}
+	checkAborted() {
+		if (this.signal?.aborted) throw new AbortError();
+	}
+	settleFinish(error) {
+		if (!this.finishResolver && !this.finishRejecter) return;
+		const resolve = this.finishResolver;
+		const reject = this.finishRejecter;
+		this.finishResolver = null;
+		this.finishRejecter = null;
+		if (error) reject?.(error);
+		else resolve?.();
+	}
+	sendMessage(data, shouldThrow) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+			const error = new ConnectionError("WebSocket is not open");
+			this.emitter.emit("error", error);
+			this.settleFinish(error);
+			this.cleanup("error", error);
+			if (shouldThrow) throw error;
+			return;
+		}
+		try {
+			this.ws.send(data);
+		} catch (err) {
+			const error = new ConnectionError("WebSocket send failed", err);
+			this.emitter.emit("error", error);
+			this.settleFinish(error);
+			this.cleanup("error", error);
+			if (shouldThrow) throw error;
+		}
+	}
+	startKeepalive() {
+		if (this.keepaliveInterval) return;
+		this.keepaliveInterval = setInterval(() => {
+			this.keepAlive();
+		}, this.keepaliveIntervalMs);
+	}
+	stopKeepalive() {
+		if (this.keepaliveInterval) {
+			clearInterval(this.keepaliveInterval);
+			this.keepaliveInterval = null;
+		}
+	}
+	updateKeepalive() {
+		if ((this._state === "connected" || this._state === "finishing") && (this._paused || this.keepaliveEnabled)) this.startKeepalive();
+		else this.stopKeepalive();
+	}
+};
+
+//#endregion
+//#region src/realtime/segments.ts
+/**
+* Groups real-time tokens into segments based on specified grouping keys.
+*
+* A new segment starts when any of the `group_by` fields changes.
+* Tokens are concatenated as-is.
+*
+* @param tokens - Array of real-time tokens to segment
+* @param options - Segmentation options
+* @param options.group_by - Fields to group by (default: ['speaker', 'language'])
+* @param options.final_only - When true, only finalized tokens are included
+* @returns Array of segments with combined text and timing (if available)
+*/
+function segmentRealtimeTokens(tokens, options = {}) {
+	return segmentTokens(options.final_only ? tokens.filter((token) => token.is_final) : tokens, options, buildSegment);
+}
+function buildSegment(tokens, speaker, language) {
+	const firstToken = tokens[0];
+	const lastToken = tokens[tokens.length - 1];
+	if (!firstToken || !lastToken) throw new Error("Cannot build segment from an empty token array");
+	return {
+		text: tokens.map((t) => t.text).join(""),
+		start_ms: firstToken.start_ms,
+		end_ms: lastToken.end_ms,
+		...!!speaker && { speaker },
+		...!!language && { language },
+		tokens
+	};
+}
+
+//#endregion
+//#region src/realtime/segment-buffer.ts
+const DEFAULT_MAX_TOKENS = 2e3;
+/**
+* Rolling buffer for turning real-time results into stable segments.
+*/
+var RealtimeSegmentBuffer = class {
+	tokens = [];
+	groupBy;
+	finalOnly;
+	maxTokens;
+	maxMs;
+	constructor(options = {}) {
+		validatePositive("max_tokens", options.max_tokens);
+		validatePositive("max_ms", options.max_ms);
+		this.groupBy = options.group_by;
+		this.finalOnly = options.final_only ?? true;
+		this.maxTokens = options.max_tokens ?? DEFAULT_MAX_TOKENS;
+		this.maxMs = options.max_ms;
+	}
+	/**
+	* Number of tokens currently buffered.
+	*/
+	get size() {
+		return this.tokens.length;
+	}
+	/**
+	* Add a real-time result and return stable segments.
+	*/
+	add(result) {
+		const incoming = this.finalOnly ? result.tokens.filter((token) => token.is_final) : result.tokens;
+		if (incoming.length > 0) this.tokens.push(...incoming);
+		const stableSegments = this.flushStable(result.final_audio_proc_ms);
+		this.trim();
+		return stableSegments;
+	}
+	/**
+	* Clear all buffered tokens.
+	*/
+	reset() {
+		this.tokens = [];
+	}
+	/**
+	* Flush all buffered tokens into segments and clear the buffer.
+	*
+	* Includes tokens that are not yet stable by final_audio_proc_ms.
+	*/
+	flushAll() {
+		if (this.tokens.length === 0) return [];
+		const segments = segmentRealtimeTokens(this.tokens, { group_by: this.groupBy });
+		this.tokens = [];
+		return segments;
+	}
+	flushStable(finalAudioProcMs) {
+		if (!Number.isFinite(finalAudioProcMs) || finalAudioProcMs <= 0) return [];
+		const segments = segmentRealtimeTokens(this.tokens, { group_by: this.groupBy });
+		const stableSegments = [];
+		let dropCount = 0;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			const endMs = segment.tokens[segment.tokens.length - 1]?.end_ms;
+			if (endMs === void 0 || endMs > finalAudioProcMs) break;
+			stableSegments.push(segment);
+			dropCount += segment.tokens.length;
+		}
+		if (dropCount > 0) this.tokens = this.tokens.slice(dropCount);
+		return stableSegments;
+	}
+	trim() {
+		if (this.maxTokens !== void 0 && this.tokens.length > this.maxTokens) this.tokens = this.tokens.slice(this.tokens.length - this.maxTokens);
+		if (this.maxMs === void 0) return;
+		const latestEndMs = findLatestEndMs(this.tokens);
+		if (latestEndMs === void 0) return;
+		const cutoff = latestEndMs - this.maxMs;
+		if (cutoff <= 0) return;
+		let dropIndex = 0;
+		while (dropIndex < this.tokens.length) {
+			const token = this.tokens[dropIndex];
+			if (token?.end_ms === void 0 || token.end_ms >= cutoff) break;
+			dropIndex += 1;
+		}
+		if (dropIndex > 0) this.tokens = this.tokens.slice(dropIndex);
+	}
+};
+function findLatestEndMs(tokens) {
+	for (let i = tokens.length - 1; i >= 0; i -= 1) {
+		const endMs = tokens[i]?.end_ms;
+		if (typeof endMs === "number") return endMs;
+	}
+}
+function validatePositive(name, value) {
+	if (value === void 0) return;
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a finite positive number`);
+}
+
+//#endregion
+//#region src/realtime/utterance-buffer.ts
+/**
+* Collects real-time results into utterances for endpoint-driven workflows.
+*/
+var RealtimeUtteranceBuffer = class {
+	segmentBuffer;
+	pendingSegments = [];
+	lastFinalAudioProcMs;
+	lastTotalAudioProcMs;
+	constructor(options = {}) {
+		this.segmentBuffer = new RealtimeSegmentBuffer(options);
+	}
+	/**
+	* Add a real-time result and collect stable segments.
+	*/
+	addResult(result) {
+		this.lastFinalAudioProcMs = result.final_audio_proc_ms;
+		this.lastTotalAudioProcMs = result.total_audio_proc_ms;
+		const stableSegments = this.segmentBuffer.add(result);
+		if (stableSegments.length > 0) this.pendingSegments.push(...stableSegments);
+		return stableSegments;
+	}
+	/**
+	* Mark an endpoint and flush the current utterance.
+	*/
+	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/realtime/index.ts
+/**
+* Real-time API factory for creating STT sessions.
+*
+* @example
+* ```typescript
+* const session = client.realtime.stt({
+*   model: 'stt-rt-preview',
+*   enable_endpoint_detection: true,
+* });
+*
+* await session.connect();
+* ```
+*/
+var SonioxRealtimeApi = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 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
+	*/
+	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);
+	}
+};
+
+//#endregion
+//#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',
+* });
+* ```
+*/
+var SonioxNodeClient = class {
+	files;
+	stt;
+	models;
+	webhooks;
+	auth;
+	realtime;
+	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 http = options.http_client ?? new FetchHttpClient({
+			base_url: baseURL,
+			default_headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json"
+			}
+		});
+		this.files = new SonioxFilesAPI(http);
+		this.stt = new SonioxSttApi(http, this.files);
+		this.models = new SonioxModelsAPI(http);
+		this.webhooks = new SonioxWebhooksAPI(this.stt);
+		this.auth = new SonioxAuthAPI(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,
+			default_session_options: options.realtime?.default_session_options
+		});
+	}
+};
+
+//#endregion
+export { AbortError, AuthError, BadRequestError, ConnectionError, FetchHttpClient, FileListResult, NetworkError, QuotaError, RealtimeError, RealtimeSegmentBuffer, RealtimeSttSession, RealtimeUtteranceBuffer, SONIOX_API_BASE_URL, SONIOX_API_WEBHOOK_HEADER_ENV, SONIOX_API_WEBHOOK_SECRET_ENV, SONIOX_API_WS_URL, SONIOX_TMP_API_KEY_DURATION_MAX, SONIOX_TMP_API_KEY_DURATION_MIN, SONIOX_TMP_API_KEY_USAGE_TYPE, SonioxError, SonioxFile, SonioxHttpError, SonioxNodeClient, SonioxRealtimeApi, SonioxTranscript, SonioxTranscription, StateError, TranscriptionListResult, buildUrl, createAbortError, createHttpError, createNetworkError, createParseError, createTimeoutError, isAbortError, isSonioxError, isSonioxHttpError, mergeHeaders, normalizeHeaders, segmentRealtimeTokens, segmentTranscript };
+//# sourceMappingURL=index.mjs.map