@reactor-team/js-sdk 3.1.0 → 3.2.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 +63 -11
- package/dist/index.cjs +59 -37
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +36 -18
- package/dist/index.d.ts +36 -18
- package/dist/index.js +59 -37
- package/dist/index.js.map +1 -1
- package/dist/wasm/reactor_wasm.d.ts +15 -6
- package/dist/wasm/reactor_wasm.js +22 -9
- package/package.json +1 -1
- package/dist/wasm/reactor_wasm_bg.wasm +0 -0
package/README.md
CHANGED
|
@@ -23,6 +23,16 @@ Full reference and guides live at **[docs.reactor.inc](https://docs.reactor.inc)
|
|
|
23
23
|
npm install @reactor-team/js-sdk
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
+
No bundler configuration needed: the WebAssembly binding the SDK runs on
|
|
27
|
+
ships inside its own JavaScript module, fetched the first time a `Reactor`
|
|
28
|
+
connects rather than when the SDK is imported. Each release is
|
|
29
|
+
checked against Vite 6, 7 and 8 and Next.js 15 and 16 (webpack and
|
|
30
|
+
Turbopack), in both dev and production builds, except Next.js 15 with
|
|
31
|
+
Turbopack, checked in dev only since its production build is still beta.
|
|
32
|
+
|
|
33
|
+
If your page sets a Content Security Policy, its `script-src` needs
|
|
34
|
+
`'wasm-unsafe-eval'` for the binding to compile.
|
|
35
|
+
|
|
26
36
|
## Quickstart
|
|
27
37
|
|
|
28
38
|
```ts
|
|
@@ -30,7 +40,7 @@ import { Reactor } from "@reactor-team/js-sdk";
|
|
|
30
40
|
|
|
31
41
|
const reactor = new Reactor({
|
|
32
42
|
modelName: "my-model",
|
|
33
|
-
jwt:
|
|
43
|
+
jwt: fetchToken, // your resolver, or a plain string; omit for an unauthenticated local runtime
|
|
34
44
|
});
|
|
35
45
|
|
|
36
46
|
reactor.on("statusChanged", (status) => {
|
|
@@ -78,6 +88,45 @@ const { jwt } = await result.json();
|
|
|
78
88
|
See [Authentication](https://docs.reactor.inc/authentication) for the full request shape,
|
|
79
89
|
including `max_session_duration_seconds` and other constraints.
|
|
80
90
|
|
|
91
|
+
### Refreshing a token mid-session
|
|
92
|
+
|
|
93
|
+
A scoped token reaches only the sessions it created or was bound to. When a session outlives
|
|
94
|
+
its token, a fresh token minted the same way cannot reach it: uploads, reconnects, the session
|
|
95
|
+
delete and clip reads all return `403`. So the SDK tells the resolver what each request is for:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
async function fetchToken({ sessionId }: JwtRequestContext = {}): Promise<string> {
|
|
99
|
+
// ask your backend for a token, and pass sessionId along when it is set
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`sessionId` is set for every request that targets an existing session and unset for session
|
|
104
|
+
creation. Keep returning the token that created the session until shortly before it expires.
|
|
105
|
+
Then mint a replacement bound to that session, which lets it act on the session and create
|
|
106
|
+
nothing else:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
body: JSON.stringify({
|
|
110
|
+
authorization_details: [
|
|
111
|
+
{
|
|
112
|
+
type: "session",
|
|
113
|
+
resources: { models: { match: ["my-model"] }, sessions: { bind: [sessionId] } },
|
|
114
|
+
},
|
|
115
|
+
],
|
|
116
|
+
}),
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Reactor only binds a session the API key owns, so the question your backend must answer is
|
|
120
|
+
whether *this* browser may hold a token for *that* session. The simplest answer is to create the
|
|
121
|
+
session on the backend and hand the browser `{ jwt, sessionId }` to adopt with
|
|
122
|
+
`connect(jwt, { sessionId })`: the backend then knows the owner. When the browser creates the
|
|
123
|
+
session itself, have it register the session id as soon as the SDK first names it to the
|
|
124
|
+
resolver, which is right after creation, with the token that created it; check that token
|
|
125
|
+
against `GET /sessions/{id}` (Reactor answers only for a token bound to it), and remember the
|
|
126
|
+
session for that browser. Registering only after `connect()` returns is too late when a slow
|
|
127
|
+
model keeps the connect open past the token's expiry. The bundled examples do exactly that in
|
|
128
|
+
`examples/shared/token-server.ts`.
|
|
129
|
+
|
|
81
130
|
## Events
|
|
82
131
|
|
|
83
132
|
`on(event, handler)` / `off(event, handler)` / `once(event, handler)`. The ones you'll reach
|
|
@@ -109,9 +158,14 @@ matching `schemaReceived`/`capabilitiesReceived` events. See
|
|
|
109
158
|
|
|
110
159
|
```ts
|
|
111
160
|
const clip = await reactor.requestClip(10); // last 10 seconds
|
|
112
|
-
await reactor.downloadClipAsFile(clip, "clip.mp4", { jwt:
|
|
161
|
+
await reactor.downloadClipAsFile(clip, "clip.mp4", { jwt: reactor.getJwtResolver() });
|
|
113
162
|
```
|
|
114
163
|
|
|
164
|
+
`jwt` takes a token or a resolver. A resolver is called before every poll of the manifest with
|
|
165
|
+
`{ sessionId: clip.sessionId }`, so a clip that takes a while to become ready still downloads
|
|
166
|
+
after the token that created the session has expired. The same goes for `getJwt` on
|
|
167
|
+
`<ClipPlayer>`, `<ClipDownloadButton>` and `useClipDownload`.
|
|
168
|
+
|
|
115
169
|
`requestClip()`/`requestRecording()`/`downloadClipAsFile()` live directly on `Reactor`, and the
|
|
116
170
|
same three are bound on the React store. For a preview or download button instead, drop in
|
|
117
171
|
`<ClipPlayer>`/`<ClipDownloadButton>`:
|
|
@@ -119,8 +173,8 @@ same three are bound on the React store. For a preview or download button instea
|
|
|
119
173
|
```tsx
|
|
120
174
|
import { ClipPlayer, ClipDownloadButton } from "@reactor-team/js-sdk";
|
|
121
175
|
|
|
122
|
-
<ClipPlayer clip={clip} getJwt={
|
|
123
|
-
<ClipDownloadButton clip={clip} getJwt={
|
|
176
|
+
<ClipPlayer clip={clip} getJwt={fetchToken} />
|
|
177
|
+
<ClipDownloadButton clip={clip} getJwt={fetchToken} filename="clip.mp4" />
|
|
124
178
|
```
|
|
125
179
|
|
|
126
180
|
Full API, playback details, and the `useClipDownload` hook: [Recordings](https://docs.reactor.inc/concepts/recordings).
|
|
@@ -160,16 +214,13 @@ try {
|
|
|
160
214
|
## React
|
|
161
215
|
|
|
162
216
|
```tsx
|
|
163
|
-
import { useCallback } from "react";
|
|
164
217
|
import { ReactorProvider, ReactorView, useReactor } from "@reactor-team/js-sdk";
|
|
165
218
|
|
|
166
219
|
function App() {
|
|
167
|
-
//
|
|
168
|
-
// this matters.
|
|
169
|
-
const jwt = useCallback(() => fetchToken(), []);
|
|
170
|
-
|
|
220
|
+
// A module-level fetchToken is stable across renders — see the note on
|
|
221
|
+
// ReactorProvider below for why this matters.
|
|
171
222
|
return (
|
|
172
|
-
<ReactorProvider modelName="my-model" jwtToken={
|
|
223
|
+
<ReactorProvider modelName="my-model" jwtToken={fetchToken}>
|
|
173
224
|
<Status />
|
|
174
225
|
</ReactorProvider>
|
|
175
226
|
);
|
|
@@ -225,8 +276,9 @@ you want to stay model-agnostic. See [Typed model SDKs](https://docs.reactor.inc
|
|
|
225
276
|
```bash
|
|
226
277
|
mise run install:js # npm install
|
|
227
278
|
mise run lint:js # eslint + tsc --noEmit
|
|
228
|
-
mise run build:js # tsup -> dist/, then copies reactor-wasm's pkg/ into dist/wasm
|
|
279
|
+
mise run build:js # tsup -> dist/, then copies reactor-wasm's pkg/ into dist/wasm, binary inlined
|
|
229
280
|
mise run test:js # vitest — pure-JS unit tests against a mocked ReactorClient, no wasm build needed
|
|
281
|
+
mise run test:js:consumer-tests # the packed SDK in real Vite/Next.js apps, in a real browser — see consumer-tests/README.md
|
|
230
282
|
```
|
|
231
283
|
|
|
232
284
|
`build:js` fails fast with a clear message if `crates/reactor-wasm/pkg`
|
package/dist/index.cjs
CHANGED
|
@@ -129,7 +129,7 @@ var ReactorError = class extends Error {
|
|
|
129
129
|
* compatibility — prefer `timestamp_ms`. */
|
|
130
130
|
timestamp;
|
|
131
131
|
constructor(message, options = {}) {
|
|
132
|
-
super(message);
|
|
132
|
+
super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
|
|
133
133
|
this.name = "ReactorError";
|
|
134
134
|
this.code = options.code ?? new.target.code;
|
|
135
135
|
this.recoverable = options.recoverable ?? false;
|
|
@@ -230,7 +230,10 @@ function toReactorError(cause) {
|
|
|
230
230
|
status: payload.status,
|
|
231
231
|
operation: payload.operation,
|
|
232
232
|
retry_after_ms: payload.retry_after_ms,
|
|
233
|
-
timestamp_ms: payload.timestamp_ms
|
|
233
|
+
timestamp_ms: payload.timestamp_ms,
|
|
234
|
+
// A thrown JS error (a failed wasm load, say) keeps its stack and its own
|
|
235
|
+
// `cause` reachable; reactor-core's plain payload objects have neither.
|
|
236
|
+
cause: cause instanceof Error ? cause : void 0
|
|
234
237
|
});
|
|
235
238
|
}
|
|
236
239
|
|
|
@@ -631,27 +634,27 @@ function loadReactorWasm() {
|
|
|
631
634
|
if (!modulePromise) {
|
|
632
635
|
modulePromise = importWasmModule().catch((cause) => {
|
|
633
636
|
modulePromise = null;
|
|
634
|
-
throw new Error(
|
|
635
|
-
"reactor-wasm failed to load. Run `mise run build:wasm` (or, from a published install, reinstall the package) and try again.",
|
|
636
|
-
{ cause }
|
|
637
|
-
);
|
|
637
|
+
throw new Error(`reactor-wasm failed to load: ${describeCause(cause)}`, { cause });
|
|
638
638
|
});
|
|
639
639
|
}
|
|
640
640
|
return modulePromise;
|
|
641
641
|
}
|
|
642
642
|
async function importWasmModule() {
|
|
643
|
-
const module2 = await import(
|
|
644
|
-
/* @vite-ignore */
|
|
645
|
-
"./wasm/reactor_wasm.js"
|
|
646
|
-
);
|
|
643
|
+
const module2 = await import("./wasm/reactor_wasm.js");
|
|
647
644
|
await module2.default();
|
|
648
645
|
return module2;
|
|
649
646
|
}
|
|
647
|
+
function describeCause(cause) {
|
|
648
|
+
if (cause instanceof Error) {
|
|
649
|
+
return cause.message ? `${cause.name}: ${cause.message}` : cause.name;
|
|
650
|
+
}
|
|
651
|
+
return String(cause);
|
|
652
|
+
}
|
|
650
653
|
|
|
651
654
|
// package.json
|
|
652
655
|
var package_default = {
|
|
653
656
|
name: "@reactor-team/js-sdk",
|
|
654
|
-
version: "3.
|
|
657
|
+
version: "3.2.0",
|
|
655
658
|
description: "Connect your JavaScript/TypeScript app to a live Reactor model in the browser.",
|
|
656
659
|
license: "Apache-2.0",
|
|
657
660
|
repository: {
|
|
@@ -711,6 +714,11 @@ var package_default = {
|
|
|
711
714
|
}
|
|
712
715
|
};
|
|
713
716
|
|
|
717
|
+
// src/internal/jwt-resolver.ts
|
|
718
|
+
async function resolveJwtSource(source, context) {
|
|
719
|
+
return typeof source === "function" ? source(context) : source;
|
|
720
|
+
}
|
|
721
|
+
|
|
714
722
|
// src/recording.ts
|
|
715
723
|
var RecordingError = class extends Error {
|
|
716
724
|
constructor(code, reason) {
|
|
@@ -730,15 +738,16 @@ async function fetchPlaylist(playlistUrl, options = {}) {
|
|
|
730
738
|
const startedPollingAt = Date.now();
|
|
731
739
|
const deadlineMs = hasDeadline ? Math.max(options.predictedReadyAtMs ?? startedPollingAt, startedPollingAt) + options.slackMs : void 0;
|
|
732
740
|
const maxRetries = typeof options.maxRetries === "number" ? options.maxRetries : void 0;
|
|
733
|
-
const init = {};
|
|
734
|
-
if (options.signal) {
|
|
735
|
-
init.signal = options.signal;
|
|
736
|
-
}
|
|
737
|
-
if (options.jwt) {
|
|
738
|
-
init.headers = { Authorization: `Bearer ${options.jwt}` };
|
|
739
|
-
}
|
|
740
741
|
let attempt = 0;
|
|
741
742
|
while (true) {
|
|
743
|
+
const init = {};
|
|
744
|
+
if (options.signal) {
|
|
745
|
+
init.signal = options.signal;
|
|
746
|
+
}
|
|
747
|
+
const jwt = await resolveManifestJwt(options);
|
|
748
|
+
if (jwt) {
|
|
749
|
+
init.headers = { Authorization: `Bearer ${jwt}` };
|
|
750
|
+
}
|
|
742
751
|
let response;
|
|
743
752
|
try {
|
|
744
753
|
response = await fetch(playlistUrl, init);
|
|
@@ -841,7 +850,10 @@ function absolutizeManifestUrls(manifestBody, playlistUrl) {
|
|
|
841
850
|
return out.join(eol);
|
|
842
851
|
}
|
|
843
852
|
async function downloadClipAsFile(clip, filename = "reactor-clip.mp4", options = {}) {
|
|
844
|
-
const playlistOptions = {
|
|
853
|
+
const playlistOptions = {
|
|
854
|
+
predictedReadyAtMs: clip.predictedReadyAtMs,
|
|
855
|
+
sessionId: clip.sessionId
|
|
856
|
+
};
|
|
845
857
|
if (options.signal) {
|
|
846
858
|
playlistOptions.signal = options.signal;
|
|
847
859
|
}
|
|
@@ -1079,6 +1091,27 @@ function parseRetryAfter(header, fallbackMs) {
|
|
|
1079
1091
|
}
|
|
1080
1092
|
return fallbackMs;
|
|
1081
1093
|
}
|
|
1094
|
+
async function resolveManifestJwt(options) {
|
|
1095
|
+
if (options.jwt === void 0) {
|
|
1096
|
+
return void 0;
|
|
1097
|
+
}
|
|
1098
|
+
const context = options.sessionId === void 0 ? {} : { sessionId: options.sessionId };
|
|
1099
|
+
return abortable(resolveJwtSource(options.jwt, context), options.signal);
|
|
1100
|
+
}
|
|
1101
|
+
function abortable(promise, signal) {
|
|
1102
|
+
if (!signal) {
|
|
1103
|
+
return promise;
|
|
1104
|
+
}
|
|
1105
|
+
return new Promise((resolve, reject) => {
|
|
1106
|
+
const onAbort = () => reject(new DOMException("Aborted", "AbortError"));
|
|
1107
|
+
if (signal.aborted) {
|
|
1108
|
+
onAbort();
|
|
1109
|
+
} else {
|
|
1110
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
1111
|
+
}
|
|
1112
|
+
void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
|
|
1113
|
+
});
|
|
1114
|
+
}
|
|
1082
1115
|
function sleep(ms, signal) {
|
|
1083
1116
|
return new Promise((resolve, reject) => {
|
|
1084
1117
|
if (signal?.aborted) {
|
|
@@ -2543,11 +2576,6 @@ function describeMediaError(error) {
|
|
|
2543
2576
|
return error?.message ? `${message} (${error.message})` : message;
|
|
2544
2577
|
}
|
|
2545
2578
|
|
|
2546
|
-
// src/internal/jwt-resolver.ts
|
|
2547
|
-
async function resolveJwtSource(source) {
|
|
2548
|
-
return typeof source === "function" ? source() : source;
|
|
2549
|
-
}
|
|
2550
|
-
|
|
2551
2579
|
// src/react/ClipPlayer.tsx
|
|
2552
2580
|
var import_jsx_runtime4 = require("react/jsx-runtime");
|
|
2553
2581
|
function ClipPlayer({
|
|
@@ -2597,21 +2625,17 @@ function ClipPlayer({
|
|
|
2597
2625
|
const setup = async () => {
|
|
2598
2626
|
try {
|
|
2599
2627
|
setPhase({ kind: "waiting" });
|
|
2600
|
-
const
|
|
2601
|
-
const fallback = storeRef.current?.getState().internal.reactor.getJwtResolver();
|
|
2602
|
-
const jwt = explicit ? await explicit() : fallback !== void 0 ? await resolveJwtSource(fallback) : void 0;
|
|
2603
|
-
if (cancelled) {
|
|
2604
|
-
return;
|
|
2605
|
-
}
|
|
2628
|
+
const source = () => getJwtRef.current ?? storeRef.current?.getState().internal.reactor.getJwtResolver();
|
|
2606
2629
|
const playlistOptions = {
|
|
2607
2630
|
predictedReadyAtMs: clip.predictedReadyAtMs,
|
|
2631
|
+
sessionId: clip.sessionId,
|
|
2608
2632
|
signal: abort.signal
|
|
2609
2633
|
};
|
|
2610
2634
|
if (slackMsRef.current !== void 0) {
|
|
2611
2635
|
playlistOptions.slackMs = slackMsRef.current;
|
|
2612
2636
|
}
|
|
2613
|
-
if (
|
|
2614
|
-
playlistOptions.jwt =
|
|
2637
|
+
if (source() !== void 0) {
|
|
2638
|
+
playlistOptions.jwt = (context) => resolveJwtSource(source() ?? "", context);
|
|
2615
2639
|
}
|
|
2616
2640
|
const body = await fetchPlaylist(clip.playlistUrl, playlistOptions);
|
|
2617
2641
|
if (cancelled) {
|
|
@@ -2757,15 +2781,13 @@ function useClipDownload(clip, options = {}) {
|
|
|
2757
2781
|
abortRef.current = abort;
|
|
2758
2782
|
setState({ kind: "downloading", fetched: 0, total: 0 });
|
|
2759
2783
|
try {
|
|
2760
|
-
const
|
|
2761
|
-
const fallback = storeRef.current?.getState().internal.reactor.getJwtResolver();
|
|
2762
|
-
const jwt = explicit ? await explicit() : fallback !== void 0 ? await resolveJwtSource(fallback) : void 0;
|
|
2784
|
+
const source = () => getJwtRef.current ?? storeRef.current?.getState().internal.reactor.getJwtResolver();
|
|
2763
2785
|
const downloadOptions = {
|
|
2764
2786
|
signal: abort.signal,
|
|
2765
2787
|
onProgress: ({ fetched, total }) => setState({ kind: "downloading", fetched, total })
|
|
2766
2788
|
};
|
|
2767
|
-
if (
|
|
2768
|
-
downloadOptions.jwt =
|
|
2789
|
+
if (source() !== void 0) {
|
|
2790
|
+
downloadOptions.jwt = (context) => resolveJwtSource(source() ?? "", context);
|
|
2769
2791
|
}
|
|
2770
2792
|
const blob = await downloadClipAsFile(clipRef.current, filenameRef.current, downloadOptions);
|
|
2771
2793
|
setState({ kind: "idle" });
|