@reactor-team/js-sdk 2.6.0 → 2.8.0

package/dist/index.d.ts

@@ -2,6 +2,90 @@ 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 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 SessionResponseSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    state: z.ZodString;
+    cluster: z.ZodString;
+    model: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    server_info: z.ZodObject<{
+        server_version: z.ZodString;
+    }, z.core.$strip>;
+    selected_transport: z.ZodOptional<z.ZodObject<{
+        protocol: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>;
+    capabilities: z.ZodOptional<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 TrackCapability = z.infer<typeof TrackCapabilitySchema>;
+type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
+type SessionResponse = z.infer<typeof SessionResponseSchema>;
+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,81 +93,7 @@ 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;
@@ -112,21 +122,18 @@ interface ConnectOptions {
     maxAttempts?: number;
 }
 /**
- * One-shot 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()`).
+ * 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 polling for the SDP answer */
-    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;
+    /** Total time spent in transport.connect() (signaling, negotiation, etc.) */
+    transportConnectingMs: number;
     /** End-to-end: connect() invocation → status "ready" */
     totalMs: number;
 }
@@ -147,46 +154,31 @@ interface ConnectionStats {
     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 DEFAULT_BASE_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
     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;
 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;
@@ -194,75 +186,45 @@ declare class Reactor {
     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;
-    /**
-     * Set the session expiration time.
-     * @param newSessionExpiration The new session expiration time in seconds.
-     */
-    private setSessionExpiration;
-    /**
-     * Get the current state including status, error, and waiting info
-     */
     getState(): ReactorState$1;
-    /**
-     * Get the last error that occurred
-     */
     getLastError(): ReactorError | undefined;
+    getCapabilities(): Capabilities | undefined;
+    getSessionInfo(): SessionResponse | undefined;
     getStats(): ConnectionStats | undefined;
+    private setSessionId;
+    private setStatus;
+    private setSessionExpiration;
     private resetConnectionTimings;
     private finalizeConnectionTimings;
-    /**
-     * Create and store an error
-     */
     private createError;
 }
 
@@ -271,7 +233,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>;
@@ -316,14 +278,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;
@@ -344,8 +308,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;
@@ -389,17 +354,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
  */
 declare function useStats(): ConnectionStats | undefined;
 
-/**
- * ⚠️ INSECURE: Fetches a JWT token directly from the client.
- *
- * WARNING: This function exposes your API key in client-side code.
- * Only use this for local development or testing purposes.
- * 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 apiUrl - Optional API URL, defaults to production
- * @returns string containing the JWT token
- */
-declare function fetchInsecureToken(apiKey: string, apiUrl?: string): Promise<string>;
-
-export { AbortError, type AudioTrackOptions, 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 TrackConfig, type VideoTrackOptions, WebcamStream, type WebcamStreamProps, audio, fetchInsecureToken, 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, type ReactorStore, ReactorView, type ReactorViewProps, type SessionResponse, type TrackCapability, WebcamStream, type WebcamStreamProps, isAbortError, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };