t212-tui 0.1.0__tar.gz

t212_tui-0.1.0/LICENSE

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

t212_tui-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: t212-tui
+Version: 0.1.0
+Summary: Read-only Trading 212 portfolio terminal
+Keywords: trading212,tui,terminal,portfolio,textual
+Author: shadowhusky
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: textual>=0.85
+Requires-Dist: textual-plotext>=0.2.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: click>=8.1
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/Shadowhusky/t212
+Description-Content-Type: text/markdown
+
+# t212
+
+A terminal dashboard for your Trading 212 account. Read-only by design: it can
+show you everything and touch nothing.
+
+```
+ t212  ● live · LIVE · GBP                                Wed 10 Jun 2026 · 14:32:05
+ Portfolio value  £24,813.07   Today ▲ +£86.20   Free £312.40
+ ──────────────────────────────────────────────────────────────────────────────
+  1 Dashboard    2 Positions    3 Pies    4 History    5 Search
+ ──────────────────────────────────────────────────────────────────────────────
+ INVESTMENTS                       CASH
+ Value      £24,395.17             Available   £312.40
+ Cost       £23,190.84             In pies     £105.50
+ Unrealised ▲ +£1,204.33  +5.19%   Reserved    £0.00
+ Realised   ▲ +£430.11
+
+ INCOME                            DEPOSITS
+ Dividends  £16.30                 Net deposits  £23,300.00
+ Interest   £1.95                  Gain vs in    ▲ +£1,513.07
+
+ EQUITY · since first run
+ ▁▂▂▃▃▄▄▅▅▆▆▇▇████▇▇▆▆▇▇████
+```
+
+I wanted to check my portfolio without opening the app or a browser tab, and
+without ever worrying that a stray keypress could place an order. So: a TUI
+that polls the public API politely, renders everything worth knowing, and has
+no code path that can mutate the account. The only HTTP verb in the client
+is `GET`.
+
+## What it shows
+
+- **Dashboard** – account value, unrealised and realised P&L, cash breakdown
+  (available / in pies / reserved), pending orders, dividend & interest income,
+  net deposits vs. current value, allocation, top movers, equity curve.
+- **Positions** – sortable table with value, P&L, FX impact and weight, plus a
+  detail view per holding. Quantity held inside pies is marked.
+- **Pies** – each AutoInvest pie with its return, dividends and goal progress;
+  drill in for target-vs-actual drift per instrument and any flagged issues.
+- **History** – orders with realised P&L and fees, dividends with running
+  totals (cash interest included), deposits and withdrawals with a running
+  balance. `m` pages further back.
+- **Search** – the full tradeable universe, filtered as you type. Holdings are
+  flagged; the detail view shows market hours.
+- **Equity curve** – the API exposes no account-value history, so t212 records
+  a snapshot locally (SQLite) each time it polls. The chart grows the longer
+  you use it and is labelled "since first run"; nothing is back-filled.
+
+Three themes (dark, light, high-contrast), a privacy blur (`z`) for
+screen-sharing, and gains/losses always carry an arrow and a sign, never
+colour alone.
+
+## Install
+
+Needs Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+git clone https://github.com/Shadowhusky/t212.git
+cd t212
+uv sync
+uv run t212
+```
+
+First run opens a guided setup: paste your API key ID and secret, pick live or
+demo, and it validates against the API before saving. There's also a
+"browse sample data" mode if you just want to poke around the UI first.
+
+To get a key: Trading 212 app → **Settings → API (Beta)** → generate. Enable
+the read scopes (Account, Portfolio, Pies, Metadata, History). *Orders read*
+is optional — it powers the pending-orders panel. t212 works with Invest and
+Stocks ISA accounts.
+
+Prefer configuring outside the TUI? Both of these work too:
+
+```sh
+export TRADING212_API_KEY="<keyId>:<secret>"   # env var
+uv run t212 config set-key                     # prompt, saved chmod 600
+```
+
+## Usage
+
+```sh
+uv run t212              # live account
+uv run t212 --demo       # practice account
+uv run t212 --mock       # sample data, no key needed
+uv run t212 --once       # plain-text summary to stdout, then exit
+uv run t212 --refresh 15 # poll interval in seconds
+```
+
+| Key | Action |
+| --- | --- |
+| `1`–`5` | Switch tab |
+| `↑`/`↓`, `j`/`k` | Move |
+| `Enter` / `Esc` | Open / close detail |
+| `←` `→` | History section |
+| `m` | Load more (History) |
+| `s` | Sort (Positions) |
+| `z` | Privacy blur |
+| `t` | Theme |
+| `r` | Refresh now |
+| `?` | Help |
+| `q` | Quit |
+
+## Notes on behaviour
+
+- Talks to the current `/api/v0` surface (account summary, positions, pies,
+  orders, equity history) with HTTP Basic `keyId:secret` auth.
+- The API is REST-only, so prices are polled — each endpoint on its own
+  cadence within its documented rate limit, with jitter, and automatic
+  back-off on `429`.
+- Only the active tab's data is polled.
+- Credentials live in `~/.config/t212/config.toml` (chmod 600) and are sent
+  nowhere except trading212.com. They are never logged or rendered.
+- Snapshots are stored per account in `~/.local/share/t212/`.
+
+## Development
+
+```sh
+uv run pytest -q     # 109 tests, fixture-driven, no network
+uv run t212 --mock   # full UI offline
+```
+
+```
+src/t212/
+  models.py     pydantic models for the API
+  api/          client protocol · httpx client · mock client · rate limiter
+  scheduler.py  per-tab polling
+  store.py      sqlite snapshots + instrument cache
+  app.py        Textual app shell
+  screens/      dashboard · positions · pies · history · search · setup · details
+  widgets/      header · tab bar · render primitives
+```
+
+## Disclaimer
+
+Unofficial, not affiliated with Trading 212. The API is in beta and may
+change. Not financial advice; use at your own risk.
+
+[MIT](LICENSE) © shadowhusky

t212_tui-0.1.0/README.md

@@ -0,0 +1,140 @@
+# t212
+
+A terminal dashboard for your Trading 212 account. Read-only by design: it can
+show you everything and touch nothing.
+
+```
+ t212  ● live · LIVE · GBP                                Wed 10 Jun 2026 · 14:32:05
+ Portfolio value  £24,813.07   Today ▲ +£86.20   Free £312.40
+ ──────────────────────────────────────────────────────────────────────────────
+  1 Dashboard    2 Positions    3 Pies    4 History    5 Search
+ ──────────────────────────────────────────────────────────────────────────────
+ INVESTMENTS                       CASH
+ Value      £24,395.17             Available   £312.40
+ Cost       £23,190.84             In pies     £105.50
+ Unrealised ▲ +£1,204.33  +5.19%   Reserved    £0.00
+ Realised   ▲ +£430.11
+
+ INCOME                            DEPOSITS
+ Dividends  £16.30                 Net deposits  £23,300.00
+ Interest   £1.95                  Gain vs in    ▲ +£1,513.07
+
+ EQUITY · since first run
+ ▁▂▂▃▃▄▄▅▅▆▆▇▇████▇▇▆▆▇▇████
+```
+
+I wanted to check my portfolio without opening the app or a browser tab, and
+without ever worrying that a stray keypress could place an order. So: a TUI
+that polls the public API politely, renders everything worth knowing, and has
+no code path that can mutate the account. The only HTTP verb in the client
+is `GET`.
+
+## What it shows
+
+- **Dashboard** – account value, unrealised and realised P&L, cash breakdown
+  (available / in pies / reserved), pending orders, dividend & interest income,
+  net deposits vs. current value, allocation, top movers, equity curve.
+- **Positions** – sortable table with value, P&L, FX impact and weight, plus a
+  detail view per holding. Quantity held inside pies is marked.
+- **Pies** – each AutoInvest pie with its return, dividends and goal progress;
+  drill in for target-vs-actual drift per instrument and any flagged issues.
+- **History** – orders with realised P&L and fees, dividends with running
+  totals (cash interest included), deposits and withdrawals with a running
+  balance. `m` pages further back.
+- **Search** – the full tradeable universe, filtered as you type. Holdings are
+  flagged; the detail view shows market hours.
+- **Equity curve** – the API exposes no account-value history, so t212 records
+  a snapshot locally (SQLite) each time it polls. The chart grows the longer
+  you use it and is labelled "since first run"; nothing is back-filled.
+
+Three themes (dark, light, high-contrast), a privacy blur (`z`) for
+screen-sharing, and gains/losses always carry an arrow and a sign, never
+colour alone.
+
+## Install
+
+Needs Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+git clone https://github.com/Shadowhusky/t212.git
+cd t212
+uv sync
+uv run t212
+```
+
+First run opens a guided setup: paste your API key ID and secret, pick live or
+demo, and it validates against the API before saving. There's also a
+"browse sample data" mode if you just want to poke around the UI first.
+
+To get a key: Trading 212 app → **Settings → API (Beta)** → generate. Enable
+the read scopes (Account, Portfolio, Pies, Metadata, History). *Orders read*
+is optional — it powers the pending-orders panel. t212 works with Invest and
+Stocks ISA accounts.
+
+Prefer configuring outside the TUI? Both of these work too:
+
+```sh
+export TRADING212_API_KEY="<keyId>:<secret>"   # env var
+uv run t212 config set-key                     # prompt, saved chmod 600
+```
+
+## Usage
+
+```sh
+uv run t212              # live account
+uv run t212 --demo       # practice account
+uv run t212 --mock       # sample data, no key needed
+uv run t212 --once       # plain-text summary to stdout, then exit
+uv run t212 --refresh 15 # poll interval in seconds
+```
+
+| Key | Action |
+| --- | --- |
+| `1`–`5` | Switch tab |
+| `↑`/`↓`, `j`/`k` | Move |
+| `Enter` / `Esc` | Open / close detail |
+| `←` `→` | History section |
+| `m` | Load more (History) |
+| `s` | Sort (Positions) |
+| `z` | Privacy blur |
+| `t` | Theme |
+| `r` | Refresh now |
+| `?` | Help |
+| `q` | Quit |
+
+## Notes on behaviour
+
+- Talks to the current `/api/v0` surface (account summary, positions, pies,
+  orders, equity history) with HTTP Basic `keyId:secret` auth.
+- The API is REST-only, so prices are polled — each endpoint on its own
+  cadence within its documented rate limit, with jitter, and automatic
+  back-off on `429`.
+- Only the active tab's data is polled.
+- Credentials live in `~/.config/t212/config.toml` (chmod 600) and are sent
+  nowhere except trading212.com. They are never logged or rendered.
+- Snapshots are stored per account in `~/.local/share/t212/`.
+
+## Development
+
+```sh
+uv run pytest -q     # 109 tests, fixture-driven, no network
+uv run t212 --mock   # full UI offline
+```
+
+```
+src/t212/
+  models.py     pydantic models for the API
+  api/          client protocol · httpx client · mock client · rate limiter
+  scheduler.py  per-tab polling
+  store.py      sqlite snapshots + instrument cache
+  app.py        Textual app shell
+  screens/      dashboard · positions · pies · history · search · setup · details
+  widgets/      header · tab bar · render primitives
+```
+
+## Disclaimer
+
+Unofficial, not affiliated with Trading 212. The API is in beta and may
+change. Not financial advice; use at your own risk.
+
+[MIT](LICENSE) © shadowhusky

