@blaxel/core 0.3.20 → 0.3.21-preview.292

package/dist/cjs/types/client/types.gen.d.ts

@@ -4125,7 +4125,7 @@ export type SandboxScheduleMetrics = {
     until?: string;
 };
 /**
- * A point-in-time snapshot of a sandbox that can be used for forking into a new sandbox or application.
+ * A point-in-time snapshot of a sandbox. It is a workspace-level object: it outlives the sandbox it was captured from, and can be restored onto a sandbox or forked into a new sandbox or application on its own.
  */
 export type SandboxSnapshot = {
     /**
@@ -4137,36 +4137,154 @@ export type SandboxSnapshot = {
      */
     createdBy?: string;
     /**
-     * Unique snapshot identifier
+     * Identifier of the snapshot on the compute plane
      */
-    id: string;
+    readonly id: string;
     /**
-     * Optional human-readable name for the snapshot
+     * Name of the snapshot, unique in its workspace
      */
-    name?: string;
+    name: string;
     /**
-     * Name of the source sandbox
+     * Name of the source sandbox. Kept for compatibility, read source.name instead.
      */
-    sandboxName: string;
+    sandboxName?: string;
+    source?: SandboxSnapshotSource;
+    spec?: SandboxSnapshotSpec;
     /**
      * Status of the snapshot (pending, ready, failed)
      */
     status: string;
     /**
-     * Workspace of the source sandbox
+     * Workspace owning the snapshot
      */
     workspace: string;
 };
 /**
- * Request body for creating a snapshot of a sandbox. Captures the current sandbox state.
+ * A point-in-time snapshot of a sandbox. It is a workspace-level object: it outlives the sandbox it was captured from, and can be restored onto a sandbox or forked into a new sandbox or application on its own.
+ */
+export type SandboxSnapshotWritable = {
+    /**
+     * When the snapshot was created
+     */
+    createdAt: string;
+    /**
+     * Who created the snapshot
+     */
+    createdBy?: string;
+    /**
+     * Name of the snapshot, unique in its workspace
+     */
+    name: string;
+    /**
+     * Name of the source sandbox. Kept for compatibility, read source.name instead.
+     */
+    sandboxName?: string;
+    source?: SandboxSnapshotSourceWritable;
+    spec?: SandboxSnapshotSpec;
+    /**
+     * Status of the snapshot (pending, ready, failed)
+     */
+    status: string;
+    /**
+     * Workspace owning the snapshot
+     */
+    workspace: string;
+};
+/**
+ * Cursor-paginated list of snapshots. Returned starting with API version 2026-04-28; older API versions return a bare array.
+ */
+export type SandboxSnapshotList = {
+    /**
+     * Page of snapshots.
+     */
+    data?: Array<SandboxSnapshot>;
+    meta?: PaginationMeta;
+};
+/**
+ * Cursor-paginated list of snapshots. Returned starting with API version 2026-04-28; older API versions return a bare array.
+ */
+export type SandboxSnapshotListWritable = {
+    /**
+     * Page of snapshots.
+     */
+    data?: Array<SandboxSnapshotWritable>;
+    meta?: PaginationMeta;
+};
+/**
+ * Request body for creating a snapshot. The source object is required at the root endpoint and implied by the path on the nested one.
  */
 export type SandboxSnapshotRequest = {
     /**
-     * Optional human-readable name for the snapshot
+     * Name of the snapshot, unique in the workspace. Generated when absent, and always generated by the nested endpoint so a capture cannot collide with a name a user picked.
      */
     name?: string;
+    source?: SandboxSnapshotSource;
+};
+/**
+ * Request body for creating a snapshot. The source object is required at the root endpoint and implied by the path on the nested one.
+ */
+export type SandboxSnapshotRequestWritable = {
+    /**
+     * Name of the snapshot, unique in the workspace. Generated when absent, and always generated by the nested endpoint so a capture cannot collide with a name a user picked.
+     */
+    name?: string;
+    source?: SandboxSnapshotSourceWritable;
+};
+/**
+ * The object a snapshot was captured from.
+ */
+export type SandboxSnapshotSource = {
+    /**
+     * Whether the source object has since been deleted. The snapshot stays usable, the link is only kept for context.
+     */
+    readonly deleted?: boolean;
+    /**
+     * Kind of the object the snapshot was captured from. Defaults to sandbox, the only kind that can be captured today.
+     */
+    kind?: 'sandbox';
+    /**
+     * Name of the object the snapshot was captured from
+     */
+    name: string;
+};
+/**
+ * The object a snapshot was captured from.
+ */
+export type SandboxSnapshotSourceWritable = {
+    /**
+     * Kind of the object the snapshot was captured from. Defaults to sandbox, the only kind that can be captured today.
+     */
+    kind?: 'sandbox';
+    /**
+     * Name of the object the snapshot was captured from
+     */
+    name: string;
+};
+/**
+ * The configuration a snapshot carries, so a sandbox or an application can be created from it once its source object is gone.
+ */
+export type SandboxSnapshotSpec = {
+    /**
+     * Infrastructure generation the snapshot was captured on. A snapshot only restores on the generation it came from.
+     */
+    generation?: 'mk2' | 'mk3';
+    /**
+     * Image the source object ran
+     */
+    image?: string;
+    /**
+     * Memory in MB the source object ran with
+     */
+    memory?: number;
+    ports?: Ports;
+    /**
+     * Region holding the snapshot. Restores and forks land in it.
+     */
+    region?: string;
+    volumes?: VolumeAttachments;
 };
 export type SandboxSnapshots = Array<SandboxSnapshot>;
