docs: Create comprehensive WooCommerce restoration implementation plan #7

WOOCOMMERCE_RESTORATION_PLAN.md

@@ -0,0 +1,689 @@
+# WooCommerce Integration Restoration - Implementation Plan
+
+**Issue:** #7 - Restore WooCommerce integration functionality
+**Created:** 2025-01-30
+**Status:** Ready for Implementation
+
+## Executive Summary
+
+The WooCommerce integration has a solid foundation with OAuth authentication and API client implemented, but lacks the complete data synchronization features that exist for ShopRenter. This plan outlines the steps to restore full WooCommerce functionality by implementing missing Edge Functions for product, order, and customer synchronization, mirroring the comprehensive ShopRenter integration.
+
+---
+
+## Current State Analysis
+
+### ✅ What's Working
+
+1. **OAuth Flow** (`oauth-woocommerce` Edge Function)
+   - OAuth 1.0a initiation
+   - Callback handling
+   - Credential storage in `stores` table
+   - Connection testing with store API
+
+2. **API Client** (`_shared/woocommerce-client.ts`)
+   - OAuth 1.0a signature generation (HMAC-SHA256)
+   - Generic API request handler
+   - Fetch functions for products, orders, customers
+   - Error handling and rate limiting
+
+3. **Frontend UI** (`WooCommerceConnect.tsx`)
+   - Store URL input with validation
+   - OAuth initiation flow
+   - User-friendly connection wizard
+
+### ❌ What's Missing
+
+1. **No Data Synchronization Edge Functions**
+   - No `woocommerce-products` endpoint
+   - No `woocommerce-orders` endpoint
+   - No `woocommerce-customers` endpoint
+   - No `woocommerce-sync` (manual sync trigger)
+
+2. **No Scheduled Background Sync**
+   - No `woocommerce-scheduled-sync` function
+   - No caching tables for WooCommerce data
+   - No automated data refresh
+
+3. **No API Endpoint for Fetching Synced Data**
+   - Frontend has no way to display WooCommerce products/orders
+   - No integration with dashboard analytics
+
+4. **No Webhook Support**
+   - No webhook registration for order updates
+   - No real-time data updates
+
+---
+
+## Implementation Plan
+
+### Phase 1: Create Edge Functions for Data Sync (Priority: HIGH)
+
+#### Step 1.1: Create `woocommerce-products` Edge Function
+
+**File:** `supabase/functions/woocommerce-products/index.ts`
+
+**Functionality:**
+- Accept `store_id` parameter
+- Fetch all products from WooCommerce API (paginated)
+- Cache products in `woocommerce_products_cache` table
+- Return product list to frontend
+- Handle authentication via JWT
+
+**Implementation Details:**
+```typescript
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+import { fetchProducts } from '../_shared/woocommerce-client.ts'
+
+// Endpoint: GET /woocommerce-products?store_id={uuid}
+// Response: { success: boolean, products: [], cached: boolean }
+```
+
+**Estimated Time:** 4 hours
+
+---
+
+#### Step 1.2: Create `woocommerce-orders` Edge Function
+
+**File:** `supabase/functions/woocommerce-orders/index.ts`
+
+**Functionality:**
+- Accept `store_id` and optional `status` parameter
+- Fetch orders from WooCommerce API
+- Cache orders in `woocommerce_orders_cache` table
+- Return order list to frontend
+
+**Implementation Details:**
+```typescript
+// Endpoint: GET /woocommerce-orders?store_id={uuid}&status=processing
+// Response: { success: boolean, orders: [], cached: boolean }
+```
+
+**Estimated Time:** 4 hours
+
+---
+
+#### Step 1.3: Create `woocommerce-customers` Edge Function
+
+**File:** `supabase/functions/woocommerce-customers/index.ts`
+
+**Functionality:**
+- Accept `store_id` parameter
+- Fetch customers from WooCommerce API
+- Cache customers in `woocommerce_customers_cache` table
+- Return customer list to frontend
+
+**Implementation Details:**
+```typescript
+// Endpoint: GET /woocommerce-customers?store_id={uuid}
+// Response: { success: boolean, customers: [], cached: boolean }
+```
+
+**Estimated Time:** 4 hours
+
+---
+
+#### Step 1.4: Create `woocommerce-sync` Edge Function (Manual Sync)
+
+**File:** `supabase/functions/woocommerce-sync/index.ts`
+
+**Functionality:**
+- Accept `store_id` parameter
+- Sync products, orders, and customers in parallel
+- Update `last_synced_at` timestamp
+- Return sync summary
+
+**Implementation Details:**
+```typescript
+// Endpoint: POST /woocommerce-sync
+// Body: { store_id: string }
+// Response: {
+//   success: boolean,
+//   synced_at: string,
+//   products: { count: number, updated: number },
+//   orders: { count: number, updated: number },
+//   customers: { count: number, updated: number }
+// }
+```
+
+**Estimated Time:** 6 hours
+
+---
+
+### Phase 2: Create Database Tables (Priority: HIGH)
+
+#### Step 2.1: Create Migration for WooCommerce Cache Tables
+
+**File:** `supabase/migrations/20250130_woocommerce_cache_tables.sql`
+
+**Tables to Create:**
+
+1. **`woocommerce_products_cache`**
+```sql
+CREATE TABLE woocommerce_products_cache (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  store_id UUID NOT NULL REFERENCES stores(id) ON DELETE CASCADE,
+  woocommerce_product_id BIGINT NOT NULL,
+  name TEXT NOT NULL,
+  slug TEXT,
+  sku TEXT,
+  price DECIMAL(10,2),
+  regular_price DECIMAL(10,2),
+  sale_price DECIMAL(10,2),
+  currency TEXT DEFAULT 'USD',
+  description TEXT,
+  short_description TEXT,
+  stock_quantity INTEGER,
+  stock_status TEXT,
+  categories JSONB,
+  images JSONB,
+  raw_data JSONB,
+  last_synced_at TIMESTAMPTZ DEFAULT NOW(),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(store_id, woocommerce_product_id)
+);
+
+CREATE INDEX idx_woocommerce_products_store ON woocommerce_products_cache(store_id);
+CREATE INDEX idx_woocommerce_products_sku ON woocommerce_products_cache(sku);
+```
+
+2. **`woocommerce_orders_cache`**
+```sql
+CREATE TABLE woocommerce_orders_cache (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  store_id UUID NOT NULL REFERENCES stores(id) ON DELETE CASCADE,
+  woocommerce_order_id BIGINT NOT NULL,
+  order_key TEXT,
+  number TEXT,
+  status TEXT NOT NULL,
+  currency TEXT DEFAULT 'USD',
+  total DECIMAL(10,2),
+  customer_id BIGINT,
+  customer_email TEXT,
+  customer_name TEXT,
+  customer_phone TEXT,
+  billing_info JSONB,
+  line_items JSONB,
+  date_created TIMESTAMPTZ,
+  date_modified TIMESTAMPTZ,
+  raw_data JSONB,
+  last_synced_at TIMESTAMPTZ DEFAULT NOW(),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(store_id, woocommerce_order_id)
+);
+
+CREATE INDEX idx_woocommerce_orders_store ON woocommerce_orders_cache(store_id);
+CREATE INDEX idx_woocommerce_orders_status ON woocommerce_orders_cache(status);
+CREATE INDEX idx_woocommerce_orders_customer ON woocommerce_orders_cache(customer_email);
+```
+
+3. **`woocommerce_customers_cache`**
+```sql
+CREATE TABLE woocommerce_customers_cache (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  store_id UUID NOT NULL REFERENCES stores(id) ON DELETE CASCADE,
+  woocommerce_customer_id BIGINT NOT NULL,
+  email TEXT NOT NULL,
+  first_name TEXT,
+  last_name TEXT,
+  username TEXT,
+  billing_info JSONB,
+  date_created TIMESTAMPTZ,
+  date_modified TIMESTAMPTZ,
+  raw_data JSONB,
+  last_synced_at TIMESTAMPTZ DEFAULT NOW(),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(store_id, woocommerce_customer_id)
+);
+
+CREATE INDEX idx_woocommerce_customers_store ON woocommerce_customers_cache(store_id);
+CREATE INDEX idx_woocommerce_customers_email ON woocommerce_customers_cache(email);
+```
+
+4. **Add sync tracking to `stores` table**
+```sql
+ALTER TABLE stores ADD COLUMN IF NOT EXISTS last_sync_at TIMESTAMPTZ;
+ALTER TABLE stores ADD COLUMN IF NOT EXISTS sync_status TEXT DEFAULT 'never';
+ALTER TABLE stores ADD COLUMN IF NOT EXISTS sync_error TEXT;
+```
+
+**Estimated Time:** 3 hours
+
+---
+
+### Phase 3: Scheduled Sync Implementation (Priority: MEDIUM)
+
+#### Step 3.1: Create `woocommerce-scheduled-sync` Edge Function
+
+**File:** `supabase/functions/woocommerce-scheduled-sync/index.ts`
+
+**Functionality:**
+- Triggered by pg_cron scheduler
+- Fetch all WooCommerce stores with `sync_enabled = true`
+- Sync each store's data (products, orders, customers)
+- Log results to `sync_logs` table
+- Handle rate limiting across multiple stores
+
+**Implementation Details:**
+```typescript
+// Secured by INTERNAL_SYNC_SECRET
+// Endpoint: POST /woocommerce-scheduled-sync
+// Headers: { 'X-Sync-Secret': INTERNAL_SYNC_SECRET }
+```
+
+**Estimated Time:** 6 hours
+
+---
+
+#### Step 3.2: Update Database Migration for Scheduled Sync
+
+**File:** Update existing or create new migration
+
+**Changes:**
+1. Add WooCommerce to `store_sync_config` table (use existing table)
+2. Create pg_cron job for WooCommerce sync
+3. Add WooCommerce platform support to sync views
+
+```sql
+-- Enable sync for WooCommerce stores
+INSERT INTO store_sync_config (store_id, enabled, sync_frequency, sync_products, sync_orders, sync_customers)
+SELECT id, true, 'hourly', true, true, true
+FROM stores
+WHERE platform_name = 'woocommerce'
+ON CONFLICT (store_id) DO NOTHING;
+
+-- Create pg_cron job (every hour at :15)
+SELECT cron.schedule(
+  'woocommerce-sync-hourly',
+  '15 * * * *', -- Every hour at :15
+  $$
+  SELECT net.http_post(
+    url := current_setting('app.supabase_url') || '/functions/v1/woocommerce-scheduled-sync',
+    headers := jsonb_build_object(
+      'Content-Type', 'application/json',
+      'X-Sync-Secret', current_setting('app.internal_sync_secret')
+    ),
+    body := jsonb_build_object('platform', 'woocommerce')
+  ) as request_id;
+  $$
+);
+```
+
+**Estimated Time:** 2 hours
+
+---
+
+### Phase 4: Frontend Integration (Priority: MEDIUM)
+
+#### Step 4.1: Update IntegrationsContent.tsx
+
+**Changes:**
+- Already fetches stores from `/api/stores` ✅
+- WooCommerceConnect component already exists ✅
+- Add "Sync Now" button for manual sync trigger
+- Display last sync time for WooCommerce stores
+
+**Estimated Time:** 2 hours
+
+---
+
+#### Step 4.2: Create WooCommerce Data Display Components
+
+**New Components:**
+- `WooCommerceProducts.tsx` - Display synced products
+- `WooCommerceOrders.tsx` - Display synced orders
+- `WooCommerceCustomers.tsx` - Display synced customers
+
+**Integration Points:**
+- Add to Dashboard for recent WooCommerce activity
+- Add to Analytics for WooCommerce-specific metrics
+- Add to AI Config for product knowledge base
+
+**Estimated Time:** 6 hours
+
+---
+
+### Phase 5: Webhook Support (Priority: LOW)
+
+#### Step 5.1: Create `webhook-woocommerce` Edge Function
+
+**File:** `supabase/functions/webhook-woocommerce/index.ts`
+
+**Functionality:**
+- Receive webhooks from WooCommerce stores
+- Verify webhook signature
+- Update cached data in real-time
+- Support events: `order.created`, `order.updated`, `product.updated`
+
+**Estimated Time:** 6 hours
+
+---
+
+#### Step 5.2: Auto-register Webhooks on Connect
+
+**Changes to `oauth-woocommerce`:**
+- After successful OAuth, register webhooks
+- Store webhook IDs in `woocommerce_webhooks` table
+
+**Database Table:**
+```sql
+CREATE TABLE woocommerce_webhooks (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  store_id UUID NOT NULL REFERENCES stores(id) ON DELETE CASCADE,
+  woocommerce_webhook_id BIGINT NOT NULL,
+  event TEXT NOT NULL,
+  callback_url TEXT NOT NULL,
+  is_active BOOLEAN DEFAULT true,
+  last_received_at TIMESTAMPTZ,
+  total_received INTEGER DEFAULT 0,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(store_id, event)
+);
+```
+
+**Estimated Time:** 4 hours
+
+---
+
+## Testing Plan
+
+### Unit Tests
+- [ ] Test OAuth signature generation
+- [ ] Test API client error handling
+- [ ] Test rate limiting logic
+- [ ] Test product sync with pagination
+- [ ] Test order filtering by status
+- [ ] Test customer data mapping
+
+### Integration Tests
+- [ ] End-to-end OAuth flow
+- [ ] Complete sync cycle (products → orders → customers)
+- [ ] Scheduled sync execution
+- [ ] Webhook reception and processing
+- [ ] Frontend data display
+
+### Manual Testing Checklist
+- [ ] Connect a test WooCommerce store
+- [ ] Trigger manual sync
+- [ ] Verify data in cache tables
+- [ ] Check sync logs for errors
+- [ ] Test with stores having 100+ products
+- [ ] Test with stores having 0 products (edge case)
+- [ ] Verify rate limiting doesn't cause failures
+- [ ] Test disconnect and reconnect flow
+
+**Estimated Time:** 8 hours
+
+---
+
+## Deployment Plan
+
+### Pre-Deployment
+1. Create staging environment for testing
+2. Deploy to staging and run full test suite
+3. Monitor Edge Function logs for errors
+4. Verify pg_cron jobs are scheduled correctly
+
+### Deployment Steps
+1. **Database Migration**
+   ```bash
+   # Run migration locally first
+   supabase db reset
+   supabase db push
+
+   # Or apply migration to production
+   supabase migration up
+   ```
+
+2. **Deploy Edge Functions**
+   ```bash
+   # Deploy WooCommerce sync functions
+   supabase functions deploy woocommerce-products
+   supabase functions deploy woocommerce-orders
+   supabase functions deploy woocommerce-customers
+   supabase functions deploy woocommerce-sync
+   supabase functions deploy woocommerce-scheduled-sync
+   supabase functions deploy webhook-woocommerce
+   ```
+
+3. **Set Environment Variables**
+   ```bash
+   # Ensure these are set in Supabase Dashboard
+   INTERNAL_SYNC_SECRET=<secure_random_string>
+   SUPABASE_URL=<your_supabase_url>
+   SUPABASE_ANON_KEY=<your_anon_key>
+   SUPABASE_SERVICE_ROLE_KEY=<your_service_role_key>
+   ```
+
+4. **Configure Database Settings**
+   - Navigate to Supabase Dashboard → Project Settings → Database
+   - Add to Custom Postgres Configuration:
+     ```
+     app.internal_sync_secret = '<same_as_INTERNAL_SYNC_SECRET>'
+     app.supabase_url = 'https://ztklqodcdjeqpsvhlpud.supabase.co'
+     ```
+
+5. **Deploy Frontend Changes**
+   ```bash
+   cd shopcall.ai-main
+   npm run build
+   # Deploy to hosting provider (Netlify/Vercel)
+   ```
+
+### Post-Deployment
+1. Monitor Edge Function logs for errors
+2. Check sync_logs table for successful executions
+3. Verify pg_cron jobs are running
+4. Test with 2-3 real WooCommerce stores
+5. Set up alerts for sync failures
+
+---
+
+## Success Criteria
+
+### Functional Requirements
+- ✅ Users can connect WooCommerce stores via OAuth
+- ✅ Products are synced and cached in database
+- ✅ Orders are synced with status filtering
+- ✅ Customers are synced with contact info
+- ✅ Manual sync button works in frontend
+- ✅ Scheduled sync runs hourly automatically
+- ✅ Sync logs track all operations
+- ✅ Frontend displays synced WooCommerce data
+- ✅ Webhooks update data in real-time (optional)
+
+### Non-Functional Requirements
+- ⚡ Product sync completes within 30 seconds for 1000 products
+- 🔒 All API credentials stored encrypted
+- 📊 Sync success rate > 95%
+- 🚫 Rate limiting prevents API bans
+- 📝 Comprehensive error logging
+- ♻️ Failed syncs retry automatically
+
+---
+
+## Effort Estimation
+
+| Phase | Tasks | Estimated Hours |
+|-------|-------|----------------|
+| Phase 1: Edge Functions | 4 functions | 18 hours |
+| Phase 2: Database Tables | Migration + tables | 3 hours |
+| Phase 3: Scheduled Sync | Cron + function | 8 hours |
+| Phase 4: Frontend | UI components | 8 hours |
+| Phase 5: Webhooks | Webhook support | 10 hours |
+| Testing | All tests | 8 hours |
+| Documentation | Docs + deployment | 3 hours |
+| **Total** | | **58 hours** |
+
+**Estimated Calendar Time:** 7-10 business days (1-2 weeks)
+
+---
+
+## Risk Assessment
+
+### Technical Risks
+
+1. **Rate Limiting**
+   - **Risk:** WooCommerce API has rate limits
+   - **Mitigation:** Implement exponential backoff, cache aggressively
+   - **Severity:** Medium
+
+2. **Large Store Performance**
+   - **Risk:** Stores with 10,000+ products may timeout
+   - **Mitigation:** Implement batch processing, background jobs
+   - **Severity:** Medium
+
+3. **OAuth Token Expiration**
+   - **Risk:** WooCommerce API keys don't expire, but user might revoke
+   - **Mitigation:** Test connection before sync, handle 401 errors
+   - **Severity:** Low
+
+4. **Webhook Reliability**
+   - **Risk:** Webhooks may fail or be sent multiple times
+   - **Mitigation:** Idempotent webhook handling, verify signatures
+   - **Severity:** Low
+
+### Business Risks
+
+1. **Feature Parity with ShopRenter**
+   - **Risk:** Users expect same features as ShopRenter
+   - **Mitigation:** Mirror ShopRenter implementation exactly
+   - **Severity:** Medium
+
+2. **Migration from Old Implementation**
+   - **Risk:** Existing WooCommerce stores may need re-connection
+   - **Mitigation:** Provide migration path, email users
+   - **Severity:** Low (few existing users)
+
+---
+
+## Dependencies
+
+### External Dependencies
+- WooCommerce REST API v3
+- Supabase Edge Functions runtime
+- PostgreSQL with pg_cron extension
+- Deno runtime for Edge Functions
+
+### Internal Dependencies
+- `stores` table exists and has WooCommerce stores
+- `oauth_states` table for OAuth flow
+- `sync_logs` table for logging (reuse existing)
+- `store_sync_config` table for per-store settings (reuse existing)
+
+---
+
+## Rollback Plan
+
+If issues arise after deployment:
+
+1. **Disable Scheduled Sync**
+   ```sql
+   SELECT cron.unschedule('woocommerce-sync-hourly');
+   ```
+
+2. **Disable Manual Sync** (frontend)
+   - Hide "Sync Now" button temporarily
+   - Display maintenance message
+
+3. **Rollback Database Migration**
+   ```bash
+   supabase migration down
+   ```
+
+4. **Rollback Edge Functions**
+   - Deploy previous version
+   - Or delete new functions:
+     ```bash
+     supabase functions delete woocommerce-products
+     supabase functions delete woocommerce-orders
+     # etc.
+     ```
+
+---
+
+## Future Enhancements (Out of Scope)
+
+1. **Advanced Product Sync**
+   - Sync product variations
+   - Sync product categories as taxonomy
+   - Sync product attributes
+
+2. **Order Management**
+   - Update order status from ShopCall
+   - Create orders via API
+   - Refund processing
+
+3. **Customer Management**
+   - Create customers via API
+   - Update customer data
+   - Customer segmentation
+
+4. **Multi-Currency Support**
+   - Convert prices to base currency
+   - Display in user's preferred currency
+
+5. **Inventory Management**
+   - Real-time stock tracking
+   - Low stock alerts
+   - Stock synchronization
+
+---
+
+## Documentation Requirements
+
+### Developer Documentation
+- [ ] API documentation for all new Edge Functions
+- [ ] Database schema documentation
+- [ ] Webhook setup guide for WooCommerce admins
+- [ ] Troubleshooting guide for common issues
+
+### User Documentation
+- [ ] How to connect WooCommerce store (user guide)
+- [ ] How to trigger manual sync
+- [ ] Understanding sync status indicators
+- [ ] FAQ for WooCommerce integration
+
+---
+
+## Acceptance Criteria
+
+This implementation is considered complete when:
+
+1. ✅ All Edge Functions are deployed and functional
+2. ✅ Database migrations are applied successfully
+3. ✅ Manual sync works from frontend UI
+4. ✅ Scheduled sync runs automatically every hour
+5. ✅ Sync logs show successful execution history
+6. ✅ Frontend displays WooCommerce products, orders, customers
+7. ✅ All tests pass (unit + integration)
+8. ✅ Documentation is complete and published
+9. ✅ At least 3 real WooCommerce stores tested successfully
+10. ✅ Code reviewed and approved by team
+
+---
+
+## References
+
+- **Existing Implementation:** ShopRenter integration (`supabase/functions/shoprenter-*`)
+- **WooCommerce API Docs:** https://woocommerce.github.io/woocommerce-rest-api-docs/
+- **OAuth 1.0a Spec:** https://oauth.net/core/1.0a/
+- **Supabase Edge Functions:** https://supabase.com/docs/guides/functions
+- **pg_cron Documentation:** https://github.com/citusdata/pg_cron
+
+---
+
+## Next Steps
+
+1. **Review this plan** with the team
+2. **Create subtasks** in project management tool (one per phase)
+3. **Assign ownership** for each phase
+4. **Set up staging environment** for testing
+5. **Begin Phase 1** implementation
+
+---
+
+**Plan Created By:** Claude Code Assistant
+**Date:** 2025-01-30
+**Document Version:** 1.0
+**Related Issue:** #7