@usestatemachines/sdk 0.4.0 → 0.6.0

package/agents/prompt.md

@@ -1,26 +1,26 @@
 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. 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. It prints `200` and the org's limits:
+1. Install the SDK: `npm install @usestatemachines/sdk`. It is ESM only and runs on Node.js, at the versions in its `engines` field, and on Cloudflare Workers, not in browsers.
+2. Check that `STATEMACHINES_API_KEY` is set without printing it: `test -n "$STATEMACHINES_API_KEY"`. If it is missing, stop and ask me to set it; the SDK doesn't read `.env` files. 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. It prints `200` and the Salesforce org's limits:
 
 ```ts
 import { StateMachines } from '@usestatemachines/sdk';
 
-const sm = new StateMachines(); // reads STATE_API_KEY
-const env = await sm.environments.start({ apps: ['salesforce'] });
+const sm = new StateMachines(); // reads STATEMACHINES_API_KEY
+const env = await sm.environments.create({ apps: ['salesforce'] });
 
 try {
-  const salesforce = await env.connect('salesforce', { apiId: 'rest' });
+  const salesforce = await env.connect('salesforce');
   const res = await salesforce.fetch('/services/data/v67.0/limits');
   console.log(res.status, await res.json());
 } finally {
-  await env.stop();
+  await env.delete();
 }
 ```
 
-4. Adapt it to my task. Log `await sm.catalog.get()` to find each app's ID and the actors and API profiles its release offers; don't guess IDs. Start only the apps the task needs; a string such as `'salesforce'` means `{ key: 'salesforce', appId: 'salesforce' }`. Salesforce always needs an `apiId`. `connect()` acts as the declared default connection's actor, or else the app's first actor, the administrator; to act as a specific user, pass an `actorId` from `await env.actors('salesforce')`. To reuse seeded data, `await env.snapshot()` once, then `sm.environments.start({ snapshotId })`.
-5. Always call `env.stop()` in a `finally`; it ends the environment and discards its data. In CI, then await `env.waitUntilStopped()` so the run fails if cleanup isn't confirmed. If `start()` fails after creating the environment, it stops it; an `EnvironmentFailedError` or `TimeoutError` carries `err.environmentId` and `err.stopped`. If the create itself fails, call `sm.environments.start(input, { idempotencyKey: err.idempotencyKey })` with the same `input`; never retry without the key, which can start a second environment.
-6. Never print, log or commit keys or tokens, including `connection.headers()` and `connection.actorToken()`, which return live tokens.
+4. Adapt it to my task. Log `await sm.apps.list()` to find each app's ID, and `await sm.apps.versions(appId)` for the actors and APIs of its versions; don't guess IDs. Create only the apps the task needs; a string such as `'salesforce'` names the app and also becomes its name in the environment. `connect()` acts as the app's default actor, the Salesforce administrator; to act as another user, pass an `actorId` from the version's `actors`. To reuse seeded data, create a snapshot once with `await env.snapshots.create()`, then `sm.environments.create({ snapshotId })`.
+5. Always call `env.delete()` in a `finally`; it deletes the environment and its data. If the start fails, the server deletes the environment itself and `create` throws `EnvironmentFailedError`. Pass your own `idempotencyKey` to `create`; if it throws with no response, call it again with the same input and key.
+6. Never print, log or commit keys or tokens, including `credentials.token` and `credentials.headers`.
 
-Read more: `node_modules/@usestatemachines/sdk/README.md`, https://state-web.usestatemachines.workers.dev/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk
+Read more: `node_modules/@usestatemachines/sdk/README.md`, https://app.usestatemachines.com/llms.txt and https://www.npmjs.com/package/@usestatemachines/sdk

package/esm/extensions/client.d.ts

@@ -1,149 +1,138 @@
-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 { 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 { App } from '../models/app.js';
+import type { AuditEvent } from '../models/audit-event.js';
+import type { CreateEnvironment } from '../models/create-environment.js';
+import type { Me } from '../models/me.js';
+import type { GetRequestStatsRequest } from '../models/operations/get-request-stats.js';
+import type { ListAuditEventsRequest } from '../models/operations/list-audit-events.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
+import type { ListRequestsRequest } from '../models/operations/list-requests.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 { UpdateEnvironmentRequestBody } from '../models/operations/update-environment.js';
+import type { RequestT as Request } from '../models/request.js';
+import type { RequestDetail } from '../models/request-detail.js';
+import type { RequestStats } from '../models/request-stats.js';
+import type { Snapshot } from '../models/snapshot.js';
+import type { Version } from '../models/version.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';
+import { type Credentials } from './credentials.js';
+import type { Environment } from './environment.js';
+import { type KnownEnvironmentStatus, type KnownSnapshotStatus, type WaitOptions } from './wait.js';
 export interface StateMachinesOptions {
-    /** Workspace API key. Defaults to `STATE_API_KEY` where a `process` exists. */
+    /** An API key or a member's access token. Defaults to `STATEMACHINES_API_KEY` where a `process` exists. */
     apiKey?: string;
-    serverURL?: string;
-    /** Used when a call omits `workspaceId`; otherwise read from the API key. */
+    /** Defaults to `https://api.usestatemachines.com`. */
+    baseUrl?: string;
+    /** The workspace for calls that name none. Member tokens need it; an API key has its own. */
     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;
+    fetch?: typeof fetch;
+    /** Timeout of each HTTP attempt; a retry gets a fresh one. Defaults to 60 seconds. */
+    attemptTimeoutMs?: number;
 }
-export interface CallOptions {
+export interface SignalOptions {
     signal?: AbortSignal;
 }
-export interface CreateOptions extends CallOptions {
+export interface CreateEnvironmentOptions extends SignalOptions {
+    /** Wait until the environment is `running`. Defaults to true. */
+    wait?: boolean;
+    /** Deadline for the wait. Defaults to 10 minutes. */
+    timeoutMs?: number;
+    /** A replay with the same key and input returns the same environment. Defaults to a new UUID. */
     idempotencyKey?: string;
-    workspaceId?: string;
 }
-export type ListEnvironmentsQuery = Omit<ListEnvironmentsRequest, 'workspaceId'> & {
-    workspaceId?: string;
-};
+export interface ResumeOptions extends SignalOptions {
+    /** Wait until the environment is `running`. Defaults to true. */
+    wait?: boolean;
+    /** Deadline for the wait. Defaults to 10 minutes. */
+    timeoutMs?: number;
+}
+export type CreateSnapshotOptions = CreateEnvironmentOptions;
+export interface ConnectOptions {
+    /** Defaults to the app's default actor (for Salesforce, the administrator). */
+    actorId?: string;
+}
 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 type PageQuery = {
+    limit?: number;
+    cursor?: 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 type ListEnvironmentsQuery = ListEnvironmentsRequest;
+export type ListSnapshotsQuery = ListSnapshotsRequest;
+export type ListAuditEventsQuery = ListAuditEventsRequest;
+export type ListWorkspacesQuery = ListWorkspacesRequest;
+export type ListRequestsQuery = ListRequestsRequest;
+export type RequestStatsQuery = GetRequestStatsRequest;
 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>;
+    /** The caller: its principal, organization, workspace, permissions and limits. */
+    me(): Promise<Me>;
+    readonly apps: {
+        list: (query?: PageQuery) => Promise<Page<App>>;
+        /** Published versions, including retired ones. */
+        versions: (appId: string, query?: PageQuery) => Promise<Page<Version>>;
     };
     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>;
+        list: (query?: ListWorkspacesRequest) => Promise<Page<Workspace>>;
+        get: (workspaceId: string) => Promise<Workspace>;
     };
     readonly environments: {
-        list: (query?: ListEnvironmentsQuery, options?: CallOptions | undefined) => Promise<Page<Environment>>;
-        get: (environmentId: string, options?: CallOptions | undefined) => 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>;
-        /** Ends the environment and discards its data. Safe to repeat. */
-        stop: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
+        /** Creates an environment and, unless `wait` is false, waits until it is `running`. */
+        create: (input: CreateEnvironment, options?: CreateEnvironmentOptions) => Promise<Environment>;
+        /** Newest first. Leaves deleted environments out unless `status` asks for them. */
+        list: (query?: ListEnvironmentsRequest) => Promise<Page<Environment>>;
+        get: (environmentId: string) => Promise<Environment>;
+        /** `labels` replaces the whole map. */
+        update: (environmentId: string, body: UpdateEnvironmentRequestBody) => Promise<Environment>;
+        /** Takes effect when the API answers: the gateway refuses calls from then on. */
+        pause: (environmentId: string, options?: SignalOptions) => Promise<Environment>;
+        /** Resumes a paused or failed environment and, unless `wait` is false, waits until it is `running`. */
+        resume: (environmentId: string, options?: ResumeOptions) => Promise<Environment>;
+        /** Deletes the environment and its data. Safe to repeat. */
+        delete: (environmentId: string, options?: SignalOptions) => Promise<Environment>;
         /**
-         * Suspends a running environment: its sandboxes end and its data stays for `resume`.
-         * Its lifetime is paused meanwhile. Use `stop` to end it.
+         * Resolves when the environment has `status`. Throws once it cannot get there without
+         * another call: `EnvironmentFailedError` if it failed, else `UnexpectedStatusError`.
          */
-        suspend: (environmentId: string, options?: CallOptions | undefined) => Promise<Environment>;
-        /** Queues a suspended environment to run again on the data it was suspended with. */
-        resume: (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 suspends or stops it. */
-        waitUntilReady: (environmentId: string, options?: WaitOptions | undefined) => Promise<Environment>;
-        /** Resolves when the environment is suspended and can resume. */
-        waitUntilSuspended: (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>;
+        wait: (environmentId: string, options: WaitOptions<KnownEnvironmentStatus>) => Promise<Environment>;
+        /** Credentials for one app of the environment. */
+        connect: (environmentId: string, app: string, options?: ConnectOptions) => Promise<Credentials>;
     };
     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>>;
+        /** Creates a snapshot of a running environment and, unless `wait` is false, waits until it is `ready`. */
+        create: (input: {
+            environmentId: string;
+            name?: string | null;
+        }, options?: CreateEnvironmentOptions) => Promise<Snapshot>;
+        /** Newest first. Leaves deleted snapshots out unless `status` asks for them. */
+        list: (query?: ListSnapshotsRequest) => Promise<Page<Snapshot>>;
+        get: (snapshotId: string) => Promise<Snapshot>;
+        /** `null` clears the name. */
+        update: (snapshotId: string, body: {
+            name: string | null;
+        }) => Promise<Snapshot>;
+        /** A `saving` snapshot cannot be deleted. Safe to repeat. */
+        delete: (snapshotId: string) => Promise<Snapshot>;
         /**
-         * `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: 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>;
+        wait: (snapshotId: string, options: WaitOptions<KnownSnapshotStatus>) => Promise<Snapshot>;
+    };
+    readonly requests: {
+        /** Calls the gateway recorded for one environment, newest first. Recording is best effort. */
+        list: (query: ListRequestsRequest) => Promise<Page<Request>>;
+        get: (requestId: string) => Promise<RequestDetail>;
+        stats: (query: GetRequestStatsRequest) => Promise<RequestStats>;
+        /** The recorded body, in full. */
+        body: (requestId: string, direction: "request" | "response") => Promise<Uint8Array<ArrayBufferLike>>;
+    };
+    readonly auditEvents: {
+        /** Newest first. An API key that names no filter gets its own workspace. */
+        list: (query?: ListAuditEventsRequest) => Promise<Page<AuditEvent>>;
     };
 }
 /**