@vercel/sandbox 1.2.0 → 1.3.0

package/src/auth/poll-for-token.ts

@@ -1,89 +0,0 @@
-import { setTimeout } from "node:timers/promises";
-import { updateAuthConfig } from "./file";
-import { DeviceAuthorizationRequest, isOAuthError, OAuth } from "./oauth";
-
-export type PollTokenItem =
-  | { _tag: "Timeout"; newInterval: number }
-  | { _tag: "SlowDown"; newInterval: number }
-  | { _tag: "Error"; error: Error }
-  | {
-      _tag: "Response";
-      response: { text(): Promise<string> };
-    };
-
-export async function* pollForToken({
-  request,
-  oauth,
-}: {
-  request: DeviceAuthorizationRequest;
-  oauth: OAuth;
-}): AsyncGenerator<PollTokenItem, void, void> {
-  const controller = new AbortController();
-  try {
-    let intervalMs = request.interval * 1000;
-    while (Date.now() < request.expiresAt) {
-      const [tokenResponseError, tokenResponse] =
-        await oauth.deviceAccessTokenRequest(request.device_code);
-
-      if (tokenResponseError) {
-        // 2x backoff on connection timeouts per spec https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
-        if (tokenResponseError.message.includes("timeout")) {
-          intervalMs *= 2;
-          yield { _tag: "Timeout" as const, newInterval: intervalMs };
-          await setTimeout(intervalMs, { signal: controller.signal });
-          continue;
-        }
-        yield { _tag: "Error" as const, error: tokenResponseError };
-        return;
-      }
-
-      yield {
-        _tag: "Response" as const,
-        response: tokenResponse.clone() as { text(): Promise<string> },
-      };
-
-      const [tokensError, tokens] =
-        await oauth.processTokenResponse(tokenResponse);
-
-      if (isOAuthError(tokensError)) {
-        const { code } = tokensError;
-        switch (code) {
-          case "authorization_pending":
-            await setTimeout(intervalMs, { signal: controller.signal });
-            continue;
-          case "slow_down":
-            intervalMs += 5 * 1000;
-            yield { _tag: "SlowDown" as const, newInterval: intervalMs };
-            await setTimeout(intervalMs, { signal: controller.signal });
-            continue;
-          default:
-            yield { _tag: "Error", error: tokensError.cause };
-            return;
-        }
-      }
-
-      if (tokensError) {
-        yield { _tag: "Error", error: tokensError };
-        return;
-      }
-
-      updateAuthConfig({
-        token: tokens.access_token,
-        expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
-        refreshToken: tokens.refresh_token,
-      });
-
-      return;
-    }
-
-    yield {
-      _tag: "Error" as const,
-      error: new Error(
-        "Timed out waiting for authentication. Please try again.",
-      ),
-    };
-    return;
-  } finally {
-    controller.abort();
-  }
-}

package/src/auth/project.ts

