352 lines
12 KiB
Python
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)
|