@statelyai/sdk 0.13.0 → 0.13.2

package/README.md

@@ -1,20 +1,32 @@
 # @statelyai/sdk
 
-> **Preview** -- this SDK is not yet publicly available. Reach out to [team@stately.ai](mailto:team@stately.ai) for early access.
+The public alpha SDK for embedding the Stately visual editor, inspecting live
+actor systems, and using the Stately Studio API.
 
-The Stately SDK lets you embed the [Stately visual editor](https://stately.ai) directly into your own application, inspect live actor systems, and programmatically manage Stately Studio projects and machines.
+APIs may change between minor releases. Review generated source changes before
+committing them.
 
-## What's coming
+## Install
+
+<!-- install command derived from package.json#name -->
+
+```bash
+npm install @statelyai/sdk
+```
+
+## Capabilities
 
 ### Embeddable editor
 
+<!-- createStatelyEmbed usage from src/embed.ts and the hosted editor URL -->
+
 Drop a fully interactive state machine editor into any web app. The embed communicates over `postMessage` and gives you full control over theme, layout, panels, read-only mode, and more.
 
 ```ts
 import { createStatelyEmbed } from '@statelyai/sdk';
 
 const embed = createStatelyEmbed({
-  baseUrl: 'https://stately.ai',
+  baseUrl: 'https://editor.stately.ai',
   apiKey: 'your-api-key',
 });
 
@@ -68,30 +80,6 @@ Key capabilities:
 - **Asset uploads** with built-in S3 and Supabase adapters, or bring your own upload handler
 - **Runtime settings** - toggle color mode, grid, snap lines, autolayout, and view mode on the fly
 
-### Self-hosting
-
-The SDK is designed to work with both hosted Stately (`stately.ai`) and self-hosted deployments of the editor.
-
-When self-hosting, authentication is handled by your editor server, not by this npm package. The editor host supports configurable auth strategies, and you can disable API-key checks for editor-sync endpoints when running behind your own auth layer.
-
-A fully self-contained deployment with no external auth looks like:
-
-```ts
-const embed = createStatelyEmbed({
-  baseUrl: 'https://your-editor.example.com',
-});
-```
-
-Key environment variables for self-hosted deployments:
-
-| Variable                    | Purpose                                      |
-| --------------------------- | -------------------------------------------- |
-| `AUTH_PROVIDER`             | Auth strategy used by the editor host        |
-| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to skip editor-sync API-key checks |
-| `STATELY_API_KEY`           | Server-side API key for Stately data fetching |
-| `STATELY_API_URL`           | Stately API base URL override                |
-| `NEXT_PUBLIC_BASE_URL`      | Public-facing editor URL                     |
-
 ### Studio API client
 
 Programmatic access to Stately Studio for managing projects and machines, extracting machine configs from source code, and verifying API keys.
@@ -112,8 +100,10 @@ const extracted = await studio.code.extractMachines(sourceCode);
 ```
 
 Legacy `apiKey` is still accepted as an alias for
-`credential: { type: 'api_key', token }`. Use `authMode: 'none'` only for
-self-hosted deployments that intentionally accept unauthenticated calls.
+`credential: { type: 'api_key', token }`. The default `authMode: 'auto'` sends
+a credential when present and otherwise lets the server accept or reject an
+unauthenticated request. Use `authMode: 'bearer'` to require a credential before
+making requests, or `authMode: 'none'` to ignore a configured credential.
 
 ### Inspector
 
@@ -127,7 +117,7 @@ import { createInspector } from '@statelyai/sdk';
 
 const actor = createActor(machine);
 const inspector = createInspector({
-  url: 'ws://localhost:1999/inspect/local',
+  url: 'ws://localhost:4242',
 });
 
 inspector.inspect(actor);
@@ -136,15 +126,25 @@ actor.start();
 
 XState v5 and v6 inspection events normalize to actor, transition, and stop
 events before crossing the WebSocket protocol.
-In Node, the inspector opens in the default browser automatically.
+In Node, the inspector opens in the default browser automatically. The SDK
+generates a cryptographically random session capability; hosted inspectors send
+signed-out users through OAuth and return them to that same live session. The
+Node process does not need a Stately API key.
 
 ### CLI and sync
 
-A `statelyai` CLI for syncing local XState source files with Stately Studio projects: push local machines to the cloud, pull remote changes back into source, and open a local file in a browser-backed visual editor session.
+<!-- CLI package identity and commands from ../cli/package.json and ../cli/src/cli.ts#COMMANDS -->
+
+The separate [`statelyai`](https://www.npmjs.com/package/statelyai) CLI syncs
+local XState source files with Stately Studio projects: push local machines,
+pull remote changes, inspect project inventory, compare machines, and open a
+local file in a browser-backed visual editor session.
 
 ```bash
+npx statelyai status
 npx statelyai push
 npx statelyai pull
+npx statelyai diff ./checkout.machine.ts machine-id
 npx statelyai open ./checkout.machine.ts
 ```
 
@@ -152,6 +152,38 @@ npx statelyai open ./checkout.machine.ts
 
 Convert between Studio graph data, XState machine configs, and TypeScript source. Generate types from JSON Schema.
 
-## Get notified
+## Support
+
+For pricing and support, contact
+[team@stately.ai](mailto:team@stately.ai).
+
+## Self-hosting
+
+<!-- self-host configuration from the editor app auth and editor-sync routes -->
+
+The SDK works with both the hosted Stately editor (`editor.stately.ai`) and
+self-hosted deployments.
+
+When self-hosting, authentication is handled by your editor server, not by this
+npm package. The editor host supports configurable auth strategies, and you can
+disable API-key checks for editor-sync endpoints when running behind your own
+auth layer.
+
+A fully self-contained deployment with no external auth looks like:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: 'https://your-editor.example.com',
+});
+```
+
+Key environment variables for self-hosted deployments:
+
+| Variable                    | Purpose                                           |
+| --------------------------- | ------------------------------------------------- |
+| `AUTH_PROVIDER`             | Auth strategy used by the editor host             |
+| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to skip editor-sync API-key checks |
+| `NEXT_PUBLIC_BASE_URL`      | Public-facing editor URL                          |
 
-This SDK and the embeddable editor are in active development. For early access, pricing, and self-hosting details, contact [team@stately.ai](mailto:team@stately.ai).
+For self-hosting details, contact
+[team@stately.ai](mailto:team@stately.ai).

package/dist/index.d.mts

@@ -5,7 +5,7 @@ import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizati
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
 import { _ as serializeJS, c as MachineConfigOptions, d as contextSchemaToTSType, f as eventsSchemaToTSType, g as raw, h as jsonSchemaToTSType, i as CodeGenGraph, l as RawCode, m as graphToXStateTS, o as GraphPatch, p as graphToMachineConfig, t as ActionLocation, u as XStateTSOptions } from "./index-DVjNSTuQ.mjs";
 import { C as EventTypeData, S as DigraphNodeConfig, _ as studioMachineConverter, a as StatelyGraphData, b as DigraphConfig, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, o as StatelyGuard, r as StatelyEdgeData, t as StatelyAction, v as toStudioMachine, w as StateNodeJSONData, x as DigraphEdgeConfig, y as DigraphAction } from "./graph-R0sbxnZ7.mjs";
-import { a as InspectorEvents, c as createStatelyInspector, d as MultiplexedWebSocketConnectionOptions, f as Transport, h as createWebSocketTransport, i as Inspector, l as MultiplexedChannelOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as ManualActorOptions, p as createMultiplexedWebSocketConnection, r as InspectedTransition, s as createInspector, t as AdoptedActor, u as MultiplexedWebSocketConnection } from "./inspect-BMHheAvx.mjs";
+import { a as InspectorEvents, c as createStatelyInspector, d as MultiplexedWebSocketConnectionOptions, f as Transport, h as createWebSocketTransport, i as Inspector, l as MultiplexedChannelOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as ManualActorOptions, p as createMultiplexedWebSocketConnection, r as InspectedTransition, s as createInspector, t as AdoptedActor, u as MultiplexedWebSocketConnection } from "./inspect-COqtklcn.mjs";
 import { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, UpdateMachineInput, VerifyApiKeyResponse, XStateVersion, createStatelyClient } from "./studio.mjs";
 import { OAuthAuthorizationServerMetadata, OAuthClientRegistrationResponse, OAuthProtectedResourceMetadata, OAuthTokenResponse, PkcePair, buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { n as createPostMessageTransport, r as createWebSocketTransport, t as cr
 import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-D9GyHTTW.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-pcNCbL7j.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
 import { StudioApiError, createStatelyClient } from "./studio.mjs";
 import { buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";

package/dist/{inspect-BMHheAvx.d.mts → inspect-COqtklcn.d.mts}

@@ -204,8 +204,9 @@ interface CreateInspectorOptions {
   /** Auto-open browser to visualizer. Default: `true`. */
   autoOpen?: boolean;
   /**
-   * Relay session id. Defaults to a random id. This is the `?session=<id>`
-   * value the viz iframe connects with.
+   * Relay session capability. Defaults to a cryptographically random UUID.
+   * This is the `?session=<id>` value the visualizer connects with. Custom
+   * values used with a hosted relay must be unguessable.
    */
   sessionId?: string;
   /** Display name for this system in the visualizer. */

package/dist/{inspect-D9GyHTTW.mjs → inspect-pcNCbL7j.mjs}

@@ -33,9 +33,9 @@ const defaultSerializeSnapshot = (snapshot) => ({
 	status: snapshot?.status
 });
 const defaultExtractMachineConfig = (actor, source) => actor?.logic?.config ?? source?.config ?? null;
-let nextManualId = 0;
 function generateSessionId() {
-	return `manual-${Date.now()}-${nextManualId++}`;
+	if (!globalThis.crypto?.randomUUID) throw new Error("createInspector() requires crypto.randomUUID() to generate a secure session capability. Pass sessionId explicitly in older runtimes.");
+	return globalThis.crypto.randomUUID();
 }
 function createInspectorLaunchUrl(websocketUrl, sessionId) {
 	try {

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
 import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition } from "./protocol.mjs";
-import { a as InspectorEvents, c as createStatelyInspector, f as Transport, i as Inspector, n as CreateInspectorOptions, o as ManualActorOptions, r as InspectedTransition, s as createInspector, t as AdoptedActor } from "./inspect-BMHheAvx.mjs";
+import { a as InspectorEvents, c as createStatelyInspector, f as Transport, i as Inspector, n as CreateInspectorOptions, o as ManualActorOptions, r as InspectedTransition, s as createInspector, t as AdoptedActor } from "./inspect-COqtklcn.mjs";
 export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, ManualActorOptions, Transport, createInspector, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,3 +1,3 @@
-import { n as createStatelyInspector, t as createInspector } from "./inspect-D9GyHTTW.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-pcNCbL7j.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/studio.mjs

@@ -91,8 +91,9 @@ function createStatelyClient(options = {}) {
 		const authMode = authModeOverride ?? defaultAuthMode;
 		const credential = credentialOverride ?? defaultCredential;
 		if (authMode !== "none") {
-			if (!getCredentialToken(credential) || !credential) throw new StudioApiError("No Stately credential configured. Pass createStatelyClient({ credential }) or set authMode: \"none\" for no-auth self-hosted deployments.", 401);
-			headers.set("Authorization", createAuthorizationHeader(credential));
+			const token = getCredentialToken(credential);
+			if (authMode === "bearer" && (!token || !credential)) throw new StudioApiError("No Stately credential configured. Pass createStatelyClient({ credential }) or use authMode: \"auto\" to let the server decide whether authentication is required.", 401);
+			if (token && credential) headers.set("Authorization", createAuthorizationHeader(credential));
 		}
 		const response = await fetchImpl(joinApiUrl(baseUrl, path), {
 			...init,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "license": "MIT",
   "files": [
     "dist",