@lumavox/client 0.0.0-stage → 0.1.1

package/dist/gen/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@lumavox/client`: agents from an end user's device — a browser, a React
+ * Native app, Node — with their ephemeral key. Conversations on the agent's
+ * socket (`client.connect`), and the agent's REST routes: sessions, facts,
+ * relations. Bodies, answers and frames are the wire's, snake_case,
+ * typed from the published OpenAPI document (`src/gen/`) and the edge's
+ * vocabulary (`src/protocol.gen.ts`); methods are camelCase, and the SDK's
+ * own options go last.
+ */
+export type { AgentAudio } from "./audio.js";
+export { type Client, type ClientOptions, createClient, DEFAULT_BASE_URL, type Facts, type RelationListParams, type Relations, type SessionGetParams, type SessionListParams, type Sessions, } from "./client.js";
+export { type CloseInfo, type ConnectOptions, Conversation, type ConversationHandlers, type ConversationState, type Disconnect, type Dropped, READY_DEADLINE_MS, type Snapshot, type StartAudioOptions, type TranscriptOutcome, type TurnOptions, type TurnOutcome, type TurnSnapshot, } from "./conversation.js";
+export { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, type PlatformErrorInit, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export type * from "./events.js";
+export type * from "./gen/index.js";
+export { concatPcm, floatToPcm16, LITTLE_ENDIAN, pcm16ToFloat, pcmSeconds, resample, } from "./pcm.js";
+export * from "./protocol.gen.js";
+export { type AudioFrame, closeName, isFinalClose, MAX_RECONNECTS, type Reconnect, reconnectAfter, type Warning, type WebSocketConstructor, type WebSocketLike, } from "./socket.js";
+export type { GetToken, TokenRequest } from "./token.js";
+export type { Fetch, RequestOptions } from "./transport.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@lumavox/client`: agents from an end user's device — a browser, a React
+ * Native app, Node — with their ephemeral key. Conversations on the agent's
+ * socket (`client.connect`), and the agent's REST routes: sessions, facts,
+ * relations. Bodies, answers and frames are the wire's, snake_case,
+ * typed from the published OpenAPI document (`src/gen/`) and the edge's
+ * vocabulary (`src/protocol.gen.ts`); methods are camelCase, and the SDK's
+ * own options go last.
+ */
+export { createClient, DEFAULT_BASE_URL, } from "./client.js";
+export { Conversation, READY_DEADLINE_MS, } from "./conversation.js";
+export { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export { concatPcm, floatToPcm16, LITTLE_ENDIAN, pcm16ToFloat, pcmSeconds, resample, } from "./pcm.js";
+export * from "./protocol.gen.js";
+export { closeName, isFinalClose, MAX_RECONNECTS, reconnectAfter, } from "./socket.js";

package/dist/pcm.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Raw PCM in and out: the wire's audio is 16-bit signed little-endian,
+ * mono, with no header (the docs' WebSocket page, *Audio out*). The SDK
+ * captures and plays nothing in v1 — a recorder hands it samples, a player
+ * takes them — so these are the conversions between the two and the wire,
+ * each tree-shaken away when unused.
+ *
+ * **Byte order is checked once, here.** Every device the SDK runs on is
+ * little-endian, so a typed array's bytes are the wire's bytes, and the
+ * fast path is a view; a big-endian one goes through a `DataView`.
+ */
+export declare const LITTLE_ENDIAN: boolean;
+/** Float samples in [-1, 1] to 16-bit samples, clamped. */
+export declare function floatToPcm16(samples: Float32Array): Int16Array;
+/**
+ * The wire's PCM as float samples in [-1, 1]. An odd trailing byte — half a
+ * sample — is dropped: `Int16Array` throws on a buffer that holds one.
+ */
+export declare function pcm16ToFloat(pcm: ArrayBuffer | Int16Array): Float32Array;
+/**
+ * Samples at `from` Hz resampled to `to` Hz, linearly: a 48 kHz microphone
+ * is not a rate the socket accepts (`RECORDING_RATES`), and speech loses
+ * nothing a transcriber needs by it.
+ */
+export declare function resample(samples: Float32Array, from: number, to: number): Float32Array;
+/** Pieces of PCM as one buffer: the frames of a reply, to save or replay. */
+export declare function concatPcm(pieces: readonly (ArrayBuffer | ArrayBufferView)[]): ArrayBuffer;
+/** How long PCM lasts: its bytes (or a buffer of them) at `rate` Hz. */
+export declare function pcmSeconds(pcm: number | ArrayBuffer | ArrayBufferView, rate: number, channels?: number): number;
+/**
+ * Samples as the wire's bytes, as an `ArrayBuffer` — what every runtime's
+ * `WebSocket.send` takes (`socket.ts`, `WebSocketLike`). A buffer as it is,
+ * since it already holds the wire's bytes; a typed array's own buffer on a
+ * little-endian device, never copied, when the array is the whole of an
+ * unshared one — what a recorder hands over. A view onto part of a buffer,
+ * or onto a shared one, is copied: one pass over its bytes.
+ */
+export declare function wireBytes(pcm: ArrayBuffer | Int16Array): ArrayBuffer;

package/dist/pcm.js

@@ -0,0 +1,110 @@
+/**
+ * Raw PCM in and out: the wire's audio is 16-bit signed little-endian,
+ * mono, with no header (the docs' WebSocket page, *Audio out*). The SDK
+ * captures and plays nothing in v1 — a recorder hands it samples, a player
+ * takes them — so these are the conversions between the two and the wire,
+ * each tree-shaken away when unused.
+ *
+ * **Byte order is checked once, here.** Every device the SDK runs on is
+ * little-endian, so a typed array's bytes are the wire's bytes, and the
+ * fast path is a view; a big-endian one goes through a `DataView`.
+ */
+export const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+/** Float samples in [-1, 1] to 16-bit samples, clamped. */
+export function floatToPcm16(samples) {
+    const out = new Int16Array(samples.length);
+    for (let i = 0; i < samples.length; i++) {
+        const s = Math.max(-1, Math.min(1, samples[i]));
+        out[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+    }
+    return out;
+}
+/**
+ * The wire's PCM as float samples in [-1, 1]. An odd trailing byte — half a
+ * sample — is dropped: `Int16Array` throws on a buffer that holds one.
+ */
+export function pcm16ToFloat(pcm) {
+    if (pcm instanceof Int16Array) {
+        const out = new Float32Array(pcm.length);
+        for (let i = 0; i < pcm.length; i++)
+            out[i] = pcm[i] / 0x8000;
+        return out;
+    }
+    const count = pcm.byteLength >> 1;
+    const out = new Float32Array(count);
+    if (LITTLE_ENDIAN) {
+        const samples = new Int16Array(pcm, 0, count);
+        for (let i = 0; i < count; i++)
+            out[i] = samples[i] / 0x8000;
+    }
+    else {
+        const view = new DataView(pcm);
+        for (let i = 0; i < count; i++)
+            out[i] = view.getInt16(i * 2, true) / 0x8000;
+    }
+    return out;
+}
+/**
+ * Samples at `from` Hz resampled to `to` Hz, linearly: a 48 kHz microphone
+ * is not a rate the socket accepts (`RECORDING_RATES`), and speech loses
+ * nothing a transcriber needs by it.
+ */
+export function resample(samples, from, to) {
+    if (from === to || samples.length === 0)
+        return samples;
+    const length = Math.max(1, Math.round((samples.length * to) / from));
+    const out = new Float32Array(length);
+    const step = from / to;
+    const last = samples.length - 1;
+    for (let i = 0; i < length; i++) {
+        const at = i * step;
+        const left = Math.min(Math.floor(at), last);
+        const right = Math.min(left + 1, last);
+        const weight = at - left;
+        out[i] = samples[left] * (1 - weight) + samples[right] * weight;
+    }
+    return out;
+}
+/** Pieces of PCM as one buffer: the frames of a reply, to save or replay. */
+export function concatPcm(pieces) {
+    const bytes = pieces.map((piece) => piece instanceof ArrayBuffer
+        ? new Uint8Array(piece)
+        : new Uint8Array(piece.buffer, piece.byteOffset, piece.byteLength));
+    const out = new Uint8Array(bytes.reduce((n, piece) => n + piece.length, 0));
+    let offset = 0;
+    for (const piece of bytes) {
+        out.set(piece, offset);
+        offset += piece.length;
+    }
+    return out.buffer;
+}
+/** How long PCM lasts: its bytes (or a buffer of them) at `rate` Hz. */
+export function pcmSeconds(pcm, rate, channels = 1) {
+    const bytes = typeof pcm === "number" ? pcm : pcm.byteLength;
+    return Math.floor(bytes / 2 / channels) / rate;
+}
+/**
+ * Samples as the wire's bytes, as an `ArrayBuffer` — what every runtime's
+ * `WebSocket.send` takes (`socket.ts`, `WebSocketLike`). A buffer as it is,
+ * since it already holds the wire's bytes; a typed array's own buffer on a
+ * little-endian device, never copied, when the array is the whole of an
+ * unshared one — what a recorder hands over. A view onto part of a buffer,
+ * or onto a shared one, is copied: one pass over its bytes.
+ */
+export function wireBytes(pcm) {
+    if (pcm instanceof ArrayBuffer)
+        return pcm;
+    if (LITTLE_ENDIAN) {
+        const { buffer, byteOffset, byteLength } = pcm;
+        return buffer instanceof ArrayBuffer &&
+            byteOffset === 0 &&
+            byteLength === buffer.byteLength
+            ? buffer
+            : new Uint8Array(buffer, byteOffset, byteLength).slice().buffer;
+    }
+    const out = new ArrayBuffer(pcm.length * 2);
+    const view = new DataView(out);
+    for (let i = 0; i < pcm.length; i++)
+        view.setInt16(i * 2, pcm[i], true);
+    return out;
+}

package/dist/protocol.gen.d.ts

@@ -0,0 +1,44 @@
+/** The protocol, sent as the WebSocket subprotocol and echoed on `ready`. */
+export declare const PROTOCOL = "ino.v1";
+/** Every frame a client may send; the edge closes on any other (4009). */
+export declare const CLIENT_VERBS: readonly ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping"];
+export type ClientVerb = (typeof CLIENT_VERBS)[number];
+/** Every event the edge sends. */
+export declare const SERVER_EVENTS: readonly ["ready", "turn.start", "heard", "heard.partial", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "knowledge", "audio.start", "audio.end", "muted", "relation", "usage", "turn.done", "interrupted", "error", "pong"];
+export type ServerEventName = (typeof SERVER_EVENTS)[number];
+/** The events that end a turn: exactly one of them ends every turn. */
+export declare const TERMINAL_EVENTS: readonly ["turn.done", "interrupted"];
+/** The edge's close codes by name: `CLOSE.auth_timeout === 4001`. */
+export declare const CLOSE: {
+    readonly auth_timeout: 4001;
+    readonly auth_failed: 4002;
+    readonly expired: 4003;
+    readonly revoked: 4004;
+    readonly no_credits: 4005;
+    readonly rate_limited: 4006;
+    readonly idle: 4007;
+    readonly gone: 4008;
+    readonly protocol: 4009;
+    readonly unavailable: 4010;
+    readonly audio: 4011;
+    readonly internal: 4013;
+    readonly too_many_for_end_user: 4014;
+};
+export type CloseName = keyof typeof CLOSE;
+/** The codes no reconnect with the same key can fix (the edge's `fatal`). */
+export declare const FINAL_CLOSE_CODES: readonly number[];
+export declare const AUTH_DEADLINE_S = 10;
+export declare const IDLE_S = 300;
+export declare const KEEPALIVE_S = 30;
+export declare const MAX_AUDIO_BYTES = 10485760;
+export declare const MAX_MESSAGE_CHARS = 32000;
+export declare const HEARINGS_IN_FLIGHT = 3;
+export declare const RECORDING_RATES: readonly [8000, 16000, 22050, 24000, 44100];
+export declare const STT_MODELS: readonly ["scribe_v2"];
+export declare const LANGUAGE_CHARS: readonly [2, 8];
+export declare const MODEL_MAX_CHARS = 64;
+export declare const RECORDING_ID_MAX_CHARS = 64;
+export declare const AUDIO_CODEC = "pcm_s16le";
+export declare const AUDIO_CHANNELS = 1;
+export declare const DEFAULT_SAMPLE_RATE = 24000;
+export declare const MAX_SOCKETS_PER_END_USER = 3;

package/dist/protocol.gen.js

@@ -0,0 +1,46 @@
+// Generated by `scripts/protocol.mjs` from the edge's vocabulary
+// (`apps/edge/src/wire/vocabulary.json`). Never edit it: run
+// `npm run protocol -w sdks/client`, which `scripts/sdk-protocol.mjs`
+// fails until it is.
+/** The protocol, sent as the WebSocket subprotocol and echoed on `ready`. */
+export const PROTOCOL = "ino.v1";
+/** Every frame a client may send; the edge closes on any other (4009). */
+export const CLIENT_VERBS = ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping"];
+/** Every event the edge sends. */
+export const SERVER_EVENTS = ["ready", "turn.start", "heard", "heard.partial", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "knowledge", "audio.start", "audio.end", "muted", "relation", "usage", "turn.done", "interrupted", "error", "pong"];
+/** The events that end a turn: exactly one of them ends every turn. */
+export const TERMINAL_EVENTS = ["turn.done", "interrupted"];
+/** The edge's close codes by name: `CLOSE.auth_timeout === 4001`. */
+export const CLOSE = {
+    auth_timeout: 4001,
+    auth_failed: 4002,
+    expired: 4003,
+    revoked: 4004,
+    no_credits: 4005,
+    rate_limited: 4006,
+    idle: 4007,
+    gone: 4008,
+    protocol: 4009,
+    unavailable: 4010,
+    audio: 4011,
+    internal: 4013,
+    too_many_for_end_user: 4014,
+};
+/** The codes no reconnect with the same key can fix (the edge's `fatal`). */
+export const FINAL_CLOSE_CODES = [4002, 4004, 4008, 4010];
+// The limits, as the edge holds them.
+export const AUTH_DEADLINE_S = 10;
+export const IDLE_S = 300;
+export const KEEPALIVE_S = 30;
+export const MAX_AUDIO_BYTES = 10485760;
+export const MAX_MESSAGE_CHARS = 32000;
+export const HEARINGS_IN_FLIGHT = 3;
+export const RECORDING_RATES = [8000, 16000, 22050, 24000, 44100];
+export const STT_MODELS = ["scribe_v2"];
+export const LANGUAGE_CHARS = [2, 8];
+export const MODEL_MAX_CHARS = 64;
+export const RECORDING_ID_MAX_CHARS = 64;
+export const AUDIO_CODEC = "pcm_s16le";
+export const AUDIO_CHANNELS = 1;
+export const DEFAULT_SAMPLE_RATE = 24000;
+export const MAX_SOCKETS_PER_END_USER = 3;

package/dist/socket.d.ts

@@ -0,0 +1,167 @@
+/**
+ * One socket of `/v1/agent/stream`, and the policy for what follows its
+ * close — lifted from the console's `src/lib/agent-socket.ts`, which was
+ * written to be (left-overs #53). `conversation.ts` runs a conversation on
+ * as many of these as it takes.
+ *
+ * Three things about the protocol are worth knowing before reading:
+ *
+ * - **Text frames are JSON, binary frames are raw PCM.** A binary frame
+ *   belongs to the `audio.start` before it, and the edge keeps one audio
+ *   window open at a time — so there is no correlation to do beyond
+ *   remembering which window is open.
+ * - **The credential travels in the first frame**, because a browser
+ *   cannot put an `Authorization` header on a `WebSocket`, and a query
+ *   parameter would put the key in every proxy log on the way.
+ * - **A close code says what to do next** (`reconnectAfter`).
+ *
+ * **What every runtime has, and nothing more**: the `on*` properties of a
+ * `WebSocket` (React Native's, a browser's, Node's and the `ws` package's
+ * all have them), `binaryType = "arraybuffer"` (React Native's default is
+ * a Blob), and text frames as strings — no `TextDecoder`.
+ */
+import type { ServerFrame } from "./events.js";
+/**
+ * A handler the SDK sets on a socket, its event checked as a method's
+ * parameter is — both ways — so every runtime's own handler type fits: a
+ * browser's `onmessage` takes a whole `MessageEvent`, which a plain
+ * function property would refuse to stand in for `{ data }` (the docs'
+ * `createClient({ WebSocket })` failed to compile until this,
+ * `test/docs.test.ts`).
+ */
+type Handler<Event> = {
+    bivariance(event: Event): void;
+}["bivariance"];
+/** What `new WebSocket(url, protocol)` makes, as far as the SDK uses it. */
+export interface WebSocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    onopen: ((event: never) => void) | null;
+    onmessage: Handler<{
+        data: unknown;
+    }> | null;
+    onclose: Handler<{
+        code: number;
+        reason: string;
+    }> | null;
+    onerror: ((event: never) => void) | null;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+}
+/** A `WebSocket` class: the runtime's own by default, or `ws`, or a fake. */
+export type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/** Raw PCM for the open audio window, with what its `audio.start` said. */
+export interface AudioFrame {
+    /** 16-bit little-endian PCM, as it came off the wire: never copied. */
+    pcm: ArrayBuffer;
+    chunk: number;
+    turn: string;
+    sample_rate: number;
+    channels: number;
+}
+/** A frame the SDK could not use, and so dropped: a bug on one side. Never the frame itself, which may be someone's words. */
+export type Warning = 
+/** A frame's `seq` was not the last one plus one. */
+{
+    type: "gap";
+    expected: number;
+    got: number;
+}
+/** Text that is not a server event, or audio with no window open. */
+ | {
+    type: "unreadable";
+    what: "text" | "audio";
+}
+/** `sendAudio` past the 10 MB one recording may carry: not sent. */
+ | {
+    type: "audio_limit";
+    bytes: number;
+};
+export interface DialOptions {
+    url: string;
+    key: string;
+    sessionId: string;
+    WebSocket: WebSocketConstructor;
+    onFrame(frame: ServerFrame): void;
+    onAudio(frame: AudioFrame): void;
+    onClose(code: number, reason: string): void;
+    onWarning(warning: Warning): void;
+}
+/** One socket, from `dial`. */
+export interface Dialled {
+    /** A client frame, as JSON; dropped unless the socket is open. */
+    send(frame: {
+        type: string;
+    } & Record<string, unknown>): boolean;
+    /** PCM, straight through; dropped unless the socket is open. */
+    sendBinary(data: ArrayBuffer): boolean;
+    /** 1000: the 4000 range is the edge's vocabulary for why *it* hung up. */
+    close(): void;
+    /** Says nothing more to the handlers: for a socket being replaced. */
+    detach(): void;
+    readonly ready: boolean;
+}
+/**
+ * Open a socket, authenticate in the first frame, and dispatch what
+ * arrives. Answers at once, not at `ready`: one way to learn a failure
+ * (`onClose`), not a promise and a close both.
+ */
+export declare function dial(options: DialOptions): Dialled;
+/**
+ * One text frame, or `null` for anything that is not a server event: JSON
+ * that is `null`, a number or an array once threw inside the listener,
+ * which silenced the conversation with no close and no error.
+ */
+export declare function parseFrame(raw: string): ServerFrame | null;
+/**
+ * The socket's URL for one session. **`?session_id=` is how the edge
+ * routes**: its front door picks the conversation before a frame is read,
+ * so the session is in the URL as well as in `auth`, and the two must be
+ * equal. An id is not a credential.
+ */
+export declare function socketUrl(base: string, sessionId: string): string;
+/** What to do after a close. */
+export type Reconnect = 
+/** Dial again after `delayMs`. */
+{
+    kind: "retry";
+    delayMs: number;
+}
+/** Mint a new key, then dial — once, until a turn ends on the new key. */
+ | {
+    kind: "new-key";
+}
+/** The edge hung up on a quiet connection: dial on the next send. */
+ | {
+    kind: "dormant";
+}
+/** Nothing a reconnect can fix, or the tries ran out. */
+ | {
+    kind: "final";
+};
+/** Reconnects in a row before the SDK stops on its own; `ready` resets the count. */
+export declare const MAX_RECONNECTS = 5;
+/**
+ * The close policy, from the code and how many reconnects in a row came
+ * before it — pure, so its table is tested whole:
+ *
+ * - **1000 (ours), 4008, 4010: final.** 4002 and 4004 are final for the
+ *   key that was refused, not for the conversation.
+ * - **4002–4005: a new key**, which the caller takes once and not again
+ *   until a turn ends on it — the console's old 4005 loop (`ready` resets
+ *   the count, so five tries were an unbounded loop of mints) cannot recur.
+ * - **4007: dormant.** Reconnecting at once would be hung up on again five
+ *   minutes later.
+ * - **4006, 4014: 5 s doubling** — a window, or another tab's socket, is
+ *   the cure, and both take longer than half a second.
+ * - **Anything else** — 4001, 4009, 4011, 4013, 1006, a dead network, no
+ *   `ready`, the watchdog — **0.5 s doubling**. Both capped at 30 s, then
+ *   ±20 % at random, so an edge deploy does not bring every socket back in
+ *   the same millisecond; five in a row is final.
+ */
+export declare function reconnectAfter(code: number, attempt: number, random?: () => number): Reconnect;
+/** Whether no reconnect with the same key can fix this close. */
+export declare const isFinalClose: (code: number) => boolean;
+/** A close code's name: the edge's (`auth_failed`), WebSocket's (`abnormal`), or `other`. */
+export declare function closeName(code: number): string;
+export {};

package/dist/socket.js

@@ -0,0 +1,185 @@
+import { CLOSE, FINAL_CLOSE_CODES, PROTOCOL } from "./protocol.gen.js";
+/** `WebSocket.OPEN`, which every implementation numbers the same. */
+const OPEN = 1;
+/**
+ * Open a socket, authenticate in the first frame, and dispatch what
+ * arrives. Answers at once, not at `ready`: one way to learn a failure
+ * (`onClose`), not a promise and a close both.
+ */
+export function dial(options) {
+    const socket = new options.WebSocket(options.url, PROTOCOL);
+    socket.binaryType = "arraybuffer";
+    // The window a binary frame belongs to: the edge opens one at a time.
+    let window = null;
+    let ready = false;
+    let detached = false;
+    let lastSeq = null;
+    const send = (data) => {
+        if (socket.readyState !== OPEN)
+            return false;
+        socket.send(data);
+        return true;
+    };
+    socket.onopen = () => {
+        // Two fields, and the edge refuses any third by name.
+        send(JSON.stringify({
+            type: "auth",
+            key: options.key,
+            session_id: options.sessionId,
+        }));
+    };
+    socket.onmessage = ({ data }) => {
+        if (detached)
+            return;
+        if (typeof data !== "string") {
+            // Audio outside a window is the edge's bug; dropping it beats playing
+            // it against the wrong sentence.
+            if (window && isArrayBuffer(data)) {
+                options.onAudio({
+                    pcm: data,
+                    chunk: window.chunk,
+                    turn: window.turn,
+                    sample_rate: window.sample_rate,
+                    channels: window.channels,
+                });
+            }
+            else
+                options.onWarning({ type: "unreadable", what: "audio" });
+            return;
+        }
+        const frame = parseFrame(data);
+        if (!frame) {
+            options.onWarning({ type: "unreadable", what: "text" });
+            return;
+        }
+        if (typeof frame.seq === "number") {
+            if (lastSeq !== null && frame.seq !== lastSeq + 1) {
+                options.onWarning({
+                    type: "gap",
+                    expected: lastSeq + 1,
+                    got: frame.seq,
+                });
+            }
+            lastSeq = frame.seq;
+        }
+        if (frame.type === "audio.start")
+            window = frame;
+        else if (frame.type === "audio.end")
+            window = null;
+        else if (frame.type === "ready")
+            ready = true;
+        options.onFrame(frame);
+    };
+    socket.onclose = ({ code, reason }) => {
+        ready = false;
+        if (!detached)
+            options.onClose(code, reason);
+    };
+    // swallowed: a close always follows an error, and carries what is known.
+    socket.onerror = () => { };
+    return {
+        send: (frame) => send(JSON.stringify(frame)),
+        sendBinary: send,
+        close() {
+            if (socket.readyState <= OPEN)
+                socket.close(1000, "done");
+        },
+        detach() {
+            detached = true;
+            ready = false;
+        },
+        get ready() {
+            return ready;
+        },
+    };
+}
+/** An `ArrayBuffer`, from this realm or another (a test's, a worker's). */
+const isArrayBuffer = (data) => data instanceof ArrayBuffer ||
+    Object.prototype.toString.call(data) === "[object ArrayBuffer]";
+/**
+ * One text frame, or `null` for anything that is not a server event: JSON
+ * that is `null`, a number or an array once threw inside the listener,
+ * which silenced the conversation with no close and no error.
+ */
+export function parseFrame(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // swallowed: not a server event — the socket warns `unreadable`.
+        return null;
+    }
+    return typeof parsed === "object" &&
+        parsed !== null &&
+        typeof parsed.type === "string"
+        ? parsed
+        : null;
+}
+/**
+ * The socket's URL for one session. **`?session_id=` is how the edge
+ * routes**: its front door picks the conversation before a frame is read,
+ * so the session is in the URL as well as in `auth`, and the two must be
+ * equal. An id is not a credential.
+ */
+export function socketUrl(base, sessionId) {
+    return `${base}${base.includes("?") ? "&" : "?"}session_id=${encodeURIComponent(sessionId)}`;
+}
+/** Reconnects in a row before the SDK stops on its own; `ready` resets the count. */
+export const MAX_RECONNECTS = 5;
+/** The codes a new key may cure: the key failed, lapsed, was revoked, or its org ran dry. */
+const NEW_KEY = [
+    CLOSE.auth_failed,
+    CLOSE.expired,
+    CLOSE.revoked,
+    CLOSE.no_credits,
+];
+/**
+ * The close policy, from the code and how many reconnects in a row came
+ * before it — pure, so its table is tested whole:
+ *
+ * - **1000 (ours), 4008, 4010: final.** 4002 and 4004 are final for the
+ *   key that was refused, not for the conversation.
+ * - **4002–4005: a new key**, which the caller takes once and not again
+ *   until a turn ends on it — the console's old 4005 loop (`ready` resets
+ *   the count, so five tries were an unbounded loop of mints) cannot recur.
+ * - **4007: dormant.** Reconnecting at once would be hung up on again five
+ *   minutes later.
+ * - **4006, 4014: 5 s doubling** — a window, or another tab's socket, is
+ *   the cure, and both take longer than half a second.
+ * - **Anything else** — 4001, 4009, 4011, 4013, 1006, a dead network, no
+ *   `ready`, the watchdog — **0.5 s doubling**. Both capped at 30 s, then
+ *   ±20 % at random, so an edge deploy does not bring every socket back in
+ *   the same millisecond; five in a row is final.
+ */
+export function reconnectAfter(code, attempt, random = Math.random) {
+    if (code === 1000 || code === CLOSE.gone || code === CLOSE.unavailable) {
+        return { kind: "final" };
+    }
+    if (NEW_KEY.includes(code))
+        return { kind: "new-key" };
+    if (code === CLOSE.idle)
+        return { kind: "dormant" };
+    if (attempt >= MAX_RECONNECTS)
+        return { kind: "final" };
+    const slow = code === CLOSE.rate_limited || code === CLOSE.too_many_for_end_user;
+    const delay = Math.min((slow ? 5000 : 500) * 2 ** attempt, 30000);
+    return { kind: "retry", delayMs: Math.round(delay * (0.8 + 0.4 * random())) };
+}
+/** Whether no reconnect with the same key can fix this close. */
+export const isFinalClose = (code) => code === 1000 || FINAL_CLOSE_CODES.includes(code);
+const NAMES = {
+    1000: "normal",
+    1001: "going_away",
+    1005: "no_status",
+    1006: "abnormal",
+    1011: "server_error",
+};
+/** A close code's name: the edge's (`auth_failed`), WebSocket's (`abnormal`), or `other`. */
+export function closeName(code) {
+    for (const [name, value] of Object.entries(CLOSE)) {
+        if (value === code)
+            return name;
+    }
+    return NAMES[code] ?? "other";
+}

package/dist/token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The end user's ephemeral key: asked of the app's `getToken`, kept, and
+ * replaced when the platform refuses it.
+ *
+ * - **Single-flight.** Every mint deducts the key's credit up front, so N
+ *   calls refused at once must not mint N keys: one mint is in flight at a
+ *   time, and every caller waits on it.
+ * - **A refusal replaces only the key it refused**: a call refused with a
+ *   key already replaced takes the new one, mints nothing.
+ * - **The app's policy decides**: `getToken` is told why it is asked —
+ *   `initial`, or `refused` with the HTTP status or close code — and may
+ *   answer from a budget of its own, or throw to stop.
+ */
+/** Why the SDK asks for a key. */
+export interface TokenRequest {
+    /** `initial`: none yet, or `clearToken()` dropped it. `refused`: the platform refused the last one. */
+    reason: "initial" | "refused";
+    /** The HTTP status that refused it: 401. */
+    status?: number;
+    /** The socket's close code (4002–4005), or the API's error `type`. */
+    code?: number | string;
+}
+/** The app's way to an ephemeral key: usually a call to its own server, which mints one. */
+export type GetToken = (request: TokenRequest) => string | Promise<string>;
+export declare class Tokens {
+    private readonly get;
+    private token;
+    private pending;
+    /** Moves on `clear()`, so a mint already out is not kept after a sign-out. */
+    private epoch;
+    constructor(get: GetToken);
+    /** The key: the one kept, or one minted. */
+    current(): Promise<string>;
+    /** A key to use instead of `refused`, which the platform refused. */
+    replace(refused: string, why?: Omit<TokenRequest, "reason">): Promise<string>;
+    /** Forget the key: sign-out. The next call asks `getToken` again. */
+    clear(): void;
+    private mint;
+}