@vercel/sandbox 0.0.4 → 0.0.6

package/dist/sandbox.d.ts

@@ -0,0 +1,201 @@
+import { Readable, type Writable } from "stream";
+import { APIClient } from "./api-client";
+import { Command, CommandFinished } from "./command";
+import { type Credentials } from "./utils/get-credentials";
+/** @inline */
+export interface CreateSandboxParams {
+    /**
+     * The source of the sandbox.
+     *
+     * Omit this parameter start a sandbox without a source.
+     */
+    source?: {
+        type: "git";
+        url: string;
+    } | {
+        type: "tarball";
+        url: string;
+    };
+    /**
+     * Array of port numbers to expose from the sandbox.
+     */
+    ports?: number[];
+    /**
+     * Timeout in milliseconds before the sandbox auto-terminates.
+     */
+    timeout?: number;
+    /**
+     * Resources to allocate to the sandbox.
+     *
+     * Your sandbox will get the amount of cores you specify here. For memory,
+     * you will get double the amount of cores.
+     */
+    resources?: {
+        cores: number;
+    };
+}
+/** @inline */
+interface GetSandboxParams {
+    /**
+     * Port-to-subdomain route mappings.
+     */
+    routes: Array<{
+        subdomain: string;
+        port: number;
+    }>;
+    /**
+     * Unique identifier of the sandbox.
+     */
+    sandboxId: string;
+}
+/** @inline */
+interface RunCommandParams {
+    /**
+     * The command to execute
+     */
+    cmd: string;
+    /**
+     * Arguments to pass to the command
+     */
+    args?: string[];
+    /**
+     * Working directory to execute the command in
+     */
+    cwd?: string;
+    /**
+     * Environment variables to set for this command
+     */
+    env?: Record<string, string>;
+    /**
+     * If true, the command will return without waiting for `exitCode`
+     */
+    detached?: boolean;
+    /**
+     * A `Writable` stream where `stdout` from the command will be piped
+     */
+    stdout?: Writable;
+    /**
+     * A `Writable` stream where `stderr` from the command will be piped
+     */
+    stderr?: Writable;
+}
+/**
+ * A Sandbox is an isolated Linux MicroVM to run commands in.
+ *
+ * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
+ * @hideconstructor
+ */
+export declare class Sandbox {
+    private readonly client;
+    /**
+     * Routes from ports to subdomains.
+    /* @hidden
+     */
+    readonly routes: {
+        subdomain: string;
+        port: number;
+    }[];
+    /**
+     * Unique ID of this sandbox.
+     */
+    readonly sandboxId: string;
+    /**
+     * Create a new sandbox.
+     *
+     * @param params - Creation parameters and optional credentials.
+     * @returns A promise resolving to the created {@link Sandbox}.
+     */
+    static create(params?: CreateSandboxParams | (CreateSandboxParams & Credentials)): Promise<Sandbox>;
+    /**
+     * Retrieve an existing sandbox.
+     *
+     * @param params - Get parameters and optional credentials.
+     * @returns A promise resolving to the {@link Sandbox}.
+     */
+    static get(params: GetSandboxParams | (GetSandboxParams & Credentials)): Promise<Sandbox>;
+    /**
+     * Create a new Sandbox instance.
+     *
+     * @param client - API client used to communicate with the backend
+     * @param routes - Port-to-subdomain mappings for exposed ports
+     * @param sandboxId - Unique identifier for the sandbox
+     */
+    constructor({ client, routes, sandboxId, }: {
+        client: APIClient;
+        routes: {
+            subdomain: string;
+            port: number;
+        }[];
+        sandboxId: string;
+    });
+    /**
+     * Get a previously run command by its ID.
+     *
+     * @param cmdId - ID of the command to retrieve
+     * @returns A {@link Command} instance representing the command
+     */
+    getCommand(cmdId: string): Command;
+    /**
+     * Start executing a command in this sandbox.
+     *
+     * @param command - The command to execute.
+     * @param args - Arguments to pass to the command.
+     * @returns A {@link CommandFinished} result once execution is done.
+     */
+    runCommand(command: string, args?: string[]): Promise<CommandFinished>;
+    /**
+     * Start executing a command in detached mode.
+     *
+     * @param params - The command parameters.
+     * @returns A {@link Command} instance for the running command.
+     */
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    /**
+     * Start executing a command in this sandbox.
+     *
+     * @param params - The command parameters.
+     * @returns A {@link CommandFinished} result once execution is done.
+     */
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    /**
+     * Internal helper to start a command in the sandbox.
+     *
+     * @param params - Command execution parameters.
+     * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
+     * @internal
+     */
+    _runCommand(params: RunCommandParams): Promise<CommandFinished | Command>;
+    /**
+     * Create a directory in the filesystem of this sandbox.
+     *
+     * @param path - Path of the directory to create
+     */
+    mkDir(path: string): Promise<void>;
+    /**
+     * Write files to the filesystem of this sandbox.
+     *
+     * @param files - Array of files with path and stream/buffer contents
+     * @returns A promise that resolves when the files are written
+     */
+    writeFiles(files: {
+        path: string;
+        stream: Readable | Buffer;
+    }[]): Promise<void>;
+    /**
+     * Get the public domain of a port of this sandbox.
+     *
+     * @param p - Port number to resolve
+     * @returns A full domain (e.g. `https://subdomain.vercel.run`)
+     * @throws If the port has no associated route
+     */
+    domain(p: number): string;
+    /**
+     * Stop the sandbox.
+     *
+     * @returns A promise that resolves when the sandbox is stopped
+     */
+    stop(): Promise<void>;
+}
+export {};

