Set Up Stripe Subscription Billing

I need to set up Stripe subscription billing for my SaaS product with multiple pricing tiers, a customer portal, and webhook handling.

Product details:
- App name: [your app name]
- Backend: [e.g. Next.js API routes, Express.js, Python/Flask]
- Database: [e.g. PostgreSQL with Prisma, Supabase, MongoDB]
- Auth system: [e.g. Clerk, NextAuth, Supabase Auth]
- Pricing tiers:
  - Free: $0/mo, [limits, e.g. "1 project, 100 API calls"]
  - Pro: $[X]/mo, [limits, e.g. "10 projects, 10K API calls"]
  - Team: $[Y]/mo, [limits, e.g. "unlimited projects, 100K API calls"]

Set up the complete billing system:

1. Stripe product and price configuration:
   - Create Products for each tier in Stripe Dashboard
   - Create monthly and annual Prices (show annual at [X]% discount)
   - Store the Price IDs as environment variables:
     STRIPE_PRICE_PRO_MONTHLY, STRIPE_PRICE_PRO_ANNUAL, etc.
   - Explain lookup_keys as an alternative to hardcoded Price IDs

2. Checkout session creation:
   - Build an API endpoint that creates a Stripe Checkout Session
   - Pass the customer's email and user ID as metadata
   - Set success_url and cancel_url
   - Include a free trial of [X] days if applicable
   - Show the complete server-side code for [backend framework]

3. Webhook handler:
   - Create a webhook endpoint at /api/webhooks/stripe
   - Verify the webhook signature using STRIPE_WEBHOOK_SECRET
   - Handle these events (give me the exact code for each):
     - checkout.session.completed -> create subscription record, update user plan
     - customer.subscription.updated -> handle plan changes (upgrade/downgrade)
     - customer.subscription.deleted -> revert user to Free tier
     - invoice.payment_failed -> flag the account, send warning
   - Store subscription status, current_period_end, and stripe_customer_id in my database

4. Customer portal:
   - Create a Stripe Billing Portal configuration
   - Build an API endpoint that generates a portal session URL
   - Let users manage their own plan changes, payment methods, and cancellations
   - Show me the 5 lines of code to redirect a user to their portal

5. Entitlement checks:
   - Create a helper function: getUserPlan(userId) that returns the current plan and limits
   - Show me middleware that blocks API calls when a user exceeds their tier limits
   - Add a grace period of [X] hours after payment failure before restricting access

6. Testing:
   - List the Stripe test card numbers for: successful payment, declined card, 3D Secure
   - Show me how to test webhooks locally using Stripe CLI
   - Walk through a full test: signup -> checkout -> webhook -> plan active

Give me production-ready code, not pseudocode. Include error handling and TypeScript types where applicable.