@statelyai/sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @statelyai/sdk
 
-Embed the [Stately editor](https://stately.ai) in your app. Zero dependencies, fully typed.
+Embed the [Stately editor](https://stately.ai) in your app and talk to the Stately Studio API. Zero dependencies, fully typed.
 
 ## Install
 
@@ -8,9 +8,13 @@ Embed the [Stately editor](https://stately.ai) in your app. Zero dependencies, f
 npm install @statelyai/sdk
 ```
 
-## API key
+## Authentication
 
-An API key is required to use the embed SDK. To get one:
+The editor uses a pluggable authentication system. How you configure it depends on whether you're using the hosted Stately platform or self-hosting.
+
+### With Stately (default)
+
+An API key is required. To get one:
 
 1. Go to your [Stately settings](https://stately.ai/settings)
 2. Select the **API Key** tab
@@ -19,8 +23,68 @@ An API key is required to use the embed SDK. To get one:
 
 See the [Studio API docs](https://stately.ai/docs/studio-api) for more details.
 
+Pass the key to the SDK:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  apiKey: 'your-api-key',
+});
+```
+
+The server validates the key against the Stately registry API.
+
+### Self-hosting
+
+When self-hosting the editor, authentication is controlled by the `AUTH_PROVIDER` environment variable on the server:
+
+| Value | Behavior |
+| ---------- | ----------------------------------------------------------- |
+| `stately` | Validates tokens against the Stately registry API |
+| `none` | Allows all requests (no authentication) |
+| _(unset)_ | `none` in development, `stately` in production |
+
+For a fully self-contained deployment with no Stately dependency:
+
+```bash
+AUTH_PROVIDER=none
+```
+
+### Custom authentication
+
+You can implement your own auth by writing a custom `AuthValidator` — an async function that receives a token and returns whether it's valid:
+
+```ts
+import type { AuthValidator } from '@/lib/auth';
+
+const myValidator: AuthValidator = async (token) => {
+  const res = await fetch('https://my-auth-server.com/verify', {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  return res.ok;
+};
+```
+
+The built-in adapters are:
+
+- **`createStatelyValidator(baseUrl?)`** — verifies against the Stately registry API (`/registry/api/v1/verify`)
+- **`allowAllValidator`** — always returns `true`
+
+To use a custom validator, call `getAuthValidator()` from `src/lib/auth` in the server-side page code, or replace the resolver logic in `src/lib/auth/index.tsx` to return your implementation.
+
+### Environment variables
+
+| Variable | Purpose |
+| ----------------------- | -------------------------------------------- |
+| `AUTH_PROVIDER` | Auth strategy: `stately`, `none`, or unset |
+| `STATELY_API_KEY` | Server-side API key for Stately data fetching |
+| `STATELY_API_URL` | Stately API base URL (server-side override) |
+| `NEXT_PUBLIC_BASE_URL` | Public-facing base URL |
+
 ## Quick start
 
+### Third-party embed (with API key)
+
 ```ts
 import { createStatelyEmbed } from '@statelyai/sdk';
 
@@ -29,10 +93,8 @@ const embed = createStatelyEmbed({
   apiKey: 'your-api-key',
 });
 
-// Mount into a container
 embed.mount(document.getElementById('editor')!);
 
-// Initialize with a machine
 embed.init({
   machine: myMachineConfig,
   mode: 'editing',
@@ -40,26 +102,84 @@ embed.init({
 });
 ```
 
+### Same-origin embed (cookie auth)
+
+When the embed host and the editor share a domain (e.g. Stately Studio embedding the beta editor), Supabase session cookies handle auth automatically — no API key needed:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: process.env.NEXT_PUBLIC_BETA_EDITOR_URL ?? window.location.origin,
+});
+
+embed.mount(container);
+```
+
+### Self-hosted (no auth)
+
+When self-hosting with `AUTH_PROVIDER=none`, no token is required:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: 'https://your-editor.example.com',
+});
+
+embed.mount(container);
+```
+
+## Module layout
+
+The SDK ships direct root exports for the common entry points:
+
+```ts
+import {
+  createStatelyInspector,
+  createStatelyEmbed,
+  createStatelyClient,
+} from '@statelyai/sdk';
+```
+
+It also supports subpath imports when you want a narrower surface:
+
+```ts
+import { createStatelyClient } from '@statelyai/sdk/studio';
+import { createStatelyInspector } from '@statelyai/sdk/inspect';
+import { createStatelyEmbed } from '@statelyai/sdk/embed';
+```
+
+## Studio API client
+
+```ts
+import { createStatelyClient } from '@statelyai/sdk';
+
+const studio = createStatelyClient({
+  apiKey: process.env.STATELY_API_KEY,
+});
+
+const project = await studio.projects.get('project-id');
+const machine = await studio.machines.get('machine-id', { version: '42' });
+const extracted = await studio.code.extractMachines(sourceCode);
+```
+
 ## API
 
 ### `createStatelyEmbed(options)`
 
 Creates an embed instance.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `baseUrl` | `string` | **Required.** Base URL of the Stately app |
-| `apiKey` | `string` | **Required.** Your Stately API key |
-| `origin` | `string` | Custom target origin for postMessage |
-| `onReady` | `() => void` | Called when embed is ready |
-| `onLoaded` | `(graph) => void` | Called when machine is loaded |
-| `onChange` | `(graph, machineConfig) => void` | Called on every change |
-| `onSave` | `(graph, machineConfig) => void` | Called on save |
-| `onError` | `({ code, message }) => void` | Called on error |
+| Option     | Type                             | Description                               |
+| ---------- | -------------------------------- | ----------------------------------------- |
+| `baseUrl`  | `string`                         | **Required.** Base URL of the Stately app  |
+| `apiKey`   | `string`                         | API key for authentication (see [Authentication](#authentication)) |
+| `origin`   | `string`                         | Custom target origin for postMessage      |
+| `onReady`  | `() => void`                     | Called when embed is ready                |
+| `onLoaded` | `(graph) => void`                | Called when machine is loaded             |
+| `onChange` | `(graph, machineConfig) => void` | Called on every change                    |
+| `onSave`   | `(graph, machineConfig) => void` | Called on save                            |
+| `onError`  | `({ code, message }) => void`    | Called on error                           |
 
 ### Embed methods
 
-#### `mount(container)` / `attach(iframe)`
+#### `embed.mount(container)` / `embed.attach(iframe)`
 
 Mount creates an iframe inside a container element. Attach connects to an existing iframe.
 
@@ -71,7 +191,7 @@ const iframe = embed.mount(document.getElementById('editor')!);
 embed.attach(document.querySelector('iframe')!);
 ```
 
-#### `init(options)`
+#### `embed.init(options)`
 
 Initialize the embed with a machine and display options.
 
@@ -79,8 +199,8 @@ Initialize the embed with a machine and display options.
 embed.init({
   machine: machineConfig,
   format: 'xstate', // optional
-  mode: 'editing',  // 'editing' | 'viewing' | 'simulating'
-  theme: 'dark',    // 'light' | 'dark'
+  mode: 'editing', // 'editing' | 'viewing' | 'simulating'
+  theme: 'dark', // 'light' | 'dark'
   readOnly: false,
   depth: 3,
   panels: {
@@ -91,15 +211,15 @@ embed.init({
 });
 ```
 
-#### `updateMachine(machine, format?)`
+#### `embed.updateMachine(machine, format?)`
 
 Update the displayed machine.
 
-#### `setMode(mode)` / `setTheme(theme)`
+#### `embed.setMode(mode)` / `embed.setTheme(theme)`
 
 Change the embed mode or theme at runtime.
 
-#### `export(format, options?)`
+#### `embed.export(format, options?)`
 
 Export the current machine. Returns a promise.
 
@@ -111,7 +231,7 @@ const mermaid = await embed.export('mermaid');
 
 Supported formats: `xstate`, `json`, `digraph`, `mermaid`, `scxml`
 
-#### `on(event, handler)` / `off(event, handler)`
+#### `embed.on(event, handler)` / `embed.off(event, handler)`
 
 Subscribe/unsubscribe to embed events: `ready`, `loaded`, `change`, `save`, `error`.
 
@@ -121,10 +241,10 @@ embed.on('change', ({ graph, machineConfig }) => {
 });
 ```
 
-#### `toast(message, type?)`
+#### `embed.toast(message, type?)`
 
 Show a toast notification in the embed. Type: `'success' | 'error' | 'info' | 'warning'`
 
-#### `destroy()`
+#### `embed.destroy()`
 
 Tear down the embed. Removes listeners, rejects pending promises, and removes the iframe if it was created via `mount()`.

package/dist/embed.d.mts

@@ -0,0 +1,43 @@
+import { a as ExportCallOptions, c as InitOptions, i as EmbedMode, n as EmbedEventMap, o as ExportFormat, r as EmbedEventName, s as ExportFormatMap, t as EmbedEventHandler } from "./protocol-BC-_s3if.mjs";
+
+//#region src/embed.d.ts
+interface StatelyEmbedOptions {
+  baseUrl: string;
+  apiKey?: string;
+  origin?: string;
+  onReady?: () => void;
+  onLoaded?: (graph: unknown) => void;
+  onChange?: (graph: unknown, machineConfig: unknown) => void;
+  onSave?: (graph: unknown, machineConfig: unknown) => void;
+  onError?: (error: {
+    code: string;
+    message: string;
+  }) => void;
+}
+interface StatelyEmbed {
+  /** Attach to an existing iframe element. Sets src and begins handshake. */
+  attach(iframe: HTMLIFrameElement): void;
+  /** Create an iframe and mount it into a container element. */
+  mount(container: HTMLElement): HTMLIFrameElement;
+  /** Send init message (queued if iframe not ready yet). */
+  init(options: InitOptions): void;
+  /** Update the machine (shorthand for update message). */
+  updateMachine(machine: unknown, format?: string): void;
+  /** Change the embed mode. */
+  setMode(mode: EmbedMode): void;
+  /** Change the embed theme. */
+  setTheme(theme: 'light' | 'dark'): void;
+  /** Export the current machine in a given format. Returns a promise. */
+  export<F extends ExportFormat>(format: F, options?: ExportCallOptions<F>): Promise<ExportFormatMap[F]['result']>;
+  /** Subscribe to an embed event. */
+  on<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Unsubscribe from an embed event. */
+  off<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Show a toast message in the embed. */
+  toast(message: string, toastType?: 'success' | 'error' | 'info' | 'warning'): void;
+  /** Tear down: remove listener, reject pending promises, optionally remove iframe. */
+  destroy(): void;
+}
+declare function createStatelyEmbed(options: StatelyEmbedOptions): StatelyEmbed;
+//#endregion
+export { type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed };

package/dist/embed.mjs

@@ -0,0 +1,175 @@
+import { i as createPendingExportManager, o as toInitMessage, r as createEventRegistry, t as createPostMessageTransport } from "./transport-D352iKKa.mjs";
+
+//#region src/embed.ts
+function createStatelyEmbed(options) {
+	const base = options.baseUrl.replace(/\/+$/, "") + "/embed";
+	const embedUrl = options.apiKey ? `${base}?api_key=${encodeURIComponent(options.apiKey)}` : base;
+	const targetOrigin = options.origin ?? new URL(embedUrl).origin;
+	let iframe = null;
+	let transport = null;
+	let ownedIframe = false;
+	let destroyed = false;
+	const pendingMessages = [];
+	const events = createEventRegistry();
+	const exportManager = createPendingExportManager((message) => send(message));
+	function send(msg) {
+		if (!transport?.ready) {
+			pendingMessages.push(msg);
+			return;
+		}
+		transport.send(msg);
+	}
+	function flush() {
+		if (!transport) return;
+		while (pendingMessages.length > 0) {
+			const msg = pendingMessages.shift();
+			transport.send(msg);
+		}
+	}
+	function handleMessage(data) {
+		if (destroyed) return;
+		switch (data.type) {
+			case "@statelyai.ready": {
+				const ready = data;
+				flush();
+				options.onReady?.();
+				events.emit("ready", { version: ready.version });
+				break;
+			}
+			case "@statelyai.loaded": {
+				const loaded = data;
+				options.onLoaded?.(loaded.graph);
+				events.emit("loaded", { graph: loaded.graph });
+				break;
+			}
+			case "@statelyai.change": {
+				const change = data;
+				options.onChange?.(change.graph, change.machineConfig);
+				events.emit("change", {
+					graph: change.graph,
+					machineConfig: change.machineConfig
+				});
+				break;
+			}
+			case "@statelyai.save": {
+				const save = data;
+				options.onSave?.(save.graph, save.machineConfig);
+				events.emit("save", {
+					graph: save.graph,
+					machineConfig: save.machineConfig
+				});
+				break;
+			}
+			case "@statelyai.retrieved": {
+				const retrieved = data;
+				exportManager.resolve(retrieved.requestId, retrieved.data);
+				break;
+			}
+			case "@statelyai.error": {
+				const error = data;
+				const err = {
+					code: error.code,
+					message: error.message
+				};
+				exportManager.reject(new Error(err.message), error.requestId);
+				options.onError?.(err);
+				events.emit("error", err);
+				break;
+			}
+		}
+	}
+	function replaceTransport(nextTransport) {
+		transport?.destroy();
+		transport = nextTransport;
+	}
+	function setupTransport(el) {
+		const nextTransport = createPostMessageTransport({
+			iframe: el,
+			targetOrigin
+		});
+		replaceTransport(nextTransport);
+		nextTransport.onMessage(handleMessage);
+		nextTransport.onReady(flush);
+	}
+	return {
+		attach(el) {
+			if (destroyed) return;
+			const currentSrc = el.getAttribute("src");
+			if (currentSrc && currentSrc !== "about:blank" && el.src !== embedUrl) console.warn("Replacing existing iframe src during attach()", {
+				currentSrc,
+				nextSrc: embedUrl
+			});
+			iframe = el;
+			ownedIframe = false;
+			el.src = embedUrl;
+			setupTransport(el);
+		},
+		mount(container) {
+			if (destroyed) throw new Error("Embed is destroyed");
+			const el = document.createElement("iframe");
+			el.src = embedUrl;
+			el.style.border = "none";
+			el.style.width = "100%";
+			el.style.height = "100%";
+			el.setAttribute("sandbox", "allow-scripts allow-same-origin");
+			el.setAttribute("allow", "clipboard-read; clipboard-write");
+			container.appendChild(el);
+			iframe = el;
+			ownedIframe = true;
+			setupTransport(el);
+			return el;
+		},
+		init(opts) {
+			send(toInitMessage(opts));
+		},
+		updateMachine(machine, format) {
+			send({
+				type: "@statelyai.update",
+				machine,
+				format
+			});
+		},
+		setMode(mode) {
+			send({
+				type: "@statelyai.setMode",
+				mode
+			});
+		},
+		setTheme(theme) {
+			send({
+				type: "@statelyai.setTheme",
+				theme
+			});
+		},
+		toast(message, toastType) {
+			send({
+				type: "@statelyai.toast",
+				message,
+				toastType
+			});
+		},
+		export(format, callOptions) {
+			return exportManager.start(format, callOptions, "Embed is destroyed", () => destroyed);
+		},
+		on(event, handler) {
+			events.on(event, handler);
+		},
+		off(event, handler) {
+			events.off(event, handler);
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			transport?.destroy();
+			transport = null;
+			exportManager.clear("Embed destroyed");
+			events.clear();
+			pendingMessages.length = 0;
+			if (ownedIframe && iframe) iframe.remove();
+			iframe = null;
+		}
+	};
+}
+
+//#endregion
+export { createStatelyEmbed };