From 062486bc43b7be6bc37f8684b37245555e689a74 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Dec 2025 20:12:55 +0000 Subject: [PATCH 01/32] Initial plan From 900cc0b0af191315267b680d8c79050e3e821a8d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Dec 2025 20:20:01 +0000 Subject: [PATCH 02/32] Add Facebook Shop integration database models Co-authored-by: rezwana-karim <126201034+rezwana-karim@users.noreply.github.com> --- .../facebook-shop-integration-research.md | 703 ++++++++++++++++++ prisma/schema.prisma | 221 ++++++ 2 files changed, 924 insertions(+) create mode 100644 docs/research/facebook-shop-integration-research.md diff --git a/docs/research/facebook-shop-integration-research.md b/docs/research/facebook-shop-integration-research.md new file mode 100644 index 00000000..58f96b83 --- /dev/null +++ b/docs/research/facebook-shop-integration-research.md @@ -0,0 +1,703 @@ +# Facebook Shop Integration - Technical Research + +**Date**: December 26, 2025 +**Version**: 1.0 +**Target Platform**: StormCom Multi-Tenant SaaS +**Facebook API Version**: v21.0 (Latest Stable as of Dec 2025) + +--- + +## Executive Summary + +This document outlines the comprehensive research for integrating Facebook Shop into StormCom, enabling vendors to: +1. Connect their Facebook Business Page via OAuth +2. Automatically sync product catalogs to Facebook Commerce +3. Receive and process orders from Facebook Shops +4. Handle customer inquiries via Facebook Messenger +5. Sync inventory updates in real-time + +--- + +## Facebook Commerce Platform Overview + +### Key Components + +1. **Facebook Business Page**: Required for Commerce features +2. **Meta Commerce Manager**: Dashboard for managing shops +3. **Facebook Product Catalog**: Container for product data +4. **Facebook Shops**: Storefront on Facebook +5. **Instagram Shopping**: Product tagging on Instagram (requires Facebook Catalog) +6. **Facebook Messenger**: Customer communication channel + +### Prerequisites + +- Facebook Business Page (verified) +- Facebook App (Developer account required) +- HTTPS domain (for webhooks) +- Business verification (for advanced features) + +--- + +## Facebook Graph API v21.0 + +### Base URL +``` +https://graph.facebook.com/v21.0 +``` + +### Authentication + +#### OAuth 2.0 Flow + +**Step 1: Initiate OAuth** +``` +GET https://www.facebook.com/v21.0/dialog/oauth? + client_id={app-id} + &redirect_uri={redirect-uri} + &state={state-param} + &scope=pages_show_list,pages_read_engagement,pages_manage_metadata,commerce_manage_catalog,commerce_manage_orders,pages_messaging +``` + +**Required Scopes**: +- `pages_show_list` - List Facebook Pages +- `pages_read_engagement` - Read Page engagement data +- `pages_manage_metadata` - Manage Page settings +- `commerce_manage_catalog` - Create and manage product catalogs +- `commerce_manage_orders` - Access and manage orders +- `pages_messaging` - Send and receive messages +- `instagram_basic` - (Optional) Instagram Shopping +- `instagram_shopping_tag_products` - (Optional) Tag products on Instagram + +**Step 2: Exchange Code for Access Token** +``` +GET https://graph.facebook.com/v21.0/oauth/access_token? + client_id={app-id} + &redirect_uri={redirect-uri} + &client_secret={app-secret} + &code={code-parameter} +``` + +**Step 3: Get Long-Lived Token** +``` +GET https://graph.facebook.com/v21.0/oauth/access_token? + grant_type=fb_exchange_token + &client_id={app-id} + &client_secret={app-secret} + &fb_exchange_token={short-lived-token} +``` + +Long-lived tokens expire in 60 days. Use refresh tokens to maintain access. + +--- + +## Product Catalog Management + +### 1. Create Product Catalog + +**Endpoint**: `POST /v21.0/{page-id}/product_catalogs` + +```json +{ + "name": "StormCom Store - {vendor-name}", + "vertical": "commerce" +} +``` + +**Response**: +```json +{ + "id": "123456789" +} +``` + +### 2. Add Products to Catalog + +**Endpoint**: `POST /v21.0/{catalog-id}/products` + +```json +{ + "retailer_id": "stormcom_{product_id}", + "name": "Product Name", + "description": "Product description", + "price": "2999", + "currency": "BDT", + "availability": "in stock", + "condition": "new", + "brand": "Brand Name", + "url": "https://{store-slug}.stormcom.app/products/{product-slug}", + "image_url": "https://cdn.stormcom.app/products/image.jpg", + "additional_image_urls": [ + "https://cdn.stormcom.app/products/image2.jpg", + "https://cdn.stormcom.app/products/image3.jpg" + ], + "inventory": 50, + "category": "Electronics > Smartphones", + "custom_data": { + "sku": "SKU123", + "weight": "200g", + "dimensions": "15x7x0.8cm" + } +} +``` + +**Required Fields**: +- `retailer_id` - Unique identifier (use StormCom product ID) +- `name` - Product name (max 150 chars) +- `description` - Product description (max 5000 chars) +- `price` - Price in minor units (2999 = 29.99 BDT) +- `currency` - ISO 4217 currency code (BDT for Bangladesh) +- `availability` - `in stock`, `out of stock`, `preorder`, `available for order`, `discontinued` +- `condition` - `new`, `refurbished`, `used` +- `url` - Product URL on storefront +- `image_url` - Main product image (min 500x500px, HTTPS) + +**Optional But Recommended**: +- `brand` - Brand name +- `inventory` - Stock quantity +- `category` - Google Product Category +- `sale_price` - Discounted price +- `sale_price_effective_date` - Sale period (ISO 8601) +- `gtin` - Global Trade Item Number (barcode) + +### 3. Update Product + +**Endpoint**: `POST /v21.0/{product-id}` + +```json +{ + "price": "2499", + "inventory": 25, + "availability": "in stock" +} +``` + +### 4. Delete Product + +**Endpoint**: `DELETE /v21.0/{product-id}` + +### 5. Bulk Product Upload (CSV) + +**Endpoint**: `POST /v21.0/{catalog-id}/product_feeds` + +```json +{ + "name": "Product Feed - {timestamp}", + "url": "https://stormcom.app/api/facebook/product-feed/{store-id}.csv", + "format": "TSV", + "update_schedule": "DAILY" +} +``` + +**CSV Format (TSV - Tab Separated)**: +``` +id title description availability condition price link image_link brand inventory category custom_label_0 +stormcom_123 iPhone 15 Latest Apple iPhone in stock new 99900 BDT https://store.stormcom.app/iphone-15 https://cdn.stormcom.app/iphone.jpg Apple 50 Electronics > Smartphones stormcom_sku_ABC123 +``` + +--- + +## Order Management + +### 1. Receive Order Webhooks + +**Webhook Subscription**: +``` +POST /v21.0/{app-id}/subscriptions +{ + "object": "page", + "callback_url": "https://api.stormcom.app/webhooks/facebook", + "fields": "commerce_orders", + "verify_token": "{your-verify-token}" +} +``` + +**Webhook Verification** (GET request): +```javascript +// Facebook sends GET request to verify webhook +const mode = req.query['hub.mode']; +const token = req.query['hub.verify_token']; +const challenge = req.query['hub.challenge']; + +if (mode === 'subscribe' && token === process.env.FB_WEBHOOK_VERIFY_TOKEN) { + res.status(200).send(challenge); +} else { + res.status(403).send('Forbidden'); +} +``` + +**Order Webhook Payload** (POST request): +```json +{ + "entry": [ + { + "id": "page-id", + "time": 1703601234, + "changes": [ + { + "field": "commerce_orders", + "value": { + "event": "ORDER_CREATED", + "order_id": "fb_order_123456789", + "page_id": "page-id", + "merchant_order_id": "fb_order_123456789" + } + } + ] + } + ] +} +``` + +### 2. Fetch Order Details + +**Endpoint**: `GET /v21.0/{order-id}` + +``` +GET /v21.0/fb_order_123456789?fields=id,buyer_details,shipping_address,order_status,created,items{quantity,price_per_unit,product_name,product_id,retailer_id},payment_status,total_price,currency +``` + +**Response**: +```json +{ + "id": "fb_order_123456789", + "buyer_details": { + "name": "John Doe", + "email": "john@example.com", + "phone": "+8801712345678" + }, + "shipping_address": { + "street1": "123 Main St", + "street2": "Apt 4B", + "city": "Dhaka", + "state": "Dhaka Division", + "postal_code": "1200", + "country": "BD" + }, + "order_status": { + "state": "CREATED" + }, + "payment_status": "PENDING", + "created": "2025-12-26T10:30:00+0000", + "items": { + "data": [ + { + "id": "item_1", + "quantity": 2, + "price_per_unit": { + "amount": "2999", + "currency": "BDT" + }, + "product_name": "Product Name", + "product_id": "fb_product_987", + "retailer_id": "stormcom_123" + } + ] + }, + "total_price": { + "amount": "5998", + "currency": "BDT" + }, + "currency": "BDT" +} +``` + +### 3. Update Order Status + +**Endpoint**: `POST /v21.0/{order-id}/order_status` + +```json +{ + "state": "PROCESSING" +} +``` + +**Valid States**: +- `CREATED` - Order placed +- `PROCESSING` - Order being prepared +- `SHIPPED` - Order shipped +- `COMPLETED` - Order delivered +- `CANCELLED` - Order cancelled +- `REFUNDED` - Order refunded + +**Add Tracking**: +```json +{ + "state": "SHIPPED", + "tracking_info": { + "tracking_number": "TRACK123456", + "carrier": "Pathao", + "shipping_method": "Standard Delivery" + } +} +``` + +--- + +## Customer Messaging (Facebook Messenger) + +### 1. Subscribe to Messages + +**Webhook Fields**: `messages`, `messaging_postbacks`, `message_deliveries`, `message_reads` + +### 2. Receive Message Webhook + +**Webhook Payload**: +```json +{ + "entry": [ + { + "id": "page-id", + "time": 1703601234, + "messaging": [ + { + "sender": { + "id": "user-id" + }, + "recipient": { + "id": "page-id" + }, + "timestamp": 1703601234567, + "message": { + "mid": "message-id", + "text": "Hi, I have a question about product ABC", + "attachments": [] + } + } + ] + } + ] +} +``` + +### 3. Send Message Response + +**Endpoint**: `POST /v21.0/me/messages` + +```json +{ + "recipient": { + "id": "user-id" + }, + "message": { + "text": "Thank you for contacting us! A vendor representative will respond shortly." + }, + "messaging_type": "RESPONSE" +} +``` + +**With Quick Replies**: +```json +{ + "recipient": { + "id": "user-id" + }, + "message": { + "text": "How can we help you?", + "quick_replies": [ + { + "content_type": "text", + "title": "Track Order", + "payload": "TRACK_ORDER" + }, + { + "content_type": "text", + "title": "Product Inquiry", + "payload": "PRODUCT_INQUIRY" + }, + { + "content_type": "text", + "title": "Support", + "payload": "SUPPORT" + } + ] + } +} +``` + +--- + +## Inventory Sync + +### Real-Time Inventory Updates + +**Endpoint**: `POST /v21.0/{product-id}` + +```json +{ + "inventory": 45, + "availability": "in stock" +} +``` + +**Batch Update**: +```json +{ + "requests": [ + { + "method": "POST", + "relative_url": "/{product-id-1}", + "body": "inventory=45&availability=in stock" + }, + { + "method": "POST", + "relative_url": "/{product-id-2}", + "body": "inventory=0&availability=out of stock" + } + ] +} +``` + +**Low Stock Notification**: +When inventory falls below threshold, update availability: +```json +{ + "inventory": 2, + "availability": "limited quantity" +} +``` + +--- + +## Error Handling + +### Common Error Codes + +| Code | Message | Solution | +|------|---------|----------| +| 190 | Invalid OAuth access token | Refresh token or re-authenticate | +| 100 | Invalid parameter | Check API request format | +| 200 | Permission denied | Request additional scopes | +| 368 | Temporarily blocked | Retry after delay (exponential backoff) | +| 4 | Rate limit exceeded | Implement rate limiting (200 calls/hour per user) | +| 2500 | Product catalog full | Contact Facebook support | + +### Rate Limits + +- **Standard tier**: 200 calls per hour per user +- **Advanced tier**: 1,000+ calls per hour (requires business verification) +- **Batch API**: Counts as 1 call for up to 50 operations + +### Best Practices + +1. **Use Batch API** for bulk operations +2. **Implement exponential backoff** for retries +3. **Cache access tokens** (60-day validity) +4. **Store webhook payloads** before processing +5. **Use idempotency keys** for order processing +6. **Monitor webhook delivery** (Facebook retries 3 times with exponential backoff) +7. **Validate webhook signatures** (X-Hub-Signature-256 header) + +--- + +## Facebook Pixel Integration + +### Install Facebook Pixel + +**Add to storefront layout** (`src/app/store/[slug]/layout.tsx`): + +```html + + +``` + +### Track Events + +**View Product**: +```javascript +fbq('track', 'ViewContent', { + content_ids: ['stormcom_123'], + content_type: 'product', + value: 29.99, + currency: 'BDT' +}); +``` + +**Add to Cart**: +```javascript +fbq('track', 'AddToCart', { + content_ids: ['stormcom_123'], + content_type: 'product', + value: 29.99, + currency: 'BDT' +}); +``` + +**Purchase**: +```javascript +fbq('track', 'Purchase', { + content_ids: ['stormcom_123', 'stormcom_456'], + content_type: 'product', + value: 59.98, + currency: 'BDT', + num_items: 2 +}); +``` + +--- + +## Conversion API (Server-Side Tracking) + +**Endpoint**: `POST https://graph.facebook.com/v21.0/{pixel-id}/events` + +```json +{ + "data": [ + { + "event_name": "Purchase", + "event_time": 1703601234, + "user_data": { + "em": "7d8c3d5a9f6e2b4c8a1e5d9f3b7c4a6e", // SHA-256 hashed email + "ph": "5f8d9e2c4b7a3f6e1d8c5a9b3e7f2c6d", // SHA-256 hashed phone + "client_ip_address": "103.123.45.67", + "client_user_agent": "Mozilla/5.0..." + }, + "custom_data": { + "value": 59.98, + "currency": "BDT", + "content_ids": ["stormcom_123", "stormcom_456"], + "content_type": "product", + "num_items": 2 + }, + "action_source": "website" + } + ], + "access_token": "{access-token}" +} +``` + +--- + +## Security Considerations + +### 1. Webhook Signature Verification + +```javascript +import crypto from 'crypto'; + +function verifyWebhookSignature(payload, signature) { + const expectedSignature = crypto + .createHmac('sha256', process.env.FB_APP_SECRET) + .update(payload) + .digest('hex'); + + const signatureHash = signature.replace('sha256=', ''); + + return crypto.timingSafeEqual( + Buffer.from(signatureHash, 'hex'), + Buffer.from(expectedSignature, 'hex') + ); +} +``` + +### 2. Access Token Security + +- Store tokens encrypted in database +- Use environment variables for app secrets +- Implement token rotation +- Never log tokens in plaintext + +### 3. Data Privacy + +- Hash PII before sending to Facebook (GDPR/CCPA compliance) +- Implement data deletion on user request +- Store only necessary customer data +- Use Facebook's Advanced Matching for better tracking without storing PII + +--- + +## Testing + +### 1. Facebook Test Mode + +- Use test catalog and test products +- Generate test orders via Commerce Manager +- Test webhooks with test events + +### 2. Webhook Testing + +Use Facebook's Webhook Test Tool: +1. Go to App Dashboard > Webhooks +2. Send test events +3. Verify endpoint receives and processes correctly + +### 3. Product Catalog Validation + +Use Facebook's Product Diagnostics: +- Check product feed errors +- Validate image URLs +- Verify product availability + +--- + +## Migration Plan + +### Phase 1: Foundation (Week 1) +- Set up Facebook App +- Implement OAuth flow +- Store access tokens securely + +### Phase 2: Product Sync (Week 2) +- Create product catalog API integration +- Implement product CRUD operations +- Add product mapping table + +### Phase 3: Order Processing (Week 3) +- Set up webhook endpoint +- Implement order webhook handler +- Map Facebook orders to StormCom + +### Phase 4: Messaging (Week 4) +- Implement message webhook +- Create notification system +- Build message response API + +### Phase 5: Dashboard UI (Week 5) +- Create connection flow UI +- Build sync status dashboard +- Add manual sync controls + +### Phase 6: Testing & Launch (Week 6-7) +- End-to-end testing +- Beta vendor testing +- Documentation and training + +--- + +## Resources + +### Official Documentation +- Facebook Graph API: https://developers.facebook.com/docs/graph-api +- Commerce Platform: https://developers.facebook.com/docs/commerce-platform +- Messenger Platform: https://developers.facebook.com/docs/messenger-platform +- Marketing API: https://developers.facebook.com/docs/marketing-apis +- Webhooks: https://developers.facebook.com/docs/graph-api/webhooks + +### Developer Tools +- Graph API Explorer: https://developers.facebook.com/tools/explorer +- Commerce Manager: https://business.facebook.com/commerce +- Webhook Debugger: https://developers.facebook.com/tools/webhooks + +### SDKs +- JavaScript SDK: https://developers.facebook.com/docs/javascript +- Node.js SDK: https://github.com/node-facebook/fbgraph (Unofficial) + +--- + +**Document Status**: Complete +**Last Updated**: December 26, 2025 +**Next Review**: January 2026 +**Owner**: StormCom Development Team diff --git a/prisma/schema.prisma b/prisma/schema.prisma index 2d0e34e4..85ded721 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -327,6 +327,9 @@ model Store { platformActivities PlatformActivity[] createdFromRequest StoreRequest? @relation("CreatedFromRequest") + // Facebook Shop Integration + facebookIntegration FacebookIntegration? @relation("FacebookIntegration") + // Storefront customization settings (JSON) storefrontConfig String? // JSON field for all storefront settings @@ -511,6 +514,7 @@ model Product { reviews Review[] inventoryLogs InventoryLog[] @relation("InventoryLogs") inventoryReservations InventoryReservation[] + facebookProducts FacebookProduct[] @relation("FacebookProductMapping") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@ -795,6 +799,7 @@ model Order { paymentAttempts PaymentAttempt[] inventoryReservations InventoryReservation[] fulfillments Fulfillment[] + facebookOrders FacebookOrder[] @relation("FacebookOrderMapping") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@ -1264,4 +1269,220 @@ model StoreRequest { @@index([status, createdAt]) @@index([reviewedBy]) @@map("store_requests") +} + +// ============================================================================ +// FACEBOOK SHOP INTEGRATION MODELS +// ============================================================================ + +// Facebook Integration - stores Facebook connection for a store +model FacebookIntegration { + id String @id @default(cuid()) + storeId String @unique + store Store @relation("FacebookIntegration", fields: [storeId], references: [id], onDelete: Cascade) + + // Facebook Page connection + pageId String @unique // Facebook Page ID + pageName String + pageAccessToken String // Encrypted long-lived page access token (60 days) + tokenExpiresAt DateTime? + + // Facebook Catalog + catalogId String? @unique // Facebook Product Catalog ID + catalogName String? + + // Instagram connection (optional) + instagramAccountId String? @unique + instagramUsername String? + + // Facebook Pixel + pixelId String? + + // Connection status + isActive Boolean @default(true) + lastSyncAt DateTime? + + // OAuth state + oauthState String? // Random state for OAuth flow + + // Webhook verification + webhookVerifyToken String? // Token for webhook verification + + // Relations + products FacebookProduct[] + orders FacebookOrder[] + messages FacebookMessage[] + syncLogs FacebookSyncLog[] + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([storeId]) + @@index([pageId]) + @@index([catalogId]) + @@map("facebook_integrations") +} + +// Facebook Product Mapping - maps StormCom products to Facebook catalog products +model FacebookProduct { + id String @id @default(cuid()) + integrationId String + integration FacebookIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade) + + // StormCom Product reference + productId String + product Product @relation("FacebookProductMapping", fields: [productId], references: [id], onDelete: Cascade) + + // Facebook Product reference + facebookProductId String // Facebook Product ID (e.g., "123456789") + retailerId String // Our unique identifier (stormcom_{productId}) + + // Sync status + syncStatus String @default("PENDING") // PENDING, SYNCED, FAILED, OUT_OF_SYNC + lastSyncedAt DateTime? + syncError String? + + // Facebook-specific fields + availabilityStatus String @default("in stock") // "in stock", "out of stock", "preorder", etc. + condition String @default("new") // "new", "refurbished", "used" + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([integrationId, productId]) + @@unique([integrationId, facebookProductId]) + @@unique([integrationId, retailerId]) + @@index([productId]) + @@index([syncStatus]) + @@map("facebook_products") +} + +// Facebook Order - stores orders received from Facebook Shop +model FacebookOrder { + id String @id @default(cuid()) + integrationId String + integration FacebookIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade) + + // Facebook Order reference + facebookOrderId String @unique // Facebook Order ID + merchantOrderId String? // Facebook's merchant order ID + + // StormCom Order reference (created after mapping) + orderId String? @unique + order Order? @relation("FacebookOrderMapping", fields: [orderId], references: [id], onDelete: SetNull) + + // Order details (stored from webhook) + buyerName String + buyerEmail String? + buyerPhone String? + + // Shipping address + shippingStreet1 String? + shippingStreet2 String? + shippingCity String? + shippingState String? + shippingPostalCode String? + shippingCountry String? + + // Order status + facebookStatus String // Facebook order status (CREATED, PROCESSING, SHIPPED, etc.) + paymentStatus String // PENDING, PAID, REFUNDED + + // Tracking + trackingNumber String? + trackingCarrier String? + + // Financial + totalAmount Float + currency String @default("BDT") + + // Raw webhook payload (for debugging) + rawPayload String? // JSON + + // Processing status + processingStatus String @default("PENDING") // PENDING, PROCESSED, FAILED + processingError String? + + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([integrationId]) + @@index([facebookOrderId]) + @@index([orderId]) + @@index([processingStatus]) + @@index([createdAt]) + @@map("facebook_orders") +} + +// Facebook Message - stores customer messages from Facebook Messenger +model FacebookMessage { + id String @id @default(cuid()) + integrationId String + integration FacebookIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade) + + // Facebook Message reference + facebookMessageId String @unique // Facebook Message ID + conversationId String // Facebook Conversation/Thread ID + + // Sender information + senderId String // Facebook User ID + senderName String? + + // Message content + messageText String? + attachments String? // JSON array of attachment URLs + + // Message metadata + timestamp DateTime + isFromCustomer Boolean @default(true) // true = customer to store, false = store to customer + + // Processing status + isRead Boolean @default(false) + isReplied Boolean @default(false) + + // Store staff who handled message + handledBy String? + handledAt DateTime? + + createdAt DateTime @default(now()) + + @@index([integrationId]) + @@index([conversationId]) + @@index([senderId]) + @@index([isRead]) + @@index([timestamp]) + @@map("facebook_messages") +} + +// Facebook Sync Log - tracks sync operations +model FacebookSyncLog { + id String @id @default(cuid()) + integrationId String + integration FacebookIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade) + + // Sync operation details + operation String // CREATE_PRODUCT, UPDATE_PRODUCT, DELETE_PRODUCT, SYNC_INVENTORY, etc. + entityType String // PRODUCT, ORDER, INVENTORY + entityId String? // StormCom entity ID + externalId String? // Facebook entity ID + + // Status + status String // SUCCESS, FAILED, PENDING + errorMessage String? + errorCode String? + + // Request/Response data (for debugging) + requestData String? // JSON + responseData String? // JSON + + // Timing + duration Int? // Duration in milliseconds + + createdAt DateTime @default(now()) + + @@index([integrationId, createdAt]) + @@index([status]) + @@index([operation]) + @@index([createdAt]) + @@map("facebook_sync_logs") } \ No newline at end of file From dd299dab4fcecbc732ead3e677fb8c76e1fc045f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Dec 2025 20:32:47 +0000 Subject: [PATCH 03/32] feat: Add comprehensive Facebook Shop integration UI/UX components Implemented full UI/UX for Facebook Shop integration in dashboard: Components Created: - FacebookConnectionDialog: Multi-step OAuth setup flow - ConnectionStatus: Status card with sync stats and actions - ProductSyncStatus: Data table with bulk sync operations - FacebookOrdersList: Orders table with filtering and search - FacebookMessagesList: Customer messages with reply dialog - SyncLogsTable: Operation logs with error details - Facebook settings page with tabbed interface Features: - Mobile-first responsive design - Accessible components (ARIA, keyboard nav, focus management) - shadcn/ui patterns throughout - TanStack Table for data tables - Multi-tenancy ready (requires API implementation) - Loading, empty, and error states - Mock data for development Updated: - integrations-list.tsx: Added Facebook Shop option Files modified: 1 Files created: 7 Total lines: ~53,000 characters of production-ready UI code --- .../dashboard/integrations/facebook/page.tsx | 309 +++++++++++++++ .../facebook-connection-dialog.tsx | 279 ++++++++++++++ .../facebook/connection-status.tsx | 179 +++++++++ .../facebook/facebook-messages-list.tsx | 256 +++++++++++++ .../facebook/facebook-orders-list.tsx | 251 ++++++++++++ .../facebook/product-sync-status.tsx | 360 ++++++++++++++++++ .../integrations/facebook/sync-logs-table.tsx | 299 +++++++++++++++ .../integrations/integrations-list.tsx | 25 +- 8 files changed, 1957 insertions(+), 1 deletion(-) create mode 100644 src/app/dashboard/integrations/facebook/page.tsx create mode 100644 src/components/integrations/facebook-connection-dialog.tsx create mode 100644 src/components/integrations/facebook/connection-status.tsx create mode 100644 src/components/integrations/facebook/facebook-messages-list.tsx create mode 100644 src/components/integrations/facebook/facebook-orders-list.tsx create mode 100644 src/components/integrations/facebook/product-sync-status.tsx create mode 100644 src/components/integrations/facebook/sync-logs-table.tsx diff --git a/src/app/dashboard/integrations/facebook/page.tsx b/src/app/dashboard/integrations/facebook/page.tsx new file mode 100644 index 00000000..d2bfe3d2 --- /dev/null +++ b/src/app/dashboard/integrations/facebook/page.tsx @@ -0,0 +1,309 @@ +/** + * Facebook Shop Integration Settings Page + * + * Main dashboard page for managing Facebook Shop integration. + * Displays connection status, product sync, orders, messages, and settings. + * + * @module app/dashboard/integrations/facebook/page + */ + +import { Suspense } from 'react'; +import { getServerSession } from 'next-auth'; +import { authOptions } from '@/lib/auth'; +import { redirect } from 'next/navigation'; +import { AppSidebar } from "@/components/app-sidebar"; +import { SiteHeader } from "@/components/site-header"; +import { + SidebarInset, + SidebarProvider, +} from "@/components/ui/sidebar"; +import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; +import { Button } from "@/components/ui/button"; +import { Alert, AlertDescription } from "@/components/ui/alert"; +import { AlertCircle, ArrowLeft } from "lucide-react"; +import { ConnectionStatus } from "@/components/integrations/facebook/connection-status"; +import { ProductSyncStatus } from "@/components/integrations/facebook/product-sync-status"; +import { FacebookOrdersList } from "@/components/integrations/facebook/facebook-orders-list"; +import { FacebookMessagesList } from "@/components/integrations/facebook/facebook-messages-list"; +import { SyncLogsTable } from "@/components/integrations/facebook/sync-logs-table"; +import Link from "next/link"; + +export const metadata = { + title: 'Facebook Shop Integration | Dashboard', + description: 'Manage your Facebook Shop integration', +}; + +// Mock data - In production, fetch from API with proper multi-tenancy +const mockIntegration = { + id: 'fb-int-1', + pageName: 'StormCom Demo Store', + pageId: '123456789', + status: 'active' as const, + lastSyncedAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), + syncStats: { + products: 42, + orders: 18, + messages: 5, + }, +}; + +const mockProducts = [ + { + id: 'prod-1', + name: 'Premium Wireless Headphones', + sku: 'WH-001', + thumbnail: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=100&h=100&fit=crop', + facebookSyncStatus: 'synced' as const, + lastSyncedAt: new Date(Date.now() - 1 * 60 * 60 * 1000).toISOString(), + facebookProductId: 'fb-prod-001', + }, + { + id: 'prod-2', + name: 'Smart Watch Pro', + sku: 'SW-002', + thumbnail: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=100&h=100&fit=crop', + facebookSyncStatus: 'pending' as const, + }, + { + id: 'prod-3', + name: 'Bluetooth Speaker', + sku: 'BS-003', + facebookSyncStatus: 'failed' as const, + }, + { + id: 'prod-4', + name: 'USB-C Cable 6ft', + sku: 'UC-004', + facebookSyncStatus: 'not_synced' as const, + }, +]; + +const mockOrders = [ + { + id: 'order-1', + facebookOrderId: 'FB-2024-001', + customerName: 'John Doe', + totalAmount: 149.99, + currency: 'USD', + status: 'processing' as const, + createdAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), + }, + { + id: 'order-2', + facebookOrderId: 'FB-2024-002', + customerName: 'Jane Smith', + totalAmount: 89.50, + currency: 'USD', + status: 'completed' as const, + createdAt: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), + }, +]; + +const mockMessages = [ + { + id: 'msg-1', + facebookUserId: 'fb-user-123', + customerName: 'Sarah Johnson', + message: 'Hi! Is this product still available? I\'d like to order 2 units.', + createdAt: new Date(Date.now() - 30 * 60 * 1000).toISOString(), + isRead: false, + hasReplied: false, + }, + { + id: 'msg-2', + facebookUserId: 'fb-user-456', + customerName: 'Mike Wilson', + message: 'What are the shipping options for international orders?', + createdAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), + isRead: true, + hasReplied: true, + }, +]; + +const mockLogs = [ + { + id: 'log-1', + operation: 'CREATE_PRODUCT' as const, + entityType: 'Product', + entityName: 'Premium Wireless Headphones', + status: 'success' as const, + createdAt: new Date(Date.now() - 1 * 60 * 60 * 1000).toISOString(), + }, + { + id: 'log-2', + operation: 'SYNC_ORDER' as const, + entityType: 'Order', + entityName: 'FB-2024-001', + status: 'success' as const, + createdAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(), + }, + { + id: 'log-3', + operation: 'UPDATE_PRODUCT' as const, + entityType: 'Product', + entityName: 'Bluetooth Speaker', + status: 'failed' as const, + error: 'Facebook API Error: Invalid product category. Please select a valid category from the catalog.', + createdAt: new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString(), + }, +]; + +async function FacebookIntegrationContent() { + // In production, fetch data with proper multi-tenancy filtering + // const integration = await fetchFacebookIntegration(storeId); + // const products = await fetchProducts(storeId); + // etc. + + return ( +
+ + + + + Overview + Products + Orders + Messages + Settings + + + + + + + Your Facebook Shop is connected and syncing. Last sync was 2 hours ago. + + + +
+
+

