abysshub 0.1.1-dev.2 → 0.1.1-dev.4

package/README.md

@@ -20,6 +20,14 @@ try {
 
 `Abyss` is the package's default export, the form each Widget's page shows. The named form, `import { Abyss } from "abysshub"`, works too and is the same class.
 
+From CommonJS, `require()` loads the same module on Node 20.19+ and 22.12+:
+
+```js
+const { Abyss, file } = require("abysshub");
+```
+
+A bare `require("abysshub")` returns the module, not the class, so destructure it. On an older Node, `require()` fails with `ERR_REQUIRE_ESM`: use `const { Abyss, file } = await import("abysshub")` there, or upgrade Node.
+
 `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.
@@ -111,6 +119,7 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `request_id` | quote it to support, else `null` |
 | `shortfall` | with `insufficient_funds`: how much Byssium the wallet is short, else `null` |
 | `price` | with `price_above_max`: what the run costs now, else `null` |
+| `run_id` | the id of the run the call started or read, once the press's `Location` or a run body named it, 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).
@@ -137,13 +146,14 @@ There is no timeout by default: `run()` waits as long as the run takes. `timeout
 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.
+  if (error instanceof AbyssError && error.code === "timeout" && error.run_id) {
+    // The run goes on: wait for it again, without pressing (and paying) twice.
+    const run = await abyss.runs.get(error.run_id, { wait: true });
   }
 }
 ```
 
-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 })`.
+Either one raises `AbyssError` with `code: "timeout"`, `run`, the run as last seen or `null`, and `run_id`, the run's id. The press answers its `Location` at once, so `run_id` is set as soon as the press has answered, even while no run has been seen yet; it is `null` only when the waiting stopped before that. Nothing is sent after the waiting stops.
 
 ## Names
 

package/dist/client.js

@@ -1,11 +1,13 @@
 import { AbyssError } from "./error.js";
 import { uploadFiles } from "./files.js";
-import { request } from "./http.js";
+import { LIMITS, 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_";
+/** A `Location` naming a run, `…/v1/runs/{id}`, with the id as its group. */
+const RUN_LOCATION = /\/v1\/runs\/([^/?#]+)\/?(?:[?#]|$)/;
 /** 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. */
@@ -67,6 +69,7 @@ export class Abyss {
                     code: run.error?.code ?? "platform_fault",
                     message: run.error?.message ?? "The run failed.",
                     request_id: reply.requestId,
+                    run_id: run.id,
                     run,
                 });
             }
@@ -79,7 +82,7 @@ export class Abyss {
     }
     /**
      * 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.
+     * call raises `AbyssError` with `code: "timeout"`, the run as last seen and its id.
      */
     async #call(options, work) {
         const timeout = options.timeout ?? this.timeout;
@@ -95,14 +98,20 @@ export class Abyss {
         if (options.signal?.aborted)
             abort();
         options.signal?.addEventListener("abort", abort, { once: true });
-        const call = { signal: stop.signal, seen: null };
+        const call = newCall(stop.signal);
         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) });
+            throw new AbyssError({
+                code: "timeout",
+                message,
+                request_id: call.requestId,
+                run_id: call.runId,
+                run: call.seen && this.#run(call.seen),
+            });
         }
         finally {
             clearTimeout(timer);
@@ -187,7 +196,7 @@ export class Abyss {
         return reply;
     }
     #run(data) {
-        return new Run(data, () => this.#getRun({ signal: null, seen: null }, data.id, false));
+        return new Run(data, () => this.#getRun(newCall(null), data.id, false));
     }
     #widgetURL(widget) {
         return `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}`;
@@ -199,6 +208,7 @@ export class Abyss {
                 code: "unexpected_response",
                 message: "The press answered without a Location to read the run at.",
                 request_id: reply.requestId,
+                run_id: reply.runId,
             });
         }
         const url = new URL(location, `${this.baseURL}/`);
