@usestatemachines/sdk 0.2.0 → 0.4.0

package/agents/llms.txt

@@ -1,48 +1,61 @@
 # State Machines
 
-> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Start, connect to and stop them with the TypeScript SDK `@usestatemachines/sdk`.
+> State Machines runs disposable environments of replica SaaS apps, such as Salesforce, for tests and coding agents. Start, connect to, suspend, resume and stop them with the TypeScript SDK `@usestatemachines/sdk`.
 
 Install with `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later (22 or 24 recommended) and Cloudflare Workers, not browsers. TypeScript needs `lib: ["DOM"]` or `@types/node`. `new StateMachines()` reads the API key from `STATE_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory.
 
 ## Concepts
 
 - Environment: one disposable run of one or more apps. `const env = await sm.environments.start({ apps: ['salesforce'] })` creates it, waits until it is `running` and returns a `RunningEnvironment`. If the environment fails or the wait times out or is aborted, `start()` stops the environment and rethrows the original error; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. Always call `env.stop()` in a `finally`.
+- Suspend and resume: `env.suspend()` ends the sandboxes and keeps the data; the lifetime pauses. Await `env.waitUntilSuspended()`, later `env.resume()` and `env.waitUntilReady()` to run again on the same data. `env.stop()` ends the environment and discards its data; a suspended environment still needs it.
 - Apps: a string is shorthand for `{ key: s, appId: s }`, nothing more. Use the object form, such as `{ key: 'crm', appId: 'salesforce' }`, for your own key or two instances of one app. `appId` names the app in the catalog (`sm.catalog.get()`); `key` is your name for it in this environment, and later calls take the key.
 - Actor: one of the app's users; requests run with that user's permissions. Salesforce actor IDs are its user IDs, such as `005…`, never a role name. `await env.actors('salesforce')` lists them in the release's order. connect() acts as the environment's declared default connection's actor, or else the first actor, the administrator, unless you pass `actorId`; pick a less-privileged actor to test permissions.
 - API profile: one API of the app, with its path and versions. Salesforce offers several (`rest`, `soap-partner`, `bulk2`, `oauth`) and has no default, so always pass `apiId`: `env.connect('salesforce', { apiId: 'rest' })`.
 - Connection: `connection.fetch` never sends your API key, never follows redirects and never retries. `connection.headers()` returns live tokens: treat them as secrets. Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope instead: put `connection.actorToken()`, also a secret, in `SessionHeader/sessionId`; `headers()` then carries only `X-State-Environment-Token`.
 - Full control: `sm.environments.create(input)` returns one `Environment` before the apps boot, `sm.environments.waitUntilReady(environment.id)` waits, and `sm.environments.connect(environment.id, key, options)` connects. Nothing on this path stops the environment for you; use it to keep a failed environment for inspection.
+- Snapshot: the saved data of a running environment's apps, taken per app instance. `const snapshot = await env.snapshot({ name: 'seeded' })` captures it and waits until it is `ready`. `sm.environments.start({ snapshotId: snapshot.id })` starts a new environment from it, in place of `apps`; each app keeps its key. Capturing needs `snapshots:create` and `snapshots:read`, restoring needs `snapshots:read`, `rename` needs `snapshots:create`, and `sm.snapshots.delete(id)` needs `snapshots:delete`, which keys created by members don't hold. Snapshots are never deleted automatically, not even failed or timed-out ones: `SnapshotFailedError` and `SnapshotTimeoutError` carry `err.snapshotId`. `sm.snapshots` also has `create`, `waitUntilReady`, `get`, `list` and `rename`.
 - Vendor clients: the gateway needs `X-State-Environment-Token` on every request. A client such as jsforce only sends it if you configure custom headers. Prefer `connection.fetch`; if you pass `headers()` to another client, send them only to `connection.baseUrl` and disable redirects.
-- Pagination: `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
+- Pagination: `environments.list`, `environments.events`, `workspaces.events` and `snapshots.list` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
 
 ## Statuses
 
 Enums are open: handle values you don't recognise.
 
-- Environment `status`: `queued`, `starting`, `running`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`.
-- App `status`: `pending`, `starting`, `ready`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.
+- Environment `status`: `queued`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `failed`. `stopReason`: `requested`, `expired`, `app_failed`, `owner_lost`. A suspended environment keeps its data and carries `suspendedAt`.
+- App `status`: `pending`, `starting`, `ready`, `recovering`, `suspended`, `stopping`, `stopped`, `failed`. A failed app carries `errorCode`.
 - App `disposal`: `pending`, `complete`, `failed`, `unknown`.
