@reactor-team/js-sdk 2.4.0 → 2.5.1

package/dist/index.d.mts

@@ -9,6 +9,81 @@ type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
  * - "runtime": platform-level control messages (e.g., capabilities exchange).
  */
 type MessageScope = "application" | "runtime";
+/**
+ * Describes a single named media track for SDP negotiation.
+ *
+ * Track names must exactly match the class attribute names defined on the
+ * model's Python code.  The name is encoded as the SDP MID so both sides
+ * can route media by name rather than by positional index.
+ *
+ * Use the {@link video} and {@link audio} helper functions to create
+ * instances instead of constructing this interface directly.
+ */
+interface TrackConfig {
+    name: string;
+    kind: "audio" | "video";
+}
+/**
+ * Optional configuration for a video track (reserved for future use).
+ */
+interface VideoTrackOptions {
+    /** Maximum framerate constraint for the video track. */
+    maxFramerate?: number;
+}
+/**
+ * Optional configuration for an audio track (reserved for future use).
+ */
+interface AudioTrackOptions {
+    /** Sample rate constraint for the audio track. */
+    sampleRate?: number;
+}
+/**
+ * Creates a **video** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** video frames **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** video frames **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `maxFramerate`).
+ *
+ * When no `receive` array is provided to the Reactor constructor, a single
+ * `video("main_video")` track is used by default.
+ *
+ * @example
+ * ```ts
+ * receive: [video("main_video")]          // receive video from the model
+ * send:    [video("webcam")]              // send webcam video to the model
+ * ```
+ */
+declare function video(name: string, _options?: VideoTrackOptions): TrackConfig;
+/**
+ * Creates an **audio** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** audio samples **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** audio samples **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `sampleRate`).
+ *
+ * @example
+ * ```ts
+ * receive: [audio("main_audio")]          // receive audio from the model
+ * send:    [audio("mic")]                 // send microphone audio to the model
+ * ```
+ */
+declare function audio(name: string, _options?: AudioTrackOptions): TrackConfig;
 interface ReactorError {
     code: string;
     message: string;
@@ -20,6 +95,11 @@ interface ReactorError {
 declare class ConflictError extends Error {
     constructor(message: string);
 }
+declare class AbortError extends Error {
+    constructor(message: string);
+}
+/** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
+declare function isAbortError(error: unknown): boolean;
 interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
@@ -46,13 +126,27 @@ interface ConnectionStats {
     jitter?: number;
     timestamp: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "streamChanged" | "error" | "sessionExpirationChanged" | "statsUpdate";
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
     coordinatorUrl: z.ZodDefault<z.ZodString>;
     modelName: z.ZodString;
     local: z.ZodDefault<z.ZodBoolean>;
+    receive: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
+    send: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Options = z.input<typeof OptionsSchema>;
 type EventHandler = (...args: any[]) => void;
@@ -65,6 +159,10 @@ declare class Reactor {
     private model;
     private sessionExpiration?;
     private local;
+    /** Tracks the client RECEIVES from the model (model → client). */
+    private receive;
+    /** Tracks the client SENDS to the model (client → model). */
+    private send;
     private sessionId?;
     constructor(options: Options);
     private eventListeners;
@@ -72,24 +170,26 @@ declare class Reactor {
     off(event: ReactorEvent, handler: EventHandler): void;
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
-     * Public method to send a message to the machine.
-     * Wraps the message in the specified channel envelope (defaults to "application").
-     * @param command The command name to send.
+     * Sends a command to the model via the data channel.
+     *
+     * @param command The command name.
      * @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
+     * @param scope "application" (default) for model commands, "runtime" for platform messages.
      */
     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.
+     * Publishes a MediaStreamTrack to a named send track.
+     *
+     * @param name The declared send track name (e.g. "webcam").
+     * @param track The MediaStreamTrack to publish.
      */
-    publishTrack(track: MediaStreamTrack): Promise<void>;
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
     /**
-     * Public method to unpublish the currently published track.
+     * Unpublishes the track with the given name.
+     *
+     * @param name The declared send track name to unpublish.
      */
-    unpublishTrack(): Promise<void>;
+    unpublishTrack(name: string): 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)
@@ -105,6 +205,11 @@ declare class Reactor {
     connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     /**
      * Sets up event handlers for the machine client.
+     *
+     * Each handler captures the client reference at registration time and
+     * ignores events if this.machineClient has since changed (e.g. after
+     * disconnect + reconnect), preventing stale WebRTC teardown events from
+     * interfering with a new connection.
      */
     private setupMachineClientHandlers;
     /**
@@ -138,19 +243,24 @@ declare class Reactor {
 
 interface ReactorState {
     status: ReactorStatus;
-    videoTrack: MediaStreamTrack | null;
+    /**
+     * Media tracks received from the model, keyed by track name.
+     *
+     * Each entry maps a declared **receive** track name (e.g. `"main_video"`,
+     * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
+     */
+    tracks: Record<string, MediaStreamTrack>;
     lastError?: ReactorError;
     sessionId?: string;
     sessionExpiration?: number;
-    insecureApiKey?: string;
     jwtToken?: string;
 }
 interface ReactorActions {
     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>;
+    publish(name: string, track: MediaStreamTrack): Promise<void>;
+    unpublish(name: string): Promise<void>;
     reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
@@ -180,13 +290,26 @@ declare function ReactorProvider({ children, connectOptions, jwtToken, ...props
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
+    /**
+     * The name of the **receive** track to render.
+     * Must match a track name declared in the `receive` array (model → client).
+     * Defaults to `"main_video"`.
+     */
+    track?: string;
+    /**
+     * Optional name of a **receive** audio track to play alongside the video
+     * (e.g. `"main_audio"`).  The audio is mixed into the same `<video>` element.
+     */
+    audioTrack?: string;
     width?: number;
     height?: number;
     className?: string;
     style?: React.CSSProperties;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
+    /** Controls whether inbound audio plays. Default true (muted) to satisfy browser autoplay policies. */
+    muted?: boolean;
 }
-declare function ReactorView({ width, height, className, style, videoObjectFit, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
+declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
 
 interface ReactorControllerProps {
     className?: string;
@@ -194,14 +317,19 @@ interface ReactorControllerProps {
 }
 declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
 
-interface Props {
+interface WebcamStreamProps {
+    /**
+     * The name of the **send** track to publish the webcam to.
+     * Must match a track name declared in the `send` array (client → model).
+     */
+    track: string;
     className?: string;
     style?: React.CSSProperties;
     videoConstraints?: MediaTrackConstraints;
     showWebcam?: boolean;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
 }
-declare function WebcamStream({ className, style, videoConstraints, showWebcam, videoObjectFit, }: Props): react_jsx_runtime.JSX.Element;
+declare function WebcamStream({ track, className, style, videoConstraints, showWebcam, videoObjectFit, }: WebcamStreamProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Generic hook for accessing selected parts of the Reactor store.
@@ -249,4 +377,4 @@ declare function useStats(): ConnectionStats | undefined;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-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 };
+export { AbortError, type AudioTrackOptions, 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, type TrackConfig, type VideoTrackOptions, WebcamStream, type WebcamStreamProps, audio, fetchInsecureJwtToken, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats, video };

package/dist/index.d.ts

@@ -9,6 +9,81 @@ type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
  * - "runtime": platform-level control messages (e.g., capabilities exchange).
  */
 type MessageScope = "application" | "runtime";
+/**
+ * Describes a single named media track for SDP negotiation.
+ *
+ * Track names must exactly match the class attribute names defined on the
+ * model's Python code.  The name is encoded as the SDP MID so both sides
+ * can route media by name rather than by positional index.
+ *
+ * Use the {@link video} and {@link audio} helper functions to create
+ * instances instead of constructing this interface directly.
+ */
+interface TrackConfig {
+    name: string;
+    kind: "audio" | "video";
+}
+/**
+ * Optional configuration for a video track (reserved for future use).
+ */
+interface VideoTrackOptions {
+    /** Maximum framerate constraint for the video track. */
+    maxFramerate?: number;
+}
+/**
+ * Optional configuration for an audio track (reserved for future use).
+ */
+interface AudioTrackOptions {
+    /** Sample rate constraint for the audio track. */
+    sampleRate?: number;
+}
+/**
+ * Creates a **video** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** video frames **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** video frames **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `maxFramerate`).
+ *
+ * When no `receive` array is provided to the Reactor constructor, a single
+ * `video("main_video")` track is used by default.
+ *
+ * @example
+ * ```ts
+ * receive: [video("main_video")]          // receive video from the model
+ * send:    [video("webcam")]              // send webcam video to the model
+ * ```
+ */
+declare function video(name: string, _options?: VideoTrackOptions): TrackConfig;
+/**
+ * Creates an **audio** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** audio samples **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** audio samples **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `sampleRate`).
+ *
+ * @example
+ * ```ts
+ * receive: [audio("main_audio")]          // receive audio from the model
+ * send:    [audio("mic")]                 // send microphone audio to the model
+ * ```
+ */
+declare function audio(name: string, _options?: AudioTrackOptions): TrackConfig;
 interface ReactorError {
     code: string;
     message: string;
@@ -20,6 +95,11 @@ interface ReactorError {
 declare class ConflictError extends Error {
     constructor(message: string);
 }
+declare class AbortError extends Error {
+    constructor(message: string);
+}
+/** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
+declare function isAbortError(error: unknown): boolean;
 interface ReactorState$1 {
     status: ReactorStatus;
     lastError?: ReactorError;
@@ -46,13 +126,27 @@ interface ConnectionStats {
     jitter?: number;
     timestamp: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "streamChanged" | "error" | "sessionExpirationChanged" | "statsUpdate";
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
     coordinatorUrl: z.ZodDefault<z.ZodString>;
     modelName: z.ZodString;
     local: z.ZodDefault<z.ZodBoolean>;
+    receive: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
+    send: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Options = z.input<typeof OptionsSchema>;
 type EventHandler = (...args: any[]) => void;
@@ -65,6 +159,10 @@ declare class Reactor {
     private model;
     private sessionExpiration?;
     private local;
+    /** Tracks the client RECEIVES from the model (model → client). */
+    private receive;
+    /** Tracks the client SENDS to the model (client → model). */
+    private send;
     private sessionId?;
     constructor(options: Options);
     private eventListeners;
@@ -72,24 +170,26 @@ declare class Reactor {
     off(event: ReactorEvent, handler: EventHandler): void;
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
-     * Public method to send a message to the machine.
-     * Wraps the message in the specified channel envelope (defaults to "application").
-     * @param command The command name to send.
+     * Sends a command to the model via the data channel.
+     *
+     * @param command The command name.
      * @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
+     * @param scope "application" (default) for model commands, "runtime" for platform messages.
      */
     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.
+     * Publishes a MediaStreamTrack to a named send track.
+     *
+     * @param name The declared send track name (e.g. "webcam").
+     * @param track The MediaStreamTrack to publish.
      */
-    publishTrack(track: MediaStreamTrack): Promise<void>;
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
     /**
-     * Public method to unpublish the currently published track.
+     * Unpublishes the track with the given name.
+     *
+     * @param name The declared send track name to unpublish.
      */
-    unpublishTrack(): Promise<void>;
+    unpublishTrack(name: string): 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)
@@ -105,6 +205,11 @@ declare class Reactor {
     connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     /**
      * Sets up event handlers for the machine client.
+     *
+     * Each handler captures the client reference at registration time and
+     * ignores events if this.machineClient has since changed (e.g. after
+     * disconnect + reconnect), preventing stale WebRTC teardown events from
+     * interfering with a new connection.
      */
     private setupMachineClientHandlers;
     /**
@@ -138,19 +243,24 @@ declare class Reactor {
 
 interface ReactorState {
     status: ReactorStatus;
-    videoTrack: MediaStreamTrack | null;
+    /**
+     * Media tracks received from the model, keyed by track name.
+     *
+     * Each entry maps a declared **receive** track name (e.g. `"main_video"`,
+     * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
+     */
+    tracks: Record<string, MediaStreamTrack>;
     lastError?: ReactorError;
     sessionId?: string;
     sessionExpiration?: number;
-    insecureApiKey?: string;
     jwtToken?: string;
 }
 interface ReactorActions {
     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>;
+    publish(name: string, track: MediaStreamTrack): Promise<void>;
+    unpublish(name: string): Promise<void>;
     reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
@@ -180,13 +290,26 @@ declare function ReactorProvider({ children, connectOptions, jwtToken, ...props
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
+    /**
+     * The name of the **receive** track to render.
+     * Must match a track name declared in the `receive` array (model → client).
+     * Defaults to `"main_video"`.
+     */
+    track?: string;
+    /**
+     * Optional name of a **receive** audio track to play alongside the video
+     * (e.g. `"main_audio"`).  The audio is mixed into the same `<video>` element.
+     */
+    audioTrack?: string;
     width?: number;
     height?: number;
     className?: string;
     style?: React.CSSProperties;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
+    /** Controls whether inbound audio plays. Default true (muted) to satisfy browser autoplay policies. */
+    muted?: boolean;
 }
-declare function ReactorView({ width, height, className, style, videoObjectFit, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
+declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
 
 interface ReactorControllerProps {
     className?: string;
@@ -194,14 +317,19 @@ interface ReactorControllerProps {
 }
 declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
 
-interface Props {
+interface WebcamStreamProps {
+    /**
+     * The name of the **send** track to publish the webcam to.
+     * Must match a track name declared in the `send` array (client → model).
+     */
+    track: string;
     className?: string;
     style?: React.CSSProperties;
     videoConstraints?: MediaTrackConstraints;
     showWebcam?: boolean;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
 }
-declare function WebcamStream({ className, style, videoConstraints, showWebcam, videoObjectFit, }: Props): react_jsx_runtime.JSX.Element;
+declare function WebcamStream({ track, className, style, videoConstraints, showWebcam, videoObjectFit, }: WebcamStreamProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Generic hook for accessing selected parts of the Reactor store.
@@ -249,4 +377,4 @@ declare function useStats(): ConnectionStats | undefined;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-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 };
+export { AbortError, type AudioTrackOptions, 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, type TrackConfig, type VideoTrackOptions, WebcamStream, type WebcamStreamProps, audio, fetchInsecureJwtToken, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats, video };