@usestatemachines/sdk 0.5.0 → 0.6.1

package/esm/extensions/client.js

@@ -1,330 +1,214 @@
 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 { CallerAbortedError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, toStateMachinesError, } from './errors.js';
-import { RunningEnvironment } from './running-environment.js';
+import { bindCredentials } from './credentials.js';
+import { CallerAbortedError, StateMachinesError, toStateMachinesError, } from './errors.js';
 import { linkSignal } from './signal.js';
-import { backoff, defaultTimeoutMs, disposed, poll, pollUntil, ready, sleep, snapshotReady, suspended, } from './wait.js';
-const stopAfterFailureMs = 30000;
-const busyBudgetMs = 60000;
+import { environmentAt, poll, snapshotAt, } from './wait.js';
 export class StateMachines {
     #sdk;
     #fetch;
     #workspaceId;
     #callSignals = new Map();
+    #apis = new Map();
     #lastCall = 0;
-    #credentialWorkspace;
     constructor(options = {}) {
         const apiKey = options.apiKey ?? environmentApiKey();
         if (!apiKey) {
-            throw new TypeError('Pass apiKey or set STATE_API_KEY.');
+            throw new TypeError('Pass apiKey or set STATEMACHINES_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 attemptTimeoutMs = options.attemptTimeoutMs ?? 60000;
+        if (!(attemptTimeoutMs > 0 && Number.isFinite(attemptTimeoutMs))) {
+            throw new RangeError('attemptTimeoutMs must be a positive, finite number.');
         }
         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.#callSignals);
+        const httpClient = new HTTPClient(fetcher ? { fetcher: (input) => fetcher(input) } : {});
+        addAttemptTimeout(httpClient, attemptTimeoutMs, this.#callSignals);
         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 } : {}),
+            ...(options.baseUrl ? { serverURL: options.baseUrl } : {}),
         });
     }
-    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)),
+    /** The caller: its principal, organization, workspace, permissions and limits. */
+    me() {
+        return this.#call(undefined, (call) => this.#sdk.me(call));
+    }
+    apps = {
+        list: (query = {}) => this.#call(undefined, (call) => this.#sdk.apps.list(query, call)),
+        /** Published versions, including retired ones. */
+        versions: (appId, query = {}) => this.#call(undefined, (call) => this.#sdk.apps.versions({ ...query, appId }, 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)),
+        list: (query = {}) => this.#call(undefined, (call) => this.#sdk.workspaces.list(query, call)),
+        get: (workspaceId) => this.#call(undefined, (call) => this.#sdk.workspaces.get({ 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)),
-        /**
-         * 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.
-         */
+        /** Creates an environment and, unless `wait` is false, waits until it is `running`. */
         create: async (input, options = {}) => {
+            const { signal } = 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 }, call);
-                    const [environment] = data;
-                    if (!environment) {
-                        throw new Error('Invalid response from the State API: the create returned no environment.');
-                    }
-                    return environment;
+            const created = await this.#call(signal, (call) => this.#sdk.environments.create({ idempotencyKey, body: this.#inWorkspace(input) }, call));
+            return options.wait === false
+                ? this.#bind(created)
+                : this.environments.wait(created.id, {
+                    status: 'running',
+                    ...waitOptions(options),
                 });
-            }
-            catch (error) {
-                // Always a new instance: concurrent creates can share one failed workspace lookup.
-                throw new StateMachinesError(error, { idempotencyKey });
-            }
         },
-        /** Ends the environment and discards its data. Safe to repeat. */
-        stop: (environmentId, options) => this.#command('stop', environmentId, options),
-        /**
-         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
-         * Its lifetime is paused meanwhile. Use `stop` to end it.
-         */
-        suspend: (environmentId, options) => this.#command('suspend', environmentId, options),
-        /** Resumes a suspended or failed environment using its retained data. */
-        resume: (environmentId, options) => this.#command('resume', environmentId, options),
-        events: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.events({ ...query, environmentId }, call)),
-        listRequests: (environmentId, query = {}, options) => this.#call(options, (call) => this.#sdk.environments.listRequests({ ...query, environmentId }, call)),
-        getRequestStats: (environmentId, query, options) => this.#unwrap(options, (call) => this.#sdk.environments.getRequestStats({ ...query, environmentId }, call)),
-        getRequest: (environmentId, requestId, options) => this.#unwrap(options, (call) => this.#sdk.environments.getRequest({ environmentId, requestId }, call)),
-        getRequestPayload: (environmentId, requestId, direction, options) => this.#call(options, (call) => this.#sdk.environments.getRequestPayload({ environmentId, requestId, direction }, 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.#reveal(environmentId, appKey, { actorId }, options),
-        /** Resolves when the environment is running. Never suspends or stops it. */
-        waitUntilReady: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), ready, options),
-        /** Resolves when the environment is suspended and can resume. */
-        waitUntilSuspended: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), suspended, options),
-        /** Resolves when the environment ended and every sandbox is confirmed disposed. */
-        waitUntilStopped: (environmentId, options) => poll((signal) => this.#poll(environmentId, signal), disposed, options),
+        /** Newest first. Leaves deleted environments out unless `status` asks for them. */
+        list: async (query = {}) => {
+            const page = await this.#call(undefined, (call) => this.#sdk.environments.list(this.#inWorkspace(query), call));
+            return { ...page, data: page.data.map((each) => this.#bind(each)) };
+        },
+        get: async (environmentId) => this.#bind(await this.#call(undefined, (call) => this.#sdk.environments.get({ environmentId }, call))),
+        /** `labels` replaces the whole map. */
+        update: async (environmentId, body) => this.#bind(await this.#call(undefined, (call) => this.#sdk.environments.update({ environmentId, body }, call))),
+        /** Takes effect when the API answers: the gateway refuses calls from then on. */
+        pause: async (environmentId, options = {}) => this.#bind(await this.#call(options.signal, (call) => this.#sdk.environments.pause({ environmentId }, call))),
+        /** Resumes a paused or failed environment and, unless `wait` is false, waits until it is `running`. */
+        resume: async (environmentId, options = {}) => {
+            const resumed = await this.#call(options.signal, (call) => this.#sdk.environments.resume({ environmentId }, call));
+            return options.wait === false
+                ? this.#bind(resumed)
+                : this.environments.wait(environmentId, {
+                    status: 'running',
+                    ...waitOptions(options),
+                });
+        },
+        /** Deletes the environment and its data. Safe to repeat. */
+        delete: async (environmentId, options = {}) => this.#bind(await this.#call(options.signal, (call) => this.#sdk.environments.delete({ environmentId }, call))),
         /**
-         * 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.
+         * Resolves when the environment has `status`. Throws once it cannot get there without
+         * another call: `EnvironmentFailedError` if it failed, else `UnexpectedStatusError`.
          */
-        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}).`);
-            }
-            // 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);
-        },
+        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),
     };
     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;
+        /** Creates a snapshot of a running environment and, unless `wait` is false, waits until it is `ready`. */
+        create: async (input, 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 } : {}),
+            const created = await this.#call(options.signal, (call) => this.#sdk.snapshots.create({ idempotencyKey, body: input }, call));
+            return options.wait === false
+                ? created
+                : this.snapshots.wait(created.id, {
+                    status: 'ready',
+                    ...waitOptions(options),
                 });
-            }
-            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);
-        }),
+        /** Newest first. Leaves deleted snapshots out unless `status` asks for them. */
+        list: (query = {}) => this.#call(undefined, (call) => this.#sdk.snapshots.list(this.#inWorkspace(query), call)),
+        get: (snapshotId) => this.#call(undefined, (call) => this.#sdk.snapshots.get({ snapshotId }, call)),
+        /** `null` clears the name. */
+        update: (snapshotId, body) => this.#call(undefined, (call) => this.#sdk.snapshots.update({ snapshotId, body }, call)),
+        /** A `saving` snapshot cannot be deleted. Safe to repeat. */
+        delete: (snapshotId) => this.#call(undefined, (call) => this.#sdk.snapshots.delete({ snapshotId }, 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.
+         * Resolves when the snapshot has `status`. Throws once it cannot get there without
+         * another call: `SnapshotFailedError` if it failed, else `UnexpectedStatusError`.
          */
-        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)),
+        wait: (snapshotId, options) => poll(snapshotId, (signal) => this.#read(signal, (call) => this.#sdk.snapshots.get({ snapshotId }, call)), snapshotAt(options.status), options),
     };
-    async #command(verb, environmentId, options = {}) {
-        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
-        try {
-            return await this.#unwrap(options, (call) => this.#sdk.environments[verb]({ environmentId, idempotencyKey }, call));
-        }
-        catch (error) {
-            throw new StateMachinesError(error, { idempotencyKey });
-        }
-    }
-    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();
-        }
+    requests = {
+        /** Calls the gateway recorded for one environment, newest first. Recording is best effort. */
+        list: (query) => this.#call(undefined, (call) => this.#sdk.requests.list(query, call)),
+        get: (requestId) => this.#call(undefined, (call) => this.#sdk.requests.get({ requestId }, call)),
+        stats: (query) => this.#call(undefined, (call) => this.#sdk.requests.stats(query, call)),
+        /** The recorded body, in full. */
+        body: (requestId, direction) => 
+        // Read inside the call: settling it aborts the signal the body streams under.
+        this.#call(undefined, async (call) => {
+            const stream = await this.#sdk.requests.body({ requestId, direction }, call);
+            return new Uint8Array(await new Response(stream).arrayBuffer());
+        }),
+    };
+    auditEvents = {
+        /** Newest first. An API key that names no filter gets its own workspace. */
+        list: (query = {}) => this.#call(undefined, (call) => this.#sdk.auditEvents.list(query.environmentId ? query : this.#inWorkspace(query), call)),
+    };
+    #inWorkspace(input) {
+        return input.workspaceId === undefined && this.#workspaceId !== undefined
+            ? { ...input, workspaceId: this.#workspaceId }
+            : input;
     }
-    /** 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' } }));
+    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);
     }
-    /** 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);
+    /** 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);
         }
-        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);
+        return apis;
     }
-    #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;
+    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,
         });
-        return lookup;
     }
-    #unwrap(options, run) {
-        return this.#call(options, async (call) => (await run(call)).data);
+    #bind(data) {
+        const { id } = data;
+        const helpers = {
+            connect: (app, options = {}) => this.#connect(id, data, app, options),
+            pause: (options) => this.environments.pause(id, options),
+            resume: (options) => this.environments.resume(id, options),
+            delete: (options) => this.environments.delete(id, options),
+            refresh: () => this.environments.get(id),
+            snapshots: {
+                create: (input = {}, options) => this.snapshots.create({ ...input, environmentId: id }, options),
+            },
+        };
+        return Object.defineProperties({ ...data }, Object.fromEntries(Object.entries(helpers).map(([name, value]) => [
+            name,
+            { value, enumerable: false },
+        ])));
+    }
+    /** One read for the poller, which owns retries, timing and the caller's signal. */
+    #read(signal, run) {
+        return this.#call(signal, (call) => run({ ...call, retries: { strategy: 'none' } }));
     }
     /**
      * 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);
+    async #call(signal, run) {
+        const scope = linkSignal(signal);
         const id = String(++this.#lastCall);
         this.#callSignals.set(id, scope.signal);
         try {
@@ -335,9 +219,7 @@ export class StateMachines {
         }
         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);
+            throw toStateMachinesError(signal?.aborted ? new CallerAbortedError(signal.reason) : error);
         }
         finally {
             this.#callSignals.delete(id);
@@ -360,14 +242,13 @@ function addAttemptTimeout(httpClient, timeoutMs, calls) {
     httpClient.addHook('beforeRequest', (request) => {
         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, {
+        const attempt = new globalThis.Request(request, {
             headers,
             signal: linkSignal(sources, timeoutMs).signal,
         });
@@ -382,56 +263,15 @@ function addAttemptTimeout(httpClient, timeoutMs, calls) {
         }
     });
 }
-function isStartError(error) {
-    return (error instanceof StateMachinesError ||
-        error instanceof EnvironmentFailedError ||
-        error instanceof TimeoutError);
-}
-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 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 (!api) {
-        throw new TypeError(`Choose one API for ${appKey}: ${ids(apis) || 'none available'}.`);
-    }
-    return api;
-}
-function ids(choices) {
-    return choices.map(({ id }) => id).join(', ');
+function waitOptions(options) {
+    return {
+        ...(options.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: options.timeoutMs }),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
 }
 function environmentApiKey() {
     const runtime = globalThis;
-    return runtime.process?.env?.STATE_API_KEY;
+    return runtime.process?.env?.STATEMACHINES_API_KEY;
 }

package/esm/extensions/credentials.d.ts

@@ -0,0 +1,13 @@
+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. */
+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.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+};
+export declare function bindCredentials(data: CredentialsData, apis: readonly Api[], fetcher: typeof fetch | undefined): Credentials;