+export type SandboxSnapshotsWritable = Array<SandboxSnapshotWritable>;
 /**
  * Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies
  */
@@ -8166,7 +8284,7 @@ export type ListSandboxSnapshotsResponses = {
 };
 export type ListSandboxSnapshotsResponse = ListSandboxSnapshotsResponses[keyof ListSandboxSnapshotsResponses];
 export type CreateSandboxSnapshotData = {
-    body: SandboxSnapshotRequest;
+    body: SandboxSnapshotRequestWritable;
     path: {
         /**
          * Name of the sandbox to snapshot
@@ -8682,6 +8800,154 @@ export type DeleteApiKeyForServiceAccountResponses = {
      */
     200: unknown;
 };
+export type ListSnapshotsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Opaque cursor returned by a previous response's meta.nextCursor. Only valid for the same query (workspace + filters); the server rejects cursors bound to a different query or older than 24h. Omit on the first page.
+         */
+        cursor?: string;
+        /**
+         * Maximum number of items to return per page. Defaults to 50, clamped to 200.
+         */
+        limit?: number;
+        /**
+         * Sort spec, formatted as `<key>:<direction>`. Allowed values are `createdAt:desc` (default), `createdAt:asc`, `name:asc`, `name:desc`. The cursor fingerprint is bound to the sort, so a cursor opened with one value cannot be reused with another. Only honoured starting on Blaxel-Version 2026-04-28.
+         */
+        sort?: 'createdAt:desc' | 'createdAt:asc' | 'name:asc' | 'name:desc';
+        /**
+         * Substring search across `metadata.name`, `metadata.displayName` and labels (keys + values). Trimmed and lowercased server-side; queries shorter than 2 characters fall back to the unfiltered listing. Bound into the cursor fingerprint so a cursor opened with one query cannot be reused with another. Only honoured starting on Blaxel-Version 2026-04-28.
+         */
+        q?: string;
+        /**
+         * Start from a known pagination boundary. `end` is only supported for `createdAt` listings (asc or desc) and returns the tail page directly without walking every cursor from the first page.
+         */
+        anchor?: 'end';
+    };
+    url: '/snapshots';
+};
+export type ListSnapshotsErrors = {
+    /**
+     * Internal server error
+     */
+    500: _Error;
+};
+export type ListSnapshotsError = ListSnapshotsErrors[keyof ListSnapshotsErrors];
+export type ListSnapshotsResponses = {
+    /**
+     * successful operation
+     */
+    200: SandboxSnapshotList;
+};
+export type ListSnapshotsResponse = ListSnapshotsResponses[keyof ListSnapshotsResponses];
+export type CreateSnapshotData = {
+    body: SandboxSnapshotRequestWritable;
+    path?: never;
+    query?: never;
+    url: '/snapshots';
+};
+export type CreateSnapshotErrors = {
+    /**
+     * Not found - Source object does not exist
+     */
+    404: _Error;
+    /**
+     * Internal server error
+     */
+    500: _Error;
+};
+export type CreateSnapshotError = CreateSnapshotErrors[keyof CreateSnapshotErrors];
+export type CreateSnapshotResponses = {
+    /**
+     * Snapshot created successfully
+     */
+    200: SandboxSnapshot;
+};
+export type CreateSnapshotResponse = CreateSnapshotResponses[keyof CreateSnapshotResponses];
+export type DeleteSnapshotData = {
+    body?: never;
+    path: {
+        /**
+         * Name of the snapshot
+         */
+        snapshotName: string;
+    };
+    query?: never;
+    url: '/snapshots/{snapshotName}';
+};
+export type DeleteSnapshotErrors = {
+    /**
+     * Not found - Snapshot does not exist
+     */
+    404: _Error;
+    /**
+     * Internal server error
+     */
+    500: _Error;
+};
+export type DeleteSnapshotError = DeleteSnapshotErrors[keyof DeleteSnapshotErrors];
+export type DeleteSnapshotResponses = {
+    /**
+     * Snapshot deleted successfully
+     */
+    204: void;
+};
+export type DeleteSnapshotResponse = DeleteSnapshotResponses[keyof DeleteSnapshotResponses];
+export type GetSnapshotData = {
+    body?: never;
+    path: {
+        /**
+         * Name of the snapshot
+         */
+        snapshotName: string;
+    };
+    query?: never;
+    url: '/snapshots/{snapshotName}';
+};
+export type GetSnapshotErrors = {
+    /**
+     * Not found - Snapshot does not exist
+     */
+    404: _Error;
+};
+export type GetSnapshotError = GetSnapshotErrors[keyof GetSnapshotErrors];
+export type GetSnapshotResponses = {
+    /**
+     * successful operation
+     */
+    200: SandboxSnapshot;
+};
+export type GetSnapshotResponse = GetSnapshotResponses[keyof GetSnapshotResponses];
+export type ForkSnapshotData = {
+    body: SandboxForkRequest;
+    path: {
+        /**
+         * Name of the snapshot to create the resource from
+         */
+        snapshotName: string;
+    };
+    query?: never;
+    url: '/snapshots/{snapshotName}/fork';
+};
+export type ForkSnapshotErrors = {
+    /**
+     * Not found - Snapshot does not exist
+     */
+    404: _Error;
+    /**
+     * Internal server error
+     */
+    500: _Error;
+};
+export type ForkSnapshotError = ForkSnapshotErrors[keyof ForkSnapshotErrors];
+export type ForkSnapshotResponses = {
+    /**
+     * Resource created successfully
+     */
+    200: SandboxForkResponse;
+};
+export type ForkSnapshotResponse = ForkSnapshotResponses[keyof ForkSnapshotResponses];
 export type ListTemplatesData = {
     body?: never;
     path?: never;

package/dist/cjs/types/index.d.ts

@@ -18,6 +18,7 @@ export * from "./jobs/index.js";
 export * from "./mcp/index.js";
 export * from "./models/index.js";
 export * from "./sandbox/index.js";
+export * from "./snapshot/index.js";
 export * from "./telemetry/telemetry.js";
 export * from "./tools/index.js";
 export * from "./tools/types.js";

package/dist/cjs/types/sandbox/index.d.ts

@@ -5,6 +5,7 @@ export * from "./codegen/index.js";
 export { SandboxDrive, type DriveMountRequest, type DriveMountResponse, type DriveMountInfo, type DriveUnmountResponse } from "./drive/index.js";
 export * from "./preview.js";
 export * from "./schedule.js";
+export * from "./snapshot.js";
 export * from "./session.js";
 export * from "./sandbox.js";
 export * from "./system.js";

package/dist/cjs/types/sandbox/sandbox.d.ts

@@ -1,5 +1,5 @@
 import type http2 from "http2";
-import { type Env, type ListSandboxesData, type SandboxForkResponse, type SandboxLifecycle, type Sandbox as SandboxModel, type SandboxRestoreResponse, type SandboxSnapshot, type SandboxSnapshots } from "../client/index.js";
+import { type Env, type ListSandboxesData, type SandboxForkResponse, type SandboxLifecycle, type Sandbox as SandboxModel, type SandboxRestoreResponse, type SandboxSnapshot } from "../client/index.js";
 import { SandboxCodegen } from "./codegen/index.js";
 import { SandboxDrive } from "./drive/index.js";
 import { SandboxFileSystem } from "./filesystem/index.js";
@@ -7,6 +7,7 @@ import { SandboxNetwork } from "./network/index.js";
 import { SandboxPreviews } from "./preview.js";
 import { SandboxProcess } from "./process/index.js";
 import { SandboxSchedules } from "./schedule.js";
+import { SandboxSnapshotsResource } from "./snapshot.js";
 import { SandboxSessions } from "./session.js";
 import { SandboxSystem } from "./system.js";
 import { SandboxConfiguration, SandboxCreateConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
@@ -55,6 +56,7 @@ export declare class SandboxInstance {
     codegen: SandboxCodegen;
     system: SandboxSystem;
     drives: SandboxDrive;
+    snapshots: SandboxSnapshotsResource;
     h2Session: http2.ClientHttp2Session | null;
     constructor(sandbox: SandboxConfiguration);
     get metadata(): import("../client/types.gen.js").Metadata;
@@ -90,14 +92,19 @@ export declare class SandboxInstance {
      * sandbox state and can be forked into new sandboxes or applications.
      *
      * @param name - Optional human-readable name for the snapshot.
+     * @deprecated Use `sandbox.snapshots.create(name)`.
      */
     snapshot(name?: string): Promise<SandboxSnapshot>;
     /**
      * List the snapshots of this sandbox.
+     *
+     * @deprecated Use `sandbox.snapshots.list()`.
      */
-    listSnapshots(): Promise<SandboxSnapshots>;
+    listSnapshots(): Promise<SandboxSnapshot[]>;
     /**
      * Delete a snapshot of this sandbox by its ID.
+     *
+     * @deprecated Use `sandbox.snapshots.delete(name)`.
      */
     deleteSnapshot(snapshotId: string): Promise<void>;
     /**
@@ -110,6 +117,7 @@ export declare class SandboxInstance {
      * is: connections to a sandbox still resuming are retried by the gateway.
      *
      * @param snapshotId - ID of the snapshot to restore this sandbox to.
+     * @deprecated Use `sandbox.snapshots.restore(name)`.
      */
     restore(snapshotId: string): Promise<SandboxRestoreResponse>;
     /**

package/dist/cjs/types/sandbox/snapshot.d.ts

@@ -0,0 +1,40 @@
+import { type Sandbox, type SandboxRestoreResponse } from "../client/index.js";
+import { Snapshot } from "../snapshot/index.js";
+/**
+ * SandboxSnapshotsResource is the sandbox's view of the workspace's snapshots: the
+ * ones captured from it. A snapshot itself belongs to the workspace, so
+ * deleting one here deletes it everywhere, and it stays after this sandbox is
+ * deleted.
+ */
+export declare class SandboxSnapshotsResource {
+    private sandbox;
+    constructor(sandbox: Sandbox);
+    get sandboxName(): string;
+    /**
+     * Capture a snapshot of the sandbox.
+     *
+     * @param name - Name of the snapshot, unique among this sandbox's
+     * snapshots. Generated when omitted.
+     */
+    create(name?: string): Promise<Snapshot>;
+    /** List the snapshots captured from this sandbox. */
+    list(): Promise<Snapshot[]>;
+    /**
+     * Find a snapshot captured from this sandbox by its name, or by its
+     * identifier. Names are only unique within the sandbox, which is why the
+     * workspace-level `Snapshot.get` takes the identifier instead.
+     */
+    get(snapshotName: string): Promise<Snapshot>;
+    /**
+     * Delete a snapshot captured from this sandbox. The snapshot is a workspace
+     * object, so it is removed for the whole workspace.
+     */
+    delete(snapshotName: string): Promise<void>;
+    /**
+     * Restore the sandbox to one of its snapshots. The sandbox keeps its name,
+     * its URLs and its previews: the running instance is torn down and rebuilt
+     * from the snapshot, so everything written since it was taken is lost unless
+     * it was snapshotted too.
+     */
+    restore(snapshotName: string): Promise<SandboxRestoreResponse>;
+}

package/dist/cjs/types/snapshot/index.d.ts

@@ -0,0 +1,103 @@
+import { type Env, type ListSnapshotsData, type SandboxForkResponse, type SandboxSnapshot, type SandboxSnapshotSource } from "../client/index.js";
+export type SnapshotListQuery = NonNullable<ListSnapshotsData["query"]>;
+/** The object a snapshot is captured from. `kind` defaults to `sandbox`. */
+export type SnapshotSourceConfiguration = {
+    name: string;
+    kind?: SandboxSnapshotSource["kind"];
+};
+export type SnapshotCreateConfiguration = {
+    /** Name of the snapshot, unique in the workspace. Generated when omitted. */
+    name?: string;
+    source: SnapshotSourceConfiguration;
+};
+export type SnapshotForkOptions = {
+    /** Resource type to create from the snapshot. Defaults to "sandbox". */
+    targetType?: "sandbox" | "application";
+    /** Port to expose from the created resource. */
+    port?: number;
+    /** Canary traffic percentage (0-100) when forking into an application. */
+    traffic?: number;
+    /** Custom domain for the application fork. */
+    customDomain?: string;
+    /** URL prefix for the application fork. */
+    prefix?: string;
+    /**
+     * Environment variables the fork runs with, on top of the source's. A
+     * variable the source already has takes this value, others are added.
+     */
+    envs?: Env[];
+};
+/**
+ * A snapshot is a workspace resource: it is captured from a sandbox, but it
+ * outlives it. Deleting the sandbox it came from leaves the snapshot in place,
+ * with `source.deleted` set, and it still carries what a fork needs to run.
+ */
+export declare class Snapshot {
+    private snapshot;
+    constructor(snapshot: SandboxSnapshot);
+    get name(): string;
+    /** Identifier of the snapshot on the compute plane. */
+    get id(): string;
+    get status(): string;
+    get workspace(): string;
+    get createdAt(): string;
+    /** The object the snapshot was captured from, and whether it still exists. */
+    get source(): SandboxSnapshotSource | undefined;
+    /** The configuration a fork of this snapshot runs with. */
+    get spec(): import("../client/types.gen.js").SandboxSnapshotSpec | undefined;
+    /**
+     * Capture a snapshot of a source object.
+     *
+     * @example
+     * ```ts
+     * const snapshot = await Snapshot.create({
+     *   name: "my-snapshot",
+     *   source: { name: "my-sandbox" },
+     * });
+     * ```
+     */
+    static create(config: SnapshotCreateConfiguration): Promise<Snapshot>;
+    /**
+     * Fetch a snapshot by its identifier (`snapshot.id`). Names are only unique
+     * within the sandbox they were captured from, so the workspace-level routes
+     * take the identifier; use `sandbox.snapshots.get(name)` to address one by
+     * name.
+     */
+    static get(snapshotId: string): Promise<Snapshot>;
+    /**
+     * List one page of the workspace's snapshots.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and `nextPage()` / `autoPagingEach()` / `autoPagingToArray()`
+     * helpers. Iterate it directly with `for await` to walk every page.
+     *
+     * @example
+     * ```ts
+     * const page = await Snapshot.list({ limit: 50 });
+     * for await (const snapshot of page) {
+     *   console.log(snapshot.name);
+     * }
+     * ```
+     */
+    static list(query?: SnapshotListQuery): Promise<import("../common/pagination.js").PaginatedList<Snapshot, {
+        cursor?: string;
+        limit?: number;
+        sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+        q?: string;
+        anchor?: "end";
+    }>>;
+    /**
+     * Delete a snapshot. There is one snapshot object, so this removes it for
+     * the whole workspace, whether or not the sandbox it came from still exists.
+     */
+    static delete(snapshotId: string): Promise<void>;
+    delete(): Promise<void>;
+    /**
+     * Create a sandbox or an application from this snapshot. This works after
+     * the sandbox the snapshot was captured from has been deleted.
+     *
+     * @param targetName - Name of the sandbox/application to create.
+     * @param options - Fork options (target type, port, traffic, ...).
+     */
+    fork(targetName: string, options?: SnapshotForkOptions): Promise<SandboxForkResponse>;
+}