t212_tui-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "t212-tui"
+version = "0.1.0"
+description = "Read-only Trading 212 portfolio terminal"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "shadowhusky" }]
+keywords = ["trading212", "tui", "terminal", "portfolio", "textual"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "textual>=0.85",
+    "textual-plotext>=0.2.1",
+    "httpx>=0.27",
+    "pydantic>=2.6",
+    "click>=8.1",
+]
+
+[project.urls]
+Repository = "https://github.com/Shadowhusky/t212"
+
+[project.scripts]
+t212 = "t212.cli:main"
+t212-tui = "t212.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "textual-dev>=1.8.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.uv.build-backend]
+module-name = "t212"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"

t212_tui-0.1.0/src/t212/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

t212_tui-0.1.0/src/t212/api/base.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+from typing import Protocol
+from t212.models import (AccountSummary, Position, PendingOrder, Pie, PieDetail,
+                         TradableInstrument, Exchange, HistoricalOrder, Dividend, Transaction)
+from t212.pagination import Page
+
+
+class ApiError(Exception):
+    pass
+
+
+class AuthError(ApiError):
+    pass
+
+
+class ScopeError(ApiError):
+    pass
+
+
+class RateLimited(ApiError):
+    def __init__(self, retry_after: float):
+        super().__init__(f"rate limited, retry in {retry_after:.0f}s")
+        self.retry_after = retry_after
+
+
+class T212Client(Protocol):
+    async def summary(self) -> AccountSummary: ...
+    async def positions(self) -> list[Position]: ...
+    async def orders(self) -> list[PendingOrder]: ...
+    async def pies(self) -> list[Pie]: ...
+    async def pie(self, pie_id: int) -> PieDetail: ...
+    async def instruments(self) -> list[TradableInstrument]: ...
+    async def exchanges(self) -> list[Exchange]: ...
+    async def history_orders(self, cursor: str | None = None,
+                             ticker: str | None = None) -> Page[HistoricalOrder]: ...
+    async def dividends(self, cursor: str | None = None,
+                        ticker: str | None = None) -> Page[Dividend]: ...
+    async def transactions(self, cursor: str | None = None) -> Page[Transaction]: ...
+    async def get_page(self, path: str) -> dict: ...
+    async def aclose(self) -> None: ...

