@usestatemachines/sdk 0.1.1 → 0.3.0

package/esm/extensions/client.d.ts

@@ -2,15 +2,21 @@ 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 { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { EventPage } from '../models/event-page.js';
+import type { CaptureSnapshotRequestBody } from '../models/operations/capture-snapshot.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
+import type { ListSnapshotsRequest } from '../models/operations/list-snapshots.js';
 import type { ListWorkspacesRequest } from '../models/operations/list-workspaces.js';
+import type { UpdateSnapshotRequestBody } from '../models/operations/update-snapshot.js';
 import type { Release } from '../models/release.js';
+import type { ReleaseActor } from '../models/release-actor.js';
 import type { Workspace } from '../models/workspace.js';
+import { type EnvironmentSource } from './apps.js';
 import { Connection } from './connection.js';
+import { RunningEnvironment } from './running-environment.js';
 import { type WaitOptions } from './wait.js';
 export interface StateMachinesOptions {
     /** Workspace API key. Defaults to `STATE_API_KEY` where a `process` exists. */
@@ -38,8 +44,20 @@ export interface Page<T> {
     data: T[];
     nextCursor: string | null;
 }
+export interface StartOptions extends CreateOptions {
+    /** Deadline for the whole wait for readiness. Defaults to 10 minutes. */
+    readyTimeoutMs?: number;
+}
+export type CaptureInput = Omit<CaptureSnapshotRequestBody, 'environmentId'>;
+/** `readyTimeoutMs` bounds the wait for `ready`, as in `start()`. */
+export type CaptureOptions = StartOptions;
+export type ListSnapshotsQuery = Omit<ListSnapshotsRequest, 'workspaceId'> & {
+    workspaceId?: string;
+};
 export interface ConnectOptions extends CallOptions {
+    /** Defaults to the actor of the environment's declared default connection, else the app's first actor. */
     actorId?: string;
+    /** Required when the app has more than one API, as Salesforce does. */
     apiId?: string;
 }
 export declare class StateMachines {
@@ -63,19 +81,64 @@ export declare class StateMachines {
     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>;
+        /**
+         * Creates an environment and waits until it's running. If the wait fails, stops the
+         * environment (unless the caller passed its own `idempotencyKey`), then rethrows the
+         * error with `environmentId`, `stopped` and `stopError`.
+         */
+        start: (input: EnvironmentSource, options?: StartOptions) => Promise<RunningEnvironment>;
+        /**
+         * A string app is shorthand for `{ key: <the string>, appId: <the string> }`. Every
+         * failure carries the `idempotencyKey`; replaying the create with it is safe.
+         */
+        create: (input: EnvironmentSource, 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>;
+        /** The app's users, in the release's order. */
+        actors: (environmentId: string, appKey: string, options?: CallOptions | undefined) => Promise<ReleaseActor[]>;
         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>;
+        /**
+         * actorId defaults to the actor of the environment's declared default connection, or
+         * else the app's first actor (for Salesforce, the administrator). Pick another from
+         * actors() to act with that user's permissions.
+         */
         connect: (environmentId: string, appKey: string, options?: ConnectOptions) => Promise<Connection>;
     };
+    readonly snapshots: {
+        /** Returns the API's answer at once: it may still be `capturing`. */
+        create: (environmentId: string, input?: CaptureInput, options?: CreateOptions) => Promise<EnvironmentSnapshot>;
+        /**
+         * Creates a snapshot and waits until it's `ready`. Needs `snapshots:create` and
+         * `snapshots:read`. A failed or timed-out snapshot is never deleted: the error
+         * carries `snapshotId` and `idempotencyKey`.
+         */
+        capture: (environmentId: string, input?: CaptureInput, options?: StartOptions) => Promise<EnvironmentSnapshot>;
+        /** Resolves when the snapshot is `ready`. Never deletes it. */
+        waitUntilReady: (snapshotId: string, options?: WaitOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Deleted snapshots too, with `deletedAt` set. */
+        get: (snapshotId: string, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Newest first. Deleted snapshots are left out. */
+        list: (query?: ListSnapshotsQuery, options?: CallOptions | undefined) => Promise<Page<EnvironmentSnapshot>>;
+        /**
+         * `null` clears the name. A stale `expectedVersion`, or a deleted snapshot, is a 409
+         * `version-conflict`; so is a retry of a rename whose first answer was lost.
+         */
+        rename: (snapshotId: string, body: UpdateSnapshotRequestBody, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+        /** Marks the snapshot deleted and returns it; safe to repeat. A capturing snapshot is a 409 `not-ready`. */
+        delete: (snapshotId: string, options?: CallOptions | undefined) => Promise<EnvironmentSnapshot>;
+    };
 }
+/**
+ * Names the call a request belongs to. Never sent: the attempt hook removes it.
+ * Needed because the generated loop clones each attempt, and after a garbage
+ * collection a clone's signal no longer follows the call's (Node 20 and 24).
+ */
+export declare const CALL_HEADER = "x-statemachines-call";

package/esm/extensions/client.js

@@ -1,21 +1,20 @@
 import { SDK_METADATA } from '../lib/config.js';
 import { HTTPClient } from '../lib/http.js';
 import { StateMachines as Generated } from '../sdk/sdk.js';
+import { expandSource } from './apps.js';
 import { Connection } from './connection.js';
-import { StateMachinesError, toStateMachinesError } from './errors.js';
+import { CallerAbortedError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, toStateMachinesError, } from './errors.js';
+import { RunningEnvironment } from './running-environment.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 });
-    }
-}
+import { backoff, defaultTimeoutMs, disposed, poll, pollUntil, ready, sleep, snapshotReady, } from './wait.js';
+const stopAfterFailureMs = 30000;
+const busyBudgetMs = 60000;
 export class StateMachines {
     #sdk;
     #fetch;
     #workspaceId;
+    #callSignals = new Map();
+    #lastCall = 0;
     #credentialWorkspace;
     constructor(options = {}) {
         const apiKey = options.apiKey ?? environmentApiKey();
@@ -37,7 +36,7 @@ export class StateMachines {
         }
         const httpClient = options.httpClient?.clone() ??
             new HTTPClient(fetcher ? { fetcher: (input) => fetcher(input) } : {});
-        addAttemptTimeout(httpClient, timeoutMs);
+        addAttemptTimeout(httpClient, timeoutMs, this.#callSignals);
         this.#fetch = fetcher;
         this.#workspaceId = options.workspaceId;
         this.#sdk = new Generated({
@@ -66,13 +65,56 @@ export class StateMachines {
             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. */
+        /**
+         * Creates an environment and waits until it's running. If the wait fails, stops the
+         * environment (unless the caller passed its own `idempotencyKey`), then rethrows the
+         * error with `environmentId`, `stopped` and `stopError`.
+         */
+        start: async (input, options = {}) => {
+            const { readyTimeoutMs, ...createOptions } = options;
+            const { idempotencyKey, signal } = options;
+            const timeoutMs = readyTimeoutMs ?? defaultTimeoutMs;
+            if (!(timeoutMs > 0)) {
+                throw new RangeError('readyTimeoutMs must be more than 0.');
+            }
+            const created = await this.environments.create(input, createOptions);
+            try {
+                const environment = await this.environments.waitUntilReady(created.id, {
+                    timeoutMs,
+                    ...(signal ? { signal } : {}),
+                });
+                return new RunningEnvironment(this, environment);
+            }
+            catch (error) {
+                // The API replays a create by key, returning the same environment to another
+                // start() that may still be using it, so only the SDK's own key allows a stop.
+                const outcome = idempotencyKey === undefined
+                    ? await this.#stopAfterFailure(created.id)
+                    : { environmentId: created.id, stopped: false };
+                const isCallerReason = signal?.aborted && Object.is(error, signal.reason);
+                if (isCallerReason) {
+                    if (outcome.stopped) {
+                        throw error;
+                    }
+                    throw Object.assign(new StateMachinesError(new CallerAbortedError(error)), outcome);
+                }
+                if (isStartError(error) && Object.isExtensible(error)) {
+                    Object.assign(error, outcome);
+                }
+                throw error;
+            }
+        },
+        /**
+         * A string app is shorthand for `{ key: <the string>, appId: <the string> }`. Every
+         * failure carries the `idempotencyKey`; replaying the create with it is safe.
+         */
         create: async (input, options = {}) => {
             const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
             try {
+                const body = expandSource(input);
                 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 { data } = await this.#sdk.environments.create({ workspaceId, idempotencyKey, body }, call);
                     const [environment] = data;
                     if (!environment) {
                         throw new Error('Invalid response from the State API: the create returned no environment.');
@@ -87,23 +129,142 @@ export class StateMachines {
         },
         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)),
+        /** The app's users, in the release's order. */
+        actors: async (environmentId, appKey, options) => (await this.environments.getConnection(environmentId, appKey, options))
+            .actors,
         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)),
+        reveal: (environmentId, appKey, actorId, options) => this.#reveal(environmentId, appKey, { actorId }, options),
         /** 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),
+        /**
+         * actorId defaults to the actor of the environment's declared default connection, or
+         * else the app's first actor (for Salesforce, the administrator). Pick another from
+         * actors() to act with that user's permissions.
+         */
         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);
+            // The API resolves { actorId } to that actor's first connection, not the declared one.
+            const body = options.actorId === undefined && details.defaultConnection
+                ? { connectionKey: details.defaultConnection }
+                : { actorId: pickActor(appKey, details.actors, options.actorId).id };
+            const api = pickApi(appKey, details.apis, options.apiId);
+            const secret = await this.#reveal(environmentId, appKey, body, options);
             return new Connection(details.baseUrl, api, secret, this.#fetch);
         },
     };
+    snapshots = {
+        /** Returns the API's answer at once: it may still be `capturing`. */
+        create: (environmentId, input = {}, options = {}) => this.#createSnapshot(environmentId, input, options, 0),
+        /**
+         * Creates a snapshot and waits until it's `ready`. Needs `snapshots:create` and
+         * `snapshots:read`. A failed or timed-out snapshot is never deleted: the error
+         * carries `snapshotId` and `idempotencyKey`.
+         */
+        capture: async (environmentId, input = {}, options = {}) => {
+            const { readyTimeoutMs, ...createOptions } = options;
+            const { signal } = options;
+            const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+            const timeoutMs = readyTimeoutMs ?? defaultTimeoutMs;
+            if (!(timeoutMs > 0)) {
+                throw new RangeError('readyTimeoutMs must be more than 0.');
+            }
+            const created = await this.#createSnapshot(environmentId, input, { ...createOptions, idempotencyKey }, busyBudgetMs);
+            try {
+                signal?.throwIfAborted();
+                if (snapshotReady(created)) {
+                    return created;
+                }
+                return await this.snapshots.waitUntilReady(created.id, {
+                    timeoutMs,
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (error) {
+                const snapshotId = created.id;
+                if (signal?.aborted && Object.is(error, signal.reason)) {
+                    throw Object.assign(new StateMachinesError(new CallerAbortedError(error), {
+                        idempotencyKey,
+                    }), { snapshotId });
+                }
+                if (error instanceof StateMachinesError ||
+                    error instanceof SnapshotFailedError ||
+                    error instanceof SnapshotTimeoutError) {
+                    Object.assign(error, { snapshotId, idempotencyKey });
+                }
+                throw error;
+            }
+        },
+        /** Resolves when the snapshot is `ready`. Never deletes it. */
+        waitUntilReady: (snapshotId, options) => pollUntil((signal) => this.#unwrap({ signal }, (call) => this.#sdk.snapshots.get({ snapshotId }, { ...call, retries: { strategy: 'none' } })), snapshotReady, options, (timeoutMs, last) => new SnapshotTimeoutError(timeoutMs, last, snapshotId)),
+        /** Deleted snapshots too, with `deletedAt` set. */
+        get: (snapshotId, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.get({ snapshotId }, call)),
+        /** Newest first. Deleted snapshots are left out. */
+        list: (query = {}, options) => this.#call(options, async (call) => {
+            const { workspaceId, ...filters } = query;
+            const resolved = await this.#workspace(workspaceId, call.signal);
+            return this.#sdk.snapshots.list({ ...filters, workspaceId: resolved }, call);
+        }),
+        /**
+         * `null` clears the name. A stale `expectedVersion`, or a deleted snapshot, is a 409
+         * `version-conflict`; so is a retry of a rename whose first answer was lost.
+         */
+        rename: (snapshotId, body, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.update({ snapshotId, body }, call)),
+        /** Marks the snapshot deleted and returns it; safe to repeat. A capturing snapshot is a 409 `not-ready`. */
+        delete: (snapshotId, options) => this.#unwrap(options, (call) => this.#sdk.snapshots.delete({ snapshotId }, call)),
+    };
+    async #createSnapshot(environmentId, input, options, busyMs) {
+        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+        try {
+            return await this.#call(options, async (call) => {
+                const workspaceId = await this.#workspace(options.workspaceId, call.signal);
+                const request = {
+                    workspaceId,
+                    idempotencyKey,
+                    body: { ...input, environmentId },
+                };
+                const deadline = Date.now() + busyMs;
+                for (let attempt = 0;; attempt += 1) {
+                    try {
+                        return (await this.#sdk.snapshots.capture(request, call)).data;
+                    }
+                    catch (error) {
+                        const busy = toStateMachinesError(error);
+                        const waitMs = Math.max(busy.retryAfter ?? 0, backoff(attempt));
+                        if (busy.code !== 'snapshot-limit' ||
+                            Date.now() + waitMs >= deadline) {
+                            throw error;
+                        }
+                        await sleep(waitMs, call.signal);
+                    }
+                }
+            });
+        }
+        catch (error) {
+            throw new StateMachinesError(error, { idempotencyKey });
+        }
+    }
+    #reveal(environmentId, appKey, body, options) {
+        return this.#unwrap(options, (call) => this.#sdk.environments.reveal({ environmentId, appKey, body }, call));
+    }
+    async #stopAfterFailure(environmentId) {
+        const budget = linkSignal(undefined, stopAfterFailureMs);
+        try {
+            // abortable() ends the wait at the budget even during a retry delay.
+            await abortable(this.environments.stop(environmentId, { signal: budget.signal }), budget.signal);
+            return { environmentId, stopped: true };
+        }
+        catch (stopError) {
+            return { environmentId, stopped: false, stopError };
+        }
+        finally {
+            budget.dispose();
+        }
+    }
     /** 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' } }));
@@ -141,8 +302,13 @@ export class StateMachines {
      */
     async #call(options, run) {
         const scope = linkSignal(options?.signal);
+        const id = String(++this.#lastCall);
+        this.#callSignals.set(id, scope.signal);
         try {
-            return await run({ signal: scope.signal });
+            return await run({
+                signal: scope.signal,
+                headers: { [CALL_HEADER]: id },
+            });
         }
         catch (error) {
             // A caller abort can surface as a raw TimeoutError while a body is read; it is never retryable.
@@ -151,35 +317,53 @@ export class StateMachines {
                 : error);
         }
         finally {
+            this.#callSignals.delete(id);
             scope.close();
         }
     }
 }
 /**
- * Gives each attempt its own timeout, linked to the caller's signal. The generated
+ * Names the call a request belongs to. Never sent: the attempt hook removes it.
+ * Needed because the generated loop clones each attempt, and after a garbage
+ * collection a clone's signal no longer follows the call's (Node 20 and 24).
+ */
+export const CALL_HEADER = 'x-statemachines-call';
+/**
+ * Gives each attempt its own timeout, linked to its call's signal. The generated
  * `timeoutMs` is never used: it is dropped when a caller passes a signal.
  */
-function addAttemptTimeout(httpClient, timeoutMs) {
+function addAttemptTimeout(httpClient, timeoutMs, calls) {
     const callers = new WeakMap();
     httpClient.addHook('beforeRequest', (request) => {
-        const caller = request.signal;
-        if (caller.aborted) {
-            throw new CallerAbortedError(caller.reason);
+        const headers = new Headers(request.headers);
+        const call = calls.get(headers.get(CALL_HEADER) ?? '');
+        // The request's own signal still counts: a caller's hook may have set it.
+        const sources = call ? [call, request.signal] : [request.signal];
+        const aborted = sources.find(({ aborted }) => aborted);
+        headers.delete(CALL_HEADER);
+        if (aborted) {
+            throw new CallerAbortedError(aborted.reason);
         }
         const attempt = new Request(request, {
-            signal: linkSignal(caller, timeoutMs).signal,
+            headers,
+            signal: linkSignal(sources, timeoutMs).signal,
         });
-        callers.set(attempt, caller);
+        callers.set(attempt, sources);
         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);
+        const aborted = callers.get(request)?.find(({ aborted }) => aborted);
+        if (aborted) {
+            throw new CallerAbortedError(aborted.reason);
         }
     });
 }
+function isStartError(error) {
+    return (error instanceof StateMachinesError ||
+        error instanceof EnvironmentFailedError ||
+        error instanceof TimeoutError);
+}
 function abortable(promise, signal) {
     if (!signal) {
         return promise;
@@ -196,16 +380,33 @@ function abortable(promise, signal) {
             .finally(() => signal.removeEventListener('abort', onAbort));
     });
 }
-function pick(kind, choices, id) {
-    const found = id
-        ? choices.find((choice) => choice.id === id)
-        : choices.length === 1
-            ? choices[0]
+function pickActor(appKey, actors, actorId) {
+    const [first] = actors;
+    if (!first) {
+        throw new TypeError(`App ${appKey} has no actors.`);
+    }
+    if (actorId === undefined) {
+        return first;
+    }
+    const actor = actors.find(({ id }) => id === actorId);
+    if (!actor) {
+        throw new TypeError(`Unknown actor ${actorId} for ${appKey}. Choose one of: ${ids(actors)}.`);
+    }
+    return actor;
+}
+function pickApi(appKey, apis, apiId) {
+    const api = apiId
+        ? apis.find(({ id }) => id === apiId)
+        : apis.length === 1
+            ? apis[0]
             : undefined;
-    if (!found) {
-        throw new TypeError(`Choose one ${kind}: ${choices.map((choice) => choice.id).join(', ') || 'none available'}.`);
+    if (!api) {
+        throw new TypeError(`Choose one API for ${appKey}: ${ids(apis) || 'none available'}.`);
     }
-    return found;
+    return api;
+}
+function ids(choices) {
+    return choices.map(({ id }) => id).join(', ');
 }
 function environmentApiKey() {
     const runtime = globalThis;

package/esm/extensions/errors.d.ts

@@ -1,5 +1,15 @@
 import type { Environment } from '../models/environment.js';
+import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
 import type { Code } from '../models/error-response.js';
+/** What `environments.start()` adds to the error it rethrows after a failed wait. */
+export interface StartFailure {
+    /** The environment the start created. */
+    readonly environmentId?: string;
+    /** Whether the stop request succeeded. Disposal may still be in progress. */
+    readonly stopped?: boolean;
+    /** Why the stop request failed, when it did. */
+    readonly stopError?: unknown;
+}
 interface Details {
     readonly message: string;
     readonly cause?: unknown;
@@ -12,11 +22,17 @@ interface Details {
     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.
+ * Any failed API call: an error response, an invalid response, no response at all,
+ * or input the SDK rejected before sending (`status` null for the last three). The
+ * message never includes a response body.
  */
-export declare class StateMachinesError extends Error implements Details {
+export declare class StateMachinesError extends Error implements Details, StartFailure {
     readonly name = "StateMachinesError";
+    readonly environmentId?: string;
+    readonly stopped?: boolean;
+    readonly stopError?: unknown;
+    /** Set when `snapshots.capture()` fails after the snapshot was created. */
+    readonly snapshotId?: string;
     readonly status: number | null;
     readonly code: Code | null;
     readonly requestId: string | null;
@@ -25,7 +41,7 @@ export declare class StateMachinesError extends Error implements Details {
     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. */
+    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
     readonly idempotencyKey?: string;
     /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
     constructor(error: unknown, extra?: {
@@ -33,9 +49,12 @@ export declare class StateMachinesError extends Error implements Details {
     });
 }
 export declare function toStateMachinesError(error: unknown): StateMachinesError;
-export declare class EnvironmentFailedError extends Error {
+export declare class EnvironmentFailedError extends Error implements StartFailure {
     readonly environment: Environment;
     readonly name = "EnvironmentFailedError";
+    readonly environmentId?: string;
+    readonly stopped?: boolean;
+    readonly stopError?: unknown;
     constructor(environment: Environment);
 }
 export declare class DisposalIncompleteError extends Error {
@@ -43,10 +62,35 @@ export declare class DisposalIncompleteError extends Error {
     readonly name = "DisposalIncompleteError";
     constructor(environment: Environment);
 }
-export declare class TimeoutError extends Error {
+export declare class TimeoutError extends Error implements StartFailure {
     readonly timeoutMs: number;
     readonly environment: Environment | null;
     readonly name = "TimeoutError";
+    readonly environmentId?: string;
+    readonly stopped?: boolean;
+    readonly stopError?: unknown;
     constructor(timeoutMs: number, environment: Environment | null);
 }
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+export declare class CallerAbortedError extends Error {
+    readonly name = "CallerAbortedError";
+    constructor(reason: unknown);
+}
+/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
+export declare class SnapshotFailedError extends Error {
+    readonly snapshot: EnvironmentSnapshot;
+    readonly name = "SnapshotFailedError";
+    readonly snapshotId: string;
+    readonly idempotencyKey?: string;
+    constructor(snapshot: EnvironmentSnapshot);
+}
+/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
+export declare class SnapshotTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly snapshot: EnvironmentSnapshot | null;
+    readonly snapshotId: string;
+    readonly name = "SnapshotTimeoutError";
+    readonly idempotencyKey?: string;
+    constructor(timeoutMs: number, snapshot: EnvironmentSnapshot | null, snapshotId: string);
+}
 export {};

package/esm/extensions/errors.js

@@ -3,8 +3,9 @@ import { ConnectionError, RequestTimeoutError, } from '../models/errors/http-cli
 import { ResponseValidationError } from '../models/errors/response-validation-error.js';
 import { StateMachinesHTTPError } from '../models/errors/state-machines-http-error.js';
 /**
- * Any failed API call: an error response, an invalid response, or no response at
- * all (`status` null). The message never includes a response body.
+ * Any failed API call: an error response, an invalid response, no response at all,
+ * or input the SDK rejected before sending (`status` null for the last three). The
+ * message never includes a response body.
  */
 export class StateMachinesError extends Error {
     name = 'StateMachinesError';
@@ -16,7 +17,7 @@ export class StateMachinesError extends Error {
     retryAfter;
     /** Transient: a 502, 503 or 504, or the request never got a response. */
     retryable;
-    /** Set on `environments.create` failures; replay the create with it to recover. */
+    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
     idempotencyKey;
     /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
     constructor(error, extra = {}) {
@@ -127,3 +128,36 @@ export class TimeoutError extends Error {
         this.environment = environment;
     }
 }
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+export class CallerAbortedError extends Error {
+    name = 'CallerAbortedError';
+    constructor(reason) {
+        super('The caller aborted the request.', { cause: reason });
+    }
+}
+/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
+export class SnapshotFailedError extends Error {
+    snapshot;
+    name = 'SnapshotFailedError';
+    snapshotId;
+    constructor(snapshot) {
+        super(snapshot.status === 'failed'
+            ? `Snapshot ${snapshot.id} is failed (${snapshot.errorCode ?? 'no error code'}).`
+            : `Snapshot ${snapshot.id} was deleted.`);
+        this.snapshot = snapshot;
+        this.snapshotId = snapshot.id;
+    }
+}
+/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
+export class SnapshotTimeoutError extends Error {
+    timeoutMs;
+    snapshot;
+    snapshotId;
+    name = 'SnapshotTimeoutError';
+    constructor(timeoutMs, snapshot, snapshotId) {
+        super(`Timed out after ${timeoutMs} ms waiting for snapshot ${snapshotId}.`);
+        this.timeoutMs = timeoutMs;
+        this.snapshot = snapshot;
+        this.snapshotId = snapshotId;
+    }
+}

package/esm/extensions/index.d.ts

@@ -1,11 +1,13 @@
 export type { Fetcher, HTTPClientOptions } from '../lib/http.js';
 export { HTTPClient } from '../lib/http.js';
 export { ConnectionError, ErrorResponse, HTTPClientError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, ResponseValidationError, SDKValidationError, StateMachinesHTTPError, UnexpectedClientError, UnexpectedResponseError, } from '../models/errors/index.js';
-export type { ApiProfile, App, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
+export type { ApiProfile, App, AppInstanceSnapshot, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, EnvironmentSnapshot, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
 export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../models/index.js';
 export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
-export type { CallOptions, ConnectOptions, CreateOptions, ListEnvironmentsQuery, Page, StateMachinesOptions, } from './client.js';
+export type { AppInput, EnvironmentInput, SnapshotEnvironmentInput, } from './apps.js';
+export type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, CreateOptions, ListEnvironmentsQuery, ListSnapshotsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
 export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, StateMachinesError, TimeoutError, } from './errors.js';
+export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
+export { RunningEnvironment } from './running-environment.js';
 export type { WaitOptions } from './wait.js';

package/esm/extensions/index.js

@@ -4,4 +4,5 @@ export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../
 export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
 export { StateMachines } from './client.js';
 export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, StateMachinesError, TimeoutError, } from './errors.js';
+export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
+export { RunningEnvironment } from './running-environment.js';