Recent Activity

+ +
+
+ + + +
+

Product Sync Status

+

+ Manage which products are synced to your Facebook Shop. Products marked as synced are visible to customers on Facebook and Instagram. +

+ +
+ + + +
+

Facebook Orders

+

+ View and manage orders placed through Facebook and Instagram shops. +

+ +
+ + + +
+

Customer Messages

+

+ Respond to customer inquiries from Facebook Messenger. +

+ +
+ + + +
+

Integration Settings

+

+ Manage your Facebook Shop integration settings. +

+ +
+
+

Connected Page

+

+ {mockIntegration.pageName} +

+ +
+ +
+

Webhook Status

+
+
+

Active and receiving events

+
+ +
+ +
+

Disconnect Facebook Shop

+

+ This will stop syncing products and orders. Your Facebook Shop will remain active but won't be managed from StormCom. +

+ +
+
+
+ + +
+ ); +} + +export default async function FacebookIntegrationPage() { + const session = await getServerSession(authOptions); + + if (!session) { + redirect('/login'); + } + + return ( + + + + +
+
+
+
+
+
+ +
+

Facebook Shop

+

+ Manage your Facebook and Instagram shop integration +

+
+
+ + Loading integration details...
}> + + +
+
+
+
+
+ + + ); +} diff --git a/src/components/integrations/facebook-connection-dialog.tsx b/src/components/integrations/facebook-connection-dialog.tsx new file mode 100644 index 00000000..ea9aa6ff --- /dev/null +++ b/src/components/integrations/facebook-connection-dialog.tsx @@ -0,0 +1,279 @@ +/** + * Facebook Connection Dialog Component + * + * Multi-step dialog for connecting Facebook Shop integration. + * Handles OAuth flow, prerequisites check, and connection setup. + * + * @module components/integrations/facebook-connection-dialog + */ + +'use client'; + +import { useState } from 'react'; +import { Button } from '@/components/ui/button'; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from '@/components/ui/dialog'; +import { Badge } from '@/components/ui/badge'; +import { CheckCircle, AlertCircle, Facebook } from 'lucide-react'; +import { toast } from 'sonner'; +import { useRouter } from 'next/navigation'; + +interface FacebookConnectionDialogProps { + onClose: () => void; + onSuccess: () => void; +} + +type Step = 'welcome' | 'oauth' | 'complete'; + +const REQUIRED_SCOPES = [ + 'pages_show_list', + 'pages_read_engagement', + 'pages_manage_metadata', + 'pages_manage_posts', + 'pages_messaging', + 'instagram_basic', + 'instagram_manage_messages', + 'catalog_management', + 'business_management', +]; + +export function FacebookConnectionDialog({ + onClose, + onSuccess, +}: FacebookConnectionDialogProps) { + const router = useRouter(); + const [currentStep, setCurrentStep] = useState('welcome'); + const [loading, setLoading] = useState(false); + const [connectedPageName, setConnectedPageName] = useState(''); + + const handleOAuthConnect = async () => { + setLoading(true); + try { + // Initiate OAuth flow + const response = await fetch('/api/facebook/auth/initiate', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + }); + + if (!response.ok) { + throw new Error('Failed to initiate Facebook OAuth'); + } + + const data = await response.json(); + + if (data.authUrl) { + // Redirect to Facebook OAuth + window.location.href = data.authUrl; + } else { + throw new Error('No auth URL returned'); + } + } catch (error) { + toast.error('Failed to connect to Facebook'); + console.error('Facebook OAuth error:', error); + setLoading(false); + } + }; + + const handleGoToSettings = () => { + onClose(); + router.push('/dashboard/integrations/facebook'); + }; + + const renderWelcomeStep = () => ( + <> + +
+
📘
+ Connect Facebook Shop +
+ + Sell your products on Facebook and Instagram to reach millions of customers + + + +
+
+

Prerequisites

+
+
+ +
+ A Facebook Business Page (required) +
+
+
+ +
+ Admin access to your Facebook Business Page +
+
+
+ +
+ Verified business (recommended for full features) +
+
+
+
+ +
+
+ +
+

What you'll be able to do:

+
    +
  • Sync products to Facebook Shop automatically
    • +
  • Receive orders from Facebook and Instagram
    • +
  • Respond to customer messages
    • +
  • Track performance with analytics
    • +
+
+
+
+
+ + + + + + + ); + + const renderOAuthStep = () => ( + <> + + Connect Your Facebook Page + + Click the button below to authorize StormCom to access your Facebook Business Page + + + +
+
+

Required Permissions

+

+ We'll request these permissions to manage your Facebook Shop: +

+
+ {REQUIRED_SCOPES.map((scope) => ( + + {scope.replace(/_/g, ' ')} + + ))} +
+
+ +
+
+ +
+

Important:

+

+ You'll be redirected to Facebook. Make sure to grant all requested permissions + for the integration to work properly. +

+
+
+
+
+ + + + + + + ); + + const renderCompleteStep = () => ( + <> + +
+
+ +
+ Facebook Shop Connected! + + Your Facebook Business Page has been successfully connected + +
+ + +
+ {connectedPageName && ( +
+

Connected Page

+

{connectedPageName}

+
+ )} + +
+

Next Steps:

+
+
+ +
+ Sync your products to Facebook Shop +
+
+
+ +
+ Configure your shop settings and preferences +
+
+
+ +
+ Start receiving orders from Facebook and Instagram +
+
+
+
+
+ + + + + + + ); + + return ( + + + {currentStep === 'welcome' && renderWelcomeStep()} + {currentStep === 'oauth' && renderOAuthStep()} + {currentStep === 'complete' && renderCompleteStep()} + + + ); +} diff --git a/src/components/integrations/facebook/connection-status.tsx b/src/components/integrations/facebook/connection-status.tsx new file mode 100644 index 00000000..bcc3eb3b --- /dev/null +++ b/src/components/integrations/facebook/connection-status.tsx @@ -0,0 +1,179 @@ +/** + * Facebook Connection Status Component + * + * Displays Facebook integration status, page info, and quick actions. + * + * @module components/integrations/facebook/connection-status + */ + +'use client'; + +import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'; +import { Button } from '@/components/ui/button'; +import { Badge } from '@/components/ui/badge'; +import { RefreshCw, Settings, FileText, CheckCircle, AlertCircle } from 'lucide-react'; +import { toast } from 'sonner'; +import { useState } from 'react'; + +interface FacebookIntegration { + id: string; + pageName: string; + pageId: string; + status: 'active' | 'inactive' | 'error'; + lastSyncedAt?: string; + syncStats?: { + products: number; + orders: number; + messages: number; + }; +} + +interface ConnectionStatusProps { + integration: FacebookIntegration | null; + onRefresh?: () => void; +} + +export function ConnectionStatus({ integration, onRefresh }: ConnectionStatusProps) { + const [syncing, setSyncing] = useState(false); + + const handleSyncNow = async () => { + setSyncing(true); + try { + const response = await fetch('/api/facebook/sync', { + method: 'POST', + }); + + if (!response.ok) { + throw new Error('Sync failed'); + } + + toast.success('Sync started successfully'); + onRefresh?.(); + } catch (error) { + toast.error('Failed to start sync'); + console.error('Sync error:', error); + } finally { + setSyncing(false); + } + }; + + const formatLastSync = (dateString?: string) => { + if (!dateString) return 'Never'; + + const date = new Date(dateString); + const now = new Date(); + const diffMs = now.getTime() - date.getTime(); + const diffMins = Math.floor(diffMs / 60000); + + if (diffMins < 1) return 'Just now'; + if (diffMins < 60) return `${diffMins} minute${diffMins > 1 ? 's' : ''} ago`; + + const diffHours = Math.floor(diffMins / 60); + if (diffHours < 24) return `${diffHours} hour${diffHours > 1 ? 's' : ''} ago`; + + const diffDays = Math.floor(diffHours / 24); + return `${diffDays} day${diffDays > 1 ? 's' : ''} ago`; + }; + + if (!integration) { + return ( + + + Facebook Shop + + +
+ +

+ No Facebook integration connected +

+ +
+ + + ); + } + + return ( + + +
+
+
📘
+
+ {integration.pageName} +
+ + {integration.status === 'active' ? ( + + ) : ( + + )} + {integration.status === 'active' ? 'Connected' : 'Disconnected'} + +
+
+
+
+ + +
+
+

Products Synced

+

{integration.syncStats?.products || 0}

+
+
+

Total Orders

+

{integration.syncStats?.orders || 0}

+
+
+

Messages

+

{integration.syncStats?.messages || 0}

+
+
+ +
+
+

+ Last synced: {formatLastSync(integration.lastSyncedAt)} +

+
+
+ +
+ + + +
+ + + ); +} diff --git a/src/components/integrations/facebook/facebook-messages-list.tsx b/src/components/integrations/facebook/facebook-messages-list.tsx new file mode 100644 index 00000000..77b388b2 --- /dev/null +++ b/src/components/integrations/facebook/facebook-messages-list.tsx @@ -0,0 +1,256 @@ +/** + * Facebook Messages List Component + * + * List of customer messages from Facebook Messenger. + * Shows unread count, message preview, and reply functionality. + * + * @module components/integrations/facebook/facebook-messages-list + */ + +'use client'; + +import { useState } from 'react'; +import { Button } from '@/components/ui/button'; +import { Badge } from '@/components/ui/badge'; +import { Card, CardContent } from '@/components/ui/card'; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from '@/components/ui/select'; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from '@/components/ui/dialog'; +import { Textarea } from '@/components/ui/textarea'; +import { MessageCircle, Reply, Clock } from 'lucide-react'; +import { toast } from 'sonner'; + +interface FacebookMessage { + id: string; + facebookUserId: string; + customerName?: string; + message: string; + createdAt: string; + isRead: boolean; + hasReplied: boolean; +} + +interface FacebookMessagesListProps { + messages: FacebookMessage[]; + onRefresh?: () => void; +} + +export function FacebookMessagesList({ messages, onRefresh }: FacebookMessagesListProps) { + const [filter, setFilter] = useState<'all' | 'unread' | 'replied'>('all'); + const [replyingTo, setReplyingTo] = useState(null); + const [replyText, setReplyText] = useState(''); + const [sending, setSending] = useState(false); + + const getRelativeTime = (dateString: string) => { + const date = new Date(dateString); + const now = new Date(); + const diffMs = now.getTime() - date.getTime(); + const diffMins = Math.floor(diffMs / 60000); + + if (diffMins < 1) return 'Just now'; + if (diffMins < 60) return `${diffMins}m ago`; + + const diffHours = Math.floor(diffMins / 60); + if (diffHours < 24) return `${diffHours}h ago`; + + const diffDays = Math.floor(diffHours / 24); + if (diffDays < 7) return `${diffDays}d ago`; + + return date.toLocaleDateString(); + }; + + const handleSendReply = async () => { + if (!replyingTo || !replyText.trim()) return; + + setSending(true); + try { + const response = await fetch('/api/facebook/messages/reply', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + messageId: replyingTo.id, + reply: replyText, + }), + }); + + if (!response.ok) throw new Error('Failed to send reply'); + + toast.success('Reply sent successfully'); + setReplyingTo(null); + setReplyText(''); + onRefresh?.(); + } catch (error) { + toast.error('Failed to send reply'); + console.error('Reply error:', error); + } finally { + setSending(false); + } + }; + + const filteredMessages = messages.filter((msg) => { + if (filter === 'unread') return !msg.isRead; + if (filter === 'replied') return msg.hasReplied; + return true; + }); + + const unreadCount = messages.filter((m) => !m.isRead).length; + + return ( + <> +
+
+
+ +

Customer Messages

+ {unreadCount > 0 && ( + + {unreadCount} + + )} +
+ +
+ +
+ {filteredMessages.length > 0 ? ( + filteredMessages.map((message) => ( + + +
+
+
+

+ {message.customerName || `User ${message.facebookUserId.slice(0, 8)}`} +

+ {!message.isRead && ( + + New + + )} + {message.hasReplied && ( + + Replied + + )} +
+

+ {message.message} +

+
+ + {getRelativeTime(message.createdAt)} +
+
+ +
+ + + )) + ) : ( + + +
+ +

+ {filter === 'all' + ? 'No messages yet' + : filter === 'unread' + ? 'No unread messages' + : 'No replied messages'} +

+

+ Customer messages from Facebook Messenger will appear here +

+
+ + + )} +
+
+ + {replyingTo && ( + setReplyingTo(null)}> + + + Reply to Customer + + Replying to {replyingTo.customerName || `User ${replyingTo.facebookUserId.slice(0, 8)}`} + + + +
+
+

Original Message:

+

{replyingTo.message}

+
+ +
+ +