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

import type { RatingEvent } from '../entities/RatingEvent';
import type { RatingEventId } from '../value-objects/RatingEventId';

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

export interface RatingEventFilter {
  /** 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?: RatingEventFilter;
}

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

export interface RatingEventRepository {
  /**
   * Save a rating event to the ledger
   */
  save(event: RatingEvent): Promise<RatingEvent>;
  
  /**
   * Find all rating events for a user, ordered by occurredAt (ascending)
   * Options allow for pagination and streaming
   */
  findByUserId(userId: string, options?: FindByUserIdOptions): Promise<RatingEvent[]>;
  
  /**
   * Find multiple events by their IDs
   */
  findByIds(ids: RatingEventId[]): Promise<RatingEvent[]>;
  
  /**
   * Get all events for a user (for snapshot recomputation)
   */
  getAllByUserId(userId: string): Promise<RatingEvent[]>;
  
  /**
   * Find events with pagination and filtering
   */
  findEventsPaginated(userId: string, options?: PaginatedQueryOptions): Promise<PaginatedResult<RatingEvent>>;
}
