qvapaykit 0.1.0__py3-none-any.whl

qvapaykit/__init__.py

@@ -0,0 +1,91 @@
+"""qvapay: SDK Python para la API de QvaPay.
+
+Documentación de la API: https://www.qvapay.com/docs
+
+Quickstart (modo App, credenciales en ``QVAPAY_APP_ID``/``QVAPAY_APP_SECRET``)::
+
+    from qvapaykit import QvaPayClient
+
+    with QvaPayClient.from_env() as client:
+        invoice = client.create_invoice(
+            amount="25.00",
+            description="Compra en Mi Tienda",
+            remote_id="orden-1234",
+        )
+        print(invoice.url)  # enlace de pago para compartir
+"""
+
+from qvapaykit.client import AsyncQvaPayClient, QvaPayClient
+from qvapaykit.config import QvaPaySettings
+from qvapaykit.exceptions import (
+    ATTESTATION_CODES,
+    QvaPayAttestationRequiredError,
+    QvaPayAuthError,
+    QvaPayDuplicateRequestError,
+    QvaPayError,
+    QvaPayForbiddenError,
+    QvaPayKYCRequiredError,
+    QvaPayNetworkError,
+    QvaPayNotFoundError,
+    QvaPayRateLimitError,
+    QvaPayServerError,
+    QvaPayValidationError,
+    WebhookMismatchError,
+    WebhookParseError,
+)
+from qvapaykit.models import (
+    AppInfo,
+    Balance,
+    Invoice,
+    InvoiceRequest,
+    Payer,
+    Product,
+    Transaction,
+    TransactionStatus,
+)
+from qvapaykit.webhooks import (
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+    WebhookEvent,
+    areconcile_webhook,
+    assert_matches,
+    parse_webhook,
+    reconcile_webhook,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ATTESTATION_CODES",
+    "AppInfo",
+    "AsyncQvaPayClient",
+    "Balance",
+    "IdempotencyStore",
+    "InMemoryIdempotencyStore",
+    "Invoice",
+    "InvoiceRequest",
+    "Payer",
+    "Product",
+    "QvaPayAttestationRequiredError",
+    "QvaPayAuthError",
+    "QvaPayClient",
+    "QvaPayDuplicateRequestError",
+    "QvaPayError",
+    "QvaPayForbiddenError",
+    "QvaPayKYCRequiredError",
+    "QvaPayNetworkError",
+    "QvaPayNotFoundError",
+    "QvaPayRateLimitError",
+    "QvaPayServerError",
+    "QvaPaySettings",
+    "QvaPayValidationError",
+    "Transaction",
+    "TransactionStatus",
+    "WebhookEvent",
+    "WebhookMismatchError",
+    "WebhookParseError",
+    "areconcile_webhook",
+    "assert_matches",
+    "parse_webhook",
+    "reconcile_webhook",
+]

qvapaykit/client.py

