puffin-app/docs/NOCODB_INTEGRATION_GUIDE.md

# NocoDB Integration Guide

## 🎯 Overview
This guide explains how to test and verify the NocoDB integration with Stripe webhooks.

## ✅ Implementation Summary

### Files Created/Modified

**New Files:**
- `server/utils/nocodbClient.js` - NocoDB REST API client
- `server/utils/nocodbMapper.js` - Maps Stripe data to NocoDB format
- `docs/NOCODB_INTEGRATION_GUIDE.md` - This file

**Modified Files:**
- `server/routes/webhooks.js` - Added NocoDB integration
- `src/api/nocodbClient.ts` - Added `createOrder()` method
- `.env.example` - Added NocoDB configuration template

### Integration Flow

```
Stripe Payment Complete
        ↓
Webhook: checkout.session.completed
        ↓
logStripeSessionData() - Comprehensive logging
        ↓
Order.updateStatus() - Update local DB
        ↓
saveOrderToNocoDB() - Save to NocoDB ✨ NEW
        ↓
fulfillOrder() - Create Wren offset
        ↓
updateNocoDBFulfillment() - Update with Wren data ✨ NEW
        ↓
Send receipt email
```

## 🔧 Environment Variables

Ensure these are set in `server/.env`:

```bash
# NocoDB Configuration
NOCODB_BASE_URL=https://database.puffinoffset.com
NOCODB_BASE_ID=p11p8be6tzttkhy
NOCODB_API_KEY=Y1thvyr9N53n8WFn7rCgY3ZnLlzPFc4_BdwXCmx-
NOCODB_ORDERS_TABLE_ID=mxusborf4x91e1j
```

**How to find these values:**
1. **NOCODB_BASE_URL**: Your NocoDB instance URL
2. **NOCODB_BASE_ID**: Go to Base → Copy Base ID
3. **NOCODB_API_KEY**: User Settings → Tokens → Create Token
4. **NOCODB_ORDERS_TABLE_ID**: Open table → URL contains table ID

## 🧪 Testing the Integration

### Method 1: Stripe CLI Test (Recommended)

**Setup:**
```bash
# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# In another terminal, start the server
cd server
npm run dev
```

**Trigger Test Payment:**
```bash
stripe trigger checkout.session.completed
```

**Expected Console Output:**
```
📬 Received webhook: checkout.session.completed

╔════════════════════════════════════════════════════════════════╗
║         STRIPE CHECKOUT SESSION - COMPREHENSIVE DATA          ║
╚════════════════════════════════════════════════════════════════╝
... (all Stripe data logged)

✅ Checkout session completed: cs_test_...
💳 Payment confirmed for order: e0e976e5-...
   Amount: $1649.79

💾 Saving order e0e976e5-... to NocoDB...
✅ Order saved to NocoDB successfully
   NocoDB Record ID: 123
   Order ID: e0e976e5-...
   Customer: Matthew Ciaccio (matt@letsbe.solutions)
   Business: LetsBe Solutions LLC
   Tax ID: eu_vat - FRAB123456789

🌱 Fulfilling order via Wren API...
✅ Order fulfilled successfully
   Wren Order ID: wren_...
   Tons offset: 6.73

💾 Updating NocoDB with fulfillment data...
✅ NocoDB updated with fulfillment data
   Wren Order ID: wren_...
   Status: fulfilled

📧 Receipt email sent to matt@letsbe.solutions
```

### Method 2: Real Test Payment

1. **Start Server:**
   ```bash
   cd server
   npm run dev
   ```

2. **Make Test Payment:**
   - Navigate to checkout
   - Use test card: `4242 4242 4242 4242`
   - Fill in test billing information
   - Complete payment

3. **Check Logs:**
   - Look for NocoDB save confirmation
   - Verify fulfillment update logs

4. **Verify in NocoDB:**
   - Open NocoDB Orders table
   - Find the new order by `orderId`
   - Check all fields are populated

## 🔍 Verification Checklist

After a test payment, verify:

### ✅ Server Logs
- [ ] Comprehensive Stripe data logged
- [ ] "Saving order to NocoDB" message
- [ ] "Order saved to NocoDB successfully" with Record ID
- [ ] "Updating NocoDB with fulfillment data" message
- [ ] "NocoDB updated with fulfillment data" message

### ✅ NocoDB Database
- [ ] New record exists in Orders table
- [ ] `orderId` matches Stripe order
- [ ] `status` = "fulfilled" (after Wren fulfillment)
- [ ] `stripeSessionId` populated
- [ ] `stripePaymentIntent` populated
- [ ] `baseAmount`, `processingFee`, `totalAmount` correct
- [ ] `co2Tons`, `portfolioId` from metadata
- [ ] `customerName`, `customerEmail` populated
- [ ] `customerPhone` populated (if collected)
- [ ] `businessName` populated (if B2B)
- [ ] `taxIdType` and `taxIdValue` populated (if collected)
- [ ] `billingLine1`, `billingCity`, `billingCountry` populated
- [ ] `wrenOrderId` populated after fulfillment
- [ ] `fulfilledAt` timestamp set

### ✅ Error Handling
Test error scenarios:
- [ ] NocoDB temporarily unavailable (should log error but not fail webhook)
- [ ] Invalid NocoDB credentials (should skip gracefully)
- [ ] Wren API failure (should still save to NocoDB with status='paid')

