@lumavox/client 0.1.1 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ const conversation = lumavox.connect(session.id, {
 });
 
 const outcome = await conversation.send("What should I see on my first morning?");
-// { status: "done", frame } | { status: "interrupted", frame } | { status: "dropped", reason }
+// { status: "done", frame } | { status: "interrupted", frame } | { status: "dropped", reason, message }
 ```
 
 React and React Native: `@lumavox/react`, hooks over this.
@@ -55,15 +55,18 @@ 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`, `delete`, `deleteAll` |
-| `relations` | `list` |
+| `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 }`. A delete of what is already gone answers `null`. Errors are
+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`,
-`type`, `requestId`, `details` and `retryAfter`, as `@lumavox/server`'s.
+`code`, `requestId`, `issues` and `retryAfter`, as `@lumavox/server`'s.
 
 ## A conversation
 

package/dist/client.d.ts

@@ -7,8 +7,10 @@
  * - **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()` one page; a delete of what is already gone answers
- *   `null`; the same `transport.ts` and `errors.ts`, copied.
+ *   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
@@ -20,7 +22,7 @@
  *   and later, browsers, React Native.
  */
 import { type ConnectOptions, Conversation, type ConversationHandlers } from "./conversation.js";
-import type { CompactionInfo, CompactRequest, FactList, ForgottenFacts, MessageInfo, RelationList, SessionCreateRequest, SessionDetail, SessionInfo } from "./gen/index.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";
@@ -48,49 +50,60 @@ export interface ClientOptions {
 export interface SessionListParams {
     /** How many a page holds, up to 200. */
     limit?: number;
-    offset?: 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;
-    /** Only messages before this `seq`: the last page's `next_before`. */
-    before?: 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, newest first, page after page. */
-    list(params?: SessionListParams, options?: RequestOptions): AsyncGenerator<SessionInfo, void, undefined>;
-    /** One page of them. */
-    page(params?: SessionListParams, options?: RequestOptions): Promise<SessionInfo[]>;
-    /** One conversation, with a page of its transcript. */
+    /** 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 `next_before`. */
+    /** Its whole transcript, newest message first, paging back by `messages.next_cursor`. */
     history(id: string, options?: RequestOptions): AsyncGenerator<MessageInfo, void, undefined>;
-    /** Delete it; `null` when it is already gone. */
-    delete(id: string, options?: RequestOptions): Promise<SessionInfo | null>;
+    /** 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 {
-    /** What is remembered about the person: the first 100, as the route answers (left-overs #109). */
-    list(options?: RequestOptions): Promise<FactList>;
-    /** Forget one; `null` when it is already gone. */
-    delete(id: string, options?: RequestOptions): Promise<ForgottenFacts | null>;
-    /** Forget everything about the person. Their conversations stay. */
-    deleteAll(options?: RequestOptions): Promise<ForgottenFacts>;
+    /**
+     * 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;
-    /** Up to 50 by default; clamped to the route's cap, which `total` shows. */
+    /** 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 recent first. */
-    list(params?: RelationListParams, options?: RequestOptions): Promise<RelationList>;
+    /** 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;

package/dist/client.js

@@ -7,8 +7,10 @@
  * - **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()` one page; a delete of what is already gone answers
- *   `null`; the same `transport.ts` and `errors.ts`, copied.
+ *   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
@@ -26,6 +28,17 @@ 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.");
@@ -53,53 +66,50 @@ export function createClient(options) {
                 throw error;
             const fresh = await tokens.replace(key, {
                 status: 401,
-                code: error.type,
+                code: error.code,
             });
             return (await transport.request({ ...call, token: fresh }, request))
                 .data;
         }
     }
     const sessionPath = (id, rest = "") => `/v1/agent/sessions/${segment(id)}${rest}`;
-    const page = (params = {}, request) => send({ method: "GET", path: "/v1/agent/sessions", query: { ...params } }, request);
+    /** 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),
-            async *list(params = {}, request) {
-                const limit = params.limit ?? PAGE;
-                let offset = params.offset ?? 0;
-                for (;;) {
-                    const items = await page({ limit, offset }, request);
-                    yield* items;
-                    offset += items.length;
-                    if (items.length < limit)
-                        return;
-                }
-            },
+            list: (params = {}, request) => pages((cursor) => page({ limit: PAGE, ...params, cursor }, request)),
             page,
             get,
             async *history(id, request) {
-                let before;
+                let cursor;
                 do {
-                    const detail = await get(id, { limit: PAGE, before: before ?? undefined }, request);
-                    for (let i = detail.messages.length - 1; i >= 0; i--) {
-                        yield detail.messages[i];
+                    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];
                     }
-                    before = detail.next_before;
-                } while (before !== null && before !== undefined);
+                    cursor = messages.next_cursor;
+                } while (cursor);
             },
-            delete: (id, request) => orNull(send({ method: "DELETE", path: sessionPath(id) }, request)),
+            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) => send({ method: "GET", path: "/v1/agent/facts" }, request),
-            delete: (id, request) => orNull(send({ method: "DELETE", path: `/v1/agent/facts/${segment(id)}` }, request)),
+            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) => send({ method: "GET", path: "/v1/agent/relations", query: { ...params } }, request),
+            list: (params = {}, request) => pages((cursor) => relationPage({ limit: PAGE, ...params, cursor }, request)),
+            page: relationPage,
         },
         connect(sessionId, handlers = {}, connectOptions = {}) {
             const WebSocket = options.WebSocket ??

package/dist/conversation.d.ts

@@ -96,7 +96,7 @@ export type TurnOutcome = {
 export type TranscriptOutcome = {
     status: "done";
     text: string;
-    seconds: number;
+    audioSeconds: number;
     frame: TranscriptFrame;
 }
 /** The edge refused or failed it: a rate it does not take, no audio, the provider. */
@@ -108,7 +108,8 @@ export type TranscriptOutcome = {
 export interface Dropped {
     status: "dropped";
     reason: "closed" | "cancelled" | "refused";
-    detail?: string;
+    /** The edge's words for a refusal; `null` otherwise. */
+    message: string | null;
 }
 /** Why a conversation ended without reconnecting. */
 export interface CloseInfo {

package/dist/conversation.js

@@ -1,5 +1,5 @@
 import { wireBytes } from "./pcm.js";
-import { KEEPALIVE_S, MAX_AUDIO_BYTES, MAX_MESSAGE_CHARS, RECORDING_RATES, } from "./protocol.gen.js";
+import { KEEPALIVE_SECONDS, MAX_AUDIO_BYTES, MAX_MESSAGE_CHARS, RECORDING_RATES, } from "./protocol.gen.js";
 import { dial, isFinalClose, reconnectAfter, socketUrl, } from "./socket.js";
 /** No `ready` this long after the dial — a proxy that took the upgrade and says nothing — is a dropped connection. */
 export const READY_DEADLINE_MS = 15000;
@@ -52,9 +52,11 @@ function call(fn, value) {
         });
     }
 }
-const dropped = (reason, detail) => detail
-    ? { status: "dropped", reason, detail }
-    : { status: "dropped", reason };
+const dropped = (reason, message) => ({
+    status: "dropped",
+    reason,
+    message: message ?? null,
+});
 /** Characters as the edge counts them: code points. */
 function characters(text) {
     let n = 0;
@@ -164,7 +166,7 @@ export class Conversation {
             recording.dropped = "closed";
             return id;
         }
-        const frame = this.turnFrame({ type: "user_audio.start", id, rate }, options);
+        const frame = this.turnFrame({ type: "user_audio.start", recording_id: id, rate }, options);
         if (language)
             frame.language = language;
         if (model)
@@ -217,7 +219,7 @@ export class Conversation {
         if (failed) {
             return Promise.resolve(options.transcribeOnly
                 ? { status: "failed", frame: failed }
-                : dropped("refused", failed.detail));
+                : dropped("refused", failed.message));
         }
         if (recording.dropped || this.closed) {
             return Promise.resolve(dropped(recording.dropped ?? "closed"));
@@ -327,10 +329,10 @@ export class Conversation {
         this.deadline = setTimeout(() => this.drop(generation, "The connection never became ready."), READY_DEADLINE_MS);
         this.watchdog = setInterval(() => {
             const quiet = Date.now() - Math.max(this.heardAt, this.saidAt);
-            if (quiet > 2 * KEEPALIVE_S * 1000) {
+            if (quiet > 2 * KEEPALIVE_SECONDS * 1000) {
                 this.drop(generation, "Nothing came from the edge for a minute.");
             }
-        }, KEEPALIVE_S * 500);
+        }, KEEPALIVE_SECONDS * 500);
     }
     /** A socket given up on from this side: lost as a dropped network is (1006). */
     drop(generation, reason) {
@@ -586,7 +588,7 @@ export class Conversation {
         return false;
     }
     error(frame) {
-        if (frame.id) {
+        if (frame.recording_id) {
             this.refuse(frame);
             return;
         }
@@ -597,14 +599,14 @@ export class Conversation {
         const pending = this.inFlight;
         if (pending && !pending.started) {
             this.inFlight = null;
-            pending.resolve(dropped("refused", frame.detail));
+            pending.resolve(dropped("refused", frame.message));
             this.update({ done: true });
             this.sync();
         }
     }
     /** An error naming a recording: it was refused, or failed. */
     refuse(frame) {
-        const { id } = frame;
+        const id = frame.recording_id;
         const open = this.open;
         if (open && open.id === id) {
             open.failed = frame;
@@ -618,23 +620,23 @@ export class Conversation {
         const pending = this.inFlight;
         if (pending && pending.recording?.id === id && !pending.started) {
             this.inFlight = null;
-            pending.resolve(dropped("refused", frame.detail));
+            pending.resolve(dropped("refused", frame.message));
             this.update({ done: true });
         }
         this.emit({ caption: null });
         this.sync();
     }
     transcript(frame) {
-        // By its id; the oldest, from an edge that echoes none.
-        const recording = frame.id
-            ? this.hearing.find((r) => r.id === frame.id)
+        // By its id; the oldest, when it names none.
+        const recording = frame.recording_id
+            ? this.hearing.find((r) => r.id === frame.recording_id)
             : this.hearing[0];
         if (recording) {
             this.hearing = this.hearing.filter((r) => r !== recording);
             recording.settle?.({
                 status: "done",
                 text: frame.text,
-                seconds: frame.seconds,
+                audioSeconds: frame.audio_seconds,
                 frame,
             });
         }

package/dist/errors.d.ts

@@ -4,43 +4,51 @@
  * caller acts on differently.
  *
  * The API answers its errors in one envelope —
- * `{"error":{"type","message","request_id","details"?}}`
- * (`apps/api/src/http/errors.ts`) — and `type` is the thing to switch on.
- * Two bodies are not that envelope, and are read here too:
- * - **the 400 the document declares** on every route with a body or a path
- *   parameter, `{status_code, detail, extra}`;
- * - **Cloudflare's own refusal**, `error code: 1010` as plain text with no
- *   `X-Request-Id`: the request never reached the API, so there is no id
- *   to report.
+ * `{"error":{"code","message","request_id","issues"}}`
+ * (`apps/api/src/http/errors.ts`) — and `code` is the thing to switch on.
+ * One body is not that envelope, and is read here too: **Cloudflare's own
+ * refusal**, `error code: 1010` as plain text with no `X-Request-Id` — the
+ * request never reached the API, so there is no id to report.
  */
+import type { ErrorCode, ValidationIssue } from "./gen/index.js";
+export type { ErrorCode, ValidationIssue };
 /** What one error says, as the SDK read it. */
 export interface PlatformErrorInit {
     status: number;
-    type: string;
+    code: PlatformErrorCode;
     message: string;
     requestId: string | null;
-    details?: unknown;
+    issues?: ValidationIssue[];
     retryAfter?: number | null;
     cause?: unknown;
 }
+/**
+ * The API's codes, and the SDK's own for an answer that was not the API's:
+ * `cloudflare_error`, `http_error` (an error body that was not the
+ * envelope), `invalid_response` (a success that was not JSON),
+ * `connection_error` and `timeout` — and `client_error`, no request at
+ * all: the app's own code (its `getToken`) threw, as `@lumavox/react`
+ * reports it.
+ */
+export type PlatformErrorCode = ErrorCode | "cloudflare_error" | "http_error" | "invalid_response" | "connection_error" | "timeout" | "client_error";
 export declare class PlatformError extends Error {
     name: string;
     /** The HTTP status; `0` when no response came back. */
     readonly status: number;
-    /** The API's machine-readable category: `validation_error`, `rate_limit_error`, … */
-    readonly type: string;
+    /** What went wrong: the API's `code` — `validation_failed`, `rate_limited`, … */
+    readonly code: PlatformErrorCode;
     /**
      * The request's `X-Request-Id` — the one the SDK sent, which the API
      * keeps. `null` only when Cloudflare refused it before the API saw it.
      */
     readonly requestId: string | null;
-    /** Field-level problems on a 422; the 400's `extra`; otherwise `undefined`. */
-    readonly details: unknown;
+    /** Where a request failed validation; empty otherwise. */
+    readonly issues: ValidationIssue[];
     /** Seconds to wait before trying again, from `Retry-After`; `null` without one. */
     readonly retryAfter: number | null;
     constructor(init: PlatformErrorInit);
 }
-/** 400 or 422: the request is malformed or failed validation; `details` says where. */
+/** 400 or 422: the request is malformed or failed validation; `issues` says where. */
 export declare class ValidationError extends PlatformError {
     name: string;
 }
@@ -60,7 +68,7 @@ export declare class PermissionError extends PlatformError {
 export declare class NotFoundError extends PlatformError {
     name: string;
 }
-/** 409: a plan's maximum, or an id already taken. */
+/** 409: a plan's maximum, an id already taken, or a change since it was read. */
 export declare class ConflictError extends PlatformError {
     name: string;
 }

package/dist/errors.js

@@ -1,18 +1,3 @@
-/**
- * Every failure the SDK throws: a `PlatformError`, so one `catch` with
- * `instanceof PlatformError` sees them all, and a subclass per status a
- * caller acts on differently.
- *
- * The API answers its errors in one envelope —
- * `{"error":{"type","message","request_id","details"?}}`
- * (`apps/api/src/http/errors.ts`) — and `type` is the thing to switch on.
- * Two bodies are not that envelope, and are read here too:
- * - **the 400 the document declares** on every route with a body or a path
- *   parameter, `{status_code, detail, extra}`;
- * - **Cloudflare's own refusal**, `error code: 1010` as plain text with no
- *   `X-Request-Id`: the request never reached the API, so there is no id
- *   to report.
- */
 export class PlatformError extends Error {
     constructor(init) {
         // `init` is the options too: `Error` reads only its `cause`.
@@ -20,13 +5,13 @@ export class PlatformError extends Error {
         // Written out, not `new.target.name`: a customer's minifier renames classes.
         this.name = "PlatformError";
         this.status = init.status;
-        this.type = init.type;
+        this.code = init.code;
         this.requestId = init.requestId;
-        this.details = init.details;
+        this.issues = init.issues ?? [];
         this.retryAfter = init.retryAfter ?? null;
     }
 }
-/** 400 or 422: the request is malformed or failed validation; `details` says where. */
+/** 400 or 422: the request is malformed or failed validation; `issues` says where. */
 export class ValidationError extends PlatformError {
     constructor() {
         super(...arguments);
@@ -61,7 +46,7 @@ export class NotFoundError extends PlatformError {
         this.name = "NotFoundError";
     }
 }
-/** 409: a plan's maximum, or an id already taken. */
+/** 409: a plan's maximum, an id already taken, or a change since it was read. */
 export class ConflictError extends PlatformError {
     constructor() {
         super(...arguments);
@@ -132,34 +117,29 @@ export function errorFromResponse(status, headers, text, sentRequestId) {
         body = undefined;
     }
     const e = isObject(body) && isObject(body.error) ? body.error : null;
-    const code = /^error code: (\d+)/.exec(text.trim())?.[1];
+    const cloudflare = /^error code: (\d+)/.exec(text.trim())?.[1];
     const snippet = text.trim().slice(0, 200);
     const said = e
         ? {
-            type: typeof e.type === "string" ? e.type : "unknown_error",
+            code: typeof e.code === "string"
+                ? e.code
+                : "http_error",
             message: typeof e.message === "string" ? e.message : http,
             requestId: typeof e.request_id === "string" ? e.request_id : requestId,
-            details: e.details ?? undefined,
+            issues: Array.isArray(e.issues) ? e.issues : [],
         }
-        : isObject(body) && typeof body.detail === "string"
+        : cloudflare && answered === null
             ? {
-                type: "invalid_request",
-                message: body.detail,
-                requestId,
-                details: body.extra ?? undefined,
+                code: "cloudflare_error",
+                message: `Cloudflare refused the request with error code ${cloudflare} ` +
+                    "before it reached the API.",
+                requestId: null,
             }
-            : code && answered === null
-                ? {
-                    type: "cloudflare_error",
-                    message: `Cloudflare refused the request with error code ${code} ` +
-                        "before it reached the API.",
-                    requestId: null,
-                }
-                : {
-                    type: "http_error",
-                    message: snippet ? `${http}: ${snippet}` : http,
-                    requestId,
-                };
+            : {
+                code: "http_error",
+                message: snippet ? `${http}: ${snippet}` : http,
+                requestId,
+            };
     return new (classOf(status))({
         ...said,
         status,

package/dist/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * Every frame the edge sends, as it sends it: the wire's own field names,
  * snake_case included, so the docs' WebSocket page and these types read
- * the same.
+ * the same — and every field always there, `null` where it does not apply.
  *
  * **Hand-written, and held twice.** `ServerFrames` is keyed by the event
  * names `protocol.gen.ts` takes from the edge's vocabulary, so an event the
@@ -9,7 +9,7 @@
  * test (`apps/edge/test/sdk.test.ts`) holds every field of every frame the
  * real conversation object sends to these, both ways.
  */
-import type { RelationInfo } from "./gen/index.js";
+import type { ErrorCode, RelationInfo } from "./gen/index.js";
 import type { ServerEventName } from "./protocol.gen.js";
 interface Frame<T extends ServerEventName> {
     type: T;
@@ -51,7 +51,8 @@ export interface TurnStartFrame extends Frame<"turn.start">, InTurn {
 /** A spoken turn's transcript, before the reply. */
 export interface HeardFrame extends Frame<"heard">, InTurn {
     text: string;
-    seconds: number;
+    /** How long the recording was. */
+    audio_seconds: number;
 }
 /** The open recording as heard so far: a caption, replaced by the next. */
 export interface HeardPartialFrame extends Frame<"heard.partial"> {
@@ -60,10 +61,11 @@ export interface HeardPartialFrame extends Frame<"heard.partial"> {
 /** A `transcribeOnly` recording's words: part of no turn. */
 export interface TranscriptFrame extends Frame<"transcript"> {
     text: string;
-    seconds: number;
+    /** How long the recording was. */
+    audio_seconds: number;
     request_id: string;
     /** The recording's id, which the SDK names every recording with. */
-    id?: string;
+    recording_id: string | null;
 }
 export interface MoodFrame extends Frame<"mood">, InTurn {
     mood: string;
@@ -109,7 +111,7 @@ export interface AudioStartFrame extends Frame<"audio.start">, InTurn, AudioForm
 export interface AudioEndFrame extends Frame<"audio.end">, InTurn {
     chunk: number;
     bytes: number;
-    audio_s: number;
+    audio_seconds: number;
 }
 /** After `mute`, once the last audio window has closed. */
 export interface MutedFrame extends Frame<"muted">, InTurn {
@@ -150,10 +152,8 @@ export interface TurnDoneFrame extends Frame<"turn.done">, InTurn {
     output_tokens: number | null;
     mood: string | null;
     mood_intensity: number | null;
-    /** Always `null`: a relationship that moved arrives as its own frame. */
-    relation: null;
-    /** `true` when the reply was cut short. */
-    truncated: true | null;
+    /** Whether the reply was cut short. */
+    truncated: boolean;
     chunks_spoken: number;
     heard: string | null;
     heard_seconds: number | null;
@@ -164,22 +164,27 @@ export interface InterruptedFrame extends Frame<"interrupted">, InTurn {
     message: string;
     mood: string | null;
     mood_intensity: number | null;
-    detail: string | null;
+    /** Why it stopped: `cancel`, or the failure its `error` named. */
+    reason: string | null;
 }
 /**
  * Something went wrong. It does not end the connection, and inside a turn
- * it does not end the turn. `detail` alone: a frame refused; `stage:
- * "speech"`: the reply could not be spoken; `status`: the turn or a
- * `transcribeOnly` recording failed.
+ * it does not end the turn. `code` is the REST API's (`conflict` for a
+ * turn already running, `insufficient_credits`, `provider_failed`, …);
+ * `stage: "speech"` when only the speaking failed.
  */
 export interface ErrorFrame extends Frame<"error"> {
-    detail: string;
-    turn?: string;
-    status?: number;
-    stage?: string;
-    request_id?: string;
+    code: ErrorCode;
+    message: string;
+    /** The turn it ended or interrupted. */
+    turn: string | null;
+    stage: "speech" | null;
+    /** The reply's chunk that could not be spoken. */
+    chunk: number | null;
+    /** A `transcribeOnly` recording's request. */
+    request_id: string | null;
     /** The recording it refused or failed. */
-    id?: string;
+    recording_id: string | null;
 }
 /** The answer to `ping`, and sent unprompted after 30 s of client silence. */
 export interface PongFrame extends Frame<"pong"> {