abysshub 0.0.1-dev.6 → 0.0.1-dev.8

package/README.md

@@ -20,11 +20,62 @@ 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.
-- **A run** has `/v1`'s fields: `id`, `widget`, `status`, `price`, `result`, `output_files`, `error`, `created_at`, `started_at` and `ended_at`.
-- **A drop before any headers** presses again, at most `maxRetries` times, with the same body and `Idempotency-Key`.
-- **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
 
@@ -43,3 +94,51 @@ const paths = await run.save("output"); // ["output/charts/a.png", "output/outpu
 - **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,22 +1,69 @@
 import { Run } from "./run.js";
-import type { Input } from "./types.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);
     /**
      * Uploads the input's files, presses a Widget and waits for the run's ending,
@@ -24,4 +71,6 @@ export declare class Abyss {
      * 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

@@ -2,18 +2,27 @@ 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 pause before pressing again after a drop before any headers. */
+/** 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({
@@ -25,66 +34,111 @@ 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)),
+        };
     }
     /**
      * 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 widgetURL = `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}`;
+    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(widgetURL, field, filename, data)),
+            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.#press(`${widgetURL}/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);
-        const run = new Run(reply.run, () => this.#read(reply.run.id));
-        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;
     }
-    /**
-     * Sends the press. A drop before any headers presses again, at most `maxRetries`
-     * times, with the same body and `Idempotency-Key`, so the uploads are never redone.
-     */
-    async #press(url, headers, body) {
-        for (let attempt = 0;; attempt++) {
-            try {
-                return await this.#send("POST", url, headers, body);
-            }
-            catch (error) {
-                if (error instanceof AbyssError || attempt >= this.maxRetries)
-                    throw error;
-                await sleep(RETRY_PAUSE_MS);
-            }
-        }
+    /** 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 with `POST /v1/widgets/{widget}/uploads`, sends the file to storage and answers its id. */
-    async #upload(widgetURL, field, filename, data) {
-        const grant = await this.#send("POST", `${widgetURL}/uploads`, { "Content-Type": "application/json" }, JSON.stringify({ field, filename, size: data.size }));
-        if (!isUpload(grant.body)) {
-            throw new AbyssError({
-                code: "unexpected_response",
-                message: "The upload answered without an id and a form.",
-                request_id: grant.requestId,
-            });
-        }
+    /** 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.body.upload.fields))
+        for (const [name, value] of Object.entries(grant.upload.fields))
             form.append(name, value);
         form.append("file", data, filename);
-        const stored = await fetch(grant.body.upload.url, { method: "POST", body: form });
+        const stored = await fetch(grant.upload.url, { method: "POST", body: form, signal: call.signal });
         await stored.body?.cancel();
         if (!stored.ok) {
             throw new AbyssError({
@@ -94,30 +148,44 @@ export class Abyss {
                 param: field,
             });
         }
-        return grant.body.id;
+        return grant.id;
     }
-    /** Reads a run at once with `GET /v1/runs/{id}`. */
-    async #read(id) {
-        const reply = await this.#send("GET", `${this.baseURL}/v1/runs/${encodeURIComponent(id)}`);
-        if (!reply.run) {
-            throw new AbyssError({
-                code: "unexpected_response",
-                message: "The read answered without a run.",
-                request_id: reply.requestId,
-            });
-        }
-        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);
+    /** 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) {
@@ -131,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 { body: parsed, 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") {
@@ -180,6 +296,15 @@ 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" &&
@@ -200,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

@@ -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/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,5 +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 { file, type FileData, type FileOptions, type InputFile } from "./files.js";
 export type { Run, RunFile } from "./run.js";
-export type { Input, RunError, RunStatus } from "./types.js";
+export type { Input, Key, RunError, RunList, RunStatus, Upload, Widget } from "./types.js";

package/dist/index.js

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

package/dist/types.d.ts

@@ -27,3 +27,47 @@ export interface RunData {
 }
 /** 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.8";

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abysshub",
-  "version": "0.0.1-dev.6",
+  "version": "0.0.1-dev.8",
   "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"
   },