Session Handoff — Bookify AI Studio: billing/metering money spine (backend built + deployed)

Where it started

Continuing the BookifAI build (children's/general KDP book SaaS, cloned off Lovable onto Sondra's own stack). She chose to build billing/metering next. Session was a long design discussion that locked the free-plan spec, caps, refund rules, and positioning, then built + deployed the backend "money spine." Nothing is public; Stripe is in TEST mode; app has 0 real users.

Decisions locked + what shipped

• Free plan (locked): FREE = full story text + 1 cover illustration + watermarked in-app reading. LOCKED until $29 = all downloads (KDP print PDF, ebook) + KDP how-to/launch kit. 1 lifetime free book/account (counted by books-ever-created, no delete-and-remake). Cover re-rolls capped at 3 on free; per-story Illustrate/Redraw disabled on free (cover only). Email confirmation required on prod (auto-confirm OFF).
• Metering rule (locked): text edits/rewrites = unlimited & free; images = metered (15 included/paid book, re-rolls count, ~40 hard ceiling, extra $9/25 credits).
• Refunds (locked): image credits non-refundable + disclosed at the generate button; auto-refund only on technical failure; $29 = all-sales-final once paid art generated OR files downloaded.
• Positioning correction: NOT children-only; illustrations general-purpose; children's is one template/mode. Add illustration-idea suggestions + upload-a-similar-reference.
• BYO images: users upload their own image for any page/cover, FREE, does NOT count against 15/40 caps. Show KDP sizing (8x10 -> 2438x3075px, 300 DPI, no text, full-bleed).
• Cover typography: art generated text-free (already the rule); title overlays as real editable text. v1 = font/color/placement; v2 = full editor (later). All in PRD.md section 7.7.
• Model decision: no Fable; built directly here with a verify loop. Confirmed by Sondra.
• Data model applied to live DB (project umnlokuehteqwrheoyai): tables profiles, book_meters, purchases — RLS on, read-own only, server-write-only (no user write policies); signup trigger auto-creates profile; project trigger auto-creates book_meter. Migration billing_money_spine. Local copy: c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\migrations\20260705000000_billing_money_spine.sql.
• Atomic grant fn applied to live DB: apply_purchase(...) — records purchase (idempotent via unique stripe_event_id) + grants entitlement/credits in one transaction; execute revoked from public/anon/authenticated, granted to service_role only. Migration billing_apply_purchase_fn (MCP-only, no local file yet).
• Stripe TEST products created on her real account (RvzUwDwHkj): Single $29 price_1Tq2waRvzUwDwHkj3fQI5qy2, Author Pack $79 price_1Tq2waRvzUwDwHkjNujqRWdE, Image Credits $9 price_1Tq2wbRvzUwDwHkjvc3q9Kb0. Saved: c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\stripe-test-products.json.
• Stripe TEST webhook endpoint we_1Tq36BRvzUwDwHkj39V7Q7rv -> deployed function, event checkout.session.completed.
• Edge functions written + deployed: create-checkout (verify_jwt=true, ownership-checked) and stripe-webhook (verify_jwt=false, signature-verified). config.toml sets webhook verify_jwt=false.
• Edge secrets set (Supabase): STRIPE_SECRET_KEY (test), STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_SINGLE, STRIPE_PRICE_AUTHOR_PACK, STRIPE_PRICE_IMAGE_CREDITS. (SUPABASE_URL/SERVICE_ROLE_KEY/ANON_KEY auto-provided.)

Key files for next session

• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\PRD.md — read section 7.7 first (the locked billing/metering/refund spec + next-build backlog).
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\functions\create-checkout\index.ts
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\functions\stripe-webhook\index.ts
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\migrations\20260705000000_billing_money_spine.sql
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\stripe-test-products.json — price IDs for checkout.
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\src\components\create-book\BookPreview.tsx + ExportOptions.tsx — where Buy/Unlock buttons + gates attach next.
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\functions\generate-illustration\index.ts — currently UNAUTH + UNMETERED; the image gate goes here.
• Plan file: none (PRD is the spec).
• Memory files touched: none.

Running state

• Background processes: none. (A find was run in background earlier this session; it completed — nothing to kill.)
• Dev servers / ports: none started this session. To run: cd "PROJECTS/Bookify AI Studio/app" && npm run dev -> localhost:8080 (kill stale node if 8080-8083 busy).
• Open worktrees / branches: none (working on main of the cloned repo, local only, nothing pushed).

Verification — how to confirm things still work

• Supabase MCP list_tables project umnlokuehteqwrheoyai -> confirm profiles, book_meters, purchases exist, RLS on.
• curl -s -o /dev/null -w "%{http_code}" -X POST https://umnlokuehteqwrheoyai.supabase.co/functions/v1/create-checkout -H "Authorization: Bearer <VITE anon key>" -H "Content-Type: application/json" -d '{"product":"single","projectId":"0","origin":"http://localhost:8080"}' -> expect 401.
• curl -s -o /dev/null -w "%{http_code}" -X POST https://umnlokuehteqwrheoyai.supabase.co/functions/v1/stripe-webhook -H "stripe-signature: t=1,v1=forged" -d '{}' -> expect 400.
• apply_purchase grant/idempotency already SQL-verified this session (grants once, duplicate event returns false, book->paid, +25/+5 credits).
• Redeploy pattern: TOKEN=$(python -c "import re,pathlib;print(re.findall(r'sbp_[A-Za-z0-9]+',pathlib.Path.home().joinpath('.claude.json').read_text(encoding='utf-8'))[0])"); CLI ~/AppData/Local/Programs/cli-bin/supabase.exe; SUPABASE_ACCESS_TOKEN=$TOKEN supabase.exe functions deploy <name> --project-ref umnlokuehteqwrheoyai.
• Typecheck: cd "PROJECTS/Bookify AI Studio/app" && npx tsc --noEmit.

Deferred + open questions

• Deferred (NOT built): the live test-card round-trip (real 4242 card -> Stripe delivers webhook -> book flips to paid) — needs client Buy button + app running + test user + browser. Only the grant logic + endpoint boundaries are verified so far.
• Deferred (NOT built): all server-side gates — free=cover-only + 3 re-roll cap, downloads locked until paid, images metered 15/40, text stays free. generate-illustration is currently unauthenticated + unmetered; project/book creation likely direct client insert (free-book "claim" logic must be added server-side).
• Deferred: watermark free preview; BYO image upload + sizing UI; refund disclosure copy + auto-refund-on-failure; auto-confirm OFF for prod; regenerate stale app/src/integrations/supabase/types.ts (live DB has children's cols + new billing tables it doesn't reflect); /app-safety-check before any deploy.
• Deferred: flip Stripe TEST -> LIVE at launch (live key STRIPE_API_KEY_MAIN in master .env) — create live products + live webhook endpoint + reset secrets.
• Deferred (post-billing next-build backlog, PRD section 7.7): v1 cover typography overlay; visual style showcase + broaden styles; illustration-idea suggestions; Pillar A market research.
• Open (design detail for the gates step): how book #2+ is entitled at creation time — consume an Author-Pack book_credits vs require a $29 Single before images/downloads unlock; and where the free-book "claim" (set profiles.free_book_claimed=true, meter entitlement='free') is enforced.
• Open: Stripe receipt/statement branding (account-wide, low priority, her call).

Pick up here

Build the client Buy/Unlock buttons (call create-checkout, redirect to Stripe) and run the live test-card round-trip to prove the webhook grants access, then build the server-side gates (starting with authenticating + metering generate-illustration).