@boxrouter/sdk 0.0.1-alpha.0 → 0.12.190

package/dist/routing.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoutingResources = void 0;
+/** Workspace Routing settings and read-only availability preview. */
+class RoutingResources {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    async settings(options = {}) {
+        return this.api.routing.settings({ signal: options.signal });
+    }
+    /** Change only the routing fields you give; omitted fields keep their stored values. */
+    async update(fields, options = {}) {
+        if (Object.keys(fields).length === 0)
+            throw new TypeError('Pass at least one routing field to change');
+        return this.api.routing.updateSettings({
+            body: { section: 'routing', routing: fields },
+            headers: options.ifMatch === undefined ? undefined : { 'If-Match': options.ifMatch },
+            signal: options.signal,
+        });
+    }
+    /** Change only the funding fields you give for one provider. */
+    async updateFunding(provider, funding, options = {}) {
+        if (Object.keys(funding).length === 0)
+            throw new TypeError('Pass funding_order or credits to change');
+        return this.api.routing.updateSettings({
+            body: { section: 'provider_funding', provider, funding },
+            headers: options.ifMatch === undefined ? undefined : { 'If-Match': options.ifMatch },
+            signal: options.signal,
+        });
+    }
+    /** Read current routing availability; this is not a route prediction. */
+    async preview(options = {}) {
+        return this.api.routing.preview({ signal: options.signal });
+    }
+}
+exports.RoutingResources = RoutingResources;

package/dist/sandbox-handle.gen.d.ts

@@ -0,0 +1,8 @@
+import type { Sandbox } from './types.gen';
+/** The sandbox's fields as of the last response, shown as read-only handle properties. */
+export interface SandboxFields extends Readonly<Pick<Sandbox, "id" | "state" | "state_reason" | "failure" | "native_state" | "observed_at" | "state_recorded_at" | "created_at" | "expires_at" | "ready_at" | "ended_at" | "created_at_source" | "created_at_how" | "created_at_step" | "ready_at_source" | "ready_at_how" | "ready_at_step" | "ended_at_source" | "ended_at_how" | "ended_at_step" | "cost_source" | "cost_how" | "cost_step" | "origin" | "labels" | "name" | "resources" | "image" | "image_setup" | "usage" | "cost" | "charge" | "funded_until" | "connectable" | "lifetime" | "route" | "contract" | "request" | "hidden_secrets" | "tcp_ports" | "recorder" | "limits" | "volume" | "operation_id" | "account">> {
+}
+/** Define each field as a getter on the handle's prototype, read from the handle's current sandbox. */
+export declare function defineSandboxFields<Handle extends object>(handle: {
+    prototype: Handle;
+}, read: (handle: Handle) => Sandbox): void;

package/dist/sandbox-handle.gen.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineSandboxFields = defineSandboxFields;
+const SANDBOX_FIELDS = ["id", "state", "state_reason", "failure", "native_state", "observed_at", "state_recorded_at", "created_at", "expires_at", "ready_at", "ended_at", "created_at_source", "created_at_how", "created_at_step", "ready_at_source", "ready_at_how", "ready_at_step", "ended_at_source", "ended_at_how", "ended_at_step", "cost_source", "cost_how", "cost_step", "origin", "labels", "name", "resources", "image", "image_setup", "usage", "cost", "charge", "funded_until", "connectable", "lifetime", "route", "contract", "request", "hidden_secrets", "tcp_ports", "recorder", "limits", "volume", "operation_id", "account"];
+/** Define each field as a getter on the handle's prototype, read from the handle's current sandbox. */
+function defineSandboxFields(handle, read) {
+    for (const name of SANDBOX_FIELDS) {
+        Object.defineProperty(handle.prototype, name, {
+            get() { return read(this)[name]; },
+            enumerable: true,
+            configurable: true,
+        });
+    }
+}

package/dist/sandboxes.d.ts

