@itsoltech/basal-client 0.4.0 → 0.5.0

package/dist/cjs/resources.cjs

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Batches = exports.Files = void 0;
+const errors_cjs_1 = require("./errors.cjs");
+const batches_cjs_1 = require("./batches.cjs");
+const TERMINAL = new Set(batches_cjs_1.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. */
+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); }
+}
+exports.Files = Files;
+/** `client.batches`: resource names for the flat Batch methods plus `create({requests})`, `wait` and `results`.
+ * Nothing runs in the background and nothing is retried.
+ */
+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();
+        (0, batches_cjs_1.idempotencyHeader)(idempotencyKey);
+        duration(uploadTimeoutMs, 1, "uploadTimeoutMs");
+        const content = (0, batches_cjs_1.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 errors_cjs_1.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 errors_cjs_1.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 = {}) {
+        (0, batches_cjs_1.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 errors_cjs_1.BasalTransportError)) {
+                        throw new errors_cjs_1.BasalBatchTimeoutError(batchId, last, timeoutMs, { cause });
+                    }
+                    if (controller.signal.aborted && cause === controller.signal.reason) {
+                        throw new errors_cjs_1.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 = {}) {
+        (0, batches_cjs_1.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 errors_cjs_1.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 errors_cjs_1.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* (0, batches_cjs_1.readBatchResultLines)(content, fileId);
+        }
+    }
+}
+exports.Batches = Batches;

package/dist/cjs/resources.d.cts

@@ -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.cjs";
+import type { BasalClient } from "./index.cjs";
+/** `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/batches.d.ts

@@ -146,6 +146,45 @@ export interface UploadFileRequest {
     /** File lifetime (server default 30 days). */
     expires_after?: ExpiresAfter;
 }
+/** Parameters shared by both `batches.create` forms. Defaults: `endpoint: "/v1/basal"`, `completion_window: "24h"`. */
+export interface BatchCreateCommonParams {
+    endpoint?: "/v1/basal";
+    completion_window?: "24h";
+    metadata?: Metadata | null;
+    /** Lifetime of each result file, anchored at its creation. */
+    output_expires_after?: ExpiresAfter | null;
+}
+/** Create a batch from an uploaded input file; the same request as `createBatch`. */
+export interface BatchCreateFromFileParams extends BatchCreateCommonParams {
+    input_file_id: string;
+    requests?: never;
+}
+/** Create a batch from records: the SDK writes JSONL in memory, uploads it (`purpose=batch`), then creates the batch. */
+export interface BatchCreateFromRequestsParams extends BatchCreateCommonParams {
+    /** 1–50 000 records, unique `custom_id` (1–256 UTF-8 bytes), at most 200 000 000 bytes of JSONL in total. */
+    requests: Iterable<BatchInputLine>;
+    input_file_id?: never;
+}
+/** Exactly one of `input_file_id` or `requests`. */
+export type BatchCreateParams = BatchCreateFromFileParams | BatchCreateFromRequestsParams;
+export interface BatchCreateOptions extends CreateBatchOptions {
+    /** Deadline of the input upload (`requests` form only); defaults to the client `timeoutMs`. */
+    uploadTimeoutMs?: number;
+}
+export interface BatchWaitOptions extends RequestOptions {
+    /** Deadline of the whole wait, including in-flight retrieves and sleeps; default 600 000 ms. */
+    timeoutMs?: number;
+    /** Delay between retrieves; default 5000 ms. The first retrieve is immediate. */
+    pollIntervalMs?: number;
+}
+/** Each result file is downloaded whole into memory (up to `maxBytes`, default the client `maxResponseBytes`) and
+ * parsed one line at a time; `timeoutMs` is the deadline of each download.
+ */
+export type BatchResultsOptions = DownloadOptions;
+/** Client-side bounds of `batches.create({requests})`, equal to the server defaults; a server may be configured lower. */
+export declare const MAX_BATCH_REQUESTS = 50000;
+export declare const MAX_BATCH_INPUT_BYTES = 200000000;
+export declare const TERMINAL_BATCH_STATUSES: readonly BatchStatus[];
 /** Path segment of a resource id. `.` and `..` would be resolved as dot segments by URL parsing. */
 export declare function resourcePath(prefix: string, id: string, suffix?: string): string;
 export declare function listPath(path: string, options: ListFilesOptions): string;
