@lumavox/server 0.0.0-stage → 0.2.1

package/dist/upload.js

@@ -0,0 +1,34 @@
+/** The data's size, when it can be told without reading it. */
+export const sizeOf = (data, size) => size ??
+    (data instanceof ReadableStream
+        ? undefined
+        : data instanceof Blob
+            ? data.size
+            : data.byteLength);
+/** The data's type: the caller's, or a Blob's own; `""` when neither says. */
+export const typeOf = (data, type) => type || (data instanceof Blob ? data.type : "");
+/** `type`, or a `TypeError` naming what to pass. */
+export function needType(data, type) {
+    const found = typeOf(data, type);
+    if (!found)
+        throw new TypeError("This upload needs its content_type.");
+    return found;
+}
+/** The bytes, to a ticket's signed URL, valid for its `expires_in` seconds. */
+export async function put(api, ticket, data, type, options) {
+    let raw = data;
+    const headers = {};
+    if (data instanceof ReadableStream) {
+        const size = options.size;
+        if (size === undefined) {
+            throw new TypeError("A stream uploads only with its size: { size }.");
+        }
+        headers["Content-Length"] = String(size);
+        // Workers' own class, read off the global: no other runtime has it,
+        // nor do the types a customer compiles against.
+        const { FixedLengthStream: Fixed } = globalThis;
+        if (Fixed)
+            raw = data.pipeThrough(new Fixed(size));
+    }
+    await api.request({ method: "PUT", path: ticket.url, raw, type, headers, open: true }, { ...options, timeoutMs: options.timeoutMs ?? ticket.expires_in * 1000 });
+}

package/dist/wait.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Waiting on a job: the API has no route for "a job" — each kind is read
+ * where it lives (a generation, a voice, an asset, a knowledge entry), and
+ * each says how it went in its `status`. `wait(id)` reads it until that
+ * status is no longer one of work in progress.
+ *
+ * - **One set of in-progress states for every kind**: a generation is
+ *   `queued`, `submitted` or `running`, the rest `pending`, and a
+ *   knowledge file or page `importing` before that — which the document
+ *   does not list (left-overs #113; `STATUSES` in
+ *   `apps/api/src/knowledge/service.ts`). Anything else — `succeeded`,
+ *   `failed`, `moderated`, `ready`, or a state this release does not know
+ *   — ends the wait, so a new one cannot hang a caller.
+ * - **It answers the last read, never throws for a failure**: a `failed`
+ *   or `moderated` generation is refunded, and its `error` says why — the
+ *   caller reads `status`, as the API's own docs say to.
+ * - **The polls**: 1 s, then ×1.5 each time, at most 10 s apart. The
+ *   caller's `signal` ends the wait (`AbortSignal.timeout(…)` for a
+ *   deadline); otherwise the job's own deadline does, which refunds what
+ *   never reports (the API's `settlers.ts`).
+ * - **Its ceiling is the organisation's Durable Object, not a rate
+ *   limit**: a poll is unmetered, so the per-minute window
+ *   (`RATE_LIMIT_RPM`, the org's, which only metered routes count) never
+ *   sees it (`admit` in `apps/api/src/org/object.ts`). Each poll is two
+ *   calls on the org's DO — its admission and the read — so at the 10 s
+ *   cap 2,500 waits at once are 500 calls a second, the DO's trigger in
+ *   the root `CLAUDE.md`; in their first second, 250 are.
+ */
+import { type RequestOptions } from "./transport.js";
+/**
+ * A job as each kind's read answers it: with a `status` — which the
+ * document lets an asset and an entry leave out (it has a default), and
+ * which, absent, is no work in progress.
+ */
+export interface Job {
+    status?: string;
+}
+/**
+ * Reads `read` until its status is final, starting from `first` (a job
+ * just made, so the first read waits) or with a read now.
+ */
+export declare function poll<T extends Job>(read: () => Promise<T>, options?: RequestOptions, first?: T): Promise<T>;

package/dist/wait.js

@@ -0,0 +1,51 @@
+/**
+ * Waiting on a job: the API has no route for "a job" — each kind is read
+ * where it lives (a generation, a voice, an asset, a knowledge entry), and
+ * each says how it went in its `status`. `wait(id)` reads it until that
+ * status is no longer one of work in progress.
+ *
+ * - **One set of in-progress states for every kind**: a generation is
+ *   `queued`, `submitted` or `running`, the rest `pending`, and a
+ *   knowledge file or page `importing` before that — which the document
+ *   does not list (left-overs #113; `STATUSES` in
+ *   `apps/api/src/knowledge/service.ts`). Anything else — `succeeded`,
+ *   `failed`, `moderated`, `ready`, or a state this release does not know
+ *   — ends the wait, so a new one cannot hang a caller.
+ * - **It answers the last read, never throws for a failure**: a `failed`
+ *   or `moderated` generation is refunded, and its `error` says why — the
+ *   caller reads `status`, as the API's own docs say to.
+ * - **The polls**: 1 s, then ×1.5 each time, at most 10 s apart. The
+ *   caller's `signal` ends the wait (`AbortSignal.timeout(…)` for a
+ *   deadline); otherwise the job's own deadline does, which refunds what
+ *   never reports (the API's `settlers.ts`).
+ * - **Its ceiling is the organisation's Durable Object, not a rate
+ *   limit**: a poll is unmetered, so the per-minute window
+ *   (`RATE_LIMIT_RPM`, the org's, which only metered routes count) never
+ *   sees it (`admit` in `apps/api/src/org/object.ts`). Each poll is two
+ *   calls on the org's DO — its admission and the read — so at the 10 s
+ *   cap 2,500 waits at once are 500 calls a second, the DO's trigger in
+ *   the root `CLAUDE.md`; in their first second, 250 are.
+ */
+import { sleep } from "./transport.js";
+const IN_PROGRESS = [
+    "queued",
+    "submitted",
+    "running",
+    "pending",
+    "importing",
+];
+const FIRST_MS = 1_000;
+const MAX_MS = 10_000;
+/**
+ * Reads `read` until its status is final, starting from `first` (a job
+ * just made, so the first read waits) or with a read now.
+ */
+export async function poll(read, options = {}, first) {
+    let job = first ?? (await read());
+    for (let ms = FIRST_MS; IN_PROGRESS.includes(job.status);) {
+        await sleep(ms, options.signal);
+        job = await read();
+        ms = Math.min(ms * 1.5, MAX_MS);
+    }
+    return job;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@lumavox/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "The Lumavox API from your server: end users, ephemeral keys and the rest, typed from the published OpenAPI document. Zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/refuse.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "workerd": "./dist/index.js",
+      "worker": "./dist/index.js",
+      "edge-light": "./dist/index.js",
+      "deno": "./dist/index.js",
+      "bun": "./dist/index.js",
+      "node": "./dist/index.js",
+      "react-native": "./dist/refuse.js",
+      "browser": "./dist/refuse.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "generate": "openapi-ts",
+    "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",
+    "@cloudflare/vitest-plugin": "1.4.7",
+    "@cloudflare/workers-types": "^5.20261022.1",
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@types/node": "^24",
+    "esbuild": "^0.28.1",
+    "typescript": "^6",
+    "vitest": "^4.1.12"
+  }
+}