@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 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: () => fetchToken(), // or a plain string; omit for an unauthenticated local runtime
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: await fetchToken() });
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={() => fetchToken()} />
123
- <ClipDownloadButton clip={clip} getJwt={() => fetchToken()} filename="clip.mp4" />
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
- // Stable across renders — see the note on ReactorProvider below for why
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={jwt}>
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.1.0",
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 = { predictedReadyAtMs: clip.predictedReadyAtMs };
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 explicit = getJwtRef.current;
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 (jwt !== void 0) {
2614
- playlistOptions.jwt = 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 explicit = getJwtRef.current;
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 (jwt !== void 0) {
2768
- downloadOptions.jwt = 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" });