@reactor-team/js-sdk 2.5.1 → 2.7.0

package/dist/index.d.mts

@@ -2,6 +2,95 @@ import { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+/**
+ * Internal types for the Reactor SDK.
+ *
+ * All Zod schemas and derived TypeScript types live here.
+ * Version constants are sourced from package.json via resolveJsonModule.
+ */
+
+declare const TransportDeclarationSchema: z.ZodObject<{
+    protocol: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>;
+declare const TrackCapabilitySchema: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        video: "video";
+        audio: "audio";
+    }>;
+    direction: z.ZodEnum<{
+        recvonly: "recvonly";
+        sendonly: "sendonly";
+    }>;
+}, z.core.$strip>;
+declare const CommandCapabilitySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+declare const CapabilitiesSchema: z.ZodObject<{
+    protocol_version: z.ZodString;
+    tracks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            video: "video";
+            audio: "audio";
+        }>;
+        direction: z.ZodEnum<{
+            recvonly: "recvonly";
+            sendonly: "sendonly";
+        }>;
+    }, z.core.$strip>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>>>;
+    emission_fps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+declare const CreateSessionResponseSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    server_info: z.ZodOptional<z.ZodObject<{
+        server_version: z.ZodString;
+    }, z.core.$strip>>;
+    model: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    state: z.ZodString;
+    cluster: z.ZodOptional<z.ZodString>;
+    selected_transport: z.ZodObject<{
+        protocol: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    capabilities: z.ZodObject<{
+        protocol_version: z.ZodString;
+        tracks: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            kind: z.ZodEnum<{
+                video: "video";
+                audio: "audio";
+            }>;
+            direction: z.ZodEnum<{
+                recvonly: "recvonly";
+                sendonly: "sendonly";
+            }>;
+        }, z.core.$strip>>;
+        commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        }, z.core.$strip>>>;
+        emission_fps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type TransportDeclaration = z.infer<typeof TransportDeclarationSchema>;
+type TrackCapability = z.infer<typeof TrackCapabilitySchema>;
+type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
+type CreateSessionResponse = z.infer<typeof CreateSessionResponseSchema>;
+type Capabilities = z.infer<typeof CapabilitiesSchema>;
+
 type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
 /**
  * The message scope identifies the envelope layer a data channel message belongs to.
@@ -9,87 +98,13 @@ 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;
     timestamp: number;
     recoverable: boolean;
-    component: "coordinator" | "gpu" | "livekit";
+    component: "api" | "gpu";
     retryAfter?: number;
 }
 declare class ConflictError extends Error {
@@ -111,6 +126,22 @@ interface ConnectOptions {
     /** Maximum number of SDP polling attempts before giving up. Default: 6. */
     maxAttempts?: number;
 }
