@boxrouter/sdk 0.0.0-stage → 0.12.190

package/dist/api-error.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_KIND = exports.RequestError = exports.APIError = void 0;
+exports.reportUrl = reportUrl;
+exports.unconfirmed = unconfirmed;
+exports.markAfterSend = markAfterSend;
+exports.requestFailure = requestFailure;
+exports.foreign = foreign;
+exports.invalidResponse = invalidResponse;
+const addresses_1 = require("./addresses");
+const SUPPORT_URL = 'https://boxrouter.ai/support';
+function reportInstruction(url) {
+    return ` If this keeps happening, report it at ${url} or email ${addresses_1.SUPPORT}.`;
+}
+/** Where to report an unexpected failure, with the request ID prefilled when there is one. */
+function reportUrl(requestId) {
+    return requestId ? `${SUPPORT_URL}?request=${encodeURIComponent(requestId)}` : SUPPORT_URL;
+}
+const MAX_RESPONSE_SCHEMA_DIAGNOSTICS = 8;
+const SAFE_SCHEMA_KEYWORD = /^[A-Za-z][A-Za-z0-9_-]{0,39}$/;
+const SAFE_SCHEMA_PATH = /^#(?:\/[A-Za-z0-9_$~.-]+)*$/;
+function safeInstancePath(value) {
+    if (typeof value !== 'string' || value.length > 1024)
+        return undefined;
+    if (value === '')
+        return '(root)';
+    if (!value.startsWith('/'))
+        return undefined;
+    // A numeric segment can be a user-supplied object key as well as an array index.
+    // Keep the path depth, but never expose any response-derived key or index.
+    const parts = value.slice(1).split('/').slice(0, 16).map(() => '[field]');
+    return `/${parts.join('/')}`;
+}
+function safeResponseSchemaDiagnostics(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const diagnostics = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const issue = item;
+        const keyword = issue.keyword;
+        const schemaPath = issue.schemaPath;
+        const instancePath = safeInstancePath(issue.instancePath);
+        if (typeof keyword !== 'string' || !SAFE_SCHEMA_KEYWORD.test(keyword) ||
+            typeof schemaPath !== 'string' || schemaPath.length > 256 || !SAFE_SCHEMA_PATH.test(schemaPath) ||
+            instancePath === undefined)
+            continue;
+        const key = `${keyword}\n${instancePath}\n${schemaPath}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        diagnostics.push(Object.freeze({ keyword, instancePath, schemaPath }));
+        if (diagnostics.length >= MAX_RESPONSE_SCHEMA_DIAGNOSTICS)
+            break;
+    }
+    return diagnostics.length ? Object.freeze(diagnostics) : undefined;
+}
+/**
+ * An API failure with an explanation and identifiers for reconciliation. An unexpected failure (a 5xx, an
+ * uncertain outcome or a reply this SDK cannot read) says where to report it; a failure the caller can fix, such
+ * as a bad key, does not. `unexpected` overrides that rule for a reply that is not BoxRouter's at all.
+ */
+class APIError extends Error {
+    response;
+    request;
+    status;
+    error;
+    /** The documented codes complete in an editor; a code newer than this SDK is still a string. */
+    code;
+    requestId;
+    operationId;
+    sandboxId;
+    outcome;
+    /** What to do next, when the API names a fix. */
+    fix;
+    /** What to do about sending the call again: `safe`, `after_fix`, `check_outcome` or `never` (a newer API may add values). */
+    retry;
+    /** How long to wait before a `retry: "safe"` resend; undefined when the API names no wait. */
+    retryAfterSeconds;
+    /** The documentation page for this code (`.../docs/error-codes#<code>`); undefined when the API names none. */
+    docUrl;
+    /** Code-specific context for programs; fields this SDK does not know are kept. */
+    details;
+    /** Safe schema paths only; never includes response values or validator params. */
+    schemaDiagnostics;
+    idempotencyKey;
+    /** Where to report this failure; undefined for a failure the caller can fix. */
+    reportUrl;
+    constructor(payload, response, request, message, idempotencyKey, unexpected, schemaDiagnostics) {
+        const envelope = payload !== null && typeof payload === 'object' && 'error' in payload
+            ? payload.error : undefined;
+        const fields = envelope !== null && typeof envelope === 'object'
+            ? envelope : {};
+        const text = (name) => typeof fields[name] === 'string' ? fields[name] : undefined;
+        const code = text('code');
+        const requestId = text('request_id') ?? response.headers.get('x-request-id') ?? undefined;
+        const fix = text('fix');
+        const explanation = message ?? text('message') ?? 'BoxRouter request failed. Check the current state before retrying.';
+        const description = message === undefined && fix ? `${explanation} Fix: ${fix}` : explanation;
+        const outcome = text('outcome');
+        // A provider's own 4xx behind our 5xx (a refused credential) is the caller's to fix.
+        const native = fields.native_status;
+        const refused = typeof native === 'number' && native >= 400 && native < 500;
+        const report = (unexpected ?? (outcome === 'unknown' || outcome === 'partial' || (response.status >= 500 && !refused)))
+            ? reportUrl(requestId) : undefined;
+        super(`${description} (HTTP ${response.status}${code && message === undefined ? `, ${code}` : ''})${requestId ? ` [request ${requestId}]` : ''}${report ? reportInstruction(report) : ''}`);
+        this.response = response;
+        this.request = request;
+        this.reportUrl = report;
+        this.name = 'APIError';
+        this.error = { ...fields, message: description,
+            ...(requestId ? { request_id: requestId } : {}),
+        };
+        this.status = response.status;
+        this.code = code;
+        this.requestId = requestId;
+        this.operationId = text('operation_id');
+        this.sandboxId = text('sandbox_id');
+        this.outcome = outcome;
+        this.fix = fix;
+        const retry = text('retry');
+        this.retry = retry;
+        const after = fields.retry_after_seconds;
+        this.retryAfterSeconds = typeof after === 'number' && Number.isFinite(after) ? after : undefined;
+        this.docUrl = text('doc_url');
+        const details = fields.details;
+        this.details = details !== null && typeof details === 'object' && !Array.isArray(details)
+            ? details : {};
+        this.schemaDiagnostics = safeResponseSchemaDiagnostics(schemaDiagnostics);
+        this.idempotencyKey = request?.headers.get('idempotency-key') ?? idempotencyKey;
+    }
+}
+exports.APIError = APIError;
+const READS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** Say what a failed call means: a read changed nothing, a mutation may have happened. */
+function unconfirmed(request, failure) {
+    return READS.has(request.method.toUpperCase())
+        ? `${failure}; the read failed and nothing was changed. It can be retried.`
+        : `${failure}; the operation result is unconfirmed. Inspect the operation before retrying.`;
+}
+/** Node's system error codes for a connection that was never established. */
+const NOT_CONNECTED = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH',
+    'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT']);
+/** Failures of a replay: the first attempt had been sent, so the server may have recorded the request. */
+const AFTER_SEND = new WeakSet();
+/** Mark a failure that followed a send, so its message does not claim the request was never sent. */
+function markAfterSend(error) {
+    if (error !== null && typeof error === 'object')
+        AFTER_SEND.add(error);
+    return error;
+}
+function lostAfterSend(cause, request) {
+    if (cause === null || typeof cause !== 'object' || !AFTER_SEND.has(cause))
+        return undefined;
+    const read = READS.has(request.method.toUpperCase());
+    // A read that failed in some other way keeps the generic message, which already says it can be retried.
+    if (read && unreachable(cause, request) === undefined)
+        return undefined;
+    const advice = read
+        ? 'nothing was changed; it can be retried.'
+        : 'the request may have been received. Read the operation or the sandbox before retrying, ' +
+            'and resend with the same Idempotency-Key.';
+    return `The connection to BoxRouter at ${new URL(request.url).origin} was lost after the request was sent; ${advice}`;
+}
+/** The `could not reach` message when fetch failed before a connection existed, else undefined. */
+function unreachable(cause, request) {
+    let code;
+    try {
+        const inner = cause !== null && typeof cause === 'object' && 'cause' in cause ? cause.cause : undefined;
+        code = inner !== null && typeof inner === 'object' && 'code' in inner ? String(inner.code) : undefined;
+    }
+    catch {
+        return undefined; // A cause whose properties throw is not diagnosed; the original stays the cause.
+    }
+    if (code === undefined || !NOT_CONNECTED.has(code))
+        return undefined;
+    return `Could not reach BoxRouter at ${new URL(request.url).origin} (${code}). ` +
+        'The request was not sent; check BOXROUTER_BASE_URL and your network.';
+}
+function isBoxRouterHost(request) {
+    try {
+        const hostname = new URL(request.url).hostname.toLowerCase().replace(/\.$/, '');
+        return hostname === 'boxrouter.ai' || hostname.endsWith('.boxrouter.ai');
+    }
+    catch {
+        return false;
+    }
+}
+function isAbort(cause, depth = 0) {
+    if (depth > 4 || cause === null || typeof cause !== 'object')
+        return false;
+    try {
+        if ('name' in cause && cause.name === 'AbortError')
+            return true;
+        return 'cause' in cause && isAbort(cause.cause, depth + 1);
+    }
+    catch {
+        return false;
+    }
+}
+/** A request failed locally; a mutation's remote outcome may still be unknown. */
+class RequestError extends Error {
+    request;
+    response;
+    idempotencyKey;
+    requestId;
+    /** Where to report a persistent transport failure against BoxRouter. */
+    reportUrl;
+    constructor(cause, request, response) {
+        const report = isBoxRouterHost(request) && !isAbort(cause)
+            ? reportUrl(response?.headers.get('x-request-id') ?? undefined) : undefined;
+        const message = lostAfterSend(cause, request) ?? unreachable(cause, request) ??
+            unconfirmed(request, 'Request failed');
+        super(`${message}${report ? reportInstruction(report) : ''}`, { cause });
+        this.request = request;
+        this.response = response;
+        this.name = 'RequestError';
+        this.idempotencyKey = request.headers.get('idempotency-key') ?? undefined;
+        this.requestId = response?.headers.get('x-request-id') ?? undefined;
+        this.reportUrl = report;
+    }
+}
+exports.RequestError = RequestError;
+function requestFailure(error, request, response) {
+    return !request || error instanceof APIError || error instanceof RequestError
+        ? error : new RequestError(error, request, response);
+}
+/** Where no kind of record matched, a newer API may be the cause; say what then fixes it. */
+exports.UNKNOWN_KIND = 'It may hold a kind of record this SDK does not know; if it keeps failing, a newer SDK is needed.';
+/** A response BoxRouter did not send: every BoxRouter response carries a request ID. */
+function foreign(response, request) {
+    if (response.headers.get('x-request-id'))
+        return undefined;
+    return `This is not a BoxRouter API response: ${new URL(request.url).origin} answered HTTP ${response.status} ` +
+        'without a request ID. Check that BOXROUTER_BASE_URL points at the BoxRouter API (it ends in /api/v1).';
+}
+function invalidResponse(response, request, payload, kind = false, schemaDiagnostics) {
+    const other = foreign(response, request);
+    if (other !== undefined)
+        return new APIError({ error: {} }, response, request, other, undefined, false);
+    const fields = payload !== null && typeof payload === 'object' && 'error' in payload &&
+        payload.error !== null && typeof payload.error === 'object' ? payload.error : {};
+    const body = payload !== null && typeof payload === 'object' ? payload : {};
+    const identifier = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value)
+        ? value : undefined;
+    const operationId = identifier(fields.operation_id) ?? identifier(body.operation_id);
+    const sandboxId = identifier(fields.sandbox_id) ?? identifier(body.sandbox_id) ??
+        (request.method.toUpperCase() === 'POST' && new URL(request.url).pathname.replace(/\/$/, '').endsWith('/sandboxes')
+            ? identifier(body.id) : undefined);
+    const mayHaveSucceeded = response.ok && !READS.has(request.method.toUpperCase());
+    const guidance = mayHaveSucceeded
+        ? 'Invalid API response; the request may have succeeded. Check the operation or sandbox before retrying. ' +
+            'Find a sandbox with sandboxes.get(id), or list sandboxes with api.sandboxes.list().' +
+            (operationId ? ` [operation ${operationId}]` : '') + (sandboxId ? ` [sandbox ${sandboxId}]` : '')
+        : unconfirmed(request, 'Invalid API response');
+    return new APIError({ error: {
+            ...fields,
+            ...(operationId ? { operation_id: operationId } : {}),
+            ...(sandboxId ? { sandbox_id: sandboxId } : {}),
+            message: kind ? `${guidance} ${exports.UNKNOWN_KIND}` : guidance,
+        } }, response, request, undefined, undefined, true, schemaDiagnostics);
+}

