Types

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 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 & {
  buffer_queue_size?: number;
  session_options?: SttSessionOptions;
  signal?: AbortSignal;
  source?: AudioSource;
};

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

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

type SonioxClientOptions = {
  api_key: ApiKeyConfig;
  buffer_queue_size?: number;
  default_session_options?: SttSessionOptions;
  permissions?: PermissionResolver;
  ws_base_url?: string;
};

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

// 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 resume(): void;

start(handlers): Promise<void>;

stop(): void;

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