Next.js শপ EcomSolveBD-তে কানেক্ট করুন

Path contract (host must expose these; package does not inject files):

  POST|GET  /api/ecomsolvebd/collect
  GET|POST  /api/ecomsolvebd/attribution-config
  POST      /api/ecomsolvebd/order-status

Exports:
  @ecomsolvebd/next                 → buildOrderPayload, OrderWebhookPoster, …
  @ecomsolvebd/next/client          → EsbTracker (sets window.esbTrack)
  @ecomsolvebd/next/route-handlers  → create*RouteHandlers factories

Also required (sections below): all browser events via lib/esb-track.ts and
GET /feed/{products|facebook|tiktok|google}.xml via app/feed/[channel]/route.ts.

Out of scope for this SDK: your catalog UI, cart store, ORM, CMS, checkout UX.
Prefix paths with src/ when using src/app.

Identity: never fabricate visitor ids. Forward Cookie via buildOrderPayload(..., { cookieHeader }).

১) ইনস্টল npm install @ecomsolvebd/next

1. 2) Environment

   Merchant Key + Webhook Secret ড্যাশবোর্ড Connect থেকে। Secret শুধু সার্ভার রানটাইমে।

   .envকপি

   ECOMSOLVEBD_API_BASE=https://api.ecomsolvebd.com
   ECOMSOLVEBD_MERCHANT_KEY=<tracking_merchant_id>
   ECOMSOLVEBD_WEBHOOK_SECRET=<webhook_secret>
   ECOMSOLVEBD_GA4_MEASUREMENT_ID=G-XXXXXXXX   # optional
   NEXT_PUBLIC_STORE_URL=https://your-store.example
   # ECOMSOLVEBD_DEPLOY_ENV=staging            # when connected via staging dashboard

2. 3) Browser tracker

   EsbTracker transport মাউন্ট করে (window.esbTrack)। funnelAuto={false} = হোস্ট ইভেন্ট ওয়্যারিং।

   root layoutকপি

   // Root layout — path may be app/layout.tsx or src/app/layout.tsx
   import { EsbTracker } from "@ecomsolvebd/next/client";
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html lang="en">
         <body>
           <EsbTracker
             merchantKey={process.env.ECOMSOLVEBD_MERCHANT_KEY!}
             // Public store origin (scheme + host). Used to build same-origin collect URL.
             storeBaseUrl={process.env.NEXT_PUBLIC_STORE_URL!}
             apiBase={process.env.ECOMSOLVEBD_API_BASE}
             deployEnv={process.env.ECOMSOLVEBD_DEPLOY_ENV}
             ga4MeasurementId={process.env.ECOMSOLVEBD_GA4_MEASUREMENT_ID}
             // You fire every event via lib/esb-track.ts (see events section)
             funnelAuto={false}
           />
           {/* <Suspense fallback={null}><EsbPageViews /></Suspense> — SPA route-change page_view */}
           {children}
         </body>
       </html>
     );
   }

3. 4) Collect proxy

   First-party Auto ladder: browser → same-origin → API। Thin wrapper only.

   app/api/ecomsolvebd/collect/route.tsকপি

   // app/api/ecomsolvebd/collect/route.ts
   import { createCollectRouteHandlers } from "@ecomsolvebd/next/route-handlers";
   
   export const { POST, GET } = createCollectRouteHandlers({
     merchantKey: process.env.ECOMSOLVEBD_MERCHANT_KEY!,
     apiBase: process.env.ECOMSOLVEBD_API_BASE,
     deployEnv: process.env.ECOMSOLVEBD_DEPLOY_ENV,
   });

4. 5) Attribution config proxy

   Same-origin attribution config — path ঠিক রাখুন।

   app/api/ecomsolvebd/attribution-config/route.tsকপি

   // app/api/ecomsolvebd/attribution-config/route.ts
   import { createAttributionConfigRouteHandlers } from "@ecomsolvebd/next/route-handlers";
   
   export const { GET, POST } = createAttributionConfigRouteHandlers({
     merchantKey: process.env.ECOMSOLVEBD_MERCHANT_KEY!,
     apiBase: process.env.ECOMSOLVEBD_API_BASE,
     deployEnv: process.env.ECOMSOLVEBD_DEPLOY_ENV,
   });

