@statelyai/sdk 0.6.0 → 0.7.0

package/README.md

@@ -137,6 +137,8 @@ import {
   createStatelyClient,
   createStatelyEmbed,
   createStatelyInspector,
+  createS3AssetUploadAdapter,
+  createSupabaseAssetUploadAdapter,
   fromStudioMachine,
   graphToMachineConfig,
   graphToXStateTS,
@@ -156,6 +158,10 @@ import {
 } from '@statelyai/sdk/api';
 import { fromStudioMachine, toStudioMachine } from '@statelyai/sdk/graph';
 import { planSync, pullSync, pushSync } from '@statelyai/sdk/sync';
+import {
+  createS3AssetUploadAdapter,
+  createSupabaseAssetUploadAdapter,
+} from '@statelyai/sdk/assetStorage';
 import type { GraphPatch } from '@statelyai/sdk/patchTypes';
 ```
 
@@ -200,12 +206,15 @@ Available client methods:
 | `studio.projects.get(projectId)`                                        | Fetch a project and its machines                                         |
 | `studio.machines.create({ projectVersionId, ... })`                     | Create a machine through the published REST API                          |
 | `studio.machines.createMany({ projectVersionId, ... })`                 | Compatibility wrapper around `create()` that returns a one-item array    |
+| `studio.machines.update({ id, ... })`                                   | Update a machine through the published REST API                          |
 | `studio.machines.get(machineId, { version? })`                          | Fetch a machine, optionally pinned to a version                          |
 | `studio.code.extractMachines(code, { apiKey? })`                        | Extract machine configs from source text                                 |
 
 ## Sync Helpers
 
-`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, creates the remote machine, and writes `// @statelyai id=...` back into XState source files.
+`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, updates the linked remote machine when `// @statelyai id=...` is present, otherwise creates one, and writes the pragma back into XState source files when needed.
+
+For project-scoped discovery flows, `statelyai.json` defines which local files should be scanned. The CLI `statelyai push` command uses that config to find local XState sources, creates remote Studio machines for unlabeled ones, updates already-linked ones, and writes returned `// @statelyai id=...` pragmas back into source.
 
 ```ts
 import { pushSync } from '@statelyai/sdk/sync';
@@ -226,7 +235,7 @@ const result = await pushSync({
 });
 ```
 
-Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`.
+Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`. The strict XState JSON export schema is published at `@statelyai/sdk/xstate-json.schema.json`.
 
 ```json
 {
@@ -235,17 +244,7 @@ Projects can also check in a `statelyai.json` file to describe which local sourc
   "projectId": "project_123",
   "studioUrl": "https://stately.ai",
   "defaultXStateVersion": 5,
-  "sources": [
-    {
-      "include": ["src/**/*.ts", "src/**/*.tsx"],
-      "exclude": ["**/*.test.ts", "**/dist/**"],
-      "format": "xstate"
-    },
-    {
-      "include": ["docs/**/*.mmd"],
-      "format": "mermaid"
-    }
-  ]
+  "sources": []
 }
 ```
 
@@ -417,7 +416,7 @@ const aslYaml = await embed.export('asl-yaml');
 
 <!-- supported export formats from ExportFormatMap in src/protocol.ts -->
 
-Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
+Supported formats: `xstate`, `xstate-json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
@@ -462,9 +461,54 @@ const embed = createStatelyEmbed({
 });
 ```
 
+For reusable integrations, pass an upload adapter instead of wiring the callback inline:
+
+```ts
+import { createStatelyEmbed, createS3AssetUploadAdapter } from '@statelyai/sdk';
+
+const adapter = createS3AssetUploadAdapter({
+  bucket: 'assets',
+  publicBaseUrl: 'https://cdn.example.com/assets',
+  async getUploadTarget({ key, contentType }) {
+    const response = await fetch('/api/assets/presign', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key, contentType }),
+    });
+    return response.json();
+  },
+});
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: { adapter },
+});
+```
+
+Supabase storage can use the same adapter contract:
+
+```ts
+import {
+  createStatelyEmbed,
+  createSupabaseAssetUploadAdapter,
+} from '@statelyai/sdk';
+
+const adapter = createSupabaseAssetUploadAdapter({
+  client: supabaseClient,
+  bucket: 'assets',
+  projectVersionId,
+});
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: { adapter },
+});
+```
+
 | Option            | Type                                                                      | Description                                                 |
 | ----------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | **Required.** Called when the editor needs to upload a file |
+| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | Called when the editor needs to upload a file               |
+| `adapter`         | `AssetUploadAdapter`                                                      | Provider-specific uploader, such as the S3 or Supabase adapter |
 | `accept`          | `string[]`                                                                | Accepted MIME types. Supports wildcards like `image/*`      |
 | `maxFileSize`     | `number`                                                                  | Max file size in bytes. Defaults to `10_485_760`            |
 
@@ -554,11 +598,15 @@ Installing the package also exposes a `statelyai` binary:
 npx statelyai open ./checkout.machine.ts
 
 statelyai init
+statelyai init --scan
 statelyai login
 statelyai auth status
 statelyai plan ./checkout.machine.ts machine-id
 statelyai diff ./checkout.machine.ts machine-id --fail-on-changes
+statelyai push
+statelyai push ./checkout.machine.ts
 statelyai pull machine-id ./checkout.machine.ts
+statelyai pull ./checkout.machine.ts
 statelyai open ./checkout.machine.ts
 ```
 
@@ -568,13 +616,15 @@ Available commands:
 
 | Command                            | Description                                                                 |
 | ---------------------------------- | --------------------------------------------------------------------------- |
-| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` |
+| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` with an empty `sources` array |
 | `statelyai login`                  | Store an API key for future CLI use                                         |
 | `statelyai logout`                 | Remove a stored API key                                                     |
 | `statelyai auth status`            | Show whether the CLI would use an environment variable or stored credential |
 | `statelyai plan <source> <target>` | Print a semantic sync summary                                               |
 | `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes                            |
+| `statelyai push [file]`            | Discover local machine sources, create remote Studio machines for unlabeled files, update linked ones, and persist returned ids |
 | `statelyai pull <source> <target>` | Materialize a source into a local target file                               |
+| `statelyai pull <linked-file>`     | Refresh a linked local file from the `@statelyai id=...` pragma             |
 | `statelyai open <file>`            | Open a local file in a browser-backed visual editor session                 |
 
 Common flags:
@@ -585,6 +635,8 @@ Common flags:
 
 The CLI resolves credentials in this order: `--api-key`, then `STATELY_API_KEY`/`NEXT_PUBLIC_STATELY_API_KEY`, then the key stored by `statelyai login`. `login` stores the key in the OS credential store when available, with a private file fallback.
 
+`statelyai init --scan` walks local code files, detects machine-bearing files from their contents, and suggests `sources` globs to save into `statelyai.json`. Without `--scan`, `init` leaves `sources` empty so you can opt in explicitly before running `statelyai push`.
+
 `statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. When the source file contains `// @statelyai id=...` and an API key is available, the editor session also reuses the referenced remote machine layout while continuing to treat the local source as the semantic source of truth. Pass `--api-key`, set `STATELY_API_KEY`, or run `statelyai login` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
 
 ## Transport Helpers

package/dist/assetStorage.d.mts

@@ -0,0 +1,73 @@
+import { m as UploadResult } from "./protocol-DN4mH4jR.mjs";
+
+//#region src/assetStorage.d.ts
+interface AssetUploadContext {
+  stateNodeId: string;
+}
+interface AssetUploadRequest extends AssetUploadContext {
+  file: File;
+}
+interface AssetUploadAdapter {
+  upload(request: AssetUploadRequest): Promise<UploadResult>;
+  accept?: string[];
+  maxFileSize?: number;
+}
+type AssetObjectKeyFactory = (request: AssetUploadRequest) => string | Promise<string>;
+interface S3UploadTarget {
+  uploadUrl: string;
+  publicUrl?: string;
+  method?: 'PUT' | 'POST';
+  headers?: Record<string, string>;
+  fields?: Record<string, string>;
+}
+interface CreateS3AssetUploadAdapterOptions {
+  bucket?: string;
+  publicBaseUrl?: string;
+  accept?: string[];
+  maxFileSize?: number;
+  key?: AssetObjectKeyFactory;
+  getUploadTarget: (request: AssetUploadRequest & {
+    key: string;
+    contentType: string;
+    bucket?: string;
+  }) => Promise<S3UploadTarget>;
+}
+interface SupabaseStorageBucket {
+  upload(path: string, file: File, options?: {
+    cacheControl?: string;
+    contentType?: string;
+    upsert?: boolean;
+  }): Promise<{
+    data: {
+      path: string;
+    } | null;
+    error: Error | {
+      message: string;
+    } | null;
+  }>;
+  getPublicUrl?(path: string): {
+    data: {
+      publicUrl: string;
+    };
+  };
+}
+interface SupabaseStorageClient {
+  storage: {
+    from(bucket: string): SupabaseStorageBucket;
+  };
+}
+interface CreateSupabaseAssetUploadAdapterOptions {
+  client: SupabaseStorageClient;
+  bucket?: string;
+  publicBaseUrl?: string;
+  projectVersionId?: string;
+  accept?: string[];
+  maxFileSize?: number;
+  cacheControl?: string;
+  upsert?: boolean;
+  key?: AssetObjectKeyFactory;
+}
+declare function createS3AssetUploadAdapter(options: CreateS3AssetUploadAdapterOptions): AssetUploadAdapter;
+declare function createSupabaseAssetUploadAdapter(options: CreateSupabaseAssetUploadAdapterOptions): AssetUploadAdapter;
+//#endregion
+export { AssetObjectKeyFactory, AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter };

package/dist/assetStorage.mjs

@@ -0,0 +1,99 @@
+//#region src/assetStorage.ts
+function sanitizeFileName(name) {
+	return name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function defaultObjectKey({ file, stateNodeId }) {
+	const fileName = sanitizeFileName(file.name) || "asset";
+	return `${stateNodeId}/${crypto.randomUUID()}-${fileName}`;
+}
+function createProjectObjectKey(projectVersionId) {
+	return ({ file }) => {
+		const fileName = sanitizeFileName(file.name) || "asset";
+		return `${projectVersionId}/${crypto.randomUUID()}-${fileName}`;
+	};
+}
+function joinUrl(baseUrl, key) {
+	return `${baseUrl.replace(/\/+$/, "")}/${key.split("/").map(encodeURIComponent).join("/")}`;
+}
+async function uploadToTarget(target, file) {
+	if (target.method === "POST" || target.fields) {
+		const formData = new FormData();
+		Object.entries(target.fields ?? {}).forEach(([name, value]) => {
+			formData.append(name, value);
+		});
+		formData.append("file", file);
+		const response = await fetch(target.uploadUrl, {
+			method: "POST",
+			body: formData
+		});
+		if (!response.ok) throw new Error(`Asset upload failed with ${response.status}`);
+		return;
+	}
+	const response = await fetch(target.uploadUrl, {
+		method: target.method ?? "PUT",
+		headers: {
+			"Content-Type": file.type || "application/octet-stream",
+			...target.headers
+		},
+		body: file
+	});
+	if (!response.ok) throw new Error(`Asset upload failed with ${response.status}`);
+}
+function createS3AssetUploadAdapter(options) {
+	return {
+		accept: options.accept,
+		maxFileSize: options.maxFileSize,
+		async upload(request) {
+			const key = await (options.key ?? defaultObjectKey)(request);
+			const target = await options.getUploadTarget({
+				...request,
+				key,
+				contentType: request.file.type || "application/octet-stream",
+				bucket: options.bucket
+			});
+			await uploadToTarget(target, request.file);
+			const url = target.publicUrl ?? (options.publicBaseUrl ? joinUrl(options.publicBaseUrl, key) : void 0);
+			if (!url) throw new Error("S3 asset upload adapter requires a publicUrl or publicBaseUrl");
+			return {
+				url,
+				name: request.file.name,
+				metadata: {
+					bucket: options.bucket,
+					key
+				}
+			};
+		}
+	};
+}
+function createSupabaseAssetUploadAdapter(options) {
+	const bucket = options.bucket ?? "assets";
+	return {
+		accept: options.accept,
+		maxFileSize: options.maxFileSize,
+		async upload(request) {
+			const storage = options.client.storage.from(bucket);
+			const key = await (options.key ?? (options.projectVersionId ? createProjectObjectKey(options.projectVersionId) : defaultObjectKey))(request);
+			const { data, error } = await storage.upload(key, request.file, {
+				cacheControl: options.cacheControl,
+				contentType: request.file.type || "application/octet-stream",
+				upsert: options.upsert
+			});
+			if (error) throw new Error(error.message);
+			if (!data?.path) throw new Error("Supabase asset upload did not return a path");
+			const publicUrl = storage.getPublicUrl?.(data.path)?.data.publicUrl ?? (options.publicBaseUrl ? joinUrl(options.publicBaseUrl, data.path) : void 0);
+			if (!publicUrl) throw new Error("Supabase asset upload adapter requires getPublicUrl or publicBaseUrl");
+			return {
+				url: publicUrl,
+				name: request.file.name,
+				metadata: {
+					bucket,
+					path: data.path,
+					key: data.path
+				}
+			};
+		}
+	};
+}
+
+//#endregion
+export { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter };

package/dist/cli.d.mts

@@ -1,14 +1,14 @@
 import { ConnectedRepo, CreateProjectInput, ProjectData, StudioClient } from "./studio.mjs";
-import "./graph-CB-ALrdk.mjs";
+import "./graph-DpBGHZwl.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
+//#region src/projectConfig.d.ts
 interface StatelySourceConfig {
   include: string[];
   exclude?: string[];
-  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'json' | 'asl-json' | 'asl-yaml' | 'auto';
+  format: 'xstate' | 'redux' | 'zustand' | 'xgraph' | 'digraph' | 'mermaid' | 'scxml' | 'xstate-json' | 'asl-json' | 'asl-yaml' | 'auto';
   xstateVersion?: number;
 }
 interface StatelyProjectConfig {
@@ -19,6 +19,13 @@ interface StatelyProjectConfig {
   defaultXStateVersion: number;
   sources: StatelySourceConfig[];
 }
+declare function createStatelyProjectConfig(options: {
+  projectId: string;
+  studioUrl: string;
+  defaultXStateVersion?: number;
+}): StatelyProjectConfig;
+//#endregion
+//#region src/cli.d.ts
 interface InitProjectOptions {
   apiKey: string;
   baseUrl?: string;
@@ -34,11 +41,11 @@ interface InitProjectResult {
   configPath: string;
   project: ProjectData;
 }
-declare function createStatelyProjectConfig(options: {
-  projectId: string;
-  studioUrl: string;
+interface ScanProjectSourcesOptions {
+  cwd?: string;
+  client: StudioClient;
   defaultXStateVersion?: number;
-}): StatelyProjectConfig;
+}
 type ApiKeyResolution = {
   apiKey: string;
   detail: string;
@@ -55,6 +62,7 @@ declare function getEnvApiKey(): {
 declare function resolveApiKey(explicitApiKey?: string): Promise<ApiKeyResolution>;
 declare function inferInitProjectName(cwd: string, repo?: ConnectedRepo): string;
 declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
+declare function scanProjectSources(options: ScanProjectSourcesOptions): Promise<StatelySourceConfig[]>;
 declare function formatPlanSummary(plan: SyncPlan): string;
 declare abstract class BaseSyncCommand extends Command {
   static enableJsonFlag: boolean;
@@ -100,7 +108,22 @@ declare class PullCommand extends ParsedSyncCommand {
   static description: string;
   static args: {
     source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
-    target: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+    target: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  run(): Promise<void>;
+}
+declare class PushCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    file: _oclif_core_interfaces0.Arg<string | undefined, Record<string, unknown>>;
+  };
+  static flags: {
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    'api-key': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    config: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
   run(): Promise<void>;
 }
@@ -133,6 +156,7 @@ declare class InitCommand extends Command {
     name: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
     visibility: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
     force: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    scan: _oclif_core_interfaces0.BooleanFlag<boolean>;
   };
   run(): Promise<void>;
 }
@@ -169,6 +193,7 @@ declare const COMMANDS: {
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
   pull: typeof PullCommand;
+  push: typeof PushCommand;
   open: typeof OpenCommand;
   init: typeof InitCommand;
   login: typeof LoginCommand;
@@ -177,4 +202,4 @@ declare const COMMANDS: {
 };
 declare function run(argv?: string[], entryUrl?: string): Promise<void>;
 //#endregion
-export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, StatelyProjectConfig, StatelySourceConfig, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run };
+export { ApiKeyResolution, COMMANDS, InitProjectOptions, InitProjectResult, ScanProjectSourcesOptions, createStatelyProjectConfig, formatPlanSummary, getEnvApiKey, inferInitProjectName, initProject, resolveApiKey, run, scanProjectSources };