@reactor-team/js-sdk 2.8.1 → 2.9.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/dist/index.d.mts CHANGED
@@ -86,6 +86,22 @@ type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
86
86
  type SessionResponse = z.infer<typeof SessionResponseSchema>;
87
87
  type Capabilities = z.infer<typeof CapabilitiesSchema>;
88
88
 
89
+ /**
90
+ * Reference to an uploaded file, returned by {@link Reactor.uploadFile}.
91
+ *
92
+ * Pass a `FileRef` as a value in {@link Reactor.sendCommand} and it will
93
+ * be serialized into the `uploads` section of the wire envelope, separate
94
+ * from scalar arguments. The runtime resolves each reference to bytes
95
+ * before dispatching the event to the model handler.
96
+ */
97
+ declare class FileRef {
98
+ readonly uploadId: string;
99
+ readonly name: string;
100
+ readonly mimeType: string;
101
+ readonly size: number;
102
+ constructor(uploadId: string, name: string, mimeType: string, size: number);
103
+ }
104
+
89
105
  type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
90
106
  /**
91
107
  * The message scope identifies the envelope layer a data channel message belongs to.
@@ -163,6 +179,7 @@ declare const OptionsSchema: z.ZodObject<{
163
179
  local: z.ZodDefault<z.ZodBoolean>;
164
180
  }, z.core.$strip>;
165
181
  type Options = z.input<typeof OptionsSchema>;
182
+
166
183
  type EventHandler = (...args: any[]) => void;
167
184
  declare class Reactor {
168
185
  private coordinatorClient;
@@ -186,8 +203,27 @@ declare class Reactor {
186
203
  emit(event: ReactorEvent, ...args: any[]): void;
187
204
  /**
188
205
  * Sends a command to the model via the data channel.
206
+ *
207
+ * When any value in `data` is a {@link FileRef}, it is automatically
208
+ * extracted and serialized into a separate `uploads` section on the
209
+ * wire, keyed by the parameter name. Scalar values remain in `data`.
189
210
  */
190
211
  sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
212
+ /**
213
+ * Uploads a file to the session's object store and returns a {@link FileRef}.
214
+ *
215
+ * Flow:
216
+ * 1. POST /sessions/{id}/uploads → allocate presigned PUT URL
217
+ * 2. PUT file bytes to the presigned URL
218
+ * 3. Send `fileUploaded` notification on the runtime data channel
219
+ * (fires `@file_uploaded` on the model if registered)
220
+ * 4. Return a `FileRef` to pass into {@link sendCommand}
221
+ *
222
+ * Works identically in local and production modes.
223
+ */
224
+ uploadFile(file: File | Blob, options?: {
225
+ name?: string;
226
+ }): Promise<FileRef>;
191
227
  /**
192
228
  * Publishes a MediaStreamTrack to a named sendonly track.
193
229
  * The transceiver is already set up from capabilities — this just
@@ -249,6 +285,9 @@ interface ReactorActions {
249
285
  publish(name: string, track: MediaStreamTrack): Promise<void>;
250
286
  unpublish(name: string): Promise<void>;
251
287
  reconnect(options?: ConnectOptions): Promise<void>;
288
+ uploadFile(file: File | Blob, options?: {
289
+ name?: string;
290
+ }): Promise<FileRef>;
252
291
  }
253
292
  interface ReactorInternalState {
254
293
  reactor: Reactor;
@@ -354,4 +393,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
354
393
  */
355
394
  declare function useStats(): ConnectionStats | undefined;
356
395
 
