@usestatemachines/sdk 0.7.1 → 0.8.1

package/agents/llms.txt

@@ -4,11 +4,29 @@
 
 Use the project's package manager to install or reuse `@usestatemachines/sdk`. It is ESM only and runs on Node.js and Cloudflare Workers, not browsers. `engines` in its `package.json` gives the Node.js versions. TypeScript needs `lib: ["DOM"]` or `@types/node`. `new StateMachines()` reads the API key from `STATEMACHINES_API_KEY` and doesn't read `.env` files; in Cloudflare Workers, pass `apiKey` explicitly. Never print the key. The installed `node_modules/@usestatemachines/sdk/README.md` matches your version: read it before relying on memory. Read the bundled `agents/SKILL.md` for the task workflow. Reuse the project's secret loader and check the key in the process that runs the test, not just the current shell. Installing the skill does not require SDK installation, example files or remote resources. Ask what the user wants to run and wait. Install the SDK and verify access when their chosen task needs it. Run the connection check below only if the user asks to verify the connection. Do not choose a business workflow from the repository.
 
+## Get a credential
+
+If the project's existing command loads `STATEMACHINES_API_KEY`, reuse that command and secret loader. Keep the same credential loader, CLI profile and API origin across setup commands. Otherwise, run `npx @usestatemachines/cli@0.1.1 whoami --json`. If it succeeds, confirm the account and organization match the task, then use the workspace commands below. If the CLI credential is missing, expired or revoked, start `npx @usestatemachines/cli@0.1.1 login --no-wait --json`. For an expired or revoked saved session, add `--yes` to replace that invalid session in the same profile. Do not replace a valid session for a different account. Show its `verificationUrl` and `userCode`, and wait for approval. A matching code does not identify the requesting computer. After that approval, run `npx @usestatemachines/cli@0.1.1 login --resume --json` with the same profile to finish that attempt. Resume an existing pending login after approval instead of creating another. Report access denial or an API origin mismatch without changing accounts or permissions.
+
+If a pending login's approval URL or code is unavailable, ask before recovering it. Explain that recovery may finish an already-approved login. After confirmation, run `npx @usestatemachines/cli@0.1.1 login --resume --json --stream` with the same profile and API origin. Keep that process running and show its URL and code. Request approval only for a recognized login. Wait for `signed-in` before continuing setup. Do not start another login or resume process. If streaming output is unavailable, report the blocker without reading credential files.
+
+For `cli.not_linked`, run `npx @usestatemachines/cli@0.1.1 workspaces list --json`. Ask which workspace to use when there is more than one, then run `npx @usestatemachines/cli@0.1.1 link --workspace <workspace-id> --json`. Run the user's existing code with `npx @usestatemachines/cli@0.1.1 run -- <command>`. Never print or commit a credential.
+
+## CLI commands
+
+Prefix these commands with `npx @usestatemachines/cli@0.1.1`. Use `help --json` for flags and result schemas:
+
+- `login`, `logout`, `whoami`, `profiles list`, and `profiles use`
+- `workspaces list`, `workspaces use`, `link`, `unlink`, and `init`
+- `apps list`, `environments create`, `environments list`, `environments get`, `environments wait`, and `environments delete`
+- `connect`, `snapshots create`, `snapshots list`, `snapshots get`, `snapshots delete`, `requests list`, and `requests get`
+- `run -- <command>`, `env pull`, `api`, `doctor`, `version`, `help`, and `completion`
+
 ## Concepts
 
 - Environment: one disposable run of one or more apps. `const env = await sm.environments.create({ apps: ['salesforce'] })` creates it and waits until it is `running`. Use `{ wait: false }` to retain the ID before startup. Wait for `running` inside `try`, then delete the owned environment in `finally`, including after a wait failure.
