@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 CHANGED
@@ -1,20 +1,226 @@
1
- # Reactor Frontend SDK
1
+ # @reactor-team/js-sdk
2
2
 
3
- ## Overview
3
+ The official JavaScript/TypeScript SDK for [Reactor](https://reactor.inc), the developer platform for real-time world models.
4
4
 
5
- This is the frontend SDK for Reactor. It provides a set of tools and utilities to build frontend applications that can use the Reactor platform.
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
- There are two main ways to use the frontend SDK:
7
+ Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)**.
8
8
 
9
- 1. **Imperative API**: Use it in any TS/JS application.
10
- 2. **React API**: Use it in a React applications.
9
+ ---
11
10
 
12
- ## Building the SDK
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 build
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
- ## Documentation
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
- - [Getting Started](https://docs.reactor.inc)
226
+ MIT. © Reactor Technologies, Inc.