API de facturación y franja

import { stripe } from '@zappway/lib/stripe';

1. User selects a plan in the UI
   POST /api/stripe/create-checkout-session { priceId, successUrl, cancelUrl }
   → Creates Stripe Checkout Session
   → Returns { url } for redirect

2. User completes payment on Stripe-hosted page
   → Stripe redirects to successUrl with ?session_id=...

3. App fetches session result
   GET /api/stripe/get-checkout-session?session_id=...
   → Validates payment success
   → Returns subscription status

4. Stripe fires webhook
   POST /api/stripe/webhook
   → Updates organization subscription in DB

// Webhook signature verification (mandatory)
const event = stripe.webhooks.constructEvent(
  body,
  req.headers.get('stripe-signature'),
  process.env.STRIPE_WEBHOOK_SECRET
);

// Example: Personal Assistant plan gate
import { assertPersonalAssistantPlan } from '@zappway/lib/personal-assistant';
assertPersonalAssistantPlan(req.session); // throws 403 if plan doesn't include feature

// POST /api/stripe/proration-preview
// Body: { newPriceId: string }
// Returns: Stripe InvoicePreviewParams result

// POST /api/stripe/validate-downgrade
// Body: { targetPriceId: string }
// Returns: { canDowngrade: boolean, blockers: string[] }
// blockers example: ['You have 15 active agents, plan limit is 5']