175 lines
7.4 KiB
Markdown
Raw Permalink Normal View History

2026-06-17 02:09:36 +03:00
# AI Export Pro — FastAPI SaaS gated by SettleKit
A complete, **runnable** demo SaaS built with FastAPI. It sells a single paid
feature — an "AI export" — and gates it behind **SettleKit entitlements** with a
**prepaid-credit** fallback, using the real [SettleKit Python SDK](../../sdks/python)
(`import settlekit`) and HTTP API. There is no mock data and no fake gate: every
handler calls SettleKit.
## Access policy
A `POST /ai/export` call is allowed when **either** of these is true:
1. The customer holds the **`ai_export` entitlement** (e.g. an active Pro plan) —
verified via `verify_entitlement` / `entitlements.verify`. Unlimited, no
credit spent.
2. The customer has a **prepaid credit** — one credit is atomically consumed via
the SettleKit usage API. Pay-as-you-go.
Otherwise the request is denied with **402 Payment Required** (out of
credits/entitlement) carrying a friendly upgrade message.
## Layout
```
examples/python-saas/
├── requirements.txt # fastapi, uvicorn, httpx, editable SDK
├── pyproject.toml # optional project metadata
├── README.md
└── app/
├── __init__.py
├── main.py # FastAPI app + routes + error handlers
├── deps.py # the entitlement/credit gate dependency
└── settlekit_client.py # constructs the SDK client + credit helpers
```
## Endpoints
| Method | Path | Purpose |
|--------|----------------------------------------|-------------------------------------------|
| GET | `/` | Public landing JSON (plan tiers) |
| GET | `/healthz` | Liveness probe (no SettleKit call) |
| POST | `/signup` | Create a SettleKit customer |
| GET | `/me/entitlements?customer_id=` | Show entitlement + credit balance |
| POST | `/ai/export?customer_id=` | **PAID** — gated AI export |
| POST | `/billing/grant-credits` | Admin: grant prepaid credits |
## Environment variables
| Variable | Required | Default | Description |
|------------------------|----------|--------------------------|------------------------------------------------------|
| `SETTLEKIT_API_KEY` | yes | — | Bearer key sent on every request (`Authorization`). |
| `SETTLEKIT_ORG_ID` | yes | — | Organization id customers/usage are scoped to. |
| `SETTLEKIT_API_URL` | no | `http://localhost:8787` | SettleKit API base URL. |
| `SETTLEKIT_PRODUCT_ID` | no | `ai_export` | Product id recorded against metered usage. |
| `AI_EXPORT_FEATURE` | no | `ai_export` | Entitlement feature key the paid route checks. |
The app validates required vars at startup and fails fast with a clear message.
## Install & run
> The SDK is installed in editable mode from the monorepo via `requirements.txt`.
```bash
cd examples/python-saas
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# (equivalently: pip install fastapi "uvicorn[standard]" httpx -e ../../sdks/python)
export SETTLEKIT_API_KEY="sk_live_..." # your SettleKit API key
export SETTLEKIT_ORG_ID="org_123" # your organization id
export SETTLEKIT_API_URL="http://localhost:8787" # optional
uvicorn app.main:app --reload --port 8000
```
Make sure the SettleKit API is running and reachable at `SETTLEKIT_API_URL`, and
that the `ai_export` feature/product exists in your organization (so entitlement
verification and credit grants resolve).
## Full curl walkthrough
### 0) Landing page (public)
```bash
curl -s http://localhost:8000/ | python3 -m json.tool
```
### 1) Sign up — create a customer
```bash
curl -s -X POST http://localhost:8000/signup \
-H 'Content-Type: application/json' \
-d '{"email":"ada@example.com","name":"Ada Lovelace"}' | python3 -m json.tool
```
Copy the returned `customerId` (referred to as `$CID` below):
```bash
CID="cus_...." # paste the id from the signup response
```
### 2) Check access (should be denied — no entitlement, no credits)
```bash
curl -s "http://localhost:8000/me/entitlements?customer_id=$CID" | python3 -m json.tool
# -> { "entitled": false, "credits": 0, "canExport": false, "accessVia": "none" }
```
### 3) Try the paid export — DENIED (402)
```bash
curl -s -i -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"csv"}'
# -> HTTP/1.1 402 Payment Required
# -> {"error":{"code":"payment_required","message":"AI export is a paid feature...","upgradeUrl":"/#pricing"}}
```
### 4a) Grant prepaid credits (admin) — then export is ALLOWED via credit
```bash
curl -s -X POST http://localhost:8000/billing/grant-credits \
-H 'Content-Type: application/json' \
-d "{\"customer_id\":\"$CID\",\"credits\":5}" | python3 -m json.tool
curl -s -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"csv"}' | python3 -m json.tool
# -> { "ok": true, "export": {...}, "access": {"via":"credit","creditsRemaining":4} }
```
Each successful credit-based export consumes one credit. Re-check the balance:
```bash
curl -s "http://localhost:8000/me/entitlements?customer_id=$CID" | python3 -m json.tool
```
### 4b) Alternatively, grant the `ai_export` entitlement — unlimited exports
Grant the entitlement in SettleKit (e.g. by attaching the `ai_export` feature to
the customer through a Pro subscription or directly via the SettleKit dashboard /
API). Once `POST /v1/entitlements/verify` returns `{"allowed": true}` for the
customer, exports succeed **without** spending credits:
```bash
curl -s -X POST "http://localhost:8000/ai/export?customer_id=$CID" \
-H 'Content-Type: application/json' \
-d '{"dataset":"q2-sales","fmt":"json"}' | python3 -m json.tool
# -> { "ok": true, "access": {"via":"entitlement","creditsRemaining":null} }
```
## How it works
- **`app/settlekit_client.py`** constructs one process-wide `AsyncSettleKit`
client from env vars (closed on app shutdown). It also wraps the prepaid-credit
and metered-usage endpoints (`/v1/usage/credits`, `/v1/usage/credits/grant`,
`/v1/usage/credits/consume`, `/v1/usage/record`) through the SDK's low-level
`arequest` method.
- **`app/deps.py`** is the gate: a FastAPI dependency that (1) calls
`entitlements.verify`, then (2) falls back to atomically consuming a credit.
Denials raise `GateDenied`; genuine SettleKit/API failures propagate so they
surface as 5xx rather than being mistaken for a billing decision.
- **`app/main.py`** wires the routes, validates input with Pydantic, records
usage after a successful export, and maps `GateDenied` / `SettleKitError` to
clean HTTP responses (402/403 for billing, 502 for upstream outages, 500 for
misconfiguration).
## Notes
- Money is represented as `{"amount": "25.00", "currency": "USDC"}`, matching the
SettleKit API convention (see the plan tiers on `GET /`).
- The admin route `POST /billing/grant-credits` is left open for the demo. In
production, protect it with an admin API key / role check.