Add POST /api/v1/stripe/create-subscription-checkout endpoint with
get_or_create_stripe_customer (SELECT FOR UPDATE), plan_id→price_id
mapping from env vars, active subscription guard (409), and
session_id in success URL. Add GET /verify-checkout-session endpoint
for server-side payment verification. Add /subscription-success
frontend page with loading/verified/failed states.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Keeps subscription SaaS vision from PRD while adding accurate as-is
analysis of existing code. Each story now has an "As-Is" table showing
what exists and where the gaps are.
Key points:
- Story 3.5: Transition from BYOK to system-managed models with token
billing. BYOK stays for self-hosted mode (deployment_mode=self-hosted),
system models + subscription quota for hosted mode.
- Story 5.1: Pricing UI exists (Free/PAYG/Enterprise) but needs redesign
to subscription tiers (Free/Pro) with monthly/yearly toggle.
- Story 5.2: PAYG checkout exists (mode=payment), need NEW subscription
endpoint (mode=subscription) with stripe_customer_id binding.
- Story 5.3: Webhook infrastructure exists (signature verify, PAYG handlers).
Need subscription event handlers (customer.subscription.*) alongside.
- Story 5.4: PageLimitService fully implemented. Gap is HTTP-layer pre-check,
plan-based limits, frontend quota indicator, and 402 error handling.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Stories were written for a subscription SaaS model, but SurfSense is a
self-hosted product with BYOK + optional PAYG page packs via Stripe.
Key corrections:
- Story 3.5: Not "remove BYOK + token billing" → actual gap is adding
HTTP-layer quota pre-check before document upload enqueue
- Story 5.1: Pricing UI already exists (Free/PAYG/Enterprise) → gap is
wiring "Get Started" button to existing Stripe checkout endpoint
- Story 5.2: mode=payment PAYG already works → needs verification/hardening
not a subscription checkout rewrite
- Story 5.3: Webhook already handles checkout.session.completed correctly
→ no subscription events needed, gap is idempotency test + purchase history UI
- Story 5.4: PageLimitService + enforcement in tasks/connectors already exists
→ gap is HTTP-layer pre-check, quota UI indicator, and 402 frontend handling
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
