rivalsdata-api 1.1.0__tar.gz → 1.2.0__tar.gz

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.1.0
+Version: 1.2.0
 Summary: Python client and MCP server for public Marvel Rivals stats from RivalsData
 Project-URL: Homepage, https://github.com/GS-Rionnag/rivalsdata-api
 Project-URL: Repository, https://github.com/GS-Rionnag/rivalsdata-api
@@ -67,6 +67,7 @@ with RivalsDataClient() as rd:
 
     # Player profile sections are lazy resource managers.
     hero_season = player.heroes.fetch(season=20)
+    all_hero_seasons = player.heroes.fetch(season="all")
     map_stats = player.stats.maps(season=20)
     match_page = player.matches.fetch(season=20)
 
@@ -84,6 +85,37 @@ with RivalsDataClient() as rd:
 print(hero_season[0].win_rate)  # integer percent when wins/losses are present
 ```
 
+Calculated player class statistics are available through
+`player.stats.classes(season=20)` and the MCP `get_player_stats` tool with
+`category="classes"`. Each row contains `player_class` (`tank`, `support`,
+`dps`), the official role, hero IDs, and separate `competitive` and `quickplay`
+totals for games, wins, losses, and available MVP/SVP counts.
+
+```python
+with RivalsDataClient() as rd:
+    stats = rd.get_player("GS-").stats.classes(season=20)
+    for row in stats.classes:
+        print(row.player_class, row.competitive.win_rate)
+    print(stats.excluded)  # Unknown roles or incomplete win/loss records
+```
+
+Win rates are `total wins / (total wins + total losses)`, rounded to an integer
+percent. They are weighted by hero records, rather than averaging hero win
+rates. Switching heroes can make one match contribute to multiple records;
+these totals describe hero participation, not distinct matches. Empty modes
+have a `None` win rate. Role mappings were observed on RivalsData on
+2026-09-30, including Deadpool's separate role IDs; generic Deadpool and unknown
+IDs are excluded rather than assigned a guessed class.
+
+Character playtime was checked with Camoufox on 2026-09-30. Player hero stats
+did not expose cumulative hours, including in All Seasons. Match details do
+provide seconds in `match.teams[].players[].heroes[].play_time`; the site shows
+these as minutes and seconds when hovering a hero portrait. Sum the relevant
+player's entries across distinct retrieved matches and divide by 3600 to get
+character hours for those matches. Incomplete history prevents treating this as
+a lifetime total. See [the playtime investigation](docs/API.md#character-playtime-investigation-2026-09-30)
+for the observed fields and example.
+
 ## MCP server (ChatGPT and Claude)
 
 Install the MCP extra and the package:

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/README.md

@@ -1,70 +1,102 @@
-# rivalsdata-api
-
-An unofficial Python client for RivalsData's public Marvel Rivals data. It
-uses the site's undocumented API, so routes and fields can change. The client
-keeps unknown response fields accessible instead of discarding them.
-
-## Install
-
-Python 3.10 or newer:
-
-```console
-python -m pip install rivalsdata-api
-```
-
-For editable development, clone the repository and run
-`python -m pip install -e '.[dev]'`. The optional Camoufox Cloudflare fallback
-is installed with `python -m pip install 'rivalsdata-api[browser]'`, followed
-by `python -m camoufox fetch`.
-
-## Quick start
-
-```python
+# rivalsdata-api
+
+An unofficial Python client for RivalsData's public Marvel Rivals data. It
+uses the site's undocumented API, so routes and fields can change. The client
+keeps unknown response fields accessible instead of discarding them.
+
+## Install
+
+Python 3.10 or newer:
+
+```console
+python -m pip install rivalsdata-api
+```
+
+For editable development, clone the repository and run
+`python -m pip install -e '.[dev]'`. The optional Camoufox Cloudflare fallback
+is installed with `python -m pip install 'rivalsdata-api[browser]'`, followed
+by `python -m camoufox fetch`.
+
+## Quick start
+
+```python
 from rivalsdata import RivalsDataClient, hero_id, hero_name
 
 print(hero_name(1016))  # Loki
 print(hero_id("Loki"))  # 1016
-
-with RivalsDataClient() as rd:
-    player = rd.get_player("GS-")  # numeric UID works too
-    print(player.name, player.level, player.rank_game_season)
-
-    # Player profile sections are lazy resource managers.
-    hero_season = player.heroes.fetch(season=20)
-    map_stats = player.stats.maps(season=20)
-    match_page = player.matches.fetch(season=20)
-
-    # Current match (None if the profile is not currently in a game).
-    live_game = player.live_game.fetch()
-    if live_game is not None:
-        print(live_game.players, live_game.team_avg_rank)
-
-    # Site-wide resources are available from the client.
-    leaderboard = rd.leaderboards.fetch(limit=100, season=20, platform=1)
-    tier_list = rd.heroes.tier_list(platform=1, rank="grandmaster_plus")
-    team_ups = rd.team_ups.fetch(platform=1, rank="grandmaster_plus")
-    xp_page = rd.insights.xp()
-
-print(hero_season[0].win_rate)  # integer percent when wins/losses are present
-```
-
-## MCP server (ChatGPT and Claude)
-
-Install the MCP extra and the package:
-
-```console
-python -m pip install 'rivalsdata-api[mcp]'
-```
-
-The server exposes read-only tools for player search and profiles, a player's
-current live match (when they are in one), match history, player stats,
-leaderboards, heroes, team-ups, public insights, matches, and factions. The
-`show_player_dashboard` tool returns an MCP-UI player card with rank and
-competitive record plus one optional data section per call: current match
-roster, hero win-rate chart, or recent match form with K/D/A. This keeps each
-dashboard pull to the profile plus at most one additional endpoint. It supports
-local stdio for Claude Desktop
-and Streamable HTTP for remote MCP clients such as ChatGPT. Data comes from
+
+with RivalsDataClient() as rd:
+    player = rd.get_player("GS-")  # numeric UID works too
+    print(player.name, player.level, player.rank_game_season)
+
+    # Player profile sections are lazy resource managers.
+    hero_season = player.heroes.fetch(season=20)
+    all_hero_seasons = player.heroes.fetch(season="all")
+    map_stats = player.stats.maps(season=20)
+    match_page = player.matches.fetch(season=20)
+
+    # Current match (None if the profile is not currently in a game).
+    live_game = player.live_game.fetch()
+    if live_game is not None:
+        print(live_game.players, live_game.team_avg_rank)
+
+    # Site-wide resources are available from the client.
+    leaderboard = rd.leaderboards.fetch(limit=100, season=20, platform=1)
+    tier_list = rd.heroes.tier_list(platform=1, rank="grandmaster_plus")
+    team_ups = rd.team_ups.fetch(platform=1, rank="grandmaster_plus")
+    xp_page = rd.insights.xp()
+
+print(hero_season[0].win_rate)  # integer percent when wins/losses are present
+```
+
+Calculated player class statistics are available through
+`player.stats.classes(season=20)` and the MCP `get_player_stats` tool with
+`category="classes"`. Each row contains `player_class` (`tank`, `support`,
+`dps`), the official role, hero IDs, and separate `competitive` and `quickplay`
+totals for games, wins, losses, and available MVP/SVP counts.
+
+```python
+with RivalsDataClient() as rd:
+    stats = rd.get_player("GS-").stats.classes(season=20)
+    for row in stats.classes:
+        print(row.player_class, row.competitive.win_rate)
+    print(stats.excluded)  # Unknown roles or incomplete win/loss records
+```
+
+Win rates are `total wins / (total wins + total losses)`, rounded to an integer
+percent. They are weighted by hero records, rather than averaging hero win
+rates. Switching heroes can make one match contribute to multiple records;
+these totals describe hero participation, not distinct matches. Empty modes
+have a `None` win rate. Role mappings were observed on RivalsData on
+2026-09-30, including Deadpool's separate role IDs; generic Deadpool and unknown
+IDs are excluded rather than assigned a guessed class.
+
+Character playtime was checked with Camoufox on 2026-09-30. Player hero stats
+did not expose cumulative hours, including in All Seasons. Match details do
+provide seconds in `match.teams[].players[].heroes[].play_time`; the site shows
+these as minutes and seconds when hovering a hero portrait. Sum the relevant
+player's entries across distinct retrieved matches and divide by 3600 to get
+character hours for those matches. Incomplete history prevents treating this as
+a lifetime total. See [the playtime investigation](docs/API.md#character-playtime-investigation-2026-09-30)
+for the observed fields and example.
+
+## MCP server (ChatGPT and Claude)
+
+Install the MCP extra and the package:
+
+```console
+python -m pip install 'rivalsdata-api[mcp]'
+```
+
+The server exposes read-only tools for player search and profiles, a player's
+current live match (when they are in one), match history, player stats,
+leaderboards, heroes, team-ups, public insights, matches, and factions. The
+`show_player_dashboard` tool returns an MCP-UI player card with rank and
+competitive record plus one optional data section per call: current match
+roster, hero win-rate chart, or recent match form with K/D/A. This keeps each
+dashboard pull to the profile plus at most one additional endpoint. It supports
+local stdio for Claude Desktop
+and Streamable HTTP for remote MCP clients such as ChatGPT. Data comes from
 RivalsData's undocumented API and may change; profile match history can be
 private.
 
@@ -75,9 +107,9 @@ a hero name or numeric ID. The pip package also exports `hero_name(id)` and
 `.top_hero_name` conveniences. Those resolved fields are included in mapping
 iteration and `.to_dict()` output to simplify serialization; `.raw` remains the
 untouched source payload.
-
-### How the MCP UI works
-
+
+### How the MCP UI works
+
 `show_player_dashboard` fetches current data, then returns an HTML UI resource
 alongside the tool result. It advertises the dashboard through
 `_meta.ui.resourceUri`, uses the `text/html;profile=mcp-app` resource MIME type,
@@ -88,44 +120,44 @@ also includes `openai/outputTemplate` as a ChatGPT compatibility alias. Hosts
 without UI support still receive a text result and can use the regular MCP
 tools. The dashboard is a snapshot from the time the tool runs; ask for it
 again to refresh.
-The `section` argument defaults to `live_match`; use `hero_form` or
-`recent_matches` in separate calls when you need those views.
-
-### Claude Desktop (local)
-
-Add a server entry to Claude Desktop's `claude_desktop_config.json`, replacing
-the path with the Python executable in the environment where the extra is
-installed:
-
-```json
-{
-  "mcpServers": {
-    "rivalsdata": {
-      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
-      "args": ["-m", "rivalsdata.mcp_server"]
-    }
-  }
-}
-```
-
-On macOS/Linux, use the environment's `bin/python` path. Restart Claude Desktop
-after saving the configuration.
-
-### ChatGPT or remote Claude connector
-
-Run the server on a host reachable over HTTPS:
-
-```console
-uvicorn rivalsdata.mcp_server:app --host 0.0.0.0 --port 8000
-```
-
-The MCP endpoint is `/mcp` (for example, `https://your-host.example/mcp`). Add
-that endpoint through the client's custom/remote MCP connector settings. The
-server does not implement authentication; put it behind an authenticated
-HTTPS gateway before exposing it publicly. For local development, bind to
-`127.0.0.1` instead. The `app` is the MCP SDK's Streamable HTTP ASGI
-application; Uvicorn manages its lifespan and session manager.
-
+The `section` argument defaults to `live_match`; use `hero_form` or
+`recent_matches` in separate calls when you need those views.
+
+### Claude Desktop (local)
+
+Add a server entry to Claude Desktop's `claude_desktop_config.json`, replacing
+the path with the Python executable in the environment where the extra is
+installed:
+
+```json
+{
+  "mcpServers": {
+    "rivalsdata": {
+      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
+      "args": ["-m", "rivalsdata.mcp_server"]
+    }
+  }
+}
+```
+
+On macOS/Linux, use the environment's `bin/python` path. Restart Claude Desktop
+after saving the configuration.
+
+### ChatGPT or remote Claude connector
+
+Run the server on a host reachable over HTTPS:
+
+```console
+uvicorn rivalsdata.mcp_server:app --host 0.0.0.0 --port 8000
+```
+
+The MCP endpoint is `/mcp` (for example, `https://your-host.example/mcp`). Add
+that endpoint through the client's custom/remote MCP connector settings. The
+server does not implement authentication; put it behind an authenticated
+HTTPS gateway before exposing it publicly. For local development, bind to
+`127.0.0.1` instead. The `app` is the MCP SDK's Streamable HTTP ASGI
+application; Uvicorn manages its lifespan and session manager.
+
 Every implemented response route now has named endpoint models and row models
 with annotations for fields observed in the API inventory. This includes
 `Player`, `Match`, `MatchHistory`, `MatchTeam`, `MatchPlayer`, `Character`,
