prometiam-risk-api 0.1.0__tar.gz

prometiam_risk_api-0.1.0/LICENSE

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

prometiam_risk_api-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: prometiam-risk-api
+Version: 0.1.0
+Summary: Official Python client for the Prometiam Risk Intelligence API: EU company registry data (ES, FR, GB, IE, PL, NO, FI, SE, HR, BE, DK), corporate insolvency across twelve markets, sanctions screening, VAT and LEI lookups.
+Author-email: Prometiam <support@prometiam.com>
+License: MIT
+Project-URL: Homepage, https://www.prometiam.com/risk-api/docs
+Project-URL: Documentation, https://www.prometiam.com/risk-api/docs
+Keywords: prometiam,kyb,company-registry,sanctions-screening,insolvency,borme,bodacc,companies-house
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# prometiam-risk-api (Python)
+
+Official Python client for the [Prometiam Risk Intelligence API](https://www.prometiam.com/risk-api/docs): company registry data for Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium and Denmark, corporate insolvency notices across twelve markets, sanctions screening, VAT and LEI lookups.
+
+```bash
+pip install prometiam-risk-api
+```
+
+## Quick start
+
+```python
+import os
+from prometiam_risk_api import Client
+
+api = Client(api_key=os.environ["PROMETIAM_API_KEY"])
+
+page = api.companies_search(name="Inditex", country="ES")   # fuzzy, best match first (match_score 0-100)
+first = page["data"][0]
+print(first["company_name"], first["company_number"])
+
+detail = api.company(first["id"], include="risk_flags,insolvency")
+```
+
+Every method returns the API envelope `{"data": ..., "pagination": ..., "meta": ...}` exactly as documented.
+
+## Batch calls
+
+One HTTP call for a whole list. Every item counts as one request against your plan limits; a batch that does not fit raises `RateLimitError` whose `max_items_now` says how many items would fit.
+
+```python
+lookup = api.companies_lookup([
+    {"country": "ES", "company_number": "A46103834"},
+    {"country": "FR", "siren": "552032534"},
+    {"country": "ES", "name": "Inditex"},          # best fuzzy match, with match_score
+])
+for r in lookup["data"]:
+    print(r["status"], (r["company"] or {}).get("company_name"))
+
+screen = api.sanctions_screen_batch(["Vladimir Putin", "Acme Trading Ltd"], group="entity")
+flagged = [r for r in screen["data"] if r["status"] == "match"]
+
+distress = api.insolvency_check([
+    {"country": "FR", "company_number": "917499519"},
+    {"country": "DE", "name": "Wirecard"},
+])
+```
+
+## Pagination
+
+```python
+for page in api.paginate("/people/search", {"name": "garcia", "country": "ES", "limit": 50}):
+    for person in page:
+        print(person["full_name"])
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `AuthError` | 401, or 403 for a country the key cannot access |
+| `UpgradeRequiredError` | 403 `upgrade_required`: scope not in your plan or the free trial allowance is used up. Carries `included_in`, `price`, `upgrade_url`, `trial_allowance` |
+| `RateLimitError` | 429, retried automatically up to `max_retries` (default 2) honouring `Retry-After`; carries `retry_after` and `max_items_now` |
+| `ValidationError` | 400 |
+| `NotFoundError` | 404 |
+| `PrometiamError` | anything else; `status`, `code`, `body` on every error |
+
+## Options
+
+```python
+Client(api_key, base_url="https://api.prometiam.com/functions/v1/risk-api", timeout=30.0, max_retries=2, transport=None)
+```
+
+Use `with Client(...) as api:` to close the connection pool, and `api.request("GET", "/coverage")` for anything not wrapped.
+
+## Rate limits
+
+Per-key limits by plan (requests/minute, requests/day, requests/month):
+
+| Plan | Price | RPM | Daily | Monthly |
+|---|---|---|---|---|
+| Free (14-day trial) | €0 | 10 | 200 | 1,000 |
+| Starter | €9.99/mo | 60 | 2,000 | 10,000 |
+| Professional | €29.99/mo | 300 | 20,000 | 100,000 |
+| Scale | €99.99/mo | 600 | 200,000 | 1,000,000 |
+| Enterprise | Custom | Custom | Custom | Custom |
+
+`api.account()` returns your key's current limits and usage (`rate_limit.rpm_remaining`, `daily_remaining`, `monthly_remaining`). A 429 raises `RateLimitError`, retried automatically up to `max_retries` honouring `Retry-After`. Batch calls (`companies_lookup`, `sanctions_screen_batch`, `insolvency_check`) count every item in the list as one request against these limits; a batch that would not fit in the remaining quota raises `RateLimitError` up front (`code == "batch_exceeds_quota"`, `max_items_now` set).
+
+## Scope limits
+
+The API's coverage has real edges — every method above reflects them, not a marketing claim:
+
+- **Company registry (`companies_search`, `company`, `people_search`, `events_*`, `directors_network`):** Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium, Denmark. Ireland and Poland are company-level today (no officers yet). Finland, Sweden, Croatia, Belgium and Denmark are company records only, with register-change events (name, status, legal form and registered address; share capital for Croatia; dated when the change first appears in the register data, not gazette notices, none before 2026-09-30) and monitoring, but no officers and no registry-compliance signal. Corporate insolvency notices are linked by business ID (Finland), organisationsnummer (Sweden), MBS (Croatia) and CVR number (Denmark); Belgium has none (its bankruptcy shows in the company status and in its register-change events). Sole traders (enskild näringsverksamhet, trgovac pojedinac), enterprises of natural persons (eenmanszaak / entreprise individuelle), sole proprietorships (enkeltmandsvirksomhed) and estates are never served. Denmark has no share capital, and its status includes the register's bankruptcy state.
+- **Insolvency (`insolvency_search`, `insolvency_check`):** corporate only, twelve markets (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE). Personal/consumer insolvency is never returned. Spain's concursal data is on `records_search` (`GET /search`), not `insolvency_search`.
+- **Monitoring (`monitors`, `monitor`, `monitor_create`, `monitor_delete`):** ES, IE, PL, FI, SE, BE, HR, DK; alerts on status changes, dissolutions, sanctions matches and corporate events (ES and FI/SE/BE/HR/DK).
+- **Sanctions screening (`sanctions_screen*`):** beta.
+- **PEP hits (`sanctions_screen(name, include_pep=True)`):** beta, Spain only.
+- **Norway:** no corporate-event stream (`events_*` returns empty for NO, and for IE and PL).
+- **Finland:** company records only (`people_search` returns empty for FI; `events_*` returns register-change events, dated when first seen in the register data and none before 2026-09-30; `monitor_create` accepts it). Its insolvency notices are linked by business ID.
+- **Sweden:** company records only (`people_search` returns empty for SE; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs, företagsrekonstruktion, ackordsförhandling; updated weekly, no court, case number or source link, proceedings that ended before collection not included) are on `insolvency`, linked by organisationsnummer.
+- **Croatia:** company records only (`people_search` returns empty for HR; `events_*` returns register-change events, including share capital; `monitor_create` accepts it). Corporate insolvency notices (court decisions on bankruptcy, shortened bankruptcy and pre-bankruptcy proceedings, with court and case number where the register states them; only companies still on the register) are linked by MBS. A Croatian company is found by MBS (`company_number`), OIB (`oib`) or the VAT alias (`vat=HR` plus the OIB).
+- **Belgium:** company records only (`people_search` returns empty for BE; `events_*` returns register-change events; `monitor_create` accepts it). Belgium is not one of the twelve insolvency markets: its bankruptcy shows in the company status and in its register-change events. A Belgian company is found by enterprise number (`company_number`, the dots and spaces optional) or the VAT alias (`vat=BE` plus the ten digits).
+- **Denmark:** company records only (`people_search` returns empty for DK; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs and tvangsakkord decisions from CVR credit information, dated by the decision, no court or case number) are linked by CVR number. Contains CVR data (Erhvervsstyrelsen), CC BY 4.0. A Danish company is found by CVR number (`company_number`, spaces and hyphens optional; the mod-11 check is advisory) or the VAT alias (`vat=DK` plus the eight digits).
+
+## Get a key
+
+Free at https://www.prometiam.com/signup, no card required. Docs: https://www.prometiam.com/risk-api/docs. Support: support@prometiam.com.

prometiam_risk_api-0.1.0/README.md

@@ -0,0 +1,107 @@
+# prometiam-risk-api (Python)
+
+Official Python client for the [Prometiam Risk Intelligence API](https://www.prometiam.com/risk-api/docs): company registry data for Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium and Denmark, corporate insolvency notices across twelve markets, sanctions screening, VAT and LEI lookups.
+
+```bash
+pip install prometiam-risk-api
+```
+
+## Quick start
+
+```python
+import os
+from prometiam_risk_api import Client
+
+api = Client(api_key=os.environ["PROMETIAM_API_KEY"])
+
+page = api.companies_search(name="Inditex", country="ES")   # fuzzy, best match first (match_score 0-100)
+first = page["data"][0]
+print(first["company_name"], first["company_number"])
+
+detail = api.company(first["id"], include="risk_flags,insolvency")
+```
+
+Every method returns the API envelope `{"data": ..., "pagination": ..., "meta": ...}` exactly as documented.
+
+## Batch calls
+
+One HTTP call for a whole list. Every item counts as one request against your plan limits; a batch that does not fit raises `RateLimitError` whose `max_items_now` says how many items would fit.
+
+```python
+lookup = api.companies_lookup([
+    {"country": "ES", "company_number": "A46103834"},
+    {"country": "FR", "siren": "552032534"},
+    {"country": "ES", "name": "Inditex"},          # best fuzzy match, with match_score
+])
+for r in lookup["data"]:
+    print(r["status"], (r["company"] or {}).get("company_name"))
+
+screen = api.sanctions_screen_batch(["Vladimir Putin", "Acme Trading Ltd"], group="entity")
+flagged = [r for r in screen["data"] if r["status"] == "match"]
+
+distress = api.insolvency_check([
+    {"country": "FR", "company_number": "917499519"},
+    {"country": "DE", "name": "Wirecard"},
+])
+```
+
+## Pagination
+
+```python
+for page in api.paginate("/people/search", {"name": "garcia", "country": "ES", "limit": 50}):
+    for person in page:
+        print(person["full_name"])
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `AuthError` | 401, or 403 for a country the key cannot access |
+| `UpgradeRequiredError` | 403 `upgrade_required`: scope not in your plan or the free trial allowance is used up. Carries `included_in`, `price`, `upgrade_url`, `trial_allowance` |
+| `RateLimitError` | 429, retried automatically up to `max_retries` (default 2) honouring `Retry-After`; carries `retry_after` and `max_items_now` |
+| `ValidationError` | 400 |
+| `NotFoundError` | 404 |
+| `PrometiamError` | anything else; `status`, `code`, `body` on every error |
+
+## Options
+
+```python
+Client(api_key, base_url="https://api.prometiam.com/functions/v1/risk-api", timeout=30.0, max_retries=2, transport=None)
+```
+
+Use `with Client(...) as api:` to close the connection pool, and `api.request("GET", "/coverage")` for anything not wrapped.
+
+## Rate limits
+
+Per-key limits by plan (requests/minute, requests/day, requests/month):
+
+| Plan | Price | RPM | Daily | Monthly |
+|---|---|---|---|---|
+| Free (14-day trial) | €0 | 10 | 200 | 1,000 |
+| Starter | €9.99/mo | 60 | 2,000 | 10,000 |
+| Professional | €29.99/mo | 300 | 20,000 | 100,000 |
+| Scale | €99.99/mo | 600 | 200,000 | 1,000,000 |
+| Enterprise | Custom | Custom | Custom | Custom |
+
+`api.account()` returns your key's current limits and usage (`rate_limit.rpm_remaining`, `daily_remaining`, `monthly_remaining`). A 429 raises `RateLimitError`, retried automatically up to `max_retries` honouring `Retry-After`. Batch calls (`companies_lookup`, `sanctions_screen_batch`, `insolvency_check`) count every item in the list as one request against these limits; a batch that would not fit in the remaining quota raises `RateLimitError` up front (`code == "batch_exceeds_quota"`, `max_items_now` set).
+
+## Scope limits
+
+The API's coverage has real edges — every method above reflects them, not a marketing claim:
+
+- **Company registry (`companies_search`, `company`, `people_search`, `events_*`, `directors_network`):** Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium, Denmark. Ireland and Poland are company-level today (no officers yet). Finland, Sweden, Croatia, Belgium and Denmark are company records only, with register-change events (name, status, legal form and registered address; share capital for Croatia; dated when the change first appears in the register data, not gazette notices, none before 2026-09-30) and monitoring, but no officers and no registry-compliance signal. Corporate insolvency notices are linked by business ID (Finland), organisationsnummer (Sweden), MBS (Croatia) and CVR number (Denmark); Belgium has none (its bankruptcy shows in the company status and in its register-change events). Sole traders (enskild näringsverksamhet, trgovac pojedinac), enterprises of natural persons (eenmanszaak / entreprise individuelle), sole proprietorships (enkeltmandsvirksomhed) and estates are never served. Denmark has no share capital, and its status includes the register's bankruptcy state.
+- **Insolvency (`insolvency_search`, `insolvency_check`):** corporate only, twelve markets (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE). Personal/consumer insolvency is never returned. Spain's concursal data is on `records_search` (`GET /search`), not `insolvency_search`.
+- **Monitoring (`monitors`, `monitor`, `monitor_create`, `monitor_delete`):** ES, IE, PL, FI, SE, BE, HR, DK; alerts on status changes, dissolutions, sanctions matches and corporate events (ES and FI/SE/BE/HR/DK).
+- **Sanctions screening (`sanctions_screen*`):** beta.
+- **PEP hits (`sanctions_screen(name, include_pep=True)`):** beta, Spain only.
+- **Norway:** no corporate-event stream (`events_*` returns empty for NO, and for IE and PL).
+- **Finland:** company records only (`people_search` returns empty for FI; `events_*` returns register-change events, dated when first seen in the register data and none before 2026-09-30; `monitor_create` accepts it). Its insolvency notices are linked by business ID.
+- **Sweden:** company records only (`people_search` returns empty for SE; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs, företagsrekonstruktion, ackordsförhandling; updated weekly, no court, case number or source link, proceedings that ended before collection not included) are on `insolvency`, linked by organisationsnummer.
+- **Croatia:** company records only (`people_search` returns empty for HR; `events_*` returns register-change events, including share capital; `monitor_create` accepts it). Corporate insolvency notices (court decisions on bankruptcy, shortened bankruptcy and pre-bankruptcy proceedings, with court and case number where the register states them; only companies still on the register) are linked by MBS. A Croatian company is found by MBS (`company_number`), OIB (`oib`) or the VAT alias (`vat=HR` plus the OIB).
+- **Belgium:** company records only (`people_search` returns empty for BE; `events_*` returns register-change events; `monitor_create` accepts it). Belgium is not one of the twelve insolvency markets: its bankruptcy shows in the company status and in its register-change events. A Belgian company is found by enterprise number (`company_number`, the dots and spaces optional) or the VAT alias (`vat=BE` plus the ten digits).
+- **Denmark:** company records only (`people_search` returns empty for DK; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs and tvangsakkord decisions from CVR credit information, dated by the decision, no court or case number) are linked by CVR number. Contains CVR data (Erhvervsstyrelsen), CC BY 4.0. A Danish company is found by CVR number (`company_number`, spaces and hyphens optional; the mod-11 check is advisory) or the VAT alias (`vat=DK` plus the eight digits).
+
+## Get a key
+
+Free at https://www.prometiam.com/signup, no card required. Docs: https://www.prometiam.com/risk-api/docs. Support: support@prometiam.com.

prometiam_risk_api-0.1.0/prometiam_risk_api/__init__.py

@@ -0,0 +1,23 @@
+"""Official Python client for the Prometiam Risk Intelligence API."""
+from .client import DEFAULT_BASE_URL, SDK_VERSION, Client
+from .errors import (
+    AuthError,
+    NotFoundError,
+    PrometiamError,
+    RateLimitError,
+    UpgradeRequiredError,
+    ValidationError,
+)
+
+__all__ = [
+    "Client",
+    "DEFAULT_BASE_URL",
+    "SDK_VERSION",
+    "PrometiamError",
+    "AuthError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "UpgradeRequiredError",
+]
+__version__ = SDK_VERSION

prometiam_risk_api-0.1.0/prometiam_risk_api/client.py

@@ -0,0 +1,245 @@
+"""Prometiam Risk Intelligence API client.
+
+    from prometiam_risk_api import Client
+    api = Client(api_key=os.environ["PROMETIAM_API_KEY"])
+    page = api.companies_search(name="Inditex", country="ES")
+    print(page["data"][0]["company_name"])
+
+Every method returns the API envelope ``{"data": ..., "pagination": ..., "meta": ...}`` untouched, so the
+fields documented at https://www.prometiam.com/risk-api/docs are exactly what you get. Failures raise typed
+errors (see errors.py); 429 and 5xx responses are retried automatically, honouring Retry-After.
+"""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Union
+
+import httpx
+
+from .errors import RateLimitError, error_from_response
+
+DEFAULT_BASE_URL = "https://api.prometiam.com/functions/v1/risk-api"
+SDK_VERSION = "0.1.0"
+
+Params = Dict[str, Any]
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required (rk_live_...)")
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": f"prometiam-risk-api-python/{SDK_VERSION}",
+            },
+        )
+
+    # ── plumbing ─────────────────────────────────────────────────────────
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    @staticmethod
+    def _clean(params: Optional[Params]) -> Params:
+        return {k: v for k, v in (params or {}).items() if v is not None and v != ""}
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Params] = None,
+        json_body: Any = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Low-level call. Sends the key, retries 429/5xx, raises typed errors.
+
+        ``idempotency_key`` (batch POST endpoints only) is sent as the ``Idempotency-Key`` header:
+        a replay of the same key with the same request within 24h returns the stored response with
+        ``Idempotent-Replayed: true`` and costs no quota. See docs #idempotency-keys.
+        """
+        attempt = 0
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        while True:
+            res = self._http.request(method, path, params=self._clean(params), json=json_body, headers=headers)
+            text = res.text
+            try:
+                body = json.loads(text) if text else None
+            except ValueError:
+                body = None
+            if res.is_success:
+                return body if isinstance(body, dict) else {"data": body}
+            err = error_from_response(res.status_code, res.headers.get("retry-after"), body, text)
+            retryable = res.status_code == 429 or res.status_code >= 500
+            if retryable and attempt < self.max_retries:
+                attempt += 1
+                wait = err.retry_after if isinstance(err, RateLimitError) else 0.5 * (2 ** attempt)
+                time.sleep(min(wait, 60.0))
+                continue
+            raise err
+
+    def paginate(self, path: str, params: Optional[Params] = None, max_pages: Optional[int] = None) -> Iterator[List[Any]]:
+        """Yield each page's ``data`` of a cursor-paginated GET endpoint."""
+        params = dict(params or {})
+        cursor = params.pop("cursor", None)
+        pages = 0
+        while True:
+            page = self.request("GET", path, params={**params, "cursor": cursor})
+            yield page.get("data") or []
+            pages += 1
+            pag = page.get("pagination") or {}
+            cursor = pag.get("next_cursor") if pag.get("has_more") else None
+            if not cursor or (max_pages is not None and pages >= max_pages):
+                return
+
+    # ── companies ────────────────────────────────────────────────────────
+    def companies_search(self, **params: Any) -> Dict[str, Any]:
+        """GET /companies/search: name (fuzzy, match_score), company_number/nif/siren/vat, founded_after, cnae, objeto..."""
+        return self.request("GET", "/companies/search", params)
+
+    def company(self, company_id: Union[int, str], **params: Any) -> Dict[str, Any]:
+        """GET /companies/{id}: full detail; include=risk_flags,insolvency,procurement,lei or all."""
+        return self.request("GET", f"/companies/{company_id}", params)
+
+    def companies_lookup(self, items: Iterable[Dict[str, Any]], idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """POST /companies/lookup: up to 100 identifiers or names in one call; every item counts as one request.
+        ``idempotency_key`` makes a retry of the exact same batch free and safe to repeat (docs #idempotency-keys)."""
+        return self.request("POST", "/companies/lookup", json_body={"items": list(items)}, idempotency_key=idempotency_key)
+
+    # ── people / events ──────────────────────────────────────────────────
+    def people_search(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/people/search", params)
+
+    def person(self, person_id: Union[int, str], **params: Any) -> Dict[str, Any]:
+        return self.request("GET", f"/people/{person_id}", params)
+
+    def events_search(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/company-events/search", params)
+
+    def events_timeline(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/company-events/timeline", params)
+
+    def event(self, event_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("GET", f"/company-events/records/{event_id}")
+
+    # ── sanctions ────────────────────────────────────────────────────────
+    def sanctions_screen(self, name: str, **params: Any) -> Dict[str, Any]:
+        """GET /sanctions/screen: fuzzy screen of one name; group='entity' folds hits per listed person or company."""
+        return self.request("GET", "/sanctions/screen", {"name": name, **params})
+
+    def sanctions_screen_batch(
+        self,
+        items: Iterable[Union[str, Dict[str, Any]]],
+        idempotency_key: Optional[str] = None,
+        **options: Any,
+    ) -> Dict[str, Any]:
+        """POST /sanctions/screen: up to 50 names in one call (sanctions scope; no trial allowance).
+        Options: threshold, list, active_only, group='entity', limit (hits per name).
+        ``idempotency_key`` makes a retry of the exact same batch free and safe to repeat (docs #idempotency-keys)."""
+        norm = [{"name": i} if isinstance(i, str) else i for i in items]
+        return self.request("POST", "/sanctions/screen", json_body={**options, "items": norm}, idempotency_key=idempotency_key)
+
+    def sanctions_entity(self, entity_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("GET", f"/sanctions/entity/{entity_id}")
+
+    def sanctions_changes(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/sanctions/changes", params)
+
+    def watchlist(self) -> Dict[str, Any]:
+        return self.request("GET", "/sanctions/watchlist")
+
+    def watchlist_add(self, **body: Any) -> Dict[str, Any]:
+        return self.request("POST", "/sanctions/watchlist", json_body=body)
+
+    def watchlist_remove(self, entry_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("DELETE", f"/sanctions/watchlist/{entry_id}")
+
+    # ── insolvency / notices ─────────────────────────────────────────────
+    def procurement_awards(self, **params: Any) -> Dict[str, Any]:
+        """GET /procurement/awards: public-contract awards (ES, FR, GB, IE, PL, NO) by supplier, buyer, nif, cpv or date; one row per award to one supplier."""
+        return self.request("GET", "/procurement/awards", params)
+
+    def procurement_buyer(self, buyer_id: str, **params: Any) -> Dict[str, Any]:
+        """GET /procurement/buyer/{id}: public-buyer risk profile (beta, ES + FR); scores about the contracting body."""
+        return self.request("GET", f"/procurement/buyer/{buyer_id}", params)
+
+    def procurement_buyers(self, **params: Any) -> Dict[str, Any]:
+        """GET /procurement/buyers: scored public buyers ordered by score (beta, ES + FR)."""
+        return self.request("GET", "/procurement/buyers", params)
+
+    def procurement_relationship(self, **params: Any) -> Dict[str, Any]:
+        """GET /procurement/relationship: a buyer and one of its five largest suppliers (beta, ES + FR)."""
+        return self.request("GET", "/procurement/relationship", params)
+
+    def insolvency_search(self, **params: Any) -> Dict[str, Any]:
+        """GET /insolvency/search: corporate notices across FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE."""
+        return self.request("GET", "/insolvency/search", params)
+
+    def insolvency_check(self, items: Iterable[Dict[str, Any]], idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """POST /insolvency/check: up to 100 counterparties in one call.
+        ``idempotency_key`` makes a retry of the exact same batch free and safe to repeat (docs #idempotency-keys)."""
+        return self.request("POST", "/insolvency/check", json_body={"items": list(items)}, idempotency_key=idempotency_key)
+
+    def records_search(self, **params: Any) -> Dict[str, Any]:
+        """GET /search: Spanish risk and concursal notices."""
+        return self.request("GET", "/search", params)
+
+    def record(self, record_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("GET", f"/records/{record_id}")
+
+    def notice(self, notice_id: Union[int, str], **params: Any) -> Dict[str, Any]:
+        return self.request("GET", f"/notices/{notice_id}", params)
+
+    # ── graph / registries ───────────────────────────────────────────────
+    def directors_network(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/directors/network", params)
+
+    def vat(self, vat_number: str) -> Dict[str, Any]:
+        return self.request("GET", f"/vat/{vat_number}")
+
+    def lei(self, lei: str) -> Dict[str, Any]:
+        return self.request("GET", f"/lei/{lei}")
+
+    def lei_relationships(self, lei: str) -> Dict[str, Any]:
+        return self.request("GET", f"/lei/{lei}/relationships")
+
+    def lei_search(self, **params: Any) -> Dict[str, Any]:
+        return self.request("GET", "/lei/search", params)
+
+    # ── monitoring / account ─────────────────────────────────────────────
+    def monitors(self) -> Dict[str, Any]:
+        return self.request("GET", "/monitor")
+
+    def monitor(self, monitor_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("GET", f"/monitor/{monitor_id}")
+
+    def monitor_create(self, **body: Any) -> Dict[str, Any]:
+        return self.request("POST", "/monitor", json_body=body)
+
+    def monitor_delete(self, monitor_id: Union[int, str]) -> Dict[str, Any]:
+        return self.request("DELETE", f"/monitor/{monitor_id}")
+
+    def coverage(self) -> Dict[str, Any]:
+        return self.request("GET", "/coverage")
+
+    def account(self) -> Dict[str, Any]:
+        return self.request("GET", "/account")

prometiam_risk_api-0.1.0/prometiam_risk_api/errors.py

@@ -0,0 +1,82 @@
+"""Errors raised by the Prometiam client. Every one carries the HTTP status, the API's error code and the raw body."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class PrometiamError(Exception):
+    def __init__(self, message: str, status: int, code: str, body: Any):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{self.__class__.__name__}(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class AuthError(PrometiamError):
+    """401, or 403 for a country the key cannot access."""
+
+
+class ValidationError(PrometiamError):
+    """400 / 422."""
+
+
+class NotFoundError(PrometiamError):
+    """404."""
+
+
+class RateLimitError(PrometiamError):
+    """429: per-minute, daily or monthly limit, or a batch larger than the remaining quota."""
+
+    def __init__(self, message: str, status: int, code: str, body: Any, retry_after: float):
+        super().__init__(message, status, code, body)
+        self.retry_after = retry_after
+        b = body if isinstance(body, dict) else {}
+        self.max_items_now: Optional[int] = b.get("max_items_now") if isinstance(b.get("max_items_now"), int) else None
+
+
+class UpgradeRequiredError(PrometiamError):
+    """403 upgrade_required: the scope is not in the plan, or the free trial allowance for it is used up."""
+
+    def __init__(self, message: str, status: int, code: str, body: Any):
+        super().__init__(message, status, code, body)
+        b = body if isinstance(body, dict) else {}
+        self.required_scope: Optional[str] = b.get("required_scope")
+        self.included_in: Optional[str] = b.get("included_in")
+        self.price: Optional[str] = b.get("price")
+        self.upgrade_url: Optional[str] = b.get("upgrade_url")
+        self.trial_allowance: Optional[dict] = b.get("trial_allowance")
+
+
+def error_from_response(status: int, retry_after_header: Optional[str], body: Any, raw_text: str) -> PrometiamError:
+    b = body if isinstance(body, dict) else {}
+    err = b.get("error") if isinstance(b.get("error"), dict) else {}
+    code = str(err.get("code") or b.get("code") or ("rate_limit_exceeded" if status == 429 else "server_error" if status >= 500 else "error"))
+    message = str(err.get("message") or b.get("message") or (raw_text[:200] if raw_text else f"HTTP {status}"))
+    if status == 401:
+        return AuthError(message, status, code, body)
+    if status == 403 and code == "upgrade_required":
+        return UpgradeRequiredError(message, status, code, body)
+    if status == 403:
+        return AuthError(message, status, code, body)
+    if status == 404:
+        return NotFoundError(message, status, code, body)
+    if status in (400, 422):
+        return ValidationError(message, status, code, body)
+    if status == 429:
+        retry_after: Optional[float] = None
+        for candidate in (retry_after_header, b.get("retry_after_seconds")):
+            if candidate is None or candidate == "":
+                continue
+            try:
+                v = float(candidate)
+            except (TypeError, ValueError):
+                continue
+            if v >= 0:
+                retry_after = v
+                break
+        return RateLimitError(message, status, code, body, 60.0 if retry_after is None else retry_after)
+    return PrometiamError(message, status, code, body)

prometiam_risk_api-0.1.0/prometiam_risk_api.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: prometiam-risk-api
+Version: 0.1.0
+Summary: Official Python client for the Prometiam Risk Intelligence API: EU company registry data (ES, FR, GB, IE, PL, NO, FI, SE, HR, BE, DK), corporate insolvency across twelve markets, sanctions screening, VAT and LEI lookups.
+Author-email: Prometiam <support@prometiam.com>
+License: MIT
+Project-URL: Homepage, https://www.prometiam.com/risk-api/docs
+Project-URL: Documentation, https://www.prometiam.com/risk-api/docs
+Keywords: prometiam,kyb,company-registry,sanctions-screening,insolvency,borme,bodacc,companies-house
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# prometiam-risk-api (Python)
+
+Official Python client for the [Prometiam Risk Intelligence API](https://www.prometiam.com/risk-api/docs): company registry data for Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium and Denmark, corporate insolvency notices across twelve markets, sanctions screening, VAT and LEI lookups.
+
+```bash
+pip install prometiam-risk-api
+```
+
+## Quick start
+
+```python
+import os
+from prometiam_risk_api import Client
+
+api = Client(api_key=os.environ["PROMETIAM_API_KEY"])
+
+page = api.companies_search(name="Inditex", country="ES")   # fuzzy, best match first (match_score 0-100)
+first = page["data"][0]
+print(first["company_name"], first["company_number"])
+
+detail = api.company(first["id"], include="risk_flags,insolvency")
+```
+
+Every method returns the API envelope `{"data": ..., "pagination": ..., "meta": ...}` exactly as documented.
+
+## Batch calls
+
+One HTTP call for a whole list. Every item counts as one request against your plan limits; a batch that does not fit raises `RateLimitError` whose `max_items_now` says how many items would fit.
+
+```python
+lookup = api.companies_lookup([
+    {"country": "ES", "company_number": "A46103834"},
+    {"country": "FR", "siren": "552032534"},
+    {"country": "ES", "name": "Inditex"},          # best fuzzy match, with match_score
+])
+for r in lookup["data"]:
+    print(r["status"], (r["company"] or {}).get("company_name"))
+
+screen = api.sanctions_screen_batch(["Vladimir Putin", "Acme Trading Ltd"], group="entity")
+flagged = [r for r in screen["data"] if r["status"] == "match"]
+
+distress = api.insolvency_check([
+    {"country": "FR", "company_number": "917499519"},
+    {"country": "DE", "name": "Wirecard"},
+])
+```
+
+## Pagination
+
+```python
+for page in api.paginate("/people/search", {"name": "garcia", "country": "ES", "limit": 50}):
+    for person in page:
+        print(person["full_name"])
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `AuthError` | 401, or 403 for a country the key cannot access |
+| `UpgradeRequiredError` | 403 `upgrade_required`: scope not in your plan or the free trial allowance is used up. Carries `included_in`, `price`, `upgrade_url`, `trial_allowance` |
+| `RateLimitError` | 429, retried automatically up to `max_retries` (default 2) honouring `Retry-After`; carries `retry_after` and `max_items_now` |
+| `ValidationError` | 400 |
+| `NotFoundError` | 404 |
+| `PrometiamError` | anything else; `status`, `code`, `body` on every error |
+
+## Options
+
+```python
+Client(api_key, base_url="https://api.prometiam.com/functions/v1/risk-api", timeout=30.0, max_retries=2, transport=None)
+```
+
+Use `with Client(...) as api:` to close the connection pool, and `api.request("GET", "/coverage")` for anything not wrapped.
+
+## Rate limits
+
+Per-key limits by plan (requests/minute, requests/day, requests/month):
+
+| Plan | Price | RPM | Daily | Monthly |
+|---|---|---|---|---|
+| Free (14-day trial) | €0 | 10 | 200 | 1,000 |
+| Starter | €9.99/mo | 60 | 2,000 | 10,000 |
+| Professional | €29.99/mo | 300 | 20,000 | 100,000 |
+| Scale | €99.99/mo | 600 | 200,000 | 1,000,000 |
+| Enterprise | Custom | Custom | Custom | Custom |
+
+`api.account()` returns your key's current limits and usage (`rate_limit.rpm_remaining`, `daily_remaining`, `monthly_remaining`). A 429 raises `RateLimitError`, retried automatically up to `max_retries` honouring `Retry-After`. Batch calls (`companies_lookup`, `sanctions_screen_batch`, `insolvency_check`) count every item in the list as one request against these limits; a batch that would not fit in the remaining quota raises `RateLimitError` up front (`code == "batch_exceeds_quota"`, `max_items_now` set).
+
+## Scope limits
+
+The API's coverage has real edges — every method above reflects them, not a marketing claim:
+
+- **Company registry (`companies_search`, `company`, `people_search`, `events_*`, `directors_network`):** Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium, Denmark. Ireland and Poland are company-level today (no officers yet). Finland, Sweden, Croatia, Belgium and Denmark are company records only, with register-change events (name, status, legal form and registered address; share capital for Croatia; dated when the change first appears in the register data, not gazette notices, none before 2026-09-30) and monitoring, but no officers and no registry-compliance signal. Corporate insolvency notices are linked by business ID (Finland), organisationsnummer (Sweden), MBS (Croatia) and CVR number (Denmark); Belgium has none (its bankruptcy shows in the company status and in its register-change events). Sole traders (enskild näringsverksamhet, trgovac pojedinac), enterprises of natural persons (eenmanszaak / entreprise individuelle), sole proprietorships (enkeltmandsvirksomhed) and estates are never served. Denmark has no share capital, and its status includes the register's bankruptcy state.
+- **Insolvency (`insolvency_search`, `insolvency_check`):** corporate only, twelve markets (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE). Personal/consumer insolvency is never returned. Spain's concursal data is on `records_search` (`GET /search`), not `insolvency_search`.
+- **Monitoring (`monitors`, `monitor`, `monitor_create`, `monitor_delete`):** ES, IE, PL, FI, SE, BE, HR, DK; alerts on status changes, dissolutions, sanctions matches and corporate events (ES and FI/SE/BE/HR/DK).
+- **Sanctions screening (`sanctions_screen*`):** beta.
+- **PEP hits (`sanctions_screen(name, include_pep=True)`):** beta, Spain only.
+- **Norway:** no corporate-event stream (`events_*` returns empty for NO, and for IE and PL).
+- **Finland:** company records only (`people_search` returns empty for FI; `events_*` returns register-change events, dated when first seen in the register data and none before 2026-09-30; `monitor_create` accepts it). Its insolvency notices are linked by business ID.
+- **Sweden:** company records only (`people_search` returns empty for SE; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs, företagsrekonstruktion, ackordsförhandling; updated weekly, no court, case number or source link, proceedings that ended before collection not included) are on `insolvency`, linked by organisationsnummer.
+- **Croatia:** company records only (`people_search` returns empty for HR; `events_*` returns register-change events, including share capital; `monitor_create` accepts it). Corporate insolvency notices (court decisions on bankruptcy, shortened bankruptcy and pre-bankruptcy proceedings, with court and case number where the register states them; only companies still on the register) are linked by MBS. A Croatian company is found by MBS (`company_number`), OIB (`oib`) or the VAT alias (`vat=HR` plus the OIB).
+- **Belgium:** company records only (`people_search` returns empty for BE; `events_*` returns register-change events; `monitor_create` accepts it). Belgium is not one of the twelve insolvency markets: its bankruptcy shows in the company status and in its register-change events. A Belgian company is found by enterprise number (`company_number`, the dots and spaces optional) or the VAT alias (`vat=BE` plus the ten digits).
+- **Denmark:** company records only (`people_search` returns empty for DK; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs and tvangsakkord decisions from CVR credit information, dated by the decision, no court or case number) are linked by CVR number. Contains CVR data (Erhvervsstyrelsen), CC BY 4.0. A Danish company is found by CVR number (`company_number`, spaces and hyphens optional; the mod-11 check is advisory) or the VAT alias (`vat=DK` plus the eight digits).
+
+## Get a key
+
+Free at https://www.prometiam.com/signup, no card required. Docs: https://www.prometiam.com/risk-api/docs. Support: support@prometiam.com.

prometiam_risk_api-0.1.0/prometiam_risk_api.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+prometiam_risk_api/__init__.py
+prometiam_risk_api/client.py
+prometiam_risk_api/errors.py
+prometiam_risk_api.egg-info/PKG-INFO
+prometiam_risk_api.egg-info/SOURCES.txt
+prometiam_risk_api.egg-info/dependency_links.txt
+prometiam_risk_api.egg-info/requires.txt
+prometiam_risk_api.egg-info/top_level.txt
+tests/test_client.py

prometiam_risk_api-0.1.0/prometiam_risk_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prometiam_risk_api-0.1.0/prometiam_risk_api.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.25

prometiam_risk_api-0.1.0/prometiam_risk_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+prometiam_risk_api

prometiam_risk_api-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "prometiam-risk-api"
+version = "0.1.0"
+description = "Official Python client for the Prometiam Risk Intelligence API: EU company registry data (ES, FR, GB, IE, PL, NO, FI, SE, HR, BE, DK), corporate insolvency across twelve markets, sanctions screening, VAT and LEI lookups."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Prometiam", email = "support@prometiam.com" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25"]
+keywords = ["prometiam", "kyb", "company-registry", "sanctions-screening", "insolvency", "borme", "bodacc", "companies-house"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Topic :: Office/Business :: Financial",
+]
+
+[project.urls]
+Homepage = "https://www.prometiam.com/risk-api/docs"
+Documentation = "https://www.prometiam.com/risk-api/docs"
+
+[tool.setuptools]
+packages = ["prometiam_risk_api"]

prometiam_risk_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prometiam_risk_api-0.1.0/tests/test_client.py

@@ -0,0 +1,122 @@
+import json
+import sys
+import unittest
+from pathlib import Path
+
+import httpx
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from prometiam_risk_api import AuthError, Client, RateLimitError, UpgradeRequiredError  # noqa: E402
+
+
+def make_client(handler, **kw):
+    calls = []
+
+    def _handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return handler(request, len(calls))
+
+    return Client(api_key="rk_live_test", transport=httpx.MockTransport(_handler), **kw), calls
+
+
+class ClientTests(unittest.TestCase):
+    def test_sends_key_and_query(self):
+        api, calls = make_client(lambda r, n: httpx.Response(200, json={"data": [{"company_name": "INDITEX SA"}], "meta": {"query_ms": 5}}))
+        res = api.companies_search(name="Inditex", country="ES", limit=1, empty=None)
+        self.assertEqual(res["data"][0]["company_name"], "INDITEX SA")
+        self.assertEqual(calls[0].headers["authorization"], "Bearer rk_live_test")
+        self.assertEqual(calls[0].url.path, "/functions/v1/risk-api/companies/search")
+        self.assertEqual(calls[0].url.params["name"], "Inditex")
+        self.assertNotIn("empty", calls[0].url.params)
+
+    def test_batch_lookup_posts_items(self):
+        def h(r, n):
+            body = json.loads(r.content)
+            return httpx.Response(200, json={"data": [{"index": i, "status": "found"} for i, _ in enumerate(body["items"])], "meta": {"found": len(body["items"])}})
+        api, calls = make_client(h)
+        res = api.companies_lookup([{"country": "ES", "company_number": "A46103834"}, {"country": "FR", "siren": "552032534"}])
+        self.assertEqual(calls[0].method, "POST")
+        self.assertEqual(res["meta"]["found"], 2)
+
+    def test_sanctions_batch_normalises_strings(self):
+        api, calls = make_client(lambda r, n: httpx.Response(200, json={"data": []}))
+        api.sanctions_screen_batch(["Vladimir Putin", {"name": "Acme", "entity_type": "company"}], group="entity", threshold=85)
+        body = json.loads(calls[0].content)
+        self.assertEqual(body["items"], [{"name": "Vladimir Putin"}, {"name": "Acme", "entity_type": "company"}])
+        self.assertEqual(body["group"], "entity")
+
+    def test_idempotency_key_sent_as_header_on_batch_methods(self):
+        api, calls = make_client(lambda r, n: httpx.Response(200, json={"data": [], "meta": {}}))
+        api.companies_lookup([{"country": "ES", "company_number": "A46103834"}], idempotency_key="key-1")
+        self.assertEqual(calls[0].headers["idempotency-key"], "key-1")
+
+        api.sanctions_screen_batch(["Vladimir Putin"], idempotency_key="key-2")
+        self.assertEqual(calls[1].headers["idempotency-key"], "key-2")
+
+        api.insolvency_check([{"country": "FR", "siren": "552032534"}], idempotency_key="key-3")
+        self.assertEqual(calls[2].headers["idempotency-key"], "key-3")
+
+        api.companies_lookup([{"country": "ES", "company_number": "A46103834"}])
+        self.assertNotIn("idempotency-key", calls[3].headers)
+
+    def test_idempotency_key_reuse_and_in_progress_raise_typed_errors(self):
+        api422, _ = make_client(lambda r, n: httpx.Response(
+            422, json={"error": {"code": "idempotency_key_reuse", "message": "reused with a different body", "status": 422}}))
+        with self.assertRaises(Exception) as ctx:
+            api422.companies_lookup([{"country": "ES", "company_number": "A46103834"}], idempotency_key="dup")
+        self.assertEqual(ctx.exception.code, "idempotency_key_reuse")
+        self.assertEqual(ctx.exception.status, 422)
+
+        api409, _ = make_client(
+            lambda r, n: httpx.Response(409, headers={"Retry-After": "2"}, json={"error": {"code": "idempotency_key_in_progress", "message": "still running", "status": 409}}),
+            max_retries=0,
+        )
+        with self.assertRaises(Exception) as ctx:
+            api409.companies_lookup([{"country": "ES", "company_number": "A46103834"}], idempotency_key="inflight")
+        self.assertEqual(ctx.exception.code, "idempotency_key_in_progress")
+        self.assertEqual(ctx.exception.status, 409)
+
+    def test_retries_429_then_succeeds(self):
+        def h(r, n):
+            if n == 1:
+                return httpx.Response(429, headers={"Retry-After": "0"}, json={"error": {"code": "rate_limit_exceeded", "message": "slow", "status": 429}})
+            return httpx.Response(200, json={"data": {"ok": True}})
+        api, calls = make_client(h, max_retries=2)
+        self.assertTrue(api.coverage()["data"]["ok"])
+        self.assertEqual(len(calls), 2)
+
+    def test_rate_limit_error_after_retries(self):
+        api, _ = make_client(lambda r, n: httpx.Response(429, headers={"Retry-After": "0"}, json={"error": {"code": "batch_exceeds_quota", "message": "too big", "status": 429}, "max_items_now": 8}), max_retries=1)
+        with self.assertRaises(RateLimitError) as cm:
+            api.coverage()
+        self.assertEqual(cm.exception.max_items_now, 8)
+
+    def test_upgrade_required(self):
+        api, _ = make_client(lambda r, n: httpx.Response(403, json={"error": {"code": "upgrade_required", "message": "no", "status": 403}, "required_scope": "sanctions", "included_in": "professional", "price": "EUR 29.99/month", "trial_allowance": {"scope": "sanctions", "used": 25, "limit": 25, "resets_on": "2026-10-01"}}))
+        with self.assertRaises(UpgradeRequiredError) as cm:
+            api.sanctions_screen("x")
+        self.assertEqual(cm.exception.included_in, "professional")
+        self.assertEqual(cm.exception.trial_allowance["limit"], 25)
+
+    def test_auth_error(self):
+        api, _ = make_client(lambda r, n: httpx.Response(401, json={"error": {"code": "unauthorized", "message": "bad key", "status": 401}}))
+        with self.assertRaises(AuthError):
+            api.account()
+
+    def test_paginate_follows_cursor(self):
+        def h(r, n):
+            c = r.url.params.get("cursor")
+            if not c:
+                return httpx.Response(200, json={"data": [1, 2], "pagination": {"count": 2, "has_more": True, "next_cursor": "o:2"}})
+            if c == "o:2":
+                return httpx.Response(200, json={"data": [3], "pagination": {"count": 1, "has_more": False, "next_cursor": None}})
+            raise AssertionError("unexpected cursor")
+        api, calls = make_client(h)
+        pages = list(api.paginate("/people/search", {"name": "garcia", "limit": 2}))
+        self.assertEqual(pages, [[1, 2], [3]])
+        self.assertEqual(len(calls), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()