@soniox/node 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,3043 @@
+//#region src/constants.d.ts
+declare const SONIOX_API_BASE_URL = "https://api.soniox.com";
+declare const SONIOX_API_WS_URL = "wss://stt-rt.soniox.com/transcribe-websocket";
+declare const SONIOX_TMP_API_KEY_USAGE_TYPE = "transcribe_websocket";
+declare const SONIOX_TMP_API_KEY_DURATION_MIN = 1;
+declare const SONIOX_TMP_API_KEY_DURATION_MAX = 3600;
+declare const SONIOX_API_WEBHOOK_HEADER_ENV = "SONIOX_API_WEBHOOK_HEADER";
+declare const SONIOX_API_WEBHOOK_SECRET_ENV = "SONIOX_API_WEBHOOK_SECRET";
+//#endregion
+//#region src/types/public/errors.d.ts
+/**
+ * Unified error types for the Soniox SDK
+ *
+ * All SDK errors extend SonioxError, providing a consistent interface
+ * for error handling across both REST (HTTP) and WebSocket (Real-time) APIs.
+ */
+/**
+ * Error codes for HTTP client errors
+ */
+type HttpErrorCode = 'network_error' | 'timeout' | 'aborted' | 'http_error' | 'parse_error';
+/**
+ * Error codes for Real-time (WebSocket) API errors
+ */
+type RealtimeErrorCode = 'auth_error' | 'bad_request' | 'quota_exceeded' | 'connection_error' | 'network_error' | 'aborted' | 'state_error' | 'realtime_error';
+/**
+ * All possible SDK error codes
+ */
+type SonioxErrorCode = HttpErrorCode | RealtimeErrorCode | 'soniox_error';
+/**
+ * HTTP methods supported by the client
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+/**
+ * Error details for SonioxHttpError
+ */
+interface HttpErrorDetails {
+  code: HttpErrorCode;
+  message: string;
+  url: string;
+  method: HttpMethod;
+  statusCode?: number | undefined;
+  headers?: Record<string, string> | undefined;
+  /** Response body text (capped at 4KB) */
+  bodyText?: string | undefined;
+  cause?: unknown;
+}
+//#endregion
+//#region src/types/public/http.d.ts
+
+/**
+ * Response types
+ */
+type HttpResponseType = 'json' | 'text' | 'arrayBuffer';
+/**
+ * Request body types
+ */
+type HttpRequestBody = string | Record<string, unknown> | ArrayBuffer | Uint8Array | FormData | null;
+/**
+ * Query parameters
+ */
+type QueryParams = Record<string, string | number | boolean | undefined>;
+/**
+ * HTTP request configuration
+ */
+interface HttpRequest {
+  /** HTTP method */
+  method: HttpMethod;
+  /**
+   * URL path (relative to baseUrl) or absolute URL
+   */
+  path: string;
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** Query parameters (will be URL-encoded) */
+  query?: QueryParams;
+  /** Request body */
+  body?: HttpRequestBody;
+  /**
+   * Expected response type
+   * @default 'json'
+   */
+  responseType?: HttpResponseType;
+  /**
+   * Request timeout in milliseconds
+   * If not specified, uses the client's default timeout
+   */
+  timeoutMs?: number;
+  /**
+   * Optional AbortSignal for request cancellation
+   * If provided along with timeoutMs, both will be respected
+   */
+  signal?: AbortSignal;
+}
+/**
+ * HTTP response from the client
+ */
+interface HttpResponse<T> {
+  /** HTTP status code */
+  status: number;
+  /** Response headers (normalized to lowercase keys) */
+  headers: Record<string, string>;
+  /** Parsed response data */
+  data: T;
+}
+/**
+ * Metadata provided to observability hooks
+ */
+interface HttpRequestMeta {
+  /** Request start timestamp (Date.now()) */
+  startTime: number;
+  url: string;
+  method: HttpMethod;
+  headers: Record<string, string>;
+}
+/**
+ * Metadata provided to response/error hooks
+ */
+interface HttpResponseMeta extends HttpRequestMeta {
+  /** Request duration in milliseconds */
+  durationMs: number;
+  /** Response status code (if available) */
+  status?: number;
+}
+/**
+ * Observability hooks for monitoring HTTP requests
+ */
+interface HttpObservabilityHooks {
+  /**
+   * Called before a request is sent
+   */
+  onRequest?: (request: HttpRequest, meta: HttpRequestMeta) => void;
+  /**
+   * Called after a successful response is received
+   */
+  onResponse?: <T>(response: HttpResponse<T>, meta: HttpResponseMeta) => void;
+  /**
+   * Called when an error occurs
+   */
+  onError?: (error: Error, meta: HttpResponseMeta) => void;
+}
+/**
+ * Configuration options for the HTTP client
+ */
+interface HttpClientOptions {
+  /**
+   * Base URL for all requests
+   * @example 'https://api.soniox.com/v1'
+   */
+  base_url?: string;
+  /**
+   * Default headers to include in all requests
+   */
+  default_headers?: Record<string, string>;
+  /**
+   * Default timeout in milliseconds
+   * @default 30000 (30 seconds)
+   */
+  default_timeout_ms?: number;
+  /**
+   * Observability hooks for monitoring requests
+   */
+  hooks?: HttpObservabilityHooks;
+  /**
+   * Custom fetch implementation
+   * Defaults to global fetch
+   */
+  fetch?: typeof fetch;
+}
+/**
+ * Pluggable HTTP client interface
+ */
+interface HttpClient {
+  /**
+   * Perform an HTTP request
+   *
+   * @param request - Request configuration
+   * @returns Promise resolving to the response
+   * @throws {SonioxHttpError} On network errors, timeouts, HTTP errors, or parse errors
+   */
+  request<T>(request: HttpRequest): Promise<HttpResponse<T>>;
+}
+//#endregion
+//#region src/types/public/files.d.ts
+/**
+ * Raw file metadata from the API.
+ */
+type SonioxFileData = {
+  /**
+   * Unique identifier of the file.
+   * @format uuid
+   */
+  id: string;
+  /**
+   * Name of the file.
+   */
+  filename: string;
+  /**
+   * Size of the file in bytes.
+   */
+  size: number;
+  /**
+   * UTC timestamp indicating when the file was uploaded.
+   * @format date-time
+   */
+  created_at: string;
+  /**
+   * Optional tracking identifier string.
+   */
+  client_reference_id?: string | null | undefined;
+};
+/**
+ * Options for listing files.
+ */
+type ListFilesOptions = {
+  /**
+   * Maximum number of files to return.
+   * @default 1000
+   * @minimum 1
+   * @maximum 1000
+   */
+  limit?: number | undefined;
+  /**
+   * Pagination cursor for the next page of results.
+   */
+  cursor?: string | undefined;
+  /**
+   * AbortSignal for cancelling the request
+   */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Response from listing files.
+ */
+type ListFilesResponse<T> = {
+  /**
+   * List of uploaded files.
+   */
+  files: T[];
+  /**
+   * A pagination token that references the next page of results.
+   * When null, no additional results are available.
+   */
+  next_page_cursor: string | null;
+};
+/**
+ * File identifier - either a string ID or an object with an id property.
+ */
+type FileIdentifier = string | {
+  readonly id: string;
+};
+/**
+ * Supported input types for file upload
+ */
+type UploadFileInput = Buffer | Uint8Array | Blob | ReadableStream<Uint8Array> | NodeJS.ReadableStream;
+/**
+ * Options for uploading a file
+ */
+type UploadFileOptions = {
+  /**
+   * Custom filename for the uploaded file
+   */
+  filename?: string | undefined;
+  /**
+   * Optional tracking identifier string. Does not need to be unique
+   * @maxLength 256
+   */
+  client_reference_id?: string | undefined;
+  /**
+   * AbortSignal for cancelling the upload
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Request timeout in milliseconds
+   */
+  timeout_ms?: number | undefined;
+};
+/**
+ * Options for purging all files.
+ */
+type PurgeFilesOptions = {
+  /**
+   * AbortSignal for cancelling the purge operation.
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Callback invoked before each file is deleted.
+   * Receives the file data and its 0-based index.
+   */
+  on_progress?: ((file: SonioxFileData, index: number) => void) | undefined;
+};
+//#endregion
+//#region src/types/public/transcriptions.d.ts
+/**
+ * Status of a transcription request.
+ */
+type TranscriptionStatus = 'queued' | 'processing' | 'completed' | 'error';
+/**
+ * Resource types that can be cleaned up after transcription completes.
+ *
+ * - `'file'` - The uploaded file
+ * - `'transcription'` - The transcription record
+ */
+type CleanupTarget = 'file' | 'transcription';
+/**
+ * Key-value pair for general context information.
+ */
+type ContextGeneralEntry = {
+  /**
+   * The key describing the context type (e.g., "domain", "topic", "doctor").
+   */
+  key: string;
+  /**
+   * The value for the context key.
+   */
+  value: string;
+};
+/**
+ * Custom translation term mapping.
+ */
+type ContextTranslationTerm = {
+  /**
+   * The source term to translate.
+   */
+  source: string;
+  /**
+   * The target translation for the term.
+   */
+  target: string;
+};
+/**
+ * Additional context to improve transcription and translation accuracy.
+ * All sections are optional - include only what's relevant for your use case.
+ */
+type TranscriptionContext = {
+  /**
+   * Structured key-value pairs describing domain, topic, intent, participant names, etc.
+   */
+  general?: ContextGeneralEntry[] | undefined;
+  /**
+   * Longer free-form background text, prior interaction history, reference documents, or meeting notes.
+   */
+  text?: string | undefined;
+  /**
+   * Domain-specific or uncommon words to recognize.
+   */
+  terms?: string[] | undefined;
+  /**
+   * Custom translations for ambiguous terms.
+   */
+  translation_terms?: ContextTranslationTerm[] | undefined;
+};
+/**
+ * One-way translation configuration.
+ * Translates all spoken languages into a single target language.
+ */
+type OneWayTranslationConfig = {
+  /**
+   * Translation type.
+   */
+  type: 'one_way';
+  /**
+   * Target language code for translation (e.g., "fr", "es", "de").
+   */
+  target_language: string;
+};
+/**
+ * Two-way translation configuration.
+ * Translates between two specified languages.
+ */
+type TwoWayTranslationConfig = {
+  /**
+   * Translation type.
+   */
+  type: 'two_way';
+  /**
+   * First language code.
+   */
+  language_a: string;
+  /**
+   * Second language code.
+   */
+  language_b: string;
+};
+/**
+ * Translation configuration.
+ */
+type TranslationConfig = OneWayTranslationConfig | TwoWayTranslationConfig;
+/**
+ * Raw transcription metadata from the API.
+ */
+type SonioxTranscriptionData = {
+  /**
+   * Unique identifier of the transcription.
+   * @format uuid
+   */
+  id: string;
+  /**
+   * Current status of the transcription.
+   */
+  status: TranscriptionStatus;
+  /**
+   * UTC timestamp when the transcription was created.
+   * @format date-time
+   */
+  created_at: string;
+  /**
+   * Speech-to-text model used.
+   */
+  model: string;
+  /**
+   * URL of the audio file being transcribed.
+   */
+  audio_url?: string | null | undefined;
+  /**
+   * ID of the uploaded file being transcribed.
+   * @format uuid
+   */
+  file_id?: string | null | undefined;
+  /**
+   * Name of the file being transcribed.
+   */
+  filename: string;
+  /**
+   * Expected languages in the audio. If not specified, languages are automatically detected.
+   */
+  language_hints?: string[] | null | undefined;
+  /**
+   * When true, speakers are identified and separated in the transcription output.
+   */
+  enable_speaker_diarization: boolean;
+  /**
+   * When true, language is detected for each part of the transcription.
+   */
+  enable_language_identification: boolean;
+  /**
+   * Duration of the audio in milliseconds. Only available after processing begins.
+   */
+  audio_duration_ms?: number | null | undefined;
+  /**
+   * Error type if transcription failed. Null for successful or in-progress transcriptions.
+   */
+  error_type?: string | null | undefined;
+  /**
+   * Error message if transcription failed. Null for successful or in-progress transcriptions.
+   */
+  error_message?: string | null | undefined;
+  /**
+   * URL to receive webhook notifications when transcription is completed or fails.
+   */
+  webhook_url?: string | null | undefined;
+  /**
+   * Name of the authentication header sent with webhook notifications.
+   */
+  webhook_auth_header_name?: string | null | undefined;
+  /**
+   * Authentication header value. Always returned masked.
+   */
+  webhook_auth_header_value?: string | null | undefined;
+  /**
+   * HTTP status code received from your server when webhook was delivered. Null if not yet sent.
+   */
+  webhook_status_code?: number | null | undefined;
+  /**
+   * Optional tracking identifier.
+   * @maxLength 256
+   */
+  client_reference_id?: string | null | undefined;
+  /**
+   * Additional context provided for the transcription.
+   */
+  context?: TranscriptionContext | null | undefined;
+};
+/**
+ * Options for creating a transcription.
+ */
+type CreateTranscriptionOptions = {
+  /**
+   * Speech-to-text model to use.
+   * @maxLength 32
+   */
+  model: string;
+  /**
+   * URL of a publicly accessible audio file.
+   * @maxLength 4096
+   */
+  audio_url?: string | undefined;
+  /**
+   * ID of a previously uploaded file.
+   * @format uuid
+   */
+  file_id?: string | undefined;
+  /**
+   * Array of expected ISO language codes to bias recognition.
+   */
+  language_hints?: string[] | undefined;
+  /**
+   * When true, model relies more heavily on language hints.
+   */
+  language_hints_strict?: boolean | undefined;
+  /**
+   * Enable automatic language identification.
+   */
+  enable_language_identification?: boolean | undefined;
+  /**
+   * Enable speaker diarization to identify different speakers.
+   */
+  enable_speaker_diarization?: boolean | undefined;
+  /**
+   * Additional context to improve transcription accuracy and formatting of specialized terms.
+   */
+  context?: TranscriptionContext | undefined;
+  /**
+   * Translation configuration.
+   */
+  translation?: TranslationConfig | undefined;
+  /**
+   * URL to receive webhook notifications when transcription is completed or fails.
+   * @maxLength 256
+   */
+  webhook_url?: string | undefined;
+  /**
+   * Name of the authentication header sent with webhook notifications.
+   * @maxLength 256
+   */
+  webhook_auth_header_name?: string | undefined;
+  /**
+   * Authentication header value sent with webhook notifications.
+   * @maxLength 256
+   */
+  webhook_auth_header_value?: string | undefined;
+  /**
+   * Optional tracking identifier.
+   * @maxLength 256
+   */
+  client_reference_id?: string | undefined;
+};
+/**
+ * Options for polling/waiting for transcription completion.
+ */
+type WaitOptions = {
+  /**
+   * Polling interval in milliseconds.
+   * @default 1000
+   * @minimum 1000
+   */
+  interval_ms?: number | undefined;
+  /**
+   * Maximum time to wait in milliseconds.
+   * @default 300000 (5 minutes)
+   */
+  timeout_ms?: number | undefined;
+  /**
+   * Callback invoked when status changes.
+   */
+  on_status_change?: ((status: TranscriptionStatus, transcription: SonioxTranscriptionData) => void) | undefined;
+  /**
+   * AbortSignal to cancel waiting.
+   */
+  signal?: AbortSignal | undefined;
+};
+/**
+ * Base options shared by all audio source variants.
+ */
+type TranscribeBaseOptions = {
+  /**
+   * Speech-to-text model to use.
+   * @maxLength 32
+   */
+  model: string;
+  /**
+   * Array of expected ISO language codes to bias recognition.
+   */
+  language_hints?: string[] | undefined;
+  /**
+   * When true, model relies more heavily on language hints.
+   */
+  language_hints_strict?: boolean | undefined;
+  /**
+   * Enable automatic language identification.
+   */
+  enable_language_identification?: boolean | undefined;
+  /**
+   * Enable speaker diarization to identify different speakers.
+   */
+  enable_speaker_diarization?: boolean | undefined;
+  /**
+   * Additional context to improve transcription accuracy and formatting of specialized terms.
+   */
+  context?: TranscriptionContext | undefined;
+  /**
+   * Translation configuration.
+   */
+  translation?: TranslationConfig | undefined;
+  /**
+   * URL to receive webhook notifications when transcription is completed or fails.
+   * @maxLength 256
+   */
+  webhook_url?: string | undefined;
+  /**
+   * Name of the authentication header sent with webhook notifications.
+   * @maxLength 256
+   */
+  webhook_auth_header_name?: string | undefined;
+  /**
+   * Authentication header value sent with webhook notifications.
+   * @maxLength 256
+   */
+  webhook_auth_header_value?: string | undefined;
+  /**
+   * Optional tracking identifier.
+   * @maxLength 256
+   */
+  client_reference_id?: string | undefined;
+  /**
+   * When true, waits for transcription to complete before returning.
+   * @default false
+   */
+  wait?: boolean | undefined;
+  /**
+   * Options for waiting (only used when wait=true).
+   */
+  wait_options?: WaitOptions | undefined;
+  /**
+   * When true (default), fetches the transcript and attaches it to the result
+   * when wait=true and the transcription completes successfully.
+   * Set to false to skip fetching the full transcript payload.
+   * @default true
+   */
+  fetch_transcript?: boolean | undefined;
+  /**
+   * Query parameters to append to the webhook URL.
+   * Useful for encoding metadata like transcription ID in the webhook callback.
+   * Can be a string, URLSearchParams, or Record<string, string>.
+   */
+  webhook_query?: string | URLSearchParams | Record<string, string> | undefined;
+  /**
+   * AbortSignal to cancel the operation
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Timeout in milliseconds
+   */
+  timeout_ms?: number | undefined;
+  /**
+   * Resources to clean up after transcription completes or on error/timeout.
+   * Only applies when `wait: true`.
+   *
+   * Cleanup runs in all cases when `wait: true`:
+   * - After successful completion
+   * - After transcription errors (status: 'error')
+   * - On timeout or abort
+   *
+   * This ensures no orphaned resources are left behind.
+   *
+   * @example
+   * ```typescript
+   * // Delete only the uploaded file
+   * cleanup: ['file']
+   *
+   * // Delete only the transcription record
+   * cleanup: ['transcription']
+   *
+   * // Delete both file and transcription
+   * cleanup: ['file', 'transcription']
+   * ```
+   */
+  cleanup?: CleanupTarget[] | undefined;
+};
+/**
+ * Transcribe from a direct file upload (Buffer, Uint8Array, Blob, or ReadableStream)
+ */
+type TranscribeFromFile = TranscribeBaseOptions & {
+  /**
+   * File data to upload and transcribe.
+   */
+  file: UploadFileInput;
+  filename?: string | undefined;
+  file_id?: never;
+  audio_url?: never;
+};
+/**
+ * Transcribe from a previously uploaded file
+ */
+type TranscribeFromFileId = TranscribeBaseOptions & {
+  /**
+   * ID of a previously uploaded file.
+   * @format uuid
+   */
+  file_id: string;
+  file?: never;
+  filename?: never;
+  audio_url?: never;
+};
+/**
+ * Transcribe from a publicly accessible audio URL
+ */
+type TranscribeFromUrl = TranscribeBaseOptions & {
+  /**
+   * URL of a publicly accessible audio file.
+   * @maxLength 4096
+   */
+  audio_url: string;
+  file?: never;
+  filename?: never;
+  file_id?: never;
+};
+/**
+ * Options for the unified transcribe method
+ * Exactly one audio source must be provided: `file`, `file_id`, or `audio_url`
+ */
+type TranscribeOptions = TranscribeFromFile | TranscribeFromFileId | TranscribeFromUrl;
+/**
+ * Options for transcribing from a URL via `transcribeFromUrl`.
+ */
+type TranscribeFromUrlOptions = Omit<TranscribeFromUrl, 'audio_url'>;
+/**
+ * Options for transcribing from a file via `transcribeFromFile`.
+ */
+type TranscribeFromFileOptions = Omit<TranscribeFromFile, 'file'>;
+/**
+ * Options for transcribing from an uploaded file ID via `transcribeFromFileId`.
+ */
+type TranscribeFromFileIdOptions = Omit<TranscribeFromFileId, 'file_id'>;
+/**
+ * Options for listing transcriptions
+ */
+type ListTranscriptionsOptions = {
+  /**
+   * Maximum number of transcriptions to return.
+   * @default 1000
+   * @minimum 1
+   * @maximum 1000
+   */
+  limit?: number | undefined;
+  /**
+   * Pagination cursor for the next page of results
+   */
+  cursor?: string | undefined;
+};
+/**
+ * Response from listing transcriptions.
+ */
+type ListTranscriptionsResponse<T> = {
+  /**
+   * List of transcriptions.
+   */
+  transcriptions: T[];
+  /**
+   * A pagination token that references the next page of results.
+   * When null, no additional results are available.
+   * TODO: potentially can be undefined?
+   */
+  next_page_cursor: string | null;
+};
+/**
+ * Transcription identifier - either a string ID or an object with an id property.
+ */
+type TranscriptionIdentifier = string | {
+  readonly id: string;
+};
+/**
+ * A single token from the transcript with timing and confidence information.
+ */
+type TranscriptToken = {
+  /**
+   * The text content of this token.
+   */
+  text: string;
+  /**
+   * Start time of the token in milliseconds.
+   */
+  start_ms: number;
+  /**
+   * End time of the token in milliseconds.
+   */
+  end_ms: number;
+  /**
+   * Confidence score for this token (0.0 to 1.0).
+   */
+  confidence: number;
+  /**
+   * Speaker identifier (if speaker diarization was enabled).
+   */
+  speaker?: string | null | undefined;
+  /**
+   * Detected language code (if language identification was enabled).
+   */
+  language?: string | null | undefined;
+  /**
+   * Translation status for this token.
+   */
+  translation_status?: 'none' | 'original' | 'translation' | null | undefined;
+  /**
+   * Whether this token represents an audio event.
+   */
+  is_audio_event?: boolean | null | undefined;
+};
+/**
+ * Response from getting a transcription transcript.
+ */
+type TranscriptResponse = {
+  /**
+   * Unique identifier of the transcription this transcript belongs to.
+   * @format uuid
+   */
+  id: string;
+  /**
+   * Complete transcribed text content.
+   */
+  text: string;
+  /**
+   * List of detailed token information with timestamps and metadata.
+   */
+  tokens: TranscriptToken[];
+};
+/**
+ * Fields that can be used to group tokens into segments
+ */
+type SegmentGroupKey = 'speaker' | 'language';
+/**
+ * Options for segmenting a transcript
+ */
+type SegmentTranscriptOptions = {
+  /**
+   * Fields to group by. A new segment starts when any of these fields changes
+   * @default ['speaker', 'language']
+   */
+  group_by?: SegmentGroupKey[] | undefined;
+};
+/**
+ * A segment of contiguous tokens grouped by speaker and language
+ */
+type TranscriptSegment = {
+  /**
+   * Concatenated text of all tokens in this segment.
+   */
+  text: string;
+  /**
+   * Start time of the segment in milliseconds (from first token).
+   */
+  start_ms: number;
+  /**
+   * End time of the segment in milliseconds (from last token).
+   */
+  end_ms: number;
+  /**
+   * Speaker identifier (if speaker diarization was enabled).
+   */
+  speaker?: string | undefined;
+  /**
+   * Detected language code (if language identification was enabled).
+   */
+  language?: string | undefined;
+  /**
+   * Original tokens in this segment.
+   */
+  tokens: TranscriptToken[];
+};
+/**
+ * Options for purging all transcriptions.
+ */
+type PurgeTranscriptionsOptions = {
+  /**
+   * AbortSignal for cancelling the purge operation.
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Callback invoked before each transcription is deleted.
+   * Receives the transcription data and its 0-based index.
+   */
+  on_progress?: ((transcription: SonioxTranscriptionData, index: number) => void) | undefined;
+};
+/**
+ * Type contract for SonioxTranscript class.
+ * @see SonioxTranscript for full documentation.
+ */
+interface ISonioxTranscript {
+  readonly id: string;
+  readonly text: string;
+  readonly tokens: TranscriptToken[];
+  segments(options?: SegmentTranscriptOptions): TranscriptSegment[];
+}
+/**
+ * Type contract for SonioxTranscription class.
+ * @see SonioxTranscription for full documentation.
+ */
+interface ISonioxTranscription {
+  readonly id: string;
+  readonly status: TranscriptionStatus;
+  readonly created_at: string;
+  readonly model: string;
+  readonly audio_url: string | null | undefined;
+  readonly file_id: string | null | undefined;
+  readonly filename: string;
+  readonly language_hints: string[] | undefined;
+  readonly enable_speaker_diarization: boolean;
+  readonly enable_language_identification: boolean;
+  readonly audio_duration_ms: number | null | undefined;
+  readonly error_type: string | null | undefined;
+  readonly error_message: string | null | undefined;
+  readonly webhook_url: string | null | undefined;
+  readonly webhook_auth_header_name: string | null | undefined;
+  readonly webhook_auth_header_value: string | null | undefined;
+  readonly webhook_status_code: number | null | undefined;
+  readonly client_reference_id: string | null | undefined;
+  readonly context: TranscriptionContext | string | null | undefined;
+  readonly transcript: ISonioxTranscript | null | undefined;
+  toJSON(): SonioxTranscriptionData;
+  delete(): Promise<void>;
+  destroy(): Promise<void>;
+  getTranscript(options?: {
+    force?: boolean;
+    signal?: AbortSignal;
+  }): Promise<ISonioxTranscript | null>;
+  refresh(signal?: AbortSignal): Promise<ISonioxTranscription>;
+  wait(options?: WaitOptions): Promise<ISonioxTranscription>;
+}
+//#endregion
+//#region src/types/public/realtime.d.ts
+/**
+ * Supported audio formats for real-time transcription.
+ */
+type AudioFormat = 'pcm_s8' | 'pcm_s8le' | 'pcm_s8be' | 'pcm_s16le' | 'pcm_s16be' | 'pcm_s24le' | 'pcm_s24be' | 'pcm_s32le' | 'pcm_s32be' | 'pcm_u8' | 'pcm_u8le' | 'pcm_u8be' | 'pcm_u16le' | 'pcm_u16be' | 'pcm_u24le' | 'pcm_u24be' | 'pcm_u32le' | 'pcm_u32be' | 'pcm_f32le' | 'pcm_f32be' | 'pcm_f64le' | 'pcm_f64be' | 'mulaw' | 'alaw' | 'aac' | 'aiff' | 'amr' | 'asf' | 'wav' | 'mp3' | 'flac' | 'ogg' | 'webm';
+/**
+ * Configuration sent to the Soniox WebSocket API when starting a session.
+ */
+type SttSessionConfig = {
+  /**
+   * Speech-to-text model to use.
+   */
+  model: string;
+  /**
+   * Audio format. Use 'auto' for automatic detection of container formats.
+   * For raw PCM formats, also set sample_rate and num_channels.
+   * @default 'auto'
+   */
+  audio_format?: 'auto' | AudioFormat | undefined;
+  /**
+   * Sample rate in Hz (required for PCM formats).
+   */
+  sample_rate?: number | undefined;
+  /**
+   * Number of audio channels (required for raw audio formats).
+   */
+  num_channels?: number | undefined;
+  /**
+   * Expected languages in the audio (ISO language codes).
+   */
+  language_hints?: string[] | undefined;
+  /**
+   * When true, recognition is strongly biased toward language hints.
+   * Best-effort only, not a hard guarantee.
+   */
+  language_hints_strict?: boolean | undefined;
+  /**
+   * Enable speaker identification.
+   */
+  enable_speaker_diarization?: boolean | undefined;
+  /**
+   * Enable automatic language detection.
+   */
+  enable_language_identification?: boolean | undefined;
+  /**
+   * Enable endpoint detection for utterance boundaries.
+   * Useful for voice AI agents.
+   */
+  enable_endpoint_detection?: boolean | undefined;
+  /**
+   * Optional tracking identifier (max 256 chars).
+   */
+  client_reference_id?: string | undefined;
+  /**
+   * Additional context to improve transcription accuracy.
+   */
+  context?: TranscriptionContext | undefined;
+  /**
+   * Translation configuration.
+   */
+  translation?: TranslationConfig | undefined;
+};
+/**
+ * SDK-level session options (not sent to the server).
+ */
+type SttSessionOptions = {
+  /**
+   * AbortSignal for cancellation.
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * When true, sends keepalive messages while connected (not only when paused).
+   * @default false
+   */
+  keepalive?: boolean | undefined;
+  /**
+   * Interval for sending keepalive messages while connected or paused (milliseconds).
+   * @default 5000
+   */
+  keepalive_interval_ms?: number | undefined;
+};
+/**
+ * A single token from the real-time transcription.
+ */
+type RealtimeToken = {
+  /**
+   * The transcribed text.
+   */
+  text: string;
+  /**
+   * Start time in milliseconds relative to audio start.
+   */
+  start_ms?: number | undefined;
+  /**
+   * End time in milliseconds relative to audio start.
+   */
+  end_ms?: number | undefined;
+  /**
+   * Confidence score (0.0 to 1.0).
+   */
+  confidence: number;
+  /**
+   * Whether this is a finalized token.
+   */
+  is_final: boolean;
+  /**
+   * Speaker identifier (if diarization enabled).
+   */
+  speaker?: string | undefined;
+  /**
+   * Detected language code (if language identification enabled).
+   */
+  language?: string | undefined;
+  /**
+   * Translation status of this token.
+   */
+  translation_status?: 'none' | 'original' | 'translation' | undefined;
+  /**
+   * Source language for translated tokens.
+   */
+  source_language?: string | undefined;
+};
+/**
+ * A segment of contiguous real-time tokens grouped by speaker/language.
+ */
+type RealtimeSegment = {
+  /**
+   * Concatenated text of all tokens in this segment.
+   */
+  text: string;
+  /**
+   * Start time of the segment in milliseconds (from first token).
+   */
+  start_ms?: number | undefined;
+  /**
+   * End time of the segment in milliseconds (from last token).
+   */
+  end_ms?: number | undefined;
+  /**
+   * Speaker identifier (if diarization enabled).
+   */
+  speaker?: string | undefined;
+  /**
+   * Detected language code (if language identification enabled).
+   */
+  language?: string | undefined;
+  /**
+   * Original tokens in this segment.
+   */
+  tokens: RealtimeToken[];
+};
+/**
+ * Options for segmenting real-time tokens.
+ */
+type RealtimeSegmentOptions = {
+  /**
+   * Fields to group by. A new segment starts when any of these fields changes
+   * @default ['speaker', 'language']
+   */
+  group_by?: SegmentGroupKey[] | undefined;
+  /**
+   * When true, only tokens marked as final are included.
+   * @default false
+   */
+  final_only?: boolean | undefined;
+};
+/**
+ * Options for rolling real-time segmentation buffers.
+ */
+type RealtimeSegmentBufferOptions = {
+  /**
+   * Fields to group by. A new segment starts when any of these fields changes
+   * @default ['speaker', 'language']
+   */
+  group_by?: SegmentGroupKey[] | undefined;
+  /**
+   * When true, only tokens marked as final are buffered.
+   * @default true
+   */
+  final_only?: boolean | undefined;
+  /**
+   * Maximum number of tokens to keep in the buffer.
+   * @default 2000
+   */
+  max_tokens?: number | undefined;
+  /**
+   * Maximum time window to keep in milliseconds (requires token timings).
+   */
+  max_ms?: number | undefined;
+};
+/**
+ * A single utterance built from real-time segments.
+ */
+type RealtimeUtterance = {
+  /**
+   * Concatenated text of all segments in this utterance.
+   */
+  text: string;
+  /**
+   * Segments included in this utterance.
+   */
+  segments: RealtimeSegment[];
+  /**
+   * Tokens included in this utterance.
+   */
+  tokens: RealtimeToken[];
+  /**
+   * Start time of the utterance in milliseconds (from first segment).
+   */
+  start_ms?: number | undefined;
+  /**
+   * End time of the utterance in milliseconds (from last segment).
+   */
+  end_ms?: number | undefined;
+  /**
+   * Speaker identifier when consistent across segments.
+   */
+  speaker?: string | undefined;
+  /**
+   * Detected language code when consistent across segments.
+   */
+  language?: string | undefined;
+  /**
+   * Milliseconds of audio that have been finalized at flush time.
+   */
+  final_audio_proc_ms?: number | undefined;
+  /**
+   * Total milliseconds of audio processed at flush time.
+   */
+  total_audio_proc_ms?: number | undefined;
+};
+/**
+ * Options for buffering real-time utterances.
+ */
+type RealtimeUtteranceBufferOptions = {
+  /**
+   * Fields to group by. A new segment starts when any of these fields changes
+   * @default ['speaker', 'language']
+   */
+  group_by?: SegmentGroupKey[] | undefined;
+  /**
+   * When true, only tokens marked as final are buffered.
+   * @default true
+   */
+  final_only?: boolean | undefined;
+  /**
+   * Maximum number of tokens to keep in the buffer.
+   * @default 2000
+   */
+  max_tokens?: number | undefined;
+  /**
+   * Maximum time window to keep in milliseconds (requires token timings).
+   */
+  max_ms?: number | undefined;
+};
+/**
+ * A result message from the real-time WebSocket.
+ */
+type RealtimeResult = {
+  /**
+   * Tokens in this result.
+   */
+  tokens: RealtimeToken[];
+  /**
+   * Milliseconds of audio that have been finalized.
+   */
+  final_audio_proc_ms: number;
+  /**
+   * Total milliseconds of audio processed.
+   */
+  total_audio_proc_ms: number;
+  /**
+   * Whether this is the final result (session ending).
+   */
+  finished?: boolean | undefined;
+};
+/**
+ * Typed event for async iterator consumption.
+ */
+type RealtimeEvent = {
+  kind: 'result';
+  data: RealtimeResult;
+} | {
+  kind: 'endpoint';
+} | {
+  kind: 'finalized';
+} | {
+  kind: 'finished';
+};
+/**
+ * Session lifecycle states.
+ */
+type SttSessionState = 'idle' | 'connecting' | 'connected' | 'finishing' | 'finished' | 'canceled' | 'closed' | 'error';
+/**
+ * Event handlers for the STT session.
+ */
+type SttSessionEvents = {
+  /**
+   * Parsed result received.
+   */
+  result: (result: RealtimeResult) => void;
+  /**
+   * Individual token received.
+   */
+  token: (token: RealtimeToken) => void;
+  /**
+   * Error occurred.
+   */
+  error: (error: Error) => void;
+  /**
+   * Endpoint detected (<end> token).
+   */
+  endpoint: () => void;
+  /**
+   * Finalization complete (<fin> token).
+   */
+  finalized: () => void;
+  /**
+   * Session finished (server signaled end of stream).
+   */
+  finished: () => void;
+  /**
+   * Session connected and ready.
+   */
+  connected: () => void;
+  /**
+   * Session disconnected.
+   */
+  disconnected: (reason?: string) => void;
+  /**
+   * Session state transition.
+   */
+  state_change: (update: {
+    old_state: SttSessionState;
+    new_state: SttSessionState;
+  }) => void;
+};
+/**
+ * Audio data types accepted by sendAudio.
+ */
+type AudioData = Buffer | Uint8Array | ArrayBuffer;
+/**
+ * Options for streaming audio from an async iterable source.
+ */
+type SendStreamOptions = {
+  /**
+   * Delay in milliseconds between sending chunks.
+   * Useful for simulating real-time pace when streaming pre-recorded files.
+   * Not needed for live audio sources.
+   */
+  pace_ms?: number | undefined;
+  /**
+   * When true, calls finish() automatically after the stream ends.
+   * @default false
+   */
+  finish?: boolean | undefined;
+};
+/**
+ * Real-time API configuration options for the client.
+ */
+type RealtimeClientOptions = {
+  /**
+   * API key for real-time sessions.
+   */
+  api_key: string;
+  /**
+   * WebSocket base URL for real-time connections.
+   * @default 'wss://stt-rt.soniox.com/transcribe-websocket'
+   */
+  ws_base_url: string;
+  /**
+   * Default session options applied to all real-time sessions.
+   * Can be overridden per-session.
+   */
+  default_session_options?: SttSessionOptions | undefined;
+};
+//#endregion
+//#region src/types/public/models.d.ts
+/**
+ * Transcription mode of the model.
+ */
+type SonioxTranscriptionMode = 'real_time' | 'async';
+type SonioxLanguage = {
+  /**
+   * 2-letter language code.
+   */
+  code: string;
+  /**
+   * Language name.
+   */
+  name: string;
+};
+type SonioxTranslationTarget = {
+  target_language: string;
+  source_languages: string[];
+  exclude_source_languages: string[];
+};
+type SonioxModel = {
+  /**
+   * Unique identifier of the model.
+   */
+  id: string;
+  /**
+   * If this is an alias, the id of the aliased model. Null for non-alias models.
+   */
+  aliased_model_id: string | null;
+  /**
+   * Name of the model.
+   */
+  name: string;
+  /**
+   * Version of context supported.
+   */
+  context_version: number | null;
+  /**
+   * Transcription mode of the model.
+   */
+  transcription_mode: SonioxTranscriptionMode;
+  /**
+   * List of languages supported by the model.
+   */
+  languages: SonioxLanguage[];
+  /**
+   * TODO: Add documentation
+   */
+  supports_language_hints_strict: boolean;
+  /**
+   * List of supported one-way translation targets. If list is empty, check for one_way_translation field
+   */
+  translation_targets: SonioxTranslationTarget[];
+  /**
+   * List of supported two-way translation pairs. If list is empty, check for two_way_translation field
+   */
+  two_way_translation_pairs: string[];
+  /**
+   * When contains string 'all_languages', any laguage from languages can be used
+   */
+  one_way_translation: string | null;
+  /**
+   * When contains string 'all_languages',' any laguage pair from languages can be used
+   */
+  two_way_translation: string | null;
+  supports_max_endpoint_delay: boolean;
+};
+//#endregion
+//#region src/types/public/webhooks.d.ts
+/**
+ * Webhook event status values
+ */
+type WebhookEventStatus = 'completed' | 'error';
+/**
+ * Webhook event payload sent by Soniox when a transcription completes or fails.
+ */
+type WebhookEvent = {
+  /**
+   * Transcription ID
+   * @format uuid
+   */
+  id: string;
+  /**
+   * Transcription result status
+   */
+  status: WebhookEventStatus;
+};
+/**
+ * Authentication configuration for webhook verification
+ */
+type WebhookAuthConfig = {
+  /**
+   * Expected header name (case-insensitive comparison)
+   */
+  name: string;
+  /**
+   * Expected header value (exact match)
+   */
+  value: string;
+};
+/**
+ * Headers object type - supports both standard headers and record types
+ */
+type WebhookHeaders = Headers | Record<string, string | string[] | undefined> | {
+  get(name: string): string | null;
+};
+/**
+ * Result of webhook handling
+ */
+type WebhookHandlerResult = {
+  /**
+   * Whether the webhook was handled successfully
+   */
+  ok: boolean;
+  /**
+   * HTTP status code to return
+   */
+  status: number;
+  /**
+   * Parsed webhook event (only present when ok=true)
+   */
+  event?: WebhookEvent;
+  /**
+   * Error message (only present when ok=false)
+   */
+  error?: string;
+};
+/**
+ * Result of webhook handling with lazy fetch capabilities.
+ *
+ * When using `client.webhooks.handleExpress()` (or other framework handlers),
+ * the result includes helper methods to fetch the transcript or transcription.
+ */
+type WebhookHandlerResultWithFetch = WebhookHandlerResult & {
+  /**
+   * Fetch the transcript for a completed transcription.
+   * Only available when `ok=true` and `event.status='completed'`.
+   *
+   * @returns The transcript with text and tokens, or null if not found
+   *
+   * @example
+   * ```typescript
+   * const result = soniox.webhooks.handleExpress(req);
+   * if (result.ok && result.event.status === 'completed') {
+   *     const transcript = await result.fetchTranscript();
+   *     console.log(transcript?.text);
+   * }
+   * ```
+   */
+  fetchTranscript: (() => Promise<ISonioxTranscript | null>) | undefined;
+  /**
+   * Fetch the full transcription object.
+   * Useful for both completed (metadata) and error (error details) statuses.
+   *
+   * @returns The transcription object, or null if not found
+   *
+   * @example
+   * ```typescript
+   * const result = soniox.webhooks.handleExpress(req);
+   * if (result.ok && result.event.status === 'error') {
+   *     const transcription = await result.fetchTranscription();
+   *     console.log(transcription?.error_message);
+   * }
+   * ```
+   */
+  fetchTranscription: (() => Promise<ISonioxTranscription | null>) | undefined;
+};
+/**
+ * Options for the handleWebhook function
+ */
+type HandleWebhookOptions = {
+  /**
+   * HTTP method of the request
+   */
+  method: string;
+  /**
+   * Request headers
+   */
+  headers: WebhookHeaders;
+  /**
+   * Request body (parsed JSON or raw string)
+   */
+  body: unknown;
+  /**
+   * Optional authentication configuration
+   */
+  auth?: WebhookAuthConfig;
+};
+/**
+ * Express/Connect-style request object
+ */
+type ExpressLikeRequest = {
+  method: string;
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;
+};
+/**
+ * Fastify-style request object
+ */
+type FastifyLikeRequest = {
+  method: string;
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;
+};
+/**
+ * NestJS-style request object (uses Express under the hood by default)
+ */
+type NestJSLikeRequest = {
+  method: string;
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;
+};
+/**
+ * Hono context object
+ */
+type HonoLikeContext = {
+  req: {
+    method: string;
+    header(name: string): string | undefined;
+    json(): Promise<unknown>;
+  };
+};
+//#endregion
+//#region src/types/public/index.d.ts
+/**
+ * Result of a purge operation.
+ */
+type PurgeResult = {
+  /**
+   * Number of resources deleted.
+   */
+  deleted: number;
+};
+type TemporaryApiKeyUsageType = 'transcribe_websocket';
+type TemporaryApiKeyRequest = {
+  /**
+   * Intended usage of the temporary API key.
+   */
+  usage_type: TemporaryApiKeyUsageType;
+  /**
+   * Duration in seconds until the temporary API key expires
+   * @minimum 1
+   * @maximum 3600
+   */
+  expires_in_seconds: number;
+  /**
+   * Optional tracking identifier string. Does not need to be unique
+   * @maxLength 256
+   */
+  client_reference_id?: string;
+};
+type TemporaryApiKeyResponse = {
+  /**
+   * Created temporary API key.
+   */
+  api_key: string;
+  /**
+   * UTC timestamp indicating when generated temporary API key will expire
+   * @format date-time
+   */
+  expires_at: string;
+};
+/**
+ * Real-time configuration options for the main client.
+ */
+type RealtimeOptions = {
+  /**
+   * WebSocket base URL for real-time connections.
+   * Falls back to SONIOX_WS_URL environment variable,
+   * then to 'wss://stt-rt.soniox.com/transcribe-websocket'.
+   */
+  ws_base_url?: string | undefined;
+  /**
+   * Default session options applied to all real-time sessions.
+   * Can be overridden per-session.
+   */
+  default_session_options?: SttSessionOptions | undefined;
+};
+type SonioxNodeClientOptions = {
+  /**
+   * API key for authentication.
+   * Falls back to SONIOX_API_KEY environment variable if not provided.
+   */
+  api_key?: string;
+  /**
+   * Base URL for the REST API.
+   * Falls back to SONIOX_API_BASE_URL environment variable,
+   * then to 'https://api.soniox.com'.
+   */
+  base_url?: string;
+  /**
+   * Custom HTTP client implementation.
+   */
+  http_client?: HttpClient;
+  /**
+   * Real-time API configuration options.
+   */
+  realtime?: RealtimeOptions;
+};
+//#endregion
+//#region src/async/auth.d.ts
+declare class SonioxAuthAPI {
+  private http;
+  constructor(http: HttpClient);
+  /**
+   * 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
+   */
+  createTemporaryKey(request: TemporaryApiKeyRequest, signal?: AbortSignal): Promise<TemporaryApiKeyResponse>;
+}
+//#endregion
+//#region src/async/files.d.ts
+/**
+ * Uploaded file
+ */
+declare class SonioxFile {
+  private readonly _http;
+  readonly id: string;
+  readonly filename: string;
+  readonly size: number;
+  readonly created_at: string;
+  readonly client_reference_id: string | undefined;
+  constructor(data: SonioxFileData, _http: HttpClient);
+  /**
+   * Returns the raw data for this file.
+   */
+  toJSON(): SonioxFileData;
+  /**
+   * 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();
+   * }
+   * ```
+   */
+  delete(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Result set for file listing
+ */
+declare class FileListResult implements AsyncIterable<SonioxFile> {
+  private readonly _http;
+  private readonly _limit;
+  private readonly _signal;
+  /**
+   * Files from the first page of results
+   */
+  readonly files: SonioxFile[];
+  /**
+   * Pagination cursor for the next page. Null if no more pages
+   */
+  readonly next_page_cursor: string | null;
+  constructor(initialResponse: ListFilesResponse<SonioxFileData>, _http: HttpClient, _limit: number | undefined, _signal?: AbortSignal | undefined);
+  /**
+   * Returns the raw data for this list result.
+   * Also used by JSON.stringify() to prevent serialization of internal HTTP client.
+   */
+  toJSON(): ListFilesResponse<SonioxFileData>;
+  /**
+   * Returns true if there are more pages of results beyond the first page
+   */
+  isPaged(): boolean;
+  /**
+   * Async iterator that automatically fetches all pages
+   * Use with `for await...of` to iterate through all files
+   */
+  [Symbol.asyncIterator](): AsyncIterator<SonioxFile>;
+}
+declare class SonioxFilesAPI {
+  private http;
+  constructor(http: HttpClient);
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  upload(file: UploadFileInput, options?: UploadFileOptions): Promise<SonioxFile>;
+  /**
+   * 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 });
+   * ```
+   */
+  list(options?: ListFilesOptions): Promise<FileListResult>;
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  get(file: FileIdentifier, signal?: AbortSignal): Promise<SonioxFile | null>;
+  /**
+   * 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();
+   * ```
+   */
+  delete(file: FileIdentifier, signal?: AbortSignal): Promise<void>;
+  /**
+   * 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 });
+   * ```
+   */
+  purge(options?: PurgeFilesOptions): Promise<PurgeResult>;
+}
+//#endregion
+//#region src/async/models.d.ts
+declare class SonioxModelsAPI {
+  private http;
+  constructor(http: HttpClient);
+  /**
+   * 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.
+   */
+  list(signal?: AbortSignal): Promise<SonioxModel[]>;
+}
+//#endregion
+//#region src/async/stt.d.ts
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+declare function segmentTranscript(tokens: TranscriptToken[], options?: SegmentTranscriptOptions): TranscriptSegment[];
+/**
+ * A Transcript result containing the transcribed text and tokens.
+ */
+declare class SonioxTranscript implements ISonioxTranscript {
+  /**
+   * Unique identifier of the transcription this transcript belongs to.
+   */
+  readonly id: string;
+  /**
+   * Complete transcribed text content.
+   */
+  readonly text: string;
+  /**
+   * List of detailed token information with timestamps and metadata.
+   */
+  readonly tokens: TranscriptToken[];
+  constructor(data: TranscriptResponse);
+  /**
+   * 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?: SegmentTranscriptOptions): TranscriptSegment[];
+}
+/**
+ * A Transcription instance
+ */
+declare class SonioxTranscription implements ISonioxTranscription {
+  private readonly _http;
+  /**
+   * Unique identifier of the transcription.
+   */
+  readonly id: string;
+  /**
+   * Current status of the transcription.
+   */
+  readonly status: TranscriptionStatus;
+  /**
+   * UTC timestamp when the transcription was created.
+   */
+  readonly created_at: string;
+  /**
+   * Speech-to-text model used.
+   */
+  readonly model: string;
+  /**
+   * URL of the audio file being transcribed.
+   */
+  readonly audio_url: string | null | undefined;
+  /**
+   * ID of the uploaded file being transcribed.
+   */
+  readonly file_id: string | null | undefined;
+  /**
+   * Name of the file being transcribed.
+   */
+  readonly filename: string;
+  /**
+   * Expected languages in the audio.
+   */
+  readonly language_hints: string[] | undefined;
+  /**
+   * When true, speakers are identified and separated in the transcription output.
+   */
+  readonly enable_speaker_diarization: boolean;
+  /**
+   * When true, language is detected for each part of the transcription.
+   */
+  readonly enable_language_identification: boolean;
+  /**
+   * Duration of the audio in milliseconds. Only available after processing begins.
+   */
+  readonly audio_duration_ms: number | null | undefined;
+  /**
+   * Error type if transcription failed.
+   */
+  readonly error_type: string | null | undefined;
+  /**
+   * Error message if transcription failed.
+   */
+  readonly error_message: string | null | undefined;
+  /**
+   * URL to receive webhook notifications.
+   */
+  readonly webhook_url: string | null | undefined;
+  /**
+   * Name of the authentication header sent with webhook notifications.
+   */
+  readonly webhook_auth_header_name: string | null | undefined;
+  /**
+   * Authentication header value (masked).
+   */
+  readonly webhook_auth_header_value: string | null | undefined;
+  /**
+   * HTTP status code received when webhook was delivered.
+   */
+  readonly webhook_status_code: number | null | undefined;
+  /**
+   * Optional tracking identifier.
+   */
+  readonly client_reference_id: string | null | undefined;
+  /**
+   * Additional context provided for the transcription.
+   */
+  readonly context: TranscriptionContext | null | undefined;
+  /**
+   * Pre-fetched transcript. Only available when using `transcribe()` with `wait: true`,
+   * `fetch_transcript !== false`, and the transcription completed successfully
+   */
+  readonly transcript: SonioxTranscript | null | undefined;
+  constructor(data: SonioxTranscriptionData, _http: HttpClient, transcript?: SonioxTranscript | null);
+  /**
+   * Returns the raw data for this transcription.
+   */
+  toJSON(): SonioxTranscriptionData;
+  /**
+   * 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();
+   * ```
+   */
+  delete(): Promise<void>;
+  /**
+   * 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
+   * ```
+   */
+  destroy(): Promise<void>;
+  /**
+   * 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 });
+   * ```
+   */
+  getTranscript(options?: {
+    force?: boolean;
+    signal?: AbortSignal;
+  }): Promise<SonioxTranscript | null>;
+  /**
+   * 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);
+   * ```
+   */
+  refresh(signal?: AbortSignal): Promise<SonioxTranscription>;
+  /**
+   * 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}`),
+   * });
+   * ```
+   */
+  wait(options?: WaitOptions): Promise<SonioxTranscription>;
+}
+/**
+ * Result set for transcription listing.
+ */
+declare class TranscriptionListResult implements AsyncIterable<SonioxTranscription> {
+  private readonly _http;
+  private readonly _options;
+  /**
+   * Transcriptions from the first page of results.
+   */
+  readonly transcriptions: SonioxTranscription[];
+  /**
+   * Pagination cursor for the next page. Null if no more pages.
+   */
+  readonly next_page_cursor: string | null;
+  constructor(initialResponse: ListTranscriptionsResponse<SonioxTranscriptionData>, _http: HttpClient, _options: ListTranscriptionsOptions);
+  /**
+   * Returns the raw data for this list result
+   */
+  toJSON(): ListTranscriptionsResponse<SonioxTranscriptionData>;
+  /**
+   * Returns true if there are more pages of results beyond the first page.
+   */
+  isPaged(): boolean;
+  /**
+   * Async iterator that automatically fetches all pages.
+   * Use with `for await...of` to iterate through all transcriptions.
+   */
+  [Symbol.asyncIterator](): AsyncIterator<SonioxTranscription>;
+}
+declare class SonioxSttApi {
+  private http;
+  private filesApi;
+  constructor(http: HttpClient, filesApi: SonioxFilesAPI);
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  create(options: CreateTranscriptionOptions, signal?: AbortSignal): Promise<SonioxTranscription>;
+  /**
+   * 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');
+   * }
+   * ```
+   */
+  list(options?: ListTranscriptionsOptions): Promise<TranscriptionListResult>;
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  get(id: TranscriptionIdentifier): Promise<SonioxTranscription | null>;
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  delete(id: TranscriptionIdentifier): Promise<void>;
+  /**
+   * 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');
+   * ```
+   */
+  destroy(id: TranscriptionIdentifier): Promise<void>;
+  /**
+   * 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);
+   *     }
+   * }
+   * ```
+   */
+  getTranscript(id: TranscriptionIdentifier, signal?: AbortSignal): Promise<SonioxTranscript | null>;
+  /**
+   * 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}`),
+   * });
+   * ```
+   */
+  wait(id: TranscriptionIdentifier, options?: WaitOptions): Promise<SonioxTranscription>;
+  /**
+   * 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).
+   */
+  transcribeFromUrl(audio_url: string, options: TranscribeFromUrlOptions): Promise<SonioxTranscription>;
+  /**
+   * 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).
+   */
+  transcribeFromFileId(file_id: string, options: TranscribeFromFileIdOptions): Promise<SonioxTranscription>;
+  /**
+   * 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).
+   */
+  transcribeFromFile(file: UploadFileInput, options: TranscribeFromFileOptions): Promise<SonioxTranscription>;
+  /**
+   * 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
+   * });
+   * ```
+   */
+  transcribe(options: TranscribeOptions): Promise<SonioxTranscription>;
+  /**
+   * 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 });
+   * ```
+   */
+  purge(options?: PurgeTranscriptionsOptions): Promise<PurgeResult>;
+}
+//#endregion
+//#region src/async/webhooks.d.ts
+/**
+ * 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.
+ */
+declare class SonioxWebhooksAPI {
+  private stt;
+  /**
+   * @internal
+   */
+  constructor(stt?: SonioxSttApi);
+  /**
+   * Enhance a webhook result with fetch helpers
+   */
+  private withFetchHelpers;
+  /**
+   * 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(): WebhookAuthConfig | undefined;
+  /**
+   * Type guard to check if a value is a valid WebhookEvent
+   */
+  isEvent(payload: unknown): payload is WebhookEvent;
+  /**
+   * Parse and validate a webhook event payload
+   */
+  parseEvent(payload: unknown): WebhookEvent;
+  /**
+   * Verify webhook authentication header
+   */
+  verifyAuth(headers: WebhookHeaders, auth: WebhookAuthConfig): boolean;
+  /**
+   * Framework-agnostic webhook handler
+   */
+  handle(options: HandleWebhookOptions): WebhookHandlerResultWithFetch;
+  /**
+   * Handle a webhook from a Fetch API Request
+   */
+  handleRequest(request: Request, auth?: WebhookAuthConfig): Promise<WebhookHandlerResultWithFetch>;
+  /**
+   * 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: ExpressLikeRequest, auth?: WebhookAuthConfig): WebhookHandlerResultWithFetch;
+  /**
+   * Handle a webhook from a Fastify request
+   */
+  handleFastify(req: FastifyLikeRequest, auth?: WebhookAuthConfig): WebhookHandlerResultWithFetch;
+  /**
+   * Handle a webhook from a NestJS request
+   */
+  handleNestJS(req: NestJSLikeRequest, auth?: WebhookAuthConfig): WebhookHandlerResultWithFetch;
+  /**
+   * Handle a webhook from a Hono context
+   */
+  handleHono(c: HonoLikeContext, auth?: WebhookAuthConfig): Promise<WebhookHandlerResultWithFetch>;
+}
+//#endregion
+//#region src/realtime/stt.d.ts
+/**
+ * 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();
+ * ```
+ */
+declare class RealtimeSttSession implements AsyncIterable<RealtimeEvent> {
+  private readonly emitter;
+  private readonly eventQueue;
+  private readonly apiKey;
+  private readonly wsBaseUrl;
+  private readonly config;
+  private readonly keepaliveIntervalMs;
+  private readonly keepaliveEnabled;
+  private readonly signal;
+  private ws;
+  private _state;
+  private _paused;
+  private keepaliveInterval;
+  private finishResolver;
+  private finishRejecter;
+  private abortHandler;
+  constructor(apiKey: string, wsBaseUrl: string, config: SttSessionConfig, options?: SttSessionOptions);
+  /**
+   * Current session state.
+   */
+  get state(): SttSessionState;
+  /**
+   * Whether the session is currently paused.
+   */
+  get paused(): boolean;
+  /**
+   * Connect to the Soniox WebSocket API.
+   *
+   * @throws {AbortError} If aborted
+   * @throws {NetworkError} If connection fails
+   * @throws {StateError} If already connected
+   */
+  connect(): Promise<void>;
+  /**
+   * 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: AudioData): void;
+  /**
+   * 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 });
+   * ```
+   */
+  sendStream(stream: AsyncIterable<AudioData>, options?: SendStreamOptions): Promise<void>;
+  /**
+   * Pause audio transmission and starts automatic keepalive messages
+   */
+  pause(): void;
+  /**
+   * Resume audio transmission
+   */
+  resume(): void;
+  /**
+   * Requests the server to finalize current transcription
+   */
+  finalize(options?: {
+    trailing_silence_ms?: number;
+  }): void;
+  /**
+   * Send a keepalive message
+   */
+  keepAlive(): void;
+  /**
+   * Gracefully finish the session
+   */
+  finish(): Promise<void>;
+  /**
+   * Close (cancel) the session immediately without waiting
+   */
+  close(): void;
+  /**
+   * Register an event handler
+   */
+  on<E extends keyof SttSessionEvents>(event: E, handler: SttSessionEvents[E]): this;
+  /**
+   * Register a one-time event handler
+   */
+  once<E extends keyof SttSessionEvents>(event: E, handler: SttSessionEvents[E]): this;
+  /**
+   * Remove an event handler
+   */
+  off<E extends keyof SttSessionEvents>(event: E, handler: SttSessionEvents[E]): this;
+  /**
+   * Async iterator for consuming events.
+   */
+  [Symbol.asyncIterator](): AsyncIterator<RealtimeEvent>;
+  private createWebSocket;
+  private handleMessage;
+  private handleClose;
+  private handleError;
+  private handleAbort;
+  private setState;
+  private cleanup;
+  private isTerminalState;
+  private checkAborted;
+  private settleFinish;
+  private sendMessage;
+  private startKeepalive;
+  private stopKeepalive;
+  private updateKeepalive;
+}
+//#endregion
+//#region src/realtime/segments.d.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)
+ */
+declare function segmentRealtimeTokens(tokens: RealtimeToken[], options?: RealtimeSegmentOptions): RealtimeSegment[];
+//#endregion
+//#region src/realtime/segment-buffer.d.ts
+/**
+ * Rolling buffer for turning real-time results into stable segments.
+ */
+declare class RealtimeSegmentBuffer {
+  private tokens;
+  private readonly groupBy;
+  private readonly finalOnly;
+  private readonly maxTokens;
+  private readonly maxMs;
+  constructor(options?: RealtimeSegmentBufferOptions);
+  /**
+   * Number of tokens currently buffered.
+   */
+  get size(): number;
+  /**
+   * Add a real-time result and return stable segments.
+   */
+  add(result: RealtimeResult): RealtimeSegment[];
+  /**
+   * Clear all buffered tokens.
+   */
+  reset(): void;
+  /**
+   * Flush all buffered tokens into segments and clear the buffer.
+   *
+   * Includes tokens that are not yet stable by final_audio_proc_ms.
+   */
+  flushAll(): RealtimeSegment[];
+  private flushStable;
+  private trim;
+}
+//#endregion
+//#region src/realtime/utterance-buffer.d.ts
+/**
+ * Collects real-time results into utterances for endpoint-driven workflows.
+ */
+declare class RealtimeUtteranceBuffer {
+  private readonly segmentBuffer;
+  private pendingSegments;
+  private lastFinalAudioProcMs;
+  private lastTotalAudioProcMs;
+  constructor(options?: RealtimeUtteranceBufferOptions);
+  /**
+   * Add a real-time result and collect stable segments.
+   */
+  addResult(result: RealtimeResult): RealtimeSegment[];
+  /**
+   * Mark an endpoint and flush the current utterance.
+   */
+  markEndpoint(): RealtimeUtterance | undefined;
+  /**
+   * Clear buffered segments and tokens.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/http/errors.d.ts
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+declare class SonioxError extends Error {
+  /**
+   * Error code describing the type of error
+   */
+  readonly code: SonioxErrorCode;
+  /**
+   * HTTP status code when applicable (e.g., 401 for auth errors, 500 for server errors).
+   */
+  readonly statusCode: number | undefined;
+  /**
+   * The underlying error that caused this error, if any.
+   */
+  readonly cause: unknown;
+  constructor(message: string, code?: SonioxErrorCode, statusCode?: number, cause?: unknown);
+  /**
+   * Creates a human-readable string representation
+   */
+  toString(): string;
+  /**
+   * Converts to a plain object for logging/serialization
+   */
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+declare class SonioxHttpError extends SonioxError {
+  /** Categorized HTTP error code */
+  readonly code: HttpErrorCode;
+  /** Request URL */
+  readonly url: string;
+  /** HTTP method */
+  readonly method: HttpMethod;
+  /** Response headers (only for http_error) */
+  readonly headers: Record<string, string> | undefined;
+  /** Response body text, capped at 4KB (only for http_error/parse_error) */
+  readonly bodyText: string | undefined;
+  constructor(details: HttpErrorDetails);
+  /**
+   * Creates a human-readable string representation
+   */
+  toString(): string;
+  /**
+   * Converts to a plain object for logging/serialization
+   */
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Creates a network error
+ */
+declare function createNetworkError(url: string, method: HttpMethod, cause: unknown): SonioxHttpError;
+/**
+ * Creates a timeout error
+ */
+declare function createTimeoutError(url: string, method: HttpMethod, timeoutMs: number): SonioxHttpError;
+/**
+ * Creates an abort error
+ */
+declare function createAbortError(url: string, method: HttpMethod, cause?: unknown): SonioxHttpError;
+/**
+ * Creates an HTTP error (non-2xx status)
+ */
+declare function createHttpError(url: string, method: HttpMethod, statusCode: number, headers: Record<string, string>, bodyText: string): SonioxHttpError;
+/**
+ * Creates a parse error (invalid JSON, etc.)
+ */
+declare function createParseError(url: string, method: HttpMethod, bodyText: string, cause: unknown): SonioxHttpError;
+/**
+ * Type guard to check if an error is an AbortError
+ */
+declare function isAbortError(error: unknown): boolean;
+/**
+ * Type guard to check if an error is any SonioxError (base class).
+ * This catches all SDK errors including HTTP and real-time errors.
+ */
+declare function isSonioxError(error: unknown): error is SonioxError;
+/**
+ * Type guard to check if an error is a SonioxHttpError
+ */
+declare function isSonioxHttpError(error: unknown): error is SonioxHttpError;
+//#endregion
+//#region src/realtime/errors.d.ts
+/**
+ * Base error class for all real-time (WebSocket) SDK errors
+ */
+declare class RealtimeError extends SonioxError {
+  /** Real-time error code */
+  readonly code: RealtimeErrorCode;
+  /**
+   * Original response payload for debugging.
+   * Contains the raw WebSocket message that caused the error.
+   */
+  readonly raw: unknown;
+  constructor(message: string, code?: RealtimeErrorCode, statusCode?: number, raw?: unknown);
+  /**
+   * Creates a human-readable string representation
+   */
+  toString(): string;
+  /**
+   * Converts to a plain object for logging/serialization
+   */
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication error (401).
+ * Thrown when the API key is invalid or expired.
+ */
+declare class AuthError extends RealtimeError {
+  constructor(message: string, statusCode?: number, raw?: unknown);
+}
+/**
+ * Bad request error (400).
+ * Thrown for invalid configuration or parameters.
+ */
+declare class BadRequestError extends RealtimeError {
+  constructor(message: string, statusCode?: number, raw?: unknown);
+}
+/**
+ * Quota error (402, 429).
+ * Thrown when rate limits are exceeded or quota is exhausted.
+ */
+declare class QuotaError extends RealtimeError {
+  constructor(message: string, statusCode?: number, raw?: unknown);
+}
+/**
+ * Connection error.
+ * Thrown for WebSocket connection failures and transport errors.
+ */
+declare class ConnectionError extends RealtimeError {
+  constructor(message: string, raw?: unknown);
+}
+/**
+ * Network error.
+ * Thrown for server-side network issues (408, 500, 503).
+ */
+declare class NetworkError extends RealtimeError {
+  constructor(message: string, statusCode?: number, raw?: unknown);
+}
+/**
+ * Abort error.
+ * Thrown when an operation is cancelled via AbortSignal.
+ */
+declare class AbortError extends RealtimeError {
+  constructor(message?: string);
+}
+/**
+ * State error.
+ * Thrown when an operation is attempted in an invalid state.
+ */
+declare class StateError extends RealtimeError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/realtime/index.d.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();
+ * ```
+ */
+declare class SonioxRealtimeApi {
+  private readonly options;
+  constructor(options: RealtimeClientOptions);
+  /**
+   * 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: SttSessionConfig, options?: SttSessionOptions): RealtimeSttSession;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Soniox Node Client
+ * @returns {SonioxNodeClient}
+ *
+ * @example
+ * ```typescript
+ * import { SonioxNodeClient } from '@soniox/node';
+ *
+ * const client = new SonioxNodeClient({
+ *   api_key: 'your-api-key',
+ * });
+ * ```
+ */
+declare class SonioxNodeClient {
+  readonly files: SonioxFilesAPI;
+  readonly stt: SonioxSttApi;
+  readonly models: SonioxModelsAPI;
+  readonly webhooks: SonioxWebhooksAPI;
+  readonly auth: SonioxAuthAPI;
+  readonly realtime: SonioxRealtimeApi;
+  constructor(options?: SonioxNodeClientOptions);
+}
+//#endregion
+//#region src/http/fetch-adapter.d.ts
+/**
+ * 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,
+ * });
+ * ```
+ */
+declare class FetchHttpClient implements HttpClient {
+  private readonly baseUrl;
+  private readonly defaultHeaders;
+  private readonly defaultTimeoutMs;
+  private readonly hooks;
+  private readonly fetchImpl;
+  constructor(options?: HttpClientOptions);
+  /**
+   * Performs an HTTP request.
+   *
+   * @param request - Request configuration
+   * @returns Promise resolving to the response
+   * @throws {SonioxHttpError}
+   */
+  request<T>(request: HttpRequest): Promise<HttpResponse<T>>;
+  /**
+   * Normalizes various error types into SonioxHttpError.
+   */
+  private normalizeError;
+}
+//#endregion
+//#region src/http/url.d.ts
+/**
+ * Builds a complete URL from base URL, path, and query parameters
+ */
+declare function buildUrl(baseUrl: string | undefined, path: string, query?: QueryParams): string;
+/**
+ * Normalizes fetch Headers to a plain object with lowercase keys
+ */
+declare function normalizeHeaders(headers: Headers): Record<string, string>;
+/**
+ * Merges header objects
+ */
+declare function mergeHeaders(...headerObjects: (Record<string, string> | undefined)[]): Record<string, string>;
+//#endregion
+export { AbortError, type AudioData, type AudioFormat, AuthError, BadRequestError, type CleanupTarget, ConnectionError, type ContextGeneralEntry, type ContextTranslationTerm, type CreateTranscriptionOptions, type ExpressLikeRequest, type FastifyLikeRequest, FetchHttpClient, type FileIdentifier, FileListResult, type HandleWebhookOptions, type HonoLikeContext, type HttpClient, type HttpClientOptions, type HttpErrorCode, type HttpErrorDetails, type HttpMethod, type HttpObservabilityHooks, type HttpRequest, type HttpRequestBody, type HttpRequestMeta, type HttpResponse, type HttpResponseMeta, type HttpResponseType, type ISonioxTranscript, type ISonioxTranscription, type ListFilesOptions, type ListFilesResponse, type ListTranscriptionsOptions, type ListTranscriptionsResponse, type NestJSLikeRequest, NetworkError, type OneWayTranslationConfig, type PurgeFilesOptions, PurgeResult, type PurgeTranscriptionsOptions, type QueryParams, QuotaError, type RealtimeClientOptions, RealtimeError, type RealtimeErrorCode, type RealtimeEvent, RealtimeOptions, type RealtimeResult, type RealtimeSegment, RealtimeSegmentBuffer, type RealtimeSegmentBufferOptions, type RealtimeSegmentOptions, RealtimeSttSession, type RealtimeToken, type RealtimeUtterance, RealtimeUtteranceBuffer, type RealtimeUtteranceBufferOptions, 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, type SegmentGroupKey, type SegmentTranscriptOptions, type SendStreamOptions, SonioxError, type SonioxErrorCode, SonioxFile, type SonioxFileData, SonioxHttpError, type SonioxLanguage, type SonioxModel, SonioxNodeClient, SonioxNodeClientOptions, SonioxRealtimeApi, SonioxTranscript, SonioxTranscription, type SonioxTranscriptionData, type SonioxTranscriptionMode, type SonioxTranslationTarget, StateError, type SttSessionConfig, type SttSessionEvents, type SttSessionOptions, type SttSessionState, TemporaryApiKeyRequest, TemporaryApiKeyResponse, TemporaryApiKeyUsageType, type TranscribeBaseOptions, type TranscribeFromFile, type TranscribeFromFileId, type TranscribeFromFileIdOptions, type TranscribeFromFileOptions, type TranscribeFromUrl, type TranscribeFromUrlOptions, type TranscribeOptions, type TranscriptResponse, type TranscriptSegment, type TranscriptToken, type TranscriptionContext, type TranscriptionIdentifier, TranscriptionListResult, type TranscriptionStatus, type TranslationConfig, type TwoWayTranslationConfig, type UploadFileInput, type UploadFileOptions, type WaitOptions, type WebhookAuthConfig, type WebhookEvent, type WebhookEventStatus, type WebhookHandlerResult, type WebhookHandlerResultWithFetch, type WebhookHeaders, buildUrl, createAbortError, createHttpError, createNetworkError, createParseError, createTimeoutError, isAbortError, isSonioxError, isSonioxHttpError, mergeHeaders, normalizeHeaders, segmentRealtimeTokens, segmentTranscript };
+//# sourceMappingURL=index.d.mts.map