altpay-py 0.1.0__py3-none-any.whl

altpay/__init__.py

@@ -0,0 +1,119 @@
+"""AltPay - the official Python SDK for the AltPay crypto-payments API.
+
+Quick start (sync)::
+
+    from decimal import Decimal
+    from altpay import AltPay, Credentials
+
+    client = AltPay(Credentials(
+        merchant_id="YOUR_MERCHANT_ID",
+        api_key="vc_live_...",
+        api_secret="YOUR_API_SECRET",
+    ))
+    invoice = client.invoices.create(
+        uuid="order-42",
+        amount=Decimal("100.00"),
+        fiat_currency="USD",
+        url_callback="https://example.com/altpay/webhook",
+    )
+    print(invoice.url)
+
+Quick start (async)::
+
+    from altpay import AsyncAltPay, Credentials
+
+    async with AsyncAltPay(creds) as client:
+        invoice = await client.invoices.create(uuid="order-42", amount="100.00", fiat_currency="USD")
+
+Verifying a webhook::
+
+    from altpay import WebhookVerifier
+    verifier = WebhookVerifier(webhook_secret, target="/altpay/webhook")
+    event = verifier.parse(raw_body, request_headers)  # raises on a bad signature
+
+Documentation: https://docs.altpay.money/docs
+"""
+
+from .__meta__ import __version__
+from .client import AltPay, AsyncAltPay
+from .credentials import Credentials
+from .enums import FiatCurrency, MerchantStatus, PaymentMethod, PaymentStatus, WithdrawalStatus
+from .errors import (
+    AltPayError,
+    AltPayTransportError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    Forbidden,
+    NotFoundError,
+    PermissionError_,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Account,
+    AssetBalance,
+    AssetBalanceItem,
+    Balance,
+    BalanceAsset,
+    Invoice,
+    InvoicePage,
+    MethodBalance,
+    MethodBalanceItem,
+    Service,
+    ServiceCommission,
+    Statistics,
+    Wallet,
+    WalletDeposit,
+    WebhookEvent,
+    Withdrawal,
+    WithdrawalFee,
+)
+from .webhook import WebhookVerifier
+
+__all__ = [
+    "__version__",
+    # Clients
+    "AltPay",
+    "AsyncAltPay",
+    "Credentials",
+    # Webhooks
+    "WebhookVerifier",
+    # Enums
+    "PaymentStatus",
+    "PaymentMethod",
+    "FiatCurrency",
+    "MerchantStatus",
+    "WithdrawalStatus",
+    # Models
+    "Invoice",
+    "InvoicePage",
+    "Service",
+    "ServiceCommission",
+    "Balance",
+    "BalanceAsset",
+    "AssetBalance",
+    "AssetBalanceItem",
+    "Wallet",
+    "WalletDeposit",
+    "Account",
+    "MethodBalance",
+    "MethodBalanceItem",
+    "Statistics",
+    "Withdrawal",
+    "WithdrawalFee",
+    "WebhookEvent",
+    # Errors
+    "AltPayError",
+    "AltPayTransportError",
+    "APIError",
+    "AuthenticationError",
+    "Forbidden",
+    "PermissionError_",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+]

altpay/__meta__.py

@@ -0,0 +1,5 @@
+"""Package metadata, kept in one place so the version has a single source of truth."""
+
+__version__ = "0.1.0"
+__title__ = "altpay-py"
+__user_agent__ = f"altpay-py/{__version__}"

altpay/client/__init__.py

@@ -0,0 +1,6 @@
+"""HTTP clients: the synchronous :class:`AltPay` and asynchronous :class:`AsyncAltPay`."""
+
+from .async_client import AsyncAltPay
+from .sync_client import AltPay
+
+__all__ = ["AltPay", "AsyncAltPay"]

altpay/client/async_client.py

