@reactor-team/js-sdk 2.3.2 → 2.4.0

package/dist/index.d.mts

@@ -31,7 +31,22 @@ interface ConnectOptions {
     /** Maximum number of SDP polling attempts before giving up. Default: 6. */
     maxAttempts?: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+interface ConnectionStats {
+    /** ICE candidate-pair round-trip time in milliseconds */
+    rtt?: number;
+    /** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
+    candidateType?: string;
+    /** Estimated available outgoing bitrate in bits/second */
+    availableOutgoingBitrate?: number;
+    /** Received video frames per second */
+    framesPerSecond?: number;
+    /** Ratio of packets lost (0-1) */
+    packetLossRatio?: number;
+    /** Network jitter in seconds (from inbound-rtp) */
+    jitter?: number;
+    timestamp: number;
+}
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "streamChanged" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
@@ -114,6 +129,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -195,15 +211,30 @@ declare function WebcamStream({ className, style, videoConstraints, showWebcam,
  */
 declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
- * Hook for handling message subscriptions with proper React lifecycle management.
+ * Hook for receiving model application messages.
+ *
+ * Only fires for messages sent by the model via `get_ctx().send()`.
+ * Internal platform-level messages (e.g. capabilities) are NOT delivered here.
+ *
+ * @param handler - Callback invoked with each application message payload.
+ */
+declare function useReactorMessage(handler: (message: any) => void): void;
+/**
+ * Hook for receiving internal platform-level (runtime) messages.
  *
- * The handler receives the message payload and the scope it arrived on:
- *   - "application" for model-defined messages (via get_ctx().send())
- *   - "runtime" for platform-level messages (e.g., capabilities response)
+ * This is intended for advanced use cases that need access to the runtime
+ * control layer, such as capabilities negotiation. Model application messages
+ * sent via `get_ctx().send()` are NOT delivered through this hook — use
+ * {@link useReactorMessage} for those.
  *
- * @param handler - The message handler function (message, scope)
+ * @param handler - Callback invoked with each runtime message payload.
+ */
+declare function useReactorInternalMessage(handler: (message: any) => void): void;
+/**
+ * Hook that returns the current connection stats (RTT, etc.).
+ * Updates every ~2s while connected. Returns undefined when disconnected.
  */
-declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
+declare function useStats(): ConnectionStats | undefined;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -218,4 +249,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type ConnectOptions, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { ConflictError, type ConnectOptions, type ConnectionStats, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };

package/dist/index.d.ts

@@ -31,7 +31,22 @@ interface ConnectOptions {
     /** Maximum number of SDP polling attempts before giving up. Default: 6. */
     maxAttempts?: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+interface ConnectionStats {
+    /** ICE candidate-pair round-trip time in milliseconds */
+    rtt?: number;
+    /** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
+    candidateType?: string;
+    /** Estimated available outgoing bitrate in bits/second */
+    availableOutgoingBitrate?: number;
+    /** Received video frames per second */
+    framesPerSecond?: number;
+    /** Ratio of packets lost (0-1) */
+    packetLossRatio?: number;
+    /** Network jitter in seconds (from inbound-rtp) */
+    jitter?: number;
+    timestamp: number;
+}
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "streamChanged" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
@@ -114,6 +129,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -195,15 +211,30 @@ declare function WebcamStream({ className, style, videoConstraints, showWebcam,
  */
 declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
- * Hook for handling message subscriptions with proper React lifecycle management.
+ * Hook for receiving model application messages.
+ *
+ * Only fires for messages sent by the model via `get_ctx().send()`.
+ * Internal platform-level messages (e.g. capabilities) are NOT delivered here.
+ *
+ * @param handler - Callback invoked with each application message payload.
+ */
+declare function useReactorMessage(handler: (message: any) => void): void;
+/**
+ * Hook for receiving internal platform-level (runtime) messages.
  *
- * The handler receives the message payload and the scope it arrived on:
- *   - "application" for model-defined messages (via get_ctx().send())
- *   - "runtime" for platform-level messages (e.g., capabilities response)
+ * This is intended for advanced use cases that need access to the runtime
+ * control layer, such as capabilities negotiation. Model application messages
+ * sent via `get_ctx().send()` are NOT delivered through this hook — use
+ * {@link useReactorMessage} for those.
  *
- * @param handler - The message handler function (message, scope)
+ * @param handler - Callback invoked with each runtime message payload.
+ */
+declare function useReactorInternalMessage(handler: (message: any) => void): void;
+/**
+ * Hook that returns the current connection stats (RTT, etc.).
+ * Updates every ~2s while connected. Returns undefined when disconnected.
  */
-declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
+declare function useStats(): ConnectionStats | undefined;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -218,4 +249,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type ConnectOptions, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { ConflictError, type ConnectOptions, type ConnectionStats, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };

package/dist/index.js

@@ -88,8 +88,10 @@ __export(index_exports, {
   WebcamStream: () => WebcamStream,
   fetchInsecureJwtToken: () => fetchInsecureJwtToken,
   useReactor: () => useReactor,
+  useReactorInternalMessage: () => useReactorInternalMessage,
   useReactorMessage: () => useReactorMessage,
-  useReactorStore: () => useReactorStore
+  useReactorStore: () => useReactorStore,
+  useStats: () => useStats
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -249,6 +251,52 @@ function parseMessage(data) {
 function closePeerConnection(pc) {
   pc.close();
 }
+function extractConnectionStats(report) {
+  let rtt;
+  let availableOutgoingBitrate;
+  let localCandidateId;
+  let framesPerSecond;
+  let jitter;
+  let packetLossRatio;
+  report.forEach((stat) => {
+    if (stat.type === "candidate-pair" && stat.state === "succeeded") {
+      if (stat.currentRoundTripTime !== void 0) {
+        rtt = stat.currentRoundTripTime * 1e3;
+      }
+      if (stat.availableOutgoingBitrate !== void 0) {
+        availableOutgoingBitrate = stat.availableOutgoingBitrate;
+      }
+      localCandidateId = stat.localCandidateId;
+    }
+    if (stat.type === "inbound-rtp" && stat.kind === "video") {
+      if (stat.framesPerSecond !== void 0) {
+        framesPerSecond = stat.framesPerSecond;
+      }
+      if (stat.jitter !== void 0) {
+        jitter = stat.jitter;
+      }
+      if (stat.packetsReceived !== void 0 && stat.packetsLost !== void 0 && stat.packetsReceived + stat.packetsLost > 0) {
+        packetLossRatio = stat.packetsLost / (stat.packetsReceived + stat.packetsLost);
+      }
+    }
+  });
+  let candidateType;
+  if (localCandidateId) {
+    const localCandidate = report.get(localCandidateId);
+    if (localCandidate == null ? void 0 : localCandidate.candidateType) {
+      candidateType = localCandidate.candidateType;
+    }
+  }
+  return {
+    rtt,
+    candidateType,
+    availableOutgoingBitrate,
+    framesPerSecond,
+    packetLossRatio,
+    jitter,
+    timestamp: Date.now()
+  };
+}
 
 // src/core/CoordinatorClient.ts
 var INITIAL_BACKOFF_MS = 500;
@@ -624,6 +672,7 @@ var LocalCoordinatorClient = class extends CoordinatorClient {
 
 // src/core/GPUMachineClient.ts
 var PING_INTERVAL_MS = 5e3;
+var STATS_INTERVAL_MS = 2e3;
 var GPUMachineClient = class {
   constructor(config) {
     this.eventListeners = /* @__PURE__ */ new Map();
@@ -707,6 +756,7 @@ var GPUMachineClient = class {
   disconnect() {
     return __async(this, null, function* () {
       this.stopPing();
+      this.stopStatsPolling();
       if (this.publishedTrack) {
         yield this.unpublishTrack();
       }
@@ -863,6 +913,31 @@ var GPUMachineClient = class {
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Stats Polling (RTT)
+  // ─────────────────────────────────────────────────────────────────────────────
+  getStats() {
+    return this.stats;
+  }
+  startStatsPolling() {
+    this.stopStatsPolling();
+    this.statsInterval = setInterval(() => __async(this, null, function* () {
+      if (!this.peerConnection) return;
+      try {
+        const report = yield this.peerConnection.getStats();
+        this.stats = extractConnectionStats(report);
+        this.emit("statsUpdate", this.stats);
+      } catch (e) {
+      }
+    }), STATS_INTERVAL_MS);
+  }
+  stopStatsPolling() {
+    if (this.statsInterval !== void 0) {
+      clearInterval(this.statsInterval);
+      this.statsInterval = void 0;
+    }
+    this.stats = void 0;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Private Helpers
   // ─────────────────────────────────────────────────────────────────────────────
   setStatus(newStatus) {
@@ -881,6 +956,7 @@ var GPUMachineClient = class {
         switch (state) {
           case "connected":
             this.setStatus("connected");
+            this.startStatsPolling();
             break;
           case "disconnected":
           case "closed":
@@ -1170,7 +1246,11 @@ var Reactor = class {
   setupMachineClientHandlers() {
     if (!this.machineClient) return;
     this.machineClient.on("message", (message, scope) => {
-      this.emit("newMessage", message, scope);
+      if (scope === "application") {
+        this.emit("message", message);
+      } else if (scope === "runtime") {
+        this.emit("runtimeMessage", message);
+      }
     });
     this.machineClient.on("statusChanged", (status) => {
       switch (status) {
@@ -1197,6 +1277,9 @@ var Reactor = class {
         this.emit("streamChanged", track, stream);
       }
     );
+    this.machineClient.on("statsUpdate", (stats) => {
+      this.emit("statsUpdate", stats);
+    });
   }
   /**
    * Disconnects from the coordinator and the gpu machine.
@@ -1283,6 +1366,10 @@ var Reactor = class {
   getLastError() {
     return this.lastError;
   }
+  getStats() {
+    var _a;
+    return (_a = this.machineClient) == null ? void 0 : _a.getStats();
+  }
   /**
    * Create and store an error
    */
@@ -1371,10 +1458,10 @@ var createReactorStore = (initProps, publicState = defaultInitState) => {
       // actions
       onMessage: (handler) => {
         console.debug("[ReactorStore] Registering message handler");
-        get().internal.reactor.on("newMessage", handler);
+        get().internal.reactor.on("message", handler);
         return () => {
           console.debug("[ReactorStore] Cleaning up message handler");
-          get().internal.reactor.off("newMessage", handler);
+          get().internal.reactor.off("message", handler);
         };
       },
       sendCommand: (command, data, scope) => __async(null, null, function* () {
@@ -1588,21 +1675,45 @@ function useReactorMessage(handler) {
     handlerRef.current = handler;
   }, [handler]);
   (0, import_react4.useEffect)(() => {
-    console.debug("[useReactorMessage] Setting up message subscription");
-    const stableHandler = (message, scope) => {
-      console.debug("[useReactorMessage] Message received", {
-        message,
-        scope
-      });
-      handlerRef.current(message, scope);
+    const stableHandler = (message) => {
+      handlerRef.current(message);
+    };
+    reactor.on("message", stableHandler);
+    return () => {
+      reactor.off("message", stableHandler);
+    };
+  }, [reactor]);
+}
+function useReactorInternalMessage(handler) {
+  const reactor = useReactor((state) => state.internal.reactor);
+  const handlerRef = (0, import_react4.useRef)(handler);
+  (0, import_react4.useEffect)(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+  (0, import_react4.useEffect)(() => {
+    const stableHandler = (message) => {
+      handlerRef.current(message);
+    };
+    reactor.on("runtimeMessage", stableHandler);
+    return () => {
+      reactor.off("runtimeMessage", stableHandler);
+    };
+  }, [reactor]);
+}
+function useStats() {
+  const reactor = useReactor((state) => state.internal.reactor);
+  const [stats, setStats] = (0, import_react4.useState)(void 0);
+  (0, import_react4.useEffect)(() => {
+    const handler = (newStats) => {
+      setStats(newStats);
     };
-    reactor.on("newMessage", stableHandler);
-    console.debug("[useReactorMessage] Message handler registered");
+    reactor.on("statsUpdate", handler);
     return () => {
-      console.debug("[useReactorMessage] Cleaning up message subscription");
-      reactor.off("newMessage", stableHandler);
+      reactor.off("statsUpdate", handler);
+      setStats(void 0);
     };
   }, [reactor]);
+  return stats;
 }
 
 // src/react/ReactorView.tsx
@@ -1740,8 +1851,8 @@ function ReactorController({
     }, 5e3);
     return () => clearInterval(interval);
   }, [status, commands, requestCapabilities]);
-  useReactorMessage((message, scope) => {
-    if (scope === "runtime" && message && typeof message === "object" && message.type === "modelCapabilities" && message.data && "commands" in message.data) {
+  useReactorInternalMessage((message) => {
+    if (message && typeof message === "object" && message.type === "modelCapabilities" && message.data && "commands" in message.data) {
       const commandsMessage = message.data;
       setCommands(commandsMessage.commands);
       const initialValues = {};
@@ -2374,7 +2485,9 @@ function fetchInsecureJwtToken(_0) {
   WebcamStream,
   fetchInsecureJwtToken,
   useReactor,
+  useReactorInternalMessage,
   useReactorMessage,
-  useReactorStore
+  useReactorStore,
+  useStats
 });
 //# sourceMappingURL=index.js.map