+/**
+ * Transport-agnostic timing breakdown of the connect() handshake, recorded
+ * once per connection and included in every subsequent {@link ConnectionStats}
+ * update. All durations are in milliseconds (from `performance.now()`).
+ *
+ * For transport-specific timings (e.g. ICE negotiation, data channel open),
+ * see the relevant transport stats type (e.g. {@link WebRTCTransportTimings}).
+ */
+interface ConnectionTimings {
+    /** POST /sessions round-trip time */
+    sessionCreationMs: number;
+    /** Total time spent in transport.connect() (signaling, negotiation, etc.) */
+    transportConnectingMs: number;
+    /** End-to-end: connect() invocation → status "ready" */
+    totalMs: number;
+}
 interface ConnectionStats {
     /** ICE candidate-pair round-trip time in milliseconds */
     rtt?: number;
@@ -124,121 +155,259 @@ interface ConnectionStats {
     packetLossRatio?: number;
     /** Network jitter in seconds (from inbound-rtp) */
     jitter?: number;
+    /** Timing breakdown of the initial connection handshake (set once, persisted until disconnect) */
+    connectionTimings?: ConnectionTimings;
     timestamp: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "statsUpdate";
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "capabilitiesReceived" | "statsUpdate";
 
-declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
+declare const DEFAULT_BASE_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
-    coordinatorUrl: z.ZodDefault<z.ZodString>;
+    apiUrl: 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;
+type EventHandler$2 = (...args: any[]) => void;
 declare class Reactor {
     private coordinatorClient;
-    private machineClient;
+    private transportClient;
     private status;
     private coordinatorUrl;
     private lastError?;
     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?;
+    private connectStartTime?;
+    private connectionTimings?;
+    private capabilities?;
+    private tracks;
+    private sessionResponse?;
     constructor(options: Options);
     private eventListeners;
-    on(event: ReactorEvent, handler: EventHandler): void;
-    off(event: ReactorEvent, handler: EventHandler): void;
+    on(event: ReactorEvent, handler: EventHandler$2): void;
+    off(event: ReactorEvent, handler: EventHandler$2): void;
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
      * Sends a command to the model via the data channel.
-     *
-     * @param command The command name.
-     * @param data The command payload.
-     * @param scope "application" (default) for model commands, "runtime" for platform messages.
      */
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
-     * Publishes a MediaStreamTrack to a named send track.
-     *
-     * @param name The declared send track name (e.g. "webcam").
-     * @param track The MediaStreamTrack to publish.
+     * Publishes a MediaStreamTrack to a named sendonly track.
+     * The transceiver is already set up from capabilities — this just
+     * calls replaceTrack() on the sender.
      */
     publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
-    /**
-     * Unpublishes the track with the given name.
-     *
-     * @param name The declared send track name to unpublish.
-     */
     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)
+     * Reconnects to an existing session with a fresh transport.
      */
     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)
+     * Connects to the coordinator, creates a session, then establishes
+     * the transport using server-declared capabilities.
      */
     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.
+     * Sets up event handlers for the transport client.
+     * Each handler captures the client reference to ignore stale events.
      */
-    private setupMachineClientHandlers;
+    private setupTransportHandlers;
     /**
-     * Disconnects from the coordinator and the gpu machine.
-     * Ensures cleanup completes even if individual disconnections fail.
+     * Disconnects from both the transport and the coordinator.
      */
     disconnect(recoverable?: boolean): Promise<void>;
-    private setSessionId;
     getSessionId(): string | undefined;
-    private setStatus;
     getStatus(): ReactorStatus;
+    getState(): ReactorState$1;
+    getLastError(): ReactorError | undefined;
+    getCapabilities(): Capabilities | undefined;
+    getSessionInfo(): CreateSessionResponse | undefined;
+    getStats(): ConnectionStats | undefined;
+    private setSessionId;
+    private setStatus;
+    private setSessionExpiration;
+    private resetConnectionTimings;
+    private finalizeConnectionTimings;
+    private createError;
+}
+
+type EventHandler$1 = (...args: any[]) => void;
+interface WebRTCTransportConfig extends TransportClientConfig {
+    webrtcVersion?: string;
+    maxPollAttempts?: number;
+}
+/**
+ * WebRTC-specific timing breakdown of the transport connection.
+ * Recorded once per connection and accessible via {@link WebRTCTransportClient.getTransportTimings}.
+ */
+interface WebRTCTransportTimings {
+    protocol: "webrtc";
+    /** Time spent polling for the SDP answer (POST offer → GET answer 200) */
+    sdpPollingMs: number;
+    /** Number of SDP poll requests made (1 = answered on first try) */
+    sdpPollingAttempts: number;
+    /** setRemoteDescription → RTCPeerConnection connectionState "connected" */
+    iceNegotiationMs: number;
+    /** setRemoteDescription → RTCDataChannel "open" */
+    dataChannelMs: number;
+}
+declare class WebRTCTransportClient implements TransportClient {
+    private eventListeners;
+    private peerConnection;
+    private dataChannel;
+    private status;
+    private pingInterval;
+    private statsInterval;
+    private stats;
+    private transceiverMap;
+    private publishedTracks;
+    private peerConnected;
+    private dataChannelOpen;
+    private iceStartTime?;
+    private iceNegotiationMs?;
+    private dataChannelMs?;
+    private sdpPollingMs?;
+    private sdpPollingAttempts?;
+    private readonly baseUrl;
+    private readonly sessionId;
+    private readonly jwtToken;
+    private readonly webrtcVersion;
+    private readonly maxPollAttempts;
+    private abortController;
+    constructor(config: WebRTCTransportConfig);
+    on(event: TransportEvent, handler: EventHandler$1): void;
+    off(event: TransportEvent, handler: EventHandler$1): void;
+    private emit;
+    private get signal();
+    private get transportBaseUrl();
+    private getHeaders;
+    private checkVersionMismatch;
+    private sleep;
+    private fetchIceServers;
+    private sendSdpOffer;
+    private pollSdpAnswer;
+    connect(tracks: TrackCapability[]): Promise<void>;
+    reconnect(tracks: TrackCapability[]): Promise<void>;
+    disconnect(): Promise<void>;
+    abort(): void;
+    getStatus(): TransportStatus;
     /**
-     * Set the session expiration time.
-     * @param newSessionExpiration The new session expiration time in seconds.
+     * Builds the track_mapping array from capabilities + transceiver MIDs.
+     * Must be called after createOffer + setLocalDescription so that
+     * transceiver.mid is assigned.
      */
-    private setSessionExpiration;
+    private buildTrackMapping;
+    private get maxMessageBytes();
+    sendCommand(command: string, data: any, scope?: MessageScope): void;
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
+    unpublishTrack(name: string): Promise<void>;
+    getStats(): ConnectionStats | undefined;
+    getTransportTimings(): WebRTCTransportTimings | undefined;
+    private resetTransportTimings;
+    private startStatsPolling;
+    private stopStatsPolling;
+    private startPing;
+    private stopPing;
+    private checkFullyConnected;
+    private setStatus;
+    private setupPeerConnectionHandlers;
+    private setupDataChannelHandlers;
+}
+
+/**
+ * Generic transport interface for connecting to a Reactor session.
+ *
+ * A TransportClient encapsulates the full transport lifecycle: signaling,
+ * connection establishment, media track management, and data channel
+ * messaging. Implementations handle protocol specifics (WebRTC, MOQ, etc.)
+ * while the Reactor orchestrator works only through this interface.
+ */
+
+/**
+ * Discriminated union of all transport-specific timing types.
+ * Each member carries a `protocol` tag for narrowing.
+ * Extend this union when adding new transport implementations.
+ */
+type TransportTimings = WebRTCTransportTimings;
+type TransportStatus = "disconnected" | "connecting" | "connected" | "error";
+type TransportEvent = "statusChanged" | "trackReceived" | "trackRemoved" | "message" | "statsUpdate";
+type EventHandler = (...args: any[]) => void;
+interface TransportClientConfig {
+    baseUrl: string;
+    sessionId: string;
+    jwtToken: string;
+}
+interface TransportClient {
     /**
-     * Get the current state including status, error, and waiting info
+     * Establishes the transport connection using server-declared tracks.
+     *
+     * Internally handles: signaling (ICE servers, SDP offer/answer),
+     * connection negotiation, and transceiver setup. For sendonly tracks,
+     * no media flows until {@link publishTrack} is called.
      */
-    getState(): ReactorState$1;
+    connect(tracks: TrackCapability[]): Promise<void>;
     /**
-     * Get the last error that occurred
+     * Reconnects an existing session with a fresh transport negotiation.
+     * Uses the same tracks as the original connection.
+     */
+    reconnect(tracks: TrackCapability[]): Promise<void>;
+    /**
+     * Tears down the transport connection and releases all resources.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Returns the current transport connection status.
+     */
+    getStatus(): TransportStatus;
+    /**
+     * Sends a command to the model via the data channel.
+     *
+     * @param command The command name.
+     * @param data The command payload.
+     * @param scope "application" for model commands, "runtime" for platform messages.
+     */
+    sendCommand(command: string, data: any, scope: MessageScope): void;
+    /**
+     * Publishes a MediaStreamTrack to a named sendonly track.
+     * The transceiver must already exist (declared by capabilities).
+     * Uses replaceTrack() — no renegotiation needed.
+     */
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
+    /**
+     * Stops sending media on a named track.
+     */
+    unpublishTrack(name: string): Promise<void>;
+    /**
+     * Subscribes to transport events.
+     *
+     * Events:
+     * - "statusChanged" (status: TransportStatus)
+     * - "trackReceived" (name: string, track: MediaStreamTrack, stream: MediaStream)
+     * - "trackRemoved" (name: string)
+     * - "message" (message: any, scope: MessageScope)
+     * - "statsUpdate" (stats: ConnectionStats)
+     */
+    on(event: TransportEvent, handler: EventHandler): void;
+    /**
+     * Unsubscribes from transport events.
+     */
+    off(event: TransportEvent, handler: EventHandler): void;
+    /**
+     * Returns current connection statistics, or undefined if not connected.
      */
-    getLastError(): ReactorError | undefined;
     getStats(): ConnectionStats | undefined;
     /**
-     * Create and store an error
+     * Returns transport-specific timing breakdown of the most recent
+     * connection attempt. Narrow on the `protocol` discriminant to
+     * access implementation-specific fields.
      */
-    private createError;
+    getTransportTimings(): TransportTimings | undefined;
+    /**
+     * Cancels any in-flight signaling (HTTP polling, pending fetches).
+     */
+    abort(): void;
 }
 
 interface ReactorState {
@@ -246,7 +415,7 @@ interface ReactorState {
     /**
      * Media tracks received from the model, keyed by track name.
      *
-     * Each entry maps a declared **receive** track name (e.g. `"main_video"`,
+     * Each entry maps a recvonly track name (e.g. `"main_video"`,
      * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
      */
     tracks: Record<string, MediaStreamTrack>;
@@ -291,14 +460,16 @@ declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStor
 
 interface ReactorViewProps {
     /**
-     * The name of the **receive** track to render.
-     * Must match a track name declared in the `receive` array (model → client).
+     * The name of the recvonly track to render.
+     * Must match a track name declared in the server capabilities.
+     * Check the model's documentation for available track names.
      * 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.
+     * Optional name of a recvonly audio track to play alongside the video
+     * (e.g. `"main_audio"`). The audio is mixed into the same `<video>` element.
+     * Check the model's documentation for available track names.
      */
     audioTrack?: string;
     width?: number;
@@ -319,8 +490,9 @@ declare function ReactorController({ className, style, }: ReactorControllerProps
 
 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).
+     * The name of the sendonly track to publish the webcam to.
+     * Must match a track name declared in the server capabilities.
+     * Check the model's documentation for available track names.
      */
     track: string;
     className?: string;
@@ -372,9 +544,9 @@ declare function useStats(): ConnectionStats | undefined;
  * In production, call /tokens from your server and pass the JWT to your frontend.
  *
  * @param apiKey - Your Reactor API key (will be exposed in client code!)
- * @param coordinatorUrl - Optional coordinator URL, defaults to production
+ * @param apiUrl - Optional API URL, defaults to production
  * @returns string containing the JWT token
  */
-declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
+declare function fetchInsecureToken(apiKey: string, apiUrl?: string): Promise<string>;
 
-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 };
+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, ReactorView, type ReactorViewProps, type CreateSessionResponse as SessionInfo, type TrackCapability, type TransportClient, type TransportClientConfig, type TransportDeclaration, type TransportEvent, type TransportStatus, type TransportTimings, WebRTCTransportClient, type WebRTCTransportConfig, type WebRTCTransportTimings, WebcamStream, type WebcamStreamProps, fetchInsecureToken, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };