Add Facebook Login for Business + Commerce Platform integration with multi-tenant support

.env.example

@@ -16,3 +16,10 @@ NEXTAUTH_URL="http://localhost:3000"
 # Email Configuration
 EMAIL_FROM="noreply@example.com"
 RESEND_API_KEY="re_dummy_key_for_build"  # Build fails without this
+
+# Facebook Integration Configuration
+# Get these from https://developers.facebook.com/apps/
+FACEBOOK_APP_ID=""                        # Facebook App ID
+FACEBOOK_APP_SECRET=""                    # Facebook App Secret
+FACEBOOK_WEBHOOK_VERIFY_TOKEN=""          # Random string for webhook verification
+ENCRYPTION_KEY=""                         # 32-byte hex key for encrypting tokens (generate with: openssl rand -hex 32)

README.md

@@ -26,6 +26,11 @@ A production-ready Next.js 16 SaaS boilerplate with authentication, multi-tenanc
 - ✅ **Team Invitations** via email
 - ✅ **Multi-Tenant Database** with proper isolation
 
+### Integrations
+- ✅ **Facebook Login for Business** - OAuth integration for commerce
+- ✅ **Facebook Commerce Platform** - Webhook support for orders and catalogs
+- ✅ **Encrypted Token Storage** - Secure credential management
+
 ### UI/UX
 - ✅ **30+ shadcn/ui Components** pre-configured
 - ✅ **Dark Mode** with next-themes
@@ -74,6 +79,75 @@ export $(cat .env.local | xargs) && npm run prisma:migrate:dev
 npm run dev
 ```
 
+## 🔌 Facebook Integration Setup
+
+### Prerequisites
+
+1. **Facebook App**: Create a Facebook App at [developers.facebook.com](https://developers.facebook.com/apps/)
+2. **App Review**: Submit for App Review to access production features
+3. **Permissions Required**:
+   - `public_profile` (default)
+   - `email` (default)
+   - `pages_read_engagement` (for page access)
+   - `pages_manage_metadata` (for page management)
+   - `catalog_management` (for product catalogs)
+   - `business_management` (for business assets)
+
+### Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# Facebook Integration
+FACEBOOK_APP_ID="your-app-id"
+FACEBOOK_APP_SECRET="your-app-secret"
+FACEBOOK_WEBHOOK_VERIFY_TOKEN="random-string-for-verification"
+ENCRYPTION_KEY="generate-with-openssl-rand-hex-32"
+```
+
+**Generate Encryption Key:**
+```bash
+openssl rand -hex 32
+```
+
+### OAuth Flow
+
+1. **Start OAuth**: Redirect users to `/api/auth/facebook/start?tenant=STORE_ID`
+2. **User Authorization**: Facebook prompts user to grant permissions
+3. **Callback**: System exchanges code for long-lived token (60 days)
+4. **Asset Discovery**: Automatically discovers connected pages, catalogs, and business
+5. **Storage**: Encrypts and stores token with tenant isolation
+
+### Webhook Configuration
+
+1. **Configure in Facebook App Dashboard**:
+   - Webhook URL: `https://your-domain.com/api/facebook/webhook`
+   - Verify Token: Use value from `FACEBOOK_WEBHOOK_VERIFY_TOKEN`
+
+2. **Subscribe to Events**:
+   - `commerce_orders` - Order status updates
+   - `page` - Page and catalog updates
+   - `feed` - Product feed changes
+
+3. **Verify Signature**: All webhooks verify `X-Hub-Signature-256` header
+
+### Multi-Tenant Isolation
+
+- Each Facebook connection is scoped to a specific Store (tenant)
+- State parameter includes signed tenant ID for CSRF protection
+- Tokens encrypted at rest using AES-256-GCM
+- Query filters always include `storeId` to prevent data leakage
+
+### Testing
+
+```bash
+# Start OAuth flow (replace with actual store ID)
+curl "http://localhost:3000/api/auth/facebook/start?tenant=YOUR_STORE_ID"
+
+# Test webhook verification
+curl "http://localhost:3000/api/facebook/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123"
+```
+
 ## 🚀 Deployment
 
 ### Deploy to Vercel