Upgrade from SDK 0.5 to 0.6

SDK 0.6 follows the current management API. SDK 0.5 and older call routes that the API no longer serves, so they fail against it.

Install 0.6

The SDK is ESM only and needs Node.js 20.20 or later.

npm install @usestatemachines/sdk@0.6

Update the key and host

Rename the STATE_API_KEY variable to STATEMACHINES_API_KEY. The SDK reads only the new name. The default host is now https://api.usestatemachines.com. If your code passes baseUrl: 'https://state-api.usestatemachines.workers.dev', delete that option.

Rename lifecycle calls

0.5	0.6
`sm.environments.start(input)`	`sm.environments.create(input)`, which waits until `running`
`sm.environments.start({ snapshotId })`	`sm.environments.create({ snapshotId })`
`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 })`

Pausing keeps the environment’s data. Deleting removes it. Map each old stop call to delete only where the task is finished with the data.

Update app entries and credentials

0.5	0.6
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` header	`StateMachines-Environment-Token` header

For Salesforce SOAP, put credentials.token in SessionHeader/sessionId in the envelope. See credentials and actors.

Update snapshots, requests and identity

0.5	0.6
`env.snapshot(options)`	`env.snapshots.create(options)`
`sm.snapshots.capture(environmentId, options)`	`sm.snapshots.create({ environmentId, ...options })`
`sm.environments.listRequests`	`sm.requests.list({ environmentId })`
`sm.environments.getRequest`	`sm.requests.get(id)`
`sm.environments.getRequestPayload`	`sm.requests.body(id, direction)`
`sm.environments.getRequestStats`	`sm.requests.stats(query)`
`sm.credential.get()`	`sm.me()`
The catalog	`sm.apps.list()`, `sm.apps.versions(appId)`

Update error handling

0.5	0.6
`TimeoutError`	`WaitTimeoutError`
`error.retryAfter`	`error.retryAfterMs`
`environment-limit`	`environment_limit_reached`
`capture-in-progress`	`snapshot_in_progress`

Every 0.6 error code uses underscores. Check the error subclasses with instanceof before you read StateMachinesError.code. Never match message text. The SDK error reference lists the classes and codes.

Confirm one complete task

Run the quickstart outside production. Confirm that creation reaches running, the app request succeeds, and deletion completes.

Pin the minor version

A 0.x minor release can include breaking changes. Pin the minor version in package.json so an install does not move you to 0.7:

{
  "dependencies": {
    "@usestatemachines/sdk": "~0.6.0"
  }
}

​Install 0.6

​Update the key and host

​Rename lifecycle calls

​Update app entries and credentials

​Update snapshots, requests and identity

​Update error handling

​Confirm one complete task

​Pin the minor version