@@ -164,3 +203,12 @@ export declare function uploadForm(request: UploadFileRequest): Multipart;
 export declare function batchInput(lines: Iterable<BatchInputLine>): Uint8Array;
 /** Parse downloaded result bytes (output or error file) into lines. Never fetches anything. */
 export declare function parseBatchResults(content: Uint8Array): BatchResultLine[];
+/** Validated JSONL of `batches.create({requests})`: nonempty, supported envelope, unique ids and the bounds above.
+ * The result is held in memory (at most `MAX_BATCH_INPUT_BYTES`). Never sends anything.
+ */
+export declare function serializeBatchRequests(requests: Iterable<BatchInputLine>): Blob;
+/** Result lines of one downloaded file, decoded and checked one line at a time (no list of all lines). A final LF is
+ * optional; any other empty line, invalid UTF-8 (a BOM included), JSON or envelope raises `BasalBatchResultError`.
+ * Unknown fields are preserved.
+ */
+export declare function readBatchResultLines(content: Uint8Array, fileId: string): Generator<BatchResultLine, void, undefined>;

package/dist/esm/batches.js

@@ -1,4 +1,8 @@
-import { BasalProtocolError } from "./errors.js";
+import { BasalBatchResultError, BasalProtocolError } from "./errors.js";
+/** Client-side bounds of `batches.create({requests})`, equal to the server defaults; a server may be configured lower. */
+export const MAX_BATCH_REQUESTS = 50_000;
+export const MAX_BATCH_INPUT_BYTES = 200_000_000;
+export const TERMINAL_BATCH_STATUSES = Object.freeze(["completed", "failed", "expired", "cancelled"]);
 const encoder = new TextEncoder();
 /** Path segment of a resource id. `.` and `..` would be resolved as dot segments by URL parsing. */
 export function resourcePath(prefix, id, suffix = "") {
@@ -180,3 +184,117 @@ export function parseBatchResults(content) {
         return value;
     });
 }
