@lumavox/client 0.0.0-stage → 0.1.1

package/dist/errors.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/** What one error says, as the SDK read it. */
+export interface PlatformErrorInit {
+    status: number;
+    type: string;
+    message: string;
+    requestId: string | null;
+    details?: unknown;
+    retryAfter?: number | null;
+    cause?: unknown;
+}
+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;
+    /**
+     * 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;
+    /** 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. */
+export declare class ValidationError extends PlatformError {
+    name: string;
+}
+/** 401: no credential, a wrong one, or one that expired or was revoked. */
+export declare class AuthenticationError extends PlatformError {
+    name: string;
+}
+/** 402: the balance cannot cover it, or the organisation is suspended or on no plan. */
+export declare class InsufficientCreditsError extends PlatformError {
+    name: string;
+}
+/** 403: the key's scopes do not cover this, or the waitlist holds the organisation. */
+export declare class PermissionError extends PlatformError {
+    name: string;
+}
+/** 404: nothing by that id in this organisation. */
+export declare class NotFoundError extends PlatformError {
+    name: string;
+}
+/** 409: a plan's maximum, or an id already taken. */
+export declare class ConflictError extends PlatformError {
+    name: string;
+}
+/** 429: a request window or the plan's mint rate; `retryAfter` says when. */
+export declare class RateLimitError extends PlatformError {
+    name: string;
+}
+/** 5xx: the API or something behind it failed. */
+export declare class ServerError extends PlatformError {
+    name: string;
+}
+/** No response: DNS, TLS, a reset connection. `cause` is what `fetch` threw. */
+export declare class ConnectionError extends PlatformError {
+    name: string;
+}
+/** No response within `timeoutMs`, on the last attempt. */
+export declare class TimeoutError extends PlatformError {
+    name: string;
+}
+/** `Retry-After` as seconds: a number of them, or an HTTP date. */
+export declare function retryAfterOf(headers: Headers): number | null;
+/** The error a non-2xx response stands for, from its status, headers and body text. */
+export declare function errorFromResponse(status: number, headers: Headers, text: string, sentRequestId: string): PlatformError;

package/dist/errors.js

@@ -0,0 +1,168 @@
+/**
+ * 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`.
+        super(init.message, init);
+        // Written out, not `new.target.name`: a customer's minifier renames classes.
+        this.name = "PlatformError";
+        this.status = init.status;
+        this.type = init.type;
+        this.requestId = init.requestId;
+        this.details = init.details;
+        this.retryAfter = init.retryAfter ?? null;
+    }
+}
+/** 400 or 422: the request is malformed or failed validation; `details` says where. */
+export class ValidationError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "ValidationError";
+    }
+}
+/** 401: no credential, a wrong one, or one that expired or was revoked. */
+export class AuthenticationError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "AuthenticationError";
+    }
+}
+/** 402: the balance cannot cover it, or the organisation is suspended or on no plan. */
+export class InsufficientCreditsError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "InsufficientCreditsError";
+    }
+}
+/** 403: the key's scopes do not cover this, or the waitlist holds the organisation. */
+export class PermissionError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "PermissionError";
+    }
+}
+/** 404: nothing by that id in this organisation. */
+export class NotFoundError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "NotFoundError";
+    }
+}
+/** 409: a plan's maximum, or an id already taken. */
+export class ConflictError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "ConflictError";
+    }
+}
+/** 429: a request window or the plan's mint rate; `retryAfter` says when. */
+export class RateLimitError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "RateLimitError";
+    }
+}
+/** 5xx: the API or something behind it failed. */
+export class ServerError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "ServerError";
+    }
+}
+/** No response: DNS, TLS, a reset connection. `cause` is what `fetch` threw. */
+export class ConnectionError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "ConnectionError";
+    }
+}
+/** No response within `timeoutMs`, on the last attempt. */
+export class TimeoutError extends PlatformError {
+    constructor() {
+        super(...arguments);
+        this.name = "TimeoutError";
+    }
+}
+const BY_STATUS = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+};
+const classOf = (status) => BY_STATUS[status] ?? (status >= 500 ? ServerError : PlatformError);
+/** `Retry-After` as seconds: a number of them, or an HTTP date. */
+export function retryAfterOf(headers) {
+    const value = headers.get("retry-after")?.trim();
+    if (!value)
+        return null;
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : Math.max(0, (at - Date.now()) / 1000);
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The error a non-2xx response stands for, from its status, headers and body text. */
+export function errorFromResponse(status, headers, text, sentRequestId) {
+    const answered = headers.get("x-request-id");
+    const requestId = answered ?? sentRequestId;
+    const http = `HTTP ${status}`;
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        // swallowed: not JSON — Cloudflare's text, or a proxy's page; read below.
+        body = undefined;
+    }
+    const e = isObject(body) && isObject(body.error) ? body.error : null;
+    const code = /^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",
+            message: typeof e.message === "string" ? e.message : http,
+            requestId: typeof e.request_id === "string" ? e.request_id : requestId,
+            details: e.details ?? undefined,
+        }
+        : isObject(body) && typeof body.detail === "string"
+            ? {
+                type: "invalid_request",
+                message: body.detail,
+                requestId,
+                details: body.extra ?? undefined,
+            }
+            : 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,
+                };
+    return new (classOf(status))({
+        ...said,
+        status,
+        retryAfter: retryAfterOf(headers),
+    });
+}

