@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 CHANGED
@@ -1,240 +1,246 @@
1
- # @reactor-team/js-sdk
1
+ # Reactor JS SDK
2
2
 
3
- The official JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform for real-time world models.
3
+ [![npm version](https://img.shields.io/npm/v/@reactor-team/js-sdk)](https://www.npmjs.com/package/@reactor-team/js-sdk)
4
+ [![build](https://img.shields.io/github/actions/workflow/status/reactor-team/reactor-client-sdks/ci.yml?branch=main)](https://github.com/reactor-team/reactor-client-sdks/actions)
5
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/reactor-team/reactor-client-sdks/blob/main/LICENSE)
4
6
 
5
- In a few lines of code you can connect a browser or Node app to a Reactor session over WebRTC, render live model video at 30–60 FPS, send typed commands to steer what generates, and receive structured messages back. The SDK ships a React API (`ReactorProvider`, `ReactorView`, `useReactor`, …) for browser apps, and an imperative `Reactor` class for everything else.
7
+ The JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform
8
+ for real-time world models.
6
9
 
7
- Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
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
- ## Quickstart
18
+ Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
12
19
 
13
- The fastest path is `create-reactor-app`, which scaffolds a Next.js app with auth wired up:
20
+ ## Install
14
21
 
15
22
  ```bash
16
- pnpm create reactor-app my-app
17
- cd my-app && pnpm install && pnpm dev
23
+ npm install @reactor-team/js-sdk
18
24
  ```
19
25
 
20
- Or wire it up by hand. Exchange your API key on the server for a short-lived JWT **scoped to your model**, then mount `<ReactorProvider>` in the client. The `authorization_details` block is what downscopes the token: it can create a bounded number of sessions for that one model and act only on the sessions it created — a leaked token exposes nothing else on the account:
26
+ ## Quickstart
21
27
 
22
28
  ```ts
23
- // app/api/token/route.ts
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
- ```tsx
49
- // app/page.tsx
50
- "use client";
51
- import { use } from "react";
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
- const tokenPromise = fetch("/api/token", { method: "POST" })
55
- .then((r) => r.json())
56
- .then(({ jwt }) => jwt);
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
- export default function App() {
59
- const token = use(tokenPromise);
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
- See the [Quickstart](https://docs.reactor.inc/quickstart) and [Authentication](https://docs.reactor.inc/authentication) docs for the full walkthrough, including production auth patterns.
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
- ### Display video
50
+ ## Authentication
81
51
 
82
- `<ReactorView>` binds to the model's `main_video` track and manages the underlying `<video>` element. Most models expose a single video output and you can drop it in unchanged:
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
- ```tsx
85
- <ReactorView className="w-full aspect-video" videoObjectFit="cover" />
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
- To play model audio alongside the video, set `audioTrack` to the track name declared by the model. To attach the stream to your own `<video>` element instead, read `tracks[name]` from `useReactor()`.
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
- ### Send commands
81
+ ## Events
91
82
 
92
- Commands are the model's typed RPC surface (`set_prompt`, `set_image`, and any custom events declared in the model schema). The full catalog is in the [Model API Reference](https://docs.reactor.inc/model-api-reference/overview).
83
+ `on(event, handler)` / `off(event, handler)` / `once(event, handler)`. The ones you'll reach
84
+ for most:
93
85
 
94
- ```tsx
95
- import { useReactor } from "@reactor-team/js-sdk";
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
- function PromptInput() {
98
- const { status, sendCommand } = useReactor((s) => ({
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
- return (
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
- For video-to-video models, drop `<WebcamStream>` inside the provider and name the track the model expects. The component handles `getUserMedia`, lifecycle, and cleanup:
117
-
118
- ```tsx
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
- ### Receive messages
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
- Models emit structured messages back to your app, such as progress updates, state snapshots, or custom model events. Subscribe with `useReactorMessage`. Select store fields one at a time so a component only re-renders when something it actually uses changes — passing `(s) => s` will rerender on every track frame, status flip, and error:
108
+ ## Recording and clips
128
109
 
129
- ```tsx
130
- import { useReactorMessage } from "@reactor-team/js-sdk";
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
- ### Error handling
142
-
143
- `useReactor((s) => s.lastError)` exposes the most recent `ReactorError`. Recoverable errors can be retried via `s.reconnect()`. Full code catalog: [`ReactorError`](https://docs.reactor.inc/api-reference/types#reactorerror).
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
- const { uploadFile, sendCommand } = useReactor((s) => ({
151
- uploadFile: s.uploadFile,
152
- sendCommand: s.sendCommand,
153
- }));
120
+ import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
154
121
 
155
- const ref = await uploadFile(file);
156
- await sendCommand("set_image", { image: ref });
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
- For non-React apps such as Electron shells, game engines, or Node scripts, use the `Reactor` class directly. It exposes the same surface as the React store, without the React glue:
128
+ ## Stats and timings
164
129
 
165
130
  ```ts
166
- import { Reactor } from "@reactor-team/js-sdk";
131
+ reactor.on("statsUpdate", (stats) => console.log(stats.rtt, stats.packetLossRatio));
132
+ ```
167
133
 
168
- const reactor = new Reactor({
169
- apiUrl: "https://api.reactor.inc",
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
- reactor.on("statusChanged", (status) => console.log("status:", status));
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
- await reactor.connect(await fetchJwt());
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
- await reactor.sendCommand("set_prompt", { prompt: "a forest at dawn" });
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
- ## Recording
162
+ ```tsx
163
+ import { useCallback } from "react";
164
+ import { ReactorProvider, ReactorView, useReactor } from "@reactor-team/js-sdk";
187
165
 
188
- Sessions are recorded as they stream. Ask the runtime for the last `N` seconds with `requestClip`, or the full session so far with `requestRecording`. Both resolve to a `Clip` value that you can pass to `<ClipPlayer>` for preview, or to `<ClipDownloadButton>` to save as MP4.
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
- ```tsx
191
- import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
192
- import type { Clip } from "@reactor-team/js-sdk";
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
- <ClipPlayer clip={clip} getJwt={() => jwt} />
198
- <ClipDownloadButton clip={clip} getJwt={() => jwt} />
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
- Capture a clip from anywhere inside the provider:
194
+ `react` is a peer dependency — install it yourself, matching your app's own version.
205
195
 
206
- ```tsx
207
- const reactor = useReactor((s) => s.internal.reactor);
208
- const clip = await reactor.requestClip(10); // last 10 s
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
- `<ClipPlayer>` streams clips with `hls.js` wherever the browser has Media Source Extensions — Chrome, Firefox, Edge, Safari, and iOS Safari 17.1 and later. It ships with the SDK, and nothing needs installing. The import is dynamic, so `hls.js` gets a chunk of its own: an app that renders a player fetches it when the first clip plays, and one that never renders a player leaves it out of the build.
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
- On iOS before 17.1, where those extensions don't exist, the player fetches the clip's chunks itself and plays the assembled MP4 from memory. The viewer waits for the whole clip rather than the first segment, and it plays.
206
+ ## Typed model SDKs
214
207
 
215
- Downloads are remuxed into a flat MP4 (`start_time=0`, faststart, `major_brand=isom`) under the hood so the resulting file uploads cleanly to Twitter, Instagram, TikTok, and YouTube without any extra setup on your side — the H.264 / AAC bitstream itself is passed through untouched.
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
- Full walkthrough, error codes, and the headless `useClipDownload` hook: [Recordings](https://docs.reactor.inc/concepts/recordings).
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
- ## Typed model SDKs
223
+ ## Development
222
224
 
223
- For models with a published typed SDK, prefer [`@reactor-models/<name>`](https://www.npmjs.com/org/reactor-models). It re-exports everything here and adds typed commands, messages, and hooks for one specific model. Use this base SDK when the model doesn't have a typed package yet, or when you want to stay model-agnostic.
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
- ## API surface
235
+ See the repo-wide [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the rest
236
+ (DCO, commit conventions, opening a PR).
228
237
 
229
- | Surface | Where it lives |
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
- [Apache 2.0](https://github.com/reactor-team/js-sdk/blob/main/LICENSE) © 2024-2026 Reactor Technologies, Inc.
246
+ Apache-2.0 — see [`LICENSE`](../../LICENSE).