abysshub 0.0.1-dev.4 → 0.0.1-dev.6

package/README.md

@@ -3,3 +3,43 @@
 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.
+- **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.
+
+## 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}`.

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import { Run } from "./run.js";
+import type { Input } 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);
+    /**
+     * 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>;
+}

package/dist/client.js

@@ -0,0 +1,205 @@
+import { AbyssError } from "./error.js";
+import { uploadFiles } from "./files.js";
+import { request } from "./http.js";
+import { Run } from "./run.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. */
+const RETRY_PAUSE_MS = 500;
+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;
+    }
+    /**
+     * 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)}`;
+        const body = {
+            input: await uploadFiles(input, (field, filename, data) => this.#upload(widgetURL, field, filename, data)),
+        };
+        if (options.maxPrice !== undefined)
+            body.max_price = options.maxPrice;
+        const press = await this.#press(`${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`, 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,
+            });
+        }
+        const form = new FormData();
+        for (const [name, value] of Object.entries(grant.body.upload.fields))
+            form.append(name, value);
+        form.append("file", data, filename);
+        const stored = await fetch(grant.body.upload.url, { method: "POST", body: form });
+        await stored.body?.cancel();
+        if (!stored.ok) {
+            throw new AbyssError({
+                code: "unexpected_response",
+                message: `Storage answered ${stored.status} to the upload of ${filename}.`,
+                status: stored.status,
+                param: field,
+            });
+        }
+        return grant.body.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);
+        }
+        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 { body: parsed, 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";
+}
+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");
+}
+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 "./run.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/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

@@ -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,5 @@
+export { Abyss, type AbyssOptions, type RunOptions } 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";

package/dist/index.js

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,29 @@
+/** A run's place: `succeeded` and `failed` are final. */
+export type RunStatus = "queued" | "running" | "succeeded" | "failed";
+/** Why a run failed: `widget_fault`, `platform_fault` or `budget_exceeded`. */
+export interface RunError {
+    code: string;
+    message: string;
+}
+/** 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: RunFileData[];
+    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.6",
   "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 ?? {}), []);
-});