5. 6) Inbound order status

   SaaS → store। findOrder / updateOrder আপনার persistence-এ ম্যাপ — ORM বাধ্যতামূলক নয়।

   app/api/ecomsolvebd/order-status/route.tsকপি

   // app/api/ecomsolvebd/order-status/route.ts  (or src/app/…)
   import { createOrderStatusRouteHandlers } from "@ecomsolvebd/next/route-handlers";
   
   // Wire find/update to YOUR persistence (Prisma, Drizzle, SQL, REST CMS, …).
   // The factory only needs: load by orderNumber → read status → write status.
   
   export const { POST } = createOrderStatusRouteHandlers({
     webhookSecret: process.env.ECOMSOLVEBD_WEBHOOK_SECRET!,
     allowedStatuses: ["pending", "confirmed", "delivered", "cancelled", "returned"],
     findOrder: async (orderNumber) => {
       // return await db.orders.findByNumber(orderNumber)
       return null; // replace — null → handler reports not found
     },
     getCurrentStatus: (order) => {
       // return order.status
       return (order as { status?: string }).status;
     },
     updateOrder: async (order, update) => {
       // Prefer business key orderNumber over PK type (Int vs String/cuid).
       // await db.orders.updateStatus(order.orderNumber, update.status)
       void order;
       void update;
     },
   });

6. 7) Order ingest

   Checkout success call site (যেখানেই অর্ডার কমিট হয়)। Ads Purchase নয়।

   call site · serverকপি

   // Call from YOUR checkout success path (Route Handler, Server Action, etc.)
   // Exact file path depends on your storefront — not prescribed by this SDK.
   import { cookies } from "next/headers";
   import { buildOrderPayload, OrderWebhookPoster } from "@ecomsolvebd/next";
   
   // 1) Persist the order in your own database first, then:
   const poster = new OrderWebhookPoster({
     merchantKey: process.env.ECOMSOLVEBD_MERCHANT_KEY!,
     webhookSecret: process.env.ECOMSOLVEBD_WEBHOOK_SECRET!,
     apiBase: process.env.ECOMSOLVEBD_API_BASE,
   });
   
   const payload = buildOrderPayload(
     {
       orderNumber: order.number,
       // Use your store currency (ISO 4217) — do not hardcode
       currency: order.currency,
       customer: {
         fullName: order.customerName, // name
         phone: order.phone,
         // email: order.email,
       },
       items: order.lines.map((l) => ({
         sku: l.sku,
         title: l.title,
         quantity: l.qty,
         unitPrice: String(l.unitPrice),
         // productId: l.productId,
         // variantTitle: l.variantTitle,
       })),
       // Shipping / address (uncomment when your checkout collects them)
       // district: order.district,
       // upazila: order.upazila,
       // address: order.address,
       // notes: order.notes,
       // Money (flat fields — not a nested totals object)
       // shippingTotal: String(order.shippingTotal),
       // discountTotal: String(order.discountTotal),
       // taxTotal: String(order.taxTotal),
     },
     { cookieHeader: (await cookies()).toString() },
   );
   
   try {
     await poster.postOrder(payload);
   } catch (err) {
     console.error("[ecomsolvebd] postOrder failed", err);
   }
   // Ingest only — ads Purchase is sent later from the EcomSolveBD dashboard / courier flow.

• চারটা পাবলিক GET URL (লগইন/মিডলওয়্যার/লোকেল রিডাইরেক্ট ছাড়া): /feed/products.xml (EcomSolveBD), /feed/facebook.xml, /feed/tiktok.xml, /feed/google.xml।
• সব active/published প্রোডাক্ট আসবে — খালি লিস্ট বা placeholder ডাটা নয়। ভ্যারিয়েশন থাকলে প্রতিটি ভ্যারিয়েন্ট আলাদা row (id = parentId-variantId)।
• id = ইভেন্টের item_id = অর্ডারের productId। price = ক্রেতা যে দাম দেয় (সেল প্রাইস থাকলে সেটা)।
• ইমেজ ও লিংক সম্পূর্ণ https URL (relative path নয়)। Meta/TikTok/Google ফিডে ইমেজ নেই বা price ≤ 0 হলে সেই প্রোডাক্ট বাদ দিন।
• XML escape করুন (& < > " ')। description-এ HTML নয়, plain text।
• কস্ট (buying_cost ইত্যাদি) ফিডে দেবেন না — EcomSolveBD-তে সেট করা কস্ট সিঙ্কে মুছে যায় না।

1. 1) Feed route (একটা ফাইল, চারটা URL)

   ফোল্ডারের নাম [channel] — [channel].xml নয়। /feed/* পাবলিক রাখুন (middleware/auth/i18n বাদ)।

   app/feed/[channel]/route.tsকপি

   // app/feed/[channel]/route.ts   (src/app/feed/[channel]/route.ts with a src/ dir)
   // One file serves all four URLs: /feed/products.xml · /feed/facebook.xml · /feed/tiktok.xml · /feed/google.xml
   // The [channel] segment receives "products.xml" etc.; the package strips ".xml".
   // Do NOT name the folder "[channel].xml" and no next.config rewrite is needed.
   import { createFeedRouteHandlers } from "@ecomsolvebd/next/route-handlers";
   import { productFeedProvider } from "@/lib/esb-product-feed";
   
   export const dynamic = "force-dynamic"; // always read the live catalog
   
   export const { GET } = createFeedRouteHandlers({
     storeOrigin: process.env.NEXT_PUBLIC_STORE_URL!, // https://your-store.example
     currency: process.env.ECOMSOLVEBD_FEED_CURRENCY || "BDT",
     storeName: process.env.ECOMSOLVEBD_FEED_STORE_NAME || "My Shop",
     provider: productFeedProvider,
   });
   
   // middleware.ts / proxy.ts: make sure /feed/* is NOT behind auth, i18n or locale redirects
   // (e.g. add "feed" to the matcher's excluded paths).

2. 2) ProductFeedProvider — আসল ক্যাটালগ থেকে

   db.product… লাইনটা আপনার ডাটা সোর্সে বদলান; বাকি ম্যাপিং রাখুন। খালি array রেখে দেবেন না।

   lib/esb-product-feed.tsকপি

   // lib/esb-product-feed.ts — read YOUR real catalog (Prisma, Drizzle, CMS, REST API, …)
   import type { FeedCatalogProduct, FeedChannelItem, ProductFeedProvider } from "@ecomsolvebd/next";
   
   const ORIGIN = process.env.NEXT_PUBLIC_STORE_URL!.replace(/\/$/, "");
   const CURRENCY = process.env.ECOMSOLVEBD_FEED_CURRENCY || "BDT";
   const BRAND = process.env.ECOMSOLVEBD_FEED_STORE_NAME || "My Shop";
   
   const abs = (u?: string | null) => (!u ? "" : /^https?:\/\//i.test(u) ? u : ORIGIN + "/" + u.replace(/^\//, ""));
   const plain = (html?: string | null) => String(html ?? "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
   
   /** One row per sellable unit. Expand variants here (id = `${productId}-${variantId}`). */
   async function loadRows() {
     // ↓ replace with your query — ONLY active/published products, ALL of them (no paging limit)
     const products = await db.product.findMany({
       where: { isActive: true },
       include: { category: true, images: true, variants: true },
     });
   
     return products.flatMap((p) => {
       const base = {
         title: p.name,
         description: plain(p.description) || p.name,
         category: p.category?.name ?? "",
         image: abs(p.images[0]?.url ?? p.thumbnail),
         url: `${ORIGIN}/product/${p.slug}`,          // your real PDP URL pattern
       };
       if (p.variants.length === 0) {
         return [{ ...base, id: String(p.id), sku: p.sku ?? String(p.id),
           price: Number(p.salePrice ?? p.price), stock: p.stock }];
       }
       return p.variants.map((v) => ({
         ...base,
         id: `${p.id}-${v.id}`,
         title: `${p.name} — ${v.name}`,
         sku: v.sku ?? `${p.id}-${v.id}`,
         image: abs(v.image) || base.image,
         price: Number(v.salePrice ?? v.price),
         stock: v.stock,
       }));
     });
   }
   
   export const productFeedProvider: ProductFeedProvider = {
     // → /feed/products.xml (EcomSolveBD catalog). Include every row, even out of stock.
     async catalogProducts(): Promise<FeedCatalogProduct[]> {
       const rows = await loadRows();
       return rows.map((r) => ({
         id: r.id,                                   // = event item_id = order productId
         title: r.title,
         price: r.price.toFixed(2),
         currency: CURRENCY,
         category: r.category,
         image: r.image,
         stockStatus: r.stock === null || r.stock > 0 ? "in_stock" : "out_of_stock",
         stockQty: r.stock === null ? "unlimited" : String(Math.max(0, r.stock)),
         productUrl: r.url,
         sku: r.sku,
       }));
     },
   
     // → facebook.xml / tiktok.xml / google.xml. The package does NOT filter — skip bad rows here.
     async channelItems(): Promise<FeedChannelItem[]> {
       const rows = await loadRows();
       return rows
         .filter((r) => r.price > 0 && /^https:\/\//i.test(r.image))
         .map((r) => {
           const inStock = r.stock === null || r.stock > 0;
           return {
             id: r.id,
             skuId: r.sku,
             title: r.title.slice(0, 150),
             description: r.description.slice(0, 5000),
             availabilityMeta: inStock ? "in stock" : "out of stock",
             availabilityGoogle: inStock ? "in_stock" : "out_of_stock",
             price: `${r.price.toFixed(2)} ${CURRENCY}`,
             link: r.url,
             imageLink: r.image,
             brand: BRAND,
             productType: r.category || "General",
           };
         });
     },
   };

3. 3) যাচাই + ড্যাশবোর্ডে বসানো

   ডিপ্লয়ের পর URL খুলে দেখুন, তারপর Dashboard → Products → Feed URL → Save → Fetch now।

   verifyকপি

   # Replace with your public store origin
   curl -sI https://your-store.example/feed/products.xml | head -n 5   # HTTP 200 + application/xml
   curl -s  https://your-store.example/feed/products.xml | head -n 40  # real <product> rows
   curl -s  https://your-store.example/feed/facebook.xml | head -n 30
   curl -s  https://your-store.example/feed/google.xml   | head -n 30
   
   # Then in EcomSolveBD:
   #   Dashboard → Products → Feed URL = https://your-store.example/feed/products.xml
   #   → Save → Fetch now → products appear in the list (auto re-fetch interval on the same card)
   # Ads catalogs:
   #   Meta Commerce Manager → Data sources → Scheduled feed → /feed/facebook.xml
   #   TikTok Ads → Catalog → Data feed → /feed/tiktok.xml
   #   Google Merchant Center → Products → Feeds → Scheduled fetch → /feed/google.xml