@@ -219,7 +229,7 @@ export class Abyss {
         for (let attempt = 0;; attempt++) {
             let answer;
             try {
-                answer = await request(url, init);
+                answer = await request(url, init, LIMITS, (headers) => heard(call, headers));
             }
             catch (error) {
                 if (call.signal?.aborted)
@@ -228,6 +238,7 @@ export class Abyss {
                     throw new AbyssError({
                         code: "connection_error",
                         message: "The connection dropped, or timed out, before the API answered.",
+                        run_id: call.runId,
                         cause: error,
                     });
                 }
@@ -238,17 +249,31 @@ export class Abyss {
             const parsed = parse(answer.text);
             if (answer.status === 200 || answer.status === 202) {
                 const run = isRun(parsed) ? parsed : null;
-                if (run)
+                if (run) {
                     call.seen = run;
-                return { body: parsed, run, cut: answer.text === null, location: answer.headers.get("location"), requestId };
+                    call.runId = run.id;
+                }
+                const location = answer.headers.get("location");
+                return { body: parsed, run, cut: answer.text === null, location, requestId, runId: call.runId };
             }
             const pause = retryPause(answer, attempt);
             if (pause === null || attempt >= retries)
-                throw refusal(answer.status, parsed, requestId);
+                throw refusal(answer.status, parsed, requestId, call.runId);
             await sleep(pause, call.signal);
         }
     }
 }
+/** A call's waiting before it has learned anything. */
+function newCall(signal) {
+    return { signal, seen: null, runId: null, requestId: null };
+}
+/** Notes a response's headers as they arrive: its `Request-Id`, and the run its `Location` names. */
+function heard(call, headers) {
+    call.requestId = headers.get("request-id") ?? call.requestId;
+    const runId = headers.get("location")?.match(RUN_LOCATION)?.[1];
+    if (runId)
+        call.runId = runId;
+}
 /** 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) {
@@ -265,9 +290,9 @@ function backoff(attempt) {
 function expect(reply, is, message) {
     if (is(reply.body))
         return reply.body;
-    throw new AbyssError({ code: "unexpected_response", message, request_id: reply.requestId });
+    throw new AbyssError({ code: "unexpected_response", message, request_id: reply.requestId, run_id: reply.runId });
 }
-function refusal(status, body, requestId) {
+function refusal(status, body, requestId, runId) {
     const error = isObject(body) && isObject(body.error) ? body.error : null;
     if (!error || typeof error.code !== "string") {
         return new AbyssError({
@@ -275,6 +300,7 @@ function refusal(status, body, requestId) {
             message: `The API answered ${status} without an error body.`,
             status,
             request_id: requestId,
+            run_id: runId,
         });
     }
     return new AbyssError({
@@ -286,6 +312,7 @@ function refusal(status, body, requestId) {
         shortfall: typeof error.shortfall === "number" ? error.shortfall : null,
         price: typeof error.price === "number" ? error.price : null,
         request_id: isObject(body) && typeof body.request_id === "string" ? body.request_id : requestId,
+        run_id: runId,
     });
 }
 function parse(text) {

package/dist/error.d.ts

@@ -6,6 +6,8 @@ export interface AbyssErrorFields {
     param?: string | null;
     doc_url?: string | null;
     request_id?: string | null;
+    /** The id of the run the call started or read, once the call has learned it. */
+    run_id?: string | null;
     /** With `insufficient_funds`: how much Byssium the wallet is short. */
     shortfall?: number | null;
     /** With `price_above_max`: what the run costs now. */
@@ -25,6 +27,12 @@ export declare class AbyssError extends Error {
     readonly param: string | null;
     readonly doc_url: string | null;
     readonly request_id: string | null;
+    /**
+     * The id of the run the call started or read, once the call has learned it from a
+     * `Location` header or a run body; else null. A `timeout` carries it even when no run
+     * body has arrived, so `runs.get(run_id, { wait: true })` finds the run again.
+     */
+    readonly run_id: string | null;
     /** With `insufficient_funds`: how much Byssium the wallet is short; else null. */
     readonly shortfall: number | null;
     /** With `price_above_max`: what the run costs now; else null. */

package/dist/error.js

@@ -9,6 +9,12 @@ export class AbyssError extends Error {
     param;
     doc_url;
     request_id;
+    /**
+     * The id of the run the call started or read, once the call has learned it from a
+     * `Location` header or a run body; else null. A `timeout` carries it even when no run
+     * body has arrived, so `runs.get(run_id, { wait: true })` finds the run again.
+     */
+    run_id;
     /** With `insufficient_funds`: how much Byssium the wallet is short; else null. */
     shortfall;
     /** With `price_above_max`: what the run costs now; else null. */
@@ -22,6 +28,7 @@ export class AbyssError extends Error {
         this.param = fields.param ?? null;
         this.doc_url = fields.doc_url ?? null;
         this.request_id = fields.request_id ?? null;
+        this.run_id = fields.run_id ?? null;
         this.shortfall = fields.shortfall ?? null;
         this.price = fields.price ?? null;
         this.run = fields.run ?? null;

package/dist/http.d.ts

@@ -14,6 +14,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. `init.signal`
- * stops the request at any point, and then it always rejects.
+ * stops the request at any point, and then it always rejects. `heard` is handed the
+ * headers as soon as they arrive, so a stop during the body still leaves them known.
  */
-export declare function request(url: string, init: RequestInit, limits?: Limits): Promise<Answer>;
+export declare function request(url: string, init: RequestInit, limits?: Limits, heard?: (headers: Headers) => void): Promise<Answer>;

package/dist/http.js

@@ -2,9 +2,10 @@ 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.
+ * stops the request at any point, and then it always rejects. `heard` is handed the
+ * headers as soon as they arrive, so a stop during the body still leaves them known.
  */
-export async function request(url, init, limits = LIMITS) {
+export async function request(url, init, limits = LIMITS, heard) {
     const stop = init.signal;
     stop?.throwIfAborted();
     const controller = new AbortController();
@@ -19,6 +20,7 @@ export async function request(url, init, limits = LIMITS) {
         finally {
             clearTimeout(connect);
         }
+        heard?.(response.headers);
         const text = await readBody(response, controller, limits.silenceMs);
         stop?.throwIfAborted();
         return { status: response.status, headers: response.headers, text };

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abysshub",
-  "version": "0.1.1-dev.2",
+  "version": "0.1.1-dev.4",
   "description": "The official JavaScript library for the Abyss API.",
   "license": "MIT",
   "homepage": "https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme",
@@ -16,7 +16,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [