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
}

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

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