@@ -0,0 +1,310 @@
+"""Clientes del SDK: ``QvaPayClient`` (sync) y ``AsyncQvaPayClient`` (async).
+
+Modo App (server-to-server): headers ``app-id`` + ``app-secret``, endpoints
+``/v2/*``. Las credenciales se pasan explícitas o se leen del entorno
+(``QVAPAY_APP_ID`` / ``QVAPAY_APP_SECRET``).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+
+import httpx
+
+from qvapaykit.config import QvaPaySettings
+from qvapaykit.exceptions import QvaPayValidationError
+from qvapaykit.http import AsyncQvaPayTransport, QvaPayTransport, RateLimiter
+from qvapaykit.models import (
+    AppInfo,
+    Balance,
+    Invoice,
+    InvoiceRequest,
+    Product,
+    Transaction,
+)
+
+_DEFAULT_BASE_URL = "https://api.qvapay.com"
+
+
+def _credentials(
+    app_id: str | None,
+    app_secret: str | None,
+) -> tuple[str, str]:
+    if app_id is None or app_secret is None:
+        # Los campos llegan por variables de entorno (QVAPAY_APP_ID/SECRET);
+        # mypy no puede verlos, pero pydantic-settings los exige en runtime.
+        settings = QvaPaySettings()
+        app_id = app_id if app_id is not None else settings.app_id
+        app_secret = app_secret if app_secret is not None else settings.app_secret
+    return app_id, app_secret
+
+
+def _validate_page_params(page: int, take: int) -> None:
+    if page < 1:
+        msg = "page debe ser >= 1"
+        raise QvaPayValidationError(msg)
+    if not 1 <= take <= 100:
+        msg = "take debe estar entre 1 y 100"
+        raise QvaPayValidationError(msg)
+
+
+def _build_invoice_payload(
+    *,
+    amount: Decimal | int | str,
+    description: str,
+    remote_id: str,
+    webhook: str | None,
+    products: list[Product] | None,
+    expire_at: datetime | None,
+) -> dict[str, object]:
+    request = InvoiceRequest.model_validate(
+        {
+            "amount": amount,
+            "description": description,
+            "remote_id": remote_id,
+            "webhook": webhook,
+            "products": products,
+            "expire_at": expire_at,
+        }
+    )
+    return request.model_dump(mode="json", exclude_none=True)
+
+
+class QvaPayClient:
+    """Cliente síncrono del modo App de QvaPay.
+
+    Ejemplo::
+
+        from qvapaykit import QvaPayClient
+        client = QvaPayClient.from_env()
+        invoice = client.create_invoice(
+            amount="25.00", description="Café", remote_id="orden-1234",
+        )
+        print(invoice.url)
+    """
+
+    def __init__(
+        self,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        transport: httpx.BaseTransport | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        resolved_id, resolved_secret = _credentials(app_id, app_secret)
+        self._transport = QvaPayTransport(
+            resolved_id,
+            resolved_secret,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+            rate_limiter=rate_limiter,
+        )
+
+    @classmethod
+    def from_env(cls) -> QvaPayClient:
+        settings = QvaPaySettings()
+        return cls(
+            settings.app_id,
+            settings.app_secret,
+            base_url=settings.base_url,
+            timeout=settings.timeout,
+            max_retries=settings.max_retries,
+        )
+
+    def info(self) -> AppInfo:
+        """``POST /v2/info``: datos de la app; útil para verificar credenciales."""
+        response = self._transport.post("/v2/info", {})
+        return AppInfo.model_validate(response.json())
+
+    def balance(self) -> Decimal:
+        """``POST /v2/balance``: balance disponible en USD."""
+        response = self._transport.post("/v2/balance", {})
+        return Balance.model_validate(response.json()).balance
+
+    def create_invoice(
+        self,
+        *,
+        amount: Decimal | int | str,
+        description: str,
+        remote_id: str,
+        webhook: str | None = None,
+        products: list[Product] | None = None,
+        expire_at: datetime | None = None,
+    ) -> Invoice:
+        """``POST /v2/create_invoice``: crea una factura y devuelve su enlace de pago.
+
+        ``remote_id`` es la clave de idempotencia: usa el ID de tu orden.
+        Repetirlo genera ``QvaPayDuplicateRequestError``.
+        """
+        payload = _build_invoice_payload(
+            amount=amount,
+            description=description,
+            remote_id=remote_id,
+            webhook=webhook,
+            products=products,
+            expire_at=expire_at,
+        )
+        response = self._transport.post("/v2/create_invoice", payload, bucket="charge")
+        return Invoice.model_validate(response.json())
+
+    def transactions(self, *, page: int = 1, take: int = 30) -> list[Transaction]:
+        """``POST /v2/transactions``: listado paginado de transacciones de la app."""
+        _validate_page_params(page, take)
+        response = self._transport.post("/v2/transactions", {"page": page, "take": take})
+        data = response.json()
+        items = data.get("transactions", []) if isinstance(data, dict) else []
+        return [Transaction.model_validate(item) for item in items]
+
+    def transaction_detail(self, transaction_uuid: str) -> Transaction:
+        """``POST /v2/transactions/{uuid}``: detalle con datos del pagador si fue pagada."""
+        if not transaction_uuid:
+            msg = "transaction_uuid es obligatorio"
+            raise QvaPayValidationError(msg)
+        response = self._transport.post(f"/v2/transactions/{transaction_uuid}", {})
+        data = response.json()
+        tx_data = data.get("transaction", data) if isinstance(data, dict) else data
+        return Transaction.model_validate(tx_data)
+
+    def find_transaction_by_remote_id(
+        self,
+        remote_id: str,
+        *,
+        max_pages: int = 10,
+    ) -> Transaction | None:
+        """Busca en el listado paginado la primera transacción con ese ``remote_id``."""
+        for page in range(1, max_pages + 1):
+            page_items = self.transactions(page=page, take=100)
+            for transaction in page_items:
+                if transaction.remote_id == remote_id:
+                    return transaction
+            if len(page_items) < 100:
+                break
+        return None
+
+    def health_check(self) -> tuple[AppInfo, Decimal]:
+        """Verificación de salud para despliegues: credenciales + balance responden."""
+        return self.info(), self.balance()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> QvaPayClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncQvaPayClient:
+    """Cliente asíncrono del modo App (httpx.AsyncClient)."""
+
+    def __init__(
+        self,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        transport: httpx.AsyncBaseTransport | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        resolved_id, resolved_secret = _credentials(app_id, app_secret)
+        self._transport = AsyncQvaPayTransport(
+            resolved_id,
+            resolved_secret,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+            rate_limiter=rate_limiter,
+        )
+
+    @classmethod
+    def from_env(cls) -> AsyncQvaPayClient:
+        settings = QvaPaySettings()
+        return cls(
+            settings.app_id,
+            settings.app_secret,
+            base_url=settings.base_url,
+            timeout=settings.timeout,
+            max_retries=settings.max_retries,
+        )
+
+    async def info(self) -> AppInfo:
+        response = await self._transport.post("/v2/info", {})
+        return AppInfo.model_validate(response.json())
+
+    async def balance(self) -> Decimal:
+        response = await self._transport.post("/v2/balance", {})
+        return Balance.model_validate(response.json()).balance
+
+    async def create_invoice(
+        self,
+        *,
+        amount: Decimal | int | str,
+        description: str,
+        remote_id: str,
+        webhook: str | None = None,
+        products: list[Product] | None = None,
+        expire_at: datetime | None = None,
+    ) -> Invoice:
+        payload = _build_invoice_payload(
+            amount=amount,
+            description=description,
+            remote_id=remote_id,
+            webhook=webhook,
+            products=products,
+            expire_at=expire_at,
+        )
+        response = await self._transport.post("/v2/create_invoice", payload, bucket="charge")
+        return Invoice.model_validate(response.json())
+
+    async def transactions(self, *, page: int = 1, take: int = 30) -> list[Transaction]:
+        _validate_page_params(page, take)
+        response = await self._transport.post("/v2/transactions", {"page": page, "take": take})
+        data = response.json()
+        items = data.get("transactions", []) if isinstance(data, dict) else []
+        return [Transaction.model_validate(item) for item in items]
+
+    async def transaction_detail(self, transaction_uuid: str) -> Transaction:
+        if not transaction_uuid:
+            msg = "transaction_uuid es obligatorio"
+            raise QvaPayValidationError(msg)
+        response = await self._transport.post(f"/v2/transactions/{transaction_uuid}", {})
+        data = response.json()
+        tx_data = data.get("transaction", data) if isinstance(data, dict) else data
+        return Transaction.model_validate(tx_data)
+
+    async def find_transaction_by_remote_id(
+        self,
+        remote_id: str,
+        *,
+        max_pages: int = 10,
+    ) -> Transaction | None:
+        for page in range(1, max_pages + 1):
+            page_items = await self.transactions(page=page, take=100)
+            for transaction in page_items:
+                if transaction.remote_id == remote_id:
+                    return transaction
+            if len(page_items) < 100:
+                break
+        return None
+
+    async def health_check(self) -> tuple[AppInfo, Decimal]:
+        return await self.info(), await self.balance()
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncQvaPayClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

qvapaykit/config.py

@@ -0,0 +1,20 @@
+"""Configuración del SDK por entorno (prefijo ``QVAPAY_`` o archivo .env)."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class QvaPaySettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="QVAPAY_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_id: str
+    app_secret: str
+    base_url: str = "https://api.qvapay.com"
+    timeout: float = 10.0
+    max_retries: int = 3

qvapaykit/exceptions.py

@@ -0,0 +1,111 @@
+"""Jerarquía de excepciones del SDK qvapay.
+
+La API de QvaPay documenta códigos estables (``KYC_REQUIRED``,
+``DUPLICATE_REQUEST``, etc.); este módulo los traduce a excepciones
+específicas para programar contra el tipo, no contra el texto del error.
+"""
+
+from __future__ import annotations
+
+ATTESTATION_CODES: frozenset[str] = frozenset(
+    {
+        "US_PERSON_ATTESTATION_REQUIRED",
+        "W1_ATTESTATION_REQUIRED",
+        "CACR_ATTESTATION_REQUIRED",
+    }
+)
+
+
+class QvaPayError(Exception):
+    """Base de todas las excepciones que genera este SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"{self.message} (code={self.code})"
+        return self.message
+
+
+class QvaPayNetworkError(QvaPayError):
+    """Fallo de transporte: timeout, DNS, conexión caída, etc."""
+
+
+class QvaPayAuthError(QvaPayError):
+    """401: credenciales inválidas o token expirado."""
+
+
+class QvaPayValidationError(QvaPayError):
+    """400 genérico: request inválido, datos faltantes o validación fallida."""
+
+
+class QvaPayDuplicateRequestError(QvaPayValidationError):
+    """400 con code=DUPLICATE_REQUEST: remote_id repetido. Clave de idempotencia."""
+
+
+class QvaPayAttestationRequiredError(QvaPayValidationError):
+    """400 con code de atestación: falta la autocertificación del cliente.
+
+    Se trata como "falta el formulario": la UI debe mostrar las declaraciones
+    al usuario; nunca autocumplimentarlas desde el código.
+    """
+
+
+class QvaPayKYCRequiredError(QvaPayError):
+    """403 con code=KYC_REQUIRED: la cuenta no completó la verificación de identidad."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        kyc_url: str | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, code=code)
+        self.kyc_url = kyc_url
+
+
+class QvaPayForbiddenError(QvaPayError):
+    """403 sin código específico: sin permisos para la operación."""
+
+
+class QvaPayNotFoundError(QvaPayError):
+    """404: recurso no encontrado o no pertenece a la app."""
+
+
+class QvaPayRateLimitError(QvaPayError):
+    """429: rate limit excedido; reintentar con backoff."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, code=code)
+        self.retry_after = retry_after
+
+
+class QvaPayServerError(QvaPayError):
+    """5xx: error interno del servidor de QvaPay."""
+
+
+class WebhookParseError(QvaPayError):
+    """El payload del webhook no es JSON válido o no contiene transaction_uuid."""
+
+
+class WebhookMismatchError(QvaPayError):
+    """La transacción reconciliada no coincide con lo esperado (posible evento alterado)."""

qvapaykit/http.py

@@ -0,0 +1,250 @@
+"""Transporte HTTP hacia QvaPay: rate-limit, reintentos y mapeo de errores.
+
+Límites documentados que este módulo respeta por diseño:
+- Endpoints de cobro: 5 requests cada 20 segundos por app.
+- Endpoints generales: 3 requests cada 5 segundos.
+- 429/5xx/fallo de red: backoff exponencial con jitter (máx. configurable).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import threading
+import time
+from typing import Any
+
+import httpx
+
+from qvapaykit.exceptions import (
+    ATTESTATION_CODES,
+    QvaPayAttestationRequiredError,
+    QvaPayAuthError,
+    QvaPayDuplicateRequestError,
+    QvaPayError,
+    QvaPayForbiddenError,
+    QvaPayKYCRequiredError,
+    QvaPayNetworkError,
+    QvaPayNotFoundError,
+    QvaPayRateLimitError,
+    QvaPayServerError,
+    QvaPayValidationError,
+)
+
+_MAX_BACKOFF_SECONDS = 30.0
+
+
+class TokenBucket:
+    """Cubo de tokens thread-safe; el transporte async lo consulta y espera con asyncio.sleep."""
+
+    def __init__(self, rate_per_second: float, capacity: int) -> None:
+        self.rate_per_second = rate_per_second
+        self.capacity = capacity
+        self._tokens = float(capacity)
+        self._updated = time.monotonic()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> float:
+        """Consume un token y devuelve segundos de espera (0.0 si había disponible)."""
+        with self._lock:
+            now = time.monotonic()
+            elapsed = now - self._updated
+            self._tokens = min(self.capacity, self._tokens + elapsed * self.rate_per_second)
+            self._updated = now
+            if self._tokens >= 1.0:
+                self._tokens -= 1.0
+                return 0.0
+            return (1.0 - self._tokens) / self.rate_per_second
+
+
+class RateLimiter:
+    """Buckets según los límites documentados por QvaPay."""
+
+    def __init__(self) -> None:
+        self.charge = TokenBucket(rate_per_second=5 / 20, capacity=5)
+        self.general = TokenBucket(rate_per_second=3 / 5, capacity=3)
+
+    def wait(self, bucket_name: str) -> float:
+        bucket = self.charge if bucket_name == "charge" else self.general
+        return bucket.acquire()
+
+
+def _is_retryable(response: httpx.Response) -> bool:
+    return response.status_code == 429 or response.status_code >= 500
+
+
+def _retry_delay(response: httpx.Response | None, attempt: int) -> float:
+    if response is not None:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after is not None:
+            try:
+                return max(0.0, float(retry_after))
+            except ValueError:
+                pass
+    backoff = 0.5 * (2**attempt)
+    jittered = backoff * (1.0 + random.uniform(0.0, 0.25))
+    return min(_MAX_BACKOFF_SECONDS, jittered)
+
+
+def _error_dict(response: httpx.Response) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def raise_api_error(response: httpx.Response) -> None:
+    """Traduce una respuesta no-2xx a la excepción específica del SDK.
+
+    Se programa contra el ``code`` estable de la API, nunca contra el texto
+    del campo ``error`` (que puede cambiar).
+    """
+    payload = _error_dict(response)
+    raw_message = payload.get("error", response.text or "Error de QvaPay")
+    message = raw_message if isinstance(raw_message, str) else str(raw_message)
+    code = payload.get("code")
+    status = response.status_code
+
+    if status == 401:
+        raise QvaPayAuthError(message, status_code=status, code=code)
+    if status == 403 and code == "KYC_REQUIRED":
+        kyc_url = payload.get("kyc_url")
+        raise QvaPayKYCRequiredError(
+            message,
+            status_code=status,
+            code=code,
+            kyc_url=kyc_url if isinstance(kyc_url, str) else None,
+        )
+    if status == 403:
+        raise QvaPayForbiddenError(message, status_code=status, code=code)
+    if status == 404:
+        raise QvaPayNotFoundError(message, status_code=status, code=code)
+    if status == 429:
+        retry_after = response.headers.get("Retry-After")
+        parsed_after: float | None = None
+        if retry_after is not None:
+            try:
+                parsed_after = max(0.0, float(retry_after))
+            except ValueError:
+                parsed_after = None
+        raise QvaPayRateLimitError(message, status_code=status, code=code, retry_after=parsed_after)
+    if status == 400 and code == "DUPLICATE_REQUEST":
+        raise QvaPayDuplicateRequestError(message, status_code=status, code=code)
+    if status == 400 and isinstance(code, str) and code in ATTESTATION_CODES:
+        raise QvaPayAttestationRequiredError(message, status_code=status, code=code)
+    if status == 400:
+        raise QvaPayValidationError(message, status_code=status, code=code)
+    if status >= 500:
+        raise QvaPayServerError(message, status_code=status, code=code)
+    raise QvaPayError(message, status_code=status, code=code)
+
+
+class QvaPayTransport:
+    """Transporte síncrono (httpx.Client)."""
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        *,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        transport: httpx.BaseTransport | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        headers = {"app-id": app_id, "app-secret": app_secret}
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+        self._max_retries = max_retries
+        self._limiter = rate_limiter if rate_limiter is not None else RateLimiter()
+
+    def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        *,
+        bucket: str = "general",
+    ) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            can_retry = attempt < self._max_retries
+            wait = self._limiter.wait(bucket)
+            if wait > 0:
+                time.sleep(wait)
+            try:
+                response = self._client.post(path, json=payload)
+            except httpx.HTTPError as exc:
+                if not can_retry:
+                    raise QvaPayNetworkError(f"fallo de red: {exc}") from exc
+                time.sleep(_retry_delay(None, attempt))
+                continue
+            if _is_retryable(response) and can_retry:
+                time.sleep(_retry_delay(response, attempt))
+                continue
+            if not response.is_success:
+                raise_api_error(response)
+            return response
+        raise QvaPayNetworkError("reintentos agotados antes de obtener respuesta")
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncQvaPayTransport:
+    """Transporte asíncrono (httpx.AsyncClient)."""
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        *,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        transport: httpx.AsyncBaseTransport | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        headers = {"app-id": app_id, "app-secret": app_secret}
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+        self._max_retries = max_retries
+        self._limiter = rate_limiter if rate_limiter is not None else RateLimiter()
+
+    async def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        *,
+        bucket: str = "general",
+    ) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            can_retry = attempt < self._max_retries
+            wait = self._limiter.wait(bucket)
+            if wait > 0:
+                await asyncio.sleep(wait)
+            try:
+                response = await self._client.post(path, json=payload)
+            except httpx.HTTPError as exc:
+                if not can_retry:
+                    raise QvaPayNetworkError(f"fallo de red: {exc}") from exc
+                await asyncio.sleep(_retry_delay(None, attempt))
+                continue
+            if _is_retryable(response) and can_retry:
+                await asyncio.sleep(_retry_delay(response, attempt))
+                continue
+            if not response.is_success:
+                raise_api_error(response)
+            return response
+        raise QvaPayNetworkError("reintentos agotados antes de obtener respuesta")
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

qvapaykit/models.py

@@ -0,0 +1,170 @@
+"""Modelos de dominio del SDK (pydantic v2).
+
+Reglas de dinero: TODO monto es ``Decimal``. Se rechaza ``float`` de forma
+explícita para evitar errores de precisión; usa ``Decimal("25.00")``, ``str``
+o ``int``. La conversión a número JSON ocurre únicamente en la capa HTTP,
+en el último límite antes del cable.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
+
+def _reject_float(value: object) -> object:
+    # float para dinero pierde precisión silenciosamente; el error explícito
+    # educa al integrador desde el primer uso. ValueError (no TypeError) para
+    # que pydantic lo convierta en ValidationError.
+    if isinstance(value, float):
+        msg = "usa Decimal/str/int para montos, nunca float (p. ej. Decimal('25.00'))"
+        raise ValueError(msg)
+    return value
+
+
+def _max_two_decimals(value: Decimal) -> Decimal:
+    exponent = value.as_tuple().exponent
+    # El exponente es int salvo valores especiales (NaN/Inf) que no llegan aquí,
+    # pero mypy exige el guard antes del unary -.
+    if isinstance(exponent, int) and -exponent > 2:
+        msg = "el monto admite como máximo 2 decimales"
+        raise ValueError(msg)
+    return value
+
+
+class TransactionStatus(StrEnum):
+    PENDING = "pending"
+    PAID = "paid"
+    CANCELLED = "cancelled"
+
+
+class _QvaPayModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class Product(_QvaPayModel):
+    name: str = Field(min_length=1, max_length=255)
+    price: Decimal = Field(gt=0)
+    quantity: int = Field(default=1, ge=1)
+
+    # Sin rechazo de float aquí: este modelo TAMBIÉN parsea respuestas de la
+    # API, donde los montos llegan como números JSON (float en json.loads).
+    # El guardrail de "nunca float" vive en InvoiceRequest.amount (entrada
+    # del integrador); pydantic convierte el float del cable a Decimal.
+    _decimals = field_validator("price")(_max_two_decimals)
+
+    @field_serializer("price")
+    def _serialize_price(self, value: Decimal) -> float:
+        # Único punto donde Decimal se convierte a float: el JSON de la API
+        # exige número y montos <= 100000.00 con 2 decimales caben exactos en float64.
+        return float(value)
+
+
+class InvoiceRequest(_QvaPayModel):
+    """Payload de ``POST /v2/create_invoice``.
+
+    ``remote_id`` es la clave de idempotencia: identificador externo de tu
+    sistema (p. ej. el ID de la orden). Reutilizarlo dispara
+    ``QvaPayDuplicateRequestError``.
+    """
+
+    amount: Decimal = Field(gt=0, le=100000)
+    description: str = Field(min_length=1, max_length=255)
+    remote_id: str = Field(min_length=1, max_length=255)
+    webhook: str | None = None
+    products: list[Product] | None = None
+    expire_at: datetime | None = None
+
+    _reject = field_validator("amount", mode="before")(_reject_float)
+    _decimals = field_validator("amount")(_max_two_decimals)
+
+    @field_serializer("amount")
+    def _serialize_amount(self, value: Decimal) -> float:
+        # Ídem Product.price: float solo en el cable, Decimal en todo el dominio.
+        return float(value)
+
+    @field_validator("webhook")
+    @classmethod
+    def _webhook_format(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if not value.startswith(("http://", "https://")):
+            msg = "webhook debe ser una URL http(s) válida"
+            raise ValueError(msg)
+        return value
+
+    @field_validator("expire_at")
+    @classmethod
+    def _expire_in_future(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=UTC)
+        if value <= datetime.now(UTC):
+            msg = "expire_at debe ser una fecha futura"
+            raise ValueError(msg)
+        return value
+
+
+class Invoice(_QvaPayModel):
+    """Factura creada; ``url`` es el enlace de pago para compartir."""
+
+    app_id: str
+    amount: Decimal
+    description: str
+    remote_id: str
+    transaction_uuid: str
+    expire_at: datetime | None = None
+    url: str
+
+
+class AppInfo(_QvaPayModel):
+    uuid: str
+    name: str
+    url: str | None = None
+    desc: str | None = None
+    callback: str | None = None
+    success_url: str | None = None
+    cancel_url: str | None = None
+    logo: str | None = None
+    active: bool | None = None
+    enabled: bool | None = None
+    card: bool | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    app_photo_url: str | None = None
+
+
+class Balance(_QvaPayModel):
+    balance: Decimal
+
+
+class Payer(_QvaPayModel):
+    uuid: str
+    name: str | None = None
+    username: str | None = None
+    lastname: str | None = None
+    image: str | None = None
+    vip: bool | None = None
+    kyc: str | None = None
+    golden_check: bool | None = None
+
+
+class Transaction(_QvaPayModel):
+    uuid: str
+    amount: Decimal
+    description: str
+    remote_id: str
+    status: TransactionStatus
+    products: list[Product] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    # La API devuelve "PaidBy" (PascalCase); el alias permite el nombre pythonico.
+    payer: Payer | None = Field(default=None, alias="PaidBy")
+
+    @property
+    def is_paid(self) -> bool:
+        return self.status == TransactionStatus.PAID

qvapaykit/webhooks.py

@@ -0,0 +1,112 @@
+"""Capa de webhooks: parseo del evento, reconciliación con la API e idempotencia.
+
+Principio rector: el POST que llega al endpoint es una señal NO confiable.
+Solo indica QUÉ transacción verificar; la confirmación real siempre sale de
+``POST /v2/transactions/{uuid}`` con las credenciales del comercio.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from decimal import Decimal
+from typing import Any, Protocol
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, ValidationError
+
+from qvapaykit.client import AsyncQvaPayClient, QvaPayClient
+from qvapaykit.exceptions import WebhookMismatchError, WebhookParseError
+from qvapaykit.models import Transaction
+
+
+class WebhookEvent(BaseModel):
+    """Campos mínimos que usamos del webhook; el resto se ignora a propósito.
+
+    La API puede enviar el identificador como ``uuid`` o ``transaction_uuid``;
+    aceptamos ambos. Monto y demás datos no se extraen porque la reconciliación
+    con la API es la fuente de verdad.
+    """
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    transaction_uuid: str = Field(
+        min_length=1,
+        validation_alias=AliasChoices("transaction_uuid", "uuid"),
+    )
+    status: str | None = None
+    description: str | None = None
+    remote_id: str | None = None
+
+
+def parse_webhook(body: str | bytes | dict[str, Any]) -> WebhookEvent:
+    """Convierte el payload crudo en ``WebhookEvent``; falla con ``WebhookParseError``."""
+    data: Any = body
+    if isinstance(body, (str, bytes)):
+        try:
+            data = json.loads(body)
+        except (ValueError, UnicodeDecodeError) as exc:
+            msg = "payload del webhook no es JSON válido"
+            raise WebhookParseError(msg) from exc
+    if not isinstance(data, dict):
+        msg = "payload del webhook no es un objeto JSON"
+        raise WebhookParseError(msg)
+    try:
+        return WebhookEvent.model_validate(data)
+    except ValidationError as exc:
+        msg = f"payload del webhook inválido: {exc.error_count()} error(es) de validación"
+        raise WebhookParseError(msg) from exc
+
+
+def reconcile_webhook(client: QvaPayClient, event: WebhookEvent) -> Transaction:
+    """Verifica el evento contra la API (sync). Marca ``transaction.is_paid``."""
+    return client.transaction_detail(event.transaction_uuid)
+
+
+async def areconcile_webhook(client: AsyncQvaPayClient, event: WebhookEvent) -> Transaction:
+    """Verifica el evento contra la API (async). Marca ``transaction.is_paid``."""
+    return await client.transaction_detail(event.transaction_uuid)
+
+
+def assert_matches(
+    transaction: Transaction,
+    *,
+    remote_id: str | None = None,
+    amount: Decimal | None = None,
+) -> None:
+    """Defensa anti-manipulación: la transacción debe ser la esperada por el integrador.
+
+    Si el POST entrante fue alterado (p. ej. un uuid ajeno), la reconciliación
+    devolverá una transacción cuyo ``remote_id``/``amount`` no coincide y esta
+    función lo detecta.
+    """
+    if remote_id is not None and transaction.remote_id != remote_id:
+        msg = f"remote_id no coincide: esperado {remote_id!r}, recibido {transaction.remote_id!r}"
+        raise WebhookMismatchError(msg)
+    if amount is not None and transaction.amount != amount:
+        msg = f"monto no coincide: esperado {amount!r}, recibido {transaction.amount!r}"
+        raise WebhookMismatchError(msg)
+
+
+class IdempotencyStore(Protocol):
+    """Contrato para deduplicar eventos: devuelve False si ya fue procesado."""
+
+    def mark_processed(self, key: str) -> bool: ...
+
+
+class InMemoryIdempotencyStore:
+    """Implementación en memoria para tests y prototipos.
+
+    En producción usa una restricción UNIQUE sobre ``transaction_uuid`` en la
+    base de datos (ver apps/links): es la única garante bajo concurrencia.
+    """
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+        self._lock = threading.Lock()
+
+    def mark_processed(self, key: str) -> bool:
+        with self._lock:
+            if key in self._seen:
+                return False
+            self._seen.add(key)
+            return True

