@vercel/sandbox 0.0.8 → 0.0.9

package/dist/api-client/validators.js

@@ -1,32 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLine = exports.StoppedSandbox = exports.WrittenFile = exports.CommandFinished = exports.Command = exports.CreatedCommand = exports.CreatedSandbox = void 0;
+exports.LogLine = exports.EmptyResponse = exports.CommandFinishedResponse = exports.CommandResponse = exports.SandboxAndRoutesResponse = exports.SandboxResponse = exports.Command = exports.SandboxRoute = exports.Sandbox = void 0;
 const zod_1 = require("zod");
-exports.CreatedSandbox = zod_1.z.object({
-    sandboxId: zod_1.z.string(),
-    routes: zod_1.z.array(zod_1.z.object({ subdomain: zod_1.z.string(), port: zod_1.z.number() })),
+exports.Sandbox = zod_1.z.object({
+    id: zod_1.z.string(),
+    memory: zod_1.z.number(),
+    vcpus: zod_1.z.number(),
+    region: zod_1.z.string(),
+    runtime: zod_1.z.string(),
+    timeout: zod_1.z.number(),
+    status: zod_1.z.enum(["pending", "running", "stopping", "stopped", "failed"]),
+    requestedAt: zod_1.z.number(),
+    startedAt: zod_1.z.number().optional(),
+    requestedStopAt: zod_1.z.number().optional(),
+    stoppedAt: zod_1.z.number().optional(),
+    duration: zod_1.z.number().optional(),
+    createdAt: zod_1.z.number(),
+    updatedAt: zod_1.z.number(),
 });
-exports.CreatedCommand = zod_1.z.object({
-    cmdId: zod_1.z.string(),
+exports.SandboxRoute = zod_1.z.object({
+    url: zod_1.z.string(),
+    subdomain: zod_1.z.string(),
+    port: zod_1.z.number(),
 });
 exports.Command = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
     args: zod_1.z.array(zod_1.z.string()),
-    cmdId: zod_1.z.string(),
     cwd: zod_1.z.string(),
+    sandboxId: zod_1.z.string(),
     exitCode: zod_1.z.number().nullable(),
-    name: zod_1.z.string(),
+    startedAt: zod_1.z.number(),
 });
-exports.CommandFinished = zod_1.z.object({
-    args: zod_1.z.array(zod_1.z.string()),
-    cmdId: zod_1.z.string(),
-    cwd: zod_1.z.string(),
+const CommandFinished = exports.Command.extend({
     exitCode: zod_1.z.number(),
-    name: zod_1.z.string(),
 });
-exports.WrittenFile = zod_1.z.object({});
-exports.StoppedSandbox = zod_1.z.object({
-    sandboxId: zod_1.z.string(),
+exports.SandboxResponse = zod_1.z.object({
+    sandbox: exports.Sandbox,
+});
+exports.SandboxAndRoutesResponse = exports.SandboxResponse.extend({
+    routes: zod_1.z.array(exports.SandboxRoute),
+});
+exports.CommandResponse = zod_1.z.object({
+    command: exports.Command,
+});
+exports.CommandFinishedResponse = zod_1.z.object({
+    command: CommandFinished,
 });
+exports.EmptyResponse = zod_1.z.object({});
 exports.LogLine = zod_1.z.object({
     stream: zod_1.z.enum(["stdout", "stderr"]),
     data: zod_1.z.string(),

package/dist/command.d.ts

@@ -1,4 +1,5 @@
-import { APIClient } from "./api-client";
+import { APIClient, type CommandData } from "./api-client";
+import { Signal } from "./utils/resolveSignal";
 /**
  * A command executed in a Sandbox.
  *
@@ -19,20 +20,24 @@ export declare class Command {
      * ID of the sandbox this command is running in.
      */
     private sandboxId;
+    /**
+     * Data for the command execution.
+     */
+    private cmd;
     /**
      * ID of the command execution.
      */
-    cmdId: string;
+    get cmdId(): string;
     /**
      * @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, cmdId, }: {
+    constructor({ client, sandboxId, cmd, }: {
         client: APIClient;
         sandboxId: string;
-        cmdId: string;
+        cmd: CommandData;
     });
     /**
      * Iterate over the output of this command.
@@ -97,6 +102,14 @@ export declare class Command {
      * @returns The standard error output of the command.
      */
     stderr(): Promise<string>;
+    /**
+     * Kill a running command in a sandbox.
+     *
+     * @param params - commandId and the signal to send the running process.
+     * Defaults to SIGTERM.
+     * @returns Promise<void>.
+     */
+    kill(signal?: Signal): Promise<void>;
 }
 /**
  * A command that has finished executing.
@@ -121,7 +134,7 @@ export declare class CommandFinished extends Command {
     constructor(params: {
         client: APIClient;
         sandboxId: string;
-        cmdId: string;
+        cmd: CommandData;
         exitCode: number;
     });
 }

package/dist/command.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandFinished = exports.Command = void 0;
+const resolveSignal_1 = require("./utils/resolveSignal");
 /**
  * A command executed in a Sandbox.
  *
@@ -12,16 +13,22 @@ exports.CommandFinished = exports.Command = void 0;
  * @hideconstructor
  */
 class Command {
+    /**
+     * ID of the command execution.
+     */
+    get cmdId() {
+        return this.cmd.id;
+    }
     /**
      * @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, cmdId, }) {
+    constructor({ client, sandboxId, cmd, }) {
         this.client = client;
         this.sandboxId = sandboxId;
-        this.cmdId = cmdId;
+        this.cmd = cmd;
     }
     /**
      * Iterate over the output of this command.
@@ -44,7 +51,7 @@ class Command {
     logs() {
         return this.client.getLogs({
             sandboxId: this.sandboxId,
-            cmdId: this.cmdId,
+            cmdId: this.cmd.id,
         });
     }
     /**
@@ -62,14 +69,14 @@ class Command {
     async wait() {
         const command = await this.client.getCommand({
             sandboxId: this.sandboxId,
-            cmdId: this.cmdId,
+            cmdId: this.cmd.id,
             wait: true,
         });
         return new CommandFinished({
             client: this.client,
             sandboxId: this.sandboxId,
-            cmdId: command.json.cmdId,
-            exitCode: command.json.exitCode,
+            cmd: command.json.command,
+            exitCode: command.json.command.exitCode,
         });
     }
     /**
@@ -112,6 +119,20 @@ class Command {
     async stderr() {
         return this.output("stderr");
     }
+    /**
+     * Kill a running command in a sandbox.
+     *
+     * @param params - commandId and the signal to send the running process.
+     * Defaults to SIGTERM.
+     * @returns Promise<void>.
+     */
+    async kill(signal) {
+        await this.client.killCommand({
+            sandboxId: this.sandboxId,
+            commandId: this.cmd.id,
+            signal: (0, resolveSignal_1.resolveSignal)(signal ?? "SIGTERM"),
+        });
+    }
 }
 exports.Command = Command;
 /**

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 {
@@ -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.
      *

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,7 +139,7 @@ class Sandbox {
      */
     async mkDir(path) {
         await this.client.mkDir({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             path: path,
         });
     }
@@ -138,7 +151,7 @@ class Sandbox {
      */
     async writeFiles(files) {
         return this.client.writeFiles({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
             files: files,
         });
     }
@@ -165,7 +178,7 @@ class Sandbox {
      */
     async stop() {
         await this.client.stopSandbox({
-            sandboxId: this.sandboxId,
+            sandboxId: this.sandbox.id,
         });
     }
 }

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.9";

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.9";

package/package.json

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

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

@@ -5,13 +5,12 @@ 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";
@@ -56,6 +55,13 @@ 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;
@@ -67,7 +73,7 @@ export class APIClient extends BaseClient {
     runtime?: "node22" | "python3.13";
   }) {
     return parseOrThrow(
-      CreatedSandbox,
+      SandboxAndRoutesResponse,
       await this.request("/v1/sandboxes", {
         method: "POST",
         body: JSON.stringify({
@@ -90,7 +96,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 +113,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 +126,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 +142,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 }),
@@ -169,7 +175,7 @@ export class APIClient extends BaseClient {
     }
 
     await writer.end();
-    await parseOrThrow(WrittenFile, await response);
+    await parseOrThrow(EmptyResponse, await response);
   }
 
   async readFile(params: {
@@ -192,6 +198,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 +249,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(),