feat: implement Shopify order webhooks and order history (#854)

E-Commerce Completion:
- Implemented Shopify order creation webhook handler
- Added HMAC signature verification for webhook security
- Created Order and OrderItem database models
- Built order history page for authenticated users
- Added API endpoint to fetch user orders

Webhook Features:
- Verifies Shopify webhook authenticity via HMAC
- Stores order details in database
- Links orders to VWC users by email
- Prevents duplicate order entries
- Handles order items with full product details

Order History Page:
- Displays all user orders (matched by email)
- Shows order status badges (paid, pending, etc.)
- Displays fulfillment status
- Lists all items per order with quantities and prices
- Formatted dates and currency
- Empty state with link to store
- Requires authentication

Database Schema:
- Order model: tracks Shopify orders with status
- OrderItem model: stores individual line items
- Linked to User model by email matching
- Timestamps for order creation and updates

API Endpoints:
- POST /api/shopify/webhooks/orders/create - Webhook receiver
- GET /api/orders - Fetch user's order history

Documentation:
- Created ECOMMERCE_TESTING.md with test checklist
- Updated .env.example with webhook configuration
- Documented all required environment variables

Environment Variables:
- SHOPIFY_API_SECRET - For webhook HMAC verification
- SHOPIFY_ADMIN_ACCESS_TOKEN - Optional for admin API
- Supports multiple secret key naming conventions

Phase 2 E-Commerce Status:
✅ Cart to checkout flow (already working)
✅ Product variant selection (already working)
✅ Order confirmation webhook (NEW)
✅ Order history page (NEW)

Author: jeromehardaway

.env.example

@@ -4,6 +4,10 @@
 # For production, use PostgreSQL (Vercel Postgres, Railway, Supabase, etc.):
 DATABASE_URL="postgresql://username:password@hostname:port/database"
 
+# LMS Development Access - Set to 'true' to bypass auth in development ONLY
+# WARNING: Never enable in production!
+LMS_DEV_BYPASS=false
+
 # NextAuth.js
 NEXTAUTH_SECRET="your-secret-key-here"
 NEXTAUTH_URL="http://localhost:3000"
@@ -12,6 +16,14 @@ NEXTAUTH_URL="http://localhost:3000"
 GITHUB_CLIENT_ID="your-github-client-id"
 GITHUB_CLIENT_SECRET="your-github-client-secret"
 
+# GitHub API Access (for fetching org data, repos, etc.)
+GITHUB_PAT="your-github-personal-access-token"
+GITHUB_TOKEN="your-github-token"
+GITHUB_ORG="Vets-Who-Code"
+
+# Google Maps API (for location features)
+NEXT_PUBLIC_GOOGLE_MAPS_KEY="your-google-maps-api-key"
+
 # Optional: Other OAuth providers
 # GOOGLE_CLIENT_ID="your-google-client-id"
 # GOOGLE_CLIENT_SECRET="your-google-client-secret"
@@ -35,11 +47,19 @@ OPENAI_API_KEY="your-openai-api-key"
 PHI3_ENDPOINT="your-phi3-endpoint"
 PHI3_API_KEY="your-phi3-api-key"
 
-# Shopify Storefront API
+# Shopify Storefront API (for browsing products/cart)
 SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
 SHOPIFY_STOREFRONT_ACCESS_TOKEN="your-storefront-access-token"
+
+# Shopify Admin API (optional - for making API calls to Shopify)
 SHOPIFY_ADMIN_ACCESS_TOKEN="your-admin-access-token"
 
+# Shopify Webhook/API Secrets (REQUIRED for order webhooks - the API Secret Key from API credentials)
+# The webhook handler will check for any of these names:
+SHOPIFY_WEBHOOK_SECRET="your-webhook-secret"     # Primary option
+SHOPIFY_API_SECRET="your-api-secret-key"         # Alternative name
+SHOPIFY_CLIENT_SECRET="your-client-secret"       # Alternative name
+
 # Cloudinary (for image uploads and management)
 NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloud-name"
 CLOUDINARY_API_KEY="your-api-key"

docs/ECOMMERCE_TESTING.md

@@ -0,0 +1,178 @@
+# E-Commerce Testing Checklist
+
+## Test Environment Setup
+
+### Required Environment Variables
+```bash
+SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
+SHOPIFY_STOREFRONT_ACCESS_TOKEN="your-storefront-token"
+SHOPIFY_ADMIN_ACCESS_TOKEN="your-admin-token"
+```
+
+## 1. Cart to Checkout Flow ✅
+
+### Test Steps:
+1. Navigate to `/store`
+2. Click on a product
+3. Select variant options (if applicable)
+4. Adjust quantity
+5. Click "Add to Cart"
+6. Cart slide-out should open
+7. Verify item appears in cart with correct:
+   - Product name
+   - Variant details
+   - Price
+   - Quantity
+8. Adjust quantity in cart
+9. Click "Proceed to Checkout"
+10. Should redirect to Shopify checkout page
+
+### Expected Behavior:
+- ✅ Cart persists across page refreshes (localStorage)
+- ✅ Correct pricing calculations
+- ✅ Checkout URL redirects to Shopify
+- ✅ Can update quantities
+- ✅ Can remove items
+
+### Code Locations:
+- Store page: `src/pages/store/index.tsx`
+- Product detail: `src/pages/store/products/[handle].tsx`
+- Cart component: `src/components/shopping-cart/shopping-cart.tsx`
+- Cart hook: `src/hooks/useCart.ts`
+- Shopify API: `src/lib/shopify.ts`
+
+## 2. Product Variant Selection ✅
+
+### Test Steps:
+1. Find a product with variants (Size, Color, etc.)
+2. Click on different variant options
+3. Verify:
+   - Price updates if variant has different price
+   - Image changes if variant has specific image
+   - "Add to Cart" uses correct variant ID
+   - Selected variant is highlighted
+
+### Expected Behavior:
+- ✅ Options are displayed as buttons
+- ✅ Selecting option finds matching variant
+- ✅ Visual feedback for selected option
+- ✅ Image gallery updates
+- ✅ Correct variant added to cart
+
+### Code Location:
+- Variant selection: `src/pages/store/products/[handle].tsx:68-93`
+
+## 3. Order Confirmation Webhook ❌ TO IMPLEMENT
+
+### Requirements:
+- Shopify webhook endpoint at `/api/shopify/webhooks/orders/create`
+- Verify webhook signature (HMAC)
+- Store order details in database
+- Send confirmation email to customer (optional)
+
+### Webhook Setup in Shopify:
+1. Go to Shopify Admin → Settings → Notifications → Webhooks
+2. Create webhook:
+   - Event: Order creation
+   - Format: JSON
+   - URL: `https://your-domain.com/api/shopify/webhooks/orders/create`
+   - Version: 2024-01 or latest
+
+### Test Steps:
+1. Complete a test order on Shopify checkout
+2. Verify webhook is received at endpoint
+3. Check database for order record
+4. Verify order details are correct
+
+### Expected Data:
+```json
+{
+  "id": 1234567890,
+  "email": "customer@example.com",
+  "total_price": "29.99",
+  "currency": "USD",
+  "line_items": [...],
+  "created_at": "2024-01-02T00:00:00Z",
+  "customer": {...}
+}
+```
+
+## 4. Order History Page ❌ TO IMPLEMENT
+
+### Requirements:
+- Page at `/orders` or `/store/orders`
+- Fetch user's orders from database or Shopify
+- Display order list with:
+  - Order number
+  - Date
+  - Items
+  - Total amount
+  - Order status
+  - Tracking info (if available)
+
+### Test Steps:
+1. Login as user
+2. Navigate to `/orders`
+3. Verify orders are displayed
+4. Click on an order to see details
+5. Check tracking link (if available)
+
+### Expected Behavior:
+- Shows all user's orders
+- Most recent orders first
+- Can view order details
+- Shows order status (pending, fulfilled, etc.)
+- Empty state if no orders
+
+## Browser Testing Matrix
+
+Test on:
+- ✅ Chrome (latest)
+- ✅ Firefox (latest)
+- ✅ Safari (latest)
+- ✅ Mobile Safari (iOS)
+- ✅ Chrome Mobile (Android)
+
+## Performance Checks
+
+- [ ] Cart operations complete in < 1s
+- [ ] Product page loads in < 2s
+- [ ] Images are optimized
+- [ ] No console errors
+- [ ] Proper loading states
+
+## Security Checks
+
+- [ ] Webhook signature verification
+- [ ] CORS configured correctly
+- [ ] No sensitive data in frontend
+- [ ] API keys not exposed
+- [ ] HTTPS only for checkout
+
+## Accessibility Checks
+
+- [ ] Keyboard navigation works
+- [ ] Screen reader friendly
+- [ ] ARIA labels on interactive elements
+- [ ] Focus states visible
+- [ ] Color contrast meets WCAG AA
+
+## Notes
+
+- Cart uses Shopify Storefront API (read-only, safe for frontend)
+- Checkout happens on Shopify (PCI compliant, secure)
+- Webhooks use Admin API (requires HMAC verification)
+- Orders stored locally for history/analytics
+
+## Known Issues
+
+None currently
+
+## Future Enhancements
+
+- [ ] Wishlist functionality
+- [ ] Product reviews
+- [ ] Related products
+- [ ] Recently viewed products
+- [ ] Abandoned cart recovery
+- [ ] Discount code validation

prisma/schema.prisma

@@ -61,6 +61,9 @@ model User {
   bookmarks     Bookmark[]
   notes         Note[]
 
+  // E-commerce relationships
+  orders        Order[]
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 }
@@ -391,4 +394,63 @@ model Note {
   // Relationships
   user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
   lesson    Lesson   @relation(fields: [lessonId], references: [id], onDelete: Cascade)
+}
+
+// E-Commerce Models - Shopify order tracking
+
+model Order {
+  id             String      @id @default(cuid())
+  shopifyId      String      @unique // Shopify order ID
+  orderNumber    String      // Human-readable order number
+
+  // Customer info
+  userId         String?     // Linked VWC user (if authenticated)
+  customerEmail  String
+  customerName   String?
+
+  // Order details
+  totalPrice     String      // Total price (as string to maintain precision)
+  currency       String      @default("USD")
+  financialStatus String     // paid, pending, refunded, etc.
+  fulfillmentStatus String?  // fulfilled, partial, unfulfilled, etc.
+
+  // Order metadata
+  tags           String[]    // Shopify tags
+  note           String?     // Order notes
+
+  // Timestamps
+  orderCreatedAt DateTime    // When order was created in Shopify
+  createdAt      DateTime    @default(now())
+  updatedAt      DateTime    @updatedAt
+
+  // Relationships
+  user           User?       @relation(fields: [userId], references: [id], onDelete: SetNull)
+  items          OrderItem[]
+}
+
+model OrderItem {
+  id           String   @id @default(cuid())
+  orderId      String
+
+  // Product details
+  shopifyProductId  String
+  shopifyVariantId  String
+  productTitle      String
+  variantTitle      String?
+
+  // Pricing
+  quantity     Int
+  price        String   // Price per item
+  totalPrice   String   // quantity * price
+
+  // SKU and metadata
+  sku          String?
+  vendor       String?
+  imageUrl     String?
+
+  // Timestamps
+  createdAt    DateTime @default(now())
+
+  // Relationships
+  order        Order    @relation(fields: [orderId], references: [id], onDelete: Cascade)
 }

src/pages/api/orders/index.ts

@@ -0,0 +1,62 @@
+import { NextApiResponse } from 'next';
+import { requireAuth, AuthenticatedRequest } from '@/lib/rbac';
+import prisma from '@/lib/prisma';
+
+/**
+ * GET /api/orders
+ *
+ * Fetch all orders for the authenticated user
+ *
+ * Response:
+ * {
+ *   orders: [
+ *     {
+ *       id: string,
+ *       shopifyId: string,
+ *       orderNumber: string,
+ *       totalPrice: string,
+ *       currency: string,
+ *       financialStatus: string,
+ *       fulfillmentStatus: string,
+ *       orderCreatedAt: Date,
+ *       items: OrderItem[]
+ *     }
+ *   ]
+ * }
+ */
+export default requireAuth(async (req: AuthenticatedRequest, res: NextApiResponse) => {
+  if (req.method !== 'GET') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  try {
+    const userId = req.user!.id;
+    const userEmail = req.user!.email;
+
+    // Fetch orders for this user
+    // Match by userId OR by email (for orders before user logged in)
+    const orders = await prisma.order.findMany({
+      where: {
+        OR: [
+          { userId },
+          { customerEmail: userEmail },
+        ],
+      },
+      include: {
+        items: {
+          orderBy: {
+            createdAt: 'asc',
+          },
+        },
+      },
+      orderBy: {
+        orderCreatedAt: 'desc', // Most recent first
+      },
+    });
+
+    return res.status(200).json({ orders });
+  } catch (error) {
+    console.error('Error fetching orders:', error);
+    return res.status(500).json({ error: 'Failed to fetch orders' });
+  }
+});