pokewallet 0.1.1__tar.gz

pokewallet-0.1.1/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.env
+.env.*
+.dev.vars
+*.log
+.DS_Store
+
+# generated from openapi/pokewallet.yaml at build time
+packages/ts/src/generated/
+
+# recorded or scratch output
+.tmp/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+*.pyc
+build/
+.wrangler/

pokewallet-0.1.1/LICENSE

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

pokewallet-0.1.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: pokewallet
+Version: 0.1.1
+Summary: Official Python SDK for the PokeWallet API
+Project-URL: Homepage, https://github.com/pokewallet-lab/pokewallet-sdk#readme
+Project-URL: Repository, https://github.com/pokewallet-lab/pokewallet-sdk
+Project-URL: Issues, https://github.com/pokewallet-lab/pokewallet-sdk/issues
+Author: PokeWallet
+License-Expression: MIT
+License-File: LICENSE
+Keywords: card-prices,cardmarket,magic-the-gathering,one-piece,pokemon,pokewallet,sdk,tcg,tcgplayer,trading-cards
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pokewallet
+
+> Preview: install from the GitHub release files, see [Install](../../README.md#2-install) in the root README, which also has the quickstart, the full method table and the MCP server.
+
+Official Python SDK for the [PokeWallet API](https://pokewallet.io): Pokémon, One Piece and ten more card games, with TCGPlayer and CardMarket prices. Python 3.9+, sync and async clients, `httpx` is the only dependency.
+
+```python
+from pokewallet import PokeWallet
+
+# Key format: pk_live_xxx. Keep it in the environment, never in source control.
+pw = PokeWallet()  # reads POKEWALLET_API_KEY, or pass api_key=...
+
+page = pw.pokemon.search("charizard", limit=10)
+op01 = pw.onepiece.set("OP01")
+for card in pw.games.mtg.set_cards("FRA"):
+    print(card.name)
+```
+
+Async:
+
+```python
+from pokewallet import AsyncPokeWallet
+
+async with AsyncPokeWallet() as pw:
+    page = await pw.pokemon.search("pikachu")
+    async for card in pw.games.mtg.search_all("lotus"):
+        ...
+```
+
+Pokémon, One Piece and the ten games (`pw.games.mtg`, `pw.games.ygo`, ... or `pw.game(code)`) share one interface: `search`, `search_all`, `card`, `sets`, `set`, `set_cards`, `prices`, `statistics`, `completion_value`, `trending`, `top_cards`. Pokémon adds `price_history`.
+
+- **Typed errors:** `AuthError`, `PlanRequiredError` (`redeem_url` / `upgrade_url`), `FeatureNotEnabledError`, `RateLimitError`, `AmbiguousSetError` (`matches`), `NotFoundError`, `UnavailableError`, `ValidationError`.
+- **Retries:** only on 429 (when `Retry-After` is present, within `retry_after_cap`, default 30 s, and no quota window is exhausted) and on 503 (up to `max_retries`, default 2). Never on other 4xx or 5xx.
+- **Validation:** `limit` and `page` are checked before the request is sent.
+- **Normalization:** prices are `float | None`; set identifiers are exposed as `set_id` / `set_code`; every object keeps the server value in `raw`. Ambiguous set answers (200, 300 and 409 on the wire) all raise `AmbiguousSetError`.
+- **Key safety:** the key is held in a closure and shown as `pk_***` by `repr`, `str` and errors; clients cannot be pickled.
+- **Images:** `image_url(card_id)` only builds the URL; the image routes need the `X-API-Key` header.
+
+The client can be created without a key: `health()` and `list_games()` are public and work without one (the `X-API-Key` header is sent only when a key is set); every other call raises `ValidationError` before any request is made.
+
+Every request carries `User-Agent: pokewallet-sdk-py/<version>`.
+
+Attribution: if you show data obtained through the PokeWallet API, SDKs or MCP server to other people, credit PokéWallet with visible text "Data by PokéWallet" (or "Powered by PokéWallet") linking to <https://pokewallet.io>; private use needs no attribution. See the [Terms of Use](https://pokewallet.io/terms-conditions). This concerns the data and the service; the MIT license of the code is separate.

pokewallet-0.1.1/README.md

@@ -0,0 +1,43 @@
+# pokewallet
+
+> Preview: install from the GitHub release files, see [Install](../../README.md#2-install) in the root README, which also has the quickstart, the full method table and the MCP server.
+
+Official Python SDK for the [PokeWallet API](https://pokewallet.io): Pokémon, One Piece and ten more card games, with TCGPlayer and CardMarket prices. Python 3.9+, sync and async clients, `httpx` is the only dependency.
+
+```python
+from pokewallet import PokeWallet
+
+# Key format: pk_live_xxx. Keep it in the environment, never in source control.
+pw = PokeWallet()  # reads POKEWALLET_API_KEY, or pass api_key=...
+
+page = pw.pokemon.search("charizard", limit=10)
+op01 = pw.onepiece.set("OP01")
+for card in pw.games.mtg.set_cards("FRA"):
+    print(card.name)
+```
+
+Async:
+
+```python
+from pokewallet import AsyncPokeWallet
+
+async with AsyncPokeWallet() as pw:
+    page = await pw.pokemon.search("pikachu")
+    async for card in pw.games.mtg.search_all("lotus"):
+        ...
+```
+
+Pokémon, One Piece and the ten games (`pw.games.mtg`, `pw.games.ygo`, ... or `pw.game(code)`) share one interface: `search`, `search_all`, `card`, `sets`, `set`, `set_cards`, `prices`, `statistics`, `completion_value`, `trending`, `top_cards`. Pokémon adds `price_history`.
+
+- **Typed errors:** `AuthError`, `PlanRequiredError` (`redeem_url` / `upgrade_url`), `FeatureNotEnabledError`, `RateLimitError`, `AmbiguousSetError` (`matches`), `NotFoundError`, `UnavailableError`, `ValidationError`.
+- **Retries:** only on 429 (when `Retry-After` is present, within `retry_after_cap`, default 30 s, and no quota window is exhausted) and on 503 (up to `max_retries`, default 2). Never on other 4xx or 5xx.
+- **Validation:** `limit` and `page` are checked before the request is sent.
+- **Normalization:** prices are `float | None`; set identifiers are exposed as `set_id` / `set_code`; every object keeps the server value in `raw`. Ambiguous set answers (200, 300 and 409 on the wire) all raise `AmbiguousSetError`.
+- **Key safety:** the key is held in a closure and shown as `pk_***` by `repr`, `str` and errors; clients cannot be pickled.
+- **Images:** `image_url(card_id)` only builds the URL; the image routes need the `X-API-Key` header.
+
+The client can be created without a key: `health()` and `list_games()` are public and work without one (the `X-API-Key` header is sent only when a key is set); every other call raises `ValidationError` before any request is made.
+
+Every request carries `User-Agent: pokewallet-sdk-py/<version>`.
+
+Attribution: if you show data obtained through the PokeWallet API, SDKs or MCP server to other people, credit PokéWallet with visible text "Data by PokéWallet" (or "Powered by PokéWallet") linking to <https://pokewallet.io>; private use needs no attribution. See the [Terms of Use](https://pokewallet.io/terms-conditions). This concerns the data and the service; the MIT license of the code is separate.

pokewallet-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pokewallet"
+version = "0.1.1"
+description = "Official Python SDK for the PokeWallet API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["pokewallet", "pokemon", "tcg", "trading-cards", "one-piece", "magic-the-gathering", "card-prices", "tcgplayer", "cardmarket", "sdk"]
+authors = [{ name = "PokeWallet" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/pokewallet-lab/pokewallet-sdk#readme"
+Repository = "https://github.com/pokewallet-lab/pokewallet-sdk"
+Issues = "https://github.com/pokewallet-lab/pokewallet-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pokewallet"]
+
+# The source distribution carries the package, its metadata files and nothing else:
+# no tests, no recorded fixtures, no local environments.
+[tool.hatch.build.targets.sdist]
+include = ["/src/pokewallet", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit"]

pokewallet-0.1.1/src/pokewallet/__init__.py

@@ -0,0 +1,24 @@
+"""Official Python SDK for the PokeWallet API."""
+from ._core import RateLimitInfo
+from ._images import image_url
+from ._version import VERSION as __version__
+from .client import AsyncPokeWallet, PokeWallet
+from .errors import (
+    AmbiguousSetError, AuthError, BadRequestError, FeatureNotEnabledError, GameUnavailableError,
+    LimitWindow, NetworkError, NotFoundError, PlanRequiredError, PokeWalletError, RateLimitError,
+    ServerError, SetMatch, UnavailableError, ValidationError,
+)
+from .types import (
+    GAME_CODES, Card, CardmarketPrice, CompletionValue, Game, Health, HealthCheck, Page, PriceHistory, PriceRow,
+    SearchPage, SetPage, SetPrices, SetStatistics, SetSummary, TcgPrice, TopCard,
+    TrendingSet,
+)
+
+__all__ = [
+    "AmbiguousSetError", "AsyncPokeWallet", "AuthError", "BadRequestError", "Card", "CardmarketPrice",
+    "CompletionValue", "FeatureNotEnabledError", "GAME_CODES", "Game", "GameUnavailableError", "Health", "HealthCheck", "LimitWindow",
+    "NetworkError", "NotFoundError", "Page", "PlanRequiredError", "PokeWallet", "PokeWalletError",
+    "PriceHistory", "PriceRow", "RateLimitError", "RateLimitInfo", "SearchPage",
+    "ServerError", "SetMatch", "SetPage", "SetPrices", "SetStatistics", "SetSummary", "TcgPrice",
+    "TopCard", "TrendingSet", "UnavailableError", "ValidationError", "__version__", "image_url",
+]

pokewallet-0.1.1/src/pokewallet/_async.py

@@ -0,0 +1,138 @@
+"""Asynchronous transport and worlds (httpx.AsyncClient)."""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator, Awaitable, Callable, List, Mapping, Optional
+
+import httpx
+
+from ._core import Core, clean_query
+from ._dialect import CardDialect, OnePieceDialect, PokemonDialect
+from .errors import NetworkError
+from .types import (
+    Card, CompletionValue, PriceHistory, SearchPage, SetPage, SetPrices,
+    SetStatistics, SetSummary, TopCard, TrendingSet,
+)
+
+
+class AsyncTransport:
+    def __init__(self, core: Core, client: httpx.AsyncClient, sleep: Callable[[float], Awaitable[Any]]) -> None:
+        self._core = core
+        self._client = client
+        self._sleep = sleep
+
+    async def get(self, path: str, query: Optional[Mapping[str, Any]] = None, *, public: bool = False, accept: Optional[Callable[[Any], bool]] = None) -> Any:
+        self._core.require_key(public)
+        attempt = 0
+        while True:
+            response: Optional[httpx.Response] = None
+            failure: Optional[str] = None
+            try:
+                response = await self._client.get(
+                    self._core.url(path), params=clean_query(query), headers=self._core.headers(), timeout=self._core.timeout
+                )
+            except httpx.HTTPError as exc:
+                failure = self._core.network_error_message(exc)
+            if failure is not None:
+                # Raised outside the except block so no chained exception can carry the request headers.
+                raise NetworkError(failure)
+            assert response is not None
+            body, err, retry_after = self._core.interpret(response.status_code, response.headers, response.text, path)
+            if err is None:
+                return body
+            # Some non-2xx answers are data, not failures (an "unhealthy" report): return them as is, no retry.
+            if accept is not None and accept(body):
+                return body
+            wait = self._core.wait_before_retry(err, retry_after, attempt)
+            if wait is None:
+                raise err
+            attempt += 1
+            await self._sleep(wait)
+
+
+class AsyncWorld:
+    """The one interface shared by Pokémon, One Piece and the ten games."""
+
+    def __init__(self, transport: AsyncTransport, dialect: Any) -> None:
+        self._t = transport
+        self._d = dialect
+
+    async def _get(self, req: Any) -> Any:
+        return await self._t.get(req.path, req.query)
+
+    async def search(self, q: str, *, page: Optional[int] = None, limit: Optional[int] = None) -> SearchPage:
+        """One page of search results. ``q`` is 2-100 characters for the ten games."""
+        return self._d.parse_search(await self._get(self._d.search(q, page, limit)))
+
+    def search_all(self, q: str, *, limit: Optional[int] = None, max_items: Optional[int] = None) -> AsyncIterator[Card]:
+        """Every result of a search, page after page."""
+        return self._walk(lambda p: self.search(q, page=p, limit=limit), max_items)
+
+    async def card(self, card_id: str) -> Card:
+        """Card by id (``pk_…``, ``op_…``, ``<code>_…``, or a 64-hex CardMarket id)."""
+        return self._d.parse_card(await self._get(self._d.card(card_id)))
+
+    async def sets(self, *, language: Optional[str] = None) -> List[SetSummary]:
+        """All sets of the world. The API does not paginate this list."""
+        return self._d.parse_sets(await self._get(self._d.sets(language)))
+
+    async def set(self, code: str, *, page: Optional[int] = None, limit: Optional[int] = None, language: Optional[str] = None) -> SetPage:
+        """One page of a set's cards. Raises ``AmbiguousSetError`` when the code matches several sets."""
+        return self._d.parse_set(await self._get(self._d.set(code, page, limit, language)))
+
+    def set_cards(self, code: str, *, limit: Optional[int] = None, language: Optional[str] = None, max_items: Optional[int] = None) -> AsyncIterator[Card]:
+        """Every card of a set, page after page."""
+        return self._walk(lambda p: self.set(code, page=p, limit=limit, language=language), max_items)
+
+    async def prices(self, code: str, *, source: Optional[str] = None) -> SetPrices:
+        """Prices of every card in a set: hundreds to thousands of rows. Plan-gated."""
+        return self._d.parse_prices(await self._get(self._d.prices(code, source)))
+
+    async def statistics(self, code: str, *, variant: Optional[str] = None) -> SetStatistics:
+        return self._d.parse_statistics(await self._get(self._d.statistics(code, variant)))
+
+    async def completion_value(self, code: str) -> CompletionValue:
+        return self._d.parse_completion_value(await self._get(self._d.completion_value(code)))
+
+    async def trending(self, *, period: Optional[str] = None, limit: Optional[int] = None) -> List[TrendingSet]:
+        return self._d.parse_trending(await self._get(self._d.trending(period, limit)))
+
+    async def top_cards(self, *, metric: Optional[str] = None, source: Optional[str] = None, limit: Optional[int] = None) -> List[TopCard]:
+        return self._d.parse_top_cards(await self._get(self._d.top_cards(metric, source, limit)))
+
+    @staticmethod
+    async def _walk(fetch: Callable[[int], Awaitable[Any]], max_items: Optional[int]) -> AsyncIterator[Card]:
+        page, yielded = 1, 0
+        while True:
+            res = await fetch(page)
+            for item in res.items:
+                if max_items is not None and yielded >= max_items:
+                    return
+                yield item
+                yielded += 1
+            if not res.items or page >= res.total_pages:
+                return
+            page += 1
+
+
+class AsyncPokemonWorld(AsyncWorld):
+    def __init__(self, transport: AsyncTransport) -> None:
+        super().__init__(transport, PokemonDialect())
+
+    async def card(self, card_id: str, *, set_code: Optional[str] = None) -> Card:  # type: ignore[override]
+        """Card by id, or by plain card number together with ``set_code``."""
+        return self._d.parse_card(await self._get(self._d.card(card_id, set_code)))
+
+    async def price_history(self, card_id: str) -> PriceHistory:
+        """Price snapshots at 7/14/30/60/120 days, per finish (not a time series). Plan-gated."""
+        return self._d.parse_price_history(await self._get(self._d.price_history(card_id)))
+
+
+def build_async_worlds(transport: AsyncTransport):
+    from .types import GAME_CODES
+
+    games = {code: AsyncWorld(transport, CardDialect(f"/{code}", ("7d",), 2)) for code in GAME_CODES}
+    return AsyncPokemonWorld(transport), AsyncWorld(transport, OnePieceDialect()), games
+
+
+default_sleep = asyncio.sleep

pokewallet-0.1.1/src/pokewallet/_core.py

@@ -0,0 +1,189 @@
+"""I/O-free core shared by the sync and async clients: credentials, headers, response handling, retry rules."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Optional, Tuple
+
+from ._error_map import error_from_response
+from .errors import PokeWalletError, RateLimitError, ValidationError
+from ._version import DEFAULT_BASE_URL, DEFAULT_USER_AGENT
+
+MASK = "pk_***"
+_GAME_PREFIXES = ("/mtg/", "/ygo/", "/cfv/", "/dbs/", "/fab/", "/dgm/", "/swu/", "/lor/", "/rft/", "/cpk/")
+
+
+@dataclass
+class RateLimitInfo:
+    """Quota counters from the ``X-RateLimit-*`` headers of the last answer."""
+
+    limit_hour: Optional[int]
+    remaining_hour: Optional[int]
+    limit_day: Optional[int]
+    remaining_day: Optional[int]
+
+
+class Credentials:
+    """Holds the API key in a closure: not in ``vars()``, not in repr/str, not picklable or copyable."""
+
+    __slots__ = ("_get",)
+
+    def __init__(self, key: Optional[str]) -> None:
+        def get() -> Optional[str]:
+            return key
+
+        object.__setattr__(self, "_get", get)
+
+    @property
+    def present(self) -> bool:
+        return self._get() is not None
+
+    def header_value(self) -> Optional[str]:
+        return self._get()
+
+    def redact(self, value: str) -> str:
+        key = self._get()
+        return value if key is None else value.replace(key, MASK)
+
+    def __repr__(self) -> str:
+        return f"<Credentials {MASK if self.present else 'none'}>"
+
+    __str__ = __repr__
+
+    def __reduce__(self) -> Any:
+        raise TypeError("API credentials cannot be pickled or copied")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError("credentials are read-only")
+
+
+KEY_REQUIRED = "An API key is required: pass apiKey or set POKEWALLET_API_KEY"
+
+
+def read_key(api_key: Optional[str]) -> Optional[str]:
+    """The key from the argument or the environment; None when there is none (public endpoints still work)."""
+    key = (api_key or os.environ.get("POKEWALLET_API_KEY") or "").strip()
+    if not key:
+        return None
+    if not key.startswith("pk_"):
+        raise ValidationError('API keys start with "pk_"')
+    return key
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Seconds from a ``Retry-After`` value (delta-seconds or HTTP date), or None."""
+    if value is None or not value.strip():
+        return None
+    try:
+        n = float(value)
+    except ValueError:
+        from email.utils import parsedate_to_datetime
+        from datetime import datetime, timezone
+
+        try:
+            when = parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+    return n if n >= 0 else None
+
+
+def _int(headers: Mapping[str, str], name: str) -> Optional[int]:
+    value = headers.get(name)
+    try:
+        return int(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+class Core:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        user_agent: Optional[str],
+        max_retries: int,
+        retry_after_cap: float,
+        timeout: float,
+    ) -> None:
+        self.credentials = Credentials(read_key(api_key))
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.user_agent = user_agent or DEFAULT_USER_AGENT
+        self.max_retries = max_retries
+        self.retry_after_cap = retry_after_cap
+        self.timeout = timeout
+        self.last_rate_limit: Optional[RateLimitInfo] = None
+
+    def url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def headers(self) -> dict:
+        key = self.credentials.header_value()
+        base = {"User-Agent": self.user_agent, "Accept": "application/json"}
+        return base if key is None else {"X-API-Key": key, **base}
+
+    def require_key(self, public: bool) -> None:
+        """Raised before any network call: only the two public endpoints work without a key."""
+        if not public and not self.credentials.present:
+            raise ValidationError(KEY_REQUIRED)
+
+    def network_error_message(self, exc: BaseException) -> str:
+        return self.credentials.redact(f"Request failed before an answer arrived: {type(exc).__name__}: {exc}")
+
+    def interpret(
+        self, status: int, headers: Mapping[str, str], body_text: str, path: str
+    ) -> Tuple[Any, Optional[PokeWalletError], Optional[float]]:
+        """Returns (body, error, retry_after). The body never contains the key."""
+        body = _parse_json(self.credentials.redact(body_text))
+        self._track_quota(headers)
+        if 200 <= status < 300:
+            return body, None, None
+        retry_after = parse_retry_after(headers.get("retry-after"))
+        return body, error_from_response(status, body, retry_after, path.startswith(_GAME_PREFIXES)), retry_after
+
+    def wait_before_retry(self, err: PokeWalletError, retry_after: Optional[float], attempt: int) -> Optional[float]:
+        """Seconds to wait before the next attempt, or None when the error must be raised."""
+        if attempt >= self.max_retries:
+            return None
+        if err.status == 429:
+            # Never guess a wait: no header, or an exhausted window, means retrying is pointless.
+            ok = retry_after is not None and retry_after <= self.retry_after_cap
+            if ok and isinstance(err, RateLimitError) and err.exhausted:
+                ok = False
+            return retry_after if ok else None
+        if err.status == 503:
+            wait = 1.0 if retry_after is None else retry_after
+            return wait if wait <= self.retry_after_cap else None
+        return None
+
+    def _track_quota(self, headers: Mapping[str, str]) -> None:
+        info = RateLimitInfo(
+            _int(headers, "x-ratelimit-limit-hour"),
+            _int(headers, "x-ratelimit-remaining-hour"),
+            _int(headers, "x-ratelimit-limit-day"),
+            _int(headers, "x-ratelimit-remaining-day"),
+        )
+        if any(v is not None for v in (info.limit_hour, info.remaining_hour, info.limit_day, info.remaining_day)):
+            self.last_rate_limit = info
+
+    def __repr__(self) -> str:
+        return f"Core(base_url={self.base_url!r}, user_agent={self.user_agent!r}, api_key={MASK if self.credentials.present else None!r})"
+
+
+def _parse_json(text: str) -> Any:
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return {"error": text[:200]}
+
+
+def clean_query(query: Optional[Mapping[str, Any]]) -> dict:
+    return {k: v for k, v in (query or {}).items() if v is not None}
+
+
+Sleep = Callable[[float], Any]