@itsoltech/basal-client 0.3.0 → 0.4.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class BasalError extends Error {
+}
+/** Non-2xx response. Server body and Retry-After are available without logging them. */
+export declare class BasalHTTPError extends BasalError {
+    readonly statusCode: number;
+    readonly body: unknown;
+    readonly retryAfter: string | null;
+    constructor(statusCode: number, body: unknown, retryAfter: string | null);
+}
+export declare class BasalTransportError extends BasalError {
+}
+export declare class BasalProtocolError extends BasalError {
+}
+export declare class BasalResponseTooLargeError extends BasalError {
+}

package/dist/esm/errors.js

@@ -0,0 +1,23 @@
+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 {
+}

package/dist/esm/index.d.ts

@@ -1,7 +1,11 @@
 import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.js";
+import { type Batch, type BatchList, type CreateBatchOptions, type CreateBatchRequest, type DeletedFile, type DownloadOptions, type FileList, type FileObject, type ListFilesOptions, type ListOptions, type RequestOptions, type TransferOptions, type UploadFileRequest } from "./batches.js";
 export * from "./questions.js";
 export * from "./media.js";
 export * from "./tasks.js";
+export * from "./errors.js";
+export { batchInput, parseBatchResults } from "./batches.js";
+export type { Batch, BatchErrorCode, BatchErrorEntry, BatchErrors, BatchInputLine, BatchList, BatchResultLine, BatchStatus, CreateBatchOptions, CreateBatchRequest, DeletedFile, DownloadOptions, ExpiresAfter, FileList, FileObject, FilePurpose, ListFilesOptions, ListOptions, ListPage, Metadata, RequestCounts, RequestOptions, TransferOptions, UploadContent, UploadFileRequest, } from "./batches.js";
 import type { TaskAnswer } from "./tasks.js";
 /** Native Basal wire types. Criterion order is significant; do not sort keys. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
@@ -164,21 +168,6 @@ export interface ModelMetadata {
 export interface ModelsResponse {
     models: ModelMetadata[];
 }
-export declare class BasalError extends Error {
-}
-/** Non-2xx response. Server body and Retry-After are available without logging them. */
-export declare class BasalHTTPError extends BasalError {
-    readonly statusCode: number;
-    readonly body: unknown;
-    readonly retryAfter: string | null;
-    constructor(statusCode: number, body: unknown, retryAfter: string | null);
-}
-export declare class BasalTransportError extends BasalError {
-}
-export declare class BasalProtocolError extends BasalError {
-}
-export declare class BasalResponseTooLargeError extends BasalError {
-}
 /** Web Fetch input accepted by browsers and server runtimes. */
 export type RequestInput = string | URL | Request;
 /** A transport adapter must honor signal/redirect and return a standard Web Response. */
@@ -202,7 +191,20 @@ export declare class BasalClient {
     private readonly fetch;
     constructor(options?: BasalClientOptions);
     private request;
+    private call;
     decide(request: DecisionRequest, signal?: AbortSignal): Promise<DecisionResponse>;
     decide<const Q extends QuestionSet>(state: JsonValue, questions: Q, options?: DecisionOptions): Promise<TypedDecisionResponse<Q>>;
     models(signal?: AbortSignal): Promise<ModelsResponse>;
+    /** Upload a JSONL input file (`purpose=batch`) from caller-owned bytes, a Blob or a stream; never fetches URLs. */
+    uploadFile(request: UploadFileRequest, options?: TransferOptions): Promise<FileObject>;
+    listFiles(options?: ListFilesOptions): Promise<FileList>;
+    getFile(fileId: string, options?: RequestOptions): Promise<FileObject>;
+    deleteFile(fileId: string, options?: RequestOptions): Promise<DeletedFile>;
+    /** Raw file bytes (JSONL), buffered up to `maxBytes` (default `maxResponseBytes`); never JSON-parsed. */
+    downloadFile(fileId: string, options?: DownloadOptions): Promise<Uint8Array>;
+    createBatch(request: CreateBatchRequest, options?: CreateBatchOptions): Promise<Batch>;
+    listBatches(options?: ListOptions): Promise<BatchList>;
+    getBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
+    /** Request cancellation; the batch moves to `cancelling` and later `cancelled`. Does not wait. */
+    cancelBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
 }

package/dist/esm/index.js

@@ -1,40 +1,20 @@
 import { buildRequest } from "./questions.js";
+import { BasalError, BasalHTTPError, BasalProtocolError, BasalResponseTooLargeError, BasalTransportError } from "./errors.js";
+import { createBody, idempotencyHeader, listPath, resourcePath, uploadForm, } from "./batches.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, parseBatchResults } from "./batches.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 +29,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.
@@ -96,15 +94,24 @@ export class BasalClient {
             this.headers.Authorization = `Bearer ${options.apiKey}`;
         }
     }
-    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);
+    request(method, path, body, signal) {
+        return this.call({ method, path, json: body, signal });
+    }
+    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 +121,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 +179,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 +216,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/package.json

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