@lumavox/client 0.0.0-stage → 0.2.0

package/dist/token.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+export class Tokens {
+    constructor(get) {
+        this.token = null;
+        this.pending = null;
+        /** Moves on `clear()`, so a mint already out is not kept after a sign-out. */
+        this.epoch = 0;
+        this.get = get;
+    }
+    /** The key: the one kept, or one minted. */
+    current() {
+        return this.token !== null
+            ? Promise.resolve(this.token)
+            : this.mint({ reason: "initial" });
+    }
+    /** A key to use instead of `refused`, which the platform refused. */
+    replace(refused, why = {}) {
+        if (this.token !== null && this.token !== refused) {
+            return Promise.resolve(this.token);
+        }
+        this.token = null;
+        return this.mint({ reason: "refused", ...why });
+    }
+    /** Forget the key: sign-out. The next call asks `getToken` again. */
+    clear() {
+        this.token = null;
+        this.pending = null;
+        this.epoch += 1;
+    }
+    mint(request) {
+        if (this.pending)
+            return this.pending;
+        const epoch = this.epoch;
+        const pending = Promise.resolve()
+            .then(() => this.get(request))
+            .then((token) => {
+            if (typeof token !== "string" || !token) {
+                throw new TypeError("getToken must answer an ephemeral key.");
+            }
+            if (epoch === this.epoch)
+                this.token = token;
+            return token;
+        })
+            .finally(() => {
+            if (this.pending === pending)
+                this.pending = null;
+        });
+        this.pending = pending;
+        return pending;
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,83 @@
+/** What `fetch` the client calls: the global one, or the caller's. */
+export type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/** Options any call takes, in its last argument. */
+export interface RequestOptions {
+    /** Per attempt; the client's `timeoutMs` (30 s) by default. */
+    timeoutMs?: number;
+    /** Aborts the call, its retries and their waits. */
+    signal?: AbortSignal;
+    /** The client's `maxRetries` (2) by default; `0` sends once. */
+    maxRetries?: number;
+    /** Sent as `X-Request-Id` on every attempt; one is made when absent. */
+    requestId?: string;
+}
+export interface TransportConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    maxRetries: number;
+    fetch: Fetch;
+}
+export type Query = Record<string, string | number | boolean | null | undefined>;
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** One call, as a method describes it. */
+export interface Call {
+    method: Method;
+    /** With its parameters already encoded (`segment`); or a whole URL. */
+    path: string;
+    query?: Query;
+    /** A JSON body. */
+    body?: unknown;
+    /** A body sent as it is, with `type` as its `Content-Type`. */
+    raw?: BodyInit;
+    type?: string;
+    headers?: Record<string, string>;
+    /** The answer's bytes, or its body unread; JSON by default. */
+    read?: "bytes" | "stream";
+    /** No credential: the open routes, and object storage's signed URLs. */
+    open?: boolean;
+    /** A POST that may be sent twice with the same effect. */
+    idempotent?: boolean;
+    /** Another bearer for this call: an end user's ephemeral key. */
+    token?: string;
+}
+export interface Answer<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+    requestId: string;
+}
+/** The longest `Retry-After` slept through; past it the 429 is thrown. */
+export declare const MAX_RETRY_AFTER_S = 60;
+/** A path parameter or a query's value, encoded: an `external_id` may hold `/` or `?`. */
+export declare const segment: (value: string | number | boolean) => string;
+/**
+ * A request id of the API's own shape: 16 hex. From `Math.random`, not
+ * `crypto`, which React Native lacks (this file is the client SDK's too):
+ * an id names a call in the logs and is no secret.
+ */
+export declare const newRequestId: () => string;
+/**
+ * How long to wait before retry `attempt` (1, 2, …): the doubling backoff
+ * less up to a quarter, or `Retry-After`'s seconds when the API sent one.
+ */
+export declare function retryDelayMs(attempt: number, retryAfter: number | null, random?: () => number): number;
+/** Waits `ms`, or rejects with the signal's reason when it aborts first. */
+export declare function sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;
+/** A 2xx body: JSON, or nothing. Anything else is not the API answering. */
+export declare function parsed<T>(text: string, status: number, requestId: string): T;
+/** `promise`'s value, or `null` when it is a 404: what is not there is done. */
+export declare const orNull: <T>(promise: Promise<T>) => Promise<T | null>;
+export declare class Transport {
+    private readonly config;
+    constructor(config: TransportConfig);
+    /** A JSON call's answer: `data` is a GET's query and any other's body. */
+    send<T>(method: Method, path: string, options?: RequestOptions, data?: unknown): Promise<T>;
+    request<T>(call: Call, options?: RequestOptions): Promise<Answer<T>>;
+    private url;
+    /**
+     * One send and its body read, under this attempt's timer — which stops
+     * at the headers of a stream the caller reads (and of nothing else).
+     */
+    private attempt;
+}

package/dist/transport.js

@@ -0,0 +1,236 @@
+/**
+ * One HTTP call to the API, with everything every method shares: the
+ * credential, the request id, the timeout, the retries and the errors.
+ *
+ * - **One request id per call** (16 hex, as the API mints its own), sent
+ *   as `X-Request-Id` and **reused on every retry**: the API keeps a valid
+ *   one (`apps/api/src/http/request-id.ts`), so every attempt of a call
+ *   shares one id in Workers Logs and in the error the caller sees.
+ * - **The timeout is per attempt**, a timer joined with the caller's
+ *   `signal`, and it covers reading the body — **except a stream's**,
+ *   whose timer stops at the headers: a transcript streamed for minutes
+ *   is not a call that timed out. The caller's abort is theirs: it is
+ *   thrown as their reason and never retried, and it still ends a stream.
+ * - **Not every body is JSON**: speech is bytes or a stream, `/v1/stt`
+ *   takes the audio raw, and an upload's `PUT` goes to object storage's
+ *   own URL with no credential (`open`) — the same attempts, retries and
+ *   errors. A body that is a stream is sent once: it cannot be read twice.
+ * - **What is retried is what cannot have done anything twice.** GET, PUT,
+ *   PATCH and DELETE: a connection that failed, a timeout, 429, 502, 503,
+ *   504. A POST: only a 429, which the API answers at admission before any
+ *   work — unless the method says the POST is idempotent
+ *   (`POST /v1/end-users` with an `external_id`). Never a 500: whatever
+ *   failed may have half-happened.
+ * - **The wait** doubles from 0.5 s to 8 s, less up to a quarter at random
+ *   so callers refused together do not return together; `Retry-After`
+ *   wins, up to a minute. A longer one is thrown at once as a
+ *   `RateLimitError` with its `retryAfter`: a call that sleeps for an hour
+ *   is not one a caller can reason about.
+ * - **The client SDK runs this file too** (`sdks/client/src/transport.ts`,
+ *   a copy its `test/copies.test.ts` holds identical), on React Native's
+ *   Hermes as well: so no `crypto`, `URLSearchParams`, `AbortSignal.any`
+ *   or global `ReadableStream` taken for granted, each of which it lacks.
+ */
+import { ConnectionError, errorFromResponse, NotFoundError, PlatformError, TimeoutError, } from "./errors.js";
+const RETRIED_STATUS = new Set([429, 502, 503, 504]);
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 8000;
+/** The longest `Retry-After` slept through; past it the 429 is thrown. */
+export const MAX_RETRY_AFTER_S = 60;
+/** A path parameter or a query's value, encoded: an `external_id` may hold `/` or `?`. */
+export const segment = (value) => encodeURIComponent(value);
+/**
+ * A request id of the API's own shape: 16 hex. From `Math.random`, not
+ * `crypto`, which React Native lacks (this file is the client SDK's too):
+ * an id names a call in the logs and is no secret.
+ */
+export const newRequestId = () => "x".repeat(16).replace(/x/g, () => ((Math.random() * 16) | 0).toString(16));
+/**
+ * How long to wait before retry `attempt` (1, 2, …): the doubling backoff
+ * less up to a quarter, or `Retry-After`'s seconds when the API sent one.
+ */
+export function retryDelayMs(attempt, retryAfter, random = Math.random) {
+    if (retryAfter !== null)
+        return Math.ceil(retryAfter * 1000);
+    const full = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** (attempt - 1));
+    return Math.round(full * (1 - 0.25 * random()));
+}
+/** Waits `ms`, or rejects with the signal's reason when it aborts first. */
+export function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const done = () => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        const stop = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+/** A 2xx body: JSON, or nothing. Anything else is not the API answering. */
+export function parsed(text, status, requestId) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new PlatformError({
+            status,
+            code: "invalid_response",
+            message: `HTTP ${status} with a body that is not JSON.`,
+            requestId,
+            cause,
+        });
+    }
+}
+/** `promise`'s value, or `null` when it is a 404: what is not there is done. */
+export const orNull = (promise) => promise.catch((error) => {
+    if (error instanceof NotFoundError)
+        return null;
+    throw error;
+});
+export class Transport {
+    constructor(config) {
+        this.config = config;
+    }
+    /** A JSON call's answer: `data` is a GET's query and any other's body. */
+    send(method, path, options, data) {
+        return this.request(method === "GET"
+            ? { method, path, query: data }
+            : { method, path, body: data }, options).then((answer) => answer.data);
+    }
+    async request(call, options = {}) {
+        const requestId = options.requestId ?? newRequestId();
+        // A stream by its shape: not every runtime has a global `ReadableStream`.
+        const once = "getReader" in Object(call.raw);
+        const maxRetries = once
+            ? 0
+            : (options.maxRetries ?? this.config.maxRetries);
+        const retriesAll = call.method !== "POST" || call.idempotent === true;
+        const url = this.url(call);
+        const headers = {
+            Accept: call.read ? "*/*" : "application/json",
+            "X-Request-Id": requestId,
+            ...call.headers,
+        };
+        if (!call.open) {
+            headers.Authorization = `Bearer ${call.token ?? this.config.apiKey}`;
+        }
+        let body = call.raw;
+        if (call.type)
+            headers["Content-Type"] = call.type;
+        if (call.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(call.body);
+        }
+        const init = { method: call.method, headers, body };
+        // Node's fetch sends a stream only when told it is one-way.
+        if (once)
+            Object.assign(init, { duplex: "half" });
+        for (let attempt = 0;; attempt++) {
+            const outcome = await this.attempt(url, init, call.read, options);
+            const last = attempt >= maxRetries;
+            if (outcome.kind === "response") {
+                const { response, body: read } = outcome;
+                if (response.ok) {
+                    return {
+                        data: call.read
+                            ? read
+                            : parsed(read, response.status, requestId),
+                        status: response.status,
+                        headers: response.headers,
+                        requestId,
+                    };
+                }
+                const error = errorFromResponse(response.status, response.headers, read, requestId);
+                const retried = response.status === 429 ||
+                    (retriesAll && RETRIED_STATUS.has(response.status));
+                if (last || !retried || (error.retryAfter ?? 0) > MAX_RETRY_AFTER_S) {
+                    throw error;
+                }
+                await sleep(retryDelayMs(attempt + 1, error.retryAfter), options.signal);
+                continue;
+            }
+            if (last || !retriesAll) {
+                throw outcome.kind === "timeout"
+                    ? new TimeoutError({
+                        status: 0,
+                        code: "timeout",
+                        message: "The API did not answer in time.",
+                        requestId,
+                    })
+                    : new ConnectionError({
+                        status: 0,
+                        code: "connection_error",
+                        message: "Could not reach the API.",
+                        requestId,
+                        cause: outcome.error,
+                    });
+            }
+            await sleep(retryDelayMs(attempt + 1, null), options.signal);
+        }
+    }
+    url(call) {
+        // By hand: React Native's `URLSearchParams` is partial.
+        let query = "";
+        for (const [key, value] of Object.entries(call.query ?? {})) {
+            if (value != null) {
+                query += `${query ? "&" : "?"}${key}=${segment(value)}`;
+            }
+        }
+        const base = /^https?:/.test(call.path) ? "" : this.config.baseUrl;
+        return base + call.path + query;
+    }
+    /**
+     * One send and its body read, under this attempt's timer — which stops
+     * at the headers of a stream the caller reads (and of nothing else).
+     */
+    async attempt(url, init, read, options) {
+        // The caller's signal joined to the timer by hand, its reason carried
+        // over: `AbortSignal.any` is not React Native's. Left joined for a
+        // stream, whose body the caller's abort still ends.
+        const { signal } = options;
+        const timer = new AbortController();
+        const stop = () => timer.abort(signal?.reason);
+        const clock = setTimeout(stop, options.timeoutMs ?? this.config.timeoutMs);
+        signal?.addEventListener("abort", stop);
+        // Already aborted: no event will come, and `fetch` sends nothing.
+        if (signal?.aborted)
+            stop();
+        try {
+            const response = await this.config.fetch(url, {
+                ...init,
+                signal: timer.signal,
+            });
+            const body = !response.ok
+                ? await response.text()
+                : read === "stream"
+                    ? response.body
+                    : read === "bytes"
+                        ? await response.arrayBuffer()
+                        : await response.text();
+            return { kind: "response", response, body };
+        }
+        catch (error) {
+            // The caller's abort is the caller's, whatever else happened.
+            if (signal?.aborted)
+                throw signal.reason;
+            if (timer.signal.aborted)
+                return { kind: "timeout" };
+            return { kind: "network", error };
+        }
+        finally {
+            clearTimeout(clock);
+            if (read !== "stream")
+                signal?.removeEventListener("abort", stop);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@lumavox/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Talk to Lumavox agents from a browser, a React Native app or Node, with an end user's ephemeral key: conversations on the agent's socket, sessions, memory and relations. Zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@ino/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "generate": "openapi-ts",
+    "protocol": "node scripts/protocol.mjs",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "check": "biome check --write",
+    "format": "biome format --write",
+    "lint": "biome lint",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.2",
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@types/node": "^24",
+    "esbuild": "^0.28.1",
+    "typescript": "^6",
+    "vitest": "^4.1.12"
+  }
+}