package/dist/boxrouter.d.ts

@@ -0,0 +1,68 @@
+import { BoxRouterApi } from './sdk.gen';
+import { SandboxResources } from './sandboxes';
+import { RoutingResources } from './routing';
+import { ImageResources } from './images';
+import { SpendLimitResources } from './spend-limits';
+import { OperationResources } from './operations';
+import { VolumeResources } from './volumes';
+export interface BoxRouterOptions {
+    /** Defaults to the BOXROUTER_API_KEY environment variable. */
+    apiKey?: string;
+    /** Defaults to the BOXROUTER_BASE_URL environment variable, then to the hosted API. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Optional product token(s) appended to the SDK identification. */
+    userAgentSuffix?: string;
+    /**
+     * How often a call is resent when the API marks the failure `retry: "safe"` (nothing ran and waiting
+     * helps), with the same idempotency key. 0 turns resending off.
+     */
+    maxRetries?: number;
+}
+type Configuration = Required<Pick<BoxRouterOptions, 'apiKey' | 'baseUrl'>> & Pick<BoxRouterOptions, 'fetch' | 'userAgentSuffix'> & {
+    identification: string;
+    maxRetries: number;
+};
+type ConnectorSocket = {
+    once(event: 'connect' | 'secureConnect', listener: () => void): ConnectorSocket;
+};
+type ConnectorOptions = {
+    hostname: string;
+    protocol: string;
+};
+type ConnectorCallback = (error: Error | null, socket: ConnectorSocket | null) => void;
+type Connector = (options: ConnectorOptions, callback: ConnectorCallback) => ConnectorSocket;
+/** Pool options shared by the plain and the timing-instrumented connector. */
+export declare function pooledAgentOptions(connect: Connector): {
+    connections: number;
+    keepAliveTimeout: number;
+    connect: Connector;
+};
+/** The options a client was created with, for the opt-in native surface; never serialized. */
+export declare function clientOptions(client: BoxRouter): Configuration;
+/** Sent with a key made for this request; never with a key that may have been sent before. */
+export declare const FIRST_SEND_HEADER = "X-BoxRouter-First-Send";
+/** Mutations without a caller key get a fresh one, so a lost response can be reconciled.
+ * A fresh key is marked as a first send: Cloud may then dispatch the operation beside its record. */
+export declare function idempotencyKeys(operations: Set<string>): (request: Request, options: {
+    url: string;
+}) => Request;
+/** Each instance owns its BoxRouter authentication and HTTP configuration. */
+export declare class BoxRouter {
+    readonly api: BoxRouterApi;
+    readonly usage: Pick<BoxRouterApi['usage'], 'list' | 'exportCsv'>;
+    readonly images: ImageResources;
+    readonly spendLimits: SpendLimitResources;
+    readonly operations: OperationResources;
+    readonly sandboxes: SandboxResources;
+    readonly volumes: VolumeResources;
+    readonly routing: RoutingResources;
+    /** Close this client's owned HTTP connection pool. Borrowed views and custom fetches are caller-owned. */
+    close(): Promise<void>;
+    /** Release this client's owned HTTP connection pool when used with `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Clone current HTTP configuration/interceptors without changing the owner. */
+    withUserAgentSuffix(suffix: string): BoxRouter;
+    constructor(options?: BoxRouterOptions);
+}
+export {};

package/dist/boxrouter.js

@@ -0,0 +1,291 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoxRouter = exports.FIRST_SEND_HEADER = void 0;
+exports.pooledAgentOptions = pooledAgentOptions;
+exports.clientOptions = clientOptions;
+exports.idempotencyKeys = idempotencyKeys;
+const api_error_1 = require("./api-error");
+const workflow_policy_gen_1 = require("./workflow-policy.gen");
+const user_agent_1 = require("./user-agent");
+const client_1 = require("./client");
+const idempotency_gen_1 = require("./idempotency.gen");
+const retry_1 = require("./retry");
+const sdk_gen_1 = require("./sdk.gen");
+const sandboxes_1 = require("./sandboxes");
+const routing_1 = require("./routing");
+const images_1 = require("./images");
+const spend_limits_1 = require("./spend-limits");
+const operations_1 = require("./operations");
+const volumes_1 = require("./volumes");
+const data_origin_1 = require("./data-origin");
+const server_timing_1 = require("./server-timing");
+const transports = new WeakMap();
+const configured = new WeakMap();
+const dataOrigins = new WeakMap();
+const closeTransport = new WeakMap();
+const noOwnedTransport = Promise.resolve();
+const undiciSpecifier = 'undici';
+const IDLE_SOCKET_TIMEOUT_MS = 120_000;
+const POOL_CONNECTIONS = 64;
+const TCP_KEEPALIVE_INITIAL_DELAY_MS = 15_000;
+const SAFE_RETRY_METHODS = new Set(['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE']);
+const STALE_SOCKET_CODES = new Set(['ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET']);
+function hasStaleSocketCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth++) {
+        const code = current.code;
+        if (typeof code === 'string' && STALE_SOCKET_CODES.has(code))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** Pool options shared by the plain and the timing-instrumented connector. */
+function pooledAgentOptions(connect) {
+    return { connections: POOL_CONNECTIONS, keepAliveTimeout: IDLE_SOCKET_TIMEOUT_MS, connect };
+}
+/** Node's fetch needs an explicit, client-owned dispatcher to retain HTTP connections. */
+function nodePooledFetch(instrumentClientTiming = false) {
+    const process = globalThis.process;
+    if (!process?.versions?.node)
+        return undefined;
+    const fetch = globalThis.fetch;
+    let pool;
+    let closing;
+    let closed = false;
+    let firstRequest = true;
+    let pendingDispatches = 0;
+    let dispatchesDrained;
+    let resolveDispatchesDrained;
+    return {
+        fetch: (input, init) => {
+            if (closed)
+                return Promise.reject(new TypeError('BoxRouter client is closed'));
+            if (pendingDispatches++ === 0) {
+                dispatchesDrained = new Promise(resolve => { resolveDispatchesDrained = resolve; });
+            }
+            pool ??= import(/* @vite-ignore */ undiciSpecifier).then(module => {
+                const { Agent, buildConnector } = module;
+                if (!instrumentClientTiming) {
+                    const connect = buildConnector({ keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY_MS });
+                    return new Agent(pooledAgentOptions(connect));
+                }
+                return import('node:dns').then(dns => {
+                    const connector = buildConnector({ keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY_MS, lookup(hostname, options, callback) {
+                            const started = globalThis.performance?.now();
+                            const recordDns = (0, server_timing_1.connectionSegmentRecorder)('dnsMs');
+                            dns.lookup(hostname, options, (error, address, family) => {
+                                const ended = globalThis.performance?.now();
+                                if (typeof started === 'number' && typeof ended === 'number') {
+                                    recordDns(started, ended);
+                                }
+                                callback(error, address, family);
+                            });
+                        } });
+                    const connect = (options, callback) => {
+                        const started = globalThis.performance?.now() ?? 0;
+                        const recordConnect = (0, server_timing_1.connectionSegmentRecorder)('connectMs');
+                        const recordTls = (0, server_timing_1.connectionSegmentRecorder)('tlsMs');
+                        let tcpConnectedAt;
+                        const socket = connector(options, callback);
+                        socket.once('connect', () => {
+                            const ended = globalThis.performance?.now();
+                            if (typeof ended === 'number') {
+                                tcpConnectedAt = ended;
+                                recordConnect(recordConnect.dnsEndedAt() ?? started, ended);
+                            }
+                        });
+                        socket.once('secureConnect', () => {
+                            const ended = globalThis.performance?.now();
+                            if (typeof ended === 'number' && tcpConnectedAt !== undefined)
+                                recordTls(tcpConnectedAt, ended);
+                        });
+                        return socket;
+                    };
+                    return new Agent(pooledAgentOptions(connect));
+                });
+            });
+            return pool.then(async (dispatcher) => {
+                if (!firstRequest) {
+                    // Let Undici return completed response sockets to the pool before dispatching again.
+                    await new Promise(resolve => setImmediate(resolve));
+                }
+                firstRequest = false;
+                const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+                const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+                if (!SAFE_RETRY_METHODS.has(method.toUpperCase()) && !headers.has('Idempotency-Key')) {
+                    return fetch(input, { ...init, dispatcher });
+                }
+                const request = new Request(input, init);
+                const replay = request.clone();
+                // The first send may already have run: the replay must let Cloud check its record first.
+                replay.headers.delete(exports.FIRST_SEND_HEADER);
+                try {
+                    return await fetch(request, { dispatcher });
+                }
+                catch (error) {
+                    if (!hasStaleSocketCode(error))
+                        throw error;
+                    try {
+                        return await fetch(replay, { dispatcher });
+                    }
+                    catch (replayError) {
+                        throw (0, api_error_1.markAfterSend)(replayError);
+                    }
+                }
+            }).finally(() => {
+                if (--pendingDispatches === 0) {
+                    resolveDispatchesDrained?.();
+                    dispatchesDrained = undefined;
+                    resolveDispatchesDrained = undefined;
+                }
+            });
+        },
+        close: () => {
+            if (closing)
+                return closing;
+            closed = true;
+            const pending = dispatchesDrained;
+            closing = (async () => {
+                await pending;
+                if (pool !== undefined)
+                    await (await pool).close();
+            })();
+            return closing;
+        },
+    };
+}
+function setting(value, option, variable, fallback) {
+    const environment = globalThis.process?.env;
+    const resolved = value ?? environment?.[variable] ?? fallback;
+    if (!resolved)
+        throw new TypeError(`Set ${variable} or pass ${option} to the client`);
+    return resolved;
+}
+/** Add a per-client timing context around generated operations only when the timing hook is installed. */
+function timedApi(api) {
+    const proxies = new WeakMap();
+    const methods = new WeakMap();
+    const wrap = (target) => {
+        const cached = proxies.get(target);
+        if (cached)
+            return cached;
+        const proxy = new Proxy(target, {
+            get(object, property, receiver) {
+                const value = Reflect.get(object, property, receiver);
+                if (property === 'client')
+                    return value;
+                if (typeof value === 'function') {
+                    let byFunction = methods.get(object);
+                    if (!byFunction)
+                        methods.set(object, byFunction = new WeakMap());
+                    let wrapped = byFunction.get(value);
+                    if (!wrapped) {
+                        wrapped = (...args) => (0, server_timing_1.withClientTiming)(() => Promise.resolve(Reflect.apply(value, object, args)), true);
+                        byFunction.set(value, wrapped);
+                    }
+                    return wrapped;
+                }
+                return value !== null && typeof value === 'object' ? wrap(value) : value;
+            },
+        });
+        proxies.set(target, proxy);
+        return proxy;
+    };
+    return wrap(api);
+}
+/** The options a client was created with, for the opt-in native surface; never serialized. */
+function clientOptions(client) {
+    const options = configured.get(client);
+    if (options === undefined)
+        throw new TypeError('Expected a BoxRouter client');
+    return options;
+}
+/** Sent with a key made for this request; never with a key that may have been sent before. */
+exports.FIRST_SEND_HEADER = 'X-BoxRouter-First-Send';
+/** Mutations without a caller key get a fresh one, so a lost response can be reconciled.
+ * A fresh key is marked as a first send: Cloud may then dispatch the operation beside its record. */
+function idempotencyKeys(operations) {
+    return (request, options) => {
+        if (operations.has(`${request.method} ${options.url}`) && !request.headers.has('Idempotency-Key')) {
+            request.headers.set('Idempotency-Key', globalThis.crypto.randomUUID());
+            request.headers.set(exports.FIRST_SEND_HEADER, '1');
+        }
+        return request;
+    };
+}
+/** Each instance owns its BoxRouter authentication and HTTP configuration. */
+class BoxRouter {
+    api;
+    usage;
+    images;
+    spendLimits;
+    operations;
+    sandboxes;
+    volumes;
+    routing;
+    /** Close this client's owned HTTP connection pool. Borrowed views and custom fetches are caller-owned. */
+    close() {
+        return closeTransport.get(this)();
+    }
+    /** Release this client's owned HTTP connection pool when used with `await using`. */
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+    /** Clone current HTTP configuration/interceptors without changing the owner. */
+    withUserAgentSuffix(suffix) {
+        const parent = transports.get(this);
+        const config = parent.getConfig();
+        const headers = new Headers(config.headers);
+        const identification = (0, user_agent_1.appendUserAgentSuffix)(headers.get('User-Agent') ?? user_agent_1.userAgent, suffix);
+        headers.set('User-Agent', identification);
+        const view = new BoxRouter(clientOptions(this));
+        configured.set(view, { ...clientOptions(view), identification });
+        const transport = transports.get(view);
+        transport.setConfig({ ...config, headers });
+        // The view shares what its owner has learned, through the owner's response interceptor copied below.
+        dataOrigins.set(transport, dataOrigins.get(parent));
+        for (const kind of ['request', 'response', 'error']) {
+            transport.interceptors[kind].clear();
+            for (const fn of parent.interceptors[kind].fns) {
+                if (fn)
+                    transport.interceptors[kind].use(fn);
+            }
+        }
+        return view;
+    }
+    constructor(options = {}) {
+        const apiKey = setting(options.apiKey, 'apiKey', 'BOXROUTER_API_KEY');
+        const baseUrl = setting(options.baseUrl, 'baseUrl', 'BOXROUTER_BASE_URL', workflow_policy_gen_1.DEFAULT_BASE_URL);
+        const pooled = options.fetch === undefined || (0, server_timing_1.usesClientOwnedFetch)(options.fetch)
+            ? nodePooledFetch(options.fetch !== undefined) : undefined;
+        const fetch = options.fetch === undefined ? pooled?.fetch
+            : (0, server_timing_1.useClientOwnedFetch)(options.fetch, pooled?.fetch);
+        const { userAgentSuffix } = options;
+        const identification = userAgentSuffix === undefined ? user_agent_1.userAgent : (0, user_agent_1.appendUserAgentSuffix)(user_agent_1.userAgent, userAgentSuffix);
+        const maxRetries = (0, retry_1.checkMaxRetries)(options.maxRetries);
+        configured.set(this, { apiKey, baseUrl, fetch, userAgentSuffix, identification, maxRetries });
+        closeTransport.set(this, pooled?.close ?? (() => noOwnedTransport));
+        const client = (0, client_1.createClient)({ auth: apiKey, baseUrl, throwOnError: true, headers: { 'User-Agent': identification },
+            fetch: (0, retry_1.retryingFetch)(() => fetch ?? globalThis.fetch, maxRetries) });
+        transports.set(this, client);
+        client.interceptors.request.use(idempotencyKeys(idempotency_gen_1.idempotentOperations));
+        const dataOrigin = {};
+        dataOrigins.set(client, dataOrigin);
+        client.interceptors.response.use((0, data_origin_1.observeDataOrigin)(baseUrl, dataOrigin));
+        const api = new sdk_gen_1.BoxRouterApi({ client });
+        this.api = (0, server_timing_1.usesClientTimingFetch)(fetch) ? timedApi(api) : api;
+        (0, data_origin_1.provideDataOrigin)(this.api, () => dataOrigins.get(client)?.baseUrl);
+        this.images = new images_1.ImageResources(this.api);
+        this.spendLimits = new spend_limits_1.SpendLimitResources(this.api);
+        this.operations = new operations_1.OperationResources(this.api);
+        this.usage = {
+            list: (...args) => this.api.usage.list(...args),
+            exportCsv: (...args) => this.api.usage.exportCsv(...args),
+        };
+        this.sandboxes = new sandboxes_1.SandboxResources(this.api);
+        this.volumes = new volumes_1.VolumeResources(this.api);
+        this.routing = new routing_1.RoutingResources(this.api);
+    }
+}
+exports.BoxRouter = BoxRouter;

package/dist/browser-session/index.d.ts

@@ -0,0 +1,17 @@
+import { type BrowserSessionOperationId, type BrowserSessionResponses } from './operations.gen';
+export type { BrowserSessionOperationId, BrowserSessionResponses } from './operations.gen';
+export { browserSessionOperations } from './operations.gen';
+export { APIError } from '../api-error';
+/** The HTTP method and path of an operation, as data. */
+export declare function browserSessionOperation(id: BrowserSessionOperationId): {
+    readonly method: string;
+    readonly path: string;
+};
+/**
+ * Validate a response the caller received for `request` against the operation's declared
+ * contract. Returns the parsed body (`undefined` for a body-less success) or throws the
+ * SDK's `APIError`.
+ */
+export declare function parseBrowserSessionResponse<Id extends BrowserSessionOperationId>(id: Id, response: Response, request: Request): Promise<BrowserSessionResponses[Id]>;
+/** The compiled validator for one declared success status, for build-time checks such as an early read. */
+export declare function loadBrowserSessionValidator(id: BrowserSessionOperationId, status: string): Promise<(value: unknown) => boolean>;