@@ -0,0 +1,213 @@
+import type { BoxRouterApi } from './sdk.gen';
+import type { AgentPage, ByteCommandResult, DirectoryEntry, Launch, Lifetime, MatchResult, OpenPreview, Paused, Preview, Resumed, RunCommand, CommandResult, ProcessOutput, Sandbox, SandboxPage, SandboxesListData, StartProcess, VolumeCheckpoint } from './types.gen';
+import { type Terminal, type TerminalOptions } from './terminal';
+import { type LaunchOptions } from './launch';
+import { type TransferProgress } from './transfer';
+import { type SandboxConfig, type SandboxVolumeSaveArguments } from './creation.gen';
+import { type SandboxFields } from './sandbox-handle.gen';
+export type { SandboxConfig } from './creation.gen';
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface MutationOptions extends RequestOptions {
+    idempotencyKey?: string;
+}
+export declare function mutationOptions({ signal, idempotencyKey }: MutationOptions): {
+    signal: AbortSignal | undefined;
+    headers: {
+        'Idempotency-Key': string;
+    } | undefined;
+};
+/** What a text command may carry: today's fields, and `output` left out or `'text'`. */
+export type TextCommandConfig = Omit<RunCommand, 'command' | 'output'> & CommandCheck & {
+    output?: 'text';
+};
+/** What a command asking for bytes carries. */
+export type ByteCommandConfig = Omit<RunCommand, 'command' | 'output'> & CommandCheck & {
+    output: 'bytes';
+};
+/** Client-side: raise the contract's result-check error when the command fails or times out. */
+export interface CommandCheck {
+    check?: boolean;
+}
+/** A byte-mode command result after decoding the JSON transport's base64 streams. */
+export interface CommandBytesResult extends Omit<ByteCommandResult, 'stdout_base64' | 'stderr_base64'> {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}
+export declare function decodeBase64(value: string): Uint8Array;
+/** Provider-neutral sandbox operations. */
+export declare class SandboxResources {
+    private readonly api;
+    constructor(api: BoxRouterApi);
+    agents(options?: RequestOptions): Promise<AgentPage>;
+    create(config?: SandboxConfig, options?: MutationOptions): Promise<SandboxHandle>;
+    /** Explain which routes creation would use for the same config, without creating anything. */
+    match(config?: SandboxConfig, options?: RequestOptions): Promise<MatchResult>;
+    /** Read a sandbox's live state from Cloud and return its handle. */
+    get(id: string, options?: RequestOptions): Promise<SandboxHandle>;
+    /** One page of the caller's sandboxes; the query filters and pages as the list operation defines. */
+    list(query?: NonNullable<SandboxesListData['query']>, options?: RequestOptions): Promise<SandboxPage>;
+    /** Open a PTY shell by sandbox ID, or attach with terminalId; the shell keeps running afterwards. */
+    openTerminal(id: string, options?: TerminalOptions): Promise<Terminal>;
+    /**
+     * Launch a catalog agent, image, source manifest, plain checkout or manifest. Waits until the launch is
+     * ready and returns the sandbox, the same handle `create` returns; `destroy()` ends it. `openTerminal`
+     * on the handle opens a shell that starts the launch's command. Rejects with a TimeoutError when the
+     * launch is still pending after its bound.
+     */
+    launch(options?: LaunchOptions): Promise<SandboxHandle>;
+    launch(agent: string, options?: LaunchOptions): Promise<SandboxHandle>;
+}
+export interface SandboxHandle extends SandboxFields {
+}
+/**
+ * A bound sandbox. Its properties are the Sandbox fields (`state`, `lifetime`, `route`, ...) as
+ * of the last response: `get` returns a handle, `refresh` reads again, and `destroy`, `pause`,
+ * `resume` and `extend` update it. Every handle has every method: a sandbox created without the
+ * requirement a method needs answers with an `APIError` whose code is `not_named`.
+ */
+export declare class SandboxHandle {
+    #private;
+    /** The launch result when `sandboxes.launch` returned this handle (with `interactive` resolved), otherwise undefined. */
+    readonly launch: Launch | undefined;
+    readonly files: SandboxFiles;
+    readonly processes: SandboxProcesses;
+    readonly previews: SandboxPreviews;
+    private readonly api;
+    constructor(api: BoxRouterApi, sandbox: Sandbox, launched?: {
+        launch: Launch;
+        terminalCommand: string | undefined;
+    });
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Read the sandbox again from Cloud and update this handle's properties. */
+    refresh(options?: RequestOptions): Promise<this>;
+    /**
+     * Open a PTY shell in this sandbox, or attach with terminalId. After `sandboxes.launch`, a new shell starts
+     * the launch's command (written first, with a 3600 s timeout unless you give one).
+     */
+    openTerminal(options?: TerminalOptions): Promise<Terminal>;
+    /** Run a command; byte mode returns exact stdout and stderr Uint8Arrays. */
+    exec(command: string, config?: TextCommandConfig, options?: MutationOptions): Promise<CommandResult>;
+    exec(command: string, config: ByteCommandConfig, options?: MutationOptions): Promise<CommandBytesResult>;
+    /** `output` chosen at run time: the result is whichever form it named. */
+    exec(command: string, config: Omit<RunCommand, 'command'> & CommandCheck, options?: MutationOptions): Promise<CommandResult | CommandBytesResult>;
+    saveVolume(...[options]: SandboxVolumeSaveArguments): Promise<VolumeCheckpoint>;
+    /**
+     * Request destruction and update this handle from the sandbox Cloud returns: `destroyed`, or
+     * `destroying` with an `operation_id` while Cloud finishes the destroy without the caller.
+     */
+    destroy(options?: MutationOptions & {
+        discardUnsaved?: boolean;
+    }): Promise<Sandbox>;
+    /** Pause the sandbox; the handle's `state` and `lifetime` follow the response. */
+    pause(options?: MutationOptions): Promise<Paused>;
+    /** Resume the sandbox; undefined means it was already running (204), and nothing changes. */
+    resume(options?: MutationOptions): Promise<Resumed | undefined>;
+    /** Set the sandbox's new total running-time budget in seconds (not an increment). */
+    extend(body: {
+        lifetime_seconds: number;
+    }, options?: MutationOptions): Promise<Lifetime>;
+}
+/** Previews of one sandbox. */
+export declare class SandboxPreviews {
+    private readonly api;
+    private readonly id;
+    constructor(api: BoxRouterApi, id: string);
+    /** Open a preview of `port`, which the sandbox's previews requirement must name. */
+    open(port: number, config?: Omit<OpenPreview, 'port'>, options?: MutationOptions): Promise<Preview>;
+}
+/** Options of `ProcessHandle.wait()`. */
+export interface ProcessWaitOptions extends RequestOptions {
+    /** Byte offsets to start from. */
+    stdout?: number | bigint;
+    stderr?: number | bigint;
+    /** Reject with a TimeoutError after this many seconds; the command keeps running. */
+    timeoutSeconds?: number;
+}
+/** Background commands bound to one sandbox. */
+export declare class SandboxProcesses {
+    private readonly api;
+    private readonly id;
+    constructor(api: BoxRouterApi, id: string);
+    start(command: string, config?: Omit<StartProcess, 'command'>, options?: MutationOptions): Promise<ProcessHandle>;
+    /** A handle for a started process. */
+    fromId(processId: string): ProcessHandle;
+}
+/** A started command, addressed by its durable ID. Nothing here cancels it implicitly. */
+export declare class ProcessHandle {
+    #private;
+    private readonly api;
+    constructor(api: BoxRouterApi, sandboxId: string, processId: string);
+    get id(): string;
+    /**
+     * Output from the given byte offsets; continue from next_stdout and next_stderr.
+     * exit_code is set once the process ended and both streams were read to their ends.
+     */
+    read(options?: RequestOptions & {
+        stdout?: number | bigint;
+        stderr?: number | bigint;
+    }): Promise<ProcessOutput>;
+    /**
+     * Polls read() until the process exits and returns the result `exec` returns for the same
+     * `output`: text (invalid bytes replaced) by default, or the exact bytes with `output: 'bytes'`.
+     * Rejects with a TimeoutError once timeoutSeconds have passed, never later: every read and
+     * pause is bounded by the time left. The command keeps running.
+     */
+    wait(options?: ProcessWaitOptions & {
+        output?: 'text';
+    }): Promise<CommandResult>;
+    wait(options: ProcessWaitOptions & {
+        output: 'bytes';
+    }): Promise<CommandBytesResult>;
+    wait(options: ProcessWaitOptions & {
+        output?: 'text' | 'bytes';
+    }): Promise<CommandResult | CommandBytesResult>;
+    /** Appends text to stdin; the process must have started with stdin: true. */
+    writeStdin(data: string, options?: MutationOptions): Promise<void>;
+    closeStdin(options?: RequestOptions): Promise<void>;
+    /** Requests termination; wait() or read() confirms the exit. */
+    cancel(options?: MutationOptions): Promise<void>;
+    /** Deletes the retained output of a finished process. */
+    remove(options?: MutationOptions): Promise<void>;
+}
+export interface SandboxUploadOptions extends MutationOptions {
+    /** Required for a stream; checked against any other source. */
+    size?: number;
+    concurrency?: number;
+    progress?: TransferProgress;
+}
+export interface SandboxDownloadOptions extends RequestOptions {
+    progress?: TransferProgress;
+}
+export declare class SandboxFiles {
+    private readonly api;
+    private readonly id;
+    private readonly inlineTransferMaxBytes?;
+    constructor(api: BoxRouterApi, id: string, inlineTransferMaxBytes?: number | undefined);
+    /** The route's advertised inline size, capped at the inline read's own bound. */
+    private inlineBelow;
+    list(path: string, options?: RequestOptions): Promise<DirectoryEntry[]>;
+    exists(path: string, options?: RequestOptions): Promise<boolean>;
+    mkdir(path: string, options?: MutationOptions & {
+        parents?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: MutationOptions & {
+        recursive?: boolean;
+    }): Promise<void>;
+    read(path: string, options?: RequestOptions): Promise<Uint8Array>;
+    write(path: string, content: string | Uint8Array | Blob, options?: MutationOptions): Promise<void>;
+    /**
+     * Upload a local file path, Blob, bytes or stream to `remotePath`. A stream needs `size`. The request
+     * carries the exact length, so a stream is first spooled to a temporary file (never into memory).
+     * `progress` is called as each part finishes. An upload that fails before completion is sent is aborted;
+     * one that fails after is left as it is, its outcome unknown. Bytes already written may remain.
+     */
+    upload(source: string | Blob | Uint8Array | ReadableStream<Uint8Array>, remotePath: string, options?: SandboxUploadOptions): Promise<void>;
+    /**
+     * Download `remotePath` to `localPath` (written through a temporary file and renamed once the full
+     * length has arrived), or with no `localPath` return the bytes as a stream that errors if it ends short.
+     */
+    download(remotePath: string, localPath?: undefined, options?: SandboxDownloadOptions): Promise<ReadableStream<Uint8Array>>;
+    download(remotePath: string, localPath: string, options?: SandboxDownloadOptions): Promise<void>;
+}