rivalsdata-api 1.0.0__py3-none-any.whl

rivalsdata/resources.py

@@ -0,0 +1,248 @@
+"""Resource managers for public non-player and player-section endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .models import DataModel, StatRecord
+
+
+def _one(value: Any) -> Any:
+    return DataModel(value) if isinstance(value, dict) else value
+
+
+def _many(value: Any) -> Any:
+    if isinstance(value, list):
+        return [StatRecord(row) if isinstance(row, dict) else row for row in value]
+    return _one(value)
+
+
+class Leaderboards:
+    """Global player leaderboard resource (``GET /leaderboards``)."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def fetch(
+        self, *, limit: int = 100, skip: int = 0, season: int | None = None,
+        platform: int | str | None = None,
+    ) -> DataModel | list[Any]:
+        params: dict[str, Any] = {"limit": limit}
+        if skip:
+            params["skip"] = skip
+        if season is not None:
+            params["season"] = season
+        if platform is not None:
+            params["os"] = platform
+        return _one(self._client._get_json("/leaderboards", params=params))
+
+
+class HeroStats:
+    """Aggregate hero tier-list, detail, trend, and leaderboard data."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def tier_list(
+        self, *, platform: int | str = 1, rank: str = "grandmaster_plus"
+    ) -> Any:
+        return _many(self._client._get_json(
+            "/stats/tierlist", params={"platform": platform, "rank": rank}
+        ))
+
+    def get(self, hero_id: str | int) -> Any:
+        return _one(self._client._get_json(f"/stats/heroes/{quote(str(hero_id))}"))
+
+    def meta(self, hero_id: str | int, *, range: int = 90) -> Any:
+        if range not in (30, 90, 180):
+            raise ValueError("range must be 30, 90, or 180 days")
+        return _one(self._client._get_json(
+            f"/stats/meta/{quote(str(hero_id))}", params={"range": range}
+        ))
+
+    def leaderboard(self, hero_id: str | int, **filters: Any) -> Any:
+        """Fetch a hero-specific leaderboard; filters pass through as query args."""
+        params = {"hero": hero_id, **filters}
+        return _many(self._client._get_json("/stats/leaderboards", params=params))
+
+
+class TeamUps:
+    """Global team-up analytics (``GET /stats/teamups``)."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def fetch(self, *, platform: int | str = 1, rank: str = "grandmaster_plus") -> Any:
+        return _many(self._client._get_json(
+            "/stats/teamups", params={"platform": platform, "rank": rank}
+        ))
+
+
+class Insights:
+    """Public site-wide insights pages and their pagination metadata."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def punishments(self, *, kind: str = "login", cursor: str | None = None) -> Any:
+        params: dict[str, Any] = {"kind": kind}
+        if cursor:
+            params["cursor"] = cursor
+        return _one(self._client._get_json("/stats/punishments", params=params))
+
+    def xp(self, *, cursor: str | None = None) -> Any:
+        params = {"cursor": cursor} if cursor else None
+        return _one(self._client._get_json("/stats/xp", params=params))
+
+    def top_500(self, *, platform: int | str = 1) -> Any:
+        return _one(self._client._get_json("/stats/oaa", params={"os": platform}))
+
+    def commbans(self, *, mode: str = "all") -> Any:
+        return _one(self._client._get_json("/stats/commbans", params={"mode": mode}))
+
+    def leavers(self, *, mode: str = "all") -> Any:
+        return _one(self._client._get_json("/stats/leavers", params={"mode": mode}))
+
+
+class Factions:
+    """Faction pages (``GET /faction/{faction_id}``)."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def get(self, faction_id: str | int) -> Any:
+        return _one(self._client._get_json(f"/faction/{quote(str(faction_id))}"))
+
+
+class Profiles:
+    """Public profile-card pages (response schema is not fully mapped)."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def get(self, username: str) -> Any:
+        if not username.strip():
+            raise ValueError("username must not be empty")
+        return _one(self._client._get_json(
+            f"/profiles/{quote(username.strip(), safe='')}"
+        ))
+
+
+class Favorites:
+    """Fetch profile summaries for a supplied list of favorite UIDs."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def fetch(self, uids: list[str | int]) -> Any:
+        return _many(self._client._post_json("/favorites", {"uids": [str(uid) for uid in uids]}))
+
+
+class PlayerResource:
+    def __init__(self, client: Any, uid: int) -> None:
+        self._client = client
+        self.uid = uid
+
+    def _post(self, path: str, **payload: Any) -> Any:
+        return self._client._post_json(path, {"uid": self.uid, **payload})
+
+
+class PlayerHeroes(PlayerResource):
+    """Per-player hero summary rows from ``POST /player/heroes``."""
+
+    def fetch(self, *, season: int | None = None) -> Any:
+        payload = {"season": season} if season is not None else {}
+        return _many(self._post("/player/heroes", **payload))
+
+
+class PlayerStats(PlayerResource):
+    """Detailed per-player statistics tabs."""
+
+    def heroes(self, *, season: int | None = None) -> Any:
+        payload = {"season": season} if season is not None else {}
+        return _many(self._post("/player/stats/heroes", **payload))
+
+    def maps(self, *, season: int | None = None) -> Any:
+        payload = {"season": season} if season is not None else {}
+        return _many(self._post("/player/stats/maps", **payload))
+
+    def bans(self, *, season: int | None = None) -> Any:
+        payload = {"season": season} if season is not None else {}
+        return _many(self._post("/player/stats/bans", **payload))
+
+
+class PlayerMatches(PlayerResource):
+    """Player match-history pages."""
+
+    def fetch(
+        self, *, cursor: str | None = None, season: int | None = None,
+        mode: str | None = None, hero: str | int | None = None,
+        teammate: str | int | None = None, cached: bool = True,
+    ) -> Any:
+        payload: dict[str, Any] = {"cursor": cursor}
+        for key, value in (("season", season), ("mode", mode), ("hero", hero), ("teammate", teammate)):
+            if value is not None:
+                payload[key] = value
+        path = "/player/matches/cached" if cached else "/player/matches"
+        return _one(self._post(path, **payload))
+
+
+class PlayerLiveGame(PlayerResource):
+    """Current live match data for a player whose profile status is in-game.
+
+    The site supplies the opaque match ID in the player's ``status.battle_id``
+    field. A fresh player profile is needed to discover the current match.
+    """
+
+    def __init__(self, client: Any, player_data: dict[str, Any]) -> None:
+        super().__init__(client, int(player_data["uid"]))
+        self._player_data = player_data
+
+    def fetch(self) -> DataModel | None:
+        """Fetch the current live match, or return ``None`` if out of game."""
+        status = self._player_data.get("status")
+        if not isinstance(status, dict):
+            return None
+        match_id = status.get("battle_id")
+        if not match_id:
+            return None
+        return _one(self._client._post_json(
+            "/live", {"match_id": str(match_id), "uid": self.uid}
+        ))
+
+
+class PlayerTeammates(PlayerResource):
+    def fetch(self, *, season: int | None = None, mode: str | None = None) -> Any:
+        payload = {key: value for key, value in (("season", season), ("mode", mode)) if value is not None}
+        return _many(self._post("/player/teammates", **payload))
+
+
+class PlayerCrosshairs(PlayerResource):
+    def fetch(self) -> Any:
+        return _many(self._post("/player/crosshairs"))
+
+
+class PlayerProficiency(PlayerResource):
+    def fetch(self) -> Any:
+        return _one(self._post("/player/proficiency"))
+
+
+class PlayerPunishments(PlayerResource):
+    def fetch(self) -> Any:
+        return _one(self._post("/player/punishments"))
+
+
+class PlayerNameHistory(PlayerResource):
+    def fetch(self) -> Any:
+        return _many(self._post("/player/name-history"))
+
+
+class Matches:
+    """Match detail endpoint. The upstream match identifier format is opaque."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def get(self, match_id: str | int) -> Any:
+        return _one(self._client._post_json("/match", {"match_id": str(match_id)}))

rivalsdata_api-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+rivalsdata/__init__.py,sha256=TFp3SdV5ioBVUL7RBBsy6vImKjK4DxxXLaA8r2A9Bps,477
+rivalsdata/client.py,sha256=OQM2L1t2LLcbBKoKGr4060RSNYl1egb8bd7Ct0PRqt0,10974
+rivalsdata/exceptions.py,sha256=rL7sfeFnb5vb1xOG5P_Tt-NGf9U1Y0YkpLE3EZ0mK0k,455
+rivalsdata/mcp_server.py,sha256=t0M2rErOGLfraTk2frdSjS6QO0mLkWGYEAiiLlTSTTk,21922
+rivalsdata/models.py,sha256=PUffcUJuIEgZe1x3m8UseqXAmOiRsQ5ObLswtPxHnQ4,5550
+rivalsdata/resources.py,sha256=NlwiOUYxYIW96KR5flA2RQ24MuKo_itUT4pGTdu5l3U,8571
+rivalsdata_api-1.0.0.dist-info/METADATA,sha256=RSPO8g2NfqBufF26gwxV7IE17rFd-e6x7Fq7YqKJLD4,7540
+rivalsdata_api-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+rivalsdata_api-1.0.0.dist-info/entry_points.txt,sha256=wgwiN90usgAAOWS2__aZfvB0zBvBiXIC0ZKUn7p6FSc,62
+rivalsdata_api-1.0.0.dist-info/licenses/LICENSE,sha256=B19xsF0tqLiaasaK8QyX4GbA2dZNWlf7PcF7GbDZ2Y0,1084
+rivalsdata_api-1.0.0.dist-info/RECORD,,

rivalsdata_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

rivalsdata_api-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rivalsdata-mcp = rivalsdata.mcp_server:main

rivalsdata_api-1.0.0.dist-info/licenses/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.