invonetwork 0.1.0__py3-none-any.whl

invonetwork/__init__.py

@@ -0,0 +1,95 @@
+"""invonetwork -- first-party Python server SDK for the INVO API.
+
+Server-side counterpart to the JS web SDK. Holds the game secret and runs every
+server-side money flow (mint player token, initiate send/transfer, currency purchase,
+item purchase) plus server-only reads and webhook verification.
+
+Zero runtime dependencies (stdlib only). Python 3.9+.
+
+Quickstart::
+
+    from invonetwork import InvoServer, InvoError, verify_webhook
+
+    server = InvoServer(
+        game_secret=os.environ["INVO_GAME_SECRET"],   # server-side only
+        base_url="https://sandbox.invo.network/sandbox",
+    )
+    token = server.mint_player_token(player_email="p@example.com")
+"""
+
+from __future__ import annotations
+
+from .errors import InvoError, error_from_response
+from .hooks import ErrorInfo, Hooks, RequestInfo, ResponseInfo
+from .http import (
+    Http,
+    HttpRequest,
+    HttpResponse,
+    Transport,
+    TransportError,
+    assert_secure_base_url,
+)
+from .server import InvoServer
+from .types import (
+    ConfirmPaymentResult,
+    CreateCheckoutResult,
+    CurrencyBalance,
+    InboundPendingItem,
+    InboundPendingResult,
+    InitiateResult,
+    ItemHistoryResult,
+    LinkedIdentitiesResult,
+    LinkedIdentityEmail,
+    Money,
+    OrderDetailsResult,
+    PlayerBalanceResult,
+    PlayerToken,
+    PurchaseItemResult,
+    PurchaseResult,
+    Rail,
+    VerificationMethod,
+)
+from .webhooks import WebhookEvent, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core
+    "InvoServer",
+    "InvoError",
+    "error_from_response",
+    "verify_webhook",
+    "WebhookEvent",
+    # Hooks
+    "Hooks",
+    "RequestInfo",
+    "ResponseInfo",
+    "ErrorInfo",
+    # Transport (advanced / testing)
+    "Http",
+    "HttpRequest",
+    "HttpResponse",
+    "Transport",
+    "TransportError",
+    "assert_secure_base_url",
+    # Result types
+    "PlayerToken",
+    "InitiateResult",
+    "CreateCheckoutResult",
+    "PurchaseResult",
+    "ConfirmPaymentResult",
+    "OrderDetailsResult",
+    "PurchaseItemResult",
+    "ItemHistoryResult",
+    "CurrencyBalance",
+    "PlayerBalanceResult",
+    "InboundPendingItem",
+    "InboundPendingResult",
+    "LinkedIdentityEmail",
+    "LinkedIdentitiesResult",
+    # Aliases
+    "Rail",
+    "VerificationMethod",
+    "Money",
+]

invonetwork/errors.py

@@ -0,0 +1,165 @@
+"""Typed error for every INVO backend failure.
+
+The backend error envelope is usually ``{"error": <message>, "code": <STABLE_CODE>}``,
+but a few txn-state/claim errors carry only ``error`` (no ``code``) and some use
+``{"status": "error", "message": ...}``. So ``code`` may be ``None`` -- branch on
+``code`` when present, else fall back to ``message``.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Dict, Optional, Union
+
+__all__ = ["InvoError", "error_from_response"]
+
+_INSUFFICIENT_RE = re.compile(r"insufficient[_ ]balance", re.IGNORECASE)
+_DUPLICATE_RE = re.compile(r"duplicate", re.IGNORECASE)
+_RECEIVER_NOT_ENROLLED_RE = re.compile(r"receiver_not_enrolled_use_claim_code", re.IGNORECASE)
+_PROMOTABLE_ERROR_RE = re.compile(
+    r"^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code)\Z"
+)
+
+
+class InvoError(Exception):
+    """The single error type raised by the SDK.
+
+    Attributes:
+        message: Human-readable description.
+        code: Stable machine code from the backend (``code``/``error_code``), when present.
+        status: HTTP status (``0`` for client-side validation and network errors).
+        body: Raw parsed response body, for debugging / fields not surfaced here.
+        request_id: Backend request id (from response headers), when present -- quote it
+            in support tickets.
+    """
+
+    code: Optional[str]
+    status: int
+    body: Any
+    request_id: Optional[str]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status: int = 0,
+        body: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.body = body if body is not None else None
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"InvoError(code={self.code!r}, status={self.status!r}, message={self.message!r})"
+
+    # ---- Classifiers (mirror the JS getters) ----
+
+    @property
+    def is_receiver_not_enrolled(self) -> bool:
+        """True for the "recipient isn't passkey-enrolled, fall back to claim code" signal.
+
+        Returned in the ``error`` field with NO ``code`` key by some backends.
+        """
+        return (
+            self.code == "receiver_not_enrolled_use_claim_code"
+            or bool(_RECEIVER_NOT_ENROLLED_RE.search(self.message))
+        )
+
+    @property
+    def is_token_expired(self) -> bool:
+        """True if the session/SDK token expired and the caller should re-mint + retry."""
+        return self.code == "SDK_TOKEN_EXPIRED"
+
+    @property
+    def is_enrollment_authorization_required(self) -> bool:
+        """True if enrollment needs the OTP-grant flow (``enrollmentBegin``/``enrollmentVerify``)."""
+        return self.code == "ENROLLMENT_REQUIRES_AUTHORIZATION"
+
+    @property
+    def is_enrollment_proof_required(self) -> bool:
+        """True if enrolling is blocked because another method exists -- use device link."""
+        return self.code == "ENROLLMENT_REQUIRES_PROOF"
+
+    @property
+    def is_insufficient_balance(self) -> bool:
+        """True if an item purchase failed because the player's balance was too low (400).
+
+        The backend carries ``required_amount`` + ``current_balance`` on ``body`` for the UI.
+        Gated to status 400 so the ``429 insufficient_balance_blocked`` abuse throttle (a
+        rate-limit, not a top-up condition) is NOT misclassified as this.
+        """
+        if self.status != 400:
+            return False
+        b = self._body_object()
+        return (
+            self.code == "INSUFFICIENT_BALANCE"
+            or "required_amount" in b
+            or bool(_INSUFFICIENT_RE.search(self.message))
+        )
+
+    @property
+    def is_duplicate_request(self) -> bool:
+        """True if an idempotency-keyed request was a duplicate (item purchase -> 409)."""
+        return self.code == "DUPLICATE_REQUEST" or (
+            self.status == 409 and bool(_DUPLICATE_RE.search(self.message))
+        )
+
+    @property
+    def retry_after(self) -> Optional[Union[int, float]]:
+        """Seconds to wait before retrying, when the backend throttled the call (429).
+
+        Reads ``retry_after`` from the body (numeric or string). ``None`` when absent/invalid.
+        """
+        v = self._body_object().get("retry_after")
+        n: Optional[Union[int, float]]
+        if isinstance(v, bool):
+            return None
+        if isinstance(v, str):
+            try:
+                n = float(v)
+            except ValueError:
+                return None
+        elif isinstance(v, (int, float)):
+            n = v
+        else:
+            return None
+        if math.isfinite(n) and n >= 0:
+            return n
+        return None
+
+    def _body_object(self) -> Dict[str, Any]:
+        """``body`` as a plain dict, or ``{}`` for non-object bodies (``in`` throws on primitives)."""
+        return self.body if isinstance(self.body, dict) else {}
+
+
+def error_from_response(
+    status: int, body: Any, request_id: Optional[str] = None
+) -> InvoError:
+    """Build an :class:`InvoError` from a parsed (or text) response body."""
+    message = f"INVO request failed (HTTP {status})"
+    code: Optional[str] = None
+    if isinstance(body, dict):
+        if isinstance(body.get("code"), str):
+            code = body["code"]
+        elif isinstance(body.get("error_code"), str):
+            code = body["error_code"]
+        if isinstance(body.get("error"), str):
+            message = body["error"]
+        elif isinstance(body.get("message"), str):
+            message = body["message"]
+        # A few txn-state errors ship only an `error` token with no code/error_code --
+        # promote the known ones so consumers can branch on `err.code`.
+        if not code and isinstance(body.get("error"), str) and _PROMOTABLE_ERROR_RE.match(body["error"]):
+            code = body["error"]
+    elif isinstance(body, str) and body.strip():
+        message = body
+    return InvoError(message, code=code, status=status, body=body, request_id=request_id)

invonetwork/hooks.py

@@ -0,0 +1,63 @@
+"""Optional observability callbacks (``on_request`` / ``on_response`` / ``on_error``).
+
+All hooks are best-effort: a throwing hook is swallowed and never breaks a request.
+
+.. note::
+    Hook payloads include the request ``url``, which for some calls embeds a player
+    email (e.g. balance-by-email). The game secret is sent as a header and is **never**
+    passed to hooks -- but redact the ``url`` if you log hook payloads.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from .errors import InvoError
+
+__all__ = ["RequestInfo", "ResponseInfo", "ErrorInfo", "Hooks"]
+
+
+@dataclass
+class RequestInfo:
+    """Passed to ``on_request`` before each attempt."""
+
+    method: str
+    url: str
+    attempt: int
+    """0-based attempt number (0 = first try, 1 = first retry, ...)."""
+
+
+@dataclass
+class ResponseInfo:
+    """Passed to ``on_response`` after a response is received."""
+
+    method: str
+    url: str
+    attempt: int
+    status: int
+    duration_ms: float
+    request_id: Optional[str] = None
+    """Backend request id from the response headers, when present."""
+
+
+@dataclass
+class ErrorInfo:
+    """Passed to ``on_error`` on a network error or a non-2xx response."""
+
+    method: str
+    url: str
+    attempt: int
+    error: "InvoError"
+    will_retry: bool
+    """Whether the SDK will retry after this error."""
+
+
+@dataclass
+class Hooks:
+    """Observability callbacks. Pass any subset; all are best-effort."""
+
+    on_request: Optional[Callable[[RequestInfo], None]] = None
+    on_response: Optional[Callable[[ResponseInfo], None]] = None
+    on_error: Optional[Callable[[ErrorInfo], None]] = None

invonetwork/http.py

@@ -0,0 +1,323 @@
+"""Transport, retry/backoff, and observability for the INVO SDK.
+
+Zero runtime dependencies: the default transport is built on :mod:`urllib.request`.
+The transport is a plain callable ``(HttpRequest) -> HttpResponse`` so tests (and
+advanced callers) can inject a fake instead of touching the network. A transport
+signals a network failure/timeout by raising :class:`TransportError`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import random
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional
+from urllib.parse import urlparse
+
+from .errors import InvoError, error_from_response
+from .hooks import ErrorInfo, Hooks, RequestInfo, ResponseInfo
+
+__all__ = [
+    "HttpRequest",
+    "HttpResponse",
+    "Transport",
+    "TransportError",
+    "Http",
+    "assert_secure_base_url",
+]
+
+DEFAULT_TIMEOUT = 30.0
+"""Default per-request timeout, in seconds."""
+
+MAX_RETRY_AFTER = 20.0
+"""Upper bound on an honored ``retry_after`` (seconds); larger values surface the 429."""
+
+_RETRIABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass
+class HttpRequest:
+    """A single outbound HTTP request handed to the transport."""
+
+    method: str
+    url: str
+    headers: Dict[str, str]
+    body: Optional[bytes]
+
+
+@dataclass
+class HttpResponse:
+    """A raw HTTP response returned by the transport."""
+
+    status: int
+    headers: Mapping[str, str] = field(default_factory=dict)
+    body: bytes = b""
+
+
+#: A transport is any callable turning a request into a response. It must raise
+#: :class:`TransportError` for network failures/timeouts (so retries can kick in).
+Transport = Callable[[HttpRequest], HttpResponse]
+
+
+class TransportError(Exception):
+    """Raised by a transport for a network failure or timeout (never an HTTP status)."""
+
+    def __init__(self, message: str, *, timeout: bool = False) -> None:
+        super().__init__(message)
+        self.message = message
+        self.timeout = timeout
+
+
+def assert_secure_base_url(base_url: str) -> None:
+    """Reject a non-https ``base_url``.
+
+    The game secret travels in a request header, so ``http://`` would expose it on the
+    wire. ``http://localhost`` (and loopback) is allowed for local development only.
+
+    Raises:
+        ValueError: if the URL is unparseable or not https (non-loopback).
+    """
+    try:
+        u = urlparse(base_url)
+    except Exception as exc:  # pragma: no cover - urlparse rarely raises
+        raise ValueError(f"Invalid baseUrl: {base_url}") from exc
+    if not u.scheme or not u.netloc:
+        raise ValueError(f"Invalid baseUrl: {base_url}")
+    host = (u.hostname or "").lower()
+    is_local = host in ("localhost", "127.0.0.1", "::1")
+    if u.scheme == "https" or (u.scheme == "http" and is_local):
+        return
+    raise ValueError(
+        f'baseUrl must use https:// (got "{u.scheme}://"). '
+        "Plaintext would expose the game secret on the wire."
+    )
+
+
+def _make_urllib_transport(timeout: float) -> Transport:
+    """Build the default transport backed by :mod:`urllib.request`."""
+
+    def transport(request: HttpRequest) -> HttpResponse:
+        req = urllib.request.Request(request.url, data=request.body, method=request.method)
+        for name, value in request.headers.items():
+            req.add_header(name, value)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (https enforced)
+                headers = {k.lower(): v for k, v in resp.headers.items()}
+                return HttpResponse(status=resp.status, headers=headers, body=resp.read())
+        except urllib.error.HTTPError as exc:
+            # HTTPError IS a response object -- surface its status/body rather than retrying.
+            raw = exc.headers.items() if exc.headers else []
+            headers = {k.lower(): v for k, v in raw}
+            return HttpResponse(status=exc.code, headers=headers, body=exc.read())
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            reason = getattr(exc, "reason", exc)
+            is_timeout = isinstance(reason, TimeoutError) or "timed out" in str(reason).lower()
+            raise TransportError(str(reason), timeout=is_timeout) from exc
+
+    return transport
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    """Case-insensitive header lookup that tolerates unlowered keys."""
+    target = name.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            return value
+    return None
+
+
+def _pick_request_id(headers: Mapping[str, str]) -> Optional[str]:
+    """Pull a backend request id from the response headers (for support/tracing)."""
+    return _get_header(headers, "x-invo-request-id") or _get_header(headers, "x-request-id")
+
+
+def _retry_after_seconds(parsed: Any, headers: Mapping[str, str]) -> Optional[float]:
+    """Honor a 429 ``retry_after`` (seconds) from the body or the ``Retry-After`` header."""
+    if isinstance(parsed, dict):
+        v = parsed.get("retry_after")
+        n: Optional[float] = None
+        if isinstance(v, bool):
+            n = None
+        elif isinstance(v, (int, float)):
+            n = float(v)
+        elif isinstance(v, str):
+            try:
+                n = float(v)
+            except ValueError:
+                n = None
+        if n is not None and n >= 0:
+            return n
+    header = _get_header(headers, "retry-after")
+    if header:
+        try:
+            n = float(header)
+        except ValueError:
+            return None
+        if n >= 0:
+            return n
+    return None
+
+
+class Http:
+    """HTTP core: builds requests, retries transient failures, and fires hooks.
+
+    Retries apply ONLY to idempotent requests (network error/timeout, 429, 5xx). A
+    timeout can fire while the server is mid-processing, so a non-idempotent POST is
+    never auto-retried (it could double-apply an action).
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        retry_base_delay: float = 0.25,
+        user_agent: Optional[str] = None,
+        hooks: Optional[Hooks] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.retry_base_delay = retry_base_delay
+        self.user_agent = user_agent
+        self.hooks = hooks
+        self._transport: Transport = transport or _make_urllib_transport(timeout)
+
+    def get(self, path: str, auth_headers: Dict[str, str]) -> Any:
+        """GET is always idempotent -> safe to retry."""
+        return self._request("GET", path, None, auth_headers, idempotent=True)
+
+    def post(
+        self,
+        path: str,
+        body: Optional[Dict[str, Any]],
+        auth_headers: Dict[str, str],
+        *,
+        idempotent: bool = False,
+    ) -> Any:
+        """POST. ``idempotent=True`` marks it safe to auto-retry (carries an idempotency key)."""
+        return self._request("POST", path, body, auth_headers, idempotent=idempotent)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]],
+        auth_headers: Dict[str, str],
+        *,
+        idempotent: bool,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        headers: Dict[str, str] = {"Accept": "application/json", **auth_headers}
+        if self.user_agent:
+            headers["User-Agent"] = self.user_agent
+        payload: Optional[bytes] = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            payload = json.dumps(body).encode("utf-8")
+
+        attempt = 0
+        while True:
+            start = time.monotonic()
+            self._fire_request(RequestInfo(method=method, url=url, attempt=attempt))
+            request = HttpRequest(method=method, url=url, headers=dict(headers), body=payload)
+
+            network_error: Optional[InvoError] = None
+            response: Optional[HttpResponse] = None
+            try:
+                response = self._transport(request)
+            except TransportError as exc:
+                message = (
+                    f"Request to {path} timed out after {self.timeout}s"
+                    if exc.timeout
+                    else f"Network error calling {path}: {exc.message}"
+                )
+                network_error = InvoError(message, status=0)
+            except Exception as exc:  # any other transport failure == network error
+                network_error = InvoError(f"Network error calling {path}: {exc}", status=0)
+
+            if network_error is not None:
+                will_retry = idempotent and attempt < self.max_retries
+                self._fire_error(
+                    ErrorInfo(method=method, url=url, attempt=attempt, error=network_error, will_retry=will_retry)
+                )
+                if will_retry:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise network_error
+
+            assert response is not None
+            request_id = _pick_request_id(response.headers)
+            raw_body = response.body
+            text = raw_body.decode("utf-8") if isinstance(raw_body, bytes) else str(raw_body)
+            parsed: Any = None
+            if text:
+                try:
+                    parsed = json.loads(text)
+                except ValueError:
+                    parsed = text
+
+            self._fire_response(
+                ResponseInfo(
+                    method=method,
+                    url=url,
+                    attempt=attempt,
+                    status=response.status,
+                    duration_ms=(time.monotonic() - start) * 1000.0,
+                    request_id=request_id,
+                )
+            )
+
+            if not (200 <= response.status < 300):
+                err = error_from_response(response.status, parsed, request_id)
+                wait: Optional[float] = None
+                if idempotent and attempt < self.max_retries and response.status in _RETRIABLE_STATUS:
+                    if response.status == 429:
+                        ra = _retry_after_seconds(parsed, response.headers)
+                        if ra is None:
+                            wait = self._backoff(attempt)
+                        elif ra <= MAX_RETRY_AFTER:
+                            wait = ra
+                        else:
+                            wait = None  # surface the 429 rather than stalling
+                    else:
+                        wait = self._backoff(attempt)
+                self._fire_error(
+                    ErrorInfo(method=method, url=url, attempt=attempt, error=err, will_retry=wait is not None)
+                )
+                if wait is not None:
+                    time.sleep(wait)
+                    attempt += 1
+                    continue
+                raise err
+
+            return parsed if parsed is not None else {}
+
+    def _backoff(self, attempt: int) -> float:
+        """Exponential backoff with full jitter: ``base * 2**attempt``, randomized."""
+        ceil = self.retry_base_delay * (2.0 ** attempt)
+        return random.random() * ceil + self.retry_base_delay
+
+    # ---- Hook firing (best-effort; a throwing hook never breaks a request) ----
+
+    def _fire_request(self, info: RequestInfo) -> None:
+        if self.hooks and self.hooks.on_request:
+            with contextlib.suppress(Exception):
+                self.hooks.on_request(info)
+
+    def _fire_response(self, info: ResponseInfo) -> None:
+        if self.hooks and self.hooks.on_response:
+            with contextlib.suppress(Exception):
+                self.hooks.on_response(info)
+
+    def _fire_error(self, info: ErrorInfo) -> None:
+        if self.hooks and self.hooks.on_error:
+            with contextlib.suppress(Exception):
+                self.hooks.on_error(info)