qvapaykit-0.1.0.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: qvapaykit
+Version: 0.1.0
+Summary: QvaPayKit: SDK Python para integrar pagos con QvaPay — facturas, webhooks verificados, dinero en Decimal
+Project-URL: Homepage, https://www.qvapay.com/docs
+Author: RolandoJV
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# QvaPayKit
+
+**SDK Python para integrar pagos con [QvaPay](https://www.qvapay.com/docs)**: facturas, enlaces de pago, webhooks verificados contra la API y transacciones — con dinero en `Decimal` (nunca `float`) e idempotencia garantizada por base de datos.
+
+Diferenciado del wrapper genérico comunitario: QvaPayKit está enfocado en que tu app **cobre de forma segura**, no en envolver toda la API.
+
+> Documentación completa al finalizar el monorepo (Fase 6 del roadmap).

qvapaykit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+qvapaykit/__init__.py,sha256=49ZDceAyEOxUplDzX7NXKCUB8NvnIidEiuPjtkHR3ww,2141
+qvapaykit/client.py,sha256=B4fOXEjcC4hN_uz2h8dwZwgDJI6DHxCzYl3xC422fsY,10538
+qvapaykit/config.py,sha256=HTiLtguKjT1_u8VweqHvD-owKkY21EbyXWnw-pSRg0A,509
+qvapaykit/exceptions.py,sha256=BiAnlimx9mReEshj5LrKsuYry80sEP-8YONMfVeV5ro,3153
+qvapaykit/http.py,sha256=xgXkdVe2nagOpYQELXkGHihPur2TxdKHVWFd6k9xzss,8592
+qvapaykit/models.py,sha256=iHYwp9pchI8ypA_woUJo4Ll2ez60UoibFxf2gKXF8BQ,5482
+qvapaykit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qvapaykit/webhooks.py,sha256=pexyyhQKFWPiRzr74lcbne2jVnHOgzrW_FATpXcDMhM,4137
+qvapaykit-0.1.0.dist-info/METADATA,sha256=W8_I39Toku89fK45Nr9twgEFf8BvImo-Z3LwHiDbqeA,1275
+qvapaykit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+qvapaykit-0.1.0.dist-info/RECORD,,

qvapaykit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any