@vercel/sandbox 0.0.18 → 0.0.19

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.18 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.18 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,16 @@
 # @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

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

@@ -2,6 +2,7 @@ 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;
@@ -38,7 +39,7 @@ export declare class APIClient extends BaseClient {
             port: number;
         }[];
     }>>;
-    createSandbox(params: {
+    createSandbox(params: WithPrivate<{
         ports?: number[];
         projectId: string;
         source?: {
@@ -57,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";
@@ -121,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;
@@ -153,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

@@ -15,6 +15,7 @@ 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({
@@ -55,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({
@@ -64,6 +66,7 @@ class APIClient extends base_client_1.BaseClient {
                 timeout: params.timeout,
                 resources: params.resources,
                 runtime: params.runtime,
+                ...privateParams,
             }),
         }));
     }
@@ -106,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,
@@ -143,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`;
@@ -166,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.
      *
@@ -35,6 +49,7 @@ class Sandbox {
             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,

package/dist/utils/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility type that extends a type to accept private parameters.
+ *
+ * The private parameters can then be extracted out of the object using
+ * `getPrivateParams`.
+ */
+export type WithPrivate<T> = T & {
+    [K in `__${string}`]?: unknown;
+};
+/**
+ * Extract private parameters out of an object.
+ */
+export declare const getPrivateParams: (params?: object) => { [K in keyof typeof params as K extends `__${string}` ? K : never]: (typeof params)[K]; };

package/dist/utils/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPrivateParams = void 0;
+/**
+ * Extract private parameters out of an object.
+ */
+const getPrivateParams = (params) => {
+    const privateEntries = Object.entries(params ?? {}).filter(([k]) => k.startsWith("__"));
+    return Object.fromEntries(privateEntries);
+};
+exports.getPrivateParams = getPrivateParams;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.18";
+export declare const VERSION = "0.0.19";

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.18";
+exports.VERSION = "0.0.19";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,6 +33,6 @@
     "test": "vitest run",
     "typedoc": "typedoc",
     "typecheck": "tsc --noEmit",
-    "inject-version": "ts-node scripts/inject-version.ts"
+    "version:bump": "ts-node scripts/inject-version.ts"
   }
 }

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

@@ -11,6 +11,7 @@ import {
   CommandFinishedResponse,
   EmptyResponse,
   LogLine,
+  SandboxesResponse,
 } from "./validators";
 import { APIError } from "./api-error";
 import { FileWriter } from "./file-writer";
@@ -22,6 +23,7 @@ import os from "os";
 import { Readable } from "stream";
 import { normalizePath } from "../utils/normalizePath";
 import { JwtExpiry } from "../utils/jwt-expiry";
+import { getPrivateParams, WithPrivate } from "../utils/types";
 
 export class APIClient extends BaseClient {
   private teamId: string;
@@ -76,23 +78,26 @@ export class APIClient extends BaseClient {
     );
   }
 
-  async createSandbox(params: {
-    ports?: number[];
-    projectId: string;
-    source?:
-      | {
-          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" | (string & {});
-  }) {
+  async createSandbox(
+    params: WithPrivate<{
+      ports?: number[];
+      projectId: string;
+      source?:
+        | {
+            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" | (string & {});
+    }>,
+  ) {
+    const privateParams = getPrivateParams(params);
     return parseOrThrow(
       SandboxAndRoutesResponse,
       await this.request("/v1/sandboxes", {
@@ -104,6 +109,7 @@ export class APIClient extends BaseClient {
           timeout: params.timeout,
           resources: params.resources,
           runtime: params.runtime,
+          ...privateParams,
         }),
       }),
     );
@@ -190,6 +196,48 @@ export class APIClient extends BaseClient {
     };
   }
 
+  async 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;
+  }) {
+    return parseOrThrow(
+      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: {
     sandboxId: string;
     cwd: string;
@@ -257,29 +305,53 @@ export class APIClient extends BaseClient {
     );
   }
 
-  async *getLogs(params: {
+  getLogs(params: {
     sandboxId: string;
     cmdId: string;
-  }): AsyncIterable<z.infer<typeof LogLine>> {
-    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 APIError(response, {
-        message: "Expected a stream of logs",
+    signal?: AbortSignal;
+  }): AsyncGenerator<z.infer<typeof LogLine>, void, void> &
+    Disposable & { close(): void } {
+    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.headers.get("content-type") !== "application/x-ndjson") {
+        throw new APIError(response, {
+          message: "Expected a stream of logs",
+        });
+      }
 
-    if (response.body === null) {
-      throw new APIError(response, {
-        message: "No response body",
+      if (response.body === null) {
+        throw new APIError(response, {
+          message: "No response body",
+        });
+      }
+
+      const jsonlinesStream = jsonlines.parse();
+      pipe(response.body, jsonlinesStream).catch((err) => {
+        console.error("Error piping logs:", err);
       });
-    }
 
-    for await (const chunk of Readable.fromWeb(response.body).pipe(
-      jsonlines.parse(),
-    )) {
-      yield LogLine.parse(chunk);
-    }
+      for await (const chunk of jsonlinesStream) {
+        yield LogLine.parse(chunk);
+      }
+    })();
+
+    return Object.assign(generator, {
+      [Symbol.dispose]() {
+        disposer.abort("Disposed");
+      },
+      close: () => disposer.abort("Disposed"),
+    });
   }
 
   async stopSandbox(params: {
@@ -292,3 +364,43 @@ export class APIClient extends BaseClient {
     );
   }
 }
+
+async function pipe(
+  readable: ReadableStream<Uint8Array>,
+  output: NodeJS.WritableStream,
+) {
+  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: [AbortSignal, ...AbortSignal[]]) {
+  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/src/api-client/validators.ts

@@ -28,6 +28,24 @@ export const SandboxRoute = z.object({
   port: z.number(),
 });
 
+export const Pagination = z.object({
+  /**
+   * Amount of items in the current page.
+   * @example 20
+   */
+  count: z.number(),
+  /**
+   * Timestamp that must be used to request the next page.
+   * @example 1540095775951
+   */
+  next: z.number().nullable(),
+  /**
+   * Timestamp that must be used to request the previous page.
+   * @example 1540095775951
+   */
+  prev: z.number().nullable(),
+});
+
 export type CommandData = z.infer<typeof Command>;
 
 export const Command = z.object({
@@ -66,3 +84,8 @@ export const LogLine = z.object({
   stream: z.enum(["stdout", "stderr"]),
   data: z.string(),
 });
+
+export const SandboxesResponse = z.object({
+  sandboxes: z.array(Sandbox),
+  pagination: Pagination,
+});

package/src/command.ts

@@ -82,15 +82,18 @@ export 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?: { signal?: AbortSignal }) {
     return this.client.getLogs({
       sandboxId: this.sandboxId,
       cmdId: this.cmd.id,
+      signal: opts?.signal,
     });
   }
 

package/src/sandbox.ts

@@ -3,6 +3,7 @@ import type { Writable } from "stream";
 import { APIClient } from "./api-client";
 import { Command, type CommandFinished } from "./command";
 import { type Credentials, getCredentials } from "./utils/get-credentials";
+import { getPrivateParams, WithPrivate } from "./utils/types";
 
 /** @inline */
 export interface CreateSandboxParams {
@@ -133,6 +134,22 @@ export class Sandbox {
    */
   private readonly sandbox: SandboxMetaData;
 
+  /**
+   * 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: Parameters<APIClient["listSandboxes"]>[0] & Partial<Credentials>,
+  ) {
+    const credentials = await getCredentials(params);
+    const client = new APIClient({
+      teamId: credentials.teamId,
+      token: credentials.token,
+    });
+    return client.listSandboxes(params);
+  }
+
   /**
    * Create a new sandbox.
    *
@@ -140,7 +157,9 @@ export class Sandbox {
    * @returns A promise resolving to the created {@link Sandbox}.
    */
   static async create(
-    params?: CreateSandboxParams | (CreateSandboxParams & Credentials),
+    params?: WithPrivate<
+      CreateSandboxParams | (CreateSandboxParams & Credentials)
+    >,
   ): Promise<Sandbox> {
     const credentials = await getCredentials(params);
     const client = new APIClient({
@@ -148,6 +167,7 @@ export class Sandbox {
       token: credentials.token,
     });
 
+    const privateParams = getPrivateParams(params);
     const sandbox = await client.createSandbox({
       source: params?.source,
       projectId: credentials.projectId,
@@ -155,6 +175,7 @@ export class Sandbox {
       timeout: params?.timeout,
       resources: params?.resources,
       runtime: params?.runtime,
+      ...privateParams,
     });
 
     return new Sandbox({

package/src/utils/types.test.js

@@ -0,0 +1,7 @@
+import { expect, it } from "vitest";
+import { getPrivateParams } from "./types";
+
+it("getPrivateParams filters unknown params", async () => {
+  const result = getPrivateParams({ foo: 123, __someParam: "abc" });
+  expect(result).toEqual({ __someParam: "abc" });
+});

package/src/utils/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility type that extends a type to accept private parameters.
+ *
+ * The private parameters can then be extracted out of the object using
+ * `getPrivateParams`.
+ */
+export type WithPrivate<T> = T & {
+  [K in `__${string}`]?: unknown;
+};
+
+/**
+ * Extract private parameters out of an object.
+ */
+export const getPrivateParams = (params?: object) => {
+  const privateEntries = Object.entries(params ?? {}).filter(([k]) =>
+    k.startsWith("__"),
+  );
+  return Object.fromEntries(privateEntries) as {
+    [K in keyof typeof params as K extends `__${string}`
+      ? K
+      : never]: (typeof params)[K];
+  };
+};

package/src/version.ts

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

package/turbo.json

@@ -0,0 +1,9 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "version:bump": {
+      "inputs": ["package.json"],
+      "outputs": ["src/version.ts"]
+    }
+  }
+}