t212_tui-0.1.0/src/t212/api/http.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+import time
+import httpx
+from t212.api.base import ApiError, AuthError, RateLimited, ScopeError
+from t212.api.ratelimit import RateLimitGovernor
+from t212.models import (AccountSummary, Position, PendingOrder, Pie, PieDetail,
+                         TradableInstrument, Exchange, HistoricalOrder, Dividend, Transaction)
+from t212.pagination import Page, parse_cursor
+
+V = "/api/v0"
+
+
+def _limit_key_for_path(path: str) -> str:
+    if "history/orders" in path:
+        return "history_orders"
+    if "dividends" in path:
+        return "dividends"
+    return "transactions"
+
+
+class HttpT212Client:
+    def __init__(self, *, api_key: str, base_url: str, governor: RateLimitGovernor,
+                 client: httpx.AsyncClient | None = None, timeout: float = 15.0):
+        self._gov = governor
+        if client is not None:
+            self._client = client
+        elif ":" in api_key:                       # current format: keyId:secret → HTTP Basic
+            key_id, secret = api_key.split(":", 1)
+            self._client = httpx.AsyncClient(
+                base_url=base_url, auth=httpx.BasicAuth(key_id, secret), timeout=timeout)
+        else:                                       # legacy single-key header
+            self._client = httpx.AsyncClient(
+                base_url=base_url, headers={"Authorization": api_key}, timeout=timeout)
+
+    async def _get(self, limit_key: str, path: str, params: dict | None = None):
+        await self._gov.acquire(limit_key)
+        try:
+            r = await self._client.get(path, params=params)
+        except httpx.HTTPError as e:
+            raise ApiError(str(e)) from e
+        if r.status_code == 429:
+            raw = float(r.headers.get("x-ratelimit-reset", "5"))
+            # header may be a unix timestamp rather than seconds-from-now
+            retry = max(1.0, raw - time.time()) if raw > 1e9 else raw
+            self._gov.note_server_reset(limit_key, retry)
+            raise RateLimited(retry)
+        if r.status_code == 401:
+            raise AuthError("unauthorized — check API key or live/demo environment")
+        if r.status_code == 403:
+            raise ScopeError("API key missing a required scope for this endpoint")
+        if r.status_code >= 400:
+            raise ApiError(f"HTTP {r.status_code} for {path}")
+        return r.json()
+
+    async def summary(self) -> AccountSummary:
+        return AccountSummary.model_validate(await self._get("summary", f"{V}/equity/account/summary"))
+
+    async def positions(self) -> list[Position]:
+        return [Position.model_validate(x) for x in await self._get("positions", f"{V}/equity/positions")]
+
+    async def orders(self) -> list[PendingOrder]:
+        return [PendingOrder.model_validate(x) for x in await self._get("orders", f"{V}/equity/orders")]
+
+    async def pies(self) -> list[Pie]:
+        return [Pie.model_validate(x) for x in await self._get("pies", f"{V}/equity/pies")]
+
+    async def pie(self, pie_id: int) -> PieDetail:
+        return PieDetail.model_validate(await self._get("pie", f"{V}/equity/pies/{pie_id}"))
+
+    async def instruments(self) -> list[TradableInstrument]:
+        return [TradableInstrument.model_validate(x)
+                for x in await self._get("instruments", f"{V}/equity/metadata/instruments")]
+
+    async def exchanges(self) -> list[Exchange]:
+        return [Exchange.model_validate(x) for x in await self._get("exchanges", f"{V}/equity/metadata/exchanges")]
+
+    async def _page(self, limit_key: str, path: str, model,
+                    cursor: str | None, ticker: str | None = None):
+        params: dict = {"limit": 50}
+        if cursor:
+            params["cursor"] = cursor
+        if ticker:
+            params["ticker"] = ticker
+        raw = await self._get(limit_key, path, params=params)
+        next_path = raw.get("nextPagePath")
+        return Page(items=[model.model_validate(x) for x in raw.get("items", [])],
+                    next_cursor=parse_cursor(next_path), next_path=next_path)
+
+    async def history_orders(self, cursor: str | None = None,
+                             ticker: str | None = None) -> Page[HistoricalOrder]:
+        return await self._page("history_orders", f"{V}/equity/history/orders",
+                                HistoricalOrder, cursor, ticker)
+
+    async def dividends(self, cursor: str | None = None,
+                        ticker: str | None = None) -> Page[Dividend]:
+        return await self._page("dividends", f"{V}/equity/history/dividends",
+                                Dividend, cursor, ticker)
+
+    async def transactions(self, cursor: str | None = None) -> Page[Transaction]:
+        return await self._page("transactions", f"{V}/equity/history/transactions",
+                                Transaction, cursor)
+
+    async def get_page(self, path: str) -> dict:
+        return await self._get(_limit_key_for_path(path), path)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

