@usestatemachines/sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,55 +1,200 @@
 # @usestatemachines/sdk
 
-TypeScript SDK for [State](https://usestatemachines.com): create disposable environments of
-replica apps, wait until they are ready, connect to them, and clean them up.
+TypeScript SDK for [State](https://usestatemachines.com): start disposable environments of replica
+apps, connect to them, snapshot their data, and stop them.
 
 - Node.js 20.20 or later (22 or 24 recommended), and Cloudflare Workers. ESM only.
 - Retries transient failures safely, including `create`, which is idempotent.
 
-## Install and quickstart
+## Install
 
 ```sh
 npm install @usestatemachines/sdk
 ```
 
+## Quickstart
+
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
-// Reads STATE_API_KEY. The workspace comes from the key.
-const sm = new StateMachines();
+const sm = new StateMachines(); // reads STATE_API_KEY
+const env = await sm.environments.start({ apps: ['salesforce'] });
+
+try {
+  const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+  const res = await salesforce.fetch('/services/data/v67.0/limits');
+  console.log(res.status, await res.json());
+} finally {
+  await env.stop();
+}
+```
+
+`start()` creates the environment, waits until it's `running`, and returns a `RunningEnvironment`.
+It takes `{ readyTimeoutMs, signal }`: the wait gives up after `readyTimeoutMs` (more than 0; 10
+minutes by default). A string app is shorthand for `{ key: s, appId: s }`; nothing else is inferred.
+Salesforce offers several APIs, so pass `apiId`.
+
+If the wait fails after the environment was created, `start()` stops the environment, then
+rethrows the original error. The SDK's errors (`EnvironmentFailedError`, `TimeoutError` or a
+`StateMachinesError`; check with `instanceof`) carry `environmentId` and `stopped`. `stopped` is
+`true` when the stop request succeeded. When it's `false`, the stop wasn't confirmed:
+`stopError` says why, and you should call `sm.environments.stop(err.environmentId)`, which is safe
+to repeat. The exception is your own key, below.
+
+When you abort the `signal` during the wait, `start()` still stops the environment. If the stop
+succeeded, it rejects with your `signal.reason`, unchanged. If not, it rejects with a
+`StateMachinesError` whose `cause` leads to your reason, carrying `environmentId`, `stopped` and
+`stopError`, so you can still clean up.
+
+If you pass your own `idempotencyKey`, `start()` doesn't stop the environment on failure: another
+`start()` with the same key gets the same environment and may be using it. The error carries
+`environmentId` with `stopped: false` and no `stopError`. Stop it only once no other `start()` with
+that key needs it.
 
-// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
+If the create step fails, including an abort, `start()` stops nothing and rejects with a
+`StateMachinesError` that carries `idempotencyKey`. The API may still have created the
+environment, so replay with that key (see
+[Recovering a failed create](#recovering-a-failed-create)) and stop what it returns.
+
+## Choosing an actor
+
+```ts
+const env = await sm.environments.start({ apps: ['salesforce'] });
+
+try {
+  // The app's users. connect() uses the default actor unless you pick one.
+  const actors = await env.actors('salesforce');
+  const rep = actors.find((actor) => actor.summary.startsWith('Sales Representative'));
+
+  if (!rep) {
+    throw new Error('No sales representative in this release.');
+  }
+
+  // Act with a sales rep's permissions to test what they can and can't do.
+  const salesforce = await env.connect('salesforce', { actorId: rep.id, apiId: 'rest' });
+  const res = await salesforce.fetch('/services/data/v67.0/sobjects/Account');
+  console.log(res.status);
+} finally {
+  await env.stop();
+}
+```
+
+Actors are the app's users, such as Salesforce user IDs (`005…`), and every request runs with the
+chosen actor's permissions. Without an `actorId`, `connect()` uses the environment's declared
+default connection, if it has one, or else the first actor the app lists, the administrator, so
+pick a less-privileged actor to test permission behaviour.
+
+## Full control
+
+Use `create`, `waitUntilReady` and `connect` directly when you want to run each step yourself, or
+keep an environment up after a failed boot so you can inspect it. You don't need this path for
+app keys, labels or `lifetimeMinutes`: `start()` takes the same input.
+**Nothing is stopped automatically on this path**: stop the environment yourself, even when a step
+throws.
+
+```ts
 const environment = await sm.environments.create({
-  name: 'quickstart',
-  // The default Salesforce app; sm.catalog.get() lists every app.
+  name: 'nightly',
+  // key is your own name for the app; later calls take it.
   apps: [{ key: 'crm', appId: 'salesforce' }],
+  lifetimeMinutes: 30,
+  labels: { suite: 'nightly' },
 });
 
 try {
-  await sm.environments.waitUntilReady(environment.id);
+  await sm.environments.waitUntilReady(environment.id, { timeoutMs: 5 * 60_000 });
+
+  const crm = await sm.environments.connect(environment.id, 'crm', { apiId: 'rest' });
+  const res = await crm.fetch('/services/data/v67.0/limits');
+  console.log(res.status);
+} finally {
+  await sm.environments.stop(environment.id);
+  // In CI: fail the run when cleanup can't be confirmed.
+  await sm.environments.waitUntilStopped(environment.id);
+}
+```
 
-  // Salesforce has several actors (its users) and API profiles, so pick one of each.
-  // The connection lists the actors; this acts as the first.
-  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
-  const [actor] = actors;
+1. `create(input)` returns one `Environment` as soon as the API accepts it, before the apps boot.
+2. `waitUntilReady(id)` polls until it is `running`. It throws `EnvironmentFailedError` if the
+   environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after `timeoutMs`
+   (default 10 minutes). It **never stops the environment**, even when it throws.
+3. `connect(id, appKey, { apiId, actorId })` returns a `Connection` to one app (see
+   [Connections](#connections)).
+4. `stop(id)` returns as soon as the API accepts it, and a second call also resolves.
+   `waitUntilStopped(id)` resolves only when the environment is `stopped` or `failed` **and**
+   every app's `disposal` is `complete`. If any disposal is `failed` or `unknown`, it throws
+   `DisposalIncompleteError` with the environment.
 
-  if (!actor) {
-    throw new Error('The Salesforce app has no actors.');
-  }
+`lifetimeMinutes` counts from when the environment starts, so boot time uses part of it. When it
+runs out, the environment stops with `stopReason: 'expired'`. The default and maximum are in
+`(await sm.credential.get()).limits.environmentLifetime`.
 
-  const crm = await sm.environments.connect(environment.id, 'crm', {
-    actorId: actor.id,
-    apiId: 'rest',
+Both waits accept `{ timeoutMs, signal }`. Aborting the `signal` rejects the wait with
+`signal.reason`. They poll at growing intervals of about 1 to 5 seconds, with random jitter, and
+keep polling through transient failures.
+
+`start()` and `create()` take the same input, including `{ key, appId }` objects for a custom key
+or two instances of one app.
+
+## Snapshots
+
+A snapshot saves the data of a running environment's apps. Seed one environment, snapshot it, and
+start later environments from the snapshot instead of seeding each one.
+
+```ts
+const env = await sm.environments.start({ apps: ['salesforce'] });
+
+try {
+  const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+  await salesforce.fetch('/services/data/v67.0/sobjects/Account', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ Name: 'Acme' }),
   });
-  const response = await crm.fetch('/services/data/v67.0/limits');
 
-  console.log(response.status, await response.json());
+  // Waits until the snapshot is ready.
+  const snapshot = await env.snapshot({ name: 'seeded accounts' });
+  console.log(snapshot.id, snapshot.sizeBytes);
 } finally {
-  // Stop even when a step fails; lifetime counts from the start.
-  await sm.environments.stop(environment.id);
+  await env.stop();
 }
 ```
 
+```ts
+// Later, or in every CI job: start from the seeded state.
+const restored = await sm.environments.start({ snapshotId: 'snp_…' });
+```
+
+Pass `snapshotId` instead of `apps` to `start()` or `create()`. Each app keeps the key it had when
+captured; `snapshotAppInstanceKeys` restores only some of them. The new environment's
+`sourceEnvironmentSnapshotId` and each app's `sourceAppInstanceSnapshotId` name the source.
+
+- A snapshot is taken per app instance (`consistency: 'per-app-instance'`), not at one instant
+  across apps. It can only be taken while the environment is `running` and each app is `ready`.
+- `readyTimeoutMs` bounds the wait for `ready` (10 minutes by default), as in `start()`. While the
+  API is busy (429 `snapshot-limit`), the capture is retried with the same idempotency key for up
+  to 60 seconds.
+- The SDK never deletes a snapshot for you, and every capture error thrown after the snapshot was
+  created carries `snapshotId`. A wait past `readyTimeoutMs` throws `SnapshotTimeoutError`, and an
+  abort after the create leaves the capture running on the server: `sm.snapshots.waitUntilReady(err.snapshotId)`
+  waits again. A failed capture throws `SnapshotFailedError` and stays failed: capture again.
+- Capturing needs `snapshots:create` and `snapshots:read`, restoring needs `snapshots:read`,
+  renaming needs `snapshots:create`, and deleting needs `snapshots:delete`. Keys created by members don't hold `snapshots:delete`, so
+  `delete` returns 403 for them.
+
+`sm.snapshots` has the individual steps:
+
+- `create(environmentId, input)` returns the API's answer at once, possibly still `capturing`, and
+  doesn't retry `snapshot-limit`. It needs only `snapshots:create`. `waitUntilReady(id)` waits for
+  `ready`. `capture(environmentId, input, options)` does both; `env.snapshot()` calls it.
+- `list({ sourceEnvironmentId, cursor, limit })` returns one page, newest first, without deleted
+  snapshots. `get(id)` also returns deleted ones, with `deletedAt` set.
+- `rename(id, { name, expectedVersion })` needs the snapshot's current `version`. A stale one, or a
+  deleted snapshot, is 409 `version-conflict`, and so is a retried rename whose first answer was
+  lost: `get(id)` shows the current name and version. `name: null` clears the name.
+- `delete(id)` marks the snapshot deleted and returns it. A snapshot that is still `capturing`
+  can't be deleted (409 `not-ready`).
+
 ## Authentication
 
 `new StateMachines()` reads the API key from `STATE_API_KEY`, but only where a global `process`
@@ -74,7 +219,8 @@ export default {
 };
 ```
 
-Calls that need a workspace (`environments.list` and `environments.create`) use, in order:
+Calls that need a workspace (`environments.list`, `environments.create`, `snapshots.list`,
+`snapshots.create` and `snapshots.capture`) use, in order:
 
 1. `workspaceId` passed to that call
 2. `workspaceId` passed to the constructor
@@ -86,24 +232,6 @@ A user session that has no workspace can't supply one, so those calls throw and
 Other constructor options: `serverURL`, `fetch` (a custom fetch implementation), `httpClient`
 (copied, never changed; not combined with `fetch`) and `timeoutMs` (see below).
 
-## Environment lifecycle
-
-1. `create(input)` returns the environment as soon as the API accepts it, before the apps boot.
-2. `waitUntilReady(id)` polls until it is `running`. It throws `EnvironmentFailedError` if the
-   environment becomes `failed`, `stopping` or `stopped`, and `TimeoutError` after `timeoutMs`
-   (default 10 minutes). It **never stops the environment**, even when it throws.
-3. `connect(id, appKey, { actorId, apiId })` returns a `Connection` to one app (see
-   [Connections](#connections)).
-4. `stop(id)` stops it. Always stop in a `finally`.
-
-`lifetimeMinutes` counts from when the environment starts, so boot time uses part of it. When it
-runs out, the environment stops with `stopReason: 'expired'`. The default and maximum are in
-`(await sm.credential.get()).limits.environmentLifetime`.
-
-Both waits accept `{ timeoutMs, signal }`. Aborting the `signal` rejects the wait with
-`signal.reason`. They poll at growing intervals of about 1 to 5 seconds, with random jitter, and
-keep polling through transient failures.
-
 ## Retries and timeouts
 
 Every API call retries on its own, with growing, jittered delays of up to about 5 seconds between
@@ -114,6 +242,7 @@ attempts:
 | `502`, `503`, `504` | Yes | The API is saturated (`503`), or Cloudflare can't reach it for a moment (`502`, `504`). |
 | No response: connection error or attempt timeout | Yes | The request may never have arrived. |
 | `429` (`environment-limit`) | No | A quota on live environments. Stop one, then create again. |
+| `429` (`snapshot-limit`) | Only by `snapshots.capture()` and `env.snapshot()`, for up to 60 seconds | The API is running as many captures as it can. |
 | Any other status: other `4xx`, and other `5xx` | No | Not retried by the SDK. |
 
 - A `Retry-After` header is honoured, up to 5 seconds.
@@ -123,7 +252,8 @@ attempts:
 - `timeoutMs` (constructor option, default 60 seconds) limits **each attempt**. A timed-out
   attempt is retried with a fresh timeout.
 - A `signal` passed to a call aborts the whole call, including retries. The call rejects with a
-  `StateMachinesError` whose `status` is `null`.
+  `StateMachinesError` whose `status` is `null`. The waits, and `start()` while it waits, reject
+  with `signal.reason` instead (see [Full control](#full-control)).
 
 ```ts
 const environment = await sm.environments.get('env_123', {
@@ -160,21 +290,12 @@ async function createOnce() {
 const environment = await createOnce();
 ```
 
-## Cleanup
-
-`stop` returns as soon as the API accepts it. To confirm cleanup, call `waitUntilStopped`. It
-resolves only when:
-
-- the environment is `stopped` or `failed`, **and**
-- every app's `disposal` is `complete`.
-
-If any app's disposal is `failed` or `unknown`, it throws `DisposalIncompleteError` with the
-environment. We recommend it in CI, so a run fails when cleanup can't be confirmed:
-
-```ts
-await sm.environments.stop(environment.id);
-await sm.environments.waitUntilStopped(environment.id);
-```
+`start()` makes the same guarantee for its create step: call
+`sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same input. A key
+only recovers a failed create. Don't reuse the key of a `start()` whose wait failed: the replay
+returns that same environment, which `start()` stopped (or, with your own key, left running for
+you to stop). And don't replay an error whose `cause`
+is a `TypeError`: the input was invalid and nothing was sent.
 
 ## Errors
 
@@ -188,14 +309,36 @@ Every failed API call throws a `StateMachinesError`:
 | `fields` | `Record<string, string[]> \| null` | Per-field validation messages. |
 | `retryAfter` | `number \| null` | Milliseconds the API asked you to wait. |
 | `retryable` | `boolean` | `true` for a `502`, `503` or `504`, a connection error or an attempt timeout. `false` for caller aborts, request validation errors and responses that aren't valid JSON. |
-| `idempotencyKey` | `string \| undefined` | Set on `environments.create` failures. |
+| `idempotencyKey` | `string \| undefined` | Set on `environments.create` failures, including the create step of `start()`, and on `snapshots.create` and `snapshots.capture` failures. |
 
-`status` is `null` when no HTTP response was received, and also when a response wasn't valid JSON.
+`status` is `null` when no HTTP response was received, when a response wasn't valid JSON, and when
+the SDK rejected the input before sending (its `cause` is then a `TypeError`).
 Error messages never include response bodies. The waits throw their own classes:
 `EnvironmentFailedError` and `DisposalIncompleteError` (both with `environment`) and
 `TimeoutError` (with `timeoutMs` and the last `environment` seen, or `null`). Check errors with
 `instanceof`, not `name`: a platform abort is also named `TimeoutError`.
 
+An SDK error that `start()` rethrows after a failed wait also carries `environmentId`, `stopped`
+and, when the stop failed, `stopError`. The stop gets 30 seconds and doesn't wait for disposal.
+Invalid `apps` fail before any request, as a `StateMachinesError` with `status: null`, the
+`idempotencyKey`, and one of these messages: `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.`
+Starting from a snapshot fails the same way with `Pass apps or snapshotId.`,
+`Pass apps or snapshotId, not both.` or `Pass snapshotAppInstanceKeys with snapshotId.`
+
+Snapshot waits throw `SnapshotFailedError`, with the `snapshot` (its `errorCode` is
+`capture-failed`, or `capture-interrupted` when the API restarted mid-capture), and
+`SnapshotTimeoutError`, with `timeoutMs` and the last `snapshot` seen, or `null`. Both carry
+`snapshotId`. From `capture`, they and any `StateMachinesError` thrown after the snapshot was
+created also carry `snapshotId` and `idempotencyKey`.
+
+| Code | Status | Meaning |
+| --- | --- | --- |
+| `snapshot-limit` | 429 | The API is running as many captures as it can. `capture` retries it for up to 60 seconds; `create` doesn't. |
+| `not-ready` | 409 | Capture: the environment isn't `running` or an app isn't `ready`. Restore: the snapshot isn't `ready` yet. 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 | Restore: no release on this deployment matches the snapshot's apps. |
+
 ```ts
 import { ErrorCode, StateMachinesError } from '@usestatemachines/sdk';
 
@@ -212,8 +355,8 @@ try {
 
 ## Pagination
 
-`environments.list`, `environments.events` and `workspaces.events` return one page,
-`{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`:
+`environments.list`, `environments.events`, `workspaces.events` and `snapshots.list` return one
+page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`:
 
 ```ts
 let cursor: string | undefined;
@@ -231,9 +374,16 @@ do {
 
 ## Connections
 
-`connect(id, appKey)` requires the app to be ready. If the app has several actors, pass
-`{ actorId }`; if it has several API profiles, pass `{ apiId }`. Salesforce has both, so pass both.
-Otherwise it throws a `TypeError` that names the choices. It returns a `Connection` with `baseUrl`, `environmentId`, `appKey`, `actorId`, `api` and
+`connect()` needs the app to be ready, which `start()` guarantees. It takes `{ apiId, actorId }`
+and throws a `TypeError` before revealing any token when a choice is missing or wrong:
+
+- `apiId` is required when the app has several API profiles, as Salesforce does:
+  `Choose one API for <appKey>: <ids>.` There is no default API.
+- `actorId` defaults to the actor of the environment's declared default connection, or else the
+  app's first actor (for Salesforce, the administrator). One that isn't among the app's actors
+  throws `Unknown actor <id> for <appKey>. Choose one of: <ids>.`
+
+It returns a `Connection` with `baseUrl`, `environmentId`, `appKey`, `actorId`, `api` and
 `expiresAt`, and these ways to call the app:
 
 - `headers()` returns `X-State-Environment-Token` plus the app's actor header, such as
@@ -258,10 +408,7 @@ release does), takes the actor token in the envelope's `SessionHeader/sessionId`
 value you put in the envelope:
 
 ```ts
-const soap = await sm.environments.connect(environment.id, 'crm', {
-  actorId: actor.id, // from getConnection, as in the quickstart
-  apiId: 'soap-partner',
-});
+const soap = await env.connect('salesforce', { apiId: 'soap-partner' });
 const envelope = `<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:partner.soap.sforce.com">
   <env:Header><SessionHeader><sessionId>${soap.actorToken()}</sessionId></SessionHeader></env:Header>
   <env:Body><undelete><ids>001000000000000AAA</ids></undelete></env:Body>
@@ -279,12 +426,9 @@ as jsforce only sends it if you configure custom headers. Prefer `Connection.fet
 don't let the client follow redirects, which would forward the tokens to another host:
 
 ```ts
-const crm = await sm.environments.connect(environment.id, 'crm', {
-  actorId: actor.id, // from getConnection, as in the quickstart
-  apiId: 'rest',
-});
-const response = await fetch(new URL('services/data/v67.0/limits', crm.baseUrl), {
-  headers: crm.headers(),
+const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+const response = await fetch(new URL('services/data/v67.0/limits', salesforce.baseUrl), {
+  headers: salesforce.headers(),
   redirect: 'manual',
 });
 ```
@@ -305,6 +449,52 @@ TypeScript consumers need `lib: ["DOM"]` or `@types/node`, for the `fetch`, `Req
   version.
 - The API may add error codes and enum values, such as a new status or stop reason. Enums are
   open: handle values you don't recognise.
+- 0.3.0 adds the snapshot APIs and keeps every 0.2.0 call. An input with neither `apps` nor
+  `snapshotId` now fails with `Pass apps or snapshotId.` `Environment` and its apps gain
+  `sourceEnvironmentSnapshotId` and `sourceAppInstanceSnapshotId` (`null` unless restored), so
+  object literals typed as `Environment` need them.
+- 0.2.0 adds APIs and keeps every 0.1.x call, with these deliberate changes:
+  - `connect()` without `actorId` now succeeds when an app has several actors, acting as the
+    default actor (for Salesforce, the administrator, with full access).
+  - An empty `actorId` (`''`) now throws `Unknown actor`, instead of acting as an app's only actor.
+  - `create()` rejects an empty `apps` list or a repeated app key before sending a request, as a
+    `StateMachinesError` with `status: null`.
+  - `connect()`'s error messages now name the app: `Unknown actor <id> for <appKey>. …` and
+    `Choose one API for <appKey>: …`.
+
+## Known limitations
+
+- Vendor clients such as jsforce don't send `X-State-Environment-Token` unless you configure
+  custom headers, so the gateway rejects them. Use `Connection.fetch`, or pass `headers()` as
+  shown in [Connections](#connections).
+- There is no default API profile: pass `apiId` whenever an app has more than one.
+- Without a declared default connection, the default actor is the first one the release lists;
+  releases don't declare a default actor yet.
+- `await using` isn't supported. Stop the environment in `finally`.
+
+## What's new in 0.3.0
+
+- `sm.snapshots`: `capture`, `create`, `waitUntilReady`, `get`, `list`, `rename` and `delete`
+  (see [Snapshots](#snapshots)).
+- `env.snapshot()` captures a running environment and waits until the snapshot is `ready`.
+- `start({ snapshotId })` and `create({ snapshotId })` start an environment from a snapshot.
+  Environments carry `sourceEnvironmentSnapshotId`, and apps `sourceAppInstanceSnapshotId`.
+- `environments.list({ snapshotId })` lists the environments started from a snapshot.
+- `SnapshotFailedError` and `SnapshotTimeoutError`.
+
+## What's new in 0.2.0
+
+- `sm.environments.start()` creates an environment and waits until it's running. It returns a
+  `RunningEnvironment` with `connect`, `actors`, `stop` and `waitUntilStopped`.
+- String apps: `apps: ['salesforce']` means `[{ key: 'salesforce', appId: 'salesforce' }]`, in
+  `start()` and `create()`.
+- `actors(appKey)` lists an app's actors in the release's order.
+- `actorId` is optional in `connect()`. It defaults to the environment's declared default
+  connection's actor, or else the app's first actor.
+- When readiness fails, `start()` stops the environment before it rethrows.
+- Cancelling a call now takes effect immediately (fixes 0.1.1). A `signal` used to reach an
+  in-flight request only when its attempt timeout (60 seconds by default) fired. An abort during
+  a retry delay still takes effect when the delay ends.
 
 ## License
 

package/agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: state-machines
-description: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a sandboxed copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - creating environments, connecting as an actor, cleanup, and errors such as environment-limit and release-unavailable. Also use when the user mentions State Machines, STATE_API_KEY or @usestatemachines/sdk.
+description: Use when an agent or test needs a disposable replica of a SaaS app such as Salesforce, to run integration tests or try API calls against a sandboxed copy instead of a real org. Covers the @usestatemachines/sdk TypeScript SDK - starting environments, choosing an actor, snapshots, cleanup, and errors such as environment-limit and release-unavailable. Also use when the user mentions State Machines, STATE_API_KEY or @usestatemachines/sdk.
 ---
 
 Read `node_modules/@usestatemachines/sdk/README.md` before relying on memory; it matches the installed version. If the package is missing, run `npm install @usestatemachines/sdk`.
@@ -8,83 +8,70 @@ Read `node_modules/@usestatemachines/sdk/README.md` before relying on memory; it
 ## Workflow
 
 1. Check that `STATE_API_KEY` is set without printing it (`test -n "$STATE_API_KEY"`). If it isn't, ask the user to set it; the SDK doesn't read `.env` files.
-2. Create the environment with only the apps the task needs. Log `await sm.catalog.get()` for each app's `appId` and the actors and API profiles its release offers; don't guess IDs. `key` is your own name for the app, and later calls take it.
-3. Open a `try` right after `create` returns, and call `stop` in its `finally`.
-4. `await sm.environments.waitUntilReady(environment.id)`. It never stops the environment.
-5. Connect as one actor through one API profile. Salesforce has several of each, so name both: `sm.environments.connect(environment.id, 'crm', { actorId: actor.id, apiId: 'rest' })`, taking `actor` from `(await sm.environments.getConnection(environment.id, 'crm')).actors`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name, so read them from the connection instead of hard-coding one. Choose the actor whose permissions the task needs; each release in the catalog lists them.
-6. Call the app with the connection's `fetch`. A leading `/` means the root of `baseUrl`.
-7. In `finally`, `await sm.environments.stop(environment.id)`. In CI, then await `sm.environments.waitUntilStopped(environment.id)`.
+2. Start the environment with only the apps the task needs: `const env = await sm.environments.start({ apps: ['salesforce'] })`. Log `await sm.catalog.get()` for each app's ID and the actors and API profiles its release offers; don't guess IDs. A string app means `{ key: s, appId: s }`; use `{ key, appId }` for your own key. `start()` waits until the environment is `running`. If that fails, it stops the environment and rethrows; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`.
+3. Open a `try` right after `start()` returns, and call `env.stop()` in its `finally`.
+4. Connect through one API profile. Salesforce offers several and has no default, so pass `apiId`: `env.connect('salesforce', { apiId: 'rest' })`. This acts as the environment's declared default connection's actor, or else the app's first actor, the administrator. To act with another user's permissions, choose one from `await env.actors('salesforce')` and pass its `id` as `actorId`. Salesforce actor IDs are its user IDs, such as `005…`, never a role name, so read them instead of hard-coding one.
+5. Call the app with the connection's `fetch`. A leading `/` means the root of `baseUrl`.
+6. In `finally`, `await env.stop()`. In CI, then `await env.waitUntilStopped()`.
 
 The whole flow, as the package ships it. It is ESM with top-level `await`: save it as `state-quickstart.mts` and run `npx tsx state-quickstart.mts`.
 
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
-// Reads STATE_API_KEY. The workspace comes from the key.
-const sm = new StateMachines();
-
-// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
-const environment = await sm.environments.create({
-  name: 'quickstart',
-  // The default Salesforce app; sm.catalog.get() lists every app.
-  apps: [{ key: 'crm', appId: 'salesforce' }],
-});
+const sm = new StateMachines(); // reads STATE_API_KEY
+const env = await sm.environments.start({ apps: ['salesforce'] });
 
 try {
-  await sm.environments.waitUntilReady(environment.id);
-
-  // Salesforce has several actors (its users) and API profiles, so pick one of each.
-  // The connection lists the actors; this acts as the first.
-  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
-  const [actor] = actors;
-
-  if (!actor) {
-    throw new Error('The Salesforce app has no actors.');
-  }
-
-  const crm = await sm.environments.connect(environment.id, 'crm', {
-    actorId: actor.id,
-    apiId: 'rest',
-  });
-  const response = await crm.fetch('/services/data/v67.0/limits');
-
-  console.log(response.status, await response.json());
+  const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+  const res = await salesforce.fetch('/services/data/v67.0/limits');
+  console.log(res.status, await res.json());
 } finally {
-  // Stop even when a step fails; lifetime counts from the start.
-  await sm.environments.stop(environment.id);
+  await env.stop();
 }
 ```
 
 ## Rules
 
 - Always stop in `finally`. `waitUntilStopped` confirms every app was disposed; use it in CI so a run fails when cleanup can't be confirmed.
-- Lifetime counts from the start, including boot. It defaults to 15 minutes, or the deployment maximum if that is lower: `(await sm.credential.get()).limits.environmentLifetime`. Set `lifetimeMinutes` in `create` for longer runs.
+- To keep a failed environment for inspection, use the full-control path: `sm.environments.create`, then `sm.environments.waitUntilReady(environment.id)`, then `sm.environments.connect(environment.id, key, options)`. Nothing on that path stops the environment for you.
+- Lifetime counts from the start, including boot. It defaults to 15 minutes, or the deployment maximum if that is lower: `(await sm.credential.get()).limits.environmentLifetime`. Set `lifetimeMinutes` in `start` or `create` for longer runs.
 - Live environments are capped per organization: `limits.liveEnvironments` from `sm.credential.get()`. Stop the ones you no longer need.
 - Never print, log or commit `STATE_API_KEY`, tokens, or `headers()` or `actorToken()` output.
 - Salesforce's SOAP profile (`soap-partner`) takes the actor token in the envelope, not a header: put `connection.actorToken()` in `SessionHeader/sessionId`. For it, `headers()` carries only `X-State-Environment-Token`.
 - `connection.fetch` never sends your API key, never follows redirects and only reaches URLs under `baseUrl`.
 - Runtimes: Node.js 20.20 or later (22 or 24 recommended), and Cloudflare Workers. ESM only. TypeScript needs `lib: ["DOM"]` or `@types/node`. Never ship an API key to a browser.
 - In Cloudflare Workers, pass the key explicitly: `new StateMachines({ apiKey: env.STATE_API_KEY })`, and bound calls with `{ signal: AbortSignal.timeout(20_000) }`, since retries can take minutes.
-- `environments.list`, `environments.events` and `workspaces.events` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
-- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `DisposalIncompleteError`, `TimeoutError`), not by `name`.
+- `environments.list`, `environments.events`, `workspaces.events` and `snapshots.list` return one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it is `null`.
+- To reuse seeded data, `await env.snapshot({ name })` once, then `sm.environments.start({ snapshotId })` in place of `apps`. Capturing needs `snapshots:create` and `snapshots:read`. Snapshots are never deleted automatically, not even failed ones.
+- Check errors with `instanceof` (`StateMachinesError`, `EnvironmentFailedError`, `DisposalIncompleteError`, `TimeoutError`, `SnapshotFailedError`, `SnapshotTimeoutError`), not by `name`.
 
 ## Recovering a failed create
 
-The SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If `create` still throws, don't call it again as a new request: that can start a second environment. Every error from `create` carries `err.idempotencyKey`. Call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency-conflict`. Keys are kept for a day.
+The SDK already retries `502`, `503`, `504` and connection errors with one idempotency key. If `start()` or `create` still throws with `err.idempotencyKey`, the create failed: don't call it again as a new request, which can start a second environment. Call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. Don't replay when `err.status` is `null` and `err.cause` is a `TypeError`: the input was invalid and nothing was sent; fix the input instead. A key only recovers a failed create: don't reuse the key of a `start()` whose wait failed, because the replay returns that stopped environment. With your own key, `start()` doesn't stop the environment on failure, because another `start()` with that key may be using it: the error carries `err.environmentId`, `err.stopped` is `false` and there is no `err.stopError`. Stop it only once nothing else needs it. It returns the environment the first call created, or creates it if that call never arrived. A different input fails with `idempotency-conflict`. Keys are kept for a day.
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `release-unavailable`, 422 | Unknown or retired `appId` or `appReleaseId`. | Check the IDs against `sm.catalog.get()`. Omit `appReleaseId` for the default release. |
+| `release-unavailable`, 422 | Unknown or retired `appId` or `appReleaseId`. A string app is used as the `appId`. | Check the IDs against `sm.catalog.get()`. Omit `appReleaseId` for the default release. |
 | `release-unavailable`, 503, or a failed app with that `errorCode` | This deployment doesn't serve the release. The SDK retries a 503 within a 10-minute budget. | Omit `appReleaseId`. If it persists, report the `requestId`. Pass a `signal` to bound the wait. |
-| `environment-limit`, 429 | The organization is at its live-environment cap. Not retried. | `sm.environments.list({ status: 'live' })`, stop one you no longer need, then create again. |
+| `environment-limit`, 429 | The organization is at its live-environment cap. Not retried. | `sm.environments.list({ status: 'live' })`, stop one you no longer need, then start again. |
 | `lifetime-too-long`, 422 | `lifetimeMinutes` is above the maximum. | Use at most `limits.environmentLifetime.maximumMinutes`. |
-| `TypeError: Choose one actor: ...` or `Choose one API: ...` | The app has several actors or API profiles, or the ID doesn't exist. The message lists the valid IDs. | Pass both `actorId` and `apiId` from the listed IDs. |
-| `TypeError: App ... is not ready to connect` | connect() ran before the app was `ready`. | Await `waitUntilReady` first. |
-| `connection-unavailable`, 409 | The app stopped, or the environment is no longer `running`. | Check `sm.environments.get(environment.id)`; if it stopped or expired, create a new one. |
-| `EnvironmentFailedError` from `waitUntilReady` | The environment became `failed`, `stopping` or `stopped`. | Read `err.environment.stopReason` and each app's `errorCode`. Still stop it in `finally`. |
+| `TypeError: Unknown actor <id> for <appKey>. Choose one of: <ids>.` | The `actorId` isn't one of the app's actors. No token was revealed. | Pass an `id` from `await env.actors(appKey)`, or omit `actorId` to act as the default actor. |
+| `TypeError: Choose one API for <appKey>: <ids>.` | The app has several API profiles and `apiId` is missing or unknown. Salesforce always needs one. | Pass `apiId` from the listed IDs, such as `rest`. |
+| `start()` rejects with `EnvironmentFailedError` or `TimeoutError` | The environment failed, or wasn't `running` within `readyTimeoutMs` (10 minutes by default). If `err.stopped` is `true`, `start()` already stopped it. | Read `err.environment` (`null` on a `TimeoutError` that saw no read): its `stopReason` and each app's `errorCode`. If `err.stopped` is `false`, read `err.stopError` and call `sm.environments.stop(err.environmentId)`. To keep a failed environment, use the full-control path. |
+| `StateMachinesError` (`status` null) for invalid `apps`: `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.` | Empty list, duplicate key, or a string that isn't a valid key. No request was sent. | Pass one to ten apps with unique keys; use `{ key, appId }` when the ID isn't a valid key. |
+| `TypeError: App ... is not ready to connect` | On the full-control path, connect() ran before the app was `ready`. | Await `waitUntilReady` first, or use `start()`. |
+| `connection-unavailable`, 409 | The app stopped, or the environment is no longer `running`. | Check `sm.environments.get(env.id)`; if it stopped or expired, start a new one. |
+| `EnvironmentFailedError` from `waitUntilReady` | On the full-control path, the environment became `failed`, `stopping` or `stopped`. | Read `err.environment.stopReason` and each app's `errorCode`. Still stop it in `finally`. |
 | A vendor client such as jsforce is rejected by the gateway | The gateway needs `X-State-Environment-Token` on every request; jsforce only sends it with custom headers configured. | Prefer `connection.fetch`. If you pass `headers()` to another client, send them only to `baseUrl` and disable redirects. |
+| `not-ready`, 409 | Capture: the environment isn't `running` or an app isn't `ready`. Restore: the snapshot isn't `ready` yet. Delete: the snapshot is still `capturing`. | Capture from the handle `start()` returns. Before a restore or delete, `await sm.snapshots.waitUntilReady(snapshotId)`. |
+| `snapshot-limit`, 429 | The API is running as many captures as it can. `capture` and `env.snapshot()` already retried it for 60 seconds. | Wait, then capture again. |
+| `SnapshotFailedError` | The capture failed. `err.snapshot.errorCode` is `capture-failed`, or `capture-interrupted` when the API restarted mid-capture. The snapshot is kept. | Capture again with a new idempotency key (the default); the old key returns the same failed snapshot. |
+| `SnapshotTimeoutError` | The snapshot wasn't `ready` within `readyTimeoutMs`. The capture continues on the server. | `await sm.snapshots.waitUntilReady(err.snapshotId)`. |
+| `forbidden`, 403, from `sm.snapshots.delete` | The key lacks `snapshots:delete`. Keys created by members never hold it. | Use a key whose creator holds `snapshots:delete`, or keep the snapshot. |
+| `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. |
 | `TypeError: Pass apiKey or set STATE_API_KEY.` | No key in the environment. | Ask the user to set `STATE_API_KEY`; in Workers, pass `apiKey`. |
 
 More: https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk