@reactor-team/js-sdk 2.9.2 → 2.10.0
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 +216 -10
- package/dist/index.d.mts +636 -2
- package/dist/index.d.ts +636 -2
- package/dist/index.js +1374 -81
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1360 -81
- package/dist/index.mjs.map +1 -1
- package/package.json +37 -27
package/README.md
CHANGED
|
@@ -1,20 +1,226 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @reactor-team/js-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The official JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform for real-time world models.
|
|
4
4
|
|
|
5
|
-
|
|
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.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
2. **React API**: Use it in a React applications.
|
|
9
|
+
---
|
|
11
10
|
|
|
12
|
-
##
|
|
11
|
+
## Quickstart
|
|
12
|
+
|
|
13
|
+
The fastest path is `create-reactor-app`, which scaffolds a Next.js app with auth wired up:
|
|
13
14
|
|
|
14
15
|
```bash
|
|
15
|
-
pnpm
|
|
16
|
+
pnpm create reactor-app my-app
|
|
17
|
+
cd my-app && pnpm install && pnpm dev
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Or wire it up by hand. Exchange your API key for a short-lived JWT on the server, then mount `<ReactorProvider>` in the client:
|
|
21
|
+
|
|
22
|
+
```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: { "Reactor-API-Key": process.env.REACTOR_API_KEY! },
|
|
30
|
+
});
|
|
31
|
+
const { jwt } = await r.json();
|
|
32
|
+
return NextResponse.json({ jwt });
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
// app/page.tsx
|
|
38
|
+
"use client";
|
|
39
|
+
import { use } from "react";
|
|
40
|
+
import { ReactorProvider, ReactorView } from "@reactor-team/js-sdk";
|
|
41
|
+
|
|
42
|
+
const tokenPromise = fetch("/api/token", { method: "POST" })
|
|
43
|
+
.then((r) => r.json())
|
|
44
|
+
.then(({ jwt }) => jwt);
|
|
45
|
+
|
|
46
|
+
export default function App() {
|
|
47
|
+
const token = use(tokenPromise);
|
|
48
|
+
return (
|
|
49
|
+
<ReactorProvider
|
|
50
|
+
modelName="your-model-name"
|
|
51
|
+
jwtToken={token}
|
|
52
|
+
connectOptions={{ autoConnect: true }}
|
|
53
|
+
>
|
|
54
|
+
<ReactorView className="w-full aspect-video" />
|
|
55
|
+
</ReactorProvider>
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
See the [Quickstart](https://docs.reactor.inc/quickstart) and [Authentication](https://docs.reactor.inc/authentication) docs for the full walkthrough, including production auth patterns.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## React API
|
|
65
|
+
|
|
66
|
+
`<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.
|
|
67
|
+
|
|
68
|
+
### Display video
|
|
69
|
+
|
|
70
|
+
`<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:
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
<ReactorView className="w-full aspect-video" videoObjectFit="cover" />
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
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()`.
|
|
77
|
+
|
|
78
|
+
### Send commands
|
|
79
|
+
|
|
80
|
+
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).
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
import { useReactor } from "@reactor-team/js-sdk";
|
|
84
|
+
|
|
85
|
+
function PromptInput() {
|
|
86
|
+
const { status, sendCommand } = useReactor((s) => ({
|
|
87
|
+
status: s.status,
|
|
88
|
+
sendCommand: s.sendCommand,
|
|
89
|
+
}));
|
|
90
|
+
|
|
91
|
+
return (
|
|
92
|
+
<button
|
|
93
|
+
disabled={status !== "ready"}
|
|
94
|
+
onClick={() => sendCommand("set_prompt", { prompt: "a forest at dawn" })}
|
|
95
|
+
>
|
|
96
|
+
Set prompt
|
|
97
|
+
</button>
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Publish webcam input
|
|
103
|
+
|
|
104
|
+
For video-to-video models, drop `<WebcamStream>` inside the provider and name the track the model expects. The component handles `getUserMedia`, lifecycle, and cleanup:
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
<ReactorProvider modelName="your-model-name" jwtToken={token}>
|
|
108
|
+
<ReactorView className="w-full aspect-video" />
|
|
109
|
+
<WebcamStream track="webcam" className="w-48 aspect-video" />
|
|
110
|
+
</ReactorProvider>
|
|
16
111
|
```
|
|
17
112
|
|
|
18
|
-
|
|
113
|
+
### Receive messages
|
|
114
|
+
|
|
115
|
+
Models emit structured messages back to your app, such as progress updates, state snapshots, or custom model events. Subscribe with `useReactorMessage`:
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
import { useReactorMessage } from "@reactor-team/js-sdk";
|
|
119
|
+
|
|
120
|
+
function FrameCounter() {
|
|
121
|
+
const [frame, setFrame] = useState(0);
|
|
122
|
+
useReactorMessage((msg) => {
|
|
123
|
+
if (msg.type === "state") setFrame(msg.data.current_frame);
|
|
124
|
+
});
|
|
125
|
+
return <div>Frame: {frame}</div>;
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Error handling
|
|
130
|
+
|
|
131
|
+
`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).
|
|
132
|
+
|
|
133
|
+
### Upload files
|
|
134
|
+
|
|
135
|
+
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:
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
const { uploadFile, sendCommand } = useReactor((s) => s);
|
|
139
|
+
|
|
140
|
+
const ref = await uploadFile(file);
|
|
141
|
+
await sendCommand("set_image", { image: ref });
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Imperative API
|
|
147
|
+
|
|
148
|
+
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:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import { Reactor } from "@reactor-team/js-sdk";
|
|
152
|
+
|
|
153
|
+
const reactor = new Reactor({
|
|
154
|
+
apiUrl: "https://api.reactor.inc",
|
|
155
|
+
modelName: "your-model-name",
|
|
156
|
+
jwtToken: await fetchJwt(),
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
reactor.on("statusChange", (status) => console.log("status:", status));
|
|
160
|
+
reactor.on("message", (msg) => console.log("model:", msg));
|
|
161
|
+
|
|
162
|
+
await reactor.connect();
|
|
163
|
+
|
|
164
|
+
await reactor.sendCommand("set_prompt", { prompt: "a forest at dawn" });
|
|
165
|
+
|
|
166
|
+
const stream = reactor.getMediaStream("main_video");
|
|
167
|
+
videoEl.srcObject = stream;
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Recording
|
|
173
|
+
|
|
174
|
+
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.
|
|
175
|
+
|
|
176
|
+
```tsx
|
|
177
|
+
import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
|
|
178
|
+
import type { Clip } from "@reactor-team/js-sdk";
|
|
179
|
+
|
|
180
|
+
function ClipModal({ clip, jwt }: { clip: Clip; jwt: string }) {
|
|
181
|
+
return (
|
|
182
|
+
<>
|
|
183
|
+
<ClipPlayer clip={clip} getJwt={() => jwt} />
|
|
184
|
+
<ClipDownloadButton clip={clip} getJwt={() => jwt} />
|
|
185
|
+
</>
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Capture a clip from anywhere inside the provider:
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
const reactor = useReactor((s) => s.internal.reactor);
|
|
194
|
+
const clip = await reactor.requestClip(10); // last 10 s
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`<ClipPlayer>` uses native HLS on Safari/iOS; install `hls.js` to support Chrome, Firefox, and Edge:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
pnpm add hls.js
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Full walkthrough, error codes, and the headless `useClipDownload` hook: [Recordings](https://docs.reactor.inc/concepts/recordings).
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Typed model SDKs
|
|
208
|
+
|
|
209
|
+
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.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## API surface
|
|
214
|
+
|
|
215
|
+
| Surface | Where it lives |
|
|
216
|
+
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
217
|
+
| `Reactor` | [Reactor class](https://docs.reactor.inc/api-reference/reactor-class) |
|
|
218
|
+
| `<ReactorProvider>`, `<ReactorView>`, `<WebcamStream>`, `<ReactorController>` | [React components](https://docs.reactor.inc/api-reference/react-components) |
|
|
219
|
+
| `useReactor`, `useReactorMessage`, `useStats` | [React hooks](https://docs.reactor.inc/api-reference/react-hooks) |
|
|
220
|
+
| `<ClipPlayer>`, `<ClipDownloadButton>`, `useClipDownload`, `RecordingClient`, `RecordingError`, `fetchPlaylist`, `parsePlaylist` | [Recordings](https://docs.reactor.inc/concepts/recordings) |
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## License
|
|
19
225
|
|
|
20
|
-
|
|
226
|
+
MIT. © Reactor Technologies, Inc.
|