@vercel/sandbox 0.0.17 → 0.0.19

package/dist/utils/get-credentials.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
 exports.getCredentials = getCredentials;
 const oidc_1 = require("@vercel/oidc");
 const decode_base64_url_1 = require("./decode-base64-url");
@@ -14,12 +15,12 @@ const zod_1 = require("zod");
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-function getCredentials(params) {
+async function getCredentials(params) {
     const credentials = getCredentialsFromParams(params ?? {});
     if (credentials) {
         return credentials;
     }
-    const oidcToken = (0, oidc_1.getVercelOidcTokenSync)();
+    const oidcToken = await (0, oidc_1.getVercelOidcToken)();
     if (oidcToken) {
         return getCredentialsFromOIDCToken(oidcToken);
     }
@@ -32,6 +33,10 @@ function getCredentials(params) {
  * or none of them, otherwise an error is thrown.
  */
 function getCredentialsFromParams(params) {
+    // Type guard: params must be an object
+    if (!params || typeof params !== "object") {
+        return null;
+    }
     const missing = [
         "token" in params && typeof params.token === "string" ? null : "token",
         "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
@@ -57,7 +62,9 @@ function getCredentialsFromParams(params) {
  * Schema to validate the payload of the Vercel OIDC token where we expect
  * to find the `teamId` and `projectId`.
  */
-const schema = zod_1.z.object({
+exports.schema = zod_1.z.object({
+    exp: zod_1.z.number().optional().describe("Expiry timestamp (seconds since epoch)"),
+    iat: zod_1.z.number().optional().describe("Issued at timestamp"),
     owner_id: zod_1.z.string(),
     project_id: zod_1.z.string(),
 });
@@ -71,7 +78,7 @@ const schema = zod_1.z.object({
  */
 function getCredentialsFromOIDCToken(token) {
     try {
-        const payload = schema.parse((0, decode_base64_url_1.decodeBase64Url)(token.split(".")[1]));
+        const payload = exports.schema.parse((0, decode_base64_url_1.decodeBase64Url)(token.split(".")[1]));
         return {
             token,
             projectId: payload.project_id,

package/dist/utils/jwt-expiry.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { schema } from "./get-credentials";
+export declare class OidcRefreshError extends Error {
+    name: string;
+}
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+export declare class JwtExpiry {
+    readonly token: string;
+    private expiryTime;
+    readonly payload?: Readonly<z.infer<typeof schema>>;
+    static fromToken(token: string): JwtExpiry | null;
+    /**
+     * Creates a new JWT expiry checker.
+     *
+     * @param token - The JWT token to parse
+     */
+    constructor(token: string);
+    /**
+     * Checks if the JWT token is valid (not expired).
+     * @returns true if token is valid, false if expired or expiring soon
+     */
+    isValid(): boolean;
+    /**
+     * Gets the expiry date of the JWT token.
+     *
+     * @returns Date object representing when the token expires, or null if no expiry
+     */
+    getExpiryDate(): Date | null;
+    /**
+     * Refreshes the JWT token by fetching a new OIDC token.
+     *
+     * @returns Promise resolving to a new JwtExpiry instance with fresh token
+     */
+    refresh(): Promise<JwtExpiry>;
+    /**
+     * Refreshes the JWT token if it's expired or expiring soon.
+     */
+    tryRefresh(): Promise<JwtExpiry | null>;
+}

package/dist/utils/jwt-expiry.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtExpiry = exports.OidcRefreshError = void 0;
+const decode_base64_url_1 = require("./decode-base64-url");
+const get_credentials_1 = require("./get-credentials");
+const oidc_1 = require("@vercel/oidc");
+const ms_1 = __importDefault(require("ms"));
+/** Time buffer before token expiry to consider it invalid (in milliseconds) */
+const BUFFER_MS = (0, ms_1.default)("5m");
+class OidcRefreshError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "OidcRefreshError";
+    }
+}
+exports.OidcRefreshError = OidcRefreshError;
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+class JwtExpiry {
+    static fromToken(token) {
+        if (!isJwtFormat(token)) {
+            return null;
+        }
+        else {
+            return new JwtExpiry(token);
+        }
+    }
+    /**
+     * Creates a new JWT expiry checker.
+     *
+     * @param token - The JWT token to parse
+     */
+    constructor(token) {
+        this.token = token;
+        try {
+            const tokenContents = token.split(".")[1];
+            this.payload = get_credentials_1.schema.parse((0, decode_base64_url_1.decodeBase64Url)(tokenContents));
+            this.expiryTime = this.payload.exp || null;
+        }
+        catch {
+            // Malformed token - treat as expired to trigger refresh
+            this.expiryTime = 0;
+        }
+    }
+    /**
+     * Checks if the JWT token is valid (not expired).
+     * @returns true if token is valid, false if expired or expiring soon
+     */
+    isValid() {
+        if (this.expiryTime === null) {
+            return false; // No expiry means malformed JWT
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const buffer = BUFFER_MS / 1000;
+        return now + buffer < this.expiryTime;
+    }
+    /**
+     * Gets the expiry date of the JWT token.
+     *
+     * @returns Date object representing when the token expires, or null if no expiry
+     */
+    getExpiryDate() {
+        return this.expiryTime ? new Date(this.expiryTime * 1000) : null;
+    }
+    /**
+     * Refreshes the JWT token by fetching a new OIDC token.
+     *
+     * @returns Promise resolving to a new JwtExpiry instance with fresh token
+     */
+    async refresh() {
+        try {
+            const freshToken = await (0, oidc_1.getVercelOidcToken)();
+            return new JwtExpiry(freshToken);
+        }
+        catch (cause) {
+            throw new OidcRefreshError("Failed to refresh OIDC token", {
+                cause,
+            });
+        }
+    }
+    /**
+     * Refreshes the JWT token if it's expired or expiring soon.
+     */
+    async tryRefresh() {
+        if (this.isValid()) {
+            return null; // Still valid, no need to refresh
+        }
+        return this.refresh();
+    }
+}
+exports.JwtExpiry = JwtExpiry;
+/**
+ * Checks if a token follows JWT format (has 3 parts separated by dots).
+ *
+ * @param token - The token to check
+ * @returns true if token appears to be a JWT, false otherwise
+ */
+function isJwtFormat(token) {
+    return token.split(".").length === 3;
+}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@vercel/oidc": "^2.0.0",
+    "@vercel/oidc": "^2.0.2",
     "async-retry": "1.3.3",
     "jsonlines": "0.1.1",
     "ms": "2.1.3",
@@ -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";
@@ -21,9 +22,12 @@ import jsonlines from "jsonlines";
 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;
+  private tokenExpiry: JwtExpiry | null;
 
   constructor(params: { host?: string; teamId: string; token: string }) {
     super({
@@ -33,9 +37,29 @@ export class APIClient extends BaseClient {
     });
 
     this.teamId = params.teamId;
+    this.tokenExpiry = JwtExpiry.fromToken(params.token);
+  }
+
+  private async ensureValidToken(): Promise<void> {
+    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;
+    }
   }
 
   protected async request(path: string, params?: RequestParams) {
+    await this.ensureValidToken();
+
     return super.request(path, {
       ...params,
       query: { teamId: this.teamId, ...params?.query },
@@ -54,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", {
@@ -82,6 +109,7 @@ export class APIClient extends BaseClient {
           timeout: params.timeout,
           resources: params.resources,
           runtime: params.runtime,
+          ...privateParams,
         }),
       }),
     );
@@ -168,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;
@@ -235,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: {
@@ -270,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,14 +157,17 @@ 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 = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       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({
@@ -173,7 +194,7 @@ export class Sandbox {
   static async get(
     params: GetSandboxParams | (GetSandboxParams & Credentials),
   ): Promise<Sandbox> {
-    const credentials = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       token: credentials.token,