@vercel/sandbox 0.0.1

package/dist/create-sandbox.d.ts

@@ -0,0 +1,175 @@
+import { SandboxClient } from "./client/client";
+import { Readable } from "stream";
+/**
+ * Create a new instance of the SandboxSDK.
+ *
+ * ````
+ * const teamId = process.env.VERCEL_TEAM_ID
+ * const token = process.env.VERCEL_TOKEN
+ * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
+ * ````
+ *
+ * @see {@link createSandbox} to start a sandbox.
+ */
+export declare class SandboxSDK {
+    client: SandboxClient;
+    constructor({ teamId, token }: {
+        teamId: string;
+        token: string;
+    });
+    /**
+     * Create a new Sandbox with the given resources, source code, and ports.
+     *
+     * Upon start, the sandbox will perform a `git clone` of the repository given.
+     * This repo needs to be public.
+     *
+     * @param params
+     * @returns a
+     */
+    createSandbox(params: {
+        source: {
+            type: "git";
+            url: string;
+        };
+        ports: number[];
+        timeout?: number;
+    }): Promise<Sandbox>;
+    /** @hidden */
+    getSandbox({ routes, sandboxId, }: {
+        routes: {
+            subdomain: string;
+            port: number;
+        }[];
+        sandboxId: string;
+    }): Promise<Sandbox>;
+}
+/**
+ * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
+ *
+ * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @hideconstructor
+ */
+export declare class Sandbox {
+    private client;
+    /** @hidden */
+    routes: {
+        subdomain: string;
+        port: number;
+    }[];
+    /**
+     * The ID of this sandbox.
+     */
+    sandboxId: string;
+    constructor({ client, routes, sandboxId, }: {
+        client: SandboxClient;
+        routes: {
+            subdomain: string;
+            port: number;
+        }[];
+        sandboxId: string;
+    });
+    /**
+     * Start executing a command in this sandbox.
+     * @param command
+     * @param args
+     * @returns
+     */
+    runCommand(command: string, args?: string[]): Promise<Command>;
+    /**
+     * Write files to the filesystem of this sandbox.
+     */
+    writeFiles(files: {
+        path: string;
+        stream: Readable | Buffer;
+    }[]): Promise<void>;
+    /**
+     * Get the public domain of a port of this sandbox.
+     *
+     * E.g. `2grza2l7imxe.vercel.run`
+     */
+    domain(p: number): string;
+}
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+export declare class Command {
+    private client;
+    private sandboxId;
+    /**
+     * ID of the command execution.
+     */
+    cmdId: string;
+    /**
+     * The exit code of the command, if available. This is set after
+     * {@link wait} has returned.
+     */
+    exitCode: number | null;
+    constructor({ client, sandboxId, cmdId, }: {
+        client: SandboxClient;
+        sandboxId: string;
+        cmdId: string;
+    });
+    /**
+     * Iterate over the output of this command.
+     *
+     * ```
+     * for await (const log of cmd.logs()) {
+     *   if (log.stream === "stdout") {
+     *     process.stdout.write(log.data);
+     *   } else {
+     *     process.stderr.write(log.data);
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+     * to access output as a string.
+     */
+    logs(): AsyncGenerator<{
+        data: string;
+        stream: "stdout" | "stderr";
+    }, void, void>;
+    /**
+     * Wait for a command to exit and populate it's exit code.
+     *
+     * ```
+     * await cmd.wait()
+     * if (cmd.exitCode != 0) {
+     *   console.error("Something went wrong...")
+     * }
+     * ````
+     */
+    wait(): Promise<this>;
+    /**
+     * Print command logs to stdout/stderr
+     */
+    printLogs(): Promise<void>;
+    /**
+     * Get the output of `stdout` or `stderr` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    output(stream?: "stdout" | "stderr" | "both"): Promise<string>;
+    /**
+     * Get the output of `stdout` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    stdout(): Promise<string>;
+    /**
+     * Get the output of `stderr` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    stderr(): Promise<string>;
+}

package/dist/create-sandbox.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = exports.Sandbox = exports.SandboxSDK = void 0;
+const client_1 = require("./client/client");
+/**
+ * Create a new instance of the SandboxSDK.
+ *
+ * ````
+ * const teamId = process.env.VERCEL_TEAM_ID
+ * const token = process.env.VERCEL_TOKEN
+ * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
+ * ````
+ *
+ * @see {@link createSandbox} to start a sandbox.
+ */
+class SandboxSDK {
+    constructor({ teamId, token }) {
+        this.client = new client_1.SandboxClient({ teamId, token });
+    }
+    /**
+     * Create a new Sandbox with the given resources, source code, and ports.
+     *
+     * Upon start, the sandbox will perform a `git clone` of the repository given.
+     * This repo needs to be public.
+     *
+     * @param params
+     * @returns a
+     */
+    async createSandbox(params) {
+        const { client } = this;
+        const sandbox = await client.createSandbox({
+            source: params.source,
+            ports: params.ports,
+            timeout: params.timeout,
+        });
+        return new Sandbox({
+            client,
+            sandboxId: sandbox.json.sandboxId,
+            routes: sandbox.json.routes,
+        });
+    }
+    /** @hidden */
+    async getSandbox({ routes, sandboxId, }) {
+        return new Sandbox({
+            client: this.client,
+            sandboxId: sandboxId,
+            routes: routes,
+        });
+    }
+}
+exports.SandboxSDK = SandboxSDK;
+/**
+ * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
+ *
+ * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @hideconstructor
+ */
+class Sandbox {
+    constructor({ client, routes, sandboxId, }) {
+        this.client = client;
+        this.routes = routes;
+        this.sandboxId = sandboxId;
+    }
+    /**
+     * Start executing a command in this sandbox.
+     * @param command
+     * @param args
+     * @returns
+     */
+    async runCommand(command, args = []) {
+        const commandResponse = await this.client.runCommand({
+            sandboxId: this.sandboxId,
+            command,
+            args,
+        });
+        return new Command({
+            client: this.client,
+            sandboxId: this.sandboxId,
+            cmdId: commandResponse.json.cmdId,
+        });
+    }
+    /**
+     * Write files to the filesystem of this sandbox.
+     */
+    async writeFiles(files) {
+        return this.client.writeFiles({
+            sandboxId: this.sandboxId,
+            files: files,
+        });
+    }
+    /**
+     * Get the public domain of a port of this sandbox.
+     *
+     * E.g. `2grza2l7imxe.vercel.run`
+     */
+    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}`);
+        }
+    }
+}
+exports.Sandbox = Sandbox;
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+class Command {
+    constructor({ client, sandboxId, cmdId, }) {
+        this.client = client;
+        this.sandboxId = sandboxId;
+        this.cmdId = cmdId;
+        this.exitCode = null;
+    }
+    /**
+     * Iterate over the output of this command.
+     *
+     * ```
+     * for await (const log of cmd.logs()) {
+     *   if (log.stream === "stdout") {
+     *     process.stdout.write(log.data);
+     *   } else {
+     *     process.stderr.write(log.data);
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
+     * to access output as a string.
+     */
+    logs() {
+        return this.client.getLogs({
+            sandboxId: this.sandboxId,
+            cmdId: this.cmdId,
+        });
+    }
+    /**
+     * Wait for a command to exit and populate it's exit code.
+     *
+     * ```
+     * await cmd.wait()
+     * if (cmd.exitCode != 0) {
+     *   console.error("Something went wrong...")
+     * }
+     * ````
+     */
+    async wait() {
+        const command = await this.client.getCommand({
+            sandboxId: this.sandboxId,
+            cmdId: this.cmdId,
+            wait: true,
+        });
+        this.exitCode = command.json.exitCode;
+        return this;
+    }
+    /**
+     * Print command logs to stdout/stderr
+     */
+    async printLogs() {
+        for await (const log of this.logs()) {
+            if (log.stream === "stdout") {
+                process.stdout.write(log.data);
+            }
+            else {
+                process.stderr.write(log.data);
+            }
+        }
+    }
+    /**
+     * Get the output of `stdout` or `stderr` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    async output(stream = "both") {
+        let data = "";
+        for await (const log of this.logs()) {
+            if (log.stream === stream) {
+                data += log.data;
+            }
+        }
+        return data;
+    }
+    /**
+     * Get the output of `stdout` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    async stdout() {
+        return this.output("stdout");
+    }
+    /**
+     * Get the output of `stderr` as a string.
+     *
+     * NOTE: This may error with string conversion errors if the command does
+     * not ouptut valid unicode.
+     */
+    async stderr() {
+        return this.output("stderr");
+    }
+}
+exports.Command = Command;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SandboxSDK, Sandbox, Command } from "./create-sandbox";
+export { SandboxClient } from "./client/client";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxClient = exports.Command = exports.Sandbox = exports.SandboxSDK = void 0;
+var create_sandbox_1 = require("./create-sandbox");
+Object.defineProperty(exports, "SandboxSDK", { enumerable: true, get: function () { return create_sandbox_1.SandboxSDK; } });
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return create_sandbox_1.Sandbox; } });
+Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return create_sandbox_1.Command; } });
+var client_1 = require("./client/client");
+Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_1.SandboxClient; } });

package/dist/utils/array.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns an array from the given item. If the  item is an array it will be
+ * returned as a it is, otherwise it will be returned as a single item array.
+ * If the item is undefined or null an empty array will be returned.
+ *
+ * @param item The item to convert to an array.
+ * @returns An array.
+ */
+export declare function array<T>(item?: null | T | T[]): T[];

package/dist/utils/array.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.array = array;
+/**
+ * Returns an array from the given item. If the  item is an array it will be
+ * returned as a it is, otherwise it will be returned as a single item array.
+ * If the item is undefined or null an empty array will be returned.
+ *
+ * @param item The item to convert to an array.
+ * @returns An array.
+ */
+function array(item) {
+    return item !== undefined && item !== null
+        ? Array.isArray(item)
+            ? item
+            : [item]
+        : [];
+}

package/dist/utils/deferred-generator.d.ts

@@ -0,0 +1,5 @@
+export interface DeferredGenerator<T, R> {
+    generator(): AsyncGenerator<T, R, void>;
+    next: (value: IteratorResult<T | Promise<T>>) => void;
+}
+export declare function createDeferredGenerator<T, R>(): DeferredGenerator<T, R>;

package/dist/utils/deferred-generator.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeferredGenerator = createDeferredGenerator;
+const deferred_1 = require("./deferred");
+function createDeferredGenerator() {
+    const deferreds = [new deferred_1.Deferred()];
+    let currentIndex = 0;
+    const next = (value) => {
+        const currentDeferred = deferreds[currentIndex];
+        if (!value.done) {
+            deferreds.push(new deferred_1.Deferred());
+            currentIndex++;
+        }
+        currentDeferred.resolve(value);
+    };
+    function generator() {
+        let currentIndex = 0;
+        return (async function* () {
+            while (true) {
+                const result = await deferreds[currentIndex].promise;
+                if (result.done)
+                    return result.value;
+                yield result.value;
+                currentIndex++;
+            }
+        })();
+    }
+    return {
+        generator,
+        next,
+    };
+}

package/dist/utils/deferred.d.ts

@@ -0,0 +1,6 @@
+export declare class Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+    constructor();
+}

package/dist/utils/deferred.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deferred = void 0;
+class Deferred {
+    constructor() {
+        this.promise = new Promise((res, rej) => {
+            this.resolve = res;
+            this.reject = rej;
+        });
+    }
+}
+exports.Deferred = Deferred;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@vercel/sandbox",
+  "version": "0.0.1",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "async-retry": "1.3.3",
+    "form-data": "3.0.0",
+    "jsonlines": "0.1.1",
+    "node-fetch": "2.6.11",
+    "zod": "3.24.4"
+  },
+  "devDependencies": {
+    "@types/async-retry": "1.4.9",
+    "@types/jsonlines": "0.1.5",
+    "@types/node": "22.15.12",
+    "@types/node-fetch": "2.6.12",
+    "typedoc": "^0.28.4",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typedoc": "typedoc",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/client/api-error.ts

@@ -0,0 +1,26 @@
+import type { Response } from "node-fetch";
+
+interface Options<ErrorData> {
+  message?: string;
+  json?: ErrorData;
+  text?: string;
+}
+
+export class APIError<ErrorData> extends Error {
+  public response: Response;
+  public message: string;
+  public json?: ErrorData;
+  public text?: string;
+
+  constructor(response: Response, options?: Options<ErrorData>) {
+    super(response.statusText);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, APIError);
+    }
+
+    this.response = response;
+    this.message = options?.message ?? "";
+    this.json = options?.json;
+    this.text = options?.text;
+  }
+}

package/src/client/base-client.ts

