@watasu/sdk 0.1.4 → 0.1.5

package/README.md

@@ -26,4 +26,20 @@ await sbx.kill()
 `Sandbox.create` and `Sandbox.connect` return only after the Watasu API supplies
 a usable data-plane session. The SDK does not poll sandbox readiness.
 
+## Metrics And Snapshots
+
+```ts
+import { Sandbox } from '@watasu/sdk'
+
+const sbx = await Sandbox.create()
+const metrics = await sbx.getMetrics()
+const snapshot = await sbx.createSnapshot({ name: 'ready' })
+const snapshots = await sbx.listSnapshots().nextItems()
+const restored = await sbx.restore({ snapshotId: snapshot.snapshotId })
+await sbx.kill()
+```
+
+Watasu snapshots are backed by sandbox checkpoints. Use the returned
+`snapshotId` when restoring from a checkpoint.
+
 The SDK is ESM-first and ships TypeScript declarations.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
 export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
-export { Sandbox } from './sandbox.js';
-export type { SandboxCreateOpts, SandboxConnectOpts, SandboxInfo } from './sandbox.js';
+export { Sandbox, SnapshotPaginator } from './sandbox.js';
+export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxMetrics, SnapshotInfo, } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
 export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
 export { FileType, Filesystem } from './filesystem.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
 export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
-export { Sandbox } from './sandbox.js';
+export { Sandbox, SnapshotPaginator } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
 export { FileType, Filesystem } from './filesystem.js';
 export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.js';

package/dist/sandbox.d.ts

@@ -28,6 +28,45 @@ export interface SandboxInfo {
     startedAt?: string;
     endAt?: string;
 }