+const LINE_KEYS = new Set(["custom_id", "method", "url", "body"]);
+/** Validated JSONL of `batches.create({requests})`: nonempty, supported envelope, unique ids and the bounds above.
+ * The result is held in memory (at most `MAX_BATCH_INPUT_BYTES`). Never sends anything.
+ */
+export function serializeBatchRequests(requests) {
+    if (!requests || typeof requests !== "object" || typeof requests[Symbol.iterator] !== "function") {
+        throw new TypeError("requests must be an iterable of batch records");
+    }
+    const parts = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const line of requests) {
+        const at = `requests[${parts.length}]`;
+        if (parts.length >= MAX_BATCH_REQUESTS)
+            throw new TypeError(`requests must have at most ${MAX_BATCH_REQUESTS} records`);
+        if (!line || typeof line !== "object" || Array.isArray(line))
+            throw new TypeError(`${at} must be an object`);
+        for (const key of Object.keys(line)) {
+            if (!LINE_KEYS.has(key))
+                throw new TypeError(`${at} has unsupported field ${JSON.stringify(key)}`);
+        }
+        const { custom_id: id, body } = line;
+        // Lone surrogates have no UTF-8 form; the server compares ids byte for byte.
+        if (typeof id !== "string" || !id || /\p{Cs}/u.test(id) || encoder.encode(id).length > 256) {
+            throw new TypeError(`${at}.custom_id must be a string of 1-256 UTF-8 bytes`);
+        }
+        if (seen.has(id))
+            throw new TypeError(`${at}.custom_id duplicates an earlier record`);
+        seen.add(id);
+        if (line.method !== undefined && line.method !== "POST")
+            throw new TypeError(`${at}.method must be POST`);
+        if (line.url !== undefined && line.url !== "/v1/basal")
+            throw new TypeError(`${at}.url must be /v1/basal`);
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            throw new TypeError(`${at}.body must be a native request object`);
+        if (body.stream === true)
+            throw new TypeError(`${at}.body.stream must not be true`);
+        let json;
+        try {
+            json = JSON.stringify({ custom_id: id, method: "POST", url: "/v1/basal", body });
+        }
+        catch (cause) {
+            throw new TypeError(`${at}.body is not serializable as JSON`, { cause });
+        }
+        const encoded = encoder.encode(json + "\n");
+        bytes += encoded.byteLength;
+        if (bytes > MAX_BATCH_INPUT_BYTES)
+            throw new TypeError(`requests exceed ${MAX_BATCH_INPUT_BYTES} bytes of JSONL`);
+        parts.push(encoded);
+    }
+    if (!parts.length)
+        throw new TypeError("requests must contain at least one record");
+    return new Blob(parts, { type: "application/jsonl" });
+}
+/** Result lines of one downloaded file, decoded and checked one line at a time (no list of all lines). A final LF is
+ * optional; any other empty line, invalid UTF-8 (a BOM included), JSON or envelope raises `BasalBatchResultError`.
+ * Unknown fields are preserved.
+ */
+export function* readBatchResultLines(content, fileId) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    let start = 0;
+    for (let number = 1; start < content.byteLength; number++) {
+        // UTF-8 never encodes another code point with byte 0x0A, so splitting bytes at LF is exact.
+        let end = content.indexOf(0x0a, start);
+        if (end < 0)
+            end = content.byteLength;
+        const bytes = content.subarray(start, end);
+        start = end + 1;
+        let text;
+        try {
+            text = decoder.decode(bytes);
+        }
+        catch (cause) {
+            throw new BasalBatchResultError(fileId, number, "is not UTF-8", { cause });
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (cause) {
+            throw new BasalBatchResultError(fileId, number, "is not JSON", { cause });
+        }
+        const problem = envelopeProblem(value);
+        if (problem)
+            throw new BasalBatchResultError(fileId, number, problem);
+        yield value;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function envelopeProblem(value) {
+    if (!isObject(value))
+        return "is not a JSON object";
+    if (typeof value.id !== "string" || !value.id)
+        return "has no string id";
+    if (typeof value.custom_id !== "string" || !value.custom_id)
+        return "has no string custom_id";
+    const { response, error } = value;
+    if (response === undefined || error === undefined)
+        return "lacks response or error";
+    if (response !== null && (!isObject(response) || !Number.isSafeInteger(response.status_code)
+        || response.status_code < 100 || response.status_code > 599
+        || typeof response.request_id !== "string" || !response.request_id || !isObject(response.body)))
+        return "has an invalid response";
+    if (error !== null && (!isObject(error) || typeof error.code !== "string" || !error.code || typeof error.message !== "string")) {
+        return "has an invalid error";
+    }
+    if (response === null && error === null)
+        return "has neither response nor error";
+    if (response !== null && error !== null)
+        return "has both response and error";
+    return undefined;
+}

package/dist/esm/errors.d.ts

@@ -1,3 +1,4 @@
+import type { Batch, FileObject } from "./batches.js";
 export declare class BasalError extends Error {
 }
 /** Non-2xx response. Server body and Retry-After are available without logging them. */
@@ -13,3 +14,46 @@ export declare class BasalProtocolError extends BasalError {
 }
 export declare class BasalResponseTooLargeError extends BasalError {
 }
+/** `batches.create({requests})` uploaded the input file, but creating the batch failed (HTTP, transport or abort).
+ * The SDK neither retries nor deletes the file. The create may still have succeeded on the server, so resume with
+ * the same parameters, `{input_file_id: error.fileId}` and `{idempotencyKey: error.idempotencyKey}`; the original
+ * failure is in `cause`.
+ */
+export declare class BasalBatchSubmissionError extends BasalError {
+    readonly file: FileObject;
+    readonly idempotencyKey: string;
+    readonly fileId: string;
+    constructor(file: FileObject, idempotencyKey: string, options: {
+        cause: unknown;
+    });
+}
+/** `batches.wait` reached its deadline. The batch keeps running on the server; nothing is cancelled.
+ * `lastBatch` is the last retrieved state (null if no retrieve finished) and is non-enumerable, like `BasalHTTPError.body`.
+ */
+export declare class BasalBatchTimeoutError extends BasalError {
+    readonly batchId: string;
+    readonly lastBatch: Batch | null;
+    readonly timeoutMs: number;
+    constructor(batchId: string, lastBatch: Batch | null, timeoutMs: number, options?: {
+        cause: unknown;
+    });
+}
+/** `batches.results` was called for a batch that is not `completed`, `failed`, `expired` or `cancelled`.
+ * `batch` (non-enumerable) is the retrieved state; `status` is its raw status.
+ */
+export declare class BasalBatchNotReadyError extends BasalError {
+    readonly batchId: string;
+    readonly batch: Batch;
+    readonly status: string;
+    constructor(batchId: string, batch: Batch);
+}
+/** A result file line that is not UTF-8, not JSON or not a result envelope. `line` is 1-based; the content is not
+ * copied into the error.
+ */
+export declare class BasalBatchResultError extends BasalProtocolError {
+    readonly fileId: string;
+    readonly line: number;
+    constructor(fileId: string, line: number, reason: string, options?: {
+        cause: unknown;
+    });
+}

package/dist/esm/errors.js

@@ -21,3 +21,65 @@ export class BasalProtocolError extends BasalError {
 }
 export class BasalResponseTooLargeError extends BasalError {
 }
+/** `batches.create({requests})` uploaded the input file, but creating the batch failed (HTTP, transport or abort).
+ * The SDK neither retries nor deletes the file. The create may still have succeeded on the server, so resume with
+ * the same parameters, `{input_file_id: error.fileId}` and `{idempotencyKey: error.idempotencyKey}`; the original
+ * failure is in `cause`.
+ */
+export class BasalBatchSubmissionError extends BasalError {
+    file;
+    idempotencyKey;
+    fileId;
+    constructor(file, idempotencyKey, options) {
+        super(`Basal batch creation failed after uploading input file ${file.id}`, options);
+        this.file = file;
+        this.idempotencyKey = idempotencyKey;
+        this.name = "BasalBatchSubmissionError";
+        this.fileId = file.id;
+    }
+}
+/** `batches.wait` reached its deadline. The batch keeps running on the server; nothing is cancelled.
+ * `lastBatch` is the last retrieved state (null if no retrieve finished) and is non-enumerable, like `BasalHTTPError.body`.
+ */
+export class BasalBatchTimeoutError extends BasalError {
+    batchId;
+    lastBatch;
+    timeoutMs;
+    constructor(batchId, lastBatch, timeoutMs, options) {
+        super(`Basal batch did not reach a terminal status within ${timeoutMs} ms`, options);
+        this.batchId = batchId;
+        this.lastBatch = lastBatch;
+        this.timeoutMs = timeoutMs;
+        this.name = "BasalBatchTimeoutError";
+        Object.defineProperty(this, "lastBatch", { enumerable: false });
+    }
+}
+/** `batches.results` was called for a batch that is not `completed`, `failed`, `expired` or `cancelled`.
+ * `batch` (non-enumerable) is the retrieved state; `status` is its raw status.
+ */
+export class BasalBatchNotReadyError extends BasalError {
+    batchId;
+    batch;
+    status;
+    constructor(batchId, batch) {
+        super("Basal batch has not reached a terminal status");
+        this.batchId = batchId;
+        this.batch = batch;
+        this.name = "BasalBatchNotReadyError";
+        this.status = String(batch.status);
+        Object.defineProperty(this, "batch", { enumerable: false });
+    }
+}
+/** A result file line that is not UTF-8, not JSON or not a result envelope. `line` is 1-based; the content is not
+ * copied into the error.
+ */
+export class BasalBatchResultError extends BasalProtocolError {
+    fileId;
+    line;
+    constructor(fileId, line, reason, options) {
+        super(`Batch result file ${fileId} line ${line} ${reason}`, options);
+        this.fileId = fileId;
+        this.line = line;
+        this.name = "BasalBatchResultError";
+    }
+}

package/dist/esm/index.d.ts

@@ -1,11 +1,13 @@
 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";
+import { Batches, Files } from "./resources.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";
+export { batchInput, MAX_BATCH_INPUT_BYTES, MAX_BATCH_REQUESTS, parseBatchResults, TERMINAL_BATCH_STATUSES, } from "./batches.js";
+export { Batches, Files } from "./resources.js";
+export type { Batch, BatchCreateCommonParams, BatchCreateFromFileParams, BatchCreateFromRequestsParams, BatchCreateOptions, BatchCreateParams, BatchErrorCode, BatchErrorEntry, BatchErrors, BatchInputLine, BatchList, BatchResultLine, BatchResultsOptions, BatchStatus, BatchWaitOptions, 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[] | {
@@ -189,6 +191,10 @@ export declare class BasalClient {
     private readonly timeoutMs;
     private readonly maxResponseBytes;
     private readonly fetch;
+    /** Files API under resource names: `create`, `retrieve`, `list`, `delete`, `content`. */
+    readonly files: Files;
+    /** Batch API under resource names, with `create({requests})`, `wait` and `results`. */
+    readonly batches: Batches;
     constructor(options?: BasalClientOptions);
     private request;
     private call;

package/dist/esm/index.js

@@ -1,11 +1,13 @@
 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 * from "./errors.js";
-export { batchInput, parseBatchResults } from "./batches.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();
@@ -69,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("#")) {
@@ -93,6 +99,8 @@ 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 });