## 🐛 Troubleshooting

### Issue: "NocoDB not configured"
**Cause:** Environment variables missing or incorrect

**Fix:**
```bash
# Check environment variables
cd server
cat .env | grep NOCODB

# Ensure all 4 variables are set:
# NOCODB_BASE_URL
# NOCODB_BASE_ID
# NOCODB_API_KEY
# NOCODB_ORDERS_TABLE_ID
```

### Issue: "NocoDB request failed: 401"
**Cause:** Invalid API key

**Fix:**
1. Go to NocoDB → User Settings → Tokens
2. Create new token
3. Update `NOCODB_API_KEY` in `.env`
4. Restart server

### Issue: "NocoDB request failed: 404"
**Cause:** Incorrect table ID or base ID

**Fix:**
1. Open your Orders table in NocoDB
2. Check URL: `https://nocodb.com/nc/BASE_ID/TABLE_ID`
3. Update `NOCODB_BASE_ID` and `NOCODB_ORDERS_TABLE_ID`
4. Restart server

### Issue: Order saved but fields are null
**Cause:** Stripe metadata not passed correctly

**Fix:**
Check checkout session creation includes metadata:
```javascript
const session = await stripe.checkout.sessions.create({
  metadata: {
    baseAmount: '160174',
    processingFee: '4805',
    portfolioId: '37',
    tons: '6.73',
    // Add vessel/trip data if available
  },
  // ... other settings
});
```

### Issue: Business fields not populated
**Cause:** Stripe checkout not collecting business information

**Fix:**
Update checkout session to collect business details:
```javascript
const session = await stripe.checkout.sessions.create({
  customer_creation: 'always',
  tax_id_collection: {
    enabled: true,
    required: 'never' // or 'if_supported'
  },
  // ... other settings
});
```

## 📊 Database Record Example

**Expected NocoDB Record (Business Customer):**

```json
{
  "Id": 123,
  "CreatedAt": "2025-11-03T14:30:00.000Z",
  "UpdatedAt": "2025-11-03T14:31:00.000Z",
  "orderId": "e0e976e5-4272-4f5b-a379-c059df6cb5de",
  "status": "fulfilled",
  "source": "web",
  "stripeSessionId": "cs_test_...",
  "stripePaymentIntent": "pi_...",
  "stripeCustomerId": "cus_TM7pU6vRGh0N5N",
  "baseAmount": "160174",
  "processingFee": "4805",
  "totalAmount": "164979",
  "currency": "USD",
  "amountUSD": "164979",
  "paymentMethod": "card",
  "co2Tons": "6.73",
  "portfolioId": "37",
  "portfolioName": null,
  "wrenOrderId": "wren_order_123",
  "certificateUrl": null,
  "fulfilledAt": "2025-11-03T14:31:00.000Z",
  "customerName": "LetsBe Solutions LLC",
  "customerEmail": "matt@letsbe.solutions",
  "customerPhone": "+33633219796",
  "businessName": "LetsBe Solutions LLC",
  "taxIdType": "eu_vat",
  "taxIdValue": "FRAB123456789",
  "billingLine1": "108 Avenue du Trois Septembre",
  "billingLine2": null,
  "billingCity": "Cap-d'Ail",
  "billingState": null,
  "billingPostalCode": "06320",
  "billingCountry": "FR",
  "vesselName": null,
  "imoNumber": null,
  "vesselType": null,
  "vesselLength": null,
  "departurePort": null,
  "arrivalPort": null,
  "distance": null,
  "avgSpeed": null,
  "duration": null,
  "enginePower": null,
  "notes": null
}
```

## 🚀 Deployment Checklist

Before deploying to production:

- [ ] All NocoDB columns created (42 total)
- [ ] Environment variables configured in production `.env`
- [ ] NocoDB API key has proper permissions
- [ ] Stripe webhook endpoint configured in Stripe Dashboard
- [ ] Webhook signing secret set in production `.env`
- [ ] Test payment processed successfully
- [ ] Verify data appears correctly in NocoDB
- [ ] Error handling tested (NocoDB unavailable scenario)
- [ ] Logs reviewed for any warnings or errors

## 📝 Next Steps

1. **Test with Real Payment:**
   - Make a test purchase
   - Verify all fields in NocoDB
   - Check fulfillment updates correctly

2. **Enable Additional Features (Optional):**
   - Phone number collection in checkout
   - Tax ID collection for B2B customers
   - Vessel/trip metadata for yacht calculations

3. **Admin Portal Integration:**
   - Connect admin dashboard to NocoDB
   - Display orders table with filters
   - Add order management functionality

4. **Monitoring:**
   - Set up alerts for failed NocoDB saves
   - Monitor webhook processing times
   - Track fulfillment success rate

## 📚 Related Documentation

- **Schema Reference:** `docs/NOCODB_SCHEMA.md`
- **Stripe Webhook Testing:** `docs/TESTING_STRIPE_WEBHOOK.md`
- **Integration Summary:** `docs/STRIPE_INTEGRATION_SUMMARY.md`

---

**Status:** ✅ Integration complete and ready for testing
**Last Updated:** 2025-11-03