# Product Requirements Document (PRD)

## 1. Problem & Goals
SaaS API with:
- **FREE**: hard cap **10,000** requests/month (API Gateway Usage Plan).
- **METERED**: first **10,000** requests/month free, then **$0.10 per additional 1,000** requests (graduated). Stripe invoices; system reports usage.

Principles:
- **Near zero-ops**: Stripe manages billing lifecycle. You react via **Event Destinations → EventBridge → Lambdas**.
- **Developer Portal (REST)**: Usage by **API keys + Usage Plans**; migrate keys between plans based on Stripe state.
- **Separation**: `augint-billing-lib` (pure Python, testable) and `augint-billing-infra` (SAM wiring).

## 2. Key Integrations
- Stripe **Payment Links** now; add **Customer Portal** later.
- Event flow: Stripe → EventBridge (partner) → Lambda handlers.
- Hourly usage reporter: API Gateway `GetUsage` → Stripe **Usage Records** for the **subscription item** of the metered price.

## 3. Environments
- **staging**: Stripe test mode; **prod**: live.
- Non-secrets via `.env` (chezmoi); secrets via **AWS Secrets Manager** (JSON).

## 4. Acceptance
- Card attached → promote to METERED within 1 minute.
- Payment failure → demote to FREE within 1 minute.
- Hourly reporter correct deltas (idempotent), month rollover safe.
- FREE users hard-blocked at 10k/month.