@@ -151,43 +183,43 @@ with RivalsDataClient() as rd:
     tier_list = rd.heroes.tier_list()               # TierListResponse
     print(tier_list.heroes[0].hero_id)             # Character
 ```
-
-## Public resources
-
-- `rd.leaderboards.fetch(...)` — global player ranking.
-- `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
-  `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
-- `rd.team_ups.fetch(...)` — team-up stats.
-- `rd.insights.punishments(...)`, `.xp(...)`, `.top_500(...)`, `.commbans(...)`,
-  `.leavers(...)` — public insights and cursor metadata.
-- `rd.factions.get(faction_id)`, `rd.matches.get(match_id)`,
-  `rd.profiles.get(username)`, and `rd.favorites.fetch(uids)` — detail/profile
-  lookups.
-- `player.heroes.fetch(...)`, `.matches.fetch(...)`, `.live_game.fetch()`, `.teammates.fetch(...)`,
-  `.crosshairs.fetch()`, `.proficiency.fetch()`, `.punishments.fetch()`,
-  `.name_history.fetch()` — profile sections.
-- `player.stats.heroes(...)`, `.maps(...)`, `.bans(...)` — detailed profile stats.
-
-See [the observed API inventory](docs/API.md) for methods, parameters, observed
-response shapes, and endpoints that require a RivalsData account. The API
-inventory distinguishes observed behavior from inferred/unverified details.
-
-## Cloudflare fallback
-
-Requests use curl_cffi with a Chrome TLS profile by default. If blocked, enable
-the optional browser fallback:
-
-```python
-with RivalsDataClient(use_browser_fallback=True) as rd:
-    player = rd.get_player(1970288503)
-```
-
-## Errors and contributions
-
-All package exceptions inherit from `RivalsDataError`. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for setup, code layout, change workflow, and
-notes for new contributors. [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md)
-is the handoff document for new coding sessions.
-
-This project is not affiliated with RivalsData, NetEase, or Marvel. Keep
-request rates reasonable and respect the site's terms.
+
+## Public resources
+
+- `rd.leaderboards.fetch(...)` — global player ranking.
+- `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
+  `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
+- `rd.team_ups.fetch(...)` — team-up stats.
+- `rd.insights.punishments(...)`, `.xp(...)`, `.top_500(...)`, `.commbans(...)`,
+  `.leavers(...)` — public insights and cursor metadata.
+- `rd.factions.get(faction_id)`, `rd.matches.get(match_id)`,
+  `rd.profiles.get(username)`, and `rd.favorites.fetch(uids)` — detail/profile
+  lookups.
+- `player.heroes.fetch(...)`, `.matches.fetch(...)`, `.live_game.fetch()`, `.teammates.fetch(...)`,
+  `.crosshairs.fetch()`, `.proficiency.fetch()`, `.punishments.fetch()`,
+  `.name_history.fetch()` — profile sections.
+- `player.stats.heroes(...)`, `.maps(...)`, `.bans(...)` — detailed profile stats.
+
+See [the observed API inventory](docs/API.md) for methods, parameters, observed
+response shapes, and endpoints that require a RivalsData account. The API
+inventory distinguishes observed behavior from inferred/unverified details.
+
+## Cloudflare fallback
+
+Requests use curl_cffi with a Chrome TLS profile by default. If blocked, enable
+the optional browser fallback:
+
+```python
+with RivalsDataClient(use_browser_fallback=True) as rd:
+    player = rd.get_player(1970288503)
+```
+
+## Errors and contributions
+
+All package exceptions inherit from `RivalsDataError`. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup, code layout, change workflow, and
+notes for new contributors. [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md)
+is the handoff document for new coding sessions.
+
+This project is not affiliated with RivalsData, NetEase, or Marvel. Keep
+request rates reasonable and respect the site's terms.

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/docs/API.md

@@ -16,7 +16,7 @@ and `.raw` so upstream additions are not discarded.
 | Search | `POST /players/search` | `{"name": name}` | Search rows; `aid` may contain the numeric UID after the final `_`. |
 | Player overview | `POST /player` | `{"uid": number}` | Object keys observed: `cached_at`, `claimed`, `faction`, `icon`, `last_seen`, `leaderboard`, `level`, `login_os`, `match_history_is_visible`, `mood`, `name`, `rank_game_season`, `status`, `uid`, `xp`. `rank_game_season` is keyed by game/season ids; competitive rows include `battle_count`, `rank_game_id`, `rank_score`, and `win_count`. |
 | Player live game | `POST /live` | `{"match_id": status.battle_id, "uid": number}` | Object keys observed: `players` (12 player entries keyed by team slot) and `team_avg_rank` (rank averages keyed by side). Player rows include `ai`, `games`, `icon`, `losses`, `name`, `proficiency`, `rank`, `side`, `team_id`, `top_heroes`, `uid`, and `wins`. The match ID comes from the player's current `/player` response; the endpoint was observed on a profile marked `In game (Competitive)`. |
-| Player hero summary | `POST /player/heroes` | `uid`, optional `season` | Array rows: `assists`, `deaths`, `games`, `hero_id`, `kda`, `kills`, `losses`, `rank`, `wins`. |
+| Player hero summary | `POST /player/heroes` | `uid`, optional `season`; wrapper `season="all"` sends season ID `-1` | Array rows: `assists`, `deaths`, `games`, `hero_id`, `kda`, `kills`, `losses`, `rank`, `wins`. The all-seasons selector was verified against the public `GS-` profile; `season=-1` returned 40 hero rows, while `season=0` returned none. |
 | Player crosshairs | `POST /player/crosshairs` | `uid` | Array rows: `crosshair`, `uses`. |
 | Player match history | `POST /player/matches/cached` (or `/player/matches`) | `uid`, `cursor`, optional `season`; cached endpoint also accepts `mode`, `hero`, `teammate` | Cached response keys observed: `matches`, `next_cursor`, `source`; match rows include `assists`, `deaths`, `game_mode_id`, `game_play_mode_id`, `hero_id`, `is_mvp`, `is_svp`, `is_win`, `kills`, `map_id`, `match_uid`, `os`, `placement`, `platform`, `rank_level`, `rank_score`, `score_change`, `season`, `team_score`, `timestamp`, `winner_camp`. A sample profile marked its history private; a private profile can return no visible match rows. |
 | Player teammates | `POST /player/teammates` | `uid`, optional `season`, `mode` | Array rows: `games`, `icon`, `losses`, `name`, `teammate_uid`, `wins`. |
@@ -50,6 +50,41 @@ none of these, it returns `None`.
 
 ## Observed UI and routes
 
+`player.stats.classes(season=...)` derives tank (Vanguard), support (Strategist),
+and DPS (Duelist) totals from `/player/stats/heroes`; it does not call a class
+endpoint. It sums games/wins/losses separately for competitive and quickplay,
+and MVP/SVP counts when every included row supplies them. Win rate is calculated
+from summed wins and losses. Unknown classes and incomplete win/loss rows appear
+in `excluded`. Hero switching can count a single match in multiple hero records,
+so class totals are participation counts rather than distinct matches.
+
+The roster at `/stats` on 2026-09-30 identifies Deadpool variants as 10571
+(tank), 10572 (DPS), and 10573 (support), Daredevil as 1055, and Angela as 1056.
+
+### Character playtime investigation (2026-09-30)
+
+Using Camoufox (the package's optional browser dependency), the public GS-
+profile (`1970288503`) was inspected in Stats > Heroes for the current season
+and All Seasons. Expanded hero cards showed games, wins/losses, win rate, KDA,
+accuracy, MVP/SVP counts, combat averages, and team-ups. Neither the UI nor the
+captured `/player/heroes` and `/player/stats/heroes` responses supplied cumulative
+hero playtime. The all-seasons stats request returned 49 hero rows, including
+Deadpool's distinct role variants.
+
+Match details do expose per-character time in seconds at
+`teams[].players[].heroes[].play_time`. For match
+`5518155_1790655030_1272083_11001_11`, the match duration was 584 seconds and GS-'s
+Loki entry contained `play_time=583.8668914120644`. Hovering the hero portrait
+displayed `Loki` and `9:43`. The observed frontend formatter takes
+`floor(play_time / 60)` minutes and `floor(play_time % 60)` seconds.
+
+Hours for a character over a supplied set of matches can be calculated by
+summing that player's matching hero entries and dividing by 3600. Include all
+matching entries (a hero can have multiple usage segments), and deduplicate
+match IDs. This produces time for the retrieved matches, not a guaranteed
+lifetime or season total: history and detail availability may be incomplete.
+No automatic bulk match fetch was added as part of class statistics.
+
 | UI route | What the UI exposes |
 | --- | --- |
 | `/` | Search, top leaderboard, favorites, top heroes, and top team-ups. |

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/docs/PROJECT_CONTEXT.md

@@ -15,7 +15,7 @@ as public, stable methods. Keep requests respectful and conservative.
 ## Current package
 
 - Distribution: `rivalsdata-api`; import: `rivalsdata`.
-- Version: `1.1.0`.
+- Version: `1.2.0`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsDataClient`.
@@ -45,7 +45,7 @@ copy of the full response.
 Lazy subresources include `player.heroes.fetch(...)`, `player.matches.fetch(...)`,
 `player.teammates.fetch(...)`, `player.crosshairs.fetch()`,
 `player.proficiency.fetch()`, `player.punishments.fetch()`,
