@itsoltech/basal-client 0.3.0 → 0.5.0

package/dist/esm/batches.js

@@ -0,0 +1,300 @@
+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 = "") {
+    if (typeof id !== "string" || !id || id === "." || id === "..")
+        throw new TypeError("resource id must be a nonempty string");
+    return `${prefix}/${encodeURIComponent(id)}${suffix}`;
+}
+export 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;
+}
+export 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 };
+}
+export 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).
+ */
+export 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. */
+export 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. */
+export function parseBatchResults(content) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+    }
+    catch (cause) {
+        throw new 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 BasalProtocolError(`Batch result line ${index + 1} is not JSON`, { cause });
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new 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.
+ */
+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

@@ -0,0 +1,59 @@
+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. */
+export declare class BasalHTTPError extends BasalError {
+    readonly statusCode: number;
+    readonly body: unknown;
+    readonly retryAfter: string | null;
+    constructor(statusCode: number, body: unknown, retryAfter: string | null);
+}
+export declare class BasalTransportError extends BasalError {
+}
+export declare class BasalProtocolError extends BasalError {
+}
+export declare class BasalResponseTooLargeError extends BasalError {
+}
+/** `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

@@ -0,0 +1,85 @@
+export class BasalError extends Error {
+}
+/** Non-2xx response. Server body and Retry-After are available without logging them. */
+export class BasalHTTPError extends BasalError {
+    statusCode;
+    body;
+    retryAfter;
+    constructor(statusCode, body, retryAfter) {
+        super(`Basal HTTP ${statusCode}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.retryAfter = retryAfter;
+        this.name = "BasalHTTPError";
+        // Node's default inspection and JSON.stringify must not print reflected state or credentials.
+        Object.defineProperty(this, "body", { enumerable: false });
+    }
+}
+export class BasalTransportError extends BasalError {
+}
+export class BasalProtocolError extends BasalError {
+}
+export class BasalResponseTooLargeError extends BasalError {
+}
+/** `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,7 +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, 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[] | {
@@ -164,21 +170,6 @@ export interface ModelMetadata {
 export interface ModelsResponse {
     models: ModelMetadata[];
 }
-export declare class BasalError extends Error {
-}
-/** Non-2xx response. Server body and Retry-After are available without logging them. */
-export declare class BasalHTTPError extends BasalError {
-    readonly statusCode: number;
-    readonly body: unknown;
-    readonly retryAfter: string | null;
-    constructor(statusCode: number, body: unknown, retryAfter: string | null);
-}
-export declare class BasalTransportError extends BasalError {
-}
-export declare class BasalProtocolError extends BasalError {
-}
-export declare class BasalResponseTooLargeError extends BasalError {
-}
 /** Web Fetch input accepted by browsers and server runtimes. */
 export type RequestInput = string | URL | Request;
 /** A transport adapter must honor signal/redirect and return a standard Web Response. */
@@ -200,9 +191,26 @@ 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;
     decide(request: DecisionRequest, signal?: AbortSignal): Promise<DecisionResponse>;
     decide<const Q extends QuestionSet>(state: JsonValue, questions: Q, options?: DecisionOptions): Promise<TypedDecisionResponse<Q>>;
     models(signal?: AbortSignal): Promise<ModelsResponse>;
+    /** Upload a JSONL input file (`purpose=batch`) from caller-owned bytes, a Blob or a stream; never fetches URLs. */
+    uploadFile(request: UploadFileRequest, options?: TransferOptions): Promise<FileObject>;
+    listFiles(options?: ListFilesOptions): Promise<FileList>;
+    getFile(fileId: string, options?: RequestOptions): Promise<FileObject>;
+    deleteFile(fileId: string, options?: RequestOptions): Promise<DeletedFile>;
+    /** Raw file bytes (JSONL), buffered up to `maxBytes` (default `maxResponseBytes`); never JSON-parsed. */
+    downloadFile(fileId: string, options?: DownloadOptions): Promise<Uint8Array>;
+    createBatch(request: CreateBatchRequest, options?: CreateBatchOptions): Promise<Batch>;
+    listBatches(options?: ListOptions): Promise<BatchList>;
+    getBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
+    /** Request cancellation; the batch moves to `cancelling` and later `cancelled`. Does not wait. */
+    cancelBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
 }