@statelyai/sdk 0.3.0 → 0.4.0

package/README.md

@@ -126,6 +126,39 @@ const embed = createStatelyEmbed({
 embed.mount(container);
 ```
 
+### Comments
+
+Comments are optional and integrator-configured. Pass a `comments` object to
+`embed.init()` when you want Liveblocks-backed commenting enabled.
+
+```ts
+embed.init({
+  machine: machineConfig,
+  mode: 'editing',
+  comments: {
+    roomId: 'machine:checkout',
+    publicApiKey: 'pk_live_...',
+    userId: currentUserId ?? null,
+  },
+});
+```
+
+You can also use a custom auth endpoint instead of a public key:
+
+```ts
+embed.init({
+  machine: machineConfig,
+  comments: {
+    roomId: 'machine:checkout',
+    authEndpoint: '/api/liveblocks-auth',
+    userId: currentUserId ?? null,
+  },
+});
+```
+
+`roomId` is required when comments are enabled. `userId` is optional and only
+used for comment identity metadata.
+
 ## Module layout
 
 The SDK ships direct root exports for the common entry points:
@@ -171,6 +204,7 @@ Creates an embed instance.
 | `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      |
+| `assets`   | `AssetConfig`                    | Asset upload configuration (see [Asset uploads](#asset-uploads)) |
 | `onReady`  | `() => void`                     | Called when embed is ready                |
 | `onLoaded` | `(graph) => void`                | Called when machine is loaded             |
 | `onChange` | `(graph, machineConfig) => void` | Called on every change                    |
@@ -208,9 +242,23 @@ embed.init({
     rightPanels: ['events'],
     activePanels: ['code'],
   },
+  comments: {
+    roomId: 'machine:checkout',
+    publicApiKey: 'pk_live_...',
+  },
 });
 ```
 
+`comments` accepts:
+
+| Field | Type | Description |
+| ---------- | ---------- | ----------------------------------------------- |
+| `roomId` | `string` | **Required.** Liveblocks room identifier |
+| `publicApiKey` | `string` | Liveblocks public key |
+| `authEndpoint` | `string` | Custom Liveblocks auth endpoint |
+| `baseUrl` | `string` | Custom Liveblocks base URL for self-hosting |
+| `userId` | `string \| null` | Optional user identity metadata |
+
 #### `embed.updateMachine(machine, format?)`
 
 Update the displayed machine.
@@ -248,3 +296,99 @@ Show a toast notification in the embed. Type: `'success' | 'error' | 'info' | 'w
 #### `embed.destroy()`
 
 Tear down the embed. Removes listeners, rejects pending promises, and removes the iframe if it was created via `mount()`.
+
+### Asset uploads
+
+By default, dropped images are stored as base64 data URLs. To upload assets to your own storage, pass an `assets` config:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: {
+    onUploadRequest: async (file, { stateNodeId }) => {
+      // upload `file` (a File object) to your storage
+      // return { url } at minimum
+    },
+    accept: ['image/*'],          // MIME patterns (default: ['image/*'])
+    maxFileSize: 5 * 1024 * 1024, // bytes (default: 10 MB)
+  },
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | **Required.** Called when the editor needs to upload a file. Return the hosted URL. |
+| `accept` | `string[]` | Accepted MIME types. Supports wildcards (`image/*`). Default: `['image/*']` |
+| `maxFileSize` | `number` | Max file size in bytes. Default: `10_485_760` (10 MB) |
+
+`UploadResult`:
+
+```ts
+interface UploadResult {
+  url: string;                        // hosted URL (required)
+  name?: string;                      // display name (defaults to filename)
+  metadata?: Record<string, unknown>; // arbitrary metadata stored on the asset
+}
+```
+
+#### Example: AWS S3 (presigned URL)
+
+```ts
+import { createStatelyEmbed } from '@statelyai/sdk';
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: {
+    onUploadRequest: async (file) => {
+      // 1. Get a presigned upload URL from your backend
+      const { uploadUrl, publicUrl } = await fetch('/api/s3/presign', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          filename: file.name,
+          contentType: file.type,
+        }),
+      }).then((r) => r.json());
+
+      // 2. PUT the file directly to S3
+      await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': file.type },
+        body: file,
+      });
+
+      return { url: publicUrl, name: file.name };
+    },
+    accept: ['image/*'],
+    maxFileSize: 10 * 1024 * 1024,
+  },
+});
+```
+
+#### Example: Cloudflare R2 (worker upload)
+
+```ts
+import { createStatelyEmbed } from '@statelyai/sdk';
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: {
+    onUploadRequest: async (file) => {
+      const form = new FormData();
+      form.append('file', file);
+
+      // Upload via a Cloudflare Worker that writes to R2
+      const { url } = await fetch('https://uploads.example.com/assets', {
+        method: 'POST',
+        body: form,
+      }).then((r) => r.json());
+
+      return { url, name: file.name };
+    },
+    accept: ['image/*', 'application/pdf'],
+    maxFileSize: 25 * 1024 * 1024,
+  },
+});
+```
+
+If `onUploadRequest` throws or rejects, the editor shows an error toast. If no `assets` config is provided, files are stored as inline base64 data URLs (no network requests).

package/dist/cli.d.mts

@@ -0,0 +1,63 @@
+import "./graph-BfezxFKJ.mjs";
+import { SyncPlan } from "./sync.mjs";
+import { Command } from "@oclif/core";
+import * as _oclif_core_interfaces0 from "@oclif/core/interfaces";
+
+//#region src/cli.d.ts
+declare function formatPlanSummary(plan: SyncPlan): string;
+declare abstract class BaseSyncCommand extends Command {
+  static enableJsonFlag: boolean;
+  static flags: {
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    'fail-on-changes': _oclif_core_interfaces0.BooleanFlag<boolean>;
+    'api-key': _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+  };
+}
+declare abstract class ParsedSyncCommand extends BaseSyncCommand {
+  protected parseSync<T extends typeof BaseSyncCommand>(command: T): Promise<_oclif_core_interfaces0.ParserOutput<{
+    help: void;
+    'fail-on-changes': boolean;
+    'api-key': string;
+    'base-url': string;
+  }, {
+    [flag: string]: any;
+  }, {
+    [arg: string]: any;
+  }>>;
+}
+declare class PlanCommand extends ParsedSyncCommand {
+  static summary: string;
+  static description: string;
+  static args: {
+    source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare class DiffCommand extends ParsedSyncCommand {
+  static summary: string;
+  static description: string;
+  static args: {
+    source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare class PullCommand extends ParsedSyncCommand {
+  static summary: string;
+  static description: string;
+  static args: {
+    source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare const COMMANDS: {
+  plan: typeof PlanCommand;
+  diff: typeof DiffCommand;
+  pull: typeof PullCommand;
+};
+declare function run(argv?: string[]): Promise<void>;
+//#endregion
+export { COMMANDS, formatPlanSummary, run };

package/dist/cli.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { planSync, pullSync } from "./sync.mjs";
+import path from "node:path";
+import { Args, Command, Flags, flush, handle, run as run$1 } from "@oclif/core";
+
+//#region src/cli.ts
+function loadLocalEnv() {
+	if (typeof process.loadEnvFile !== "function") return;
+	const cwdEnvPath = path.join(process.cwd(), ".env.local");
+	try {
+		process.loadEnvFile(cwdEnvPath);
+	} catch {}
+}
+loadLocalEnv();
+const sharedFlags = {
+	help: Flags.help({ char: "h" }),
+	"fail-on-changes": Flags.boolean({
+		default: false,
+		description: "Exit with a nonzero code when differences are found"
+	}),
+	"api-key": Flags.string({
+		description: "Stately API key used for remote source or target resolution",
+		default: process.env.STATELY_API_KEY ?? process.env.NEXT_PUBLIC_STATELY_API_KEY
+	}),
+	"base-url": Flags.string({
+		description: "Base URL for Stately Studio or a self-hosted deployment",
+		default: process.env.STATELY_API_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? process.env.NEXT_PUBLIC_STATELY_API_URL
+	})
+};
+function formatChangeList(label, items) {
+	if (items.length === 0) return null;
+	return `${label}: ${items.map((item) => item.id).join(", ")}`;
+}
+function formatPlanSummary(plan) {
+	const lines = [
+		`Plan: ${plan.source.locator} -> ${plan.target.locator}`,
+		`Source: ${plan.source.kind} (${plan.source.format})`,
+		`Target: ${plan.target.kind} (${plan.target.format})`,
+		`Has changes: ${plan.summary.hasChanges ? "yes" : "no"}`,
+		`Node changes: ${plan.summary.nodeChanges}`,
+		`Edge changes: ${plan.summary.edgeChanges}`
+	];
+	const nodeSections = [
+		formatChangeList("Added nodes", plan.diff.nodes.added),
+		formatChangeList("Removed nodes", plan.diff.nodes.removed),
+		formatChangeList("Updated nodes", plan.diff.nodes.updated)
+	].filter(Boolean);
+	const edgeSections = [
+		formatChangeList("Added edges", plan.diff.edges.added),
+		formatChangeList("Removed edges", plan.diff.edges.removed),
+		formatChangeList("Updated edges", plan.diff.edges.updated)
+	].filter(Boolean);
+	lines.push(...nodeSections, ...edgeSections);
+	if (plan.warnings.length > 0) lines.push(`Warnings: ${plan.warnings.join("; ")}`);
+	return lines.join("\n");
+}
+var BaseSyncCommand = class extends Command {
+	static enableJsonFlag = false;
+	static flags = sharedFlags;
+};
+const sharedArgs = {
+	source: Args.string({
+		required: true,
+		description: "Source locator. Supports local file paths, URLs, or machine IDs."
+	}),
+	target: Args.string({
+		required: true,
+		description: "Target locator. Supports local file paths, URLs, or machine IDs."
+	})
+};
+var ParsedSyncCommand = class extends BaseSyncCommand {
+	async parseSync(command) {
+		return this.parse(command);
+	}
+};
+var PlanCommand = class PlanCommand extends ParsedSyncCommand {
+	static summary = "Plan semantic sync changes between a source and target.";
+	static description = "Resolves the source and target, normalizes both into graph form, and prints a semantic change summary.";
+	static args = sharedArgs;
+	async run() {
+		const { args, flags } = await this.parseSync(PlanCommand);
+		const plan = await planSync({
+			source: args.source,
+			target: args.target,
+			apiKey: flags["api-key"],
+			baseUrl: flags["base-url"]
+		});
+		this.log(formatPlanSummary(plan));
+		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
+	}
+};
+var DiffCommand = class DiffCommand extends ParsedSyncCommand {
+	static summary = "Diff a source and target using semantic graph comparison.";
+	static description = "Like plan, but intended for diff-style usage and exit codes in scripts.";
+	static args = sharedArgs;
+	async run() {
+		const { args, flags } = await this.parseSync(DiffCommand);
+		const plan = await planSync({
+			source: args.source,
+			target: args.target,
+			apiKey: flags["api-key"],
+			baseUrl: flags["base-url"]
+		});
+		this.log(formatPlanSummary(plan));
+		this.exit(flags["fail-on-changes"] && plan.summary.hasChanges ? 1 : 0);
+	}
+};
+var PullCommand = class PullCommand extends ParsedSyncCommand {
+	static summary = "Pull a source locator into a local target file.";
+	static description = "Resolves the source, materializes it in the target format inferred from the target file, and writes the result locally.";
+	static args = sharedArgs;
+	async run() {
+		const { args, flags } = await this.parseSync(PullCommand);
+		const result = await pullSync({
+			source: args.source,
+			target: args.target,
+			apiKey: flags["api-key"],
+			baseUrl: flags["base-url"]
+		});
+		this.log(`Pulled: ${result.source.locator} -> ${result.outputPath}\nTarget: ${result.target.kind} (${result.target.format})`);
+	}
+};
+const COMMANDS = {
+	plan: PlanCommand,
+	diff: DiffCommand,
+	pull: PullCommand
+};
+async function run(argv = process.argv.slice(2)) {
+	const normalizedArgv = argv.length === 1 && argv[0] === "-h" ? ["--help"] : argv;
+	try {
+		await run$1(normalizedArgv, import.meta.url);
+		await flush();
+	} catch (error) {
+		await handle(error);
+	}
+}
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) run();
+
+//#endregion
+export { COMMANDS, formatPlanSummary, run };

package/dist/embed.d.mts

@@ -1,10 +1,32 @@
-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";
+import { a as EmbedMode, c as ExportFormatMap, d as UploadResult, i as EmbedEventName, l as InitOptions, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig } from "./protocol-BgXSkIuc.mjs";
 
 //#region src/embed.d.ts
+interface AssetConfig {
+  /**
+   * Called when the embed needs to upload a file.
+   * Receives a real File object (reconstructed from serialized data).
+   * Throwing or rejecting will show an error toast in the embed.
+   */
+  onUploadRequest: (file: File, context: {
+    stateNodeId: string;
+  }) => Promise<UploadResult>;
+  /**
+   * Accepted MIME types. Supports wildcards (e.g. 'image/*').
+   * @default ['image/*']
+   */
+  accept?: string[];
+  /**
+   * Maximum file size in bytes.
+   * @default 10_485_760 (10MB)
+   */
+  maxFileSize?: number;
+}
 interface StatelyEmbedOptions {
   baseUrl: string;
   apiKey?: string;
   origin?: string;
+  /** Asset upload configuration. If omitted, files are stored as base64 data URLs. */
+  assets?: AssetConfig;
   onReady?: () => void;
   onLoaded?: (graph: unknown) => void;
   onChange?: (graph: unknown, machineConfig: unknown) => void;
@@ -40,4 +62,4 @@ interface StatelyEmbed {
 }
 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 };
+export { AssetConfig, type CommentsConfig, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, StatelyEmbed, StatelyEmbedOptions, type UploadResult, createStatelyEmbed };

package/dist/embed.mjs

@@ -1,4 +1,4 @@
-import { i as createPendingExportManager, o as toInitMessage, r as createEventRegistry, t as createPostMessageTransport } from "./transport-D352iKKa.mjs";
+import { i as createPendingExportManager, o as toInitMessage, r as createEventRegistry, t as createPostMessageTransport } from "./transport-C1fRAuv-.mjs";
 
 //#region src/embed.ts
 function createStatelyEmbed(options) {
@@ -32,6 +32,12 @@ function createStatelyEmbed(options) {
 			case "@statelyai.ready": {
 				const ready = data;
 				flush();
+				if (options.assets?.onUploadRequest) send({
+					type: "@statelyai.uploadCapabilities",
+					enabled: true,
+					accept: options.assets.accept,
+					maxFileSize: options.assets.maxFileSize
+				});
 				options.onReady?.();
 				events.emit("ready", { version: ready.version });
 				break;
@@ -76,6 +82,47 @@ function createStatelyEmbed(options) {
 				events.emit("error", err);
 				break;
 			}
+			case "@statelyai.uploadRequest": {
+				const req = data;
+				if (!options.assets?.onUploadRequest) {
+					send({
+						type: "@statelyai.error",
+						requestId: req.requestId,
+						code: "upload_not_configured",
+						message: "No upload handler configured"
+					});
+					break;
+				}
+				const maxSize = options.assets.maxFileSize ?? 10485760;
+				if (req.file.size > maxSize) {
+					send({
+						type: "@statelyai.error",
+						requestId: req.requestId,
+						code: "upload_file_too_large",
+						message: `File exceeds maximum size of ${maxSize} bytes`
+					});
+					break;
+				}
+				const binary = atob(req.file.data);
+				const bytes = new Uint8Array(binary.length);
+				for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+				const file = new File([bytes], req.file.name, { type: req.file.mimeType });
+				options.assets.onUploadRequest(file, { stateNodeId: req.stateNodeId }).then((result) => {
+					send({
+						type: "@statelyai.uploadResponse",
+						requestId: req.requestId,
+						result
+					});
+				}).catch((err) => {
+					send({
+						type: "@statelyai.error",
+						requestId: req.requestId,
+						code: "upload_failed",
+						message: err instanceof Error ? err.message : "Upload failed"
+					});
+				});
+				break;
+			}
 		}
 	}
 	function replaceTransport(nextTransport) {

package/dist/{graph-C-7ZK_nK.d.mts → graph-BfezxFKJ.d.mts}

@@ -388,6 +388,6 @@ type StudioAction = DigraphAction;
 type StudioEventTypeData = EventTypeData;
 declare function toStudioMachine(graph: StatelyGraph): StudioMachine;
 declare function fromStudioMachine(studioMachine: StudioMachine): StatelyGraph;
-declare const studioMachineConverter: _statelyai_graph0.GraphFormatConverter<DigraphConfig>;
+declare const studioMachineConverter: _statelyai_graph0.GraphFormatConverter<DigraphConfig, StatelyNodeData, StatelyEdgeData, StatelyGraphData>;
 //#endregion
 export { EventTypeData as C, DigraphNodeConfig as S, studioMachineConverter as _, StatelyGraphData as a, DigraphConfig as b, StatelyInvoke as c, StudioAction as d, StudioEdge as f, fromStudioMachine as g, StudioNode as h, StatelyGraph as i, StatelyNodeData as l, StudioMachine as m, StatelyActorImplementation as n, StatelyGuard as o, StudioEventTypeData as p, StatelyEdgeData as r, StatelyImplementation as s, StatelyAction as t, StatelyTagImplementation as u, toStudioMachine as v, StateNodeJSONData as w, DigraphEdgeConfig as x, DigraphAction as y };

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-C-7ZK_nK.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-BfezxFKJ.mjs";
 export { StatelyAction, StatelyActorImplementation, StatelyEdgeData, StatelyGraph, StatelyGraphData, StatelyGuard, StatelyImplementation, StatelyInvoke, StatelyNodeData, StatelyTagImplementation, StudioAction, StudioEdge, StudioEventTypeData, StudioMachine, StudioNode, fromStudioMachine, studioMachineConverter, toStudioMachine };