@itsoltech/basal-client 0.3.0 → 0.5.0

package/dist/esm/index.js

@@ -1,40 +1,22 @@
 import { buildRequest } from "./questions.js";
+import { BasalError, BasalHTTPError, BasalProtocolError, BasalResponseTooLargeError, BasalTransportError } from "./errors.js";
+import { createBody, idempotencyHeader, listPath, resourcePath, uploadForm, } from "./batches.js";
+import { Batches, Files } from "./resources.js";
 export * from "./questions.js";
 export * from "./media.js";
 export * from "./tasks.js";
-export class BasalError extends Error {
-}
-/** Non-2xx response. Server body and Retry-After are available without logging them. */
-export class BasalHTTPError extends BasalError {
-    statusCode;
-    body;
-    retryAfter;
-    constructor(statusCode, body, retryAfter) {
-        super(`Basal HTTP ${statusCode}`);
-        this.statusCode = statusCode;
-        this.body = body;
-        this.retryAfter = retryAfter;
-        this.name = "BasalHTTPError";
-        // Node's default inspection and JSON.stringify must not print reflected state or credentials.
-        Object.defineProperty(this, "body", { enumerable: false });
-    }
-}
-export class BasalTransportError extends BasalError {
-}
-export class BasalProtocolError extends BasalError {
-}
-export class BasalResponseTooLargeError extends BasalError {
-}
+export * from "./errors.js";
+export { batchInput, MAX_BATCH_INPUT_BYTES, MAX_BATCH_REQUESTS, parseBatchResults, TERMINAL_BATCH_STATUSES, } from "./batches.js";
+export { Batches, Files } from "./resources.js";
 async function readBody(response, limit, signal) {
     // Count bytes from the actual stream, including decompressed responses; never trust Content-Length alone.
     const reader = response.body?.getReader();
     if (!reader)
-        return "";
+        return new Uint8Array();
     const cancel = () => { void reader.cancel().catch(() => { }); };
     signal.addEventListener("abort", cancel, { once: true });
     if (signal.aborted)
         cancel();
-    const decoder = new TextDecoder("utf-8", { fatal: true });
     const parts = [];
     let bytes = 0;
     let complete = false;
@@ -49,18 +31,36 @@ async function readBody(response, limit, signal) {
             if (bytes > limit) {
                 throw new BasalResponseTooLargeError(`Basal response exceeds ${limit} bytes`);
             }
-            parts.push(decoder.decode(value, { stream: true }));
+            parts.push(value);
         }
-        parts.push(decoder.decode());
-        return parts.join("");
     }
     finally {
         signal.removeEventListener("abort", cancel);
-        // A decoder/read failure must also stop the underlying HTTP body, before releasing ownership.
+        // A read failure must also stop the underlying HTTP body, before releasing ownership.
         if (!complete)
             cancel();
         reader.releaseLock();
     }
+    if (parts.length === 1)
+        return parts[0];
+    const out = new Uint8Array(bytes);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+function positiveTimeout(value, name) {
+    if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647) {
+        throw new TypeError(`${name} must be positive and at most 2147483647`);
+    }
+    return value;
+}
+function byteLimit(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new TypeError(`${name} must be a positive safe integer`);
+    return value;
 }
 /** Reusable fetch client. Server root URL, optional proxy prefix, without /v1.
  * No automatic retries. AbortSignal cancels a request; timeout includes body reading.
@@ -71,6 +71,10 @@ export class BasalClient {
     timeoutMs;
     maxResponseBytes;
     fetch;
+    /** Files API under resource names: `create`, `retrieve`, `list`, `delete`, `content`. */
+    files;
+    /** Batch API under resource names, with `create({requests})`, `wait` and `results`. */
+    batches;
     constructor(options = {}) {
         const url = new URL(options.baseUrl ?? "http://127.0.0.1:8000");
         if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.href.includes("?") || url.href.includes("#")) {
@@ -95,16 +99,27 @@ export class BasalClient {
                 throw new TypeError("apiKey must be a nonempty, single-line token");
             this.headers.Authorization = `Bearer ${options.apiKey}`;
         }
+        this.files = new Files(this);
+        this.batches = new Batches(this);
+    }
+    request(method, path, body, signal) {
+        return this.call({ method, path, json: body, signal });
     }
-    async request(method, path, body, signal) {
-        // Serialization errors are local input errors, not failures of the HTTP transport.
-        const encoded = body === undefined ? undefined : JSON.stringify(body);
+    async call(call) {
+        // Serialization and option errors are local input errors, not failures of the HTTP transport.
+        const encoded = call.json === undefined ? undefined : JSON.stringify(call.json);
+        const timeoutMs = call.timeoutMs === undefined ? this.timeoutMs : positiveTimeout(call.timeoutMs, "timeoutMs");
+        const limit = call.maxBytes === undefined ? this.maxResponseBytes : byteLimit(call.maxBytes, "maxBytes");
+        const headers = { ...this.headers, ...call.headers };
+        if (encoded !== undefined)
+            headers["Content-Type"] = "application/json";
+        const { signal } = call;
         const controller = new AbortController();
         const abort = () => controller.abort(signal?.reason);
         signal?.addEventListener("abort", abort, { once: true });
         if (signal?.aborted)
             abort();
-        const timer = setTimeout(() => controller.abort(new Error("Basal request timed out")), this.timeoutMs);
+        const timer = setTimeout(() => controller.abort(new Error("Basal request timed out")), timeoutMs);
         let onAbort = () => { };
         const aborted = new Promise((_, reject) => {
             onAbort = () => reject(new BasalTransportError("Basal HTTP request aborted", { cause: controller.signal.reason }));
@@ -114,24 +129,39 @@ export class BasalClient {
         });
         const work = async () => {
             let response;
-            let raw;
+            let content;
+            let raw = "";
             try {
-                response = await this.fetch(this.baseUrl + path, {
-                    method, headers: body === undefined ? this.headers : { ...this.headers, "Content-Type": "application/json" },
-                    ...(encoded === undefined ? {} : { body: encoded }),
-                    signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
-                });
+                const init = {
+                    method: call.method, headers, signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
+                };
+                if (encoded !== undefined)
+                    init.body = encoded;
+                else if (call.body instanceof Blob)
+                    init.body = call.body;
+                else if (call.body !== undefined) {
+                    // Streamed request bodies require half-duplex fetch (Node.js, Chromium over HTTP/2).
+                    init.body = call.body(controller.signal);
+                    init.duplex = "half";
+                }
+                response = await this.fetch(this.baseUrl + call.path, init);
                 if (response.redirected || ([301, 302, 303, 307, 308].includes(response.status) && response.headers.has("Location"))) {
                     await response.body?.cancel().catch(() => { });
                     throw new BasalTransportError("Basal transport returned a redirect");
                 }
-                raw = await readBody(response, this.maxResponseBytes, controller.signal);
+                // A per-download cap limits successful artifact bytes. Error envelopes retain the client's normal cap
+                // so a small artifact cap does not hide an actionable 404/429 and its Retry-After.
+                content = await readBody(response, response.ok ? limit : this.maxResponseBytes, controller.signal);
+                if (!call.bytes || !response.ok)
+                    raw = new TextDecoder("utf-8", { fatal: true }).decode(content);
             }
             catch (cause) {
                 if (cause instanceof BasalError)
                     throw cause;
                 throw new BasalTransportError("Basal HTTP transport failed", { cause });
             }
+            if (call.bytes && response.ok)
+                return content;
             let data;
             try {
                 data = JSON.parse(raw);
@@ -157,6 +187,9 @@ export class BasalClient {
             controller.signal.removeEventListener("abort", onAbort);
             clearTimeout(timer);
             signal?.removeEventListener("abort", abort);
+            // An answer can arrive before a streamed upload is fully sent (e.g. 413); stop its source.
+            if (typeof call.body === "function")
+                controller.abort(new Error("Basal request finished"));
         }
     }
     async decide(state, questionsOrSignal, options = {}) {
@@ -191,4 +224,45 @@ export class BasalClient {
         return typed;
     }
     models(signal) { return this.request("GET", "v1/models", undefined, signal); }
+    /** Upload a JSONL input file (`purpose=batch`) from caller-owned bytes, a Blob or a stream; never fetches URLs. */
+    async uploadFile(request, options = {}) {
+        const form = uploadForm(request);
+        return await this.call({
+            method: "POST", path: "v1/files", body: form.body, headers: { "Content-Type": form.contentType },
+            signal: options.signal, timeoutMs: options.timeoutMs,
+        });
+    }
+    async listFiles(options = {}) {
+        return await this.call({ method: "GET", path: listPath("v1/files", options), signal: options.signal });
+    }
+    async getFile(fileId, options = {}) {
+        return await this.call({ method: "GET", path: resourcePath("v1/files", fileId), signal: options.signal });
+    }
+    async deleteFile(fileId, options = {}) {
+        return await this.call({ method: "DELETE", path: resourcePath("v1/files", fileId), signal: options.signal });
+    }
+    /** Raw file bytes (JSONL), buffered up to `maxBytes` (default `maxResponseBytes`); never JSON-parsed. */
+    async downloadFile(fileId, options = {}) {
+        return await this.call({
+            method: "GET", path: resourcePath("v1/files", fileId, "/content"), bytes: true,
+            headers: { Accept: "application/jsonl, application/json" },
+            signal: options.signal, timeoutMs: options.timeoutMs, maxBytes: options.maxBytes,
+        });
+    }
+    async createBatch(request, options = {}) {
+        const headers = idempotencyHeader(options.idempotencyKey);
+        return await this.call({ method: "POST", path: "v1/batches", json: createBody(request), headers, signal: options.signal });
+    }
+    async listBatches(options = {}) {
+        const { after, limit } = options;
+        const query = { ...(after === undefined ? {} : { after }), ...(limit === undefined ? {} : { limit }) };
+        return await this.call({ method: "GET", path: listPath("v1/batches", query), signal: options.signal });
+    }
+    async getBatch(batchId, options = {}) {
+        return await this.call({ method: "GET", path: resourcePath("v1/batches", batchId), signal: options.signal });
+    }
+    /** Request cancellation; the batch moves to `cancelling` and later `cancelled`. Does not wait. */
+    async cancelBatch(batchId, options = {}) {
+        return await this.call({ method: "POST", path: resourcePath("v1/batches", batchId, "/cancel"), signal: options.signal });
+    }
 }

package/dist/esm/resources.d.ts

@@ -0,0 +1,48 @@
+import { type Batch, type BatchCreateOptions, type BatchCreateParams, type BatchList, type BatchResultLine, type BatchResultsOptions, type BatchWaitOptions, type DeletedFile, type DownloadOptions, type FileList, type FileObject, type ListFilesOptions, type ListOptions, type RequestOptions, type TransferOptions, type UploadFileRequest } from "./batches.js";
+import type { BasalClient } from "./index.js";
+/** `client.files`: resource names for the flat Files methods, with the same behavior. */
+export declare class Files {
+    #private;
+    constructor(client: BasalClient);
+    /** `uploadFile`. */
+    create(request: UploadFileRequest, options?: TransferOptions): Promise<FileObject>;
+    /** `getFile`. */
+    retrieve(fileId: string, options?: RequestOptions): Promise<FileObject>;
+    /** `listFiles`. */
+    list(options?: ListFilesOptions): Promise<FileList>;
+    /** `deleteFile`. */
+    delete(fileId: string, options?: RequestOptions): Promise<DeletedFile>;
+    /** `downloadFile`: raw bytes, buffered up to `maxBytes` (default `maxResponseBytes`). */
+    content(fileId: string, options?: DownloadOptions): Promise<Uint8Array>;
+}
+/** `client.batches`: resource names for the flat Batch methods plus `create({requests})`, `wait` and `results`.
+ * Nothing runs in the background and nothing is retried.
+ */
+export declare class Batches {
+    #private;
+    constructor(client: BasalClient);
+    /** `{input_file_id, ...}` is `createBatch`. `{requests, ...}` validates and writes the JSONL in memory, uploads it,
+     * then creates the batch with `idempotencyKey` (generated when omitted). A create failure after the upload raises
+     * `BasalBatchSubmissionError` with the file id and key; the file is kept.
+     */
+    create(params: BatchCreateParams, options?: BatchCreateOptions): Promise<Batch>;
+    /** `getBatch`. */
+    retrieve(batchId: string, options?: RequestOptions): Promise<Batch>;
+    /** `listBatches`. */
+    list(options?: ListOptions): Promise<BatchList>;
+    /** `cancelBatch`: requests cancellation and returns without waiting. */
+    cancel(batchId: string, options?: RequestOptions): Promise<Batch>;
+    /** Retrieve until the status is `completed`, `failed`, `expired` or `cancelled` and return that batch (check
+     * `status`, `errors` and `request_counts`). The first retrieve is immediate. `timeoutMs` bounds the whole wait,
+     * aborting an in-flight retrieve, and raises `BasalBatchTimeoutError` without cancelling the batch. HTTP and
+     * transport errors propagate without retries; an abort rejects with `BasalTransportError` (cause: the reason).
+     */
+    wait(batchId: string, options?: BatchWaitOptions): Promise<Batch>;
+    /** Records of a finished batch: the output file, then the error file (once if both ids are equal). Does not wait:
+     * a non-terminal batch raises `BasalBatchNotReadyError`. Expired and cancelled batches yield their partial results;
+     * a completed batch can yield failed records. Batch-level validation errors are in `retrieve`/`wait`, not here.
+     * Each file is downloaded whole (bounded by `maxBytes`) and parsed one line at a time; a malformed line raises
+     * `BasalBatchResultError` after the earlier records were yielded.
+     */
+    results(batchId: string, options?: BatchResultsOptions): AsyncGenerator<BatchResultLine, void, undefined>;
+}

package/dist/esm/resources.js

@@ -0,0 +1,201 @@
+import { BasalBatchNotReadyError, BasalBatchSubmissionError, BasalBatchTimeoutError, BasalProtocolError, BasalTransportError, } from "./errors.js";
+import { idempotencyHeader, readBatchResultLines, resourcePath, serializeBatchRequests, TERMINAL_BATCH_STATUSES, } from "./batches.js";
+const TERMINAL = new Set(TERMINAL_BATCH_STATUSES);
+const COMMON_KEYS = new Set(["endpoint", "completion_window", "metadata", "output_expires_after"]);
+const MAX_TIMER_MS = 2_147_483_647;
+function duration(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMER_MS)
+        throw new TypeError(`${name} must be positive and at most ${MAX_TIMER_MS}`);
+    return value;
+}
+/** Resolves after `ms`, or rejects with `signal.reason` on abort; the timer and listener are always removed. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); reject(signal.reason); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function expiresAfter(value) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value !== "object" || value.anchor !== "created_at" || !Number.isSafeInteger(value.seconds) || value.seconds < 0) {
+        throw new TypeError("output_expires_after needs anchor created_at and whole seconds");
+    }
+}
+/** Common parameters of the `requests` form, checked before the upload so a local mistake leaves no orphan file.
+ * Metadata limits stay with the server, as in `createBatch`.
+ */
+function commonParams(params) {
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && key !== "requests" && !COMMON_KEYS.has(key))
+            throw new TypeError(`unsupported batch parameter ${JSON.stringify(key)}`);
+    }
+    const { endpoint, completion_window, metadata, output_expires_after } = params;
+    if (endpoint !== undefined && endpoint !== "/v1/basal")
+        throw new TypeError("endpoint must be /v1/basal");
+    if (completion_window !== undefined && completion_window !== "24h")
+        throw new TypeError("completion_window must be 24h");
+    if (metadata !== undefined && metadata !== null) {
+        if (typeof metadata !== "object" || Array.isArray(metadata) || Object.values(metadata).some(v => typeof v !== "string")) {
+            throw new TypeError("metadata must be an object of string values");
+        }
+    }
+    expiresAfter(output_expires_after);
+    const common = {};
+    for (const key of COMMON_KEYS)
+        if (params[key] !== undefined)
+            Object.assign(common, { [key]: params[key] });
+    return common;
+}
+function randomKey() {
+    const random = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(random);
+    return `basal-sdk-${Array.from(random, b => b.toString(16).padStart(2, "0")).join("")}`;
+}
+/** `client.files`: resource names for the flat Files methods, with the same behavior. */
+export class Files {
+    #client;
+    constructor(client) { this.#client = client; }
+    /** `uploadFile`. */
+    create(request, options = {}) { return this.#client.uploadFile(request, options); }
+    /** `getFile`. */
+    retrieve(fileId, options = {}) { return this.#client.getFile(fileId, options); }
+    /** `listFiles`. */
+    list(options = {}) { return this.#client.listFiles(options); }
+    /** `deleteFile`. */
+    delete(fileId, options = {}) { return this.#client.deleteFile(fileId, options); }
+    /** `downloadFile`: raw bytes, buffered up to `maxBytes` (default `maxResponseBytes`). */
+    content(fileId, options = {}) { return this.#client.downloadFile(fileId, options); }
+}
+/** `client.batches`: resource names for the flat Batch methods plus `create({requests})`, `wait` and `results`.
+ * Nothing runs in the background and nothing is retried.
+ */
+export class Batches {
+    #client;
+    constructor(client) { this.#client = client; }
+    /** `{input_file_id, ...}` is `createBatch`. `{requests, ...}` validates and writes the JSONL in memory, uploads it,
+     * then creates the batch with `idempotencyKey` (generated when omitted). A create failure after the upload raises
+     * `BasalBatchSubmissionError` with the file id and key; the file is kept.
+     */
+    async create(params, options = {}) {
+        if (!params || typeof params !== "object")
+            throw new TypeError("batch parameters must be an object");
+        const fromFile = params.input_file_id !== undefined;
+        if (fromFile === (params.requests !== undefined))
+            throw new TypeError("pass exactly one of input_file_id or requests");
+        const { uploadTimeoutMs, ...createOptions } = options;
+        if (fromFile) {
+            if (uploadTimeoutMs !== undefined)
+                throw new TypeError("uploadTimeoutMs applies only to requests");
+            return this.#client.createBatch(params, createOptions);
+        }
+        const common = commonParams(params);
+        const idempotencyKey = createOptions.idempotencyKey ?? randomKey();
+        idempotencyHeader(idempotencyKey);
+        duration(uploadTimeoutMs, 1, "uploadTimeoutMs");
+        const content = serializeBatchRequests(params.requests);
+        const transfer = {};
+        if (createOptions.signal !== undefined)
+            transfer.signal = createOptions.signal;
+        if (uploadTimeoutMs !== undefined)
+            transfer.timeoutMs = uploadTimeoutMs;
+        const file = await this.#client.uploadFile({ file: content, filename: "batch_input.jsonl" }, transfer);
+        if (!file || typeof file.id !== "string" || !file.id)
+            throw new BasalProtocolError("Basal upload response has no file id");
+        try {
+            return await this.#client.createBatch({ ...common, input_file_id: file.id }, { ...createOptions, idempotencyKey });
+        }
+        catch (cause) {
+            throw new BasalBatchSubmissionError(file, idempotencyKey, { cause });
+        }
+    }
+    /** `getBatch`. */
+    retrieve(batchId, options = {}) { return this.#client.getBatch(batchId, options); }
+    /** `listBatches`. */
+    list(options = {}) { return this.#client.listBatches(options); }
+    /** `cancelBatch`: requests cancellation and returns without waiting. */
+    cancel(batchId, options = {}) { return this.#client.cancelBatch(batchId, options); }
+    /** Retrieve until the status is `completed`, `failed`, `expired` or `cancelled` and return that batch (check
+     * `status`, `errors` and `request_counts`). The first retrieve is immediate. `timeoutMs` bounds the whole wait,
+     * aborting an in-flight retrieve, and raises `BasalBatchTimeoutError` without cancelling the batch. HTTP and
+     * transport errors propagate without retries; an abort rejects with `BasalTransportError` (cause: the reason).
+     */
+    async wait(batchId, options = {}) {
+        resourcePath("v1/batches", batchId);
+        const timeoutMs = duration(options.timeoutMs, 600_000, "timeoutMs");
+        const pollIntervalMs = duration(options.pollIntervalMs, 5_000, "pollIntervalMs");
+        const { signal } = options;
+        const controller = new AbortController();
+        const forward = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", forward, { once: true });
+        if (signal?.aborted)
+            forward();
+        const expired = new Error("Basal batch wait timed out");
+        // Timers use a monotonic clock, so wall-clock changes do not move the deadline.
+        const timer = setTimeout(() => controller.abort(expired), timeoutMs);
+        let last = null;
+        try {
+            for (;;) {
+                try {
+                    last = await this.#client.getBatch(batchId, { signal: controller.signal });
+                    if (TERMINAL.has(last.status))
+                        return last;
+                    await sleep(pollIntervalMs, controller.signal);
+                }
+                catch (cause) {
+                    if (controller.signal.reason === expired && (cause === expired || cause instanceof BasalTransportError)) {
+                        throw new BasalBatchTimeoutError(batchId, last, timeoutMs, { cause });
+                    }
+                    if (controller.signal.aborted && cause === controller.signal.reason) {
+                        throw new BasalTransportError("Basal batch wait aborted", { cause });
+                    }
+                    throw cause;
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", forward);
+        }
+    }
+    /** Records of a finished batch: the output file, then the error file (once if both ids are equal). Does not wait:
+     * a non-terminal batch raises `BasalBatchNotReadyError`. Expired and cancelled batches yield their partial results;
+     * a completed batch can yield failed records. Batch-level validation errors are in `retrieve`/`wait`, not here.
+     * Each file is downloaded whole (bounded by `maxBytes`) and parsed one line at a time; a malformed line raises
+     * `BasalBatchResultError` after the earlier records were yielded.
+     */
+    results(batchId, options = {}) {
+        resourcePath("v1/batches", batchId);
+        duration(options.timeoutMs, 1, "timeoutMs");
+        if (options.maxBytes !== undefined && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0)) {
+            throw new TypeError("maxBytes must be a positive safe integer");
+        }
+        return this.#results(batchId, options);
+    }
+    async *#results(batchId, options) {
+        const request = options.signal === undefined ? {} : { signal: options.signal };
+        const batch = await this.#client.getBatch(batchId, request);
+        if (!TERMINAL.has(batch.status))
+            throw new BasalBatchNotReadyError(batchId, batch);
+        const ids = [];
+        for (const id of [batch.output_file_id, batch.error_file_id]) {
+            if (id === null || id === undefined)
+                continue;
+            if (typeof id !== "string" || !id)
+                throw new BasalProtocolError("Basal batch has an invalid result file id");
+            if (!ids.includes(id))
+                ids.push(id);
+        }
+        for (const fileId of ids) {
+            const content = await this.#client.downloadFile(fileId, options);
+            yield* readBatchResultLines(content, fileId);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsoltech/basal-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "TypeScript and JavaScript client for the native Basal HTTP API",
   "type": "module",
   "main": "./dist/cjs/index.cjs",