Implement Encounter.characterRankings with advanced filtering options

[knowlen]

Summary

Implement the missing Encounter.characterRankings GraphQL field that provides advanced filtering options not currently available in our Python client.

Background

The GraphQL schema exposes Encounter.characterRankings with additional parameters that our current implementation doesn't support:

• externalBuffs: ExternalBuffRankFilter - Filter rankings by external buff usage
• hardModeLevel: HardModeLevelRankFilter - Filter by specific hard mode levels (0-4)
• leaderboard: LeaderboardRank - Include/exclude ranks without backing logs

Current State

• We have get_character_encounter_rankings() which queries Character.encounterRankings
• This is missing the advanced filtering options available on Encounter.characterRankings

Implementation Steps

1. Add the GraphQL Query

Create a new query in queries.graphql:

query getEncounterCharacterRankings(
  $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: CharacterRankingMetricType
  $includeCombatantInfo: Boolean
  $className: String
  $specName: String
  $externalBuffs: ExternalBuffRankFilter
) {
  worldData {
    zone(id: $zoneId) {
      encounters {
        id
        name
        characterRankings(
          bracket: $bracket
          difficulty: $difficulty
          filter: $filter
          page: $page
          partition: $partition
          serverRegion: $serverRegion
          serverSlug: $serverSlug
          size: $size
          leaderboard: $leaderboard
          hardModeLevel: $hardModeLevel
          metric: $metric
          includeCombatantInfo: $includeCombatantInfo
          className: $className
          specName: $specName
          externalBuffs: $externalBuffs
        )
      }
    }
  }
}

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 GetEncounterCharacterRankings response class

3. Create the Client Method

Add to WorldDataMixin or create a new mixin:

async def get_encounter_character_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[CharacterRankingMetricType] = None,
    include_combatant_info: Optional[bool] = None,
    class_name: Optional[str] = None,
    spec_name: Optional[str] = None,
    external_buffs: Optional[ExternalBuffRankFilter] = None,
) -> GetEncounterCharacterRankings:
    """
    Get character rankings for a specific encounter with advanced filtering.
    
    This method provides additional filtering options not available in 
    get_character_encounter_rankings(), including external buff filtering,
    hard mode level filtering, and leaderboard rank filtering.
    """
    # Implementation details

4. Handle the Nested Response

The response will include all encounters for the zone, so we need to:

1. Filter the encounters list to find the matching encounter_id
2. Extract the characterRankings from that specific encounter
3. Handle the case where the encounter isn't found

5. Add Tests

1. Unit tests for parameter validation
2. Integration tests with real API calls
3. Test the new filtering parameters work correctly

6. Update Documentation

1. Add to API reference docs
2. Show examples using the advanced filters
3. Explain when to use this vs get_character_encounter_rankings()

Acceptance Criteria

• Method successfully queries encounter-specific rankings
• All three new filter parameters work correctly
• Proper error handling for invalid encounter IDs
• Documentation clearly explains the difference from existing methods
• Tests pass with >90% coverage

Priority

High - This represents missing API functionality that limits advanced use cases