@reactor-team/js-sdk 2.2.2 → 2.3.2

package/dist/index.d.mts

@@ -3,6 +3,12 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
 type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
+/**
+ * The message scope identifies the envelope layer a data channel message belongs to.
+ * - "application": model-defined commands (client->runtime) and model-emitted payloads (runtime->client).
+ * - "runtime": platform-level control messages (e.g., capabilities exchange).
+ */
+type MessageScope = "application" | "runtime";
 interface ReactorError {
     code: string;
     message: string;
@@ -18,6 +24,13 @@ interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
 }
+/**
+ * Options for configuring the connect polling behavior.
+ */
+interface ConnectOptions {
+    /** Maximum number of SDP polling attempts before giving up. Default: 6. */
+    maxAttempts?: number;
+}
 type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
@@ -45,11 +58,14 @@ declare class Reactor {
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
      * Public method to send a message to the machine.
-     * Automatically wraps the message in an application message.
-     * @param message The message to send to the machine.
+     * Wraps the message in the specified channel envelope (defaults to "application").
+     * @param command The command name to send.
+     * @param data The command payload.
+     * @param scope The envelope scope – "application" (default) for model commands,
+     *              "runtime" for platform-level messages (e.g. requestCapabilities).
      * @throws Error if not in ready state
      */
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
      * Public method to publish a track to the machine.
      * @param track The track to send to the machine.
@@ -61,14 +77,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.
      */
@@ -111,12 +130,12 @@ interface ReactorState {
     jwtToken?: string;
 }
 interface ReactorActions {
-    sendCommand(command: string, data: any): Promise<void>;
-    connect(jwtToken?: string): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): 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;
@@ -128,12 +147,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 {
@@ -170,9 +197,13 @@ declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
  * Hook for handling message subscriptions with proper React lifecycle management.
  *
- * @param handler - The message handler function
+ * 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)
+ *
+ * @param handler - The message handler function (message, scope)
  */
-declare function useReactorMessage(handler: (message: any) => void): void;
+declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -187,4 +218,4 @@ declare function useReactorMessage(handler: (message: any) => void): void;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, 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 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 };

package/dist/index.d.ts

@@ -3,6 +3,12 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
 type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
+/**
+ * The message scope identifies the envelope layer a data channel message belongs to.
+ * - "application": model-defined commands (client->runtime) and model-emitted payloads (runtime->client).
+ * - "runtime": platform-level control messages (e.g., capabilities exchange).
+ */
+type MessageScope = "application" | "runtime";
 interface ReactorError {
     code: string;
     message: string;
@@ -18,6 +24,13 @@ interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
 }
+/**
+ * Options for configuring the connect polling behavior.
+ */
+interface ConnectOptions {
+    /** Maximum number of SDP polling attempts before giving up. Default: 6. */
+    maxAttempts?: number;
+}
 type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
@@ -45,11 +58,14 @@ declare class Reactor {
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
      * Public method to send a message to the machine.
-     * Automatically wraps the message in an application message.
-     * @param message The message to send to the machine.
+     * Wraps the message in the specified channel envelope (defaults to "application").
+     * @param command The command name to send.
+     * @param data The command payload.
+     * @param scope The envelope scope – "application" (default) for model commands,
+     *              "runtime" for platform-level messages (e.g. requestCapabilities).
      * @throws Error if not in ready state
      */
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
      * Public method to publish a track to the machine.
      * @param track The track to send to the machine.
@@ -61,14 +77,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.
      */
@@ -111,12 +130,12 @@ interface ReactorState {
     jwtToken?: string;
 }
 interface ReactorActions {
-    sendCommand(command: string, data: any): Promise<void>;
-    connect(jwtToken?: string): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): 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;
@@ -128,12 +147,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 {
@@ -170,9 +197,13 @@ declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
  * Hook for handling message subscriptions with proper React lifecycle management.
  *
- * @param handler - The message handler function
+ * 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)
+ *
+ * @param handler - The message handler function (message, scope)
  */
-declare function useReactorMessage(handler: (message: any) => void): void;
+declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -187,4 +218,4 @@ declare function useReactorMessage(handler: (message: any) => void): void;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, 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 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 };