abysshub 0.0.0-stage → 0.0.1-dev.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abyss
+
+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,144 @@
-# Temporary Holding Version
+# abysshub
 
-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.
+The official JavaScript library for the [Abyss](https://abysshub.com) API.
+
+Pre-release: the Abyss API opens soon.
+
+```js
+import { Abyss, AbyssError } from "abysshub";
+
+const abyss = new Abyss(); // reads ABYSS_API_KEY
+
+try {
+  const run = await abyss.run("widget_131", { amount: 250000 });
+  console.log(run.result);
+} catch (error) {
+  if (error instanceof AbyssError) console.error(error.code, error.param, error.request_id, error.run);
+  else throw error;
+}
+```
+
+`run()` presses the Widget and waits for the run to end, however long it takes, then returns the succeeded run. A refusal or a failed run raises `AbyssError`.
+
+It runs on Node 20+, Bun and Deno, with no dependencies. An API key is a server-side secret, so in a browser `new Abyss()` throws.
+
+## The client
+
+```js
+const abyss = new Abyss({ apiKey, baseURL, maxRetries, timeout });
+```
+
+- **`apiKey`:** defaults to `ABYSS_API_KEY`. Without a key, `new Abyss()` raises `AbyssError` with `code: "invalid_api_key"`.
+- **`baseURL`:** defaults to `ABYSS_BASE_URL`, else `https://api.abysshub.com`. A key starting `abyss_sk_dev_` goes to `https://api.dev.abysshub.com`.
+- **`maxRetries`:** how many times a request is sent again (see [Retries](#retries)). Defaults to 2.
+- **`timeout`:** the seconds every call waits at most, unless it sets its own (see [Timeouts](#timeouts)). None by default.
+
+Every request sends `Authorization: Bearer <key>` and `User-Agent: abysshub-js/<version> (<runtime> <version>)`.
+
+## Running a Widget
+
+```js
+const run = await abyss.run(widget, input, { maxPrice, idempotencyKey, timeout, signal });
+```
+
+- **`widget`** is `widget_<id>`, or an unlisted Widget's private token.
+- **`input`** is the Widget's Fields by name (`GET /v1/widgets/{widget}` lists them as `input_schema`). A file Field takes a file (see [Files](#files)).
+- **`maxPrice`:** the most the run may cost, in Byssium. A higher price is refused with `price_above_max`, and nothing is charged.
+- **`idempotencyKey`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one. Retries send the same one, so a run is never made or charged twice.
+
+The press holds until the run ends. When the hold ends early (a deploy cuts it, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
+
+A **run** has `/v1`'s fields: `id`, `widget`, `status` (`queued`, `running`, `succeeded` or `failed`), `price`, `result`, `output_files`, `error`, `created_at`, `started_at` and `ended_at`.
+
+## The routes
+
+Under `run()` there is one method per route. Each takes `timeout` and `signal` in its last argument.
+
+| Method | Route | Answers |
+|---|---|---|
+| `abyss.runs.create(widget, input, { maxPrice?, idempotencyKey? })` | `POST /v1/widgets/{widget}/runs` with `"wait": false` | the run, `queued`, at once |
+| `abyss.runs.get(id, { wait? })` | `GET /v1/runs/{id}`, with `?wait=true` when `wait` | the run |
+| `abyss.runs.list({ limit?, startingAfter? })` | `GET /v1/runs?limit=&starting_after=` | `{ data, has_more }`, newest first |
+| `abyss.widgets.get(widget)` | `GET /v1/widgets/{widget}` | `{ id, name, description, url, price, free_runs, input_schema }` |
+| `abyss.uploads.create(widget, { field, filename, size? })` | `POST /v1/widgets/{widget}/uploads` | `{ id, upload: { url, fields } }` |
+| `abyss.key()` | `GET /v1/key` | `{ name, key, user, spend_cap, spent_this_month, created_at }` |
+
+```js
+const queued = await abyss.runs.create("widget_131", { amount: 250000 });
+// … later, or in another process:
+const run = await abyss.runs.get(queued.id, { wait: true });
+
+let page = await abyss.runs.list({ limit: 100 });
+while (page.has_more) page = await abyss.runs.list({ limit: 100, startingAfter: page.data.at(-1).id });
+```
+
+- **`runs.create()`** uploads the input's files like `run()`, then answers without waiting.
+- **`runs.get()`** answers the run as it is, failed or not: only `run()` raises a failed run. With `wait`, it holds until the run ends, reading again when the hold is cut. A hold answers after an hour, or at once when the API's holds are all taken, so read again while `status` is `queued` or `running`.
+- **`runs.list()`** answers each of `data` as a run, with `save()` and `output_files`.
+- **`uploads.create()`** only asks for the grant. To upload by hand, POST every `fields` entry, then the file as `file`, to `url`, and put `id` in the input.
+
+## Files
+
+```js
+import { Abyss, file } from "abysshub";
+
+const run = await abyss.run("widget_1660", {
+  report: file("report.pdf"),
+  data: [file("jan.csv"), new File([csv], "feb.csv"), "https://example.com/sales/mar.csv"],
+});
+const paths = await run.save("output"); // ["output/charts/a.png", "output/output.json"]
+```
+
+- **`file(path)`** is a file on disk, read when it is uploaded. A file Field also takes a `Blob` or `File`, a `Buffer` or `Uint8Array`, or a stream (a web `ReadableStream`, or any async iterable such as `fs.createReadStream()`). `file(data, { filename })` names data. A file without a name uploads under its Field's name.
+- **A string passes through** as an `https` URL or an upload id. A multi-file Field takes a list, which may mix all three kinds.
+- **Before the press,** each file is uploaded with `POST /v1/widgets/{widget}/uploads`, then sent to storage, in parallel, and its id goes in the input. An upload refusal (`held_input_*`) raises before any press. A retried press reuses the ids; it never uploads again.
+- **`await run.save(dir)`** writes every output file under `dir` at its `path`, making folders, and answers the paths it wrote.
+- **Each of `run.output_files`** has `await f.save(path)` and `await f.read()`, which answers a `Uint8Array`. An expired URL is refreshed once, by reading the run again with `GET /v1/runs/{id}`.
+
+## Errors
+
+A refusal, a failed run, a timeout and a lost connection all raise one class, `AbyssError`. There is no class per status: branch on `code`.
+
+| Field | |
+|---|---|
+| `code` | `/v1`'s error code, a failed run's `error.code`, or a library-only code below |
+| `message` | what to do, for a person |
+| `status` | the HTTP status of a refusal, else `null` |
+| `param` | the Field, body key, query key or header at fault, else `null` |
+| `doc_url` | the code on the API access page, else `null` |
+| `request_id` | quote it to support, else `null` |
+| `run` | the run, for a failed run or a timeout, else `null` |
+
+- **Refusals:** `invalid_api_key` (401), `not_found` (404), `invalid_request`, `invalid_input`, `held_input_*`, `input_unreachable` and `idempotency_key_reused` (422), `insufficient_funds` (402), `spend_cap_reached` and `price_above_max` (400), `idempotency_key_in_use` (409), `rate_limited` (429), `server_error` (500).
+- **A failed run:** `widget_fault`, `platform_fault` or `budget_exceeded`, with the run as `run`.
+- **Library-only codes:** `timeout` (see [Timeouts](#timeouts)); `connection_error`, when the connection still drops before any answer after the retries, with the cause as `cause`; and `unexpected_response`, when an answer is not what the route sends.
+
+## Retries
+
+A request is sent again, at most `maxRetries` times (2 by default), only after:
+
+- **a drop before any headers arrived:** a short backoff, then the same request, with the same `Idempotency-Key` for a press;
+- **`429 rate_limited` and `409 idempotency_key_in_use`:** after the `Retry-After` seconds;
+- **a `5xx`:** a short backoff (0.5 s, then 1 s).
+
+When the last try fails too, it raises. Every other refusal raises at once, and re-attaching never counts as a retry.
+
+## Timeouts
+
+There is no timeout by default: `run()` waits as long as the run takes. `timeout` (seconds) and `signal` (an `AbortSignal`) stop the waiting, never the run.
+
+```js
+try {
+  const run = await abyss.run("widget_131", input, { timeout: 60, signal: AbortSignal.timeout(90_000) });
+} catch (error) {
+  if (error instanceof AbyssError && error.code === "timeout") {
+    // The run goes on. error.run is the run as last seen, or null when none was seen yet.
+  }
+}
+```
+
+Either one raises `AbyssError` with `code: "timeout"` and `run`, the run as last seen. During the press's first hold the run has not been seen yet, so `run` is `null`; to keep its `id` whatever happens, press with `runs.create()` and wait with `runs.get(id, { wait: true, timeout })`.
+
+## Names
+
+Returned data keeps `/v1`'s names: `output_files`, `has_more`, `request_id`. The library's own options are camelCase: `maxPrice`, `startingAfter`. A Field's name is never converted: `input` is sent as you write it.

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import { Run } from "./run.js";
+import type { Input, Key, RunList, Upload, Widget } from "./types.js";
+export interface AbyssOptions {
+    /** Defaults to `ABYSS_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `ABYSS_BASE_URL`, else the address the key belongs to. */
+    baseURL?: string;
+    /** How many times a request is sent again after a drop before any headers, a `429`, a `409` or a `5xx`. Defaults to 2. */
+    maxRetries?: number;
+    /** The seconds every call waits at most, unless it sets its own. None by default. */
+    timeout?: number;
+}
+/** What every call takes. Stopping the waiting never stops the run. */
+export interface CallOptions {
+    /** The seconds to wait at most, then raise `AbyssError` with `code: "timeout"`. */
+    timeout?: number;
+    /** Aborting it stops the waiting, as `timeout` does. */
+    signal?: AbortSignal;
+}
+export interface RunOptions extends CallOptions {
+    /** The most this run may cost, in Byssium. */
+    maxPrice?: number;
+    /** Defaults to a fresh UUID for each call. */
+    idempotencyKey?: string;
+}
+export interface GetRunOptions extends CallOptions {
+    /** Holds until the run ends, as the press holds. */
+    wait?: boolean;
+}
+export interface ListRunsOptions extends CallOptions {
+    /** How many runs to answer, 1 to 100; the API's default is 20. */
+    limit?: number;
+    /** The `id` of the last run on the page you have. */
+    startingAfter?: string;
+}
+/** What `uploads.create` asks for: the file Field, the file's name and its size in bytes. */
+export interface UploadRequest {
+    field: string;
+    filename: string;
+    size?: number;
+}
+/** `/v1`'s run routes, one method each. */
+export interface Runs {
+    /** Uploads the input's files and presses with `"wait": false`: answers the run at once, `queued`. */
+    create(widget: string, input: Input, options?: RunOptions): Promise<Run>;
+    /** Reads a run as it is, or with `wait` holds until it ends. A failed run is answered, not raised. */
+    get(id: string, options?: GetRunOptions): Promise<Run>;
+    /** Answers a page of runs, newest first. */
+    list(options?: ListRunsOptions): Promise<RunList<Run>>;
+}
+export interface Widgets {
+    /** Reads a Widget: its price, Free Runs and `input_schema`. */
+    get(widget: string, options?: CallOptions): Promise<Widget>;
+}
+export interface Uploads {
+    /** Asks for an upload's grant. `run()` and `runs.create()` upload files by themselves. */
+    create(widget: string, upload: UploadRequest, options?: CallOptions): Promise<Upload>;
+}
+export declare class Abyss {
+    #private;
+    readonly baseURL: string;
+    readonly maxRetries: number;
+    readonly timeout: number | null;
+    readonly runs: Runs;
+    readonly widgets: Widgets;
+    readonly uploads: Uploads;
+    constructor(options?: AbyssOptions);
+    /**
+     * Uploads the input's files, presses a Widget and waits for the run's ending,
+     * re-attaching through `Location` whenever the hold ends early. Returns the succeeded
+     * run; raises `AbyssError` on a refusal or a failed run.
+     */
+    run(widget: string, input: Input, options?: RunOptions): Promise<Run>;
+    /** Answers the API Key making the call, with `GET /v1/key`. */
+    key(options?: CallOptions): Promise<Key>;
+}

package/dist/client.js

@@ -0,0 +1,359 @@
+import { AbyssError } from "./error.js";
+import { uploadFiles } from "./files.js";
+import { request } from "./http.js";
+import { Run } from "./run.js";
+import { VERSION } from "./version.js";
+const API = "https://api.abysshub.com";
+const DEV_API = "https://api.dev.abysshub.com";
+const DEV_KEY_PREFIX = "abyss_sk_dev_";
+/** The pause between two re-attaches that both ended without the run's ending. */
+const REATTACH_PAUSE_MS = 1_000;
+/** The first pause before a retry after a drop or a 5xx; it doubles with each retry. */
+const RETRY_PAUSE_MS = 500;
+const BROWSER_REFUSAL = "An Abyss API key is a server-side secret. Call the API from your server.";
+const USER_AGENT = `abysshub-js/${VERSION} (${runtime()})`;
+export class Abyss {
+    baseURL;
+    maxRetries;
+    timeout;
+    runs;
+    widgets;
+    uploads;
+    #apiKey;
+    constructor(options = {}) {
+        if (inBrowser())
+            throw new Error(BROWSER_REFUSAL);
+        const apiKey = options.apiKey ?? env("ABYSS_API_KEY");
+        if (!apiKey) {
+            throw new AbyssError({
+                code: "invalid_api_key",
+                message: "No Abyss API key: pass apiKey, or set ABYSS_API_KEY.",
+            });
+        }
+        this.#apiKey = apiKey;
+        const baseURL = options.baseURL ?? env("ABYSS_BASE_URL") ?? (apiKey.startsWith(DEV_KEY_PREFIX) ? DEV_API : API);
+        this.baseURL = baseURL.replace(/\/+$/, "");
+        this.maxRetries = options.maxRetries ?? 2;
+        this.timeout = options.timeout ?? null;
+        this.runs = {
+            create: (widget, input, options = {}) => this.#call(options, async (call) => {
+                const press = await this.#press(call, widget, input, options, false);
+                return this.#run(expect(press, isRun, "The press answered without a run."));
+            }),
+            get: (id, options = {}) => this.#call(options, async (call) => this.#run(await this.#getRun(call, id, options.wait ?? false))),
+            list: (options = {}) => this.#call(options, (call) => this.#listRuns(call, options)),
+        };
+        this.widgets = {
+            get: (widget, options = {}) => this.#call(options, (call) => this.#get(call, this.#widgetURL(widget), isWidget, "The Widget answered without an id.")),
+        };
+        this.uploads = {
+            create: (widget, upload, options = {}) => this.#call(options, (call) => this.#grant(call, this.#widgetURL(widget), upload)),
+        };
+    }
+    /**
+     * Uploads the input's files, presses a Widget and waits for the run's ending,
+     * re-attaching through `Location` whenever the hold ends early. Returns the succeeded
+     * run; raises `AbyssError` on a refusal or a failed run.
+     */
+    run(widget, input, options = {}) {
+        return this.#call(options, async (call) => {
+            const press = await this.#press(call, widget, input, options, true);
+            const reply = hasEnded(press) ? press : await this.#hold(call, this.#waitURL(press), hasEnded);
+            const run = this.#run(reply.run);
+            if (run.status === "failed") {
+                throw new AbyssError({
+                    code: run.error?.code ?? "platform_fault",
+                    message: run.error?.message ?? "The run failed.",
+                    request_id: reply.requestId,
+                    run,
+                });
+            }
+            return run;
+        });
+    }
+    /** Answers the API Key making the call, with `GET /v1/key`. */
+    key(options = {}) {
+        return this.#call(options, (call) => this.#get(call, `${this.baseURL}/v1/key`, isKey, "The key answered without a key."));
+    }
+    /**
+     * Runs one call under its `timeout` and `signal`. When either stops the waiting, the
+     * call raises `AbyssError` with `code: "timeout"` and the run as last seen.
+     */
+    async #call(options, work) {
+        const timeout = options.timeout ?? this.timeout;
+        const stop = new AbortController();
+        let message = "The signal stopped the waiting. The run goes on.";
+        const abort = () => stop.abort();
+        const timer = timeout === null
+            ? undefined
+            : setTimeout(() => {
+                message = `Stopped waiting after ${timeout} s. The run goes on.`;
+                abort();
+            }, timeout * 1_000);
+        if (options.signal?.aborted)
+            abort();
+        options.signal?.addEventListener("abort", abort, { once: true });
+        const call = { signal: stop.signal, seen: null };
+        try {
+            return await work(call);
+        }
+        catch (error) {
+            if (!stop.signal.aborted)
+                throw error;
+            throw new AbyssError({ code: "timeout", message, run: call.seen && this.#run(call.seen) });
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+        }
+    }
+    /**
+     * Uploads the input's files and sends the press, with `"wait": false` unless it holds.
+     * Its retries send the same body and `Idempotency-Key`, so the uploads are never redone.
+     */
+    async #press(call, widget, input, options, hold) {
+        const widgetURL = this.#widgetURL(widget);
+        const body = {
+            input: await uploadFiles(input, (field, filename, data) => this.#upload(call, widgetURL, field, filename, data)),
+        };
+        if (options.maxPrice !== undefined)
+            body.max_price = options.maxPrice;
+        if (!hold)
+            body.wait = false;
+        return this.#send(call, "POST", `${widgetURL}/runs`, {
+            "Content-Type": "application/json",
+            "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID(),
+        }, JSON.stringify(body));
+    }
+    /** Asks for an upload with `POST /v1/widgets/{widget}/uploads`. */
+    async #grant(call, widgetURL, { field, filename, size }) {
+        // JSON.stringify leaves `size` out when it is undefined.
+        const grant = await this.#send(call, "POST", `${widgetURL}/uploads`, { "Content-Type": "application/json" }, JSON.stringify({ field, filename, size }));
+        return expect(grant, isUpload, "The upload answered without an id and a form.");
+    }
+    /** Asks for an upload, sends the file to storage and answers its id. */
+    async #upload(call, widgetURL, field, filename, data) {
+        const grant = await this.#grant(call, widgetURL, { field, filename, size: data.size });
+        const form = new FormData();
+        for (const [name, value] of Object.entries(grant.upload.fields))
+            form.append(name, value);
+        form.append("file", data, filename);
+        const stored = await fetch(grant.upload.url, { method: "POST", body: form, signal: call.signal });
+        await stored.body?.cancel();
+        if (!stored.ok) {
+            throw new AbyssError({
+                code: "unexpected_response",
+                message: `Storage answered ${stored.status} to the upload of ${filename}.`,
+                status: stored.status,
+                param: field,
+            });
+        }
+        return grant.id;
+    }
+    /** Reads a run with `GET /v1/runs/{id}`, holding with `?wait=true`. A cut hold is read again. */
+    async #getRun(call, id, wait) {
+        const url = new URL(`${this.baseURL}/v1/runs/${encodeURIComponent(id)}`);
+        if (wait)
+            url.searchParams.set("wait", "true");
+        const reply = await this.#hold(call, url.href, (reply) => !reply.cut);
+        return expect(reply, isRun, "The read answered without a run.");
+    }
+    async #listRuns(call, options) {
+        const url = new URL(`${this.baseURL}/v1/runs`);
+        if (options.limit !== undefined)
+            url.searchParams.set("limit", String(options.limit));
+        if (options.startingAfter !== undefined)
+            url.searchParams.set("starting_after", options.startingAfter);
+        const page = await this.#get(call, url.href, isRunList, "The run list answered without data.");
+        return { data: page.data.map((data) => this.#run(data)), has_more: page.has_more };
+    }
+    /** Reads `url` once and answers its body, when it is what the route answers. */
+    async #get(call, url, is, message) {
+        return expect(await this.#send(call, "GET", url), is, message);
+    }
+    /** Reads `url` until `done`. Re-attaching has no limit and is not a retry. */
+    async #hold(call, url, done) {
+        let reply = await this.#send(call, "GET", url);
+        while (!done(reply)) {
+            await sleep(REATTACH_PAUSE_MS, call.signal);
+            reply = await this.#send(call, "GET", url);
+        }
+        return reply;
+    }
+    #run(data) {
+        return new Run(data, () => this.#getRun({ signal: null, seen: null }, data.id, false));
+    }
+    #widgetURL(widget) {
+        return `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}`;
+    }
+    #waitURL(reply) {
+        const location = reply.location ?? (reply.run ? `/v1/runs/${reply.run.id}` : null);
+        if (!location) {
+            throw new AbyssError({
+                code: "unexpected_response",
+                message: "The press answered without a Location to read the run at.",
+                request_id: reply.requestId,
+            });
+        }
+        const url = new URL(location, `${this.baseURL}/`);
+        url.searchParams.set("wait", "true");
+        return url.href;
+    }
+    /**
+     * Sends one request to `/v1`. A drop before any headers, a `429`, a `409` and a `5xx`
+     * are sent again, at most `maxRetries` times; every other refusal raises at once.
+     */
+    async #send(call, method, url, headers = {}, body) {
+        const init = {
+            method,
+            headers: { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", "User-Agent": USER_AGENT, ...headers },
+            signal: call.signal,
+            ...(body === undefined ? {} : { body }),
+        };
+        for (let attempt = 0;; attempt++) {
+            let answer;
+            try {
+                answer = await request(url, init);
+            }
+            catch (error) {
+                if (call.signal?.aborted)
+                    throw error;
+                if (attempt >= this.maxRetries) {
+                    throw new AbyssError({
+                        code: "connection_error",
+                        message: "The connection dropped, or timed out, before the API answered.",
+                        cause: error,
+                    });
+                }
+                await sleep(backoff(attempt), call.signal);
+                continue;
+            }
+            const requestId = answer.headers.get("request-id");
+            const parsed = parse(answer.text);
+            if (answer.status === 200 || answer.status === 202) {
+                const run = isRun(parsed) ? parsed : null;
+                if (run)
+                    call.seen = run;
+                return { body: parsed, run, cut: answer.text === null, location: answer.headers.get("location"), requestId };
+            }
+            const pause = retryPause(answer, attempt);
+            if (pause === null || attempt >= this.maxRetries)
+                throw refusal(answer.status, parsed, requestId);
+            await sleep(pause, call.signal);
+        }
+    }
+}
+/** How long to wait before sending a refused request again, or null when it is not retried. */
+function retryPause(answer, attempt) {
+    if (answer.status === 429 || answer.status === 409) {
+        const after = answer.headers.get("retry-after");
+        const seconds = after === null ? Number.NaN : Number(after);
+        return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1_000 : backoff(attempt);
+    }
+    return answer.status >= 500 ? backoff(attempt) : null;
+}
+function backoff(attempt) {
+    return RETRY_PAUSE_MS * 2 ** attempt;
+}
+/** The reply's body when it is what the route answers, else `unexpected_response`. */
+function expect(reply, is, message) {
+    if (is(reply.body))
+        return reply.body;
+    throw new AbyssError({ code: "unexpected_response", message, request_id: reply.requestId });
+}
+function refusal(status, body, requestId) {
+    const error = isObject(body) && isObject(body.error) ? body.error : null;
+    if (!error || typeof error.code !== "string") {
+        return new AbyssError({
+            code: "unexpected_response",
+            message: `The API answered ${status} without an error body.`,
+            status,
+            request_id: requestId,
+        });
+    }
+    return new AbyssError({
+        code: error.code,
+        message: typeof error.message === "string" ? error.message : error.code,
+        status,
+        param: typeof error.param === "string" ? error.param : null,
+        doc_url: typeof error.doc_url === "string" ? error.doc_url : null,
+        request_id: isObject(body) && typeof body.request_id === "string" ? body.request_id : requestId,
+    });
+}
+function parse(text) {
+    if (text === null)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRun(value) {
+    return isObject(value) && typeof value.id === "string" && typeof value.status === "string";
+}
+function isRunList(value) {
+    return isObject(value) && Array.isArray(value.data) && value.data.every(isRun) && typeof value.has_more === "boolean";
+}
+function isWidget(value) {
+    return isObject(value) && typeof value.id === "string";
+}
+function isKey(value) {
+    return isObject(value) && typeof value.key === "string";
+}
+function isUpload(value) {
+    return (isObject(value) &&
+        typeof value.id === "string" &&
+        isObject(value.upload) &&
+        typeof value.upload.url === "string" &&
+        isObject(value.upload.fields));
+}
+/** Whether the reply carries a run that has succeeded or failed. */
+function hasEnded(reply) {
+    return reply.run !== null && (reply.run.status === "succeeded" || reply.run.status === "failed");
+}
+function env(name) {
+    try {
+        const { process } = globalThis;
+        return process?.env?.[name] || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether this runs in a browser, where an API key would be exposed. */
+function inBrowser() {
+    const scope = globalThis;
+    return scope.window !== undefined && scope.document !== undefined;
+}
+/** The runtime and its version, for the User-Agent. Bun and Deno also serve `process`, so they are asked first. */
+function runtime() {
+    const scope = globalThis;
+    if (scope.Bun?.version)
+        return `bun ${scope.Bun.version}`;
+    if (scope.Deno?.version?.deno)
+        return `deno ${scope.Deno.version.deno}`;
+    if (scope.process?.versions?.node)
+        return `node ${scope.process.versions.node}`;
+    return "unknown";
+}
+/** Waits `ms`, or rejects as soon as `signal` aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const stop = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}

package/dist/error.d.ts

@@ -0,0 +1,26 @@
+import type { Run } from "./run.js";
+export interface AbyssErrorFields {
+    code: string;
+    message: string;
+    status?: number | null;
+    param?: string | null;
+    doc_url?: string | null;
+    request_id?: string | null;
+    run?: Run | null;
+    /** What a `connection_error` was caused by. */
+    cause?: unknown;
+}
+/**
+ * The one error the library raises: a refusal from `/v1`, or a run that failed.
+ * Branch on `code`. A failed run carries the run as `run`.
+ */
+export declare class AbyssError extends Error {
+    readonly code: string;
+    /** The HTTP status of a refusal; null for a failed run. */
+    readonly status: number | null;
+    readonly param: string | null;
+    readonly doc_url: string | null;
+    readonly request_id: string | null;
+    readonly run: Run | null;
+    constructor(fields: AbyssErrorFields);
+}

package/dist/error.js

@@ -0,0 +1,23 @@
+/**
+ * The one error the library raises: a refusal from `/v1`, or a run that failed.
+ * Branch on `code`. A failed run carries the run as `run`.
+ */
+export class AbyssError extends Error {
+    code;
+    /** The HTTP status of a refusal; null for a failed run. */
+    status;
+    param;
+    doc_url;
+    request_id;
+    run;
+    constructor(fields) {
+        super(fields.message, fields.cause === undefined ? undefined : { cause: fields.cause });
+        this.name = "AbyssError";
+        this.code = fields.code;
+        this.status = fields.status ?? null;
+        this.param = fields.param ?? null;
+        this.doc_url = fields.doc_url ?? null;
+        this.request_id = fields.request_id ?? null;
+        this.run = fields.run ?? null;
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,23 @@
+import type { Input } from "./types.js";
+/** File data held in memory or streamed: a `Blob` or `File`, a `Buffer` or `Uint8Array`, or a stream. */
+export type FileData = Blob | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
+export interface FileOptions {
+    /** The name to upload under. Defaults to the path's or the `File`'s name, else the Field's name. */
+    filename?: string;
+}
+/** A file for a file Field: a path, read when it is uploaded, or data. Made by `file()`. */
+export declare class InputFile {
+    readonly source: string | FileData;
+    readonly filename: string | undefined;
+    constructor(source: string | FileData, options?: FileOptions);
+}
+/** A file for a file Field. A string is a path, read when the file is uploaded. */
+export declare function file(source: string | FileData, options?: FileOptions): InputFile;
+/** Uploads one file for a Field and answers the upload's id. */
+export type Uploader = (field: string, filename: string, data: Blob) => Promise<string>;
+/**
+ * Uploads every file value in the input, in parallel, and answers the input with each
+ * one replaced by its upload's id. Strings pass through as an `https` URL or an upload
+ * id, and a list may mix all kinds. The caller's input is never changed.
+ */
+export declare function uploadFiles(input: Input, upload: Uploader): Promise<Input>;

package/dist/files.js

@@ -0,0 +1,90 @@
+import { nodeFS } from "./node.js";
+/** A file for a file Field: a path, read when it is uploaded, or data. Made by `file()`. */
+export class InputFile {
+    source;
+    filename;
+    constructor(source, options = {}) {
+        this.source = source;
+        this.filename = options.filename;
+    }
+}
+/** A file for a file Field. A string is a path, read when the file is uploaded. */
+export function file(source, options = {}) {
+    return new InputFile(source, options);
+}
+/**
+ * Uploads every file value in the input, in parallel, and answers the input with each
+ * one replaced by its upload's id. Strings pass through as an `https` URL or an upload
+ * id, and a list may mix all kinds. The caller's input is never changed.
+ */
+export async function uploadFiles(input, upload) {
+    const uploaded = { ...input };
+    const uploads = [];
+    const uploadOne = async (field, value) => {
+        const { filename, data } = await load(value, field);
+        return upload(field, filename, data);
+    };
+    for (const [field, value] of Object.entries(input)) {
+        if (isFile(value)) {
+            uploads.push(uploadOne(field, value).then((id) => void (uploaded[field] = id)));
+        }
+        else if (Array.isArray(value) && value.some(isFile)) {
+            const list = [...value];
+            uploaded[field] = list;
+            list.forEach((item, index) => {
+                if (isFile(item))
+                    uploads.push(uploadOne(field, item).then((id) => void (list[index] = id)));
+            });
+        }
+    }
+    const failed = (await Promise.allSettled(uploads)).find((settled) => settled.status === "rejected");
+    if (failed)
+        throw failed.reason;
+    return uploaded;
+}
+function isFile(value) {
+    return (value instanceof InputFile ||
+        value instanceof Blob ||
+        value instanceof Uint8Array ||
+        value instanceof ReadableStream ||
+        (typeof value === "object" && value !== null && Symbol.asyncIterator in value));
+}
+async function load(value, field) {
+    const given = value instanceof InputFile ? value : new InputFile(value);
+    const { source } = given;
+    if (typeof source === "string") {
+        const fs = await nodeFS();
+        return { filename: given.filename ?? basename(source), data: new Blob([blobPart(await fs.readFile(source))]) };
+    }
+    const data = source instanceof Blob ? source : source instanceof Uint8Array ? new Blob([blobPart(source)]) : await drain(source);
+    return { filename: given.filename ?? nameOf(source) ?? field, data };
+}
+/** The name a `File` or a file stream (Node's `fs.createReadStream`) carries. */
+function nameOf(source) {
+    const named = source;
+    if (source instanceof Blob)
+        return typeof named.name === "string" && named.name ? named.name : undefined;
+    return typeof named.path === "string" ? basename(named.path) : undefined;
+}
+async function drain(stream) {
+    const parts = [];
+    const encoder = new TextEncoder();
+    const add = (chunk) => parts.push(typeof chunk === "string" ? encoder.encode(chunk) : blobPart(chunk));
+    if (stream instanceof ReadableStream) {
+        const reader = stream.getReader();
+        for (let read = await reader.read(); !read.done; read = await reader.read())
+            add(read.value);
+    }
+    else {
+        for await (const chunk of stream)
+            add(chunk);
+    }
+    return new Blob(parts);
+}
+/** The bytes as a `Blob` takes them, on a plain `ArrayBuffer`: copied only when they are on a shared one. */
+function blobPart(bytes) {
+    return bytes.buffer instanceof ArrayBuffer ? bytes : new Uint8Array(bytes);
+}
+function basename(path) {
+    return path.split(/[\\/]/).pop() || path;
+}

package/dist/http.d.ts

@@ -0,0 +1,19 @@
+export interface Limits {
+    /** How long to wait for the status and headers. */
+    connectMs: number;
+    /** How long the body may stay silent before it counts as a cut. */
+    silenceMs: number;
+}
+export declare const LIMITS: Limits;
+export interface Answer {
+    status: number;
+    headers: Headers;
+    /** The whole body, or null when the connection was cut or went silent after the headers. */
+    text: string | null;
+}
+/**
+ * Sends one request and reads its whole body. A failure before the headers rejects;
+ * a cut after them answers `text: null`, so the caller can re-attach. `init.signal`
+ * stops the request at any point, and then it always rejects.
+ */
+export declare function request(url: string, init: RequestInit, limits?: Limits): Promise<Answer>;

package/dist/http.js

@@ -0,0 +1,57 @@
+export const LIMITS = { connectMs: 10_000, silenceMs: 30_000 };
+/**
+ * Sends one request and reads its whole body. A failure before the headers rejects;
+ * a cut after them answers `text: null`, so the caller can re-attach. `init.signal`
+ * stops the request at any point, and then it always rejects.
+ */
+export async function request(url, init, limits = LIMITS) {
+    const stop = init.signal;
+    stop?.throwIfAborted();
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    stop?.addEventListener("abort", abort, { once: true });
+    const connect = setTimeout(abort, limits.connectMs);
+    try {
+        let response;
+        try {
+            response = await fetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(connect);
+        }
+        const text = await readBody(response, controller, limits.silenceMs);
+        stop?.throwIfAborted();
+        return { status: response.status, headers: response.headers, text };
+    }
+    finally {
+        stop?.removeEventListener("abort", abort);
+    }
+}
+async function readBody(response, controller, silenceMs) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let silence;
+    const listen = () => {
+        clearTimeout(silence);
+        silence = setTimeout(() => controller.abort(), silenceMs);
+    };
+    try {
+        listen();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            listen();
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(silence);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Abyss, type AbyssOptions, type CallOptions, type GetRunOptions, type ListRunsOptions, type RunOptions, type Runs, type UploadRequest, type Uploads, type Widgets, } from "./client.js";
+export { AbyssError, type AbyssErrorFields } from "./error.js";
+export { file, type FileData, type FileOptions, type InputFile } from "./files.js";
+export type { Run, RunFile } from "./run.js";
+export type { Input, Key, RunError, RunList, RunStatus, Upload, Widget } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Abyss, } from "./client.js";
+export { AbyssError } from "./error.js";
+export { file } from "./files.js";

package/dist/node.d.ts

@@ -0,0 +1,16 @@
+export interface NodeFS {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    mkdir(path: string, options: {
+        recursive: true;
+    }): Promise<unknown>;
+}
+export interface NodePath {
+    join(...paths: string[]): string;
+    dirname(path: string): string;
+    resolve(...paths: string[]): string;
+    relative(from: string, to: string): string;
+    isAbsolute(path: string): boolean;
+}
+export declare function nodeFS(): Promise<NodeFS>;
+export declare function nodePath(): Promise<NodePath>;

package/dist/node.js

@@ -0,0 +1,11 @@
+// Node's fs and path modules, which Node, Bun and Deno all serve. They are imported
+// by a non-literal specifier so the library needs no @types/node, and loads in
+// places that have neither.
+const FS = "node:fs/promises";
+const PATH = "node:path";
+export function nodeFS() {
+    return import(FS);
+}
+export function nodePath() {
+    return import(PATH);
+}

package/dist/run.d.ts

@@ -0,0 +1,33 @@
+import type { RunData, RunError, RunFileData, RunStatus } from "./types.js";
+/** Reads the run again with `GET /v1/runs/{id}`. */
+export type Reread = () => Promise<RunData>;
+/** A run, with `/v1`'s names. */
+export declare class Run {
+    #private;
+    id: string;
+    widget: string;
+    status: RunStatus;
+    price: number;
+    result: unknown;
+    output_files: RunFile[];
+    error: RunError | null;
+    created_at: string;
+    started_at: string | null;
+    ended_at: string | null;
+    constructor(data: RunData, reread: Reread);
+    /** Saves every output file under `dir`, at its `path`, and answers the paths it wrote. */
+    save(dir: string): Promise<string[]>;
+}
+/** One file a run wrote. Its `url` is signed fresh on every read of the run, and expires. */
+export declare class RunFile {
+    #private;
+    path: string;
+    size: number;
+    content_type: string;
+    url: string;
+    constructor(data: RunFileData, refresh: () => Promise<void>);
+    /** Downloads the file. An expired `url` is refreshed once, by reading the run again. */
+    read(): Promise<Uint8Array>;
+    /** Downloads the file to `path`, making its folders, and answers `path`. */
+    save(path: string): Promise<string>;
+}

package/dist/run.js

@@ -0,0 +1,96 @@
+import { AbyssError } from "./error.js";
+import { nodeFS, nodePath } from "./node.js";
+/** A run, with `/v1`'s names. */
+export class Run {
+    id;
+    widget;
+    status;
+    price;
+    result;
+    output_files;
+    error;
+    created_at;
+    started_at;
+    ended_at;
+    #reread;
+    constructor(data, reread) {
+        this.id = data.id;
+        this.widget = data.widget;
+        this.status = data.status;
+        this.price = data.price;
+        this.result = data.result;
+        this.error = data.error;
+        this.created_at = data.created_at;
+        this.started_at = data.started_at;
+        this.ended_at = data.ended_at;
+        this.#reread = reread;
+        this.output_files = data.output_files.map((output) => new RunFile(output, () => this.#refreshURLs()));
+    }
+    /** Reads the run again and gives every output file its freshly signed `url`. */
+    async #refreshURLs() {
+        const fresh = await this.#reread();
+        for (const output of this.output_files) {
+            const url = fresh.output_files.find((candidate) => candidate.path === output.path)?.url;
+            if (url)
+                output.url = url;
+        }
+    }
+    /** Saves every output file under `dir`, at its `path`, and answers the paths it wrote. */
+    async save(dir) {
+        const path = await nodePath();
+        const saved = [];
+        for (const output of this.output_files) {
+            const target = path.join(dir, output.path);
+            const inside = path.relative(path.resolve(dir), path.resolve(target));
+            if (!inside || inside.startsWith("..") || path.isAbsolute(inside)) {
+                throw new AbyssError({
+                    code: "unexpected_response",
+                    message: `The output file ${output.path} would be saved outside ${dir}.`,
+                });
+            }
+            saved.push(await output.save(target));
+        }
+        return saved;
+    }
+}
+/** One file a run wrote. Its `url` is signed fresh on every read of the run, and expires. */
+export class RunFile {
+    path;
+    size;
+    content_type;
+    url;
+    #refresh;
+    constructor(data, refresh) {
+        this.path = data.path;
+        this.size = data.size;
+        this.content_type = data.content_type;
+        this.url = data.url;
+        this.#refresh = refresh;
+    }
+    /** Downloads the file. An expired `url` is refreshed once, by reading the run again. */
+    async read() {
+        let response = await fetch(this.url);
+        if (response.status === 403) {
+            await response.body?.cancel();
+            await this.#refresh();
+            response = await fetch(this.url);
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new AbyssError({
+                code: "unexpected_response",
+                message: `The download of ${this.path} answered ${response.status}.`,
+                status: response.status,
+            });
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** Downloads the file to `path`, making its folders, and answers `path`. */
+    async save(path) {
+        const [fs, { dirname }] = await Promise.all([nodeFS(), nodePath()]);
+        const bytes = await this.read();
+        await fs.mkdir(dirname(path), { recursive: true });
+        await fs.writeFile(path, bytes);
+        return path;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+/** A run's place: `succeeded` and `failed` are final. */
+export type RunStatus = "queued" | "running" | "succeeded" | "failed";
+/** Why a run failed: `widget_fault`, `platform_fault` or `budget_exceeded`. */
+export interface RunError {
+    code: string;
+    message: string;
+}
+/** One file a run wrote, as `/v1` sends it. */
+export interface RunFileData {
+    path: string;
+    size: number;
+    content_type: string;
+    url: string;
+}
+/** A run, as `/v1` sends it. */
+export interface RunData {
+    id: string;
+    widget: string;
+    status: RunStatus;
+    price: number;
+    result: unknown;
+    output_files: RunFileData[];
+    error: RunError | null;
+    created_at: string;
+    started_at: string | null;
+    ended_at: string | null;
+}
+/** A Widget's input: its Fields by name, never converted. */
+export type Input = Record<string, unknown>;
+/** A page of runs, newest first, as `GET /v1/runs` sends it. */
+export interface RunList<R = RunData> {
+    data: R[];
+    /** Whether a page `starting_after` the last run here would find more. */
+    has_more: boolean;
+}
+/** A Widget, as the caller about to press it sees it. */
+export interface Widget {
+    id: string;
+    name: string | null;
+    description: string | null;
+    url: string;
+    /** The one price a run costs, Call Price included. */
+    price: number;
+    /** The caller's Free Runs on this Widget; null for their own Widget and for a free one. */
+    free_runs: {
+        limit: number;
+        remaining: number;
+    } | null;
+    /** The JSON Schema the input must match. */
+    input_schema: Record<string, unknown>;
+}
+/** An upload's grant: its `id` goes in the input once the file is in storage. */
+export interface Upload {
+    id: string;
+    /** POST every `fields` entry, then the file as `file`, to `url`. */
+    upload: {
+        url: string;
+        fields: Record<string, string>;
+    };
+}
+/** The API Key making the call, as `GET /v1/key` sends it. Never its secret. */
+export interface Key {
+    name: string;
+    /** The key's display form: its prefix and last four characters. */
+    key: string;
+    user: {
+        id: number;
+        name: string;
+    };
+    spend_cap: number | null;
+    spent_this_month: number;
+    created_at: string;
+}

package/dist/types.js

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version, written from package.json by scripts/version.js at build. */
+export declare const VERSION = "0.0.1-dev.10";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This package's version, written from package.json by scripts/version.js at build. */
+export const VERSION = "0.0.1-dev.10";

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "abysshub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-dev.10",
+  "description": "The official JavaScript library for the Abyss API.",
+  "license": "MIT",
+  "homepage": "https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abysshub/abysshub-sdk.git",
+    "directory": "js"
+  },
+  "bugs": "https://github.com/Abysshub/abysshub-sdk/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/version.js && tsc",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "typescript": "^5.9.3"
+  }
+}