x402-fastapi-kit 0.3.0__py3-none-any.whl

x402_fastapi_kit/__init__.py

@@ -0,0 +1,57 @@
+"""
+x402-fastapi-kit — Production-ready starter kit for x402 payment-gated FastAPI services.
+
+Deploy an x402-paid API in 10 minutes.
+Bring your data source, set your price per request,
+we handle payments, caching, rate limiting, and agent discovery.
+"""
+
+# Phase 1 — Core
+# Phase 3 — Discovery, Client, Analytics
+from x402_fastapi_kit.analytics import AnalyticsCollector
+from x402_fastapi_kit.app import PaymentApp
+
+# Phase 2 — Access Control & Events
+from x402_fastapi_kit.auth import APIKeyManager, AuthMethod, AuthResult, WalletAllowlist
+from x402_fastapi_kit.cache import RedisCache
+from x402_fastapi_kit.client import DryRunSigner, PaymentPolicy, PaymentSigner, X402Client
+from x402_fastapi_kit.config import X402Settings
+from x402_fastapi_kit.discovery import ServiceManifest, enrich_openapi, register_with_bazaar
+from x402_fastapi_kit.events import EventBus, EventType, PaymentEvent
+from x402_fastapi_kit.mcp import MCPWrapper
+from x402_fastapi_kit.middleware.payment import PaymentGate, require_payment
+from x402_fastapi_kit.middleware.rate_limit import RateLimiter
+from x402_fastapi_kit.middleware.types import RoutePrice
+
+__all__ = [
+    # Core
+    "PaymentApp",
+    "PaymentGate",
+    "X402Settings",
+    "require_payment",
+    "RoutePrice",
+    "RateLimiter",
+    # Auth & Events
+    "APIKeyManager",
+    "AuthMethod",
+    "AuthResult",
+    "WalletAllowlist",
+    "EventBus",
+    "EventType",
+    "PaymentEvent",
+    # Discovery & MCP
+    "ServiceManifest",
+    "enrich_openapi",
+    "register_with_bazaar",
+    "MCPWrapper",
+    # Client
+    "X402Client",
+    "PaymentSigner",
+    "DryRunSigner",
+    "PaymentPolicy",
+    # Infrastructure
+    "AnalyticsCollector",
+    "RedisCache",
+]
+
+__version__ = "0.3.0"

x402_fastapi_kit/analytics/__init__.py

@@ -0,0 +1,323 @@
+"""
+Analytics collector for x402-fastapi-kit.
+
+Plugs into the ``EventBus`` to accumulate real-time statistics:
+revenue, request counts, auth breakdowns, top routes, and error rates.
+
+Exposes a ``/x402/stats`` JSON endpoint and a ``/x402/dashboard``
+HTML dashboard.
+
+Usage::
+
+    from x402_fastapi_kit.analytics import AnalyticsCollector
+
+    collector = AnalyticsCollector(event_bus=bus)
+
+    # Later, register with the app
+    collector.mount(app, settings)
+"""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+from dataclasses import dataclass
+from decimal import Decimal
+from threading import Lock
+from typing import Any
+
+from fastapi import FastAPI
+
+from x402_fastapi_kit.config import X402Settings
+from x402_fastapi_kit.events import EventBus, EventType, PaymentEvent
+
+
+@dataclass
+class RouteStats:
+    """Stats for a single route."""
+
+    requests: int = 0
+    payments: int = 0
+    rejections: int = 0
+    api_key_hits: int = 0
+    allowlist_hits: int = 0
+    rate_limited: int = 0
+    revenue_cents: int = 0  # in hundredths of a dollar
+
+    @property
+    def revenue_usd(self) -> str:
+        return f"${self.revenue_cents / 100:.2f}"
+
+
+class AnalyticsCollector:
+    """
+    Real-time analytics collector powered by EventBus.
+
+    Subscribes to all payment lifecycle events and maintains
+    in-memory counters. Thread-safe for concurrent access.
+
+    Args:
+        event_bus: The EventBus instance to subscribe to.
+    """
+
+    def __init__(self, event_bus: EventBus) -> None:
+        self._bus = event_bus
+        self._lock = Lock()
+
+        # Global counters
+        self._total_requests = 0
+        self._total_payments = 0
+        self._total_rejections = 0
+        self._total_rate_limited = 0
+        self._total_facilitator_errors = 0
+        self._total_revenue_cents = 0
+
+        # Per-route stats
+        self._route_stats: dict[str, RouteStats] = defaultdict(RouteStats)
+
+        # Per-auth-method counts
+        self._auth_counts: dict[str, int] = defaultdict(int)
+
+        # Recent events (ring buffer, last 200)
+        self._recent: list[dict[str, Any]] = []
+        self._max_recent = 200
+
+        # Hourly revenue buckets (hour_key → cents)
+        self._hourly_revenue: dict[str, int] = defaultdict(int)
+
+        # Start time
+        self._started_at = time.time()
+
+        # Subscribe to all events
+        self._bus.on_all(self._handle_event)
+
+    def _hour_key(self, ts: float | None = None) -> str:
+        t = time.gmtime(ts or time.time())
+        return f"{t.tm_year}-{t.tm_mon:02d}-{t.tm_mday:02d}T{t.tm_hour:02d}"
+
+    def _price_to_cents(self, price: str | None) -> int:
+        if not price:
+            return 0
+        try:
+            return int(Decimal(price.lstrip("$")) * 100)
+        except Exception:
+            return 0
+
+    def _handle_event(self, event: PaymentEvent) -> None:
+        """Process a single event (called by EventBus)."""
+        with self._lock:
+            route = event.route
+            rs = self._route_stats[route]
+            self._total_requests += 1
+            rs.requests += 1
+
+            evt_type = event.event_type
+
+            if evt_type == EventType.PAYMENT_VERIFIED:
+                self._total_payments += 1
+                rs.payments += 1
+                cents = self._price_to_cents(event.price)
+                self._total_revenue_cents += cents
+                rs.revenue_cents += cents
+                self._hourly_revenue[self._hour_key(event.timestamp)] += cents
+                self._auth_counts["x402"] += 1
+
+            elif evt_type == EventType.PAYMENT_REJECTED:
+                self._total_rejections += 1
+                rs.rejections += 1
+
+            elif evt_type == EventType.REQUEST_GATED:
+                pass  # counted in total_requests already
+
+            elif evt_type == EventType.AUTH_API_KEY:
+                rs.api_key_hits += 1
+                self._auth_counts["api_key"] += 1
+
+            elif evt_type == EventType.AUTH_ALLOWLIST:
+                rs.allowlist_hits += 1
+                self._auth_counts["allowlist"] += 1
+
+            elif evt_type == EventType.RATE_LIMITED:
+                self._total_rate_limited += 1
+                rs.rate_limited += 1
+
+            elif evt_type == EventType.FACILITATOR_ERROR:
+                self._total_facilitator_errors += 1
+
+            # Add to recent events
+            self._recent.append({
+                "type": evt_type.value
+                if isinstance(evt_type, EventType) else str(evt_type),
+                "route": route,
+                "client": event.client_id,
+                "price": event.price,
+                "tx": event.tx_hash,
+                "time": event.timestamp,
+            })
+            if len(self._recent) > self._max_recent:
+                self._recent = self._recent[-self._max_recent:]
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a point-in-time analytics snapshot."""
+        with self._lock:
+            uptime = time.time() - self._started_at
+
+            routes = {}
+            for route, rs in sorted(self._route_stats.items()):
+                routes[route] = {
+                    "requests": rs.requests,
+                    "payments": rs.payments,
+                    "rejections": rs.rejections,
+                    "api_key_hits": rs.api_key_hits,
+                    "allowlist_hits": rs.allowlist_hits,
+                    "rate_limited": rs.rate_limited,
+                    "revenue": rs.revenue_usd,
+                }
+
+            return {
+                "uptime_seconds": round(uptime, 1),
+                "totals": {
+                    "requests": self._total_requests,
+                    "payments": self._total_payments,
+                    "rejections": self._total_rejections,
+                    "rate_limited": self._total_rate_limited,
+                    "facilitator_errors": self._total_facilitator_errors,
+                    "revenue": f"${self._total_revenue_cents / 100:.2f}",
+                },
+                "auth_breakdown": dict(self._auth_counts),
+                "routes": routes,
+                "hourly_revenue": dict(self._hourly_revenue),
+                "recent_events": list(self._recent[-50:]),
+            }
+
+    def mount(self, app: FastAPI, settings: X402Settings) -> None:
+        """Register /x402/stats and /x402/dashboard endpoints."""
+        collector = self
+
+        @app.get("/x402/stats", tags=["x402"])
+        async def x402_stats() -> dict:
+            """Real-time analytics snapshot (JSON)."""
+            return collector.snapshot()
+
+        @app.get(
+            "/x402/dashboard",
+            tags=["x402"],
+            response_class=_HTMLResponse,
+        )
+        async def x402_dashboard() -> _HTMLResponse:
+            """Live analytics dashboard (HTML)."""
+            return _HTMLResponse(content=_DASHBOARD_HTML)
+
+
+# ── Minimal HTML response class ──────────────────────────────────────────────
+
+class _HTMLResponse:
+    """Minimal HTML response to avoid import of starlette in module scope."""
+    media_type = "text/html"
+
+    def __init__(self, content: str, status_code: int = 200) -> None:
+        self.body = content.encode()
+        self.status_code = status_code
+
+
+# We use starlette's actual response at runtime
+from starlette.responses import HTMLResponse as _HTMLResponse  # noqa: E402, F811
+
+# ── Dashboard HTML ────────────────────────────────────────────────────────────
+
+_DASHBOARD_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>x402 Dashboard</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{font-family:system-ui,-apple-system,sans-serif;background:#0a0a0a;color:#e0e0e0;padding:2rem}
+  h1{font-size:1.5rem;margin-bottom:1.5rem;color:#fff}
+  h1 span{color:#4ade80;font-weight:400}
+  .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:1rem;margin-bottom:2rem}
+  .card{background:#1a1a2e;border-radius:12px;padding:1.25rem;border:1px solid #2a2a3e}
+  .card .label{font-size:.75rem;color:#888;text-transform:uppercase;letter-spacing:.05em}
+  .card .value{font-size:1.75rem;font-weight:700;margin-top:.25rem;color:#fff}
+  .card .value.green{color:#4ade80}
+  .card .value.red{color:#f87171}
+  .card .value.blue{color:#60a5fa}
+  .card .value.yellow{color:#fbbf24}
+  table{width:100%;border-collapse:collapse;background:#1a1a2e;border-radius:12px;overflow:hidden;border:1px solid #2a2a3e}
+  th,td{padding:.75rem 1rem;text-align:left;border-bottom:1px solid #2a2a3e}
+  th{background:#12122a;color:#888;font-size:.75rem;text-transform:uppercase;letter-spacing:.05em}
+  td{font-size:.875rem}
+  .tag{display:inline-block;padding:2px 8px;border-radius:4px;font-size:.75rem;font-weight:600}
+  .tag-green{background:#064e3b;color:#4ade80}
+  .tag-red{background:#450a0a;color:#f87171}
+  .tag-blue{background:#172554;color:#60a5fa}
+  .refresh{color:#888;font-size:.75rem;margin-top:1rem;text-align:center}
+  h2{font-size:1.1rem;margin:1.5rem 0 .75rem;color:#ccc}
+</style>
+</head>
+<body>
+<h1>x402 <span>Dashboard</span></h1>
+<div id="app"><p style="color:#888">Loading…</p></div>
+<p class="refresh">Auto-refreshes every 5s</p>
+<script>
+async function refresh(){
+  try{
+    const r=await fetch('/x402/stats');
+    const d=await r.json();
+    const t=d.totals;
+    const routes=d.routes||{};
+    const auth=d.auth_breakdown||{};
+    let html=`
+      <div class="grid">
+        <div class="card"><div class="label">Revenue</div><div class="value green">${t.revenue}</div></div>
+        <div class="card"><div class="label">Payments</div><div class="value blue">${t.payments}</div></div>
+        <div class="card"><div class="label">Total Requests</div><div class="value">${t.requests}</div></div>
+        <div class="card"><div class="label">Rejections</div><div class="value red">${t.rejections}</div></div>
+        <div class="card"><div class="label">Rate Limited</div><div class="value yellow">${t.rate_limited}</div></div>
+        <div class="card"><div class="label">Uptime</div><div class="value">${Math.round(d.uptime_seconds)}s</div></div>
+      </div>
+      <h2>Auth Breakdown</h2>
+      <div class="grid">
+        <div class="card"><div class="label">x402 Payments</div><div class="value green">${auth.x402||0}</div></div>
+        <div class="card"><div class="label">API Key</div><div class="value blue">${auth.api_key||0}</div></div>
+        <div class="card"><div class="label">Allowlist</div><div class="value">${auth.allowlist||0}</div></div>
+      </div>
+      <h2>Routes</h2>
+      <table>
+        <thead><tr><th>Route</th><th>Requests</th><th>Payments</th><th>Revenue</th><th>API Key</th><th>Rate Ltd</th></tr></thead>
+        <tbody>`;
+    for(const[route,s]of Object.entries(routes)){
+      html+=`<tr>
+        <td><code>${route}</code></td>
+        <td>${s.requests}</td>
+        <td><span class="tag tag-green">${s.payments}</span></td>
+        <td>${s.revenue}</td>
+        <td><span class="tag tag-blue">${s.api_key_hits}</span></td>
+        <td>${s.rate_limited?'<span class="tag tag-red">'+s.rate_limited+'</span>':'0'}</td>
+      </tr>`;
+    }
+    html+=`</tbody></table>`;
+    const events=d.recent_events||[];
+    if(events.length){
+      html+=`<h2>Recent Events (last ${events.length})</h2><table>
+        <thead><tr><th>Type</th><th>Route</th><th>Client</th><th>Price</th></tr></thead><tbody>`;
+      for(const e of events.slice(-20).reverse()){
+        const cls=e.type.includes('verified')?'tag-green':e.type.includes('reject')?'tag-red':'tag-blue';
+        html+=`<tr>
+          <td><span class="tag ${cls}">${e.type}</span></td>
+          <td><code>${e.route}</code></td>
+          <td>${(e.client||'—').substring(0,12)}</td>
+          <td>${e.price||'—'}</td>
+        </tr>`;
+      }
+      html+=`</tbody></table>`;
+    }
+    document.getElementById('app').innerHTML=html;
+  }catch(e){document.getElementById('app').innerHTML='<p style="color:#f87171">Error loading stats</p>'}
+}
+refresh();
+setInterval(refresh,5000);
+</script>
+</body>
+</html>"""

x402_fastapi_kit/app.py

@@ -0,0 +1,135 @@
+"""
+PaymentApp — batteries-included FastAPI subclass for x402 services.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+
+from x402_fastapi_kit.analytics import AnalyticsCollector
+from x402_fastapi_kit.auth import APIKeyManager, WalletAllowlist
+from x402_fastapi_kit.config import X402Settings
+from x402_fastapi_kit.discovery import (
+    ServiceManifest,
+    enrich_openapi,
+    register_well_known,
+)
+from x402_fastapi_kit.events import EventBus
+from x402_fastapi_kit.middleware.payment import PaymentGate, get_registry
+from x402_fastapi_kit.middleware.rate_limit import RateLimiter
+
+logger = logging.getLogger("x402_fastapi_kit")
+
+
+class PaymentApp(FastAPI):
+    """
+    FastAPI application pre-configured with the full x402-fastapi-kit stack.
+
+    Phases 1–3:
+    - Payment middleware with 4-step pipeline
+    - API key auth, wallet allowlist, rate limiting, event hooks
+    - Service discovery (.well-known/x402), OpenAPI enrichment, analytics
+    """
+
+    def __init__(
+        self,
+        settings: X402Settings | None = None,
+        *,
+        event_bus: EventBus | None = None,
+        api_key_manager: APIKeyManager | None = None,
+        wallet_allowlist: WalletAllowlist | None = None,
+        rate_limiter: RateLimiter | None = None,
+        manifest: ServiceManifest | None = None,
+        analytics: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        self._x402_settings = settings
+        self._event_bus = event_bus or EventBus()
+        self._api_key_manager = api_key_manager
+        self._wallet_allowlist = wallet_allowlist
+        self._rate_limiter = rate_limiter
+        self._manifest = manifest
+        self._analytics_enabled = analytics
+        self._analytics_collector: AnalyticsCollector | None = None
+
+        kwargs.setdefault("title", "x402-fastapi-kit Service")
+        super().__init__(**kwargs)
+
+        # Introspection endpoints (Phase 1)
+        self._register_introspection()
+
+        # Discovery (Phase 3)
+        if self._manifest is not None:
+            register_well_known(self, self.x402_settings, self._manifest)
+
+        # Analytics (Phase 3)
+        if self._analytics_enabled:
+            self._analytics_collector = AnalyticsCollector(self._event_bus)
+            self._analytics_collector.mount(self, self.x402_settings)
+
+        # Payment middleware (must be added last — Starlette wraps in reverse)
+        self.add_middleware(
+            PaymentGate,
+            settings=self.x402_settings,
+            owner_app=self,
+            event_bus=self._event_bus,
+            api_key_manager=self._api_key_manager,
+            wallet_allowlist=self._wallet_allowlist,
+            rate_limiter=self._rate_limiter,
+        )
+
+    @property
+    def x402_settings(self) -> X402Settings:
+        if self._x402_settings is None:
+            self._x402_settings = X402Settings()
+        return self._x402_settings
+
+    @property
+    def event_bus(self) -> EventBus:
+        return self._event_bus
+
+    @property
+    def analytics(self) -> AnalyticsCollector | None:
+        return self._analytics_collector
+
+    def enrich_openapi_schema(self) -> None:
+        """Inject x402 metadata into the OpenAPI schema."""
+        enrich_openapi(self, self.x402_settings)
+
+    def _register_introspection(self) -> None:
+        settings_ref = self
+
+        @self.get("/x402/health", tags=["x402"], include_in_schema=True)
+        async def x402_health() -> dict:
+            s = settings_ref.x402_settings
+            registry = get_registry()
+            return {
+                "status": "ok",
+                "version": "0.3.0",
+                "network": s.network,
+                "is_testnet": s.is_testnet,
+                "facilitator": s.facilitator_url,
+                "gated_routes": len(registry),
+                "rate_limit_enabled": s.rate_limit_enabled,
+                "api_keys_enabled": s.api_keys_enabled,
+                "allowlist_enabled": s.allowlist_enabled,
+                "analytics_enabled": settings_ref._analytics_enabled,
+                "manifest_enabled": settings_ref._manifest is not None,
+            }
+
+        @self.get("/x402/routes", tags=["x402"], include_in_schema=True)
+        async def x402_routes() -> dict:
+            s = settings_ref.x402_settings
+            registry = get_registry()
+            routes = {}
+            for key, rp in registry.all().items():
+                routes[key] = {
+                    "price": rp.price,
+                    "description": rp.description or s.default_description,
+                    "network": rp.network or s.network,
+                    "scheme": rp.scheme or s.scheme,
+                }
+            return {"routes": routes}