t212_tui-0.1.0/src/t212/api/limits.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+LIVE_URL = "https://live.trading212.com"
+DEMO_URL = "https://demo.trading212.com"
+
+# key: (capacity, per_seconds) — mirrors documented limits; honours x-ratelimit-reset at runtime
+RATE_LIMITS: dict[str, tuple[int, float]] = {
+    "summary": (1, 5.0),
+    "positions": (1, 1.0),
+    "orders": (1, 5.0),
+    "pies": (1, 30.0),
+    "pie": (1, 5.0),
+    "history_orders": (6, 60.0),
+    "dividends": (6, 60.0),
+    "transactions": (6, 60.0),
+    "instruments": (1, 50.0),
+    "exchanges": (1, 30.0),
+}

t212_tui-0.1.0/src/t212/api/mock.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+import json
+import pathlib
+from t212.models import (AccountSummary, Position, PendingOrder, Pie, PieDetail,
+                         TradableInstrument, Exchange, HistoricalOrder, Dividend, Transaction)
+from t212.pagination import Page, parse_cursor
+
+SAMPLE_DIR = pathlib.Path(__file__).parent.parent / "sample_data"
+
+
+class MockT212Client:
+    def __init__(self, fixtures_dir: str | pathlib.Path | None = None):
+        self._dir = pathlib.Path(fixtures_dir) if fixtures_dir else SAMPLE_DIR
+
+    def _load(self, name: str):
+        return json.loads((self._dir / f"{name}.json").read_text())
+
+    async def summary(self) -> AccountSummary:
+        return AccountSummary.model_validate(self._load("summary"))
+
+    async def positions(self) -> list[Position]:
+        return [Position.model_validate(x) for x in self._load("positions")]
+
+    async def orders(self) -> list[PendingOrder]:
+        try:
+            return [PendingOrder.model_validate(x) for x in self._load("orders")]
+        except FileNotFoundError:
+            return []
+
+    async def pies(self) -> list[Pie]:
+        return [Pie.model_validate(x) for x in self._load("pies")]
+
+    async def pie(self, pie_id: int) -> PieDetail:
+        return PieDetail.model_validate(self._load("pie_detail"))
+
+    async def instruments(self) -> list[TradableInstrument]:
+        return [TradableInstrument.model_validate(x) for x in self._load("instruments")]
+
+    async def exchanges(self) -> list[Exchange]:
+        return [Exchange.model_validate(x) for x in self._load("exchanges")]
+
+    def _page(self, name: str, model):
+        raw = self._load(name)
+        next_path = raw.get("nextPagePath")
+        return Page(items=[model.model_validate(x) for x in raw["items"]],
+                    next_cursor=parse_cursor(next_path), next_path=next_path)
+
+    async def history_orders(self, cursor: str | None = None,
+                             ticker: str | None = None) -> Page[HistoricalOrder]:
+        return self._page("history_orders", HistoricalOrder)
+
+    async def dividends(self, cursor: str | None = None,
+                        ticker: str | None = None) -> Page[Dividend]:
+        return self._page("dividends", Dividend)
+
+    async def transactions(self, cursor: str | None = None) -> Page[Transaction]:
+        return self._page("transactions", Transaction)
+
+    async def get_page(self, path: str) -> dict:
+        if "history/orders" in path:
+            return self._load("history_orders_page2")
+        return {"items": [], "nextPagePath": None}
+
+    async def aclose(self) -> None:
+        return None

