@usestatemachines/sdk 0.11.0 → 0.12.1

package/esm/extensions/client.d.ts

@@ -1,10 +1,13 @@
 import type { App } from '../models/app.js';
+import type { AppUser } from '../models/app-user.js';
 import type { AuditEvent } from '../models/audit-event.js';
 import type { CreateEnvironment } from '../models/create-environment.js';
 import type { Import } from '../models/import.js';
+import type { LaunchUiSession } from '../models/launch-ui-session.js';
 import type { Me } from '../models/me.js';
 import type { CreateCredentialsRequestBody } from '../models/operations/create-credentials.js';
 import type { GetRequestStatsRequest } from '../models/operations/get-request-stats.js';
+import type { ListActorsRequest } from '../models/operations/list-actors.js';
 import type { ListAuditEventsRequest } from '../models/operations/list-audit-events.js';
 import type { ListEnvironmentsRequest } from '../models/operations/list-environments.js';
 import type { ListImportsRequest } from '../models/operations/list-imports.js';
@@ -16,10 +19,15 @@ 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 { SnapshotListItem } from '../models/snapshot-list-item.js';
+import type { UiSessionLaunch } from '../models/ui-session-launch.js';
+import type { UiSessionRevocation } from '../models/ui-session-revocation.js';
 import type { Version } from '../models/version.js';
 import type { Workspace } from '../models/workspace.js';
 import { type Credentials } from './credentials.js';
 import type { Environment } from './environment.js';
+import { ActorCannotSignInError, ActorNotFoundError } from './errors.js';
+import { type ImportData } from './import-data.js';
 import { type KnownEnvironmentStatus, type KnownSnapshotStatus, type WaitOptions } from './wait.js';
 export interface StateMachinesOptions {
     /** An API key or a member's access token. Defaults to `STATEMACHINES_API_KEY` where a `process` exists. */
@@ -50,13 +58,34 @@ export interface UploadImportOptions extends SignalOptions {
     /** A repeat with the same key and the same bytes finds the same import. Defaults to a new UUID. */
     idempotencyKey?: string;
 }
+/** The input of `snapshots.create` that builds the snapshot from the data of an import. */
+interface CreateSnapshotFromData {
+    /** The manifest of the import, with each app's records in it. */
+    import: ImportData;
+    name?: string | null;
+    /** The workspace of the import and the snapshot. Defaults to the client's `workspaceId`; an API key has its own. */
+    workspaceId?: string;
+}
 /**
- * The body of the credentials call. `actorId` defaults to the app's default
- * actor (for Salesforce, the administrator). `services` names more services
- * to list, by ID. The credentials always list every `public` service, and a
+ * The body of the credentials call. `as` names the user to act as, by email,
+ * username or ID. Without it, the credentials act as the app's default user:
+ * the first user that the snapshot's import names in `actors`, or else the
+ * app's administrator. `services` names more services to
+ * list, by ID. The credentials always list every `public` service, and a
  * `preview` service only when `services` names it.
  */
-export type ConnectOptions = Pick<CreateCredentialsRequestBody, 'actorId' | 'services'>;
+export type ConnectOptions = Pick<CreateCredentialsRequestBody, 'as' | 'actorId' | 'services'>;
+export interface ConnectAllOptions {
+    /** An email, a username or an ID, which each app looks up among its own users. */
+    as: string;
+}
+/** Credentials for each app that lets the user act, and the refusal of each other app. */
+export interface ConnectAllResult {
+    /** By app name. */
+    readonly credentials: Readonly<Record<string, Credentials>>;
+    /** In the order of the environment's apps. */
+    readonly errors: readonly (ActorNotFoundError | ActorCannotSignInError)[];
+}
 export interface Page<T> {
     data: T[];
     nextCursor: string | null;
@@ -66,6 +95,8 @@ export type PageQuery = {
     cursor?: string;
 };
 export type ListEnvironmentsQuery = ListEnvironmentsRequest;
+/** `search` matches part of a name, an email or a username in any case, or a whole ID. */
+export type ListActorsQuery = Omit<ListActorsRequest, 'environmentId' | 'appName'>;
 export type ListSnapshotsQuery = ListSnapshotsRequest;
 export type ListImportsQuery = ListImportsRequest;
 export type ListAuditEventsQuery = ListAuditEventsRequest;
@@ -101,8 +132,27 @@ export declare class StateMachines {
          * another call: `EnvironmentFailedError` if it failed, else `UnexpectedStatusError`.
          */
         wait: (environmentId: string, options: WaitOptions<KnownEnvironmentStatus>) => Promise<Environment>;
-        /** Credentials for one app of the environment. */
+        /**
+         * Credentials for one app of the environment. A user that the app does not have
+         * throws `ActorNotFoundError`, and one it does not let sign in throws
+         * `ActorCannotSignInError`.
+         */
         connect: (environmentId: string, appName: string, options?: ConnectOptions) => Promise<Credentials>;
+        /** One page of the users who can act in one app of a running environment, the default user first. */
+        actors: (environmentId: string, appName: string, query?: ListActorsQuery) => Promise<Page<AppUser>>;
+        /**
+         * Launches a browser session of one user in a browser service of the app.
+         * `entryPath` must match one of the service's document routes, and `as` names
+         * the user as `connect` takes it. The
+         * launch holds a one-use `grant` that expires soon, and no reusable credential.
+         * Give it only to the browser it is for, which posts it to `exchangeUrl` from
+         * `launcherOrigin`, such as with `submitLaunch` from `@usestatemachines/sdk/ui`.
+         * A user that the app does not have throws `ActorNotFoundError`, and one it
+         * does not let sign in throws `ActorCannotSignInError`.
+         */
+        launchUiSession: (environmentId: string, appName: string, input: LaunchUiSession, options?: SignalOptions) => Promise<UiSessionLaunch>;
+        /** Ends a browser session that this credential launched. Safe to repeat. */
+        revokeUiSession: (environmentId: string, appName: string, sessionId: string, options?: SignalOptions) => Promise<UiSessionRevocation>;
     };
     readonly snapshots: {
         /**
@@ -110,16 +160,29 @@ export declare class StateMachines {
          * and, unless `wait` is false, waits until it is `ready`. A snapshot from an import
          * takes every app of the import, each on its default version, with empty setup and
          * services. An import that an app refuses throws `SnapshotFailedError` with its problems.
+         *
+         * `{ import }` takes an import as one object, which is the manifest with each app's
+         * records in it. The SDK writes the object as a zip file, uploads it as `imports.upload`
+         * does, and builds the snapshot from the import. The zip file holds each object's records
+         * in `<app>/records/<Object>.jsonl`, one record per line, so a problem at line N of that
+         * file names `apps.<app>.records.<Object>[N - 1]`. Data that the SDK cannot write as a
+         * zip file throws `StateMachinesError` with `code: 'invalid_request'` before any request.
+         * An import that its check leaves `invalid` throws `ImportInvalidError`, and the SDK
+         * creates no snapshot. The import and the snapshot share one idempotency key, so a
+         * retry with the same key and the same data finds both.
          */
-        create: (input: {
+        create: (input: CreateSnapshotFromData | {
             environmentId: string;
             name?: string | null;
         } | {
             importId: 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>>;
+        /**
+         * Newest first. Leaves deleted snapshots out unless `status` asks for them.
+         * Each app's load holds its counts only. `get` answers its lists too.
+         */
+        list: (query?: ListSnapshotsRequest) => Promise<Page<SnapshotListItem>>;
         get: (snapshotId: string) => Promise<Snapshot>;
         /** `null` clears the name. */
         update: (snapshotId: string, body: {
@@ -165,3 +228,4 @@ export declare class StateMachines {
  * collection a clone's signal no longer follows the call's (Node 20 and 24).
  */
 export declare const CALL_HEADER = "x-statemachines-call";
+export {};

package/esm/extensions/client.js

@@ -2,7 +2,8 @@ import { SDK_METADATA } from '../lib/config.js';
 import { HTTPClient } from '../lib/http.js';
 import { StateMachines as Generated } from '../sdk/sdk.js';
 import { bindCredentials } from './credentials.js';
-import { CallerAbortedError, StateMachinesError, toStateMachinesError, uploadRefused, uploadUnanswered, } from './errors.js';
+import { ActorCannotSignInError, ActorNotFoundError, actorError, CallerAbortedError, ImportInvalidError, StateMachinesError, toStateMachinesError, uploadRefused, uploadUnanswered, } from './errors.js';
+import { zipImport } from './import-data.js';
 import { linkSignal } from './signal.js';
 import { environmentAt, poll, snapshotAt, } from './wait.js';
 export class StateMachines {
@@ -79,8 +80,27 @@ export class StateMachines {
          * another call: `EnvironmentFailedError` if it failed, else `UnexpectedStatusError`.
          */
         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. */
+        /**
+         * Credentials for one app of the environment. A user that the app does not have
+         * throws `ActorNotFoundError`, and one it does not let sign in throws
+         * `ActorCannotSignInError`.
+         */
         connect: (environmentId, appName, options = {}) => this.#connect(environmentId, appName, options),
+        /** One page of the users who can act in one app of a running environment, the default user first. */
+        actors: (environmentId, appName, query = {}) => this.#call(undefined, (call) => this.#sdk.environments.actors({ ...query, environmentId, appName }, call)),
+        /**
+         * Launches a browser session of one user in a browser service of the app.
+         * `entryPath` must match one of the service's document routes, and `as` names
+         * the user as `connect` takes it. The
+         * launch holds a one-use `grant` that expires soon, and no reusable credential.
+         * Give it only to the browser it is for, which posts it to `exchangeUrl` from
+         * `launcherOrigin`, such as with `submitLaunch` from `@usestatemachines/sdk/ui`.
+         * A user that the app does not have throws `ActorNotFoundError`, and one it
+         * does not let sign in throws `ActorCannotSignInError`.
+         */
+        launchUiSession: (environmentId, appName, input, options = {}) => this.#launchUiSession(environmentId, appName, input, options),
+        /** Ends a browser session that this credential launched. Safe to repeat. */
+        revokeUiSession: (environmentId, appName, sessionId, options = {}) => this.#call(options.signal, (call) => this.#sdk.revokeUiSession({ environmentId, appName, sessionId }, call)),
     };
     snapshots = {
         /**
@@ -88,10 +108,24 @@ export class StateMachines {
          * and, unless `wait` is false, waits until it is `ready`. A snapshot from an import
          * takes every app of the import, each on its default version, with empty setup and
          * services. An import that an app refuses throws `SnapshotFailedError` with its problems.
+         *
+         * `{ import }` takes an import as one object, which is the manifest with each app's
+         * records in it. The SDK writes the object as a zip file, uploads it as `imports.upload`
+         * does, and builds the snapshot from the import. The zip file holds each object's records
+         * in `<app>/records/<Object>.jsonl`, one record per line, so a problem at line N of that
+         * file names `apps.<app>.records.<Object>[N - 1]`. Data that the SDK cannot write as a
+         * zip file throws `StateMachinesError` with `code: 'invalid_request'` before any request.
+         * An import that its check leaves `invalid` throws `ImportInvalidError`, and the SDK
+         * creates no snapshot. The import and the snapshot share one idempotency key, so a
+         * retry with the same key and the same data finds both.
          */
         create: async (input, options = {}) => {
+            const { signal } = options;
             const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
-            const created = await this.#call(options.signal, (call) => this.#sdk.snapshots.create({ idempotencyKey, body: input }, call));
+            const body = 'import' in input
+                ? await this.#fromData(input, idempotencyKey, signal)
+                : input;
+            const created = await this.#call(signal, (call) => this.#sdk.snapshots.create({ idempotencyKey, body }, call));
             return options.wait === false
                 ? created
                 : this.snapshots.wait(created.id, {
@@ -99,7 +133,10 @@ export class StateMachines {
                     ...waitOptions(options),
                 });
         },
-        /** Newest first. Leaves deleted snapshots out unless `status` asks for them. */
+        /**
+         * Newest first. Leaves deleted snapshots out unless `status` asks for them.
+         * Each app's load holds its counts only. `get` answers its lists too.
+         */
         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. */
@@ -166,12 +203,55 @@ export class StateMachines {
     }
     async #connect(environmentId, appName, options) {
         const body = {
+            ...(options.as === undefined ? {} : { as: options.as }),
             ...(options.actorId === undefined ? {} : { actorId: options.actorId }),
             ...(options.services === undefined ? {} : { services: options.services }),
         };
-        const credentials = await this.#call(undefined, (call) => this.#sdk.environments.connect({ environmentId, appName, body }, call));
+        // Typed inside the call, because the error that `#call` throws no longer holds the response body.
+        const credentials = await this.#call(undefined, (call) => this.#sdk.environments
+            .connect({ environmentId, appName, body }, call)
+            .catch((error) => {
+            throw actorError(error, appName);
+        }));
         return bindCredentials(credentials, this.#fetch);
     }
+    #launchUiSession(environmentId, appName, body, options) {
+        return this.#call(options.signal, (call) => this.#sdk
+            .launchUiSession({ environmentId, appName, body }, call)
+            .catch((error) => {
+            throw actorError(error, appName);
+        }));
+    }
+    async #connectAll(environment, { as }) {
+        const outcomes = await Promise.allSettled(environment.apps.map((app) => this.#connect(environment.id, app.name, { as })));
+        const credentials = {};
+        const errors = [];
+        for (const outcome of outcomes) {
+            if (outcome.status === 'fulfilled') {
+                credentials[outcome.value.appName] = outcome.value;
+            }
+            else if (outcome.reason instanceof ActorNotFoundError ||
+                outcome.reason instanceof ActorCannotSignInError) {
+                errors.push(outcome.reason);
+            }
+            else {
+                throw outcome.reason;
+            }
+        }
+        return { credentials, errors };
+    }
+    /** Uploads the data as an import under `idempotencyKey`, and answers the body that builds the snapshot from it. */
+    async #fromData({ import: data, workspaceId, ...snapshot }, idempotencyKey, signal) {
+        const imported = await this.imports.upload(zipImport(data), {
+            ...(workspaceId === undefined ? {} : { workspaceId }),
+            ...(signal ? { signal } : {}),
+            idempotencyKey,
+        });
+        if (imported.status === 'invalid') {
+            throw new ImportInvalidError(imported);
+        }
+        return { ...snapshot, importId: imported.id };
+    }
     async #send(upload, zip, signal) {
         const fetcher = this.#fetch ?? fetch;
         const scope = linkSignal(signal);
@@ -203,9 +283,13 @@ export class StateMachines {
     #bind(data) {
         const { id } = data;
         const helpers = {
+            actors: (appName, query) => this.environments.actors(id, appName, query),
             connect: (appName, options = {}) => this.#connect(id, appName, options),
+            connectAll: (options) => this.#connectAll(data, options),
             delete: (options) => this.environments.delete(id, options),
+            launchUiSession: (appName, input, options) => this.environments.launchUiSession(id, appName, input, options),
             refresh: () => this.environments.get(id),
+            revokeUiSession: (appName, sessionId, options) => this.environments.revokeUiSession(id, appName, sessionId, options),
             snapshots: {
                 create: (input = {}, options) => this.snapshots.create({ ...input, environmentId: id }, options),
             },

package/esm/extensions/credentials.js

@@ -27,6 +27,10 @@ class BoundCredentials {
         this.services = data.services;
         this.token = data.token;
         this.#fetcher = fetcher;
+        // Set only when present, so JSON and a spread hold the API's fields.
+        if (data.actor) {
+            this.actor = data.actor;
+        }
         const api = data.services.find((candidate) => candidate.id === 'api');
         this.#api = api
             ? { base: baseUrl(api.url), headers: { ...api.headers } }

package/esm/extensions/environment.d.ts

@@ -1,6 +1,10 @@
+import type { AppUser } from '../models/app-user.js';
 import type { Environment as EnvironmentData } from '../models/environment.js';
+import type { LaunchUiSession } from '../models/launch-ui-session.js';
 import type { Snapshot } from '../models/snapshot.js';
-import type { ConnectOptions, CreateSnapshotOptions, SignalOptions } from './client.js';
+import type { UiSessionLaunch } from '../models/ui-session-launch.js';
+import type { UiSessionRevocation } from '../models/ui-session-revocation.js';
+import type { ConnectAllOptions, ConnectAllResult, ConnectOptions, CreateSnapshotOptions, ListActorsQuery, Page, SignalOptions } from './client.js';
 import type { Credentials } from './credentials.js';
 /**
  * An environment as the API returned it, with helpers bound to it. The helpers are not
@@ -8,11 +12,23 @@ import type { Credentials } from './credentials.js';
  */
 export type Environment = EnvironmentData & EnvironmentHelpers;
 export interface EnvironmentHelpers {
-    /** Credentials for one app; `actorId` defaults to the app's default actor. */
+    /** Credentials for one app, acting as the user that `as` names, else as the app's default user. */
     connect(appName: string, options?: ConnectOptions): Promise<Credentials>;
+    /**
+     * Credentials for each app that lets the user that `as` names act. An app that
+     * does not have the user, or does not let the user sign in, adds its error to
+     * `errors`. Any other error throws.
+     */
+    connectAll(options: ConnectAllOptions): Promise<ConnectAllResult>;
+    /** One page of the users who can act in one app, the default user first. */
+    actors(appName: string, query?: ListActorsQuery): Promise<Page<AppUser>>;
     delete(options?: SignalOptions): Promise<Environment>;
+    /** Launches a browser session in a browser service of one app. The launch holds a one-use grant for one browser. */
+    launchUiSession(appName: string, input: LaunchUiSession, options?: SignalOptions): Promise<UiSessionLaunch>;
     /** Reads the environment again. */
     refresh(): Promise<Environment>;
+    /** Ends a browser session that this credential launched. Safe to repeat. */
+    revokeUiSession(appName: string, sessionId: string, options?: SignalOptions): Promise<UiSessionRevocation>;
     readonly snapshots: {
         /** Waits until `ready` unless `wait` is false. */
         create(input?: {

package/esm/extensions/errors.d.ts

@@ -1,5 +1,7 @@
+import type { AppUser } from '../models/app-user.js';
 import type { Environment as EnvironmentData } from '../models/environment.js';
 import type { ErrorCode } from '../models/error.js';
+import type { Import } from '../models/import.js';
 import type { ImportProblem } from '../models/import-problem.js';
 import type { Snapshot } from '../models/snapshot.js';
 export interface ErrorDetails {
@@ -42,6 +44,37 @@ export declare class SnapshotFailedError extends StateMachinesError {
     readonly problems: readonly ImportProblem[];
     constructor(snapshot: Snapshot);
 }
+/** An import that `snapshots.create` uploaded and its check left `invalid`, so the SDK created no snapshot. */
+export declare class ImportInvalidError extends StateMachinesError {
+    readonly name = "ImportInvalidError";
+    readonly import: Import;
+    /** The first problems that the check found, errors before warnings. `import.problemCount` counts them all. */
+    readonly problems: readonly ImportProblem[];
+    constructor(invalid: Import);
+}
+/** The app has no user with the email, username or ID that the call sent as `as`. */
+export declare class ActorNotFoundError extends StateMachinesError {
+    readonly appName: string;
+    /** The users who can act in the app that are nearest to `as`, nearest first. */
+    readonly nearest: readonly AppUser[];
+    readonly name = "ActorNotFoundError";
+    readonly code: 'actor_not_found';
+    constructor(error: StateMachinesError, appName: string, 
+    /** The users who can act in the app that are nearest to `as`, nearest first. */
+    nearest: readonly AppUser[]);
+}
+/** The app has the user, and does not let the user sign in now, for the reason in `fields.as`. */
+export declare class ActorCannotSignInError extends StateMachinesError {
+    readonly appName: string;
+    readonly name = "ActorCannotSignInError";
+    readonly code: 'actor_cannot_sign_in';
+    constructor(error: StateMachinesError, appName: string);
+}
+/**
+ * The typed error for an answer that refuses the user a credentials call
+ * names, else the error that any call fails with.
+ */
+export declare function actorError(error: unknown, appName: string): StateMachinesError;
 /** The resource reached a status from which the awaited one needs a call of yours. */
 export declare class UnexpectedStatusError extends Error {
     readonly resource: EnvironmentData | Snapshot;

package/esm/extensions/errors.js

@@ -92,6 +92,59 @@ export class SnapshotFailedError extends StateMachinesError {
         this.problems = problems;
     }
 }
+/** An import that `snapshots.create` uploaded and its check left `invalid`, so the SDK created no snapshot. */
+export class ImportInvalidError extends StateMachinesError {
+    name = 'ImportInvalidError';
+    import;
+    /** The first problems that the check found, errors before warnings. `import.problemCount` counts them all. */
+    problems;
+    constructor(invalid) {
+        super({
+            ...noResponse,
+            message: `Import ${invalid.id} is invalid.${firstProblem(invalid.problems)}`,
+        });
+        this.import = invalid;
+        this.problems = invalid.problems;
+    }
+}
+/** The app has no user with the email, username or ID that the call sent as `as`. */
+export class ActorNotFoundError extends StateMachinesError {
+    appName;
+    nearest;
+    name = 'ActorNotFoundError';
+    constructor(error, appName, 
+    /** The users who can act in the app that are nearest to `as`, nearest first. */
+    nearest) {
+        super(error);
+        this.appName = appName;
+        this.nearest = nearest;
+    }
+}
+/** The app has the user, and does not let the user sign in now, for the reason in `fields.as`. */
+export class ActorCannotSignInError extends StateMachinesError {
+    appName;
+    name = 'ActorCannotSignInError';
+    constructor(error, appName) {
+        super(error);
+        this.appName = appName;
+    }
+}
+/**
+ * The typed error for an answer that refuses the user a credentials call
+ * names, else the error that any call fails with.
+ */
+export function actorError(error, appName) {
+    const failure = toStateMachinesError(error);
+    const body = error instanceof ErrorT ? error.error : null;
+    switch (body?.code) {
+        case 'actor_not_found':
+            return new ActorNotFoundError(failure, appName, body.nearest ?? []);
+        case 'actor_cannot_sign_in':
+            return new ActorCannotSignInError(failure, appName);
+        default:
+            return failure;
+    }
+}
 /** The resource reached a status from which the awaited one needs a call of yours. */
 export class UnexpectedStatusError extends Error {
     resource;

package/esm/extensions/import-data.d.ts

@@ -0,0 +1,43 @@
+/** An import as one object, which is its manifest with each app's records and content in it. */
+export interface ImportData {
+    readonly format: 'statemachines.import/v1';
+    /** The import's name. */
+    readonly name: string;
+    /** By the app's name in the import, such as `salesforce`. */
+    readonly apps: Readonly<Record<string, ImportAppData>>;
+}
+/** One app of an import: its settings, its records and the files that its records name. */
+export interface ImportAppData {
+    /** Defaults to the app's name in the import. */
+    readonly appId?: string;
+    /**
+     * What the load does with a record that cannot load. `refuse`, the default,
+     * fails the snapshot. `skipRecord` leaves the record out, with each record
+     * that references it.
+     */
+    readonly loadMode?: 'skipRecord' | 'refuse';
+    /** The users to act as, by email, username or ID. */
+    readonly actors?: readonly string[];
+    /** The objects that the load leaves out, and the fields that it leaves out by object. */
+    readonly skip?: {
+        readonly objects?: readonly string[];
+        readonly fields?: Readonly<Record<string, readonly string[]>>;
+    };
+    /** The records in the app's own JSON, by object, such as `Account`. */
+    readonly records?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
+    /**
+     * The bytes of the files that the app's records name, by path inside the
+     * app's `content/` folder, such as Box's `file_version/41500000004`.
+     */
+    readonly content?: Readonly<Record<string, Uint8Array>>;
+}
+/**
+ * The zip file of `data` in the folder form. `statemachines.json` holds the
+ * manifest without each app's `records` and `content`. Each object's records
+ * go to `<app>/records/<Object>.jsonl`, one record per line, so line N of the
+ * file names the record at index N - 1. Each content file goes to
+ * `<app>/content/<path>`. Data in a shape that the folder form cannot hold
+ * throws `invalid_request`, with the path of each wrong field. The API checks
+ * the rest.
+ */
+export declare function zipImport(data: ImportData): Uint8Array<ArrayBuffer>;

package/esm/extensions/import-data.js

@@ -0,0 +1,88 @@
+import { invalidInput } from './errors.js';
+import { zipFiles } from './zip.js';
+const PLAIN_OBJECT = 'Expected a plain object.';
+const utf8 = new TextEncoder();
+/**
+ * The zip file of `data` in the folder form. `statemachines.json` holds the
+ * manifest without each app's `records` and `content`. Each object's records
+ * go to `<app>/records/<Object>.jsonl`, one record per line, so line N of the
+ * file names the record at index N - 1. Each content file goes to
+ * `<app>/content/<path>`. Data in a shape that the folder form cannot hold
+ * throws `invalid_request`, with the path of each wrong field. The API checks
+ * the rest.
+ */
+export function zipImport(data) {
+    const fields = shapeProblems(data);
+    if (Object.keys(fields).length > 0) {
+        throw invalidInput('The import data is invalid.', fields);
+    }
+    return zipFiles(folderFiles(data));
+}
+/** The fields of `data` that the folder form cannot hold, by dotted path. */
+function shapeProblems(data) {
+    const fields = {};
+    const add = (path, message) => {
+        fields[path] = [...(fields[path] ?? []), message];
+    };
+    const entriesAt = (value, path) => {
+        if (isPlainObject(value)) {
+            return Object.entries(value);
+        }
+        add(path, PLAIN_OBJECT);
+        return [];
+    };
+    if (!isPlainObject(data)) {
+        add('import', PLAIN_OBJECT);
+        return fields;
+    }
+    const { apps } = data;
+    for (const [name, app] of entriesAt(apps, 'import.apps')) {
+        const at = `import.apps.${name}`;
+        if (!isPlainObject(app)) {
+            add(at, PLAIN_OBJECT);
+            continue;
+        }
+        const { records = {}, content = {} } = app;
+        for (const [object, list] of entriesAt(records, `${at}.records`)) {
+            if (!Array.isArray(list)) {
+                add(`${at}.records.${object}`, 'Expected an array.');
+                continue;
+            }
+            for (const [index, record] of list.entries()) {
+                if (!isPlainObject(record)) {
+                    add(`${at}.records.${object}.${index}`, PLAIN_OBJECT);
+                }
+            }
+        }
+        for (const [path, bytes] of entriesAt(content, `${at}.content`)) {
+            if (!(bytes instanceof Uint8Array)) {
+                add(`${at}.content.${path}`, 'Expected a Uint8Array.');
+            }
+        }
+    }
+    return fields;
+}
+function folderFiles(data) {
+    const files = new Map();
+    const apps = {};
+    for (const [name, app] of Object.entries(data.apps)) {
+        const { records = {}, content = {}, ...settings } = app;
+        apps[name] = settings;
+        for (const [object, list] of Object.entries(records)) {
+            files.set(`${name}/records/${object}.jsonl`, utf8.encode(list.map((record) => `${JSON.stringify(record)}\n`).join('')));
+        }
+        for (const [path, bytes] of Object.entries(content)) {
+            files.set(`${name}/content/${path}`, bytes);
+        }
+    }
+    // The spread keeps any field that the manifest refuses, so the API names it.
+    files.set('statemachines.json', utf8.encode(`${JSON.stringify({ ...data, apps }, null, 2)}\n`));
+    return files;
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/esm/extensions/index.d.ts

@@ -1,8 +1,9 @@
-export type { Actor, App, AppEntry, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, Import, ImportApp, ImportProblem, ImportStatus, Me, Permission, Principal, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotStatus, Version, Workspace, } from '../models/index.js';
-export type { ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListAuditEventsQuery, ListEnvironmentsQuery, ListImportsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, SignalOptions, StateMachinesOptions, UploadImportOptions, } from './client.js';
+export type { AbsentReason, AbsentRecord, Actor, App, AppEntry, AppUser, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, FilledField, Import, ImportActor, ImportApp, ImportProblem, ImportStatus, KnownDifference, LaunchUiSession, MadeId, MatchedRecord, Me, ObjectLoad, Permission, Principal, ProblemCounts, RecordSource, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotAppLoad, SnapshotAppLoadCounts, SnapshotListItem, SnapshotStatus, UiSessionLaunch, UiSessionMode, UiSessionRevocation, Version, Workspace, } from '../models/index.js';
+export type { ConnectAllOptions, ConnectAllResult, ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListActorsQuery, ListAuditEventsQuery, ListEnvironmentsQuery, ListImportsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, SignalOptions, StateMachinesOptions, UploadImportOptions, } from './client.js';
 export { StateMachines } from './client.js';
 export type { Credentials, McpServerCredentials, ServiceCredentials, } from './credentials.js';
 export type { Environment, EnvironmentHelpers } from './environment.js';
-export { EnvironmentFailedError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
+export { ActorCannotSignInError, ActorNotFoundError, EnvironmentFailedError, ImportInvalidError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
+export type { ImportAppData, ImportData } from './import-data.js';
 export type { WaitOptions } from './wait.js';
 export { parseEnvironmentYaml } from './yaml.js';

package/esm/extensions/index.js

@@ -1,3 +1,3 @@
 export { StateMachines } from './client.js';
-export { EnvironmentFailedError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
+export { ActorCannotSignInError, ActorNotFoundError, EnvironmentFailedError, ImportInvalidError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
 export { parseEnvironmentYaml } from './yaml.js';

package/esm/extensions/packaging.d.ts

@@ -0,0 +1 @@
+export { zipFiles } from './zip.js';

package/esm/extensions/packaging.js

@@ -0,0 +1 @@
+export { zipFiles } from './zip.js';

package/esm/extensions/zip.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A zip file of `files`, keyed by their paths, in the order of their paths.
+ * Each file is stored, with a UTF-8 name, the earliest MS-DOS time, and no
+ * extra field, so the same files always give the same bytes. It refuses what
+ * needs ZIP64. It needs no `node:zlib`, because the SDK imports no Node
+ * module and runs in Cloudflare Workers.
+ */
+export declare function zipFiles(files: ReadonlyMap<string, Uint8Array>): Uint8Array<ArrayBuffer>;