python-mister-fpga 0.1.3__tar.gz → 0.2.0__tar.gz

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0
+- Add `MisterRAWeb` — async client for the [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull cloud player stats (points, rank, recently-played games, latest unlocked achievement) without SSH.
+- New dataclasses `MisterRAWebStats`, `RAGameProgress`, `RAAchievement` for aggregated cloud-stats snapshots.
+- New exception `MisterRAWebError` raised on network, HTTP, or API-level failures (including bad credentials).
+
 ## 0.1.2
 - Add online documentation (MkDocs Material) at https://hudsonbrendon.github.io/python-mister-fpga/ and enrich public-API docstrings.
 

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mister-fpga
-Version: 0.1.3
+Version: 0.2.0
 Summary: Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry
 Project-URL: Homepage, https://github.com/hudsonbrendon/python-mister-fpga
 Project-URL: Documentation, https://hudsonbrendon.github.io/python-mister-fpga/
@@ -23,6 +23,7 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: test
+Requires-Dist: aiohttp<3.10; extra == 'test'
 Requires-Dist: aioresponses>=0.7; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
 Requires-Dist: pytest>=8; extra == 'test'
@@ -107,6 +108,74 @@ async def main():
 asyncio.run(main())
 ```
 
+## RetroAchievements cloud stats
+
+`MisterRAWeb` queries the public [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull a player's points, rank, recently-played games, and latest unlocked achievement — no SSH required.  You need a **Web API key** from [retroachievements.org/settings](https://retroachievements.org/settings).
+
+```python
+import asyncio
+from mister_fpga import MisterRAWeb
+
+async def main():
+    web = MisterRAWeb("myuser", "my_api_key")
+    stats = await web.async_fetch_stats()
+    print(stats.hardcore_points, stats.rank, stats.current_game)
+    await web.async_close()
+
+asyncio.run(main())
+```
+
+### `MisterRAWeb(username, api_key, *, session=None, timeout=15)`
+
+Async HTTPS client for the RA Web API.  When `session` is `None` the client creates its own `aiohttp.ClientSession`; call `await web.async_close()` to release it.  Pass a shared session to manage its lifetime yourself.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`MisterRAWebError`** — raised by `MisterRAWeb` on network failures, HTTP errors, or API-level errors (including bad credentials).
+
 ## API
 
 - **`MisterClient(host, port=8182, *, session=None, timeout=10)`** — async REST client; call `await client.async_close()` when done, or inject your own `aiohttp.ClientSession`.
@@ -116,6 +185,9 @@ asyncio.run(main())
 - **`apply_ws_message(message, status, menu_path, index_state)`** — pure reducer; apply a single WS text frame and return updated `(status, menu_path, index_state)`.
 - **`MisterSSH(host, port, username, password)`** — persistent asyncssh connection; `await ssh.async_probe()` returns telemetry dict.
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
+- **`MisterRAWeb(username, api_key, *, session=None, timeout=15)`** — async RA Web API client; `await web.async_fetch_stats()` returns `MisterRAWebStats`.
+- **`MisterRAWebStats`**, **`RAGameProgress`**, **`RAAchievement`** — cloud-stats dataclasses (see section above).
+- **`MisterRAWebError`** — raised on RA Web API failures.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
 ## Documentation

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/README.md

@@ -76,6 +76,74 @@ async def main():
 asyncio.run(main())
 ```
 
+## RetroAchievements cloud stats
+
+`MisterRAWeb` queries the public [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull a player's points, rank, recently-played games, and latest unlocked achievement — no SSH required.  You need a **Web API key** from [retroachievements.org/settings](https://retroachievements.org/settings).
+
+```python
+import asyncio
+from mister_fpga import MisterRAWeb
+
+async def main():
+    web = MisterRAWeb("myuser", "my_api_key")
+    stats = await web.async_fetch_stats()
+    print(stats.hardcore_points, stats.rank, stats.current_game)
+    await web.async_close()
+
+asyncio.run(main())
+```
+
+### `MisterRAWeb(username, api_key, *, session=None, timeout=15)`
+
+Async HTTPS client for the RA Web API.  When `session` is `None` the client creates its own `aiohttp.ClientSession`; call `await web.async_close()` to release it.  Pass a shared session to manage its lifetime yourself.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`MisterRAWebError`** — raised by `MisterRAWeb` on network failures, HTTP errors, or API-level errors (including bad credentials).
+
 ## API
 
 - **`MisterClient(host, port=8182, *, session=None, timeout=10)`** — async REST client; call `await client.async_close()` when done, or inject your own `aiohttp.ClientSession`.
@@ -85,6 +153,9 @@ asyncio.run(main())
 - **`apply_ws_message(message, status, menu_path, index_state)`** — pure reducer; apply a single WS text frame and return updated `(status, menu_path, index_state)`.
 - **`MisterSSH(host, port, username, password)`** — persistent asyncssh connection; `await ssh.async_probe()` returns telemetry dict.
 - **`parse_ssh_probe(raw)`** — parse the raw batched SSH output into a telemetry dict.
+- **`MisterRAWeb(username, api_key, *, session=None, timeout=15)`** — async RA Web API client; `await web.async_fetch_stats()` returns `MisterRAWebStats`.
+- **`MisterRAWebStats`**, **`RAGameProgress`**, **`RAAchievement`** — cloud-stats dataclasses (see section above).
+- **`MisterRAWebError`** — raised on RA Web API failures.
 - **`KEYBOARD_NAMES`**, **`INI_VIDEO_KEYS`**, **`WS_PATH`**, **`DEFAULT_PORT`** — protocol constants.
 
 ## Documentation

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/docs/api.md

@@ -13,3 +13,13 @@
 ::: mister_fpga.parse_ssh_probe
 
 ::: mister_fpga.MisterConnectionError
+
+::: mister_fpga.MisterRAWeb
+
+::: mister_fpga.MisterRAWebStats
+
+::: mister_fpga.RAGameProgress
+
+::: mister_fpga.RAAchievement
+
+::: mister_fpga.MisterRAWebError

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.3"
+version = "0.2.0"
 description = "Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,7 +28,14 @@ Documentation = "https://hudsonbrendon.github.io/python-mister-fpga/"
 Issues = "https://github.com/hudsonbrendon/python-mister-fpga/issues"
 
 [project.optional-dependencies]
-test = ["pytest>=8", "pytest-asyncio>=0.23", "aioresponses>=0.7", "ruff"]
+test = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "aioresponses>=0.7",
+  # aiohttp<3.10: aioresponses 0.7.8 uses the removed loop= param in StreamReader
+  "aiohttp<3.10",
+  "ruff",
+]
 docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
 
 [tool.hatch.build.targets.wheel]

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/src/mister_fpga/__init__.py

@@ -12,8 +12,12 @@ from .const import (
     SSH_PROBE_CMD,
     WS_PATH,
     MisterRAStatus,
+    MisterRAWebStats,
+    RAAchievement,
+    RAGameProgress,
 )
 from .ra import MisterRA, MisterRAError, parse_ra_status
+from .ra_web import MisterRAWeb, MisterRAWebError
 from .ssh import MisterSSH, parse_ssh_probe
 from .websocket import MisterWebSocketClient, apply_ws_message
 
@@ -24,11 +28,16 @@ __all__ = [
     "MisterRA",
     "MisterRAError",
     "MisterRAStatus",
+    "MisterRAWeb",
+    "MisterRAWebError",
+    "MisterRAWebStats",
     "MisterWebSocketClient",
     "apply_ws_message",
     "MisterSSH",
     "parse_ra_status",
     "parse_ssh_probe",
+    "RAAchievement",
+    "RAGameProgress",
     "KEYBOARD_NAMES",
     "INI_VIDEO_KEYS",
     "RA_STATUS_CMD",
@@ -40,4 +49,4 @@ __all__ = [
     "DEFAULT_SSH_USERNAME",
     "SSH_PROBE_CMD",
 ]
-__version__ = "0.1.3"
+__version__ = "0.2.0"

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/src/mister_fpga/const.py

@@ -1,7 +1,7 @@
 """Protocol constants for the MiSTer FPGA mrext Remote API."""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 DEFAULT_PORT = 8182
 HTTP_TIMEOUT = 10
@@ -96,3 +96,50 @@ class MisterRAStatus:
     username: str | None = None
     cores_active: int = 0
     cores_total: int = 0
+
+
+# RetroAchievements Web API (cloud player stats) ------------------------------
+
+RA_WEB_API_BASE = "https://retroachievements.org/API/"
+RA_WEB_IMAGE_BASE = "https://media.retroachievements.org"
+RA_WEB_DEFAULT_RECENT_COUNT = 10
+RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES = 10080  # 7 days, in minutes
+
+
+@dataclass
+class RAGameProgress:
+    """Per-game achievement progress from the RA Web API."""
+
+    game_id: int
+    title: str
+    console: str
+    num_achieved: int = 0
+    num_possible: int = 0
+    percent: float = 0.0
+    last_played: str | None = None
+    icon_url: str | None = None
+
+
+@dataclass
+class RAAchievement:
+    """A single unlocked achievement from the RA Web API."""
+
+    title: str
+    description: str
+    points: int
+    game_title: str
+    date: str | None = None
+    badge_url: str | None = None
+
+
+@dataclass
+class MisterRAWebStats:
+    """Aggregated RetroAchievements cloud player stats."""
+
+    hardcore_points: int = 0
+    softcore_points: int = 0
+    rank: int | None = None
+    total_ranked: int | None = None
+    current_game: RAGameProgress | None = None
+    recent_games: list[RAGameProgress] = field(default_factory=list)
+    last_achievement: RAAchievement | None = None

python_mister_fpga-0.2.0/src/mister_fpga/ra_web.py

@@ -0,0 +1,215 @@
+"""RetroAchievements.org Web API client and parsers (cloud player stats)."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+import aiohttp
+
+from .const import (
+    RA_WEB_API_BASE,
+    RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES,
+    RA_WEB_DEFAULT_RECENT_COUNT,
+    RA_WEB_IMAGE_BASE,
+    MisterRAWebStats,
+    RAAchievement,
+    RAGameProgress,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _abs_image(path: str | None) -> str | None:
+    """Resolve a relative RA image path to an absolute media URL."""
+    if not path:
+        return None
+    if path.startswith("http://") or path.startswith("https://"):
+        return path
+    return f"{RA_WEB_IMAGE_BASE}{path}"
+
+
+def parse_rank_and_score(raw: dict) -> tuple[int, int, int | None, int | None]:
+    """Return (hardcore_points, softcore_points, rank, total_ranked)."""
+    if not isinstance(raw, dict):
+        return 0, 0, None, None
+    hardcore = int(raw.get("Score") or 0)
+    softcore = int(raw.get("SoftcoreScore") or 0)
+    rank = raw.get("Rank")
+    total = raw.get("TotalRanked")
+    return (
+        hardcore,
+        softcore,
+        int(rank) if rank is not None else None,
+        int(total) if total is not None else None,
+    )
+
+
+def parse_recently_played(raw: list) -> list[RAGameProgress]:
+    """Build RAGameProgress entries (most-recent first, as the API returns)."""
+    games: list[RAGameProgress] = []
+    if not isinstance(raw, list):
+        return games
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        achieved = int(item.get("NumAchieved") or 0)
+        possible = int(item.get("NumPossibleAchievements") or 0)
+        percent = round(achieved / possible * 100, 1) if possible else 0.0
+        games.append(
+            RAGameProgress(
+                game_id=int(item.get("GameID") or 0),
+                title=item.get("Title") or "",
+                console=item.get("ConsoleName") or "",
+                num_achieved=achieved,
+                num_possible=possible,
+                percent=percent,
+                last_played=item.get("LastPlayed"),
+                icon_url=_abs_image(item.get("ImageIcon")),
+            )
+        )
+    return games
+
+
+def parse_recent_achievements(raw: list) -> list[RAAchievement]:
+    """Build RAAchievement entries (most-recent first, as the API returns)."""
+    achievements: list[RAAchievement] = []
+    if not isinstance(raw, list):
+        return achievements
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        badge = item.get("BadgeURL")
+        if not badge and item.get("BadgeName"):
+            badge = f"/Badge/{item['BadgeName']}.png"
+        achievements.append(
+            RAAchievement(
+                title=item.get("Title") or "",
+                description=item.get("Description") or "",
+                points=int(item.get("Points") or 0),
+                game_title=item.get("GameTitle") or "",
+                date=item.get("Date"),
+                badge_url=_abs_image(badge),
+            )
+        )
+    return achievements
+
+
+class MisterRAWebError(Exception):
+    """A RetroAchievements Web API request failed (network, HTTP, or auth)."""
+
+
+class MisterRAWeb:
+    """Async client for the public RetroAchievements.org Web API.
+
+    Args:
+        username: RA account username (used for both ``z`` and ``u``).
+        api_key: RA Web API key (``y``), from retroachievements.org/settings.
+        session: Optional shared ``aiohttp.ClientSession``. When ``None`` the
+            client creates and owns one; call :meth:`async_close` to release it.
+        timeout: Per-request timeout in seconds (default ``15``).
+    """
+
+    def __init__(
+        self,
+        username: str,
+        api_key: str,
+        *,
+        session: aiohttp.ClientSession | None = None,
+        timeout: int = 15,
+    ) -> None:
+        self.username = username
+        self._api_key = api_key
+        self._timeout = timeout
+        self._session = session
+        self._owns_session = session is None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def async_close(self) -> None:
+        """Close the HTTP session if this client created it."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def _request(self, endpoint: str, params: dict[str, Any]) -> Any:
+        session = await self._get_session()
+        url = f"{RA_WEB_API_BASE}{endpoint}"
+        query = {"z": self.username, "y": self._api_key, "u": self.username, **params}
+        try:
+            async with session.get(
+                url,
+                params=query,
+                timeout=aiohttp.ClientTimeout(total=self._timeout),
+            ) as resp:
+                resp.raise_for_status()
+                text = await resp.text()
+                try:
+                    data = json.loads(text)
+                except json.JSONDecodeError as err:
+                    raise MisterRAWebError(
+                        f"{endpoint} returned invalid JSON: {err}"
+                    ) from err
+                if isinstance(data, dict) and data.get("Error"):
+                    raise MisterRAWebError(f"{endpoint} error: {data['Error']}")
+                return data
+        except (TimeoutError, aiohttp.ClientError) as err:
+            _LOGGER.debug("RA Web request %s failed: %s", endpoint, err)
+            raise MisterRAWebError(f"{endpoint} failed: {err}") from err
+
+    async def async_get_rank_and_score(self) -> dict:
+        return await self._request("API_GetUserRankAndScore.php", {})
+
+    async def async_get_recently_played(
+        self, count: int = RA_WEB_DEFAULT_RECENT_COUNT
+    ) -> list:
+        return await self._request(
+            "API_GetUserRecentlyPlayedGames.php", {"c": count}
+        )
+
+    async def async_get_recent_achievements(
+        self, minutes: int = RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES
+    ) -> list:
+        return await self._request(
+            "API_GetUserRecentAchievements.php", {"m": minutes}
+        )
+
+    async def async_fetch_stats(self) -> MisterRAWebStats:
+        """Fetch all cloud stats concurrently and assemble them."""
+        rank_raw, games_raw, ach_raw = await asyncio.gather(
+            self.async_get_rank_and_score(),
+            self.async_get_recently_played(),
+            self.async_get_recent_achievements(),
+        )
+        hardcore, softcore, rank, total = parse_rank_and_score(rank_raw)
+        games = parse_recently_played(games_raw)
+        achievements = parse_recent_achievements(ach_raw)
+        return MisterRAWebStats(
+            hardcore_points=hardcore,
+            softcore_points=softcore,
+            rank=rank,
+            total_ranked=total,
+            current_game=games[0] if games else None,
+            recent_games=games,
+            last_achievement=achievements[0] if achievements else None,
+        )
+
+    async def async_validate(self) -> None:
+        """Verify credentials with a lightweight call. Raises on failure."""
+        await self.async_get_rank_and_score()
+
+    async def async_get_badge_image(self, url: str) -> bytes:
+        """Fetch a badge/icon image by absolute URL."""
+        session = await self._get_session()
+        try:
+            async with session.get(
+                url, timeout=aiohttp.ClientTimeout(total=self._timeout)
+            ) as resp:
+                resp.raise_for_status()
+                return await resp.read()
+        except (TimeoutError, aiohttp.ClientError) as err:
+            raise MisterRAWebError(f"badge fetch failed: {err}") from err

{python_mister_fpga-0.1.3 → python_mister_fpga-0.2.0}/tests/test_ra.py

@@ -160,4 +160,4 @@ def test_public_exports():
     assert hasattr(mister_fpga, "MisterRAStatus")
     assert hasattr(mister_fpga, "MisterRAError")
     assert hasattr(mister_fpga, "RA_SUPPORTED_SYSTEMS")
-    assert mister_fpga.__version__ == "0.1.3"
+    assert mister_fpga.__version__ == "0.2.0"

python_mister_fpga-0.2.0/tests/test_ra_web.py

@@ -0,0 +1,304 @@
+"""Tests for the RetroAchievements Web API module."""
+import re
+
+import aiohttp
+import pytest
+from aioresponses import aioresponses
+
+import mister_fpga
+from mister_fpga.const import (
+    RA_WEB_API_BASE,
+    RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES,
+    RA_WEB_DEFAULT_RECENT_COUNT,
+    RA_WEB_IMAGE_BASE,
+    MisterRAWebStats,
+    RAAchievement,
+    RAGameProgress,
+)
+from mister_fpga.ra_web import (
+    MisterRAWeb,
+    MisterRAWebError,
+    parse_rank_and_score,
+    parse_recent_achievements,
+    parse_recently_played,
+)
+
+
+def test_constants():
+    assert RA_WEB_API_BASE == "https://retroachievements.org/API/"
+    assert RA_WEB_IMAGE_BASE == "https://media.retroachievements.org"
+    assert RA_WEB_DEFAULT_RECENT_COUNT == 10
+    assert RA_WEB_DEFAULT_ACHIEVEMENT_MINUTES == 10080
+
+
+def test_game_progress_defaults():
+    g = RAGameProgress(game_id=1, title="Game", console="NES")
+    assert g.num_achieved == 0
+    assert g.num_possible == 0
+    assert g.percent == 0.0
+    assert g.last_played is None
+    assert g.icon_url is None
+
+
+def test_achievement_defaults():
+    a = RAAchievement(title="Win", description="desc", points=10, game_title="G")
+    assert a.date is None
+    assert a.badge_url is None
+
+
+def test_web_stats_defaults():
+    s = MisterRAWebStats()
+    assert s.hardcore_points == 0
+    assert s.softcore_points == 0
+    assert s.rank is None
+    assert s.total_ranked is None
+    assert s.current_game is None
+    assert s.recent_games == []
+    assert s.last_achievement is None
+
+
+def test_parse_rank_and_score():
+    raw = {"Score": 12345, "SoftcoreScore": 678, "Rank": 9876, "TotalRanked": 543210}
+    points_h, points_s, rank, total = parse_rank_and_score(raw)
+    assert points_h == 12345
+    assert points_s == 678
+    assert rank == 9876
+    assert total == 543210
+
+
+def test_parse_rank_and_score_missing_keys():
+    points_h, points_s, rank, total = parse_rank_and_score({})
+    assert points_h == 0
+    assert points_s == 0
+    assert rank is None
+    assert total is None
+
+
+def test_parse_recently_played_builds_progress_with_percent_and_absolute_icon():
+    raw = [
+        {
+            "GameID": 1,
+            "Title": "Super Mario Bros.",
+            "ConsoleName": "NES",
+            "NumAchieved": 5,
+            "NumPossibleAchievements": 10,
+            "LastPlayed": "2024-01-01 12:00:00",
+            "ImageIcon": "/Images/024529.png",
+        }
+    ]
+    games = parse_recently_played(raw)
+    assert len(games) == 1
+    g = games[0]
+    assert g.game_id == 1
+    assert g.title == "Super Mario Bros."
+    assert g.console == "NES"
+    assert g.num_achieved == 5
+    assert g.num_possible == 10
+    assert g.percent == 50.0
+    assert g.last_played == "2024-01-01 12:00:00"
+    assert g.icon_url == "https://media.retroachievements.org/Images/024529.png"
+
+
+def test_parse_recently_played_zero_possible_is_zero_percent():
+    games = parse_recently_played(
+        [
+            {
+                "GameID": 2,
+                "Title": "X",
+                "ConsoleName": "SNES",
+                "NumPossibleAchievements": 0,
+            }
+        ]
+    )
+    assert games[0].percent == 0.0
+
+
+def test_parse_recently_played_empty():
+    assert parse_recently_played([]) == []
+
+
+def test_parse_recent_achievements_prefers_badge_url_then_builds_from_name():
+    raw = [
+        {
+            "Title": "Win",
+            "Description": "Beat it",
+            "Points": 10,
+            "GameTitle": "Super Mario Bros.",
+            "Date": "2024-01-02 09:00:00",
+            "BadgeURL": "/Badge/12345.png",
+        },
+        {
+            "Title": "Older",
+            "Description": "d",
+            "Points": 5,
+            "GameTitle": "G",
+            "Date": "2024-01-01 09:00:00",
+            "BadgeName": "67890",
+        },
+    ]
+    achs = parse_recent_achievements(raw)
+    assert achs[0].title == "Win"
+    assert achs[0].points == 10
+    assert achs[0].badge_url == "https://media.retroachievements.org/Badge/12345.png"
+    assert achs[1].badge_url == "https://media.retroachievements.org/Badge/67890.png"
+
+
+def test_parse_recent_achievements_empty():
+    assert parse_recent_achievements([]) == []
+
+
+def _rank_url():
+    return re.compile(r"https://retroachievements\.org/API/API_GetUserRankAndScore\.php.*")
+
+
+def _recent_games_url():
+    return re.compile(
+        r"https://retroachievements\.org/API/API_GetUserRecentlyPlayedGames\.php.*"
+    )
+
+
+def _recent_ach_url():
+    return re.compile(
+        r"https://retroachievements\.org/API/API_GetUserRecentAchievements\.php.*"
+    )
+
+
+async def test_fetch_stats_assembles_all():
+    with aioresponses() as m:
+        m.get(
+            _rank_url(),
+            payload={"Score": 100, "SoftcoreScore": 20, "Rank": 5, "TotalRanked": 999},
+        )
+        m.get(
+            _recent_games_url(),
+            payload=[
+                {
+                    "GameID": 1,
+                    "Title": "Mario",
+                    "ConsoleName": "NES",
+                    "NumAchieved": 3,
+                    "NumPossibleAchievements": 6,
+                }
+            ],
+        )
+        m.get(
+            _recent_ach_url(),
+            payload=[
+                {
+                    "Title": "Win",
+                    "Description": "d",
+                    "Points": 10,
+                    "GameTitle": "Mario",
+                    "Date": "2024-01-01 00:00:00",
+                    "BadgeName": "111",
+                }
+            ],
+        )
+        web = MisterRAWeb("user", "key")
+        try:
+            stats = await web.async_fetch_stats()
+        finally:
+            await web.async_close()
+
+    assert stats.hardcore_points == 100
+    assert stats.softcore_points == 20
+    assert stats.rank == 5
+    assert stats.total_ranked == 999
+    assert stats.current_game.title == "Mario"
+    assert stats.current_game.percent == 50.0
+    assert len(stats.recent_games) == 1
+    assert stats.last_achievement.title == "Win"
+
+
+async def test_fetch_stats_empty_lists_yield_none():
+    with aioresponses() as m:
+        m.get(_rank_url(), payload={"Score": 0, "SoftcoreScore": 0})
+        m.get(_recent_games_url(), payload=[])
+        m.get(_recent_ach_url(), payload=[])
+        web = MisterRAWeb("user", "key")
+        try:
+            stats = await web.async_fetch_stats()
+        finally:
+            await web.async_close()
+    assert stats.current_game is None
+    assert stats.recent_games == []
+    assert stats.last_achievement is None
+
+
+async def test_fetch_stats_http_error_raises():
+    with aioresponses() as m:
+        m.get(_rank_url(), status=500)
+        m.get(_recent_games_url(), payload=[])
+        m.get(_recent_ach_url(), payload=[])
+        web = MisterRAWeb("user", "key")
+        with pytest.raises(MisterRAWebError):
+            try:
+                await web.async_fetch_stats()
+            finally:
+                await web.async_close()
+
+
+async def test_validate_success_and_failure():
+    with aioresponses() as m:
+        m.get(_rank_url(), payload={"Score": 1})
+        web = MisterRAWeb("user", "key")
+        await web.async_validate()  # no raise
+        await web.async_close()
+
+    with aioresponses() as m:
+        m.get(_rank_url(), status=401)
+        web = MisterRAWeb("user", "bad")
+        with pytest.raises(MisterRAWebError):
+            await web.async_validate()
+        await web.async_close()
+
+
+def test_top_level_exports():
+    assert mister_fpga.__version__ == "0.2.0"
+    assert hasattr(mister_fpga, "MisterRAWeb")
+    assert hasattr(mister_fpga, "MisterRAWebError")
+    assert hasattr(mister_fpga, "MisterRAWebStats")
+    assert hasattr(mister_fpga, "RAGameProgress")
+    assert hasattr(mister_fpga, "RAAchievement")
+
+
+async def test_get_badge_image_returns_bytes():
+    url = "https://media.retroachievements.org/Badge/1.png"
+    with aioresponses() as m:
+        m.get(url, body=b"PNGDATA")
+        web = MisterRAWeb("user", "key")
+        data = await web.async_get_badge_image(url)
+        await web.async_close()
+    assert data == b"PNGDATA"
+
+
+async def test_get_badge_image_error_raises():
+    url = "https://media.retroachievements.org/Badge/1.png"
+    with aioresponses() as m:
+        m.get(url, status=404)
+        web = MisterRAWeb("user", "key")
+        with pytest.raises(MisterRAWebError):
+            await web.async_get_badge_image(url)
+        await web.async_close()
+
+
+def test_parse_rank_and_score_non_dict():
+    assert parse_rank_and_score(None) == (0, 0, None, None)
+    assert parse_rank_and_score([]) == (0, 0, None, None)
+
+
+async def test_request_error_payload_raises():
+    with aioresponses() as m:
+        m.get(_rank_url(), payload={"Error": "Invalid API Key"})
+        web = MisterRAWeb("user", "bad")
+        with pytest.raises(MisterRAWebError):
+            await web.async_get_rank_and_score()
+        await web.async_close()
+
+
+async def test_injected_session_not_closed():
+    session = aiohttp.ClientSession()
+    web = MisterRAWeb("user", "key", session=session)
+    await web.async_close()
+    assert not session.closed
+    await session.close()