@aerol-ai/aerolvm-sdk 0.1.9 → 0.2.1

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, MountSpecRedacted, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
+import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -21,11 +21,13 @@ export declare class MicroVM {
     private readonly client;
     constructor(config?: MicroVMConfig);
     create(options: CreateOptions): Promise<Sandbox>;
-    list(): Promise<Sandbox[]>;
+    list(options?: ListOptions): Promise<Sandbox[]>;
     get(id: string): Promise<Sandbox>;
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
+    registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<Sandbox>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;

package/dist/MicroVM.js

@@ -25,8 +25,8 @@ export class MicroVM {
         const sandbox = await this.client.create(options);
         return this.wrap(sandbox.toJSON());
     }
-    async list() {
-        const sandboxes = await this.client.list();
+    async list(options) {
+        const sandboxes = await this.client.list(options);
         return sandboxes.map((sandbox) => this.wrap(sandbox.toJSON()));
     }
     async get(id) {
@@ -44,6 +44,12 @@ export class MicroVM {
     async createSnapshot(id, name) {
         return this.client.createSnapshot(id, name);
     }
+    async registerSnapshot(options) {
+        return this.client.registerSnapshot(options);
+    }
+    async registerSnapshotFromImage(name, image, options = {}) {
+        return this.client.registerSnapshotFromImage(name, image, options);
+    }
     async destroy(id) {
         await this.client.destroy(id);
     }

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
 export type { MicroVMConfig } from "./MicroVM.js";
-export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, HealthStatus, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, HealthStatus, Lifecycle, MountSpecRedacted, NetworkUsage, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
+import type { BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, HealthStatus, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
@@ -55,11 +55,13 @@ export declare class APIClient {
      */
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     private resolveImage;
-    list(): Promise<SandboxResource[]>;
+    list(options?: ListOptions): Promise<SandboxResource[]>;
     get(id: string): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
+    registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;

package/dist/internal/client.js

@@ -85,8 +85,9 @@ export class APIClient {
         const result = await this.buildImage(options.image);
         return { ...options, image: result.image };
     }
-    async list() {
-        const response = await this.doJSON("GET", this.versioned("/sandboxes"));
+    async list(options) {
+        const path = this.versioned("/sandboxes") + buildTagQuery(options?.tags);
+        const response = await this.doJSON("GET", path);
         return response.map((item) => this.wrap(item));
     }
     async get(id) {
@@ -105,6 +106,35 @@ export class APIClient {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/snapshot`, { name });
         return fromApiSandboxSnapshot(response);
     }
+    async registerSnapshot(options) {
+        const name = options.name.trim();
+        if (name === "") {
+            throw new Error("name is required");
+        }
+        const image = options.image?.trim() ?? "";
+        const dockerfileContent = options.dockerfileContent?.trim() ?? "";
+        if (image === "" && dockerfileContent === "") {
+            throw new Error("image or dockerfile_content is required");
+        }
+        if (image !== "" && dockerfileContent !== "") {
+            throw new Error("image and dockerfile_content are mutually exclusive");
+        }
+        const response = await this.doJSON("POST", this.versioned("/snapshots"), toApiRegisterSnapshotOptions({
+            ...options,
+            name,
+            image: image || undefined,
+            dockerfileContent: dockerfileContent || undefined,
+            regionID: options.regionID?.trim() || undefined,
+        }));
+        return fromApiSandboxSnapshot(response);
+    }
+    async registerSnapshotFromImage(name, image, options = {}) {
+        return this.registerSnapshot({
+            ...options,
+            name,
+            dockerfileContent: image.dockerfile,
+        });
+    }
     async destroy(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
@@ -361,6 +391,20 @@ function toApiCreateOptions(options) {
         runtime: options.runtime,
     };
 }
+function toApiRegisterSnapshotOptions(options) {
+    return {
+        name: options.name,
+        image: options.image,
+        dockerfile_content: options.dockerfileContent,
+        context_hashes: options.contextHashes,
+        entrypoint: options.entrypoint,
+        region_id: options.regionID,
+        cpu: options.cpu,
+        gpu: options.gpu,
+        memory_mb: options.memoryMB,
+        disk_gb: options.diskGB,
+    };
+}
 function toApiResizeOptions(options) {
     return {
         cpu: options.cpu,
@@ -444,6 +488,12 @@ function fromApiSandboxSnapshot(snapshot) {
         imageID: snapshot.image_id,
         sourceSandboxID: snapshot.source_sandbox_id,
         createdAt: snapshot.created_at,
+        entrypoint: snapshot.entrypoint,
+        regionID: snapshot.region_id,
+        cpu: snapshot.cpu,
+        gpu: snapshot.gpu,
+        memoryMB: snapshot.memory_mb,
+        diskGB: snapshot.disk_gb,
     };
 }
 function fromApiSession(session) {
@@ -559,6 +609,21 @@ function fromApiLifecycle(lifecycle) {
     }
     return result;
 }
+// buildTagQuery renders ListOptions.tags as the server's wire format. The
+// `tag.` prefix is literal — the server's parseTagFilter does a prefix check
+// on the *decoded* query key, so only the user-supplied key and value get
+// percent-encoded. An empty or absent map returns "" so the request URL is
+// byte-identical to the pre-filter call site (no trailing "?"), keeping
+// fixtures and middleware that match on path stable.
+function buildTagQuery(tags) {
+    if (!tags)
+        return "";
+    const entries = Object.entries(tags);
+    if (entries.length === 0)
+        return "";
+    const parts = entries.map(([key, value]) => `tag.${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+    return "?" + parts.join("&");
+}
 function cloneSandbox(sandbox) {
     return {
         ...sandbox,

package/dist/types.d.ts

@@ -28,6 +28,25 @@ export interface BuildImageResult {
     /** Pushed reference, e.g. "ghcr.io/my-org/my-image:v1.2.3". */
     pushed?: string;
 }
+export interface RegisterSnapshotOptions {
+    /** Human-readable identifier other callers use in `CreateOptions.snapshot`. */
+    name: string;
+    /** Pre-built registry reference. Mutually exclusive with `dockerfileContent`. */
+    image?: string;
+    /** Literal Dockerfile the daemon will build. Mutually exclusive with `image`. */
+    dockerfileContent?: string;
+    /** Uploaded build-context hashes for future COPY/ADD resolution. */
+    contextHashes?: string[];
+    /** Optional command override persisted on the snapshot row. */
+    entrypoint?: string[];
+    /** Region hint persisted for read-back. */
+    regionID?: string;
+    /** Resource hints surfaced back on the snapshot row. */
+    cpu?: number;
+    gpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
+}
 export type MountType = "s3" | "nfs" | "sshfs" | "rclone";
 export interface MountSpec {
     type: MountType;
@@ -142,6 +161,15 @@ export interface ResizeOptions {
     memoryMB?: number;
     diskGB?: number;
 }
+export interface ListOptions {
+    /**
+     * Filter the result to only sandboxes whose `tags` map contains every
+     * key/value pair given here (AND semantics on the server). Wire format is
+     * `?tag.<key>=<value>`; the SDK URL-encodes keys and values for you. Omit
+     * or pass an empty map to list every sandbox visible to the PAT.
+     */
+    tags?: Record<string, string>;
+}
 export interface CreateSessionOptions {
     name?: string;
     argv?: string[];
@@ -192,6 +220,12 @@ export interface SandboxSnapshot {
     imageID?: string;
     sourceSandboxID: string;
     createdAt: string;
+    entrypoint?: string[];
+    regionID?: string;
+    cpu?: number;
+    gpu?: number;
+    memoryMB?: number;
+    diskGB?: number;
 }
 /**
  * Discriminated result from `exposePort`. Branch on `protocol` to access the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",