@reactor-team/js-sdk 3.0.0 → 3.0.2
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 +100 -133
- package/dist/index.cjs +264 -39
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +82 -9
- package/dist/index.d.ts +82 -9
- package/dist/index.js +264 -39
- package/dist/index.js.map +1 -1
- package/dist/wasm/reactor_wasm.d.ts +20 -3
- package/dist/wasm/reactor_wasm.js +58 -14
- package/dist/wasm/reactor_wasm_bg.wasm +0 -0
- package/dist/wasm/reactor_wasm_bg.wasm.d.ts +4 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,18 @@
|
|
|
4
4
|
[](https://github.com/reactor-team/reactor-client-sdks/actions)
|
|
5
5
|
[](https://github.com/reactor-team/reactor-client-sdks/blob/main/LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform
|
|
8
|
+
for real-time world models.
|
|
9
|
+
|
|
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.
|
|
13
|
+
|
|
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.
|
|
17
|
+
|
|
18
|
+
Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
|
|
8
19
|
|
|
9
20
|
## Install
|
|
10
21
|
|
|
@@ -12,10 +23,6 @@ Connect a browser app to a live [Reactor](https://reactor.inc) model.
|
|
|
12
23
|
npm install @reactor-team/js-sdk
|
|
13
24
|
```
|
|
14
25
|
|
|
15
|
-
`dist/` ships plain CJS and ESM builds plus `.d.ts` types — a bundler-free,
|
|
16
|
-
non-TypeScript app can `require()` or `import` this package directly, no
|
|
17
|
-
build step of its own required.
|
|
18
|
-
|
|
19
26
|
## Quickstart
|
|
20
27
|
|
|
21
28
|
```ts
|
|
@@ -26,105 +33,88 @@ const reactor = new Reactor({
|
|
|
26
33
|
jwt: () => fetchToken(), // or a plain string; omit for an unauthenticated local runtime
|
|
27
34
|
});
|
|
28
35
|
|
|
29
|
-
reactor.on("statusChanged", (status) =>
|
|
36
|
+
reactor.on("statusChanged", (status) => {
|
|
37
|
+
if (status === "ready") {
|
|
38
|
+
// commands and media are live
|
|
39
|
+
}
|
|
40
|
+
});
|
|
30
41
|
reactor.on("error", (error) => console.error(error.code, error.message));
|
|
31
42
|
|
|
32
43
|
await reactor.connect();
|
|
33
|
-
|
|
34
|
-
await reactor.disconnect(); // ends the session AND frees the wasm client
|
|
44
|
+
await reactor.disconnect();
|
|
35
45
|
```
|
|
36
46
|
|
|
37
47
|
The token can also be passed directly to `connect(jwt, options?)` instead of
|
|
38
48
|
the constructor.
|
|
39
49
|
|
|
40
|
-
|
|
41
|
-
instantiated lazily on the first `connect()`/`reconnect()` call, and cached
|
|
42
|
-
after that, so building a `Reactor` you never connect costs nothing.
|
|
43
|
-
|
|
44
|
-
## `disconnect()` and disposal
|
|
50
|
+
## Authentication
|
|
45
51
|
|
|
46
|
-
`
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
in one step. The `Reactor` instance itself is still usable: a later
|
|
51
|
-
`connect()`/`reconnect()` lazily builds a fresh wasm client.
|
|
52
|
-
- **`disconnect(true)`** ends the session but keeps the wasm client alive, so
|
|
53
|
-
a later `connect()`/`reconnect()` doesn't have to reload wasm and
|
|
54
|
-
reconstruct it from scratch.
|
|
55
|
-
- **`using reactor = new Reactor(...)`** (or calling `reactor[Symbol.dispose]()`
|
|
56
|
-
directly) tears the instance down for good — same resource release as a
|
|
57
|
-
plain `disconnect()`, plus dropping every registered event handler. Do this
|
|
58
|
-
when you're done with the object entirely, not on every disconnect.
|
|
59
|
-
|
|
60
|
-
## Status and session id
|
|
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:
|
|
61
56
|
|
|
62
57
|
```ts
|
|
63
|
-
|
|
64
|
-
reactor.
|
|
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();
|
|
65
76
|
```
|
|
66
77
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
to add them alongside `getStatus()`/`getSessionId()`.
|
|
78
|
+
See [Authentication](https://docs.reactor.inc/authentication) for the full request shape,
|
|
79
|
+
including `max_session_duration_seconds` and other constraints.
|
|
70
80
|
|
|
71
81
|
## Events
|
|
72
82
|
|
|
73
|
-
`on(event, handler)` / `off(event, handler)` / `once(event, handler)
|
|
83
|
+
`on(event, handler)` / `off(event, handler)` / `once(event, handler)`. The ones you'll reach
|
|
84
|
+
for most:
|
|
74
85
|
|
|
75
86
|
| Event | Payload |
|
|
76
87
|
| --- | --- |
|
|
77
88
|
| `statusChanged` | `ReactorStatus` |
|
|
78
|
-
| `sessionIdChanged` | `string \| undefined` |
|
|
79
89
|
| `error` | `ReactorError` |
|
|
80
|
-
| `message` | `ReactorMessage`
|
|
81
|
-
| `
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
| `statsUpdate` | `ConnectionStats` |
|
|
90
|
+
| `message` | `ReactorMessage` from the model |
|
|
91
|
+
| `trackReceived` | a new media track from the model |
|
|
92
|
+
|
|
93
|
+
Full list — including `schemaReceived`, `capabilitiesReceived`, and `statsUpdate` — in
|
|
94
|
+
[Events](https://docs.reactor.inc/sdk-reference/events).
|
|
86
95
|
|
|
87
96
|
## Model schema and capabilities
|
|
88
97
|
|
|
89
98
|
```ts
|
|
90
|
-
reactor.getSchema(); //
|
|
91
|
-
reactor.getCapabilities(); //
|
|
92
|
-
reactor.on("schemaReceived", (schema) => ...);
|
|
93
|
-
reactor.on("capabilitiesReceived", (capabilities) => ...);
|
|
99
|
+
reactor.getSchema(); // the model's command/webhook schema
|
|
100
|
+
reactor.getCapabilities(); // negotiated tracks and command set
|
|
94
101
|
```
|
|
95
102
|
|
|
96
|
-
Both
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
`getSessionInfo()` also returns a `capabilities` field, but it's the **raw wire shape**
|
|
102
|
-
(snake_case), not this translated one — prefer `getCapabilities()`/`capabilitiesReceived` unless
|
|
103
|
-
you specifically need the untranslated session resource.
|
|
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.
|
|
104
107
|
|
|
105
108
|
## Recording and clips
|
|
106
109
|
|
|
107
110
|
```ts
|
|
108
111
|
const clip = await reactor.requestClip(10); // last 10 seconds
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
// downloadClipAsFile() doesn't inherit the Reactor instance's JWT — pass it
|
|
112
|
-
// explicitly (omit `jwt` entirely against a local runtime, which is auth-free).
|
|
113
|
-
const blob = await reactor.downloadClipAsFile(clip, "clip.mp4", { jwt: await fetchToken() });
|
|
112
|
+
await reactor.downloadClipAsFile(clip, "clip.mp4", { jwt: await fetchToken() });
|
|
114
113
|
```
|
|
115
114
|
|
|
116
|
-
`requestClip()`/`requestRecording()`/`downloadClipAsFile()`
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
`downloadClipAsFile` in a progress/error state machine for a custom UI.
|
|
120
|
-
`downloadClipAsFile(clip, filename?, options?)` polls the clip's manifest
|
|
121
|
-
until ready, remuxes the fragmented chunks into a flat, faststart MP4, and (unless
|
|
122
|
-
`filename: null` is passed) triggers the download; pass `options.onProgress` for progress UI.
|
|
123
|
-
|
|
124
|
-
For a React preview instead of a download, `ClipPlayer`/`ClipDownloadButton`/`useClipDownload`
|
|
125
|
-
cover playback and download UI directly. Neither requires a `ReactorProvider`, but each needs a
|
|
126
|
-
JWT source outside local-dev mode — either an explicit `getJwt`, as below, or mount them under a
|
|
127
|
-
`ReactorProvider` and omit `getJwt` to inherit its resolver:
|
|
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>`:
|
|
128
118
|
|
|
129
119
|
```tsx
|
|
130
120
|
import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
|
|
@@ -133,49 +123,27 @@ import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
|
|
|
133
123
|
<ClipDownloadButton clip={clip} getJwt={() => fetchToken()} filename="clip.mp4" />
|
|
134
124
|
```
|
|
135
125
|
|
|
136
|
-
|
|
137
|
-
current browser, including iOS Safari 17.1+) and assembles a flat MP4 to play from memory on
|
|
138
|
-
the one iOS range that has none. Neither component requires a `ReactorProvider` — both work
|
|
139
|
-
directly off a `Clip` value, including clips loaded from fixtures or logs.
|
|
126
|
+
Full API, playback details, and the `useClipDownload` hook: [Recordings](https://docs.reactor.inc/concepts/recordings).
|
|
140
127
|
|
|
141
128
|
## Stats and timings
|
|
142
129
|
|
|
143
130
|
```ts
|
|
144
|
-
reactor.getStats(); // ConnectionStats | undefined
|
|
145
|
-
reactor.getConnectionTimings(); // ConnectionTimings | undefined
|
|
146
131
|
reactor.on("statsUpdate", (stats) => console.log(stats.rtt, stats.packetLossRatio));
|
|
147
132
|
```
|
|
148
133
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
type, incoming/outgoing bitrate (both estimated and real-time), video FPS,
|
|
152
|
-
packet loss ratio, and jitter — emitted as `statsUpdate` and readable
|
|
153
|
-
directly off `getStats()`. Both are `undefined` before the first sample, and
|
|
154
|
-
polling stops (clearing `getStats()`) as soon as the session leaves `"ready"`
|
|
155
|
-
for any reason, not just an explicit `disconnect()`.
|
|
156
|
-
|
|
157
|
-
`getConnectionTimings()` (also folded into every `ConnectionStats.connectionTimings`)
|
|
158
|
-
is a millisecond breakdown of the most recent `connect()`/`reconnect()`
|
|
159
|
-
handshake: `sessionCreationMs`, `transportConnectingMs`, `totalMs`.
|
|
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).
|
|
160
136
|
|
|
161
137
|
## Errors
|
|
162
138
|
|
|
163
|
-
One class, `ReactorError`, for both the `error` event payload and a rejected
|
|
164
|
-
|
|
165
|
-
`
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
It's the base of a typed hierarchy keyed by `code` — `reactor-core`'s own
|
|
169
|
-
per-failure-kind classification: `NetworkError`, `UnauthorizedError`,
|
|
170
|
-
`NotFoundError`, `ConflictError`, `RateLimitedError`, `BadRequestError`,
|
|
171
|
-
`ServerError`, `VersionMismatchError`, `DecodeError`, `InvalidStateError`,
|
|
172
|
-
`SessionTerminalError`, `MessageTooLargeError`, `TransportError`,
|
|
173
|
-
`DisconnectedError`, `RequestTimeoutError`, `AbortedError`. An unrecognized
|
|
174
|
-
code falls back to the base class. `instanceof` and matching `error.code`
|
|
175
|
-
are equivalent — pick whichever reads better at the call site:
|
|
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:
|
|
176
144
|
|
|
177
145
|
```ts
|
|
178
|
-
import {
|
|
146
|
+
import { ReactorError, UnauthorizedError } from "@reactor-team/js-sdk";
|
|
179
147
|
|
|
180
148
|
try {
|
|
181
149
|
await reactor.connect();
|
|
@@ -189,20 +157,11 @@ try {
|
|
|
189
157
|
}
|
|
190
158
|
```
|
|
191
159
|
|
|
192
|
-
`getLastError()` returns the most recent `ReactorError`, from either an
|
|
193
|
-
`error` event or a rejected call.
|
|
194
|
-
|
|
195
|
-
`sendCommand(command, data?, scope?)` awaits the model's correlated reply and
|
|
196
|
-
resolves with it (`ReactorMessage | undefined`); it never throws — a failure
|
|
197
|
-
surfaces through `getLastError()`/the `error` event instead, and the call
|
|
198
|
-
resolves `undefined`. Every other call that can fail (`connect`,
|
|
199
|
-
`publishTrack`, `uploadFile`, ...) throws normally.
|
|
200
|
-
|
|
201
160
|
## React
|
|
202
161
|
|
|
203
162
|
```tsx
|
|
204
163
|
import { useCallback } from "react";
|
|
205
|
-
import { ReactorProvider, useReactor } from "@reactor-team/js-sdk";
|
|
164
|
+
import { ReactorProvider, ReactorView, useReactor } from "@reactor-team/js-sdk";
|
|
206
165
|
|
|
207
166
|
function App() {
|
|
208
167
|
// Stable across renders — see the note on ReactorProvider below for why
|
|
@@ -224,6 +183,7 @@ function Status() {
|
|
|
224
183
|
|
|
225
184
|
return (
|
|
226
185
|
<div>
|
|
186
|
+
<ReactorView className="w-full aspect-video" videoObjectFit="cover" />
|
|
227
187
|
{status}
|
|
228
188
|
<button onClick={() => sendCommand("set_image", { url: "..." })}>Send</button>
|
|
229
189
|
</div>
|
|
@@ -231,26 +191,34 @@ function Status() {
|
|
|
231
191
|
}
|
|
232
192
|
```
|
|
233
193
|
|
|
234
|
-
`react` is a peer dependency — install it yourself, matching your app's own
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
`
|
|
241
|
-
(
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
and
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
194
|
+
`react` is a peer dependency — install it yourself, matching your app's own version.
|
|
195
|
+
|
|
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.
|
|
199
|
+
|
|
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).
|
|
205
|
+
|
|
206
|
+
## Typed model SDKs
|
|
207
|
+
|
|
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).
|
|
212
|
+
|
|
213
|
+
## API surface
|
|
214
|
+
|
|
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) |
|
|
254
222
|
|
|
255
223
|
## Development
|
|
256
224
|
|
|
@@ -271,8 +239,7 @@ See the repo-wide [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the rest
|
|
|
271
239
|
|
|
272
240
|
The [full documentation](https://docs.reactor.inc/sdk-reference/using-the-sdk)
|
|
273
241
|
covers platform concepts and the other language SDKs. See
|
|
274
|
-
[`CHANGELOG.md`](./CHANGELOG.md) for what changed release to release
|
|
275
|
-
including 3.0.0's breaking changes from the legacy 2.x SDK.
|
|
242
|
+
[`CHANGELOG.md`](./CHANGELOG.md) for what changed release to release.
|
|
276
243
|
|
|
277
244
|
## License
|
|
278
245
|
|