@@ -1,92 +0,0 @@
-import { z } from "zod";
-import { fetchApi } from "./api";
-import { NotOk } from "./error";
-import { readLinkedProject } from "./linked-project";
-
-const TeamsSchema = z.object({
-  teams: z
-    .array(
-      z.object({
-        slug: z.string(),
-      }),
-    )
-    .min(1, `No teams found. Please create a team first.`),
-});
-
-const DEFAULT_PROJECT_NAME = "vercel-sandbox-default-project";
-
-/**
- * Resolves the team and project scope for sandbox operations.
- *
- * First checks for a locally linked project in `.vercel/project.json`.
- * If found, uses the `projectId` and `orgId` from there.
- *
- * Otherwise, if `teamId` is not provided, selects the first available team for the account.
- * Ensures a default project exists within the team, creating it if necessary.
- *
- * @param opts.token - Vercel API authentication token.
- * @param opts.teamId - Optional team slug. If omitted, the first team is selected.
- * @param opts.cwd - Optional directory to search for `.vercel/project.json`. Defaults to `process.cwd()`.
- * @returns The resolved scope with `projectId`, `teamId`, and whether the project was `created`.
- *
- * @throws {NotOk} If the API returns an error other than 404 when checking the project.
- * @throws {ZodError} If no teams exist for the account.
- *
- * @example
- * ```ts
- * const scope = await inferScope({ token: "vercel_..." });
- * // => { projectId: "vercel-sandbox-default-project", teamId: "my-team", created: false }
- * ```
- */
-export async function inferScope(opts: {
-  token: string;
-  teamId?: string;
-  cwd?: string;
-}): Promise<{ projectId: string; teamId: string; created: boolean }> {
-  const linkedProject = await readLinkedProject(opts.cwd ?? process.cwd());
-  if (linkedProject) {
-    return { ...linkedProject, created: false };
-  }
-
-  const teamId = opts.teamId ?? (await selectTeam(opts.token));
-
-  let created = false;
-  try {
-    await fetchApi({
-      token: opts.token,
-      endpoint: `/v2/projects/${encodeURIComponent(DEFAULT_PROJECT_NAME)}?slug=${encodeURIComponent(teamId)}`,
-    });
-  } catch (e) {
-    if (!(e instanceof NotOk) || e.response.statusCode !== 404) {
-      throw e;
-    }
-
-    await fetchApi({
-      token: opts.token,
-      endpoint: `/v11/projects?slug=${encodeURIComponent(teamId)}`,
-      method: "POST",
-      body: JSON.stringify({
-        name: DEFAULT_PROJECT_NAME,
-      }),
-    });
-    created = true;
-  }
-
-  return { projectId: DEFAULT_PROJECT_NAME, teamId, created };
-}
-
-/**
- * Selects a team for the current token by querying the Teams API and
- * returning the slug of the first team in the result set.
- *
- * @param token - Authentication token used to call the Vercel API.
- * @returns A promise that resolves to the first team's slug.
- */
-export async function selectTeam(token: string) {
-  const {
-    teams: [team],
-  } = await fetchApi({ token, endpoint: "/v2/teams?limit=1" }).then(
-    TeamsSchema.parse,
-  );
-  return team.slug;
-}

package/src/auth/zod.ts

@@ -1,16 +0,0 @@
-import { z } from "zod";
-
-/**
- * A Zod codec that serializes and deserializes JSON strings.
- */
-export const json = z.string().transform((jsonString: string, ctx): unknown => {
-  try {
-    return JSON.parse(jsonString);
-  } catch (err: any) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      message: `Invalid JSON: ${err.message}`,
-    });
-    return z.NEVER;
-  }
-});

package/src/command.test.ts

