@itsoltech/basal-client 0.4.0 → 0.5.0

package/README.md

@@ -77,10 +77,83 @@ retains the native JSON without those defaults. The one-argument raw `decide(req
 
 ## 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. It never polls:
-call `getBatch` at an interval your application chooses and stop on `completed`, `failed`, `expired` or `cancelled`.
+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";
@@ -124,7 +197,8 @@ metadata is retained. The SDK does not retry on its own. Resource ids and cursor
 the server answers malformed ids like missing resources (404). `cancelBatch` returns the batch in
 `cancelling`; cancellation ends asynchronously.
 
-Errors use the same classes as the online API: `BasalHTTPError` with the
+`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.

package/dist/cjs/batches.cjs

@@ -1,5 +1,6 @@
 "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;
@@ -7,7 +8,13 @@ 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 = "") {
@@ -189,3 +196,117 @@ 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.
+ */
+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

@@ -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/cjs/errors.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BasalResponseTooLargeError = exports.BasalProtocolError = exports.BasalTransportError = exports.BasalHTTPError = exports.BasalError = void 0;
+exports.BasalBatchResultError = exports.BasalBatchNotReadyError = exports.BasalBatchTimeoutError = exports.BasalBatchSubmissionError = exports.BasalResponseTooLargeError = exports.BasalProtocolError = exports.BasalTransportError = exports.BasalHTTPError = exports.BasalError = void 0;
 class BasalError extends Error {
 }
 exports.BasalError = BasalError;
@@ -29,3 +29,69 @@ exports.BasalProtocolError = BasalProtocolError;
 class BasalResponseTooLargeError extends BasalError {
 }
 exports.BasalResponseTooLargeError = BasalResponseTooLargeError;
+/** `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`.
+ */
+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;
+    }
+}
+exports.BasalBatchSubmissionError = BasalBatchSubmissionError;
+/** `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`.
+ */
+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 });
+    }
+}
+exports.BasalBatchTimeoutError = BasalBatchTimeoutError;
+/** `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.
+ */
+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 });
+    }
+}
+exports.BasalBatchNotReadyError = BasalBatchNotReadyError;
+/** 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.
+ */
+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";
+    }
+}
+exports.BasalBatchResultError = BasalBatchResultError;

package/dist/cjs/errors.d.cts

@@ -1,3 +1,4 @@
+import type { Batch, FileObject } from "./batches.cjs";
 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/cjs/index.cjs

@@ -14,17 +14,24 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BasalClient = exports.parseBatchResults = exports.batchInput = void 0;
+exports.BasalClient = exports.Files = exports.Batches = exports.TERMINAL_BATCH_STATUSES = exports.parseBatchResults = exports.MAX_BATCH_REQUESTS = exports.MAX_BATCH_INPUT_BYTES = exports.batchInput = void 0;
 const questions_cjs_1 = require("./questions.cjs");
 const errors_cjs_1 = require("./errors.cjs");
 const batches_cjs_1 = require("./batches.cjs");
+const resources_cjs_1 = require("./resources.cjs");
 __exportStar(require("./questions.cjs"), exports);
 __exportStar(require("./media.cjs"), exports);
 __exportStar(require("./tasks.cjs"), exports);
 __exportStar(require("./errors.cjs"), exports);
 var batches_cjs_2 = require("./batches.cjs");
 Object.defineProperty(exports, "batchInput", { enumerable: true, get: function () { return batches_cjs_2.batchInput; } });
+Object.defineProperty(exports, "MAX_BATCH_INPUT_BYTES", { enumerable: true, get: function () { return batches_cjs_2.MAX_BATCH_INPUT_BYTES; } });
+Object.defineProperty(exports, "MAX_BATCH_REQUESTS", { enumerable: true, get: function () { return batches_cjs_2.MAX_BATCH_REQUESTS; } });
 Object.defineProperty(exports, "parseBatchResults", { enumerable: true, get: function () { return batches_cjs_2.parseBatchResults; } });
+Object.defineProperty(exports, "TERMINAL_BATCH_STATUSES", { enumerable: true, get: function () { return batches_cjs_2.TERMINAL_BATCH_STATUSES; } });
+var resources_cjs_2 = require("./resources.cjs");
+Object.defineProperty(exports, "Batches", { enumerable: true, get: function () { return resources_cjs_2.Batches; } });
+Object.defineProperty(exports, "Files", { enumerable: true, get: function () { return resources_cjs_2.Files; } });
 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();
@@ -88,6 +95,10 @@ 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("#")) {
@@ -112,6 +123,8 @@ class BasalClient {
                 throw new TypeError("apiKey must be a nonempty, single-line token");
             this.headers.Authorization = `Bearer ${options.apiKey}`;
         }
+        this.files = new resources_cjs_1.Files(this);
+        this.batches = new resources_cjs_1.Batches(this);
     }
     request(method, path, body, signal) {
         return this.call({ method, path, json: body, signal });

package/dist/cjs/index.d.cts

@@ -1,11 +1,13 @@
 import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.cjs";
 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.cjs";
+import { Batches, Files } from "./resources.cjs";
 export * from "./questions.cjs";
 export * from "./media.cjs";
 export * from "./tasks.cjs";
 export * from "./errors.cjs";
-export { batchInput, parseBatchResults } from "./batches.cjs";
-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.cjs";
+export { batchInput, MAX_BATCH_INPUT_BYTES, MAX_BATCH_REQUESTS, parseBatchResults, TERMINAL_BATCH_STATUSES, } from "./batches.cjs";
+export { Batches, Files } from "./resources.cjs";
+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.cjs";
 import type { TaskAnswer } from "./tasks.cjs";
 /** 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;