Types

type AudioData = Buffer | Uint8Array | ArrayBuffer;

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";

type CleanupTarget = "file" | "transcription";

type ContextGeneralEntry = {
  key: string;
  value: string;
};

type ContextTranslationTerm = {
  source: string;
  target: string;
};

type CreateTranscriptionOptions = {
  audio_url?: string;
  client_reference_id?: string;
  context?: TranscriptionContext;
  enable_language_identification?: boolean;
  enable_speaker_diarization?: boolean;
  file_id?: string;
  language_hints?: string[];
  language_hints_strict?: boolean;
  model: string;
  translation?: TranslationConfig;
  webhook_auth_header_name?: string;
  webhook_auth_header_value?: string;
  webhook_url?: string;
};

type DeleteAllFilesOptions = {
  signal?: AbortSignal;
};

type DeleteAllTranscriptionsOptions = {
  on_progress?: (transcription, index) => void;
  signal?: AbortSignal;
};

type ExpressLikeRequest = {
  body?: unknown;
  headers: Record<string, string | string[] | undefined>;
  method: string;
};

type FastifyLikeRequest = {
  body?: unknown;
  headers: Record<string, string | string[] | undefined>;
  method: string;
};

type FileIdentifier = 
  | string
  | {
  id: string;
};

type HandleWebhookOptions = {
  auth?: WebhookAuthConfig;
  body: unknown;
  headers: WebhookHeaders;
  method: string;
};

type HonoLikeContext = {
  req: {
     method: string;
     header: string | undefined;
     json: Promise<unknown>;
  };
};

type HttpErrorCode = "network_error" | "timeout" | "aborted" | "http_error" | "parse_error";

type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";

type HttpRequestBody = 
  | string
  | Record<string, unknown>
  | ArrayBuffer
  | Uint8Array
  | FormData
  | null;

type HttpResponseType = "json" | "text" | "arrayBuffer";

type ListFilesOptions = {
  cursor?: string;
  limit?: number;
  signal?: AbortSignal;
};

type ListFilesResponse<T> = {
  files: T[];
  next_page_cursor: string | null;
};

type ListTranscriptionsOptions = {
  cursor?: string;
  limit?: number;
};

type ListTranscriptionsResponse<T> = {
  next_page_cursor: string | null;
  transcriptions: T[];
};

type NestJSLikeRequest = {
  body?: unknown;
  headers: Record<string, string | string[] | undefined>;
  method: string;
};

type OneWayTranslationConfig = {
  target_language: string;
  type: "one_way";
};

type QueryParams = Record<string, string | number | boolean | undefined>;

type RealtimeClientOptions = {
  api_key: string;
  default_session_options?: SttSessionOptions;
  ws_base_url: string;
};

type RealtimeErrorCode = 
  | "auth_error"
  | "bad_request"
  | "quota_exceeded"
  | "connection_error"
  | "network_error"
  | "aborted"
  | "state_error"
  | "realtime_error";

type RealtimeEvent = 
  | {
  data: RealtimeResult;
  kind: "result";
}
  | {
  kind: "endpoint";
}
  | {
  kind: "finalized";
}
  | {
  kind: "finished";
};

type RealtimeOptions = {
  default_session_options?: SttSessionOptions;
  ws_base_url?: string;
};

type RealtimeResult = {
  final_audio_proc_ms: number;
  finished?: boolean;
  tokens: RealtimeToken[];
  total_audio_proc_ms: number;
};

type RealtimeSegment = {
  end_ms?: number;
  language?: string;
  speaker?: string;
  start_ms?: number;
  text: string;
  tokens: RealtimeToken[];
};

type RealtimeSegmentBufferOptions = {
  final_only?: boolean;
  group_by?: SegmentGroupKey[];
  max_ms?: number;
  max_tokens?: number;
};

type RealtimeSegmentOptions = {
  final_only?: boolean;
  group_by?: SegmentGroupKey[];
};

type RealtimeToken = {
  confidence: number;
  end_ms?: number;
  is_final: boolean;
  language?: string;
  source_language?: string;
  speaker?: string;
  start_ms?: number;
  text: string;
  translation_status?: "none" | "original" | "translation";
};

type RealtimeUtterance = {
  end_ms?: number;
  final_audio_proc_ms?: number;
  language?: string;
  segments: RealtimeSegment[];
  speaker?: string;
  start_ms?: number;
  text: string;
  tokens: RealtimeToken[];
  total_audio_proc_ms?: number;
};

type RealtimeUtteranceBufferOptions = {
  final_only?: boolean;
  group_by?: SegmentGroupKey[];
  max_ms?: number;
  max_tokens?: number;
};

type SegmentGroupKey = "speaker" | "language";

type SegmentTranscriptOptions = {
  group_by?: SegmentGroupKey[];
};

type SendStreamOptions = {
  finish?: boolean;
  pace_ms?: number;
};

type SonioxErrorCode = 
  | RealtimeErrorCode
  | "soniox_error"
  | HttpErrorCode;

type SonioxFileData = {
  client_reference_id?: string | null;
  created_at: string;
  filename: string;
  id: string;
  size: number;
};

type SonioxLanguage = {
  code: string;
  name: string;
};

type SonioxModel = {
  aliased_model_id: string | null;
  context_version: number | null;
  id: string;
  languages: SonioxLanguage[];
  name: string;
  one_way_translation: string | null;
  supports_language_hints_strict: boolean;
  supports_max_endpoint_delay: boolean;
  transcription_mode: SonioxTranscriptionMode;
  translation_targets: SonioxTranslationTarget[];
  two_way_translation: string | null;
  two_way_translation_pairs: string[];
};

type SonioxNodeClientOptions = {
  api_key?: string;
  base_url?: string;
  http_client?: HttpClient;
  realtime?: RealtimeOptions;
};

type SonioxTranscriptionData = {
  audio_duration_ms?: number | null;
  audio_url?: string | null;
  client_reference_id?: string | null;
  context?: TranscriptionContext | null;
  created_at: string;
  enable_language_identification: boolean;
  enable_speaker_diarization: boolean;
  error_message?: string | null;
  error_type?: string | null;
  file_id?: string | null;
  filename: string;
  id: string;
  language_hints?: string[] | null;
  model: string;
  status: TranscriptionStatus;
  webhook_auth_header_name?: string | null;
  webhook_auth_header_value?: string | null;
  webhook_status_code?: number | null;
  webhook_url?: string | null;
};

type SonioxTranscriptionMode = "real_time" | "async";

type SonioxTranslationTarget = {
  exclude_source_languages: string[];
  source_languages: string[];
  target_language: string;
};

type SttSessionConfig = {
  audio_format?: "auto" | AudioFormat;
  client_reference_id?: string;
  context?: TranscriptionContext;
  enable_endpoint_detection?: boolean;
  enable_language_identification?: boolean;
  enable_speaker_diarization?: boolean;
  language_hints?: string[];
  language_hints_strict?: boolean;
  model: string;
  num_channels?: number;
  sample_rate?: number;
  translation?: TranslationConfig;
};

type SttSessionEvents = {
  connected: () => void;
  disconnected: (reason?) => void;
  endpoint: () => void;
  error: (error) => void;
  finalized: () => void;
  finished: () => void;
  result: (result) => void;
  state_change: (update) => void;
  token: (token) => void;
};

type SttSessionOptions = {
  keepalive_interval_ms?: number;
  signal?: AbortSignal;
};

type SttSessionState = 
  | "idle"
  | "connecting"
  | "connected"
  | "finishing"
  | "finished"
  | "canceled"
  | "closed"
  | "error";

type TemporaryApiKeyRequest = {
  client_reference_id?: string;
  expires_in_seconds: number;
  usage_type: TemporaryApiKeyUsageType;
};

type TemporaryApiKeyResponse = {
  api_key: string;
  expires_at: string;
};

type TemporaryApiKeyUsageType = "transcribe_websocket";

type TranscribeBaseOptions = {
  cleanup?: CleanupTarget[];
  client_reference_id?: string;
  context?: TranscriptionContext;
  enable_language_identification?: boolean;
  enable_speaker_diarization?: boolean;
  fetch_transcript?: boolean;
  language_hints?: string[];
  language_hints_strict?: boolean;
  model: string;
  signal?: AbortSignal;
  timeout_ms?: number;
  translation?: TranslationConfig;
  wait?: boolean;
  wait_options?: WaitOptions;
  webhook_auth_header_name?: string;
  webhook_auth_header_value?: string;
  webhook_query?: string | URLSearchParams | Record<string, string>;
  webhook_url?: string;
};

type TranscribeFromFile = TranscribeBaseOptions & {
  audio_url?: never;
  file: UploadFileInput;
  file_id?: never;
  filename?: string;
};

type TranscribeFromFileId = TranscribeBaseOptions & {
  audio_url?: never;
  file?: never;
  file_id: string;
  filename?: never;
};

type TranscribeFromFileIdOptions = Omit<TranscribeFromFileId, "file_id">;

type TranscribeFromFileOptions = Omit<TranscribeFromFile, "file">;

type TranscribeFromUrl = TranscribeBaseOptions & {
  audio_url: string;
  file?: never;
  file_id?: never;
  filename?: never;
};

type TranscribeFromUrlOptions = Omit<TranscribeFromUrl, "audio_url">;

type TranscribeOptions = 
  | TranscribeFromFile
  | TranscribeFromFileId
  | TranscribeFromUrl;

type TranscriptResponse = {
  id: string;
  text: string;
  tokens: TranscriptToken[];
};

type TranscriptSegment = {
  end_ms: number;
  language?: string;
  speaker?: string;
  start_ms: number;
  text: string;
  tokens: TranscriptToken[];
};

type TranscriptToken = {
  confidence: number;
  end_ms: number;
  is_audio_event?: boolean | null;
  language?: string | null;
  speaker?: string | null;
  start_ms: number;
  text: string;
  translation_status?: "none" | "original" | "translation" | null;
};

type TranscriptionContext = {
  general?: ContextGeneralEntry[];
  terms?: string[];
  text?: string;
  translation_terms?: ContextTranslationTerm[];
};

type TranscriptionIdentifier = 
  | string
  | {
  id: string;
};

type TranscriptionStatus = "queued" | "processing" | "completed" | "error";

type TranslationConfig = 
  | OneWayTranslationConfig
  | TwoWayTranslationConfig;

type TwoWayTranslationConfig = {
  language_a: string;
  language_b: string;
  type: "two_way";
};

type UploadFileInput = 
  | Buffer
  | Uint8Array
  | Blob
  | ReadableStream<Uint8Array>
  | NodeJS.ReadableStream;

type UploadFileOptions = {
  client_reference_id?: string;
  filename?: string;
  signal?: AbortSignal;
  timeout_ms?: number;
};

type WaitOptions = {
  interval_ms?: number;
  on_status_change?: (status, transcription) => void;
  signal?: AbortSignal;
  timeout_ms?: number;
};

type WebhookAuthConfig = {
  name: string;
  value: string;
};

type WebhookEvent = {
  id: string;
  status: WebhookEventStatus;
};

type WebhookEventStatus = "completed" | "error";

type WebhookHandlerResult = {
  error?: string;
  event?: WebhookEvent;
  ok: boolean;
  status: number;
};

type WebhookHandlerResultWithFetch = WebhookHandlerResult & {
  fetchTranscript:   | () => Promise<ISonioxTranscript | null>
     | undefined;
  fetchTranscription:   | () => Promise<ISonioxTranscription | null>
     | undefined;
};

type WebhookHeaders = 
  | Headers
  | Record<string, string | string[] | undefined>
  | {
  get: string | null;
};

request<T>(request): Promise<HttpResponse<T>>;

segments(options?): TranscriptSegment[];

delete(): Promise<void>;

destroy(): Promise<void>;

getTranscript(options?): Promise<ISonioxTranscript | null>;

refresh(signal?): Promise<ISonioxTranscription>;

toJSON(): SonioxTranscriptionData;

wait(options?): Promise<ISonioxTranscription>;