@itsoltech/basal-client 0.3.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

@@ -0,0 +1,214 @@
+import type { DecisionRequest, JsonValue } from "./index.js";
+/** 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>;