@itsoltech/basal-client 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @itsoltech/basal-client
 
-TypeScript/JavaScript SDK for the native Basal API (`POST /v1/basal`). ESM and CommonJS, with type declarations.
+TypeScript/JavaScript SDK for the native Basal API (`POST /v1/basal`) and the Batch API. ESM and CommonJS, with type declarations.
 Node.js 22+ or modern browsers with `fetch` and `AbortController`. No runtime dependencies or GPU requirement.
 
 This package is versioned independently. Release tag: `sdk-typescript-vX.Y.Z`.
@@ -75,6 +75,134 @@ validated before the promise resolves. Typed evidence defaults to an empty array
 retains the native JSON without those defaults. The one-argument raw `decide(request, signal)` remains available.
 
 
+## Batch API
+
+Resource helpers (`create`, `wait`, `results`) require SDK 0.5.0+.
+
+Requires a Basal server with the Batch API enabled ([docs/BATCHES.md](https://github.com/itsoltech/basal-rs/blob/main/docs/BATCHES.md)).
+Every Batch and Files route needs `apiKey` set to a batch token `<key_id>.<secret>`, also on loopback; the owner
+of every file and batch comes from that token. Records are native `/v1/basal` requests; the SDK only transfers files and controls batches.
+`client.files` and `client.batches` follow the OpenAI resource names and workflow (upload, create, retrieve, download).
+That compatibility is in naming and workflow only: records are native Basal requests, not OpenAI chat payloads.
+
+```typescript
+import { BasalBatchSubmissionError, BasalClient, batchInput, buildRequest, choice, parseBatchResults } from "@itsoltech/basal-client";
+
+const client = new BasalClient({ baseUrl: "https://basal.example.com", apiKey: "<key_id>.<secret>" });
+const body = buildRequest("Klient prosi o zwrot.", { department: choice("Dział?", { returns: "Zwroty", support: "Wsparcie" }) }, {});
+
+// Simplified: records in, terminal batch and records out.
+const batch = await client.batches.create({ requests: [{ custom_id: "ticket-1", body }], metadata: { source: "tickets" } });
+const done = await client.batches.wait(batch.id);           // completed, failed, expired or cancelled
+for await (const line of client.batches.results(done.id)) { // output file, then error file
+  console.log(line.custom_id, line.response?.status_code ?? line.error?.code);
+}
+```
+
+```typescript
+// Same steps as separate calls: upload, create, retrieve, download.
+const file = await client.files.create({ file: batchInput([{ custom_id: "ticket-1", body }]), filename: "tickets.jsonl" });
+const created = await client.batches.create({ input_file_id: file.id }, { idempotencyKey: "tickets-2026-10-20" });
+const current = await client.batches.retrieve(created.id);
+const lines = current.output_file_id ? parseBatchResults(await client.files.content(current.output_file_id)) : [];
+```
+
+| Resource method | Same as |
+|---|---|
+| `files.create`, `files.retrieve`, `files.list`, `files.delete`, `files.content` | `uploadFile`, `getFile`, `listFiles`, `deleteFile`, `downloadFile` |
+| `batches.create({input_file_id, ...})`, `batches.retrieve`, `batches.list`, `batches.cancel` | `createBatch`, `getBatch`, `listBatches`, `cancelBatch` |
+| `batches.create({requests, ...}, {idempotencyKey?, uploadTimeoutMs?, signal?})` | validate, `uploadFile`, `createBatch` |
+| `batches.wait(id, {timeoutMs?, pollIntervalMs?, signal?})` | `getBatch` until a terminal status |
+| `batches.results(id, {maxBytes?, timeoutMs?, signal?})` → async iterator | `getBatch`, `downloadFile`, line parsing |
+
+`batches.create` takes exactly one of `input_file_id` and `requests` (a type error otherwise, and a `TypeError` at runtime).
+`requests` is an iterable of `{custom_id, body, method?, url?}`; the SDK checks it before uploading anything: at least one
+record, no other fields, unique `custom_id` of 1–256 UTF-8 bytes, `method` POST, `url` /v1/basal, an object `body`, at most
+`MAX_BATCH_REQUESTS` (50 000) records and `MAX_BATCH_INPUT_BYTES` (200 000 000) bytes of JSONL. These are the server
+defaults; a server configured lower refuses the upload or fails the batch. The JSONL is built in memory, so for a short
+time memory holds up to about twice its size; `body` contents are checked by the server. Unknown top-level parameters
+are refused locally in this form. The upload uses the client `timeoutMs` unless `uploadTimeoutMs` is set.
+Without `idempotencyKey` the SDK generates one for the call. If the upload succeeds and creating the batch then fails
+(HTTP, transport or abort), `BasalBatchSubmissionError` gives `fileId`, `idempotencyKey` and the original error in
+`cause`. The file is not deleted and nothing is retried. The create may have succeeded on the server, so resume
+with the file instead of uploading again:
+
+```typescript
+try { await client.batches.create({ requests, metadata }); }
+catch (error) {
+  if (!(error instanceof BasalBatchSubmissionError)) throw error;
+  await client.batches.create({ input_file_id: error.fileId, metadata }, { idempotencyKey: error.idempotencyKey });
+}
+```
+
+`batches.wait` retrieves immediately, then every `pollIntervalMs` (default 5000) until `completed`, `failed`, `expired`
+or `cancelled`, and returns that batch. Check `status`, `errors` (validation errors of a `failed` batch) and
+`request_counts`. Other and unknown statuses keep it waiting. `timeoutMs` (default 600 000) bounds the whole wait, including an
+in-flight retrieve, which is aborted. It then raises `BasalBatchTimeoutError` with `batchId` and `lastBatch` (null if no
+retrieve finished). The batch is not cancelled. HTTP and transport errors propagate without retries. Aborting
+`signal` rejects with `BasalTransportError` (the reason in `cause`). Timers and listeners are removed when the wait ends;
+nothing keeps running in the background.
+
+`batches.results` does not wait: a batch that is not terminal raises `BasalBatchNotReadyError` (`batchId`, `status`).
+It yields the records of `output_file_id`, then `error_file_id` (once if they are equal). Match records by `custom_id`, not by order. An
+expired or cancelled batch yields its partial results; a completed batch can yield failed records (`response.status_code`
+other than 200, or `error`). A batch without result files yields nothing. Each file is downloaded whole into memory,
+bounded by `maxBytes` (default `maxResponseBytes`, 8 MiB); raise it for large results. `timeoutMs` is the deadline of each
+download. The downloaded bytes are then decoded and checked one line at a time. A line that is not UTF-8 (including a BOM), not JSON, or not a
+result envelope (`id`, `custom_id`, `response` or `error`) raises `BasalBatchResultError` (`fileId`, 1-based `line`, a
+`BasalProtocolError`) after the earlier records were yielded; no record is skipped. Invalid arguments throw when
+`results` is called; nothing is sent until iteration starts.
+
+The flat methods below remain available with unchanged behavior. They never poll.
+
+```typescript
+import { BasalClient, batchInput, buildRequest, choice, parseBatchResults } from "@itsoltech/basal-client";
+
+const client = new BasalClient({ baseUrl: "https://basal.example.com", apiKey: "<key_id>.<secret>" });
+const body = buildRequest("Klient prosi o zwrot.", { department: choice("Dział?", { returns: "Zwroty", support: "Wsparcie" }) }, {});
+const file = await client.uploadFile({ file: batchInput([{ custom_id: "ticket-1", body }]), filename: "tickets.jsonl" });
+const batch = await client.createBatch({ input_file_id: file.id, metadata: { source: "tickets" } }, { idempotencyKey: "tickets-2026-10-20" });
+// Later:
+const current = await client.getBatch(batch.id);
+if (current.status === "completed" && current.output_file_id) {
+  const lines = parseBatchResults(await client.downloadFile(current.output_file_id, { maxBytes: 256 * 1024 * 1024 }));
+}
+```
+
+| Method | Route |
+|---|---|
+| `uploadFile({file, filename, expires_after?}, {signal?, timeoutMs?})` | `POST /v1/files` |
+| `listFiles({after?, limit?, purpose?, signal?})`, `getFile(id)`, `deleteFile(id)` | `/v1/files[/{id}]` |
+| `downloadFile(id, {signal?, timeoutMs?, maxBytes?})` → `Uint8Array` | `GET /v1/files/{id}/content` |
+| `createBatch({input_file_id, metadata?, output_expires_after?}, {idempotencyKey?, signal?})` | `POST /v1/batches` |
+| `listBatches({after?, limit?, signal?})`, `getBatch(id)`, `cancelBatch(id)` | `/v1/batches[/{id}[/cancel]]` |
+
+Uploads accept `Uint8Array`, `ArrayBuffer`, `Blob` (a browser `File`, or Node's `fs.openAsBlob`) or a
+`ReadableStream<Uint8Array>`. They never fetch URLs or read paths. The form sends `expires_after[...]`
+and `purpose=batch` before the file part, as the server requires. Bytes and Blobs are sent with a
+Content-Length; a stream is sent chunked and needs streaming request bodies (`duplex: "half"`): Node.js,
+or Chromium over HTTP/2. Otherwise pass a Blob. The SDK takes ownership of a stream: it is
+consumed and cancelled on abort, timeout or an early server answer (e.g. 413). The filename (1–255 UTF-8 bytes)
+must not contain control characters or backslashes; it is stored by the server as given.
+
+`downloadFile` returns the raw bytes and never parses JSON. It buffers the body in memory and is bounded by
+`maxResponseBytes` (8 MiB by default). For larger result files, raise `maxBytes` for that call, and
+`timeoutMs` if needed, instead of raising the client-wide limit. `parseBatchResults` turns the bytes into result lines; their
+`response.body` is the native answer (`DecisionResponse` for status 200, the native error body otherwise).
+
+`createBatch` fills `endpoint: "/v1/basal"` and `completion_window: "24h"` (the only accepted values).
+`metadata` keeps insertion order, except integer-like keys, which JavaScript enumerates first.
+`idempotencyKey` (1–128 visible ASCII characters) makes a retried create return the same batch while its
+metadata is retained. The SDK does not retry on its own. Resource ids and cursors are URL-encoded;
+the server answers malformed ids like missing resources (404). `cancelBatch` returns the batch in
+`cancelling`; cancellation ends asynchronously.
+
+`BasalBatchTimeoutError.lastBatch` and `BasalBatchNotReadyError.batch` are non-enumerable, like `BasalHTTPError.body`,
+so default inspection does not log batch metadata. Errors use the same classes as the online API: `BasalHTTPError` with the
+`{"error": {message, type, param, code}}` body and `retryAfter` (429/503), and
+`BasalResponseTooLargeError` above the byte cap. Resource types preserve unknown fields at runtime, and
+status/code enumerations accept future string values.
+
 [Full documentation and publication setup](https://github.com/itsoltech/basal-rs/blob/main/docs/SDK.md).
 
 

package/dist/cjs/batches.cjs

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_BATCH_STATUSES = exports.MAX_BATCH_INPUT_BYTES = exports.MAX_BATCH_REQUESTS = void 0;
+exports.resourcePath = resourcePath;
+exports.listPath = listPath;
+exports.idempotencyHeader = idempotencyHeader;
+exports.createBody = createBody;
+exports.uploadForm = uploadForm;
+exports.batchInput = batchInput;
+exports.parseBatchResults = parseBatchResults;
+exports.serializeBatchRequests = serializeBatchRequests;
+exports.readBatchResultLines = readBatchResultLines;
+const errors_cjs_1 = require("./errors.cjs");
+/** Client-side bounds of `batches.create({requests})`, equal to the server defaults; a server may be configured lower. */
+exports.MAX_BATCH_REQUESTS = 50_000;
+exports.MAX_BATCH_INPUT_BYTES = 200_000_000;
+exports.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. */
+function resourcePath(prefix, id, suffix = "") {
+    if (typeof id !== "string" || !id || id === "." || id === "..")
+        throw new TypeError("resource id must be a nonempty string");
+    return `${prefix}/${encodeURIComponent(id)}${suffix}`;
+}
+function listPath(path, options) {
+    const query = new URLSearchParams();
+    if (options.after !== undefined) {
+        if (typeof options.after !== "string" || !options.after)
+            throw new TypeError("after must be a nonempty id");
+        query.set("after", options.after);
+    }
+    if (options.limit !== undefined) {
+        if (!Number.isSafeInteger(options.limit) || options.limit < 1)
+            throw new TypeError("limit must be a positive integer");
+        query.set("limit", String(options.limit));
+    }
+    if (options.purpose !== undefined) {
+        if (typeof options.purpose !== "string" || !options.purpose)
+            throw new TypeError("purpose must be a nonempty string");
+        query.set("purpose", options.purpose);
+    }
+    const encoded = query.toString();
+    return encoded ? `${path}?${encoded}` : path;
+}
+function idempotencyHeader(key) {
+    if (key === undefined)
+        return {};
+    if (typeof key !== "string" || !/^[!-~]{1,128}$/.test(key)) {
+        throw new TypeError("idempotencyKey must have 1-128 visible ASCII characters");
+    }
+    return { "Idempotency-Key": key };
+}
+function createBody(request) {
+    if (!request || typeof request !== "object" || typeof request.input_file_id !== "string" || !request.input_file_id) {
+        throw new TypeError("input_file_id must be a nonempty string");
+    }
+    // Extra caller fields are forwarded; the server refuses fields it does not know.
+    return { endpoint: "/v1/basal", completion_window: "24h", ...request };
+}
+function expiresFields(expires) {
+    if (expires === undefined)
+        return [];
+    if (!expires || expires.anchor !== "created_at" || !Number.isSafeInteger(expires.seconds) || expires.seconds < 0) {
+        throw new TypeError("expires_after needs anchor created_at and whole seconds");
+    }
+    return [["expires_after[anchor]", expires.anchor], ["expires_after[seconds]", String(expires.seconds)]];
+}
+/** Multipart form of an upload: `expires_after[...]`, then `purpose`, then the file part last (the server reserves the
+ * upload session at the file part, so expiry fields must precede it).
+ */
+function uploadForm(request) {
+    if (!request || typeof request !== "object")
+        throw new TypeError("upload request must be an object");
+    const { file, filename } = request;
+    if (request.purpose !== undefined && request.purpose !== "batch")
+        throw new TypeError("purpose must be batch");
+    // Control characters (CR/LF) would split the part header; a backslash is ambiguous in a quoted filename.
+    if (typeof filename !== "string" || !filename || encoder.encode(filename).length > 255 || /[\p{Cc}\\]/u.test(filename)) {
+        throw new TypeError("filename must have 1-255 UTF-8 bytes without control characters or backslashes");
+    }
+    const random = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(random);
+    const boundary = `basal-${Array.from(random, b => b.toString(16).padStart(2, "0")).join("")}`;
+    let head = "";
+    for (const [name, value] of [...expiresFields(request.expires_after), ["purpose", "batch"]]) {
+        head += `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`;
+    }
+    head += `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename.replaceAll('"', '\\"')}"\r\n`
+        + "Content-Type: application/jsonl\r\n\r\n";
+    const prefix = encoder.encode(head);
+    const suffix = encoder.encode(`\r\n--${boundary}--\r\n`);
+    const contentType = `multipart/form-data; boundary=${boundary}`;
+    if (file instanceof ReadableStream) {
+        if (file.locked)
+            throw new TypeError("upload stream is locked");
+        return { contentType, body: signal => framedStream(prefix, file, suffix, signal) };
+    }
+    let content;
+    if (file instanceof Blob || file instanceof ArrayBuffer)
+        content = file;
+    else if (file instanceof Uint8Array)
+        content = file.buffer instanceof ArrayBuffer ? file : new Uint8Array(file);
+    else
+        throw new TypeError("file must be a Uint8Array, ArrayBuffer, Blob or ReadableStream");
+    return { contentType, body: new Blob([prefix, content, suffix]) };
+}
+/** Streams the multipart prefix, the caller's chunks and the suffix without buffering the file.
+ * Fetch implementations may keep pulling a request body after abort, so `signal` cancels the source here.
+ */
+function framedStream(prefix, source, suffix, signal) {
+    let reader;
+    let stage = "prefix";
+    const stop = (reason) => {
+        signal.removeEventListener("abort", onAbort);
+        if (stage === "finished" || stage === "stopped")
+            return Promise.resolve();
+        stage = "stopped";
+        return (reader ? reader.cancel(reason) : source.cancel(reason)).catch(() => { });
+    };
+    const onAbort = () => { void stop(signal.reason); };
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    return new ReadableStream({
+        async pull(controller) {
+            if (stage === "stopped")
+                throw signal.reason ?? new Error("upload stopped");
+            if (stage === "prefix") {
+                stage = "file";
+                controller.enqueue(prefix);
+                return;
+            }
+            if (stage === "finished") {
+                controller.close();
+                return;
+            }
+            reader ??= source.getReader();
+            const { done, value } = await reader.read();
+            // A read cancelled by `stop` ends as done; it must not be framed as a complete file.
+            if (stage !== "file")
+                throw signal.reason ?? new Error("upload stopped");
+            if (!done) {
+                if (!(value instanceof Uint8Array)) {
+                    const error = new TypeError("upload stream chunks must be Uint8Array");
+                    await stop(error);
+                    throw error;
+                }
+                controller.enqueue(value);
+                return;
+            }
+            reader.releaseLock();
+            reader = undefined;
+            stage = "finished";
+            signal.removeEventListener("abort", onAbort);
+            controller.enqueue(suffix);
+        },
+        cancel(reason) { return stop(reason); },
+    });
+}
+/** JSONL input file of native records (`method` POST and `url` /v1/basal are filled in). Never sends anything. */
+function batchInput(lines) {
+    const out = [];
+    for (const line of lines) {
+        if (!line || typeof line.custom_id !== "string" || !line.custom_id || !line.body || typeof line.body !== "object") {
+            throw new TypeError("each batch line needs a custom_id and a native request body");
+        }
+        out.push(JSON.stringify({ custom_id: line.custom_id, method: line.method ?? "POST", url: line.url ?? "/v1/basal", body: line.body }));
+    }
+    if (!out.length)
+        throw new TypeError("a batch input needs at least one line");
+    return encoder.encode(out.join("\n") + "\n");
+}
+/** Parse downloaded result bytes (output or error file) into lines. Never fetches anything. */
+function parseBatchResults(content) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+    }
+    catch (cause) {
+        throw new errors_cjs_1.BasalProtocolError("Batch result file is not UTF-8", { cause });
+    }
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines.map((line, index) => {
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (cause) {
+            throw new errors_cjs_1.BasalProtocolError(`Batch result line ${index + 1} is not JSON`, { cause });
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new errors_cjs_1.BasalProtocolError(`Batch result line ${index + 1} is not a JSON object`);
+        }
+        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.
+ */
+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 >= exports.MAX_BATCH_REQUESTS)
+            throw new TypeError(`requests must have at most ${exports.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 > exports.MAX_BATCH_INPUT_BYTES)
+            throw new TypeError(`requests exceed ${exports.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.
+ */
+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 errors_cjs_1.BasalBatchResultError(fileId, number, "is not UTF-8", { cause });
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (cause) {
+            throw new errors_cjs_1.BasalBatchResultError(fileId, number, "is not JSON", { cause });
+        }
+        const problem = envelopeProblem(value);
+        if (problem)
+            throw new errors_cjs_1.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/cjs/batches.d.cts

@@ -0,0 +1,214 @@
+import type { DecisionRequest, JsonValue } from "./index.cjs";
+/** Batch and Files wire types (`contracts/batches/openapi.json`). Times are Unix seconds.
+ * Unknown response fields are preserved at runtime; `(string & {})` keeps enums open to future server values.
+ */
+export type FilePurpose = "batch" | "batch_output";
+export interface FileObject {
+    id: string;
+    object: "file";
+    bytes: number;
+    created_at: number;
+    expires_at: number | null;
+    /** As uploaded, or `batch_<id>_output.jsonl` / `batch_<id>_error.jsonl` for results; never a server path. */
+    filename: string;
+    purpose: FilePurpose | (string & {});
+    /** Always `processed` (OpenAI compatibility). */
+    status: "processed" | (string & {});
+    status_details: string | null;
+}
+export interface DeletedFile {
+    id: string;
+    object: "file";
+    deleted: boolean;
+}
+export interface ListPage<T> {
+    object: "list";
+    data: T[];
+    first_id: string | null;
+    last_id: string | null;
+    has_more: boolean;
+}
+export type FileList = ListPage<FileObject>;
+export type BatchList = ListPage<Batch>;
+/** At most 16 pairs, keys of 1–64 and values of up to 512 characters, in insertion order (checked by the server).
+ * JavaScript enumerates integer-like keys first; use textual keys when order matters.
+ */
+export type Metadata = Record<string, string>;
+export interface ExpiresAfter {
+    anchor: "created_at";
+    seconds: number;
+}
+export type BatchStatus = "validating" | "failed" | "in_progress" | "finalizing" | "completed" | "expired" | "cancelling" | "cancelled";
+export type BatchErrorCode = "empty_file" | "empty_line" | "invalid_json_line" | "line_too_large" | "too_many_records" | "invalid_custom_id" | "duplicate_custom_id" | "invalid_method" | "invalid_url" | "stream_unsupported" | "invalid_body" | "model_not_found" | "mixed_models" | "budget_exceeded" | "host_budget_exceeded" | "unbounded_feature" | "input_changed" | "batch_expired" | "errors_truncated";
+export interface RequestCounts {
+    total: number;
+    completed: number;
+    failed: number;
+}
+export interface BatchErrorEntry {
+    code: BatchErrorCode | (string & {});
+    message: string;
+    param: string | null;
+    line: number | null;
+}
+export interface BatchErrors {
+    object: "list";
+    data: BatchErrorEntry[];
+}
+export interface Batch {
+    id: string;
+    object: "batch";
+    endpoint: "/v1/basal" | (string & {});
+    model: string | null;
+    errors: BatchErrors | null;
+    input_file_id: string;
+    completion_window: "24h" | (string & {});
+    status: BatchStatus | (string & {});
+    output_file_id: string | null;
+    error_file_id: string | null;
+    created_at: number;
+    in_progress_at: number | null;
+    /** End of the 24h inference window; export may finish later. */
+    expires_at: number;
+    finalizing_at: number | null;
+    completed_at: number | null;
+    failed_at: number | null;
+    expired_at: number | null;
+    cancelling_at: number | null;
+    cancelled_at: number | null;
+    request_counts: RequestCounts;
+    metadata: Metadata | null;
+}
+/** `POST /v1/batches` body. `endpoint` and `completion_window` default to their only accepted values. */
+export interface CreateBatchRequest {
+    input_file_id: string;
+    endpoint?: "/v1/basal";
+    completion_window?: "24h";
+    metadata?: Metadata | null;
+    /** Lifetime of each result file, anchored at its creation. */
+    output_expires_after?: ExpiresAfter | null;
+}
+/** One line of an input file; `body` is the native `/v1/basal` request (see `buildRequest`). */
+export interface BatchInputLine {
+    custom_id: string;
+    method?: "POST";
+    url?: "/v1/basal";
+    body: DecisionRequest;
+}
+/** One line of a result file. `response.body` is the native answer: a `DecisionResponse` for status 200, otherwise
+ * the native error body. `error` is set when the record has no response (e.g. `batch_expired`, `result_too_large`).
+ */
+export interface BatchResultLine {
+    id: string;
+    custom_id: string;
+    response: {
+        status_code: number;
+        request_id: string;
+        body: {
+            [key: string]: JsonValue;
+        };
+    } | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** Common options of Batch and Files calls. */
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+/** Upload and download options; `timeoutMs` replaces the client deadline for this call only. */
+export interface TransferOptions extends RequestOptions {
+    timeoutMs?: number;
+}
+export interface DownloadOptions extends TransferOptions {
+    /** Byte cap of this download; defaults to the client's `maxResponseBytes`. The body is buffered in memory. */
+    maxBytes?: number;
+}
+export interface CreateBatchOptions extends RequestOptions {
+    /** 1–128 visible ASCII characters; a replay with the same request data returns the existing batch. */
+    idempotencyKey?: string;
+}
+export interface ListOptions extends RequestOptions {
+    after?: string;
+    limit?: number;
+}
+export interface ListFilesOptions extends ListOptions {
+    purpose?: FilePurpose;
+}
+/** Caller-owned upload content. The SDK never fetches URLs or reads paths; a stream is consumed and locked. */
+export type UploadContent = Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+export interface UploadFileRequest {
+    file: UploadContent;
+    /** 1–255 UTF-8 bytes without control characters or backslashes; stored as given, never used as a path. */
+    filename: string;
+    purpose?: "batch";
+    /** 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;
+export declare function idempotencyHeader(key: string | undefined): Record<string, string>;
+export declare function createBody(request: CreateBatchRequest): CreateBatchRequest;
+/** A multipart body; a stream body is created per request and stops its source when `signal` aborts. */
+export interface Multipart {
+    contentType: string;
+    body: Blob | ((signal: AbortSignal) => ReadableStream<Uint8Array>);
+}
+/** Multipart form of an upload: `expires_after[...]`, then `purpose`, then the file part last (the server reserves the
+ * upload session at the file part, so expiry fields must precede it).
+ */
+export declare function uploadForm(request: UploadFileRequest): Multipart;
+/** JSONL input file of native records (`method` POST and `url` /v1/basal are filled in). Never sends anything. */
+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>;