357
- export { AbortError, type Capabilities, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, type MessageScope, type Options, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, type SessionResponse, type TrackCapability, WebcamStream, type WebcamStreamProps, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
396
+ export { AbortError, type Capabilities, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, FileRef, type MessageScope, type Options, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, type SessionResponse, type TrackCapability, WebcamStream, type WebcamStreamProps, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
package/dist/index.d.ts CHANGED
@@ -86,6 +86,22 @@ type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
86
86
  type SessionResponse = z.infer<typeof SessionResponseSchema>;
87
87
  type Capabilities = z.infer<typeof CapabilitiesSchema>;
88
88
 
89
+ /**
90
+ * Reference to an uploaded file, returned by {@link Reactor.uploadFile}.
91
+ *
92
+ * Pass a `FileRef` as a value in {@link Reactor.sendCommand} and it will
93
+ * be serialized into the `uploads` section of the wire envelope, separate
94
+ * from scalar arguments. The runtime resolves each reference to bytes
95
+ * before dispatching the event to the model handler.
96
+ */
97
+ declare class FileRef {
98
+ readonly uploadId: string;
99
+ readonly name: string;
100
+ readonly mimeType: string;
101
+ readonly size: number;
102
+ constructor(uploadId: string, name: string, mimeType: string, size: number);
103
+ }
104
+
89
105
  type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
90
106
  /**
91
107
  * The message scope identifies the envelope layer a data channel message belongs to.
@@ -163,6 +179,7 @@ declare const OptionsSchema: z.ZodObject<{
163
179
  local: z.ZodDefault<z.ZodBoolean>;
164
180
  }, z.core.$strip>;
165
181
  type Options = z.input<typeof OptionsSchema>;
182
+
166
183
  type EventHandler = (...args: any[]) => void;
167
184
  declare class Reactor {
168
185
  private coordinatorClient;
@@ -186,8 +203,27 @@ declare class Reactor {
186
203
  emit(event: ReactorEvent, ...args: any[]): void;
187
204
  /**
188
205
  * Sends a command to the model via the data channel.
206
+ *
207
+ * When any value in `data` is a {@link FileRef}, it is automatically
208
+ * extracted and serialized into a separate `uploads` section on the
209
+ * wire, keyed by the parameter name. Scalar values remain in `data`.
189
210
  */
190
211
  sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
212
+ /**
213
+ * Uploads a file to the session's object store and returns a {@link FileRef}.
214
+ *
215
+ * Flow:
216
+ * 1. POST /sessions/{id}/uploads → allocate presigned PUT URL
217
+ * 2. PUT file bytes to the presigned URL
218
+ * 3. Send `fileUploaded` notification on the runtime data channel
219
+ * (fires `@file_uploaded` on the model if registered)
220
+ * 4. Return a `FileRef` to pass into {@link sendCommand}
221
+ *
222
+ * Works identically in local and production modes.
223
+ */
224
+ uploadFile(file: File | Blob, options?: {
225
+ name?: string;
226
+ }): Promise<FileRef>;
191
227
  /**
192
228
  * Publishes a MediaStreamTrack to a named sendonly track.
193
229
  * The transceiver is already set up from capabilities — this just
@@ -249,6 +285,9 @@ interface ReactorActions {
249
285
  publish(name: string, track: MediaStreamTrack): Promise<void>;
250
286
  unpublish(name: string): Promise<void>;
251
287
  reconnect(options?: ConnectOptions): Promise<void>;
288
+ uploadFile(file: File | Blob, options?: {
289
+ name?: string;
290
+ }): Promise<FileRef>;
252
291
  }
253
292
  interface ReactorInternalState {
254
293
  reactor: Reactor;
@@ -354,4 +393,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
354
393
  */
355
394
  declare function useStats(): ConnectionStats | undefined;
356
395
 
357
- export { AbortError, type Capabilities, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, type MessageScope, type Options, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, type SessionResponse, type TrackCapability, WebcamStream, type WebcamStreamProps, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
396
+ export { AbortError, type Capabilities, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, FileRef, type MessageScope, type Options, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, type SessionResponse, type TrackCapability, WebcamStream, type WebcamStreamProps, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
package/dist/index.js CHANGED
@@ -82,6 +82,7 @@ __export(index_exports, {
82
82
  AbortError: () => AbortError,
83
83
  ConflictError: () => ConflictError,
84
84
  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
85
+ FileRef: () => FileRef,
85
86
  Reactor: () => Reactor,
86
87
  ReactorController: () => ReactorController,
87
88
  ReactorProvider: () => ReactorProvider,
@@ -96,6 +97,18 @@ __export(index_exports, {
96
97
  });
97
98
  module.exports = __toCommonJS(index_exports);
98
99
 
100
+ // src/core/FileRef.ts
101
+ var FileRef = class {
102
+ constructor(uploadId, name, mimeType, size) {
103
+ this.uploadId = uploadId;
104
+ this.name = name;
105
+ this.mimeType = mimeType;
106
+ this.size = size;
107
+ /** @internal Marker so sendCommand can detect FileRef values. */
108
+ this.__isFileRef = true;
109
+ }
110
+ };
111
+
99
112
  // src/types.ts
100
113
  var ConflictError = class extends Error {
101
114
  constructor(message) {
@@ -117,7 +130,7 @@ var import_zod = require("zod");
117
130
  // package.json
118
131
  var package_default = {
119
132
  name: "@reactor-team/js-sdk",
120
- version: "2.8.1",
133
+ version: "2.9.0",
121
134
  description: "Reactor JavaScript frontend SDK",
122
135
  main: "dist/index.js",
123
136
  module: "dist/index.mjs",
@@ -156,7 +169,7 @@ var package_default = {
156
169
  license: "MIT",
157
170
  repository: {
158
171
  type: "git",
159
- url: "https://github.com/reactor-team/js-sdk"
172
+ url: "https://github.com/reactor-team/js-sdk.git"
160
173
  },
161
174
  packageManager: "pnpm@10.12.1",
162
175
  devDependencies: {
@@ -245,6 +258,16 @@ var SessionResponseSchema = CreateSessionResponseSchema.extend({
245
258
  var TerminateSessionRequestSchema = import_zod.z.object({
246
259
  reason: import_zod.z.string().optional()
247
260
  });
261
+ var CreateUploadRequestSchema = import_zod.z.object({
262
+ name: import_zod.z.string(),
263
+ size: import_zod.z.number().int().positive(),
264
+ mime_type: import_zod.z.string()
265
+ });
266
+ var CreateUploadResponseSchema = import_zod.z.object({
267
+ presigned_id: import_zod.z.string(),
268
+ presigned_url: import_zod.z.string(),
269
+ path: import_zod.z.string()
270
+ });
248
271
  var IceServerCredentialsSchema = import_zod.z.object({
249
272
  username: import_zod.z.string(),
250
273
  password: import_zod.z.string()
@@ -581,6 +604,40 @@ var CoordinatorClient = class {
581
604
  );
582
605
  });
583
606
  }
607
+ /**
608
+ * Allocates an upload slot for a file.
609
+ * Returns a presigned PUT URL the caller can use to upload the file
610
+ * directly to the object store (production) or local runtime (local dev).
611
+ */
612
+ createUpload(sessionId, request) {
613
+ return __async(this, null, function* () {
614
+ console.debug("[CoordinatorClient] Creating upload slot...", {
615
+ sessionId,
616
+ name: request.name,
617
+ size: request.size
618
+ });
619
+ const response = yield fetch(
620
+ `${this.baseUrl}/sessions/${sessionId}/uploads`,
621
+ {
622
+ method: "POST",
623
+ headers: __spreadProps(__spreadValues({}, this.getHeaders()), {
624
+ "Content-Type": "application/json"
625
+ }),
626
+ body: JSON.stringify(request),
627
+ signal: this.signal
628
+ }
629
+ );
630
+ yield this.checkVersionMismatch(response);
631
+ if (!response.ok) {
632
+ const errorText = yield response.text();
633
+ throw new Error(
634
+ `Failed to create upload slot: ${response.status} ${errorText}`
635
+ );
636
+ }
637
+ const data = yield response.json();
638
+ return CreateUploadResponseSchema.parse(data);
639
+ });
640
+ }
584
641
  getSessionId() {
585
642
  return this.currentSessionId;
586
643
  }
@@ -749,12 +806,15 @@ function waitForIceGathering(pc, timeoutMs = 5e3) {
749
806
  }, timeoutMs);
750
807
  });
751
808
  }
752
- function sendMessage(channel, command, data, scope = "application", maxBytes = DEFAULT_MAX_MESSAGE_BYTES) {
809
+ function sendMessage(channel, command, data, scope = "application", maxBytes = DEFAULT_MAX_MESSAGE_BYTES, uploads) {
753
810
  if (channel.readyState !== "open") {
754
811
  throw new Error(`Data channel not open: ${channel.readyState}`);
755
812
  }
756
813
  const jsonData = typeof data === "string" ? JSON.parse(data) : data;
757
814
  const inner = { type: command, data: jsonData };
815
+ if (uploads && Object.keys(uploads).length > 0) {
816
+ inner.uploads = uploads;
817
+ }
758
818
  const payload = { scope, data: inner };
759
819
  const serialized = JSON.stringify(payload);
760
820
  const byteLength = new TextEncoder().encode(serialized).byteLength;
@@ -1163,7 +1223,7 @@ var WebRTCTransportClient = class {
1163
1223
  var _a, _b, _c;
1164
1224
  return (_c = (_b = (_a = this.peerConnection) == null ? void 0 : _a.sctp) == null ? void 0 : _b.maxMessageSize) != null ? _c : void 0;
1165
1225
  }
1166
- sendCommand(command, data, scope = "application") {
1226
+ sendCommand(command, data, scope = "application", uploads) {
1167
1227
  if (!this.dataChannel) {
1168
1228
  throw new Error("[WebRTCTransport] Data channel not available");
1169
1229
  }
@@ -1173,7 +1233,8 @@ var WebRTCTransportClient = class {
1173
1233
  command,
1174
1234
  data,
1175
1235
  scope,
1176
- this.maxMessageBytes
1236
+ this.maxMessageBytes,
1237
+ uploads
1177
1238
  );
1178
1239
  } catch (error) {
1179
1240
  console.warn("[WebRTCTransport] Failed to send message:", error);
@@ -1449,6 +1510,10 @@ var Reactor = class {
1449
1510
  }
1450
1511
  /**
1451
1512
  * Sends a command to the model via the data channel.
1513
+ *
1514
+ * When any value in `data` is a {@link FileRef}, it is automatically
1515
+ * extracted and serialized into a separate `uploads` section on the
1516
+ * wire, keyed by the parameter name. Scalar values remain in `data`.
1452
1517
  */
1453
1518
  sendCommand(command, data, scope = "application") {
1454
1519
  return __async(this, null, function* () {
@@ -1459,7 +1524,28 @@ var Reactor = class {
1459
1524
  return;
1460
1525
  }
1461
1526
  try {
1462
- (_a = this.transportClient) == null ? void 0 : _a.sendCommand(command, data, scope);
1527
+ let uploads;
1528
+ if (data && typeof data === "object" && !Array.isArray(data)) {
1529
+ const scalarData = {};
1530
+ const extractedUploads = {};
1531
+ for (const [key, value] of Object.entries(data)) {
1532
+ if (value instanceof FileRef) {
1533
+ extractedUploads[key] = {
1534
+ upload_id: value.uploadId,
1535
+ name: value.name,
1536
+ mime_type: value.mimeType,
1537
+ size: value.size
1538
+ };
1539
+ } else {
1540
+ scalarData[key] = value;
1541
+ }
1542
+ }
1543
+ if (Object.keys(extractedUploads).length > 0) {
1544
+ uploads = extractedUploads;
1545
+ data = scalarData;
1546
+ }
1547
+ }
1548
+ (_a = this.transportClient) == null ? void 0 : _a.sendCommand(command, data, scope, uploads);
1463
1549
  } catch (error) {
1464
1550
  console.error("[Reactor] Failed to send message:", error);
1465
1551
  this.createError(
@@ -1471,6 +1557,71 @@ var Reactor = class {
1471
1557
  }
1472
1558
  });
1473
1559
  }
1560
+ /**
1561
+ * Uploads a file to the session's object store and returns a {@link FileRef}.
1562
+ *
1563
+ * Flow:
1564
+ * 1. POST /sessions/{id}/uploads → allocate presigned PUT URL
1565
+ * 2. PUT file bytes to the presigned URL
1566
+ * 3. Send `fileUploaded` notification on the runtime data channel
1567
+ * (fires `@file_uploaded` on the model if registered)
1568
+ * 4. Return a `FileRef` to pass into {@link sendCommand}
1569
+ *
1570
+ * Works identically in local and production modes.
1571
+ */
1572
+ uploadFile(file, options) {
1573
+ return __async(this, null, function* () {
1574
+ var _a;
1575
+ if (this.status !== "ready") {
1576
+ throw new Error(
1577
+ `Cannot upload file, status is "${this.status}". Must be "ready".`
1578
+ );
1579
+ }
1580
+ if (!this.coordinatorClient || !this.sessionId) {
1581
+ throw new Error("No active session. Call connect() first.");
1582
+ }
1583
+ const name = (_a = options == null ? void 0 : options.name) != null ? _a : file instanceof File ? file.name : "upload";
1584
+ const mimeType = file.type || "application/octet-stream";
1585
+ const size = file.size;
1586
+ if (size <= 0) {
1587
+ throw new Error("File is empty");
1588
+ }
1589
+ const slot = yield this.coordinatorClient.createUpload(this.sessionId, {
1590
+ name,
1591
+ size,
1592
+ mime_type: mimeType
1593
+ });
1594
+ const putResponse = yield fetch(slot.presigned_url, {
1595
+ method: "PUT",
1596
+ body: file,
1597
+ headers: {
1598
+ "Content-Length": String(size)
1599
+ }
1600
+ });
1601
+ if (!putResponse.ok) {
1602
+ throw new Error(
1603
+ `File upload failed: ${putResponse.status} ${putResponse.statusText}`
1604
+ );
1605
+ }
1606
+ yield this.sendCommand(
1607
+ "fileUploaded",
1608
+ {
1609
+ upload_id: slot.presigned_id,
1610
+ name,
1611
+ mime_type: mimeType,
1612
+ size
1613
+ },
1614
+ "runtime"
1615
+ );
1616
+ console.debug("[Reactor] File uploaded:", {
1617
+ uploadId: slot.presigned_id,
1618
+ name,
1619
+ mimeType,
1620
+ size
1621
+ });
1622
+ return new FileRef(slot.presigned_id, name, mimeType, size);
1623
+ });
1624
+ }
1474
1625
  /**
1475
1626
  * Publishes a MediaStreamTrack to a named sendonly track.
1476
1627
  * The transceiver is already set up from capabilities — this just
@@ -1977,6 +2128,17 @@ var createReactorStore = (initProps, publicState = defaultInitState) => {
1977
2128
  console.error("[ReactorStore] Failed to reconnect:", error);
1978
2129
  throw error;
1979
2130
  }
2131
+ }),
2132
+ uploadFile: (file, options) => __async(null, null, function* () {
2133
+ console.debug("[ReactorStore] Uploading file");
2134
+ try {
2135
+ const result = yield get().internal.reactor.uploadFile(file, options);
2136
+ console.debug("[ReactorStore] File uploaded successfully", result);
2137
+ return result;
2138
+ } catch (error) {
2139
+ console.error("[ReactorStore] Failed to upload file:", error);
2140
+ throw error;
2141
+ }
1980
2142
  })
1981
2143
  });
1982
2144
  });
@@ -2920,6 +3082,7 @@ function WebcamStream({
2920
3082
  AbortError,
2921
3083
  ConflictError,
2922
3084
  DEFAULT_BASE_URL,
3085
+ FileRef,
2923
3086
  Reactor,
2924
3087
  ReactorController,
2925
3088
  ReactorProvider,