donutstats 0.1.1__tar.gz

donutstats-0.1.1/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + test deps
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest -v

donutstats-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.env
+__pycache__/
+.claude/

donutstats-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ryder4est
+
+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.

donutstats-0.1.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: donutstats
+Version: 0.1.1
+Summary: Async client for the DonutSMP API
+Project-URL: Homepage, https://github.com/optccopa/donutstats
+Project-URL: Issues, https://github.com/optccopa/donutstats/issues
+Author: optccopa
+License: MIT License
+        
+        Copyright (c) 2026 ryder4est
+        
+        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.
+License-File: LICENSE
+Keywords: async,donutsmp,minecraft,stats
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.0; extra == 'discord'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# donutstats
+
+Async Python wrapper for the [DonutSMP](https://donutsmp.net) API.
+
+![PyPI](https://img.shields.io/pypi/v/donutstats) ![Python](https://img.shields.io/pypi/pyversions/donutstats) ![License](https://img.shields.io/pypi/l/donutstats)
+
+[![tests](https://github.com/optccopa/donutstats/actions/workflows/tests.yml/badge.svg)](https://github.com/optccopa/donutstats/actions/workflows/tests.yml)
+
+## Install
+
+### Basic Install
+```bash
+pip install donutstats
+```
+
+### Discord Feature Usage
+```bash
+pip install donutstats[discord]
+```
+
+## Usage
+
+### Simple api usage
+```python
+import asyncio
+from donutstats import DonutStats
+
+async def main():
+    donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api")
+
+    # Full stats dict
+    stats = await donutstats.get_stats(username="copa6076") # Pull the stats from donutsmp api
+    print(stats.get('money')) # 2920840615
+
+    # Single stat
+    shards = await donutstats.get_shards(username="copa6076") # Pull the shards from donutsmp api
+    print(shards) # 8410
+
+    await donutstats.close() # Close it when you close your bot
+
+asyncio.run(main())
+```
+
+### Simple discord bot cog usage
+```python
+import discord
+from discord.ext import commands
+
+from donutstats import DonutStats
+
+class Stats(commands.Cog):
+    def __init__(self, bot: commands.Bot):
+        # Initialize donutstats when your cog gets initialized
+        self.donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api")
+
+    @discord.app_commands.command()
+    async def stats(self, interaction: discord.Interaction, username: str):
+        # Returns a full stats embed
+        embed: discord.Embed = await self.donutstats.get_stats_embed(username, discord.Color.blue())
+
+        await interaction.response.send_message(embed=embed)
+
+async def setup(bot: commands.Bot):
+    await bot.add_cog(Stats(bot))
+```
+## Exceptions
+
+- `DonutSMPError` - Raised when DonutSMP cannot handle a query, Very likely could not find username
+- `UnauthorizedRequest` - Raised when DonutSMP returns a 401 unauthorized.
+- `RateLimited` - Raised when DonutSMP returns a 429 ratelimited
+- `UnexpectedError` - Raised when there is an unexpected api response status.
+
+## License
+
+MIT License [LICENSE](LICENSE)

donutstats-0.1.1/README.md

@@ -0,0 +1,75 @@
+# donutstats
+
+Async Python wrapper for the [DonutSMP](https://donutsmp.net) API.
+
+![PyPI](https://img.shields.io/pypi/v/donutstats) ![Python](https://img.shields.io/pypi/pyversions/donutstats) ![License](https://img.shields.io/pypi/l/donutstats)
+
+[![tests](https://github.com/optccopa/donutstats/actions/workflows/tests.yml/badge.svg)](https://github.com/optccopa/donutstats/actions/workflows/tests.yml)
+
+## Install
+
+### Basic Install
+```bash
+pip install donutstats
+```
+
+### Discord Feature Usage
+```bash
+pip install donutstats[discord]
+```
+
+## Usage
+
+### Simple api usage
+```python
+import asyncio
+from donutstats import DonutStats
+
+async def main():
+    donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api")
+
+    # Full stats dict
+    stats = await donutstats.get_stats(username="copa6076") # Pull the stats from donutsmp api
+    print(stats.get('money')) # 2920840615
+
+    # Single stat
+    shards = await donutstats.get_shards(username="copa6076") # Pull the shards from donutsmp api
+    print(shards) # 8410
+
+    await donutstats.close() # Close it when you close your bot
+
+asyncio.run(main())
+```
+
+### Simple discord bot cog usage
+```python
+import discord
+from discord.ext import commands
+
+from donutstats import DonutStats
+
+class Stats(commands.Cog):
+    def __init__(self, bot: commands.Bot):
+        # Initialize donutstats when your cog gets initialized
+        self.donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api")
+
+    @discord.app_commands.command()
+    async def stats(self, interaction: discord.Interaction, username: str):
+        # Returns a full stats embed
+        embed: discord.Embed = await self.donutstats.get_stats_embed(username, discord.Color.blue())
+
+        await interaction.response.send_message(embed=embed)
+
+async def setup(bot: commands.Bot):
+    await bot.add_cog(Stats(bot))
+```
+## Exceptions
+
+- `DonutSMPError` - Raised when DonutSMP cannot handle a query, Very likely could not find username
+- `UnauthorizedRequest` - Raised when DonutSMP returns a 401 unauthorized.
+- `RateLimited` - Raised when DonutSMP returns a 429 ratelimited
+- `UnexpectedError` - Raised when there is an unexpected api response status.
+
+## License
+
+MIT License [LICENSE](LICENSE)

donutstats-0.1.1/docs/functions.md

@@ -0,0 +1,21 @@
+# Functions
+
+| Name | Args | Returns |
+|---|---|---|
+| `await get_stats` | `username: str` | `dict[str, str]` |
+| `await get_broken_blocks` | `username: str` | `int` |
+| `await get_deaths` | `username: str` | `int` |
+| `await get_kills` | `username: str` | `int` |
+| `await get_mobs_killed` | `username: str` | `int` |
+| `await get_balance` | `username: str` | `int` — `money` |
+| `await get_money_made_from_sell` | `username: str` | `int` |
+| `await get_money_spent_on_shop` | `username: str` | `int` |
+| `await get_placed_blocks` | `username: str` | `int` |
+| `await get_playtime` | `username: str` | `int` |
+| `await get_shards` | `username: str` | `int` |
+| `await get_stats_embed` | `username: str, color: discord.Color \| Default` | `discord.Embed` — requires `donutstats[discord]` |
+| `await close` | `None` | closes the session
+
+### `get_stats` keys
+
+`broken_blocks`, `deaths`, `kills`, `mobs_killed`, `money`, `money_made_from_sell`, `money_spent_on_shop`, `placed_blocks`, `playtime`, `shards`

donutstats-0.1.1/examples/discord_cog_stats.py

@@ -0,0 +1,19 @@
+import discord
+from discord.ext import commands
+
+from donutstats import DonutStats
+
+class Stats(commands.Cog):
+    def __init__(self, bot: commands.Bot):
+        # Initialize donutstats when your cog gets initialized
+        self.donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api")
+
+    @discord.app_commands.command()
+    async def stats(self, interaction: discord.Interaction, username: str):
+        # Returns a full stats embed
+        embed: discord.Embed = await self.donutstats.get_stats_embed(username, discord.Color.blue())
+
+        await interaction.response.send_message(embed=embed)
+
+async def setup(bot: commands.Bot):
+    await bot.add_cog(Stats(bot))

donutstats-0.1.1/examples/get_single_stat.py

@@ -0,0 +1,13 @@
+import asyncio
+from donutstats import DonutStats
+
+async def main():
+    donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api)")
+
+    shards = await donutstats.get_shards(username="copa6076") # Pull the shards from donutsmp api via ign
+
+    print(shards) # 8410
+
+    await donutstats.close() # Close the aiohttp connection, aiohttp gets loud about unclosed connections
+
+asyncio.run(main()) # Start the async event loop

donutstats-0.1.1/examples/get_stats.py

@@ -0,0 +1,13 @@
+import asyncio
+from donutstats import DonutStats
+
+async def main():
+    donutstats = DonutStats("Your DonutSMP api key (generate ingame with /api)")
+
+    stats = await donutstats.get_stats(username="copa6076") # Pull the stats from donutsmp api via ign
+
+    print(stats.get('money')) # 2920840615
+
+    await donutstats.close() # Close the aiohttp connection, aiohttp gets loud about unclosed connections
+
+asyncio.run(main()) # Start the async event loop

donutstats-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "donutstats"
+version = "0.1.1"
+description = "Async client for the DonutSMP API"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [{ name = "optccopa" }]
+keywords = ["donutsmp", "minecraft", "stats", "async"]
+dependencies = ["aiohttp>=3.9"]
+
+[project.optional-dependencies]
+discord = ["discord.py>=2.0"]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/optccopa/donutstats"
+Issues = "https://github.com/optccopa/donutstats/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/donutstats"]

donutstats-0.1.1/src/donutstats/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .donutstats import (
+    DonutStats,
+    DonutSMPError,
+    UnauthorizedRequest,
+    RateLimited,
+    UnexpectedError
+)
+
+__all__ = [
+    "DonutStats",
+    "DonutSMPError",
+    "UnauthorizedRequest",
+    "RateLimited",
+    "UnexpectedError",
+]
+
+try:
+    __version__ = version("donutstats")
+except PackageNotFoundError:  # not installed (e.g. running from source tree)
+    __version__ = "0.0.0"

donutstats-0.1.1/src/donutstats/donutstats.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import logging
+from json import JSONDecodeError
+from urllib.parse import quote
+
+import aiohttp
+
+from .utils import fmt_amount, fmt_playtime
+
+logger = logging.getLogger(__name__)
+
+try:
+    import discord
+
+    _DISCORD = True
+except ImportError:
+    _DISCORD = False
+    logger.info(
+        "Some functionality requires discord.py, Install with: pip install donutstats[discord]"
+    )
+
+class DonutSMPError(Exception):
+    """Raised when DonutSMP cannot handle a query, Very likely could not find username"""
+    pass
+
+class UnauthorizedRequest(Exception):
+    """Raised when DonutSMP returns a 401 unauthorized"""
+    pass
+
+class RateLimited(Exception):
+    """Raised when DonutSMP returns a 429 ratelimited"""
+
+class UnexpectedError(Exception):
+    """Raised when there is an unexpected api response status"""
+    pass
+
+class DonutStats:
+    def __init__(self, donutsmp_api_key: str):
+        self._base_url = "https://api.donutsmp.net/v1"
+        self._donutsmp_headers = {"Authorization": f"Bearer {donutsmp_api_key}"}
+        self._session: aiohttp.ClientSession | None = None
+        self._timeout = aiohttp.ClientTimeout(total=10)
+
+    def _resolve_session(self) -> aiohttp.ClientSession:
+        """Fetches the aiohttp session or creates a new one"""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(timeout=self._timeout)
+        return self._session
+
+    async def get_stats(self, username: str) -> dict[str, str]:
+        """
+        Returns a users donutsmp stats as a dict
+
+        Stats: 
+            broken_blocks         string
+            deaths	              string
+            kills                 string
+            mobs_killed           string
+            money                 string
+            money_made_from_sell  string
+            money_spent_on_shop	  string
+            placed_blocks         string
+            playtime              string
+            shards                string
+        """
+        url = f"{self._base_url}/stats/{quote(username, safe='')}"
+        session = self._resolve_session()
+        try:
+            async with session.get(url, headers=self._donutsmp_headers) as resp:
+                if resp.status == 401:
+                    raise UnauthorizedRequest("Please generate an API Key in game with /api and supply it when initializing this class")
+                if resp.status == 429:
+                    raise RateLimited(f"Ratelimited, DonutSMP currently has a ratelimit of 250 Reqs / Minute")
+                if resp.status != 200:
+                    raise DonutSMPError(f"Could not handle your request. This may be because the specified user/page/item does not exist. (Status: {resp.status})")
+                try:
+                    data: dict = await resp.json(content_type=None)
+                except JSONDecodeError as e:
+                    raise UnexpectedError("DonutSMP API failed to return valid json") from e
+                result = data.get('result')
+                if result is None:
+                    raise UnexpectedError(f"The DonutSMP api failed to return a result field")
+                return result
+        except aiohttp.ClientError as e:
+            raise UnexpectedError("Aiohttp had a ClientError, Refer to the traceback") from e
+        
+    async def _get_stat(self, username: str, field: str) -> int:
+        """Fetch a single stat field for a user and convert it to an int"""
+        stats = await self.get_stats(username=username)
+        strfield = stats.get(field)
+        try:
+            # via float() so scientific-notation strings (e.g. "2.9e9") parse too
+            return int(float(strfield))
+        except (ValueError, TypeError) as e:
+            raise UnexpectedError(f"DonutSMP failed to return a valid '{field}' field (Got: {strfield})") from e
+
+    async def get_broken_blocks(self, username: str) -> int:
+        """Returns a users DonutSMP broken blocks"""
+        return await self._get_stat(username, "broken_blocks")
+
+    async def get_deaths(self, username: str) -> int:
+        """Returns a users DonutSMP deaths"""
+        return await self._get_stat(username, "deaths")
+
+    async def get_kills(self, username: str) -> int:
+        """Returns a users DonutSMP kills"""
+        return await self._get_stat(username, "kills")
+
+    async def get_mobs_killed(self, username: str) -> int:
+        """Returns a users DonutSMP mobs killed"""
+        return await self._get_stat(username, "mobs_killed")
+
+    async def get_balance(self, username: str) -> int:
+        """Returns a users DonutSMP balance"""
+        return await self._get_stat(username, "money")
+    
+    async def get_money_made_from_sell(self, username: str) -> int:
+        """Returns a users DonutSMP money made from sell"""
+        return await self._get_stat(username, "money_made_from_sell")
+    
+    async def get_money_spent_on_shop(self, username: str) -> int:
+        """Returns a users DonutSMP money spent on shop"""
+        return await self._get_stat(username, "money_spent_on_shop")
+
+    async def get_placed_blocks(self, username: str) -> int:
+        """Returns a users DonutSMP placed blocks"""
+        return await self._get_stat(username, "placed_blocks")
+
+    async def get_playtime(self, username: str) -> int:
+        """Returns a users DonutSMP playtime"""
+        return await self._get_stat(username, "playtime")
+
+    async def get_shards(self, username: str) -> int:
+        """Returns a users DonutSMP shards"""
+        return await self._get_stat(username, "shards")
+    
+    async def get_stats_embed(self, username: str, color: discord.Color | None = None):
+        """Returns a premade stats embed, REQUIRES pip install donutstats[discord]"""
+        if not _DISCORD:
+            raise RuntimeError("get_stats_embed() requires donutstats[discord], Install with: pip install donutstats[discord]")
+        stats: dict = await self.get_stats(username=username)
+        if color is None:
+            color = discord.Color.blurple()
+        embed = discord.Embed(
+            title=f"{username}'s Stats",
+            description=(
+                f"**Balance:** {fmt_amount(stats['money'])}\n"
+                f"**Shards:** {fmt_amount(stats['shards'])}\n"
+                f"**Playtime:** {fmt_playtime(int(stats['playtime']))}\n"
+                f"**Kills:** {fmt_amount(stats['kills'])}\n"
+                f"**Deaths:** {fmt_amount(stats['deaths'])}\n"
+                f"**Blocks Placed:** {fmt_amount(stats['placed_blocks'])}\n"
+                f"**Blocks Broken:** {fmt_amount(stats['broken_blocks'])}\n"
+                f"**Mobs Killed:** {fmt_amount(stats['mobs_killed'])}\n"
+                f"**Money Spent On /shop:** {fmt_amount(stats['money_spent_on_shop'])}\n"
+                f"**Money Made From /sell:** {fmt_amount(stats['money_made_from_sell'])}"
+            ),
+            color=color
+        )
+        embed.set_thumbnail(url=f"https://mc-heads.net/avatar/{username}")
+
+        return embed
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def close(self):
+        """Close the aiohttp session"""
+        if self._session and not self._session.closed:
+            await self._session.close()

donutstats-0.1.1/src/donutstats/utils.py

@@ -0,0 +1,28 @@
+def fmt_amount(n: int | float) -> str:
+    """Formats into a k / m / b / t string"""
+    n = float(n)
+    if abs(n) < 1000:
+        return str(int(n)) if n == int(n) else f"{n:.2f}"
+    for divisor, suffix in ((1e12, "t"), (1e9, "b"), (1e6, "m"), (1e3, "k")):
+        if abs(n) >= divisor:
+            v = n / divisor
+            s = f"{v:.2f}".rstrip("0").rstrip(".")
+            return f"{s}{suffix}"
+        
+def fmt_playtime(ms: int) -> str:
+    """Formats donutsmp playtime"""
+    seconds = ms // 1000
+
+    days, seconds = divmod(seconds, 86400)
+    hours, seconds = divmod(seconds, 3600)
+    minutes, _ = divmod(seconds, 60)
+
+    parts = []
+    if days:
+        parts.append(f"{days}d")
+    if hours:
+        parts.append(f"{hours}h")
+    if minutes:
+        parts.append(f"{minutes}m")
+
+    return " ".join(parts) or "0m"

donutstats-0.1.1/tests/test_donutstats.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import random
+import string
+from json import JSONDecodeError
+from unittest.mock import AsyncMock, MagicMock
+
+import aiohttp
+import pytest
+
+
+def rand_ign() -> str:
+    """Random Minecraft-style username (3-16 chars). Mocked, so any name works."""
+    length = random.randint(3, 16)
+    return "".join(random.choices(string.ascii_letters + string.digits + "_", k=length))
+
+from donutstats import (
+    DonutStats,
+    DonutSMPError,
+    UnauthorizedRequest,
+    RateLimited,
+    UnexpectedError,
+)
+from donutstats.utils import fmt_amount, fmt_playtime
+
+SAMPLE_RESULT = {
+    "money": "2577174314",
+    "shards": "8461",
+    "kills": "24",
+    "deaths": "92",
+    "playtime": "1050579440",
+    "placed_blocks": "7524",
+    "broken_blocks": "7285",
+    "mobs_killed": "63",
+    "money_spent_on_shop": "2688539",
+    "money_made_from_sell": "1.1477798052923137e+8",
+}
+
+UNKNOWN_USER_BODY = {
+    "status": 500,
+    "reason": "Error handling request",
+    "message": (
+        "Could not handle your request. This may be because the "
+        "specified user/page/item does not exist."
+    ),
+}
+
+INT_METHODS = [
+    "get_broken_blocks",
+    "get_deaths",
+    "get_kills",
+    "get_mobs_killed",
+    "get_balance",
+    "get_money_made_from_sell",
+    "get_money_spent_on_shop",
+    "get_placed_blocks",
+    "get_playtime",
+    "get_shards",
+]
+
+
+def make_client(
+    *, status: int = 200, payload=None, json_exc: Exception | None = None,
+    enter_exc: Exception | None = None,
+) -> tuple[DonutStats, MagicMock]:
+    resp = MagicMock()
+    resp.status = status
+    resp.text = AsyncMock(return_value="<mock body>")
+    if json_exc is not None:
+        resp.json = AsyncMock(side_effect=json_exc)
+    else:
+        resp.json = AsyncMock(return_value=payload)
+
+    cm = MagicMock()
+    if enter_exc is not None:
+        cm.__aenter__ = AsyncMock(side_effect=enter_exc)
+    else:
+        cm.__aenter__ = AsyncMock(return_value=resp)
+    cm.__aexit__ = AsyncMock(return_value=False)
+
+    session = MagicMock()
+    session.closed = False
+    session.get = MagicMock(return_value=cm)
+    session.close = AsyncMock()
+
+    ds = DonutStats("fake-token")
+    ds._session = session
+    ds._resolve_session = lambda: session
+    return ds, session
+
+async def test_get_stats_returns_result_dict():
+    ds, session = make_client(payload={"result": SAMPLE_RESULT})
+    stats = await ds.get_stats("copa6076")
+    assert stats == SAMPLE_RESULT
+    # auth header sent
+    _, kwargs = session.get.call_args
+    assert kwargs["headers"] == {"Authorization": "Bearer fake-token"}
+
+
+async def test_get_stats_url_encodes_username():
+    ds, session = make_client(payload={"result": SAMPLE_RESULT})
+    await ds.get_stats("weird / name")
+    url = session.get.call_args.args[0]
+    assert url.endswith("/stats/weird%20%2F%20name")
+
+@pytest.mark.parametrize(
+    "status,exc",
+    [
+        (401, UnauthorizedRequest),
+        (429, RateLimited),
+        (404, DonutSMPError),
+        (500, DonutSMPError),
+    ],
+)
+async def test_status_codes_raise(status, exc):
+    ds, _ = make_client(status=status, payload={"result": SAMPLE_RESULT})
+    with pytest.raises(exc):
+        await ds.get_stats("copa6076")
+
+
+async def test_unknown_user_raises_donutsmp_error():
+    ds, _ = make_client(status=500, payload=UNKNOWN_USER_BODY)
+    with pytest.raises(DonutSMPError):
+        await ds.get_stats(rand_ign())
+
+
+async def test_invalid_json_raises_unexpected():
+    ds, _ = make_client(json_exc=JSONDecodeError("bad", "doc", 0))
+    with pytest.raises(UnexpectedError):
+        await ds.get_stats("copa6076")
+
+
+async def test_missing_result_field_raises_unexpected():
+    ds, _ = make_client(payload={"something_else": 1})
+    with pytest.raises(UnexpectedError):
+        await ds.get_stats("copa6076")
+
+
+async def test_client_error_wrapped_as_unexpected():
+    ds, _ = make_client(enter_exc=aiohttp.ClientError("boom"))
+    with pytest.raises(UnexpectedError):
+        await ds.get_stats("copa6076")
+@pytest.mark.parametrize("method", INT_METHODS)
+async def test_int_methods_return_int(method):
+    ds, _ = make_client(payload={"result": SAMPLE_RESULT})
+    value = await getattr(ds, method)("copa6076")
+    assert isinstance(value, int)
+    assert value >= 0
+
+
+async def test_balance_maps_to_money():
+    ds, _ = make_client(payload={"result": SAMPLE_RESULT})
+    assert await ds.get_balance("copa6076") == 2577174314
+
+
+async def test_scientific_notation_parses():
+    ds, _ = make_client(payload={"result": SAMPLE_RESULT})
+    assert await ds.get_money_made_from_sell("copa6076") == 114777980
+
+
+async def test_non_numeric_field_raises_unexpected():
+    result = dict(SAMPLE_RESULT, kills="not-a-number")
+    ds, _ = make_client(payload={"result": result})
+    with pytest.raises(UnexpectedError):
+        await ds.get_kills("copa6076")
+
+
+async def test_missing_field_raises_unexpected():
+    result = {k: v for k, v in SAMPLE_RESULT.items() if k != "shards"}
+    ds, _ = make_client(payload={"result": result})
+    with pytest.raises(UnexpectedError):
+        await ds.get_shards("copa6076")
+
+
+# --------------------------------------------------------------------------- #
+# session lifecycle
+# --------------------------------------------------------------------------- #
+async def test_context_manager_closes_session():
+    ds, session = make_client(payload={"result": SAMPLE_RESULT})
+    async with ds as c:
+        await c.get_stats("copa6076")
+    session.close.assert_awaited_once()
+
+
+async def test_close_is_idempotent_when_no_session():
+    ds = DonutStats("fake-token")
+    # never opened a session; close() must not blow up
+    await ds.close()
+
+
+# --------------------------------------------------------------------------- #
+# formatting helpers (pure)
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize(
+    "value,expected",
+    [
+        (0, "0"),
+        (500, "500"),
+        (1500, "1.5k"),
+        (8410, "8.41k"),
+        (1_000_000, "1m"),
+        (2_920_840_615, "2.92b"),
+        (1_500_000_000_000, "1.5t"),
+    ],
+)
+def test_fmt_amount(value, expected):
+    assert fmt_amount(value) == expected
+
+
+@pytest.mark.parametrize(
+    "ms,expected",
+    [
+        (0, "0m"),
+        (90_000, "1m"),
+        (3_600_000, "1h"),
+        (90_060_000, "1d 1h 1m"),
+    ],
+)
+def test_fmt_playtime(ms, expected):
+    assert fmt_playtime(ms) == expected