-`player.name_history.fetch()`, and `player.stats.heroes/maps/bans(...)`.
+`player.name_history.fetch()`, and `player.stats.heroes/maps/bans/classes(...)`.
 Client-wide resources include `client.leaderboards`, `client.heroes`,
 `client.team_ups`, `client.insights`, `client.factions`, and `client.matches`.
 `client.profiles` and `client.favorites` have typed read methods. The profile
@@ -54,6 +54,21 @@ Favorites requires numeric UIDs and returns player summary rows.
 Rows offer `.win_rate` and `.winrate` integer-percent access when data supports
 it; all original data remains in mapping access.
 
+`player.stats.classes(season=...)` groups observed hero IDs into tank, support,
+and DPS. It sums games, wins, losses, and available MVP/SVP counts separately
+for competitive and quickplay, with win rates calculated from summed wins and
+losses. The response has typed `classes` rows and an `excluded` list for unknown
+roles or incomplete win/loss data. MCP exposes it through `get_player_stats`
+with `category="classes"`. Hero switching means totals count participation,
+not unique matches. Role IDs and the corrected Angela/Daredevil IDs were
+verified against RivalsData's roster on 2026-09-30; Deadpool has separate role
+variants (10571/10572/10573), while generic 1057 remains unclassified.
+
+Camoufox inspection found no cumulative hero hours in current-season or
+all-seasons player stats. Match hero usage does include `play_time` in seconds.
+See `docs/API.md` for the recorded investigation; no playtime aggregation
+method was added.
+
 ## Observed API details
 
 The major UI areas inspected are home, player profile/tabs, global leaderboard,
