@statelyai/sdk 0.10.0 → 0.10.2

package/README.md

@@ -1,26 +1,110 @@
 # @statelyai/sdk
 
-Shared SDK modules for Stately clients, sync helpers, graph conversion, and code generation.
+> **Preview** -- this SDK is not yet publicly available. Reach out to [team@stately.ai](mailto:team@stately.ai) for early access.
 
-The Stately CLI now lives in:
+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.
 
-- `statelyai`
+## What's coming
 
-If you want the command-line workflow, use:
+### Embeddable editor
 
-```bash
-npx statelyai --help
+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',
+  apiKey: 'your-api-key',
+});
+
+embed.mount(document.getElementById('editor')!);
+
+embed.init({
+  machine: myMachineConfig,
+  format: 'xstate',
+  mode: 'editing',
+  theme: 'dark',
+});
 ```
 
-This package is the programmatic dependency used by that CLI.
+Key capabilities:
+
+- **Mount or attach** to any container element or existing iframe
+- **Two-way sync** - push machine configs in, get changes and saves back via event callbacks
+- **Export** to multiple formats: XState v5, XState JSON, Mermaid, Redux, Zustand, ASL, SCXML, and more
+- **Comments** via Liveblocks integration (optional)
+- **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
 
-The broader in-progress package documentation draft is kept in:
+Programmatic access to Stately Studio for managing projects and machines, extracting machine configs from source code, and verifying API keys.
+
+```ts
+import { createStatelyClient } from '@statelyai/sdk';
+
+const studio = createStatelyClient({
+  apiKey: process.env.STATELY_API_KEY,
+});
+
+const projects = await studio.projects.list();
+const machine = await studio.machines.get('machine-id');
+const extracted = await studio.code.extractMachines(sourceCode);
+```
+
+### Inspector
+
+Stream live actor-system state to the Stately inspector over WebSockets, with support for automatic XState actor adoption and manual actor registration.
+
+```ts
+import { createActor } from 'xstate';
+import { createStatelyInspector } from '@statelyai/sdk';
+
+const inspector = createStatelyInspector({
+  actor: createActor(machine),
+  autoOpen: true,
+});
+```
+
+### 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.
+
+```bash
+npx statelyai push
+npx statelyai pull
+npx statelyai open ./checkout.machine.ts
+```
 
-- [README-next.md](./README-next.md)
+### Graph and codegen helpers
 
-Published schemas:
+Convert between Studio graph data, XState machine configs, and TypeScript source. Generate types from JSON Schema.
 
-- `@statelyai/sdk/statelyai.schema.json`
-- `@statelyai/sdk/xstate.schema.json`
+## Get notified
 
-The CLI-facing `statelyai.json` schema now uses top-level `include` / `exclude` globs for local file discovery, plus `newMachineDir` for pulling remote-only project machines into new local files.
+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).

package/dist/{graph-DmXh22Zu.d.mts → graph-GeuH-mFK.d.mts}

@@ -142,6 +142,8 @@ interface JSONSchema7 {
 //#endregion
 //#region ../graph-tools/src/codegenTypes.d.ts
 interface CodeGenAction {
+  /** Graph-native block id, referenced by `@statelyai.action.*` transitions. */
+  id?: string;
   type: string;
   params?: Record<string, unknown>;
 }
@@ -161,10 +163,18 @@ interface CodeExpression {
   '@type': 'code';
   lang: 'js' | 'ts';
   expr: string;
+  imports?: CodeImport[];
+}
+interface CodeImport {
+  package: string;
+  import: string;
+  importKind?: 'named' | 'default' | 'namespace';
+  version?: string;
 }
 interface CodeGenInvoke {
   src: string;
   id: string;
+  invocationId?: string;
   input?: Record<string, unknown> | CodeExpression;
   output?: Record<string, unknown> | CodeExpression;
 }
@@ -184,7 +194,7 @@ interface CodeGenNodeData {
   meta?: Record<string, unknown> | null;
   color?: string;
   parentId?: string | null;
-  temp?: boolean;
+  temp?: unknown;
 }
 interface CodeGenEdgeData {
   eventType: string;
@@ -194,7 +204,7 @@ interface CodeGenEdgeData {
   description?: string | null;
   color?: string;
   meta?: Record<string, unknown> | null;
-  temp?: boolean;
+  temp?: unknown;
 }
 interface CodeGenImplementation {
   id: string;
@@ -220,6 +230,7 @@ interface CodeGenActorImplementation {
   } | null;
 }
 interface CodeGenGraphData {
+  context?: Record<string, unknown> | CodeExpression | null;
   schemas?: {
     context?: Record<string, JSONSchema7> | null;
     events?: Record<string, JSONSchema7> | null;

package/dist/graph.d.mts

@@ -1,2 +1,2 @@
-import { _ as studioMachineConverter, a as StatelyGraphData, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, n as StatelyActorImplementation, o as StatelyGuard, p as StudioEventTypeData, r as StatelyEdgeData, s as StatelyImplementation, t as StatelyAction, u as StatelyTagImplementation, v as toStudioMachine } from "./graph-DmXh22Zu.mjs";
+import { _ as studioMachineConverter, a as StatelyGraphData, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, n as StatelyActorImplementation, o as StatelyGuard, p as StudioEventTypeData, r as StatelyEdgeData, s as StatelyImplementation, t as StatelyAction, u as StatelyTagImplementation, v as toStudioMachine } from "./graph-GeuH-mFK.mjs";
 export { StatelyAction, StatelyActorImplementation, StatelyEdgeData, StatelyGraph, StatelyGraphData, StatelyGuard, StatelyImplementation, StatelyInvoke, StatelyNodeData, StatelyTagImplementation, StudioAction, StudioEdge, StudioEventTypeData, StudioMachine, StudioNode, fromStudioMachine, studioMachineConverter, toStudioMachine };