feat: implement AI chat with vector search and random loading messages

Major Features: - ✅ AI chat with Azure OpenAI GPT-4o integration - ✅ Vector search across Bible versions (ASV English, RVA 1909 Spanish) - ✅ Multi-language support with automatic English fallback - ✅ Bible version citations in responses [ASV] [RVA 1909] - ✅ Random Bible-themed loading messages (5 variants) - ✅ Safe build script with memory guardrails - ✅ 8GB swap memory for build safety - ✅ Stripe donation integration (multiple payment methods) AI Chat Improvements: - Implement vector search with 1536-dim embeddings (Azure text-embedding-ada-002) - Search all Bible versions in user's language, fallback to English - Cite Bible versions properly in AI responses - Add 5 random loading messages: "Searching the Scriptures...", etc. - Fix Ollama conflict (disabled to use Azure OpenAI exclusively) - Optimize hybrid search queries for actual table schema Build & Infrastructure: - Create safe-build.sh script with memory monitoring (prevents server crashes) - Add 8GB swap memory for emergency relief - Document build process in BUILD_GUIDE.md - Set Node.js memory limits (4GB max during builds) Database: - Clean up 115 old vector tables with wrong dimensions - Keep only 2 tables with correct 1536-dim embeddings - Add Stripe schema for donations and subscriptions Documentation: - AI_CHAT_FINAL_STATUS.md - Complete implementation status - AI_CHAT_IMPLEMENTATION_COMPLETE.md - Technical details - BUILD_GUIDE.md - Safe building guide with guardrails - CHAT_LOADING_MESSAGES.md - Loading messages implementation - STRIPE_IMPLEMENTATION_COMPLETE.md - Stripe integration docs - STRIPE_SETUP_GUIDE.md - Stripe configuration guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-12 19:37:24 +00:00
parent b3ec31a265
commit a01377b21a
20 changed files with 3022 additions and 130 deletions
--- a/STRIPE_SETUP_GUIDE.md
+++ b/STRIPE_SETUP_GUIDE.md
@@ -0,0 +1,222 @@
+# Stripe Integration Setup Guide
+
+This guide will help you complete the Stripe integration for Biblical Guide donations.
+
+## What Has Been Implemented
+
+### 1. Database Schema
+- Added `Donation` model to Prisma schema with the following fields:
+  - Stripe session and payment IDs
+  - Donor information (email, name, message)
+  - Amount and currency
+  - Status tracking (PENDING, COMPLETED, FAILED, REFUNDED, CANCELLED)
+  - Anonymous and recurring donation support
+- Database has been synced with `prisma db push`
+
+### 2. Backend API Routes
+- **`/api/stripe/checkout`** - Creates Stripe checkout sessions
+- **`/api/stripe/webhook`** - Handles Stripe webhook events for payment status updates
+
+### 3. Frontend Pages
+- **`/[locale]/donate`** - Main donation page with form
+- **`/[locale]/donate/success`** - Success confirmation page after donation
+
+### 4. Utility Functions
+- **`lib/stripe.ts`** - Stripe initialization and helper functions
+
+## Setup Instructions
+
+### Step 1: Get Stripe API Keys
+
+1. Go to [Stripe Dashboard](https://dashboard.stripe.com/)
+2. Sign up or log in to your account
+3. Navigate to **Developers > API keys**
+4. Copy your keys:
+   - **Publishable key** (starts with `pk_`)
+   - **Secret key** (starts with `sk_`)
+
+### Step 2: Configure Environment Variables
+
+Update your `.env.local` file with your actual Stripe keys:
+
+```bash
+# Stripe
+STRIPE_SECRET_KEY=sk_test_your_actual_secret_key_here
+STRIPE_PUBLISHABLE_KEY=pk_test_your_actual_publishable_key_here
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_actual_publishable_key_here
+```
+
+**Important Notes:**
+- Use **test keys** (starting with `sk_test_` and `pk_test_`) for development
+- Use **live keys** (starting with `sk_live_` and `pk_live_`) for production
+- The `NEXT_PUBLIC_` prefix makes the key available in the browser
+
+### Step 3: Set Up Stripe Webhook
+
+Webhooks are crucial for updating donation status when payments complete.
+
+#### For Development (Local Testing)
+
+1. Install Stripe CLI:
+   ```bash
+   # On Linux
+   wget https://github.com/stripe/stripe-cli/releases/download/v1.19.5/stripe_1.19.5_linux_x86_64.tar.gz
+   tar -xvf stripe_1.19.5_linux_x86_64.tar.gz
+   sudo mv stripe /usr/local/bin/
+   ```
+
+2. Login to Stripe CLI:
+   ```bash
+   stripe login
+   ```
+
+3. Forward webhook events to your local server:
+   ```bash
+   stripe listen --forward-to localhost:3010/api/stripe/webhook
+   ```
+
+4. Copy the webhook signing secret (starts with `whsec_`) and add it to your `.env.local` file
+
+#### For Production
+
+1. Go to [Stripe Dashboard > Webhooks](https://dashboard.stripe.com/webhooks)
+2. Click **Add endpoint**
+3. Enter your webhook URL: `https://biblical-guide.com/api/stripe/webhook`
+4. Select events to listen to:
+   - `checkout.session.completed`
+   - `checkout.session.expired`
+   - `payment_intent.payment_failed`
+   - `charge.refunded`
+5. Copy the webhook signing secret and add it to your production `.env.local` (or use environment variables in your hosting platform)
+
+### Step 4: Test the Integration
+
+1. Start your development server:
+   ```bash
+   npm run dev
+   ```
+
+2. Start the Stripe CLI webhook forwarding (in another terminal):
+   ```bash
+   stripe listen --forward-to localhost:3010/api/stripe/webhook
+   ```
+
+3. Visit `http://localhost:3010/en/donate` (or your locale)
+
+4. Test a donation using Stripe test cards:
+   - **Success:** `4242 4242 4242 4242`
+   - **Decline:** `4000 0000 0000 0002`
+   - **Requires Auth:** `4000 0025 0000 3155`
+   - Use any future expiry date, any 3-digit CVC, and any ZIP code
+
+5. Check the Stripe CLI output to see webhook events
+
+6. Verify the donation status in your database:
+   ```bash
+   npx prisma studio
+   ```
+
+### Step 5: Enable Recurring Donations (Optional)
+
+Recurring donations are already implemented in the code. To enable them in Stripe:
+
+1. Go to [Stripe Dashboard > Products](https://dashboard.stripe.com/products)
+2. The system will automatically create products when users make recurring donations
+3. Subscriptions will appear in [Stripe Dashboard > Subscriptions](https://dashboard.stripe.com/subscriptions)
+
+## Features Included
+
+### Donation Form Features
+- ✅ Preset donation amounts ($5, $10, $25, $50, $100, $250)
+- ✅ Custom donation amount input
+- ✅ One-time and recurring donations (monthly/yearly)
+- ✅ Donor information (email, name, message)
+- ✅ Anonymous donation option
+- ✅ Secure Stripe Checkout redirect
+- ✅ Success confirmation page
+- ✅ Email receipt from Stripe
+
+### Backend Features
+- ✅ Stripe checkout session creation
+- ✅ Webhook handling for payment events
+- ✅ Database tracking of all donations
+- ✅ Status updates (pending → completed/failed/cancelled)
+- ✅ Support for refunds
+- ✅ Metadata storage for additional info
+
+### Security Features
+- ✅ Webhook signature verification
+- ✅ Server-side payment processing
+- ✅ No card details stored on your server
+- ✅ PCI compliance through Stripe
+
+## File Structure
+
+```
+/root/biblical-guide/
+├── app/
+│   ├── api/
+│   │   └── stripe/
+│   │       ├── checkout/
+│   │       │   └── route.ts          # Create checkout session
+│   │       └── webhook/
+│   │           └── route.ts          # Handle webhook events
+│   └── [locale]/
+│       └── donate/
+│           ├── page.tsx              # Donation form
+│           └── success/
+│               └── page.tsx          # Success page
+├── lib/
+│   └── stripe.ts                     # Stripe utilities
+├── prisma/
+│   └── schema.prisma                 # Database schema (Donation model)
+└── .env                              # Environment variables
+```
+
+## Troubleshooting
+
+### Issue: "No signature" error in webhook
+**Solution:** Make sure Stripe CLI is running with the correct forward URL
+
+### Issue: Webhook events not received
+**Solution:** Check that your webhook secret is correct in `.env.local`
+
+### Issue: "Invalid API key" error
+**Solution:** Verify your Stripe keys are correct and match the environment (test/live)
+
+### Issue: Donation status stays PENDING
+**Solution:** Check webhook events are being received and processed correctly
+
+## Going Live Checklist
+
+Before launching in production:
+
+- [ ] Switch to live Stripe API keys (not test keys)
+- [ ] Set up production webhook endpoint in Stripe Dashboard
+- [ ] Update `NEXTAUTH_URL` in `.env.local` to production URL (or use environment variables in hosting platform)
+- [ ] Test a real payment with a real card
+- [ ] Set up Stripe email receipts (in Stripe Dashboard > Settings > Emails)
+- [ ] Configure Stripe tax settings if needed
+- [ ] Review Stripe security settings
+- [ ] Set up monitoring for failed payments
+- [ ] Create a plan for handling refunds
+
+## Admin Dashboard (Future Enhancement)
+
+You may want to add an admin page to view donations:
+- View all donations
+- Filter by status, date, amount
+- View donor messages
+- Export donation data
+- Issue refunds
+
+## Support
+
+For Stripe-specific questions:
+- [Stripe Documentation](https://stripe.com/docs)
+- [Stripe Support](https://support.stripe.com/)
+
+For implementation questions, refer to:
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Prisma Documentation](https://www.prisma.io/docs)