@vercel/sandbox 0.0.4 → 0.0.6

package/.turbo/turbo-build.log

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

package/.turbo/turbo-typecheck.log

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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @vercel/sandbox
 
+## 0.0.6
+
+### Patch Changes
+
+- Better types for `Command` allowing a shorcut for waiting ([#29](https://github.com/vercel/sandbox-sdk/pull/29))
+
+- Remove `SDK` and simplify API surface ([#38](https://github.com/vercel/sandbox-sdk/pull/38))
+
+## 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

package/README.md

@@ -13,6 +13,7 @@ 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 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:
@@ -22,6 +23,7 @@ mkdir sandbox-test
 cd sandbox-test
 pnpm init
 pnpm add @vercel/sandbox ms
+pnpm add -D @types/ms @types/node
 ```
 
 Now create `next-dev.ts`:
@@ -31,7 +33,7 @@ Now create `next-dev.ts`:
 Run it like this:
 
 ```sh
-VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> node --experimental-strip-types ./next-dev.ts
+VERCEL_TEAM_ID=<team_id> VERCEL_TOKEN=<token> VERCEL_PROJECT_ID=<project_id> node --experimental-strip-types ./next-dev.ts
 ```
 
 This will:

package/dist/{client/client.d.ts → api-client/api-client.d.ts}

@@ -1,6 +1,8 @@
-import { APIClient, type RequestParams } from "./base-client";
+import { BaseClient, type Parsed, type RequestParams } from "./base-client";
+import { Command, CommandFinished, LogLine, StoppedSandbox } from "./validators";
 import { Readable } from "stream";
-export declare class SandboxClient extends APIClient {
+import { z } from "zod";
+export declare class APIClient extends BaseClient {
     private teamId;
     constructor(params: {
         host?: string;
@@ -9,14 +11,21 @@ export declare class SandboxClient extends APIClient {
     });
     protected request(path: string, params?: RequestParams): Promise<import("node-fetch").Response>;
     createSandbox(params: {
-        ports: number[];
+        ports?: number[];
         projectId: string;
-        source: {
+        source?: {
             type: "git";
             url: string;
+        } | {
+            type: "tarball";
+            url: string;
         };
         timeout?: number;
-    }): Promise<import("./base-client").Parsed<{
+        resources?: {
+            cores: number;
+            memory: number;
+        };
+    }): Promise<Parsed<{
         sandboxId: string;
         routes: {
             port: number;
@@ -28,20 +37,25 @@ export declare class SandboxClient extends APIClient {
         cwd?: string;
         command: string;
         args: string[];
-    }): Promise<import("./base-client").Parsed<{
+        env: Record<string, string>;
+    }): Promise<Parsed<{
         cmdId: string;
     }>>;
     getCommand(params: {
         sandboxId: string;
         cmdId: string;
-        wait?: boolean;
-    }): Promise<import("./base-client").Parsed<{
-        name: string;
-        cwd: string;
-        args: string[];
+        wait: true;
+    }): Promise<Parsed<z.infer<typeof CommandFinished>>>;
+    getCommand(params: {
+        sandboxId: string;
         cmdId: string;
-        exitCode: number | null;
-    }>>;
+        wait?: boolean;
+    }): Promise<Parsed<z.infer<typeof Command>>>;
+    mkDir(params: {
+        sandboxId: string;
+        path: string;
+        cwd?: string;
+    }): Promise<Parsed<{}>>;
     writeFiles(params: {
         sandboxId: string;
         files: {
@@ -57,8 +71,8 @@ export declare class SandboxClient extends APIClient {
     getLogs(params: {
         sandboxId: string;
         cmdId: string;
-    }): AsyncGenerator<{
-        data: string;
-        stream: "stdout" | "stderr";
-    }, void, void>;
+    }): AsyncIterable<z.infer<typeof LogLine>>;
+    stopSandbox(params: {
+        sandboxId: string;
+    }): Promise<Parsed<z.infer<typeof StoppedSandbox>>>;
 }

package/dist/{client/client.js → api-client/api-client.js}

@@ -3,16 +3,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxClient = void 0;
+exports.APIClient = void 0;
 const form_data_1 = __importDefault(require("form-data"));
 const base_client_1 = require("./base-client");
 const validators_1 = require("./validators");
 const api_error_1 = require("./api-error");
-const deferred_generator_1 = require("../utils/deferred-generator");
+const lru_cache_1 = require("lru-cache");
 const version_1 = require("../version");
 const jsonlines_1 = __importDefault(require("jsonlines"));
 const os_1 = __importDefault(require("os"));
-class SandboxClient extends base_client_1.APIClient {
+const ms_1 = __importDefault(require("ms"));
+/**
+ * Allows to track the logs hits for a command un a to maximum of items and
+ * TTL so that we don't incur in memory leaks in a log running process.
+ */
+const logHits = new lru_cache_1.LRUCache({
+    ttl: (0, ms_1.default)("45m"),
+    max: 1000,
+});
+class APIClient extends base_client_1.BaseClient {
     constructor(params) {
         super({
             host: params.host ?? "https://api.vercel.com",
@@ -40,6 +49,7 @@ class SandboxClient extends base_client_1.APIClient {
                 ports: params.ports,
                 source: params.source,
                 timeout: params.timeout,
+                resources: params.resources,
             }),
         }));
     }
@@ -50,11 +60,20 @@ class SandboxClient extends base_client_1.APIClient {
                 command: params.command,
                 args: params.args,
                 cwd: params.cwd,
+                env: params.env,
             }),
         }));
     }
     async getCommand(params) {
-        return (0, base_client_1.parseOrThrow)(validators_1.Command, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: params.wait ? "true" : undefined } }));
+        return params.wait
+            ? (0, base_client_1.parseOrThrow)(validators_1.CommandFinished, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`, { query: { wait: "true" } }))
+            : (0, base_client_1.parseOrThrow)(validators_1.Command, await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}`));
+    }
+    async mkDir(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.WrittenFile, await this.request(`/v1/sandboxes/${params.sandboxId}/fs/mkdir`, {
+            method: "POST",
+            body: JSON.stringify({ path: params.path, cwd: params.cwd }),
+        }));
     }
     async writeFiles(params) {
         const formData = new form_data_1.default();
@@ -77,46 +96,33 @@ class SandboxClient extends base_client_1.APIClient {
         }
         return response.body;
     }
-    getLogs(params) {
-        const deferred = (0, deferred_generator_1.createDeferredGenerator)();
-        (async () => {
-            const response = await this.request(`/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`, { method: "GET" });
-            if (response.headers.get("content-type") !== "application/x-ndjson") {
-                throw new api_error_1.APIError(response, {
-                    message: "Expected a stream of logs",
-                });
-            }
-            const parser = jsonlines_1.default.parse();
-            response.body.pipe(parser);
-            parser.on("data", (data) => {
-                const parsed = validators_1.LogLine.safeParse(data);
-                if (parsed.success) {
-                    deferred.next({
-                        value: parsed.data,
-                        done: false,
-                    });
-                }
-                else {
-                    deferred.next({
-                        value: Promise.reject(parsed.error),
-                        done: false,
-                    });
-                }
-            });
-            parser.on("error", (err) => {
-                deferred.next({
-                    value: Promise.reject(err),
-                    done: false,
-                });
+    async *getLogs(params) {
+        const url = `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`;
+        const response = await this.request(url, { method: "GET" });
+        if (response.headers.get("content-type") !== "application/x-ndjson") {
+            throw new api_error_1.APIError(response, {
+                message: "Expected a stream of logs",
             });
-            parser.on("end", () => {
-                deferred.next({
-                    value: undefined,
-                    done: true,
-                });
-            });
-        })();
-        return deferred.generator();
+        }
+        /**
+         * Currently, once we consume logs in the backend we cannot read them
+         * again. This logic writes a warning when the endpoint for a command
+         * logs is consumed more than once to alert the user about this.
+         *
+         * This is a temporary solution, we should be able to handle this in
+         * the backend in the future.
+         */
+        if (logHits.get(url)) {
+            console.warn(`Multiple consumers for logs of command \`${params.cmdId}\`. This may lead to unexpected behavior.`);
+        }
+        logHits.set(url, true);
+        for await (const chunk of response.body.pipe(jsonlines_1.default.parse())) {
+            yield validators_1.LogLine.parse(chunk);
+        }
+    }
+    async stopSandbox(params) {
+        const url = `/v1/sandboxes/${params.sandboxId}/stop`;
+        return (0, base_client_1.parseOrThrow)(validators_1.StoppedSandbox, await this.request(url, { method: "POST" }));
     }
 }
-exports.SandboxClient = SandboxClient;
+exports.APIClient = APIClient;

package/dist/{client → api-client}/base-client.d.ts

@@ -15,7 +15,7 @@ export interface RequestParams extends RequestInit {
  * we can pass query parameters as an object, support retries, debugging
  * and automatic authorization.
  */
-export declare class APIClient {
+export declare class BaseClient {
     protected token?: string;
     private fetch;
     private debug;

package/dist/{client → api-client}/base-client.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APIClient = void 0;
+exports.BaseClient = void 0;
 exports.parse = parse;
 exports.parseOrThrow = parseOrThrow;
 const api_error_1 = require("./api-error");
@@ -15,7 +15,7 @@ const node_fetch_1 = __importDefault(require("node-fetch"));
  * we can pass query parameters as an object, support retries, debugging
  * and automatic authorization.
  */
-class APIClient {
+class BaseClient {
     constructor(params) {
         this.fetch = (0, with_retry_1.withRetry)(node_fetch_1.default);
         this.host = params.host;
@@ -54,7 +54,7 @@ class APIClient {
         return response;
     }
 }
-exports.APIClient = APIClient;
+exports.BaseClient = BaseClient;
 /**
  * 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.

package/dist/api-client/index.d.ts

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

package/dist/api-client/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIClient = void 0;
+var api_client_1 = require("./api-client");
+Object.defineProperty(exports, "APIClient", { enumerable: true, get: function () { return api_client_1.APIClient; } });

package/dist/{client → api-client}/validators.d.ts

@@ -50,14 +50,33 @@ export declare const Command: z.ZodObject<{
     cmdId: string;
     exitCode: number | null;
 }>;
-export declare const FinishedCommand: z.ZodObject<{
+export declare const CommandFinished: z.ZodObject<{
+    args: z.ZodArray<z.ZodString, "many">;
     cmdId: z.ZodString;
+    cwd: z.ZodString;
+    exitCode: z.ZodNumber;
+    name: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    name: string;
+    cwd: string;
+    args: string[];
     cmdId: string;
+    exitCode: number;
 }, {
+    name: string;
+    cwd: string;
+    args: string[];
     cmdId: string;
+    exitCode: number;
 }>;
 export declare const WrittenFile: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const StoppedSandbox: z.ZodObject<{
+    sandboxId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sandboxId: string;
+}, {
+    sandboxId: string;
+}>;
 export declare const LogLine: z.ZodObject<{
     stream: z.ZodEnum<["stdout", "stderr"]>;
     data: z.ZodString;

package/dist/{client → api-client}/validators.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLine = exports.WrittenFile = exports.FinishedCommand = exports.Command = exports.CreatedCommand = exports.CreatedSandbox = void 0;
+exports.LogLine = exports.StoppedSandbox = exports.WrittenFile = exports.CommandFinished = exports.Command = exports.CreatedCommand = exports.CreatedSandbox = void 0;
 const zod_1 = require("zod");
 exports.CreatedSandbox = zod_1.z.object({
     sandboxId: zod_1.z.string(),
@@ -16,10 +16,17 @@ exports.Command = zod_1.z.object({
     exitCode: zod_1.z.number().nullable(),
     name: zod_1.z.string(),
 });
-exports.FinishedCommand = zod_1.z.object({
+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(),
+    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.LogLine = zod_1.z.object({
     stream: zod_1.z.enum(["stdout", "stderr"]),
     data: zod_1.z.string(),

package/dist/command.d.ts

@@ -0,0 +1,127 @@
+import { APIClient } from "./api-client";
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+export declare class Command {
+    /**
+     * @internal
+     * @private
+     */
+    protected client: APIClient;
+    /**
+     * ID of the sandbox this command is running in.
+     */
+    private sandboxId;
+    /**
+     * ID of the command execution.
+     */
+    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, }: {
+        client: APIClient;
+        sandboxId: string;
+        cmdId: string;
+    });
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     *
+     * @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(): AsyncIterable<{
+        data: string;
+        stream: "stdout" | "stderr";
+    }>;
+    /**
+     * Wait for a command to exit and populate its exit code.
+     *
+     * ```
+     * await cmd.wait()
+     * if (cmd.exitCode != 0) {
+     *   console.error("Something went wrong...")
+     * }
+     * ```
+     *
+     * @returns A {@link CommandFinished} instance with populated exit code.
+     */
+    wait(): Promise<CommandFinished>;
+    /**
+     * 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".
+     * @returns The output of the specified stream(s) as a string.
+     */
+    output(stream?: "stdout" | "stderr" | "both"): Promise<string>;
+    /**
+     * Get the output of `stdout` as a string.
+     *
+     * NOTE: This may throw string conversion errors if the command does
+     * not output valid Unicode.
+     *
+     * @returns The standard output of the command.
+     */
+    stdout(): Promise<string>;
+    /**
+     * Get the output of `stderr` as a string.
+     *
+     * NOTE: This may throw string conversion errors if the command does
+     * not output valid Unicode.
+     *
+     * @returns The standard error output of the command.
+     */
+    stderr(): Promise<string>;
+}
+/**
+ * A command that has finished executing.
+ *
+ * Contains the exit code of the command.
+ *
+ * @hideconstructor
+ */
+export declare class CommandFinished extends Command {
+    /**
+     * The exit code of the command, if available. This is set after
+     * {@link wait} has returned.
+     */
+    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;
+        cmdId: string;
+        exitCode: number;
+    });
+}