+export interface SandboxMetrics {
+    sandboxId?: string;
+    state?: string;
+    node?: string;
+    backend?: string;
+    cpuCount?: number;
+    memoryMb?: number;
+    raw: Record<string, unknown>;
+}
+export interface SnapshotInfo {
+    snapshotId: string;
+    sandboxId?: string;
+    name?: string;
+    status?: string;
+    sizeBytes?: number;
+    createdAt?: string;
+    expiresAt?: string;
+    raw: Record<string, unknown>;
+}
+export interface CreateSnapshotOpts extends ConnectionOpts {
+    name?: string;
+    metadata?: Record<string, string>;
+    expiresAt?: string;
+    quiesceMode?: string;
+}
+export interface RestoreSnapshotOpts extends ConnectionOpts {
+    checkpointId?: string | number;
+    snapshotId?: string | number;
+    timeout?: number;
+    timeoutMs?: number;
+}
+export declare class SnapshotPaginator {
+    private readonly loadItems;
+    private consumed;
+    hasNext: boolean;
+    nextToken: string | undefined;
+    constructor(loadItems: () => Promise<SnapshotInfo[]>);
+    nextItems(): Promise<SnapshotInfo[]>;
+}
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export declare class Sandbox {
     /** Default template slug used when create is called without a template. */
@@ -62,6 +101,16 @@ export declare class Sandbox {
     connect(opts?: SandboxConnectOpts): Promise<this>;
     /** Destroy a sandbox by id. */
     static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Fetch sandbox metrics by id. */
+    static getMetrics(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    /** Deprecated alias for `getInfo`. */
+    static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
+    /** Create a Watasu checkpoint using snapshot naming. */
+    static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** List checkpoints for one sandbox using snapshot naming. */
+    static listSnapshots(sandboxId: string, opts?: ConnectionOpts): SnapshotPaginator;
+    /** Snapshot deletion is not backed by a Watasu checkpoint delete API yet. */
+    static deleteSnapshot(..._args: unknown[]): never;
     /** Destroy this sandbox. */
     kill(): Promise<boolean>;
     /** Check if this sandbox is in a runtime-active lifecycle state. */
@@ -74,15 +123,25 @@ export declare class Sandbox {
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
     getInfo(): Promise<SandboxInfo>;
+    /** Fetch latest sandbox metrics. */
+    getMetrics(opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    /** Create a Watasu checkpoint using snapshot naming. */
+    createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** Watasu-native alias for `createSnapshot`. */
+    checkpoint(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** List checkpoints for this sandbox using snapshot naming. */
+    listSnapshots(opts?: ConnectionOpts): SnapshotPaginator;
+    /** Restore a checkpoint into a new sandbox and return its control-plane info. */
+    restore(opts?: RestoreSnapshotOpts | string | number): Promise<SandboxInfo>;
     /** List sandboxes visible to the configured API key. */
     static list(opts?: ConnectionOpts & {
         team?: string;
     }): Promise<SandboxInfo[]>;
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port: number): string;
+    updateNetwork(..._args: unknown[]): never;
     pause(): never;
+    betaPause(): never;
     resume(): never;
-    createSnapshot(): never;
-    checkpoint(): never;
-    restore(): never;
+    private configOptions;
 }

package/dist/sandbox.js

@@ -3,6 +3,22 @@ import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connec
 import { DataPlaneClient, ControlClient } from './transport.js';
 import { NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
+export class SnapshotPaginator {
+    loadItems;
+    consumed = false;
+    hasNext = true;
+    nextToken;
+    constructor(loadItems) {
+        this.loadItems = loadItems;
+    }
+    async nextItems() {
+        if (this.consumed)
+            throw new SandboxError('No more snapshots to fetch');
+        this.consumed = true;
+        this.hasNext = false;
+        return this.loadItems();
+    }
+}
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export class Sandbox {
     /** Default template slug used when create is called without a template. */
@@ -102,6 +118,42 @@ export class Sandbox {
         await control.delete(`/sandboxes/${sandboxId}`);
         return true;
     }
+    /** Fetch sandbox metrics by id. */
+    static async getMetrics(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        const payload = await control.get(`/sandboxes/${sandboxId}/metrics`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return metricsList(payload.metrics ?? payload);
+    }
+    /** Deprecated alias for `getInfo`. */
+    static async getFullInfo(sandboxId, opts = {}) {
+        return this.getInfo(sandboxId, opts);
+    }
+    /** Create a Watasu checkpoint using snapshot naming. */
+    static async createSnapshot(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        const payload = await control.post(`/sandboxes/${sandboxId}/checkpoints`, {
+            json: snapshotPayload(opts),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
+    }
+    /** List checkpoints for one sandbox using snapshot naming. */
+    static listSnapshots(sandboxId, opts = {}) {
+        return new SnapshotPaginator(async () => {
+            const control = new ControlClient(new ConnectionConfig(opts));
+            const payload = await control.get(`/sandboxes/${sandboxId}/checkpoints`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            const snapshots = Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
+            return snapshots.map((item) => snapshotInfo(record(item)));
+        });
+    }
+    /** Snapshot deletion is not backed by a Watasu checkpoint delete API yet. */
+    static deleteSnapshot(..._args) {
+        unsupported('Sandbox.deleteSnapshot');
+    }
     /** Destroy this sandbox. */
     async kill() {
         await this.control.delete(`/sandboxes/${this.sandboxId}`);
@@ -146,6 +198,41 @@ export class Sandbox {
         const payload = await this.control.get(`/sandboxes/${this.sandboxId}`);
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
+    /** Fetch latest sandbox metrics. */
+    async getMetrics(opts = {}) {
+        return Sandbox.getMetrics(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Create a Watasu checkpoint using snapshot naming. */
+    async createSnapshot(opts = {}) {
+        return Sandbox.createSnapshot(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Watasu-native alias for `createSnapshot`. */
+    async checkpoint(opts = {}) {
+        return this.createSnapshot(opts);
+    }
+    /** List checkpoints for this sandbox using snapshot naming. */
+    listSnapshots(opts = {}) {
+        return Sandbox.listSnapshots(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Restore a checkpoint into a new sandbox and return its control-plane info. */
+    async restore(opts = {}) {
+        const restoreOpts = typeof opts === 'string' || typeof opts === 'number'
+            ? { checkpointId: opts }
+            : opts;
+        const checkpointId = restoreOpts.checkpointId ?? restoreOpts.snapshotId;
+        if (checkpointId === undefined)
+            throw new SandboxError('checkpointId or snapshotId is required');
+        const payload = { checkpoint_id: checkpointId };
+        if (restoreOpts.timeout !== undefined)
+            payload.timeout_seconds = restoreOpts.timeout;
+        if (restoreOpts.timeoutMs !== undefined)
+            payload.timeout_seconds = Math.ceil(restoreOpts.timeoutMs / 1000);
+        const response = await this.control.post(`/sandboxes/${this.sandboxId}/restore`, {
+            json: payload,
+            requestTimeoutMs: restoreOpts.requestTimeoutMs,
+        });
+        return sandboxInfo(record(response.sandbox ?? response));
+    }
     /** List sandboxes visible to the configured API key. */
     static async list(opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
@@ -162,11 +249,18 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
+    updateNetwork(..._args) { unsupported('Sandbox.updateNetwork'); }
     pause() { unsupported('Sandbox.pause'); }
+    betaPause() { unsupported('Sandbox.betaPause'); }
     resume() { unsupported('Sandbox.resume'); }
-    createSnapshot() { unsupported('Sandbox.createSnapshot'); }
-    checkpoint() { unsupported('Sandbox.checkpoint'); }
-    restore() { unsupported('Sandbox.restore'); }
+    configOptions() {
+        return {
+            apiKey: this.config.apiKey,
+            apiUrl: this.config.apiUrl,
+            dataPlaneDomain: this.config.dataPlaneDomain,
+            requestTimeoutMs: this.config.requestTimeoutMs,
+        };
+    }
 }
 function dataPlaneFromSession(session, config) {
     const item = record(session);
@@ -199,6 +293,55 @@ function sandboxInfo(payload) {
             : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function metricsList(value) {
+    if (Array.isArray(value))
+        return value.map((item) => metricsInfo(record(item)));
+    return [metricsInfo(record(value))];
+}
+function metricsInfo(value) {
+    return {
+        sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
+        state: stringValue(value.state),
+        node: stringValue(value.node),
+        backend: stringValue(value.backend),
+        cpuCount: numberValue(value.cpu_count ?? value.cpuCount),
+        memoryMb: numberValue(value.memory_mb ?? value.memoryMb),
+        raw: value,
+    };
+}
+function snapshotPayload(opts) {
+    const payload = {};
+    putIfPresent(payload, 'name', opts.name);
+    putIfPresent(payload, 'metadata', opts.metadata);
+    putIfPresent(payload, 'expires_at', opts.expiresAt);
+    putIfPresent(payload, 'quiesce_mode', opts.quiesceMode);
+    return payload;
+}
+function snapshotInfo(value) {
+    const id = value.snapshot_id ?? value.snapshotId ?? value.checkpoint_id ?? value.checkpointId ?? value.id;
+    if (id === undefined)
+        throw new SandboxError('snapshot response did not include id');
+    return {
+        snapshotId: String(id),
+        sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
+        name: stringValue(value.name),
+        status: stringValue(value.status),
+        sizeBytes: numberValue(value.size_bytes ?? value.sizeBytes),
+        createdAt: stringValue(value.created_at ?? value.createdAt),
+        expiresAt: stringValue(value.expires_at ?? value.expiresAt),
+        raw: value,
+    };
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}
 function templateSlug(value) {
     const template = record(value);
     return typeof template.slug === 'string' ? template.slug : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",
@@ -28,5 +28,10 @@
     "@types/node": "^24.0.3",
     "@types/ws": "^8.18.1",
     "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/watasuio/sdk.git",
+    "directory": "ts"
   }
 }