@statelyai/sdk 0.1.1 → 0.3.0

package/dist/inspect.d.mts

@@ -0,0 +1,45 @@
+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/inspect.d.ts
+interface CreateInspectorOptions {
+  /** WebSocket URL of the devtools server. Default: 'ws://localhost:4242' */
+  url?: string;
+  /** Auto-open browser to visualizer. Default: true */
+  autoOpen?: boolean;
+  /** Unique session ID. Auto-generated if not provided. */
+  sessionId?: string;
+  /** Display name for this connection in the visualizer. */
+  name?: string;
+}
+interface Inspector {
+  /** Send a machine for inspection (starts visualization). */
+  inspect(options: InspectOptions): void;
+  /** Update the machine currently being inspected. */
+  update(machine: unknown, format?: string): void;
+  /** Change the visualization mode. */
+  setMode(mode: EmbedMode): 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 events from the visualizer. */
+  on<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Unsubscribe from an event. */
+  off<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Send a state snapshot for real-time inspection. */
+  sendSnapshot(snapshot: unknown, event?: unknown): void;
+  /** Clean up the connection. */
+  destroy(): void;
+  /** Session ID for this connection. */
+  readonly sessionId: string;
+}
+interface InspectOptions {
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  panels?: InitOptions['panels'];
+}
+declare function createStatelyInspector(options?: CreateInspectorOptions): Inspector;
+//#endregion
+export { CreateInspectorOptions, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, InspectOptions, Inspector, createStatelyInspector };

package/dist/inspect.mjs

@@ -0,0 +1,122 @@
+import { a as createRequestId, i as createPendingExportManager, n as createWebSocketTransport, o as toInitMessage, r as createEventRegistry } from "./transport-D352iKKa.mjs";
+
+//#region src/inspect.ts
+function generateId() {
+	return createRequestId();
+}
+function createStatelyInspector(options) {
+	const { url = "ws://localhost:4242", autoOpen = true, sessionId = generateId(), name } = options ?? {};
+	let destroyed = false;
+	const pendingMessages = [];
+	const events = createEventRegistry();
+	const transport = createWebSocketTransport({
+		url,
+		role: "client",
+		sessionId,
+		...name && { metadata: { name } }
+	});
+	const exportManager = createPendingExportManager((message) => send(message));
+	function send(msg) {
+		if (!transport.ready) {
+			pendingMessages.push(msg);
+			return;
+		}
+		transport.send(msg);
+	}
+	function flush() {
+		while (pendingMessages.length > 0) {
+			const msg = pendingMessages.shift();
+			transport.send(msg);
+		}
+	}
+	transport.onReady(() => {
+		flush();
+	});
+	if (autoOpen) transport.onReady(() => {
+		transport.send({
+			type: "@statelyai.requestOpen",
+			sessionId
+		});
+	});
+	transport.onMessage((msg) => {
+		if (destroyed) return;
+		switch (msg.type) {
+			case "@statelyai.ready":
+				events.emit("ready", { version: msg.version });
+				break;
+			case "@statelyai.loaded":
+				events.emit("loaded", { graph: msg.graph });
+				break;
+			case "@statelyai.change":
+				events.emit("change", {
+					graph: msg.graph,
+					machineConfig: msg.machineConfig
+				});
+				break;
+			case "@statelyai.save":
+				events.emit("save", {
+					graph: msg.graph,
+					machineConfig: msg.machineConfig
+				});
+				break;
+			case "@statelyai.retrieved":
+				exportManager.resolve(msg.requestId, msg.data);
+				break;
+			case "@statelyai.error":
+				exportManager.reject(new Error(msg.message), msg.requestId);
+				events.emit("error", {
+					code: msg.code,
+					message: msg.message
+				});
+				break;
+		}
+	});
+	return {
+		get sessionId() {
+			return sessionId;
+		},
+		inspect(opts) {
+			send(toInitMessage(opts));
+		},
+		update(machine, format) {
+			send({
+				type: "@statelyai.update",
+				machine,
+				format
+			});
+		},
+		setMode(mode) {
+			send({
+				type: "@statelyai.setMode",
+				mode
+			});
+		},
+		export(format, callOptions) {
+			return exportManager.start(format, callOptions, "Inspector is destroyed", () => destroyed);
+		},
+		on(event, handler) {
+			events.on(event, handler);
+		},
+		off(event, handler) {
+			events.off(event, handler);
+		},
+		sendSnapshot(snapshot, event) {
+			send({
+				type: "@statelyai.inspectSnapshot",
+				snapshot,
+				event: event ?? null
+			});
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			transport.destroy();
+			exportManager.clear("Inspector destroyed");
+			events.clear();
+			pendingMessages.length = 0;
+		}
+	};
+}
+
+//#endregion
+export { createStatelyInspector };

package/dist/protocol-BC-_s3if.d.mts

@@ -0,0 +1,172 @@
+//#region src/protocol.d.ts
+type EmbedMode = 'editing' | 'viewing' | 'simulating' | 'inspecting';
+interface ExportFormatMap {
+  xstate: {
+    options: {
+      version?: 4 | 5;
+      addTSTypes?: boolean;
+      showIds?: boolean;
+      showDescriptions?: boolean;
+    };
+    result: string;
+  };
+  json: {
+    options: {
+      simplifyArrays?: boolean;
+      version?: 4 | 5;
+    };
+    result: Record<string, unknown>;
+  };
+  digraph: {
+    options: object;
+    result: Record<string, unknown>;
+  };
+  mermaid: {
+    options: object;
+    result: string;
+  };
+  scxml: {
+    options: object;
+    result: string;
+  };
+}
+type ExportFormat = keyof ExportFormatMap;
+type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
+  timeout?: number;
+};
+interface EmbedEventMap {
+  ready: {
+    version: string;
+  };
+  loaded: {
+    graph: unknown;
+  };
+  change: {
+    graph: unknown;
+    machineConfig: unknown;
+  };
+  save: {
+    graph: unknown;
+    machineConfig: unknown;
+  };
+  error: {
+    code: string;
+    message: string;
+  };
+  snapshot: {
+    snapshot: unknown;
+    event: unknown | null;
+  };
+}
+type EmbedEventName = keyof EmbedEventMap;
+type EmbedEventHandler<K extends EmbedEventName> = (data: EmbedEventMap[K]) => void;
+interface InitOptions {
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  panels?: {
+    leftPanels?: string[];
+    rightPanels?: string[];
+    activePanels?: string[];
+  };
+}
+interface InitMessage {
+  type: '@statelyai.init';
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  leftPanels?: string[];
+  rightPanels?: string[];
+  activePanels?: string[];
+}
+interface UpdateMessage {
+  type: '@statelyai.update';
+  machine: unknown;
+  format?: string;
+}
+interface SetModeMessage {
+  type: '@statelyai.setMode';
+  mode: EmbedMode;
+}
+interface SetThemeMessage {
+  type: '@statelyai.setTheme';
+  theme: 'light' | 'dark';
+}
+interface RetrieveMessage {
+  type: '@statelyai.retrieve';
+  requestId: string;
+  format: ExportFormat;
+  options?: Record<string, unknown>;
+}
+interface ToastMessage {
+  type: '@statelyai.toast';
+  message: string;
+  toastType?: 'success' | 'error' | 'info' | 'warning';
+}
+interface InspectSnapshotMessage {
+  type: '@statelyai.inspectSnapshot';
+  snapshot: unknown;
+  event: unknown | null;
+}
+/** All messages a client (embed/inspector) can send to the viz. */
+type ClientMessage = InitMessage | UpdateMessage | SetModeMessage | SetThemeMessage | RetrieveMessage | ToastMessage | InspectSnapshotMessage;
+interface ReadyMessage {
+  type: '@statelyai.ready';
+  version: string;
+}
+interface LoadedMessage {
+  type: '@statelyai.loaded';
+  graph: unknown;
+}
+interface ChangeMessage {
+  type: '@statelyai.change';
+  graph: unknown;
+  machineConfig: unknown;
+}
+interface SaveMessage {
+  type: '@statelyai.save';
+  graph: unknown;
+  machineConfig: unknown;
+}
+interface RetrievedMessage {
+  type: '@statelyai.retrieved';
+  requestId: string;
+  data: unknown;
+}
+interface ErrorMessage {
+  type: '@statelyai.error';
+  code: string;
+  message: string;
+  requestId?: string;
+}
+/** All messages the viz can send back to a client. */
+type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | RetrievedMessage | ErrorMessage;
+interface RegisterMessage {
+  type: '@statelyai.register';
+  role: 'client' | 'viz';
+  sessionId: string;
+  metadata?: {
+    name?: string;
+    machineId?: string;
+  };
+}
+interface RegisteredMessage {
+  type: '@statelyai.registered';
+  sessionId: string;
+}
+interface RequestOpenMessage {
+  type: '@statelyai.requestOpen';
+  sessionId: string;
+}
+/** All session-management messages for the WS relay. */
+type SessionMessage = RegisterMessage | RegisteredMessage | RequestOpenMessage;
+/** Any valid protocol message. */
+type ProtocolMessage = ClientMessage | VizMessage | SessionMessage;
+//#endregion
+export { ExportCallOptions as a, InitOptions as c, EmbedMode as i, ProtocolMessage as l, EmbedEventMap as n, ExportFormat as o, EmbedEventName as r, ExportFormatMap as s, EmbedEventHandler as t };

package/dist/studio.d.mts

@@ -0,0 +1,54 @@
+//#region src/studio.d.ts
+interface StudioClientOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+}
+interface VerifyApiKeyResponse {
+  valid: boolean;
+}
+interface ProjectMachine {
+  machineId: string;
+  name: string;
+}
+interface ProjectData {
+  projectId: string;
+  machines: ProjectMachine[];
+}
+interface ExtractedMachine {
+  id?: string;
+  config: Record<string, unknown>;
+  setupConfig?: Record<string, unknown>;
+  implementations?: Record<string, unknown>;
+  _type: 'setup.createMachine' | 'createMachine';
+}
+interface ExtractMachinesResponse {
+  machines: ExtractedMachine[];
+  error?: string;
+}
+interface GetMachineOptions {
+  version?: string;
+}
+declare class StudioApiError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number);
+}
+interface StudioClient {
+  auth: {
+    verify(apiKey?: string): Promise<VerifyApiKeyResponse>;
+  };
+  projects: {
+    get(projectId: string): Promise<ProjectData>;
+  };
+  machines: {
+    get<TMachine = Record<string, unknown>>(machineId: string, options?: GetMachineOptions): Promise<TMachine>;
+  };
+  code: {
+    extractMachines(code: string, options?: {
+      apiKey?: string | null;
+    }): Promise<ExtractMachinesResponse>;
+  };
+}
+declare function createStatelyClient(options?: StudioClientOptions): StudioClient;
+//#endregion
+export { ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, StudioApiError, StudioClient, StudioClientOptions, VerifyApiKeyResponse, createStatelyClient };

package/dist/studio.mjs

@@ -0,0 +1,62 @@
+//#region src/studio.ts
+var StudioApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "StudioApiError";
+		this.status = status;
+	}
+};
+function getFetch(fetchImpl) {
+	const resolvedFetch = fetchImpl ?? globalThis.fetch;
+	if (!resolvedFetch) throw new Error("No fetch implementation available. Pass one via createStatelyClient({ fetch }).");
+	return resolvedFetch;
+}
+function joinApiUrl(baseUrl, path) {
+	return `${baseUrl.replace(/\/+$/, "")}/registry/api/v1${path}`;
+}
+async function parseJson(response) {
+	if (!response.headers.get("content-type")?.includes("application/json")) return null;
+	return response.json().catch(() => null);
+}
+function createStatelyClient(options = {}) {
+	const baseUrl = options.baseUrl ?? "https://stately.ai";
+	const fetchImpl = getFetch(options.fetch);
+	async function request(path, init = {}, apiKeyOverride) {
+		const headers = new Headers(init.headers);
+		const apiKey = apiKeyOverride ?? options.apiKey;
+		if (apiKey) headers.set("Authorization", `Bearer ${apiKey}`);
+		const response = await fetchImpl(joinApiUrl(baseUrl, path), {
+			...init,
+			headers
+		});
+		const data = await parseJson(response);
+		if (!response.ok) throw new StudioApiError(typeof data === "object" && data !== null && "error" in data && typeof data.error === "string" ? data.error : `HTTP ${response.status}`, response.status);
+		return data;
+	}
+	return {
+		auth: { verify(apiKey) {
+			return request("/verify", { method: "GET" }, apiKey);
+		} },
+		projects: { get(projectId) {
+			return request(`/projects/${encodeURIComponent(projectId)}`, { method: "GET" });
+		} },
+		machines: { get(machineId, getOptions = {}) {
+			const search = new URLSearchParams();
+			if (getOptions.version) search.set("version", getOptions.version);
+			const suffix = search.size > 0 ? `?${search.toString()}` : "";
+			return request(`/machines/${encodeURIComponent(machineId)}${suffix}`, { method: "GET" });
+		} },
+		code: { extractMachines(code, extractOptions = {}) {
+			const apiKey = extractOptions.apiKey ?? options.apiKey ?? "anonymous";
+			return request("/code", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ code })
+			}, apiKey);
+		} }
+	};
+}
+
+//#endregion
+export { StudioApiError, createStatelyClient };