Skip to content

[Phase 3] Meta (Facebook) Shop Integration — Next.js 16 + Shadcn UI Full Implementation Plan (Refined, Latest Docs) #154

New issue
New issue
Open
Feature
#155
Open
[Phase 3] Meta (Facebook) Shop Integration — Next.js 16 + Shadcn UI Full Implementation Plan (Refined, Latest Docs)#154
Feature
#155
Assignees
syed-reza98rezwana-karimcopilot-swe-agent
Labels
Phase 3Priority 1dependenciesPull requests that update a dependency filedocumentationImprovements or additions to documentationenhancementNew feature or requestproductionChanges for Production Environment and Configurationtype:story
@syed-reza98

Description

@syed-reza98
syed-reza98
opened on Jan 16, 2026

Purpose

Integrate Meta (Facebook) Shop with StormCom to enable real-time product sync, storefront, inventory/order/message management, leveraging Next.js 16 with MCP (App Router) and shadcn-ui. All integration is to be performed in strict accordance with the latest Meta Developer Docs (Graph API, webhooks, Commerce Manager, OAuth, Messenger), Next.js 16 best practices, and Shadcn UI component standards. This issue refines and unifies #43 and #153.

Meta/Facebook Developer Documentation Links (Complete, Authoritative)

See also:

Multi-Stage Integration Plan — Next.js 16 + Shadcn UI (Latest Best Practices)

General Principles

  • Use Next.js 16 MCP (App Router, Client/Server Components) for all pages/routes/APIs.
  • All UI elements built with shadcn-ui (V1/V2, as applicable).
  • API endpoints deployed in /api/ with Route Handlers.
  • Integrations are implemented as isolated packages/modules in /lib/integrations
  • Follow Meta required security standards (OAuth, webhook signature validation, encrypted tokens).
  • Detailed logging, health checks, and dashboard visibility for merchants.

Implementation Phases and Steps

Phase 1: Meta App Registration & OAuth Flow

  1. Register a Meta App in Facebook Developer Portal.
    • App ID, Secret, callback URLs, required scopes.
    • Document app review steps and all permissions required (pages_manage_metadata, pages_read_engagement, commerce_management, pages_messaging, etc).
  2. Build OAuth Connect UI in StormCom dashboard using shadcn-ui (Button, Progress, Modals).
  3. OAuth flow:
    • Implement connect start (src/app/dashboard/integrations/facebook/connect.tsx — shadcn Modal/Button)
    • Handle OAuth callback in Route Handler (src/app/api/integrations/facebook/oauth/callback/route.ts)
    • Store encrypted tokens using Prisma schema; offer long-lived token exchange.
    • Display connected Page(s), app status, error logs in the dashboard.

Phase 2: Catalog Creation & Product Sync

  1. Create/attach Catalog via Graph API (POST /v{api_version}/{business_id}/owned_product_catalogs).
  2. Sync products:
    • Product push (POST /v{api_version}/{catalog_id}/products).
    • Batch update for large product sets (see Batch sync docs).
    • Monitor import status, job errors.
  3. Product detail mapping: Ensure all required fields (title, description, price, image_url, quantity, sku/gtin).
  4. Background jobs for batch uploads (BullMQ/Redis or Next.js background task integration).
  5. UI for sync control, health/errors, batch job status (DataTable, Toasts in shadcn-ui).

Phase 3: Inventory Sync & Order Webhook

  1. Implement real-time inventory sync — update Facebook whenever StormCom inventory changes.
  2. InventorySnapshot model (channel, externalProductId, quantity, lastSyncAt, lastError).
  3. Webhook endpoint for Facebook orders/messages (src/app/api/webhooks/facebook/route.ts).
    • Verify webhook handshake (hub.challenge), validate signature (X-Hub-Signature, HMAC SHA1).
    • On order.created, deduplicate, create local Order model, decrement inventory transactionally.
    • Maintain ExternalOrderMapping for reconciliation.
  4. Retry policies, error alerts via dashboard and email (windowed retries, shadcn Toast alerts).

Phase 4: Messenger API — Conversations & Messaging

  1. Messenger platform integration — subscribe to Pages, permissions for messaging.
  2. Use Graph API to fetch conversations & messages (GET /v{api_version}/{page_id}/conversations).
  3. Surface messages in vendor dashboard (shadcn-ui Inbox, List, Notification systems).
  4. Respond to messages via /me/messages with tokens; ensure permissions, app review compliance.

Phase 5: Security, Compliance & App Review

  1. Implement and document domain verification (DNS, HTML upload), emails, and business review in Developer Portal.
  2. Verify all webhook requests via signature validation.
  3. Use appsecret_proof in outgoing requests for additional security (per Meta recommendation).
  4. Encrypt all tokens at rest, ensure GDPR/data minimization.

Phase 6: Monitoring, Health Dashboard & Logging

  1. Integration status UI: lastSyncAt, lastError, error count via shadcn-ui Widgets/Banners.
  2. Detailed logs for product sync, inventory updates, orders, messaging.
  3. Alert merchant (email + in-app notification) on repeated sync failures.
  4. Expose monitoring route /api/integrations/facebook/status for health checks.

Acceptance Criteria

  • Dashboard has "Connect Facebook" button (shadcn-ui) launching OAuth, shows connected pages, error logs.
  • Products sync bidirectionally between StormCom and Facebook Catalog.
  • Orders from Facebook Shops auto-import into StormCom dashboard, with proper source tagging.
  • StormCom inventory updates reflect in Facebook Shop within 30 seconds (real-time for small changes, batch for large volumes).
  • Messages from Facebook Pages (Messenger) appear in vendor dashboard; responses are possible from StormCom.
  • All endpoints/routes and UI conform to Next.js 16 MCP and shadcn-ui conventions.
  • Tokens and sensitive data are encrypted; security practices comply with Meta, Next.js, and GDPR standards.
  • Full monitoring, logs, and health metrics exposed to merchants/admins.

Technical Checklist (Match Next.js 16 + shadcn-ui standards)

  • All API routes use App Router handlers and type safety.
  • All components (buttons, lists, tables, modals, notifications) use shadcn-ui with accessibility.
  • Data models updated with Prisma for integration (FacebookIntegration, InventorySnapshot, ExternalOrderMapping).
  • Background processing (jobs, batch sync) architected per Next.js background job recommendations.
  • All endpoints, models, async jobs, and security routines confirmed with Meta's latest docs above.

Resources for Implementation

Note

This issue supersedes #43 and #153. After confirming completeness, close those issues to avoid duplication.

Implementation must always use the latest Meta/Facebook, Next.js 16 MCP, and shadcn-ui documentation and conventions!

Metadata

Metadata

Assignees

Labels

Phase 3Priority 1dependenciesPull requests that update a dependency filedocumentationImprovements or additions to documentationenhancementNew feature or requestproductionChanges for Production Environment and Configurationtype:story

Type

Feature

Projects

StormCom

Status

In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions