@usestatemachines/sdk 0.5.0 → 0.6.1

package/README.md

@@ -1,10 +1,10 @@
 # @usestatemachines/sdk
 
-TypeScript SDK for [State](https://usestatemachines.com): start disposable environments of replica
-apps, connect to them, snapshot their data, suspend and resume them, and stop them.
+TypeScript SDK for [State Machines](https://usestatemachines.com): create disposable environments
+of replica apps, connect to them, take snapshots of their data, pause and resume them, and delete
+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.
+Documentation: [docs.usestatemachines.com](https://docs.usestatemachines.com)
 
 ## Install
 
@@ -17,587 +17,243 @@ npm install @usestatemachines/sdk
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
-const sm = new StateMachines(); // reads STATE_API_KEY
-const env = await sm.environments.start({ apps: ['salesforce'] });
+const sm = new StateMachines(); // reads STATEMACHINES_API_KEY
+const env = await sm.environments.create({ apps: ['salesforce'] });
 
 try {
-  const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+  const salesforce = await env.connect('salesforce');
   const res = await salesforce.fetch('/services/data/v67.0/limits');
   console.log(res.status, await res.json());
 } finally {
-  await env.stop();
+  await env.delete();
 }
 ```
 
-`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`.
+`create` waits until the environment is `running`. If an app fails to start, the server deletes
+the environment. [Waiting](#waiting) lists what each method throws.
 
-`env.stop()` ends the environment and discards its data. 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.
-
-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
+## The client
 
 ```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();
-}
+const sm = new StateMachines({
+  apiKey: process.env.STATEMACHINES_API_KEY, // the default where `process` exists
+  baseUrl: 'https://api.usestatemachines.com', // the default
+  workspaceId: 'ws_...', // for member tokens; an API key has its own workspace
+  fetch, // defaults to the global fetch
+  attemptTimeoutMs: 60_000, // per HTTP attempt; a retry gets a fresh one
+});
 ```
 
-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.
+| Namespace | Methods |
+| --- | --- |
+| `sm` | `me()` |
+| `sm.apps` | `list(query?)`, `versions(appId, query?)` |
+| `sm.workspaces` | `list(query?)`, `get(id)` |
+| `sm.environments` | `create(input, options?)`, `list(query?)`, `get(id)`, `update(id, { name?, labels? })`, `pause(id)`, `resume(id, options?)`, `delete(id)`, `wait(id, { status })`, `connect(id, app, { actorId? }?)` |
+| `sm.snapshots` | `create({ environmentId, name? }, options?)`, `list(query?)`, `get(id)`, `update(id, { name })`, `delete(id)`, `wait(id, { status })` |
+| `sm.requests` | `list(query)`, `get(id)`, `stats(query)`, `body(id, 'request' \| 'response')` |
+| `sm.auditEvents` | `list(query?)` |
 
-## Suspending and resuming
+Every environment the SDK returns carries bound helpers: `env.connect(app)`, `env.pause()`,
+`env.resume()`, `env.delete()`, `env.refresh()` and `env.snapshots.create({ name? })`. They are
+not enumerable, so `JSON.stringify(env)` holds only the API's fields.
 
-Suspend an environment to end its sandboxes and keep its data, then resume it later on the same
-data:
+## Apps
 
-```ts
-await env.suspend();
-await env.waitUntilSuspended();
-// Later, from the same handle or with sm.environments.resume(env.id):
-await env.resume();
-await env.waitUntilReady();
-```
-
-- `env.suspend()` is `sm.environments.suspend(id)`. The environment reads `suspending`, then
-  `suspended`, its apps read `suspended` and `suspendedAt` is set. Only a running environment
-  whose apps are all ready can be suspended; anything else answers `409 not-ready`.
-- While suspended, the lifetime is paused: `expiresAt` moves out by the suspended time when it
-  resumes, and the environment doesn't count toward the live-environment cap.
-- `resume()` starts it again; it answers `409 not-suspended` unless the environment is
-  `suspended` or `failed`, and `429 environment-limit` when the cap is reached. `waitUntilSuspended()` resolves
-  on `suspended` and throws `EnvironmentFailedError` if the environment ends instead.
-- Suspending isn't cleanup: a suspended environment keeps its data until you stop it.
-  `stop()` interrupts ongoing work, including suspension and snapshot capture.
-
-Lifecycle commands require orchestration availability. `stop`, `suspend` and `resume` each
-send a fresh idempotency key and reuse it across automatic retries. You can pass your own
-`{ idempotencyKey }`. Failures carry that key so you can retry the same command after a timeout;
-a timeout does not establish whether the command was accepted.
-
-## 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.
+A string names the app, and its name in the environment is the same string. Use the object form
+for your own name, for two copies of one app, or for settings:
 
 ```ts
-const environment = await sm.environments.create({
-  name: 'nightly',
-  // key is your own name for the app; later calls take it.
-  apps: [{ key: 'crm', appId: 'salesforce' }],
-  lifetimeMinutes: 30,
-  labels: { suite: 'nightly' },
+await sm.environments.create({
+  name: 'Checkout tests',
+  labels: { team: 'crm' },
+  timeLimitMinutes: 30,
+  apps: [
+    'salesforce',
+    {
+      app: 'salesforce',
+      name: 'partner-org',
+      settings: { settings: { soapApiLoginEnabled: false } },
+    },
+  ],
 });
+```
 
-try {
-  await sm.environments.waitUntilReady(environment.id, { timeoutMs: 5 * 60_000 });
+`settings` is passed to the app unchanged. Salesforce takes
+`{ preset?: 'development', configure?, settings?: { soapApiLoginEnabled?: boolean } }`, where
+`configure` can set the organization's `Name` and the administrator's `Username`. A refused value
+fails the start with `failure.code: 'invalid_settings'`, and its `failure.message` names the
+setting.
 
-  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);
-}
-```
+`sm.apps.list()` lists the apps. `sm.apps.versions(appId)` lists each version's APIs and actors.
+A new environment runs each app's default version.
 
-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`, `suspending`, `suspended`, `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` **and**
-   every app's `disposal` is `complete`. If any disposal is `failed` or `unknown`, it throws
-   `DisposalIncompleteError` with the environment.
-
-`lifetimeMinutes` counts from when the environment starts, so boot time uses part of it; time spent
-suspended doesn't count. 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.
-
-`start()` and `create()` take the same input, including `{ key, appId }` objects for a custom key
-or two instances of one app.
+## Credentials
 
-## Snapshots
+`env.connect(app, { actorId? })` returns the API's `Credentials`: `url`, `headers`, `token`,
+`expiresAt` and `login`, plus `fetch(path, init?)`.
 
-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.
+- `fetch` joins `path` to `url`; a leading `/` means the root of the app. It adds `headers`
+  (`StateMachines-Environment-Token`), and puts `token` in the header of the API whose path
+  matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0.
+- Salesforce SOAP takes the token in the envelope: put `credentials.token` in
+  `SessionHeader/sessionId` yourself.
+- `fetch` never sends your API key, never follows redirects, never retries and only reaches paths
+  under `url`.
+- `actorId` defaults to the app's default actor (for Salesforce, the administrator). Pick another
+  from the version's `actors` to act with that user's permissions.
+- `login` holds what the vendor's own login call needs, when the version declares one for the
+  actor.
+- `token` and `headers` are secrets. To use another client, such as jsforce, send `headers` and
+  the actor header only to `url`, with redirects off.
 
-```ts
-const env = await sm.environments.start({ apps: ['salesforce'] });
+Environments created with `tokenInUrl: true` carry the environment token in `url` instead, and
+`headers` is empty.
 
-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' }),
-  });
-
-  // Waits until the snapshot is ready.
-  const snapshot = await env.snapshot({ name: 'seeded accounts' });
-  console.log(snapshot.id, snapshot.sizeBytes);
-} finally {
-  await env.stop();
-}
-```
+## Pausing and resuming
 
-```ts
-// Later, or in every CI job: start from the seeded state.
-const restored = await sm.environments.start({ snapshotId: 'snp_…' });
-```
+`env.pause()` takes effect when the API answers: the gateway refuses calls, the compute is
+released and the data stays. The time limit stops counting. `env.resume()` boots the apps again
+on the same data and waits until `running`. A paused or failed environment is deleted after one
+day.
 
-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.
-
-- Every app is paused while the snapshot is cut, so a multi-app snapshot records one instant
-  across apps (`consistency: 'environment'`). A single app, or a capture whose pause was refused,
-  is `'app_instance'`. 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`
-exists. Without a key, the constructor throws a `TypeError`.
-
-In Cloudflare Workers, pass `apiKey` explicitly:
+## Snapshots
 
 ```ts
-import { StateMachines } from '@usestatemachines/sdk';
-
-export default {
-  async fetch(_request: Request, env: { STATE_API_KEY: string }) {
-    const sm = new StateMachines({ apiKey: env.STATE_API_KEY });
-    // Bound the call: retries could otherwise hold the request for minutes.
-    const { data } = await sm.environments.list(
-      { status: 'live' },
-      { signal: AbortSignal.timeout(20_000) },
-    );
-
-    return Response.json(data.map(({ id, status }) => ({ id, status })));
-  },
-};
+const seeded = await env.snapshots.create({ name: 'seeded' });
+const copy = await sm.environments.create({ snapshotId: seeded.id });
 ```
 
-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
-3. the workspace of the API key, read once from `sm.credential.get()` and cached
-
-A user session that has no workspace can't supply one, so those calls throw and ask for
-`workspaceId`.
+A snapshot holds every app of a running environment at one moment, and waits until `ready`. A
+pause or delete during the snapshot fails it with `failure.code: 'interrupted'`. One snapshot is
+`saving` per environment at a time. `sm.snapshots.delete(id)` deletes a `ready` or `failed`
+snapshot.
 
-Other constructor options: `serverURL`, `fetch` (a custom fetch implementation), `httpClient`
-(copied, never changed; not combined with `fetch`) and `timeoutMs` (see below).
+## Waiting
 
-## Retries and timeouts
-
-Every API call retries on its own, with growing, jittered delays of up to about 5 seconds between
-attempts:
-
-| Response | Retried | Why |
+| Method | Waits for | Throws |
 | --- | --- | --- |
-| `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. Suspend or stop one, then create again. |
-| `429` (`snapshot-limit`) | Only by `snapshots.capture()` and `env.snapshot()`, for up to 60 seconds | Sent by older APIs when too many captures ran. The current API answers `409 capture-in-progress` instead. |
-| Any other status: other `4xx`, and other `5xx` | No | Not retried by the SDK. |
-
-- A `Retry-After` header is honoured, up to 5 seconds.
-- Retries have a 10-minute budget, checked after each failed attempt. It is not a deadline: the
-  last delay and attempt can end later. Pass a `signal` to bound a call: an abort during a
-  retry delay takes effect when the delay ends, at most about 5 seconds later.
-- `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`. 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', {
-  signal: AbortSignal.timeout(30_000),
-});
-```
+| `environments.create` | `running` | `EnvironmentFailedError` when the environment fails; `UnexpectedStatusError` on `paused` or `deleted` for another reason; `WaitTimeoutError` |
+| `environments.resume` | `running` | `EnvironmentFailedError` when the environment fails; `UnexpectedStatusError` on `paused` or `deleted` for another reason; `WaitTimeoutError` |
+| `snapshots.create` | `ready` | `SnapshotFailedError` on `failed`; `UnexpectedStatusError` on `deleted` |
+| `environments.wait(id, { status })`, `snapshots.wait(id, { status })` | `status` | the same rule: a status that cannot reach `status` without another call |
 
-## Recovering a failed create
+Pass `{ wait: false }` to `create`, `resume` or `snapshots.create` to get the API's answer at once.
+`timeoutMs` bounds the wait, and `signal` aborts it. The option types document each default.
+`pause` and `delete` do not wait: the status changes when the API answers.
 
-Every error thrown by `environments.create` carries `err.idempotencyKey`. Replaying the create
-with that key and the **same input** returns the environment the first call created, instead of
-creating a duplicate. If the first call never reached the API, the replay creates it. Replaying
-with a different input fails with `idempotency-conflict`. Keys are kept for a day.
+## YAML
 
 ```ts
-import { StateMachines, StateMachinesError } from '@usestatemachines/sdk';
-
-const sm = new StateMachines();
-const input = { name: 'nightly', apps: [{ key: 'crm', appId: 'salesforce' }] };
-
-async function createOnce() {
-  try {
-    return await sm.environments.create(input);
-  } catch (error) {
-    // Safe after any failure: the replay can't create a second environment.
-    if (error instanceof StateMachinesError && error.idempotencyKey) {
-      return sm.environments.create(input, { idempotencyKey: error.idempotencyKey });
-    }
-
-    throw error;
-  }
-}
+import { parseEnvironmentYaml } from '@usestatemachines/sdk';
 
-const environment = await createOnce();
+const input = parseEnvironmentYaml(await readFile('environment.yaml', 'utf8'));
+const env = await sm.environments.create(input);
 ```
 
-`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.
+The document has the fields of `create`. A bad document throws `StateMachinesError` with
+`code: 'invalid_request'`, `status: null` and `fields` keyed by dotted path. Anchors, aliases,
+tags and duplicate keys are refused.
 
 ## Errors
 
-Every failed API call throws a `StateMachinesError`:
+A failed call throws `StateMachinesError` with `code`, `status`, `message`, `requestId`, `fields`
+and `retryAfterMs`. `status` is `null` when no response arrived. The message never holds a
+response body.
 
-| Field | Type | Meaning |
+| Class | Thrown when | Carries |
 | --- | --- | --- |
-| `status` | `number \| null` | HTTP status; `null` when there was no parsed response. |
-| `code` | `ErrorCode \| null` | API error code, such as `environment-limit`. |
-| `requestId` | `string \| null` | Include it when you contact support. |
-| `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, including the create step of `start()`, and on `snapshots.create` and `snapshots.capture` failures. |
-
-`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`.
+| `StateMachinesError` | any failed call | `code`, `status`, `requestId`, `fields`, `retryAfterMs` |
+| `EnvironmentFailedError` (a `StateMachinesError`) | a waited environment failed | `environment` |
+| `SnapshotFailedError` (a `StateMachinesError`) | a waited snapshot failed | `snapshot` |
+| `UnexpectedStatusError` | a waited resource cannot reach the status without another call | `resource`, `status` |
+| `WaitTimeoutError` | a wait passed `timeoutMs` | `resource` (the last read), `timeoutMs` |
 
 | Code | Status | Meaning |
 | --- | --- | --- |
-| `capture-in-progress` | 409 | This environment is already capturing a snapshot; one runs at a time. Wait for it (`waitUntilReady`), then capture again. |
-| `snapshot-limit` | 429 | Older APIs only: too many captures were running. `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';
-
-try {
-  await sm.environments.create(input);
-} catch (error) {
-  if (error instanceof StateMachinesError && error.code === ErrorCode.EnvironmentLimit) {
-    console.error('Too many live environments; suspend or stop one first.');
-  } else {
-    throw error;
-  }
-}
-```
-
-## Pagination
-
-`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;
-
-do {
-  const page = await sm.environments.list({ status: 'live', cursor });
-
-  for (const environment of page.data) {
-    console.log(environment.id, environment.status);
-  }
+| `invalid_request` | 400 | A wrong field; see `fields`. |
+| `unauthenticated` | 401 | A missing, expired or revoked key. |
+| `forbidden` | 403 | The key lacks the permission. |
+| `not_found` | 404 | No such resource in this workspace. |
+| `invalid_status` | 409 | The status does not allow the call. |
+| `snapshot_in_progress` | 409 | The environment has a snapshot in `saving`. |
+| `idempotency_key_reused` | 409 | The same `idempotencyKey` with a different input. |
+| `workspace_archived` | 409 | A write in an archived workspace. |
+| `body_too_large` | 413 | The request body is over the API's size limit, which the message names. |
+| `version_unavailable` | 422 | The app has no default version. |
+| `environment_limit_reached` | 429 | Too many environments `starting` or `running`. |
+| `internal_error` | 500 | An error on the server. |
+| `unavailable` | 503 | Retried automatically. |
+
+### Errors from the app URL
+
+`Credentials.fetch` returns the gateway's and the app's answers as responses, with the same JSON
+error envelope, and never retries them. These codes come from State Machines, in front of the app:
 
-  cursor = page.nextCursor ?? undefined;
-} while (cursor);
-```
+| Code | Status | Meaning |
+| --- | --- | --- |
+| `environment_not_running` | 409 | The environment is `paused`, `failed` or `deleted`. The body's `error.status` names the status. |
+| `environment_starting` | 503 | The environment is still `starting`. The response carries `Retry-After`. |
+| `environment_unavailable` | 503 | The app is restarting or did not answer. The response carries `Retry-After`. |
+| `response_too_large` | 502 | The app's response is over the size limit of State Machines. |
+| `capacity_exceeded` | 429 | The app has too many requests in flight. |
+| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |
 
-## Connections
-
-`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
-  `Authorization: Bearer <token>`. For an API that takes the actor token in the request body,
-  such as SOAP, it returns only `X-State-Environment-Token`.
-- `fetch(path, init)` sends one request with those headers and returns the raw `Response`. A
-  leading `/` means the root of `baseUrl`. It:
-  - only reaches URLs under `baseUrl`, and throws for any other path
-  - never follows redirects (`redirect: 'manual'`)
-  - never sends your API key
-  - never retries
-  - rejects `x-state-*` headers from the caller
-- `actorToken()` returns the actor token itself, for APIs that take it in the request body, such
-  as SOAP. Treat it as a secret.
-
-`formatActorHeader(actorHeader, token)` returns the `{ name, value }` for an API profile's actor
-header: `Bearer <token>` for `Authorization`, and the raw token for any other header. It returns
-`null` for a SOAP profile (`SOAP SessionHeader`), whose token goes in the envelope instead.
-
-**SOAP APIs:** Salesforce's `soap-partner` profile, when the release offers it (the default
-release does), takes the actor token in the envelope's `SessionHeader/sessionId`. XML-escape any
-value you put in the envelope:
+## Retries and timeouts
 
-```ts
-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>
-</env:Envelope>`;
-const response = await soap.fetch('/services/Soap/u/67.0', {
-  method: 'POST',
-  headers: { 'Content-Type': 'text/xml', SOAPAction: '""' },
-  body: envelope,
-});
-```
+The SDK retries `502`, `503`, `504` and connection errors with backoff, until a deadline.
+`create` and `snapshots.create` send one `Idempotency-Key` for every retry; pass your own
+`idempotencyKey` to replay a call whose outcome you don't know. Each HTTP attempt times out after
+`attemptTimeoutMs`.
 
-**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, those headers carry live tokens: only send them to `baseUrl`, and
-don't let the client follow redirects, which would forward the tokens to another host:
+## Pagination
 
-```ts
-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',
-});
-```
+Every `list` returns one page, `{ data, nextCursor }`. Pass `nextCursor` back as `cursor` until it
+is `null`. [`openapi.json`](openapi.json) in this package gives the range and the default of `limit`.
 
 ## Recorded requests
 
-Request history is best effort. Missing records do not mean that no requests ran.
-Stored records remain readable after an environment stops.
-
-```ts
-const stats = await sm.environments.getRequestStats(env.id, {
-  from: new Date(Date.now() - 60 * 60_000),
-  to: new Date(),
-});
-console.log(stats.count, stats.p95Ms);
-const page = await sm.environments.listRequests(env.id, { appKey: 'salesforce', limit: 20 });
-const first = page.data[0];
-if (first) {
-  const detail = await sm.environments.getRequest(env.id, first.id);
-  console.log(detail.status, detail.responseBody.preview);
-  const body = await sm.environments.getRequestPayload(env.id, first.id, 'response');
-  const bytes = await new Response(body).arrayBuffer();
-}
-```
-
-Payload coverage reports credential redaction and omissions. The detail preview
-is bounded; the payload method returns the full stored body as a byte stream.
+`sm.requests.list({ environmentId })` pages the calls the gateway recorded for an environment,
+newest first. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id,
+'response')` returns the full body as a `Uint8Array`. `sm.requests.stats({ environmentId, from,
+to })` counts them. Recording is best effort.
 
 ## Supported runtimes
 
-- **Node.js 20.20 or later**, with 22 or 24 recommended: Node 20 is past its end of life, and
-  earlier Node 20 releases fail when retrying a `POST`.
-- **Cloudflare Workers.**
+- **Node.js**, at the versions that `engines` in `package.json` allows. ESM only.
+- **Cloudflare Workers.** Pass `apiKey` explicitly.
 - **Not browsers.** Never ship an API key to a browser.
 
 TypeScript consumers need `lib: ["DOM"]` or `@types/node`, for the `fetch`, `Request` and
-`Response` types.
-
-## Compatibility
-
-- While the version is `0.x`, a minor release may include breaking changes. Pin the minor
-  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.5.0 removes database history and fork metadata. See [What's new in 0.5.0](#whats-new-in-050).
-- 0.4.0 adds suspend and resume and keeps every 0.3.0 call: `stop` still ends the environment.
-  `Environment` gains `suspendedAt` and `sourceEnvironmentId`, so object literals typed as
-  `Environment` need them. A snapshot's `consistency` is now `'environment'`, `'app_instance'`
-  or `null` while it isn't ready (it was always `'per-app-instance'`). See
-  [What's new in 0.4.0](#whats-new-in-040).
-- Upgrade from 0.3.0 to capture snapshots: the API now answers `consistency: null` while a
-  capture runs, which 0.3.0 rejects as an invalid response even though the capture started.
-- 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.5.0
-
-### Added
-
-- `sm.environments.listRequests`, `getRequest`, `getRequestPayload` and `getRequestStats`
-  read best-effort gateway request history, including after the environment stops.
-- A failed environment retains its application data and can be resumed or stopped.
-  Stop takes priority over startup, recovery and snapshot capture.
-
-### Removed
-
-- The generated `listEnvironmentHistory`, `getEnvironmentPosition` and
-  `getEnvironmentExchange` operations and their history/position/exchange models.
-  Use the request-history methods above for recorded replica traffic.
-- `EnvironmentApp.forkedAt`. Database object history and point-in-time forks are no longer
-  part of the API.
-
-`waitUntilStopped()` now requires `stopped` and completed disposal. A retained `failed`
-environment is not stopped. Lifecycle commands require Temporal availability; existing
-replica traffic does not.
-
-## What's new in 0.4.0
-
-- `sm.environments.suspend(id)` ends an environment's sandboxes and keeps its data;
-  `sm.environments.resume(id)` runs it again on that data, and
-  `sm.environments.waitUntilSuspended(id)` waits for the suspension (see
-  [Suspending and resuming](#suspending-and-resuming)).
-- `RunningEnvironment` gains `suspend()`, `resume()`, `waitUntilSuspended()` and
-  `waitUntilReady()`.
-- `stop` is unchanged: it ends the environment and discards its data, suspended or not.
-- New statuses: `suspending` and `suspended` for environments, `suspended` and `recovering` for
-  apps. New fields: `suspendedAt` and `sourceEnvironmentId` on an environment, `forkedAt` on an
-  app. `waitUntilReady()` throws `EnvironmentFailedError` on `suspending` and `suspended`.
-- Snapshots: `consistency` is `'environment'` (every app paused together), `'app_instance'` (each
-  app captured on its own) or `null` until ready. One capture runs per environment at a time; a
-  second gets `409 capture-in-progress`.
-
-## 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.
+`Response` types. While the version is `0.x`, a minor version may include breaking changes. Enums
+are open: handle values you don't recognise.
+
+## Upgrade from 0.5
+
+0.6 follows the current API. 0.5 and older call routes that the API no longer serves, so they fail
+against it.
+
+| 0.5 | 0.6 |
+| --- | --- |
+| `STATE_API_KEY` | `STATEMACHINES_API_KEY` |
+| Default host `https://state-api.usestatemachines.workers.dev` | `https://api.usestatemachines.com` |
+| `sm.environments.start(input)` | `sm.environments.create(input)`, which waits until `running` |
+| `env.stop()`, `sm.environments.stop(id)` | `env.delete()`, `sm.environments.delete(id)` |
+| `env.suspend()`, `sm.environments.suspend(id)` | `env.pause()`, `sm.environments.pause(id)` |
+| `env.resume()` then `env.waitUntilReady()` | `env.resume()`, which waits until `running` |
+| `waitUntilReady`, `waitUntilStopped`, `waitUntilSuspended` | `sm.environments.wait(id, { status })` |
+| Apps as `{ key, appId }` | Apps as `{ app, name }`, or the app name as a string |
+| `env.connect(app, { apiId, actorId })` returns a `Connection` | `env.connect(app, { actorId })` returns `Credentials`; `fetch` picks the API from the path |
+| `connection.baseUrl`, `connection.headers()` | `credentials.url`, `credentials.headers`, `credentials.token` |
+| `X-State-Environment-Token` | `StateMachines-Environment-Token` |
+| `env.snapshot(options)`, `sm.snapshots.capture(environmentId, options)` | `env.snapshots.create(options)`, `sm.snapshots.create({ environmentId, ...options })` |
+| `sm.environments.start({ snapshotId })` | `sm.environments.create({ snapshotId })` |
+| `sm.environments.listRequests`, `getRequest`, `getRequestPayload`, `getRequestStats` | `sm.requests.list({ environmentId })`, `get(id)`, `body(id, direction)`, `stats(query)` |
+| `sm.credential.get()` | `sm.me()` |
+| The catalog | `sm.apps.list()`, `sm.apps.versions(appId)` |
+| `TimeoutError` | `WaitTimeoutError` |
+| `error.retryAfter` | `error.retryAfterMs` |
+| Error codes such as `environment-limit` and `capture-in-progress` | Codes such as `environment_limit_reached` and `snapshot_in_progress`; see [Errors](#errors) |
 
 ## License