@vercel/sandbox 1.1.9 → 1.2.1

package/src/sandbox.ts

@@ -1,572 +0,0 @@
-import type { SandboxMetaData, SandboxRouteData } from "./api-client";
-import type { Writable } from "stream";
-import { APIClient } from "./api-client";
-import { Command, type CommandFinished } from "./command";
-import { type Credentials, getCredentials } from "./utils/get-credentials";
-import { getPrivateParams, WithPrivate } from "./utils/types";
-import { WithFetchOptions } from "./api-client/api-client";
-import { RUNTIMES } from "./constants";
-import { Snapshot } from "./snapshot";
-
-/** @inline */
-export interface BaseCreateSandboxParams {
-  /**
-   * The source of the sandbox.
-   *
-   * Omit this parameter start a sandbox without a source.
-   *
-   * For git sources:
-   * - `depth`: Creates shallow clones with limited commit history (minimum: 1)
-   * - `revision`: Clones and checks out a specific commit, branch, or tag
-   */
-  source?:
-    | {
-        type: "git";
-        url: string;
-        depth?: number;
-        revision?: string;
-      }
-    | {
-        type: "git";
-        url: string;
-        username: string;
-        password: string;
-        depth?: number;
-        revision?: string;
-      }
-    | { type: "tarball"; url: string };
-  /**
-   * Array of port numbers to expose from the sandbox. Sandboxes can
-   * expose up to 4 ports.
-   */
-  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 vCPUs you specify here and
-   * 2048 MB of memory per vCPU.
-   */
-  resources?: { vcpus: number };
-
-  /**
-   * The runtime of the sandbox, currently only `node24`, `node22` and `python3.13` are supported.
-   * If not specified, the default runtime `node24` will be used.
-   */
-  runtime?: RUNTIMES | (string & {});
-
-  /**
-   * An AbortSignal to cancel sandbox creation.
-   */
-  signal?: AbortSignal;
-}
-
-export type CreateSandboxParams =
-  | BaseCreateSandboxParams
-  | (Omit<BaseCreateSandboxParams, "runtime" | "source"> & {
-      source: { type: "snapshot"; snapshotId: string };
-    });
-
-/** @inline */
-interface GetSandboxParams {
-  /**
-   * Unique identifier of the sandbox.
-   */
-  sandboxId: string;
-  /**
-   * An AbortSignal to cancel the operation.
-   */
-  signal?: AbortSignal;
-}
-
-/** @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, execute this command with root privileges. Defaults to false.
-   */
-  sudo?: boolean;
-  /**
-   * 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;
-  /**
-   * An AbortSignal to cancel the command execution
-   */
-  signal?: AbortSignal;
-}
-
-/**
- * A Sandbox is an isolated Linux MicroVM to run commands in.
- *
- * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
- * @hideconstructor
- */
-export class Sandbox {
-  private readonly client: APIClient;
-
-  /**
-   * Routes from ports to subdomains.
-  /* @hidden
-   */
-  public readonly routes: SandboxRouteData[];
-
-  /**
-   * Unique ID of this sandbox.
-   */
-  public get sandboxId(): string {
-    return this.sandbox.id;
-  }
-
-  public get interactivePort(): number | undefined {
-    return this.sandbox.interactivePort ?? undefined;
-  }
-
-  /**
-   * The status of the sandbox.
-   */
-  public get status(): SandboxMetaData["status"] {
-    return this.sandbox.status;
-  }
-
-  /**
-   * The creation date of the sandbox.
-   */
-  public get createdAt(): Date {
-    return new Date(this.sandbox.createdAt);
-  }
-
-  /**
-   * The timeout of the sandbox in milliseconds.
-   */
-  public get timeout(): number {
-    return this.sandbox.timeout;
-  }
-
-  /**
-   * If the sandbox was created from a snapshot, the ID of that snapshot.
-   */
-  public get sourceSnapshotId(): string | undefined {
-    return this.sandbox.sourceSnapshotId;
-  }
-
-  /**
-   * Internal metadata about this sandbox.
-   */
-  private sandbox: SandboxMetaData;
-
-  /**
-   * 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
-   * the next page of results.
-   */
-  static async list(
-    params?: Partial<Parameters<APIClient["listSandboxes"]>[0]> &
-      Partial<Credentials> &
-      WithFetchOptions,
-  ) {
-    const credentials = await getCredentials(params);
-    const client = new APIClient({
-      teamId: credentials.teamId,
-      token: credentials.token,
-      fetch: params?.fetch,
-    });
-    return client.listSandboxes({
-      ...credentials,
-      ...params,
-    });
-  }
-
-  /**
-   * Create a new sandbox.
-   *
-   * @param params - Creation parameters and optional credentials.
-   * @returns A promise resolving to the created {@link Sandbox}.
-   * @example
-   * <caption>Create a sandbox and drop it in the end of the block</caption>
-   * async function fn() {
-   *   await using const sandbox = await Sandbox.create();
-   *   // Sandbox automatically stopped at the end of the lexical scope
-   * }
-   */
-  static async create(
-    params?: WithPrivate<
-      CreateSandboxParams | (CreateSandboxParams & Credentials)
-    > &
-      WithFetchOptions,
-  ): Promise<Sandbox & AsyncDisposable> {
-    const credentials = await getCredentials(params);
-    const client = new APIClient({
-      teamId: credentials.teamId,
-      token: credentials.token,
-      fetch: params?.fetch,
-    });
-
-    const privateParams = getPrivateParams(params);
-    const sandbox = await client.createSandbox({
-      source: params?.source,
-      projectId: credentials.projectId,
-      ports: params?.ports ?? [],
-      timeout: params?.timeout,
-      resources: params?.resources,
-      runtime: params && "runtime" in params ? params?.runtime : undefined,
-      signal: params?.signal,
-      ...privateParams,
-    });
-
-    return new DisposableSandbox({
-      client,
-      sandbox: sandbox.json.sandbox,
-      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: WithPrivate<GetSandboxParams | (GetSandboxParams & Credentials)> &
-      WithFetchOptions,
-  ): Promise<Sandbox> {
-    const credentials = await getCredentials(params);
-    const client = new APIClient({
-      teamId: credentials.teamId,
-      token: credentials.token,
-      fetch: params.fetch,
-    });
-
-    const privateParams = getPrivateParams(params);
-    const sandbox = await client.getSandbox({
-      sandboxId: params.sandboxId,
-      signal: params.signal,
-      ...privateParams,
-    });
-
-    return new Sandbox({
-      client,
-      sandbox: sandbox.json.sandbox,
-      routes: sandbox.json.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,
-    sandbox,
-  }: {
-    client: APIClient;
-    routes: SandboxRouteData[];
-    sandbox: SandboxMetaData;
-  }) {
-    this.client = client;
-    this.routes = routes;
-    this.sandbox = 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
-   */
-  async getCommand(
-    cmdId: string,
-    opts?: { signal?: AbortSignal },
-  ): Promise<Command> {
-    const command = await this.client.getCommand({
-      sandboxId: this.sandbox.id,
-      cmdId,
-      signal: opts?.signal,
-    });
-
-    return new Command({
-      client: this.client,
-      sandboxId: this.sandbox.id,
-      cmd: command.json.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.
-   */
-  async runCommand(
-    command: string,
-    args?: string[],
-    opts?: { signal?: AbortSignal },
-  ): Promise<CommandFinished>;
-
-  /**
-   * Start executing a command in detached mode.
-   *
-   * @param params - The command parameters.
-   * @returns A {@link Command} instance for the running command.
-   */
-  async 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.
-   */
-  async runCommand(params: RunCommandParams): Promise<CommandFinished>;
-
-  async runCommand(
-    commandOrParams: string | RunCommandParams,
-    args?: string[],
-    opts?: { signal?: AbortSignal },
-  ): Promise<Command | CommandFinished> {
-    return typeof commandOrParams === "string"
-      ? this._runCommand({ cmd: commandOrParams, args, signal: opts?.signal })
-      : 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: RunCommandParams) {
-    const commandResponse = await this.client.runCommand({
-      sandboxId: this.sandbox.id,
-      command: params.cmd,
-      args: params.args ?? [],
-      cwd: params.cwd,
-      env: params.env ?? {},
-      sudo: params.sudo ?? false,
-      signal: params.signal,
-    });
-
-    const command = new Command({
-      client: this.client,
-      sandboxId: this.sandbox.id,
-      cmd: commandResponse.json.command,
-    });
-
-    if (params.stdout || params.stderr) {
-      (async () => {
-        try {
-          for await (const log of command.logs({ signal: params.signal })) {
-            if (log.stream === "stdout") {
-              params.stdout?.write(log.data);
-            } else if (log.stream === "stderr") {
-              params.stderr?.write(log.data);
-            }
-          }
-        } catch (err) {
-          if (params.signal?.aborted) {
-            return;
-          }
-          throw err;
-        }
-      })();
-    }
-
-    return params.detached ? command : command.wait({ signal: params.signal });
-  }
-
-  /**
-   * 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.
-   */
-  async mkDir(path: string, opts?: { signal?: AbortSignal }): Promise<void> {
-    await this.client.mkDir({
-      sandboxId: this.sandbox.id,
-      path: path,
-      signal: opts?.signal,
-    });
-  }
-
-  /**
-   * 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
-   */
-  async readFile(
-    file: { path: string; cwd?: string },
-    opts?: { signal?: AbortSignal },
-  ) {
-    return this.client.readFile({
-      sandboxId: this.sandbox.id,
-      path: file.path,
-      cwd: file.cwd,
-      signal: opts?.signal,
-    });
-  }
-
-  /**
-   * Write files to the filesystem of this 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 opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel the operation.
-   * @returns A promise that resolves when the files are written
-   */
-  async writeFiles(
-    files: { path: string; content: Buffer }[],
-    opts?: { signal?: AbortSignal },
-  ) {
-    return this.client.writeFiles({
-      sandboxId: this.sandbox.id,
-      cwd: this.sandbox.cwd,
-      extractDir: "/",
-      files: files,
-      signal: opts?.signal,
-    });
-  }
-
-  /**
-   * 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 {
-    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.
-   *
-   * @param opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel the operation.
-   * @returns A promise that resolves when the sandbox is stopped
-   */
-  async stop(opts?: { signal?: AbortSignal }) {
-    await this.client.stopSandbox({
-      sandboxId: this.sandbox.id,
-      signal: opts?.signal,
-    });
-  }
-
-  /**
-   * 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
-   *
-   * @example
-   * const sandbox = await Sandbox.create({ timeout: ms('10m') });
-   * // Extends timeout by 5 minutes, to a total of 15 minutes.
-   * await sandbox.extendTimeout(ms('5m'));
-   */
-  async extendTimeout(
-    duration: number,
-    opts?: { signal?: AbortSignal },
-  ): Promise<void> {
-    const response = await this.client.extendTimeout({
-      sandboxId: this.sandbox.id,
-      duration,
-      signal: opts?.signal,
-    });
-
-    // Update the internal sandbox metadata with the new timeout value
-    this.sandbox = response.json.sandbox;
-  }
-
-  /**
-   * Create a snapshot from this currently running sandbox. New sandboxes can
-   * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.
-   *
-   * Note: this sandbox will be stopped as part of the snapshot creation process.
-   *
-   * @param opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel the operation.
-   * @returns A promise that resolves to the Snapshot instance
-   */
-  async snapshot(opts?: { signal?: AbortSignal }): Promise<Snapshot> {
-    const response = await this.client.createSnapshot({
-      sandboxId: this.sandbox.id,
-      signal: opts?.signal,
-    });
-
-    this.sandbox = response.json.sandbox;
-
-    return new Snapshot({
-      client: this.client,
-      snapshot: response.json.snapshot,
-    });
-  }
-}
-
-/**
- * A {@link Sandbox} that can automatically be disposed using a `await using` statement.
- *
- * @example
- * {
- *   await using const sandbox = await Sandbox.create();
- * }
- * // Sandbox is automatically stopped here
- */
-class DisposableSandbox extends Sandbox implements AsyncDisposable {
-  async [Symbol.asyncDispose]() {
-    await this.stop();
-  }
-}

package/src/snapshot.ts

@@ -1,110 +0,0 @@
-import type { SnapshotMetadata } from "./api-client";
-import { APIClient } from "./api-client";
-import { Credentials, getCredentials } from "./utils/get-credentials";
-
-/** @inline */
-interface GetSnapshotParams {
-  /**
-   * Unique identifier of the snapshot.
-   */
-  snapshotId: string;
-  /**
-   * An AbortSignal to cancel the operation.
-   */
-  signal?: AbortSignal;
-}
-
-/**
- * A Snapshot is a saved state of a Sandbox that can be used to create new Sandboxes
- *
- * Use {@link Sandbox.snapshot} or {@link Snapshot.get} to construct.
- * @hideconstructor
- */
-export class Snapshot {
-  private readonly client: APIClient;
-
-  /**
-   * Unique ID of this snapshot.
-   */
-  public get snapshotId(): string {
-    return this.snapshot.id;
-  }
-
-  /**
-   * The ID the sandbox from which this snapshot was created.
-   */
-  public get sourceSandboxId(): string {
-    return this.snapshot.sourceSandboxId;
-  }
-
-  /**
-   * The status of the snapshot.
-   */
-  public get status(): SnapshotMetadata["status"] {
-    return this.snapshot.status;
-  }
-
-  /**
-   * Internal metadata about this snapshot.
-   */
-  private snapshot: SnapshotMetadata;
-
-  /**
-   * Create a new Snapshot instance.
-   *
-   * @param client - API client used to communicate with the backend
-   * @param snapshot - Snapshot metadata
-   */
-  constructor({
-    client,
-    snapshot,
-  }: {
-    client: APIClient;
-    snapshot: SnapshotMetadata;
-  }) {
-    this.client = client;
-    this.snapshot = snapshot;
-  }
-
-  /**
-   * Retrieve an existing snapshot.
-   *
-   * @param params - Get parameters and optional credentials.
-   * @returns A promise resolving to the {@link Sandbox}.
-   */
-  static async get(
-    params: GetSnapshotParams | (GetSnapshotParams & Credentials),
-  ): Promise<Snapshot> {
-    const credentials = await getCredentials(params);
-    const client = new APIClient({
-      teamId: credentials.teamId,
-      token: credentials.token,
-    });
-
-    const sandbox = await client.getSnapshot({
-      snapshotId: params.snapshotId,
-      signal: params.signal,
-    });
-
-    return new Snapshot({
-      client,
-      snapshot: sandbox.json.snapshot,
-    });
-  }
-
-  /**
-   * Delete this snapshot.
-   *
-   * @param opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel the operation.
-   * @returns A promise that resolves once the snapshot has been deleted.
-   */
-  async delete(opts?: { signal?: AbortSignal }): Promise<void> {
-    const response = await this.client.deleteSnapshot({
-      snapshotId: this.snapshot.id,
-      signal: opts?.signal,
-    });
-
-    this.snapshot = response.json.snapshot;
-  }
-}

package/src/utils/array.ts

@@ -1,15 +0,0 @@
-/**
- * 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 function array<T>(item?: null | T | T[]): T[] {
-  return item !== undefined && item !== null
-    ? Array.isArray(item)
-      ? item
-      : [item]
-    : [];
-}

package/src/utils/consume-readable.ts

@@ -1,12 +0,0 @@
-/**
- * Consumes a readable entirely concatenating all content in a single Buffer
- * @param readable A Readable stream
- */
-export function consumeReadable(readable: NodeJS.ReadableStream) {
-  return new Promise<Buffer>((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    readable.on("error", (err) => reject(err));
-    readable.on("data", (chunk) => chunks.push(chunk));
-    readable.on("end", () => resolve(Buffer.concat(chunks)));
-  });
-}