@vercel/sandbox 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxMetaData, SandboxRouteData, NamedSandboxMetaData } from "./api-client";
+import type { SessionMetaData, SandboxRouteData, SandboxMetaData } from "./api-client";
 import { APIClient } from "./api-client";
 import { type Credentials } from "./utils/get-credentials";
 import { type WithPrivate } from "./utils/types";
@@ -7,7 +7,7 @@ import type { RUNTIMES } from "./constants";
 import { Session, type RunCommandParams } from "./session";
 import type { Command, CommandFinished } from "./command";
 import type { Snapshot } from "./snapshot";
-import type { ConvertedSandbox } from "./utils/convert-sandbox";
+import type { ConvertedSession } from "./utils/convert-sandbox";
 import type { NetworkPolicy } from "./network-policy";
 export type { NetworkPolicy };
 /** @inline */
@@ -82,14 +82,25 @@ export interface BaseCreateSandboxParams {
      * await sandbox.runCommand("node", ["app.js"]);
      */
     env?: Record<string, string>;
+    /**
+     * Key-value tags to associate with the sandbox. Maximum 5 tags.
+     * @example { env: "staging", team: "infra" }
+     */
+    tags?: Record<string, string>;
     /**
      * An AbortSignal to cancel sandbox creation.
      */
     signal?: AbortSignal;
     /**
-     * Whether to enable snapshots on shutdown. Defaults to true.
+     * Enable or disable automatic restore of the filesystem between sessions.
      */
     persistent?: boolean;
+    /**
+     * Default snapshot expiration in milliseconds.
+     * When set, snapshots created for this sandbox will expire after this duration.
+     * Use `0` for no expiration.
+     */
+    snapshotExpiration?: number;
 }
 export type CreateSandboxParams = BaseCreateSandboxParams | (Omit<BaseCreateSandboxParams, "runtime" | "source"> & {
     source: {
@@ -120,14 +131,18 @@ interface GetSandboxParams {
 export declare class Sandbox {
     private readonly client;
     private readonly projectId;
+    /**
+     * In-flight resume promise, used to deduplicate concurrent resume calls.
+     */
+    private resumePromise;
     /**
      * Internal Session instance for the current VM.
      */
     private session;
     /**
-     * Internal metadata about the named sandbox.
+     * Internal metadata about the sandbox.
      */
-    private namedSandbox;
+    private sandbox;
     /**
      * The name of this sandbox.
      */
@@ -144,17 +159,17 @@ export declare class Sandbox {
     /**
      * The region this sandbox runs in.
      */
-    get region(): string;
+    get region(): string | undefined;
     /**
      * Number of virtual CPUs allocated.
      */
-    get vcpus(): number;
+    get vcpus(): number | undefined;
     /**
      * Memory allocated in MB.
      */
-    get memory(): number;
+    get memory(): number | undefined;
     /** Runtime identifier (e.g. "node24", "python3.13"). */
-    get runtime(): string;
+    get runtime(): string | undefined;
     /**
      * Cumulative egress bytes across all sessions.
      */
@@ -175,6 +190,10 @@ export declare class Sandbox {
      * When this sandbox was last updated.
      */
     get updatedAt(): Date;
+    /**
+     * When the sandbox status was last updated.
+     */
+    get statusUpdatedAt(): Date | undefined;
     /**
      * When this sandbox was created.
      */
@@ -186,11 +205,15 @@ export declare class Sandbox {
     /**
      * The status of the current session.
      */
-    get status(): SandboxMetaData["status"];
+    get status(): SessionMetaData["status"];
     /**
      * The default timeout of this sandbox in milliseconds.
      */
-    get timeout(): number;
+    get timeout(): number | undefined;
+    /**
+     * Key-value tags attached to the sandbox.
+     */
+    get tags(): Record<string, string> | undefined;
     /**
      * The default network policy of this sandbox.
      */
@@ -203,6 +226,10 @@ export declare class Sandbox {
      * The current snapshot ID of this sandbox, if any.
      */
     get currentSnapshotId(): string | undefined;
+    /**
+     * The default snapshot expiration in milliseconds, if set.
+     */
+    get snapshotExpiration(): number | undefined;
     /**
      * The amount of CPU used by the session. Only reported once the VM is stopped.
      */
@@ -219,57 +246,56 @@ export declare class Sandbox {
      * It returns both the sandboxes and the pagination metadata to allow getting
      * the next page of results.
      */
-    static list(params?: Partial<Parameters<APIClient["listNamedSandboxes"]>[0]> & Partial<Credentials> & WithFetchOptions): Promise<{
-        json: {
-            sandboxes: {
-                memory: number;
-                vcpus: number;
-                region: string;
-                runtime: string;
-                timeout: number;
-                status: "aborted" | "pending" | "running" | "stopping" | "stopped" | "failed" | "snapshotting";
-                createdAt: number;
-                updatedAt: number;
-                name: string;
-                persistent: boolean;
-                currentSandboxId: string;
-                networkPolicy?: import("zod").objectInputType<{
-                    mode: import("zod").ZodLiteral<"allow-all">;
-                }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
-                    mode: import("zod").ZodLiteral<"deny-all">;
-                }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
-                    mode: import("zod").ZodLiteral<"custom">;
-                    allowedDomains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-                    allowedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-                    deniedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-                    injectionRules: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
-                        domain: import("zod").ZodString;
-                        headers: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
-                        headerNames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
-                    }, "strip", import("zod").ZodTypeAny, {
-                        domain: string;
-                        headers?: Record<string, string> | undefined;
-                        headerNames?: string[] | undefined;
-                    }, {
-                        domain: string;
-                        headers?: Record<string, string> | undefined;
-                        headerNames?: string[] | undefined;
-                    }>, "many">>;
-                }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-                totalEgressBytes?: number | undefined;
-                totalIngressBytes?: number | undefined;
-                totalActiveCpuDurationMs?: number | undefined;
-                totalDurationMs?: number | undefined;
-                currentSnapshotId?: string | undefined;
-            }[];
-            pagination: {
-                count: number;
-                next: string | null;
-                total: number;
-            };
+    static list(params?: Partial<Parameters<APIClient["listSandboxes"]>[0]> & Partial<Credentials> & WithFetchOptions): Promise<{
+        pagination: {
+            count: number;
+            next: string | null;
         };
-        response: Response;
-        text: string;
+        sandboxes: {
+            status: "aborted" | "pending" | "running" | "stopping" | "stopped" | "failed" | "snapshotting";
+            createdAt: number;
+            updatedAt: number;
+            name: string;
+            persistent: boolean;
+            currentSessionId: string;
+            memory?: number | undefined;
+            vcpus?: number | undefined;
+            region?: string | undefined;
+            runtime?: string | undefined;
+            timeout?: number | undefined;
+            cwd?: string | undefined;
+            networkPolicy?: import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"allow-all">;
+            }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"deny-all">;
+            }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"custom">;
+                allowedDomains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                allowedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                deniedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                injectionRules: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                    domain: import("zod").ZodString;
+                    headers: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+                    headerNames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }>, "many">>;
+            }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+            totalEgressBytes?: number | undefined;
+            totalIngressBytes?: number | undefined;
+            totalActiveCpuDurationMs?: number | undefined;
+            totalDurationMs?: number | undefined;
+            currentSnapshotId?: string | undefined;
+            statusUpdatedAt?: number | undefined;
+            tags?: Record<string, string> | undefined;
+            snapshotExpiration?: number | undefined;
+        }[];
     }>;
     /**
      * Create a new sandbox.
@@ -291,11 +317,11 @@ export declare class Sandbox {
      * @returns A promise resolving to the {@link Sandbox}.
      */
     static get(params: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> & WithFetchOptions): Promise<Sandbox>;
-    constructor({ client, routes, session, namedSandbox, projectId, }: {
+    constructor({ client, routes, session, sandbox, projectId, }: {
         client: APIClient;
         routes: SandboxRouteData[];
-        session: SandboxMetaData;
-        namedSandbox: NamedSandboxMetaData;
+        session: SessionMetaData;
+        sandbox: SandboxMetaData;
         projectId: string;
     });
     /**
@@ -305,15 +331,16 @@ export declare class Sandbox {
      */
     currentSession(): Session;
     /**
-     * Resume this sandbox by creating a new session via `getNamedSandbox`.
+     * Resume this sandbox by creating a new session via `getSandbox`.
      */
     private resume;
+    private doResume;
     /**
      * Poll until the current session reaches a terminal state, then resume.
      */
     private waitForStopAndResume;
     /**
-     * Execute `fn`, and if the session is stopped/stopping, resume and retry.
+     * Execute `fn`, and if the session is stopped/stopping/snapshotting, resume and retry.
      */
     private withResume;
     /**
@@ -417,14 +444,21 @@ export declare class Sandbox {
      * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
      * Writes files using the `vercel-sandbox` user.
      *
-     * @param files - Array of files with path and stream/buffer contents
+     * @param files - Array of files with path, content, and optional mode (permissions)
      * @param opts - Optional parameters.
      * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the files are written
+     *
+     * @example
+     * // Write an executable script
+     * await sandbox.writeFiles([
+     *   { path: "/usr/local/bin/myscript", content: Buffer.from("#!/bin/bash\necho hello"), mode: 0o755 }
+     * ]);
      */
     writeFiles(files: {
         path: string;
         content: Buffer;
+        mode?: number;
     }[], opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -442,15 +476,17 @@ export declare class Sandbox {
      * @param opts - Optional parameters.
      * @param opts.signal - An AbortSignal to cancel the operation.
      * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.
-     * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.
+     * @returns The sandbox at the time the stop was acknowledged, or after fully stopped if `blocking` is true.
      */
     stop(opts?: {
         signal?: AbortSignal;
         blocking?: boolean;
-    }): Promise<ConvertedSandbox>;
+    }): Promise<ConvertedSession>;
     /**
      * Update the network policy for this sandbox.
      *
+     * @deprecated Use {@link Sandbox.update} instead.
+     *
      * @param networkPolicy - The new network policy to apply.
      * @param opts - Optional parameters.
      * @param opts.signal - An AbortSignal to cancel the operation.
@@ -517,69 +553,77 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<Snapshot>;
     /**
-     * Update the named sandbox configuration. Only provided fields are modified.
+     * Update the sandbox configuration.
      *
      * @param params - Fields to update.
      * @param opts - Optional abort signal.
      */
     update(params: {
+        persistent?: boolean;
         resources?: {
             vcpus?: number;
-            memory?: number;
         };
-        runtime?: RUNTIMES | (string & {});
         timeout?: number;
         networkPolicy?: NetworkPolicy;
+        tags?: Record<string, string>;
+        snapshotExpiration?: number;
     }, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /**
-     * Delete this named sandbox.
+     * Delete this sandbox.
      *
      * After deletion the instance becomes inert — all further API calls will
      * throw immediately.
      */
     delete(opts?: {
-        preserveSnapshots?: boolean;
         signal?: AbortSignal;
     }): Promise<void>;
     /**
-     * List sessions (VMs) that have been created for this named sandbox.
+     * List sessions (VMs) that have been created for this sandbox.
      *
      * @param params - Optional pagination parameters.
      * @returns The list of sessions and pagination metadata.
      */
     listSessions(params?: {
         limit?: number;
-        since?: number | Date;
-        until?: number | Date;
+        cursor?: string;
+        sortOrder?: "asc" | "desc";
         signal?: AbortSignal;
-    }): Promise<import("./api-client/base-client").Parsed<{
-        sandboxes: {
-            id: string;
-            memory: number;
-            vcpus: number;
-            region: string;
-            runtime: string;
-            timeout: number;
-            status: "aborted" | "pending" | "running" | "stopping" | "stopped" | "failed" | "snapshotting";
-            requestedAt: number;
-            createdAt: number;
-            cwd: string;
-            updatedAt: number;
-            startedAt?: number | undefined;
-            requestedStopAt?: number | undefined;
-            stoppedAt?: number | undefined;
-            abortedAt?: number | undefined;
-            duration?: number | undefined;
-            sourceSnapshotId?: string | undefined;
-            snapshottedAt?: number | undefined;
-            interactivePort?: number | undefined;
-            networkPolicy?: import("zod").objectInputType<{
+    }): Promise<{
+        sessions: import("zod").objectInputType<{
+            id: import("zod").ZodString;
+            memory: import("zod").ZodNumber;
+            vcpus: import("zod").ZodNumber;
+            region: import("zod").ZodString;
+            runtime: import("zod").ZodString;
+            timeout: import("zod").ZodNumber;
+            status: import("zod").ZodEnum<["pending", "running", "stopping", "stopped", "failed", "aborted", "snapshotting"]>;
+            requestedAt: import("zod").ZodNumber;
+            startedAt: import("zod").ZodOptional<import("zod").ZodNumber>;
+            requestedStopAt: import("zod").ZodOptional<import("zod").ZodNumber>;
+            stoppedAt: import("zod").ZodOptional<import("zod").ZodNumber>;
+            abortedAt: import("zod").ZodOptional<import("zod").ZodNumber>;
+            duration: import("zod").ZodOptional<import("zod").ZodNumber>;
+            sourceSnapshotId: import("zod").ZodOptional<import("zod").ZodString>;
+            snapshottedAt: import("zod").ZodOptional<import("zod").ZodNumber>;
+            createdAt: import("zod").ZodNumber;
+            cwd: import("zod").ZodString;
+            updatedAt: import("zod").ZodNumber;
+            interactivePort: import("zod").ZodOptional<import("zod").ZodNumber>;
+            networkPolicy: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodObject<{
                 mode: import("zod").ZodLiteral<"allow-all">;
-            }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
+            }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+                mode: import("zod").ZodLiteral<"allow-all">;
+            }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"allow-all">;
+            }, import("zod").ZodTypeAny, "passthrough">>, import("zod").ZodObject<{
                 mode: import("zod").ZodLiteral<"deny-all">;
-            }, import("zod").ZodTypeAny, "passthrough"> | import("zod").objectInputType<{
+            }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+                mode: import("zod").ZodLiteral<"deny-all">;
+            }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"deny-all">;
+            }, import("zod").ZodTypeAny, "passthrough">>, import("zod").ZodObject<{
                 mode: import("zod").ZodLiteral<"custom">;
                 allowedDomains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
                 allowedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
@@ -597,35 +641,75 @@ export declare class Sandbox {
                     headers?: Record<string, string> | undefined;
                     headerNames?: string[] | undefined;
                 }>, "many">>;
-            }, import("zod").ZodTypeAny, "passthrough"> | undefined;
-            activeCpuDurationMs?: number | undefined;
-            networkTransfer?: {
+            }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+                mode: import("zod").ZodLiteral<"custom">;
+                allowedDomains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                allowedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                deniedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                injectionRules: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                    domain: import("zod").ZodString;
+                    headers: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+                    headerNames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }>, "many">>;
+            }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+                mode: import("zod").ZodLiteral<"custom">;
+                allowedDomains: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                allowedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                deniedCIDRs: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                injectionRules: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                    domain: import("zod").ZodString;
+                    headers: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+                    headerNames: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }, {
+                    domain: string;
+                    headers?: Record<string, string> | undefined;
+                    headerNames?: string[] | undefined;
+                }>, "many">>;
+            }, import("zod").ZodTypeAny, "passthrough">>]>>;
+            activeCpuDurationMs: import("zod").ZodOptional<import("zod").ZodNumber>;
+            networkTransfer: import("zod").ZodOptional<import("zod").ZodObject<{
+                ingress: import("zod").ZodNumber;
+                egress: import("zod").ZodNumber;
+            }, "strip", import("zod").ZodTypeAny, {
                 ingress: number;
                 egress: number;
-            } | undefined;
-        }[];
+            }, {
+                ingress: number;
+                egress: number;
+            }>>;
+        }, import("zod").ZodTypeAny, "passthrough">[];
         pagination: {
             count: number;
-            next: number | null;
-            prev: number | null;
+            next: string | null;
         };
-    }>>;
+    }>;
     /**
-     * List snapshots that belong to this named sandbox.
+     * List snapshots that belong to this sandbox.
      *
      * @param params - Optional pagination parameters.
      * @returns The list of snapshots and pagination metadata.
      */
     listSnapshots(params?: {
         limit?: number;
-        since?: number | Date;
-        until?: number | Date;
+        cursor?: string;
+        sortOrder?: "asc" | "desc";
         signal?: AbortSignal;
-    }): Promise<import("./api-client/base-client").Parsed<{
+    }): Promise<{
         pagination: {
             count: number;
-            next: number | null;
-            prev: number | null;
+            next: string | null;
         };
         snapshots: {
             id: string;
@@ -633,9 +717,9 @@ export declare class Sandbox {
             status: "failed" | "created" | "deleted";
             createdAt: number;
             updatedAt: number;
-            sourceSandboxId: string;
+            sourceSessionId: string;
             sizeBytes: number;
             expiresAt?: number | undefined;
         }[];
-    }>>;
+    }>;
 }