@vercel/sandbox 0.0.21 → 0.0.23

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.21 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.23 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.21 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.23 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @vercel/sandbox
 
+## 0.0.23
+
+### Patch Changes
+
+- Add `Sandbox.extendTimeout()` ([#148](https://github.com/vercel/sandbox-sdk/pull/148))
+
+## 0.0.22
+
+### Patch Changes
+
+- add AbortSignal support in public interface ([#137](https://github.com/vercel/sandbox-sdk/pull/137))
+
+- add AbortSignal support to command.wait ([#136](https://github.com/vercel/sandbox-sdk/pull/136))
+
 ## 0.0.21
 
 ### Patch Changes

package/dist/api-client/api-client.d.ts

@@ -1,5 +1,5 @@
 import { BaseClient, type Parsed, type RequestParams } from "./base-client";
-import { SandboxResponse, CommandResponse, CommandFinishedResponse, LogLine } from "./validators";
+import { SandboxResponse, CommandResponse, CommandFinishedResponse, LogLine, ExtendTimeoutResponse } from "./validators";
 import { FileWriter } from "./file-writer";
 import { z } from "zod";
 import { WithPrivate } from "../utils/types";
@@ -15,6 +15,7 @@ export declare class APIClient extends BaseClient {
     protected request(path: string, params?: RequestParams): Promise<Response>;
     getSandbox(params: {
         sandboxId: string;
+        signal?: AbortSignal;
     }): Promise<Parsed<{
         sandbox: {
             region: string;
@@ -58,6 +59,7 @@ export declare class APIClient extends BaseClient {
             vcpus: number;
         };
         runtime?: "node22" | "python3.13" | (string & {});
+        signal?: AbortSignal;
     }>): Promise<Parsed<{
         sandbox: {
             region: string;
@@ -89,6 +91,7 @@ export declare class APIClient extends BaseClient {
         args: string[];
         env: Record<string, string>;
         sudo: boolean;
+        signal?: AbortSignal;
     }): Promise<Parsed<{
         command: {
             name: string;
@@ -104,20 +107,24 @@ export declare class APIClient extends BaseClient {
         sandboxId: string;
         cmdId: string;
         wait: true;
+        signal?: AbortSignal;
     }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
     getCommand(params: {
         sandboxId: string;
         cmdId: string;
         wait?: boolean;
+        signal?: AbortSignal;
     }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
     mkDir(params: {
         sandboxId: string;
         path: string;
         cwd?: string;
+        signal?: AbortSignal;
     }): Promise<Parsed<{}>>;
     getFileWriter(params: {
         sandboxId: string;
         extractDir: string;
+        signal?: AbortSignal;
     }): {
         response: Promise<Response>;
         writer: FileWriter;
@@ -143,6 +150,7 @@ export declare class APIClient extends BaseClient {
          * @example 1540095775951
          */
         until?: number | Date;
+        signal?: AbortSignal;
     }): Promise<Parsed<{
         sandboxes: {
             region: string;
@@ -175,16 +183,19 @@ export declare class APIClient extends BaseClient {
             content: Buffer;
         }[];
         extractDir: string;
+        signal?: AbortSignal;
     }): Promise<void>;
     readFile(params: {
         sandboxId: string;
         path: string;
         cwd?: string;
+        signal?: AbortSignal;
     }): Promise<NodeJS.ReadableStream | null>;
     killCommand(params: {
         sandboxId: string;
         commandId: string;
         signal: number;
+        abortSignal?: AbortSignal;
     }): Promise<Parsed<{
         command: {
             name: string;
@@ -205,5 +216,11 @@ export declare class APIClient extends BaseClient {
     };
     stopSandbox(params: {
         sandboxId: string;
+        signal?: AbortSignal;
     }): Promise<Parsed<z.infer<typeof SandboxResponse>>>;
+    extendTimeout(params: {
+        sandboxId: string;
+        duration: number;
+        signal?: AbortSignal;
+    }): Promise<Parsed<z.infer<typeof ExtendTimeoutResponse>>>;
 }

package/dist/api-client/api-client.js

@@ -53,7 +53,9 @@ class APIClient extends base_client_1.BaseClient {
         });
     }
     async getSandbox(params) {
-        return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request(`/v1/sandboxes/${params.sandboxId}`));
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request(`/v1/sandboxes/${params.sandboxId}`, {
+            signal: params.signal,
+        }));
     }
     async createSandbox(params) {
         const privateParams = (0, types_1.getPrivateParams)(params);
@@ -68,6 +70,7 @@ class APIClient extends base_client_1.BaseClient {
                 runtime: params.runtime,
                 ...privateParams,
             }),
+            signal: params.signal,
         }));
     }
     async runCommand(params) {
@@ -80,17 +83,19 @@ class APIClient extends base_client_1.BaseClient {
                 env: params.env,
                 sudo: params.sudo,
             }),
+            signal: params.signal,
         }));
     }
     async getCommand(params) {
         return params.wait
-            ? (0, base_client_1.parseOrThrow)(validators_1.CommandFinishedResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: "true" } }))
-            : (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`));
+            ? (0, base_client_1.parseOrThrow)(validators_1.CommandFinishedResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { signal: params.signal, query: { wait: "true" } }))
+            : (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { signal: params.signal }));
     }
     async mkDir(params) {
         return (0, base_client_1.parseOrThrow)(validators_1.EmptyResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
             method: "POST",
             body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+            signal: params.signal,
         }));
     }
     getFileWriter(params) {
@@ -104,6 +109,7 @@ class APIClient extends base_client_1.BaseClient {
                         "x-cwd": params.extractDir,
                     },
                     body: await (0, consume_readable_1.consumeReadable)(writer.readable),
+                    signal: params.signal,
                 });
             })(),
             writer,
@@ -122,12 +128,14 @@ class APIClient extends base_client_1.BaseClient {
                     : params.until?.getTime(),
             },
             method: "GET",
+            signal: params.signal,
         }));
     }
     async writeFiles(params) {
         const { writer, response } = this.getFileWriter({
             sandboxId: params.sandboxId,
             extractDir: params.extractDir,
+            signal: params.signal,
         });
         for (const file of params.files) {
             await writer.addFile({
@@ -146,6 +154,7 @@ class APIClient extends base_client_1.BaseClient {
         const response = await this.request(`/v1/sandboxes/${params.sandboxId}/fs/read`, {
             method: "POST",
             body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+            signal: params.signal,
         });
         if (response.status === 404) {
             return null;
@@ -159,6 +168,7 @@ class APIClient extends base_client_1.BaseClient {
         return (0, base_client_1.parseOrThrow)(validators_1.CommandResponse, await this.request(`/v1/sandboxes/${params.sandboxId}/${params.commandId}/kill`, {
             method: "POST",
             body: JSON.stringify({ signal: params.signal }),
+            signal: params.abortSignal,
         }));
     }
     getLogs(params) {
@@ -200,7 +210,15 @@ class APIClient extends base_client_1.BaseClient {
     }
     async stopSandbox(params) {
         const url = `/v1/sandboxes/${params.sandboxId}/stop`;
-        return (0, base_client_1.parseOrThrow)(validators_1.SandboxResponse, await this.request(url, { method: "POST" }));
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxResponse, await this.request(url, { method: "POST", signal: params.signal }));
+    }
+    async extendTimeout(params) {
+        const url = `/v1/sandboxes/${params.sandboxId}/extend-timeout`;
+        return (0, base_client_1.parseOrThrow)(validators_1.ExtendTimeoutResponse, await this.request(url, {
+            method: "POST",
+            body: JSON.stringify({ duration: params.duration }),
+            signal: params.signal,
+        }));
     }
 }
 exports.APIClient = APIClient;

package/dist/api-client/base-client.js

@@ -41,6 +41,7 @@ class BaseClient {
                 : opts?.headers,
             // @ts-expect-error Node.js' and undici's Agent have different types
             dispatcher: this.agent,
+            signal: opts?.signal,
         });
         if (this.debug) {
             const duration = Date.now() - start;

package/dist/api-client/validators.d.ts

@@ -540,3 +540,90 @@ export declare const SandboxesResponse: z.ZodObject<{
         prev: number | null;
     };
 }>;
+export declare const ExtendTimeoutResponse: z.ZodObject<{
+    sandbox: z.ZodObject<{
+        id: z.ZodString;
+        memory: z.ZodNumber;
+        vcpus: z.ZodNumber;
+        region: z.ZodString;
+        runtime: z.ZodString;
+        timeout: z.ZodNumber;
+        status: z.ZodEnum<["pending", "running", "stopping", "stopped", "failed"]>;
+        requestedAt: z.ZodNumber;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        requestedStopAt: z.ZodOptional<z.ZodNumber>;
+        stoppedAt: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodNumber;
+        cwd: z.ZodString;
+        updatedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        timeout: number;
+        cwd: string;
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        requestedAt: number;
+        createdAt: number;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }, {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        timeout: number;
+        cwd: string;
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        requestedAt: number;
+        createdAt: number;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    sandbox: {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        timeout: number;
+        cwd: string;
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        requestedAt: number;
+        createdAt: number;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    };
+}, {
+    sandbox: {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        timeout: number;
+        cwd: string;
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        requestedAt: number;
+        createdAt: number;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    };
+}>;

package/dist/api-client/validators.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxesResponse = exports.LogLine = exports.EmptyResponse = exports.CommandFinishedResponse = exports.CommandResponse = exports.SandboxAndRoutesResponse = exports.SandboxResponse = exports.Command = exports.Pagination = exports.SandboxRoute = exports.Sandbox = void 0;
+exports.ExtendTimeoutResponse = exports.SandboxesResponse = exports.LogLine = exports.EmptyResponse = exports.CommandFinishedResponse = exports.CommandResponse = exports.SandboxAndRoutesResponse = exports.SandboxResponse = exports.Command = exports.Pagination = exports.SandboxRoute = exports.Sandbox = void 0;
 const zod_1 = require("zod");
 exports.Sandbox = zod_1.z.object({
     id: zod_1.z.string(),
@@ -74,3 +74,6 @@ exports.SandboxesResponse = zod_1.z.object({
     sandboxes: zod_1.z.array(exports.Sandbox),
     pagination: exports.Pagination,
 });
+exports.ExtendTimeoutResponse = zod_1.z.object({
+    sandbox: exports.Sandbox,
+});

package/dist/command.d.ts

@@ -88,9 +88,13 @@ export declare class Command {
      * }
      * ```
      *
+     * @param params - Optional parameters.
+     * @param params.signal - An AbortSignal to cancel waiting.
      * @returns A {@link CommandFinished} instance with populated exit code.
      */
-    wait(): Promise<CommandFinished>;
+    wait(params?: {
+        signal?: AbortSignal;
+    }): Promise<CommandFinished>;
     /**
      * Get the output of `stdout`, `stderr`, or both as a string.
      *
@@ -98,35 +102,50 @@ export declare class Command {
      * not output valid Unicode.
      *
      * @param stream - The output stream to read: "stdout", "stderr", or "both".
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The output of the specified stream(s) as a string.
      */
-    output(stream?: "stdout" | "stderr" | "both"): Promise<string>;
+    output(stream?: "stdout" | "stderr" | "both", opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
     /**
      * Get the output of `stdout` as a string.
      *
      * NOTE: This may throw string conversion errors if the command does
      * not output valid Unicode.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The standard output of the command.
      */
-    stdout(): Promise<string>;
+    stdout(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
     /**
      * Get the output of `stderr` as a string.
      *
      * NOTE: This may throw string conversion errors if the command does
      * not output valid Unicode.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The standard error output of the command.
      */
-    stderr(): Promise<string>;
+    stderr(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
     /**
      * Kill a running command in a sandbox.
      *
-     * @param params - commandId and the signal to send the running process.
-     * Defaults to SIGTERM.
+     * @param signal - The signal to send the running process. Defaults to SIGTERM.
+     * @param opts - Optional parameters.
+     * @param opts.abortSignal - An AbortSignal to cancel the kill operation.
      * @returns Promise<void>.
      */
-    kill(signal?: Signal): Promise<void>;
+    kill(signal?: Signal, opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
 }
 /**
  * A command that has finished executing.

package/dist/command.js

@@ -82,13 +82,17 @@ class Command {
      * }
      * ```
      *
+     * @param params - Optional parameters.
+     * @param params.signal - An AbortSignal to cancel waiting.
      * @returns A {@link CommandFinished} instance with populated exit code.
      */
-    async wait() {
+    async wait(params) {
+        params?.signal?.throwIfAborted();
         const command = await this.client.getCommand({
             sandboxId: this.sandboxId,
             cmdId: this.cmd.id,
             wait: true,
+            signal: params?.signal,
         });
         return new CommandFinished({
             client: this.client,
@@ -104,11 +108,13 @@ class Command {
      * not output valid Unicode.
      *
      * @param stream - The output stream to read: "stdout", "stderr", or "both".
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The output of the specified stream(s) as a string.
      */
-    async output(stream = "both") {
+    async output(stream = "both", opts) {
         let data = "";
-        for await (const log of this.logs()) {
+        for await (const log of this.logs({ signal: opts?.signal })) {
             if (stream === "both" || log.stream === stream) {
                 data += log.data;
             }
@@ -121,10 +127,12 @@ class Command {
      * NOTE: This may throw string conversion errors if the command does
      * not output valid Unicode.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The standard output of the command.
      */
-    async stdout() {
-        return this.output("stdout");
+    async stdout(opts) {
+        return this.output("stdout", opts);
     }
     /**
      * Get the output of `stderr` as a string.
@@ -132,23 +140,27 @@ class Command {
      * NOTE: This may throw string conversion errors if the command does
      * not output valid Unicode.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel output streaming.
      * @returns The standard error output of the command.
      */
-    async stderr() {
-        return this.output("stderr");
+    async stderr(opts) {
+        return this.output("stderr", opts);
     }
     /**
      * Kill a running command in a sandbox.
      *
-     * @param params - commandId and the signal to send the running process.
-     * Defaults to SIGTERM.
+     * @param signal - The signal to send the running process. Defaults to SIGTERM.
+     * @param opts - Optional parameters.
+     * @param opts.abortSignal - An AbortSignal to cancel the kill operation.
      * @returns Promise<void>.
      */
-    async kill(signal) {
+    async kill(signal, opts) {
         await this.client.killCommand({
             sandboxId: this.sandboxId,
             commandId: this.cmd.id,
             signal: (0, resolveSignal_1.resolveSignal)(signal ?? "SIGTERM"),
+            abortSignal: opts?.abortSignal,
         });
     }
 }

package/dist/sandbox.d.ts

@@ -54,6 +54,10 @@ export interface CreateSandboxParams {
      * If not specified, the default runtime `node22` will be used.
      */
     runtime?: "node22" | "python3.13" | (string & {});
+    /**
+     * An AbortSignal to cancel sandbox creation.
+     */
+    signal?: AbortSignal;
 }
 /** @inline */
 interface GetSandboxParams {
@@ -61,6 +65,10 @@ interface GetSandboxParams {
      * Unique identifier of the sandbox.
      */
     sandboxId: string;
+    /**
+     * An AbortSignal to cancel the operation.
+     */
+    signal?: AbortSignal;
 }
 /** @inline */
 interface RunCommandParams {
@@ -96,6 +104,10 @@ interface RunCommandParams {
      * A `Writable` stream where `stderr` from the command will be piped
      */
     stderr?: Writable;
+    /**
+     * An AbortSignal to cancel the command execution
+     */
+    signal?: AbortSignal;
 }
 /**
  * A Sandbox is an isolated Linux MicroVM to run commands in.
@@ -118,10 +130,14 @@ export declare class Sandbox {
      * The status of the sandbox.
      */
     get status(): SandboxMetaData["status"];
+    /**
+     * The timeout of the sandbox in milliseconds.
+     */
+    get timeout(): number;
     /**
      * Internal metadata about this sandbox.
      */
-    private readonly sandbox;
+    private sandbox;
     /**
      * Allow to get a list of sandboxes for a team narrowed to the given params.
      * It returns both the sandboxes and the pagination metadata to allow getting
@@ -181,17 +197,25 @@ export declare class Sandbox {
      * Get a previously run command by its ID.
      *
      * @param cmdId - ID of the command to retrieve
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A {@link Command} instance representing the command
      */
-    getCommand(cmdId: string): Promise<Command>;
+    getCommand(cmdId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Command>;
     /**
      * Start executing a command in this sandbox.
      *
      * @param command - The command to execute.
      * @param args - Arguments to pass to the command.
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the command execution.
      * @returns A {@link CommandFinished} result once execution is done.
      */
-    runCommand(command: string, args?: string[]): Promise<CommandFinished>;
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<CommandFinished>;
     /**
      * Start executing a command in detached mode.
      *
@@ -220,17 +244,25 @@ export declare class Sandbox {
      * Create a directory in the filesystem of this sandbox.
      *
      * @param path - Path of the directory to create
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      */
-    mkDir(path: string): Promise<void>;
+    mkDir(path: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * Read a file from the filesystem of this sandbox.
      *
      * @param file - File to read, with path and optional cwd
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves to a ReadableStream containing the file contents
      */
     readFile(file: {
         path: string;
         cwd?: string;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<NodeJS.ReadableStream | null>;
     /**
      * Write files to the filesystem of this sandbox.
@@ -238,12 +270,16 @@ export declare class Sandbox {
      * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the files are written
      */
     writeFiles(files: {
         path: string;
         content: Buffer;
-    }[]): Promise<void>;
+    }[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * Get the public domain of a port of this sandbox.
      *
@@ -255,8 +291,26 @@ export declare class Sandbox {
     /**
      * Stop the sandbox.
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
      * @returns A promise that resolves when the sandbox is stopped
      */
-    stop(): Promise<void>;
+    stop(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Extend the timeout of the sandbox by the specified duration.
+     *
+     * This allows you to extend the lifetime of a sandbox up until the maximum
+     * execution timeout for your plan.
+     *
+     * @param duration - The duration in milliseconds to extend the timeout by
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel the operation.
+     * @returns A promise that resolves when the timeout is extended
+     */
+    extendTimeout(duration: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 export {};