175 lines
7.4 KiB
Markdown
175 lines
7.4 KiB
Markdown
|
|
# 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.
|