package/dist/sandbox.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sandbox = void 0;
+const api_client_1 = require("./api-client");
+const command_1 = require("./command");
+const get_credentials_1 = require("./utils/get-credentials");
+/**
+ * A Sandbox is an isolated Linux MicroVM to run commands in.
+ *
+ * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
+ * @hideconstructor
+ */
+class Sandbox {
+    /**
+     * Create a new sandbox.
+     *
+     * @param params - Creation parameters and optional credentials.
+     * @returns A promise resolving to the created {@link Sandbox}.
+     */
+    static async create(params) {
+        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const client = new api_client_1.APIClient({
+            teamId: credentials.teamId,
+            token: credentials.token,
+        });
+        const sandbox = await client.createSandbox({
+            source: params?.source,
+            projectId: credentials.projectId,
+            ports: params?.ports ?? [],
+            timeout: params?.timeout,
+            ...(params?.resources && {
+                cores: params.resources.cores,
+                memory: 2048 * params.resources.cores,
+            }),
+        });
+        return new Sandbox({
+            client,
+            sandboxId: sandbox.json.sandboxId,
+            routes: sandbox.json.routes,
+        });
+    }
+    /**
+     * Retrieve an existing sandbox.
+     *
+     * @param params - Get parameters and optional credentials.
+     * @returns A promise resolving to the {@link Sandbox}.
+     */
+    static async get(params) {
+        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const client = new api_client_1.APIClient({
+            teamId: credentials.teamId,
+            token: credentials.token,
+        });
+        return new Sandbox({
+            client,
+            sandboxId: params.sandboxId,
+            routes: params.routes,
+        });
+    }
+    /**
+     * Create a new Sandbox instance.
+     *
+     * @param client - API client used to communicate with the backend
+     * @param routes - Port-to-subdomain mappings for exposed ports
+     * @param sandboxId - Unique identifier for the sandbox
+     */
+    constructor({ client, routes, sandboxId, }) {
+        this.client = client;
+        this.routes = routes;
+        this.sandboxId = sandboxId;
+    }
+    /**
+     * Get a previously run command by its ID.
+     *
+     * @param cmdId - ID of the command to retrieve
+     * @returns A {@link Command} instance representing the command
+     */
+    getCommand(cmdId) {
+        return new command_1.Command({
+            client: this.client,
+            sandboxId: this.sandboxId,
+            cmdId,
+        });
+    }
+    async runCommand(commandOrParams, args) {
+        return typeof commandOrParams === "string"
+            ? this._runCommand({ cmd: commandOrParams, args })
+            : this._runCommand(commandOrParams);
+    }
+    /**
+     * Internal helper to start a command in the sandbox.
+     *
+     * @param params - Command execution parameters.
+     * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
+     * @internal
+     */
+    async _runCommand(params) {
+        const commandResponse = await this.client.runCommand({
+            sandboxId: this.sandboxId,
+            command: params.cmd,
+            args: params.args ?? [],
+            cwd: params.cwd,
+            env: params.env ?? {},
+        });
+        const command = new command_1.Command({
+            client: this.client,
+            sandboxId: this.sandboxId,
+            cmdId: commandResponse.json.cmdId,
+        });
+        if (params.stdout || params.stderr) {
+            (async () => {
+                for await (const log of command.logs()) {
+                    if (log.stream === "stdout") {
+                        params.stdout?.write(log.data);
+                    }
+                    else if (log.stream === "stderr") {
+                        params.stderr?.write(log.data);
+                    }
+                }
+            })();
+        }
+        return params.detached ? command : command.wait();
+    }
+    /**
+     * Create a directory in the filesystem of this sandbox.
+     *
+     * @param path - Path of the directory to create
+     */
+    async mkDir(path) {
+        await this.client.mkDir({
+            sandboxId: this.sandboxId,
+            path: path,
+        });
+    }
+    /**
+     * Write files to the filesystem of this sandbox.
+     *
+     * @param files - Array of files with path and stream/buffer contents
+     * @returns A promise that resolves when the files are written
+     */
+    async writeFiles(files) {
+        return this.client.writeFiles({
+            sandboxId: this.sandboxId,
+            files: files,
+        });
+    }
+    /**
+     * Get the public domain of a port of this sandbox.
+     *
+     * @param p - Port number to resolve
+     * @returns A full domain (e.g. `https://subdomain.vercel.run`)
+     * @throws If the port has no associated route
+     */
+    domain(p) {
+        const route = this.routes.find(({ port }) => port == p);
+        if (route) {
+            return `https://${route.subdomain}.vercel.run`;
+        }
+        else {
+            throw new Error(`No route for port ${p}`);
+        }
+    }
+    /**
+     * Stop the sandbox.
+     *
+     * @returns A promise that resolves when the sandbox is stopped
+     */
+    async stop() {
+        await this.client.stopSandbox({
+            sandboxId: this.sandboxId,
+        });
+    }
+}
+exports.Sandbox = Sandbox;

