@vercel/sandbox 0.0.17 → 0.0.19

package/.turbo/turbo-build.log

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

package/.turbo/turbo-typecheck.log

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

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @vercel/sandbox
 
+## 0.0.19
+
+### Patch Changes
+
+- https://github.com/vercel/sandbox-sdk/pull/104/files introduced `Sandbox.list` ([#119](https://github.com/vercel/sandbox-sdk/pull/119))
+
+- support interrupting the log consuming ([#123](https://github.com/vercel/sandbox-sdk/pull/123))
+
+  - using [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) with `cmd.logs({ signal })`
+  - using [`Disposable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using) with `using logs = cmd.logs()`
+
+## 0.0.18
+
+### Patch Changes
+
+- refresh oidc token if stale in development ([#106](https://github.com/vercel/sandbox-sdk/pull/106))
+
 ## 0.0.17
 
 ### Patch Changes

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

@@ -2,13 +2,16 @@ import { BaseClient, type Parsed, type RequestParams } from "./base-client";
 import { SandboxResponse, CommandResponse, CommandFinishedResponse, LogLine } from "./validators";
 import { FileWriter } from "./file-writer";
 import { z } from "zod";
+import { WithPrivate } from "../utils/types";
 export declare class APIClient extends BaseClient {
     private teamId;
+    private tokenExpiry;
     constructor(params: {
         host?: string;
         teamId: string;
         token: string;
     });
+    private ensureValidToken;
     protected request(path: string, params?: RequestParams): Promise<Response>;
     getSandbox(params: {
         sandboxId: string;
@@ -36,7 +39,7 @@ export declare class APIClient extends BaseClient {
             port: number;
         }[];
     }>>;
-    createSandbox(params: {
+    createSandbox(params: WithPrivate<{
         ports?: number[];
         projectId: string;
         source?: {
@@ -55,7 +58,7 @@ export declare class APIClient extends BaseClient {
             vcpus: number;
         };
         runtime?: "node22" | "python3.13" | (string & {});
-    }): Promise<Parsed<{
+    }>): Promise<Parsed<{
         sandbox: {
             region: string;
             status: "pending" | "running" | "stopping" | "stopped" | "failed";
@@ -119,6 +122,51 @@ export declare class APIClient extends BaseClient {
         response: Promise<Response>;
         writer: FileWriter;
     };
+    listSandboxes(params: {
+        /**
+         * The ID or name of the project to which the sandboxes belong.
+         * @example "my-project"
+         */
+        projectId: string;
+        /**
+         * Maximum number of sandboxes to list from a request.
+         * @example 10
+         */
+        limit?: number;
+        /**
+         * Get sandboxes created after this JavaScript timestamp.
+         * @example 1540095775941
+         */
+        since?: number | Date;
+        /**
+         * Get sandboxes created before this JavaScript timestamp.
+         * @example 1540095775951
+         */
+        until?: number | Date;
+    }): Promise<Parsed<{
+        sandboxes: {
+            region: string;
+            status: "pending" | "running" | "stopping" | "stopped" | "failed";
+            id: string;
+            memory: number;
+            vcpus: number;
+            runtime: string;
+            timeout: number;
+            requestedAt: number;
+            createdAt: number;
+            cwd: string;
+            updatedAt: number;
+            duration?: number | undefined;
+            startedAt?: number | undefined;
+            requestedStopAt?: number | undefined;
+            stoppedAt?: number | undefined;
+        }[];
+        pagination: {
+            count: number;
+            next: number | null;
+            prev: number | null;
+        };
+    }>>;
     writeFiles(params: {
         sandboxId: string;
         cwd: string;
@@ -151,7 +199,10 @@ export declare class APIClient extends BaseClient {
     getLogs(params: {
         sandboxId: string;
         cmdId: string;
-    }): AsyncIterable<z.infer<typeof LogLine>>;
+        signal?: AbortSignal;
+    }): AsyncGenerator<z.infer<typeof LogLine>, void, void> & Disposable & {
+        close(): void;
+    };
     stopSandbox(params: {
         sandboxId: string;
     }): Promise<Parsed<z.infer<typeof SandboxResponse>>>;

package/dist/api-client/api-client.js

@@ -14,6 +14,8 @@ const jsonlines_1 = __importDefault(require("jsonlines"));
 const os_1 = __importDefault(require("os"));
 const stream_1 = require("stream");
 const normalizePath_1 = require("../utils/normalizePath");
+const jwt_expiry_1 = require("../utils/jwt-expiry");
+const types_1 = require("../utils/types");
 class APIClient extends base_client_1.BaseClient {
     constructor(params) {
         super({
@@ -22,8 +24,24 @@ class APIClient extends base_client_1.BaseClient {
             debug: false,
         });
         this.teamId = params.teamId;
+        this.tokenExpiry = jwt_expiry_1.JwtExpiry.fromToken(params.token);
+    }
+    async ensureValidToken() {
+        if (!this.tokenExpiry) {
+            return;
+        }
+        const newExpiry = await this.tokenExpiry.tryRefresh();
+        if (!newExpiry) {
+            return;
+        }
+        this.tokenExpiry = newExpiry;
+        this.token = this.tokenExpiry.token;
+        if (this.tokenExpiry.payload) {
+            this.teamId = this.tokenExpiry.payload?.owner_id;
+        }
     }
     async request(path, params) {
+        await this.ensureValidToken();
         return super.request(path, {
             ...params,
             query: { teamId: this.teamId, ...params?.query },
@@ -38,6 +56,7 @@ class APIClient extends base_client_1.BaseClient {
         return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request(`/v1/sandboxes/${params.sandboxId}`));
     }
     async createSandbox(params) {
+        const privateParams = (0, types_1.getPrivateParams)(params);
         return (0, base_client_1.parseOrThrow)(validators_1.SandboxAndRoutesResponse, await this.request("/v1/sandboxes", {
             method: "POST",
             body: JSON.stringify({
@@ -47,6 +66,7 @@ class APIClient extends base_client_1.BaseClient {
                 timeout: params.timeout,
                 resources: params.resources,
                 runtime: params.runtime,
+                ...privateParams,
             }),
         }));
     }
@@ -89,6 +109,21 @@ class APIClient extends base_client_1.BaseClient {
             writer,
         };
     }
+    async listSandboxes(params) {
+        return (0, base_client_1.parseOrThrow)(validators_1.SandboxesResponse, await this.request(`/v1/sandboxes`, {
+            query: {
+                project: params.projectId,
+                limit: params.limit,
+                since: typeof params.since === "number"
+                    ? params.since
+                    : params.since?.getTime(),
+                until: typeof params.until === "number"
+                    ? params.until
+                    : params.until?.getTime(),
+            },
+            method: "GET",
+        }));
+    }
     async writeFiles(params) {
         const { writer, response } = this.getFileWriter({
             sandboxId: params.sandboxId,
@@ -126,22 +161,42 @@ class APIClient extends base_client_1.BaseClient {
             body: JSON.stringify({ signal: params.signal }),
         }));
     }
-    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",
+    getLogs(params) {
+        const self = this;
+        const disposer = new AbortController();
+        const signal = !params.signal
+            ? disposer.signal
+            : mergeSignals(params.signal, disposer.signal);
+        const generator = (async function* () {
+            const url = `/v1/sandboxes/${params.sandboxId}/cmd/${params.cmdId}/logs`;
+            const response = await self.request(url, {
+                method: "GET",
+                signal,
             });
-        }
-        if (response.body === null) {
-            throw new api_error_1.APIError(response, {
-                message: "No response body",
+            if (response.headers.get("content-type") !== "application/x-ndjson") {
+                throw new api_error_1.APIError(response, {
+                    message: "Expected a stream of logs",
+                });
+            }
+            if (response.body === null) {
+                throw new api_error_1.APIError(response, {
+                    message: "No response body",
+                });
+            }
+            const jsonlinesStream = jsonlines_1.default.parse();
+            pipe(response.body, jsonlinesStream).catch((err) => {
+                console.error("Error piping logs:", err);
             });
-        }
-        for await (const chunk of stream_1.Readable.fromWeb(response.body).pipe(jsonlines_1.default.parse())) {
-            yield validators_1.LogLine.parse(chunk);
-        }
+            for await (const chunk of jsonlinesStream) {
+                yield validators_1.LogLine.parse(chunk);
+            }
+        })();
+        return Object.assign(generator, {
+            [Symbol.dispose]() {
+                disposer.abort("Disposed");
+            },
+            close: () => disposer.abort("Disposed"),
+        });
     }
     async stopSandbox(params) {
         const url = `/v1/sandboxes/${params.sandboxId}/stop`;
@@ -149,3 +204,40 @@ class APIClient extends base_client_1.BaseClient {
     }
 }
 exports.APIClient = APIClient;
+async function pipe(readable, output) {
+    const reader = readable.getReader();
+    try {
+        while (true) {
+            const read = await reader.read();
+            if (read.value) {
+                output.write(Buffer.from(read.value));
+            }
+            if (read.done) {
+                break;
+            }
+        }
+    }
+    catch (err) {
+        output.emit("error", err);
+    }
+    finally {
+        output.end();
+    }
+}
+function mergeSignals(...signals) {
+    const controller = new AbortController();
+    const onAbort = () => {
+        controller.abort();
+        for (const signal of signals) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    };
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort();
+            break;
+        }
+        signal.addEventListener("abort", onAbort);
+    }
+    return controller.signal;
+}

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

@@ -63,6 +63,31 @@ export declare const SandboxRoute: z.ZodObject<{
     subdomain: string;
     port: number;
 }>;
+export declare const Pagination: z.ZodObject<{
+    /**
+     * Amount of items in the current page.
+     * @example 20
+     */
+    count: z.ZodNumber;
+    /**
+     * Timestamp that must be used to request the next page.
+     * @example 1540095775951
+     */
+    next: z.ZodNullable<z.ZodNumber>;
+    /**
+     * Timestamp that must be used to request the previous page.
+     * @example 1540095775951
+     */
+    prev: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    next: number | null;
+    prev: number | null;
+}, {
+    count: number;
+    next: number | null;
+    prev: number | null;
+}>;
 export type CommandData = z.infer<typeof Command>;
 export declare const Command: z.ZodObject<{
     id: z.ZodString;
@@ -393,3 +418,125 @@ export declare const LogLine: z.ZodObject<{
     stream: "stdout" | "stderr";
     data: string;
 }>;
+export declare const SandboxesResponse: z.ZodObject<{
+    sandboxes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        memory: z.ZodNumber;
+        vcpus: z.ZodNumber;
+        region: z.ZodString;
+        runtime: z.ZodString;
+        timeout: z.ZodNumber;
+        status: z.ZodEnum<["pending", "running", "stopping", "stopped", "failed"]>;
+        requestedAt: z.ZodNumber;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        requestedStopAt: z.ZodOptional<z.ZodNumber>;
+        stoppedAt: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodNumber;
+        cwd: z.ZodString;
+        updatedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        timeout: number;
+        requestedAt: number;
+        createdAt: number;
+        cwd: string;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }, {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        timeout: number;
+        requestedAt: number;
+        createdAt: number;
+        cwd: string;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }>, "many">;
+    pagination: z.ZodObject<{
+        /**
+         * Amount of items in the current page.
+         * @example 20
+         */
+        count: z.ZodNumber;
+        /**
+         * Timestamp that must be used to request the next page.
+         * @example 1540095775951
+         */
+        next: z.ZodNullable<z.ZodNumber>;
+        /**
+         * Timestamp that must be used to request the previous page.
+         * @example 1540095775951
+         */
+        prev: z.ZodNullable<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        count: number;
+        next: number | null;
+        prev: number | null;
+    }, {
+        count: number;
+        next: number | null;
+        prev: number | null;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    sandboxes: {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        timeout: number;
+        requestedAt: number;
+        createdAt: number;
+        cwd: string;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }[];
+    pagination: {
+        count: number;
+        next: number | null;
+        prev: number | null;
+    };
+}, {
+    sandboxes: {
+        region: string;
+        status: "pending" | "running" | "stopping" | "stopped" | "failed";
+        id: string;
+        memory: number;
+        vcpus: number;
+        runtime: string;
+        timeout: number;
+        requestedAt: number;
+        createdAt: number;
+        cwd: string;
+        updatedAt: number;
+        duration?: number | undefined;
+        startedAt?: number | undefined;
+        requestedStopAt?: number | undefined;
+        stoppedAt?: number | undefined;
+    }[];
+    pagination: {
+        count: number;
+        next: number | null;
+        prev: number | null;
+    };
+}>;

package/dist/api-client/validators.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLine = exports.EmptyResponse = exports.CommandFinishedResponse = exports.CommandResponse = exports.SandboxAndRoutesResponse = exports.SandboxResponse = exports.Command = exports.SandboxRoute = exports.Sandbox = void 0;
+exports.SandboxesResponse = exports.LogLine = exports.EmptyResponse = exports.CommandFinishedResponse = exports.CommandResponse = exports.SandboxAndRoutesResponse = exports.SandboxResponse = exports.Command = exports.Pagination = exports.SandboxRoute = exports.Sandbox = void 0;
 const zod_1 = require("zod");
 exports.Sandbox = zod_1.z.object({
     id: zod_1.z.string(),
@@ -24,6 +24,23 @@ exports.SandboxRoute = zod_1.z.object({
     subdomain: zod_1.z.string(),
     port: zod_1.z.number(),
 });
+exports.Pagination = zod_1.z.object({
+    /**
+     * Amount of items in the current page.
+     * @example 20
+     */
+    count: zod_1.z.number(),
+    /**
+     * Timestamp that must be used to request the next page.
+     * @example 1540095775951
+     */
+    next: zod_1.z.number().nullable(),
+    /**
+     * Timestamp that must be used to request the previous page.
+     * @example 1540095775951
+     */
+    prev: zod_1.z.number().nullable(),
+});
 exports.Command = zod_1.z.object({
     id: zod_1.z.string(),
     name: zod_1.z.string(),
@@ -53,3 +70,7 @@ exports.LogLine = zod_1.z.object({
     stream: zod_1.z.enum(["stdout", "stderr"]),
     data: zod_1.z.string(),
 });
+exports.SandboxesResponse = zod_1.z.object({
+    sandboxes: zod_1.z.array(exports.Sandbox),
+    pagination: exports.Pagination,
+});

package/dist/command.d.ts

@@ -58,15 +58,21 @@ export declare class Command {
      * }
      * ```
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel log streaming.
      * @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<{
+    logs(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
         stream: "stdout" | "stderr";
         data: string;
-    }>;
+    }, void, void> & Disposable & {
+        close(): void;
+    };
     /**
      * Wait for a command to exit and populate its exit code.
      *

package/dist/command.js

@@ -53,15 +53,18 @@ class Command {
      * }
      * ```
      *
+     * @param opts - Optional parameters.
+     * @param opts.signal - An AbortSignal to cancel log streaming.
      * @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() {
+    logs(opts) {
         return this.client.getLogs({
             sandboxId: this.sandboxId,
             cmdId: this.cmd.id,
+            signal: opts?.signal,
         });
     }
     /**

package/dist/sandbox.d.ts

@@ -3,6 +3,7 @@ import type { Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, type CommandFinished } from "./command";
 import { type Credentials } from "./utils/get-credentials";
+import { WithPrivate } from "./utils/types";
 /** @inline */
 export interface CreateSandboxParams {
     /**
@@ -121,13 +122,42 @@ export declare class Sandbox {
      * Internal metadata about this sandbox.
      */
     private readonly sandbox;
+    /**
+     * Allow to get a list of sandboxes for a team narrowed to the given params.
+     * It returns both the sandboxes and the pagination metadata to allow getting
+     * the next page of results.
+     */
+    static list(params: Parameters<APIClient["listSandboxes"]>[0] & Partial<Credentials>): Promise<import("./api-client/base-client").Parsed<{
+        sandboxes: {
+            region: string;
+            status: "pending" | "running" | "stopping" | "stopped" | "failed";
+            id: string;
+            memory: number;
+            vcpus: number;
+            runtime: string;
+            timeout: number;
+            requestedAt: number;
+            createdAt: number;
+            cwd: string;
+            updatedAt: number;
+            duration?: number | undefined;
+            startedAt?: number | undefined;
+            requestedStopAt?: number | undefined;
+            stoppedAt?: number | undefined;
+        }[];
+        pagination: {
+            count: number;
+            next: number | null;
+            prev: number | null;
+        };
+    }>>;
     /**
      * Create a new sandbox.
      *
      * @param params - Creation parameters and optional credentials.
      * @returns A promise resolving to the created {@link Sandbox}.
      */
-    static create(params?: CreateSandboxParams | (CreateSandboxParams & Credentials)): Promise<Sandbox>;
+    static create(params?: WithPrivate<CreateSandboxParams | (CreateSandboxParams & Credentials)>): Promise<Sandbox>;
     /**
      * Retrieve an existing sandbox.
      *

package/dist/sandbox.js

@@ -4,6 +4,7 @@ exports.Sandbox = void 0;
 const api_client_1 = require("./api-client");
 const command_1 = require("./command");
 const get_credentials_1 = require("./utils/get-credentials");
+const types_1 = require("./utils/types");
 /**
  * A Sandbox is an isolated Linux MicroVM to run commands in.
  *
@@ -23,6 +24,19 @@ class Sandbox {
     get status() {
         return this.sandbox.status;
     }
+    /**
+     * Allow to get a list of sandboxes for a team narrowed to the given params.
+     * It returns both the sandboxes and the pagination metadata to allow getting
+     * the next page of results.
+     */
+    static async list(params) {
+        const credentials = await (0, get_credentials_1.getCredentials)(params);
+        const client = new api_client_1.APIClient({
+            teamId: credentials.teamId,
+            token: credentials.token,
+        });
+        return client.listSandboxes(params);
+    }
     /**
      * Create a new sandbox.
      *
@@ -30,11 +44,12 @@ class Sandbox {
      * @returns A promise resolving to the created {@link Sandbox}.
      */
     static async create(params) {
-        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const credentials = await (0, get_credentials_1.getCredentials)(params);
         const client = new api_client_1.APIClient({
             teamId: credentials.teamId,
             token: credentials.token,
         });
+        const privateParams = (0, types_1.getPrivateParams)(params);
         const sandbox = await client.createSandbox({
             source: params?.source,
             projectId: credentials.projectId,
@@ -42,6 +57,7 @@ class Sandbox {
             timeout: params?.timeout,
             resources: params?.resources,
             runtime: params?.runtime,
+            ...privateParams,
         });
         return new Sandbox({
             client,
@@ -56,7 +72,7 @@ class Sandbox {
      * @returns A promise resolving to the {@link Sandbox}.
      */
     static async get(params) {
-        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const credentials = await (0, get_credentials_1.getCredentials)(params);
         const client = new api_client_1.APIClient({
             teamId: credentials.teamId,
             token: credentials.token,

package/dist/utils/get-credentials.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export interface Credentials {
     /**
      * Authentication token for the Vercel API. It could be an OIDC token
@@ -23,4 +24,24 @@ export interface Credentials {
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-export declare function getCredentials<T>(params?: T | Credentials): Credentials;
+export declare function getCredentials(params?: unknown): Promise<Credentials>;
+/**
+ * Schema to validate the payload of the Vercel OIDC token where we expect
+ * to find the `teamId` and `projectId`.
+ */
+export declare const schema: z.ZodObject<{
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+    owner_id: z.ZodString;
+    project_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    owner_id: string;
+    project_id: string;
+    exp?: number | undefined;
+    iat?: number | undefined;
+}, {
+    owner_id: string;
+    project_id: string;
+    exp?: number | undefined;
+    iat?: number | undefined;
+}>;