catalejo 0.1.0__tar.gz

catalejo-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+
+# local HTTP cache for CNMV requests
+.catalejo_cache/
+
+# raw screen recordings (only the converted GIFs go in the repo)
+docs/*.mov
+docs/Screen*

catalejo-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First public release.
+
+- `catalejo.filings()`: price-sensitive (IP) and other regulatory (OIR) announcements from the CNMV register, with full history since 2020, date ranges and server-side filtering by NIF.
+- `catalejo.securities()`: ISINs registered under an issuer (shares, bonds...).
+- `catalejo.document_text()`: text of the PDF attached to a filing (`catalejo[pdf]`).
+- MCP server (`catalejo-mcp`, `catalejo[mcp]`) with `latest_filings` and `issuer_filings` tools.
+- Polite by default: identifiable User-Agent, 1 request per second, on-disk cache.

catalejo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pol Fañanás
+
+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.

catalejo-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: catalejo
+Version: 0.1.0
+Summary: Clean, structured access to Spanish securities regulator (CNMV) public data, as a Python library and MCP server.
+Project-URL: Homepage, https://github.com/polfananas/catalejo
+Project-URL: Issues, https://github.com/polfananas/catalejo/issues
+Project-URL: Changelog, https://github.com/polfananas/catalejo/blob/main/CHANGELOG.md
+Author: Pol Fañanás
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cnmv,corporate-disclosures,edgar,finance,financial-data,mcp,securities,spain
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: selectolax>=1.0
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pypdf>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.20; extra == 'mcp'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=5; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# catalejo
+
+[![tests](https://github.com/polfananas/catalejo/actions/workflows/tests.yml/badge.svg)](https://github.com/polfananas/catalejo/actions/workflows/tests.yml)
+
+> *catalejo* (Spanish): spyglass.
+
+**Spain's securities regulator (CNMV) publishes everything listed companies have to disclose, but only through web forms and PDFs.** catalejo turns that into clean Python objects, and plugs it into AI agents through an MCP server.
+
+Think of it as a small **SEC EDGAR for Spain**.
+
+> *Having had perfect understanding of all things from the very first, to write unto thee in order, that thou mightest know the certainty of those things.* (Luke 1:3-4)
+
+![catalejo in a terminal: the latest price-sensitive announcements, 176 BBVA filings since 2020, the whole BBVA–Sabadell takeover bid in order, and its outcome read from the CNMV's own PDF. All live data.](https://raw.githubusercontent.com/polfananas/catalejo/main/docs/demo.gif)
+
+<!-- TODO: second GIF, Claude Desktop using the MCP server -->
+
+```python
+>>> import catalejo
+>>> for f in catalejo.filings(days=7, kind="IP"):
+...     print(f.registered_at, f.issuer, "|", f.title)
+2026-11-10 16:20:00+01:00 CONSTRUCCIONES Y AUXILIAR DE FERROCARRILES, S.A | El Consejo de Administración de la Sociedad ha aprobado el Plan Estratégico 2027-2030.
+2026-11-09 12:14:00+01:00 ELECNOR, S.A. | Elecnor comunica la propuesta del Consejo de Administración de distribución de un dividendo ...
+```
+
+## Install
+
+```bash
+pip install catalejo            # library
+pip install "catalejo[mcp]"     # + MCP server for Claude and other agents
+pip install "catalejo[pdf]"     # + text extraction from filed PDFs
+```
+
+Python 3.10+.
+
+## What you can get
+
+**Price-sensitive announcements (`IP`) and other regulatory announcements (`OIR`)**, the two channels issuers use to disclose anything that can move the price: results, M&A, takeover bids, guidance, board changes, buybacks...
+
+```python
+from datetime import date
+import catalejo
+
+catalejo.filings(days=3)                          # everything from the last 3 days, IP + OIR
+catalejo.filings(days=30, kind="IP", issuer="cellnex")
+
+# Full history for one company. Filtering by NIF (Spanish tax id) is done
+# by the CNMV itself, so years of data come back in a few seconds.
+catalejo.filings(since=date(2020, 1, 1), kind="IP", issuer="A64907306")
+```
+
+Each `Filing` has `kind`, `registered_at` (timezone-aware, Madrid), `issuer`, `issuer_nif`, `category`, `title`, `registry_number` and `document_url`.
+
+**The text of the filed document:**
+
+```python
+f = catalejo.filings(days=10, kind="IP", issuer="A64907306")[0]
+print(catalejo.document_text(f))     # needs catalejo[pdf]
+```
+
+**The securities (ISINs) of an issuer**, shares and bonds:
+
+```python
+>>> [s for s in catalejo.securities("A64907306") if s.is_share]
+[Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]
+```
+
+## Use it from Claude (MCP)
+
+catalejo ships an MCP server with two tools, `latest_filings` and `issuer_filings`, so you can ask things like *"What price-sensitive news has Cellnex published since 2023? Group it by topic."*
+
+**Claude Desktop:** add this to `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "catalejo": { "command": "catalejo-mcp" }
+  }
+}
+```
+
+If Claude can't find the command, use the full path from `which catalejo-mcp`.
+
+**Claude Code:** `claude mcp add catalejo -- catalejo-mcp`
+
+## Why not just ask an AI with web search?
+
+Because the CNMV's search pages are forms that search engines barely index. An agent with web search ends up reading press articles: incomplete, late, and you can't tell what's missing. With catalejo it reads the official register directly: every filing, with its exact time, registry number and a link to the original document. And it can do what web search can't, like going through years of history or across every issuer.
+
+## Being a good citizen
+
+catalejo talks only to `cnmv.es`, sends an identifiable User-Agent, makes **at most one request per second** and caches responses on disk (`~/.cache/catalejo`, or set `CATALEJO_CACHE_DIR`). Filed documents never change, so they are downloaded once. Please keep it that way if you fork it.
+
+## Good to know
+
+- **Price-sensitive announcements (`IP`) have their own channel since 8 February 2020.** Before that, everything was published as *hechos relevantes*, which catalejo doesn't cover yet.
+- Searching by **NIF** is fast (the CNMV filters). Searching by **name** works, but scans every filing in the window, so keep the window short.
+- Times are the CNMV's registration time, to the minute.
+- Filings come in the language the issuer used, which is almost always Spanish.
+- Early days: the API may still change before 1.0.
+
+## Roadmap
+
+- [x] Price-sensitive and other regulatory announcements, with full history
+- [x] ISINs per issuer, text of filed PDFs
+- [x] MCP server
+- [ ] Directors' and managers' share dealings (art. 19 MAR)
+- [ ] Net short positions
+- [ ] Takeover bids (OPAs): status, price, spread
+- [ ] Fund portfolios
+- [ ] CLI
+
+## Data and license
+
+The data comes from the [CNMV](https://www.cnmv.es) public registers and remains subject to the CNMV's [legal notice](https://www.cnmv.es/Portal/utilidades/NotaLegal): reproduce it faithfully, and if you ever sell it, tell your buyers it's free at cnmv.es. catalejo is not affiliated with or endorsed by the CNMV.
+
+Code: MIT. See [LICENSE](https://github.com/polfananas/catalejo/blob/main/LICENSE).

catalejo-0.1.0/README.md

@@ -0,0 +1,116 @@
+# catalejo
+
+[![tests](https://github.com/polfananas/catalejo/actions/workflows/tests.yml/badge.svg)](https://github.com/polfananas/catalejo/actions/workflows/tests.yml)
+
+> *catalejo* (Spanish): spyglass.
+
+**Spain's securities regulator (CNMV) publishes everything listed companies have to disclose, but only through web forms and PDFs.** catalejo turns that into clean Python objects, and plugs it into AI agents through an MCP server.
+
+Think of it as a small **SEC EDGAR for Spain**.
+
+> *Having had perfect understanding of all things from the very first, to write unto thee in order, that thou mightest know the certainty of those things.* (Luke 1:3-4)
+
+![catalejo in a terminal: the latest price-sensitive announcements, 176 BBVA filings since 2020, the whole BBVA–Sabadell takeover bid in order, and its outcome read from the CNMV's own PDF. All live data.](https://raw.githubusercontent.com/polfananas/catalejo/main/docs/demo.gif)
+
+<!-- TODO: second GIF, Claude Desktop using the MCP server -->
+
+```python
+>>> import catalejo
+>>> for f in catalejo.filings(days=7, kind="IP"):
+...     print(f.registered_at, f.issuer, "|", f.title)
+2026-11-10 16:20:00+01:00 CONSTRUCCIONES Y AUXILIAR DE FERROCARRILES, S.A | El Consejo de Administración de la Sociedad ha aprobado el Plan Estratégico 2027-2030.
+2026-11-09 12:14:00+01:00 ELECNOR, S.A. | Elecnor comunica la propuesta del Consejo de Administración de distribución de un dividendo ...
+```
+
+## Install
+
+```bash
+pip install catalejo            # library
+pip install "catalejo[mcp]"     # + MCP server for Claude and other agents
+pip install "catalejo[pdf]"     # + text extraction from filed PDFs
+```
+
+Python 3.10+.
+
+## What you can get
+
+**Price-sensitive announcements (`IP`) and other regulatory announcements (`OIR`)**, the two channels issuers use to disclose anything that can move the price: results, M&A, takeover bids, guidance, board changes, buybacks...
+
+```python
+from datetime import date
+import catalejo
+
+catalejo.filings(days=3)                          # everything from the last 3 days, IP + OIR
+catalejo.filings(days=30, kind="IP", issuer="cellnex")
+
+# Full history for one company. Filtering by NIF (Spanish tax id) is done
+# by the CNMV itself, so years of data come back in a few seconds.
+catalejo.filings(since=date(2020, 1, 1), kind="IP", issuer="A64907306")
+```
+
+Each `Filing` has `kind`, `registered_at` (timezone-aware, Madrid), `issuer`, `issuer_nif`, `category`, `title`, `registry_number` and `document_url`.
+
+**The text of the filed document:**
+
+```python
+f = catalejo.filings(days=10, kind="IP", issuer="A64907306")[0]
+print(catalejo.document_text(f))     # needs catalejo[pdf]
+```
+
+**The securities (ISINs) of an issuer**, shares and bonds:
+
+```python
+>>> [s for s in catalejo.securities("A64907306") if s.is_share]
+[Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]
+```
+
+## Use it from Claude (MCP)
+
+catalejo ships an MCP server with two tools, `latest_filings` and `issuer_filings`, so you can ask things like *"What price-sensitive news has Cellnex published since 2023? Group it by topic."*
+
+**Claude Desktop:** add this to `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "catalejo": { "command": "catalejo-mcp" }
+  }
+}
+```
+
+If Claude can't find the command, use the full path from `which catalejo-mcp`.
+
+**Claude Code:** `claude mcp add catalejo -- catalejo-mcp`
+
+## Why not just ask an AI with web search?
+
+Because the CNMV's search pages are forms that search engines barely index. An agent with web search ends up reading press articles: incomplete, late, and you can't tell what's missing. With catalejo it reads the official register directly: every filing, with its exact time, registry number and a link to the original document. And it can do what web search can't, like going through years of history or across every issuer.
+
+## Being a good citizen
+
+catalejo talks only to `cnmv.es`, sends an identifiable User-Agent, makes **at most one request per second** and caches responses on disk (`~/.cache/catalejo`, or set `CATALEJO_CACHE_DIR`). Filed documents never change, so they are downloaded once. Please keep it that way if you fork it.
+
+## Good to know
+
+- **Price-sensitive announcements (`IP`) have their own channel since 8 February 2020.** Before that, everything was published as *hechos relevantes*, which catalejo doesn't cover yet.
+- Searching by **NIF** is fast (the CNMV filters). Searching by **name** works, but scans every filing in the window, so keep the window short.
+- Times are the CNMV's registration time, to the minute.
+- Filings come in the language the issuer used, which is almost always Spanish.
+- Early days: the API may still change before 1.0.
+
+## Roadmap
+
+- [x] Price-sensitive and other regulatory announcements, with full history
+- [x] ISINs per issuer, text of filed PDFs
+- [x] MCP server
+- [ ] Directors' and managers' share dealings (art. 19 MAR)
+- [ ] Net short positions
+- [ ] Takeover bids (OPAs): status, price, spread
+- [ ] Fund portfolios
+- [ ] CLI
+
+## Data and license
+
+The data comes from the [CNMV](https://www.cnmv.es) public registers and remains subject to the CNMV's [legal notice](https://www.cnmv.es/Portal/utilidades/NotaLegal): reproduce it faithfully, and if you ever sell it, tell your buyers it's free at cnmv.es. catalejo is not affiliated with or endorsed by the CNMV.
+
+Code: MIT. See [LICENSE](https://github.com/polfananas/catalejo/blob/main/LICENSE).

catalejo-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "catalejo"
+version = "0.1.0"
+description = "Clean, structured access to Spanish securities regulator (CNMV) public data, as a Python library and MCP server."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Pol Fañanás" }]
+keywords = ["cnmv", "spain", "finance", "securities", "financial-data", "corporate-disclosures", "mcp", "edgar"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "selectolax>=1.0",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/polfananas/catalejo"
+Issues = "https://github.com/polfananas/catalejo/issues"
+Changelog = "https://github.com/polfananas/catalejo/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.10", "pypdf>=5"]
+pdf = ["pypdf>=5"]
+mcp = ["mcp>=1.20,<2"]
+
+[project.scripts]
+catalejo-mcp = "catalejo.mcp_server:main"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["docs", ".github"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/catalejo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+strict = true

catalejo-0.1.0/src/catalejo/__init__.py

@@ -0,0 +1,10 @@
+"""catalejo: Spanish CNMV public data, made usable."""
+
+__version__ = "0.1.0"
+
+from catalejo.documents import document_text
+from catalejo.filings import filings
+from catalejo.models import Filing, Security
+from catalejo.securities import securities
+
+__all__ = ["Filing", "Security", "document_text", "filings", "securities"]

catalejo-0.1.0/src/catalejo/_http.py

@@ -0,0 +1,203 @@
+"""Polite HTTP client for cnmv.es.
+
+Everything catalejo downloads goes through here, so the rules for being a
+good citizen live in one place:
+
+* identifiable User-Agent,
+* at most one request per ``min_interval`` seconds,
+* on-disk cache so repeated calls don't hit the CNMV again,
+* a few retries with backoff on 429/5xx and network errors,
+* only *.cnmv.es hosts are allowed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+
+from catalejo import __version__
+
+USER_AGENT = f"catalejo/{__version__} (+https://github.com/polfananas/catalejo)"
+ALLOWED_HOST_SUFFIX = "cnmv.es"
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+class CNMVRequestError(RuntimeError):
+    """Raised when the CNMV can't be reached or keeps answering with errors."""
+
+
+@dataclass(frozen=True)
+class Response:
+    url: str
+    status_code: int
+    content: bytes
+    content_type: str
+    from_cache: bool = False
+
+    @property
+    def text(self) -> str:
+        return self.content.decode("utf-8", errors="replace")
+
+
+def default_cache_dir() -> Path:
+    env = os.environ.get("CATALEJO_CACHE_DIR")
+    if env:
+        return Path(env)
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "catalejo"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        cache_dir: Path | None = None,
+        cache_ttl: float = 3600.0,
+        min_interval: float = 1.0,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.cache_dir = cache_dir if cache_dir is not None else default_cache_dir()
+        self.cache_ttl = cache_ttl
+        self.min_interval = min_interval
+        self.max_retries = max_retries
+        self._sleep = sleep
+        self._clock = clock
+        self._last_request: float | None = None
+        self._client = httpx.Client(
+            headers={"User-Agent": USER_AGENT},
+            timeout=timeout,
+            follow_redirects=True,
+            transport=transport,
+        )
+
+    # -- public -----------------------------------------------------------
+
+    def get(
+        self,
+        url: str,
+        params: Mapping[str, str | int] | None = None,
+        *,
+        use_cache: bool = True,
+        ttl: float | None = None,
+    ) -> Response:
+        """GET a cnmv.es URL. `ttl` overrides the client's cache_ttl for this call
+        (use `math.inf` for things that never change, like filed documents)."""
+        _check_host(url)
+        key = _cache_key(url, params)
+        ttl = self.cache_ttl if ttl is None else ttl
+
+        if use_cache and ttl > 0:
+            cached = self._read_cache(key, ttl)
+            if cached is not None:
+                return cached
+
+        response = self._fetch(url, params)
+        if use_cache and ttl > 0:
+            self._write_cache(key, response)
+        return response
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- internals --------------------------------------------------------
+
+    def _throttle(self) -> None:
+        if self._last_request is not None:
+            wait = self.min_interval - (self._clock() - self._last_request)
+            if wait > 0:
+                self._sleep(wait)
+        self._last_request = self._clock()
+
+    def _fetch(self, url: str, params: Mapping[str, str | int] | None) -> Response:
+        last_error: str = ""
+        for attempt in range(self.max_retries + 1):
+            if attempt:
+                self._sleep(min(2**attempt, 30))
+            self._throttle()
+            try:
+                r = self._client.get(url, params=dict(params) if params else None)
+            except httpx.TransportError as e:
+                last_error = f"{type(e).__name__}: {e}"
+                continue
+
+            if r.status_code in RETRY_STATUSES:
+                last_error = f"HTTP {r.status_code}"
+                retry_after = r.headers.get("Retry-After", "")
+                if retry_after.isdigit():
+                    self._sleep(min(int(retry_after), 60))
+                continue
+            if r.status_code >= 400:
+                raise CNMVRequestError(f"HTTP {r.status_code} for {r.url}")
+
+            return Response(
+                url=str(r.url),
+                status_code=r.status_code,
+                content=r.content,
+                content_type=r.headers.get("Content-Type", ""),
+            )
+
+        raise CNMVRequestError(
+            f"giving up on {url} after {self.max_retries + 1} attempts ({last_error})"
+        )
+
+    def _read_cache(self, key: str, ttl: float) -> Response | None:
+        meta_path = self.cache_dir / f"{key}.json"
+        body_path = self.cache_dir / f"{key}.bin"
+        try:
+            meta = json.loads(meta_path.read_text())
+            if time.time() - meta["fetched_at"] > ttl:
+                return None
+            content = body_path.read_bytes()
+        except (OSError, ValueError, KeyError):
+            return None
+        return Response(
+            url=meta["url"],
+            status_code=meta["status_code"],
+            content=content,
+            content_type=meta["content_type"],
+            from_cache=True,
+        )
+
+    def _write_cache(self, key: str, response: Response) -> None:
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+            (self.cache_dir / f"{key}.bin").write_bytes(response.content)
+            meta = {
+                "url": response.url,
+                "status_code": response.status_code,
+                "content_type": response.content_type,
+                "fetched_at": time.time(),
+            }
+            (self.cache_dir / f"{key}.json").write_text(json.dumps(meta))
+        except OSError:
+            pass  # a broken cache shouldn't break the request
+
+
+def _check_host(url: str) -> None:
+    host = (urlsplit(url).hostname or "").lower()
+    if host != ALLOWED_HOST_SUFFIX and not host.endswith("." + ALLOWED_HOST_SUFFIX):
+        raise ValueError(f"catalejo only talks to cnmv.es, got {host!r}")
+
+
+def _cache_key(url: str, params: Mapping[str, str | int] | None) -> str:
+    items = sorted((k, str(v)) for k, v in (params or {}).items())
+    raw = url + "?" + "&".join(f"{k}={v}" for k, v in items)
+    return hashlib.sha256(raw.encode()).hexdigest()[:32]