qvapaykit 0.1.0__tar.gz

qvapaykit-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+
+# Entorno y secretos
+.env
+.env.*
+!.env.example
+
+# Bases de datos locales
+*.db
+*.sqlite3
+
+# IDE
+.idea/
+
+# Cobertura
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

qvapaykit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,7 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "qvapaykit"
+version = "0.1.0"
+description = "QvaPayKit: SDK Python para integrar pagos con QvaPay — facturas, webhooks verificados, dinero en Decimal"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "RolandoJV" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+]
+
+[project.urls]
+Homepage = "https://www.qvapay.com/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qvapaykit"]

qvapaykit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)."""