t212_tui-0.1.0/src/t212/api/ratelimit.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import asyncio
+import random
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class _Bucket:
+    capacity: float
+    per_seconds: float
+    tokens: float
+    updated: float
+
+
+class RateLimitGovernor:
+    """Per-endpoint token bucket; honours server x-ratelimit-reset; jittered waits."""
+
+    def __init__(self, limits, *, clock=time.monotonic, sleep=asyncio.sleep, rng=random.random, jitter=0.25):
+        now = clock()
+        self._buckets = {k: _Bucket(c, s, c, now) for k, (c, s) in limits.items()}
+        self._clock = clock
+        self._sleep = sleep
+        self._rng = rng
+        self._jitter = jitter
+        self._reset_until: dict[str, float] = {}
+
+    def _refill(self, b: _Bucket, now: float) -> None:
+        elapsed = max(0.0, now - b.updated)
+        b.tokens = min(b.capacity, b.tokens + elapsed * (b.capacity / b.per_seconds))
+        b.updated = now
+
+    async def acquire(self, key: str) -> None:
+        b = self._buckets[key]
+        while True:
+            now = self._clock()
+            until = self._reset_until.get(key, 0.0)
+            if until > now:
+                await self._sleep(until - now)
+                now = self._clock()
+                self._reset_until.pop(key, None)
+                b.tokens = b.capacity
+                b.updated = now
+            self._refill(b, now)
+            if b.tokens >= 1.0:
+                b.tokens -= 1.0
+                return
+            deficit = 1.0 - b.tokens
+            wait = deficit * (b.per_seconds / b.capacity)
+            await self._sleep(wait * (1.0 + self._rng() * self._jitter))
+
+    def note_server_reset(self, key: str, seconds_from_now: float) -> None:
+        self._reset_until[key] = self._clock() + max(0.0, seconds_from_now)