solverr 0.1.0__py3-none-any.whl

solverr/__init__.py

@@ -0,0 +1,8 @@
+"""Server SDK for the Solverr crypto payment API."""
+
+from . import types, webhooks
+from ._client import Solverr
+from ._config import SDK_VERSION as __version__
+from ._errors import SolverrError, WebhookVerificationError
+
+__all__ = ["Solverr", "SolverrError", "WebhookVerificationError", "__version__", "types", "webhooks"]

solverr/_client.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import os
+import re
+import urllib.parse
+
+from ._config import BASE_URL_ENV, LOCAL_HOSTS
+from ._http import HttpClient
+from .resources import Credits, Invoices, PaymentLinks, Payouts, Refunds, Subscriptions, Tokens, Webhooks
+
+_API_KEY_PATTERN = re.compile(r"sk_live_[\x21-\x7e]+")
+# Whitespace and control characters, which http.client refuses in a URL.
+_URL_UNSAFE = re.compile(r"[\s\x00-\x1f\x7f]")
+
+
+def _resolve_base_url(base_url: str | None) -> str:
+    """Validates the base URL and drops a trailing slash so API paths can be appended."""
+    value = base_url if base_url is not None else os.environ.get(BASE_URL_ENV)
+    if not value:
+        raise ValueError(f"Pass base_url to Solverr() or set the {BASE_URL_ENV} environment variable.")
+    parts = urllib.parse.urlsplit(value)
+    if not parts.netloc or _URL_UNSAFE.search(value):
+        raise ValueError(f"base_url is not a valid URL: {value}")
+    if parts.scheme != "https" and not (parts.scheme == "http" and parts.hostname in LOCAL_HOSTS):
+        raise ValueError("base_url must be an https URL (http only for localhost).")
+    # "?" or "#" with nothing after it gives an empty query or fragment, yet still breaks the appended API paths.
+    if "?" in value or "#" in value:
+        raise ValueError("base_url must not have a query string or fragment.")
+    return value.rstrip("/")
+
+
+class Solverr:
+    """Client for the Solverr API; ``api_key`` is an API key starting with ``sk_live_``.
+
+    ``base_url`` is the origin of the Solverr app, such as ``"https://pay.example.com"``; defaults to ``SOLVERR_URL``."""
+
+    def __init__(self, api_key: str | None, base_url: str | None = None) -> None:
+        if not api_key or not _API_KEY_PATTERN.fullmatch(api_key):
+            raise ValueError("api_key must be a Solverr API key starting with sk_live_.")
+        http = HttpClient(api_key, _resolve_base_url(base_url))
+        self.invoices = Invoices(http)
+        self.payment_links = PaymentLinks(http)
+        self.refunds = Refunds(http)
+        self.payouts = Payouts(http)
+        self.subscriptions = Subscriptions(http)
+        self.credits = Credits(http)
+        self.tokens = Tokens(http)
+        self.webhooks = Webhooks(http)

solverr/_config.py

@@ -0,0 +1,38 @@
+SDK_VERSION = "0.1.0"
+
+BASE_URL_ENV = "SOLVERR_URL"
+
+# Hosts that may serve the API over plain http, for local development; every other host needs https.
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+# Socket timeout for connecting and for each read; reading the body also stops once this many seconds have passed since the attempt began.
+REQUEST_TIMEOUT_SECONDS = 15.0
+
+# Largest piece of a response body read at once, between checks of the request deadline.
+READ_CHUNK_BYTES = 65536
+
+# Extra attempts after a network error or a 5xx response.
+MAX_RETRIES = 2
+
+# Delay before the first retry; each later retry doubles it.
+RETRY_BASE_DELAY_SECONDS = 0.5
+
+# Extra attempts after a 429, or a 409 for a key that is still being processed, each after its Retry-After wait.
+MAX_RETRY_AFTER_RETRIES = 3
+
+# Longest Retry-After the client waits for; a longer one is raised as an error.
+MAX_RETRY_AFTER_SECONDS = 10
+
+WEBHOOK_TOLERANCE_SECONDS = 300
+
+# Standard Webhooks headers (standardwebhooks.com), lowercase for lookups.
+WEBHOOK_ID_HEADER = "webhook-id"
+
+WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp"
+
+WEBHOOK_SIGNATURE_HEADER = "webhook-signature"
+
+WEBHOOK_SECRET_PREFIX = "whsec_"
+
+# Shortest signing key accepted after decoding; Standard Webhooks secrets are 24 to 64 bytes.
+WEBHOOK_SECRET_MIN_BYTES = 24

solverr/_errors.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+
+class SolverrError(Exception):
+    """An error returned by the Solverr API, or a request that never got a response (``status`` 0)."""
+
+    def __init__(
+        self,
+        status: int,
+        type: str,
+        message: str,
+        param: str | None = None,
+        code: str | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.message = message
+        self.param = param
+        # Finer reason inside ``type``, such as ``invoice_paid``, when the API sends one.
+        self.code = code
+        # Seconds the API asked to wait before trying again (its ``Retry-After`` header), such as on a 429.
+        self.retry_after = retry_after
+
+    def __reduce__(self) -> tuple[type[SolverrError], tuple[int, str, str, str | None, str | None, int | None]]:
+        """Rebuilds the error from all its fields, so it survives pickling across processes and ``copy``."""
+        return (SolverrError, (self.status, self.type, self.message, self.param, self.code, self.retry_after))
+
+    def __repr__(self) -> str:
+        return (
+            f"SolverrError(status={self.status!r}, type={self.type!r}, code={self.code!r}, "
+            f"message={self.message!r}, param={self.param!r}, retry_after={self.retry_after!r})"
+        )
+
+
+class WebhookVerificationError(Exception):
+    """A webhook whose signature, timestamp or body could not be verified."""

solverr/_http.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import http.client
+import json
+import random
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from collections.abc import Mapping
+from email.message import Message
+from typing import Any, Literal
+
+from ._config import (
+    MAX_RETRIES,
+    MAX_RETRY_AFTER_RETRIES,
+    MAX_RETRY_AFTER_SECONDS,
+    READ_CHUNK_BYTES,
+    REQUEST_TIMEOUT_SECONDS,
+    RETRY_BASE_DELAY_SECONDS,
+    SDK_VERSION,
+)
+from ._errors import SolverrError
+
+Method = Literal["GET", "POST", "DELETE"]
+
+# Characters http.client cannot send in a header value; such a key fails before any request is sent.
+_INVALID_HEADER_VALUE = re.compile(r"[\x00\r\n]|[^\x00-\xff]")
+
+
+class _RejectRedirects(urllib.request.HTTPRedirectHandler):
+    """Returns a 3xx response as an error instead of following it, so credentials never move to another URL."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+def _retry_delay(attempt: int) -> float:
+    """Exponential backoff with up to 25% random jitter."""
+    return RETRY_BASE_DELAY_SECONDS * 2.0**attempt * (1 + random.random() / 4)
+
+
+def path_segment(value: str) -> str:
+    """An id as one URL path segment; empty, ``.`` and ``..`` are refused because they would point at another path."""
+    if value in ("", ".", ".."):
+        raise ValueError(f"{value!r} is not a valid id.")
+    return urllib.parse.quote(value, safe="")
+
+
+def _read_body(response: Any, deadline: float) -> bytes:
+    """Reads the response body piece by piece and gives up with ``TimeoutError`` once ``deadline`` has passed."""
+    chunks: list[bytes] = []
+    while True:
+        if time.monotonic() > deadline:
+            raise TimeoutError(f"no complete response within {REQUEST_TIMEOUT_SECONDS:g} seconds")
+        chunk = response.read1(READ_CHUNK_BYTES)
+        if not chunk:
+            return b"".join(chunks)
+        chunks.append(chunk)
+
+
+def _parse_json(text: bytes) -> Any:
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def _retry_after_seconds(value: str | None) -> int | None:
+    """``Retry-After`` in seconds; only the delay-seconds form is read, as the API never sends an HTTP date."""
+    return int(value) if value is not None and value.isascii() and value.isdigit() else None
+
+
+def _to_api_error(status: int, payload: Any, retry_after: str | None) -> SolverrError:
+    seconds = _retry_after_seconds(retry_after)
+    error = payload.get("error") if isinstance(payload, dict) else None
+    if isinstance(error, dict) and isinstance(error.get("type"), str) and isinstance(error.get("message"), str):
+        param, code = error.get("param"), error.get("code")
+        return SolverrError(
+            status,
+            error["type"],
+            error["message"],
+            param if isinstance(param, str) else None,
+            code if isinstance(code, str) else None,
+            seconds,
+        )
+    return SolverrError(status, "api_error", f"Solverr returned HTTP {status}.", retry_after=seconds)
+
+
+def _retry_after_delay(status: int, retry_after: str | None, payload: Any) -> float | None:
+    """Seconds to wait before retrying a 429 or an in-progress Idempotency-Key 409; None when it must not be retried."""
+    error = payload.get("error") if isinstance(payload, dict) else None
+    error_type = error.get("type") if isinstance(error, dict) else None
+    retryable = status == 429 or (status == 409 and error_type == "idempotency_conflict")
+    seconds = _retry_after_seconds(retry_after)
+    if not retryable or seconds is None:
+        return None
+    return float(seconds) if seconds <= MAX_RETRY_AFTER_SECONDS else None
+
+
+class HttpClient:
+    """Sends authenticated JSON requests, retrying network errors and 5xx responses, and 429s or in-progress 409s after a short ``Retry-After``."""
+
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._opener = urllib.request.build_opener(_RejectRedirects)
+
+    def request(
+        self,
+        method: Method,
+        path: str,
+        *,
+        query: Mapping[str, str | int | None] | None = None,
+        body: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        url = self._url(path, query or {})
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"solverr-python/{SDK_VERSION}",
+        }
+        payload: bytes | None = None
+        if method == "POST":
+            # The same key is sent on every retry, so the server never applies a POST twice.
+            headers["Idempotency-Key"] = idempotency_key if idempotency_key is not None else str(uuid.uuid4())
+            if _INVALID_HEADER_VALUE.search(headers["Idempotency-Key"]):
+                raise ValueError("idempotency_key cannot contain line breaks, NUL or characters above U+00FF.")
+            if body is not None:
+                # Fields set to None are left out, because the API refuses null in place of an omitted optional field.
+                fields = {name: value for name, value in body.items() if value is not None}
+                headers["Content-Type"] = "application/json"
+                payload = json.dumps(fields, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+        attempt = 0
+        retry_after_retries = 0
+        while True:
+            can_retry = attempt < MAX_RETRIES
+            try:
+                status, response_headers, text = self._send(urllib.request.Request(url, data=payload, headers=headers, method=method))
+            except (urllib.error.URLError, http.client.HTTPException, OSError) as error:
+                if can_retry:
+                    time.sleep(_retry_delay(attempt))
+                    attempt += 1
+                    continue
+                reason = getattr(error, "reason", error)
+                raise SolverrError(0, "connection_error", f"Could not reach Solverr at {self._base_url}: {reason}") from error
+
+            if 300 <= status < 400:
+                location = response_headers.get("Location")
+                target = f" to {location}" if location else ""
+                raise SolverrError(
+                    status, "api_error", f"Solverr answered with a redirect{target}. Set base_url to the address Solverr is served from."
+                )
+            if status >= 500 and can_retry:
+                time.sleep(_retry_delay(attempt))
+                attempt += 1
+                continue
+            parsed = _parse_json(text)
+            retry_after = response_headers.get("Retry-After")
+            delay = _retry_after_delay(status, retry_after, parsed) if retry_after_retries < MAX_RETRY_AFTER_RETRIES else None
+            if delay is not None:
+                time.sleep(delay)
+                retry_after_retries += 1
+                continue
+            if status < 200 or status >= 300:
+                raise _to_api_error(status, parsed, retry_after)
+            if parsed is None:
+                raise SolverrError(status, "api_error", "Solverr returned a response that is not JSON.")
+            return parsed
+
+    def _send(self, request: urllib.request.Request) -> tuple[int, Message, bytes]:
+        """One HTTP attempt; returns the status, headers and body for every response, including 3xx, 4xx and 5xx.
+
+        ``REQUEST_TIMEOUT_SECONDS`` is the socket timeout, and the body read stops at that deadline, so a body sent a byte at a time cannot hold the call open."""
+        deadline = time.monotonic() + REQUEST_TIMEOUT_SECONDS
+        try:
+            with self._opener.open(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+                return response.status, response.headers, _read_body(response, deadline)
+        except urllib.error.HTTPError as error:
+            with error:
+                return error.code, error.headers, _read_body(error, deadline)
+
+    def _url(self, path: str, query: Mapping[str, str | int | None]) -> str:
+        url = self._base_url + path
+        params = {name: str(value) for name, value in query.items() if value is not None}
+        return f"{url}?{urllib.parse.urlencode(params, quote_via=urllib.parse.quote)}" if params else url

solverr/resources/__init__.py

@@ -0,0 +1,10 @@
+from .credits import Credits
+from .invoices import Invoices
+from .payment_links import PaymentLinks
+from .payouts import Payouts
+from .refunds import Refunds
+from .subscriptions import Subscriptions
+from .tokens import Tokens
+from .webhooks import Webhooks
+
+__all__ = ["Credits", "Invoices", "PaymentLinks", "Payouts", "Refunds", "Subscriptions", "Tokens", "Webhooks"]

solverr/resources/credits.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Literal, cast
+
+from .._http import HttpClient, path_segment
+from ..types import CreditCharge, CreditTopup
+
+
+class Credits:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def topup(
+        self,
+        *,
+        amount: str,
+        currency: Literal["USD"],
+        credit_account_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> CreditTopup:
+        """Creates a USD credit account and the invoice that funds it; the balance is added once the invoice is paid.
+
+        Pass ``credit_account_id`` to add to an existing account instead of creating a new one (and a new token)."""
+        body = {"amount": amount, "currency": currency, "credit_account_id": credit_account_id}
+        return cast(CreditTopup, self._http.request("POST", "/api/v1/credits/topup", body=body, idempotency_key=idempotency_key))
+
+    def charge(
+        self,
+        *,
+        token: str,
+        amount: str,
+        currency: Literal["USD"] | None = None,
+        description: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> CreditCharge:
+        """Deducts an amount from the credit account that owns ``token`` and returns the charge with the remaining balance.
+
+        Credit balances are kept in USD; other currencies are rejected."""
+        body = {"token": token, "amount": amount, "currency": currency, "description": description}
+        return cast(CreditCharge, self._http.request("POST", "/api/v1/credits/charge", body=body, idempotency_key=idempotency_key))
+
+    def refund_charge(self, charge_id: str, *, idempotency_key: str | None = None) -> CreditCharge:
+        """Gives a charge back to its credit account, once; for a request the charge paid for that then failed."""
+        path = f"/api/v1/credits/charges/{path_segment(charge_id)}/refund"
+        return cast(CreditCharge, self._http.request("POST", path, body={}, idempotency_key=idempotency_key))

solverr/resources/invoices.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import cast
+
+from .._http import HttpClient, path_segment
+from ..types import Currency, Invoice, InvoiceList, InvoiceRedemption, InvoiceStatus
+
+
+def _invoice_path(invoice_id: str) -> str:
+    return f"/api/v1/invoices/{path_segment(invoice_id)}"
+
+
+class Invoices:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        amount: str,
+        currency: Currency,
+        order_id: str | None = None,
+        description: str | None = None,
+        redirect_url: str | None = None,
+        customer_email: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        expires_in: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Invoice:
+        """Creates an invoice; send the customer to its ``checkout_url``.
+
+        ``amount`` has up to two decimals, such as ``"25.00"``; ``expires_in`` is the invoice lifetime in seconds, 900 to 86400."""
+        body = {
+            "amount": amount,
+            "currency": currency,
+            "order_id": order_id,
+            "description": description,
+            "redirect_url": redirect_url,
+            "customer_email": customer_email,
+            "metadata": dict(metadata) if metadata is not None else None,
+            "expires_in": expires_in,
+        }
+        return cast(Invoice, self._http.request("POST", "/api/v1/invoices", body=body, idempotency_key=idempotency_key))
+
+    def retrieve(self, invoice_id: str) -> Invoice:
+        return cast(Invoice, self._http.request("GET", _invoice_path(invoice_id)))
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        starting_after: str | None = None,
+        status: InvoiceStatus | None = None,
+    ) -> InvoiceList:
+        """One page of invoices, newest first. ``limit`` is 1 to 100."""
+        query = {"limit": limit, "starting_after": starting_after, "status": status}
+        return cast(InvoiceList, self._http.request("GET", "/api/v1/invoices", query=query))
+
+    def list_all(
+        self,
+        *,
+        limit: int | None = None,
+        starting_after: str | None = None,
+        status: InvoiceStatus | None = None,
+    ) -> Iterator[Invoice]:
+        """Every matching invoice, newest first, fetching pages as the loop advances."""
+        while True:
+            page = self.list(limit=limit, starting_after=starting_after, status=status)
+            yield from page["data"]
+            if not page["has_more"] or not page["data"]:
+                return
+            starting_after = page["data"][-1]["id"]
+
+    def redeem(self, invoice_id: str, *, idempotency_key: str | None = None) -> InvoiceRedemption:
+        """Marks a paid invoice as used, so it grants access only once.
+
+        Raises ``SolverrError`` 409 with type ``invalid_state`` when unpaid, or ``already_redeemed`` when used before."""
+        path = f"{_invoice_path(invoice_id)}/redeem"
+        return cast(InvoiceRedemption, self._http.request("POST", path, idempotency_key=idempotency_key))

solverr/resources/payment_links.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._http import HttpClient, path_segment
+from ..types import Currency, PaymentLink, PaymentLinkList
+
+
+class PaymentLinks:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        title: str,
+        currency: Currency,
+        amount: str | None = None,
+        redirect_url: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> PaymentLink:
+        """Creates a payment link; leave out ``amount`` to let the customer choose it, and ``redirect_url`` to send customers to the business website after paying."""
+        body = {"title": title, "amount": amount, "currency": currency, "redirect_url": redirect_url}
+        return cast(PaymentLink, self._http.request("POST", "/api/v1/payment-links", body=body, idempotency_key=idempotency_key))
+
+    def list(self, *, limit: int | None = None, starting_after: str | None = None) -> PaymentLinkList:
+        query = {"limit": limit, "starting_after": starting_after}
+        return cast(PaymentLinkList, self._http.request("GET", "/api/v1/payment-links", query=query))
+
+    def deactivate(self, link_id: str) -> PaymentLink:
+        """Turns a link off and returns it with ``active`` false; invoices already created from it stay payable."""
+        path = f"/api/v1/payment-links/{path_segment(link_id)}"
+        return cast(PaymentLink, self._http.request("DELETE", path))

solverr/resources/payouts.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import cast
+
+from .._http import HttpClient, path_segment
+from ..types import Payout, PayoutBatch, PayoutList
+
+
+def _payout_path(payout_id: str) -> str:
+    return f"/api/v1/payouts/{path_segment(payout_id)}"
+
+
+class Payouts:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        recipient: str,
+        asset_id: str,
+        amount: str,
+        idempotency_key: str | None = None,
+    ) -> Payout:
+        """Creates a payout of the coin ``asset_id``, taken from ``tokens.list()``; the business completes it by signing at ``sign_url``."""
+        body = {"recipient": recipient, "asset_id": asset_id, "amount": amount}
+        return cast(Payout, self._http.request("POST", "/api/v1/payouts", body=body, idempotency_key=idempotency_key))
+
+    def create_batch(
+        self,
+        *,
+        payouts: Sequence[Mapping[str, str]],
+        idempotency_key: str | None = None,
+    ) -> PayoutBatch:
+        """Creates 1 to 200 payouts that share one ``batch_id``; every row is checked before any payout is created.
+
+        Each item has the keys ``recipient``, ``asset_id`` and ``amount``."""
+        body = {"payouts": [dict(payout) for payout in payouts]}
+        return cast(PayoutBatch, self._http.request("POST", "/api/v1/payouts/batch", body=body, idempotency_key=idempotency_key))
+
+    def retrieve(self, payout_id: str) -> Payout:
+        return cast(Payout, self._http.request("GET", _payout_path(payout_id)))
+
+    def list(self, *, limit: int | None = None, starting_after: str | None = None) -> PayoutList:
+        query = {"limit": limit, "starting_after": starting_after}
+        return cast(PayoutList, self._http.request("GET", "/api/v1/payouts", query=query))
+
+    def cancel(self, payout_id: str, *, idempotency_key: str | None = None) -> Payout:
+        """Cancels a payout that was not sent. Raises a 409 error once it was sent."""
+        return cast(Payout, self._http.request("POST", f"{_payout_path(payout_id)}/cancel", body={}, idempotency_key=idempotency_key))

solverr/resources/refunds.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._http import HttpClient, path_segment
+from ..types import Refund, RefundList
+
+
+def _refund_path(refund_id: str) -> str:
+    return f"/api/v1/refunds/{path_segment(refund_id)}"
+
+
+class Refunds:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        invoice_id: str,
+        payment_id: str | None = None,
+        amount: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Refund:
+        """Refunds the payment that paid the invoice, or ``payment_id`` for an extra payment; the business signs it at ``sign_url``.
+
+        ``amount`` is in the settlement coin; leave it out to refund what is left of that payment."""
+        body = {"invoice_id": invoice_id, "payment_id": payment_id, "amount": amount}
+        return cast(Refund, self._http.request("POST", "/api/v1/refunds", body=body, idempotency_key=idempotency_key))
+
+    def retrieve(self, refund_id: str) -> Refund:
+        return cast(Refund, self._http.request("GET", _refund_path(refund_id)))
+
+    def list(self, *, limit: int | None = None, starting_after: str | None = None) -> RefundList:
+        query = {"limit": limit, "starting_after": starting_after}
+        return cast(RefundList, self._http.request("GET", "/api/v1/refunds", query=query))
+
+    def cancel(self, refund_id: str, *, idempotency_key: str | None = None) -> Refund:
+        """Cancels a refund that was not sent; its amount can then be refunded again. Raises a 409 error once it was sent."""
+        return cast(Refund, self._http.request("POST", f"{_refund_path(refund_id)}/cancel", body={}, idempotency_key=idempotency_key))

solverr/resources/subscriptions.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._http import HttpClient, path_segment
+from ..types import Currency, Subscription, SubscriptionInterval, SubscriptionList
+
+
+class Subscriptions:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        customer_email: str,
+        amount: str,
+        currency: Currency,
+        interval: SubscriptionInterval,
+        description: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Subscription:
+        """Creates a subscription that issues an invoice to the customer every ``interval``."""
+        body = {
+            "customer_email": customer_email,
+            "amount": amount,
+            "currency": currency,
+            "interval": interval,
+            "description": description,
+        }
+        return cast(Subscription, self._http.request("POST", "/api/v1/subscriptions", body=body, idempotency_key=idempotency_key))
+
+    def list(self, *, limit: int | None = None, starting_after: str | None = None) -> SubscriptionList:
+        query = {"limit": limit, "starting_after": starting_after}
+        return cast(SubscriptionList, self._http.request("GET", "/api/v1/subscriptions", query=query))
+
+    def cancel(self, subscription_id: str) -> Subscription:
+        """Cancels a subscription and returns it with status ``canceled``; invoices already sent stay payable."""
+        path = f"/api/v1/subscriptions/{path_segment(subscription_id)}"
+        return cast(Subscription, self._http.request("DELETE", path))

solverr/resources/tokens.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._http import HttpClient
+from ..types import TokenList
+
+
+class Tokens:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> TokenList:
+        """Lists the coins the checkout accepts, with USD prices; the API caches the list for 60 seconds."""
+        return cast(TokenList, self._http.request("GET", "/api/v1/tokens"))

solverr/resources/webhooks.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._http import HttpClient
+from ..types import WebhookTest
+
+
+class Webhooks:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def send_test(self) -> WebhookTest:
+        """Queues a signed ``test.ping`` event to the business's webhook URL; raises ``SolverrError`` 409 when none is set."""
+        return cast(WebhookTest, self._http.request("POST", "/api/v1/webhooks/test"))