JavaScript SDK types

class FileRef {
  readonly uploadId: string; // Upload identifier
  readonly name: string; // Filename
  readonly mimeType: string; // MIME type (e.g. "image/jpeg")
  readonly size: number; // File size in bytes
}

isFileRef(value: unknown): value is FileRef

type MessageScope = "application" | "runtime";

type ReactorStatus =
  | "disconnected" // No active connection
  | "connecting" // Connecting to the API
  | "waiting" // Waiting for a GPU to be assigned
  | "ready"; // Connected to the model, can send and receive

interface ReactorState {
  status: ReactorStatus;
  sessionId: string | undefined;
  lastError: ReactorError | undefined;
  lastMessage: ReactorMessage | undefined; // Most recent application-scope message payload
  tracks: Record<string, MediaStreamTrack>; // Received tracks by name
  jwtToken: JwtSource | undefined;
  connectOptions: ConnectOptions | undefined;
}

interface ConnectOptions {
  maxAttempts?: number; // Max SDP polling attempts before giving up. Default: 6.
  autoResumeTracks?: boolean; // Subscribe to output tracks on connect. Default: true.
  sessionId?: string; // Adopt an existing session instead of creating one.
  connectionId?: number; // Adopt a pre-registered WebRTC connection id.
}

class ReactorError extends Error {
  readonly code: string;
  readonly message: string;
  readonly recoverable: boolean;
  readonly status?: number; // HTTP status, when the failure came from one
  readonly operation?: string; // Which call failed, e.g. "connect", "sendCommand"
  readonly retry_after_ms?: number; // Backoff hint the platform sent
  readonly timestamp_ms: number;

  // Kept alongside the fields above under their previous names, for compatibility:
  readonly retryAfter?: number; // Same value as retry_after_ms
  readonly timestamp: number; // Same value as timestamp_ms
}

import { ReactorError, UnauthorizedError, ConflictError } from "@reactor-team/js-sdk";

reactor.on("error", (error) => {
  if (error instanceof UnauthorizedError) {
    refreshToken(); // a specific, actionable failure
  } else if (error instanceof ConflictError) {
    // a previous run left the session orphaned
  } else if (error.recoverable) {
    setTimeout(() => reactor.reconnect(), (error.retry_after_ms ?? 1000) / 1000);
  }
});

interface TrackCapability {
  name: string;
  kind: "video" | "audio";
  direction: "recvonly" | "sendonly";
}

interface TrackMappingEntry extends TrackCapability {
  mid: string;
}

interface Capabilities {
  protocolVersion: string;
  tracks: TrackCapability[];
  commands?: CommandCapability[];
  emissionFps?: number;
}

interface SessionResponse {
  session_id: string;
  state: string;
  model?: { name: string; version?: string };
  cluster?: string;
  capabilities?: {
    protocol_version: string;
    tracks: TrackCapability[];
    commands?: CommandCapability[];
    emission_fps?: number;
  };
  // Fields newer servers add are preserved rather than dropped.
  [key: string]: unknown;
}

interface Clip {
  sessionId: string;
  kind: "snap" | "recording";
  startMarker: number; // Session-relative seconds.
  endMarker: number; // Session-relative seconds.
  nowMarker: number; // Session-relative seconds at request time.
  predictedReadyAtMs: number; // Unix epoch (ms) when the clip is expected to be playable.
  playlistUrl: string; // Short-lived URL pointing at the clip.
}

class RecordingError extends Error {
  readonly code: RecordingErrorCode;
  readonly reason: string;
}

type ClipDownloadState =
  | { kind: "idle" }
  | { kind: "downloading"; fetched: number; total: number }
  | { kind: "error"; message: string };

interface ConnectionStats {
  timestamp: number; // When stats were collected (Unix ms)
  rtt?: number; // Round-trip time in milliseconds
  framesPerSecond?: number; // Received video frames per second
  jitter?: number; // Network jitter in seconds
  packetLossRatio?: number; // Packet loss ratio (0 to 1)
  candidateType?: string; // ICE candidate type: "host", "srflx", "prflx", or "relay"
  availableOutgoingBitrate?: number; // Available outgoing bitrate in bits/second
  connectionTimings?: ConnectionTimings; // Timing breakdown of the initial handshake
}

interface ConnectionTimings {
  sessionCreationMs: number; // POST /sessions round-trip
  transportConnectingMs: number; // Transport connect (signaling, negotiation)
  totalMs: number; // End-to-end connect() → "ready"
}