uvd-x402-sdk 0.2.0__py3-none-any.whl

uvd_x402_sdk/exceptions.py

@@ -0,0 +1,254 @@
+"""
+Custom exceptions for the x402 SDK.
+
+These exceptions provide clear, actionable error messages for different
+failure scenarios in the payment flow.
+"""
+
+from typing import Optional, List, Dict, Any
+
+
+class X402Error(Exception):
+    """Base exception for all x402 SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.message = message
+        self.code = code or "X402_ERROR"
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert exception to dictionary for API responses."""
+        return {
+            "error": self.code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+class PaymentRequiredError(X402Error):
+    """
+    Raised when a payment is required but not provided.
+
+    This should trigger a 402 Payment Required response.
+    """
+
+    def __init__(
+        self,
+        message: str = "Payment required",
+        amount_usd: Optional[str] = None,
+        recipient: Optional[str] = None,
+        supported_networks: Optional[List[str]] = None,
+    ) -> None:
+        details = {}
+        if amount_usd:
+            details["amount"] = amount_usd
+        if recipient:
+            details["recipient"] = recipient
+        if supported_networks:
+            details["supportedNetworks"] = supported_networks
+
+        super().__init__(
+            message=message,
+            code="PAYMENT_REQUIRED",
+            details=details,
+        )
+        self.amount_usd = amount_usd
+        self.recipient = recipient
+        self.supported_networks = supported_networks
+
+
+class PaymentVerificationError(X402Error):
+    """
+    Raised when payment verification fails.
+
+    Common causes:
+    - Invalid signature
+    - Amount mismatch
+    - Wrong recipient
+    - Expired payment authorization
+    """
+
+    def __init__(
+        self,
+        message: str,
+        reason: Optional[str] = None,
+        errors: Optional[List[str]] = None,
+    ) -> None:
+        details = {}
+        if reason:
+            details["reason"] = reason
+        if errors:
+            details["errors"] = errors
+
+        super().__init__(
+            message=message,
+            code="PAYMENT_VERIFICATION_FAILED",
+            details=details,
+        )
+        self.reason = reason
+        self.errors = errors or []
+
+
+class PaymentSettlementError(X402Error):
+    """
+    Raised when payment settlement fails on-chain.
+
+    Common causes:
+    - Insufficient USDC balance
+    - Nonce already used
+    - Authorization expired
+    - Network congestion/timeout
+    """
+
+    def __init__(
+        self,
+        message: str,
+        network: Optional[str] = None,
+        tx_hash: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> None:
+        details = {}
+        if network:
+            details["network"] = network
+        if tx_hash:
+            details["transactionHash"] = tx_hash
+        if reason:
+            details["reason"] = reason
+
+        super().__init__(
+            message=message,
+            code="PAYMENT_SETTLEMENT_FAILED",
+            details=details,
+        )
+        self.network = network
+        self.tx_hash = tx_hash
+        self.reason = reason
+
+
+class UnsupportedNetworkError(X402Error):
+    """
+    Raised when an unsupported network is specified.
+
+    Use `register_network()` to add custom network support.
+    """
+
+    def __init__(
+        self,
+        network: str,
+        supported_networks: Optional[List[str]] = None,
+    ) -> None:
+        super().__init__(
+            message=f"Unsupported network: {network}",
+            code="UNSUPPORTED_NETWORK",
+            details={
+                "requestedNetwork": network,
+                "supportedNetworks": supported_networks or [],
+            },
+        )
+        self.network = network
+        self.supported_networks = supported_networks or []
+
+
+class InvalidPayloadError(X402Error):
+    """
+    Raised when the X-PAYMENT header payload is invalid.
+
+    Common causes:
+    - Invalid base64 encoding
+    - Invalid JSON format
+    - Missing required fields
+    - Invalid x402 version
+    """
+
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+        expected: Optional[str] = None,
+        received: Optional[str] = None,
+    ) -> None:
+        details = {}
+        if field:
+            details["field"] = field
+        if expected:
+            details["expected"] = expected
+        if received:
+            details["received"] = received
+
+        super().__init__(
+            message=message,
+            code="INVALID_PAYLOAD",
+            details=details,
+        )
+        self.field = field
+        self.expected = expected
+        self.received = received
+
+
+class ConfigurationError(X402Error):
+    """
+    Raised when SDK configuration is invalid or missing.
+    """
+
+    def __init__(self, message: str, config_key: Optional[str] = None) -> None:
+        super().__init__(
+            message=message,
+            code="CONFIGURATION_ERROR",
+            details={"configKey": config_key} if config_key else {},
+        )
+        self.config_key = config_key
+
+
+class FacilitatorError(X402Error):
+    """
+    Raised when the facilitator returns an error.
+
+    Contains the raw error response from the facilitator for debugging.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            code="FACILITATOR_ERROR",
+            details={
+                "statusCode": status_code,
+                "response": response_body,
+            },
+        )
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class TimeoutError(X402Error):
+    """
+    Raised when a facilitator request times out.
+
+    Settlement operations can take up to 55 seconds on congested networks.
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        timeout_seconds: float,
+    ) -> None:
+        super().__init__(
+            message=f"{operation} timed out after {timeout_seconds}s",
+            code="TIMEOUT",
+            details={
+                "operation": operation,
+                "timeoutSeconds": timeout_seconds,
+            },
+        )
+        self.operation = operation
+        self.timeout_seconds = timeout_seconds