package/dist/events.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ *
+ * **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
+ * edge gains fails `tsc` here until it has a type; and the edge's contract
+ * 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 { ServerEventName } from "./protocol.gen.js";
+interface Frame<T extends ServerEventName> {
+    type: T;
+    /** Rises by one with every frame on the connection. */
+    seq: number;
+}
+/** Inside a turn: the id from its `turn.start`. */
+interface InTurn {
+    turn: string;
+}
+/** How audio is encoded: `pcm_s16le`, its rate, and one channel. */
+export interface AudioFormat {
+    codec: string;
+    sample_rate: number;
+    channels: number;
+}
+export interface ReadyFrame extends Frame<"ready"> {
+    protocol: string;
+    session_id: string;
+    agent_id: string;
+    end_user_id: string;
+    /** Whether the agent replies with audio. */
+    speaks: boolean;
+    /** The format replies come back in. */
+    audio: AudioFormat;
+    /** What a recording is assumed to be when `startAudio` names no rate. */
+    hearing: AudioFormat;
+    emotion: boolean;
+    /** The standing relationship; `null` when the agent keeps none. */
+    relation: RelationInfo | null;
+    /** The agent speaks first: a turn is already running. */
+    greeting: boolean;
+    idle_seconds: number;
+    edge_version: string;
+}
+export interface TurnStartFrame extends Frame<"turn.start">, InTurn {
+    session_id: string;
+}
+/** A spoken turn's transcript, before the reply. */
+export interface HeardFrame extends Frame<"heard">, InTurn {
+    text: string;
+    seconds: number;
+}
+/** The open recording as heard so far: a caption, replaced by the next. */
+export interface HeardPartialFrame extends Frame<"heard.partial"> {
+    text: string;
+}
+/** A `transcribeOnly` recording's words: part of no turn. */
+export interface TranscriptFrame extends Frame<"transcript"> {
+    text: string;
+    seconds: number;
+    request_id: string;
+    /** The recording's id, which the SDK names every recording with. */
+    id?: string;
+}
+export interface MoodFrame extends Frame<"mood">, InTurn {
+    mood: string;
+    /** 0 to 1, or `null` when the model gave none. */
+    intensity: number | null;
+}
+/** A piece of the reply as the model writes it. */
+export interface TextDeltaFrame extends Frame<"text.delta">, InTurn {
+    text: string;
+}
+/** A piece of the reply cut for speech; its audio has the same `chunk`. */
+export interface TextChunkFrame extends Frame<"text.chunk">, InTurn {
+    chunk: number;
+    text: string;
+}
+/** A piece of a thinking summary, when the turn asked for `thoughts`. */
+export interface ThoughtDeltaFrame extends Frame<"thought.delta">, InTurn {
+    text: string;
+}
+export interface ToolStartFrame extends Frame<"tool.start">, InTurn {
+    name: string;
+}
+export interface ToolEndFrame extends Frame<"tool.end">, InTurn {
+    name: string;
+}
+export interface KnowledgeEntry {
+    entry_id: string;
+    title: string;
+    score: number;
+}
+/** The agent looked something up in its knowledge. */
+export interface KnowledgeFrame extends Frame<"knowledge">, InTurn {
+    /** `first`, before the reply, or `tool`, when the model asked. */
+    via: string;
+    /** `found`, `none` or `failed`. */
+    outcome: string;
+    entries: KnowledgeEntry[];
+}
+/** An audio window opens: the binary frames until `audio.end` are its PCM. */
+export interface AudioStartFrame extends Frame<"audio.start">, InTurn, AudioFormat {
+    chunk: number;
+}
+export interface AudioEndFrame extends Frame<"audio.end">, InTurn {
+    chunk: number;
+    bytes: number;
+    audio_s: number;
+}
+/** After `mute`, once the last audio window has closed. */
+export interface MutedFrame extends Frame<"muted">, InTurn {
+}
+/** The relationship moved on this turn: its new fields. */
+export interface RelationFrame extends Frame<"relation">, InTurn, RelationInfo {
+}
+export interface UsageFrame extends Frame<"usage">, InTurn {
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    thought_tokens: number | null;
+    cached_tokens: number | null;
+    generation_seconds: number;
+}
+/** Where a turn's time went, in milliseconds from the message; `null` for a step it did not take. */
+export interface TurnTimings {
+    heard_ms: number | null;
+    knowledge_ms: number | null;
+    model_request_ms: number | null;
+    model_head_ms: number | null;
+    model_first_thought_ms: number | null;
+    model_first_text_ms: number | null;
+    first_text_sent_ms: number | null;
+    first_audio_sent_ms: number | null;
+    model_done_ms: number | null;
+    total_ms: number;
+    model_attempts: number | null;
+    /** The Cloudflare location the conversation runs in. */
+    colo: string | null;
+}
+/** The turn finished: the whole reply, so a client that ignored every delta is still right. */
+export interface TurnDoneFrame extends Frame<"turn.done">, InTurn {
+    session_id: string;
+    message: string;
+    model: string | null;
+    input_tokens: number | null;
+    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;
+    chunks_spoken: number;
+    heard: string | null;
+    heard_seconds: number | null;
+    timings: TurnTimings;
+}
+/** The turn ended early; what was written before it stopped still stands. */
+export interface InterruptedFrame extends Frame<"interrupted">, InTurn {
+    message: string;
+    mood: string | null;
+    mood_intensity: number | null;
+    detail: 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.
+ */
+export interface ErrorFrame extends Frame<"error"> {
+    detail: string;
+    turn?: string;
+    status?: number;
+    stage?: string;
+    request_id?: string;
+    /** The recording it refused or failed. */
+    id?: string;
+}
+/** The answer to `ping`, and sent unprompted after 30 s of client silence. */
+export interface PongFrame extends Frame<"pong"> {
+}
+/**
+ * Every event, by name. **Exhaustive**: a name in the vocabulary with no
+ * entry, an entry the vocabulary does not name, or an entry whose `type`
+ * is another's, fails to type-check.
+ */
+export type ServerFrames = Exhaustive<{
+    ready: ReadyFrame;
+    "turn.start": TurnStartFrame;
+    heard: HeardFrame;
+    "heard.partial": HeardPartialFrame;
+    transcript: TranscriptFrame;
+    mood: MoodFrame;
+    "text.delta": TextDeltaFrame;
+    "text.chunk": TextChunkFrame;
+    "thought.delta": ThoughtDeltaFrame;
+    "tool.start": ToolStartFrame;
+    "tool.end": ToolEndFrame;
+    knowledge: KnowledgeFrame;
+    "audio.start": AudioStartFrame;
+    "audio.end": AudioEndFrame;
+    muted: MutedFrame;
+    relation: RelationFrame;
+    usage: UsageFrame;
+    "turn.done": TurnDoneFrame;
+    interrupted: InterruptedFrame;
+    error: ErrorFrame;
+    pong: PongFrame;
+}>;
+type Exhaustive<T extends {
+    [K in ServerEventName]: {
+        type: K;
+    };
+} & {
+    [K in Exclude<keyof T, ServerEventName>]: never;
+}> = T;
+/** Any frame the edge sends. */
+export type ServerFrame = ServerFrames[ServerEventName];
+export {};

package/dist/events.js

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

package/dist/gen/index.d.ts

@@ -0,0 +1 @@
+export type { ClientOptions, CompactData, CompactError, CompactErrors, CompactionInfo, CompactRequest, CompactResponse, CompactResponses, CreateSessionData, CreateSessionError, CreateSessionErrors, CreateSessionResponse, CreateSessionResponses, DeleteSessionData, DeleteSessionError, DeleteSessionErrors, DeleteSessionResponse, DeleteSessionResponses, ErrorInfo, ErrorResponse, ExtractData, ExtractError, ExtractErrors, ExtractResponse, ExtractResponses, FactInfo, FactList, ForgetFactData, ForgetFactError, ForgetFactErrors, ForgetFactResponse, ForgetFactResponses, ForgetUserFactsData, ForgetUserFactsError, ForgetUserFactsErrors, ForgetUserFactsResponse, ForgetUserFactsResponses, ForgottenFacts, GetSessionDetailData, GetSessionDetailError, GetSessionDetailErrors, GetSessionDetailResponse, GetSessionDetailResponses, KnowledgeCitation, KnowledgeLookupInfo, ListFactsData, ListFactsError, ListFactsErrors, ListFactsResponse, ListFactsResponses, ListRelationsData, ListRelationsError, ListRelationsErrors, ListRelationsResponse, ListRelationsResponses, ListSessionsData, ListSessionsError, ListSessionsErrors, ListSessionsResponse, ListSessionsResponses, MessageInfo, MessageKnowledge, RelationInfo, RelationList, SessionCreateRequest, SessionDetail, SessionInfo } from './types.gen.js';

package/dist/gen/index.js

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