<?xml version="1.0" encoding="UTF-8"?>
<products generated_at="2026-10-23T10:00:00Z" currency="BDT">
  <product>
    <id>1042</id>                       <!-- required · same as event item_id + order productId -->
    <title>Cotton Panjabi — Navy</title> <!-- required -->
    <price>1450.00</price>              <!-- required · selling price, number only -->
    <currency>BDT</currency>
    <category>Panjabi</category>
    <image>https://shop.example/img/1042.jpg</image> <!-- absolute https -->
    <sku>PJ-NAVY-42</sku>
    <product_url>https://shop.example/product/cotton-panjabi-navy</product_url>
    <stock>in_stock</stock>             <!-- in_stock | out_of_stock -->
    <stock_qty>25</stock_qty>           <!-- integer, or "unlimited"; 0 = out of stock -->
  </product>
</products>

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">
<channel>
<title>My Shop Product Feed</title>
<link>https://shop.example/</link>
<description>Product Feed</description>
<item>
<g:id>1042</g:id>
<g:title>Cotton Panjabi — Navy</g:title>
<g:description>Plain-text description (no HTML)</g:description>
<g:link>https://shop.example/product/cotton-panjabi-navy</g:link>
<g:image_link>https://shop.example/img/1042.jpg</g:image_link>
<g:brand>My Shop</g:brand>
<g:condition>new</g:condition>
<g:availability>in stock</g:availability>   <!-- google.xml: in_stock / out_of_stock -->
<g:price>1450.00 BDT</g:price>
<g:product_type>Men &gt; Panjabi</g:product_type>
<!-- google.xml only: <g:identifier_exists>no</g:identifier_exists> when no GTIN/MPN -->
<!-- tiktok.xml only: <sku_id>PJ-NAVY-42</sku_id> -->
</item>
</channel>
</rss>