@@ -103,7 +118,7 @@ Use a virtual environment. Install editable dependencies with
 fallback work. The global host Python has unrelated package conflicts; don't
 change global dependencies to resolve those.
 
-No automated test suite is currently tracked. Don't add network-dependent
-checks to routine development; use mocked tests when the project owner asks for
-tests. Ruff and wheel builds are available for code checks. Commit coherent
+Mocked tests in `tests/` cover hero lookups, typed responses, and calculated
+class stats. Keep network-dependent checks opt-in. Run pytest, Ruff, and package
+builds for code checks. Commit coherent
 milestones and push to `origin` when explicitly requested by the project owner.

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rivalsdata-api"
-version = "1.1.0"
+version = "1.2.0"
 description = "Python client and MCP server for public Marvel Rivals stats from RivalsData"
 keywords = ["marvel-rivals", "rivalsdata", "game-stats", "api-client", "mcp"]
 readme = "README.md"

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/src/rivalsdata/__init__.py

@@ -7,10 +7,13 @@ from .exceptions import (
     RivalsDataError,
     RivalsDataHTTPError,
 )
-from .hero_ids import HERO_NAMES, hero_id, hero_name
+from .hero_ids import HERO_CLASSES, HERO_NAMES, hero_class, hero_id, hero_name
 from .models import (
     BanRecord,
     Character,
+    ClassModeStats,
+    ClassStatsRecord,
+    ClassStatsResponse,
     CombatAverages,
     CommBanHero,
     CommBanInsights,
@@ -74,9 +77,13 @@ from .models import (
 )
 
 __all__ = [
+    "HERO_CLASSES",
     "HERO_NAMES",
     "BanRecord",
     "Character",
+    "ClassModeStats",
+    "ClassStatsRecord",
+    "ClassStatsResponse",
     "CloudflareError",
     "CombatAverages",
     "CommBanHero",
@@ -142,7 +149,8 @@ __all__ = [
     "Top500Season",
     "XPPage",
     "XPRecord",
+    "hero_class",
     "hero_id",
     "hero_name",
 ]
-__version__ = "1.1.0"
+__version__ = "1.2.0"

{rivalsdata_api-1.1.0 → rivalsdata_api-1.2.0}/src/rivalsdata/hero_ids.py

@@ -46,9 +46,12 @@ HERO_NAMES: dict[str, str] = {
     "1052": "Iron Fist",
     "1053": "Emma Frost",
     "1054": "Phoenix",
-    "1055": "Angela",
-    "1056": "Daredevil",
+    "1055": "Daredevil",
+    "1056": "Angela",
     "1057": "Deadpool",
+    "10571": "Tankpool",
+    "10572": "DPSpool",
+    "10573": "Stratpool",
     "1058": "Gambit",
     "1059": "Elsa Bloodstone",
     "1060": "White Fox",
@@ -61,6 +64,30 @@ HERO_NAMES: dict[str, str] = {
     "1067": "Gorr the God Butcher",
 }
 
+# Observed on https://rivalsdata.com/stats on 2026-09-30. The unspecialized
+# Deadpool ID (1057) has no single role and is deliberately left unresolved.
+HERO_CLASSES: dict[str, str] = {
+    **dict.fromkeys((
+        "1011", "1018", "1022", "1027", "1035", "1037", "1039", "1042",
+        "1051", "1053", "1056", "1062", "1065", "1066", "10571",
+    ), "tank"),
+    **dict.fromkeys((
+        "1016", "1020", "1023", "1025", "1028", "1031", "1046", "1047",
+        "1050", "1058", "1060", "1064", "10573",
+    ), "support"),
+    **dict.fromkeys((
+        "1014", "1015", "1017", "1021", "1024", "1026", "1029", "1030",
+        "1032", "1033", "1034", "1036", "1038", "1040", "1041", "1043",
+        "1044", "1045", "1048", "1049", "1052", "1054", "1055", "1059",
+        "1061", "1063", "1067", "10572",
+    ), "dps"),
+}
+
+
+def hero_class(hero_id: object) -> str | None:
+    """Return tank, support, or dps for a known role-specific hero ID."""
+    return HERO_CLASSES.get(str(hero_id))
+
 
 def hero_name(hero_id: object) -> str | None:
     """Resolve a known playable hero ID, preserving unknown IDs for callers."""