@statelyai/sdk 0.16.0 → 0.16.2

package/README.md

@@ -106,20 +106,20 @@ const extracted = await studio.code.extractMachines({
 
 The client namespaces map one-to-one onto the server-owned `/api/v1` contract:
 
-| Method                                             | Operation                                             |
-| -------------------------------------------------- | ------------------------------------------------------ |
-| `auth.verify()`                                    | `GET /api/v1/auth/verify`                             |
-| `projects.list()`                                  | `GET /api/v1/projects`                                |
-| `projects.create(input)`                           | `POST /api/v1/projects`                               |
-| `projects.get(projectId)`                          | `GET /api/v1/projects/:projectId`                     |
-| `projects.update(projectId, input)`                | `PATCH /api/v1/projects/:projectId`                   |
-| `projects.delete(projectId)`                       | `DELETE /api/v1/projects/:projectId`                  |
-| `projects.listMachines(projectId)`                 | `GET /api/v1/projects/:projectId/machines`            |
-| `machines.create(input)`                           | `POST /api/v1/machines`                               |
-| `machines.get(machineId)`                          | `GET /api/v1/machines/:machineId`                     |
-| `machines.getVersion(machineId, versionId)`        | `GET /api/v1/machines/:machineId/versions/:versionId` |
-| `machines.update(machineId, input)`                | `PATCH /api/v1/machines/:machineId`                   |
-| `code.extractMachines(input)`                      | `POST /api/v1/code/extract-machines`                  |
+| Method                                      | Operation                                             |
+| ------------------------------------------- | ----------------------------------------------------- |
+| `auth.verify()`                             | `GET /api/v1/auth/verify`                             |
+| `projects.list()`                           | `GET /api/v1/projects`                                |
+| `projects.create(input)`                    | `POST /api/v1/projects`                               |
+| `projects.get(projectId)`                   | `GET /api/v1/projects/:projectId`                     |
+| `projects.update(projectId, input)`         | `PATCH /api/v1/projects/:projectId`                   |
+| `projects.delete(projectId)`                | `DELETE /api/v1/projects/:projectId`                  |
+| `projects.listMachines(projectId)`          | `GET /api/v1/projects/:projectId/machines`            |
+| `machines.create(input)`                    | `POST /api/v1/machines`                               |
+| `machines.get(machineId)`                   | `GET /api/v1/machines/:machineId`                     |
+| `machines.getVersion(machineId, versionId)` | `GET /api/v1/machines/:machineId/versions/:versionId` |
+| `machines.update(machineId, input)`         | `PATCH /api/v1/machines/:machineId`                   |
+| `code.extractMachines(input)`               | `POST /api/v1/code/extract-machines`                  |
 
 `projects.ensure(input)` is a client workflow composed of `projects.list`,
 `projects.get`, and `projects.create`, not a route.
@@ -186,12 +186,24 @@ hours without activity. Only actor checkpoints and observations are replayed;
 export traffic is live-only, and auth/upload/embed-control messages are rejected.
 AI-backed features remain separately authenticated.
 
+After successful registration, hosted Sky records coarse connection analytics:
+role, normalized browser origin or `unknown`, localhost status, runtime,
+SDK/protocol versions, Cloudflare country, ASN organization, and colo, plus an
+opaque room identifier. The analytics event excludes raw room capabilities, IP
+addresses, actor/session ids, machine names, inspection messages, and payloads.
+Cloudflare operational logs may separately contain the request URL, IP address,
+and request metadata. A source origin can identify a site or customer, so this
+is operational telemetry rather than anonymous data. Pass a self-hosted `url`
+to opt out of Stately-hosted collection.
+
 Set `autoOpen: false`, await `inspector.ready`, and navigate to
 `inspector.inspectorUrl` when a test runner or another process owns the browser.
 `inspectorBaseUrl` targets an inspector UI hosted separately from the WebSocket
 relay. An explicit `url` wins over `STATELY_INSPECT_URL`, which wins over the
 hosted default. See `@statelyai/sdk/protocol` for the versioned message and
-`?r=` query contract.
+`?r=` query contract. SDK producer registration also reports its SDK version
+and coarse browser, Node, or unknown runtime; it never adds inspection payloads
+to registration metadata.
 
 ### CLI and sync
 
@@ -258,12 +270,12 @@ reference deployment.
 
 Key environment variables for self-hosted deployments:
 
-| Variable                    | Purpose                                           |
-| --------------------------- | ------------------------------------------------- |
-| `AUTH_PROVIDER`             | Auth strategy used by the editor host             |
+| Variable                    | Purpose                                                                                            |
+| --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `AUTH_PROVIDER`             | Auth strategy used by the editor host                                                              |
 | `RESOURCE_PROVIDER`         | Set to `stately` to enable project and machine resource operations; `none` (default) disables them |
-| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to skip editor-sync API-key checks |
-| `NEXT_PUBLIC_BASE_URL`      | Public-facing editor URL                          |
+| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to skip editor-sync API-key checks                                                  |
+| `NEXT_PUBLIC_BASE_URL`      | Public-facing editor URL                                                                           |
 
 For enterprise self-hosting options, [see pricing and contact
 us](https://stately.ai/pricing).

package/dist/index.d.mts

@@ -5,7 +5,7 @@ import { CapabilityDeniedCapability, CapabilityDeniedEvent, CommentsConfig, Edit
 import { AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
 import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizationHeader, t as StatelyAuthMode } from "./auth-2Thaw42j.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
-import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, h as createWebSocketTransport, i as InspectedSnapshot, l as ManualActorOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as Inspector, p as TransportFailure, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-CduY_2Fa.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, h as createWebSocketTransport, i as InspectedSnapshot, l as ManualActorOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as Inspector, p as TransportFailure, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BScvqVcM.mjs";
 import { A as Machine, C as StudioMachineRecord, D as VerifyApiKeyResponse, E as UpdateProjectInput, F as ProjectVisibility, I as VerifyResult, L as XStateVersion, M as Project, N as ProjectMachineSummary, O as createStatelyClient, P as ProjectSummary, R as ResourceErrorCode, S as StudioClientOptions, T as UpdateMachineInput, _ as ProjectMachine, a as CreateMachineTemplate, b as StudioApiErrorOptions, c as EnsureProjectInput, d as ExtractedMachine, f as GetMachineOptions, g as ProjectData, h as LegacyUpdateMachineInput, i as CreateMachineInput, j as MachineVersion, k as ExtractedMachines, l as ExtractMachinesInput, m as LegacyProjectVisibility, n as CreateMachineFromDefinitionInput, o as CreateProjectInput, r as CreateMachineFromTemplateInput, s as DEFAULT_STATELY_BASE_URL, t as ConnectedRepo, u as ExtractMachinesResponse, v as RepoType, w as StudioRequestOptions, x as StudioClient, y as StudioApiError } from "./studio-Bk_u41gu.mjs";
 import { OAuthAuthorizationServerMetadata, OAuthClientRegistrationResponse, OAuthProtectedResourceMetadata, OAuthTokenResponse, PkcePair, buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";

package/dist/index.mjs

@@ -2,9 +2,9 @@ import { n as createWebSocketTransport, t as createPostMessageTransport } from "
 import { INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-BwVdM4R8.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-DxOsKzlq.mjs";
 import { n as StudioApiError, r as createStatelyClient, t as DEFAULT_STATELY_BASE_URL } from "./studio-txdyJHD7.mjs";
-import { a as RawCode, c as eventsSchemaToTSType, d as jsonSchemaToTSType, f as raw, l as graphToMachineConfig, n as getStatelyPragma, o as contextSchemaToTSType, p as serializeJS, r as upsertStatelyPragma, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Th0gdXfx.mjs";
+import { a as RawCode, c as eventsSchemaToTSType, d as jsonSchemaToTSType, f as raw, l as graphToMachineConfig, n as getStatelyPragma, o as contextSchemaToTSType, p as serializeJS, r as upsertStatelyPragma, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Bm9O4XV6.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
 import { buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";

package/dist/{inspect-CduY_2Fa.d.mts → inspect-BScvqVcM.d.mts}

@@ -1,4 +1,4 @@
-import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
+import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionClientMetadata, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
 
 //#region src/transport.d.ts
 interface TransportFailure {
@@ -24,10 +24,7 @@ interface WebSocketTransportOptions {
   url: string;
   role: 'producer' | 'viewer';
   producerId?: string;
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
+  metadata?: InspectionClientMetadata;
   /** Reconnect on disconnect. Default true. */
   reconnect?: boolean;
   /** Max reconnect attempts after the first connection. Default 10. */

package/dist/{inspect-BwVdM4R8.mjs → inspect-DxOsKzlq.mjs}

@@ -26,6 +26,15 @@ async function openBrowser(url) {
 	});
 }
 
+//#endregion
+//#region src/version.ts
+const SDK_VERSION = "0.16.2";
+function inspectionRuntime() {
+	if (typeof window !== "undefined") return "browser";
+	if (typeof process !== "undefined" && process.versions?.node) return "node";
+	return "unknown";
+}
+
 //#endregion
 //#region src/inspect.ts
 const defaultSerializeSnapshot = (snapshot) => ({
@@ -76,7 +85,11 @@ function createInspector(options = {}) {
 		url: relayUrl,
 		role: "producer",
 		producerId,
-		metadata: { name: displayName }
+		metadata: {
+			name: displayName,
+			sdkVersion: SDK_VERSION,
+			runtime: inspectionRuntime()
+		}
 	});
 	const ownsTransport = !injectedTransport;
 	const exportManager = createPendingExportManager((message) => send(message));

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
 import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition } from "./protocol.mjs";
-import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-CduY_2Fa.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BScvqVcM.mjs";
 export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedEvent, InspectedSnapshot, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, InspectorInspectionEvent, ManualActorOptions, Transport, createInspector, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,3 +1,3 @@
-import { n as createStatelyInspector, t as createInspector } from "./inspect-BwVdM4R8.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-DxOsKzlq.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/oauth.mjs

@@ -13,6 +13,24 @@ async function getOAuthResponseError(response) {
 	const detail = (await response.text().catch(() => "")).trim();
 	return detail ? `: ${detail}` : "";
 }
+var OAuthTokenRequestError = class extends Error {
+	constructor(message, status, oauthError) {
+		super(message);
+		this.status = status;
+		this.oauthError = oauthError;
+		this.name = "OAuthTokenRequestError";
+	}
+};
+async function createOAuthTokenRequestError(response, message) {
+	const body = await response.text().catch(() => "");
+	let oauthError;
+	try {
+		const parsed = JSON.parse(body);
+		if (typeof parsed.error === "string") oauthError = parsed.error;
+	} catch {}
+	const detail = body.trim() ? `: ${body.trim()}` : "";
+	return new OAuthTokenRequestError(`${message} with HTTP ${response.status}${detail}`, response.status, oauthError);
+}
 async function discoverProtectedResource(resourceUrl, options = {}) {
 	const resource = new URL(String(resourceUrl));
 	const pathParts = resource.pathname.split("/").filter(Boolean);
@@ -110,7 +128,7 @@ async function refreshToken(options) {
 		headers: { "Content-Type": "application/x-www-form-urlencoded" },
 		body
 	});
-	if (!response.ok) throw new Error(`Token refresh failed with HTTP ${response.status}${await getOAuthResponseError(response)}`);
+	if (!response.ok) throw await createOAuthTokenRequestError(response, "Token refresh failed");
 	return response.json();
 }
 

package/dist/protocol.d.mts

@@ -521,15 +521,18 @@ interface UploadResponseMessage {
 type ClientMessage = InitMessage | SetApiKeyMessage | ProjectInitMessage | ProjectUpdateMessage | ProjectSelectMachineMessage | UpdateMessage | SetModeMessage | SetThemeMessage | SetSettingsMessage | RetrieveMessage | ToastMessage | InspectSnapshotMessage | SystemInitMessage | SystemSelectActorMessage | SystemActorRegisteredMessage | SystemActorEventMessage | SystemActorSnapshotMessage | SystemActorStoppedMessage | UploadCapabilitiesMessage | UploadResponseMessage | ErrorMessage;
 /** All messages the viz can send back to a client. */
 type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | ProjectMachineSelectedMessage | RetrievedMessage | ErrorMessage | CapabilityDeniedMessage | UploadRequestMessage;
+interface InspectionClientMetadata {
+  name?: string;
+  machineId?: string;
+  sdkVersion?: string;
+  runtime?: 'browser' | 'node' | 'unknown';
+}
 interface RegisterMessage {
   type: '@statelyai.register';
   protocolVersion: number;
   role: 'producer' | 'viewer';
   producerId?: string;
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
+  metadata?: InspectionClientMetadata;
 }
 interface RegisteredMessage {
   type: '@statelyai.registered';
@@ -546,4 +549,4 @@ declare const PREFIX = "@statelyai.";
 /** Current WebSocket inspection protocol version. */
 declare const INSPECTION_PROTOCOL_VERSION = 2;
 //#endregion
-export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage, createInspectionRoomUrls, getInspectionRoomId };
+export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionClientMetadata, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage, createInspectionRoomUrls, getInspectionRoomId };

package/dist/{statelyPragma-Th0gdXfx.mjs → statelyPragma-Bm9O4XV6.mjs}

@@ -1,5 +1,6 @@
 import { a as array, c as literal, d as record, f as string, i as _enum, l as number, m as unknown, o as boolean, p as union, s as discriminatedUnion, u as object } from "./studio-txdyJHD7.mjs";
 import ts from "typescript";
+import "xstate";
 import "xstate/graph";
 
 //#region ../../node_modules/.pnpm/js-yaml@4.2.0/node_modules/js-yaml/dist/js-yaml.mjs

package/dist/sync.mjs

@@ -1,5 +1,5 @@
 import { r as createStatelyClient } from "./studio-txdyJHD7.mjs";
-import { i as INLINE_EXPRESSION_DIRECTIVE_FIELDS, m as xstateSourceToConfig, n as getStatelyPragma, p as serializeJS, r as upsertStatelyPragma, s as detectXStateSourceProfile, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Th0gdXfx.mjs";
+import { i as INLINE_EXPRESSION_DIRECTIVE_FIELDS, m as xstateSourceToConfig, n as getStatelyPragma, p as serializeJS, r as upsertStatelyPragma, s as detectXStateSourceProfile, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Bm9O4XV6.mjs";
 import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
 import * as ts$1 from "typescript";
 import ts from "typescript";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "license": "MIT",
   "bin": {
     "stately-sdk": "./dist/bin.mjs"
@@ -89,8 +89,8 @@
     "jsdom": "^27.4.0",
     "tsdown": "0.21.0-beta.2",
     "vitest": "^3.2.4",
-    "@statelyai/api-contract": "0.0.1",
-    "@statelyai/graph-tools": "0.0.7"
+    "@statelyai/api-contract": "0.0.2",
+    "@statelyai/graph-tools": "0.0.8"
   },
   "engines": {
     "node": ">=22.4"