@vercel/sandbox 0.0.3 → 0.0.5

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.3 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.5 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.3 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.5 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @vercel/sandbox
 
+## 0.0.5
+
+### Patch Changes
+
+- Allow specifying env vars and cwd when running commands ([#25](https://github.com/vercel/sandbox-sdk/pull/25))
+
+- createSandbox: do not require ports to be specified ([#27](https://github.com/vercel/sandbox-sdk/pull/27))
+
+## 0.0.4
+
+### Patch Changes
+
+- Rename `SandboxSDK` to `SDK` and incorporate `projectId` as a required parameter ([#21](https://github.com/vercel/sandbox-sdk/pull/21))
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -12,31 +12,37 @@ infrastructure][hive] that powers 1M+ builds a day at Vercel.
 Vercel Sandbox is in private beta. These examples will not work unless these
 APIs are enabled for your team.
 
- - Go to your team settings, and copy the team ID.
- - Go to your Vercel account settings and [create a token][create-token]. Make
-   sure it is scoped to the team ID from the previous step.
- - Create a new project:
-
-```
-$ mkdir sandbox-test
-$ pnpm init
-$ pnpm add @vercel/sandbox
-$ pnpm add --save-dev tsx
+- Go to your team settings, and copy the team ID.
+- Go to a project's settings, and copy the project ID.
+- Go to your Vercel account settings and [create a token][create-token]. Make
+  sure it is scoped to the team ID from the previous step.
+- Create a new project:
+
+```sh
+mkdir sandbox-test
+cd sandbox-test
+pnpm init
+pnpm add @vercel/sandbox ms
 ```
 
-Now create `whoami.ts`:
+Now create `next-dev.ts`:
 
-{@includeCode ../cli/src/example-whoami.ts}
+{@includeCode ../cli/src/example-next.ts}
 
 Run it like this:
 
+```sh
+VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> VERCEL_PROJECT_ID=<project_id> node --experimental-strip-types ./next-dev.ts
 ```
-$ VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> pnpm tsx ./whoami.ts
-Running as: vercel-sandbox
-Working dir: /vercel/sandbox
-```
 
-Now have a look at the sidebar for which classes exist.
+This will:
+
+- Start a sandbox, seeding it with a git repository.
+- Install dependencies.
+- Run a `next dev` server
+- Open it in your browser
+
+All while streaming logs to your local terminal.
 
 ## Limitations
 

package/dist/client/client.d.ts

@@ -9,11 +9,12 @@ export declare class SandboxClient extends APIClient {
     });
     protected request(path: string, params?: RequestParams): Promise<import("node-fetch").Response>;
     createSandbox(params: {
+        ports: number[];
+        projectId: string;
         source: {
             type: "git";
             url: string;
         };
-        ports: number[];
         timeout?: number;
     }): Promise<import("./base-client").Parsed<{
         sandboxId: string;
@@ -27,6 +28,7 @@ export declare class SandboxClient extends APIClient {
         cwd?: string;
         command: string;
         args: string[];
+        env: Record<string, string>;
     }): Promise<import("./base-client").Parsed<{
         cmdId: string;
     }>>;

package/dist/client/client.js

@@ -36,6 +36,7 @@ class SandboxClient extends base_client_1.APIClient {
         return (0, base_client_1.parseOrThrow)(validators_1.CreatedSandbox, await this.request("/v1/sandboxes", {
             method: "POST",
             body: JSON.stringify({
+                projectId: params.projectId,
                 ports: params.ports,
                 source: params.source,
                 timeout: params.timeout,
@@ -49,6 +50,7 @@ class SandboxClient extends base_client_1.APIClient {
                 command: params.command,
                 args: params.args,
                 cwd: params.cwd,
+                env: params.env,
             }),
         }));
     }

package/dist/create-sandbox.d.ts

@@ -1,37 +1,58 @@
 import { SandboxClient } from "./client/client";
 import { Readable } from "stream";
 /**
- * Create a new instance of the SandboxSDK.
+ * SDK for interacting with the Sandbox API. Provides methods to create and
+ * manage sandboxes configured with specific source code and network ports.
  *
- * ````
- * const teamId = process.env.VERCEL_TEAM_ID
- * const token = process.env.VERCEL_TOKEN
- * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
- * ````
+ * Example:
+ * ```ts
+ * const sdk = new SDK({
+ *   teamId: process.env.VERCEL_TEAM_ID!,
+ *   token: process.env.VERCEL_TOKEN!,
+ * });
+ * ```
  *
- * @see {@link createSandbox} to start a sandbox.
+ * @see {@link SDK.createSandbox} to start a new sandbox.
  */
-export declare class SandboxSDK {
-    client: SandboxClient;
+export declare class SDK {
+    /**
+     * Internal API client for communicating with the sandbox backend.
+     */
+    private client;
+    /**
+     * Create a new instance of `SDK`.
+     *
+     * @param config - Configuration options for the SDK.
+     * @param config.teamId - The Vercel team ID used to scope the Sandbox.
+     * @param config.token - The API token used for authentication.
+     */
     constructor({ teamId, token }: {
         teamId: string;
         token: string;
     });
     /**
-     * Create a new Sandbox with the given resources, source code, and ports.
+     * Creates a new sandbox instance using the provided Git repository and exposed ports.
      *
-     * Upon start, the sandbox will perform a `git clone` of the repository given.
-     * This repo needs to be public.
+     * The repository must be public. On start, the sandbox will clone the repository
+     * and expose the specified ports for access.
      *
-     * @param params
-     * @returns a
+     * @param params - Configuration parameters for the sandbox.
+     * @param params.source - The source of the sandbox, currently supports Git repositories only.
+     * @param params.source.type - Type of source, must be `"git"`.
+     * @param params.source.url - The URL of the public Git repository to clone.
+     * @param params.projectId - The Vercel project ID used to link the Sandbox to.
+     * @param params.ports - Array of port numbers to expose from the sandbox.
+     * @param params.timeout - (Optional) Timeout in seconds before the sandbox auto-terminates.
+     *
+     * @returns A promise that resolves to a `Sandbox` instance.
      */
     createSandbox(params: {
         source: {
             type: "git";
             url: string;
         };
-        ports: number[];
+        projectId: string;
+        ports?: number[];
         timeout?: number;
     }): Promise<Sandbox>;
     /** @hidden */
@@ -43,10 +64,21 @@ export declare class SandboxSDK {
         sandboxId: string;
     }): Promise<Sandbox>;
 }
+/** @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>;
+}
 /**
  * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
  *
- * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @see {@link SDK.createSandbox} to construct a Sandbox.
  * @hideconstructor
  */
 export declare class Sandbox {
@@ -70,11 +102,22 @@ export declare class Sandbox {
     });
     /**
      * Start executing a command in this sandbox.
-     * @param command
-     * @param args
-     * @returns
+     *
+     * @param command - The command to execute.
+     * @param args - Arguments to pass to the command.
+     *
+     * @returns A {@link Command} instance.
      */
     runCommand(command: string, args?: string[]): Promise<Command>;
+    /**
+     * Start executing a command in this sandbox.
+     *
+     * @param params - What should be executed.
+     *
+     * @returns A {@link Command} instance.
+     */
+    runCommand(params: RunCommandParams): Promise<Command>;
+    _runCommand(params: RunCommandParams): Promise<Command>;
     /**
      * Write files to the filesystem of this sandbox.
      */
@@ -173,3 +216,4 @@ export declare class Command {
      */
     stderr(): Promise<string>;
 }
+export {};

package/dist/create-sandbox.js

@@ -1,36 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Command = exports.Sandbox = exports.SandboxSDK = void 0;
+exports.Command = exports.Sandbox = exports.SDK = void 0;
 const client_1 = require("./client/client");
 /**
- * Create a new instance of the SandboxSDK.
+ * SDK for interacting with the Sandbox API. Provides methods to create and
+ * manage sandboxes configured with specific source code and network ports.
  *
- * ````
- * const teamId = process.env.VERCEL_TEAM_ID
- * const token = process.env.VERCEL_TOKEN
- * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
- * ````
+ * Example:
+ * ```ts
+ * const sdk = new SDK({
+ *   teamId: process.env.VERCEL_TEAM_ID!,
+ *   token: process.env.VERCEL_TOKEN!,
+ * });
+ * ```
  *
- * @see {@link createSandbox} to start a sandbox.
+ * @see {@link SDK.createSandbox} to start a new sandbox.
  */
-class SandboxSDK {
+class SDK {
+    /**
+     * Create a new instance of `SDK`.
+     *
+     * @param config - Configuration options for the SDK.
+     * @param config.teamId - The Vercel team ID used to scope the Sandbox.
+     * @param config.token - The API token used for authentication.
+     */
     constructor({ teamId, token }) {
         this.client = new client_1.SandboxClient({ teamId, token });
     }
     /**
-     * Create a new Sandbox with the given resources, source code, and ports.
+     * Creates a new sandbox instance using the provided Git repository and exposed ports.
+     *
+     * The repository must be public. On start, the sandbox will clone the repository
+     * and expose the specified ports for access.
      *
-     * Upon start, the sandbox will perform a `git clone` of the repository given.
-     * This repo needs to be public.
+     * @param params - Configuration parameters for the sandbox.
+     * @param params.source - The source of the sandbox, currently supports Git repositories only.
+     * @param params.source.type - Type of source, must be `"git"`.
+     * @param params.source.url - The URL of the public Git repository to clone.
+     * @param params.projectId - The Vercel project ID used to link the Sandbox to.
+     * @param params.ports - Array of port numbers to expose from the sandbox.
+     * @param params.timeout - (Optional) Timeout in seconds before the sandbox auto-terminates.
      *
-     * @param params
-     * @returns a
+     * @returns A promise that resolves to a `Sandbox` instance.
      */
     async createSandbox(params) {
         const { client } = this;
         const sandbox = await client.createSandbox({
             source: params.source,
-            ports: params.ports,
+            projectId: params.projectId,
+            ports: params.ports ?? [],
             timeout: params.timeout,
         });
         return new Sandbox({
@@ -48,11 +66,11 @@ class SandboxSDK {
         });
     }
 }
-exports.SandboxSDK = SandboxSDK;
+exports.SDK = SDK;
 /**
  * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
  *
- * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @see {@link SDK.createSandbox} to construct a Sandbox.
  * @hideconstructor
  */
 class Sandbox {
@@ -61,17 +79,18 @@ class Sandbox {
         this.routes = routes;
         this.sandboxId = sandboxId;
     }
-    /**
-     * Start executing a command in this sandbox.
-     * @param command
-     * @param args
-     * @returns
-     */
-    async runCommand(command, args = []) {
+    async runCommand(commandOrParams, args) {
+        return typeof commandOrParams === "string"
+            ? this._runCommand({ cmd: commandOrParams, args })
+            : this._runCommand(commandOrParams);
+    }
+    async _runCommand(params) {
         const commandResponse = await this.client.runCommand({
             sandboxId: this.sandboxId,
-            command,
-            args,
+            command: params.cmd,
+            args: params.args ?? [],
+            cwd: params.cwd,
+            env: params.env ?? {},
         });
         return new Command({
             client: this.client,

package/dist/index.d.ts

@@ -1,2 +1 @@
-export { SandboxSDK, Sandbox, Command } from "./create-sandbox";
-export { SandboxClient } from "./client/client";
+export { SDK, Sandbox, Command } from "./create-sandbox";

package/dist/index.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxClient = exports.Command = exports.Sandbox = exports.SandboxSDK = void 0;
+exports.Command = exports.Sandbox = exports.SDK = void 0;
 var create_sandbox_1 = require("./create-sandbox");
-Object.defineProperty(exports, "SandboxSDK", { enumerable: true, get: function () { return create_sandbox_1.SandboxSDK; } });
+Object.defineProperty(exports, "SDK", { enumerable: true, get: function () { return create_sandbox_1.SDK; } });
 Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return create_sandbox_1.Sandbox; } });
 Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return create_sandbox_1.Command; } });
-var client_1 = require("./client/client");
-Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_1.SandboxClient; } });

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.3";
+export declare const VERSION = "0.0.5";

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.3";
+exports.VERSION = "0.0.5";

package/package.json

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

package/src/client/client.ts

@@ -41,8 +41,9 @@ export class SandboxClient extends APIClient {
   }
 
   async createSandbox(params: {
-    source: { type: "git"; url: string };
     ports: number[];
+    projectId: string;
+    source: { type: "git"; url: string };
     timeout?: number;
   }) {
     return parseOrThrow(
@@ -50,6 +51,7 @@ export class SandboxClient extends APIClient {
       await this.request("/v1/sandboxes", {
         method: "POST",
         body: JSON.stringify({
+          projectId: params.projectId,
           ports: params.ports,
           source: params.source,
           timeout: params.timeout,
@@ -63,6 +65,7 @@ export class SandboxClient extends APIClient {
     cwd?: string;
     command: string;
     args: string[];
+    env: Record<string, string>;
   }) {
     return parseOrThrow(
       CreatedCommand,
@@ -72,6 +75,7 @@ export class SandboxClient extends APIClient {
           command: params.command,
           args: params.args,
           cwd: params.cwd,
+          env: params.env,
         }),
       }),
     );

package/src/create-sandbox.ts

@@ -2,41 +2,63 @@ import { SandboxClient } from "./client/client";
 import { Readable } from "stream";
 
 /**
- * Create a new instance of the SandboxSDK.
+ * SDK for interacting with the Sandbox API. Provides methods to create and
+ * manage sandboxes configured with specific source code and network ports.
  *
- * ````
- * const teamId = process.env.VERCEL_TEAM_ID
- * const token = process.env.VERCEL_TOKEN
- * const sdk = new SandboxSDK({ teamId: teamId!, token: token! });
- * ````
+ * Example:
+ * ```ts
+ * const sdk = new SDK({
+ *   teamId: process.env.VERCEL_TEAM_ID!,
+ *   token: process.env.VERCEL_TOKEN!,
+ * });
+ * ```
  *
- * @see {@link createSandbox} to start a sandbox.
+ * @see {@link SDK.createSandbox} to start a new sandbox.
  */
-export class SandboxSDK {
-  public client: SandboxClient;
+export class SDK {
+  /**
+   * Internal API client for communicating with the sandbox backend.
+   */
+  private client: SandboxClient;
 
+  /**
+   * Create a new instance of `SDK`.
+   *
+   * @param config - Configuration options for the SDK.
+   * @param config.teamId - The Vercel team ID used to scope the Sandbox.
+   * @param config.token - The API token used for authentication.
+   */
   constructor({ teamId, token }: { teamId: string; token: string }) {
     this.client = new SandboxClient({ teamId, token });
   }
 
   /**
-   * Create a new Sandbox with the given resources, source code, and ports.
+   * Creates a new sandbox instance using the provided Git repository and exposed ports.
+   *
+   * The repository must be public. On start, the sandbox will clone the repository
+   * and expose the specified ports for access.
    *
-   * Upon start, the sandbox will perform a `git clone` of the repository given.
-   * This repo needs to be public.
+   * @param params - Configuration parameters for the sandbox.
+   * @param params.source - The source of the sandbox, currently supports Git repositories only.
+   * @param params.source.type - Type of source, must be `"git"`.
+   * @param params.source.url - The URL of the public Git repository to clone.
+   * @param params.projectId - The Vercel project ID used to link the Sandbox to.
+   * @param params.ports - Array of port numbers to expose from the sandbox.
+   * @param params.timeout - (Optional) Timeout in seconds before the sandbox auto-terminates.
    *
-   * @param params
-   * @returns a
+   * @returns A promise that resolves to a `Sandbox` instance.
    */
   async createSandbox(params: {
     source: { type: "git"; url: string };
-    ports: number[];
+    projectId: string;
+    ports?: number[];
     timeout?: number;
   }) {
     const { client } = this;
     const sandbox = await client.createSandbox({
       source: params.source,
-      ports: params.ports,
+      projectId: params.projectId,
+      ports: params.ports ?? [],
       timeout: params.timeout,
     });
 
@@ -63,10 +85,22 @@ export class SandboxSDK {
   }
 }
 
+/** @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>;
+}
+
 /**
  * A Sandbox is an isolated Linux MicroVM that you can your experiments on.
  *
- * @see {@link SandboxSDK.createSandbox} to construct a Sandbox.
+ * @see {@link SDK.createSandbox} to construct a Sandbox.
  * @hideconstructor
  */
 export class Sandbox {
@@ -96,15 +130,39 @@ export class Sandbox {
 
   /**
    * Start executing a command in this sandbox.
-   * @param command
-   * @param args
-   * @returns
+   *
+   * @param command - The command to execute.
+   * @param args - Arguments to pass to the command.
+   *
+   * @returns A {@link Command} instance.
+   */
+  async runCommand(command: string, args?: string[]): Promise<Command>;
+
+  /**
+   * Start executing a command in this sandbox.
+   *
+   * @param params - What should be executed.
+   *
+   * @returns A {@link Command} instance.
    */
-  async runCommand(command: string, args: string[] = []) {
+  async runCommand(params: RunCommandParams): Promise<Command>;
+
+  async runCommand(
+    commandOrParams: string | RunCommandParams,
+    args?: string[],
+  ): Promise<Command> {
+    return typeof commandOrParams === "string"
+      ? this._runCommand({ cmd: commandOrParams, args })
+      : this._runCommand(commandOrParams);
+  }
+
+  async _runCommand(params: RunCommandParams) {
     const commandResponse = await this.client.runCommand({
       sandboxId: this.sandboxId,
-      command,
-      args,
+      command: params.cmd,
+      args: params.args ?? [],
+      cwd: params.cwd,
+      env: params.env ?? {},
     });
 
     return new Command({

package/src/index.ts

@@ -1,2 +1 @@
-export { SandboxSDK, Sandbox, Command } from "./create-sandbox";
-export { SandboxClient } from "./client/client";
+export { SDK, Sandbox, Command } from "./create-sandbox";

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.3";
+export const VERSION = "0.0.5";