abysshub 0.0.1-dev.5 → 0.0.1-dev.7

package/README.md

@@ -20,6 +20,125 @@ try {
 
 `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`.
 
-- **`new Abyss({ apiKey?, baseURL?, maxRetries? })`:** the key defaults to `ABYSS_API_KEY`. A key starting `abyss_sk_dev_` goes to `https://api.dev.abysshub.com`. `ABYSS_BASE_URL` or `baseURL` overrides the address.
-- **`abyss.run(widget, input, { maxPrice?, idempotencyKey? })`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one.
-- **Names:** returned data keeps the API's names (`output_files`, `request_id`). Options are camelCase. Field names are never converted.
+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

@@ -1,26 +1,76 @@
-import type { Input, Run } from "./types.js";
+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;
 }
-export interface RunOptions {
+/** 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);
     /**
-     * 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.
+     * 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

@@ -1,15 +1,28 @@
 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({
@@ -21,41 +34,158 @@ export class Abyss {
         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)),
+        };
     }
     /**
-     * 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.
+     * 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.
      */
-    async run(widget, input, options = {}) {
-        const body = { input };
+    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;
-        const press = await this.#send("POST", `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}/runs`, {
+        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));
-        const reply = hasEnded(press) ? press : await this.#reattach(press);
-        if (reply.run.status === "failed") {
+    }
+    /** 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: reply.run.error?.code ?? "platform_fault",
-                message: reply.run.error?.message ?? "The run failed.",
-                request_id: reply.requestId,
-                run: reply.run,
+                code: "unexpected_response",
+                message: `Storage answered ${stored.status} to the upload of ${filename}.`,
+                status: stored.status,
+                param: field,
             });
         }
-        return reply.run;
-    }
-    /** Reads the run with `GET <Location>?wait=true` until it ends. Re-attaching has no limit and is not a retry. */
-    async #reattach(press) {
-        const url = this.#waitURL(press);
-        let reply = await this.#send("GET", url);
-        while (!hasEnded(reply)) {
-            await sleep(REATTACH_PAUSE_MS);
-            reply = await this.#send("GET", url);
+        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) {
@@ -69,20 +199,68 @@ export class Abyss {
         url.searchParams.set("wait", "true");
         return url.href;
     }
-    async #send(method, url, headers = {}, body) {
-        const answer = await request(url, {
+    /**
+     * 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", ...headers },
+            headers: { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", "User-Agent": USER_AGENT, ...headers },
+            signal: call.signal,
             ...(body === undefined ? {} : { body }),
-        });
-        const requestId = answer.headers.get("request-id");
-        const parsed = parse(answer.text);
-        if (answer.status === 200 || answer.status === 202) {
-            return { run: isRun(parsed) ? parsed : null, location: answer.headers.get("location"), requestId };
+        };
+        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);
         }
-        throw refusal(answer.status, parsed, requestId);
     }
 }
+/** 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") {
@@ -118,6 +296,22 @@ function isObject(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");
@@ -131,6 +325,35 @@ function env(name) {
         return undefined;
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** 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

@@ -1,4 +1,4 @@
-import type { Run } from "./types.js";
+import type { Run } from "./run.js";
 export interface AbyssErrorFields {
     code: string;
     message: string;
@@ -7,6 +7,8 @@ export interface AbyssErrorFields {
     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.

package/dist/error.js

@@ -11,7 +11,7 @@ export class AbyssError extends Error {
     request_id;
     run;
     constructor(fields) {
-        super(fields.message);
+        super(fields.message, fields.cause === undefined ? undefined : { cause: fields.cause });
         this.name = "AbyssError";
         this.code = fields.code;
         this.status = fields.status ?? 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

@@ -13,6 +13,7 @@ export interface Answer {
 }
 /**
  * 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.
+ * 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

@@ -1,20 +1,31 @@
 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.
+ * 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 connect = setTimeout(() => controller.abort(), limits.connectMs);
-    let response;
+    const abort = () => controller.abort();
+    stop?.addEventListener("abort", abort, { once: true });
+    const connect = setTimeout(abort, limits.connectMs);
     try {
-        response = await fetch(url, { ...init, signal: controller.signal });
+        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 {
-        clearTimeout(connect);
+        stop?.removeEventListener("abort", abort);
     }
-    const text = await readBody(response, controller, limits.silenceMs);
-    return { status: response.status, headers: response.headers, text };
 }
 async function readBody(response, controller, silenceMs) {
     if (!response.body)

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-export { Abyss, type AbyssOptions, type RunOptions } from "./client.js";
+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 type { Input, Run, RunError, RunFile, RunStatus } from "./types.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

@@ -1,2 +1,3 @@
-export { Abyss } from "./client.js";
+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

@@ -1,25 +1,25 @@
 /** A run's place: `succeeded` and `failed` are final. */
 export type RunStatus = "queued" | "running" | "succeeded" | "failed";
-/** One file a run wrote. Its `url` is signed fresh on every read, and expires. */
-export interface RunFile {
-    path: string;
-    size: number;
-    content_type: string;
-    url: string;
-}
 /** Why a run failed: `widget_fault`, `platform_fault` or `budget_exceeded`. */
 export interface RunError {
     code: string;
     message: string;
 }
-/** A run, with `/v1`'s names. */
-export interface Run {
+/** 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: RunFile[];
+    output_files: RunFileData[];
     error: RunError | null;
     created_at: string;
     started_at: string | null;
@@ -27,3 +27,47 @@ export interface Run {
 }
 /** 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/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.7";

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.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abysshub",
-  "version": "0.0.1-dev.5",
+  "version": "0.0.1-dev.7",
   "description": "The official JavaScript library for the Abyss API.",
   "license": "MIT",
   "homepage": "https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme",
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/version.js && tsc",
     "prepack": "npm run build",
     "test": "npm run build && node --test test/*.test.js"
   },