2026-06-17 02:09:36 +03:00

352 lines
12 KiB
Python

"""AI Export Pro — a runnable FastAPI SaaS gated by SettleKit.
A complete demo SaaS that sells an "AI export" feature. Access is gated behind
SettleKit **entitlements** (for subscribers) with a **prepaid-credit** fallback
(for pay-as-you-go users), enforced via the real SettleKit Python SDK and HTTP
API. See README.md for a full curl walkthrough.
Run::
uvicorn app.main:app --reload --port 8000
"""
from __future__ import annotations
import time
import uuid
from contextlib import asynccontextmanager
from typing import Any, AsyncIterator, Optional
from fastapi import Depends, FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field, field_validator
from settlekit.errors import (
SettleKitConfigError,
SettleKitConnectionError,
SettleKitError,
)
from . import settlekit_client as sk
from .deps import AccessGrant, GateDenied, require_ai_export_access
# ---------------------------------------------------------------------------
# Product catalog (the public landing page advertises these tiers).
# ---------------------------------------------------------------------------
PLAN_TIERS: list[dict[str, Any]] = [
{
"id": "free",
"name": "Free",
"price": {"amount": "0.00", "currency": "USDC"},
"description": "Explore the API. AI exports require credits or Pro.",
"ai_exports": "0 included",
},
{
"id": "payg",
"name": "Pay As You Go",
"price": {"amount": "1.00", "currency": "USDC"},
"description": "Buy prepaid credits. 1 credit = 1 AI export.",
"ai_exports": "metered (1 credit each)",
},
{
"id": "pro",
"name": "Pro",
"price": {"amount": "25.00", "currency": "USDC"},
"description": "Unlimited AI exports via the ai_export entitlement.",
"ai_exports": "unlimited",
},
]
# ---------------------------------------------------------------------------
# Lifespan: validate config on boot, close the SDK client on shutdown.
# ---------------------------------------------------------------------------
@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
"""Fail fast on missing config at startup; release the client at shutdown."""
sk.get_settings() # raises SettleKitConfigError if misconfigured
sk.get_client()
try:
yield
finally:
await sk.close_client()
app = FastAPI(
title="AI Export Pro",
version="0.1.0",
summary="Demo SaaS gating a paid feature behind SettleKit entitlements + credits.",
lifespan=lifespan,
)
# ---------------------------------------------------------------------------
# Request / response models.
# ---------------------------------------------------------------------------
class SignupRequest(BaseModel):
"""Payload for creating a SettleKit customer."""
email: str = Field(..., min_length=3, max_length=320)
name: Optional[str] = Field(default=None, max_length=200)
@field_validator("email")
@classmethod
def _validate_email(cls, value: str) -> str:
"""Lightweight email shape check (avoids the email-validator dependency)."""
value = value.strip()
if "@" not in value or value.startswith("@") or value.endswith("@"):
raise ValueError("email must be a valid address")
return value
class GrantCreditsRequest(BaseModel):
"""Admin payload for granting prepaid credits."""
customer_id: str = Field(..., min_length=1)
credits: int = Field(..., gt=0, le=1_000_000)
class ExportRequest(BaseModel):
"""Payload describing the dataset the customer wants exported."""
dataset: str = Field(..., min_length=1, max_length=500)
fmt: str = Field(default="csv", pattern="^(csv|json|parquet)$")
# ---------------------------------------------------------------------------
# Error handlers — map SDK/gate exceptions to clean HTTP responses.
# ---------------------------------------------------------------------------
@app.exception_handler(GateDenied)
async def _gate_denied_handler(_, exc: GateDenied) -> JSONResponse:
"""Render a denied access decision as 402/403 with an upgrade message."""
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": "payment_required"
if exc.status_code == 402
else "forbidden",
"message": (
"AI export is a paid feature. You have no active "
f"'{exc.feature}' entitlement and no remaining prepaid "
"credits. Grant credits via POST /billing/grant-credits, "
"buy a Pay-As-You-Go pack, or upgrade to Pro for unlimited "
"exports."
),
"customerId": exc.customer_id,
"creditsRemaining": exc.credits_remaining,
"upgradeUrl": "/#pricing",
}
},
)
@app.exception_handler(SettleKitConfigError)
async def _config_error_handler(_, exc: SettleKitConfigError) -> JSONResponse:
"""Configuration problems are a 500 — the server, not the client, is at fault."""
return JSONResponse(
status_code=500,
content={"error": {"code": "config_error", "message": exc.message}},
)
@app.exception_handler(SettleKitConnectionError)
async def _connection_error_handler(_, exc: SettleKitConnectionError) -> JSONResponse:
"""The SettleKit API was unreachable — surface as 502 Bad Gateway."""
return JSONResponse(
status_code=502,
content={
"error": {
"code": "upstream_unreachable",
"message": (
"Could not reach the SettleKit API. Check SETTLEKIT_API_URL "
"and that the API is running."
),
}
},
)
@app.exception_handler(SettleKitError)
async def _settlekit_error_handler(_, exc: SettleKitError) -> JSONResponse:
"""Map a generic SettleKit API error to a faithful HTTP response."""
# Pass client errors (4xx) straight through; treat upstream 5xx as 502.
status = exc.status if 400 <= exc.status < 500 else 502
return JSONResponse(
status_code=status,
content={"error": {"code": exc.code, "message": exc.message}},
)
# ---------------------------------------------------------------------------
# Routes.
# ---------------------------------------------------------------------------
@app.get("/", tags=["public"])
async def landing() -> dict[str, Any]:
"""Public landing page describing the product and its plan tiers."""
return {
"product": "AI Export Pro",
"tagline": "Export AI-generated datasets, gated by SettleKit.",
"feature": sk.get_settings().feature,
"plans": PLAN_TIERS,
"docs": {
"signup": "POST /signup",
"entitlements": "GET /me/entitlements?customer_id=",
"aiExport": "POST /ai/export?customer_id=",
"grantCredits": "POST /billing/grant-credits",
"health": "GET /healthz",
},
}
@app.get("/healthz", tags=["public"])
async def healthz() -> dict[str, str]:
"""Liveness probe. Does not call SettleKit so it stays cheap and reliable."""
return {"status": "ok"}
@app.post("/signup", status_code=201, tags=["accounts"])
async def signup(req: SignupRequest) -> dict[str, Any]:
"""Create a SettleKit customer for this organization."""
settings = sk.get_settings()
customer = await sk.get_client().customers.create(
organization_id=settings.organization_id,
email=req.email,
name=req.name,
metadata={"source": "ai-export-pro"},
)
customer_id = _extract_id(customer)
return {
"customer": customer,
"customerId": customer_id,
"next": f"GET /me/entitlements?customer_id={customer_id}",
}
@app.get("/me/entitlements", tags=["accounts"])
async def my_entitlements(customer_id: str) -> dict[str, Any]:
"""Show the customer's access: entitlement status + prepaid credit balance."""
settings = sk.get_settings()
client = sk.get_client()
entitlement = await client.entitlements.verify(
customer_id=customer_id, feature=settings.feature
)
allowed = (
bool(entitlement.get("allowed")) if isinstance(entitlement, dict) else False
)
credits_payload = await sk.get_credits(customer_id)
credits = credits_payload.get("credits", credits_payload.get("balance", 0))
can_export = allowed or (isinstance(credits, int) and credits > 0)
return {
"customerId": customer_id,
"feature": settings.feature,
"entitled": allowed,
"credits": credits,
"canExport": can_export,
"accessVia": "entitlement"
if allowed
else ("credit" if can_export else "none"),
}
@app.post("/ai/export", tags=["paid"])
async def ai_export(
req: ExportRequest,
grant: AccessGrant = Depends(require_ai_export_access),
) -> dict[str, Any]:
"""PAID feature: produce an AI export.
Reaching this body means the gate (entitlement OR a freshly consumed prepaid
credit) passed. We record the usage event for analytics/billing and return
the export artifact. Denials are handled upstream as 402/403 by the
:class:`GateDenied` exception handler.
"""
# Record the metered-usage event (best-effort; export already authorized).
usage_recorded = True
try:
await sk.record_usage(grant.customer_id, quantity=1)
except SettleKitError:
# Don't fail a paid, authorized export because analytics recording
# hiccuped — but make the degraded state visible in the response.
usage_recorded = False
artifact = _build_export(req)
return {
"ok": True,
"export": artifact,
"access": {
"via": grant.source,
"creditsRemaining": grant.credits_remaining,
},
"usageRecorded": usage_recorded,
}
@app.post("/billing/grant-credits", tags=["admin"])
async def grant_credits(req: GrantCreditsRequest) -> dict[str, Any]:
"""Admin endpoint: grant prepaid credits to a customer.
In a real deployment this route would itself be protected (admin API key /
role). For the demo it calls the SettleKit credit-grant API directly.
"""
granted = await sk.grant_credits(req.customer_id, credits=req.credits)
balance = granted.get("credits", granted.get("balance"))
return {
"ok": True,
"customerId": req.customer_id,
"granted": req.credits,
"balance": balance,
"raw": granted,
}
# ---------------------------------------------------------------------------
# Helpers.
# ---------------------------------------------------------------------------
def _extract_id(payload: Any) -> Optional[str]:
"""Pull the customer id out of a SettleKit customer payload."""
if isinstance(payload, dict):
for key in ("id", "customerId", "customer_id"):
value = payload.get(key)
if value:
return str(value)
return None
def _build_export(req: ExportRequest) -> dict[str, Any]:
"""Produce the (demo) AI export artifact for the requested dataset."""
export_id = f"exp_{uuid.uuid4().hex[:12]}"
rows = [
{"id": 1, "insight": f"Top trend in {req.dataset}", "score": 0.97},
{"id": 2, "insight": f"Emerging signal in {req.dataset}", "score": 0.88},
{"id": 3, "insight": f"Anomaly detected in {req.dataset}", "score": 0.71},
]
return {
"id": export_id,
"dataset": req.dataset,
"format": req.fmt,
"generatedAt": int(time.time()),
"rowCount": len(rows),
"rows": rows,
}
if __name__ == "__main__":
import uvicorn
uvicorn.run("app.main:app", host="0.0.0.0", port=8000, reload=True)