@@ -0,0 +1,114 @@
+"""The asynchronous client, :class:`AsyncAltPay`.
+
+The async twin of :class:`~altpay.client.sync_client.AltPay`. Same API, same resources, same
+request/response logic from :mod:`altpay.client.base`; only the I/O is awaited.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TypeVar
+
+import httpx
+
+from ..credentials import Credentials
+from ..errors import AltPayTransportError, RateLimitError, ServerError
+from ..methods.account import AccountResource
+from ..methods.base import APICall
+from ..methods.invoices import Invoices
+from ..methods.withdrawals import Withdrawals
+from .base import parse_response, prepare
+from .sync_client import DEFAULT_BASE_URL, _backoff, _retry_delay
+
+T = TypeVar("T")
+
+
+class AsyncAltPay:
+    """Asynchronous AltPay API client.
+
+    Example::
+
+        from decimal import Decimal
+        from altpay import AsyncAltPay, Credentials
+
+        async with AsyncAltPay(Credentials(
+            merchant_id="...", api_key="vc_live_...", api_secret="...",
+        )) as client:
+            invoice = await client.invoices.create(
+                uuid="order-1", amount=Decimal("100.00"), fiat_currency="USD",
+            )
+            print(invoice.url)
+
+    Args mirror :class:`~altpay.client.sync_client.AltPay`; ``http_client`` here is an
+    :class:`httpx.AsyncClient`.
+
+    API reference: https://docs.altpay.money/docs
+    """
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._credentials = credentials
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        #: Invoice and static-wallet operations.
+        self.invoices = Invoices(self.call)
+        #: Payout (withdrawal) operations.
+        self.withdrawals = Withdrawals(self.call)
+        #: Account identity, balance and statistics.
+        self.account = AccountResource(self.call)
+
+    async def __aenter__(self) -> "AsyncAltPay":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool (unless you supplied your own client)."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def call(self, call: APICall[T]) -> T:
+        """Execute a described :class:`~altpay.methods.base.APICall` and return its typed result."""
+        request = prepare(
+            credentials=self._credentials,
+            base_url=self._base_url,
+            path=call.path,
+            payload=call.payload,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    request.method, request.url, headers=request.headers, content=request.content
+                )
+            except httpx.HTTPError as exc:
+                if attempt >= self._max_retries:
+                    raise AltPayTransportError(str(exc)) from exc
+                await asyncio.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+
+            try:
+                result = parse_response(
+                    status_code=response.status_code,
+                    body_text=response.text,
+                    headers=response.headers,
+                )
+            except (RateLimitError, ServerError) as exc:
+                if attempt >= self._max_retries:
+                    raise
+                await asyncio.sleep(_retry_delay(exc, attempt))
+                attempt += 1
+                continue
+            return call.parse(result)

altpay/client/base.py

@@ -0,0 +1,149 @@
+"""Transport-agnostic request building and response parsing.
+
+The sync and async clients differ only in how they *send* bytes over the wire; everything
+else - serializing the body, signing it, choosing headers, unwrapping ``result``, turning a
+non-2xx status into a typed exception - is identical and lives here so there is exactly one
+implementation to reason about and audit.
+
+A :class:`PreparedRequest` is a pure value: given credentials and a call, it produces the
+exact method/url/headers/body to send. :func:`parse_response` is a pure function from a raw
+response to either the unwrapped ``result`` payload or a raised :class:`~altpay.errors.APIError`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ..__meta__ import __user_agent__
+from ..credentials import Credentials
+from ..errors import error_from_status
+from ..signing import sign_request
+
+# The public API is JSON-only and every endpoint is POST (including reads). Bodies are
+# serialized compactly and deterministically; the exact bytes are what we hash and sign, so
+# the body that goes on the wire must be the body we signed - never re-serialize downstream.
+_JSON_SEPARATORS = (",", ":")
+
+
+def serialize_body(payload: dict[str, Any] | None) -> bytes:
+    """Serialize a request payload to the canonical bytes that get signed and sent.
+
+    ``None`` and ``{}`` both serialize to ``b""`` - the body-less endpoints (``me.get``,
+    ``invoice/services``) take no body, and the server hashes an empty body for them.
+    """
+    if not payload:
+        return b""
+    return json.dumps(payload, separators=_JSON_SEPARATORS, ensure_ascii=False).encode("utf-8")
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedRequest:
+    """A fully-signed request ready to hand to httpx."""
+
+    method: str
+    url: str
+    headers: dict[str, str]
+    content: bytes
+
+
+def prepare(
+    *,
+    credentials: Credentials,
+    base_url: str,
+    path: str,
+    payload: dict[str, Any] | None,
+) -> PreparedRequest:
+    """Build and sign a request for ``path`` with ``payload``.
+
+    Args:
+        credentials: The merchant credentials to sign with.
+        base_url: API root, e.g. ``"https://api.altpay.money"`` (no trailing ``/api/v2``).
+        path: The endpoint path, e.g. ``"/api/v2/invoice/create"``.
+        payload: The request body as a dict, or ``None`` for body-less endpoints.
+
+    Returns:
+        A :class:`PreparedRequest` whose ``headers`` already include the signature set.
+    """
+    body = serialize_body(payload)
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": __user_agent__,
+    }
+    headers.update(
+        sign_request(
+            api_secret=credentials.api_secret,
+            merchant_id=credentials.merchant_id,
+            api_key=credentials.api_key,
+            method="POST",
+            path=path,
+            body=body,
+        )
+    )
+    return PreparedRequest(method="POST", url=f"{base_url}{path}", headers=headers, content=body)
+
+
+def parse_response(
+    *,
+    status_code: int,
+    body_text: str,
+    headers: Any,
+) -> Any:
+    """Turn a raw response into the unwrapped ``result`` payload, or raise a typed error.
+
+    On a 2xx response, returns the value of the JSON body's ``result`` field (or the whole
+    body if it is not wrapped). On any other status, raises the most specific
+    :class:`~altpay.errors.APIError` subclass, carrying the server's ``detail`` and the
+    ``X-Request-Id`` header (when present) for support correlation.
+    """
+    parsed = _safe_json(body_text)
+    request_id = _get_header(headers, "X-Request-Id")
+
+    if 200 <= status_code < 300:
+        if isinstance(parsed, dict) and "result" in parsed:
+            return parsed["result"]
+        return parsed
+
+    detail = parsed.get("detail") if isinstance(parsed, dict) else None
+    retry_after = _parse_retry_after(_get_header(headers, "Retry-After"))
+    raise error_from_status(
+        status_code,
+        detail=detail if isinstance(detail, str) else None,
+        response_body=parsed,
+        request_id=request_id,
+        retry_after=retry_after,
+    )
+
+
+def _safe_json(text: str) -> Any:
+    """Parse JSON, falling back to the raw text so a non-JSON error page is still surfaced."""
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _get_header(headers: Any, name: str) -> str | None:
+    """Read a header from an httpx.Headers (case-insensitive) or a plain mapping."""
+    try:
+        return headers.get(name)
+    except AttributeError:
+        lowered = name.lower()
+        for key, value in dict(headers).items():
+            if str(key).lower() == lowered:
+                return value
+        return None
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header expressed in seconds; ignore HTTP-date form."""
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None

altpay/client/sync_client.py

@@ -0,0 +1,149 @@
+"""The synchronous client, :class:`AltPay`.
+
+Wraps an :class:`httpx.Client`. Resources (``invoices``, ``account``) describe calls; this
+class signs, sends and parses them. It is the synchronous twin of
+:class:`~altpay.client.async_client.AsyncAltPay` and shares all of its logic via
+:mod:`altpay.client.base`.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, TypeVar
+
+import httpx
+
+from ..credentials import Credentials
+from ..errors import AltPayTransportError, RateLimitError, ServerError
+from ..methods.account import AccountResource
+from ..methods.base import APICall
+from ..methods.invoices import Invoices
+from ..methods.withdrawals import Withdrawals
+from .base import parse_response, prepare
+
+T = TypeVar("T")
+
+DEFAULT_BASE_URL = "https://api.altpay.money"
+
+
+class AltPay:
+    """Synchronous AltPay API client.
+
+    Example::
+
+        from decimal import Decimal
+        from altpay import AltPay, Credentials
+
+        client = AltPay(Credentials(
+            merchant_id="...", api_key="vc_live_...", api_secret="...",
+        ))
+        invoice = client.invoices.create(
+            uuid="order-1", amount=Decimal("100.00"), fiat_currency="USD",
+            url_callback="https://example.com/altpay/webhook",
+        )
+        print(invoice.url)
+        client.close()
+
+    Use it as a context manager (``with AltPay(...) as client:``) to close the underlying
+    HTTP connection pool automatically.
+
+    Args:
+        credentials: Your merchant credentials.
+        base_url: API root (default ``https://api.altpay.money``). Override for staging.
+        timeout: Per-request timeout in seconds (default 30).
+        max_retries: How many times to retry a request that failed transiently - a network
+            error, a 5xx, or a 429. Retries use exponential backoff and honor ``Retry-After``.
+            Set to 0 to disable. Only idempotent reads and create-with-your-own-uuid are
+            safe to retry, which is the whole public surface.
+        http_client: Bring your own configured :class:`httpx.Client` (proxies, custom TLS,
+            etc.). If given, ``base_url``/``timeout`` on the httpx client are used and this
+            class will not close it for you.
+
+    API reference: https://docs.altpay.money/docs
+    """
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._credentials = credentials
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+        #: Invoice and static-wallet operations.
+        self.invoices = Invoices(self.call)
+        #: Payout (withdrawal) operations.
+        self.withdrawals = Withdrawals(self.call)
+        #: Account identity, balance and statistics.
+        self.account = AccountResource(self.call)
+
+    def __enter__(self) -> "AltPay":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool (unless you supplied your own client)."""
+        if self._owns_client:
+            self._http.close()
+
+    def call(self, call: APICall[T]) -> T:
+        """Execute a described :class:`~altpay.methods.base.APICall` and return its typed result.
+
+        You normally call resource methods (``client.invoices.create(...)``) which return an
+        ``APICall`` and pass it here implicitly; use :meth:`call` directly only for advanced
+        or custom calls.
+        """
+        request = prepare(
+            credentials=self._credentials,
+            base_url=self._base_url,
+            path=call.path,
+            payload=call.payload,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    request.method, request.url, headers=request.headers, content=request.content
+                )
+            except httpx.HTTPError as exc:
+                if attempt >= self._max_retries:
+                    raise AltPayTransportError(str(exc)) from exc
+                time.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+
+            try:
+                result = parse_response(
+                    status_code=response.status_code,
+                    body_text=response.text,
+                    headers=response.headers,
+                )
+            except (RateLimitError, ServerError) as exc:
+                if attempt >= self._max_retries:
+                    raise
+                time.sleep(_retry_delay(exc, attempt))
+                attempt += 1
+                continue
+            return call.parse(result)
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff: 0.5s, 1s, 2s, ... capped at 8s."""
+    return min(0.5 * (2 ** attempt), 8.0)
+
+
+def _retry_delay(exc: Any, attempt: int) -> float:
+    """Honor a 429's Retry-After when present, else fall back to exponential backoff."""
+    retry_after = getattr(exc, "retry_after", None)
+    if retry_after is not None:
+        return float(retry_after)
+    return _backoff(attempt)

altpay/credentials.py

@@ -0,0 +1,40 @@
+"""Merchant credentials.
+
+A small immutable holder for the four secrets the SDK needs. Grouping them keeps the client
+constructors clean and makes it obvious which value plays which role - a frequent source of
+``invalid_signature`` errors is swapping the public ``api_key`` with the secret ``api_secret``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    """The credentials issued for one API key in your dashboard.
+
+    Args:
+        merchant_id: Your merchant UUID. Sent in the clear as ``X-Merchant-Id``.
+        api_key: The public key identifier (``vc_live_...``). Sent in the clear as
+            ``X-Api-Key``; the server looks it up by hash.
+        api_secret: The signing secret. Never transmitted - it is the HMAC key for every
+            request signature. Keep it server-side only.
+        webhook_secret: The secret used to sign webhooks AltPay sends you. Optional here;
+            required only if you verify webhooks with this SDK. Distinct from ``api_secret``.
+
+    All four are shown once at key creation and cannot be retrieved later - store them in
+    your secret manager. See https://docs.altpay.money/docs/authentication
+    """
+
+    merchant_id: str
+    api_key: str
+    api_secret: str
+    webhook_secret: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.merchant_id or not self.api_key or not self.api_secret:
+            raise ValueError(
+                "merchant_id, api_key and api_secret are all required. "
+                "See https://docs.altpay.money/docs/authentication"
+            )

altpay/enums.py

@@ -0,0 +1,94 @@
+"""Enumerations used across the public API.
+
+These mirror the server's vocabulary exactly. Each is a ``str`` enum, so a member compares
+equal to its wire value (``PaymentStatus.PAYED == "PAYED"``) and serializes transparently -
+you can pass either a member or the raw string anywhere the SDK accepts one.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class PaymentStatus(str, Enum):
+    """Lifecycle state of an invoice.
+
+    * ``CREATED`` - issued, awaiting payment.
+    * ``INCOMPLETE`` - underpaid (received less than due); still open.
+    * ``PAYED`` - fully paid and confirmed (final). The webhook fires on this transition.
+    * ``EXPIRED`` - the lifetime window elapsed before payment (final).
+    * ``FAILED`` - the payment failed or was rejected (final).
+
+    ``CREATED``/``INCOMPLETE`` are non-final; the other three are final
+    (see :attr:`is_final`).
+    """
+
+    CREATED = "CREATED"
+    PAYED = "PAYED"
+    INCOMPLETE = "INCOMPLETE"
+    EXPIRED = "EXPIRED"
+    FAILED = "FAILED"
+
+    @property
+    def is_final(self) -> bool:
+        """Whether no further status change is possible (PAYED, EXPIRED or FAILED)."""
+        return self in (PaymentStatus.PAYED, PaymentStatus.EXPIRED, PaymentStatus.FAILED)
+
+
+class PaymentMethod(str, Enum):
+    """A payment method the payer can settle with.
+
+    On-chain methods deliver to a generated deposit address; ``LOLZTEAM`` and ``CRYPTOBOT``
+    are off-chain providers that redirect the payer to a hosted page. ``USDT_*`` names encode
+    the network the stablecoin settles on (e.g. ``USDT_TRC20`` is USDT on TRON).
+    """
+
+    TRX = "TRX"
+    BTC = "BTC"
+    ETH = "ETH"
+    LTC = "LTC"
+    BNB = "BNB"
+    TON = "TON"
+    SOLANA = "SOLANA"
+    USDT_TRC20 = "USDT_TRC20"
+    USDT_ETH = "USDT_ETH"
+    USDT_BSC = "USDT_BSC"
+    USDT_TON = "USDT_TON"
+    USDT_SOLANA = "USDT_SOLANA"
+    LOLZTEAM = "LOLZTEAM"
+    CRYPTOBOT = "CRYPTOBOT"
+
+
+class FiatCurrency(str, Enum):
+    """A fiat currency an invoice can be denominated in."""
+
+    RUB = "RUB"
+    USD = "USD"
+    EUR = "EUR"
+
+
+class MerchantStatus(str, Enum):
+    """Account status of a merchant.
+
+    Only ``APPROVED`` merchants can create invoices; the others block payment creation
+    (``PENDING_REVIEW`` until onboarding completes, ``SUSPENDED``/``ARCHIVED``/``REJECTED``
+    permanently or until support intervenes).
+    """
+
+    PENDING_REVIEW = "PENDING_REVIEW"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    ARCHIVED = "ARCHIVED"
+    SUSPENDED = "SUSPENDED"
+
+
+class WithdrawalStatus(str, Enum):
+    """Lifecycle state of a payout request.
+
+    A new request is ``PENDING`` review; an operator then ``APPROVED`` it (funds are paid
+    out) or ``REJECTED`` it (the reserved amount is credited back to your balance).
+    """
+
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"