eve 0.12.1 → 0.12.3

package/dist/src/compiled/@vercel/sandbox/session.d.ts

@@ -0,0 +1,432 @@
+import { SandboxMetaData, SandboxRouteData, SessionMetaData, SnapshotMetadata } from "./api-client/validators.js";
+import { NetworkPolicy, NetworkPolicyRule, NetworkTransformer } from "./network-policy.js";
+import { APIClient } from "./api-client/api-client.js";
+import "./api-client/index.js";
+import { Command, CommandFinished } from "./command.js";
+import { Snapshot } from "./snapshot.js";
+import { SandboxSnapshot } from "./utils/sandbox-snapshot.js";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "./_workflow-serde.js";
+import { Writable } from "stream";
+
+//#region src/session.d.ts
+/**
+ * Serialized representation of a Session for @workflow/serde.
+ */
+interface SerializedSession {
+  session: SandboxSnapshot;
+  routes: SandboxRouteData[];
+}
+/** @inline */
+interface RunCommandParams {
+  /**
+   * The command to execute
+   */
+  cmd: string;
+  /**
+   * Arguments to pass to the command
+   */
+  args?: string[];
+  /**
+   * Working directory to execute the command in
+   */
+  cwd?: string;
+  /**
+   * Environment variables to set for this command
+   */
+  env?: Record<string, string>;
+  /**
+   * If true, execute this command with root privileges. Defaults to false.
+   */
+  sudo?: boolean;
+  /**
+   * If true, the command will return without waiting for `exitCode`
+   */
+  detached?: boolean;
+  /**
+   * A `Writable` stream where `stdout` from the command will be piped
+   */
+  stdout?: Writable;
+  /**
+   * A `Writable` stream where `stderr` from the command will be piped
+   */
+  stderr?: Writable;
+  /**
+   * An AbortSignal to cancel the command execution
+   */
+  signal?: AbortSignal;
+  /**
+   * Maximum time in milliseconds the command may run before it is killed with
+   * SIGKILL. The timeout is enforced by the sandbox at exec time, so it applies
+   * whether or not the command is awaited (including `detached: true`).
+   */
+  timeoutMs?: number;
+}
+/**
+ * A Session represents a running VM instance within a {@link Sandbox}.
+ *
+ * Obtain a session via {@link Sandbox.currentSession}.
+ */
+declare class Session {
+  private _client;
+  /**
+   * Lazily resolve credentials and construct an API client.
+   * This is used in step contexts where the Sandbox was deserialized
+   * without a client (e.g. when crossing workflow/step boundaries).
+   * Uses getCredentials() which resolves from OIDC or env vars.
+   * @internal
+   */
+  private ensureClient;
+  /**
+   * Routes from ports to subdomains.
+   * @hidden
+   */
+  readonly routes: SandboxRouteData[];
+  /**
+   * Internal metadata about the current session.
+   */
+  private session;
+  private get client();
+  /** @internal */
+  get _sessionSnapshot(): SandboxSnapshot;
+  /**
+   * Unique ID of this session.
+   */
+  get sessionId(): string;
+  get interactivePort(): number | undefined;
+  /**
+   * The status of this session.
+   */
+  get status(): SessionMetaData["status"];
+  /**
+   * The creation date of this session.
+   */
+  get createdAt(): Date;
+  /**
+   * The timeout of this session in milliseconds.
+   */
+  get timeout(): number;
+  /**
+   * The network policy of this session.
+   */
+  get networkPolicy(): NetworkPolicy | undefined;
+  /**
+   * If the session was created from a snapshot, the ID of that snapshot.
+   */
+  get sourceSnapshotId(): string | undefined;
+  /**
+   * Memory allocated to this session in MB.
+   */
+  get memory(): number;
+  /**
+   * Number of vCPUs allocated to this session.
+   */
+  get vcpus(): number;
+  /**
+   * The region where this session is hosted.
+   */
+  get region(): string;
+  /**
+   * Runtime identifier (e.g. "node24", "python3.13").
+   */
+  get runtime(): string;
+  /**
+   * The working directory of this session.
+   */
+  get cwd(): string;
+  /**
+   * When this session was requested.
+   */
+  get requestedAt(): Date;
+  /**
+   * When this session started running.
+   */
+  get startedAt(): Date | undefined;
+  /**
+   * When this session was requested to stop.
+   */
+  get requestedStopAt(): Date | undefined;
+  /**
+   * When this session was stopped.
+   */
+  get stoppedAt(): Date | undefined;
+  /**
+   * When this session was aborted.
+   */
+  get abortedAt(): Date | undefined;
+  /**
+   * The wall-clock duration of this session in milliseconds.
+   */
+  get duration(): number | undefined;
+  /**
+   * When a snapshot was requested for this session.
+   */
+  get snapshottedAt(): Date | undefined;
+  /**
+   * When this session was last updated.
+   */
+  get updatedAt(): Date;
+  /**
+   * The amount of active CPU used by the session. Only reported once the VM is
+   * stopped.
+   */
+  get activeCpuUsageMs(): number | undefined;
+  /**
+   * The amount of network data used by the session. Only reported once the VM
+   * is stopped.
+   */
+  get networkTransfer(): {
+    ingress: number;
+    egress: number;
+  } | undefined;
+  /**
+   * Serialize a Session instance to plain data for @workflow/serde.
+   *
+   * Although Sandbox handles top-level serialization, Session needs these
+   * methods so the Workflow SWC compiler can resolve the class by name.
+   * The `new Session(...)` self-reference in WORKFLOW_DESERIALIZE forces
+   * rolldown to preserve the class name in the compiled output.
+   */
+  static [WORKFLOW_SERIALIZE](instance: Session): SerializedSession;
+  static [WORKFLOW_DESERIALIZE](data: SerializedSession): Session;
+  constructor(params: {
+    client: APIClient;
+    routes: SandboxRouteData[];
+    session: SessionMetaData;
+  } | {
+    /** @internal – used during deserialization with an already-converted snapshot */
+    routes: SandboxRouteData[];
+    snapshot: SandboxSnapshot;
+  });
+  /** @internal */
+  updateRoutes(routes: SandboxRouteData[]): void;
+  /**
+   * Get a previously run command by its ID.
+   *
+   * @param cmdId - ID of the command to retrieve
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A {@link Command} instance representing the command
+   */
+  getCommand(cmdId: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<Command>;
+  /**
+   * Start executing a command in this session.
+   *
+   * @param command - The command to execute.
+   * @param args - Arguments to pass to the command.
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the command execution.
+   * @param opts.timeoutMs - Maximum time in milliseconds to wait for the
+   * command to complete. On expiry the process is killed with SIGKILL.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  runCommand(command: string, args?: string[], opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<CommandFinished>;
+  /**
+   * Start executing a command in detached mode.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link Command} instance for the running command.
+   */
+  runCommand(params: RunCommandParams & {
+    detached: true;
+  }): Promise<Command>;
+  /**
+   * Start executing a command in this session.
+   *
+   * @param params - The command parameters.
+   * @returns A {@link CommandFinished} result once execution is done.
+   */
+  runCommand(params: RunCommandParams): Promise<CommandFinished>;
+  /**
+   * Create a directory in the filesystem of this session.
+   *
+   * @param path - Path of the directory to create
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   */
+  mkDir(path: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Open an interactive shell session. Returns the WebSocket URL and token the
+   * client uses to connect to the controller-hosted PTY.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   */
+  openInteractive(opts?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    url: string;
+    token: string;
+  }>;
+  /**
+   * Read a file from the filesystem of this session as a stream.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found
+   */
+  readFile(file: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<NodeJS.ReadableStream | null>;
+  /**
+   * Read a file from the filesystem of this session as a Buffer.
+   *
+   * @param file - File to read, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves to the file contents as a Buffer, or null if file not found
+   */
+  readFileToBuffer(file: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<Buffer | null>;
+  /**
+   * Download a file from the session to the local filesystem.
+   *
+   * @param src - Source file on the session, with path and optional cwd
+   * @param dst - Destination file on the local machine, with path and optional cwd
+   * @param opts - Optional parameters.
+   * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns The absolute path to the written file, or null if the source file was not found
+   */
+  downloadFile(src: {
+    path: string;
+    cwd?: string;
+  }, dst: {
+    path: string;
+    cwd?: string;
+  }, opts?: {
+    mkdirRecursive?: boolean;
+    signal?: AbortSignal;
+  }): Promise<string | null>;
+  /**
+   * Write files to the filesystem of this session.
+   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+   * Writes files using the `vercel-sandbox` user.
+   *
+   * @param files - Array of files with path and stream/buffer contents
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves when the files are written
+   */
+  writeFiles(files: {
+    path: string;
+    content: string | Uint8Array;
+    mode?: number;
+  }[], opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Get the public domain of a port of this session.
+   *
+   * @param p - Port number to resolve
+   * @returns A full domain (e.g. `https://subdomain.vercel.run`)
+   * @throws If the port has no associated route
+   */
+  domain(p: number): string;
+  /**
+   * Stop this session.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns The final session state and optional sandbox metadata.
+   */
+  stop(opts?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    session: SandboxSnapshot;
+    sandbox?: SandboxMetaData;
+    snapshot?: SnapshotMetadata;
+  }>;
+  /**
+   * Update the current session's settings.
+   *
+   * @param params - Fields to update.
+   * @param params.networkPolicy - The new network policy to apply.
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   *
+   * @example
+   * // Restrict to specific domains
+   * await session.update({
+   *   networkPolicy: {
+   *     allow: ["*.npmjs.org", "github.com"],
+   *   }
+   * });
+   *
+   * @example
+   * // Inject credentials with per-domain transformers
+   * await session.update({
+   *   networkPolicy: {
+   *     allow: {
+   *       "ai-gateway.vercel.sh": [{
+   *         transform: [{
+   *           headers: { authorization: "Bearer ..." }
+   *         }]
+   *       }],
+   *       "*": []
+   *     }
+   *   }
+   * });
+   *
+   * @example
+   * // Deny all network access
+   * await session.update({ networkPolicy: "deny-all" });
+   */
+  update(params: {
+    networkPolicy?: NetworkPolicy;
+  }, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Extend the timeout of the session by the specified duration.
+   *
+   * This allows you to extend the lifetime of a session up until the maximum
+   * execution timeout for your plan.
+   *
+   * @param duration - The duration in milliseconds to extend the timeout by
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves when the timeout is extended
+   *
+   * @example
+   * const sandbox = await Sandbox.create({ timeout: ms('10m') });
+   * const session = sandbox.currentSession();
+   * // Extends timeout by 5 minutes, to a total of 15 minutes.
+   * await session.extendTimeout(ms('5m'));
+   */
+  extendTimeout(duration: number, opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * Create a snapshot from this currently running session. New sandboxes can
+   * then be created from this snapshot using {@link Sandbox.create}.
+   *
+   * Note: this session will be stopped as part of the snapshot creation process.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves to the Snapshot instance
+   */
+  snapshot(opts?: {
+    expiration?: number;
+    signal?: AbortSignal;
+  }): Promise<Snapshot>;
+}
+//#endregion
+export { RunCommandParams, Session };
+//# sourceMappingURL=session.d.ts.map

package/dist/src/compiled/@vercel/sandbox/snapshot.d.ts

@@ -0,0 +1,229 @@
+import { Paginator } from "./utils/paginator.js";
+import { SnapshotMetadata } from "./api-client/validators.js";
+import { APIClient, WithFetchOptions } from "./api-client/api-client.js";
+import "./api-client/index.js";
+import { Credentials } from "./utils/get-credentials.js";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "./_workflow-serde.js";
+
+//#region src/snapshot.d.ts
+interface SerializedSnapshot {
+  snapshot: SnapshotMetadata;
+}
+/** @inline */
+interface GetSnapshotParams {
+  /**
+   * Unique identifier of the snapshot.
+   */
+  snapshotId: string;
+  /**
+   * An AbortSignal to cancel the operation.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * A Snapshot is a saved state of a Sandbox that can be used to create new Sandboxes
+ *
+ * Use {@link Sandbox.snapshot} or {@link Snapshot.get} to construct.
+ * @hideconstructor
+ */
+declare class Snapshot {
+  private _client;
+  /**
+   * Lazily resolve credentials and construct an API client.
+   * This is used in step contexts where the Snapshot was deserialized
+   * without a client (e.g. when crossing workflow/step boundaries).
+   * @internal
+   */
+  private ensureClient;
+  /**
+   * Unique ID of this snapshot.
+   */
+  get snapshotId(): string;
+  /**
+   * The ID of the session from which this snapshot was created.
+   */
+  get sourceSessionId(): string;
+  /**
+   * The status of the snapshot.
+   */
+  get status(): SnapshotMetadata["status"];
+  /**
+   * The size of the snapshot in bytes, or null if not available.
+   */
+  get sizeBytes(): number;
+  /**
+   * The creation date of this snapshot.
+   */
+  get createdAt(): Date;
+  /**
+   * When this snapshot was last updated.
+   */
+  get updatedAt(): Date;
+  /**
+   * The expiration date of this snapshot, or undefined if it does not expire.
+   */
+  get expiresAt(): Date | undefined;
+  /**
+   * Internal metadata about this snapshot.
+   */
+  private snapshot;
+  /**
+   * Serialize a Snapshot instance to plain data for @workflow/serde.
+   *
+   * @param instance - The Snapshot instance to serialize
+   * @returns A plain object containing snapshot metadata
+   */
+  static [WORKFLOW_SERIALIZE](instance: Snapshot): SerializedSnapshot;
+  /**
+   * Deserialize a Snapshot from serialized data.
+   *
+   * The deserialized instance uses the serialized metadata synchronously and
+   * lazily creates an API client only when methods perform API requests.
+   *
+   * @param data - The serialized snapshot data
+   * @returns The reconstructed Snapshot instance
+   */
+  static [WORKFLOW_DESERIALIZE](data: SerializedSnapshot): Snapshot;
+  constructor({
+    client,
+    snapshot
+  }: {
+    client?: APIClient;
+    snapshot: SnapshotMetadata;
+  });
+  /**
+   * Allow to get a list of snapshots for a team narrowed to the given params.
+   * It returns both the snapshots and the pagination metadata to allow getting
+   * the next page of results.
+   *
+   * The returned object is async-iterable to auto-paginate through all pages:
+   *
+   * ```ts
+   * const result = await Snapshot.list({ name: "my-sandbox" });
+   * for await (const snapshot of result) { ... }
+   * // or: await result.toArray();
+   * // or: for await (const page of result.pages()) { ... }
+   * ```
+   */
+  static list(params?: Partial<Parameters<APIClient["listSnapshots"]>[0]> & Partial<Credentials> & WithFetchOptions): Promise<Paginator<{
+    snapshots: {
+      id: string;
+      sourceSessionId: string;
+      region: string;
+      status: "created" | "deleted" | "failed";
+      sizeBytes: number;
+      createdAt: number;
+      updatedAt: number;
+      expiresAt?: number | undefined;
+      lastUsedAt?: number | undefined;
+      creationMethod?: string | undefined;
+      parentId?: string | undefined;
+    }[];
+    pagination: {
+      count: number;
+      next: string | null;
+    };
+  }, "snapshots">>;
+  /**
+   * Fetch the snapshot ancestry tree anchored on a given snapshot.
+   * It returns both the tree nodes and the pagination metadata to allow
+   * walking the next page of results in the same direction.
+   *
+   * The returned object is async-iterable to auto-paginate through all pages
+   * in the direction set by `sortOrder` (`"desc"` walks ancestors, `"asc"`
+   * walks descendants):
+   *
+   * ```ts
+   * const result = await Snapshot.tree({ snapshotId: "snap_abc", sortOrder: "desc" });
+   * for await (const node of result) { ... }
+   * // or: await result.toArray();
+   * // or: for await (const page of result.pages()) { ... }
+   * ```
+   */
+  static tree(params: {
+    snapshotId: string;
+  } & Partial<Parameters<APIClient["getSnapshotTree"]>[0]> & Partial<Credentials> & WithFetchOptions): Promise<Paginator<{
+    snapshots: {
+      snapshot: {
+        id: string;
+        sourceSessionId: string;
+        region: string;
+        status: "created" | "deleted" | "failed";
+        sizeBytes: number;
+        createdAt: number;
+        updatedAt: number;
+        expiresAt?: number | undefined;
+        lastUsedAt?: number | undefined;
+        creationMethod?: string | undefined;
+        parentId?: string | undefined;
+      };
+      siblings: {
+        id: string;
+        sourceSessionId: string;
+        region: string;
+        status: "created" | "deleted" | "failed";
+        sizeBytes: number;
+        createdAt: number;
+        updatedAt: number;
+        expiresAt?: number | undefined;
+        lastUsedAt?: number | undefined;
+        creationMethod?: string | undefined;
+        parentId?: string | undefined;
+      }[];
+      count: string;
+    }[];
+    pagination: {
+      count: number;
+      next: string | null;
+    };
+    anchor?: {
+      snapshot: {
+        id: string;
+        sourceSessionId: string;
+        region: string;
+        status: "created" | "deleted" | "failed";
+        sizeBytes: number;
+        createdAt: number;
+        updatedAt: number;
+        expiresAt?: number | undefined;
+        lastUsedAt?: number | undefined;
+        creationMethod?: string | undefined;
+        parentId?: string | undefined;
+      };
+      siblings: {
+        id: string;
+        sourceSessionId: string;
+        region: string;
+        status: "created" | "deleted" | "failed";
+        sizeBytes: number;
+        createdAt: number;
+        updatedAt: number;
+        expiresAt?: number | undefined;
+        lastUsedAt?: number | undefined;
+        creationMethod?: string | undefined;
+        parentId?: string | undefined;
+      }[];
+      count: string;
+    } | undefined;
+  }, "snapshots">>;
+  /**
+   * Retrieve an existing snapshot.
+   *
+   * @param params - Get parameters and optional credentials.
+   * @returns A promise resolving to the {@link Sandbox}.
+   */
+  static get(params: GetSnapshotParams | (GetSnapshotParams & Credentials)): Promise<Snapshot>;
+  /**
+   * Delete this snapshot.
+   *
+   * @param opts - Optional parameters.
+   * @param opts.signal - An AbortSignal to cancel the operation.
+   * @returns A promise that resolves once the snapshot has been deleted.
+   */
+  delete(opts?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+}
+//#endregion
+export { SerializedSnapshot, Snapshot };
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/src/compiled/@vercel/sandbox/utils/get-credentials.d.ts

@@ -0,0 +1,21 @@
+import { z } from "#compiled/zod/index.js";
+
+//#region src/utils/get-credentials.d.ts
+interface Credentials {
+  /**
+   * Authentication token for the Vercel API. It could be an OIDC token
+   * or a personal access token.
+   */
+  token: string;
+  /**
+   * The ID of the project to associate Sandbox operations.
+   */
+  projectId: string;
+  /**
+   * The ID of the team to associate Sandbox operations.
+   */
+  teamId: string;
+}
+//#endregion
+export { Credentials };
+//# sourceMappingURL=get-credentials.d.ts.map

package/dist/src/compiled/@vercel/sandbox/utils/paginator.d.ts

@@ -0,0 +1,16 @@
+//#region src/utils/paginator.d.ts
+type CursorPaginationMeta = {
+  count: number;
+  next: string | null;
+};
+type HasPagination = {
+  pagination: CursorPaginationMeta;
+};
+type ItemOf<Page, Key extends keyof Page> = Page[Key] extends Array<infer Item> ? Item : never;
+type Paginator<Page extends HasPagination, Key extends keyof Page> = Page & AsyncIterable<ItemOf<Page, Key>> & {
+  pages(): AsyncIterable<Page>;
+  toArray(): Promise<ItemOf<Page, Key>[]>;
+};
+//#endregion
+export { Paginator };
+//# sourceMappingURL=paginator.d.ts.map