@flamai/finesse 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -234,6 +234,151 @@ declare class CloneTimeoutError extends FinesseError {
     constructor(jobId: string, timeoutMs: number);
 }
 
+/** 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;
+}
+/** A direct realtime session from `realtime.sessions.create`: a socket straight to the
+ * synthesis GPU in your account's server region. Pass it to `realtime.connect({ session })`. */
+interface DirectSession {
+    session_id: string;
+    /** The GPU's WebSocket URL. Connect to it as returned. */
+    url: string;
+    /** The subprotocol to offer first (`finesse.v1`). */
+    protocol: string;
+    /** Single-use `ft1.` token, offered as the second subprotocol. */
+    token: string;
+    /** RFC 3339 time by which the socket must open (60 s after creation). */
+    connect_by: string;
+    /** The longest the session can run once connected. */
+    ttl_seconds: number;
+    /** Characters reserved for the session; it cannot synthesize more. */
+    budget_chars: number;
+    /** GPU region the session runs in: `ap-south` or `us-east`. */
+    region: string;
+    /** The only voices the session can use. */
+    voices: string[];
+}
+/** `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;
+
 /**
  * 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,
@@ -255,6 +400,11 @@ declare class CloneTimeoutError extends FinesseError {
  * 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.)
+ *
+ * For the lowest latency, run a *direct session*: the socket goes straight to the synthesis GPU
+ * in your account's server region instead of through the API. Create one on your server with
+ * `realtime.sessions.create` and connect with `{ session }` or `{ getSession }`. The messages
+ * and events are the same.
  */
 
 /** A realtime context or session failed. */
@@ -263,7 +413,8 @@ declare class RealtimeError extends FinesseError {
      * 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`, ... */
+     * `connection_lost`, `token_spent`, `session_spent`, `session_expired`, `unauthorized` (a
+     * direct session's token was refused), ... */
     readonly code: string;
     /** The context it applies to, or `null` for the whole session. */
     readonly contextId: string | null;
@@ -332,10 +483,11 @@ interface ContextOptions {
     voice_id: string;
     context_id?: string;
     language?: string;
-    /** `s16le` (default), `s24le`, `s32le`, `f32le`, `f64le` or `opus`. */
-    output_format?: "s16le" | "s24le" | "s32le" | "f32le" | "f64le" | "opus";
-    /** Output rate in Hz, 8000-48000; the native rate is 24000 and lower values still produce
-     * 24000. */
+    /** `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;
@@ -357,9 +509,23 @@ interface ConnectOptions {
     /** 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 direct session from `realtime.sessions.create`, usually created by your server. Its token
+     * is single use, so pass `getSession` too if the session should reconnect. */
+    session?: DirectSession;
+    /** Returns a new direct session, e.g. `() => client.realtime.sessions.create({ voice_ids })`
+     * on a server, or a call to your own backend in a browser. Used for the first handshake when
+     * there is no `session`, and for every reconnect. */
+    getSession?: () => DirectSession | Promise<DirectSession>;
     /** A WebSocket implementation (defaults to the `ws` package in Node, the global elsewhere). */
     WebSocket?: unknown;
 }
+interface CreateDirectSessionParams {
+    /** The voices the session may use: 1 to 16 of your voices or public platform voices. */
+    voice_ids: string[];
+    /** Characters to reserve, 1-200000 (default 20000). Unused characters are returned when the
+     * session ends. If the balance can't cover it, 1000 are reserved instead. */
+    budget_chars?: number;
+}
 /**
  * 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
@@ -427,8 +593,15 @@ declare class RealtimeSession {
     private closedWaiters;
     private readonly staticToken;
     private tokenSpent;
+    private readonly directMode;
+    private staticSessionSpent;
+    private current;
     constructor(core: Core, options?: ConnectOptions);
+    /** Where the socket connects: the API's `/stream`, or a direct session's GPU URL. */
     get url(): string;
+    /** The direct session the socket runs on (its region and budget), or `null` when the session
+     * goes through the API. */
+    get directSession(): DirectSession | null;
     get isOpen(): boolean;
     /**
      * Open the socket (no-op when open). Throws `AuthenticationError`, `PaymentRequiredError` or
@@ -459,142 +632,52 @@ declare class RealtimeSession {
     /** 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;
+    /** The direct session for the next handshake. Like a token, a static session is used first;
+     * once a handshake has spent it, `getSession` supplies one per reconnect. */
+    private nextSession;
     private dial;
     private onClose;
     private onAudio;
     private onMessage;
 }
+/** `client.realtime.sessions`: direct sessions, which run straight against the synthesis GPU. */
+declare class DirectSessions {
+    private readonly core;
+    constructor(core: Core);
+    /** Create a direct session. Call this on your server with an API key that has the `tts`
+     * scope; it reserves `budget_chars` from your balance now. Connect within 60 s
+     * (`connect_by`), with `realtime.connect({ session })`, or hand `url`, `protocol` and `token`
+     * to a browser:
+     *
+     * ```ts
+     * const session = await client.realtime.sessions.create({ voice_ids: [voiceId] });
+     * const rt = await client.realtime.connect({ session });
+     * ```
+     */
+    create(params: CreateDirectSessionParams, options?: RequestOptions): Promise<DirectSession>;
+}
 /** `client.realtime`: open realtime sessions. */
 declare class Realtime {
     private readonly core;
+    /** Direct sessions: lower latency, straight to the GPU. */
+    readonly sessions: DirectSessions;
     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;
-}
-type OutputFormat = "wav" | "s16le" | "s24le" | "s32le" | "f32le" | "f64le";
-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; 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;
+/**
+ * Open a direct session without a client, for a browser or device that holds no API key. Your
+ * server creates the session (`realtime.sessions.create`) and returns it; `getSession` fetches a
+ * new one for each reconnect.
+ *
+ * ```ts
+ * const getSession = async () => (await fetch("/api/finesse-session", { method: "POST" })).json();
+ * const rt = await connectDirect({ getSession });
+ * ```
+ */
+declare function connectDirect(options: Omit<ConnectOptions, "accessToken" | "getAccessToken">): Promise<RealtimeSession>;
 
 interface WaitOptions {
     /** Give up after this many ms. Default 300 000 (the first clone after the cloner has been
@@ -823,6 +906,6 @@ declare class Finesse {
     get withRawResponse(): RawClient<FinesseResources>;
 }
 
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.2.0";
 
-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 };
+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 CreateDirectSessionParams, type CreateTokenParams, type CreateVoiceParams, type DirectSession, 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, connectDirect, fileFromPath, isReady };