Implement Encounter.fightRankings for encounter-specific fight rankings

[knowlen]

Summary

Implement the missing Encounter.fightRankings GraphQL field to provide encounter-specific fight ranking data with advanced filtering options.

Background

The GraphQL schema exposes Encounter.fightRankings with parameters including:

• hardModeLevel: HardModeLevelRankFilter - Filter by specific hard mode levels
• leaderboard: LeaderboardRank - Include/exclude ranks without backing logs
• metric: FightRankingMetricType - Different metrics than character rankings

This complements the character rankings and provides fight-level analysis capabilities.

Current State

• We have various ranking methods but none that access fight-specific rankings at the encounter level
• This data is useful for analyzing group/raid performance rather than individual performance

Implementation Steps

1. Add the GraphQL Query

Create a new query in queries.graphql:

query getEncounterFightRankings(
  $zoneId: Int\!
  $encounterId: Int\!
  $bracket: Int
  $difficulty: Int
  $filter: String
  $page: Int
  $partition: Int
  $serverRegion: String
  $serverSlug: String
  $size: Int
  $leaderboard: LeaderboardRank
  $hardModeLevel: HardModeLevelRankFilter
  $metric: FightRankingMetricType
) {
  worldData {
    zone(id: $zoneId) {
      encounters {
        id
        name
        fightRankings(
          bracket: $bracket
          difficulty: $difficulty
          filter: $filter
          page: $page
          partition: $partition
          serverRegion: $serverRegion
          serverSlug: $serverSlug
          size: $size
          leaderboard: $leaderboard
          hardModeLevel: $hardModeLevel
          metric: $metric
        )
      }
    }
  }
}

2. Update Code Generation

1. Add the query to the code generation input
2. Run the code generation to create the response types
3. This will generate GetEncounterFightRankings response class

3. Create the Client Method

Add to WorldDataMixin or create a new RankingsMixin:

async def get_encounter_fight_rankings(
    self,
    zone_id: int,
    encounter_id: int,
    bracket: Optional[int] = None,
    difficulty: Optional[int] = None,
    filter: Optional[str] = None,
    page: Optional[int] = None,
    partition: Optional[int] = None,
    server_region: Optional[str] = None,
    server_slug: Optional[str] = None,
    size: Optional[int] = None,
    leaderboard: Optional[LeaderboardRank] = None,
    hard_mode_level: Optional[HardModeLevelRankFilter] = None,
    metric: Optional[FightRankingMetricType] = None,
) -> GetEncounterFightRankings:
    """
    Get fight rankings for a specific encounter.
    
    This provides fight-level (group/raid) rankings as opposed to 
    individual character rankings. Useful for analyzing overall
    group performance and completion times.
    
    Args:
        zone_id: The zone ID containing the encounter
        encounter_id: The specific encounter ID
        leaderboard: Filter by leaderboard rank type
        hard_mode_level: Filter by hard mode difficulty level
        metric: The ranking metric to use (default, speed, execution, etc.)
    
    Returns:
        Fight ranking data for the specified encounter
    """
    # Implementation

4. Response Processing

Similar to character rankings:

1. Filter encounters list to find the matching encounter_id
2. Extract the fightRankings from that specific encounter
3. Provide clear error messages if encounter not found

5. Add Comprehensive Tests

1. Unit tests for all parameters
2. Integration tests verifying the filters work
3. Test edge cases (invalid encounter, no rankings available)

6. Documentation Updates

1. Add to API reference under a new "Advanced Rankings" section
2. Provide examples showing fight vs character ranking differences
3. Use cases for when to use each type of ranking

Technical Considerations

• This uses FightRankingMetricType enum (different from character rankings)
• Fight rankings represent group/raid performance, not individual
• May need to handle pagination differently than character rankings

Acceptance Criteria

• Method successfully retrieves fight rankings for specific encounters
• Hard mode level filtering works correctly
• Leaderboard filtering works as expected
• Clear documentation distinguishes this from character rankings
• Integration tests verify real API behavior
• Error handling for invalid zone/encounter combinations

Priority

High - Completes the missing ranking functionality for true 100% API coverage

Related Issues

• Implement Encounter.characterRankings with advanced filtering options #47 - Implement Encounter.characterRankings (companion issue)