@@ -1,103 +0,0 @@
-import { expect, it, vi, beforeEach, afterEach, describe } from "vitest";
-import { Sandbox } from "./sandbox";
-
-describe.skipIf(process.env.RUN_INTEGRATION_TESTS !== "1")("Command", () => {
-  let sandbox: Sandbox;
-
-  beforeEach(async () => {
-    sandbox = await Sandbox.create();
-  });
-
-  afterEach(async () => {
-    await sandbox.stop();
-  });
-
-  it("supports more than one logs consumer", async () => {
-    const stdoutSpy = vi
-      .spyOn(process.stdout, "write")
-      .mockImplementation(() => true);
-
-    const cmd = await sandbox.runCommand({
-      cmd: "echo",
-      args: ["Hello World!"],
-      stdout: process.stdout,
-    });
-
-    expect(await cmd.stdout()).toEqual("Hello World!\n");
-    expect(stdoutSpy).toHaveBeenCalledWith("Hello World!\n");
-  });
-
-  it("does not warn when there is only one logs consumer", async () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
-    const cmd = await sandbox.runCommand({
-      cmd: "echo",
-      args: ["Hello World!"],
-    });
-
-    expect(await cmd.stdout()).toEqual("Hello World!\n");
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  it("Kills a command with a SIGINT", async () => {
-    const cmd = await sandbox.runCommand({
-      cmd: "sleep",
-      args: ["200000"],
-      detached: true,
-    });
-
-    await cmd.kill("SIGINT");
-    const result = await cmd.wait();
-    expect(result.exitCode).toBe(130); // 128 + 2
-  });
-
-  it("Kills a command with a SIGTERM", async () => {
-    const cmd = await sandbox.runCommand({
-      cmd: "sleep",
-      args: ["200000"],
-      detached: true,
-    });
-
-    await cmd.kill("SIGTERM");
-
-    const result = await cmd.wait();
-    expect(result.exitCode).toBe(143); // 128 + 15
-  });
-
-  it("can execute commands with sudo", async () => {
-    const cmd = await sandbox.runCommand({
-      cmd: "env",
-      sudo: true,
-      env: {
-        FOO: "bar",
-      },
-    });
-
-    expect(cmd.exitCode).toBe(0);
-
-    const output = await cmd.stdout();
-    expect(output).toContain("FOO=bar\n");
-    expect(output).toContain("USER=root\n");
-    expect(output).toContain("SUDO_USER=vercel-sandbox\n");
-
-    const pathLine = output
-      .split("\n")
-      .find((line) => line.startsWith("PATH="));
-    expect(pathLine).toBeDefined();
-
-    const pathSegments = pathLine!.slice(5).split(":");
-    expect(pathSegments).toContain("/vercel/bin");
-    expect(pathSegments).toContain("/vercel/runtimes/node22/bin");
-
-    const dnf = await sandbox.runCommand({
-      cmd: "dnf",
-      args: ["install", "-y", "golang"],
-      sudo: true,
-    });
-
-    expect(dnf.exitCode).toBe(0);
-
-    const which = await sandbox.runCommand("which", ["go"]);
-    expect(await which.output()).toContain("/usr/bin/go");
-  });
-});

package/src/command.ts

@@ -1,287 +0,0 @@
-import { APIClient, type CommandData } from "./api-client";
-import { Signal, resolveSignal } from "./utils/resolveSignal";
-
-/**
- * A command executed in a Sandbox.
- *
- * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
- * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
- * automatically waits and returns a {@link CommandFinished} instance.
- *
- * You can iterate over command output with {@link logs}.
- *
- * @see {@link Sandbox.runCommand} to start a command.
- *
- * @hideconstructor
- */
-export class Command {
-  /**
-   * @internal
-   * @private
-   */
-  protected client: APIClient;
-
-  /**
-   * ID of the sandbox this command is running in.
-   */
-  private sandboxId: string;
-
-  /**
-   * Data for the command execution.
-   */
-  private cmd: CommandData;
-
-  public exitCode: number | null;
-
-  private outputCache: Promise<{
-    stdout: string;
-    stderr: string;
-    both: string;
-  }> | null = null;
-
-  /**
-   * ID of the command execution.
-   */
-  get cmdId() {
-    return this.cmd.id;
-  }
-
-  get cwd() {
-    return this.cmd.cwd;
-  }
-
-  get startedAt() {
-    return this.cmd.startedAt;
-  }
-
-  /**
-   * @param params - Object containing the client, sandbox ID, and command ID.
-   * @param params.client - API client used to interact with the backend.
-   * @param params.sandboxId - The ID of the sandbox where the command is running.
-   * @param params.cmdId - The ID of the command execution.
-   */
-  constructor({
-    client,
-    sandboxId,
-    cmd,
-  }: {
-    client: APIClient;
-    sandboxId: string;
-    cmd: CommandData;
-  }) {
-    this.client = client;
-    this.sandboxId = sandboxId;
-    this.cmd = cmd;
-    this.exitCode = cmd.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);
-   *   }
-   * }
-   * ```
-   *
-   * @param opts - Optional parameters.
-   * @param opts.signal - An AbortSignal to cancel log streaming.
-   * @returns An async iterable of log entries from the command output.
-   *
-   * @see {@link Command.stdout}, {@link Command.stderr}, and {@link Command.output}
-   * to access output as a string.
-   */
-  logs(opts?: { signal?: AbortSignal }) {
-    return this.client.getLogs({
-      sandboxId: this.sandboxId,
-      cmdId: this.cmd.id,
-      signal: opts?.signal,
-    });
-  }
-
-  /**
-   * Wait for a command to exit and populate its exit code.
-   *
-   * This method is useful for detached commands where you need to wait
-   * for completion. For non-detached commands, {@link Sandbox.runCommand}
-   * automatically waits and returns a {@link CommandFinished} instance.
-   *
-   * ```
-   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
-   * const result = await detachedCmd.wait();
-   * if (result.exitCode !== 0) {
-   *   console.error("Something went wrong...")
-   * }
-   * ```
-   *
-   * @param params - Optional parameters.
-   * @param params.signal - An AbortSignal to cancel waiting.
-   * @returns A {@link CommandFinished} instance with populated exit code.
-   */
-  async wait(params?: { signal?: AbortSignal }) {
-    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,
-      sandboxId: this.sandboxId,
-      cmd: command.json.command,
-      exitCode: command.json.command.exitCode,
-    });
-  }
-
-  /**
-   * Get cached output, fetching logs only once and reusing for concurrent calls.
-   * This prevents race conditions when stdout() and stderr() are called in parallel.
-   */
-  private async getCachedOutput(opts?: { signal?: AbortSignal }): Promise<{
-    stdout: string;
-    stderr: string;
-    both: string;
-  }> {
-    if (!this.outputCache) {
-      this.outputCache = (async () => {
-        try {
-          let stdout = "";
-          let stderr = "";
-          let both = "";
-          for await (const log of this.logs({ signal: opts?.signal })) {
-            both += log.data;
-            if (log.stream === "stdout") {
-              stdout += log.data;
-            } else {
-              stderr += log.data;
-            }
-          }
-          return { stdout, stderr, both };
-        } catch (err) {
-          // Clear the promise so future calls can retry
-          this.outputCache = null;
-          throw err;
-        }
-      })();
-    }
-
-    return this.outputCache;
-  }
-
-  /**
-   * Get the output of `stdout`, `stderr`, or both as a string.
-   *
-   * NOTE: This may throw string conversion errors if the command does
-   * 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: "stdout" | "stderr" | "both" = "both",
-    opts?: { signal?: AbortSignal },
-  ) {
-    const cached = await this.getCachedOutput(opts);
-    return cached[stream];
-  }
-
-  /**
-   * 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.
-   */
-  async stdout(opts?: { signal?: AbortSignal }) {
-    return this.output("stdout", opts);
-  }
-
-  /**
-   * 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.
-   */
-  async stderr(opts?: { signal?: AbortSignal }) {
-    return this.output("stderr", opts);
-  }
-
-  /**
-   * Kill a running command in a sandbox.
-   *
-   * @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?: Signal, opts?: { abortSignal?: AbortSignal }) {
-    await this.client.killCommand({
-      sandboxId: this.sandboxId,
-      commandId: this.cmd.id,
-      signal: resolveSignal(signal ?? "SIGTERM"),
-      abortSignal: opts?.abortSignal,
-    });
-  }
-}
-
-/**
- * A command that has finished executing.
- *
- * The exit code is immediately available and populated upon creation.
- * Unlike {@link Command}, you don't need to call wait() - the command
- * has already completed execution.
- *
- * @hideconstructor
- */
-export class CommandFinished extends Command {
-  /**
-   * The exit code of the command. This is always populated for
-   * CommandFinished instances.
-   */
-  public exitCode: number;
-
-  /**
-   * @param params - Object containing client, sandbox ID, command ID, and exit code.
-   * @param params.client - API client used to interact with the backend.
-   * @param params.sandboxId - The ID of the sandbox where the command ran.
-   * @param params.cmdId - The ID of the command execution.
-   * @param params.exitCode - The exit code of the completed command.
-   */
-  constructor(params: {
-    client: APIClient;
-    sandboxId: string;
-    cmd: CommandData;
-    exitCode: number;
-  }) {
-    super({ ...params });
-    this.exitCode = params.exitCode;
-  }
-
-  /**
-   * The wait method is not needed for CommandFinished instances since
-   * the command has already completed and exitCode is populated.
-   *
-   * @deprecated This method is redundant for CommandFinished instances.
-   * The exitCode is already available.
-   * @returns This CommandFinished instance.
-   */
-  async wait(): Promise<CommandFinished> {
-    return this;
-  }
-}

package/src/constants.ts

@@ -1 +0,0 @@
-export type RUNTIMES = "node24" | "node22" | "python3.13";

package/src/index.ts

@@ -1,4 +0,0 @@
-export { Sandbox } from "./sandbox";
-export { Snapshot } from "./snapshot";
-export { Command, CommandFinished } from "./command";
-export { StreamError } from "./api-client/api-error";