-- Apps: a string names the app, and the app's name in the environment is the same string. Use `{ app: 'salesforce', name: 'crm', settings }` for your own name, for two copies of one app, or for settings. Later calls take the name.
-- Credentials: `const crm = await env.connect('salesforce')` returns `url`, `headers`, `token` and `fetch`. `crm.fetch(path)` joins `path` to `url`, adds `headers`, and puts `token` in the header of the API whose path matches: `Authorization: Bearer` for Salesforce REST and Bulk 2.0. For Salesforce SOAP, put `crm.token` in the envelope's `SessionHeader/sessionId` yourself. `fetch` never sends your API key, never follows redirects and never retries. `token` and `headers` are secrets.
+- Apps: a string names the app by its ID, and the app's name in the environment is the same string. Use `{ appId: 'salesforce', name: 'crm', setup }` for your own name, for two copies of one app, or for the app's setup. Later calls take the name.
+- Credentials: `const crm = await env.connect('salesforce')` returns `token`, `services` and `fetch`. Each service has an `id`, a `url` and the `headers` its requests need. The credentials always list each `public` service of the app's version. Pass `{ services: [id] }` to `connect()` to also list a service by its ID. A `preview` service is listed only when named. `crm.service('api')` returns the `api` service, which is the app URL. `crm.fetch(path)` joins `path` to the `api` service URL and adds its headers, which carry `Authorization: Bearer` with `token`. For Salesforce SOAP, also put `crm.token` in the envelope's `SessionHeader/sessionId`. `fetch` never sends your API key, never follows redirects and never retries. `token` and each service's `headers` are secrets.
 - Actor: one of the app's users; requests run with that user's permissions. `connect()` acts as the app's default actor (for Salesforce, the administrator) unless you pass `actorId`. Salesforce actor IDs are its user IDs, such as `005…`. Find the app by name in `env.apps`, then page through `sm.apps.versions(appId)` to find its exact `versionId`. Read actor IDs from that version's `actors`.
 - Snapshot: the saved data of every app of a running environment, taken at one moment. `await env.snapshots.create({ name: 'seeded' })` waits until it is `ready`. `sm.environments.create({ snapshotId })` creates a new environment from it, in place of `apps`; each app keeps its name and version. A delete during the snapshot fails it with `interrupted`.
 - Recorded requests: `sm.requests.list({ environmentId })` pages the calls made to the environment's apps. `sm.requests.get(id)` adds headers and a preview of each body. `sm.requests.body(id, 'request')` or `'response'` returns the full body as bytes. Recording is best effort.
@@ -19,7 +37,7 @@ Use the project's package manager to install or reuse `@usestatemachines/sdk`. I
 
 Enums are open: handle values you don't recognise.
 
-- Environment `status`: `starting`, `running`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. A `failed` environment has `failure`: `{ app, code, message }` with `start_failed`, `restart_failed`, `version_unavailable` or `invalid_settings`.
+- Environment `status`: `starting`, `running`, `failed`, `deleted`. A `deleted` environment has a `reason` when State Machines deleted it: `expired`, `failed` (it never reached `running`) or `cancelled` (staff ended it). The `reason` is `null` when a caller deleted it. When the environment failed, `failure` is `{ appName, code, message }`, and `code` is `start_failed`, `pause_removed`, `version_unavailable`, `invalid_setup` or `invalid_services`. For `invalid_setup` and `invalid_services`, the app refused a value in `setup` or in `services`, and `message` starts with its path.
 - Snapshot `status`: `saving`, `ready`, `failed`, `deleted`. A failed snapshot has `failure.code` `interrupted` or `internal_error`.
 - `create` throws `EnvironmentFailedError` when the environment fails, `UnexpectedStatusError` when it becomes `deleted` for another reason, and `WaitTimeoutError` when `timeoutMs` passes.
 - `snapshots.create` throws `SnapshotFailedError` when the snapshot fails and `UnexpectedStatusError` when it was deleted.
@@ -60,11 +78,13 @@ A failed API call throws `StateMachinesError` with `status`, `code`, `message`,
 | `environment_starting` | 503 | For reads, wait `Retry-After` and retry. Check stored state before retrying an uncertain write. |
 | `environment_unavailable` | 503 | The app is restarting. For reads, wait `Retry-After`. Check stored state before retrying an uncertain write. |
 | `response_too_large` | 502 | The response is over the size limit. Ask for less, for example with a smaller page. |
-| `unsupported_protocol` | 501 | The app does not serve this API version or protocol. |
+| `invalid_setup` | 503 | The app refused its `setup` after the environment started, such as in a newer version. `error.message` starts with the path of the value. Create another environment with a `setup` that the app accepts. |
+| `invalid_services` | 503 | The app refused a value in `services` after the environment started. `error.message` starts with the path of the value. Create another environment with `services` that the app accepts. |
+| `unsupported_protocol` | 501 | The app does not serve this path, method or content type, or the request body is compressed. |
 
 ## Quickstart
 
