@usestatemachines/sdk 0.1.1

package/agents/prompt.md

@@ -0,0 +1,49 @@
+Set up State Machines so this project can run code against a disposable replica of a SaaS app, such as Salesforce. Follow these steps in order.
+
+1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js 20.20 or later and on Cloudflare Workers, not in browsers.
+2. Check that `STATE_API_KEY` is set without printing it: `test -n "$STATE_API_KEY"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens. In Cloudflare Workers, pass the key as `new StateMachines({ apiKey })`.
+3. Save this quickstart unchanged as `state-quickstart.mts` and run `npx tsx state-quickstart.mts` to confirm the setup:
+
+```ts
+import { StateMachines } from '@usestatemachines/sdk';
+
+// Reads STATE_API_KEY. The workspace comes from the key.
+const sm = new StateMachines();
+
+// A failed create carries err.idempotencyKey: see "Recovering a failed create" in the README.
+const environment = await sm.environments.create({
+  name: 'quickstart',
+  // The default Salesforce app; sm.catalog.get() lists every app.
+  apps: [{ key: 'crm', appId: 'salesforce' }],
+});
+
+try {
+  await sm.environments.waitUntilReady(environment.id);
+
+  // Salesforce has several actors (its users) and API profiles, so pick one of each.
+  // The connection lists the actors; this acts as the first.
+  const { actors } = await sm.environments.getConnection(environment.id, 'crm');
+  const [actor] = actors;
+
+  if (!actor) {
+    throw new Error('The Salesforce app has no actors.');
+  }
+
+  const crm = await sm.environments.connect(environment.id, 'crm', {
+    actorId: actor.id,
+    apiId: 'rest',
+  });
+  const response = await crm.fetch('/services/data/v67.0/limits');
+
+  console.log(response.status, await response.json());
+} finally {
+  // Stop even when a step fails; lifetime counts from the start.
+  await sm.environments.stop(environment.id);
+}
+```
+
+4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's `appId` and the actors and API profiles its release offers; don't guess IDs. Create only the apps the task needs, and pass connect() the `actorId` and `apiId` the task needs.
+5. Always stop the environment in a `finally`. In CI, then await `sm.environments.waitUntilStopped(environment.id)` so the run fails if cleanup isn't confirmed.
+6. The SDK retries `502`, `503`, `504` and connection errors itself. If `create` still throws, call `sm.environments.create(input, { idempotencyKey: err.idempotencyKey })` with the same `input`. Never retry `create` without the key: that can start a second environment.
+
+Read more: `node_modules/@usestatemachines/sdk/README.md`, https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/esm/core.d.ts

@@ -0,0 +1,9 @@
+import { ClientSDK } from "./lib/sdks.js";
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+export declare class StateMachinesCore extends ClientSDK {
+}

package/esm/core.js

@@ -0,0 +1,12 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+import { ClientSDK } from "./lib/sdks.js";
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+export class StateMachinesCore extends ClientSDK {
+}

package/esm/extensions/client.d.ts

@@ -0,0 +1,81 @@
+import { type Fetcher, HTTPClient } from '../lib/http.js';
+import type { Catalog } from '../models/catalog.js';
+import type { Connection as ConnectionDetails } from '../models/connection.js';
+import type { ConnectionSecret } from '../models/connection-secret.js';
+import type { CreateEnvironmentInput } from '../models/create-environment-input.js';
+import type { Credential } from '../models/credential.js';
+import type { Environment } from '../models/environment.js';
+import type { EventPage } from '../models/event-page.js';
+import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
+import type { ListWorkspacesRequest } from '../models/operations/list-workspaces.js';
+import type { Release } from '../models/release.js';
+import type { Workspace } from '../models/workspace.js';
+import { Connection } from './connection.js';
+import { type WaitOptions } from './wait.js';
+export interface StateMachinesOptions {
+    /** Workspace API key. Defaults to `STATE_API_KEY` where a `process` exists. */
+    apiKey?: string;
+    serverURL?: string;
+    /** Used when a call omits `workspaceId`; otherwise read from the API key. */
+    workspaceId?: string;
+    fetch?: Fetcher;
+    /** Copied, never modified. Can't be combined with `fetch`. */
+    httpClient?: HTTPClient;
+    /** Timeout for each attempt of a request; retries get a fresh one. */
+    timeoutMs?: number;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+}
+export interface CreateOptions extends CallOptions {
+    idempotencyKey?: string;
+    workspaceId?: string;
+}
+export type ListEnvironmentsQuery = Omit<ListEnvironmentsRequest, 'workspaceId'> & {
+    workspaceId?: string;
+};
+export interface Page<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+export interface ConnectOptions extends CallOptions {
+    actorId?: string;
+    apiId?: string;
+}
+export declare class StateMachines {
+    #private;
+    constructor(options?: StateMachinesOptions);
+    readonly credential: {
+        get: (options?: CallOptions | undefined) => Promise<Credential>;
+    };
+    readonly catalog: {
+        get: (options?: CallOptions | undefined) => Promise<Catalog>;
+        release: (releaseId: string, options?: CallOptions | undefined) => Promise<Release>;
+    };
+    readonly workspaces: {
+        list: (query?: ListWorkspacesRequest, options?: CallOptions | undefined) => Promise<Workspace[]>;
+        get: (workspaceId: string, options?: CallOptions | undefined) => Promise<Workspace>;
+        events: (workspaceId: string, query?: {
+            limit?: number;
+            cursor?: string;
+        }, options?: CallOptions | undefined) => Promise<EventPage>;
+    };
+    readonly environments: {
+        list: (query?: ListEnvironmentsQuery, options?: CallOptions | undefined) => Promise<Page<Environment>>;
+        get: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        /** Every failure carries the `idempotencyKey`; replaying the create with it is safe. */
+        create: (input: CreateEnvironmentInput, options?: CreateOptions) => Promise<Environment>;
+        stop: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        events: (environmentId: string, query?: {
+            limit?: number;
+            cursor?: string;
+        }, options?: CallOptions | undefined) => Promise<EventPage>;
+        getConnection: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ConnectionDetails>;
+        reveal: (environmentId: string, appKey: string, actorId: string, options?: CallOptions | undefined) => Promise<ConnectionSecret>;
+        /** Resolves when the environment is running. Never stops it. */
+        waitUntilReady: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
+        /** Resolves when the environment ended and every sandbox is confirmed disposed. */
+        waitUntilStopped: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
+        connect: (environmentId: string, appKey: string, options?: ConnectOptions) => Promise<Connection>;
+    };
+}

package/esm/extensions/client.js

@@ -0,0 +1,213 @@
+import { SDK_METADATA } from '../lib/config.js';
+import { HTTPClient } from '../lib/http.js';
+import { StateMachines as Generated } from '../sdk/sdk.js';
+import { Connection } from './connection.js';
+import { StateMachinesError, toStateMachinesError } from './errors.js';
+import { linkSignal } from './signal.js';
+import { disposed, poll, ready } from './wait.js';
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+class CallerAbortedError extends Error {
+    name = 'CallerAbortedError';
+    constructor(reason) {
+        super('The caller aborted the request.', { cause: reason });
+    }
+}
+export class StateMachines {
+    #sdk;
+    #fetch;
+    #workspaceId;
+    #credentialWorkspace;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? environmentApiKey();
+        if (!apiKey) {
+            throw new TypeError('Pass apiKey or set STATE_API_KEY.');
+        }
+        // Checked here so a malformed key is never echoed by a header validation error.
+        if (!/^[\x21-\x7e]+$/.test(apiKey)) {
+            throw new TypeError('apiKey must be printable ASCII with no spaces.');
+        }
+        if (options.fetch && options.httpClient) {
+            throw new TypeError('Pass fetch or httpClient, not both.');
+        }
+        const fetcher = options.fetch;
+        // The arrow keeps `this` unbound; runtimes such as workerd reject fetch called on another object.
+        const timeoutMs = options.timeoutMs ?? 60000;
+        if (!(timeoutMs > 0 && Number.isFinite(timeoutMs))) {
+            throw new RangeError('timeoutMs must be a positive, finite number.');
+        }
+        const httpClient = options.httpClient?.clone() ??
+            new HTTPClient(fetcher ? { fetcher: (input) => fetcher(input) } : {});
+        addAttemptTimeout(httpClient, timeoutMs);
+        this.#fetch = fetcher;
+        this.#workspaceId = options.workspaceId;
+        this.#sdk = new Generated({
+            apiKey,
+            userAgent: `statemachines-sdk-ts/${SDK_METADATA.sdkVersion}`,
+            httpClient,
+            ...(options.serverURL ? { serverURL: options.serverURL } : {}),
+        });
+    }
+    credential = {
+        get: (options) => this.#unwrap(options, (call) => this.#sdk.credential.get(call)),
+    };
+    catalog = {
+        get: (options) => this.#unwrap(options, (call) => this.#sdk.catalog.get(call)),
+        release: (releaseId, options) => this.#unwrap(options, (call) => this.#sdk.catalog.release({ releaseId }, call)),
+    };
+    workspaces = {
+        list: (query = {}, options) => this.#unwrap(options, (call) => this.#sdk.workspaces.list(query, call)),
+        get: (workspaceId, options) => this.#unwrap(options, (call) => this.#sdk.workspaces.get({ workspaceId }, call)),
+        events: (workspaceId, query = {}, options) => this.#call(options, (call) => this.#sdk.workspaces.events({ ...query, workspaceId }, call)),
+    };
+    environments = {
+        list: (query = {}, options) => this.#call(options, async (call) => {
+            const { workspaceId, ...filters } = query;
+            const resolved = await this.#workspace(workspaceId, call.signal);
+            return this.#sdk.environments.list({ ...filters, workspaceId: resolved }, call);
+        }),
+        get: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.get({ environmentId }, call)),
+        /** Every failure carries the `idempotencyKey`; replaying the create with it is safe. */
+        create: async (input, options = {}) => {
+            const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+            try {
+                return await this.#call(options, async (call) => {
+                    const workspaceId = await this.#workspace(options.workspaceId, call.signal);
+                    const { data } = await this.#sdk.environments.create({ workspaceId, idempotencyKey, body: input }, call);
+                    const [environment] = data;
+                    if (!environment) {
+                        throw new Error('Invalid response from the State API: the create returned no environment.');
+                    }
+                    return environment;
+                });
+            }
+            catch (error) {
+                // Always a new instance: concurrent creates can share one failed workspace lookup.
+                throw new StateMachinesError(error, { idempotencyKey });
+            }
+        },
+        stop: (environmentId, options) => this.#unwrap(options, (call) => this.#sdk.environments.stop({ environmentId }, call)),
+        events: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.events({ ...query, environmentId }, call)),
+        getConnection: (environmentId, appKey, options) => this.#unwrap(options, (call) => this.#sdk.environments.getConnection({ environmentId, appKey }, call)),
+        reveal: (environmentId, appKey, actorId, options) => this.#unwrap(options, (call) => this.#sdk.environments.reveal({ environmentId, appKey, body: { actorId } }, call)),
+        /** Resolves when the environment is running. Never stops it. */
+        waitUntilReady: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), ready, options),
+        /** Resolves when the environment ended and every sandbox is confirmed disposed. */
+        waitUntilStopped: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), disposed, options),
+        connect: async (environmentId, appKey, options = {}) => {
+            const details = await this.environments.getConnection(environmentId, appKey, options);
+            if (details.status !== 'ready' || !details.baseUrl) {
+                throw new TypeError(`App ${appKey} is not ready to connect (${details.status}).`);
+            }
+            const actor = pick('actor', details.actors, options.actorId);
+            const api = pick('API', details.apis, options.apiId);
+            const secret = await this.environments.reveal(environmentId, appKey, actor.id, options);
+            return new Connection(details.baseUrl, api, secret, this.#fetch);
+        },
+    };
+    /** One read for the poller, which owns retries, timing and the caller's signal. */
+    #poll(environmentId, signal) {
+        return this.#unwrap({ signal }, (call) => this.#sdk.environments.get({ environmentId }, { ...call, retries: { strategy: 'none' } }));
+    }
+    /** Resolves the workspace once per client; a failed lookup is retried by the next call. */
+    #workspace(explicit, signal) {
+        const workspaceId = explicit ?? this.#workspaceId;
+        if (workspaceId) {
+            return Promise.resolve(workspaceId);
+        }
+        this.#credentialWorkspace ?? (this.#credentialWorkspace = this.#lookupWorkspace());
+        // The lookup is shared, so one caller's abort only stops that caller waiting.
+        return abortable(this.#credentialWorkspace, signal);
+    }
+    #lookupWorkspace() {
+        const lookup = this.credential.get().then((credential) => {
+            if (!credential.workspaceId) {
+                throw new TypeError('This credential has no workspace. Pass workspaceId, or use a workspace API key.');
+            }
+            return credential.workspaceId;
+        });
+        lookup.catch(() => {
+            if (this.#credentialWorkspace === lookup) {
+                this.#credentialWorkspace = undefined;
+            }
+        });
+        return lookup;
+    }
+    #unwrap(options, run) {
+        return this.#call(options, async (call) => (await run(call)).data);
+    }
+    /**
+     * Runs one API call under its own signal. Closing it when the call settles
+     * releases every attempt's timeout timer and listener.
+     */
+    async #call(options, run) {
+        const scope = linkSignal(options?.signal);
+        try {
+            return await run({ signal: scope.signal });
+        }
+        catch (error) {
+            // A caller abort can surface as a raw TimeoutError while a body is read; it is never retryable.
+            throw toStateMachinesError(options?.signal?.aborted
+                ? new CallerAbortedError(options.signal.reason)
+                : error);
+        }
+        finally {
+            scope.close();
+        }
+    }
+}
+/**
+ * Gives each attempt its own timeout, linked to the caller's signal. The generated
+ * `timeoutMs` is never used: it is dropped when a caller passes a signal.
+ */
+function addAttemptTimeout(httpClient, timeoutMs) {
+    const callers = new WeakMap();
+    httpClient.addHook('beforeRequest', (request) => {
+        const caller = request.signal;
+        if (caller.aborted) {
+            throw new CallerAbortedError(caller.reason);
+        }
+        const attempt = new Request(request, {
+            signal: linkSignal(caller, timeoutMs).signal,
+        });
+        callers.set(attempt, caller);
+        return attempt;
+    });
+    // Without this, a timeout-shaped abort reason looks like a retryable timeout to the generated loop.
+    httpClient.addHook('requestError', (_error, request) => {
+        const caller = callers.get(request);
+        if (caller?.aborted) {
+            throw new CallerAbortedError(caller.reason);
+        }
+    });
+}
+function abortable(promise, signal) {
+    if (!signal) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+function pick(kind, choices, id) {
+    const found = id
+        ? choices.find((choice) => choice.id === id)
+        : choices.length === 1
+            ? choices[0]
+            : undefined;
+    if (!found) {
+        throw new TypeError(`Choose one ${kind}: ${choices.map((choice) => choice.id).join(', ') || 'none available'}.`);
+    }
+    return found;
+}
+function environmentApiKey() {
+    const runtime = globalThis;
+    return runtime.process?.env?.STATE_API_KEY;
+}

package/esm/extensions/connection.d.ts

@@ -0,0 +1,42 @@
+import type { Fetcher } from '../lib/http.js';
+import type { ApiProfile } from '../models/api-profile.js';
+import type { ConnectionSecret } from '../models/connection-secret.js';
+/**
+ * The HTTP header an app's API expects for its actor token, or `null` when the token goes in
+ * the request body instead: for `SOAP SessionHeader`, as the envelope's `SessionHeader/sessionId`.
+ */
+export declare function formatActorHeader(actorHeader: string, token: string): {
+    name: string;
+    value: string;
+} | null;
+/** A live app connection. `fetch` only reaches paths under `baseUrl`. */
+export declare class Connection {
+    #private;
+    readonly baseUrl: string;
+    readonly environmentId: string;
+    readonly appKey: string;
+    readonly actorId: string;
+    readonly api: ApiProfile;
+    readonly expiresAt: Date;
+    constructor(baseUrl: string, api: ApiProfile, secret: ConnectionSecret, fetch?: Fetcher);
+    /**
+     * The headers the gateway and the app need, for clients that can't use `fetch`. For an API
+     * whose actor token goes in the request body, such as SOAP, only the environment token.
+     */
+    headers(): Record<string, string>;
+    /**
+     * The live actor token, for APIs that take it in the request body: for a SOAP API, put it in
+     * the envelope's `SessionHeader/sessionId`. Treat it as a secret.
+     */
+    actorToken(): string;
+    /** Sends one request to the app. Never retries, never follows redirects, never adds the API key. */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    toJSON(): {
+        baseUrl: string;
+        environmentId: string;
+        appKey: string;
+        actorId: string;
+        api: ApiProfile;
+        expiresAt: Date;
+    };
+}

package/esm/extensions/connection.js

@@ -0,0 +1,133 @@
+const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// Salesforce's SOAP API takes the actor token in the envelope, not an HTTP header.
+const SOAP_SESSION_HEADER = 'SOAP SessionHeader';
+// Visible ASCII only: `Headers` would otherwise echo a bad value, token included, in its error.
+const TOKEN_VALUE = /^[\x21-\x7e]+$/;
+// Checked on the path part only (C7). 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 = 'Connection.fetch only reaches paths under the connection baseUrl.';
+/**
+ * The HTTP header an app's API expects for its actor token, or `null` when the token goes in
+ * the request body instead: for `SOAP SessionHeader`, as the envelope's `SessionHeader/sessionId`.
+ */
+export function formatActorHeader(actorHeader, token) {
+    if (actorHeader === SOAP_SESSION_HEADER) {
+        return null;
+    }
+    if (!HTTP_TOKEN.test(actorHeader) ||
+        actorHeader.toLowerCase().startsWith('x-state-')) {
+        throw new TypeError('The API profile names an invalid actor header.');
+    }
+    return actorHeader.toLowerCase() === 'authorization'
+        ? { name: 'Authorization', value: `Bearer ${token}` }
+        : { name: actorHeader, value: token };
+}
+/** A live app connection. `fetch` only reaches paths under `baseUrl`. */
+export class Connection {
+    baseUrl;
+    environmentId;
+    appKey;
+    actorId;
+    api;
+    expiresAt;
+    #base;
+    #environmentToken;
+    #actorToken;
+    #actor;
+    #fetch;
+    constructor(baseUrl, api, secret, fetch) {
+        const base = URL.canParse(baseUrl) ? new URL(baseUrl) : null;
+        if (!base ||
+            !/^https?:$/.test(base.protocol) ||
+            base.username ||
+            base.password ||
+            base.search ||
+            base.hash) {
+            throw new TypeError('The connection baseUrl is not a plain http(s) URL.');
+        }
+        if (!TOKEN_VALUE.test(secret.environmentToken) ||
+            !TOKEN_VALUE.test(secret.actorToken)) {
+            throw new TypeError('The connection tokens are malformed.');
+        }
+        if (!base.pathname.endsWith('/')) {
+            base.pathname += '/';
+        }
+        this.#base = base;
+        this.#environmentToken = secret.environmentToken;
+        this.#actorToken = secret.actorToken;
+        this.#actor = formatActorHeader(api.actorHeader, secret.actorToken);
+        this.#fetch = fetch;
+        this.baseUrl = base.href;
+        this.environmentId = secret.environmentId;
+        this.appKey = secret.appKey;
+        this.actorId = secret.actorId;
+        this.api = api;
+        this.expiresAt = secret.expiresAt;
+    }
+    /**
+     * The headers the gateway and the app need, for clients that can't use `fetch`. For an API
+     * whose actor token goes in the request body, such as SOAP, only the environment token.
+     */
+    headers() {
+        return {
+            'X-State-Environment-Token': this.#environmentToken,
+            ...(this.#actor ? { [this.#actor.name]: this.#actor.value } : {}),
+        };
+    }
+    /**
+     * The live actor token, for APIs that take it in the request body: for a SOAP API, put it in
+     * the envelope's `SessionHeader/sessionId`. Treat it as a secret.
+     */
+    actorToken() {
+        return this.#actorToken;
+    }
+    /** Sends one request to the app. Never retries, never follows redirects, never adds the API key. */
+    async fetch(path, init = {}) {
+        const url = this.#resolve(path);
+        const headers = new Headers(init.headers);
+        for (const name of headers.keys()) {
+            if (name.startsWith('x-state-')) {
+                throw new TypeError(`Header ${name} is reserved for State.`);
+            }
+        }
+        // Ours go last so a caller header of the same name can't replace them.
+        for (const [name, value] of Object.entries(this.headers())) {
+            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 this.#fetch ? this.#fetch(request) : globalThis.fetch(request);
+    }
+    toJSON() {
+        return {
+            baseUrl: this.baseUrl,
+            environmentId: this.environmentId,
+            appKey: this.appKey,
+            actorId: this.actorId,
+            api: this.api,
+            expiresAt: this.expiresAt,
+        };
+    }
+    #resolve(path) {
+        const pathPart = path.split(/[?#]/, 1)[0] ?? '';
+        if (UNSAFE_PATH.test(pathPart)) {
+            throw new TypeError(OUTSIDE);
+        }
+        // A leading `/` means the root of the connection, not of the gateway.
+        const relative = path.startsWith('/') ? `.${path}` : path;
+        // `URL` errors carry the input, query included, so they are replaced rather than rethrown.
+        const url = URL.canParse(relative, this.#base)
+            ? new URL(relative, this.#base)
+            : null;
+        if (!url ||
+            url.origin !== this.#base.origin ||
+            url.username ||
+            url.password ||
+            !url.pathname.startsWith(this.#base.pathname) ||
+            UNSAFE_PATH.test(url.pathname)) {
+            throw new TypeError(OUTSIDE);
+        }
+        return url;
+    }
+}

package/esm/extensions/errors.d.ts

@@ -0,0 +1,52 @@
+import type { Environment } from '../models/environment.js';
+import type { Code } from '../models/error-response.js';
+interface Details {
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly status: number | null;
+    readonly code: Code | null;
+    readonly requestId: string | null;
+    readonly fields: Record<string, string[]> | null;
+    readonly retryAfter: number | null;
+    readonly retryable: boolean;
+    readonly idempotencyKey?: string;
+}
+/**
+ * Any failed API call: an error response, an invalid response, or no response at
+ * all (`status` null). The message never includes a response body.
+ */
+export declare class StateMachinesError extends Error implements Details {
+    readonly name = "StateMachinesError";
+    readonly status: number | null;
+    readonly code: Code | null;
+    readonly requestId: string | null;
+    readonly fields: Record<string, string[]> | null;
+    /** Milliseconds the server asked the client to wait. */
+    readonly retryAfter: number | null;
+    /** Transient: a 502, 503 or 504, or the request never got a response. */
+    readonly retryable: boolean;
+    /** Set on `environments.create` failures; replay the create with it to recover. */
+    readonly idempotencyKey?: string;
+    /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
+    constructor(error: unknown, extra?: {
+        idempotencyKey?: string;
+    });
+}
+export declare function toStateMachinesError(error: unknown): StateMachinesError;
+export declare class EnvironmentFailedError extends Error {
+    readonly environment: Environment;
+    readonly name = "EnvironmentFailedError";
+    constructor(environment: Environment);
+}
+export declare class DisposalIncompleteError extends Error {
+    readonly environment: Environment;
+    readonly name = "DisposalIncompleteError";
+    constructor(environment: Environment);
+}
+export declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly environment: Environment | null;
+    readonly name = "TimeoutError";
+    constructor(timeoutMs: number, environment: Environment | null);
+}
+export {};