@lumavox/client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumavox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @lumavox/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Talk to Lumavox agents from an end user's device — a browser, a React
+Native app, Node — with **their ephemeral key**, never your API key: a
+conversation on the agent's socket that keeps itself connected, and the
+agent's REST routes for sessions, memory and relationships. **Zero
+dependencies.**
+
+```sh
+npm install @lumavox/client
+```
+
+```ts
+import { createClient } from "@lumavox/client";
+
+const lumavox = createClient({
+  // Your server mints the key with your API key (POST /v1/ephemeral-keys).
+  getToken: async () => (await fetch("/api/lumavox-key")).text(),
+});
+
+const session = await lumavox.sessions.create({ agent_id: "agt_..." });
+
+const conversation = lumavox.connect(session.id, {
+  onText: ({ text }) => render(text),
+  onDone: ({ message }) => save(message),
+});
+
+const outcome = await conversation.send("What should I see on my first morning?");
+// { status: "done", frame } | { status: "interrupted", frame } | { status: "dropped", reason, message }
+```
+
+React and React Native: `@lumavox/react`, hooks over this.
+
+The guide, with every example: the docs' **SDKs** tab, *Client SDK*.
+
+## The client
+
+```ts
+createClient({
+  getToken,                            // ({ reason, status?, code? }) => key; throw to stop
+  baseUrl: "https://api.lumavox.ai",   // the default
+  socketUrl,                           // baseUrl as wss:, plus /v1/agent/stream, by default
+  timeoutMs: 30_000,                   // per attempt
+  maxRetries: 2,
+  fetch,                               // the runtime's own by default
+  WebSocket,                           // the runtime's own by default; `ws` on Node before 22
+});
+```
+
+**The key** is asked for once, kept, and replaced once when the platform
+refuses it — an HTTP 401, or the socket closed with 4002 to 4005 — however
+many calls were refused with it: every mint spends credit up front. Never
+for a 402, 403 or 429. `clearToken()` at sign-out.
+
+| Resource | Methods |
+|---|---|
+| `sessions` | `create`, `list` (every one), `page`, `get`, `history` (the whole transcript, newest first), `delete`, `compact`, `extract` |
+| `facts` | `list`, `page`, `delete`, `deleteAll` |
+| `relations` | `list`, `page` |
+
+Bodies and answers are the API's own JSON, as the API reference shows them;
+the SDK's options go in a last argument: `{ timeoutMs, signal, maxRetries,
+requestId }`. `list()` is every item, page after page by each page's
+`next_cursor`; `page()` is one page, `{ data, next_cursor }`; a session's
+messages are a page inside it, read back by `messages.next_cursor`. A
+delete answers `true`, and `false` for what is already gone. Errors are
+`PlatformError` and its subclasses — `AuthenticationError`,
+`PermissionError`, `NotFoundError`, `RateLimitError`, … — with `status`,
+`code`, `requestId`, `issues` and `retryAfter`, as `@lumavox/server`'s.
+
+## A conversation
+
+`connect(sessionId, handlers, options)` answers at once. It asks for the
+key, dials, authenticates, and from then on:
+
+- **queues** what you send behind the agent's greeting, a running turn, a
+  reconnect or a quiet spell; `send` answers how the turn ended and never
+  rejects;
+- **reconnects**: a new key once for 4002–4005, 5 s backoff for a rate or
+  connection limit, 0.5 s for anything else, ±20 % jitter, final after
+  five in a row — and **rests** after the edge hangs up on a quiet
+  connection (4007), dialling again on the next `send`;
+- **watches**: 60 s with nothing from the edge is a dead socket, dropped
+  and dialled again;
+- publishes `snapshot` — `state`, `ready`, the `turn` (its text, chunks,
+  mood, tool, knowledge), `caption`, `relation`, `queued` — with
+  `subscribe(fn)`.
+
+| Handler | Frame |
+|---|---|
+| `onReady` `onTurnStart` `onHeard` `onHeardPartial` `onKnowledge` `onMood` `onThought` `onText` `onChunk` `onToolStart` `onToolEnd` `onUsage` `onMuted` `onAudioStart` `onAudioEnd` `onTranscript` `onDone` `onInterrupted` `onError` | the wire's frame, as it is |
+| `onAudio` | `{ pcm, chunk, turn, sample_rate, channels }`: raw 16-bit PCM, never copied |
+| `onRelation` | the relationship, each change once |
+| `onState` | `connecting` `ready` `busy` `reconnecting` `dormant` `closed` |
+| `onDisconnect` | every socket that closed, recovered from or not: `{ code, reason, ready }` |
+| `onClose` | `{ code, reason, final }`, only when it will not reconnect |
+| `onWarning` | a gap in the frames, one it could not read, audio past 10 MB |
+| `onEvent` | every frame |
+
+With no `onAudio` handler every turn asks for no speech, so nothing pays
+for audio nobody hears; `connect`'s `{ speech }` overrides that.
+
+### Speaking
+
+```ts
+conversation.startAudio({ rate: 16_000 });     // one of RECORDING_RATES
+conversation.sendAudio(pcm);                    // Int16Array or ArrayBuffer of 16-bit LE PCM
+const turn = await conversation.endAudio();    // a spoken turn
+// …or the words alone, for this recording, however others finish:
+const words = await conversation.endAudio({ transcribeOnly: true });
+```
+
+The SDK captures and plays nothing itself: a recorder hands it samples, a
+player takes `onAudio`'s. `floatToPcm16`, `pcm16ToFloat`, `resample`,
+`concatPcm` and `pcmSeconds` convert between them and the wire;
+`AgentAudio` is the interface `@lumavox/react` drives.
+
+## Runtimes
+
+Browsers, React Native (Hermes, ES2020 — and each binary frame reaches JS
+as base64, a cost per audio frame no SDK can remove), Node 22 and later.
+
+MIT, copyright Lumavox.

package/dist/audio.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What an app plugs in to make a conversation audible and to speak in it:
+ * a player and a recorder. **Types only in v1**: the SDK captures and
+ * plays nothing itself, so it adds no audio library to a customer's app —
+ * the console's Web Audio player and recorder are the first implementation
+ * (`apps/console/src/components/audio/agent-audio.ts`), and
+ * `@lumavox/react`'s `useAgent` drives one: it plays every audio frame,
+ * stops on a cancel, a mute or a new turn, and records at the rate the
+ * recorder was granted. Voice activity detection stays the app's.
+ */
+export interface AgentAudio {
+    /** Queue one frame of a reply: 16-bit little-endian PCM, in wire order. */
+    play(pcm: ArrayBuffer, frame: {
+        sample_rate: number;
+        channels: number;
+        chunk: number;
+        turn: string;
+    }): void;
+    /** Drop everything queued and stop: a cancel, a mute, a barge-in. */
+    stop(): void;
+    /** Called when the queue has played out: the agent stopped speaking. Answers the unsubscribe. */
+    onDrained(fn: () => void): () => void;
+    /**
+     * Open the microphone and call `onPcm` with 16-bit little-endian PCM as
+     * it is captured. Answers the rate it was granted, which must be one of
+     * `RECORDING_RATES`: a recorder that cannot have its asked rate
+     * resamples (`resample`) or refuses.
+     */
+    startCapture(onPcm: (pcm: ArrayBuffer) => void, options?: {
+        rate?: number;
+    }): Promise<{
+        rate: number;
+    }>;
+    /** Close the microphone; the last samples are delivered before it settles. */
+    stopCapture(): Promise<void>;
+    /** Free everything: the conversation is over. */
+    dispose(): void;
+}

package/dist/audio.js

@@ -0,0 +1 @@
+export {};

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `createClient`: an end user's ephemeral key (`getToken`), one base URL,
+ * the agent's REST routes — sessions, facts, relations, the ten
+ * `/v1/agent/*` operations (`test/coverage.test.ts` holds the document to
+ * them) — and `connect`, the agent's socket (`conversation.ts`).
+ *
+ * - **Shaped as the server SDK is** (`sdks/server`): bodies and answers in
+ *   the wire's snake_case, camelCase methods, the SDK's options
+ *   (`timeoutMs`, `signal`, `maxRetries`, `requestId`) last; `list()` every
+ *   item, page after page by each page's `next_cursor`, and `page()` one
+ *   page, `{ data, next_cursor }`; a delete answers `true`, and `false`
+ *   for what is already gone; the same `transport.ts` and `errors.ts`,
+ *   copied.
+ * - **A key is asked for once, and replaced once**: a call refused with 401
+ *   asks for a new key and is sent again; a second refusal, on the fresh
+ *   key, is the caller's (`token.ts`). **Never on 402, 403 or 429**: on this
+ *   API 403 is a key bound to another agent and 429 a window, and a new key
+ *   there would spend credit to dodge a limit.
+ * - **`end_user_id` is never sent**: the key names the person.
+ * - **Nothing is read from the environment**, and the runtime's own
+ *   `fetch` and `WebSocket` are the defaults, looked up when used: Node 22
+ *   and later, browsers, React Native.
+ */
+import { type ConnectOptions, Conversation, type ConversationHandlers } from "./conversation.js";
+import type { CompactionInfo, CompactRequest, FactInfo, FactPage, FactsDeleted, MessageInfo, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage } from "./gen/index.js";
+import type { WebSocketConstructor } from "./socket.js";
+import { type GetToken } from "./token.js";
+import { type Fetch, type RequestOptions } from "./transport.js";
+export declare const DEFAULT_BASE_URL = "https://api.lumavox.ai";
+export interface ClientOptions {
+    /**
+     * The end user's ephemeral key, from your server — which mints it with
+     * your API key (`POST /v1/ephemeral-keys`). Called once, and again only
+     * when the platform refuses the key it gave; throw to stop.
+     */
+    getToken: GetToken;
+    /** `https://api.lumavox.ai` by default; staging is `https://stg-api.lumavox.ai`. */
+    baseUrl?: string;
+    /** The agent's socket: `baseUrl` as `wss:`, plus `/v1/agent/stream`, by default. */
+    socketUrl?: string;
+    /** Per attempt, in milliseconds: 30 s by default. */
+    timeoutMs?: number;
+    /** Retries of a call that can be sent again safely: 2 by default. */
+    maxRetries?: number;
+    /** The `fetch` to call: the runtime's own by default. */
+    fetch?: Fetch;
+    /** The `WebSocket` class: the runtime's own by default; `ws` on an older Node. */
+    WebSocket?: WebSocketConstructor;
+}
+export interface SessionListParams {
+    /** How many a page holds, up to 200. */
+    limit?: number;
+    /** `page()` only: the `next_cursor` of the page before. */
+    cursor?: string;
+}
+export interface SessionGetParams {
+    /** Messages, counting back from the newest: 50 by default, up to 200. */
+    limit?: number;
+    /** The older messages: `messages.next_cursor` of the page before. */
+    cursor?: string;
+}
+export interface Sessions {
+    /** Open a conversation with an agent — or resume the person's last, by default (`resume`). */
+    create(body: SessionCreateRequest, options?: RequestOptions): Promise<SessionDetail>;
+    /** Every one of the person's conversations, most recent first, page after page. */
+    list(params?: Omit<SessionListParams, "cursor">, options?: RequestOptions): AsyncGenerator<SessionInfo, void, undefined>;
+    /** One page of them, with the `next_cursor` of the next. */
+    page(params?: SessionListParams, options?: RequestOptions): Promise<SessionPage>;
+    /** One conversation, with a page of its transcript: the newest messages, oldest first. */
+    get(id: string, params?: SessionGetParams, options?: RequestOptions): Promise<SessionDetail>;
+    /** Its whole transcript, newest message first, paging back by `messages.next_cursor`. */
+    history(id: string, options?: RequestOptions): AsyncGenerator<MessageInfo, void, undefined>;
+    /** Delete it: `true`, or `false` when it is already gone. */
+    delete(id: string, options?: RequestOptions): Promise<boolean>;
+    /** Summarise it now; `extract_facts` also stores what is worth remembering. */
+    compact(id: string, body?: CompactRequest, options?: RequestOptions): Promise<CompactionInfo>;
+    /** Compact it and extract facts, in one model call. */
+    extract(id: string, options?: RequestOptions): Promise<CompactionInfo>;
+}
+export interface Facts {
+    /**
+     * Everything remembered about the person, oldest first — the newest 100
+     * for now, in one page (left-overs #109); read on by cursor the day the
+     * route pages.
+     */
+    list(options?: RequestOptions): AsyncGenerator<FactInfo, void, undefined>;
+    /** One page of them, as the route answers it. */
+    page(options?: RequestOptions): Promise<FactPage>;
+    /** Forget one: `true`, or `false` when it is already gone. */
+    delete(id: string, options?: RequestOptions): Promise<boolean>;
+    /** Forget everything about the person: how many facts went. Their conversations stay. */
+    deleteAll(options?: RequestOptions): Promise<FactsDeleted>;
+}
+export interface RelationListParams {
+    /** One agent's row alone. */
+    agent_id?: string;
+    /** How many a page holds: 50 by default, up to 200. */
+    limit?: number;
+    /** `page()` only: the `next_cursor` of the page before. */
+    cursor?: string;
+}
+export interface Relations {
+    /** How the agents the person talked to feel about them, most recently active first. */
+    list(params?: Omit<RelationListParams, "cursor">, options?: RequestOptions): AsyncGenerator<RelationInfo, void, undefined>;
+    /** One page of them, with the `next_cursor` of the next. */
+    page(params?: RelationListParams, options?: RequestOptions): Promise<RelationPage>;
+}
+export interface Client {
+    readonly sessions: Sessions;
+    readonly facts: Facts;
+    readonly relations: Relations;
+    /**
+     * Join conversation `sessionId` on the agent's socket. Answers at once:
+     * the conversation dials, authenticates and keeps itself connected, and
+     * its handlers and `snapshot` say how it goes.
+     */
+    connect(sessionId: string, handlers?: ConversationHandlers, options?: ConnectOptions): Conversation;
+    /** Forget the key — at sign-out. The next call asks `getToken` again. */
+    clearToken(): void;
+}
+export declare function createClient(options: ClientOptions): Client;

package/dist/client.js

@@ -0,0 +1,132 @@
+/**
+ * `createClient`: an end user's ephemeral key (`getToken`), one base URL,
+ * the agent's REST routes — sessions, facts, relations, the ten
+ * `/v1/agent/*` operations (`test/coverage.test.ts` holds the document to
+ * them) — and `connect`, the agent's socket (`conversation.ts`).
+ *
+ * - **Shaped as the server SDK is** (`sdks/server`): bodies and answers in
+ *   the wire's snake_case, camelCase methods, the SDK's options
+ *   (`timeoutMs`, `signal`, `maxRetries`, `requestId`) last; `list()` every
+ *   item, page after page by each page's `next_cursor`, and `page()` one
+ *   page, `{ data, next_cursor }`; a delete answers `true`, and `false`
+ *   for what is already gone; the same `transport.ts` and `errors.ts`,
+ *   copied.
+ * - **A key is asked for once, and replaced once**: a call refused with 401
+ *   asks for a new key and is sent again; a second refusal, on the fresh
+ *   key, is the caller's (`token.ts`). **Never on 402, 403 or 429**: on this
+ *   API 403 is a key bound to another agent and 429 a window, and a new key
+ *   there would spend credit to dodge a limit.
+ * - **`end_user_id` is never sent**: the key names the person.
+ * - **Nothing is read from the environment**, and the runtime's own
+ *   `fetch` and `WebSocket` are the defaults, looked up when used: Node 22
+ *   and later, browsers, React Native.
+ */
+import { Conversation, } from "./conversation.js";
+import { AuthenticationError } from "./errors.js";
+import { Tokens } from "./token.js";
+import { orNull, segment, Transport, } from "./transport.js";
+export const DEFAULT_BASE_URL = "https://api.lumavox.ai";
+/** A page as large as the route allows: fewer calls for a long list. */
+const PAGE = 200;
+/** Every item, page after page by cursor, until a page names no next one. */
+async function* pages(read) {
+    let cursor;
+    do {
+        const page = await read(cursor);
+        yield* page.data;
+        cursor = page.next_cursor ?? undefined;
+    } while (cursor);
+}
+/** `true` once `promise` is done, `false` when it was a 404: what is not there is gone. */
+const done = (promise) => orNull(promise).then((answer) => answer !== null);
+export function createClient(options) {
+    if (typeof options?.getToken !== "function") {
+        throw new TypeError("createClient needs getToken: a function answering the end user's ephemeral key.");
+    }
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const socketBase = options.socketUrl ?? `${baseUrl.replace(/^http/, "ws")}/v1/agent/stream`;
+    const own = options.fetch;
+    const transport = new Transport({
+        apiKey: "",
+        baseUrl,
+        timeoutMs: options.timeoutMs ?? 30000,
+        maxRetries: options.maxRetries ?? 2,
+        fetch: (url, init) => (own ?? fetch)(url, init),
+    });
+    const tokens = new Tokens(options.getToken);
+    /** A call with the key, and with a new one once if it is refused. */
+    async function send(call, request) {
+        const key = await tokens.current();
+        try {
+            return (await transport.request({ ...call, token: key }, request))
+                .data;
+        }
+        catch (error) {
+            if (!(error instanceof AuthenticationError))
+                throw error;
+            const fresh = await tokens.replace(key, {
+                status: 401,
+                code: error.code,
+            });
+            return (await transport.request({ ...call, token: fresh }, request))
+                .data;
+        }
+    }
+    const sessionPath = (id, rest = "") => `/v1/agent/sessions/${segment(id)}${rest}`;
+    /** One page of the list at `path`. */
+    const read = (path, params = {}, request) => send({ method: "GET", path, query: { ...params } }, request);
+    const page = (params = {}, request) => read("/v1/agent/sessions", params, request);
+    const factPage = (request, cursor) => read("/v1/agent/facts", { cursor }, request);
+    const relationPage = (params = {}, request) => read("/v1/agent/relations", params, request);
+    const get = (id, params = {}, request) => send({ method: "GET", path: sessionPath(id), query: { ...params } }, request);
+    return {
+        sessions: {
+            create: (body, request) => send({ method: "POST", path: "/v1/agent/sessions", body }, request),
+            list: (params = {}, request) => pages((cursor) => page({ limit: PAGE, ...params, cursor }, request)),
+            page,
+            get,
+            async *history(id, request) {
+                let cursor;
+                do {
+                    const { messages } = await get(id, { limit: PAGE, cursor: cursor ?? undefined }, request);
+                    // Each page is oldest first; the history runs newest first.
+                    for (let i = messages.data.length - 1; i >= 0; i--) {
+                        yield messages.data[i];
+                    }
+                    cursor = messages.next_cursor;
+                } while (cursor);
+            },
+            delete: (id, request) => done(send({ method: "DELETE", path: sessionPath(id) }, request)),
+            // The document requires a body; none is `{}`, the agent's own setting.
+            compact: (id, body = {}, request) => send({ method: "POST", path: sessionPath(id, "/compact"), body }, request),
+            extract: (id, request) => send({ method: "POST", path: sessionPath(id, "/extract") }, request),
+        },
+        facts: {
+            list: (request) => pages((cursor) => factPage(request, cursor)),
+            page: factPage,
+            delete: (id, request) => done(send({ method: "DELETE", path: `/v1/agent/facts/${segment(id)}` }, request)),
+            deleteAll: (request) => send({ method: "DELETE", path: "/v1/agent/facts" }, request),
+        },
+        relations: {
+            list: (params = {}, request) => pages((cursor) => relationPage({ limit: PAGE, ...params, cursor }, request)),
+            page: relationPage,
+        },
+        connect(sessionId, handlers = {}, connectOptions = {}) {
+            const WebSocket = options.WebSocket ??
+                globalThis
+                    .WebSocket;
+            if (!WebSocket) {
+                throw new TypeError("This runtime has no WebSocket: pass createClient({ WebSocket }), from the ws package on Node before 22.");
+            }
+            return new Conversation({
+                sessionId,
+                socketUrl: socketBase,
+                tokens,
+                WebSocket,
+                handlers,
+                options: connectOptions,
+            });
+        },
+        clearToken: () => tokens.clear(),
+    };
+}