@prized/sdk 0.0.0-stage → 0.1.0

package/dist/esm/sandbox.d.ts

@@ -0,0 +1,218 @@
+import { CommandHandle, type ExecOptions } from './commands.js';
+import { Files } from './files.js';
+import { type ClientOptions } from './http.js';
+import { type ExecResult, type Resources, type ResourcesInput, type SandboxInfo, type SandboxState, type Template } from './types.js';
+/** The header a request to a sandbox port's URL carries the API key in. */
+export declare const PREVIEW_KEY_HEADER = "Prized-Key";
+/** The template a create uses when it names none. */
+export declare const DEFAULT_TEMPLATE = "prized-base-v1";
+/** How long create, resume and fork wait for `running` by default. */
+export declare const DEFAULT_START_TIMEOUT_MS = 180000;
+/** How long pause and delete wait by default. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 120000;
+/** Cleanups still running after the call that started them has answered.
+ *  Not exported from the package; the tests await it. */
+export declare const backgroundCleanups: Set<Promise<void>>;
+/** Edge warm-ups (warmEdge) not yet settled. Not exported from the package;
+ *  the tests await it. */
+export declare const backgroundWarmups: Set<Promise<void>>;
+export interface CreateOptions extends ClientOptions {
+    /** Template id. Default `prized-base-v1`; `Sandbox.templates()` lists them. */
+    template?: string;
+    /** vCPU, memory and disk. Anything left out takes the template's default. */
+    resources?: ResourcesInput;
+    /** Environment variables for every command in the sandbox. */
+    envVars?: Record<string, string>;
+    /** Your own key/value tags (up to 32), filterable in `Sandbox.list`. */
+    labels?: Record<string, string>;
+    /**
+     * Run time in minutes; the sandbox is deleted when it ends. Paid plans:
+     * 1 440 (24 hours) by default, up to 7 days (10 080; a custom plan has no
+     * maximum), and every resume restarts the clock. The free tier: 60
+     * minutes of running at most (paused time does not count). Change it later
+     * with `prized sandbox extend` or the API's `extend` and `timeout` routes.
+     */
+    maxRuntimeMin?: number;
+    /** Pause after this many idle minutes (0: never). */
+    autoPauseMin?: number;
+    /** Delete this many minutes after pausing (0: never). */
+    autoDeleteMin?: number;
+    /**
+     * How long the create may take, in ms: the request, its retries and
+     * (unless `wait: false`) the wait for `running`. Default 180 000.
+     * Deleting a sandbox that failed (up to 5 s) comes on top.
+     */
+    timeoutMs?: number;
+    /**
+     * Makes a retried create return the same sandbox instead of a second one.
+     * The SDK sends a fresh key per call when you give none, so its own
+     * retries are always safe.
+     */
+    idempotencyKey?: string;
+    /** Resolve as soon as the API accepts the create, without waiting for `running`. */
+    wait?: boolean;
+    signal?: AbortSignal;
+}
+export interface ListOptions extends ClientOptions {
+    /** Only sandboxes carrying every one of these labels. */
+    labels?: Record<string, string>;
+    /** Only sandboxes in this state (or any of these states). */
+    state?: SandboxState | SandboxState[];
+}
+export interface WaitableOptions {
+    /** Wait for the change to land. Default true (false for delete). */
+    wait?: boolean;
+    /**
+     * How long the call may take, in ms: the request, its retries and
+     * (unless `wait: false`) the wait. Default 180 000 for resume and fork,
+     * 120 000 for pause and delete. Deleting a fork's copies that failed
+     * comes on top.
+     */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ForkOptions extends WaitableOptions {
+    /** How many copies. Default 1. */
+    count?: number;
+    /** Labels for the copies, in place of the parent's. Default: the parent's labels. */
+    labels?: Record<string, string>;
+    /**
+     * Each copy's lifetime in minutes, up to the workspace's maximum. Default:
+     * on a paid workspace, the parent's runtime, starting at the fork; on the
+     * free tier, copies keep the parent's deletion time (this may only shorten it).
+     */
+    maxRuntimeMin?: number;
+    /** Makes a retried fork return the same copies. The SDK sends one per call when you give none. */
+    idempotencyKey?: string;
+}
+/**
+ * A Prized sandbox: a microVM your code creates, runs commands in, and
+ * pauses, resumes, forks and deletes.
+ *
+ *     const sandbox = await Sandbox.create({ template: 'prized-base-v1' });
+ *     const { stdout } = await sandbox.exec('python3 --version');
+ *     await sandbox.delete();
+ */
+export declare class Sandbox {
+    /** The sandbox id (`sbx_…`). */
+    readonly id: string;
+    /** Read, write, list, remove, upload and download files. */
+    readonly files: Files;
+    private readonly config;
+    private current;
+    private readonly toolbox;
+    private constructor();
+    /** Everything the API said about this sandbox, as of the last call. */
+    get info(): SandboxInfo;
+    /** The state as of the last call; `refresh()` reads it fresh. */
+    get state(): SandboxState;
+    get template(): string | null;
+    get resources(): Resources;
+    get labels(): Record<string, string>;
+    get createdAt(): Date | null;
+    get expiresAt(): Date | null;
+    get errorReason(): string | null;
+    toJSON(): Omit<SandboxInfo, 'raw'>;
+    /**
+     * Create a sandbox and wait until it is running, ready for commands.
+     * If it fails or the wait runs out, the sandbox is deleted and the error
+     * thrown. Throws PrizedError: `paid_balance_required`, `insufficient_balance`,
+     * `sandbox_quota_exceeded` (see `reason`), `template_not_found`,
+     * `invalid_resources`, `sandbox_error`, `timeout`, …
+     */
+    static create(options?: CreateOptions): Promise<Sandbox>;
+    /** An existing sandbox by id, in whatever state it is in. */
+    static connect(id: string, options?: ClientOptions): Promise<Sandbox>;
+    /** The workspace's sandboxes (deleted ones excluded), newest first; `labels` is filtered by the API. */
+    static list(options?: ListOptions): Promise<Sandbox[]>;
+    /**
+     * Delete every sandbox carrying all of `labels` (at least one) and resolve
+     * with their ids (the API takes up to 250 a request; this repeats it until
+     * none are left). Safe to repeat: sandboxes already being
+     * deleted are in the answer again, and none matching resolves `[]`. Each
+     * counts toward the workspace's quotas until it is gone;
+     * `Sandbox.list({ labels })` coming back empty means they all are.
+     */
+    static deleteByLabels(labels: Record<string, string>, options?: ClientOptions): Promise<string[]>;
+    /** The templates you can create sandboxes from, with their default, minimum and maximum shapes. */
+    static templates(options?: ClientOptions): Promise<Template[]>;
+    /**
+     * Run a command (a shell string, or an argv array the SDK quotes) and
+     * return its output. A non-zero exit is not an error: read `exitCode`.
+     * With `background: true` it returns a CommandHandle at once.
+     */
+    exec(command: string | readonly string[], options: ExecOptions & {
+        background: true;
+    }): Promise<CommandHandle>;
+    exec(command: string | readonly string[], options?: ExecOptions & {
+        background?: false;
+    }): Promise<ExecResult>;
+    exec(command: string | readonly string[], options?: ExecOptions): Promise<ExecResult | CommandHandle>;
+    /** Read the sandbox again: `state` and the other fields update. Does not count as activity. */
+    refresh(): Promise<this>;
+    /**
+     * Count as activity now: the `autoPauseMin` idle clock starts over.
+     * Commands and file transfers already count; this is for idle stretches.
+     */
+    keepAlive(): Promise<void>;
+    /**
+     * Pause: memory and disk are kept, and only storage is billed. Waits for
+     * `paused` unless `wait: false`.
+     */
+    pause(options?: WaitableOptions): Promise<void>;
+    /** Resume a paused sandbox, with every process where it left off. Waits for `running` unless `wait: false`. */
+    resume(options?: WaitableOptions): Promise<void>;
+    /**
+     * Fork a running or paused sandbox into `count` new sandboxes, each with
+     * every process of this one running. Resolves once every copy is running,
+     * ready for commands (unless `wait: false`); if any copy fails or the
+     * wait runs out, every copy is deleted and the error thrown. The parent is
+     * left as it was: running, or paused. `timeoutMs` bounds the request and
+     * the wait together.
+     */
+    fork(options?: ForkOptions): Promise<Sandbox[]>;
+    /**
+     * Delete the sandbox and everything in it. Returns once the API accepts;
+     * `wait: true` also waits until it is gone (a deleting sandbox still
+     * counts toward the workspace's quota). `timeoutMs` (default 120 000)
+     * bounds the whole call, its retries and the wait included.
+     */
+    delete(options?: WaitableOptions): Promise<void>;
+    /**
+     * The https URL `port` of the sandbox answers at, for a request that
+     * carries a workspace-wide API key with Sandboxes: Write in the
+     * `Prized-Key` header (`previewHeaders()`): a web app, an API or a dev
+     * server listening on that port in the sandbox on 127.0.0.1 or 0.0.0.0. A
+     * request to a paused sandbox resumes it and waits up to 10 seconds, as
+     * `exec` does. Nothing is created: the URL is the sandbox's own. Throws
+     * `preview_unavailable` when the deployment has sandbox ingress off.
+     */
+    previewUrl(port: number): string;
+    /** The headers a request to `previewUrl(port)` sends: this client's API key in
+     *  `Prized-Key`. The header never reaches the app. Send them with
+     *  `redirect: 'manual'`: fetch resends custom headers to whatever host a
+     *  redirect names, so only ever send them to the sandbox's preview URL. */
+    previewHeaders(): Record<string, string>;
+    /** POST the verb, the call and its retries within `deadline`; with `hold`,
+     *  held by the API until the sandbox is that (each attempt asks only for
+     *  what is left). */
+    private verb;
+    /**
+     * Poll until the sandbox reaches `want`; throws on error/deleted or the
+     * deadline. The first read goes out at once (a held answer that has not
+     * settled is usually a breath away), then 100 ms, doubling to
+     * pollIntervalMs, and the last just before the deadline (Polls).
+     * `reportedMs` is the caller's whole budget, for the error.
+     */
+    private waitFor;
+    /** Best-effort delete after a failed wait, bounded (as the Python SDK's); never throws. */
+    private discard;
+    /**
+     * Poll the list until every fork copy is running or has failed, by
+     * `deadline`: one list call per poll, however many copies, every
+     * pollIntervalMs, and the last just before the deadline (Polls),
+     * so even a budget shorter than one interval polls once. `reportedMs` is
+     * the caller's whole budget, for the error.
+     */
+    private static settle;
+}