@@ -0,0 +1,144 @@
+import type { Options as RetryOptions } from "async-retry";
+import { APIError } from "./api-error";
+import { ZodType } from "zod";
+import { array } from "../utils/array";
+import { withRetry, type RequestOptions } from "./with-retry";
+import nodeFetch, { type Response, type RequestInit } from "node-fetch";
+
+export interface RequestParams extends RequestInit {
+  headers?: Record<string, string>;
+  method?: string;
+  onRetry?(error: any, options: RequestOptions): void;
+  query?: Record<string, number | string | null | undefined | string[]>;
+  retry?: Partial<RetryOptions>;
+}
+
+/**
+ * A base API client that provides a convenience wrapper for fetching where
+ * we can pass query parameters as an object, support retries, debugging
+ * and automatic authorization.
+ */
+export class APIClient {
+  protected token?: string;
+  private fetch: ReturnType<typeof withRetry<RequestInit>>;
+  private debug: boolean;
+  private host: string;
+
+  constructor(params: { debug?: boolean; host: string; token?: string }) {
+    this.fetch = withRetry(nodeFetch);
+    this.host = params.host;
+    this.debug = params.debug ?? process.env.DEBUG_FETCH === "true";
+    this.token = params.token;
+  }
+
+  protected async request(path: string, opts?: RequestParams) {
+    const url = new URL(path, this.host);
+    if (opts?.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        array(value).forEach((value) => {
+          url.searchParams.append(key, value.toString());
+        });
+      }
+    }
+
+    const start = Date.now();
+    const response = await this.fetch(url.toString(), {
+      ...opts,
+      body: opts?.body,
+      method: opts?.method || "GET",
+      headers: this.token
+        ? { Authorization: `Bearer ${this.token}`, ...opts?.headers }
+        : opts?.headers,
+    });
+
+    if (this.debug) {
+      const duration = Date.now() - start;
+      console.log(`[API] ${url} (${response.status}) ${duration}ms`);
+      if (response.status === 429) {
+        const retry = parseInt(response.headers.get("Retry-After") ?? "", 10);
+        const hours = Math.floor(retry / 60 / 60);
+        const minutes = Math.floor(retry / 60) % 60;
+        const seconds = retry % 60;
+        console.warn(
+          `[API] ${url} Rate Limited, Retry After ${hours}h ${minutes}m ${seconds}s`,
+        );
+      }
+    }
+
+    return response;
+  }
+}
+
+export interface Parsed<Data> {
+  response: Response;
+  text: string;
+  json: Data;
+}
+
+/**
+ * Allows to read the response text and parse it as JSON casting to the given
+ * type. If the response is not ok or cannot be parsed it will return error.
+ *
+ * @param response Response to parse.
+ * @returns Parsed response or error.
+ */
+export async function parse<Data, ErrorData>(
+  validator: ZodType<Data>,
+  response: Response,
+): Promise<Parsed<Data> | APIError<ErrorData>> {
+  const text = await response.text().catch((err) => {
+    return new APIError<ErrorData>(response, {
+      message: `Can't read response text: ${String(err)}`,
+    });
+  });
+
+  if (typeof text !== "string") {
+    return text;
+  }
+
+  let json: Data | ErrorData;
+
+  try {
+    json = JSON.parse(text || "{}");
+  } catch (error) {
+    return new APIError<ErrorData>(response, {
+      message: `Can't parse JSON: ${String(error)}`,
+      text,
+    });
+  }
+
+  if (!response.ok) {
+    return new APIError<ErrorData>(response, {
+      message: `Status code ${response.status} is not ok`,
+      json: json as ErrorData,
+      text,
+    });
+  }
+
+  const validated = validator.safeParse(json);
+  if (!validated.success) {
+    return new APIError<ErrorData>(response, {
+      message: `Response JSON is not valid: ${validated.error}`,
+      json: json as ErrorData,
+      text,
+    });
+  }
+
+  return {
+    json: validated.data,
+    response,
+    text,
+  };
+}
+
+export async function parseOrThrow<Data, ErrorData>(
+  validator: ZodType<Data>,
+  response: Response,
+): Promise<Parsed<Data>> {
+  const result = await parse<Data, ErrorData>(validator, response);
+  if (result instanceof APIError) {
+    throw result;
+  }
+
+  return result;
+}