/**
 * Repository Interface: TeamRatingEventRepository
 * 
 * Port for persisting and retrieving team rating events (ledger).
 * Events are immutable and ordered by occurredAt for deterministic snapshot computation.
 */

import type { TeamRatingEvent } from '../entities/TeamRatingEvent';
import type { TeamRatingEventId } from '../value-objects/TeamRatingEventId';

export interface FindByTeamIdOptions {
  /** Only return events after this ID (for pagination/streaming) */
  afterId?: TeamRatingEventId;
  /** Maximum number of events to return */
  limit?: number;
}

export interface TeamRatingEventFilter {
  /** Filter by dimension keys */
  dimensions?: string[];
  /** Filter by source types */
  sourceTypes?: ('race' | 'penalty' | 'vote' | 'adminAction' | 'manualAdjustment')[];
  /** Filter by date range (inclusive) */
  from?: Date;
  to?: Date;
  /** Filter by reason codes */
  reasonCodes?: string[];
  /** Filter by visibility */
  visibility?: 'public' | 'private';
}

export interface PaginatedQueryOptions {
  limit?: number;
  offset?: number;
  filter?: TeamRatingEventFilter;
}

export interface PaginatedResult<T> {
  items: T[];
  total: number;
  limit: number;
  offset: number;
  hasMore: boolean;
  nextOffset?: number;
}

export interface TeamRatingEventRepository {
  /**
   * Save a rating event to the ledger
   */
  save(event: TeamRatingEvent): Promise<TeamRatingEvent>;
  
  /**
   * Find all rating events for a team, ordered by occurredAt (ascending)
   * Options allow for pagination and streaming
   */
  findByTeamId(teamId: string, options?: FindByTeamIdOptions): Promise<TeamRatingEvent[]>;
  
  /**
   * Find multiple events by their IDs
   */
  findByIds(ids: TeamRatingEventId[]): Promise<TeamRatingEvent[]>;
  
  /**
   * Get all events for a team (for snapshot recomputation)
   */
  getAllByTeamId(teamId: string): Promise<TeamRatingEvent[]>;
  
  /**
   * Find events with pagination and filtering
   */
  findEventsPaginated(teamId: string, options?: PaginatedQueryOptions): Promise<PaginatedResult<TeamRatingEvent>>;
}