-- `start()` and `waitUntilReady` throw `EnvironmentFailedError` if the environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default (`readyTimeoutMs` for `start()`, `timeoutMs` for `waitUntilReady`). `start()` then stops the environment; `waitUntilReady` never does.
+- Snapshot `status`: `capturing`, `ready`, `failed`. A failed snapshot carries `errorCode`: `capture-failed`, `pause-failed` or `pause-lost` when the apps could not be held paused for the capture, or `capture-interrupted` when the API restarted mid-capture.
+- `start()` and `waitUntilReady` throw `EnvironmentFailedError` if the environment becomes `failed`, `suspending`, `suspended`, `stopping` or `stopped`, and `TimeoutError` after 10 minutes by default (`readyTimeoutMs` for `start()`, `timeoutMs` for `waitUntilReady`). `start()` then stops the environment; `waitUntilReady` never does.
+- `waitUntilSuspended` resolves when the environment is `suspended`, and throws `EnvironmentFailedError` if it ends instead.
 - `waitUntilStopped` resolves when the environment is `stopped` or `failed` and every app's disposal is `complete`. It throws `DisposalIncompleteError` if a disposal is `failed` or `unknown`, and `TimeoutError` if disposal stays `pending`.
 
 ## Limits
 
 - Live environments are capped per organization: `(await sm.credential.get()).limits.liveEnvironments`.
-- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it; at the end the environment stops with `stopReason: 'expired'`.
+- `lifetimeMinutes` defaults to 15 minutes, or the deployment maximum if that is lower. Both are in `(await sm.credential.get()).limits.environmentLifetime`. Lifetime counts from the start, so boot uses part of it, and pauses while suspended; at the end the environment stops with `stopReason: 'expired'`.
+- A suspended environment doesn't count toward the live cap; resuming it does.
 - Always call `env.stop()` in a `finally`. In CI, then await `env.waitUntilStopped()`.
 
 ## Errors and retries
 
-A failed API call throws `StateMachinesError` with `status`, `code`, `requestId` and `retryAfter`. The SDK retries `502`, `503`, `504`, connection errors and attempt timeouts itself, within a 10-minute retry budget (the last attempt can end later); `create` retries reuse one idempotency key. It retries nothing else: not `429`, other `4xx` or other `5xx`. `err.stopped === false` with `err.stopError` means the stop wasn't confirmed; `sm.environments.stop(err.environmentId)` is safe to repeat. Without `stopError`, you passed your own `idempotencyKey`, so `start()` left the environment running because another `start()` with that key may be using it; stop it only once nothing else needs it. Every error from `create`, including the create step of `start()`, carries `err.idempotencyKey`: `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same input returns the environment the first call created. Invalid `apps` fail before any request as a `StateMachinesError` (`status` null, `cause` a `TypeError`; don't replay it) with one of: `Pass at least one app.`, `App key "<key>" is used twice.` or `"<s>" can't be used as an app key; pass { key, appId } instead.`
+A failed API call throws `StateMachinesError` with `status`, `code`, `requestId` and `retryAfter`. The SDK retries `502`, `503`, `504`, connection errors and attempt timeouts itself, within a 10-minute retry budget (the last attempt can end later); `create` retries reuse one idempotency key. It retries nothing else: not `429`, other `4xx` or other `5xx`. The one exception is snapshot capture, which retries `429` `snapshot-limit` for up to 60 seconds with one idempotency key. `err.stopped === false` with `err.stopError` means the stop wasn't confirmed; `sm.environments.stop(err.environmentId)` is safe to repeat. Without `stopError`, you passed your own `idempotencyKey`, so `start()` left the environment running because another `start()` with that key may be using it; stop it only once nothing else needs it. Every error from `create`, including the create step of `start()`, carries `err.idempotencyKey`: `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same input returns the environment the first call created. Invalid `apps` fail before any request as a `StateMachinesError` (`status` null, `cause` a `TypeError`; don't replay it) with one of: `Pass at least one app.`, `App key "<key>" is used twice.` or `"<s>" can't be used as an app key; pass { key, appId } instead.`
 
 | Code | Status | What to do |
 | --- | --- | --- |
-| `environment-limit` | 429 | Not retried. Stop a live environment (`sm.environments.list({ status: 'live' })`), then start again. |
+| `environment-limit` | 429 | Not retried. Suspend or stop a live environment (`sm.environments.list({ status: 'live' })`), then start or resume again. |
+| `not-ready` | 409 | Only a running environment whose apps are all ready can be suspended. Wait for it, or stop it. |
+| `not-suspended` | 409 | Only a suspended environment can resume. After `suspend()`, await `waitUntilSuspended()` first. |
+| `suspend-in-progress` | 409 | The environment is suspending. Await `waitUntilSuspended()`, then stop it. |
 | `lifetime-too-long` | 422 | Lower `lifetimeMinutes` to at most `limits.environmentLifetime.maximumMinutes`. |
 | `release-unavailable` | 422 | Unknown or retired app or release. Check `appId` and `appReleaseId` against `sm.catalog.get()`. |
 | `release-unavailable` | 503 | This deployment doesn't serve the release. Retried within the budget; omit `appReleaseId` to use the default release, or contact support with the `requestId`. A failed app can carry it as `errorCode`. |
-| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it stopped or expired, start a new one. (Before revealing any token, connect() throws a `TypeError` for an app that isn't ready, an unknown actor, or a missing `apiId`.) |
+| `connection-unavailable` | 409 | The app stopped or the environment is no longer `running`. If it is suspended, resume it; if it stopped or expired, start a new one. (Before revealing any token, connect() throws a `TypeError` for an app that isn't ready, an unknown actor, or a missing `apiId`.) |
 | `idempotency-conflict` | 409 | The idempotency key was used with a different input. Replay with the exact same input. |
+| `capture-in-progress` | 409 | This environment is already capturing a snapshot; one runs at a time. Wait for it, then capture again. |
+| `snapshot-limit` | 429 | Older APIs only. `capture` and `env.snapshot()` retry it for up to 60 seconds; if it still fails, wait and capture again. |
+| `not-ready` | 409 | Capture: the environment isn't `running` or an app isn't `ready`. Restore: the snapshot isn't `ready` yet; `await sm.snapshots.waitUntilReady(id)`. Delete: the snapshot is still `capturing`. |
+| `version-conflict` | 409 | `rename` sent a stale `expectedVersion`, or the snapshot was deleted. `get` it: if `deletedAt` is set it's gone, otherwise retry with its `version`. |
+| `release-unavailable` | 422 | On a restore: no release on this deployment matches the snapshot's apps. Start from `apps`, seed again and capture a new snapshot. |
 | `request-timeout` | 503 | Retried automatically. If `create` still fails, replay it with `err.idempotencyKey`. |
 
 ## Quickstart

package/agents/prompt.md

@@ -19,8 +19,8 @@ try {
 }
 ```
 
-4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's ID and the actors and API profiles its release offers; don't guess IDs. Start only the apps the task needs; a string such as `'salesforce'` means `{ key: 'salesforce', appId: 'salesforce' }`. Salesforce always needs an `apiId`. `connect()` acts as the declared default connection's actor, or else the app's first actor, the administrator; to act as a specific user, pass an `actorId` from `await env.actors('salesforce')`.
-5. Always call `env.stop()` in a `finally`. In CI, then await `env.waitUntilStopped()` so the run fails if cleanup isn't confirmed. If `start()` fails after creating the environment, it stops it; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. If the create itself fails, call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`; never retry without the key, which can start a second environment.
+4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's ID and the actors and API profiles its release offers; don't guess IDs. Start only the apps the task needs; a string such as `'salesforce'` means `{ key: 'salesforce', appId: 'salesforce' }`. Salesforce always needs an `apiId`. `connect()` acts as the declared default connection's actor, or else the app's first actor, the administrator; to act as a specific user, pass an `actorId` from `await env.actors('salesforce')`. To reuse seeded data, `await env.snapshot()` once, then `sm.environments.start({ snapshotId })`.
+5. Always call `env.stop()` in a `finally`; it ends the environment and discards its data. In CI, then await `env.waitUntilStopped()` so the run fails if cleanup isn't confirmed. If `start()` fails after creating the environment, it stops it; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. If the create itself fails, call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`; never retry without the key, which can start a second environment.
 6. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens.
 
 Read more: `node_modules/@usestatemachines/sdk/README.md`, https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/esm/extensions/apps.d.ts

@@ -1,8 +1,18 @@
 import type { CreateEnvironmentInput, CreateEnvironmentInputApp } from '../models/create-environment-input.js';
 /** A string is shorthand for `{ key: <the string>, appId: <the string> }`. */
 export type AppInput = string | CreateEnvironmentInputApp;
-export interface EnvironmentInput extends Omit<CreateEnvironmentInput, 'apps'> {
+type Common = Omit<CreateEnvironmentInput, 'apps' | 'snapshotId' | 'snapshotAppInstanceKeys'>;
+export interface EnvironmentInput extends Common {
     /** 1 to 10 apps with unique keys. */
     apps: AppInput[];
 }
+/** Starts from a snapshot: each app keeps the key it had when captured. */
+export interface SnapshotEnvironmentInput extends Common {
+    snapshotId: string;
+    /** Keys of the snapshot's app instances to restore. Defaults to all. */
+    snapshotAppInstanceKeys?: string[];
+}
 export declare function expandApps(input: EnvironmentInput): CreateEnvironmentInput;
+export type EnvironmentSource = EnvironmentInput | SnapshotEnvironmentInput | CreateEnvironmentInput;
+export declare function expandSource(input: EnvironmentSource): CreateEnvironmentInput;
+export {};

package/esm/extensions/apps.js

@@ -21,3 +21,19 @@ export function expandApps(input) {
     }
     return { ...input, apps };
 }
+export function expandSource(input) {
+    const { apps, ...rest } = input;
+    if (rest.snapshotId === undefined) {
+        if (rest.snapshotAppInstanceKeys !== undefined) {
+            throw new TypeError('Pass snapshotAppInstanceKeys with snapshotId.');
+        }
+        if (apps === undefined) {
+            throw new TypeError('Pass apps or snapshotId.');
+        }
+        return expandApps({ ...rest, apps });
+    }
+    if (apps !== undefined) {
+        throw new TypeError('Pass apps or snapshotId, not both.');
+    }
+    return rest;
+}

package/esm/extensions/client.d.ts

@@ -4,13 +4,17 @@ import type { Connection as ConnectionDetails } from '../models/connection.js';
 import type { ConnectionSecret } from '../models/connection-secret.js';
 import type { Credential } from '../models/credential.js';
 import type { Environment } from '../models/environment.js';
+import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { EventPage } from '../models/event-page.js';
+import type { CaptureSnapshotRequestBody } from '../models/operations/capture-snapshot.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
+import type { ListSnapshotsRequest } from '../models/operations/list-snapshots.js';
 import type { ListWorkspacesRequest } from '../models/operations/list-workspaces.js';
+import type { UpdateSnapshotRequestBody } from '../models/operations/update-snapshot.js';
 import type { Release } from '../models/release.js';
 import type { ReleaseActor } from '../models/release-actor.js';
 import type { Workspace } from '../models/workspace.js';
-import { type EnvironmentInput } from './apps.js';
+import { type EnvironmentSource } from './apps.js';
 import { Connection } from './connection.js';
 import { RunningEnvironment } from './running-environment.js';
 import { type WaitOptions } from './wait.js';
@@ -44,6 +48,12 @@ export interface StartOptions extends CreateOptions {
     /** Deadline for the whole wait for readiness. Defaults to 10 minutes. */
     readyTimeoutMs?: number;
 }
+export type CaptureInput = Omit<CaptureSnapshotRequestBody, 'environmentId'>;
+/** `readyTimeoutMs` bounds the wait for `ready`, as in `start()`. */
+export type CaptureOptions = StartOptions;
+export type ListSnapshotsQuery = Omit<ListSnapshotsRequest, 'workspaceId'> & {
+    workspaceId?: string;
+};
 export interface ConnectOptions extends CallOptions {
     /** Defaults to the actor of the environment's declared default connection, else the app's first actor. */
     actorId?: string;
@@ -76,13 +86,21 @@ export declare class StateMachines {
          * environment (unless the caller passed its own `idempotencyKey`), then rethrows the
          * error with `environmentId`, `stopped` and `stopError`.
          */
-        start: (input: EnvironmentInput, options?: StartOptions) => Promise<RunningEnvironment>;
+        start: (input: EnvironmentSource, options?: StartOptions) => Promise<RunningEnvironment>;
         /**
          * A string app is shorthand for `{ key: <the string>, appId: <the string> }`. Every
          * failure carries the `idempotencyKey`; replaying the create with it is safe.
          */
-        create: (input: EnvironmentInput, options?: CreateOptions) => Promise<Environment>;
+        create: (input: EnvironmentSource, options?: CreateOptions) => Promise<Environment>;
+        /** Ends the environment and discards its data. Safe to repeat. */
         stop: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        /**
+         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
+         * Its lifetime is paused meanwhile. Use `stop` to end it.
+         */
+        suspend: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        /** Queues a suspended environment to run again on the data it was suspended with. */
+        resume: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
         events: (environmentId: string, query?: {
             limit?: number;
             cursor?: string;
@@ -91,8 +109,10 @@ export declare class StateMachines {
         actors: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ReleaseActor[]>;
         getConnection: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ConnectionDetails>;
         reveal: (environmentId: string, appKey: string, actorId: string, options?: CallOptions | undefined) => Promise<ConnectionSecret>;
-        /** Resolves when the environment is running. Never stops it. */
+        /** Resolves when the environment is running. Never suspends or stops it. */
         waitUntilReady: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
+        /** Resolves when the environment is suspended and can resume. */
+        waitUntilSuspended: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
         /** Resolves when the environment ended and every sandbox is confirmed disposed. */
         waitUntilStopped: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
         /**
@@ -102,6 +122,29 @@ export declare class StateMachines {
          */
         connect: (environmentId: string, appKey: string, options?: ConnectOptions) => Promise<Connection>;
     };
+    readonly snapshots: {
+        /** Returns the API's answer at once: it may still be `capturing`. */
+        create: (environmentId: string, input?: CaptureInput, options?: CreateOptions) => Promise<EnvironmentSnapshot>;
+        /**
+         * Creates a snapshot and waits until it's `ready`. Needs `snapshots:create` and
+         * `snapshots:read`. A failed or timed-out snapshot is never deleted: the error
+         * carries `snapshotId` and `idempotencyKey`.
+         */
+        capture: (environmentId: string, input?: CaptureInput, options?: StartOptions) => Promise<EnvironmentSnapshot>;
+        /** Resolves when the snapshot is `ready`. Never deletes it. */
+        waitUntilReady: (snapshotId: string, options?: WaitOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Deleted snapshots too, with `deletedAt` set. */
+        get: (snapshotId: string, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Newest first. Deleted snapshots are left out. */
+        list: (query?: ListSnapshotsQuery, options?: CallOptions | undefined) => Promise<Page<EnvironmentSnapshot>>;
+        /**
+         * `null` clears the name. A stale `expectedVersion`, or a deleted snapshot, is a 409
+         * `version-conflict`; so is a retry of a rename whose first answer was lost.
+         */
+        rename: (snapshotId: string, body: UpdateSnapshotRequestBody, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Marks the snapshot deleted and returns it; safe to repeat. A capturing snapshot is a 409 `not-ready`. */
+        delete: (snapshotId: string, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+    };
 }
 /**
  * Names the call a request belongs to. Never sent: the attempt hook removes it.

package/esm/extensions/client.js

@@ -1,20 +1,14 @@
 import { SDK_METADATA } from '../lib/config.js';
 import { HTTPClient } from '../lib/http.js';
 import { StateMachines as Generated } from '../sdk/sdk.js';
-import { expandApps } from './apps.js';
+import { expandSource } from './apps.js';
 import { Connection } from './connection.js';
-import { EnvironmentFailedError, StateMachinesError, TimeoutError, toStateMachinesError, } from './errors.js';
+import { CallerAbortedError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, toStateMachinesError, } from './errors.js';
 import { RunningEnvironment } from './running-environment.js';
 import { linkSignal } from './signal.js';
-import { defaultTimeoutMs, disposed, poll, ready, } from './wait.js';
+import { backoff, defaultTimeoutMs, disposed, poll, pollUntil, ready, sleep, snapshotReady, suspended, } from './wait.js';
 const stopAfterFailureMs = 30000;
-/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
-class CallerAbortedError extends Error {
-    name = 'CallerAbortedError';
-    constructor(reason) {
-        super('The caller aborted the request.', { cause: reason });
-    }
-}
+const busyBudgetMs = 60000;
 export class StateMachines {
     #sdk;
     #fetch;
@@ -117,7 +111,7 @@ export class StateMachines {
         create: async (input, options = {}) => {
             const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
             try {
-                const body = expandApps(input);
+                const body = expandSource(input);
                 return await this.#call(options, async (call) => {
                     const workspaceId = await this.#workspace(options.workspaceId, call.signal);
                     const { data } = await this.#sdk.environments.create({ workspaceId, idempotencyKey, body }, call);
@@ -133,15 +127,25 @@ export class StateMachines {
                 throw new StateMachinesError(error, { idempotencyKey });
             }
         },
+        /** Ends the environment and discards its data. Safe to repeat. */
         stop: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.stop({ environmentId }, call)),
+        /**
+         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
+         * Its lifetime is paused meanwhile. Use `stop` to end it.
+         */
+        suspend: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.suspend({ environmentId }, call)),
+        /** Queues a suspended environment to run again on the data it was suspended with. */
+        resume: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.resume({ environmentId }, call)),
         events: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.events({ ...query, environmentId }, call)),
         /** The app's users, in the release's order. */
         actors: async (environmentId, appKey, options) => (await this.environments.getConnection(environmentId, appKey, options))
             .actors,
         getConnection: (environmentId, appKey, options) => this.#unwrap(options, (call) => this.#sdk.environments.getConnection({ environmentId, appKey }, call)),
         reveal: (environmentId, appKey, actorId, options) => this.#reveal(environmentId, appKey, { actorId }, options),
-        /** Resolves when the environment is running. Never stops it. */
+        /** Resolves when the environment is running. Never suspends or stops it. */
         waitUntilReady: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), ready, options),
+        /** Resolves when the environment is suspended and can resume. */
+        waitUntilSuspended: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), suspended, options),
         /** Resolves when the environment ended and every sandbox is confirmed disposed. */
         waitUntilStopped: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), disposed, options),
         /**
@@ -163,6 +167,97 @@ export class StateMachines {
             return new Connection(details.baseUrl, api, secret, this.#fetch);
         },
     };
+    snapshots = {
+        /** Returns the API's answer at once: it may still be `capturing`. */
+        create: (environmentId, input = {}, options = {}) => this.#createSnapshot(environmentId, input, options, 0),
+        /**
+         * Creates a snapshot and waits until it's `ready`. Needs `snapshots:create` and
+         * `snapshots:read`. A failed or timed-out snapshot is never deleted: the error
+         * carries `snapshotId` and `idempotencyKey`.
+         */
+        capture: async (environmentId, input = {}, options = {}) => {
+            const { readyTimeoutMs, ...createOptions } = options;
+            const { signal } = options;
+            const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+            const timeoutMs = readyTimeoutMs ?? defaultTimeoutMs;
+            if (!(timeoutMs > 0)) {
+                throw new RangeError('readyTimeoutMs must be more than 0.');
+            }
+            const created = await this.#createSnapshot(environmentId, input, { ...createOptions, idempotencyKey }, busyBudgetMs);
+            try {
+                signal?.throwIfAborted();
+                if (snapshotReady(created)) {
+                    return created;
+                }
+                return await this.snapshots.waitUntilReady(created.id, {
+                    timeoutMs,
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (error) {
+                const snapshotId = created.id;
+                if (signal?.aborted && Object.is(error, signal.reason)) {
+                    throw Object.assign(new StateMachinesError(new CallerAbortedError(error), {
+                        idempotencyKey,
+                    }), { snapshotId });
+                }
+                if (error instanceof StateMachinesError ||
+                    error instanceof SnapshotFailedError ||
+                    error instanceof SnapshotTimeoutError) {
+                    Object.assign(error, { snapshotId, idempotencyKey });
+                }
+                throw error;
+            }
+        },
+        /** Resolves when the snapshot is `ready`. Never deletes it. */
+        waitUntilReady: (snapshotId, options) => pollUntil((signal) => this.#unwrap({ signal }, (call) => this.#sdk.snapshots.get({ snapshotId }, { ...call, retries: { strategy: 'none' } })), snapshotReady, options, (timeoutMs, last) => new SnapshotTimeoutError(timeoutMs, last, snapshotId)),
+        /** Deleted snapshots too, with `deletedAt` set. */
+        get: (snapshotId, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.get({ snapshotId }, call)),
+        /** Newest first. Deleted snapshots are left out. */
+        list: (query = {}, options) => this.#call(options, async (call) => {
+            const { workspaceId, ...filters } = query;
+            const resolved = await this.#workspace(workspaceId, call.signal);
+            return this.#sdk.snapshots.list({ ...filters, workspaceId: resolved }, call);
+        }),
+        /**
+         * `null` clears the name. A stale `expectedVersion`, or a deleted snapshot, is a 409
+         * `version-conflict`; so is a retry of a rename whose first answer was lost.
+         */
+        rename: (snapshotId, body, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.update({ snapshotId, body }, call)),
+        /** Marks the snapshot deleted and returns it; safe to repeat. A capturing snapshot is a 409 `not-ready`. */
+        delete: (snapshotId, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.delete({ snapshotId }, call)),
+    };
+    async #createSnapshot(environmentId, input, options, busyMs) {
+        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+        try {
+            return await this.#call(options, async (call) => {
+                const workspaceId = await this.#workspace(options.workspaceId, call.signal);
+                const request = {
+                    workspaceId,
+                    idempotencyKey,
+                    body: { ...input, environmentId },
+                };
+                const deadline = Date.now() + busyMs;
+                for (let attempt = 0;; attempt += 1) {
+                    try {
+                        return (await this.#sdk.snapshots.capture(request, call)).data;
+                    }
+                    catch (error) {
+                        const busy = toStateMachinesError(error);
+                        const waitMs = Math.max(busy.retryAfter ?? 0, backoff(attempt));
+                        if (busy.code !== 'snapshot-limit' ||
+                            Date.now() + waitMs >= deadline) {
+                            throw error;
+                        }
+                        await sleep(waitMs, call.signal);
+                    }
+                }
+            });
+        }
+        catch (error) {
+            throw new StateMachinesError(error, { idempotencyKey });
+        }
+    }
     #reveal(environmentId, appKey, body, options) {
         return this.#unwrap(options, (call) => this.#sdk.environments.reveal({ environmentId, appKey, body }, call));
     }

package/esm/extensions/errors.d.ts

@@ -1,4 +1,5 @@
 import type { Environment } from '../models/environment.js';
+import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { Code } from '../models/error-response.js';
 /** What `environments.start()` adds to the error it rethrows after a failed wait. */
 export interface StartFailure {
@@ -30,6 +31,8 @@ export declare class StateMachinesError extends Error implements Details, StartF
     readonly environmentId?: string;
     readonly stopped?: boolean;
     readonly stopError?: unknown;
+    /** Set when `snapshots.capture()` fails after the snapshot was created. */
+    readonly snapshotId?: string;
     readonly status: number | null;
     readonly code: Code | null;
     readonly requestId: string | null;
@@ -38,7 +41,7 @@ export declare class StateMachinesError extends Error implements Details, StartF
     readonly retryAfter: number | null;
     /** Transient: a 502, 503 or 504, or the request never got a response. */
     readonly retryable: boolean;
-    /** Set on `environments.create` failures; replay the create with it to recover. */
+    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
     readonly idempotencyKey?: string;
     /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
     constructor(error: unknown, extra?: {
@@ -68,4 +71,26 @@ export declare class TimeoutError extends Error implements StartFailure {
     readonly stopError?: unknown;
     constructor(timeoutMs: number, environment: Environment | null);
 }
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+export declare class CallerAbortedError extends Error {
+    readonly name = "CallerAbortedError";
+    constructor(reason: unknown);
+}
+/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
+export declare class SnapshotFailedError extends Error {
+    readonly snapshot: EnvironmentSnapshot;
+    readonly name = "SnapshotFailedError";
+    readonly snapshotId: string;
+    readonly idempotencyKey?: string;
+    constructor(snapshot: EnvironmentSnapshot);
+}
+/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
+export declare class SnapshotTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly snapshot: EnvironmentSnapshot | null;
+    readonly snapshotId: string;
+    readonly name = "SnapshotTimeoutError";
+    readonly idempotencyKey?: string;
+    constructor(timeoutMs: number, snapshot: EnvironmentSnapshot | null, snapshotId: string);
+}
 export {};

package/esm/extensions/errors.js

@@ -17,7 +17,7 @@ export class StateMachinesError extends Error {
     retryAfter;
     /** Transient: a 502, 503 or 504, or the request never got a response. */
     retryable;
-    /** Set on `environments.create` failures; replay the create with it to recover. */
+    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
     idempotencyKey;
     /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
     constructor(error, extra = {}) {
@@ -128,3 +128,36 @@ export class TimeoutError extends Error {
         this.environment = environment;
     }
 }
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+export class CallerAbortedError extends Error {
+    name = 'CallerAbortedError';
+    constructor(reason) {
+        super('The caller aborted the request.', { cause: reason });
+    }
+}
+/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
+export class SnapshotFailedError extends Error {
+    snapshot;
+    name = 'SnapshotFailedError';
+    snapshotId;
+    constructor(snapshot) {
+        super(snapshot.status === 'failed'
+            ? `Snapshot ${snapshot.id} is failed (${snapshot.errorCode ?? 'no error code'}).`
+            : `Snapshot ${snapshot.id} was deleted.`);
+        this.snapshot = snapshot;
+        this.snapshotId = snapshot.id;
+    }
+}
+/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
+export class SnapshotTimeoutError extends Error {
+    timeoutMs;
+    snapshot;
+    snapshotId;
+    name = 'SnapshotTimeoutError';
+    constructor(timeoutMs, snapshot, snapshotId) {
+        super(`Timed out after ${timeoutMs} ms waiting for snapshot ${snapshotId}.`);
+        this.timeoutMs = timeoutMs;
+        this.snapshot = snapshot;
+        this.snapshotId = snapshotId;
+    }
+}

package/esm/extensions/index.d.ts

@@ -1,13 +1,13 @@
 export type { Fetcher, HTTPClientOptions } from '../lib/http.js';
 export { HTTPClient } from '../lib/http.js';
 export { ConnectionError, ErrorResponse, HTTPClientError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, ResponseValidationError, SDKValidationError, StateMachinesHTTPError, UnexpectedClientError, UnexpectedResponseError, } from '../models/errors/index.js';
-export type { ApiProfile, App, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
+export type { ApiProfile, App, AppInstanceSnapshot, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, EnvironmentSnapshot, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
 export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../models/index.js';
 export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
-export type { AppInput, EnvironmentInput } from './apps.js';
-export type { CallOptions, ConnectOptions, CreateOptions, ListEnvironmentsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
+export type { AppInput, EnvironmentInput, SnapshotEnvironmentInput, } from './apps.js';
+export type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, CreateOptions, ListEnvironmentsQuery, ListSnapshotsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
 export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, StateMachinesError, TimeoutError, } from './errors.js';
+export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
 export { RunningEnvironment } from './running-environment.js';
 export type { WaitOptions } from './wait.js';

package/esm/extensions/index.js

@@ -4,5 +4,5 @@ export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../
 export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
 export { StateMachines } from './client.js';
 export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, StateMachinesError, TimeoutError, } from './errors.js';
+export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
 export { RunningEnvironment } from './running-environment.js';

package/esm/extensions/running-environment.d.ts

@@ -1,9 +1,10 @@
 import type { Environment } from '../models/environment.js';
+import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { ReleaseActor } from '../models/release-actor.js';
-import type { CallOptions, ConnectOptions, StateMachines } from './client.js';
+import type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, StateMachines } from './client.js';
 import type { Connection } from './connection.js';
 import type { WaitOptions } from './wait.js';
-/** A started environment. It remains the handle after `stop()`. */
+/** A started environment. It remains the handle after `suspend()` and `stop()`. */
 export declare class RunningEnvironment {
     #private;
     readonly id: string;
@@ -18,7 +19,23 @@ export declare class RunningEnvironment {
     connect(appKey: string, options?: ConnectOptions): Promise<Connection>;
     /** The app's users, in the release's order. */
     actors(appKey: string, options?: CallOptions): Promise<ReleaseActor[]>;
-    /** Safe to call twice. Doesn't wait for disposal: use `waitUntilStopped()`. */
+    /** Captures a snapshot in the environment's own workspace and waits until it's `ready`. */
+    snapshot(input?: CaptureInput, options?: CaptureOptions): Promise<EnvironmentSnapshot>;
+    /**
+     * Ends the sandboxes and keeps the data for `resume()`. Doesn't wait: use
+     * `waitUntilSuspended()` before resuming.
+     */
+    suspend(options?: CallOptions): Promise<Environment>;
+    /** Resolves when the environment is suspended and can resume. */
+    waitUntilSuspended(options?: WaitOptions): Promise<Environment>;
+    /** Runs a suspended environment again on its data. Use `waitUntilReady()` before connecting. */
+    resume(options?: CallOptions): Promise<Environment>;
+    /** Resolves when the environment is running again. */
+    waitUntilReady(options?: WaitOptions): Promise<Environment>;
+    /**
+     * Ends the environment and discards its data. Safe to call twice. Doesn't wait for
+     * disposal: use `waitUntilStopped()`.
+     */
     stop(options?: CallOptions): Promise<Environment>;
     /** Resolves when the environment ended and every sandbox is confirmed disposed. */
     waitUntilStopped(options?: WaitOptions): Promise<Environment>;

package/esm/extensions/running-environment.js

@@ -1,13 +1,15 @@
-/** A started environment. It remains the handle after `stop()`. */
+/** A started environment. It remains the handle after `suspend()` and `stop()`. */
 export class RunningEnvironment {
     id;
     /** The record when `start()` resolved. Use `sm.environments.get(id)` for fresh state. */
     environment;
     #environments;
+    #snapshots;
     constructor(sm, environment) {
         this.id = environment.id;
         this.environment = environment;
         this.#environments = sm.environments;
+        this.#snapshots = sm.snapshots;
     }
     /**
      * actorId defaults to the actor of the environment's declared default connection, or
@@ -21,7 +23,36 @@ export class RunningEnvironment {
     actors(appKey, options) {
         return this.#environments.actors(this.id, appKey, options);
     }
-    /** Safe to call twice. Doesn't wait for disposal: use `waitUntilStopped()`. */
+    /** Captures a snapshot in the environment's own workspace and waits until it's `ready`. */
+    snapshot(input, options = {}) {
+        return this.#snapshots.capture(this.id, input, {
+            ...options,
+            workspaceId: options.workspaceId ?? this.environment.workspaceId,
+        });
+    }
+    /**
+     * Ends the sandboxes and keeps the data for `resume()`. Doesn't wait: use
+     * `waitUntilSuspended()` before resuming.
+     */
+    suspend(options) {
+        return this.#environments.suspend(this.id, options);
+    }
+    /** Resolves when the environment is suspended and can resume. */
+    waitUntilSuspended(options) {
+        return this.#environments.waitUntilSuspended(this.id, options);
+    }
+    /** Runs a suspended environment again on its data. Use `waitUntilReady()` before connecting. */
+    resume(options) {
+        return this.#environments.resume(this.id, options);
+    }
+    /** Resolves when the environment is running again. */
+    waitUntilReady(options) {
+        return this.#environments.waitUntilReady(this.id, options);
+    }
+    /**
+     * Ends the environment and discards its data. Safe to call twice. Doesn't wait for
+     * disposal: use `waitUntilStopped()`.
+     */
     stop(options) {
         return this.#environments.stop(this.id, options);
     }