package/dist/utils/decode-base64-url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Decode a Base64 URL-encoded string into a JSON object.
+ *
+ * @param base64Url - The Base64 URL-encoded string to decode.
+ * @returns The decoded JSON object or null if decoding fails.
+ */
+export declare function decodeBase64Url(base64Url: string): any;

package/dist/utils/decode-base64-url.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeBase64Url = decodeBase64Url;
+/**
+ * Decode a Base64 URL-encoded string into a JSON object.
+ *
+ * @param base64Url - The Base64 URL-encoded string to decode.
+ * @returns The decoded JSON object or null if decoding fails.
+ */
+function decodeBase64Url(base64Url) {
+    return JSON.parse(Buffer.from(base64Url.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+}

package/dist/utils/get-credentials.d.ts

@@ -0,0 +1,26 @@
+export interface Credentials {
+    /**
+     * Authentication token for the Vercel API. It could be an OIDC token
+     * or a personal access token.
+     */
+    token: string;
+    /**
+     * The ID of the project to associate Sandbox operations.
+     */
+    projectId: string;
+    /**
+     * The ID of the team to associate Sandbox operations.
+     */
+    teamId: string;
+}
+/**
+ * Allow to get credentials to access the Vercel API. Credentials can be
+ * provided in two different ways:
+ *
+ * 1. By passing an object with the `teamId`, `token`, and `projectId` properties.
+ * 2. By using an environment variable VERCEL_OIDC_TOKEN.
+ *
+ * If both methods are used, the object properties take precedence over the
+ * environment variable. If neither method is used, an error is thrown.
+ */
+export declare function getCredentials<T>(params?: T | Credentials): Credentials;

package/dist/utils/get-credentials.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCredentials = getCredentials;
+const get_vercel_oidc_token_1 = require("./get-vercel-oidc-token");
+const decode_base64_url_1 = require("./decode-base64-url");
+const zod_1 = require("zod");
+/**
+ * Allow to get credentials to access the Vercel API. Credentials can be
+ * provided in two different ways:
+ *
+ * 1. By passing an object with the `teamId`, `token`, and `projectId` properties.
+ * 2. By using an environment variable VERCEL_OIDC_TOKEN.
+ *
+ * If both methods are used, the object properties take precedence over the
+ * environment variable. If neither method is used, an error is thrown.
+ */
+function getCredentials(params) {
+    const credentials = getCredentialsFromParams(params ?? {});
+    if (credentials) {
+        return credentials;
+    }
+    const oidcToken = (0, get_vercel_oidc_token_1.getVercelOidcToken)();
+    if (oidcToken) {
+        return getCredentialsFromOIDCToken(oidcToken);
+    }
+    throw new Error("You must provide credentials to access the Vercel API \n" +
+        "either through parameters or using OpenID Connect [https://vercel.com/docs/oidc]");
+}
+/**
+ * Attempt to extract credentials from the provided parameters. Either all
+ * required fields (`token`, `teamId`, and `projectId`) must be present
+ * or none of them, otherwise an error is thrown.
+ */
+function getCredentialsFromParams(params) {
+    const missing = [
+        "token" in params && typeof params.token === "string" ? null : "token",
+        "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
+        "projectId" in params && typeof params.projectId === "string"
+            ? null
+            : "projectId",
+    ].filter((value) => value !== null);
+    if (missing.length === 0) {
+        return {
+            token: params.token,
+            projectId: params.projectId,
+            teamId: params.teamId,
+        };
+    }
+    if (missing.length < 3) {
+        throw new Error(`Missing credentials parameters to access the Vercel API: ${missing
+            .filter((value) => value !== null)
+            .join(", ")}`);
+    }
+    return null;
+}
+/**
+ * Schema to validate the payload of the Vercel OIDC token where we expect
+ * to find the `teamId` and `projectId`.
+ */
+const schema = zod_1.z.object({
+    owner_id: zod_1.z.string(),
+    project_id: zod_1.z.string(),
+});
+/**
+ * Extracts credentials from a Vercel OIDC token. The token is expected to be
+ * a JWT with a payload that contains `project_id` and `owner_id`.
+ *
+ * @param token - The Vercel OIDC token.
+ * @returns An object containing the token, projectId, and teamId.
+ * @throws If the token is invalid or does not contain the required fields.
+ */
+function getCredentialsFromOIDCToken(token) {
+    try {
+        const payload = schema.parse((0, decode_base64_url_1.decodeBase64Url)(token.split(".")[1]));
+        return {
+            token,
+            projectId: payload.project_id,
+            teamId: payload.owner_id,
+        };
+    }
+    catch (error) {
+        throw new Error(`Invalid Vercel OIDC token: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/utils/get-vercel-oidc-token.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This function is implemented in @vercel/functions but it is asynchronous.
+ * In order to keep it synchronous, we are implementing it here as well.
+ * Ideally we should remove this and use the one from @vercel/functions.
+ */
+export declare function getVercelOidcToken(): string | undefined;

package/dist/utils/get-vercel-oidc-token.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVercelOidcToken = getVercelOidcToken;
+/**
+ * This function is implemented in @vercel/functions but it is asynchronous.
+ * In order to keep it synchronous, we are implementing it here as well.
+ * Ideally we should remove this and use the one from @vercel/functions.
+ */
+function getVercelOidcToken() {
+    const token = getContext().headers?.["x-vercel-oidc-token"] ??
+        process.env.VERCEL_OIDC_TOKEN;
+    if (!token && process.env.NODE_ENV === "production") {
+        throw new Error(`The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`);
+    }
+    return token;
+}
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+function getContext() {
+    const fromSymbol = globalThis;
+    return fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.4";
+export declare const VERSION = "0.0.6";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.4";
+exports.VERSION = "0.0.6";

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "private": false,
   "keywords": [],
   "author": "",
   "license": "ISC",
@@ -11,20 +12,26 @@
     "async-retry": "1.3.3",
     "form-data": "3.0.0",
     "jsonlines": "0.1.1",
+    "lru-cache": "11.1.0",
+    "ms": "2.1.3",
     "node-fetch": "2.6.11",
     "zod": "3.24.4"
   },
   "devDependencies": {
     "@types/async-retry": "1.4.9",
     "@types/jsonlines": "0.1.5",
+    "@types/ms": "2.1.0",
     "@types/node": "22.15.12",
     "@types/node-fetch": "2.6.12",
-    "typedoc": "^0.28.4",
-    "typescript": "5.8.3"
+    "dotenv": "16.5.0",
+    "typedoc": "0.28.5",
+    "typescript": "5.8.3",
+    "vitest": "3.2.1"
   },
   "scripts": {
     "clean": "rm -rf node_modules dist",
     "build": "tsc",
+    "test": "vitest run",
     "typedoc": "typedoc",
     "typecheck": "tsc --noEmit",
     "inject-version": "ts-node scripts/inject-version.ts"