@lizard-build/sdk 0.1.58 → 0.1.60

package/README.md

@@ -61,7 +61,7 @@ if (result.exitCode !== 0) throw new Error(result.stderr)
 
 ## Desktop (computer use)
 
-The `desktop` template runs XFCE and Chromium you can watch in a browser and an agent can drive:
+The `desktop` template runs an Openbox desktop with Chromium, streamed to a browser over WebRTC (with noVNC as the fallback). You can watch it, and an agent can drive it:
 
 ```ts
 import { Sandbox } from '@lizard-build/sdk'
@@ -108,13 +108,14 @@ const sandbox = await CodeSandbox.create({ projectId: 'proj_123' });
 try {
   await sandbox.runCode('x = 21');
   const run = await sandbox.runCode('x * 2');
-  console.log(run.results[0].data); // "42"
+  const out = run.results[0];
+  if (out?.type === 'result') console.log(out.data); // "42"
 } finally {
   await sandbox.kill();
 }
 ```
 
-`language: 'bash'` (and `'javascript'` where `node` is installed; the `interpreter` template does not ship it) runs each call as a fresh process with no shared state.
+`language: 'bash'` and `language: 'javascript'` (the `interpreter` template ships Node 22) run each call as a fresh process with no shared state.
 
 ## Configuration
 
@@ -124,7 +125,7 @@ Pass `timeoutMs` to `create()` to set the sandbox lifetime. The default is five
 
 ## Runtime limits
 
-Each sandbox is a Firecracker microVM with its own kernel. Use volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available on Firecracker sandboxes yet, volumes cannot be resized yet, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
+Each sandbox is a Firecracker microVM with its own kernel. Use volumes mounted at `/workspace` to keep files after a sandbox ends. `pause()`/`resume()` keep memory and running processes; `snapshot()` is ready in about 2 s and `Sandbox.restore()` starts a copy in about 0.4 s; `fork()` clones a running sandbox. File watching and sandbox log streaming are not available on Firecracker sandboxes yet. Volumes can grow but not shrink, and a sandbox with a volume attached cannot be forked. See the [snapshot guide](../../docs/sandboxes.md#pause-resume-snapshots-and-fork).
 
 `getHost()` returns a hostname without `https://`; the port is private, so send `sandbox.accessToken` as the `X-Lizard-Access-Token` header (or use `exposePort()`, which also returns a browser `url` carrying the token). File writes accept text or bytes (binary is sent exactly); `readBytes()` supports binary downloads.
 

package/dist/index.d.mts

@@ -23,9 +23,10 @@ declare class PlatformClient {
     readonly config: ConnectionConfig;
     constructor(opts: ConnectionOpts);
     private json;
-    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete<T = void>(path: string, body?: unknown): Promise<T>;
@@ -144,7 +145,10 @@ declare class ProjectsAPI {
     }): Promise<Project[]>;
     /** Get a project by ID. */
     get(id: string): Promise<Project>;
-    /** Create a new project. */
+    /**
+     * Create a new project. A scoped key can create one only in a workspace it
+     * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+     */
     create(opts: CreateProjectOpts): Promise<Project>;
     /** Update a project's name. */
     update(id: string, opts: {
@@ -670,7 +674,7 @@ declare class Watcher {
  * State of a sandbox's desktop, and the URLs that stream it.
  *
  * **Both URLs are credentials.** The port is published on a public hostname, and each
- * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * URL carries the stream token and a password. Anyone holding `url` can see and
  * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
  * put them anywhere you would not put an API key.
  */
@@ -679,9 +683,9 @@ interface DesktopInfo {
     /** Screen width in pixels, or `null` when the desktop has never been started. */
     width: number | null;
     height: number | null;
-    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    /** Viewer page with full control (mouse and keyboard): WebRTC, with noVNC as the fallback. Treat like a credential. */
     url: string;
-    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    /** Viewer page that can only watch; enforced by the stream server in the sandbox, not the page. */
     viewOnlyUrl: string;
 }
 interface DesktopStartOpts {
@@ -701,8 +705,9 @@ interface ClickOpts {
 /**
  * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
  *
- * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
- * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ * Only the `desktop` template has one (Xvfb + Openbox + Chromium on `DISPLAY=:1`,
+ * streamed over WebRTC with noVNC as the fallback); on any other template the calls
+ * fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
  *
  * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
  * argument goes to the sandbox as an argv array and is never parsed by a shell, so
@@ -791,9 +796,9 @@ interface SandboxInfo {
     /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
     size?: 'small' | 'medium' | 'large' | null;
-    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (private snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -825,8 +830,8 @@ interface SandboxOpts extends ConnectionOpts {
     projectId?: string;
     template?: string;
     /**
-     * Create from a private saved snapshot. The sandbox runs on the machine the
-     * snapshot was captured on and is billed by measured usage; `size` is ignored.
+     * Create from a private saved snapshot. The sandbox runs at the source sandbox's
+     * size and is billed flat at that size; `size` is ignored.
      */
     snapshotId?: string;
     /**
@@ -1153,9 +1158,10 @@ declare class Sandbox extends SandboxClient {
      */
     exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
     /**
-     * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+     * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
      * microVM at this instant -- memory, running processes and files -- and is
-     * billed like its source. The source keeps running.
+     * billed like its source. The source keeps running. Each copy counts as a
+     * sandbox start, so the account's running-sandbox limit is the real cap.
      *
      * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
      * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1175,9 +1181,10 @@ declare class Sandbox extends SandboxClient {
     }): Promise<ForkResult<this>[]>;
     /**
      * Save this sandbox -- memory, running processes and files -- as a private
-     * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-     * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-     * keeps running. `poolSize` applies to container sandboxes only.
+     * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+     * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+     * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
@@ -1418,14 +1425,22 @@ declare class WorkspacesAPI {
      * project. A full key returns every workspace the account belongs to.
      */
     list(): Promise<Workspace[]>;
-    /** Create a workspace. The caller becomes its owner. */
+    /**
+     * Create a workspace. The caller becomes its owner.
+     *
+     * Needs a key with no scopes: a scoped key gets HTTP 403 with
+     * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+     */
     create(opts: CreateWorkspaceOpts): Promise<Workspace>;
     /**
      * Delete a workspace.
      *
-     * Empty-only by default — the server refuses while any project or sandbox remains,
-     * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-     * workspace and everything in it; that is irreversible.
+     * Empty-only by default — the server refuses while any project, sandbox or volume
+     * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+     * the workspace with its apps, addons and projects; that is irreversible. It does not
+     * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+     * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+     * volumes and snapshots first.
      */
     delete(id: string, opts?: {
         force?: boolean;
@@ -1840,9 +1855,9 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * **Firecracker volumes cannot be resized yet**: volumes created for the default
-     * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-     * Create the volume at the size you need, or copy the data to a new, larger one.
+     * A Firecracker volume (the default) can only grow. The change is in place and
+     * online: a sandbox with the volume attached keeps running and sees the new size.
+     * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
      *
      * On a container volume the change is in place and online: the size is a quota,
      * so no data is copied and a mounted sandbox sees the new size immediately. Both
@@ -1850,16 +1865,17 @@ declare class Volume {
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
-     * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+     * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+     * `volume_not_resizable` (an app's volume, not a sandbox volume),
      * `volume_resize_in_progress`, `volume_not_provisioned`,
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced`.
+     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+    /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -2152,7 +2168,7 @@ interface CreateContextOpts {
  * Limits, honestly:
  * - `javascript` (node) and `bash` run each call as a fresh process: no state
  *   carries over and `results` stays empty. `node` must be installed in the
- *   template; the `interpreter` template does not ship it.
+ *   template; the `interpreter` template ships Node 22.
  * - On a template without Jupyter (e.g. `base`), Python also runs as a fresh
  *   process per call.
  * - `stdout`/`stderr` are delivered in the chunks the kernel or process
@@ -2166,7 +2182,8 @@ interface CreateContextOpts {
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  * await sandbox.runCode('x = 21')
  * const run = await sandbox.runCode('x * 2')
- * console.log(run.results[0].data) // "42"
+ * const out = run.results[0]
+ * if (out?.type === 'result') console.log(out.data) // "42"
  * await sandbox.kill()
  * ```
  */

package/dist/index.d.ts

@@ -23,9 +23,10 @@ declare class PlatformClient {
     readonly config: ConnectionConfig;
     constructor(opts: ConnectionOpts);
     private json;
-    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete<T = void>(path: string, body?: unknown): Promise<T>;
@@ -144,7 +145,10 @@ declare class ProjectsAPI {
     }): Promise<Project[]>;
     /** Get a project by ID. */
     get(id: string): Promise<Project>;
-    /** Create a new project. */
+    /**
+     * Create a new project. A scoped key can create one only in a workspace it
+     * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+     */
     create(opts: CreateProjectOpts): Promise<Project>;
     /** Update a project's name. */
     update(id: string, opts: {
@@ -670,7 +674,7 @@ declare class Watcher {
  * State of a sandbox's desktop, and the URLs that stream it.
  *
  * **Both URLs are credentials.** The port is published on a public hostname, and each
- * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * URL carries the stream token and a password. Anyone holding `url` can see and
  * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
  * put them anywhere you would not put an API key.
  */
@@ -679,9 +683,9 @@ interface DesktopInfo {
     /** Screen width in pixels, or `null` when the desktop has never been started. */
     width: number | null;
     height: number | null;
-    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    /** Viewer page with full control (mouse and keyboard): WebRTC, with noVNC as the fallback. Treat like a credential. */
     url: string;
-    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    /** Viewer page that can only watch; enforced by the stream server in the sandbox, not the page. */
     viewOnlyUrl: string;
 }
 interface DesktopStartOpts {
@@ -701,8 +705,9 @@ interface ClickOpts {
 /**
  * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
  *
- * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
- * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ * Only the `desktop` template has one (Xvfb + Openbox + Chromium on `DISPLAY=:1`,
+ * streamed over WebRTC with noVNC as the fallback); on any other template the calls
+ * fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
  *
  * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
  * argument goes to the sandbox as an argv array and is never parsed by a shell, so
@@ -791,9 +796,9 @@ interface SandboxInfo {
     /** The sandbox runtime: `'firecracker'` (a microVM), `'container'`, or `null` when unknown. */
     runtime?: 'firecracker' | 'container' | null;
     pauseError?: string | null;
-    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox created from a private snapshot. */
+    /** Machine size (`'small' | 'medium' | 'large'`); may be `null` for a sandbox billed by measured usage, such as one restored from a container snapshot. */
     size?: 'small' | 'medium' | 'large' | null;
-    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (private snapshot). */
+    /** Flat hourly price in USD for `size`, billed per second while running; may be `null` when billed by measured usage (a container snapshot). */
     pricePerHour?: number | null;
     cpus?: number;
     memoryMb?: number;
@@ -825,8 +830,8 @@ interface SandboxOpts extends ConnectionOpts {
     projectId?: string;
     template?: string;
     /**
-     * Create from a private saved snapshot. The sandbox runs on the machine the
-     * snapshot was captured on and is billed by measured usage; `size` is ignored.
+     * Create from a private saved snapshot. The sandbox runs at the source sandbox's
+     * size and is billed flat at that size; `size` is ignored.
      */
     snapshotId?: string;
     /**
@@ -1153,9 +1158,10 @@ declare class Sandbox extends SandboxClient {
      */
     exposePort(port: number, opts?: ConnectionOpts): Promise<ExposedPort>;
     /**
-     * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+     * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
      * microVM at this instant -- memory, running processes and files -- and is
-     * billed like its source. The source keeps running.
+     * billed like its source. The source keeps running. Each copy counts as a
+     * sandbox start, so the account's running-sandbox limit is the real cap.
      *
      * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
      * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1175,9 +1181,10 @@ declare class Sandbox extends SandboxClient {
     }): Promise<ForkResult<this>[]>;
     /**
      * Save this sandbox -- memory, running processes and files -- as a private
-     * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-     * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-     * keeps running. `poolSize` applies to container sandboxes only.
+     * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+     * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+     * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
@@ -1418,14 +1425,22 @@ declare class WorkspacesAPI {
      * project. A full key returns every workspace the account belongs to.
      */
     list(): Promise<Workspace[]>;
-    /** Create a workspace. The caller becomes its owner. */
+    /**
+     * Create a workspace. The caller becomes its owner.
+     *
+     * Needs a key with no scopes: a scoped key gets HTTP 403 with
+     * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+     */
     create(opts: CreateWorkspaceOpts): Promise<Workspace>;
     /**
      * Delete a workspace.
      *
-     * Empty-only by default — the server refuses while any project or sandbox remains,
-     * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-     * workspace and everything in it; that is irreversible.
+     * Empty-only by default — the server refuses while any project, sandbox or volume
+     * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+     * the workspace with its apps, addons and projects; that is irreversible. It does not
+     * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+     * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+     * volumes and snapshots first.
      */
     delete(id: string, opts?: {
         force?: boolean;
@@ -1840,9 +1855,9 @@ declare class Volume {
     /**
      * Resize a volume, by name or by id, to `sizeGb`.
      *
-     * **Firecracker volumes cannot be resized yet**: volumes created for the default
-     * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-     * Create the volume at the size you need, or copy the data to a new, larger one.
+     * A Firecracker volume (the default) can only grow. The change is in place and
+     * online: a sandbox with the volume attached keeps running and sees the new size.
+     * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
      *
      * On a container volume the change is in place and online: the size is a quota,
      * so no data is copied and a mounted sandbox sees the new size immediately. Both
@@ -1850,16 +1865,17 @@ declare class Volume {
      * new size free — otherwise it throws `ConflictError` with
      * `code: 'volume_too_full_to_shrink'`.
      *
-     * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+     * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+     * `volume_not_resizable` (an app's volume, not a sandbox volume),
      * `volume_resize_in_progress`, `volume_not_provisioned`,
      * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
      * the size is left unchanged).
      *
-     * @returns The volume's updated info, including `sizeEnforced`.
+     * @returns The volume's updated info, including `sizeEnforced` for a container volume.
      */
     static resize(projectId: string, nameOrId: string, sizeGb: number, opts?: ConnectionOpts): Promise<VolumeInfo>;
     getInfo(projectId: string): Promise<VolumeInfo>;
-    /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+    /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
     resize(projectId: string, sizeGb: number): Promise<VolumeInfo>;
     delete(projectId: string): Promise<void>;
 }
@@ -2152,7 +2168,7 @@ interface CreateContextOpts {
  * Limits, honestly:
  * - `javascript` (node) and `bash` run each call as a fresh process: no state
  *   carries over and `results` stays empty. `node` must be installed in the
- *   template; the `interpreter` template does not ship it.
+ *   template; the `interpreter` template ships Node 22.
  * - On a template without Jupyter (e.g. `base`), Python also runs as a fresh
  *   process per call.
  * - `stdout`/`stderr` are delivered in the chunks the kernel or process
@@ -2166,7 +2182,8 @@ interface CreateContextOpts {
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  * await sandbox.runCode('x = 21')
  * const run = await sandbox.runCode('x * 2')
- * console.log(run.results[0].data) // "42"
+ * const out = run.results[0]
+ * if (out?.type === 'result') console.log(out.data) // "42"
  * await sandbox.kill()
  * ```
  */

package/dist/index.js

@@ -176,19 +176,20 @@ var PlatformClient = class {
     const text = await res.text();
     return text ? JSON.parse(text) : void 0;
   }
-  request(method, path, body) {
+  /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+  request(method, path, body, timeoutMs) {
     return fetch(`${this.config.apiUrl}${path}`, {
       method,
       headers: this.config.headers,
       body: body === void 0 ? void 0 : JSON.stringify(body),
-      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+      signal: AbortSignal.timeout(Math.max(this.config.requestTimeoutMs, timeoutMs ?? 0))
     }).then((res) => this.json(res));
   }
   get(path) {
     return this.request("GET", path);
   }
-  post(path, body) {
-    return this.request("POST", path, body);
+  post(path, body, timeoutMs) {
+    return this.request("POST", path, body, timeoutMs);
   }
   put(path, body) {
     return this.request("PUT", path, body);
@@ -1126,6 +1127,7 @@ var SandboxClient = class {
 };
 
 // src/sandbox/index.ts
+var SNAPSHOT_TIMEOUT_MS = 11 * 6e4;
 var Sandbox = class extends SandboxClient {
   constructor(opts) {
     super();
@@ -1256,9 +1258,10 @@ var Sandbox = class extends SandboxClient {
     return exposed;
   }
   /**
-   * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+   * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
    * microVM at this instant -- memory, running processes and files -- and is
-   * billed like its source. The source keeps running.
+   * billed like its source. The source keeps running. Each copy counts as a
+   * sandbox start, so the account's running-sandbox limit is the real cap.
    *
    * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
    * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1286,12 +1289,13 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Save this sandbox -- memory, running processes and files -- as a private
-   * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-   * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-   * keeps running. `poolSize` applies to container sandboxes only.
+   * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+   * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+   * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope });
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1378,7 +1382,10 @@ var ProjectsAPI = class {
   get(id) {
     return this.client.get(`/api/projects/${id}`);
   }
-  /** Create a new project. */
+  /**
+   * Create a new project. A scoped key can create one only in a workspace it
+   * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+   */
   create(opts) {
     return this.client.post("/api/projects", opts);
   }
@@ -1647,16 +1654,24 @@ var WorkspacesAPI = class {
   list() {
     return this.client.get("/api/workspaces");
   }
-  /** Create a workspace. The caller becomes its owner. */
+  /**
+   * Create a workspace. The caller becomes its owner.
+   *
+   * Needs a key with no scopes: a scoped key gets HTTP 403 with
+   * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+   */
   create(opts) {
     return this.client.post("/api/workspaces", opts);
   }
   /**
    * Delete a workspace.
    *
-   * Empty-only by default — the server refuses while any project or sandbox remains,
-   * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-   * workspace and everything in it; that is irreversible.
+   * Empty-only by default — the server refuses while any project, sandbox or volume
+   * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+   * the workspace with its apps, addons and projects; that is irreversible. It does not
+   * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+   * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+   * volumes and snapshots first.
    */
   delete(id, opts) {
     const qs = opts?.force ? "" : "?requireEmpty=true";
@@ -1850,9 +1865,9 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * **Firecracker volumes cannot be resized yet**: volumes created for the default
-   * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-   * Create the volume at the size you need, or copy the data to a new, larger one.
+   * A Firecracker volume (the default) can only grow. The change is in place and
+   * online: a sandbox with the volume attached keeps running and sees the new size.
+   * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
    *
    * On a container volume the change is in place and online: the size is a quota,
    * so no data is copied and a mounted sandbox sees the new size immediately. Both
@@ -1860,12 +1875,13 @@ var Volume = class _Volume {
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
-   * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+   * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+   * `volume_not_resizable` (an app's volume, not a sandbox volume),
    * `volume_resize_in_progress`, `volume_not_provisioned`,
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced`.
+   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);
@@ -1884,7 +1900,7 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
-  /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+  /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
   async resize(projectId, sizeGb) {
     return _Volume.resize(projectId, this.volumeId, sizeGb, {
       apiKey: this.config.apiKey,

package/dist/index.mjs

@@ -123,19 +123,20 @@ var PlatformClient = class {
     const text = await res.text();
     return text ? JSON.parse(text) : void 0;
   }
-  request(method, path, body) {
+  /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+  request(method, path, body, timeoutMs) {
     return fetch(`${this.config.apiUrl}${path}`, {
       method,
       headers: this.config.headers,
       body: body === void 0 ? void 0 : JSON.stringify(body),
-      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+      signal: AbortSignal.timeout(Math.max(this.config.requestTimeoutMs, timeoutMs ?? 0))
     }).then((res) => this.json(res));
   }
   get(path) {
     return this.request("GET", path);
   }
-  post(path, body) {
-    return this.request("POST", path, body);
+  post(path, body, timeoutMs) {
+    return this.request("POST", path, body, timeoutMs);
   }
   put(path, body) {
     return this.request("PUT", path, body);
@@ -1073,6 +1074,7 @@ var SandboxClient = class {
 };
 
 // src/sandbox/index.ts
+var SNAPSHOT_TIMEOUT_MS = 11 * 6e4;
 var Sandbox = class extends SandboxClient {
   constructor(opts) {
     super();
@@ -1203,9 +1205,10 @@ var Sandbox = class extends SandboxClient {
     return exposed;
   }
   /**
-   * Clone this running sandbox `count` times (1-10). Each fork is a copy of the
+   * Clone this running sandbox `count` times (1-100). Each fork is a copy of the
    * microVM at this instant -- memory, running processes and files -- and is
-   * billed like its source. The source keeps running.
+   * billed like its source. The source keeps running. Each copy counts as a
+   * sandbox start, so the account's running-sandbox limit is the real cap.
    *
    * Returns one entry per requested fork, in order: `{ sandbox, info }`, or
    * `{ error }` for a copy that could not be made (e.g. the account's sandbox
@@ -1233,12 +1236,13 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Save this sandbox -- memory, running processes and files -- as a private
-   * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-   * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-   * keeps running. `poolSize` applies to container sandboxes only.
+   * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+   * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+   * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope });
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1325,7 +1329,10 @@ var ProjectsAPI = class {
   get(id) {
     return this.client.get(`/api/projects/${id}`);
   }
-  /** Create a new project. */
+  /**
+   * Create a new project. A scoped key can create one only in a workspace it
+   * covers; anywhere else it gets HTTP 403 with `code: 'PROJECT_OUT_OF_SCOPE'`.
+   */
   create(opts) {
     return this.client.post("/api/projects", opts);
   }
@@ -1594,16 +1601,24 @@ var WorkspacesAPI = class {
   list() {
     return this.client.get("/api/workspaces");
   }
-  /** Create a workspace. The caller becomes its owner. */
+  /**
+   * Create a workspace. The caller becomes its owner.
+   *
+   * Needs a key with no scopes: a scoped key gets HTTP 403 with
+   * `code: 'ACCOUNT_SCOPE_REQUIRED'`.
+   */
   create(opts) {
     return this.client.post("/api/workspaces", opts);
   }
   /**
    * Delete a workspace.
    *
-   * Empty-only by default — the server refuses while any project or sandbox remains,
-   * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
-   * workspace and everything in it; that is irreversible.
+   * Empty-only by default — the server refuses while any project, sandbox or volume
+   * remains, so this cannot quietly destroy a user's work. `{ force: true }` deletes
+   * the workspace with its apps, addons and projects; that is irreversible. It does not
+   * delete sandboxes, sandbox volumes or snapshots: a running sandbox keeps running with
+   * no workspace left to find it in. Kill the workspace's sandboxes and delete its
+   * volumes and snapshots first.
    */
   delete(id, opts) {
     const qs = opts?.force ? "" : "?requireEmpty=true";
@@ -1797,9 +1812,9 @@ var Volume = class _Volume {
   /**
    * Resize a volume, by name or by id, to `sizeGb`.
    *
-   * **Firecracker volumes cannot be resized yet**: volumes created for the default
-   * Firecracker sandboxes throw `LizardError` (400) with `code: 'volume_not_resizable'`.
-   * Create the volume at the size you need, or copy the data to a new, larger one.
+   * A Firecracker volume (the default) can only grow. The change is in place and
+   * online: a sandbox with the volume attached keeps running and sees the new size.
+   * A smaller size throws `LizardError` (400) with `code: 'volume_shrink_unsupported'`.
    *
    * On a container volume the change is in place and online: the size is a quota,
    * so no data is copied and a mounted sandbox sees the new size immediately. Both
@@ -1807,12 +1822,13 @@ var Volume = class _Volume {
    * new size free — otherwise it throws `ConflictError` with
    * `code: 'volume_too_full_to_shrink'`.
    *
-   * Other failures carry a `code` too: `invalid_volume_size`, `volume_not_resizable`,
+   * Other failures carry a `code` too: `invalid_volume_size`, `volume_too_large`,
+   * `volume_not_resizable` (an app's volume, not a sandbox volume),
    * `volume_resize_in_progress`, `volume_not_provisioned`,
    * `volume_capacity_unavailable`, and `volume_resize_timeout` (a `TimeoutError`;
    * the size is left unchanged).
    *
-   * @returns The volume's updated info, including `sizeEnforced`.
+   * @returns The volume's updated info, including `sizeEnforced` for a container volume.
    */
   static async resize(projectId, nameOrId, sizeGb, opts) {
     const config = new ConnectionConfig(opts);
@@ -1831,7 +1847,7 @@ var Volume = class _Volume {
     if (!res.ok) await handleApiError(res);
     return res.json();
   }
-  /** Resize this volume — see the static {@link Volume.resize} (not supported for Firecracker volumes yet). */
+  /** Resize this volume — see the static {@link Volume.resize} (a Firecracker volume can only grow). */
   async resize(projectId, sizeGb) {
     return _Volume.resize(projectId, this.volumeId, sizeGb, {
       apiKey: this.config.apiKey,

package/package.json

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