rondevu-client/src/types.ts

/**
 * Session side - identifies which peer in a connection
 */
export type Side = 'offerer' | 'answerer';

/**
 * Session information returned from discovery endpoints
 */
export interface Session {
  /** Unique session identifier (UUID) */
  code: string;
  /** Peer identifier/metadata */
  info: string;
  /** Signaling data for peer connection */
  offer: string;
  /** Additional signaling data from offerer */
  offerCandidates: string[];
  /** Unix timestamp when session was created */
  createdAt: number;
  /** Unix timestamp when session expires */
  expiresAt: number;
}

/**
 * Topic information with peer count
 */
export interface TopicInfo {
  /** Topic identifier */
  topic: string;
  /** Number of available peers in this topic */
  count: number;
}

/**
 * Pagination information
 */
export interface Pagination {
  /** Current page number */
  page: number;
  /** Results per page */
  limit: number;
  /** Total number of results */
  total: number;
  /** Whether there are more results available */
  hasMore: boolean;
}

/**
 * Response from GET / - list all topics
 */
export interface ListTopicsResponse {
  topics: TopicInfo[];
  pagination: Pagination;
}

/**
 * Response from GET /:topic/sessions - list sessions in a topic
 */
export interface ListSessionsResponse {
  sessions: Session[];
}

/**
 * Request body for POST /:topic/offer
 */
export interface CreateOfferRequest {
  /** Peer identifier/metadata (max 1024 characters) */
  info: string;
  /** Signaling data for peer connection */
  offer: string;
}

/**
 * Response from POST /:topic/offer
 */
export interface CreateOfferResponse {
  /** Unique session identifier (UUID) */
  code: string;
}

/**
 * Request body for POST /answer
 */
export interface AnswerRequest {
  /** Session UUID from the offer */
  code: string;
  /** Response signaling data (required if candidate not provided) */
  answer?: string;
  /** Additional signaling data (required if answer not provided) */
  candidate?: string;
  /** Which peer is sending the data */
  side: Side;
}

/**
 * Response from POST /answer
 */
export interface AnswerResponse {
  success: boolean;
}

/**
 * Request body for POST /poll
 */
export interface PollRequest {
  /** Session UUID */
  code: string;
  /** Which side is polling */
  side: Side;
}

/**
 * Response from POST /poll when side=offerer
 */
export interface PollOffererResponse {
  /** Answer from answerer (null if not yet received) */
  answer: string | null;
  /** Additional signaling data from answerer */
  answerCandidates: string[];
}

/**
 * Response from POST /poll when side=answerer
 */
export interface PollAnswererResponse {
  /** Offer from offerer */
  offer: string;
  /** Additional signaling data from offerer */
  offerCandidates: string[];
}

/**
 * Response from POST /poll (union type)
 */
export type PollResponse = PollOffererResponse | PollAnswererResponse;

/**
 * Response from GET /health
 */
export interface HealthResponse {
  status: 'ok';
  timestamp: number;
}

/**
 * Error response structure
 */
export interface ErrorResponse {
  error: string;
}

/**
 * Client configuration options
 */
export interface RondevuClientOptions {
  /** Base URL of the Rondevu server (e.g., 'https://example.com') */
  baseUrl: string;
  /** Origin header value for session isolation (defaults to baseUrl origin) */
  origin?: string;
  /** Optional fetch implementation (for Node.js environments) */
  fetch?: typeof fetch;
}