@statelyai/sdk 0.0.1 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -0
- package/dist/index.d.mts +1 -0
- package/dist/index.mjs +2 -1
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# @statelyai/sdk
|
|
2
|
+
|
|
3
|
+
Embed the [Stately editor](https://stately.ai) in your app. Zero dependencies, fully typed.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @statelyai/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## API key
|
|
12
|
+
|
|
13
|
+
An API key is required to use the embed SDK. To get one:
|
|
14
|
+
|
|
15
|
+
1. Go to your [Stately settings](https://stately.ai/settings)
|
|
16
|
+
2. Select the **API Key** tab
|
|
17
|
+
3. Click **Create API Key** (Project or Account scope)
|
|
18
|
+
4. Copy and store it securely
|
|
19
|
+
|
|
20
|
+
See the [Studio API docs](https://stately.ai/docs/studio-api) for more details.
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { createStatelyEmbed } from '@statelyai/sdk';
|
|
26
|
+
|
|
27
|
+
const embed = createStatelyEmbed({
|
|
28
|
+
baseUrl: 'https://stately.ai',
|
|
29
|
+
apiKey: 'your-api-key',
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
// Mount into a container
|
|
33
|
+
embed.mount(document.getElementById('editor')!);
|
|
34
|
+
|
|
35
|
+
// Initialize with a machine
|
|
36
|
+
embed.init({
|
|
37
|
+
machine: myMachineConfig,
|
|
38
|
+
mode: 'editing',
|
|
39
|
+
theme: 'dark',
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## API
|
|
44
|
+
|
|
45
|
+
### `createStatelyEmbed(options)`
|
|
46
|
+
|
|
47
|
+
Creates an embed instance.
|
|
48
|
+
|
|
49
|
+
| Option | Type | Description |
|
|
50
|
+
|--------|------|-------------|
|
|
51
|
+
| `baseUrl` | `string` | **Required.** Base URL of the Stately app |
|
|
52
|
+
| `apiKey` | `string` | **Required.** Your Stately API key |
|
|
53
|
+
| `origin` | `string` | Custom target origin for postMessage |
|
|
54
|
+
| `onReady` | `() => void` | Called when embed is ready |
|
|
55
|
+
| `onLoaded` | `(graph) => void` | Called when machine is loaded |
|
|
56
|
+
| `onChange` | `(graph, machineConfig) => void` | Called on every change |
|
|
57
|
+
| `onSave` | `(graph, machineConfig) => void` | Called on save |
|
|
58
|
+
| `onError` | `({ code, message }) => void` | Called on error |
|
|
59
|
+
|
|
60
|
+
### Embed methods
|
|
61
|
+
|
|
62
|
+
#### `mount(container)` / `attach(iframe)`
|
|
63
|
+
|
|
64
|
+
Mount creates an iframe inside a container element. Attach connects to an existing iframe.
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
// Create a new iframe
|
|
68
|
+
const iframe = embed.mount(document.getElementById('editor')!);
|
|
69
|
+
|
|
70
|
+
// Or attach to an existing one
|
|
71
|
+
embed.attach(document.querySelector('iframe')!);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
#### `init(options)`
|
|
75
|
+
|
|
76
|
+
Initialize the embed with a machine and display options.
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
embed.init({
|
|
80
|
+
machine: machineConfig,
|
|
81
|
+
format: 'xstate', // optional
|
|
82
|
+
mode: 'editing', // 'editing' | 'viewing' | 'simulating'
|
|
83
|
+
theme: 'dark', // 'light' | 'dark'
|
|
84
|
+
readOnly: false,
|
|
85
|
+
depth: 3,
|
|
86
|
+
panels: {
|
|
87
|
+
leftPanels: ['code'],
|
|
88
|
+
rightPanels: ['events'],
|
|
89
|
+
activePanels: ['code'],
|
|
90
|
+
},
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
#### `updateMachine(machine, format?)`
|
|
95
|
+
|
|
96
|
+
Update the displayed machine.
|
|
97
|
+
|
|
98
|
+
#### `setMode(mode)` / `setTheme(theme)`
|
|
99
|
+
|
|
100
|
+
Change the embed mode or theme at runtime.
|
|
101
|
+
|
|
102
|
+
#### `export(format, options?)`
|
|
103
|
+
|
|
104
|
+
Export the current machine. Returns a promise.
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
const code = await embed.export('xstate', { version: 5 });
|
|
108
|
+
const json = await embed.export('json');
|
|
109
|
+
const mermaid = await embed.export('mermaid');
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Supported formats: `xstate`, `json`, `digraph`, `mermaid`, `scxml`
|
|
113
|
+
|
|
114
|
+
#### `on(event, handler)` / `off(event, handler)`
|
|
115
|
+
|
|
116
|
+
Subscribe/unsubscribe to embed events: `ready`, `loaded`, `change`, `save`, `error`.
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
embed.on('change', ({ graph, machineConfig }) => {
|
|
120
|
+
console.log('Machine changed', machineConfig);
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
#### `toast(message, type?)`
|
|
125
|
+
|
|
126
|
+
Show a toast notification in the embed. Type: `'success' | 'error' | 'info' | 'warning'`
|
|
127
|
+
|
|
128
|
+
#### `destroy()`
|
|
129
|
+
|
|
130
|
+
Tear down the embed. Removes listeners, rejects pending promises, and removes the iframe if it was created via `mount()`.
|
package/dist/index.d.mts
CHANGED
|
@@ -71,6 +71,7 @@ type EmbedEventName = keyof EmbedEventMap;
|
|
|
71
71
|
type EmbedEventHandler<K extends EmbedEventName> = (data: EmbedEventMap[K]) => void;
|
|
72
72
|
interface StatelyEmbedOptions {
|
|
73
73
|
baseUrl: string;
|
|
74
|
+
apiKey?: string;
|
|
74
75
|
origin?: string;
|
|
75
76
|
onReady?: () => void;
|
|
76
77
|
onLoaded?: (graph: unknown) => void;
|
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
//#region src/embed.ts
|
|
2
2
|
const PREFIX = "@statelyai.";
|
|
3
3
|
function createStatelyEmbed(options) {
|
|
4
|
-
const
|
|
4
|
+
const base = options.baseUrl.replace(/\/+$/, "") + "/embed";
|
|
5
|
+
const embedUrl = options.apiKey ? `${base}?api_key=${encodeURIComponent(options.apiKey)}` : base;
|
|
5
6
|
const targetOrigin = options.origin ?? new URL(embedUrl).origin;
|
|
6
7
|
let iframe = null;
|
|
7
8
|
let ownedIframe = false;
|