@flamai/finesse 0.0.0-stage → 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,831 @@
+type Fetch = typeof globalThis.fetch;
+interface ClientOptions {
+    /** Workspace API key (`flv_...`). Defaults to `FINESSE_API_KEY`. Keep it on your server. */
+    apiKey?: string;
+    /** A short-lived token (`fin_tok_...`) from `tokens.create`, instead of an API key. It is
+     * safe in a browser: it carries the `tts` scope only and is good for one `speech.create` /
+     * `speech.stream` call or one realtime session. Sent as `Authorization: Bearer`. */
+    accessToken?: string;
+    /** API host. Defaults to `FINESSE_BASE_URL`, then production. */
+    baseURL?: string;
+    /** Per-request timeout in ms. Default 120 000. */
+    timeout?: number;
+    /** Retries for transient failures. Default 2. Reads, updates and deletes retry on network
+     * errors, timeouts, 408, 429 and 5xx. Creates, uploads and synthesis retry only when the
+     * server did no work: the connection never opened, 429, 502 or 503. With an `accessToken`
+     * only 429 and a connection that never opened are retried, since the token is single use. */
+    maxRetries?: number;
+    /** Extra headers sent on every request. */
+    defaultHeaders?: Record<string, string>;
+    /** A custom `fetch` (proxies, tests). */
+    fetch?: Fetch;
+    /** Allow an API key in a browser. The key would be visible to anyone using the page, so
+     * only do this for internal tools; otherwise use an `accessToken`. */
+    dangerouslyAllowBrowser?: boolean;
+    /** Log requests and retries: `"debug"`, `"info"` or `"off"`. Defaults to `FINESSE_LOG`, then
+     * `"off"`. The API key, bodies and audio are never logged. */
+    logLevel?: LogLevel;
+    /** Where log lines go. Defaults to `console`. */
+    logger?: Logger;
+}
+type LogLevel = "debug" | "info" | "off";
+interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+}
+/** Per-call overrides that every request method accepts as its last argument. */
+interface RequestOptions {
+    /** Abort the request, its retries and any waiting. Rejects with the signal's reason. */
+    signal?: AbortSignal;
+    /** Timeout in ms for this call (for streams, the longest wait between chunks). */
+    timeout?: number;
+    /** Retries for this call. */
+    maxRetries?: number;
+    /** Extra headers for this call; they override the client's. */
+    headers?: Record<string, string>;
+}
+interface CallOptions extends RequestOptions {
+    /** Send one Idempotency-Key for every attempt, so the call can be retried like a read. */
+    idempotent?: boolean;
+    query?: Record<string, string | number>;
+    json?: unknown;
+    form?: () => FormData;
+    stream?: boolean;
+}
+declare class Core {
+    readonly apiKey: string | null;
+    readonly accessToken: string | null;
+    readonly baseURL: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly headers: Record<string, string>;
+    readonly fetch: Fetch;
+    readonly logLevel: LogLevel;
+    readonly logger: Logger;
+    /** @internal What this client learned about the server; shared by `withOptions` copies. */
+    readonly server: {
+        honoursIdempotencyKeys: boolean;
+    };
+    /** @internal Called with each successful response (used by `withRawResponse`). */
+    onResponse: ((response: Response) => void) | null;
+    constructor(options?: ClientOptions);
+    /** @internal A view of this core with other defaults, sharing everything else. */
+    withOptions(overrides: {
+        timeout?: number;
+        maxRetries?: number;
+        headers?: Record<string, string>;
+    }): Core;
+    private debug;
+    private info;
+    url(path: string, query?: Record<string, string | number>): string;
+    get wsBaseURL(): string;
+    /** Send a request, retrying transient failures, and throw on an error status. With
+     * `stream: true` the caller owns the response body. A caller `signal` stops the request and
+     * any further retries, and rejects with the signal's reason. */
+    request(method: string, path: string, opts?: CallOptions): Promise<Response>;
+    /** Request and decode a JSON success body, stripping the `{status, error, data}` envelope. */
+    json<T>(method: string, path: string, opts?: CallOptions): Promise<T>;
+}
+
+/** The parsed result of a call plus the HTTP response it came from. For calls that make several
+ * requests (`voices.list` walking pages, `cloneAndWait` polling), `response` is the first one. */
+interface RawResponse<T> {
+    data: T;
+    response: Response;
+    status: number;
+    headers: Headers;
+    /** The service's `X-Request-Id` for this request, when sent. */
+    requestId: string | null;
+}
+type Fn = (...args: never[]) => unknown;
+type RawMethods<R> = {
+    [M in keyof R as R[M] extends Fn ? (M extends "stream" ? never : M) : never]: R[M] extends (...args: infer A) => infer Ret ? (...args: A) => Promise<RawResponse<Awaited<Ret>>> : never;
+};
+interface Resources {
+    voices: object;
+    jobs: object;
+    speech: object;
+}
+/** `client.withRawResponse`: the same methods, each resolving to a {@link RawResponse}. */
+type RawClient<R extends Resources> = {
+    [K in keyof R]: RawMethods<R[K]>;
+};
+
+/**
+ * Errors thrown by the SDK. Every error extends {@link FinesseError}; HTTP errors extend
+ * {@link APIStatusError} and are split by status so you can catch exactly what you handle:
+ *
+ * ```ts
+ * try {
+ *   await client.speech.create({ voice_id, text: "Hi" });
+ * } catch (e) {
+ *   if (e instanceof PaymentRequiredError) console.log("Out of credits", e.billingRemaining);
+ * }
+ * ```
+ */
+declare class FinesseError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request never got a response: DNS, TLS, connection reset, and so on. */
+declare class APIConnectionError extends FinesseError {
+}
+/** The request timed out. */
+declare class APITimeoutError extends APIConnectionError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API answered with a 4xx or 5xx status. The API's three error body shapes are normalised:
+ *
+ * - `{"status": 404, "error": true, "message": "Voice not found", "code": "not_found"}`
+ * - `{"error": "insufficient_credits", "unit": "character", "limit": 100, "used": 100}`
+ * - `{"error": "plan limit reached", "feature": "max_voices", "limit": 3}`
+ */
+declare class APIStatusError extends FinesseError {
+    /** HTTP status. */
+    readonly status: number;
+    /** Machine-readable code. Branch on this, never on the message. Envelope codes:
+     * `invalid_request`, `unauthorized`, `key_expired`, `token_invalid`, `payment_required`,
+     * `forbidden`, `insufficient_scope`, `voice_not_allowed`, `not_found`, `conflict`,
+     * `idempotency_in_progress`, `payload_too_large`, `invalid_input`, `idempotency_key_reused`,
+     * `rate_limited`, `concurrency_limited`, `internal_error`, `upstream_error`, `upstream_busy`,
+     * `unavailable`; plan denials: `insufficient_credits`, `quota_exhausted`, `feature_disabled`,
+     * `plan_limit_reached`; realtime: `too_many_sessions`. `null` when absent. */
+    readonly code: string | null;
+    /** The decoded JSON body, or the raw text when it is not JSON. */
+    readonly body: unknown;
+    readonly headers: Headers;
+    /** `X-Billing-Remaining` as a number, when sent. */
+    readonly billingRemaining: number | null;
+    /** The service's `X-Request-Id` for the failed request; quote it to support. */
+    readonly requestId: string | null;
+    constructor(status: number, message: string, body: unknown, code: string | null, headers: Headers);
+    /** Seconds the server asked you to wait (`Retry-After`), when it sent one. */
+    get retryAfter(): number | null;
+    /** Plan limit from an entitlement or plan-limit denial, when present. */
+    get limit(): number | null;
+    /** Amount already used, from an entitlement denial, when present. */
+    get used(): number | null;
+}
+/** 400: invalid request (missing field, text too long, voice not enrolled, ...). */
+declare class BadRequestError extends APIStatusError {
+}
+/** 401: the API key is missing, unknown or revoked; `key_expired`; or a short-lived token is
+ * invalid, expired or already used (`token_invalid`). */
+declare class AuthenticationError extends APIStatusError {
+}
+/** 402: out of credits (`insufficient_credits`) or quota (`quota_exhausted`), or another
+ * payment problem (`payment_required`). */
+declare class PaymentRequiredError extends APIStatusError {
+}
+/** 403: the key lacks the route's scope (`insufficient_scope`), a token is limited to other
+ * voices (`voice_not_allowed`), the plan lacks the feature (`feature_disabled`), or a cap is
+ * reached (`plan_limit_reached`). */
+declare class PermissionDeniedError extends APIStatusError {
+    /** The capped feature for `plan_limit_reached`, e.g. `max_voices`. */
+    get feature(): string | null;
+}
+/** 404: no such resource, or not visible to this workspace. */
+declare class NotFoundError extends APIStatusError {
+}
+/** 409: e.g. a request with the same `Idempotency-Key` is still running. */
+declare class ConflictError extends APIStatusError {
+}
+/** 413: the request body is over 21 MiB (`payload_too_large`). */
+declare class PayloadTooLargeError extends APIStatusError {
+}
+/** 422: the synthesis service could not use the input (`invalid_input`), or an
+ * `Idempotency-Key` was reused for a different request (`idempotency_key_reused`). */
+declare class UnprocessableEntityError extends APIStatusError {
+}
+/** 429: over the plan's requests per second (`rate_limited`) or concurrent synthesis
+ * (`concurrency_limited`), or (realtime) `too_many_sessions`. Wait `retryAfter` seconds. */
+declare class RateLimitError extends APIStatusError {
+}
+/** 5xx: a server error, or the synthesis service failing (`upstream_error`, 502) or at
+ * capacity (`upstream_busy`, 503, with `retryAfter`). Usually safe to retry. */
+declare class InternalServerError extends APIStatusError {
+}
+/** A speech stream failed after it started. */
+declare class StreamError extends FinesseError {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/** A clone job ended without producing a ready voice. */
+declare class CloneFailedError extends FinesseError {
+    readonly job: {
+        id: string;
+        status: string;
+        error?: Record<string, unknown> | null;
+    };
+    constructor(job: {
+        id: string;
+        status: string;
+        error?: Record<string, unknown> | null;
+    });
+}
+/** Waiting for a clone job took longer than the timeout. The job may still finish. */
+declare class CloneTimeoutError extends FinesseError {
+    readonly jobId: string;
+    readonly timeoutMs: number;
+    constructor(jobId: string, timeoutMs: number);
+}
+
+/**
+ * Realtime speech over one WebSocket. One session is one socket; each turn of speech runs in a
+ * *context*, and a socket can run several contexts at once (up to 4). Audio arrives as raw PCM,
+ * `s16le` at 24 kHz unless you ask for something else.
+ *
+ * ```ts
+ * const rt = await client.realtime.connect();
+ * for await (const event of rt.say({ voice_id, text: "Hello there." })) {
+ *   if (event.type === "audio") play(event.pcm);
+ * }
+ * await rt.close();
+ * ```
+ *
+ * In Node this needs the `ws` package (`npm i ws`), which sends the API key as a header. Bun's
+ * built-in WebSocket does too, and so does Deno's from 2.5.
+ *
+ * In a browser, never use the API key: mint a short-lived token on your server
+ * (`tokens.create`) and connect with `{ accessToken }` or `{ getAccessToken }`. The token rides
+ * in the WebSocket subprotocol list (`["finesse.v1", token]`), the one place a browser can put
+ * a credential on a handshake. (With a key, browsers and Deno before 2.5 fall back to a
+ * deprecated URL parameter, and the SDK logs a warning once.)
+ */
+
+/** A realtime context or session failed. */
+declare class RealtimeError extends FinesseError {
+    /** Per context: `voice_not_found`, `voice_not_allowed` (the token is limited to other
+     * voices), `invalid_request` (a parameter out of range), a `task_failed` code. Whole session:
+     * `insufficient_credits`, `upstream_unavailable` (the engine could not be reached),
+     * `upstream_busy` (it is at capacity), `upstream_error`, `upstream_closed`,
+     * `connection_lost`, `token_spent`, ... */
+    readonly code: string;
+    /** The context it applies to, or `null` for the whole session. */
+    readonly contextId: string | null;
+    /** The WebSocket close code, when the socket closed. */
+    closeCode: number | null;
+    constructor(code: string, message?: string, options?: {
+        contextId?: string | null;
+        closeCode?: number | null;
+    });
+    /** Whether reconnecting and trying again can succeed. */
+    get retryable(): boolean;
+}
+interface TaskStarted {
+    type: "task_started";
+    context_id: string;
+    sample_rate?: number;
+    audio_format?: string;
+}
+interface AudioEvent {
+    type: "audio";
+    context_id: string;
+    /** Raw PCM in the context's `audio_format` / `sample_rate`. */
+    pcm: Uint8Array;
+    sample_rate: number | null;
+    audio_format: string | null;
+    sentence_index?: number;
+    chunk_index?: number;
+    audio_duration_s?: number;
+}
+interface SentenceDone {
+    type: "sentence_done";
+    context_id: string;
+    sentence_index?: number;
+    text?: string;
+    audio_duration_s?: number;
+}
+/** The context finished. Last event of a context. */
+interface TaskDone {
+    type: "task_done";
+    context_id: string;
+    num_sentences?: number;
+    total_audio_duration_s?: number;
+    profile?: Record<string, unknown>;
+    trace_id?: string;
+}
+/** The context was cancelled. Last event of a cancelled context. */
+interface TaskCancelled {
+    type: "task_cancelled";
+    context_id: string;
+    sentences_completed?: number;
+    sentences_dropped?: number;
+    trace_id?: string;
+}
+/** An engine event this SDK version does not know yet. `event_type` is its `type` on the wire
+ * and `data` the whole frame. */
+interface UnknownEvent {
+    type: "unknown";
+    context_id: string;
+    event_type: string;
+    data: Record<string, unknown>;
+}
+/** Every event a context yields. Narrow it on `type`. */
+type RealtimeEvent = TaskStarted | AudioEvent | SentenceDone | TaskDone | TaskCancelled | UnknownEvent;
+interface ContextOptions {
+    /** One of your voices or a public platform voice. */
+    voice_id: string;
+    context_id?: string;
+    language?: string;
+    /** `s16le` (default), `s24le`, `s32le`, `f32le`, `f64le`, `opus`, or `mulaw` (G.711 µ-law
+     * for telephony, with `sample_rate: 8000`). */
+    output_format?: "s16le" | "s24le" | "s32le" | "f32le" | "f64le" | "opus" | "mulaw";
+    /** Output rate in Hz, 8000-48000; the native rate is 24000. 8000 is produced as asked, other
+     * lower values still produce 24000. */
+    sample_rate?: number;
+    /** Generation steps, 1-32 (default 32); fewer is faster. Values over 32 are capped. */
+    num_step?: number;
+    guidance_scale?: number;
+    /** Speaking rate. */
+    length_scale?: number;
+    /** Speak a pending sentence after this many ms without new text. */
+    idle_flush_ms?: number;
+}
+interface ConnectOptions {
+    /** Reconnect on the next context after a retryable drop. Default true. */
+    autoReconnect?: boolean;
+    /** Ms to open the socket. Default 60 000. */
+    openTimeout?: number;
+    /** A short-lived token (`fin_tok_...`) for this session instead of the API key (defaults to
+     * the client's `accessToken`). Single use: the handshake spends it, so pass
+     * `getAccessToken` too if the session should reconnect. */
+    accessToken?: string;
+    /** Returns a fresh token, e.g. from your own backend running `tokens.create`. Used for the
+     * first handshake when there is no `accessToken`, and for every reconnect. */
+    getAccessToken?: () => string | Promise<string>;
+    /** A WebSocket implementation (defaults to the `ws` package in Node, the global elsewhere). */
+    WebSocket?: unknown;
+}
+/**
+ * One turn of speech. Create it with {@link RealtimeSession.context}. `send` text (the first
+ * call opens the context), `finish` when the turn's text is complete, and iterate it for its
+ * events. Iteration ends after `task_done` or `task_cancelled`, and throws
+ * {@link RealtimeError} if the context fails.
+ *
+ * Events are buffered without limit so that one slow context never stalls the others on the
+ * same socket. Iterate every context you start, or `cancel()` the ones you abandon. Iterate a
+ * context from one place only: events are consumed as they are read.
+ */
+declare class RealtimeContext implements AsyncIterable<RealtimeEvent> {
+    private readonly session;
+    /** @internal */ readonly options: Record<string, unknown>;
+    readonly id: string;
+    cancelled: boolean;
+    sampleRate: number | null;
+    audioFormat: string | null;
+    /** @internal */ started: boolean;
+    /** @internal The socket this context runs on. */ socket: unknown;
+    /** @internal */ ended: boolean;
+    private finished;
+    private readonly items;
+    private waiter;
+    private sending;
+    constructor(session: RealtimeSession, 
+    /** @internal */ options: Record<string, unknown>, id: string);
+    /** Send text. Text is billed per character as it is sent. Pass `{ finalize: true }` with the
+     * turn's last text (or call {@link finish}). */
+    send(text: string, options?: {
+        finalize?: boolean;
+    }): Promise<void>;
+    /** No more text for this turn: speak what is buffered, then end the context. */
+    finish(): Promise<void>;
+    /** Stop this context now. Audio still in flight for it is dropped; iterating it ends with
+     * `task_cancelled`. */
+    cancel(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<RealtimeEvent>;
+    /** Iterate only the PCM of this context. */
+    audio(): AsyncGenerator<Uint8Array>;
+    /** @internal */
+    _put(event: RealtimeEvent): void;
+    /** @internal */
+    _fail(error: RealtimeError): void;
+    /** @internal */
+    _end(): void;
+    private push;
+    private serial;
+}
+/**
+ * A realtime session. Get one with `await client.realtime.connect()` and `close()` it when done.
+ * After a retryable drop the next context reconnects automatically (unless
+ * `autoReconnect: false`); contexts running at the time fail with {@link RealtimeError}.
+ */
+declare class RealtimeSession {
+    private readonly core;
+    private readonly options;
+    private ws;
+    private opening;
+    private readonly contexts;
+    private pendingAudio;
+    private fatal;
+    private error;
+    private openedOnce;
+    private closed;
+    private closedWaiters;
+    private readonly staticToken;
+    private tokenSpent;
+    constructor(core: Core, options?: ConnectOptions);
+    get url(): string;
+    get isOpen(): boolean;
+    /**
+     * Open the socket (no-op when open). Throws `AuthenticationError`, `PaymentRequiredError` or
+     * `PermissionDeniedError` when the handshake is refused, `RateLimitError` with
+     * `code === "too_many_sessions"` when the workspace already has its maximum of sessions,
+     * and `APIConnectionError` / `APITimeoutError` when the service can't be reached.
+     */
+    open(): Promise<void>;
+    /** Create a context. Nothing is sent until its first `send`. */
+    context(options: ContextOptions): RealtimeContext;
+    /** Speak `text` as one complete turn and yield its events. Breaking out of the loop cancels
+     * the turn. */
+    say(options: ContextOptions & {
+        text: string;
+    }): AsyncGenerator<RealtimeEvent>;
+    /** End the session: tell the service, then close the socket. */
+    close(): Promise<void>;
+    /** @internal */
+    _start(ctx: RealtimeContext, text: string, finalize: boolean): Promise<void>;
+    /** @internal */
+    _send(msg: Record<string, unknown>): void;
+    /** @internal Send a `task_start` / `task_continue` frame with `text`. Text that would make
+     * the frame larger than {@link MAX_FRAME_BYTES} is split across `task_continue` frames for
+     * the same context; only the last one carries `finalize`. */
+    _sendText(msg: Record<string, unknown>, text: string, finalize: boolean): void;
+    /** @internal */
+    _forget(ctx: RealtimeContext): void;
+    /** The token for the next handshake, or `null` to use the API key. A static token is used
+     * first; once a handshake has spent it, `getAccessToken` supplies one per reconnect. */
+    private nextToken;
+    private dial;
+    private onClose;
+    private onAudio;
+    private onMessage;
+}
+/** `client.realtime`: open realtime sessions. */
+declare class Realtime {
+    private readonly core;
+    constructor(core: Core);
+    /** Open a session. */
+    connect(options?: ConnectOptions): Promise<RealtimeSession>;
+    /** Create a session without opening it; it opens on first use. */
+    session(options?: ConnectOptions): RealtimeSession;
+}
+
+/** Response shapes. Field names match the API (snake_case); timestamps are Unix milliseconds.
+ * Media URLs (`original_audio_url`, `sample_audio_url`, `avatar_url`, `audio_url`) may be
+ * short-lived signed URLs: download them promptly, or fetch the object again for a fresh one. */
+interface VoiceSettings {
+    stability?: number;
+    similarity?: number;
+    style?: number;
+    speed?: number;
+    pitch?: number;
+    volume?: number;
+    use_speaker_boost?: boolean;
+    emotion?: string;
+    engine_params?: Record<string, unknown>;
+}
+/** A voice. It can synthesize once `status === "ready"`. */
+interface Voice {
+    id: string;
+    org_id: string;
+    name: string;
+    /** `draft`, `processing`, `ready`, `failed`, ... */
+    status: string;
+    clone_method: string;
+    /** `private` for your voices, `public` for platform catalog voices. */
+    visibility: string;
+    primary_language: string;
+    description?: string;
+    model?: string;
+    /** Human-friendly handle, also usable as `voice` on the OpenAI-compatible endpoint. */
+    alias?: string;
+    source?: string;
+    language?: string;
+    gender?: string;
+    /** Labels as a plain object (the API sends `[{key, value}]`; the SDK converts it). */
+    labels: Record<string, string>;
+    settings?: VoiceSettings;
+    external_ref?: string;
+    original_audio_url?: string;
+    sample_audio_url?: string;
+    avatar_url?: string;
+    base_voice_id?: string;
+    created_at?: number;
+    updated_at?: number;
+    last_used_at?: number;
+    expires_at?: number;
+    /** Prefix of the API key that created the voice; only on your own voices. */
+    created_via_key_prefix?: string;
+    [key: string]: unknown;
+}
+/** An asynchronous clone job. */
+interface CloneJob {
+    id: string;
+    org_id: string;
+    /** `pending`, `running`, `succeeded`, `failed`, `cancelled` or `expired`. */
+    status: string;
+    job_type: string;
+    voice_id?: string;
+    /** Percent complete. Not updated while running; 100 once succeeded. */
+    progress: number;
+    attempts: number;
+    /** Failure detail, `{message, status_code}`. */
+    error?: Record<string, unknown> | null;
+    started_at?: number;
+    finished_at?: number;
+    created_at?: number;
+    [key: string]: unknown;
+}
+/** What `voices.clone` / `voices.enroll` return: the voice (`processing`) and its job id. */
+interface CloneResult {
+    voice: Voice;
+    job_id: string;
+}
+/** A synthesized clip from `speech.create`. */
+interface Audio {
+    data: Uint8Array;
+    /** `audio/wav` for WAV, `application/octet-stream` for raw PCM. */
+    contentType: string;
+    sampleRate: number | null;
+    /** Id of the generation history record (when object storage is enabled). */
+    generationId: string | null;
+    /** The stored clip, when object storage is enabled; may be a short-lived signed URL. */
+    audioURL: string | null;
+    billingRemaining: number | null;
+}
+/** One chunk of raw PCM from `speech.stream`. */
+interface AudioChunk {
+    pcm: Uint8Array;
+    sampleRate: number | null;
+    /** PCM encoding, e.g. `s16le`. */
+    audioFormat: string | null;
+    index: number | null;
+}
+/** The final event of `speech.stream`. */
+interface StreamDone {
+    audio_duration_s?: number;
+    generation_id?: string;
+    audio_url?: string;
+}
+/** `wav` (one-shot default) or raw little-endian PCM. */
+/** A short-lived, single-use token from `tokens.create`. Hand `token` to a browser or device:
+ * it is good for one `speech.create` / `speech.stream` call or one realtime session, carries
+ * the `tts` scope only, and dies when the key that minted it is revoked or expires. */
+interface AccessToken {
+    token: string;
+    /** Unix epoch ms. */
+    expires_at: number;
+    ttl_seconds: number;
+}
+/** `mulaw` is raw G.711 µ-law for telephony and needs `sample_rate: 8000`. */
+type OutputFormat = "wav" | "s16le" | "s24le" | "s32le" | "f32le" | "f64le" | "mulaw";
+interface SpeechParams {
+    /** One of your voices or a public platform voice; it must be ready. */
+    voice_id: string;
+    /** At most 10,000 characters. Billed per character. */
+    text: string;
+    language?: string;
+    output_format?: OutputFormat;
+    /** Output rate in Hz, 8000-48000. The native rate is 24000; 8000 is produced as asked, other
+     * lower values still return 24000. */
+    sample_rate?: number;
+    /** Generation steps, 1-32 (default and maximum 32; over 32 is a 400); fewer is faster. */
+    num_step?: number;
+}
+declare const isReady: (voice: Voice) => boolean;
+
+interface WaitOptions {
+    /** Give up after this many ms. Default 300 000 (the first clone after the cloner has been
+     * idle can take a couple of minutes). */
+    timeout?: number;
+    /** Poll every this many ms. Default 2 000. */
+    pollInterval?: number;
+    /** Called with the job after every poll. */
+    onUpdate?: (job: CloneJob) => void;
+    /** Stop waiting (rejects with the signal's reason). The job itself keeps running. */
+    signal?: AbortSignal;
+}
+/** Clone jobs started by `voices.clone` and `voices.enroll`. */
+declare class Jobs {
+    private readonly core;
+    constructor(core: Core);
+    get(jobId: string, options?: RequestOptions): Promise<CloneJob>;
+    /** Poll until the job finishes and return it. Throws {@link CloneFailedError} if it ends
+     * `failed`, `cancelled` or `expired`, and {@link CloneTimeoutError} on timeout. */
+    wait(jobId: string, options?: WaitOptions): Promise<CloneJob>;
+}
+
+/** Speech streamed as raw PCM chunks: `for await (const chunk of stream)`. `done` is set once
+ * it finishes. The request is sent when iteration starts. Errors before the stream starts
+ * throw the usual `APIStatusError`; failures after it throw {@link StreamError}. */
+declare class SpeechStream implements AsyncIterable<AudioChunk> {
+    private readonly core;
+    private readonly path;
+    private readonly json;
+    private readonly options;
+    sampleRate: number | null;
+    audioFormat: string | null;
+    /** Final event (duration, generation id, stored clip URL), once the stream finished. */
+    done: StreamDone | null;
+    billingRemaining: number | null;
+    private consumed;
+    constructor(core: Core, path: string, json: Record<string, unknown>, options?: RequestOptions);
+    [Symbol.asyncIterator](): AsyncIterator<AudioChunk>;
+    /** Consume the stream and return all PCM joined together. */
+    readAll(): Promise<Uint8Array>;
+    private handle;
+}
+/** Text-to-speech. */
+declare class Speech {
+    private readonly core;
+    constructor(core: Core);
+    /** Synthesize `text` and return the whole clip (`wav` unless `output_format` says otherwise). */
+    create(params: SpeechParams, options?: RequestOptions): Promise<Audio>;
+    /** Stream speech as raw PCM chunks (`s16le` unless `output_format` says otherwise):
+     *
+     * ```ts
+     * for await (const chunk of client.speech.stream({ voice_id, text: "Hello" })) play(chunk.pcm);
+     * ```
+     */
+    stream(params: SpeechParams, options?: RequestOptions): SpeechStream;
+}
+
+interface CreateTokenParams {
+    /** How long the token stays valid if unused, 10-3600 seconds. Default 300. */
+    ttl_seconds?: number;
+    /** Limit the token to these voices (yours or public platform voices). */
+    voice_ids?: string[];
+}
+/** Short-lived tokens, so a browser or device can synthesize without your API key. */
+declare class Tokens {
+    private readonly core;
+    constructor(core: Core);
+    /** Mint a single-use token. Call this on your server with an API key that has the `tts`
+     * scope, and send only the token to the client:
+     *
+     * ```ts
+     * const { token } = await client.tokens.create({ ttl_seconds: 60, voice_ids: [voiceId] });
+     * ```
+     */
+    create(params?: CreateTokenParams, options?: RequestOptions): Promise<AccessToken>;
+}
+
+/** A reference clip: a `Blob`/`File`, raw bytes, or `{ data, filename, contentType }`.
+ * In Node, `await fileFromPath("ref.wav")` reads a file from disk. */
+type FileInput = Blob | Uint8Array | ArrayBuffer | {
+    data: Blob | Uint8Array | ArrayBuffer;
+    filename?: string;
+    contentType?: string;
+};
+/** Node only: read a file from disk into a {@link FileInput}. */
+declare function fileFromPath(path: string): Promise<FileInput>;
+
+interface ListVoicesParams {
+    /** 1-based page. Default 1. */
+    page?: number;
+    /** Voices per page, at most 100. Default 50. */
+    page_size?: number;
+}
+interface CreateVoiceParams {
+    name: string;
+    description?: string;
+    language?: string;
+    labels?: Record<string, string>;
+    model?: string;
+}
+interface UpdateVoiceParams {
+    name?: string;
+    description?: string;
+    language?: string;
+    /** Replaces the whole label set (`{}` clears it). */
+    labels?: Record<string, string>;
+}
+/** Cloning requires `consent: true`: you attest that you are the speaker or hold their explicit
+ * permission to clone their voice. The attestation is recorded on the voice. */
+interface ConsentParams {
+    consent: true;
+}
+interface CloneVoiceParams extends ConsentParams {
+    name: string;
+    /** Reference clip, at most 20 MiB: at least 10 s of clear speech (10-30 s works best). */
+    file: FileInput;
+    description?: string;
+    language?: string;
+    labels?: Record<string, string>;
+    /** Transcript of the reference clip, at most 4000 characters. */
+    ref_text?: string;
+    remove_background_noise?: boolean;
+}
+interface EnrollVoiceParams extends ConsentParams {
+    /** Reference clip, at most 20 MiB: at least 10 s of clear speech (10-30 s works best). */
+    file: FileInput;
+    /** Transcript of the reference clip, at most 4000 characters. */
+    ref_text?: string;
+    language?: string;
+}
+/** One page of voices. `for await (const voice of page)` walks this page and every page after
+ * it, fetching as needed. */
+declare class VoicePage implements AsyncIterable<Voice> {
+    private readonly fetchPage;
+    readonly voices: Voice[];
+    readonly page: number;
+    readonly page_size: number;
+    readonly total: number;
+    readonly has_more: boolean;
+    constructor(data: Record<string, unknown>, fetchPage: (page: number) => Promise<VoicePage>);
+    nextPage(): Promise<VoicePage>;
+    iterPages(): AsyncGenerator<VoicePage>;
+    [Symbol.asyncIterator](): AsyncIterator<Voice>;
+}
+/** What `voices.list()` returns: `await` it for the first page, or iterate it directly with
+ * `for await` to walk every voice. The first page is fetched once, on first use. */
+declare class VoicePagePromise implements PromiseLike<VoicePage>, AsyncIterable<Voice> {
+    private readonly load;
+    private first;
+    constructor(load: () => Promise<VoicePage>);
+    private page;
+    then<A = VoicePage, B = never>(onfulfilled?: ((value: VoicePage) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<VoicePage | B>;
+    finally(onfinally?: (() => void) | null): Promise<VoicePage>;
+    [Symbol.asyncIterator](): AsyncIterator<Voice>;
+}
+/** Create, list, clone and manage voices. */
+declare class Voices {
+    private readonly core;
+    private readonly jobs;
+    constructor(core: Core, jobs: Jobs);
+    /** Your voices (newest first), then the public platform voices.
+     * `for await (const voice of client.voices.list())` walks every page;
+     * `await client.voices.list()` returns just the first page. */
+    list(params?: ListVoicesParams, options?: RequestOptions): VoicePagePromise;
+    /** One of your voices or a public platform voice. */
+    get(voiceId: string, options?: RequestOptions): Promise<Voice>;
+    /** Create an empty `draft` voice. Give it a clip with {@link enroll}, or use {@link clone}. */
+    create(params: CreateVoiceParams, options?: RequestOptions): Promise<Voice>;
+    /** Change a voice's metadata. Only the fields you pass change. */
+    update(voiceId: string, params: UpdateVoiceParams, options?: RequestOptions): Promise<Voice>;
+    /** Delete one of your voices. */
+    delete(voiceId: string, options?: RequestOptions): Promise<void>;
+    /** Create a voice from a reference clip. Returns at once with the voice in `processing` and a
+     * `job_id`; see {@link waitUntilReady} or {@link cloneAndWait}. Requires `consent: true`. */
+    clone(params: CloneVoiceParams, options?: RequestOptions): Promise<CloneResult>;
+    /** Clone a reference clip into an existing voice of yours. Returns at once. Requires
+     * `consent: true`. */
+    enroll(voiceId: string, params: EnrollVoiceParams, options?: RequestOptions): Promise<CloneResult>;
+    /** Wait for a clone job to finish and return the voice, now `ready`. */
+    waitUntilReady(clone: CloneResult, options?: WaitOptions): Promise<Voice>;
+    /** {@link clone}, then {@link waitUntilReady}. Returns the ready voice. */
+    cloneAndWait(params: CloneVoiceParams, options?: WaitOptions): Promise<Voice>;
+}
+
+interface FinesseResources {
+    voices: Voices;
+    jobs: Jobs;
+    speech: Speech;
+    tokens: Tokens;
+}
+/**
+ * Client for the Finesse API.
+ *
+ * ```ts
+ * import { Finesse } from "@flamai/finesse";
+ *
+ * const client = new Finesse(); // reads FINESSE_API_KEY
+ * const audio = await client.speech.create({ voice_id: "665f1a2b3c4d5e6f7a8b9c0d", text: "Hello!" });
+ * ```
+ */
+declare class Finesse {
+    readonly voices: Voices;
+    readonly jobs: Jobs;
+    readonly speech: Speech;
+    readonly tokens: Tokens;
+    readonly realtime: Realtime;
+    /** @internal */
+    readonly _core: Core;
+    constructor(options?: ClientOptions | {
+        _core: Core;
+    });
+    get baseURL(): string;
+    /** A copy of this client with different defaults. Cheap: it shares everything else. */
+    withOptions(options: {
+        timeout?: number;
+        maxRetries?: number;
+        defaultHeaders?: Record<string, string>;
+    }): Finesse;
+    /** The same calls, each resolving to `{ data, response, status, headers, requestId }`:
+     *
+     * ```ts
+     * const { data: voice, requestId } = await client.withRawResponse.voices.get(id);
+     * ```
+     */
+    get withRawResponse(): RawClient<FinesseResources>;
+}
+
+declare const VERSION = "0.1.2";
+
+export { APIConnectionError, APIStatusError, APITimeoutError, type AccessToken, type Audio, type AudioChunk, type AudioEvent, AuthenticationError, BadRequestError, type ClientOptions, CloneFailedError, type CloneJob, type CloneResult, CloneTimeoutError, type CloneVoiceParams, ConflictError, type ConnectOptions, type ConsentParams, type ContextOptions, type CreateTokenParams, type CreateVoiceParams, type EnrollVoiceParams, type FileInput, Finesse, FinesseError, InternalServerError, type ListVoicesParams, type LogLevel, type Logger, NotFoundError, type OutputFormat, PayloadTooLargeError, PaymentRequiredError, PermissionDeniedError, RateLimitError, type RawClient, type RawResponse, RealtimeContext, RealtimeError, type RealtimeEvent, RealtimeSession, type RequestOptions, type SentenceDone, type SpeechParams, SpeechStream, type StreamDone, StreamError, type TaskCancelled, type TaskDone, type TaskStarted, type UnknownEvent, UnprocessableEntityError, type UpdateVoiceParams, VERSION, type Voice, VoicePage, VoicePagePromise, type VoiceSettings, type WaitOptions, fileFromPath, isReady };