# Kuvola Institutional Data API — Python starter (no PyPI package published; copy this file)
import requests

BASE_URL = "https://kuvola.ao"


class KuvolaClient:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def _request(self, path: str, params: dict | None = None) -> dict:
        res = requests.get(
            BASE_URL + path,
            headers={"Authorization": f"Bearer {self.api_key}"},
            params=params or {},
        )
        if res.status_code == 429:
            raise RuntimeError(f"Rate limited. Reset: {res.headers.get('X-RateLimit-Reset')}")
        if not res.ok:
            body = res.json() if res.headers.get("content-type", "").startswith("application/json") else {}
            raise RuntimeError(f"Kuvola API error {res.status_code}: {body.get('error', {}).get('message', res.reason)}")
        return res.json()

    def v2ListMarkets(self, **params) -> dict:
        # Pagination: pass page=, pageSize=; response["pagination"] has totalPages.
        return self._request("/api/v2/markets", params)


# Usage:
# client = KuvolaClient("kv_live_...")
# result = client.v2ListMarkets(pageSize=25)