Add docs

docs/STRIPE_SETUP.md

@@ -0,0 +1,119 @@
+# Stripe Setup Guide (Development)
+
+This guide provides step-by-step instructions for setting up a Stripe test account and configuring payments for Kaboot in your local development environment.
+
+## Overview
+
+Kaboot uses Stripe to manage subscriptions for "AI Pro" access. Users get 250 AI quiz generations per month with a paid subscription, while free users are limited to 5.
+
+## Prerequisites
+
+1.  A [Stripe Account](https://dashboard.stripe.com/register).
+2.  [Stripe CLI](https://stripe.com/docs/stripe-cli) installed on your machine.
+3.  Kaboot local development environment running (see [README.md](../README.md)).
+
+---
+
+## 1. Stripe Dashboard Configuration
+
+### Step 1: Enable Test Mode
+Log in to your Stripe Dashboard and ensure the **Test Mode** toggle (usually in the top right) is turned **ON**.
+
+### Step 2: Create a Product
+1.  Navigate to **Products** > **Add Product**.
+2.  **Name**: `Kaboot AI Pro`
+3.  **Description**: `250 AI quiz generations per month`
+4.  **Pricing**:
+    *   **Price 1**: $5.00 USD, Recurring, Monthly.
+    *   **Price 2**: $50.00 USD, Recurring, Yearly.
+5.  Click **Save Product**.
+
+### Step 3: Get Price IDs
+After saving, copy the **API IDs** for both prices. They look like `price_1P...`. You will need these for your environment variables.
+
+---
+
+## 2. Environment Configuration
+
+Add the following variables to your `.env` file in the project root:
+
+```env
+# Stripe API Keys (Test Mode)
+# Found at: https://dashboard.stripe.com/test/apikeys
+STRIPE_SECRET_KEY=sk_test_51P...
+
+# Stripe Price IDs (from Step 3 above)
+STRIPE_PRICE_ID_MONTHLY=price_...
+STRIPE_PRICE_ID_YEARLY=price_...
+
+# Stripe Webhook Secret (Leave empty initially, see Section 3)
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+> **Note**: In development, `STRIPE_SECRET_KEY` should always start with `sk_test_`.
+
+---
+
+## 3. Webhook Setup (Local Development)
+
+Stripe needs to send events (like successful payments) to your local server. Since Stripe cannot access `localhost` directly, you must use the Stripe CLI to forward events.
+
+### Step 1: Login to Stripe CLI
+```bash
+stripe login
+```
+
+### Step 2: Start Forwarding
+Run the following command in a new terminal window:
+
+```bash
+stripe listen --forward-to localhost:3001/api/payments/webhook
+```
+
+### Step 3: Get Webhook Secret
+The command above will output a **webhook signing secret** (e.g., `whsec_abc123...`). 
+1.  Copy this secret.
+2.  Paste it into your `.env` file as `STRIPE_WEBHOOK_SECRET`.
+3.  **Restart your backend server** to apply the changes.
+
+---
+
+## 4. Testing the Flow
+
+### Test Credit Card
+Use Stripe's [test card numbers](https://stripe.com/docs/testing#cards). The most common is:
+*   **Card Number**: `4242 4242 4242 4242`
+*   **Expiry**: Any future date
+*   **CVC**: Any 3 digits
+*   **Zip**: Any 5 digits
+
+### Webhook Events to Monitor
+When testing, watch your `stripe listen` terminal. You should see:
+- `checkout.session.completed`: When a user finishes the payment.
+- `customer.subscription.updated`: When status changes.
+- `invoice.paid`: When the monthly/yearly bill is settled (resets generation counts).
+
+---
+
+## 5. Troubleshooting
+
+### Webhook Signature Mismatch
+**Error**: `Webhook signature verification failed`
+- **Solution**: Ensure `STRIPE_WEBHOOK_SECRET` in `.env` matches the secret shown in your `stripe listen` output. Each time you run `stripe listen`, a new secret might be generated if not configured as a permanent endpoint.
+
+### Missing Keys
+**Error**: `Stripe API Key not found`
+- **Solution**: Verify `STRIPE_SECRET_KEY` is set in the `.env` file that the **backend** (server) is reading.
+
+### Checkout Session Fails
+**Error**: `No such price: price_...`
+- **Solution**: Ensure your `STRIPE_PRICE_ID_MONTHLY` and `STRIPE_PRICE_ID_YEARLY` variables match the Price IDs in your Stripe **Test Mode** dashboard.
+
+---
+
+## Technical Details
+
+- **Webhook Endpoint**: `POST /api/payments/webhook`
+- **Checkout Initiation**: `POST /api/payments/checkout`
+- **Billing Portal**: `POST /api/payments/portal` (Allows users to manage/cancel subscriptions)
+- **Database Fields**: User subscription status is stored in the `users` table (`subscription_status`, `generation_count`, etc.).