@reactor-team/js-sdk 2.12.4 → 3.0.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 +174 -168
- package/dist/index.cjs +2580 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1266 -0
- package/dist/index.d.ts +981 -1075
- package/dist/index.js +1722 -4079
- package/dist/index.js.map +1 -1
- package/dist/wasm/README.md +151 -0
- package/dist/wasm/package.json +21 -0
- package/dist/wasm/reactor_wasm.d.ts +439 -0
- package/dist/wasm/reactor_wasm.js +1465 -0
- package/dist/wasm/reactor_wasm_bg.wasm +0 -0
- package/dist/wasm/reactor_wasm_bg.wasm.d.ts +54 -0
- package/package.json +35 -53
- package/LICENSE +0 -201
- package/NOTICE +0 -5
- package/dist/index.d.mts +0 -1360
- package/dist/index.mjs +0 -4805
- package/dist/index.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -1,240 +1,246 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Reactor JS SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@reactor-team/js-sdk)
|
|
4
|
+
[](https://github.com/reactor-team/reactor-client-sdks/actions)
|
|
5
|
+
[](https://github.com/reactor-team/reactor-client-sdks/blob/main/LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
The JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform
|
|
8
|
+
for real-time world models.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
In a few lines of code you can connect a browser app to a Reactor session over WebRTC,
|
|
11
|
+
render live model video at 30–60 FPS, send typed commands to steer what generates, and
|
|
12
|
+
receive structured messages back.
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
The SDK ships a React API (`ReactorProvider`,
|
|
15
|
+
`ReactorView`, `useReactor`, …) for browser apps, and an imperative `Reactor` class for
|
|
16
|
+
everything else running in a browser context — Electron, a game engine's webview, and so on.
|
|
10
17
|
|
|
11
|
-
|
|
18
|
+
Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
|
|
12
19
|
|
|
13
|
-
|
|
20
|
+
## Install
|
|
14
21
|
|
|
15
22
|
```bash
|
|
16
|
-
|
|
17
|
-
cd my-app && pnpm install && pnpm dev
|
|
23
|
+
npm install @reactor-team/js-sdk
|
|
18
24
|
```
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
## Quickstart
|
|
21
27
|
|
|
22
28
|
```ts
|
|
23
|
-
|
|
24
|
-
import { NextResponse } from "next/server";
|
|
25
|
-
|
|
26
|
-
export async function POST() {
|
|
27
|
-
const r = await fetch("https://api.reactor.inc/tokens", {
|
|
28
|
-
method: "POST",
|
|
29
|
-
headers: {
|
|
30
|
-
"Reactor-API-Key": process.env.REACTOR_API_KEY!,
|
|
31
|
-
"Content-Type": "application/json",
|
|
32
|
-
},
|
|
33
|
-
body: JSON.stringify({
|
|
34
|
-
authorization_details: [
|
|
35
|
-
{
|
|
36
|
-
type: "session",
|
|
37
|
-
resources: { models: { match: ["your-org/your-model-name"] } },
|
|
38
|
-
constraints: { max_sessions: 10 },
|
|
39
|
-
},
|
|
40
|
-
],
|
|
41
|
-
}),
|
|
42
|
-
});
|
|
43
|
-
const { jwt } = await r.json();
|
|
44
|
-
return NextResponse.json({ jwt });
|
|
45
|
-
}
|
|
46
|
-
```
|
|
29
|
+
import { Reactor } from "@reactor-team/js-sdk";
|
|
47
30
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
import { ReactorProvider, ReactorView } from "@reactor-team/js-sdk";
|
|
31
|
+
const reactor = new Reactor({
|
|
32
|
+
modelName: "my-model",
|
|
33
|
+
jwt: () => fetchToken(), // or a plain string; omit for an unauthenticated local runtime
|
|
34
|
+
});
|
|
53
35
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
36
|
+
reactor.on("statusChanged", (status) => {
|
|
37
|
+
if (status === "ready") {
|
|
38
|
+
// commands and media are live
|
|
39
|
+
}
|
|
40
|
+
});
|
|
41
|
+
reactor.on("error", (error) => console.error(error.code, error.message));
|
|
57
42
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
return (
|
|
61
|
-
<ReactorProvider
|
|
62
|
-
modelName="your-model-name"
|
|
63
|
-
jwtToken={token}
|
|
64
|
-
connectOptions={{ autoConnect: true }}
|
|
65
|
-
>
|
|
66
|
-
<ReactorView className="w-full aspect-video" />
|
|
67
|
-
</ReactorProvider>
|
|
68
|
-
);
|
|
69
|
-
}
|
|
43
|
+
await reactor.connect();
|
|
44
|
+
await reactor.disconnect();
|
|
70
45
|
```
|
|
71
46
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## React API
|
|
77
|
-
|
|
78
|
-
`<ReactorProvider>` owns the connection. Components, hooks, and the recording surfaces all read state and methods from its context. Don't call `connect()` unless `autoConnect` is `false`; the provider can manage it for you.
|
|
47
|
+
The token can also be passed directly to `connect(jwt, options?)` instead of
|
|
48
|
+
the constructor.
|
|
79
49
|
|
|
80
|
-
|
|
50
|
+
## Authentication
|
|
81
51
|
|
|
82
|
-
|
|
52
|
+
`fetchToken()` above is your own function — mint the JWT server-side so your API key never
|
|
53
|
+
reaches the browser. The `authorization_details` block scopes the token: it can create a
|
|
54
|
+
bounded number of sessions for one model and act only on the sessions it created, so a
|
|
55
|
+
leaked token exposes nothing else on the account:
|
|
83
56
|
|
|
84
|
-
```
|
|
85
|
-
|
|
57
|
+
```ts
|
|
58
|
+
// e.g. a Next.js route handler
|
|
59
|
+
const result = await fetch("https://api.reactor.inc/tokens", {
|
|
60
|
+
method: "POST",
|
|
61
|
+
headers: {
|
|
62
|
+
"Reactor-API-Key": process.env.REACTOR_API_KEY!,
|
|
63
|
+
"Content-Type": "application/json",
|
|
64
|
+
},
|
|
65
|
+
body: JSON.stringify({
|
|
66
|
+
authorization_details: [
|
|
67
|
+
{
|
|
68
|
+
type: "session",
|
|
69
|
+
resources: { models: { match: ["my-model"] } },
|
|
70
|
+
constraints: { max_sessions: 5 },
|
|
71
|
+
},
|
|
72
|
+
],
|
|
73
|
+
}),
|
|
74
|
+
});
|
|
75
|
+
const { jwt } = await result.json();
|
|
86
76
|
```
|
|
87
77
|
|
|
88
|
-
|
|
78
|
+
See [Authentication](https://docs.reactor.inc/authentication) for the full request shape,
|
|
79
|
+
including `max_session_duration_seconds` and other constraints.
|
|
89
80
|
|
|
90
|
-
|
|
81
|
+
## Events
|
|
91
82
|
|
|
92
|
-
|
|
83
|
+
`on(event, handler)` / `off(event, handler)` / `once(event, handler)`. The ones you'll reach
|
|
84
|
+
for most:
|
|
93
85
|
|
|
94
|
-
|
|
95
|
-
|
|
86
|
+
| Event | Payload |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| `statusChanged` | `ReactorStatus` |
|
|
89
|
+
| `error` | `ReactorError` |
|
|
90
|
+
| `message` | `ReactorMessage` from the model |
|
|
91
|
+
| `trackReceived` | a new media track from the model |
|
|
96
92
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
status: s.status,
|
|
100
|
-
sendCommand: s.sendCommand,
|
|
101
|
-
}));
|
|
93
|
+
Full list — including `schemaReceived`, `capabilitiesReceived`, and `statsUpdate` — in
|
|
94
|
+
[Events](https://docs.reactor.inc/sdk-reference/events).
|
|
102
95
|
|
|
103
|
-
|
|
104
|
-
<button
|
|
105
|
-
disabled={status !== "ready"}
|
|
106
|
-
onClick={() => sendCommand("set_prompt", { prompt: "a forest at dawn" })}
|
|
107
|
-
>
|
|
108
|
-
Set prompt
|
|
109
|
-
</button>
|
|
110
|
-
);
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### Publish webcam input
|
|
96
|
+
## Model schema and capabilities
|
|
115
97
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
<ReactorProvider modelName="your-model-name" jwtToken={token}>
|
|
120
|
-
<ReactorView className="w-full aspect-video" />
|
|
121
|
-
<WebcamStream track="webcam" className="w-48 aspect-video" />
|
|
122
|
-
</ReactorProvider>
|
|
98
|
+
```ts
|
|
99
|
+
reactor.getSchema(); // the model's command/webhook schema
|
|
100
|
+
reactor.getCapabilities(); // negotiated tracks and command set
|
|
123
101
|
```
|
|
124
102
|
|
|
125
|
-
|
|
103
|
+
Both arrive automatically after `connect()` — no request needed — via the getters above or the
|
|
104
|
+
matching `schemaReceived`/`capabilitiesReceived` events. See
|
|
105
|
+
[`getSchema()`](https://docs.reactor.inc/sdk-reference/reactor-class#getschema) and
|
|
106
|
+
[`Capabilities`](https://docs.reactor.inc/sdk-reference/types#capabilities) for the full shape.
|
|
126
107
|
|
|
127
|
-
|
|
108
|
+
## Recording and clips
|
|
128
109
|
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
function FrameCounter() {
|
|
133
|
-
const [frame, setFrame] = useState(0);
|
|
134
|
-
useReactorMessage((msg) => {
|
|
135
|
-
if (msg.type === "state") setFrame(msg.data.current_frame);
|
|
136
|
-
});
|
|
137
|
-
return <div>Frame: {frame}</div>;
|
|
138
|
-
}
|
|
110
|
+
```ts
|
|
111
|
+
const clip = await reactor.requestClip(10); // last 10 seconds
|
|
112
|
+
await reactor.downloadClipAsFile(clip, "clip.mp4", { jwt: await fetchToken() });
|
|
139
113
|
```
|
|
140
114
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
### Upload files
|
|
146
|
-
|
|
147
|
-
Bind an `<input type="file">` to the model with `uploadFile` and then pass the returned [`FileRef`](https://docs.reactor.inc/api-reference/types#fileref) into any command:
|
|
115
|
+
`requestClip()`/`requestRecording()`/`downloadClipAsFile()` live directly on `Reactor`, and the
|
|
116
|
+
same three are bound on the React store. For a preview or download button instead, drop in
|
|
117
|
+
`<ClipPlayer>`/`<ClipDownloadButton>`:
|
|
148
118
|
|
|
149
119
|
```tsx
|
|
150
|
-
|
|
151
|
-
uploadFile: s.uploadFile,
|
|
152
|
-
sendCommand: s.sendCommand,
|
|
153
|
-
}));
|
|
120
|
+
import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
|
|
154
121
|
|
|
155
|
-
|
|
156
|
-
|
|
122
|
+
<ClipPlayer clip={clip} getJwt={() => fetchToken()} />
|
|
123
|
+
<ClipDownloadButton clip={clip} getJwt={() => fetchToken()} filename="clip.mp4" />
|
|
157
124
|
```
|
|
158
125
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
## Imperative API
|
|
126
|
+
Full API, playback details, and the `useClipDownload` hook: [Recordings](https://docs.reactor.inc/concepts/recordings).
|
|
162
127
|
|
|
163
|
-
|
|
128
|
+
## Stats and timings
|
|
164
129
|
|
|
165
130
|
```ts
|
|
166
|
-
|
|
131
|
+
reactor.on("statsUpdate", (stats) => console.log(stats.rtt, stats.packetLossRatio));
|
|
132
|
+
```
|
|
167
133
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
modelName: "your-model-name",
|
|
171
|
-
});
|
|
134
|
+
`getStats()`/`getConnectionTimings()` give you the same data on demand. Field list (RTT,
|
|
135
|
+
bitrate, jitter, handshake timing, ...) in [Types](https://docs.reactor.inc/sdk-reference/types#connectionstats).
|
|
172
136
|
|
|
173
|
-
|
|
174
|
-
reactor.on("message", (msg) => console.log("model:", msg));
|
|
175
|
-
reactor.on("trackReceived", (name, _track, stream) => {
|
|
176
|
-
if (name === "main_video") videoEl.srcObject = stream;
|
|
177
|
-
});
|
|
137
|
+
## Errors
|
|
178
138
|
|
|
179
|
-
|
|
139
|
+
One class, `ReactorError`, for both the `error` event payload and a rejected call's error —
|
|
140
|
+
carries `code`, `message`, and `recoverable`. It's the base of a typed hierarchy, one subclass
|
|
141
|
+
per failure kind (`UnauthorizedError`, `RateLimitedError`, `NetworkError`, ...) — full list in
|
|
142
|
+
[Types](https://docs.reactor.inc/sdk-reference/types#reactorerror). `instanceof` and matching
|
|
143
|
+
`error.code` are equivalent:
|
|
180
144
|
|
|
181
|
-
|
|
145
|
+
```ts
|
|
146
|
+
import { ReactorError, UnauthorizedError } from "@reactor-team/js-sdk";
|
|
147
|
+
|
|
148
|
+
try {
|
|
149
|
+
await reactor.connect();
|
|
150
|
+
} catch (error) {
|
|
151
|
+
if (error instanceof UnauthorizedError) {
|
|
152
|
+
await refreshToken();
|
|
153
|
+
} else if (error instanceof ReactorError && error.recoverable) {
|
|
154
|
+
await reactor.reconnect();
|
|
155
|
+
}
|
|
156
|
+
throw error;
|
|
157
|
+
}
|
|
182
158
|
```
|
|
183
159
|
|
|
184
|
-
|
|
160
|
+
## React
|
|
185
161
|
|
|
186
|
-
|
|
162
|
+
```tsx
|
|
163
|
+
import { useCallback } from "react";
|
|
164
|
+
import { ReactorProvider, ReactorView, useReactor } from "@reactor-team/js-sdk";
|
|
187
165
|
|
|
188
|
-
|
|
166
|
+
function App() {
|
|
167
|
+
// Stable across renders — see the note on ReactorProvider below for why
|
|
168
|
+
// this matters.
|
|
169
|
+
const jwt = useCallback(() => fetchToken(), []);
|
|
189
170
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
171
|
+
return (
|
|
172
|
+
<ReactorProvider modelName="my-model" jwtToken={jwt}>
|
|
173
|
+
<Status />
|
|
174
|
+
</ReactorProvider>
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
function Status() {
|
|
179
|
+
const { status, sendCommand } = useReactor((s) => ({
|
|
180
|
+
status: s.status,
|
|
181
|
+
sendCommand: s.sendCommand,
|
|
182
|
+
}));
|
|
193
183
|
|
|
194
|
-
function ClipModal({ clip, jwt }: { clip: Clip; jwt: string }) {
|
|
195
184
|
return (
|
|
196
|
-
|
|
197
|
-
<
|
|
198
|
-
|
|
199
|
-
|
|
185
|
+
<div>
|
|
186
|
+
<ReactorView className="w-full aspect-video" videoObjectFit="cover" />
|
|
187
|
+
{status}
|
|
188
|
+
<button onClick={() => sendCommand("set_image", { url: "..." })}>Send</button>
|
|
189
|
+
</div>
|
|
200
190
|
);
|
|
201
191
|
}
|
|
202
192
|
```
|
|
203
193
|
|
|
204
|
-
|
|
194
|
+
`react` is a peer dependency — install it yourself, matching your app's own version.
|
|
205
195
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
```
|
|
196
|
+
`ReactorProvider`'s props are live: changing `jwtToken`, `modelName`, or `connectOptions` tears
|
|
197
|
+
down the current connection and builds a fresh one. Pass a stable `jwtToken` (`useCallback`, or
|
|
198
|
+
hoist it outside the component) so an unrelated re-render doesn't reconnect you.
|
|
210
199
|
|
|
211
|
-
|
|
200
|
+
`useReactor(selector)` binds connection state (`status`, `lastError`, `lastMessage`, `tracks`, ...)
|
|
201
|
+
and the common actions (`connect`, `sendCommand`, `publish`, `requestClip`, ...) — enough for most
|
|
202
|
+
components. For anything else — schema, capabilities, stats, track lookups, the raw event
|
|
203
|
+
emitter — `useReactor((s) => s.internal.reactor)` gets you the underlying `Reactor` instance.
|
|
204
|
+
Full field list: [React hooks](https://docs.reactor.inc/sdk-reference/react-hooks).
|
|
212
205
|
|
|
213
|
-
|
|
206
|
+
## Typed model SDKs
|
|
214
207
|
|
|
215
|
-
|
|
208
|
+
For models with a published typed SDK, prefer [`@reactor-models/<name>`](https://www.npmjs.com/org/reactor-models).
|
|
209
|
+
It re-exports everything here and adds typed commands, messages, and hooks for one
|
|
210
|
+
specific model. Use this base SDK when the model doesn't have a typed package yet, or when
|
|
211
|
+
you want to stay model-agnostic. See [Typed model SDKs](https://docs.reactor.inc/sdk-reference/typed-model-sdk).
|
|
216
212
|
|
|
217
|
-
|
|
213
|
+
## API surface
|
|
218
214
|
|
|
219
|
-
|
|
215
|
+
| Surface | Where it lives |
|
|
216
|
+
| --- | --- |
|
|
217
|
+
| `Reactor` | [Reactor class](https://docs.reactor.inc/sdk-reference/reactor-class) |
|
|
218
|
+
| `<ReactorProvider>`, `<ReactorView>`, `<WebcamStream>` | [React components](https://docs.reactor.inc/sdk-reference/react-components) |
|
|
219
|
+
| `useReactor`, `useReactorMessage`, `useReactorInternalMessage`, `useStats` | [React hooks](https://docs.reactor.inc/sdk-reference/react-hooks) |
|
|
220
|
+
| `<ClipPlayer>`, `<ClipDownloadButton>`, `useClipDownload` | [Recordings](https://docs.reactor.inc/concepts/recordings) |
|
|
221
|
+
| `ReactorError` and its subclasses, `Clip`, `Capabilities`, `ConnectionStats`, ... | [Types](https://docs.reactor.inc/sdk-reference/types) |
|
|
220
222
|
|
|
221
|
-
##
|
|
223
|
+
## Development
|
|
222
224
|
|
|
223
|
-
|
|
225
|
+
```bash
|
|
226
|
+
mise run install:js # npm install
|
|
227
|
+
mise run lint:js # eslint + tsc --noEmit
|
|
228
|
+
mise run build:js # tsup -> dist/, then copies reactor-wasm's pkg/ into dist/wasm
|
|
229
|
+
mise run test:js # vitest — pure-JS unit tests against a mocked ReactorClient, no wasm build needed
|
|
230
|
+
```
|
|
224
231
|
|
|
225
|
-
|
|
232
|
+
`build:js` fails fast with a clear message if `crates/reactor-wasm/pkg`
|
|
233
|
+
doesn't exist yet — run `mise run build:wasm` first.
|
|
226
234
|
|
|
227
|
-
|
|
235
|
+
See the repo-wide [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the rest
|
|
236
|
+
(DCO, commit conventions, opening a PR).
|
|
228
237
|
|
|
229
|
-
|
|
230
|
-
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
231
|
-
| `Reactor` | [Reactor class](https://docs.reactor.inc/api-reference/reactor-class) |
|
|
232
|
-
| `<ReactorProvider>`, `<ReactorView>`, `<WebcamStream>` | [React components](https://docs.reactor.inc/api-reference/react-components) |
|
|
233
|
-
| `useReactor`, `useReactorMessage`, `useStats` | [React hooks](https://docs.reactor.inc/api-reference/react-hooks) |
|
|
234
|
-
| `<ClipPlayer>`, `<ClipDownloadButton>`, `useClipDownload`, `RecordingClient`, `RecordingError`, `fetchPlaylist`, `parsePlaylist` | [Recordings](https://docs.reactor.inc/concepts/recordings) |
|
|
238
|
+
## Documentation
|
|
235
239
|
|
|
236
|
-
|
|
240
|
+
The [full documentation](https://docs.reactor.inc/sdk-reference/using-the-sdk)
|
|
241
|
+
covers platform concepts and the other language SDKs. See
|
|
242
|
+
[`CHANGELOG.md`](./CHANGELOG.md) for what changed release to release.
|
|
237
243
|
|
|
238
244
|
## License
|
|
239
245
|
|
|
240
|
-
|
|
246
|
+
Apache-2.0 — see [`LICENSE`](../../LICENSE).
|