-Use the project's TypeScript runner and secret loader. For an empty Node.js project, save as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` with the key available. The check prints the response status and deletes the environment. Only after it prints `200`, report verified setup and the rerun command. Continue only with an explicitly supplied task; otherwise ask what to run next and wait with no setup environment left running.
+Use the project's TypeScript runner with its secret loader, or pass that runner through `npx @usestatemachines/cli@0.1.1 run -- <command>`. For an empty Node.js project, save as `state-quickstart.mts` and run `npx @usestatemachines/cli@0.1.1 run -- npx tsx state-quickstart.mts`. The check prints the response status and deletes the environment. Only after it prints `200`, report verified setup and the rerun command. Continue only with an explicitly supplied task. Otherwise, ask what to run next and wait with no setup environment left running.
 
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';

package/agents/prompt.md

@@ -1,6 +1,12 @@
-Install the State Machines skill in this existing repository so I can use disposable app environments with my coding agent.
+Set up State Machines in this existing repository so I can use disposable app environments with my coding agent.
 
-1. Read the repository instructions. Download the skill from https://docs.usestatemachines.com/skill.md and install it as `state-machines/SKILL.md` in this agent's supported project-local skills directory. Reuse an identical installed copy. Preserve customizations and ask before replacing a different copy. If persistent skills are unsupported, read it for this session and explain the limitation. If the download fails, report the blocker.
-2. Read the skill. Do not create a new project, install the SDK, write example code, change an integration or create remote resources during skill installation. Keep the repository's existing conventions.
-3. The API key belongs in the project's existing secret configuration as `STATEMACHINES_API_KEY`. Never ask me to paste it into chat, print it or commit it. If I need help configuring it, identify the existing secret loader and explain where to save it without reading or displaying secret values.
-4. Report where the skill was installed and whether the agent needs to reload it. Skill installation alone does not verify an API connection. Ask: "What would you like to run or test?" Wait for my answer before making further changes.
+1. Read the repository instructions and inspect the existing State Machines workspace link and agent skill. Keep the repository's structure and conventions. Check that Node.js meets the CLI's runtime requirement. Use the pinned npx command below. A global CLI installation is not required.
+2. Run `npx @usestatemachines/cli@0.1.1 whoami --json`. If the project already has a `STATEMACHINES_API_KEY` loader, run the check through that loader without reading or displaying the secret. Use the same credential loader, CLI profile and API origin for every setup command below, including workspace discovery and init. Reuse valid access and confirm the returned account and organization match my task. If the existing API key or CLI profile works, skip sign-in and reuse it for setup. Do not create a replacement API key. Report an access denial or origin mismatch instead of changing accounts or permissions.
+3. Only when no project API key is configured and the access check reports a missing, expired or revoked CLI credential, run `npx @usestatemachines/cli@0.1.1 login --no-wait --json`. For an expired or revoked saved session, add `--yes` to replace that invalid session in the same profile. Do not replace a valid session for a different account. Show me the returned verification URL and code. Wait for my approval before resuming the same login with `npx @usestatemachines/cli@0.1.1 login --resume --json`, using the same profile. If a login is already pending, resume it after approval instead of starting another. If the request expires, offer a new login. Never ask me to paste a credential into chat, print it or commit it.
+   If a pending login's approval URL or code is unavailable, ask before recovering it. Explain that recovery may finish an already-approved login. After confirmation, run `npx @usestatemachines/cli@0.1.1 login --resume --json --stream` with the same profile and API origin. Keep that process running and show its URL and code. Request approval only for a recognized login. Wait for `signed-in` before continuing setup. Do not start another login or resume process. If streaming output is unavailable, report the blocker without reading credential files.
+
+4. Run `npx @usestatemachines/cli@0.1.1 init --agent <this-agent> --yes`, choosing `claude` for Claude Code or `codex` for Codex. Reuse the repository's existing workspace link. If the CLI needs a workspace, run `npx @usestatemachines/cli@0.1.1 workspaces list --json`. Ask me which to use when more than one is available, then pass `--workspace <workspace-id>` to init. Do not replace a different workspace link or a customized skill without my approval. Read the installed skill and use its pinned npx commands for later work.
+5. Do not create a new project, install the SDK, write example code, change an integration or create remote resources during skill installation. Do not add `--sdk`, `--quickstart` or `--env` to init unless I ask for those changes.
+6. Report where the skill was installed, which workspace is linked, and whether the agent needs to reload it. Setup alone does not verify an integration. Ask: "What would you like to run or test?" Wait for my answer before making further changes.
+
+If this agent cannot run commands or is not Claude Code or Codex, ask me to download https://app.usestatemachines.com/skill.md from my signed-in browser and provide the file. Do not request session cookies or credentials. Install that file in the agent's supported project-local skills directory, preserving any customized skill. If persistent skills are unsupported, read the file for this session and explain the limitation. Report setup as incomplete if the file is unavailable.

package/esm/extensions/client.d.ts

@@ -2,6 +2,7 @@ import type { App } from '../models/app.js';
 import type { AuditEvent } from '../models/audit-event.js';
 import type { CreateEnvironment } from '../models/create-environment.js';
 import type { Me } from '../models/me.js';
+import type { CreateCredentialsRequestBody } from '../models/operations/create-credentials.js';
 import type { GetRequestStatsRequest } from '../models/operations/get-request-stats.js';
 import type { ListAuditEventsRequest } from '../models/operations/list-audit-events.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
@@ -21,7 +22,7 @@ import { type KnownEnvironmentStatus, type KnownSnapshotStatus, type WaitOptions
 export interface StateMachinesOptions {
     /** An API key or a member's access token. Defaults to `STATEMACHINES_API_KEY` where a `process` exists. */
     apiKey?: string;
-    /** Defaults to `https://api.usestatemachines.com`. */
+    /** Defaults to `STATEMACHINES_BASE_URL`, then the production API. Requires HTTPS, except HTTP on localhost or 127.0.0.1. */
     baseUrl?: string;
     /** The workspace for calls that name none. Member tokens need it; an API key has its own. */
     workspaceId?: string;
@@ -41,10 +42,13 @@ export interface CreateEnvironmentOptions extends SignalOptions {
     idempotencyKey?: string;
 }
 export type CreateSnapshotOptions = CreateEnvironmentOptions;
-export interface ConnectOptions {
-    /** Defaults to the app's default actor (for Salesforce, the administrator). */
-    actorId?: string;
-}
+/**
+ * The body of the credentials call. `actorId` defaults to the app's default
+ * actor (for Salesforce, the administrator). `services` names more services
+ * to list, by ID. The credentials always list every `public` service, and a
+ * `preview` service only when `services` names it.
+ */
+export type ConnectOptions = Pick<CreateCredentialsRequestBody, 'actorId' | 'services'>;
 export interface Page<T> {
     data: T[];
     nextCursor: string | null;
@@ -62,7 +66,7 @@ export type RequestStatsQuery = GetRequestStatsRequest;
 export declare class StateMachines {
     #private;
     constructor(options?: StateMachinesOptions);
-    /** The caller: its principal, organization, workspace, permissions and limits. */
+    /** The caller: its credential, principal, organization, workspace, permissions and limits. */
     me(): Promise<Me>;
     readonly apps: {
         list: (query?: PageQuery) => Promise<Page<App>>;
@@ -89,7 +93,7 @@ export declare class StateMachines {
          */
         wait: (environmentId: string, options: WaitOptions<KnownEnvironmentStatus>) => Promise<Environment>;
         /** Credentials for one app of the environment. */
-        connect: (environmentId: string, app: string, options?: ConnectOptions) => Promise<Credentials>;
+        connect: (environmentId: string, appName: string, options?: ConnectOptions) => Promise<Credentials>;
     };
     readonly snapshots: {
         /** Creates a snapshot of a running environment and, unless `wait` is false, waits until it is `ready`. */

package/esm/extensions/client.js

@@ -2,7 +2,7 @@ import { SDK_METADATA } from '../lib/config.js';
 import { HTTPClient } from '../lib/http.js';
 import { StateMachines as Generated } from '../sdk/sdk.js';
 import { bindCredentials } from './credentials.js';
-import { CallerAbortedError, StateMachinesError, toStateMachinesError, } from './errors.js';
+import { CallerAbortedError, toStateMachinesError } from './errors.js';
 import { linkSignal } from './signal.js';
 import { environmentAt, poll, snapshotAt, } from './wait.js';
 export class StateMachines {
@@ -10,10 +10,9 @@ export class StateMachines {
     #fetch;
     #workspaceId;
     #callSignals = new Map();
-    #apis = new Map();
     #lastCall = 0;
     constructor(options = {}) {
-        const apiKey = options.apiKey ?? environmentApiKey();
+        const apiKey = options.apiKey ?? environmentVariable('STATEMACHINES_API_KEY');
         if (!apiKey) {
             throw new TypeError('Pass apiKey or set STATEMACHINES_API_KEY.');
         }
@@ -25,6 +24,7 @@ export class StateMachines {
         if (!(attemptTimeoutMs > 0 && Number.isFinite(attemptTimeoutMs))) {
             throw new RangeError('attemptTimeoutMs must be a positive, finite number.');
         }
+        const baseUrl = baseUrlOrigin(options.baseUrl ?? environmentVariable('STATEMACHINES_BASE_URL'));
         const fetcher = options.fetch;
         // The arrow keeps `this` unbound; runtimes such as workerd reject fetch called on another object.
         const httpClient = new HTTPClient(fetcher ? { fetcher: (input) => fetcher(input) } : {});
@@ -35,10 +35,10 @@ export class StateMachines {
             apiKey,
             userAgent: `statemachines-sdk-ts/${SDK_METADATA.sdkVersion}`,
             httpClient,
-            ...(options.baseUrl ? { serverURL: options.baseUrl } : {}),
+            ...(baseUrl === undefined ? {} : { serverURL: baseUrl }),
         });
     }
-    /** The caller: its principal, organization, workspace, permissions and limits. */
+    /** The caller: its credential, principal, organization, workspace, permissions and limits. */
     me() {
         return this.#call(undefined, (call) => this.#sdk.me(call));
     }
@@ -80,7 +80,7 @@ export class StateMachines {
          */
         wait: async (environmentId, options) => this.#bind(await poll(environmentId, (signal) => this.#read(signal, (call) => this.#sdk.environments.get({ environmentId }, call)), environmentAt(options.status), options)),
         /** Credentials for one app of the environment. */
-        connect: (environmentId, app, options = {}) => this.#connect(environmentId, null, app, options),
+        connect: (environmentId, appName, options = {}) => this.#connect(environmentId, appName, options),
     };
     snapshots = {
         /** Creates a snapshot of a running environment and, unless `wait` is false, waits until it is `ready`. */
@@ -129,51 +129,18 @@ export class StateMachines {
             ? { ...input, workspaceId: this.#workspaceId }
             : input;
     }
-    async #connect(environmentId, known, app, options) {
-        const body = options.actorId === undefined ? {} : { actorId: options.actorId };
-        const [credentials, apis] = await Promise.all([
-            this.#call(undefined, (call) => this.#sdk.environments.connect({ environmentId, appName: app, body }, call)),
-            (async () => {
-                const environment = known ?? (await this.environments.get(environmentId));
-                const entry = environment.apps.find(({ name }) => name === app);
-                return entry ? this.#versionApis(entry.appId, entry.versionId) : [];
-            })(),
-        ]);
-        return bindCredentials(credentials, apis, this.#fetch);
-    }
-    /** A version's APIs never change, so each is read once per client. */
-    #versionApis(appId, versionId) {
-        let apis = this.#apis.get(versionId);
-        if (!apis) {
-            apis = this.#findVersion(appId, versionId);
-            apis.catch(() => this.#apis.delete(versionId));
-            this.#apis.set(versionId, apis);
-        }
-        return apis;
-    }
-    async #findVersion(appId, versionId) {
-        let cursor;
-        do {
-            const page = await this.apps.versions(appId, cursor ? { cursor } : {});
-            const version = page.data.find(({ id }) => id === versionId);
-            if (version) {
-                return version.apis;
-            }
-            cursor = page.nextCursor ?? undefined;
-        } while (cursor);
-        throw new StateMachinesError({
-            message: `Version ${versionId} of ${appId} was not found.`,
-            status: null,
-            code: 'not_found',
-            requestId: null,
-            fields: null,
-            retryAfterMs: null,
-        });
+    async #connect(environmentId, appName, options) {
+        const body = {
+            ...(options.actorId === undefined ? {} : { actorId: options.actorId }),
+            ...(options.services === undefined ? {} : { services: options.services }),
+        };
+        const credentials = await this.#call(undefined, (call) => this.#sdk.environments.connect({ environmentId, appName, body }, call));
+        return bindCredentials(credentials, this.#fetch);
     }
     #bind(data) {
         const { id } = data;
         const helpers = {
-            connect: (app, options = {}) => this.#connect(id, data, app, options),
+            connect: (appName, options = {}) => this.#connect(id, appName, options),
             delete: (options) => this.environments.delete(id, options),
             refresh: () => this.environments.get(id),
             snapshots: {
@@ -257,7 +224,23 @@ function waitOptions(options) {
         ...(options.signal ? { signal: options.signal } : {}),
     };
 }
-function environmentApiKey() {
+function baseUrlOrigin(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const origin = value.endsWith('/') ? value.slice(0, -1) : value;
+    const url = URL.canParse(origin) ? new URL(origin) : undefined;
+    if (!url ||
+        /[{}]/.test(origin) ||
+        origin !== url.origin ||
+        !(url.protocol === 'https:' ||
+            (url.protocol === 'http:' &&
+                (url.hostname === 'localhost' || url.hostname === '127.0.0.1')))) {
+        throw new TypeError('baseUrl or STATEMACHINES_BASE_URL must be an HTTPS origin, or HTTP with localhost or 127.0.0.1.');
+    }
+    return origin;
+}
+function environmentVariable(name) {
     const runtime = globalThis;
-    return runtime.process?.env?.STATEMACHINES_API_KEY;
+    return runtime.process?.env?.[name];
 }

package/esm/extensions/credentials.d.ts

@@ -1,13 +1,30 @@
-import type { Api } from '../models/api.js';
-import type { Credentials as CredentialsData } from '../models/credentials.js';
-/** The API's `Credentials`, plus `fetch` to call the app with them. */
+import type { Credentials as CredentialsData, CredentialsService as CredentialsServiceData } from '../models/credentials.js';
+/** What a client needs to reach one MCP server of a service: send `headers` with every request to `url`. */
+export interface McpServerCredentials {
+    url: string;
+    headers: Record<string, string>;
+}
+/** One service from the credentials, plus `server` to hand one of its MCP servers to a client. */
+export type ServiceCredentials = CredentialsServiceData & {
+    /**
+     * The URL of one MCP server the service serves, with the service's headers.
+     * Throws a `TypeError` naming the served MCP servers when it serves no MCP server
+     * named `name`.
+     */
+    server(name: string): McpServerCredentials;
+};
+/** The API's `Credentials`, plus `fetch` to call the app and `service` to find one service. */
 export type Credentials = CredentialsData & {
     /**
-     * Sends one request to the app: `path` is joined to `url`, `headers` are added, and
-     * `token` goes in the header of the API whose path matches (`Authorization: Bearer`
-     * for Salesforce REST and Bulk 2.0). Never retries, never follows redirects, never
-     * sends the State Machines API key. The SOAP session header is the caller's job.
+     * Sends one request to the `api` service: `path` is joined to its `url`.
+     * Its `headers` are defaults, so a header the caller sets, such as another
+     * session's `Authorization`, is sent instead. The environment token header
+     * is always the service's. Never retries, never follows redirects, never
+     * sends the State Machines API key. Throws a `TypeError` when the
+     * credentials list no `api` service.
      */
     fetch(path: string, init?: RequestInit): Promise<Response>;
+    /** The service with this ID. Throws a `TypeError` naming the listed services when there is none. */
+    service(id: string): ServiceCredentials;
 };
-export declare function bindCredentials(data: CredentialsData, apis: readonly Api[], fetcher: typeof fetch | undefined): Credentials;
+export declare function bindCredentials(data: CredentialsData, fetcher: typeof fetch | undefined): Credentials;

package/esm/extensions/credentials.js

@@ -1,56 +1,91 @@
-const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** The gateway admits a request by this header, so a caller cannot replace it. */
+const ENVIRONMENT_TOKEN_HEADER = 'StateMachines-Environment-Token';
 // Checked on the path part only. Covers protocol-relative starts, backslashes, control
 // characters and encoded dots, slashes and backslashes, including double encoding.
 const UNSAFE_PATH = /^\/\/|\\|%(?:25)*(?:2e|2f|5c)|\p{Cc}/iu;
-const OUTSIDE = 'Credentials.fetch only reaches paths under the app url.';
-export function bindCredentials(data, apis, fetcher) {
-    const base = URL.canParse(data.url) ? new URL(data.url) : null;
-    if (!base || !/^https?:$/.test(base.protocol) || base.search || base.hash) {
-        throw new TypeError('The credentials url is not a plain http(s) URL.');
-    }
-    if (!base.pathname.endsWith('/')) {
-        base.pathname += '/';
+const OUTSIDE = 'Credentials.fetch only reaches paths under the api service url.';
+export function bindCredentials(data, fetcher) {
+    return new BoundCredentials(data, fetcher);
+}
+// Methods live on the prototype, so neither JSON nor a spread copies them.
+class BoundCredentials {
+    actorId;
+    appName;
+    environmentId;
+    expiresAt;
+    login;
+    services;
+    token;
+    #api;
+    #fetcher;
+    constructor(data, fetcher) {
+        this.actorId = data.actorId;
+        this.appName = data.appName;
+        this.environmentId = data.environmentId;
+        this.expiresAt = data.expiresAt;
+        this.login = data.login;
+        this.services = data.services;
+        this.token = data.token;
+        this.#fetcher = fetcher;
+        const api = data.services.find((candidate) => candidate.id === 'api');
+        this.#api = api
+            ? { base: baseUrl(api.url), headers: { ...api.headers } }
+            : null;
     }
-    const send = async (path, init = {}) => {
+    async fetch(path, init = {}) {
+        const { base, headers: apiHeaders } = this.#api ?? this.#unlisted('api');
         const url = resolve(base, path);
         const headers = new Headers(init.headers);
-        const actor = actorHeader(apis, `/${url.pathname.slice(base.pathname.length)}`, data.token);
-        // Ours go last so a caller header of the same name cannot replace them.
-        for (const [name, value] of Object.entries(data.headers)) {
-            headers.set(name, value);
-        }
-        if (actor) {
-            headers.set(actor.name, actor.value);
+        for (const [name, value] of Object.entries(apiHeaders)) {
+            if (!headers.has(name) ||
+                name.toLowerCase() === ENVIRONMENT_TOKEN_HEADER.toLowerCase()) {
+                headers.set(name, value);
+            }
         }
         const request = new Request(url, { ...init, headers, redirect: 'manual' });
         // Called on `globalThis` at use time: a stored unbound `fetch` throws "Illegal invocation" in Workers.
-        return fetcher ? fetcher(request) : globalThis.fetch(request);
-    };
-    return Object.defineProperty({ ...data }, 'fetch', {
-        value: send,
-        enumerable: false,
-    });
+        return this.#fetcher ? this.#fetcher(request) : globalThis.fetch(request);
+    }
+    service(id) {
+        const entry = this.services.find((candidate) => candidate.id === id);
+        return entry ? new BoundService(entry) : this.#unlisted(id);
+    }
+    #unlisted(id) {
+        const listed = this.services.map((each) => each.id).join(', ') || 'none';
+        throw new TypeError(`These credentials list no service named ${JSON.stringify(id)}. They list ${listed}.`);
+    }
 }
-/** The longest `pathTemplate` that prefixes the path names the API; `{...}` matches one segment. */
-function actorHeader(apis, path, token) {
-    let match = null;
-    for (const api of apis) {
-        const pattern = api.pathTemplate
-            .replace(/\/+$/, '')
-            .split(/\{[^}]*\}/)
-            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-            .join('[^/]+');
-        if (new RegExp(`^${pattern}(?:/|$)`).test(path) &&
-            api.pathTemplate.length > (match?.pathTemplate.length ?? -1)) {
-            match = api;
+class BoundService {
+    headers;
+    id;
+    url;
+    constructor(entry) {
+        this.headers = entry.headers;
+        this.id = entry.id;
+        this.url = entry.url;
+        // Set only when present, so a spread or JSON of a service without servers has no `servers` key.
+        if (entry.servers) {
+            this.servers = entry.servers;
+        }
+    }
+    server(name) {
+        const found = this.servers?.find((candidate) => candidate.name === name);
+        if (!found) {
+            const served = this.servers?.map((each) => each.name).join(', ') || 'none';
+            throw new TypeError(`The ${this.id} service serves no MCP server named ${JSON.stringify(name)}. It serves ${served}.`);
         }
+        return { url: found.url, headers: { ...this.headers } };
+    }
+}
+function baseUrl(url) {
+    const base = URL.canParse(url) ? new URL(url) : null;
+    if (!base || !/^https?:$/.test(base.protocol) || base.search || base.hash) {
+        throw new TypeError('The api service url is not a plain http(s) URL.');
     }
-    if (!match || !HTTP_TOKEN.test(match.actorHeader)) {
-        return null;
+    if (!base.pathname.endsWith('/')) {
+        base.pathname += '/';
     }
-    return match.actorHeader.toLowerCase() === 'authorization'
-        ? { name: 'Authorization', value: `Bearer ${token}` }
-        : { name: match.actorHeader, value: token };
+    return base;
 }
 function resolve(base, path) {
     const pathPart = path.split(/[?#]/, 1)[0] ?? '';

package/esm/extensions/environment.d.ts

@@ -9,7 +9,7 @@ import type { Credentials } from './credentials.js';
 export type Environment = EnvironmentData & EnvironmentHelpers;
 export interface EnvironmentHelpers {
     /** Credentials for one app; `actorId` defaults to the app's default actor. */
-    connect(app: string, options?: ConnectOptions): Promise<Credentials>;
+    connect(appName: string, options?: ConnectOptions): Promise<Credentials>;
     delete(options?: SignalOptions): Promise<Environment>;
     /** Reads the environment again. */
     refresh(): Promise<Environment>;

package/esm/extensions/errors.js

@@ -48,7 +48,7 @@ export class EnvironmentFailedError extends StateMachinesError {
         super({
             ...noResponse,
             message: failure
-                ? `Environment ${environment.id} failed: ${failure.message} (${failure.code}, app ${failure.app}).`
+                ? `Environment ${environment.id} failed: ${failure.message} (${failure.code}, app ${failure.appName}).`
                 : `Environment ${environment.id} failed.`,
         });
         this.environment = environment;

package/esm/extensions/index.d.ts

@@ -1,7 +1,7 @@
-export type { Actor, Api, App, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, Me, Permission, Principal, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotStatus, Version, Workspace, } from '../models/index.js';
+export type { Actor, App, AppEntry, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, Me, Permission, Principal, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotStatus, Version, Workspace, } from '../models/index.js';
 export type { ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListAuditEventsQuery, ListEnvironmentsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, SignalOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
-export type { Credentials } from './credentials.js';
+export type { Credentials, McpServerCredentials, ServiceCredentials, } from './credentials.js';
 export type { Environment, EnvironmentHelpers } from './environment.js';
 export { EnvironmentFailedError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
 export type { WaitOptions } from './wait.js';

package/esm/extensions/yaml.js

@@ -1,6 +1,6 @@
 import { isAlias, isScalar, parseDocument, visit } from 'yaml';
 import { invalidInput } from './errors.js';
-const APP_FIELDS = new Set(['app', 'name', 'settings']);
+const APP_FIELDS = new Set(['appId', 'name', 'setup', 'services']);
 /**
  * Parses a YAML document with the fields of `CreateEnvironment`. The SDK checks the shape;
  * the API checks the values. Anchors, aliases, tags and duplicate keys are refused.
@@ -97,8 +97,8 @@ export function parseEnvironmentYaml(text) {
                 add(key, 'Unknown field.');
         }
     }
-    if ('apps' in value === 'snapshotId' in value) {
-        add('$', 'Pass exactly one of apps and snapshotId.');
+    if (!('apps' in value) && !('snapshotId' in value)) {
+        add('$', 'Send apps, snapshotId or both.');
     }
     if (Object.keys(fields).length > 0) {
         throw bad(fields);
@@ -110,22 +110,24 @@ function checkApp(app, path, add) {
         return;
     }
     if (!isRecord(app)) {
-        add(path, 'Expected an app ID or a mapping with app.');
+        add(path, 'Expected an app ID or a mapping with appId.');
         return;
     }
-    const { app: id, name, settings } = app;
-    if (typeof id !== 'string') {
-        add(`${path}.app`, 'Expected a string.');
+    const { appId, name } = app;
+    if (typeof appId !== 'string') {
+        add(`${path}.appId`, 'Expected a string.');
     }
     if ('name' in app && typeof name !== 'string') {
         add(`${path}.name`, 'Expected a string.');
     }
-    if ('settings' in app && !isRecord(settings)) {
-        add(`${path}.settings`, 'Expected a mapping.');
+    for (const field of ['setup', 'services']) {
+        if (field in app && !isRecord(app[field])) {
+            add(`${path}.${field}`, 'Expected a mapping.');
+        }
     }
-    for (const key of Object.keys(app)) {
-        if (!APP_FIELDS.has(key)) {
-            add(`${path}.${key}`, 'Unknown field.');
+    for (const field of Object.keys(app)) {
+        if (!APP_FIELDS.has(field)) {
+            add(`${path}.${field}`, 'Unknown field.');
         }
     }
 }

package/esm/funcs/environments-creators.d.ts

@@ -0,0 +1,11 @@
+import { StateMachinesCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import { StateMachinesHTTPError } from "../models/errors/state-machines-http-error.js";
+import * as operations from "../models/operations/index.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+export declare function environmentsCreators(client: StateMachinesCore, request?: operations.ListEnvironmentCreatorsRequest | undefined, options?: RequestOptions): APIPromise<Result<operations.ListEnvironmentCreatorsResponse, errors.ErrorT | StateMachinesHTTPError | ResponseValidationError | ConnectionError | RequestAbortedError | RequestTimeoutError | InvalidRequestError | UnexpectedClientError | SDKValidationError>>;