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

uvd_x402_sdk/integrations/fastapi_integration.py

@@ -0,0 +1,330 @@
+"""
+FastAPI/Starlette integration for x402 payments.
+
+Provides:
+- FastAPIX402: App integration class
+- X402Depends: Dependency injection for payment verification
+- fastapi_require_payment: Decorator for protected routes
+"""
+
+from decimal import Decimal
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, Union
+
+try:
+    from fastapi import FastAPI, Request, HTTPException, Depends
+    from fastapi.responses import JSONResponse
+    from starlette.middleware.base import BaseHTTPMiddleware
+except ImportError:
+    raise ImportError(
+        "FastAPI is required for FastAPI integration. "
+        "Install with: pip install uvd-x402-sdk[fastapi]"
+    )
+
+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])
+
+
+class FastAPIX402:
+    """
+    FastAPI integration for x402 payments.
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from uvd_x402_sdk.integrations import FastAPIX402
+        >>>
+        >>> app = FastAPI()
+        >>> x402 = FastAPIX402(app, recipient_address="0xYourWallet...")
+        >>>
+        >>> @app.get("/premium")
+        >>> async def premium(payment: PaymentResult = Depends(x402.require_payment(1.00))):
+        ...     return {"payer": payment.payer_address}
+    """
+
+    def __init__(
+        self,
+        app: Optional[FastAPI] = None,
+        config: Optional[X402Config] = None,
+        recipient_address: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize FastAPI x402 integration.
+
+        Args:
+            app: FastAPI application (optional)
+            config: X402Config object
+            recipient_address: Default recipient for EVM chains
+            **kwargs: Additional config parameters
+        """
+        self._config = config or X402Config(
+            recipient_evm=recipient_address or "",
+            **kwargs,
+        )
+        self._client = X402Client(config=self._config)
+
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: FastAPI) -> None:
+        """
+        Initialize with FastAPI app.
+
+        Stores client in app.state for access in routes.
+        """
+        app.state.x402_client = self._client
+        app.state.x402_config = self._config
+
+    @property
+    def client(self) -> X402Client:
+        """Get the x402 client."""
+        return self._client
+
+    @property
+    def config(self) -> X402Config:
+        """Get the x402 config."""
+        return self._config
+
+    def require_payment(
+        self,
+        amount_usd: Union[Decimal, float, str],
+        message: Optional[str] = None,
+    ) -> Callable[..., PaymentResult]:
+        """
+        Create a FastAPI dependency that requires payment.
+
+        Args:
+            amount_usd: Required payment amount in USD
+            message: Custom message for 402 response
+
+        Returns:
+            Dependency function that returns PaymentResult
+
+        Example:
+            >>> @app.post("/api/premium")
+            >>> async def premium(
+            ...     request: Request,
+            ...     payment: PaymentResult = Depends(x402.require_payment(5.00))
+            ... ):
+            ...     return {"payer": payment.payer_address}
+        """
+        required_amount = Decimal(str(amount_usd))
+
+        async def dependency(request: Request) -> PaymentResult:
+            payment_header = request.headers.get("X-PAYMENT")
+
+            if not payment_header:
+                response_body = create_402_response(
+                    amount_usd=required_amount,
+                    config=self._config,
+                    message=message,
+                )
+                raise HTTPException(
+                    status_code=402,
+                    detail=response_body,
+                    headers=create_402_headers(),
+                )
+
+            try:
+                return self._client.process_payment(
+                    x_payment_header=payment_header,
+                    expected_amount_usd=required_amount,
+                )
+            except X402Error as e:
+                raise HTTPException(
+                    status_code=402,
+                    detail=e.to_dict(),
+                    headers=create_402_headers(),
+                )
+
+        return dependency
+
+
+class X402Depends:
+    """
+    Reusable FastAPI dependency for x402 payments.
+
+    This provides a cleaner syntax for dependency injection.
+
+    Example:
+        >>> x402_payment = X402Depends(
+        ...     config=X402Config(recipient_evm="0x..."),
+        ...     amount_usd=Decimal("1.00")
+        ... )
+        >>>
+        >>> @app.get("/resource")
+        >>> async def resource(payment: PaymentResult = Depends(x402_payment)):
+        ...     return {"payer": payment.payer_address}
+    """
+
+    def __init__(
+        self,
+        config: X402Config,
+        amount_usd: Union[Decimal, float, str],
+        message: Optional[str] = None,
+    ) -> None:
+        self._config = config
+        self._client = X402Client(config=config)
+        self._amount = Decimal(str(amount_usd))
+        self._message = message
+
+    async def __call__(self, request: Request) -> PaymentResult:
+        """Process payment when used as dependency."""
+        payment_header = request.headers.get("X-PAYMENT")
+
+        if not payment_header:
+            response_body = create_402_response(
+                amount_usd=self._amount,
+                config=self._config,
+                message=self._message,
+            )
+            raise HTTPException(
+                status_code=402,
+                detail=response_body,
+                headers=create_402_headers(),
+            )
+
+        try:
+            return self._client.process_payment(
+                x_payment_header=payment_header,
+                expected_amount_usd=self._amount,
+            )
+        except X402Error as e:
+            raise HTTPException(
+                status_code=402,
+                detail=e.to_dict(),
+                headers=create_402_headers(),
+            )
+
+
+def fastapi_require_payment(
+    amount_usd: Union[Decimal, float, str],
+    config: X402Config,
+    message: Optional[str] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for FastAPI routes requiring payment.
+
+    Alternative to dependency injection for simpler cases.
+
+    Args:
+        amount_usd: Required payment amount
+        config: X402Config with recipient addresses
+        message: Custom 402 message
+
+    Example:
+        >>> @app.get("/resource")
+        >>> @fastapi_require_payment(amount_usd="1.00", config=config)
+        >>> async def resource(request: Request):
+        ...     # Payment already verified
+        ...     return {"success": True}
+    """
+    required_amount = Decimal(str(amount_usd))
+    client = X402Client(config=config)
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        async def wrapper(request: Request, *args: Any, **kwargs: Any) -> Any:
+            payment_header = request.headers.get("X-PAYMENT")
+
+            if not payment_header:
+                response_body = create_402_response(
+                    amount_usd=required_amount,
+                    config=config,
+                    message=message,
+                )
+                return JSONResponse(
+                    status_code=402,
+                    content=response_body,
+                    headers=create_402_headers(),
+                )
+
+            try:
+                result = client.process_payment(
+                    x_payment_header=payment_header,
+                    expected_amount_usd=required_amount,
+                )
+                # Store result in request state
+                request.state.payment_result = result
+                return await func(request, *args, **kwargs)
+
+            except X402Error as e:
+                return JSONResponse(
+                    status_code=402,
+                    content=e.to_dict(),
+                    headers=create_402_headers(),
+                )
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+class X402Middleware(BaseHTTPMiddleware):
+    """
+    Middleware that automatically handles x402 payments for configured paths.
+
+    Example:
+        >>> from uvd_x402_sdk.integrations.fastapi_integration import X402Middleware
+        >>>
+        >>> app.add_middleware(
+        ...     X402Middleware,
+        ...     config=config,
+        ...     protected_paths={
+        ...         "/api/premium": Decimal("5.00"),
+        ...         "/api/basic": Decimal("1.00"),
+        ...     }
+        ... )
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        config: X402Config,
+        protected_paths: dict[str, Decimal],
+    ) -> None:
+        super().__init__(app)
+        self._config = config
+        self._client = X402Client(config=config)
+        self._protected_paths = protected_paths
+
+    async def dispatch(self, request: Request, call_next: Any) -> Any:
+        path = request.url.path
+
+        # Check if path is protected
+        if path not in self._protected_paths:
+            return await call_next(request)
+
+        required_amount = self._protected_paths[path]
+        payment_header = request.headers.get("X-PAYMENT")
+
+        if not payment_header:
+            response_body = create_402_response(
+                amount_usd=required_amount,
+                config=self._config,
+            )
+            return JSONResponse(
+                status_code=402,
+                content=response_body,
+                headers=create_402_headers(),
+            )
+
+        try:
+            result = self._client.process_payment(
+                x_payment_header=payment_header,
+                expected_amount_usd=required_amount,
+            )
+            request.state.payment_result = result
+            return await call_next(request)
+
+        except X402Error as e:
+            return JSONResponse(
+                status_code=402,
+                content=e.to_dict(),
+                headers=create_402_headers(),
+            )

uvd_x402_sdk/integrations/flask_integration.py

@@ -0,0 +1,259 @@
+"""
+Flask integration for x402 payments.
+
+Provides:
+- FlaskX402: Extension for initializing x402 with Flask apps
+- flask_require_payment: Decorator for protecting routes
+"""
+
+from decimal import Decimal
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, Union
+
+try:
+    from flask import Flask, request, jsonify, make_response, g
+except ImportError:
+    raise ImportError(
+        "Flask is required for Flask integration. "
+        "Install with: pip install uvd-x402-sdk[flask]"
+    )
+
+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.response import create_402_response, create_402_headers
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class FlaskX402:
+    """
+    Flask extension for x402 payment integration.
+
+    Example:
+        >>> from flask import Flask
+        >>> from uvd_x402_sdk.integrations import FlaskX402
+        >>>
+        >>> app = Flask(__name__)
+        >>> x402 = FlaskX402(app, recipient_address="0xYourWallet...")
+        >>>
+        >>> @app.route("/premium")
+        >>> @x402.require_payment(amount_usd=Decimal("1.00"))
+        >>> def premium():
+        ...     return {"message": f"Paid by {g.payment_result.payer_address}"}
+    """
+
+    def __init__(
+        self,
+        app: Optional[Flask] = None,
+        config: Optional[X402Config] = None,
+        recipient_address: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize Flask x402 extension.
+
+        Args:
+            app: Flask application (optional, can use init_app later)
+            config: X402Config object
+            recipient_address: Default recipient for EVM chains
+            **kwargs: Additional config parameters
+        """
+        self.app = app
+        self._config = config
+        self._config_kwargs = {"recipient_evm": recipient_address, **kwargs}
+        self._client: Optional[X402Client] = None
+
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: Flask) -> None:
+        """
+        Initialize extension with Flask app.
+
+        Args:
+            app: Flask application
+        """
+        self.app = app
+
+        # Get config from app config if not provided
+        if self._config is None:
+            self._config = X402Config(
+                facilitator_url=app.config.get(
+                    "X402_FACILITATOR_URL",
+                    "https://facilitator.ultravioletadao.xyz",
+                ),
+                recipient_evm=app.config.get("X402_RECIPIENT_EVM", "")
+                or self._config_kwargs.get("recipient_evm", ""),
+                recipient_solana=app.config.get("X402_RECIPIENT_SOLANA", ""),
+                recipient_near=app.config.get("X402_RECIPIENT_NEAR", ""),
+                recipient_stellar=app.config.get("X402_RECIPIENT_STELLAR", ""),
+            )
+
+        self._client = X402Client(config=self._config)
+
+        # Store extension on app
+        if not hasattr(app, "extensions"):
+            app.extensions = {}
+        app.extensions["x402"] = self
+
+    @property
+    def client(self) -> X402Client:
+        """Get the x402 client."""
+        if self._client is None:
+            raise RuntimeError("FlaskX402 not initialized. Call init_app() first.")
+        return self._client
+
+    @property
+    def config(self) -> X402Config:
+        """Get the x402 config."""
+        if self._config is None:
+            raise RuntimeError("FlaskX402 not initialized. Call init_app() first.")
+        return self._config
+
+    def require_payment(
+        self,
+        amount_usd: Optional[Union[Decimal, float, str]] = None,
+        amount_callback: Optional[Callable[[], Decimal]] = None,
+        message: Optional[str] = None,
+        store_in_g: bool = True,
+    ) -> Callable[[F], F]:
+        """
+        Decorator that requires payment for a Flask route.
+
+        Args:
+            amount_usd: Fixed payment amount in USD
+            amount_callback: Callable that returns dynamic amount
+            message: Custom message for 402 response
+            store_in_g: Store PaymentResult in flask.g.payment_result
+
+        Returns:
+            Decorated route function
+
+        Example:
+            >>> @app.route("/api/premium")
+            >>> @x402.require_payment(amount_usd="5.00")
+            >>> def premium_endpoint():
+            ...     return {"payer": g.payment_result.payer_address}
+        """
+
+        def decorator(func: F) -> F:
+            @wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                # Get payment header
+                payment_header = request.headers.get("X-PAYMENT")
+
+                # Determine amount
+                if amount_callback:
+                    required_amount = Decimal(str(amount_callback()))
+                elif amount_usd:
+                    required_amount = Decimal(str(amount_usd))
+                else:
+                    raise ValueError("Either amount_usd or amount_callback is required")
+
+                # No payment header - return 402
+                if not payment_header:
+                    response_body = create_402_response(
+                        amount_usd=required_amount,
+                        config=self.config,
+                        message=message,
+                    )
+                    response = make_response(jsonify(response_body), 402)
+                    for key, value in create_402_headers().items():
+                        response.headers[key] = value
+                    return response
+
+                # Process payment
+                try:
+                    result = self.client.process_payment(
+                        x_payment_header=payment_header,
+                        expected_amount_usd=required_amount,
+                    )
+
+                    # Store result in g
+                    if store_in_g:
+                        g.payment_result = result
+
+                    return func(*args, **kwargs)
+
+                except X402Error as e:
+                    response_body = create_402_response(
+                        amount_usd=required_amount,
+                        config=self.config,
+                        message=message,
+                    )
+                    response_body["error"] = e.message
+                    response_body["details"] = e.details
+                    response = make_response(jsonify(response_body), 402)
+                    for key, value in create_402_headers().items():
+                        response.headers[key] = value
+                    return response
+
+            return wrapper  # type: ignore
+
+        return decorator
+
+
+def flask_require_payment(
+    amount_usd: Union[Decimal, float, str],
+    message: Optional[str] = None,
+) -> Callable[[F], F]:
+    """
+    Standalone decorator using global Flask x402 extension.
+
+    This decorator uses the x402 extension stored in current_app.extensions.
+
+    Example:
+        >>> @app.route("/api/resource")
+        >>> @flask_require_payment(amount_usd="1.00")
+        >>> def resource():
+        ...     return {"success": True}
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from flask import current_app, g
+
+            # Get extension from app
+            if "x402" not in current_app.extensions:
+                raise RuntimeError(
+                    "FlaskX402 not initialized. "
+                    "Add FlaskX402(app, ...) to your app setup."
+                )
+
+            x402_ext: FlaskX402 = current_app.extensions["x402"]
+            required_amount = Decimal(str(amount_usd))
+
+            # Get payment header
+            payment_header = request.headers.get("X-PAYMENT")
+
+            # No payment - return 402
+            if not payment_header:
+                response_body = create_402_response(
+                    amount_usd=required_amount,
+                    config=x402_ext.config,
+                    message=message,
+                )
+                response = make_response(jsonify(response_body), 402)
+                for key, value in create_402_headers().items():
+                    response.headers[key] = value
+                return response
+
+            # Process payment
+            try:
+                result = x402_ext.client.process_payment(
+                    x_payment_header=payment_header,
+                    expected_amount_usd=required_amount,
+                )
+                g.payment_result = result
+                return func(*args, **kwargs)
+
+            except X402Error as e:
+                response_body = e.to_dict()
+                response = make_response(jsonify(response_body), 402)
+                return response
+
+        return wrapper  # type: ignore
+
+    return decorator