stablevoy 1.0.0__tar.gz

stablevoy-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

stablevoy-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.0.0
+
+First release: invoices (create with an idempotency key, read, list and walk all pages), the store of the API key, limits, pricing and networks, typed errors with retries where a repeat is safe, and webhook signature verification. No dependencies, Python 3.11 or newer, fully typed.
+
+Security: the base URL must be https (http only for localhost) and only a host, invoice ids must be UUIDs, redirects are never followed and every request has a timeout, so the API key cannot leak or reach another path.

stablevoy-1.0.0/LICENSE

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

stablevoy-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: stablevoy
+Version: 1.0.0
+Summary: Python client for the Stablevoy API: non-custodial USDT and USDC payments, invoices and signed webhooks.
+Project-URL: Homepage, https://stablevoy.com
+Project-URL: Documentation, https://stablevoy.com/docs/
+Project-URL: Source, https://github.com/stablevoy/stablevoy-python
+Project-URL: Issues, https://github.com/stablevoy/stablevoy-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crypto payments,payment gateway,stablecoin,stablevoy,tether,trc20,tron,usdc,usdt,webhooks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Stablevoy Python SDK
+
+[![CI](https://github.com/stablevoy/stablevoy-python/actions/workflows/ci.yml/badge.svg)](https://github.com/stablevoy/stablevoy-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stablevoy)](https://pypi.org/project/stablevoy/)
+
+Python client for [Stablevoy](https://stablevoy.com), the non-custodial gateway for USDT and USDC payments. Customers pay on chain and the money goes straight to your own wallet: USDC and USDT on Base, Arbitrum, Optimism, Avalanche, Polygon and BNB Chain, and USDT (TRC20) on Tron with no fee.
+
+The library creates invoices, reads them, and verifies the signed webhooks that tell your shop an order is paid. It has no dependencies, needs Python 3.11 or newer and is fully typed.
+
+## Install
+
+```bash
+pip install stablevoy
+```
+
+## Create an invoice and send the buyer to pay
+
+Create an API key for your store in the [Stablevoy dashboard](https://stablevoy.com/app/).
+
+```python
+import os
+
+from stablevoy import Stablevoy
+
+stablevoy = Stablevoy.create(os.environ["STABLEVOY_API_KEY"])
+
+created = stablevoy.invoices.create(
+    2599,  # $25.99 in US cents
+    external_reference="order-1042",  # your order id, sent back in webhooks
+    return_url="https://shop.example/orders/1042",
+    idempotency_key="order-1042",  # a retry returns the same invoice, never a second one
+)
+
+# Send the buyer to created.checkout_url
+```
+
+Read an invoice with `stablevoy.invoices.get(invoice_id)`, or walk them all:
+
+```python
+for invoice in stablevoy.invoices.all(status="paid"):
+    print(invoice.external_reference, invoice.amount_usd_cents)
+```
+
+## Verify webhooks
+
+Stablevoy posts an event to your webhook URL when an invoice is paid, overpaid, underpaid, expired, paid late or put on hold. Check the signature before you trust it, using the signing secret shown when you set the webhook in the dashboard. Pass the raw body, exactly as received.
+
+Flask:
+
+```python
+from flask import Flask, request
+
+from stablevoy import SignatureError, WebhookVerifier
+
+verifier = WebhookVerifier(os.environ["STABLEVOY_WEBHOOK_SECRET"])
+app = Flask(__name__)
+
+
+@app.post("/stablevoy/webhook")
+def stablevoy_webhook():
+    try:
+        event = verifier.verify(request.get_data(), request.headers.get("X-Stablevoy-Signature"))
+    except SignatureError:
+        return "", 400
+    if event.invoice is not None and event.invoice.is_paid():
+        ...  # mark the order event.invoice.external_reference as paid; use event.id to handle each event once
+    return "", 200
+```
+
+Django: `verifier.verify(request.body, request.headers.get("X-Stablevoy-Signature"))`. FastAPI: `verifier.verify(await request.body(), request.headers.get("X-Stablevoy-Signature"))`.
+
+## Errors and retries
+
+Every error extends `StablevoyError`. API errors are `ApiError` with the HTTP `status`, a stable `code`, a readable `detail` and a link to the [error catalog](https://stablevoy.com/docs/api/errors/); the ones you may want to handle on their own are `AuthenticationError`, `ValidationError` (with `issues`), `NotFoundError`, `RateLimitedError` and `MaintenanceError`. `TransportError` means no answer at all.
+
+Reads, and creates that carry an idempotency key, are retried on rate limits, maintenance and failed connections, at most twice and only for waits of up to 10 seconds. Anything longer reaches you with `retry_after_seconds`, so a request never hangs. Every request times out after 30 seconds.
+
+```python
+from stablevoy import RetryPolicy, Stablevoy
+
+stablevoy = Stablevoy.create(api_key, retries=RetryPolicy(max_retries=3, max_wait_seconds=30), timeout_seconds=10)
+```
+
+## Links
+
+- [API reference](https://stablevoy.com/docs/api/)
+- [Docs](https://stablevoy.com/docs/)
+- [PHP SDK](https://github.com/stablevoy/stablevoy-php), [Node.js SDK](https://github.com/stablevoy/stablevoy-node)
+- [WooCommerce plugin](https://wordpress.org/plugins/stablevoy-for-woocommerce/)
+
+## License
+
+MIT

stablevoy-1.0.0/README.md

@@ -0,0 +1,93 @@
+# Stablevoy Python SDK
+
+[![CI](https://github.com/stablevoy/stablevoy-python/actions/workflows/ci.yml/badge.svg)](https://github.com/stablevoy/stablevoy-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stablevoy)](https://pypi.org/project/stablevoy/)
+
+Python client for [Stablevoy](https://stablevoy.com), the non-custodial gateway for USDT and USDC payments. Customers pay on chain and the money goes straight to your own wallet: USDC and USDT on Base, Arbitrum, Optimism, Avalanche, Polygon and BNB Chain, and USDT (TRC20) on Tron with no fee.
+
+The library creates invoices, reads them, and verifies the signed webhooks that tell your shop an order is paid. It has no dependencies, needs Python 3.11 or newer and is fully typed.
+
+## Install
+
+```bash
+pip install stablevoy
+```
+
+## Create an invoice and send the buyer to pay
+
+Create an API key for your store in the [Stablevoy dashboard](https://stablevoy.com/app/).
+
+```python
+import os
+
+from stablevoy import Stablevoy
+
+stablevoy = Stablevoy.create(os.environ["STABLEVOY_API_KEY"])
+
+created = stablevoy.invoices.create(
+    2599,  # $25.99 in US cents
+    external_reference="order-1042",  # your order id, sent back in webhooks
+    return_url="https://shop.example/orders/1042",
+    idempotency_key="order-1042",  # a retry returns the same invoice, never a second one
+)
+
+# Send the buyer to created.checkout_url
+```
+
+Read an invoice with `stablevoy.invoices.get(invoice_id)`, or walk them all:
+
+```python
+for invoice in stablevoy.invoices.all(status="paid"):
+    print(invoice.external_reference, invoice.amount_usd_cents)
+```
+
+## Verify webhooks
+
+Stablevoy posts an event to your webhook URL when an invoice is paid, overpaid, underpaid, expired, paid late or put on hold. Check the signature before you trust it, using the signing secret shown when you set the webhook in the dashboard. Pass the raw body, exactly as received.
+
+Flask:
+
+```python
+from flask import Flask, request
+
+from stablevoy import SignatureError, WebhookVerifier
+
+verifier = WebhookVerifier(os.environ["STABLEVOY_WEBHOOK_SECRET"])
+app = Flask(__name__)
+
+
+@app.post("/stablevoy/webhook")
+def stablevoy_webhook():
+    try:
+        event = verifier.verify(request.get_data(), request.headers.get("X-Stablevoy-Signature"))
+    except SignatureError:
+        return "", 400
+    if event.invoice is not None and event.invoice.is_paid():
+        ...  # mark the order event.invoice.external_reference as paid; use event.id to handle each event once
+    return "", 200
+```
+
+Django: `verifier.verify(request.body, request.headers.get("X-Stablevoy-Signature"))`. FastAPI: `verifier.verify(await request.body(), request.headers.get("X-Stablevoy-Signature"))`.
+
+## Errors and retries
+
+Every error extends `StablevoyError`. API errors are `ApiError` with the HTTP `status`, a stable `code`, a readable `detail` and a link to the [error catalog](https://stablevoy.com/docs/api/errors/); the ones you may want to handle on their own are `AuthenticationError`, `ValidationError` (with `issues`), `NotFoundError`, `RateLimitedError` and `MaintenanceError`. `TransportError` means no answer at all.
+
+Reads, and creates that carry an idempotency key, are retried on rate limits, maintenance and failed connections, at most twice and only for waits of up to 10 seconds. Anything longer reaches you with `retry_after_seconds`, so a request never hangs. Every request times out after 30 seconds.
+
+```python
+from stablevoy import RetryPolicy, Stablevoy
+
+stablevoy = Stablevoy.create(api_key, retries=RetryPolicy(max_retries=3, max_wait_seconds=30), timeout_seconds=10)
+```
+
+## Links
+
+- [API reference](https://stablevoy.com/docs/api/)
+- [Docs](https://stablevoy.com/docs/)
+- [PHP SDK](https://github.com/stablevoy/stablevoy-php), [Node.js SDK](https://github.com/stablevoy/stablevoy-node)
+- [WooCommerce plugin](https://wordpress.org/plugins/stablevoy-for-woocommerce/)
+
+## License
+
+MIT

stablevoy-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stablevoy"
+version = "1.0.0"
+description = "Python client for the Stablevoy API: non-custodial USDT and USDC payments, invoices and signed webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["stablevoy", "usdt", "usdc", "trc20", "stablecoin", "crypto payments", "payment gateway", "webhooks", "tether", "tron"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://stablevoy.com"
+Documentation = "https://stablevoy.com/docs/"
+Source = "https://github.com/stablevoy/stablevoy-python"
+Issues = "https://github.com/stablevoy/stablevoy-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stablevoy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/stablevoy", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=stablevoy --cov-branch --cov-report=term-missing --cov-fail-under=100"
+pythonpath = ["src"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+mypy_path = "src"
+
+[tool.ruff]
+line-length = 140
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "RUF", "SIM", "PT", "N", "ANN", "TRY", "EM", "PL"]
+ignore = ["TRY003", "PLR0913", "PLR2004", "EM101", "EM102"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106", "ANN", "PLR2004", "SLF001"]

stablevoy-1.0.0/src/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-1.0.0/src/stablevoy/_version.py

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

stablevoy-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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: ...