type ApiKeyConfig = string | () => Promise<string>;

// Static key (for demos or SSR-injected keys)
const client = new SonioxClient({ api_key: 'temp:...' });

// Async function (recommended for production)
const client = new SonioxClient({
  api_key: async () => {
    const res = await fetch('/api/get-temporary-key', { method: 'POST' });
    const { api_key } = await res.json();
    return api_key;
  },
});

type AudioErrorCode = "permission_denied" | "device_not_found" | "audio_unavailable";

type AudioSourceHandlers = {
  onData: (chunk) => void;
  onError: (error) => void;
  onMuted?: () => void;
  onUnmuted?: () => void;
};

type GenerateSpeechOptions = {
  audio_format?: string;
  bitrate?: number;
  language?: string;
  model?: string;
  sample_rate?: number;
  signal?: AbortSignal;
  text: string;
  voice: string;
};

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

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

type MicrophoneSourceOptions = {
  constraints?: MediaTrackConstraints;
  recorderOptions?: MediaRecorderOptions;
  timesliceMs?: number;
};

type PermissionResult = {
  can_request: boolean;
  status: PermissionStatus;
};

type PermissionStatus = "granted" | "denied" | "prompt" | "unavailable";

type PermissionType = "microphone";

type RecordOptions = SttSessionConfig & ReconnectOptions & {
  buffer_queue_size?: number;
  session_config?: (resolved) => SttSessionConfig;
  session_options?: SttSessionOptions;
  signal?: AbortSignal;
  source?: AudioSource;
};

type RecordingEvents = {
  connected: () => void;
  endpoint: () => void;
  error: (error) => void;
  finalized: () => void;
  finished: () => void;
  reconnected: (event) => void;
  reconnecting: (event) => void;
  result: (result) => void;
  session_restart: (event) => void;
  source_muted: () => void;
  source_unmuted: () => void;
  state_change: (update) => void;
  token: (token) => void;
};

type RecordingState = 
  | "idle"
  | "starting"
  | "connecting"
  | "recording"
  | "paused"
  | "reconnecting"
  | "stopping"
  | "stopped"
  | "error"
  | "canceled";

type SonioxClientOptions = {
  api_key?: ApiKeyConfig;
  buffer_queue_size?: number;
  config?:   | SonioxConnectionConfig
     | (context?) => Promise<SonioxConnectionConfig>;
  default_session_options?: SttSessionOptions;
  permissions?: PermissionResolver;
  ws_base_url?: string;
};

type SttOptions = {
  api_key: string;
  session_options?: SttSessionOptions;
};

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

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

type TtsConnectionOptions = {
  connect_timeout_ms?: number;
  keepalive_interval_ms?: number;
};

type TtsStreamConfig = {
  audio_format: string;
  bitrate?: number;
  language: string;
  model: string;
  sample_rate?: number;
  stream_id: string;
  voice: string;
};

type TtsStreamEvents = {
  audio: (chunk) => void;
  audioEnd: () => void;
  error: (error) => void;
  terminated: () => void;
};

type TtsStreamInput = {
  audio_format?: TtsAudioFormat;
  bitrate?: number;
  language?: string;
  model?: string;
  sample_rate?: number;
  stream_id?: string;
  voice?: string;
};

type TtsStreamState = "active" | "finishing" | "ended" | "error";

// Built-in browser source
const source = new MicrophoneSource();

// Custom source (e.g., React Native)
class MyAudioSource implements AudioSource {
  async start(handlers: AudioSourceHandlers) { ... }
  stop() { ... }
}

optional pause(): void;

optional restart(): void;

optional resume(): void;

start(handlers): Promise<void>;

stop(): void;

ClientTtsFactory(input?): Promise<RealtimeTtsStream>;

multiStream(): Promise<RealtimeTtsConnection>;

// Check before recording
const mic = await resolver.check('microphone');
if (mic.status === 'denied' && !mic.can_request) {
  showGoToSettingsMessage();
}

check(permission): Promise<PermissionResult>;

request(permission): Promise<PermissionResult>;

function resolveApiKey(config): Promise<string>;