abysshub 0.0.1-dev.5 → 0.0.1-dev.6

package/README.md

@@ -22,4 +22,24 @@ try {
 
 - **`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

@@ -1,4 +1,5 @@
-import type { Input, Run } from "./types.js";
+import { Run } from "./run.js";
+import type { Input } from "./types.js";
 export interface AbyssOptions {
     /** Defaults to `ABYSS_API_KEY`. */
     apiKey?: string;
@@ -18,9 +19,9 @@ export declare class Abyss {
     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.
+     * 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

@@ -1,10 +1,14 @@
 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;
@@ -23,25 +27,83 @@ export class Abyss {
         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.
+     * 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 body = { input };
+        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.#send("POST", `${this.baseURL}/v1/widgets/${encodeURIComponent(widget)}/runs`, {
+        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);
-        if (reply.run.status === "failed") {
+        const run = new Run(reply.run, () => this.#read(reply.run.id));
+        if (run.status === "failed") {
             throw new AbyssError({
-                code: reply.run.error?.code ?? "platform_fault",
-                message: reply.run.error?.message ?? "The run failed.",
+                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,
-                run: reply.run,
             });
         }
         return reply.run;
@@ -78,7 +140,7 @@ export class Abyss {
         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 };
+            return { body: parsed, run: isRun(parsed) ? parsed : null, location: answer.headers.get("location"), requestId };
         }
         throw refusal(answer.status, parsed, requestId);
     }
@@ -118,6 +180,13 @@ function isObject(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");

package/dist/error.d.ts

@@ -1,4 +1,4 @@
-import type { Run } from "./types.js";
+import type { Run } from "./run.js";
 export interface AbyssErrorFields {
     code: string;
     message: string;

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/index.d.ts

@@ -1,3 +1,5 @@
 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";
+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

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

@@ -1,25 +1,25 @@
 /** 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 {
+/** 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: RunFile[];
+    output_files: RunFileData[];
     error: RunError | null;
     created_at: string;
     started_at: string | null;

package/package.json

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