@reactor-team/js-sdk 2.3.1 → 2.4.0

package/dist/index.d.mts

@@ -24,7 +24,29 @@ interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+/**
+ * Options for configuring the connect polling behavior.
+ */
+interface ConnectOptions {
+    /** Maximum number of SDP polling attempts before giving up. Default: 6. */
+    maxAttempts?: number;
+}
+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<{
@@ -70,14 +92,17 @@ declare class Reactor {
     unpublishTrack(): Promise<void>;
     /**
      * Public method for reconnecting to an existing session, that may have been interrupted but can be recovered.
+     * @param options Optional connect options (e.g. maxAttempts for SDP polling)
      */
-    reconnect(): Promise<void>;
+    reconnect(options?: ConnectOptions): Promise<void>;
     /**
      * Connects to the coordinator and waits for a GPU to be assigned.
      * Once a GPU is assigned, the Reactor will connect to the gpu machine via WebRTC.
      * If no authentication is provided and not in local mode, an error is thrown.
+     * @param jwtToken Optional JWT token for authentication
+     * @param options Optional connect options (e.g. maxAttempts for SDP polling)
      */
-    connect(jwtToken?: string): Promise<void>;
+    connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     /**
      * Sets up event handlers for the machine client.
      */
@@ -104,6 +129,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -121,11 +147,11 @@ interface ReactorState {
 }
 interface ReactorActions {
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
-    connect(jwtToken?: string): Promise<void>;
+    connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
     publishVideoStream(stream: MediaStream): Promise<void>;
     unpublishVideoStream(): Promise<void>;
-    reconnect(): Promise<void>;
+    reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
     reactor: Reactor;
@@ -137,12 +163,20 @@ interface ReactorInitializationProps extends Options {
     jwtToken?: string;
 }
 
-interface ReactorProviderProps extends ReactorInitializationProps {
+/**
+ * Options for the React provider's connect behavior.
+ * Extends the core ConnectOptions with autoConnect for the React lifecycle.
+ */
+interface ReactorConnectOptions extends ConnectOptions {
+    /** Whether to automatically connect when the provider mounts. Default: false. */
     autoConnect?: boolean;
+}
+interface ReactorProviderProps extends ReactorInitializationProps {
+    connectOptions?: ReactorConnectOptions;
     jwtToken?: string;
     children: ReactNode;
 }
-declare function ReactorProvider({ children, autoConnect, jwtToken, ...props }: ReactorProviderProps): react_jsx_runtime.JSX.Element;
+declare function ReactorProvider({ children, connectOptions, jwtToken, ...props }: ReactorProviderProps): react_jsx_runtime.JSX.Element;
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
@@ -177,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.
@@ -200,4 +249,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, 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

@@ -24,7 +24,29 @@ interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+/**
+ * Options for configuring the connect polling behavior.
+ */
+interface ConnectOptions {
+    /** Maximum number of SDP polling attempts before giving up. Default: 6. */
+    maxAttempts?: number;
+}
+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<{
@@ -70,14 +92,17 @@ declare class Reactor {
     unpublishTrack(): Promise<void>;
     /**
      * Public method for reconnecting to an existing session, that may have been interrupted but can be recovered.
+     * @param options Optional connect options (e.g. maxAttempts for SDP polling)
      */
-    reconnect(): Promise<void>;
+    reconnect(options?: ConnectOptions): Promise<void>;
     /**
      * Connects to the coordinator and waits for a GPU to be assigned.
      * Once a GPU is assigned, the Reactor will connect to the gpu machine via WebRTC.
      * If no authentication is provided and not in local mode, an error is thrown.
+     * @param jwtToken Optional JWT token for authentication
+     * @param options Optional connect options (e.g. maxAttempts for SDP polling)
      */
-    connect(jwtToken?: string): Promise<void>;
+    connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     /**
      * Sets up event handlers for the machine client.
      */
@@ -104,6 +129,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -121,11 +147,11 @@ interface ReactorState {
 }
 interface ReactorActions {
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
-    connect(jwtToken?: string): Promise<void>;
+    connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
     publishVideoStream(stream: MediaStream): Promise<void>;
     unpublishVideoStream(): Promise<void>;
-    reconnect(): Promise<void>;
+    reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
     reactor: Reactor;
@@ -137,12 +163,20 @@ interface ReactorInitializationProps extends Options {
     jwtToken?: string;
 }
 
-interface ReactorProviderProps extends ReactorInitializationProps {
+/**
+ * Options for the React provider's connect behavior.
+ * Extends the core ConnectOptions with autoConnect for the React lifecycle.
+ */
+interface ReactorConnectOptions extends ConnectOptions {
+    /** Whether to automatically connect when the provider mounts. Default: false. */
     autoConnect?: boolean;
+}
+interface ReactorProviderProps extends ReactorInitializationProps {
+    connectOptions?: ReactorConnectOptions;
     jwtToken?: string;
     children: ReactNode;
 }
-declare function ReactorProvider({ children, autoConnect, jwtToken, ...props }: ReactorProviderProps): react_jsx_runtime.JSX.Element;
+declare function ReactorProvider({ children, connectOptions, jwtToken, ...props }: ReactorProviderProps): react_jsx_runtime.JSX.Element;
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
@@ -177,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.
@@ -200,4 +249,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, 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 };