solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/_http.py

@@ -0,0 +1,243 @@
+"""The HTTP layer under the generated client: auth, timeouts, retries, errors.
+
+The generated methods (``_generated/operations.py``) only build a request and
+parse its response. Everything about talking to the API lives here, once,
+for both the async and the blocking client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from .errors import SolvaPayError
+
+DEFAULT_API_BASE_URL = "https://api.solvapay.com"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_MAX_RETRIES = 2
+# Statuses worth a retry: rate limited, or the platform briefly unavailable.
+RETRY_STATUSES = frozenset({429, 502, 503, 504})
+
+M = TypeVar("M", bound=BaseModel)
+
+try:
+    _VERSION = version("solvapay")
+except PackageNotFoundError:  # running from a source checkout
+    _VERSION = "0.0.0+source"
+
+USER_AGENT = f"solvapay-python/{_VERSION}"
+
+
+def path_segment(value: str) -> str:
+    """A path parameter, percent-encoded so a reference can never change the path."""
+    if not value:
+        raise SolvaPayError("A path parameter is empty", code="invalid_argument")
+    return quote(value, safe="")
+
+
+def encode_body(body: BaseModel | Mapping[str, Any] | None) -> Any:
+    """A request body as JSON-ready data.
+
+    A model is sent with its wire names and only the fields that were set, so
+    an explicit ``None`` is sent as ``null`` and an unset field is left out.
+    """
+    if body is None:
+        return None
+    if isinstance(body, BaseModel):
+        return body.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    return dict(body)
+
+
+def _error_from_response(response: httpx.Response) -> SolvaPayError:
+    status = response.status_code
+    try:
+        body = response.json()
+    except ValueError:
+        snippet = response.text[:240]
+        return SolvaPayError(
+            f"The SolvaPay API answered {status} with a body that is not JSON: {snippet}",
+            code="non_json_response",
+            status=status,
+            body=snippet,
+        )
+    message: Any = body.get("message") if isinstance(body, dict) else None
+    if isinstance(message, list):
+        message = "; ".join(str(part) for part in message)
+    # Only a non-empty string is the API's own code, as in the TypeScript SDK.
+    code = body.get("code") if isinstance(body, dict) else None
+    return SolvaPayError(
+        str(message or f"The SolvaPay API answered {status}"),
+        code=code if isinstance(code, str) and code else f"http_{status}",
+        status=status,
+        body=body,
+    )
+
+
+def _retry_after(response: httpx.Response | None, attempt: int) -> float:
+    if response is not None:
+        header = response.headers.get("retry-after")
+        if header and header.isdigit():
+            return min(float(header), 30.0)
+    return float(0.5 * 2**attempt)
+
+
+class _Transport:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        api_base_url: str,
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        if not api_key:
+            raise SolvaPayError(
+                "A SolvaPay secret key is required (SOLVAPAY_SECRET_KEY).", code="missing_secret"
+            )
+        if max_retries < 0:
+            raise SolvaPayError("max_retries cannot be negative", code="invalid_argument")
+        self.api_base_url = api_base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+    def _build(
+        self,
+        method: str,
+        path: str,
+        query: Mapping[str, Any],
+        headers: Mapping[str, Any],
+        body: Any,
+    ) -> dict[str, Any]:
+        params = {
+            key: ("true" if value is True else "false" if value is False else value)
+            for key, value in query.items()
+            if value is not None
+        }
+        merged = {**self._headers, **{k: str(v) for k, v in headers.items() if v is not None}}
+        return {
+            "method": method,
+            "url": f"{self.api_base_url}{path}",
+            "params": params,
+            "headers": merged,
+            "json": body,
+        }
+
+    def _retryable(self, request: dict[str, Any]) -> bool:
+        """Only requests that are safe to send twice: reads, and writes with an idempotency key."""
+        has_key = any(k.lower() == "idempotency-key" for k in request["headers"])
+        return request["method"] in {"GET", "HEAD"} or has_key
+
+    @staticmethod
+    def parse(model: type[M], data: Any) -> M:
+        try:
+            return model.model_validate(data)
+        except ValidationError as error:
+            raise SolvaPayError(
+                f"The SolvaPay API answered with a {model.__name__} this SDK cannot read: {error}",
+                code="invalid_response",
+                body=data,
+            ) from error
+
+
+class SyncTransport(_Transport):
+    """Blocking transport over ``httpx.Client``."""
+
+    def __init__(self, *, client: httpx.Client | None = None, **options: Any) -> None:
+        super().__init__(**options)
+        self._client = client or httpx.Client(timeout=self.timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any],
+        headers: Mapping[str, Any],
+        body: Any,
+    ) -> Any:
+        request = self._build(method, path, query, headers, body)
+        retries = self.max_retries if self._retryable(request) else 0
+        for attempt in range(retries + 1):
+            try:
+                response = self._client.request(**request)
+            except httpx.TransportError as error:
+                if attempt < retries:
+                    time.sleep(_retry_after(None, attempt))
+                    continue
+                raise SolvaPayError(
+                    f"Could not reach the SolvaPay API: {error}", code="network_error"
+                ) from error
+            if response.status_code in RETRY_STATUSES and attempt < retries:
+                time.sleep(_retry_after(response, attempt))
+                continue
+            return _result(response)
+        raise AssertionError("unreachable")
+
+
+class AsyncTransport(_Transport):
+    """Async transport over ``httpx.AsyncClient``."""
+
+    def __init__(self, *, client: httpx.AsyncClient | None = None, **options: Any) -> None:
+        super().__init__(**options)
+        self._client = client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any],
+        headers: Mapping[str, Any],
+        body: Any,
+    ) -> Any:
+        request = self._build(method, path, query, headers, body)
+        retries = self.max_retries if self._retryable(request) else 0
+        for attempt in range(retries + 1):
+            try:
+                response = await self._client.request(**request)
+            except httpx.TransportError as error:
+                if attempt < retries:
+                    await asyncio.sleep(_retry_after(None, attempt))
+                    continue
+                raise SolvaPayError(
+                    f"Could not reach the SolvaPay API: {error}", code="network_error"
+                ) from error
+            if response.status_code in RETRY_STATUSES and attempt < retries:
+                await asyncio.sleep(_retry_after(response, attempt))
+                continue
+            return _result(response)
+        raise AssertionError("unreachable")
+
+
+def _result(response: httpx.Response) -> Any:
+    if response.status_code >= 400:
+        raise _error_from_response(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as error:
+        raise SolvaPayError(
+            f"The SolvaPay API answered {response.status_code} with a body that is not JSON",
+            code="non_json_response",
+            status=response.status_code,
+            body=response.text[:240],
+        ) from error

solvapay/_js.py

@@ -0,0 +1,114 @@
+"""JavaScript value semantics, for code ported from the TypeScript SDK.
+
+The paywall code builds its output from JSON with JavaScript's rules: a key
+that is missing (``undefined``) is not the same as a key set to ``null``,
+``??`` falls through both, and ``0`` and ``""`` are falsy. Porting it with
+these helpers keeps every branch identical, which the conformance suite then
+checks.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any, Final
+
+
+class _Undefined:
+    """JavaScript ``undefined``: a key that is not there. Falsy."""
+
+    _instance: _Undefined | None = None
+
+    def __new__(cls) -> _Undefined:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "undefined"
+
+
+UNDEFINED: Final = _Undefined()
+
+
+def get(obj: Any, key: str) -> Any:
+    """``obj?.key``: UNDEFINED when obj is null/undefined or the key is missing."""
+    if isinstance(obj, Mapping) and key in obj:
+        return obj[key]
+    return UNDEFINED
+
+
+def nullish(value: Any) -> bool:
+    return value is None or value is UNDEFINED
+
+
+def coalesce(*values: Any) -> Any:
+    """``a ?? b ?? c``: the first value that is neither null nor undefined, else the last."""
+    for value in values[:-1]:
+        if not nullish(value):
+            return value
+    return values[-1]
+
+
+def truthy(value: Any) -> bool:
+    if value is UNDEFINED or value is None or value is False:
+        return False
+    if isinstance(value, bool):
+        return True
+    if isinstance(value, (int, float)):
+        return value != 0 and not math.isnan(value)
+    if isinstance(value, str):
+        return value != ""
+    return True
+
+
+def number(value: Any) -> float:
+    """A value as a JavaScript relational operator sees it: null is 0, undefined is NaN."""
+    if value is None:
+        return 0.0
+    if value is UNDEFINED:
+        return math.nan
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    return math.nan
+
+
+def num_str(value: Any) -> str:
+    """``String(n)`` for a number: 3.0 prints as "3", as JavaScript does."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        if value.is_integer():
+            return str(int(value))
+        return repr(value)
+    if value is None:
+        return "null"
+    if value is UNDEFINED:
+        return "undefined"
+    return str(value)
+
+
+def js_round(value: float) -> int:
+    """``Math.round``: halves round toward +infinity."""
+    return math.floor(value + 0.5)
+
+
+def to_locale_string(value: float) -> str:
+    """``n.toLocaleString('en-US')``: grouped, at most 3 fraction digits, half away from zero."""
+    quantized = Decimal(repr(float(value))).quantize(Decimal("0.001"), rounding=ROUND_HALF_UP)
+    sign = "-" if quantized < 0 else ""
+    whole, _, fraction = f"{abs(quantized):f}".partition(".")
+    fraction = fraction.rstrip("0")
+    grouped = f"{int(whole):,}"
+    return f"{sign}{grouped}.{fraction}" if fraction else f"{sign}{grouped}"
+
+
+def compact(items: Mapping[str, Any]) -> dict[str, Any]:
+    """An object literal as JSON.stringify writes it: undefined values drop out."""
+    return {key: value for key, value in items.items() if value is not UNDEFINED}