@blaxel/core 0.3.20 → 0.3.21

package/dist/esm/client/sdk.gen.js

@@ -2168,6 +2168,94 @@ export const deleteApiKeyForServiceAccount = (options) => {
         ...options
     });
 };
+/**
+ * List snapshots
+ * Returns the snapshots of the workspace, newest first by default, including the ones whose source object has been deleted. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array.
+ */
+export const listSnapshots = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/snapshots',
+        ...options
+    });
+};
+/**
+ * Create snapshot
+ * Captures a snapshot from a source object. The snapshot belongs to the workspace rather than to its source, so it survives the deletion of the object it was captured from, and carries what creating a sandbox or an application from it needs.
+ */
+export const createSnapshot = (options) => {
+    return (options.client ?? _heyApiClient).post({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/snapshots',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    });
+};
+/**
+ * Delete snapshot
+ * Deletes a snapshot. There is a single snapshot object, so this removes it for the whole workspace, whether or not the object it was captured from still exists.
+ */
+export const deleteSnapshot = (options) => {
+    return (options.client ?? _heyApiClient).delete({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/snapshots/{snapshotName}',
+        ...options
+    });
+};
+/**
+ * Get snapshot
+ * Returns a snapshot of the workspace by name.
+ */
+export const getSnapshot = (options) => {
+    return (options.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/snapshots/{snapshotName}',
+        ...options
+    });
+};
+/**
+ * Fork snapshot
+ * Creates a new sandbox or application from a snapshot. The snapshot is enough on its own, so this works after the object it was captured from has been deleted.
+ */
+export const forkSnapshot = (options) => {
+    return (options.client ?? _heyApiClient).post({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/snapshots/{snapshotName}/fork',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    });
+};
 /**
  * List deployment templates
  * Returns all deployment templates available for creating agents, functions, and other resources with pre-configured settings and code.

package/dist/esm/common/settings.js

@@ -24,8 +24,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.20";
-const BUILD_COMMIT = "0be98e0951c3607a16d4c40b7612ad7a8c147703";
+const BUILD_VERSION = "0.3.21";
+const BUILD_COMMIT = "3ccc635cd5e9e15a606e3b4c4ae618f992bf4eed";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-28";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/esm/index.js

@@ -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/esm/sandbox/index.js

@@ -7,6 +7,7 @@ export * from "./codegen/index.js";
 export { SandboxDrive } 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/esm/sandbox/sandbox.js

@@ -10,6 +10,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 { normalizeEnvs, normalizePorts, normalizeVolumes } from "./types.js";
@@ -74,6 +75,7 @@ export class SandboxInstance {
     codegen;
     system;
     drives;
+    snapshots;
     h2Session;
     constructor(sandbox) {
         this.sandbox = sandbox;
@@ -86,6 +88,7 @@ export class SandboxInstance {
         this.codegen = new SandboxCodegen(sandbox);
         this.system = new SandboxSystem(sandbox);
         this.drives = new SandboxDrive(sandbox);
+        this.snapshots = new SandboxSnapshotsResource(sandbox);
         this.h2Session = null;
     }
     get metadata() {
@@ -159,6 +162,7 @@ export 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)`.
      */
     async snapshot(name) {
         const { data } = await createSandboxSnapshot({
@@ -170,6 +174,8 @@ export class SandboxInstance {
     }
     /**
      * List the snapshots of this sandbox.
+     *
+     * @deprecated Use `sandbox.snapshots.list()`.
      */
     async listSnapshots() {
         const { data } = await listSandboxSnapshots({
@@ -180,6 +186,8 @@ export class SandboxInstance {
     }
     /**
      * Delete a snapshot of this sandbox by its ID.
+     *
+     * @deprecated Use `sandbox.snapshots.delete(name)`.
      */
     async deleteSnapshot(snapshotId) {
         await deleteSandboxSnapshot({
@@ -197,6 +205,7 @@ export 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)`.
      */
     async restore(snapshotId) {
         const { data } = await restoreSandboxSnapshot({

package/dist/esm/sandbox/snapshot.js

@@ -0,0 +1,73 @@
+import { deleteSandboxSnapshot, listSandboxSnapshots, restoreSandboxSnapshot } 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 class SandboxSnapshotsResource {
+    sandbox;
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+    }
+    get sandboxName() {
+        return this.sandbox.metadata.name;
+    }
+    /**
+     * Capture a snapshot of the sandbox.
+     *
+     * @param name - Name of the snapshot, unique among this sandbox's
+     * snapshots. Generated when omitted.
+     */
+    async create(name) {
+        return await Snapshot.create({
+            ...(name !== undefined ? { name } : {}),
+            source: { name: this.sandboxName, kind: "sandbox" },
+        });
+    }
+    /** List the snapshots captured from this sandbox. */
+    async list() {
+        const { data } = await listSandboxSnapshots({
+            path: { sandboxName: this.sandboxName },
+            throwOnError: true,
+        });
+        return data.map((snapshot) => new Snapshot(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.
+     */
+    async get(snapshotName) {
+        const snapshots = await this.list();
+        const found = snapshots.find((s) => s.name === snapshotName || s.id === snapshotName);
+        if (!found) {
+            throw new Error(`Snapshot ${snapshotName} not found on sandbox ${this.sandboxName}`);
+        }
+        return found;
+    }
+    /**
+     * Delete a snapshot captured from this sandbox. The snapshot is a workspace
+     * object, so it is removed for the whole workspace.
+     */
+    async delete(snapshotName) {
+        await deleteSandboxSnapshot({
+            path: { sandboxName: this.sandboxName, snapshotId: snapshotName },
+            throwOnError: true,
+        });
+    }
+    /**
+     * 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.
+     */
+    async restore(snapshotName) {
+        const { data } = await restoreSandboxSnapshot({
+            path: { sandboxName: this.sandboxName, snapshotId: snapshotName },
+            throwOnError: true,
+        });
+        return data;
+    }
+}

package/dist/esm/snapshot/index.js

@@ -0,0 +1,141 @@
+import { createSnapshot, deleteSnapshot, forkSnapshot, getSnapshot, listSnapshots } from "../client/index.js";
+import { createPaginatedList } from "../common/pagination.js";
+/**
+ * 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 class Snapshot {
+    snapshot;
+    constructor(snapshot) {
+        this.snapshot = snapshot;
+    }
+    get name() {
+        return this.snapshot.name;
+    }
+    /** Identifier of the snapshot on the compute plane. */
+    get id() {
+        return this.snapshot.id;
+    }
+    get status() {
+        return this.snapshot.status;
+    }
+    get workspace() {
+        return this.snapshot.workspace;
+    }
+    get createdAt() {
+        return this.snapshot.createdAt;
+    }
+    /** The object the snapshot was captured from, and whether it still exists. */
+    get source() {
+        return this.snapshot.source;
+    }
+    /** The configuration a fork of this snapshot runs with. */
+    get spec() {
+        return this.snapshot.spec;
+    }
+    /**
+     * Capture a snapshot of a source object.
+     *
+     * @example
+     * ```ts
+     * const snapshot = await Snapshot.create({
+     *   name: "my-snapshot",
+     *   source: { name: "my-sandbox" },
+     * });
+     * ```
+     */
+    static async create(config) {
+        const { data } = await createSnapshot({
+            body: {
+                ...(config.name !== undefined ? { name: config.name } : {}),
+                source: {
+                    name: config.source.name,
+                    ...(config.source.kind !== undefined ? { kind: config.source.kind } : {}),
+                },
+            },
+            throwOnError: true,
+        });
+        return new Snapshot(data);
+    }
+    /**
+     * 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 async get(snapshotId) {
+        const { data } = await getSnapshot({
+            path: { snapshotName: snapshotId },
+            throwOnError: true,
+        });
+        return new Snapshot(data);
+    }
+    /**
+     * 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 async list(query) {
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listSnapshots({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (snapshot) => new Snapshot(snapshot),
+            query,
+        });
+    }
+    /**
+     * 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 async delete(snapshotId) {
+        const { data } = await deleteSnapshot({
+            path: { snapshotName: snapshotId },
+            throwOnError: true,
+        });
+        return data;
+    }
+    async delete() {
+        return await Snapshot.delete(this.id);
+    }
+    /**
+     * 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, ...).
+     */
+    async fork(targetName, options = {}) {
+        const { data } = await forkSnapshot({
+            path: { snapshotName: this.id },
+            body: {
+                targetName,
+                targetType: options.targetType ?? "sandbox",
+                ...(options.port !== undefined ? { port: options.port } : {}),
+                ...(options.traffic !== undefined ? { traffic: options.traffic } : {}),
+                ...(options.customDomain !== undefined ? { customDomain: options.customDomain } : {}),
+                ...(options.prefix !== undefined ? { prefix: options.prefix } : {}),
+                ...(options.envs !== undefined ? { envs: options.envs } : {}),
+            },
+            throwOnError: true,
+        });
+        return data;
+    }
+}