stablevoy 1.0.0__py3-none-any.whl

stablevoy/__init__.py

@@ -0,0 +1,63 @@
+"""Python client for the Stablevoy API: non-custodial USDT and USDC payments, invoices and signed webhooks."""
+
+from stablevoy._version import __version__
+from stablevoy.client import Stablevoy
+from stablevoy.errors.api_error import ApiError
+from stablevoy.errors.authentication_error import AuthenticationError
+from stablevoy.errors.configuration_error import ConfigurationError
+from stablevoy.errors.maintenance_error import MaintenanceError
+from stablevoy.errors.not_found_error import NotFoundError
+from stablevoy.errors.problem_issue import ProblemIssue
+from stablevoy.errors.rate_limited_error import RateLimitedError
+from stablevoy.errors.signature_error import SignatureError
+from stablevoy.errors.stablevoy_error import StablevoyError
+from stablevoy.errors.transport_error import TransportError
+from stablevoy.errors.unexpected_response_error import UnexpectedResponseError
+from stablevoy.errors.validation_error import ValidationError
+from stablevoy.http.retry_policy import RetryPolicy
+from stablevoy.http.transport import Transport
+from stablevoy.model.created_invoice import CreatedInvoice
+from stablevoy.model.deposit_address import DepositAddress
+from stablevoy.model.invoice import Invoice
+from stablevoy.model.invoice_page import InvoicePage
+from stablevoy.model.invoice_status import InvoiceStatus
+from stablevoy.model.limits import Limits
+from stablevoy.model.network import Network
+from stablevoy.model.payment import Payment
+from stablevoy.model.pricing import Pricing
+from stablevoy.model.store import Store
+from stablevoy.model.token import Token
+from stablevoy.webhook.webhook_event import WebhookEvent
+from stablevoy.webhook.webhook_verifier import WebhookVerifier
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "CreatedInvoice",
+    "DepositAddress",
+    "Invoice",
+    "InvoicePage",
+    "InvoiceStatus",
+    "Limits",
+    "MaintenanceError",
+    "Network",
+    "NotFoundError",
+    "Payment",
+    "Pricing",
+    "ProblemIssue",
+    "RateLimitedError",
+    "RetryPolicy",
+    "SignatureError",
+    "Stablevoy",
+    "StablevoyError",
+    "Store",
+    "Token",
+    "Transport",
+    "TransportError",
+    "UnexpectedResponseError",
+    "ValidationError",
+    "WebhookEvent",
+    "WebhookVerifier",
+    "__version__",
+]

stablevoy/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

stablevoy/client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import platform
+import time
+from collections.abc import Callable
+
+from stablevoy._version import __version__
+from stablevoy.http.error_factory import ErrorFactory
+from stablevoy.http.opener import Opener
+from stablevoy.http.retry_policy import RetryPolicy
+from stablevoy.http.transport import Transport
+from stablevoy.http.urllib_opener import UrllibOpener
+from stablevoy.http.urllib_transport import UrllibTransport
+from stablevoy.resources.invoices import Invoices
+from stablevoy.resources.platform import Platform
+from stablevoy.resources.stores import Stores
+
+
+class Stablevoy:
+    """The Stablevoy API: ``stablevoy = Stablevoy.create(os.environ["STABLEVOY_API_KEY"])``."""
+
+    def __init__(self, invoices: Invoices, stores: Stores, platform: Platform) -> None:
+        self.invoices = invoices
+        self.stores = stores
+        self.platform = platform
+
+    @classmethod
+    def create(
+        cls,
+        api_key: str,
+        *,
+        base_url: str = "https://api.stablevoy.com",
+        retries: RetryPolicy | None = None,
+        timeout_seconds: float = 30.0,
+        user_agent_suffix: str | None = None,
+        opener: Opener | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> Stablevoy:
+        user_agent = f"stablevoy-python/{__version__} Python/{platform.python_version()}"
+        if user_agent_suffix is not None:
+            user_agent += f" {user_agent_suffix}"
+        return cls.from_transport(
+            UrllibTransport(
+                api_key=api_key,
+                base_url=base_url,
+                user_agent=user_agent,
+                retries=retries if retries is not None else RetryPolicy(),
+                opener=opener if opener is not None else UrllibOpener(),
+                sleep=sleep,
+                errors=ErrorFactory(),
+                timeout_seconds=timeout_seconds,
+            )
+        )
+
+    @classmethod
+    def from_transport(cls, transport: Transport) -> Stablevoy:
+        return cls(Invoices(transport), Stores(transport), Platform(transport))

stablevoy/errors/api_error.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from stablevoy.errors.problem_issue import ProblemIssue
+from stablevoy.errors.stablevoy_error import StablevoyError
+
+
+class ApiError(StablevoyError):
+    """
+    The API answered with an error: an RFC 7807 problem document with a stable code, a readable detail and a link to the
+    code's entry in the error catalog (https://stablevoy.com/docs/api/errors/).
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        detail: str,
+        type: str | None,
+        issues: tuple[ProblemIssue, ...],
+        retry_after_seconds: int | None,
+    ) -> None:
+        super().__init__(f"{detail} (HTTP {status}, {code})")
+        self.status = status
+        self.code = code
+        self.detail = detail
+        self.type = type
+        self.issues = issues
+        self.retry_after_seconds = retry_after_seconds

stablevoy/errors/authentication_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.api_error import ApiError
+
+
+class AuthenticationError(ApiError):
+    """The API key is missing, invalid or revoked (HTTP 401)."""

stablevoy/errors/configuration_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.stablevoy_error import StablevoyError
+
+
+class ConfigurationError(StablevoyError):
+    """The client cannot be built as asked, for example with an empty API key or an unsafe base URL."""

stablevoy/errors/maintenance_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.api_error import ApiError
+
+
+class MaintenanceError(ApiError):
+    """Stablevoy is under maintenance (HTTP 503, code maintenance). Nothing was changed; retry after retry_after_seconds."""

stablevoy/errors/not_found_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.api_error import ApiError
+
+
+class NotFoundError(ApiError):
+    """The invoice or store does not exist for this API key (HTTP 404)."""

stablevoy/errors/problem_issue.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProblemIssue:
+    """A field a validation error names."""
+
+    path: str
+    message: str

stablevoy/errors/rate_limited_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.api_error import ApiError
+
+
+class RateLimitedError(ApiError):
+    """Too many requests (HTTP 429); retry_after_seconds says when to try again."""

stablevoy/errors/signature_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.stablevoy_error import StablevoyError
+
+
+class SignatureError(StablevoyError):
+    """A webhook did not pass the signature check; the message says why. Answer such a request with HTTP 400."""

stablevoy/errors/stablevoy_error.py

@@ -0,0 +1,2 @@
+class StablevoyError(Exception):
+    """Every error this library raises extends it, so one ``except StablevoyError`` covers them all."""

stablevoy/errors/transport_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.stablevoy_error import StablevoyError
+
+
+class TransportError(StablevoyError):
+    """No answer from the API: the connection failed or timed out."""

stablevoy/errors/unexpected_response_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.stablevoy_error import StablevoyError
+
+
+class UnexpectedResponseError(StablevoyError):
+    """The API answered something this library cannot read: not JSON, or a field missing or of the wrong type."""

stablevoy/errors/validation_error.py

@@ -0,0 +1,5 @@
+from stablevoy.errors.api_error import ApiError
+
+
+class ValidationError(ApiError):
+    """The request was refused because of its content (HTTP 400 or 422); issues names the fields."""

stablevoy/http/error_factory.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+
+from stablevoy.errors.api_error import ApiError
+from stablevoy.errors.authentication_error import AuthenticationError
+from stablevoy.errors.maintenance_error import MaintenanceError
+from stablevoy.errors.not_found_error import NotFoundError
+from stablevoy.errors.problem_issue import ProblemIssue
+from stablevoy.errors.rate_limited_error import RateLimitedError
+from stablevoy.errors.validation_error import ValidationError
+
+
+class ErrorFactory:
+    """Turns an error answer of the API (an RFC 7807 problem document) into the matching error."""
+
+    def from_problem(self, status: int, body: bytes, retry_after_seconds: int | None) -> ApiError:
+        problem = self._parse(body)
+        code = problem.get("code")
+        code = code if isinstance(code, str) else f"http_{status}"
+        detail = problem.get("detail")
+        problem_type = problem.get("type")
+        error_class: type[ApiError] = ApiError
+        if status == 401:
+            error_class = AuthenticationError
+        elif status == 404:
+            error_class = NotFoundError
+        elif status == 429:
+            error_class = RateLimitedError
+        elif status == 503 and code == "maintenance":
+            error_class = MaintenanceError
+        elif status in (400, 422):
+            error_class = ValidationError
+        return error_class(
+            status=status,
+            code=code,
+            detail=detail if isinstance(detail, str) else f"The API answered HTTP {status}",
+            type=problem_type if isinstance(problem_type, str) else None,
+            issues=self._issues(problem.get("issues")),
+            retry_after_seconds=retry_after_seconds,
+        )
+
+    @staticmethod
+    def _parse(body: bytes) -> dict[str, object]:
+        try:
+            value = json.loads(body)
+        except ValueError:
+            return {}
+        return value if isinstance(value, dict) else {}
+
+    @staticmethod
+    def _issues(value: object) -> tuple[ProblemIssue, ...]:
+        if not isinstance(value, list):
+            return ()
+        return tuple(
+            ProblemIssue(issue["path"], issue["message"])
+            for issue in value
+            if isinstance(issue, dict) and isinstance(issue.get("path"), str) and isinstance(issue.get("message"), str)
+        )

stablevoy/http/http_answer.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+from email.message import Message
+
+
+@dataclass(frozen=True)
+class HttpAnswer:
+    status: int
+    headers: Message
+    body: bytes

stablevoy/http/no_redirects.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from email.message import Message
+from typing import IO
+from urllib.request import HTTPRedirectHandler, Request
+
+
+class NoRedirects(HTTPRedirectHandler):
+    """The API never redirects; following one would carry the key wherever it points. The 3xx answer is returned as is."""
+
+    def redirect_request(self, req: Request, fp: IO[bytes], code: int, msg: str, headers: Message, newurl: str) -> None:  # noqa: PLR0917 - urllib defines this signature
+        return None

stablevoy/http/opener.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+from urllib.request import Request
+
+from stablevoy.http.http_answer import HttpAnswer
+
+
+class Opener(Protocol):
+    """Sends a request and returns the answer, whatever its status; raises OSError when there is no answer at all."""
+
+    def send(self, request: Request, timeout: float) -> HttpAnswer: ...

stablevoy/http/retry_policy.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+
+class RetryPolicy:
+    """
+    When to retry: on 429, 503 and a failed connection, at most max_retries times, waiting what Retry-After asks (or 1, 2,
+    4 seconds without it). A wait longer than max_wait_seconds is not slept through: the error goes to the caller with
+    retry_after_seconds, so a request never hangs for minutes during maintenance.
+    """
+
+    def __init__(self, max_retries: int = 2, max_wait_seconds: int = 10) -> None:
+        if max_retries < 0 or max_wait_seconds < 0:
+            raise ValueError("max_retries and max_wait_seconds must not be negative")
+        self.max_retries = max_retries
+        self.max_wait_seconds = max_wait_seconds
+
+    @classmethod
+    def none(cls) -> RetryPolicy:
+        return cls(0, 0)
+
+    def wait_before(self, attempt: int, retry_after_seconds: int | None) -> int | None:
+        """Seconds to wait before the next attempt, or None when the call must not be retried. ``attempt`` counts from 1."""
+        if attempt > self.max_retries:
+            return None
+        wait = retry_after_seconds if retry_after_seconds is not None else 1 << (attempt - 1)
+        return wait if wait <= self.max_wait_seconds else None

stablevoy/http/transport.py

@@ -0,0 +1,10 @@
+from collections.abc import Mapping
+from typing import Protocol
+
+
+class Transport(Protocol):
+    """Sends one API call and returns the decoded JSON answer, or raises the matching error. The resources depend on it only."""
+
+    def get(self, path: str, query: Mapping[str, str | int] | None = None) -> object: ...
+
+    def post(self, path: str, body: Mapping[str, object], idempotency_key: str | None = None) -> object: ...

stablevoy/http/urllib_opener.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from urllib.error import HTTPError
+from urllib.request import OpenerDirector, Request, build_opener
+
+from stablevoy.http.http_answer import HttpAnswer
+from stablevoy.http.no_redirects import NoRedirects
+
+
+class UrllibOpener:
+    """The standard library's HTTP client without redirects. Error statuses come back as answers, not exceptions."""
+
+    def __init__(self, opener: OpenerDirector | None = None) -> None:
+        self._opener = opener if opener is not None else build_opener(NoRedirects)
+
+    def send(self, request: Request, timeout: float) -> HttpAnswer:
+        try:
+            with self._opener.open(request, timeout=timeout) as response:
+                return HttpAnswer(response.status, response.headers, response.read())
+        except HTTPError as error:
+            with error:
+                return HttpAnswer(error.code, error.headers, error.read())

stablevoy/http/urllib_transport.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Mapping
+from urllib.parse import urlencode, urlsplit
+from urllib.request import Request
+
+from stablevoy.errors.api_error import ApiError
+from stablevoy.errors.configuration_error import ConfigurationError
+from stablevoy.errors.transport_error import TransportError
+from stablevoy.errors.unexpected_response_error import UnexpectedResponseError
+from stablevoy.http.error_factory import ErrorFactory
+from stablevoy.http.http_answer import HttpAnswer
+from stablevoy.http.opener import Opener
+from stablevoy.http.retry_policy import RetryPolicy
+
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+class UrllibTransport:
+    """
+    The API over HTTP: Bearer API key, JSON in and out, errors as exceptions, and retries only where a repeat cannot do
+    harm (reads, and creates that carry an Idempotency-Key).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        user_agent: str,
+        retries: RetryPolicy,
+        opener: Opener,
+        sleep: Callable[[float], None],
+        errors: ErrorFactory,
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        if not api_key.strip():
+            raise ConfigurationError("The API key is empty. Create one in the Stablevoy dashboard.")
+        self._api_key = api_key
+        self._base_url = self._checked_base_url(base_url)
+        self._user_agent = user_agent
+        self._retries = retries
+        self._opener = opener
+        self._sleep = sleep
+        self._errors = errors
+        self._timeout = timeout_seconds
+
+    def get(self, path: str, query: Mapping[str, str | int] | None = None) -> object:
+        url = self._base_url + path + (f"?{urlencode(query)}" if query else "")
+        return self._send(Request(url, method="GET"), retryable=True)  # noqa: S310 - the scheme is checked to be http(s)
+
+    def post(self, path: str, body: Mapping[str, object], idempotency_key: str | None = None) -> object:
+        request = Request(self._base_url + path, data=json.dumps(body).encode(), method="POST")  # noqa: S310 - checked scheme
+        request.add_header("Content-Type", "application/json")
+        if idempotency_key is not None:
+            request.add_header("Idempotency-Key", idempotency_key)
+        return self._send(request, retryable=idempotency_key is not None)
+
+    def _send(self, request: Request, *, retryable: bool) -> object:
+        request.add_header("Authorization", f"Bearer {self._api_key}")
+        request.add_header("Accept", "application/json")
+        request.add_header("User-Agent", self._user_agent)
+        attempt = 1
+        while True:
+            try:
+                answer = self._opener.send(request, self._timeout)
+            except OSError as error:
+                wait = self._retries.wait_before(attempt, None) if retryable else None
+                if wait is None:
+                    raise TransportError(f"Cannot reach the Stablevoy API: {error}") from error
+                self._sleep(wait)
+                attempt += 1
+                continue
+            if 200 <= answer.status < 300:
+                return self._decode(answer.body)
+            api_error = self._errors.from_problem(answer.status, answer.body, self._retry_after(answer))
+            retry = retryable and self._is_retryable(api_error)
+            wait = self._retries.wait_before(attempt, api_error.retry_after_seconds) if retry else None
+            if wait is None:
+                raise api_error
+            self._sleep(wait)
+            attempt += 1
+
+    @staticmethod
+    def _is_retryable(error: ApiError) -> bool:
+        return error.status in (429, 503)
+
+    @staticmethod
+    def _decode(body: bytes) -> object:
+        try:
+            value: object = json.loads(body)
+        except ValueError as error:
+            raise UnexpectedResponseError("The API answered with a body that is not JSON") from error
+        if not isinstance(value, dict | list):
+            raise UnexpectedResponseError("The API answered with JSON that is not an object or a list")
+        return value
+
+    @staticmethod
+    def _retry_after(answer: HttpAnswer) -> int | None:
+        value = (answer.headers.get("Retry-After") or "").strip()
+        return int(value) if re.fullmatch(r"\d{1,9}", value) else None
+
+    @staticmethod
+    def _checked_base_url(base_url: str) -> str:
+        """
+        Only a scheme, a host and an optional port. The API key travels in every request, so plain http is refused except
+        for a local development server, and so are credentials, paths, queries and fragments in the URL.
+        """
+        url = base_url.rstrip("/")
+        try:
+            parts = urlsplit(url)
+            _ = parts.port  # raises ValueError on a port that is no number
+        except ValueError:
+            parts = None
+        bad = (
+            parts is None
+            or not parts.hostname
+            or parts.username is not None
+            or parts.password is not None
+            or bool(parts.path or parts.query or parts.fragment)
+            or not (parts.scheme == "https" or (parts.scheme == "http" and parts.hostname in _LOCAL_HOSTS))
+        )
+        if bad:
+            raise ConfigurationError(
+                f"The base URL must be https and only a host, like https://api.stablevoy.com (http only for localhost); got {base_url}"
+            )
+        return url

stablevoy/model/created_invoice.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from stablevoy.model.fields import Fields
+from stablevoy.model.invoice import Invoice
+
+
+@dataclass(frozen=True)
+class CreatedInvoice:
+    """The answer to creating an invoice: the invoice, the hosted payment page to send the buyer to, and what was left out."""
+
+    invoice: Invoice
+    checkout_url: str
+    unavailable_networks: tuple[str, ...]
+    replayed: bool
+
+    @classmethod
+    def from_fields(cls, f: Fields) -> CreatedInvoice:
+        return cls(Invoice.from_fields(f), f.string("checkoutUrl"), f.strings("unavailableNetworks"), f.boolean("replayed"))

stablevoy/model/deposit_address.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from stablevoy.model.fields import Fields
+
+
+@dataclass(frozen=True)
+class DepositAddress:
+    """Where the buyer pays on one network: a one-time deposit address, or on Tron the merchant's own wallet."""
+
+    network: str
+    address: str
+    payout_address: str
+    amount_due_usd_cents: int
+
+    @classmethod
+    def from_fields(cls, f: Fields) -> DepositAddress:
+        return cls(f.string("network"), f.string("address"), f.string("payoutAddress"), f.integer("amountDueUsdCents"))

stablevoy/model/fields.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import TypeVar
+
+from stablevoy.errors.unexpected_response_error import UnexpectedResponseError
+
+T = TypeVar("T")
+
+
+class Fields:
+    """Strict reads from a decoded JSON object. A missing field or one of the wrong type is an error naming it, never a silent default."""
+
+    def __init__(self, data: dict[str, object], path: str) -> None:
+        self._data = data
+        self._path = path
+
+    @classmethod
+    def of(cls, value: object, path: str) -> Fields:
+        if not isinstance(value, dict):
+            raise UnexpectedResponseError(f"{path} is not a JSON object")
+        return cls(value, path)
+
+    def string(self, key: str) -> str:
+        value = self._value(key)
+        if not isinstance(value, str):
+            raise self._wrong(key, "a string")
+        return value
+
+    def nullable_string(self, key: str) -> str | None:
+        value = self._value(key)
+        if value is not None and not isinstance(value, str):
+            raise self._wrong(key, "a string or null")
+        return value
+
+    def integer(self, key: str) -> int:
+        value = self._value(key)
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise self._wrong(key, "an integer")
+        return value
+
+    def nullable_integer(self, key: str) -> int | None:
+        value = self._value(key)
+        if value is not None and (not isinstance(value, int) or isinstance(value, bool)):
+            raise self._wrong(key, "an integer or null")
+        return value
+
+    def boolean(self, key: str) -> bool:
+        value = self._value(key)
+        if not isinstance(value, bool):
+            raise self._wrong(key, "a boolean")
+        return value
+
+    def date(self, key: str) -> datetime:
+        return self._parse_date(key, self.string(key))
+
+    def nullable_date(self, key: str) -> datetime | None:
+        value = self.nullable_string(key)
+        return None if value is None else self._parse_date(key, value)
+
+    def strings(self, key: str) -> tuple[str, ...]:
+        items = self.values(key)
+        if not all(isinstance(item, str) for item in items):
+            raise self._wrong(key, "a list of strings")
+        return tuple(str(item) for item in items)
+
+    def values(self, key: str) -> list[object]:
+        value = self._value(key)
+        if not isinstance(value, list):
+            raise self._wrong(key, "a list")
+        return value
+
+    def objects(self, key: str, parse: Callable[[Fields], T]) -> tuple[T, ...]:
+        """Each item of a list of objects, parsed with ``parse``."""
+        return tuple(parse(Fields.of(item, f"{self._path}.{key}[{i}]")) for i, item in enumerate(self.values(key)))
+
+    def child(self, key: str) -> Fields:
+        return Fields.of(self._value(key), f"{self._path}.{key}")
+
+    def raw(self) -> dict[str, object]:
+        """The object as decoded, for data this library does not model."""
+        return self._data
+
+    def _value(self, key: str) -> object:
+        if key not in self._data:
+            raise UnexpectedResponseError(f"{self._path}.{key} is missing")
+        return self._data[key]
+
+    def _parse_date(self, key: str, value: str) -> datetime:
+        try:
+            parsed = datetime.fromisoformat(value)
+        except ValueError:
+            raise self._wrong(key, "an ISO 8601 date") from None
+        if parsed.tzinfo is None:
+            raise self._wrong(key, "an ISO 8601 date with a time zone")
+        return parsed
+
+    def _wrong(self, key: str, expected: str) -> UnexpectedResponseError:
+        return UnexpectedResponseError(f"{self._path}.{key} is not {expected}")