abysshub 0.0.1-dev.4 → 0.0.1-dev.5

package/README.md

@@ -3,3 +3,23 @@
 The official JavaScript library for the [Abyss](https://abysshub.com) API.
 
 Pre-release: the Abyss API opens soon.
+
+```js
+import { Abyss, AbyssError } from "abysshub";
+
+const abyss = new Abyss(); // reads ABYSS_API_KEY
+
+try {
+  const run = await abyss.run("widget_131", { amount: 250000 });
+  console.log(run.result);
+} catch (error) {
+  if (error instanceof AbyssError) console.error(error.code, error.param, error.request_id, error.run);
+  else throw error;
+}
+```
+
+`run()` presses the Widget and waits for the run to end, however long it takes, then returns the succeeded run. A refusal or a failed run raises `AbyssError`.
+
+- **`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.

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import type { Input, Run } 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;
+    maxRetries?: number;
+}
+export interface RunOptions {
+    /** The most this run may cost, in Byssium. */
+    maxPrice?: number;
+    /** Defaults to a fresh UUID for each call. */
+    idempotencyKey?: string;
+}
+export declare class Abyss {
+    #private;
+    readonly baseURL: string;
+    readonly maxRetries: number;
+    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.
+     */
+    run(widget: string, input: Input, options?: RunOptions): Promise<Run>;
+}

package/dist/client.js

@@ -0,0 +1,136 @@
+import { AbyssError } from "./error.js";
+import { request } from "./http.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;
+export class Abyss {
+    baseURL;
+    maxRetries;
+    #apiKey;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? env("ABYSS_API_KEY");
+        if (!apiKey) {
+            throw new AbyssError({
+                code: "invalid_api_key",
+                message: "No Abyss API key: pass apiKey, or set ABYSS_API_KEY.",
+            });
+        }
+        this.#apiKey = apiKey;
+        const baseURL = options.baseURL ?? env("ABYSS_BASE_URL") ?? (apiKey.startsWith(DEV_KEY_PREFIX) ? DEV_API : API);
+        this.baseURL = baseURL.replace(/\/+$/, "");
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    /**
+     * 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 };
+        if (options.maxPrice !== undefined)
+            body.max_price = options.maxPrice;
+        const press = await this.#send("POST", `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}/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") {
+            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,
+            });
+        }
+        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 reply;
+    }
+    #waitURL(reply) {
+        const location = reply.location ?? (reply.run ? `/v1/runs/${reply.run.id}` : null);
+        if (!location) {
+            throw new AbyssError({
+                code: "unexpected_response",
+                message: "The press answered without a Location to read the run at.",
+                request_id: reply.requestId,
+            });
+        }
+        const url = new URL(location, `${this.baseURL}/`);
+        url.searchParams.set("wait", "true");
+        return url.href;
+    }
+    async #send(method, url, headers = {}, body) {
+        const answer = await request(url, {
+            method,
+            headers: { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json", ...headers },
+            ...(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 };
+        }
+        throw refusal(answer.status, parsed, requestId);
+    }
+}
+function refusal(status, body, requestId) {
+    const error = isObject(body) && isObject(body.error) ? body.error : null;
+    if (!error || typeof error.code !== "string") {
+        return new AbyssError({
+            code: "unexpected_response",
+            message: `The API answered ${status} without an error body.`,
+            status,
+            request_id: requestId,
+        });
+    }
+    return new AbyssError({
+        code: error.code,
+        message: typeof error.message === "string" ? error.message : error.code,
+        status,
+        param: typeof error.param === "string" ? error.param : null,
+        doc_url: typeof error.doc_url === "string" ? error.doc_url : null,
+        request_id: isObject(body) && typeof body.request_id === "string" ? body.request_id : requestId,
+    });
+}
+function parse(text) {
+    if (text === null)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRun(value) {
+    return isObject(value) && typeof value.id === "string" && typeof value.status === "string";
+}
+/** Whether the reply carries a run that has succeeded or failed. */
+function hasEnded(reply) {
+    return reply.run !== null && (reply.run.status === "succeeded" || reply.run.status === "failed");
+}
+function env(name) {
+    try {
+        const { process } = globalThis;
+        return process?.env?.[name] || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/error.d.ts

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

package/dist/error.js

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

package/dist/http.d.ts

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

package/dist/http.js

@@ -0,0 +1,46 @@
+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.
+ */
+export async function request(url, init, limits = LIMITS) {
+    const controller = new AbortController();
+    const connect = setTimeout(() => controller.abort(), limits.connectMs);
+    let response;
+    try {
+        response = await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(connect);
+    }
+    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)
+        return "";
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let silence;
+    const listen = () => {
+        clearTimeout(silence);
+        silence = setTimeout(() => controller.abort(), silenceMs);
+    };
+    try {
+        listen();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            listen();
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(silence);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Abyss, type AbyssOptions, type RunOptions } from "./client.js";
+export { AbyssError, type AbyssErrorFields } from "./error.js";
+export type { Input, Run, RunError, RunFile, RunStatus } from "./types.js";

package/dist/index.js

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

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** 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 {
+    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;
+}
+/** A Widget's input: its Fields by name, never converted. */
+export type Input = Record<string, unknown>;

package/dist/types.js

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

package/package.json

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

package/test/package.test.js

@@ -1,9 +0,0 @@
-import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
-import { test } from "node:test";
-
-test("abysshub has no runtime dependencies", async () => {
-  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
-  assert.equal(pkg.name, "abysshub");
-  assert.deepEqual(Object.keys(pkg.dependencies ?? {}), []);
-});