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 ConcurrencyCurrentValues = {
  transcribe_concurrent: number;
  tts_concurrent: number;
};

type ConcurrencyLimitValues = {
  transcribe_concurrent: number | null;
  tts_concurrent: number | null;
};

type ConcurrencyLimitsResponse = {
  organization: ConcurrencyScopeValues;
  project: ConcurrencyScopeValues;
};

type ConcurrencyScopeValues = {
  current: ConcurrencyCurrentValues;
  limits: ConcurrencyLimitValues;
};

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 FilesCountResponse = {
  playground: number;
  public_api: number;
  total: number;
};

type GenerateSpeechOptions = {
  audio_format?: string;
  bitrate?: number;
  language?: string;
  model?: string;
  sample_rate?: number;
  signal?: AbortSignal;
  text: string;
  voice: 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 ListUsageLogsOptions = {
  cursor?: string;
  end_time: string;
  limit?: number;
  signal?: AbortSignal;
  sort?: UsageLogsSort;
  start_time: string;
};

type ListUsageLogsResponse = {
  next_page_cursor: string | null;
  usage_logs: SonioxUsageLog[];
};

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

type OneWayTranslation = {
  duration_ms: number;
  from?: string;
  mode: "one_way";
  original_text: string;
  segments: TranslationSegment[];
  to: string;
  translation_text: 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;
  stt_defaults?: Partial<SttSessionConfig>;
  tts_connection_options?: TtsConnectionOptions;
  tts_defaults?: Partial<TtsStreamConfig>;
  tts_ws_url: string;
  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;
  stt_defaults?: Partial<SttSessionConfig>;
  tts_connection_options?: TtsConnectionOptions;
  tts_defaults?: Partial<TtsStreamConfig>;
  tts_ws_url?: string;
  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_domain?: string;
  base_url?: string;
  http_client?: HttpClient;
  realtime?: RealtimeOptions;
  region?: SonioxRegion;
  stt_defaults?: Partial<SttSessionConfig>;
  tts_api_url?: string;
  tts_defaults?: Partial<TtsStreamConfig>;
};

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 SonioxTranslation = 
  | OneWayTranslation
  | TwoWayTranslation;

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

type SonioxUsageLog = {
  client_reference_id?: string | null;
  cost_usd: string;
  end_time: string;
  input_audio_cost_usd: string;
  input_audio_duration_ms: number;
  input_audio_tokens: number;
  input_cost_usd: string;
  input_text_cost_usd: string;
  input_text_tokens: number;
  model: string;
  output_audio_cost_usd: string;
  output_audio_duration_ms: number;
  output_audio_tokens: number;
  output_cost_usd: string;
  output_text_cost_usd: string;
  output_text_tokens: number;
  request_scope: string;
  start_time: string;
  uuid: 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;
  endpoint_sensitivity?: number;
  language_hints?: string[];
  language_hints_strict?: boolean;
  max_endpoint_delay_ms?: number;
  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 = {
  connect_timeout_ms?: number;
  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;
  max_session_duration_seconds?: number;
  single_use?: boolean;
  usage_type: TemporaryApiKeyUsageType;
};

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

type TemporaryApiKeyUsageType = "transcribe_websocket" | "tts_rt";

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;
  source_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 TranscriptionsCountResponse = {
  playground: number;
  public_api: number;
  total: number;
};

type TranslateAudioSource = 
  | {
  audio_url?: never;
  file: UploadFileInput;
  file_id?: never;
  filename?: string;
}
  | {
  audio_url?: never;
  file?: never;
  file_id: string;
  filename?: never;
}
  | {
  audio_url: string;
  file?: never;
  file_id?: never;
  filename?: never;
};

{
  audio_url?: never;
  file: UploadFileInput;
  file_id?: never;
  filename?: string;
}

{
  audio_url?: never;
  file?: never;
  file_id: string;
  filename?: never;
}

{
  audio_url: string;
  file?: never;
  file_id?: never;
  filename?: never;
}

type TranslateBaseOptions = {
  cleanup?: CleanupTarget[];
  client_reference_id?: string;
  context?: TranscriptionContext;
  enable_speaker_diarization?: boolean;
  fetch_translation?: boolean;
  model?: string;
  signal?: AbortSignal;
  timeout_ms?: number;
  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 TranslateFromTranscriptMode = 
  | {
  from?: string;
  to: string;
  type: "one_way";
}
  | {
  language_a: string;
  language_b: string;
  type: "two_way";
};

type TranslateMode = 
  | {
  between?: never;
  from?: never;
  to: string;
}
  | {
  between?: never;
  from: string;
  to: string;
}
  | {
  between: [string, string];
  from?: never;
  to?: never;
};

type TranslateOptions = TranslateMode & TranslateAudioSource & TranslateBaseOptions;

type TranslationConfig = 
  | OneWayTranslationConfig
  | TwoWayTranslationConfig;

type TranslationSegment = {
  end_ms?: number;
  from: string;
  original_text: string;
  original_tokens: TranscriptToken[];
  speaker?: string;
  start_ms?: number;
  to?: string;
  translation_text?: string;
  translation_tokens?: TranscriptToken[];
};

type TtsAudioFormat = 
  | "pcm_f32le"
  | "pcm_s16le"
  | "pcm_mulaw"
  | "pcm_alaw"
  | "wav"
  | "aac"
  | "mp3"
  | "opus"
  | "flac"
  | string & {
};

type TtsConnectionEvents = {
  close: () => void;
  error: (error) => void;
};