abysshub 0.0.1-dev.9 → 0.1.0

package/README.md

@@ -1,11 +1,11 @@
 # abysshub
 
-The official JavaScript library for the [Abyss](https://abysshub.com) API.
-
 Pre-release: the Abyss API opens soon.
 
+The official JavaScript library for the [Abyss](https://abysshub.com) API.
+
 ```js
-import { Abyss, AbyssError } from "abysshub";
+import Abyss, { AbyssError } from "abysshub";
 
 const abyss = new Abyss(); // reads ABYSS_API_KEY
 
@@ -18,6 +18,8 @@ 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.
+
 `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.
@@ -46,7 +48,7 @@ const run = await abyss.run(widget, input, { maxPrice, idempotencyKey, timeout,
 - **`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.
+The press holds until the run ends. When the hold ends early (a deploy cuts it, the network goes down, 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`.
 
@@ -80,7 +82,7 @@ while (page.has_more) page = await abyss.runs.list({ limit: 100, startingAfter:
 ## Files
 
 ```js
-import { Abyss, file } from "abysshub";
+import Abyss, { file } from "abysshub";
 
 const run = await abyss.run("widget_1660", {
   report: file("report.pdf"),
@@ -121,7 +123,9 @@ A request is sent again, at most `maxRetries` times (2 by default), only after:
 - **`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.
+When the last try fails too, it raises. Every other refusal raises at once.
+
+**Re-attaching never counts as a retry.** A re-attach that drops, or meets a `429`, `409` or `5xx`, is tried again with no limit until the network is back, pausing 0.5 s and doubling to at most 10 s (or the `Retry-After` seconds). Only `timeout` and `signal` stop it.
 
 ## Timeouts
 

package/dist/client.js

@@ -10,6 +10,8 @@ const DEV_KEY_PREFIX = "abyss_sk_dev_";
 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;
+/** The longest pause between two tries, which only re-attaching, with no limit, reaches. */
+const RETRY_PAUSE_CEILING_MS = 10_000;
 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 {
@@ -171,12 +173,16 @@ export class Abyss {
     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. */
+    /**
+     * Reads `url` until `done`. Re-attaching has no limit and is not a retry: a re-attach
+     * that drops, or meets a `429`, `409` or `5xx`, is tried again until the network is
+     * back, and only the call's `timeout` or `signal` stops it.
+     */
     async #hold(call, url, done) {
-        let reply = await this.#send(call, "GET", url);
+        let reply = await this.#send(call, "GET", url, {}, undefined, Infinity);
         while (!done(reply)) {
             await sleep(REATTACH_PAUSE_MS, call.signal);
-            reply = await this.#send(call, "GET", url);
+            reply = await this.#send(call, "GET", url, {}, undefined, Infinity);
         }
         return reply;
     }
@@ -201,9 +207,9 @@ export class Abyss {
     }
     /**
      * 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.
+     * are sent again, at most `retries` times; every other refusal raises at once.
      */
-    async #send(call, method, url, headers = {}, body) {
+    async #send(call, method, url, headers = {}, body, retries = this.maxRetries) {
         const init = {
             method,
             headers: { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", "User-Agent": USER_AGENT, ...headers },
@@ -218,7 +224,7 @@ export class Abyss {
             catch (error) {
                 if (call.signal?.aborted)
                     throw error;
-                if (attempt >= this.maxRetries) {
+                if (attempt >= retries) {
                     throw new AbyssError({
                         code: "connection_error",
                         message: "The connection dropped, or timed out, before the API answered.",
@@ -237,7 +243,7 @@ export class Abyss {
                 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)
+            if (pause === null || attempt >= retries)
                 throw refusal(answer.status, parsed, requestId);
             await sleep(pause, call.signal);
         }
@@ -253,7 +259,7 @@ function retryPause(answer, attempt) {
     return answer.status >= 500 ? backoff(attempt) : null;
 }
 function backoff(attempt) {
-    return RETRY_PAUSE_MS * 2 ** attempt;
+    return Math.min(RETRY_PAUSE_MS * 2 ** attempt, RETRY_PAUSE_CEILING_MS);
 }
 /** The reply's body when it is what the route answers, else `unexpected_response`. */
 function expect(reply, is, message) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Abyss, type AbyssOptions, type CallOptions, type GetRunOptions, type ListRunsOptions, type RunOptions, type Runs, type UploadRequest, type Uploads, type Widgets, } from "./client.js";
+export { Abyss, Abyss as default, 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";

package/dist/index.js

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

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.0.1-dev.9";
+export declare const VERSION = "0.1.0";

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.0.1-dev.9";
+export const VERSION = "0.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abysshub",
-  "version": "0.0.1-dev.9",
+  "version": "0.1.0",
   "description": "The official JavaScript library for the Abyss API.",
   "license": "MIT",
   "homepage": "https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme",