TypeScript SDK reference - State Machines

StateMachines is the client class of @usestatemachines/sdk. This page describes version 0.6. To move from 0.5, see Upgrade from SDK 0.5 to 0.6.

Constructor options

Option	Behavior
`apiKey`	API key or member access token. Defaults to `STATEMACHINES_API_KEY` where a process environment exists.
`baseUrl`	Management API origin. Defaults to `https://api.usestatemachines.com`. The SDK adds `/v1` resource paths.
`workspaceId`	Default workspace for scoped calls that do not supply one.
`fetch`	Custom fetch implementation, used for both management calls and `credentials.fetch()`. Defaults to the runtime’s fetch.
`attemptTimeoutMs`	Positive, finite timeout for each management HTTP attempt. Each retry gets a fresh timeout. Defaults to 60000 (60 seconds). It does not configure native app requests.

The SDK does not load .env files. A missing key, or a key that contains anything other than printable ASCII, including a space, throws TypeError in the constructor. Invalid attemptTimeoutMs throws RangeError.

Workspace scope

An API key belongs to one workspace. A workspaceId option does not grant it access to another workspace. Member access tokens need a workspace for workspace-scoped calls, supplied in the constructor or the individual input. The constructor default applies to environments.create(), environments.list(), and snapshots.list(). It also applies to auditEvents.list() when there is no environmentId filter. An explicit input workspaceId takes precedence. Calls that identify a resource by ID use that resource’s workspace and still check authorization. sm.me() returns the principal, the user when the caller is a member, the current organization, the organizations the caller belongs to, permissions, workspace, and limits. workspaceId and limits can be null. Limits include concurrentEnvironments and the default and maximum timeLimitMinutes. sm.workspaces.list({ archived, limit, cursor }) reads workspace metadata. The archived filter is the string 'true' or 'false', with 'false' as the default. An API key sees its own workspace. sm.workspaces.get(workspaceId) reads one workspace. The public SDK does not create or archive workspaces.

Public operations

Method	Input and result
`sm.me()`	Returns the caller’s identity, scope, permissions, and limits.
`sm.apps.list(query?)`	Returns one page of apps. Query accepts `limit` and `cursor`.
`sm.apps.versions(appId, query?)`	Returns one page of published and retired versions, including APIs, actors, and `isDefault`.
`sm.workspaces.list(query?)`	Returns one page of visible workspaces.
`sm.workspaces.get(workspaceId)`	Returns workspace metadata.
`sm.environments.create(input, options?)`	Creates from `apps` or `snapshotId`. Waits for `running` by default.
`sm.environments.list(query?)`	Returns one page of environments with helpers.
`sm.environments.get(environmentId)`	Returns an environment with helpers, including deleted metadata.
`sm.environments.update(environmentId, body)`	Changes `name`, `labels`, or both. `name: null` clears the name. `labels` replaces the whole map.
`sm.environments.pause(environmentId, options?)`	Returns the paused environment when the API accepts the change.
`sm.environments.resume(environmentId, options?)`	Resumes a paused or failed environment. Waits for `running` by default.
`sm.environments.delete(environmentId, options?)`	Returns the deleted environment. Safe to repeat.
`sm.environments.wait(environmentId, options)`	Reads until `options.status` is reached or the wait fails.
`sm.environments.connect(environmentId, appName, options?)`	Returns app credentials, optionally for `actorId`.
`sm.snapshots.create(input, options?)`	Accepts `{ environmentId, name? }`. Waits for `ready` by default.
`sm.snapshots.list(query?)`	Returns one page of snapshots.
`sm.snapshots.get(snapshotId)`	Returns snapshot metadata and save status.
`sm.snapshots.update(snapshotId, { name })`	Renames a snapshot. `name: null` clears its name.
`sm.snapshots.delete(snapshotId)`	Deletes a ready or failed snapshot. Safe to repeat. A saving snapshot cannot be deleted.
`sm.snapshots.wait(snapshotId, options)`	Reads until `options.status` is reached or the wait fails.
`sm.requests.list(query)`	Returns one page of recorded calls for the required `environmentId`.
`sm.requests.get(requestId)`	Returns a recorded call with headers and body previews.
`sm.requests.stats(query)`	Returns counts and latency for an environment and time window.
`sm.requests.body(requestId, direction)`	Returns recorded bytes as `Uint8Array`. `direction` is `'request'` or `'response'`.
`sm.auditEvents.list(query?)`	Returns one page of management audit events for a workspace or environment.

A snapshot is plain data and has no bound methods. Requests and audit events covers recorded bodies, time windows, and audit events.

List filters

Every list() method and apps.versions() accept limit and cursor. Read every page of a list shows the cursor loop. The additional filters are:

Method	Filters
`apps.list()` and `apps.versions(appId)`	No additional query filters. Versions include retired entries.
`workspaces.list()`	`archived: 'true'` or `'false'`, selecting archived or active workspaces.
`environments.list()`	`workspaceId`, `status` array, `snapshotId`, `search` for part of the name, and `label` array.
`snapshots.list()`	`workspaceId`, `environmentId`, and `status` array.
`requests.list()`	Required `environmentId`, plus the request filters in Requests and audit events.
`auditEvents.list()`	`workspaceId` or `environmentId`. An environment filter sets the scope. An explicit workspace that conflicts with it fails.

Environment labels use key=value strings. Every supplied label must match. A status array selects any listed status. Environment and snapshot lists are newest first. A page is a read at that time, not a frozen export of the full result set.

Operation options

Operation	Options
Environment and snapshot creation	`wait`, `timeoutMs`, `signal`, `idempotencyKey`
Environment resume	`wait`, `timeoutMs`, `signal`
Environment pause and delete	`signal`
Environment and snapshot wait	Required `status`. Optional `timeoutMs` and `signal`
Connect	Optional `actorId`

wait defaults to true. With wait: false, creation and resume return after acceptance. timeoutMs bounds the subsequent wait, starting after the initial operation returns. It is not a deadline for the combined creation and waiting time. With wait: false, timeoutMs has no effect. A create call without idempotencyKey generates one UUID and reuses it across automatic retries. Separate create calls generate separate keys. Operation recovery explains how to preserve one key across application retries. signal cancels caller-side work. It does not roll back an accepted operation. Only environment create, pause, resume and delete, snapshot create, and the two wait() methods accept signal. A wait’s timeoutMs defaults to 600000 (10 minutes). Polling starts at 1 second, multiplies the interval by 1.5 up to 5 seconds, and varies each interval at random by up to 20 percent. Each poll read times out after 30 seconds.

Environment helpers

Returned environments have connect(), pause(), resume(), delete(), refresh(), and snapshots.create() bound to their ID. The bound snapshot helper accepts { name? } and the same creation options as sm.snapshots.create(). Helpers are not enumerable. JSON.stringify(env) and object spread preserve API data, not methods. A parsed JSON environment must be read again through sm.environments.get(id) to obtain helpers. An environment object is one resource read. Operations return new objects. They do not change a previously returned object’s status. refresh() reads the current state. Explicit waits are on sm.environments.wait(), not on the environment object.

Runtime and type support

The SDK is ESM only. Node.js support follows the package’s engines field. TypeScript projects need fetch types through the DOM library or Node.js types. Response timestamps are Date objects in the SDK. Direct HTTP responses use timestamp strings. Public types and the error classes are exported from @usestatemachines/sdk. Response enums can contain values introduced after the installed SDK, so callers need a fallback for unfamiliar statuses. Polling keeps waiting on an unfamiliar status until its deadline. The SDK belongs in trusted server processes. A management API key must never be included in browser JavaScript. Cloudflare Workers use an explicitly supplied key. See Use the SDK in Cloudflare Workers.

​Constructor options

​Workspace scope

​Public operations

​List filters

​Operation options

​Environment helpers

​Runtime and type support