Kordant/tasks/kordant-unified-restructure/13-subscription-billing-router.md

# 13. Backend Router — Subscriptions, Billing, and Stripe Webhooks

meta:
  id: kordant-unified-restructure-13
  feature: kordant-unified-restructure
  priority: P1
  depends_on: [kordant-unified-restructure-11]
  tags: [backend, trpc, billing, stripe, api]

objective:
- Build the tRPC router for subscription management and Stripe billing integration. Port logic from `packages/shared-billing/` and `packages/api/src/routes/subscription.routes.ts` into a unified `billing` router.

deliverables:
- `web/src/server/api/routers/billing.ts` — Billing router with procedures:
  - `billing.getSubscription` — `protectedProcedure` returning current subscription with tier
  - `billing.createCheckoutSession` — `protectedProcedure` creating Stripe checkout for plan upgrade
  - `billing.createPortalSession` — `protectedProcedure` creating Stripe Customer Portal
  - `billing.cancelSubscription` — `protectedProcedure` scheduling cancellation at period end
  - `billing.reactivateSubscription` — `protectedProcedure` reactivating a canceled subscription
  - `billing.listInvoices` — `protectedProcedure` returning Stripe invoices for user
  - `billing.webhook` — `publicProcedure` (or raw endpoint) handling Stripe webhook events
- `web/src/server/services/billing.service.ts` — Business logic:
  - `getOrCreateCustomer(userId, email)` — Stripe customer management
  - `createCheckoutSession(userId, priceId, successUrl, cancelUrl)`
  - `createPortalSession(customerId, returnUrl)`
  - `handleWebhookEvent(event)` — processes `checkout.session.completed`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated`, `customer.subscription.deleted`
  - `updateSubscriptionInDB(subscriptionId, stripeEventData)` — syncs Stripe state to Drizzle
- `web/src/routes/api/stripe/webhook.ts` — Raw SolidStart API route for Stripe webhooks:
  - Verifies Stripe signature using `stripe.webhooks.constructEvent`
  - Forwards to billing service
- Zod schemas in `web/src/server/api/schemas/billing.ts`
- Stripe client initialization in `web/src/server/stripe.ts`

steps:
1. Install `stripe` npm package in `web/`.
2. Create `web/src/server/stripe.ts`:
   - Initialize Stripe client with `process.env.STRIPE_SECRET_KEY`
   - Export `stripe` instance
3. Create `web/src/server/services/billing.service.ts`:
   - `getOrCreateCustomer`: query DB for existing `stripeCustomerId`, or create via Stripe API and save to DB
   - `createCheckoutSession`: create Stripe Checkout session with `subscription` mode, return URL
   - `createPortalSession`: create Stripe Billing Portal session
   - `handleWebhookEvent`: switch on event type:
     - `checkout.session.completed` → create/update subscription record, set tier
     - `invoice.paid` → update subscription status to active
     - `invoice.payment_failed` → update status to past_due, send notification
     - `customer.subscription.updated` → sync tier, status, period dates
     - `customer.subscription.deleted` → mark as canceled
4. Create `web/src/server/api/routers/billing.ts`:
   - `getSubscription`: query user's active subscription, include tier details
   - `createCheckoutSession`: validate price ID against allowed prices, call service, return session URL
   - `createPortalSession`: call service, return portal URL
   - `cancelSubscription`: update Stripe subscription to `cancel_at_period_end`, update DB
   - `reactivateSubscription`: remove `cancel_at_period_end`, update DB
   - `listInvoices`: fetch Stripe invoices for customer, return paginated list
5. Create `web/src/routes/api/stripe/webhook.ts`:
   - SolidStart API route (not tRPC — Stripe needs raw body for signature verification)
   - Read raw body from request
   - Verify signature with `STRIPE_WEBHOOK_SECRET`
   - Call `billingService.handleWebhookEvent`
   - Return 200 for success, 400 for invalid signature, 500 for processing errors
6. Define Zod schemas for all inputs (priceId, successUrl, etc.).
7. Wire router into `web/src/server/api/root.ts`.
8. Write unit tests for billing service (mock Stripe API calls).

steps:
- Unit: `getOrCreateCustomer` returns existing customer or creates new one
- Unit: `handleWebhookEvent` correctly updates subscription status for each event type
- Unit: Stripe signature verification rejects invalid signatures
- Integration: `billing.getSubscription` returns subscription for authenticated user
- Integration: Checkout session creation returns valid Stripe URL

acceptance_criteria:
- [ ] `billing.getSubscription` returns current subscription with tier and status
- [ ] `billing.createCheckoutSession` creates a Stripe checkout session and returns the URL
- [ ] `billing.createPortalSession` creates a Stripe customer portal session
- [ ] `billing.cancelSubscription` sets `cancelAtPeriodEnd` in Stripe and DB
- [ ] `billing.reactivateSubscription` removes cancellation flag
- [ ] Stripe webhook endpoint correctly handles all relevant event types
- [ ] Webhook signature verification prevents spoofed requests
- [ ] Subscription tier changes correctly gate features (enforced in other routers)

validation:
- Use Stripe CLI to trigger test webhooks: `stripe listen --forward-to localhost:3000/api/stripe/webhook`
- Verify webhook handler responds 200 and updates DB correctly
- Test checkout flow with Stripe Test Mode
- Run `cd web && pnpm test` for billing unit tests

notes:
- Reference legacy: `packages/shared-billing/src/`, `packages/api/src/routes/subscription.routes.ts`
- Store Stripe price IDs in environment variables or a config file:
  - `STRIPE_PRICE_BASIC`, `STRIPE_PRICE_PLUS`, `STRIPE_PRICE_PREMIUM`
- The webhook endpoint MUST receive the raw request body, not parsed JSON. In SolidStart, use `request.text()` before any parsing.
- Ensure idempotency: webhook events may be delivered multiple times. Use Stripe event ID to deduplicate.
- For the tier enum in Drizzle schema, ensure it matches Stripe product metadata or price IDs.
- Consider adding a `billing.history` procedure that returns payment history from Stripe invoices.