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
}

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;
  lastError?: ReactorError;
}

interface ReactorError {
  code: string;
  message: string;
  timestamp: number;        // Unix timestamp
  recoverable: boolean;
  component: "api" | "gpu";
  retryAfter?: number;      // Suggested retry delay in seconds
}

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

interface Capabilities {
  protocol_version: string;
  tracks: TrackCapability[];
  commands?: CommandCapability[];
  emission_fps?: number | null;
}

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"
}