package/dist/command.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandFinished = exports.Command = void 0;
+/**
+ * A command executed in a Sandbox.
+ *
+ * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
+ * iterate over their output with {@link logs}.
+ *
+ * @see {@link Sandbox.runCommand} to start a command.
+ *
+ * @hideconstructor
+ */
+class Command {
+    /**
+     * @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, }) {
+        this.client = client;
+        this.sandboxId = sandboxId;
+        this.cmdId = cmdId;
+    }
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     *
+     * @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() {
+        return this.client.getLogs({
+            sandboxId: this.sandboxId,
+            cmdId: this.cmdId,
+        });
+    }
+    /**
+     * Wait for a command to exit and populate its exit code.
+     *
+     * ```
+     * await cmd.wait()
+     * if (cmd.exitCode != 0) {
+     *   console.error("Something went wrong...")
+     * }
+     * ```
+     *
+     * @returns A {@link CommandFinished} instance with populated exit code.
+     */
+    async wait() {
+        const command = await this.client.getCommand({
+            sandboxId: this.sandboxId,
+            cmdId: this.cmdId,
+            wait: true,
+        });
+        return new CommandFinished({
+            client: this.client,
+            sandboxId: this.sandboxId,
+            cmdId: command.json.cmdId,
+            exitCode: command.json.exitCode,
+        });
+    }
+    /**
+     * 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".
+     * @returns The output of the specified stream(s) as a string.
+     */
+    async output(stream = "both") {
+        let data = "";
+        for await (const log of this.logs()) {
+            if (stream === "both" || log.stream === stream) {
+                data += log.data;
+            }
+        }
+        return data;
+    }
+    /**
+     * Get the output of `stdout` as a string.
+     *
+     * NOTE: This may throw string conversion errors if the command does
+     * not output valid Unicode.
+     *
+     * @returns The standard output of the command.
+     */
+    async stdout() {
+        return this.output("stdout");
+    }
+    /**
+     * Get the output of `stderr` as a string.
+     *
+     * NOTE: This may throw string conversion errors if the command does
+     * not output valid Unicode.
+     *
+     * @returns The standard error output of the command.
+     */
+    async stderr() {
+        return this.output("stderr");
+    }
+}
+exports.Command = Command;
+/**
+ * A command that has finished executing.
+ *
+ * Contains the exit code of the command.
+ *
+ * @hideconstructor
+ */
+class CommandFinished extends Command {
+    /**
+     * @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) {
+        super({ ...params });
+        this.exitCode = params.exitCode;
+    }
+}
+exports.CommandFinished = CommandFinished;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxClient = exports.Command = exports.Sandbox = exports.SDK = void 0;
-var create_sandbox_1 = require("./create-sandbox");
-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; } });
+exports.CommandFinished = exports.Command = exports.Sandbox = void 0;
+var sandbox_1 = require("./sandbox");
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return sandbox_1.Sandbox; } });
+var command_1 = require("./command");
+Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return command_1.Command; } });
+Object.defineProperty(exports, "CommandFinished", { enumerable: true, get: function () { return command_1.CommandFinished; } });