withruntime 0.11.1 → 0.12.0

package/dist/sandbox.js

@@ -1,13 +1,13 @@
-import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
+import { STREAMED_EXEC_TIMEOUT_MS } from "./api-defaults.js";
 import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
-import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
-import { Transport } from "./transport.js";
+import { Transport, timeoutSignal } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
 import { pause } from "./wait.js";
-/** How long snapshot() waits, pause and capture together, unless told. */
-const SNAPSHOT_DEADLINE_MS = 10 * 60_000;
+import { Machine, machinePage, requestOnly } from "./machine.js";
+/** Sandboxes, as a product of the machine engine (machine.ts). */
+export const SANDBOXES = { plural: "sandboxes", noun: "Sandbox" };
 const CHUNK = 1_048_576;
 /** Chunks of a large write in flight at once. Each chunk's reply waits on the
  * API and the guest, and the link idles while every chunk in flight waits:
@@ -20,7 +20,7 @@ const enc = (id) => encodeURIComponent(id);
 function requestScope(options) {
     const deadline = options.timeoutMs === undefined || options.timeoutMs === 0
         ? undefined
-        : AbortSignal.timeout(options.timeoutMs);
+        : timeoutSignal(options.timeoutMs);
     const signal = deadline && options.signal
         ? AbortSignal.any([deadline, options.signal])
         : (deadline ?? options.signal);
@@ -59,15 +59,6 @@ function requestScope(options) {
     };
     return { request, check, wait };
 }
-/** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
- * `runtime.sandboxes.delete(id)`. */
-export function deleteSandbox(t, id, options = {}) {
-    return t.json({
-        method: "DELETE",
-        path: `/v1/sandboxes/${enc(id)}`,
-        ...options,
-    });
-}
 /* Web APIs only, so the sandbox's commands, processes and files work in a
    browser with a session token (Sandbox.fromSession): no Buffer, no
    node:crypto. */
@@ -97,26 +88,21 @@ function commandBody(command, options) {
     };
 }
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
-export class Sandbox {
-    #info;
-    #keepAlive;
+export class Sandbox extends Machine {
     #t;
     files;
     processes;
     /** Short-lived tokens that let a browser reach this sandbox directly. */
     sessions;
     constructor(transport, info) {
+        super(SANDBOXES, transport, info);
         this.#t = transport;
-        this.#info = info;
         this.files = new Files(transport, info.id);
         this.processes = new Processes(transport, info.id);
         this.sessions = new SandboxSessions(transport, info.id);
         for (const [name, make] of sandboxFactories())
             Object.defineProperty(this, name, { value: make(transport, this), enumerable: false });
     }
-    get id() {
-        return this.#info.id;
-    }
     /** A sandbox reached with a session token instead of an API key, for code in
      * a browser: commands and their streams, processes, files and previews of
      * this one sandbox. Makes no call; `info` holds only the id until
@@ -141,41 +127,6 @@ export class Sandbox {
         });
         return new Sandbox(transport, { id: session.sandboxId });
     }
-    /** The API's latest answer. `start`, the report of an image's start
-     * command, is the create's alone: the API keeps no record of it, so a
-     * later read of this sandbox keeps it here. */
-    #keep(info) {
-        const start = this.#info?.start;
-        this.#info = info.start === undefined && start !== undefined ? { ...info, start } : info;
-    }
-    /** What the API last said about this sandbox. `refresh()` asks again. */
-    get info() {
-        return this.#info;
-    }
-    get state() {
-        return this.#info.state;
-    }
-    async refresh(options = {}) {
-        this.#keep(await this.#t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${enc(this.id)}`,
-            ...options,
-        }));
-        return this;
-    }
-    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
-    async waitFor(state, options = {}) {
-        this.#keep(await this.#t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${enc(this.id)}`,
-            query: {
-                waitFor: state,
-                timeoutSeconds: options.timeoutSeconds ?? WAIT_FOR_TIMEOUT_SECONDS,
-            },
-            ...options,
-        }));
-        return this;
-    }
     /** Runs a command and returns its exit code and output. A string runs under
      * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
      * streams as it happens. A timeout is a result (timedOut: true, the output so
@@ -220,6 +171,7 @@ export class Sandbox {
                 ...truncation(dropped),
                 ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
                 ...(processId ? { processId } : {}),
+                ...(exit?.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
             };
         }
         if (options.check && (result.exitCode !== 0 || result.timedOut))
@@ -245,8 +197,8 @@ export class Sandbox {
                 code: "cancelled",
                 status: 0,
                 hint: stopped
-                    ? `See what it printed: runtime sandbox logs ${id}`
-                    : `Stop it: runtime sandbox kill ${id}, or sandbox.processes.get("${processId}") and kill().`,
+                    ? `See what it printed: runtime sandboxes logs ${id}`
+                    : `Stop it: runtime sandboxes kill ${id}, or sandbox.processes.get("${processId}") and kill().`,
                 details: { sandboxId: this.id, processId, stopped },
                 cause: error,
             });
@@ -257,7 +209,7 @@ export class Sandbox {
             message: `Lost the output of process ${processId}; the command may still be running.`,
             code: "connection_error",
             status: 0,
-            hint: `Follow it: runtime sandbox logs ${id} -f (sandbox.processes.get("${processId}")), or stop it: runtime sandbox kill ${id}.`,
+            hint: `Follow it: runtime sandboxes logs ${id} -f (sandbox.processes.get("${processId}")), or stop it: runtime sandboxes kill ${id}.`,
             details: { sandboxId: this.id, processId },
             cause: error,
         });
@@ -368,275 +320,6 @@ export class Sandbox {
             throw error;
         }
     }
-    async stop(options = {}) {
-        this.#keepAlive?.();
-        return this.#lifecycle("stop", options);
-    }
-    async pause(options = {}) {
-        return this.#lifecycle("pause", options);
-    }
-    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
-     * and paused memory, revokes its previews and ports, and removes it from
-     * lists. Its snapshots, usage and audit entries stay. Deleting it again
-     * answers the same. */
-    async delete(options = {}) {
-        this.#keepAlive?.();
-        return deleteSandbox(this.#t, this.id, options);
-    }
-    /** Carries on a paused sandbox; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
-    async wake(options = {}) {
-        const { timeoutSeconds, ...rest } = options;
-        try {
-            return await this.#lifecycle("wake", rest, timeoutSeconds === undefined ? {} : { timeoutSeconds });
-        }
-        catch (error) {
-            // Waking one that is already awake is done, not a mistake. With a new
-            // lease asked for, the refusal stands: it was not given.
-            if (!(error instanceof RuntimeError) || error.code !== "not_paused" || timeoutSeconds)
-                throw error;
-            await this.refresh(requestOnly(rest));
-            if (this.state !== "running" && this.state !== "starting")
-                throw error;
-            return this;
-        }
-    }
-    /** More time before its time limit ends (at most an hour ahead of now). A
-     * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
-    async extend(seconds, options = {}) {
-        return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
-    }
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
-    async update(settings, options = {}) {
-        return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
-    }
-    /** Moves it to another image (id, name, name:tag or name@version), keeping
-     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
-     * volumes, environment, name and previews. Its processes restart, and
-     * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost; snapshot it first to keep everything. A running sandbox is paused
-     * first. A switch that fails is undone (`switch_undone`), the sandbox on
-     * its old image with nothing lost. Charged as a wake. `keep` is optional:
-     * "workspace" is the only value, and it is sent either way, so an API from
-     * before it was optional accepts the call too. */
-    async switchImage(image, options = {}) {
-        const { keep = "workspace", ...rest } = options;
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
-            body: { image, keep },
-            // A pause, two boots and the copy between them.
-            wait: 120,
-            ...requestOnly(rest),
-        }));
-        return this;
-    }
-    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
-     * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
-     * persistent, and comes back running at the new size on the same server; a
-     * paused or stopped one is started. Memory bills on the new size from then.
-     * Refused, with nothing changed, when the server has no room
-     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
-    async resize(size, options = {}) {
-        const { restart = true, ...rest } = options;
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:resize`,
-            body: { ...size, restart },
-            // A pause or stop and a cold boot.
-            wait: 120,
-            ...requestOnly(rest),
-        }));
-        return this;
-    }
-    /** Keeps a sandbox with a time limit running past it, in the background,
-     * until stop() or the returned function ends it: every `everySeconds` (60)
-     * it extends the limit so that `marginSeconds` (600) remain, never more
-     * than the hour ahead the API allows. A sandbox with no time limit
-     * (`endsAt` null) needs none, and is only watched. Running time is billed
-     * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
-     * Node or Bun process alive by itself. */
-    keepAlive(options = {}) {
-        this.#keepAlive?.();
-        const every = Math.max(10, options.everySeconds ?? 60) * 1000;
-        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? KEEP_ALIVE_MARGIN_SECONDS));
-        let ended = false;
-        let timer;
-        const end = () => {
-            ended = true;
-            if (timer)
-                clearTimeout(timer);
-            if (this.#keepAlive === end)
-                this.#keepAlive = undefined;
-        };
-        const tick = async () => {
-            if (ended)
-                return;
-            try {
-                await this.refresh();
-                if (this.state === "stopped" || this.state === "stopping")
-                    return end();
-                // No time limit: nothing to extend (an older server sends no endsAt).
-                if (this.state === "running" && this.info.endsAt !== null) {
-                    const left = (Date.parse(this.info.endsAt ?? this.info.expiresAt) - Date.now()) / 1000;
-                    const need = Math.ceil(margin - left);
-                    if (need >= 1)
-                        await this.extend(Math.min(3600, need));
-                }
-            }
-            catch (error) {
-                options.onError?.(error);
-            }
-            if (ended)
-                return;
-            timer = setTimeout(() => void tick(), every);
-            timer.unref?.();
-        };
-        this.#keepAlive = end;
-        void tick();
-        return end;
-    }
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    async setRetention(days, options = {}) {
-        return this.#lifecycle("retention", { ...options, wait: false }, { days });
-    }
-    /** Keeps this sandbox's whole machine (files, memory, running processes) as
-     * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. Past
-     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
-     * the error names the snapshot. */
-    async snapshot(options = {}) {
-        const { idempotencyKey, signal, timeoutMs, ...body } = options;
-        if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
-            throw new TypeError("Snapshot mode must be memory or disk.");
-        signal?.throwIfAborted();
-        // One minute, whatever `timeoutMs` said, was too short: pausing a busy
-        // 16 vCPU, 32 GiB sandbox writes its memory out first (4 October 2026).
-        const until = performance.now() + (timeoutMs && timeoutMs > 0 ? timeoutMs : SNAPSHOT_DEADLINE_MS);
-        let running = false;
-        /** The capture in progress, once the server has one. */
-        let capturing;
-        let late = false;
-        const request = () => {
-            signal?.throwIfAborted();
-            const left = Math.ceil(until - performance.now());
-            if (left <= 0 && capturing) {
-                late = true;
-                throw new RuntimeError({
-                    code: "snapshot_timeout",
-                    status: 0,
-                    message: `Snapshot ${capturing} was still capturing at the deadline.${running ? " The sandbox stays paused until it ends: waking it now would fail the capture." : ""}`,
-                    hint: `Wait until runtime.snapshots.get("${capturing}") is ready${running ? ", then wake the sandbox" : ""}, or pass a longer timeoutMs.`,
-                    details: { snapshotId: capturing, sourceSandboxId: this.id },
-                });
-            }
-            if (left <= 0)
-                throw new RuntimeError({
-                    code: "snapshot_timeout",
-                    status: 0,
-                    message: "Snapshot capture ran past its deadline.",
-                });
-            return { ...(signal ? { signal } : {}), timeoutMs: left };
-        };
-        await this.refresh(request());
-        // Straight after a fork or a wake the sandbox is still `resuming`, and
-        // after a pause still `pausing`: wait for where it is going, or a
-        // snapshot of it is refused as not paused (user lane, 23 September 2026).
-        if (this.state === "resuming" || this.state === "starting")
-            await this.waitFor("running", request());
-        else if (this.state === "pausing")
-            await this.waitFor("paused", request());
-        running = this.state === "running";
-        // Check before entering cleanup: an abort during refresh must not pause or wake.
-        const pauseOptions = running ? request() : undefined;
-        let captured;
-        let primary;
-        let failed = false;
-        try {
-            if (running)
-                await this.pause(pauseOptions);
-            let snapshot = await this.#t.json({
-                method: "POST",
-                path: `/v1/sandboxes/${enc(this.id)}:snapshot`,
-                body,
-                wait: 10,
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-                ...request(),
-            });
-            captured = snapshot;
-            // Prefer: wait is bounded on the server. A capture still in progress
-            // must keep its source paused, or the worker refuses it after we wake.
-            while (snapshot.state === "capturing") {
-                capturing = snapshot.id;
-                request();
-                await new Promise((resolve) => setTimeout(resolve, 200));
-                snapshot = await this.#t.json({
-                    method: "GET",
-                    path: `/v1/snapshots/${enc(snapshot.id)}`,
-                    ...request(),
-                });
-            }
-            if (snapshot.state !== "ready")
-                throw new RuntimeError({
-                    code: "snapshot_failed",
-                    status: 409,
-                    message: snapshot.error ?? `Snapshot capture ended in state ${snapshot.state}.`,
-                    details: { snapshotId: snapshot.id },
-                });
-            if (body.mode === "disk" && snapshot.mode !== "disk")
-                throw new RuntimeError({
-                    code: "snapshot_mode_mismatch",
-                    status: 409,
-                    message: "The server did not confirm a disk-only snapshot.",
-                    details: { snapshotId: snapshot.id },
-                });
-            captured = snapshot;
-        }
-        catch (error) {
-            failed = true;
-            primary = error;
-            // A request cut off by the deadline mid-capture is late all the same.
-            if (capturing && performance.now() >= until)
-                late = true;
-        }
-        // A capture still running needs its source paused: the worker fails one
-        // whose source woke. The timeout says so and leaves the wake to the caller.
-        if (running && !late) {
-            try {
-                await this.wake();
-            }
-            catch (wakeError) {
-                const recovery = {
-                    ...(captured ? { snapshotId: captured.id } : {}),
-                    sourceSandboxId: this.id,
-                    sourceWakeError: {
-                        ...(wakeError instanceof RuntimeError ? { code: wakeError.code } : {}),
-                        message: wakeError instanceof Error ? wakeError.message : String(wakeError),
-                    },
-                };
-                const reported = failed ? primary : wakeError;
-                if (reported instanceof Error && Object.isExtensible(reported)) {
-                    if (reported instanceof RuntimeError)
-                        Object.assign(reported, { details: { ...reported.details, ...recovery } });
-                    else
-                        Object.assign(reported, recovery);
-                }
-                if (!failed)
-                    throw wakeError;
-            }
-        }
-        if (failed)
-            throw primary;
-        return captured;
-    }
     async fork(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
         const reply = await this.#t.json({
@@ -649,29 +332,6 @@ export class Sandbox {
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
         return options.count === undefined ? sandboxes[0] : sandboxes;
     }
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    async restart(options = {}) {
-        return this.#lifecycle("restart", options);
-    }
-    async #lifecycle(verb, options, body = {}) {
-        this.#keep(await this.#t.json({
-            method: "POST",
-            path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
-            body,
-            wait: options.wait === false ? 0 : 60,
-            ...requestOnly(options),
-        }));
-        return this;
-    }
-    async [Symbol.asyncDispose]() {
-        this.#keepAlive?.();
-        if (this.#info.state === "stopped")
-            return;
-        await this.stop({ wait: false }).catch(() => undefined);
-    }
-    toJSON() {
-        return this.#info;
-    }
 }
 /** Where a reader of a process's output is, in bytes of stdout and stderr
  * together. Output it did not receive, named by the server or not, becomes a
@@ -747,15 +407,6 @@ function pick(options) {
         ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
     };
 }
-/** Any other call's request options, as the caller gave them: `timeoutMs` is
- * the call's whole deadline, and 0 turns it off. */
-function requestOnly(options) {
-    return {
-        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
-        ...(options.signal ? { signal: options.signal } : {}),
-        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
-    };
-}
 /** Sessions: a token your backend makes and hands to your own frontend, which
  * then runs commands, reads and writes files and reaches previews in this one
  * sandbox directly, without proxying through your servers. A session cannot
@@ -894,7 +545,7 @@ export class Processes {
                         message: `Lost the output stream of process ${processId} for ${FOLLOW_OUTAGE_MS / 60_000} minutes; the command may still be running.`,
                         code: "connection_error",
                         status: 0,
-                        hint: `Follow it again: runtime sandbox logs ${this.sandboxId} ${processId} -f`,
+                        hint: `Follow it again: runtime sandboxes logs ${this.sandboxId} ${processId} -f`,
                         details: { sandboxId: this.sandboxId, processId },
                         cause: failure,
                     });
@@ -905,7 +556,7 @@ export class Processes {
                     message: `The output stream of process ${processId} keeps closing before it ends.`,
                     code: "connection_error",
                     status: 0,
-                    hint: `Read what it printed so far: runtime sandbox logs ${this.sandboxId} ${processId}`,
+                    hint: `Read what it printed so far: runtime sandboxes logs ${this.sandboxId} ${processId}`,
                     details: { sandboxId: this.sandboxId, processId },
                 });
         }
@@ -997,6 +648,7 @@ export class Process {
                 ...this.info,
                 state: exit.state,
                 exitCode: exit.exitCode,
+                ...(exit.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
             };
         return {
             exitCode: exit?.exitCode ?? null,
@@ -1004,6 +656,7 @@ export class Process {
             timedOut: exit?.timedOut ?? false,
             ...truncation(dropped),
             processId: this.id,
+            ...(exit?.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
         };
     }
     /** Sends input. Offsets protect transport retries; signal and timeoutMs cover
@@ -1618,9 +1271,11 @@ export class Files {
             const data = await readFile(localPath);
             const mode = info.mode & 0o777;
             await this.write(remotePath, data, { mode }).catch(async (error) => {
-                // A missing parent is made, as a directory upload makes its own.
+                // Make a missing parent, but keep errors about the sandbox or upload.
                 const parent = remotePath.slice(0, remotePath.lastIndexOf("/"));
-                if (!(error instanceof NotFoundError) || !parent)
+                if (!(error instanceof NotFoundError) ||
+                    (error.code !== "file_not_found" && error.code !== "path_not_found") ||
+                    !parent)
                     throw error;
                 await this.mkdir(parent, { parents: true });
                 await this.write(remotePath, data, { mode });
@@ -1752,11 +1407,7 @@ export class Files {
         }
     }
 }
+/** One page of `runtime.sandboxes.list()`, and the pages after it. */
 export function sandboxPage(t, body, query, options = {}) {
-    return new Page(body.data.map((info) => new Sandbox(t, info)), body.nextCursor, async (cursor) => sandboxPage(t, await t.json({
-        method: "GET",
-        path: "/v1/sandboxes",
-        query: Object.assign({}, query, { cursor }),
-        ...options,
-    }), query, options));
+    return machinePage(SANDBOXES, t, (transport, info) => new Sandbox(transport, info), body, query, options);
 }

package/dist/sandboxes/index.d.ts

@@ -0,0 +1,11 @@
+/** `withruntime/sandboxes`: Sandboxes alone. Linux microVMs: create, find and list sandboxes.
+ *
+ *   import { sandboxes } from "withruntime/sandboxes";
+ *   const client = sandboxes(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export { Sandbox } from "../index.js";
+export { Sandboxes } from "../client.js";
+export type * from "../types.js";
+/** `runtime.sandboxes` of a client made with `options`. */
+export declare function sandboxes(options?: RuntimeOptions): Runtime["sandboxes"];

package/dist/sandboxes/index.js

@@ -0,0 +1,12 @@
+/** `withruntime/sandboxes`: Sandboxes alone. Linux microVMs: create, find and list sandboxes.
+ *
+ *   import { sandboxes } from "withruntime/sandboxes";
+ *   const client = sandboxes(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+export { Sandbox } from "../index.js";
+export { Sandboxes } from "../client.js";
+/** `runtime.sandboxes` of a client made with `options`. */
+export function sandboxes(options) {
+    return new Runtime(options).sandboxes;
+}

package/dist/snapshots/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/snapshots`: Snapshots alone. Saved sandboxes, disk and memory, to start or fork from.
+ *
+ *   import { snapshots } from "withruntime/snapshots";
+ *   const client = snapshots(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export { Snapshots, type Snapshot, type SnapshotOptions } from "../snapshots.js";
+/** `runtime.snapshots` of a client made with `options`. */
+export declare function snapshots(options?: RuntimeOptions): Runtime["snapshots"];

package/dist/snapshots/index.js

@@ -0,0 +1,11 @@
+/** `withruntime/snapshots`: Snapshots alone. Saved sandboxes, disk and memory, to start or fork from.
+ *
+ *   import { snapshots } from "withruntime/snapshots";
+ *   const client = snapshots(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+export { Snapshots } from "../snapshots.js";
+/** `runtime.snapshots` of a client made with `options`. */
+export function snapshots(options) {
+    return new Runtime(options).snapshots;
+}

package/dist/snapshots.d.ts

@@ -17,7 +17,8 @@ export type Snapshot = {
         diskMiB: number;
         memoryGuarantee: string;
     };
-    retentionDays: number;
+    /** Null: kept while your account has credit, up to a year from when it was taken. */
+    retentionDays: number | null;
     /** True while raw fork memory awaits verified compression. The snapshot
      * remains ready for starts on its current host, with no storage charge or
      * off-host copy until final publication. Absent on older servers. */
@@ -39,7 +40,8 @@ export type Snapshot = {
     error: string | null;
     createdAt: string;
     readyAt: string | null;
-    expiresAt: string;
+    /** Null while it is kept as long as your account has credit. */
+    expiresAt: string | null;
     [key: string]: unknown;
 };
 export type SnapshotOptions = {
@@ -47,7 +49,8 @@ export type SnapshotOptions = {
     mode?: "memory" | "disk";
     name?: string;
     labels?: Record<string, string>;
-    retentionDays?: number;
+    /** Days, or null to keep it while your account has credit. */
+    retentionDays?: number | null;
 };
 /** `runtime.snapshots`. Take one with `sbx.snapshot()`, start from one with
  * `runtime.sandboxes.create({ snapshot: id })`, or do both with `sbx.fork()`. */
@@ -71,5 +74,5 @@ export declare class Snapshots {
         ifLabels?: Record<string, string>;
     }, options?: RequestOptions): Promise<Snapshot>;
     delete(id: string, options?: RequestOptions): Promise<void>;
-    extend(id: string, retentionDays: number, options?: RequestOptions): Promise<Snapshot>;
+    extend(id: string, retentionDays: number | null, options?: RequestOptions): Promise<Snapshot>;
 }