uvd_x402_sdk/integrations/__init__.py

@@ -0,0 +1,74 @@
+"""
+Framework integrations for the x402 SDK.
+
+This module provides ready-to-use integrations for popular Python web frameworks:
+
+- **Flask**: Decorator and middleware for Flask apps
+- **FastAPI**: Dependency and middleware for FastAPI/Starlette apps
+- **Django**: Middleware and decorator for Django apps
+- **AWS Lambda**: Handler wrapper for Lambda functions
+
+Each integration provides the same core functionality but adapts to the
+idioms and patterns of its target framework.
+"""
+
+# Framework availability flags
+FLASK_AVAILABLE = False
+FASTAPI_AVAILABLE = False
+DJANGO_AVAILABLE = False
+
+try:
+    from uvd_x402_sdk.integrations.flask_integration import (
+        FlaskX402,
+        flask_require_payment,
+    )
+    FLASK_AVAILABLE = True
+except ImportError:
+    FlaskX402 = None  # type: ignore
+    flask_require_payment = None  # type: ignore
+
+try:
+    from uvd_x402_sdk.integrations.fastapi_integration import (
+        FastAPIX402,
+        X402Depends,
+        fastapi_require_payment,
+    )
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FastAPIX402 = None  # type: ignore
+    X402Depends = None  # type: ignore
+    fastapi_require_payment = None  # type: ignore
+
+try:
+    from uvd_x402_sdk.integrations.django_integration import (
+        DjangoX402Middleware,
+        django_require_payment,
+    )
+    DJANGO_AVAILABLE = True
+except ImportError:
+    DjangoX402Middleware = None  # type: ignore
+    django_require_payment = None  # type: ignore
+
+from uvd_x402_sdk.integrations.lambda_integration import (
+    LambdaX402,
+    lambda_handler,
+)
+
+__all__ = [
+    # Flask
+    "FlaskX402",
+    "flask_require_payment",
+    "FLASK_AVAILABLE",
+    # FastAPI
+    "FastAPIX402",
+    "X402Depends",
+    "fastapi_require_payment",
+    "FASTAPI_AVAILABLE",
+    # Django
+    "DjangoX402Middleware",
+    "django_require_payment",
+    "DJANGO_AVAILABLE",
+    # AWS Lambda
+    "LambdaX402",
+    "lambda_handler",
+]

uvd_x402_sdk/integrations/django_integration.py

@@ -0,0 +1,237 @@
+"""
+Django integration for x402 payments.
+
+Provides:
+- DjangoX402Middleware: Middleware for protecting views
+- django_require_payment: Decorator for view functions
+"""
+
+from decimal import Decimal
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union
+import json
+
+try:
+    from django.http import JsonResponse, HttpRequest, HttpResponse
+    from django.conf import settings
+except ImportError:
+    raise ImportError(
+        "Django is required for Django integration. "
+        "Install with: pip install uvd-x402-sdk[django]"
+    )
+
+from uvd_x402_sdk.client import X402Client
+from uvd_x402_sdk.config import X402Config
+from uvd_x402_sdk.exceptions import X402Error
+from uvd_x402_sdk.models import PaymentResult
+from uvd_x402_sdk.response import create_402_response, create_402_headers
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _get_config_from_settings() -> X402Config:
+    """Get x402 configuration from Django settings."""
+    return X402Config(
+        facilitator_url=getattr(
+            settings,
+            "X402_FACILITATOR_URL",
+            "https://facilitator.ultravioletadao.xyz",
+        ),
+        recipient_evm=getattr(settings, "X402_RECIPIENT_EVM", ""),
+        recipient_solana=getattr(settings, "X402_RECIPIENT_SOLANA", ""),
+        recipient_near=getattr(settings, "X402_RECIPIENT_NEAR", ""),
+        recipient_stellar=getattr(settings, "X402_RECIPIENT_STELLAR", ""),
+        facilitator_solana=getattr(
+            settings,
+            "X402_FACILITATOR_SOLANA",
+            "F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq",
+        ),
+    )
+
+
+class DjangoX402Middleware:
+    """
+    Django middleware for x402 payment protection.
+
+    Configure protected paths in Django settings:
+
+        # settings.py
+        X402_RECIPIENT_EVM = "0xYourWallet..."
+        X402_PROTECTED_PATHS = {
+            "/api/premium/": "5.00",
+            "/api/basic/": "1.00",
+        }
+
+    Example:
+        # settings.py
+        MIDDLEWARE = [
+            ...
+            'uvd_x402_sdk.integrations.django_integration.DjangoX402Middleware',
+        ]
+    """
+
+    def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
+        self.get_response = get_response
+        self._config = _get_config_from_settings()
+        self._client = X402Client(config=self._config)
+        self._protected_paths: Dict[str, Decimal] = {}
+
+        # Load protected paths from settings
+        paths_setting = getattr(settings, "X402_PROTECTED_PATHS", {})
+        for path, amount in paths_setting.items():
+            self._protected_paths[path] = Decimal(str(amount))
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        # Check if path is protected
+        path = request.path
+
+        # Try exact match first, then prefix match
+        required_amount = None
+        for protected_path, amount in self._protected_paths.items():
+            if path == protected_path or path.startswith(protected_path):
+                required_amount = amount
+                break
+
+        if required_amount is None:
+            return self.get_response(request)
+
+        # Get payment header (Django uses HTTP_X_PAYMENT format)
+        payment_header = request.META.get("HTTP_X_PAYMENT")
+
+        if not payment_header:
+            response_body = create_402_response(
+                amount_usd=required_amount,
+                config=self._config,
+            )
+            response = JsonResponse(response_body, status=402)
+            for key, value in create_402_headers().items():
+                response[key] = value
+            return response
+
+        try:
+            result = self._client.process_payment(
+                x_payment_header=payment_header,
+                expected_amount_usd=required_amount,
+            )
+            # Store result on request for view access
+            request.payment_result = result  # type: ignore
+            return self.get_response(request)
+
+        except X402Error as e:
+            response = JsonResponse(e.to_dict(), status=402)
+            for key, value in create_402_headers().items():
+                response[key] = value
+            return response
+
+
+def django_require_payment(
+    amount_usd: Union[Decimal, float, str],
+    config: Optional[X402Config] = None,
+    message: Optional[str] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator that requires payment for a Django view.
+
+    Args:
+        amount_usd: Required payment amount in USD
+        config: X402Config (uses Django settings if not provided)
+        message: Custom message for 402 response
+
+    Example:
+        >>> from uvd_x402_sdk.integrations import django_require_payment
+        >>>
+        >>> @django_require_payment(amount_usd="1.00")
+        >>> def my_view(request):
+        ...     # Access payment result via request.payment_result
+        ...     return JsonResponse({"payer": request.payment_result.payer_address})
+    """
+    required_amount = Decimal(str(amount_usd))
+    _config = config or _get_config_from_settings()
+    _client = X402Client(config=_config)
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+            # Get payment header
+            payment_header = request.META.get("HTTP_X_PAYMENT")
+
+            if not payment_header:
+                response_body = create_402_response(
+                    amount_usd=required_amount,
+                    config=_config,
+                    message=message,
+                )
+                response = JsonResponse(response_body, status=402)
+                for key, value in create_402_headers().items():
+                    response[key] = value
+                return response
+
+            try:
+                result = _client.process_payment(
+                    x_payment_header=payment_header,
+                    expected_amount_usd=required_amount,
+                )
+                # Store result on request
+                request.payment_result = result  # type: ignore
+                return func(request, *args, **kwargs)
+
+            except X402Error as e:
+                response = JsonResponse(e.to_dict(), status=402)
+                for key, value in create_402_headers().items():
+                    response[key] = value
+                return response
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+class X402PaymentView:
+    """
+    Mixin for Django class-based views requiring payment.
+
+    Example:
+        >>> from django.views import View
+        >>> from uvd_x402_sdk.integrations.django_integration import X402PaymentView
+        >>>
+        >>> class PremiumAPIView(X402PaymentView, View):
+        ...     x402_amount = Decimal("5.00")
+        ...
+        ...     def get(self, request):
+        ...         return JsonResponse({"payer": request.payment_result.payer_address})
+    """
+
+    x402_amount: Decimal = Decimal("1.00")
+    x402_message: Optional[str] = None
+    x402_config: Optional[X402Config] = None
+
+    def dispatch(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+        config = self.x402_config or _get_config_from_settings()
+        client = X402Client(config=config)
+
+        payment_header = request.META.get("HTTP_X_PAYMENT")
+
+        if not payment_header:
+            response_body = create_402_response(
+                amount_usd=self.x402_amount,
+                config=config,
+                message=self.x402_message,
+            )
+            response = JsonResponse(response_body, status=402)
+            for key, value in create_402_headers().items():
+                response[key] = value
+            return response
+
+        try:
+            result = client.process_payment(
+                x_payment_header=payment_header,
+                expected_amount_usd=self.x402_amount,
+            )
+            request.payment_result = result  # type: ignore
+            return super().dispatch(request, *args, **kwargs)  # type: ignore
+
+        except X402Error as e:
+            response = JsonResponse(e.to_dict(), status=402)
+            for key, value in create_402_headers().items():
+                response[key] = value
+            return response