@vercel/sandbox 0.0.8 → 0.0.10

package/dist/sandbox.d.ts

@@ -1,6 +1,7 @@
-import { type Writable } from "stream";
+import type { SandboxData, SandboxRouteData } from "./api-client";
+import type { Writable } from "stream";
 import { APIClient } from "./api-client";
-import { Command, CommandFinished } from "./command";
+import { Command, type CommandFinished } from "./command";
 import { type Credentials } from "./utils/get-credentials";
 /** @inline */
 export interface CreateSandboxParams {
@@ -18,6 +19,13 @@ export interface CreateSandboxParams {
         url: string;
         depth?: number;
         revision?: string;
+    } | {
+        type: "git";
+        url: string;
+        username: string;
+        password: string;
+        depth?: number;
+        revision?: string;
     } | {
         type: "tarball";
         url: string;
@@ -47,13 +55,6 @@ export interface CreateSandboxParams {
 }
 /** @inline */
 interface GetSandboxParams {
-    /**
-     * Port-to-subdomain route mappings.
-     */
-    routes: Array<{
-        subdomain: string;
-        port: number;
-    }>;
     /**
      * Unique identifier of the sandbox.
      */
@@ -102,14 +103,15 @@ export declare class Sandbox {
      * Routes from ports to subdomains.
     /* @hidden
      */
-    readonly routes: {
-        subdomain: string;
-        port: number;
-    }[];
+    readonly routes: SandboxRouteData[];
     /**
      * Unique ID of this sandbox.
      */
-    readonly sandboxId: string;
+    get sandboxId(): string;
+    /**
+     * Data about this sandbox.
+     */
+    private readonly sandbox;
     /**
      * Create a new sandbox.
      *
@@ -131,13 +133,10 @@ export declare class Sandbox {
      * @param routes - Port-to-subdomain mappings for exposed ports
      * @param sandboxId - Unique identifier for the sandbox
      */
-    constructor({ client, routes, sandboxId, }: {
+    constructor({ client, routes, sandbox, }: {
         client: APIClient;
-        routes: {
-            subdomain: string;
-            port: number;
-        }[];
-        sandboxId: string;
+        routes: SandboxRouteData[];
+        sandbox: SandboxData;
     });
     /**
      * Get a previously run command by its ID.
@@ -145,7 +144,7 @@ export declare class Sandbox {
      * @param cmdId - ID of the command to retrieve
      * @returns A {@link Command} instance representing the command
      */
-    getCommand(cmdId: string): Command;
+    getCommand(cmdId: string): Promise<Command>;
     /**
      * Start executing a command in this sandbox.
      *
@@ -184,6 +183,16 @@ export declare class Sandbox {
      * @param path - Path of the directory to create
      */
     mkDir(path: string): Promise<void>;
+    /**
+     * Read a file from the filesystem of this sandbox.
+     *
+     * @param file - File to read, with path and optional cwd
+     * @returns A promise that resolves to a ReadableStream containing the file contents
+     */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }): Promise<NodeJS.ReadableStream | null>;
     /**
      * Write files to the filesystem of this sandbox.
      *

package/dist/sandbox.js

@@ -11,6 +11,12 @@ const get_credentials_1 = require("./utils/get-credentials");
  * @hideconstructor
  */
 class Sandbox {
+    /**
+     * Unique ID of this sandbox.
+     */
+    get sandboxId() {
+        return this.sandbox.id;
+    }
     /**
      * Create a new sandbox.
      *
@@ -33,7 +39,7 @@ class Sandbox {
         });
         return new Sandbox({
             client,
-            sandboxId: sandbox.json.sandboxId,
+            sandbox: sandbox.json.sandbox,
             routes: sandbox.json.routes,
         });
     }
@@ -49,10 +55,13 @@ class Sandbox {
             teamId: credentials.teamId,
             token: credentials.token,
         });
+        const sandbox = await client.getSandbox({
+            sandboxId: params.sandboxId,
+        });
         return new Sandbox({
             client,
-            sandboxId: params.sandboxId,
-            routes: params.routes,
+            sandbox: sandbox.json.sandbox,
+            routes: sandbox.json.routes,
         });
     }
     /**
@@ -62,10 +71,10 @@ class Sandbox {
      * @param routes - Port-to-subdomain mappings for exposed ports
      * @param sandboxId - Unique identifier for the sandbox
      */
-    constructor({ client, routes, sandboxId, }) {
+    constructor({ client, routes, sandbox, }) {
         this.client = client;
         this.routes = routes;
-        this.sandboxId = sandboxId;
+        this.sandbox = sandbox;
     }
     /**
      * Get a previously run command by its ID.
@@ -73,11 +82,15 @@ class Sandbox {
      * @param cmdId - ID of the command to retrieve
      * @returns A {@link Command} instance representing the command
      */
-    getCommand(cmdId) {
+    async getCommand(cmdId) {
+        const command = await this.client.getCommand({
+            sandboxId: this.sandbox.id,
+            cmdId,
+        });
         return new command_1.Command({
             client: this.client,
-            sandboxId: this.sandboxId,
-            cmdId,
+            sandboxId: this.sandbox.id,
+            cmd: command.json.command,
         });
     }
     async runCommand(commandOrParams, args) {
@@ -94,7 +107,7 @@ class Sandbox {
      */
     async _runCommand(params) {
         const commandResponse = await this.client.runCommand({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             command: params.cmd,
             args: params.args ?? [],
             cwd: params.cwd,
@@ -102,8 +115,8 @@ class Sandbox {
         });
         const command = new command_1.Command({
             client: this.client,
-            sandboxId: this.sandboxId,
-            cmdId: commandResponse.json.cmdId,
+            sandboxId: this.sandbox.id,
+            cmd: commandResponse.json.command,
         });
         if (params.stdout || params.stderr) {
             (async () => {
@@ -126,10 +139,23 @@ class Sandbox {
      */
     async mkDir(path) {
         await this.client.mkDir({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             path: path,
         });
     }
+    /**
+     * Read a file from the filesystem of this sandbox.
+     *
+     * @param file - File to read, with path and optional cwd
+     * @returns A promise that resolves to a ReadableStream containing the file contents
+     */
+    async readFile(file) {
+        return this.client.readFile({
+            sandboxId: this.sandbox.id,
+            path: file.path,
+            cwd: file.cwd,
+        });
+    }
     /**
      * Write files to the filesystem of this sandbox.
      *
@@ -138,7 +164,7 @@ class Sandbox {
      */
     async writeFiles(files) {
         return this.client.writeFiles({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             files: files,
         });
     }
@@ -165,7 +191,7 @@ class Sandbox {
      */
     async stop() {
         await this.client.stopSandbox({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
         });
     }
 }

package/dist/utils/consume-readable.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+export declare function consumeReadable(readable: NodeJS.ReadableStream): Promise<Buffer<ArrayBufferLike>>;

package/dist/utils/consume-readable.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumeReadable = consumeReadable;
+/**
+ * Consumes a readable entirely concatenating all content in a single Buffer
+ * @param readable A Readable stream
+ */
+function consumeReadable(readable) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        readable.on("error", (err) => reject(err));
+        readable.on("data", (chunk) => chunks.push(chunk));
+        readable.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+}

package/dist/utils/resolveSignal.d.ts

@@ -0,0 +1,13 @@
+declare const linuxSignalMapping: {
+    readonly SIGHUP: 1;
+    readonly SIGINT: 2;
+    readonly SIGQUIT: 3;
+    readonly SIGKILL: 9;
+    readonly SIGTERM: 15;
+    readonly SIGCONT: 18;
+    readonly SIGSTOP: 19;
+};
+type CommonLinuxSignals = keyof typeof linuxSignalMapping;
+export type Signal = CommonLinuxSignals | number;
+export declare function resolveSignal(signal: Signal): number;
+export {};

package/dist/utils/resolveSignal.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSignal = resolveSignal;
+const linuxSignalMapping = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGKILL: 9,
+    SIGTERM: 15,
+    SIGCONT: 18,
+    SIGSTOP: 19,
+};
+function resolveSignal(signal) {
+    if (typeof signal === "number") {
+        return signal;
+    }
+    if (signal in linuxSignalMapping) {
+        return linuxSignalMapping[signal];
+    }
+    throw new Error(`Unknown signal name: ${String(signal)}`);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.8";
+export declare const VERSION = "0.0.10";

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.8";
+exports.VERSION = "0.0.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -5,18 +5,18 @@ import {
   type RequestParams,
 } from "./base-client";
 import {
-  Command,
-  CommandFinished,
-  CreatedCommand,
-  CreatedSandbox,
+  SandboxAndRoutesResponse,
+  SandboxResponse,
+  CommandResponse,
+  CommandFinishedResponse,
+  EmptyResponse,
   LogLine,
-  StoppedSandbox,
-  WrittenFile,
 } from "./validators";
 import { APIError } from "./api-error";
 import { FileWriter } from "./file-writer";
 import { LRUCache } from "lru-cache";
 import { VERSION } from "../version";
+import { consumeReadable } from "../utils/consume-readable";
 import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
@@ -56,18 +56,32 @@ export class APIClient extends BaseClient {
     });
   }
 
+  async getSandbox(params: { sandboxId: string }) {
+    return parseOrThrow(
+      SandboxAndRoutesResponse,
+      await this.request(`/v1/sandboxes/${params.sandboxId}`),
+    );
+  }
+
   async createSandbox(params: {
     ports?: number[];
     projectId: string;
     source?:
-      | { type: "git"; url: string; depth?: number; revision?: string }
+      | {
+          type: "git";
+          url: string;
+          depth?: number;
+          revision?: string;
+          username?: string;
+          password?: string;
+        }
       | { type: "tarball"; url: string };
     timeout?: number;
     resources?: { vcpus: number };
     runtime?: "node22" | "python3.13";
   }) {
     return parseOrThrow(
-      CreatedSandbox,
+      SandboxAndRoutesResponse,
       await this.request("/v1/sandboxes", {
         method: "POST",
         body: JSON.stringify({
@@ -90,7 +104,7 @@ export class APIClient extends BaseClient {
     env: Record<string, string>;
   }) {
     return parseOrThrow(
-      CreatedCommand,
+      CommandResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/cmd`, {
         method: "POST",
         body: JSON.stringify({
@@ -107,12 +121,12 @@ export class APIClient extends BaseClient {
     sandboxId: string;
     cmdId: string;
     wait: true;
-  }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+  }): Promise<Parsed<z.infer<typeof CommandFinishedResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
     wait?: boolean;
-  }): Promise<Parsed<z.infer<typeof Command>>>;
+  }): Promise<Parsed<z.infer<typeof CommandResponse>>>;
   async getCommand(params: {
     sandboxId: string;
     cmdId: string;
@@ -120,14 +134,14 @@ export class APIClient extends BaseClient {
   }) {
     return params.wait
       ? parseOrThrow(
-          CommandFinished,
+          CommandFinishedResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
             { query: { wait: "true" } },
           ),
         )
       : parseOrThrow(
-          Command,
+          CommandResponse,
           await this.request(
             `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`,
           ),
@@ -136,7 +150,7 @@ export class APIClient extends BaseClient {
 
   async mkDir(params: { sandboxId: string; path: string; cwd?: string }) {
     return parseOrThrow(
-      WrittenFile,
+      EmptyResponse,
       await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
         method: "POST",
         body: JSON.stringify({ path: params.path, cwd: params.cwd }),
@@ -147,11 +161,13 @@ export class APIClient extends BaseClient {
   getFileWriter(params: { sandboxId: string }) {
     const writer = new FileWriter();
     return {
-      response: this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
-        method: "POST",
-        headers: { "content-type": "application/gzip" },
-        body: writer.readable,
-      }),
+      response: (async () => {
+        return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
+          method: "POST",
+          headers: { "content-type": "application/gzip" },
+          body: await consumeReadable(writer.readable),
+        });
+      })(),
       writer,
     };
   }
@@ -168,8 +184,8 @@ export class APIClient extends BaseClient {
       await writer.addFile({ name: file.path, content: file.stream });
     }
 
-    await writer.end();
-    await parseOrThrow(WrittenFile, await response);
+    writer.end();
+    await parseOrThrow(EmptyResponse, await response);
   }
 
   async readFile(params: {
@@ -192,6 +208,23 @@ export class APIClient extends BaseClient {
     return response.body;
   }
 
+  async killCommand(params: {
+    sandboxId: string;
+    commandId: string;
+    signal: number;
+  }) {
+    return parseOrThrow(
+      CommandResponse,
+      await this.request(
+        `/v1/sandboxes/${params.sandboxId}/${params.commandId}/kill`,
+        {
+          method: "POST",
+          body: JSON.stringify({ signal: params.signal }),
+        },
+      ),
+    );
+  }
+
   async *getLogs(params: {
     sandboxId: string;
     cmdId: string;
@@ -226,10 +259,10 @@ export class APIClient extends BaseClient {
 
   async stopSandbox(params: {
     sandboxId: string;
-  }): Promise<Parsed<z.infer<typeof StoppedSandbox>>> {
+  }): Promise<Parsed<z.infer<typeof SandboxResponse>>> {
     const url = `/v1/sandboxes/${params.sandboxId}/stop`;
     return parseOrThrow(
-      StoppedSandbox,
+      SandboxResponse,
       await this.request(url, { method: "POST" }),
     );
   }

package/src/api-client/index.ts

@@ -1 +1,2 @@
 export { APIClient } from "./api-client";
+export * from "./validators";

package/src/api-client/validators.ts

@@ -1,36 +1,66 @@
 import { z } from "zod";
 
-export const CreatedSandbox = z.object({
-  sandboxId: z.string(),
-  routes: z.array(z.object({ subdomain: z.string(), port: z.number() })),
+export type SandboxData = z.infer<typeof Sandbox>;
+
+export const Sandbox = z.object({
+  id: z.string(),
+  memory: z.number(),
+  vcpus: z.number(),
+  region: z.string(),
+  runtime: z.string(),
+  timeout: z.number(),
+  status: z.enum(["pending", "running", "stopping", "stopped", "failed"]),
+  requestedAt: z.number(),
+  startedAt: z.number().optional(),
+  requestedStopAt: z.number().optional(),
+  stoppedAt: z.number().optional(),
+  duration: z.number().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
 });
 
-export const CreatedCommand = z.object({
-  cmdId: z.string(),
+export type SandboxRouteData = z.infer<typeof SandboxRoute>;
+
+export const SandboxRoute = z.object({
+  url: z.string(),
+  subdomain: z.string(),
+  port: z.number(),
 });
 
+export type CommandData = z.infer<typeof Command>;
+
 export const Command = z.object({
+  id: z.string(),
+  name: z.string(),
   args: z.array(z.string()),
-  cmdId: z.string(),
   cwd: z.string(),
+  sandboxId: z.string(),
   exitCode: z.number().nullable(),
-  name: z.string(),
+  startedAt: z.number(),
 });
 
-export const CommandFinished = z.object({
-  args: z.array(z.string()),
-  cmdId: z.string(),
-  cwd: z.string(),
+const CommandFinished = Command.extend({
   exitCode: z.number(),
-  name: z.string(),
 });
 
-export const WrittenFile = z.object({});
+export const SandboxResponse = z.object({
+  sandbox: Sandbox,
+});
 
-export const StoppedSandbox = z.object({
-  sandboxId: z.string(),
+export const SandboxAndRoutesResponse = SandboxResponse.extend({
+  routes: z.array(SandboxRoute),
+});
+
+export const CommandResponse = z.object({
+  command: Command,
+});
+
+export const CommandFinishedResponse = z.object({
+  command: CommandFinished,
 });
 
+export const EmptyResponse = z.object({});
+
 export const LogLine = z.object({
   stream: z.enum(["stdout", "stderr"]),
   data: z.string(),

package/src/command.test.ts

@@ -1,17 +1,25 @@
-import { it, expect, vi } from "vitest";
+import { expect, it, vi, beforeEach, afterEach } from "vitest";
 import { Sandbox } from "./sandbox";
 
-it("warns when there is more than one logs consumer", async () => {
-  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-  const stdoutSpy = vi
-    .spyOn(process.stdout, "write")
-    .mockImplementation(() => true);
+let sandbox: Sandbox;
 
-  const sandbox = await Sandbox.create({
+beforeEach(async () => {
+  sandbox = await Sandbox.create({
     projectId: process.env.VERCEL_PROJECT_ID!,
     teamId: process.env.VERCEL_TEAM_ID!,
     token: process.env.VERCEL_TOKEN!,
   });
+});
+
+afterEach(async () => {
+  await sandbox.stop();
+});
+
+it("warns when there is more than one logs consumer", async () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation(() => true);
 
   const cmd = await sandbox.runCommand({
     cmd: "echo",
@@ -26,19 +34,11 @@ it("warns when there is more than one logs consumer", async () => {
       /Multiple consumers for logs of command `[^`]+`\.\sThis may lead to unexpected behavior\./,
     ),
   );
-
-  await sandbox.stop();
 });
 
 it("does not warn when there is only one logs consumer", async () => {
   const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
-  const sandbox = await Sandbox.create({
-    projectId: process.env.VERCEL_PROJECT_ID!,
-    teamId: process.env.VERCEL_TEAM_ID!,
-    token: process.env.VERCEL_TOKEN!,
-  });
-
   const cmd = await sandbox.runCommand({
     cmd: "echo",
     args: ["Hello World!"],
@@ -46,6 +46,29 @@ it("does not warn when there is only one logs consumer", async () => {
 
   expect(await cmd.stdout()).toEqual("Hello World!\n");
   expect(warnSpy).not.toHaveBeenCalled();
+});
 
-  await sandbox.stop();
+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
 });