@vercel/sandbox 1.1.4 → 1.1.6

package/dist/utils/log.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.write = write;
+exports.code = code;
+const picocolors_1 = __importDefault(require("picocolors"));
+const colors = {
+    warn: picocolors_1.default.yellow,
+    error: picocolors_1.default.red,
+    success: picocolors_1.default.green,
+    info: picocolors_1.default.blue,
+};
+const logPrefix = picocolors_1.default.dim("[vercel/sandbox]");
+function write(level, text) {
+    text = Array.isArray(text) ? text.join("\n") : text;
+    const prefixed = text.replace(/^/gm, `${logPrefix} `);
+    console.error(colors[level](prefixed));
+}
+function code(text) {
+    return picocolors_1.default.italic(picocolors_1.default.dim("`") + text + picocolors_1.default.dim("`"));
+}
+//# sourceMappingURL=log.js.map

package/dist/utils/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/utils/log.ts"],"names":[],"mappings":";;;;;AAQA,sBAOC;AAED,oBAEC;AAnBD,4DAA8B;AAC9B,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,oBAAI,CAAC,MAAM;IACjB,KAAK,EAAE,oBAAI,CAAC,GAAG;IACf,OAAO,EAAE,oBAAI,CAAC,KAAK;IACnB,IAAI,EAAE,oBAAI,CAAC,IAAI;CAChB,CAAC;AACF,MAAM,SAAS,GAAG,oBAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC/C,SAAgB,KAAK,CACnB,KAA4C,EAC5C,IAAuB;IAEvB,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,SAAS,GAAG,CAAC,CAAC;IACtD,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAgB,IAAI,CAAC,IAAY;IAC/B,OAAO,oBAAI,CAAC,MAAM,CAAC,oBAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,oBAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.1.4";
+export declare const VERSION = "1.1.6";

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "1.1.4";
+exports.VERSION = "1.1.6";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,8 +13,10 @@
     "async-retry": "1.3.3",
     "jsonlines": "0.1.1",
     "ms": "2.1.3",
+    "picocolors": "^1.1.1",
     "tar-stream": "3.1.7",
     "undici": "^7.16.0",
+    "xdg-app-paths": "5.1.0",
     "zod": "3.24.4"
   },
   "devDependencies": {
@@ -24,6 +26,7 @@
     "@types/node": "22.15.12",
     "@types/tar-stream": "3.1.4",
     "dotenv": "16.5.0",
+    "factoree": "^0.1.2",
     "typedoc": "0.28.5",
     "typescript": "5.8.3",
     "vitest": "3.2.1"

package/src/api-client/api-client.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { APIClient } from "./api-client";
+import { APIError, StreamError } from "./api-error";
+import { createNdjsonStream } from "../../test-utils/mock-response";
+
+describe("APIClient", () => {
+  describe("getLogs", () => {
+    let client: APIClient;
+    let mockFetch: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      mockFetch = vi.fn();
+      client = new APIClient({
+        teamId: "team_123",
+        token: "1234",
+        fetch: mockFetch,
+      });
+    });
+
+    it("yields stdout log lines", async () => {
+      const logLines = [
+        { stream: "stdout", data: "hello" },
+        { stream: "stdout", data: "world" },
+      ];
+
+      mockFetch.mockResolvedValue(
+        new Response(createNdjsonStream(logLines), {
+          headers: { "content-type": "application/x-ndjson" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+      const results: Array<{ stream: string; data: string }> = [];
+
+      for await (const log of logs) {
+        results.push(log);
+      }
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toEqual({ stream: "stdout", data: "hello" });
+      expect(results[1]).toEqual({ stream: "stdout", data: "world" });
+    });
+
+    it("yields stderr log lines", async () => {
+      const logLines = [{ stream: "stderr", data: "Error" }];
+
+      mockFetch.mockResolvedValue(
+        new Response(createNdjsonStream(logLines), {
+          headers: { "content-type": "application/x-ndjson" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+      const results: Array<{ stream: string; data: string }> = [];
+
+      for await (const log of logs) {
+        results.push(log);
+      }
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toEqual({
+        stream: "stderr",
+        data: "Error",
+      });
+    });
+
+    it("throws APIError when content-type is not application/x-ndjson", async () => {
+      mockFetch.mockResolvedValue(
+        new Response(null, {
+          headers: { "content-type": "application/json" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+
+      await expect(async () => {
+        for await (const _ of logs) {
+        }
+      }).rejects.toThrow(APIError);
+    });
+
+    it("throws APIError when response body is null", async () => {
+      mockFetch.mockResolvedValue(
+        new Response(null, {
+          headers: { "content-type": "application/x-ndjson" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+
+      await expect(async () => {
+        for await (const _ of logs) {
+        }
+      }).rejects.toThrow(APIError);
+    });
+
+    it("throws StreamError when error log line is received", async () => {
+      const logLines = [
+        { stream: "stdout", data: "some logs" },
+        {
+          stream: "error",
+          data: {
+            code: "sandbox_stream_closed",
+            message: "Sandbox stream was closed and is not accepting commands.",
+          },
+        },
+      ];
+
+      mockFetch.mockResolvedValue(
+        new Response(createNdjsonStream(logLines), {
+          headers: { "content-type": "application/x-ndjson" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+      const results: Array<{ stream: string; data: string }> = [];
+
+      await expect(async () => {
+        for await (const log of logs) {
+          results.push(log);
+        }
+      }).rejects.toThrow(StreamError);
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toEqual({ stream: "stdout", data: "some logs" });
+    });
+
+    it("includes sandboxId in APIError", async () => {
+      mockFetch.mockResolvedValue(
+        new Response(null, {
+          headers: { "content-type": "application/json" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+
+      try {
+        for await (const _ of logs) {
+        }
+        expect.fail("Expected APIError to be thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(APIError);
+        expect((err as APIError<unknown>).sandboxId).toBe("sbx_123");
+      }
+    });
+
+    it("includes sandboxId in StreamError", async () => {
+      const logLines = [
+        {
+          stream: "error",
+          data: {
+            code: "sandbox_stopped",
+            message: "Sandbox has stopped",
+          },
+        },
+      ];
+
+      mockFetch.mockResolvedValue(
+        new Response(createNdjsonStream(logLines), {
+          headers: { "content-type": "application/x-ndjson" },
+        }),
+      );
+
+      const logs = client.getLogs({ sandboxId: "sbx_123", cmdId: "cmd_456" });
+
+      try {
+        for await (const _ of logs) {
+        }
+        expect.fail("Expected StreamError to be thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(StreamError);
+        expect((err as StreamError).sandboxId).toBe("sbx_123");
+      }
+    });
+  });
+});

package/src/api-client/api-client.ts

@@ -381,12 +381,14 @@ export class APIClient extends BaseClient {
       if (response.headers.get("content-type") !== "application/x-ndjson") {
         throw new APIError(response, {
           message: "Expected a stream of logs",
+          sandboxId: params.sandboxId,
         });
       }
 
       if (response.body === null) {
         throw new APIError(response, {
           message: "No response body",
+          sandboxId: params.sandboxId,
         });
       }
 
@@ -398,7 +400,11 @@ export class APIClient extends BaseClient {
       for await (const chunk of jsonlinesStream) {
         const parsed = LogLine.parse(chunk);
         if (parsed.stream === "error") {
-          throw new StreamError(parsed.data.code, parsed.data.message);
+          throw new StreamError(
+            parsed.data.code,
+            parsed.data.message,
+            params.sandboxId,
+          );
         }
         yield parsed;
       }

package/src/api-client/api-error.ts

@@ -2,6 +2,7 @@ interface Options<ErrorData> {
   message?: string;
   json?: ErrorData;
   text?: string;
+  sandboxId?: string;
 }
 
 export class APIError<ErrorData> extends Error {
@@ -9,6 +10,7 @@ export class APIError<ErrorData> extends Error {
   public message: string;
   public json?: ErrorData;
   public text?: string;
+  public sandboxId?: string;
 
   constructor(response: Response, options?: Options<ErrorData>) {
     super(response.statusText);
@@ -20,6 +22,7 @@ export class APIError<ErrorData> extends Error {
     this.message = options?.message ?? "";
     this.json = options?.json;
     this.text = options?.text;
+    this.sandboxId = options?.sandboxId;
   }
 }
 
@@ -29,11 +32,13 @@ export class APIError<ErrorData> extends Error {
  */
 export class StreamError extends Error {
   public code: string;
+  public sandboxId: string;
 
-  constructor(code: string, message: string) {
+  constructor(code: string, message: string, sandboxId: string) {
     super(message);
     this.name = "StreamError";
     this.code = code;
+    this.sandboxId = sandboxId;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, StreamError);
     }

package/src/api-client/base-client.ts

@@ -87,6 +87,15 @@ export interface Parsed<Data> {
   json: Data;
 }
 
+/**
+ * Extract sandboxId from a sandbox API URL.
+ * URLs follow the pattern: /v1/sandboxes/{sandboxId}/...
+ */
+function extractSandboxId(url: string): string | undefined {
+  const match = url.match(/\/v1\/sandboxes\/([^/?]+)/);
+  return match?.[1];
+}
+
 /**
  * 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.
@@ -98,9 +107,12 @@ export async function parse<Data, ErrorData>(
   validator: ZodType<Data>,
   response: Response,
 ): Promise<Parsed<Data> | APIError<ErrorData>> {
+  const sandboxId = extractSandboxId(response.url);
+
   const text = await response.text().catch((err) => {
     return new APIError<ErrorData>(response, {
       message: `Can't read response text: ${String(err)}`,
+      sandboxId,
     });
   });
 
@@ -116,6 +128,7 @@ export async function parse<Data, ErrorData>(
     return new APIError<ErrorData>(response, {
       message: `Can't parse JSON: ${String(error)}`,
       text,
+      sandboxId,
     });
   }
 
@@ -124,6 +137,7 @@ export async function parse<Data, ErrorData>(
       message: `Status code ${response.status} is not ok`,
       json: json as ErrorData,
       text,
+      sandboxId,
     });
   }
 
@@ -133,6 +147,7 @@ export async function parse<Data, ErrorData>(
       message: `Response JSON is not valid: ${validated.error}`,
       json: json as ErrorData,
       text,
+      sandboxId,
     });
   }
 

package/src/api-client/with-retry.ts

@@ -1,6 +1,6 @@
 import type { Options as RetryOptions } from "async-retry";
 import { APIError } from "./api-error";
-import { setTimeout } from "timers/promises";
+import { setTimeout } from "node:timers/promises";
 import retry from "async-retry";
 
 export interface RequestOptions {

package/src/auth/api.ts

@@ -0,0 +1,31 @@
+import { NotOk } from "./error";
+
+export async function fetchApi(opts: {
+  token: string;
+  endpoint: string;
+  method?: string;
+  body?: string;
+}): Promise<unknown> {
+  const x = await fetch(`https://api.vercel.com${opts.endpoint}`, {
+    method: opts.method,
+    body: opts.body,
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      "Content-Type": "application/json",
+    },
+  });
+  if (!x.ok) {
+    let message = await x.text();
+
+    try {
+      const { error } = JSON.parse(message);
+      message = `${error.code.toUpperCase()}: ${error.message}`;
+    } catch {}
+
+    throw new NotOk({
+      responseText: message,
+      statusCode: x.status,
+    });
+  }
+  return (await x.json()) as unknown;
+}

package/src/auth/error.ts

@@ -0,0 +1,8 @@
+export class NotOk extends Error {
+  name = "NotOk";
+  response: { statusCode: number; responseText: string };
+  constructor(response: { statusCode: number; responseText: string }) {
+    super(`HTTP ${response.statusCode}: ${response.responseText}`);
+    this.response = response;
+  }
+}

package/src/auth/file.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+import fs from "node:fs";
+import { homedir } from "node:os";
+import XDGAppPaths from "xdg-app-paths";
+import { z } from "zod";
+import { json } from "./zod";
+
+const ZodDate = z.number().transform((seconds) => new Date(seconds * 1000));
+
+const AuthFile = z.object({
+  token: z.string().min(1).optional(),
+  refreshToken: z.string().min(1).optional(),
+  expiresAt: ZodDate.optional(),
+});
+
+const StoredAuthFile = json.pipe(AuthFile);
+
+type AuthFile = z.infer<typeof AuthFile>;
+
+// Returns whether a directory exists
+const isDirectory = (path: string): boolean => {
+  try {
+    return fs.lstatSync(path).isDirectory();
+  } catch (_) {
+    // We don't care which kind of error occured, it isn't a directory anyway.
+    return false;
+  }
+};
+
+// Returns in which directory the config should be present
+const getGlobalPathConfig = (): string => {
+  const vercelDirectories = XDGAppPaths("com.vercel.cli").dataDirs();
+
+  const possibleConfigPaths = [
+    ...vercelDirectories, // latest vercel directory
+    path.join(homedir(), ".now"), // legacy config in user's home directory
+    ...XDGAppPaths("now").dataDirs(), // legacy XDG directory
+  ];
+
+  // The customPath flag is the preferred location,
+  // followed by the vercel directory,
+  // followed by the now directory.
+  // If none of those exist, use the vercel directory.
+  return (
+    possibleConfigPaths.find((configPath) => isDirectory(configPath)) ||
+    vercelDirectories[0]
+  );
+};
+
+export const getAuth = () => {
+  try {
+    const pathname = path.join(getGlobalPathConfig(), "auth.json");
+    return StoredAuthFile.parse(fs.readFileSync(pathname, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+export function updateAuthConfig(config: AuthFile): void {
+  const pathname = path.join(getGlobalPathConfig(), "auth.json");
+  fs.mkdirSync(path.dirname(pathname), { recursive: true });
+  const content = {
+    token: config.token,
+    expiresAt:
+      config.expiresAt && Math.round(config.expiresAt.getTime() / 1000),
+    refreshToken: config.refreshToken,
+  } satisfies z.input<typeof AuthFile>;
+  fs.writeFileSync(pathname, JSON.stringify(content) + "\n");
+}

package/src/auth/index.ts

@@ -0,0 +1,9 @@
+// This file can also be imported as `@vercel/sandbox/dist/auth`, which is completely fine.
+// The only valid importer of this would be the CLI as we share the same codebase.
+
+export * from "./file";
+export type * from "./file";
+export * from "./oauth";
+export type * from "./oauth";
+export { pollForToken } from "./poll-for-token";
+export { inferScope, selectTeam } from "./project";

package/src/auth/infer-scope.test.ts

@@ -0,0 +1,178 @@
+import { inferScope, selectTeam } from "./project";
+import {
+  beforeEach,
+  describe,
+  test,
+  vi,
+  Mock,
+  expect,
+  onTestFinished,
+} from "vitest";
+import { fetchApi } from "./api";
+import { NotOk } from "./error";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const fetchApiMock = fetchApi as Mock<typeof fetchApi>;
+vi.mock("./api");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+async function getTempDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "infer-scope-test-"));
+  onTestFinished(() => fs.rm(dir, { recursive: true }));
+  return dir;
+}
+
+describe("selectTeam", () => {
+  test("returns the first team", async () => {
+    fetchApiMock.mockResolvedValue({
+      teams: [{ slug: "one" }, { slug: "two" }],
+    });
+    const team = await selectTeam("token");
+    expect(fetchApiMock).toHaveBeenCalledWith({
+      endpoint: "/v2/teams?limit=1",
+      token: "token",
+    });
+    expect(team).toBe("one");
+  });
+});
+
+describe("inferScope", () => {
+  test("uses provided teamId", async () => {
+    fetchApiMock.mockResolvedValue({});
+    const scope = await inferScope({ teamId: "my-team", token: "token" });
+    expect(scope).toEqual({
+      created: false,
+      projectId: "vercel-sandbox-default-project",
+      teamId: "my-team",
+    });
+  });
+
+  describe("team creation", () => {
+    test("project 404 triggers project creation", async () => {
+      fetchApiMock.mockImplementation(async ({ method }) => {
+        if (!method || method === "GET") {
+          throw new NotOk({ statusCode: 404, responseText: "Not Found" });
+        }
+        return {};
+      });
+      const scope = await inferScope({ teamId: "my-team", token: "token" });
+      expect(scope).toEqual({
+        created: true,
+        projectId: "vercel-sandbox-default-project",
+        teamId: "my-team",
+      });
+    });
+
+    test("non-404 throws", async () => {
+      fetchApiMock.mockImplementation(async ({ method }) => {
+        if (!method || method === "GET") {
+          throw new NotOk({ statusCode: 403, responseText: "Forbidden" });
+        }
+        return {};
+      });
+      await expect(
+        inferScope({ teamId: "my-team", token: "token" }),
+      ).rejects.toThrowError(
+        new NotOk({ statusCode: 403, responseText: "Forbidden" }),
+      );
+    });
+
+    test("non-status errors are thrown", async () => {
+      fetchApiMock.mockImplementation(async ({ method }) => {
+        if (!method || method === "GET") {
+          throw new Error("Oops!");
+        }
+        return {};
+      });
+      await expect(inferScope({ token: "token" })).rejects.toThrowError(
+        "Oops!",
+      );
+    });
+  });
+
+  test("infers the team", async () => {
+    fetchApiMock.mockImplementation(async ({ endpoint }) => {
+      if (endpoint === "/v2/teams?limit=1") {
+        return { teams: [{ slug: "inferred-team" }] };
+      }
+      return {};
+    });
+    const scope = await inferScope({ token: "token" });
+    expect(scope).toEqual({
+      created: false,
+      projectId: "vercel-sandbox-default-project",
+      teamId: "inferred-team",
+    });
+  });
+
+  describe("linked project", () => {
+    test("uses linked project when .vercel/project.json exists", async () => {
+      const dir = await getTempDir();
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        JSON.stringify({
+          projectId: "prj_linked",
+          orgId: "team_linked",
+        }),
+      );
+
+      const scope = await inferScope({ token: "token", cwd: dir });
+
+      expect(scope).toEqual({
+        created: false,
+        projectId: "prj_linked",
+        teamId: "team_linked",
+      });
+      // Should not call API when using linked project
+      expect(fetchApiMock).not.toHaveBeenCalled();
+    });
+
+    test("falls back to default project when .vercel/project.json does not exist", async () => {
+      const dir = await getTempDir();
+      fetchApiMock.mockResolvedValue({});
+
+      const scope = await inferScope({
+        token: "token",
+        teamId: "my-team",
+        cwd: dir,
+      });
+
+      expect(scope).toEqual({
+        created: false,
+        projectId: "vercel-sandbox-default-project",
+        teamId: "my-team",
+      });
+      expect(fetchApiMock).toHaveBeenCalled();
+    });
+
+    test("falls back to default project when .vercel/project.json is invalid", async () => {
+      const dir = await getTempDir();
+      await fs.mkdir(path.join(dir, ".vercel"));
+      await fs.writeFile(
+        path.join(dir, ".vercel", "project.json"),
+        "not valid json",
+      );
+
+      fetchApiMock.mockResolvedValue({});
+
+      const scope = await inferScope({
+        token: "token",
+        teamId: "my-team",
+        cwd: dir,
+      });
+
+      expect(scope).toEqual({
+        created: false,
+        projectId: "vercel-sandbox-default-project",
+        teamId: "my-team",
+      });
+      expect(fetchApiMock).toHaveBeenCalled();
+    });
+  });
+});