rivalsdata-api 1.0.0__tar.gz

rivalsdata_api-1.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rivalsdata-api
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

rivalsdata_api-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

rivalsdata_api-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for helping improve rivalsdata-api. The client relies on undocumented
+RivalsData endpoints, so contributions should keep requests conservative and
+record how endpoint behavior was observed.
+
+## Development setup
+
+Use an isolated virtual environment:
+
+```console
+python -m venv .venv
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+# macOS or Linux
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+```
+
+Install the optional browser dependencies only when working on Camoufox:
+
+```console
+python -m pip install -e '.[browser,dev]'
+python -m camoufox fetch
+```
+
+The browser extra does not include GeoIP support because the project does not
+need geographic spoofing. A virtual environment also prevents this package's
+dependencies from changing unrelated applications installed in system Python.
+
+## Project map
+
+- `src/rivalsdata/client.py`: HTTP client, username resolution, UID lookup,
+  shared GET/POST handling, and the optional Camoufox retry.
+- `src/rivalsdata/models.py`: mapping-compatible response models and the typed
+  `Player` wrapper.
+- `src/rivalsdata/resources.py`: lazy player and site-wide endpoint resources.
+- `src/rivalsdata/exceptions.py`: public exception types.
+- `src/rivalsdata/__init__.py`: package exports and version.
+- `pyproject.toml`: build backend, package metadata, runtime and optional
+  dependencies.
+- `docs/API.md`: observed site sections, endpoint inventory, response samples,
+  and open questions.
+- `docs/PROJECT_CONTEXT.md`: contributor and new-chat handoff notes.
+
+## How the client currently works
+
+The client uses curl_cffi with browser TLS impersonation against
+`https://api.rivalsdata.com`:
+
+- `POST /players/search` with JSON `{"name": "..."}` returns search
+  suggestions. Search records include an `aid`, such as
+  `11001_1970288503`; the final numeric segment is the profile UID.
+- `POST /player` with JSON `{"uid": 1970288503}` returns a typed `Player`
+  object. Profile keys work as both mapping values and attributes.
+- Resource managers cover public leaderboard, hero, team-up, insight, faction,
+  match, and player-tab endpoints. See `docs/API.md` for the current inventory.
+- If these requests are blocked and `use_browser_fallback=True`, the client
+  loads RivalsData in Camoufox and retries the POST from the page context.
+
+These are observed implementation details, not a supported RivalsData contract.
+Do not assume that `aid` formats, filters, routes, or JSON fields are permanent.
+
+## Contribution workflow
+
+1. Check the existing public API and exception behavior before changing it.
+2. Keep changes focused, typed, and documented. Avoid adding new runtime
+   dependencies unless the feature needs them.
+3. For endpoint changes, note the page or action that exposed the route and
+   the request shape. Never commit cookies, tokens, or browser profile data.
+4. Add or update automated tests for behavior changes. Keep network-dependent
+   checks opt-in; routine tests should use mocked HTTP responses. The initial
+   repository does not yet include an automated test suite.
+5. Run the checks for the code you changed:
+
+   ```console
+   python -m pytest
+   ruff check .
+   python -m build
+   ```
+
+6. Update the README and project context if user-facing methods, dependencies,
+   routes, or setup steps changed.
+
+There is no live API compatibility guarantee. If RivalsData changes a route,
+prefer a clear typed error over returning an empty profile or silently
+mislabeling a search result.

rivalsdata_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rivalsdata-api contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rivalsdata_api-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: rivalsdata-api
+Version: 1.0.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
+Project-URL: Issues, https://github.com/GS-Rionnag/rivalsdata-api/issues
+Project-URL: Changelog, https://github.com/GS-Rionnag/rivalsdata-api/releases
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,game-stats,marvel-rivals,mcp,rivalsdata
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.7
+Provides-Extra: browser
+Requires-Dist: camoufox>=0.5.6; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp-ui-server>=1.0.0; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.12; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# 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
+
+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 also returns an MCP-UI player report with rank and
+competitive record, current match roster split by side, a hero win-rate chart,
+and recent match form with K/D/A. 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.
+
+### How the MCP UI works
+
+`show_player_dashboard` fetches current data, then returns an HTML UI resource
+alongside the tool result. MCP-UI labels it with a `ui://` resource URI and
+preferred size. A compatible host can render that resource in a sandboxed
+panel; a host without UI support can still use the regular MCP tools and their
+text/data responses. ChatGPT uses MCP-UI's Apps SDK adapter, while Claude is
+listed as supporting MCP Apps directly. The dashboard is a snapshot from the
+time the tool runs; ask for it again to refresh.
+
+### 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
+rivalsdata-mcp --transport streamable-http --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. Use `python -m rivalsdata.mcp_server --help` to see options.
+
+`Player` and returned `DataModel` objects support both mapping access and
+attribute access (`player["level"]` or `player.level`). Nested dictionaries
+and arrays are wrapped recursively; `.raw` returns a shallow copy of a model's
+original JSON. For endpoints whose fields evolve, these generic typed wrappers
+preserve the complete payload.
+
+## 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.0.0/README.md

@@ -0,0 +1,154 @@
+# 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
+
+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 also returns an MCP-UI player report with rank and
+competitive record, current match roster split by side, a hero win-rate chart,
+and recent match form with K/D/A. 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.
+
+### How the MCP UI works
+
+`show_player_dashboard` fetches current data, then returns an HTML UI resource
+alongside the tool result. MCP-UI labels it with a `ui://` resource URI and
+preferred size. A compatible host can render that resource in a sandboxed
+panel; a host without UI support can still use the regular MCP tools and their
+text/data responses. ChatGPT uses MCP-UI's Apps SDK adapter, while Claude is
+listed as supporting MCP Apps directly. The dashboard is a snapshot from the
+time the tool runs; ask for it again to refresh.
+
+### 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
+rivalsdata-mcp --transport streamable-http --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. Use `python -m rivalsdata.mcp_server --help` to see options.
+
+`Player` and returned `DataModel` objects support both mapping access and
+attribute access (`player["level"]` or `player.level`). Nested dictionaries
+and arrays are wrapped recursively; `.raw` returns a shallow copy of a model's
+original JSON. For endpoints whose fields evolve, these generic typed wrappers
+preserve the complete payload.
+
+## 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.0.0/docs/API.md

@@ -0,0 +1,90 @@
+# RivalsData API inventory
+
+This is an observed inventory of the public web client's API, gathered by
+reviewing the RivalsData UI and its browser requests on 2026-09-29. The upstream
+API is undocumented and can change. Field sets below are examples from live
+responses, not schemas guaranteed by RivalsData. Response bodies are returned
+as attribute-accessible `DataModel` / `StatRecord` objects, preserving unknown
+keys.
+
+## Implemented public read endpoints
+
+| Site section | HTTP endpoint | Parameters sent by this client | Observed response |
+| --- | --- | --- | --- |
+| 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 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`. |
+| Player proficiency | `POST /player/proficiency` | `uid` | Object keyed by account id (sample: `11001_{uid}`); inner structure varies. |
+| Player hero stats | `POST /player/stats/heroes` | `uid`, optional `season` | Array rows: `competitive`, `hero_id`, `quickplay`, `rank`. |
+| Player map stats | `POST /player/stats/maps` | `uid`, optional `season` | Array shape varies; captured from the profile Stats tab. |
+| Player ban stats | `POST /player/stats/bans` | `uid`, optional `season` | Array shape varies; captured from the profile Stats tab. |
+| Player punishments | `POST /player/punishments` | `uid` | Object keys observed: `chat`, `login`, `rank`. |
+| Player name history | `POST /player/name-history` | `uid` | Array rows: `first_seen`, `name`. |
+| Global leaderboard | `GET /leaderboards` | `limit`, optional `skip`, `season`, `os` (Python `platform`) | Object keys observed: `count`, `players`, `updated_at`; row keys: `heroes`, `icon`, `losses`, `name`, `os`, `position`, `rank_level`, `rank_score`, `season`, `status`, `uid`, `wins`. |
+| Hero tier list | `GET /stats/tierlist` | `platform`, `rank` | Hero rows displayed with tier, win rate, pick rate, ban rate, and games; raw row keys preserved. |
+| Hero detail | `GET /stats/heroes/{hero_id}` | Path parameter | Hero aggregate object; full key set varies by hero and season. |
+| Hero trend/meta | `GET /stats/meta/{hero_id}` | `range` (30, 90, or 180 days) | Trend/analytics object; raw keys preserved. |
+| Hero leaderboard | `GET /stats/leaderboards` | `hero` plus caller-supplied query filters | Used by hero leaderboard pages. Parameter combinations and response fields are not fully verified. |
+| Team-up stats | `GET /stats/teamups` | `platform`, `rank`, optional `hero` | Team-up usage and win-rate rows; raw keys preserved. |
+| Punishments log | `GET /stats/punishments` | `kind`, optional `cursor` | Object: `last_update`, `next`, `results`; sample row keys: `expires_at`, `icon`, `issued_at`, `kind`, `name`, `peak_rank_level`, `peak_rank_score`, `rank`, `reason`, `uid`. |
+| XP leaderboard | `GET /stats/xp` | Optional `cursor` | Object: `last_update`, `next`, `results`; sample row keys: `icon`, `name`, `rank`, `uid`, `xp`. |
+| Top 500 finishes | `GET /stats/oaa` | `os` (Python `platform`) | Object: `count`, `last_update`, `os`, `players`; sample row keys: `avg_placement`, `avg_score`, `finishes`, `icon`, `name`, `seasons`, `uid`. |
+| Hero comm-ban insight | `GET /stats/commbans` | `mode` (`all` or `competitive`) | Object: `heroes`, `last_update`, `mode`, `overall_pct`; hero rows: `ci95`, `hero_id`, `pct`, `qualifying_players`, `vs_avg`, `weighted_banned`, `weighted_players`. |
+| Hero AFK insight | `GET /stats/leavers` | `mode` (`all` or `competitive`) | Object: `heroes`, `last_update`, `mode`, `overall_pct`; hero rows: `ci95`, `games`, `hero_id`, `leaves`, `leaves_per_player`, `pct`, `players`, `vs_avg`. |
+| Faction details | `GET /faction/{faction_id}` | Path parameter | Faction overview, public profile/member list, and results; nested schema varies. |
+| Match details | `POST /match` | `{"match_id": "..."}` | Object keys observed: `match_uid`, `replay_id`, `winner_camp`, `duration_seconds`, `map_id`, `game_mode_id`, `game_play_mode_id`, `platform`, `timestamp`, `draft`, `teams`; team player rows include combat stats and per-hero usage. |
+| Public profile card | `GET /profiles/{username}` | Username path parameter | Route observed in the profile frontend; complete response schema not captured. |
+| Favorites lookup | `POST /favorites` | `{"uids": [uid, ...]}` | Request observed in frontend assets; response schema not captured. |
+
+The client exposes these read resources through `RivalsDataClient` and `Player`;
+see README examples and method docstrings. `DataModel.win_rate` returns an
+integer percentage from a direct win-rate field, `wins`/`losses`, or the
+competitive profile row's `win_count`/`battle_count`. If the source provides
+none of these, it returns `None`.
+
+## Observed UI and routes
+
+| UI route | What the UI exposes |
+| --- | --- |
+| `/` | Search, top leaderboard, favorites, top heroes, and top team-ups. |
+| `/leaderboard` | Name filter, online-only switch, platform, season, refresh, and player rows. |
+| `/stats` | Hero tier list with rank/platform/role filters and tier/win/pick/ban/games sorting. |
+| `/team-ups` | Team-up pairings with hero, rank, and platform filters. |
+| `/insights/punishments`, `/insights/xp`, `/insights/oaa`, `/insights/toxicity`, `/insights/afk` | Punishment log, XP ranking, Top 500 finishes, hero comm-ban rate, and hero AFK rate. |
+| `/player/{uid}` | Overview, hero summaries, teammates, crosshairs, Match History, Live Game, Proficiency, Stats, Punishments, and Name History tabs. Match History may be private. |
+| `/heroes/{slug}/stats` | Hero statistics and selectable 30/90/180-day charts. |
+| `/heroes/{slug}/leaderboard` | Hero-specific ranked players. |
+| `/heroes/{slug}/counters` and `/heroes/{slug}/synergy` | The UI displayed “Coming Soon” during inspection; no public data call was observed. |
+| `/factions/{faction_id}` | Faction description and members. |
+| `/matches/{match_id}` | Match detail route linked from an expanded public match-history card. |
+| `/profiles` | Account-facing profile management page. |
+
+The Live Game tab requests `POST /live` for profiles whose `status.battle_id`
+is set. The client exposes this as `player.live_game.fetch()`. Since game status
+can change, load a fresh player profile before fetching; the method returns
+`None` when that profile has no active battle ID.
+
+## Account actions and unresolved endpoints
+
+Frontend assets also reference `GET /profiles`, `POST /profiles/{username}/edit`,
+`POST /bind/start`, and `POST /bind/check`. These are associated with profile
+management and account linking. Their complete request/response contracts and
+authentication behavior were not established. Profile edit and bind routes
+can modify account state; they are documented here for completeness but are
+not implemented as public methods. `GET /profiles/{username}` and
+`POST /favorites` have thin read wrappers, but their response schemas remain
+unverified.
+
+Other open research items:
+
+- Capture response bodies for the remaining Insights mode/filter variants.
+- Verify the hero leaderboard query parameters and faction response shape from
+  real visible links.
+- Determine whether match-history cursor pagination and the uncached route
+  remain available for accounts that have made history public.
+- Recheck this inventory when the site changes. Do not infer a supported API
+  contract from a route string alone.