@lizard-build/sdk 0.1.43 → 0.1.45

package/README.md

@@ -1,4 +1,4 @@
-# Lizard TypeScript SDK
+# Lizard SDK for TypeScript
 
 Run commands, work with files and execute code in Linux sandboxes on Kubernetes. The SDK also manages Lizard apps, databases, storage and projects.
 
@@ -51,26 +51,26 @@ const result = await sandbox.process.exec('printf "hello\\n"', {
 if (result.exitCode !== 0) throw new Error(result.stderr)
 ```
 
-## Run code
+## Run Python
 
-`CodeSandbox` uses the `code-interpreter-v1` template by default. Code errors appear in `result.error`; request failures throw.
+Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls. Save intermediate results to files. The API returns stdout, stderr, and an exit code; it does not return typed notebook results or chart objects.
 
 ```ts
-import { CodeSandbox } from '@lizard-build/sdk'
+import { Sandbox } from '@lizard-build/sdk';
 
-const sandbox = await CodeSandbox.create({ project: 'my-project' })
+const sandbox = await Sandbox.create('interpreter', {
+  projectId: 'proj_123', timeoutMs: 300_000,
+});
 try {
-  const result = await sandbox.runCode('print(6 * 7)', {
-    language: 'python',
-    timeoutMs: 60_000,
-    onStdout: chunk => process.stdout.write(chunk),
-  })
-  if (result.error) throw result.error
+  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'");
+  console.log(result.stdout, result.stderr, result.exitCode);
 } finally {
-  await sandbox.kill()
+  await sandbox.kill();
 }
 ```
 
+`CodeSandbox`, `runCode` / `run_code`, and execution-context methods remain in the SDK, but the hosted template catalog does not provide their required execution server. The legacy default `code-interpreter-v1` is unavailable. Changing its name to `interpreter` does not enable this API. Use `Sandbox.create("interpreter")` and process commands as shown below.
+
 ## Configuration
 
 The SDK reads `LIZARD_API_KEY` and, optionally, `LIZARD_API_URL` (default: `https://lizard.build`). You can also pass `apiKey` and `apiUrl` to the constructor or static sandbox methods.
@@ -79,10 +79,16 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Sandboxes run on Kubernetes. Use volumes mounted at `/workspace` to keep files after a sandbox ends. Pause, resume, fork, snapshot creation and snapshot restore return HTTP 501 on the current backend.
+Sandboxes run on Kubernetes. Use volumes mounted at `/workspace` to keep files after a sandbox ends. CRIU pause/resume and private snapshots preserve running memory and workspace files. Snapshot pools keep five copies warm by default and can be paused to release idle compute. Fork and file watching remain unsupported. See the [snapshot lifecycle guide](../../docs/sandboxes.md#snapshots-and-criu-pause-resume).
 
 `getHost()` returns a hostname without `https://`. File writes accept UTF-8 text or valid UTF-8 bytes; `readBytes()` supports binary downloads.
 
+## Current command and lifetime limits
+
+Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The current runtime does not apply the SDK command options `envs`, `workdir`, or `user`; set the directory and environment in the shell command when needed. Create-time `envs` and `metadata` are also not applied.
+
+The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: `timeoutMs: 0` at creation disables expiration; a positive value sets a deadline. `setTimeout` accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
+
 ## Learn more
 
 - [Sandbox reference](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md)

package/dist/index.d.mts

@@ -650,6 +650,9 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
+    pauseError?: string | null;
+    size?: 'small' | 'medium' | 'large' | null;
+    pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
     metadata?: Record<string, string>;
@@ -665,6 +668,8 @@ interface SandboxOpts extends ConnectionOpts {
     /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
     projectId?: string;
     template?: string;
+    snapshotId?: string;
+    size?: 'small' | 'medium' | 'large';
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
@@ -731,6 +736,27 @@ declare class SandboxClient {
     }>;
 }
 
+interface SandboxSnapshot {
+    id: string;
+    name: string;
+    projectId: string;
+    workspaceId: string;
+    region: string;
+    sourceSandboxId: string;
+    status: 'building' | 'warming' | 'ready' | 'paused' | 'suspended' | 'failed';
+    poolSize: number;
+    readyCount: number;
+    error: string | null;
+    cpus: number;
+    memoryMb: number;
+    createdAt: number;
+}
+interface SnapshotOpts {
+    poolSize?: number;
+}
+interface SnapshotWaitOpts extends ConnectionOpts {
+    waitTimeoutMs?: number;
+}
 /**
  * A Linux sandbox running on Kubernetes.
  *
@@ -813,14 +839,15 @@ declare class Sandbox extends SandboxClient {
      * Create a new Lizard sandbox from the specified template.
      *
      * Template availability and installed tools depend on the platform and region.
-     * Use `base` for shell commands or `CodeSandbox` for stateful code execution.
+     * Use `base` for shell commands or `interpreter` for Python process commands.
+     * Hosted templates do not support the legacy `CodeSandbox` execution API.
      *
      * @param template Name of the sandbox template to boot from.
      *
      * @example
      * ```ts
      * const sandbox = await Sandbox.create('base', { project: 'my-project' })
-     * const pythonSandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
+     * const pythonSandbox = await Sandbox.create('interpreter', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -855,20 +882,12 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-     * and attach it to a new sandbox instead.
-     */
+    /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-     * reconnect to a running sandbox.
-     */
+    /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
     resume(opts?: ConnectionOpts): Promise<boolean>;
+    /** Wait for an asynchronous pause/resume operation to finish. */
+    waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
     /**
      * Get metadata and status information about this sandbox.
      */
@@ -898,18 +917,25 @@ declare class Sandbox extends SandboxClient {
         count?: number;
         timeoutMs?: number;
     }): Promise<unknown>;
-    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-    snapshot(name?: string): Promise<unknown>;
+    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
-    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
-    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot[]>;
+    static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Start a sandbox from an available warm copy in the snapshot's project and region. */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
+    static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+    static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Refill the configured warm pool without another capture. */
+    static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    static waitForSnapshot(snapshotId: string, opts?: SnapshotWaitOpts): Promise<SandboxSnapshot>;
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<void>;
     private resolveOpts;
 }
@@ -1682,31 +1708,14 @@ interface CreateContextOpts {
 }
 
 /**
- * A Lizard sandbox with built-in stateful code execution.
- *
- * Extends the base Sandbox with `runCode()` — executes code in a persistent
- * kernel so variables and imports survive between calls.
- *
- * Supports Python, JavaScript (Node.js), and Bash out of the box.
- *
- * @example
- * ```ts
- * import { CodeSandbox } from '@lizard-build/sdk'
+ * Legacy client for the code-interpreter execution server.
  *
- * const sandbox = await CodeSandbox.create({ project: 'my-project' })
+ * Current hosted templates do not provide this server. The default
+ * `code-interpreter-v1` template is unavailable; selecting `interpreter`
+ * does not enable this API. Use `Sandbox.create('interpreter', options)`
+ * and `sandbox.process.exec()` for Python commands instead.
  *
- * await sandbox.runCode('x = 42')
- * const result = await sandbox.runCode('print(x * 2)')
- * console.log(result.stdout) // "84\n"
- *
- * await sandbox.kill()
- * ```
- *
- * @example Run JavaScript:
- * ```ts
- * const result = await sandbox.runCode('1 + 1', { language: 'javascript' })
- * console.log(result.results[0].data) // "2"
- * ```
+ * The methods remain for compatibility with a separately provided server.
  */
 declare class CodeSandbox extends Sandbox {
     protected static readonly defaultTemplate = "code-interpreter-v1";
@@ -1789,4 +1798,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.d.ts

@@ -650,6 +650,9 @@ interface SandboxInfo {
     /** Region the sandbox runs in — the volume's region when one is attached. */
     region?: string;
     status?: string;
+    pauseError?: string | null;
+    size?: 'small' | 'medium' | 'large' | null;
+    pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
     metadata?: Record<string, string>;
@@ -665,6 +668,8 @@ interface SandboxOpts extends ConnectionOpts {
     /** Exact project ID — skips resolving {@link SandboxOpts.project}. */
     projectId?: string;
     template?: string;
+    snapshotId?: string;
+    size?: 'small' | 'medium' | 'large';
     metadata?: Record<string, string>;
     envs?: Record<string, string>;
     timeoutMs?: number;
@@ -731,6 +736,27 @@ declare class SandboxClient {
     }>;
 }
 
+interface SandboxSnapshot {
+    id: string;
+    name: string;
+    projectId: string;
+    workspaceId: string;
+    region: string;
+    sourceSandboxId: string;
+    status: 'building' | 'warming' | 'ready' | 'paused' | 'suspended' | 'failed';
+    poolSize: number;
+    readyCount: number;
+    error: string | null;
+    cpus: number;
+    memoryMb: number;
+    createdAt: number;
+}
+interface SnapshotOpts {
+    poolSize?: number;
+}
+interface SnapshotWaitOpts extends ConnectionOpts {
+    waitTimeoutMs?: number;
+}
 /**
  * A Linux sandbox running on Kubernetes.
  *
@@ -813,14 +839,15 @@ declare class Sandbox extends SandboxClient {
      * Create a new Lizard sandbox from the specified template.
      *
      * Template availability and installed tools depend on the platform and region.
-     * Use `base` for shell commands or `CodeSandbox` for stateful code execution.
+     * Use `base` for shell commands or `interpreter` for Python process commands.
+     * Hosted templates do not support the legacy `CodeSandbox` execution API.
      *
      * @param template Name of the sandbox template to boot from.
      *
      * @example
      * ```ts
      * const sandbox = await Sandbox.create('base', { project: 'my-project' })
-     * const pythonSandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
+     * const pythonSandbox = await Sandbox.create('interpreter', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -855,20 +882,12 @@ declare class Sandbox extends SandboxClient {
      * @returns `true` if the sandbox was terminated, `false` if it was already gone.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-     * and attach it to a new sandbox instead.
-     */
+    /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
     pause(opts?: ConnectionOpts): Promise<boolean>;
-    /**
-     * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-     *
-     * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-     * reconnect to a running sandbox.
-     */
+    /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
     resume(opts?: ConnectionOpts): Promise<boolean>;
+    /** Wait for an asynchronous pause/resume operation to finish. */
+    waitForStatus(status: 'paused' | 'running', opts?: SnapshotWaitOpts): Promise<SandboxInfo>;
     /**
      * Get metadata and status information about this sandbox.
      */
@@ -898,18 +917,25 @@ declare class Sandbox extends SandboxClient {
         count?: number;
         timeoutMs?: number;
     }): Promise<unknown>;
-    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-    snapshot(name?: string): Promise<unknown>;
+    /** Capture memory and workspace files. Disconnect active clients before capturing. */
+    snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
     logs(opts?: {
         tail?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, any, any>;
-    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
-    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot[]>;
+    static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Start a sandbox from an available warm copy in the snapshot's project and region. */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
     }): Promise<Sandbox>;
+    static setSnapshotWarmPool(snapshotId: string, poolSize: number, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+    static pauseSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    /** Refill the configured warm pool without another capture. */
+    static resumeSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
+    static waitForSnapshot(snapshotId: string, opts?: SnapshotWaitOpts): Promise<SandboxSnapshot>;
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<void>;
     private resolveOpts;
 }
@@ -1682,31 +1708,14 @@ interface CreateContextOpts {
 }
 
 /**
- * A Lizard sandbox with built-in stateful code execution.
- *
- * Extends the base Sandbox with `runCode()` — executes code in a persistent
- * kernel so variables and imports survive between calls.
- *
- * Supports Python, JavaScript (Node.js), and Bash out of the box.
- *
- * @example
- * ```ts
- * import { CodeSandbox } from '@lizard-build/sdk'
+ * Legacy client for the code-interpreter execution server.
  *
- * const sandbox = await CodeSandbox.create({ project: 'my-project' })
+ * Current hosted templates do not provide this server. The default
+ * `code-interpreter-v1` template is unavailable; selecting `interpreter`
+ * does not enable this API. Use `Sandbox.create('interpreter', options)`
+ * and `sandbox.process.exec()` for Python commands instead.
  *
- * await sandbox.runCode('x = 42')
- * const result = await sandbox.runCode('print(x * 2)')
- * console.log(result.stdout) // "84\n"
- *
- * await sandbox.kill()
- * ```
- *
- * @example Run JavaScript:
- * ```ts
- * const result = await sandbox.runCode('1 + 1', { language: 'javascript' })
- * console.log(result.results[0].data) // "2"
- * ```
+ * The methods remain for compatibility with a separately provided server.
  */
 declare class CodeSandbox extends Sandbox {
     protected static readonly defaultTemplate = "code-interpreter-v1";
@@ -1789,4 +1798,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.js

@@ -849,6 +849,8 @@ var SandboxClient = class {
       headers: config.headers,
       body: JSON.stringify({
         template,
+        snapshotId: opts?.snapshotId,
+        size: opts?.size,
         timeoutMs,
         projectId,
         metadata: opts?.metadata,
@@ -981,24 +983,28 @@ var Sandbox = class extends SandboxClient {
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-   * and attach it to a new sandbox instead.
-   */
+  /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-   * reconnect to a running sandbox.
-   */
+  /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
   }
+  /** Wait for an asynchronous pause/resume operation to finish. */
+  async waitForStatus(status, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 6e5);
+    do {
+      const info = await this.getInfo(opts);
+      if (info.status === status) return info;
+      if (["failed", "stopped", "deleted"].includes(info.status ?? "") || info.pauseError) {
+        throw new ConflictError(info.pauseError ?? `Sandbox is ${info.status}`);
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError(`Sandbox did not become ${status} within the wait timeout`);
+  }
   /**
    * Get metadata and status information about this sandbox.
    */
@@ -1034,9 +1040,9 @@ var Sandbox = class extends SandboxClient {
   fork(opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
   }
-  /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-  snapshot(name) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name });
+  /** Capture memory and workspace files. Disconnect active clients before capturing. */
+  snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5 });
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1045,13 +1051,45 @@ var Sandbox = class extends SandboxClient {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
   static snapshots(projectId, opts) {
-    return new PlatformClient(opts ?? {}).get(`/api/projects/${projectId}/snapshots`);
+    return new PlatformClient(opts ?? {}).get(`/api/projects/${encodeURIComponent(projectId)}/snapshots`);
+  }
+  static getSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).get(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+  /** Start a sandbox from an available warm copy in the snapshot's project and region. */
   static async restore(snapshotId, opts) {
-    const result = await new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/fork`, { timeoutMs: opts?.timeoutMs ?? 0 });
+    const client = new PlatformClient(opts ?? {});
+    const snapshot = await this.getSnapshot(snapshotId, opts);
+    const result = await client.post("/api/sandboxes", {
+      snapshotId,
+      projectId: snapshot.projectId,
+      region: snapshot.region,
+      timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
+    });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });
   }
+  static setSnapshotWarmPool(snapshotId, poolSize, opts) {
+    return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
+  }
+  /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+  static pauseSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
+  }
+  /** Refill the configured warm pool without another capture. */
+  static resumeSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/resume`, {});
+  }
+  static async waitForSnapshot(snapshotId, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 9e5);
+    do {
+      const snapshot = await this.getSnapshot(snapshotId, opts);
+      if (snapshot.status === "ready") return snapshot;
+      if (["failed", "paused", "suspended"].includes(snapshot.status)) throw new ConflictError(snapshot.error ?? `Snapshot is ${snapshot.status}`);
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError("Snapshot did not become ready within the wait timeout");
+  }
   static deleteSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).delete(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }

package/dist/index.mjs

@@ -798,6 +798,8 @@ var SandboxClient = class {
       headers: config.headers,
       body: JSON.stringify({
         template,
+        snapshotId: opts?.snapshotId,
+        size: opts?.size,
         timeoutMs,
         projectId,
         metadata: opts?.metadata,
@@ -930,24 +932,28 @@ var Sandbox = class extends SandboxClient {
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox pause. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
-   * and attach it to a new sandbox instead.
-   */
+  /** Queue a CRIU checkpoint and stop compute. Use waitForStatus('paused') before resuming. */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
-  /**
-   * Request sandbox resume. The Kubernetes backend returns HTTP 501.
-   *
-   * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
-   * reconnect to a running sandbox.
-   */
+  /** Queue restoration of saved memory and files. Use waitForStatus('running') before executing. */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
   }
+  /** Wait for an asynchronous pause/resume operation to finish. */
+  async waitForStatus(status, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 6e5);
+    do {
+      const info = await this.getInfo(opts);
+      if (info.status === status) return info;
+      if (["failed", "stopped", "deleted"].includes(info.status ?? "") || info.pauseError) {
+        throw new ConflictError(info.pauseError ?? `Sandbox is ${info.status}`);
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError(`Sandbox did not become ${status} within the wait timeout`);
+  }
   /**
    * Get metadata and status information about this sandbox.
    */
@@ -983,9 +989,9 @@ var Sandbox = class extends SandboxClient {
   fork(opts = {}) {
     return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
   }
-  /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
-  snapshot(name) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name });
+  /** Capture memory and workspace files. Disconnect active clients before capturing. */
+  snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5 });
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -994,13 +1000,45 @@ var Sandbox = class extends SandboxClient {
     return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
   static snapshots(projectId, opts) {
-    return new PlatformClient(opts ?? {}).get(`/api/projects/${projectId}/snapshots`);
+    return new PlatformClient(opts ?? {}).get(`/api/projects/${encodeURIComponent(projectId)}/snapshots`);
+  }
+  static getSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).get(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+  /** Start a sandbox from an available warm copy in the snapshot's project and region. */
   static async restore(snapshotId, opts) {
-    const result = await new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/fork`, { timeoutMs: opts?.timeoutMs ?? 0 });
+    const client = new PlatformClient(opts ?? {});
+    const snapshot = await this.getSnapshot(snapshotId, opts);
+    const result = await client.post("/api/sandboxes", {
+      snapshotId,
+      projectId: snapshot.projectId,
+      region: snapshot.region,
+      timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
+    });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });
   }
+  static setSnapshotWarmPool(snapshotId, poolSize, opts) {
+    return new PlatformClient(opts ?? {}).patch(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`, { poolSize });
+  }
+  /** Release idle warm copies; retain saved state and existing claimed sandboxes. */
+  static pauseSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/pause`, {});
+  }
+  /** Refill the configured warm pool without another capture. */
+  static resumeSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/resume`, {});
+  }
+  static async waitForSnapshot(snapshotId, opts) {
+    const deadline = Date.now() + (opts?.waitTimeoutMs ?? 9e5);
+    do {
+      const snapshot = await this.getSnapshot(snapshotId, opts);
+      if (snapshot.status === "ready") return snapshot;
+      if (["failed", "paused", "suspended"].includes(snapshot.status)) throw new ConflictError(snapshot.error ?? `Snapshot is ${snapshot.status}`);
+      if (Date.now() >= deadline) break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    } while (Date.now() < deadline);
+    throw new TimeoutError("Snapshot did not become ready within the wait timeout");
+  }
   static deleteSnapshot(snapshotId, opts) {
     return new PlatformClient(opts ?? {}).delete(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "TypeScript SDK for Lizard: Kubernetes sandboxes, code execution and cloud apps.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",