medusa-storefront-analytics 1.2.0 → 1.3.0

package/package.json

@@ -1,10 +1,17 @@
 {
     "name": "medusa-storefront-analytics",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "description": "Layered storefront analytics (GTM dataLayer) with reusable domain events for reviews, forms, and more.",
     "author": "SmartByte Labs",
     "license": "MIT",
-    "keywords": ["medusa", "storefront", "analytics", "gtm", "dataLayer", "reviews"],
+    "keywords": [
+        "medusa",
+        "storefront",
+        "analytics",
+        "gtm",
+        "dataLayer",
+        "reviews"
+    ],
     "repository": {
         "type": "git",
         "url": "https://github.com/SmartByteLabs/medusa-ui-components.git",
@@ -14,7 +21,9 @@
         "access": "public"
     },
     "type": "module",
-    "sideEffects": ["dist/**/*.js"],
+    "sideEffects": [
+        "dist/**/*.js"
+    ],
     "main": "./dist/ui-library.umd.cjs",
     "module": "./dist/ui-library.js",
     "types": "./dist/index.d.ts",
@@ -29,9 +38,25 @@
             "types": "./dist/providers/gtm.d.ts",
             "import": "./dist/ui-library.js",
             "default": "./dist/ui-library.js"
+        },
+        "./api/meta-event": {
+            "types": "./src/api/meta-event.ts",
+            "import": "./src/api/meta-event.ts",
+            "default": "./src/api/meta-event.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "peerDependencies": {
+        "next": ">=14.0.0"
+    },
+    "peerDependenciesMeta": {
+        "next": {
+            "optional": true
         }
     },
-    "files": ["dist"],
     "scripts": {
         "build": "tsc && vite build",
         "dev": "vite build --watch"

package/src/api/meta-event.ts

@@ -0,0 +1,88 @@
+import { NextRequest, NextResponse } from "next/server"
+
+export type MetaCapiEventBody = {
+  event_name?: string
+  event?: string
+  action_source?: string
+  event_source_url?: string
+  event_id?: string
+  custom_data?: Record<string, unknown>
+  user_data?: Record<string, unknown>
+}
+
+function getMetaConfig() {
+  const pixelId = process.env.META_PIXEL_ID || process.env.FB_PIXEL_ID
+  const accessToken = process.env.META_ACCESS_TOKEN || process.env.FB_ACCESS_TOKEN
+  return { pixelId, accessToken }
+}
+
+/** Next.js App Router handler for `POST /api/meta/event` (Meta Conversions API). */
+export async function POST(req: NextRequest) {
+  try {
+    const body = (await req.json()) as MetaCapiEventBody
+    const { pixelId, accessToken } = getMetaConfig()
+
+    if (!pixelId || !accessToken) {
+      return NextResponse.json(
+        { success: false, error: "Configuration missing" },
+        { status: 500 }
+      )
+    }
+
+    const {
+      event_name = body.event || "Lead",
+      action_source = "website",
+      event_source_url,
+      event_id,
+      custom_data = {},
+      user_data = {},
+    } = body
+
+    const forwardedFor = req.headers.get("x-forwarded-for")
+    const clientIp =
+      forwardedFor?.split(",")[0]?.trim() ||
+      req.headers.get("x-real-ip") ||
+      ""
+
+    const payload = {
+      data: [
+        {
+          event_name,
+          event_time: Math.floor(Date.now() / 1000),
+          action_source,
+          event_id,
+          event_source_url: event_source_url || req.headers.get("referer") || "",
+          user_data: {
+            client_ip_address: clientIp,
+            client_user_agent: req.headers.get("user-agent") || "",
+            ...user_data,
+          },
+          custom_data,
+        },
+      ],
+    }
+
+    const response = await fetch(
+      `https://graph.facebook.com/v21.0/${pixelId}/events?access_token=${accessToken}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      }
+    )
+
+    const result = await response.json()
+
+    if (response.ok) {
+      return NextResponse.json({ success: true, data: result })
+    }
+
+    return NextResponse.json(
+      { success: false, error: result },
+      { status: response.status }
+    )
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown error"
+    return NextResponse.json({ success: false, error: message }, { status: 500 })
+  }
+}

package/src/core/compose.ts

@@ -0,0 +1,24 @@
+import type { FormSubmittedPayload, ReviewSubmittedPayload, StorefrontAnalyticsAdapter } from "./types";
+
+/**
+ * Fan-out to multiple adapters (e.g. GTM + custom logger).
+ */
+export function composeAnalyticsAdapters(
+    adapters: StorefrontAnalyticsAdapter[]
+): StorefrontAnalyticsAdapter {
+    const list = adapters.filter(Boolean);
+    return {
+        trackReviewSubmitted(payload: ReviewSubmittedPayload) {
+            list.forEach((a) => a.trackReviewSubmitted(payload));
+        },
+        trackReviewUpdated(payload: ReviewSubmittedPayload) {
+            list.forEach((a) => a.trackReviewUpdated?.(payload));
+        },
+        trackFormSubmitted(payload: FormSubmittedPayload) {
+            list.forEach((a) => a.trackFormSubmitted?.(payload));
+        },
+        trackEvent(eventName: string, data?: Record<string, unknown>) {
+            list.forEach((a) => a.trackEvent?.(eventName, data));
+        },
+    };
+}

package/src/core/noop-adapter.ts

@@ -0,0 +1,8 @@
+import type { StorefrontAnalyticsAdapter } from "./types";
+
+export const noopAnalyticsAdapter: StorefrontAnalyticsAdapter = {
+    trackReviewSubmitted: () => {},
+    trackReviewUpdated: () => {},
+    trackFormSubmitted: () => {},
+    trackEvent: () => {},
+};

package/src/core/types.ts

@@ -0,0 +1,35 @@
+/** Shared product reference for ecommerce / UGC events */
+export interface ProductRef {
+    productId: string;
+    productName: string;
+}
+
+export interface ReviewSubmittedPayload extends ProductRef {
+    rating: number;
+    /** Review title entered by the customer */
+    reviewTitle?: string;
+    /** True when an existing review was updated */
+    isUpdate: boolean;
+}
+
+export interface FormSubmittedPayload {
+    form_type: string;
+    formType?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Port implemented by each site (GTM, Meta, custom). Domain helpers call these methods.
+ */
+export interface StorefrontAnalyticsAdapter {
+    trackReviewSubmitted(payload: ReviewSubmittedPayload): void;
+    trackReviewUpdated?(payload: ReviewSubmittedPayload): void;
+    trackFormSubmitted?(payload: FormSubmittedPayload): void;
+    trackEvent?(eventName: string, data?: Record<string, unknown>): void;
+}
+
+export type AnalyticsEventMap = {
+    review_submitted: ReviewSubmittedPayload;
+    review_updated: ReviewSubmittedPayload;
+    form_submit: FormSubmittedPayload;
+};

package/src/ecommerce/ga4-ecommerce.ts

@@ -0,0 +1,261 @@
+/**
+ * GA4 dataLayer ecommerce helpers + Meta Pixel (explicit fbq).
+ */
+
+import {
+    fireMetaEcommerceEvent,
+    fireMetaPixelEvent,
+    fireMetaPurchase,
+} from "../providers/meta-pixel";
+import {
+    META_STANDARD_EVENTS,
+    type EcommercePayload,
+    type GA4Item,
+    type MetaStandardEventName,
+} from "../events/meta-events";
+
+export {
+    META_STANDARD_EVENTS,
+    type EcommercePayload,
+    type GA4Item,
+    type MetaStandardEventName,
+};
+
+const GA4_TO_META_EVENT: Record<string, MetaStandardEventName> = {
+    add_to_cart: META_STANDARD_EVENTS.AddToCart,
+    view_item: META_STANDARD_EVENTS.ViewContent,
+    view_cart: META_STANDARD_EVENTS.ViewContent,
+    begin_checkout: META_STANDARD_EVENTS.InitiateCheckout,
+    add_payment_info: META_STANDARD_EVENTS.AddPaymentInfo,
+    purchase: META_STANDARD_EVENTS.Purchase,
+};
+
+type CartLineLike = {
+    id: string;
+    variant_id?: string;
+    title?: string;
+    product_title?: string;
+    quantity: number;
+    total?: number;
+};
+
+type CartLike = {
+    items?: CartLineLike[];
+    total?: number;
+    currency_code?: string;
+    region?: { currency_code?: string };
+};
+
+function pushToDataLayer(obj: Record<string, unknown>) {
+    if (typeof window === "undefined") return;
+    const w = window as Window & { dataLayer?: unknown[] };
+    w.dataLayer = w.dataLayer || [];
+    w.dataLayer.push({ ecommerce: null });
+    w.dataLayer.push(obj);
+}
+
+function normalizeCurrency(currency?: string) {
+    return (currency ?? "INR").toUpperCase();
+}
+
+function buildMetaFields(payload: EcommercePayload) {
+    const items = payload.items ?? [];
+    const numItems = items.reduce((sum, i) => sum + (i.quantity ?? 1), 0);
+    return {
+        currency: normalizeCurrency(payload.currency),
+        value: payload.value,
+        content_ids: items.map((i) => String(i.item_id)),
+        content_type: "product",
+        contents: items.map((i) => ({
+            id: String(i.item_id),
+            quantity: i.quantity ?? 1,
+            item_price: i.price ?? 0,
+        })),
+        num_items: numItems,
+    };
+}
+
+function pushEcommerceEvent(
+    event: string,
+    payload: EcommercePayload,
+    extra?: Record<string, unknown>
+) {
+    const currency = normalizeCurrency(payload.currency);
+    const ecommerce = { ...payload, currency };
+    const metaFields = buildMetaFields({ ...payload, currency });
+
+    pushToDataLayer({
+        event,
+        ecommerce,
+        ...metaFields,
+        ...extra,
+    });
+
+    const metaEvent = GA4_TO_META_EVENT[event];
+    if (metaEvent) {
+        if (event === "purchase" && extra?.transaction_id) {
+            fireMetaPurchase({
+                ...payload,
+                currency,
+                transaction_id: String(extra.transaction_id),
+            });
+        } else {
+            fireMetaEcommerceEvent(metaEvent, { ...payload, currency }, extra);
+        }
+    }
+}
+
+export function trackMetaStandardEvent(
+    metaEvent: MetaStandardEventName,
+    params?: Record<string, unknown>
+) {
+    fireMetaPixelEvent(metaEvent, params ?? {});
+}
+
+export function cartToEcommercePayload(cart: CartLike | null): EcommercePayload | null {
+    if (!cart?.items?.length) return null;
+
+    const currency = normalizeCurrency(cart.currency_code ?? cart.region?.currency_code);
+    const value = (cart.total ?? 0) / 100;
+    const items = cart.items.map((item, index) => {
+        const unitTotal = item.total && item.quantity ? item.total / item.quantity : 0;
+        return {
+            item_id: item.variant_id ?? item.id,
+            item_name: item.title ?? item.product_title ?? "",
+            price: unitTotal / 100,
+            quantity: item.quantity,
+            index,
+        };
+    });
+
+    return { currency, value, items };
+}
+
+export function trackAddToCart(payload: EcommercePayload) {
+    pushEcommerceEvent("add_to_cart", payload);
+}
+
+export function trackRemoveFromCart(payload: EcommercePayload) {
+    pushEcommerceEvent("remove_from_cart", payload);
+}
+
+export function trackViewCart(payload: EcommercePayload) {
+    pushEcommerceEvent("view_cart", payload);
+}
+
+export function trackViewItem(payload: EcommercePayload) {
+    pushEcommerceEvent("view_item", payload);
+}
+
+export function trackViewItemList(payload: {
+    list_id?: string;
+    list_name?: string;
+    items: GA4Item[];
+}) {
+    const meta = buildMetaFields({
+        currency: "INR",
+        value: 0,
+        items: payload.items,
+    });
+    pushToDataLayer({
+        event: "view_item_list",
+        ecommerce: payload,
+        ...meta,
+    });
+    fireMetaEcommerceEvent(META_STANDARD_EVENTS.ViewContent, {
+        currency: "INR",
+        value: 0,
+        items: payload.items,
+    });
+}
+
+const INITIATE_CHECKOUT_KEY_PREFIX = "meta_initiate_checkout_";
+
+export function markInitiateCheckoutFired(cartId: string) {
+    if (typeof window === "undefined") return;
+    sessionStorage.setItem(`${INITIATE_CHECKOUT_KEY_PREFIX}${cartId}`, String(Date.now()));
+}
+
+export function wasInitiateCheckoutFired(cartId: string, maxAgeMs = 60_000) {
+    if (typeof window === "undefined") return false;
+    const raw = sessionStorage.getItem(`${INITIATE_CHECKOUT_KEY_PREFIX}${cartId}`);
+    if (!raw) return false;
+    return Date.now() - Number(raw) < maxAgeMs;
+}
+
+export function trackInitiateCheckoutFromCart(payload: EcommercePayload, cartId?: string) {
+    trackBeginCheckout(payload);
+    if (cartId) markInitiateCheckoutFired(cartId);
+}
+
+export function trackBeginCheckout(payload: EcommercePayload) {
+    pushEcommerceEvent("begin_checkout", payload);
+}
+
+export function trackAddShippingInfo(payload: EcommercePayload) {
+    pushEcommerceEvent("add_shipping_info", payload);
+}
+
+export function trackAddPaymentInfo(payload: EcommercePayload, extra?: Record<string, unknown>) {
+    pushEcommerceEvent("add_payment_info", payload, extra);
+}
+
+export function trackPurchase(payload: {
+    transaction_id: string;
+    currency: string;
+    value: number;
+    tax?: number;
+    shipping?: number;
+    items: GA4Item[];
+}) {
+    const { transaction_id, ...rest } = payload;
+    pushEcommerceEvent("purchase", rest, {
+        transaction_id,
+        order_id: transaction_id,
+    });
+}
+
+export function trackAddToWishlist(params: {
+    content_ids: string[];
+    currency?: string;
+    value?: number;
+}) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.AddToWishlist, {
+        content_ids: params.content_ids,
+        content_type: "product",
+        currency: normalizeCurrency(params.currency),
+        value: params.value ?? 0,
+    });
+}
+
+export function trackCompleteRegistration(params?: { status?: string; method?: string }) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.CompleteRegistration, params);
+}
+
+export function trackContact(params?: { form_type?: string }) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.Contact, params);
+}
+
+export function trackLead(params?: { form_type?: string }) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.Lead, params);
+}
+
+export function trackSearch(searchString: string) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.Search, {
+        search_string: searchString,
+    });
+}
+
+export function trackHeroCtaClick(params: { label?: string; link?: string }) {
+    trackMetaStandardEvent(META_STANDARD_EVENTS.ViewContent, {
+        content_type: "cta",
+        content_name: params.label || "shop_now",
+        content_category: "hero_banner",
+        ...(params.link ? { content_url: params.link } : {}),
+    });
+}
+
+export function trackCartNavClick(cart: CartLike | null) {
+    const payload = cartToEcommercePayload(cart);
+    if (payload) trackViewCart(payload);
+}

package/src/events/forms.ts

@@ -0,0 +1,34 @@
+import type { FormSubmittedPayload, StorefrontAnalyticsAdapter } from "../core/types";
+
+export function emitFormSubmitted(
+    analytics: StorefrontAnalyticsAdapter | undefined,
+    payload: FormSubmittedPayload
+): void {
+    analytics?.trackFormSubmitted?.(payload);
+    analytics?.trackEvent?.("form_submit", payload);
+}
+
+export function emitContactFormSubmitted(
+    analytics: StorefrontAnalyticsAdapter | undefined,
+    params?: { formType?: string; [key: string]: unknown }
+): void {
+    emitFormSubmitted(analytics, {
+        form_type: params?.formType ?? "contact_us_form",
+        ...params,
+    });
+}
+
+export function emitLeadCaptured(
+    analytics: StorefrontAnalyticsAdapter | undefined,
+    params?: { formType?: string; [key: string]: unknown }
+): void {
+    if (!analytics) return;
+    analytics.trackEvent?.("Lead", {
+        form_type: params?.formType ?? "newsletter_signup",
+        ...params,
+    });
+    emitFormSubmitted(analytics, {
+        form_type: params?.formType ?? "lead",
+        ...params,
+    });
+}

package/src/events/meta-events.ts

@@ -0,0 +1,31 @@
+/** Meta Pixel standard event names (fbq second argument) */
+export const META_STANDARD_EVENTS = {
+    AddPaymentInfo: "AddPaymentInfo",
+    AddToCart: "AddToCart",
+    AddToWishlist: "AddToWishlist",
+    CompleteRegistration: "CompleteRegistration",
+    Contact: "Contact",
+    InitiateCheckout: "InitiateCheckout",
+    Lead: "Lead",
+    Purchase: "Purchase",
+    Search: "Search",
+    ViewContent: "ViewContent",
+} as const;
+
+export type MetaStandardEventName =
+    (typeof META_STANDARD_EVENTS)[keyof typeof META_STANDARD_EVENTS];
+
+export type GA4Item = {
+    item_id: string;
+    item_name: string;
+    price?: number;
+    quantity?: number;
+    index?: number;
+    item_variant?: string;
+};
+
+export type EcommercePayload = {
+    currency: string;
+    value: number;
+    items: GA4Item[];
+};

package/src/events/reviews.ts

@@ -0,0 +1,25 @@
+import type { ReviewSubmittedPayload, StorefrontAnalyticsAdapter } from "../core/types";
+
+/**
+ * Domain helper: call after a review is successfully saved.
+ */
+export function emitReviewSubmitted(
+    analytics: StorefrontAnalyticsAdapter | undefined,
+    payload: Omit<ReviewSubmittedPayload, "isUpdate"> & { isUpdate?: boolean }
+): void {
+    if (!analytics) return;
+
+    const full: ReviewSubmittedPayload = {
+        productId: payload.productId,
+        productName: payload.productName,
+        rating: payload.rating,
+        reviewTitle: payload.reviewTitle,
+        isUpdate: payload.isUpdate ?? false,
+    };
+
+    if (full.isUpdate && analytics.trackReviewUpdated) {
+        analytics.trackReviewUpdated(full);
+    } else {
+        analytics.trackReviewSubmitted(full);
+    }
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+export type {
+    AnalyticsEventMap,
+    FormSubmittedPayload,
+    ProductRef,
+    ReviewSubmittedPayload,
+    StorefrontAnalyticsAdapter,
+} from "./core/types";
+
+export { noopAnalyticsAdapter } from "./core/noop-adapter";
+export { composeAnalyticsAdapters } from "./core/compose";
+
+export {
+    createGtmAnalyticsAdapter,
+    defaultStorefrontAnalytics,
+    pushToDataLayer,
+    trackGtmEvent,
+    trackEvent,
+    initGTM,
+    type GtmAnalyticsAdapterOptions,
+} from "./providers/gtm";
+
+export { emitReviewSubmitted } from "./events/reviews";
+export {
+    emitContactFormSubmitted,
+    emitFormSubmitted,
+    emitLeadCaptured,
+} from "./events/forms";
+
+export {
+    META_STANDARD_EVENTS,
+    type EcommercePayload,
+    type GA4Item,
+    type MetaStandardEventName,
+} from "./events/meta-events";
+
+export {
+    META_PIXEL_DATALAYER_EVENT,
+    fireMetaPixelEvent,
+    fireMetaEcommerceEvent,
+    fireMetaPurchase,
+} from "./providers/meta-pixel";
+
+export {
+    META_EXPLICIT_KEY,
+    disableMetaPixelAutoConfig,
+    installMetaPixelGuard,
+} from "./providers/meta-pixel-guard";
+
+export { POST as metaCapiEventHandler } from "./api/meta-event";
+export type { MetaCapiEventBody } from "./api/meta-event";
+
+export {
+    cartToEcommercePayload,
+    markInitiateCheckoutFired,
+    trackAddPaymentInfo,
+    trackAddShippingInfo,
+    trackAddToCart,
+    trackAddToWishlist,
+    trackBeginCheckout,
+    trackCartNavClick,
+    trackCompleteRegistration,
+    trackContact,
+    trackHeroCtaClick,
+    trackInitiateCheckoutFromCart,
+    trackLead,
+    trackMetaStandardEvent,
+    trackPurchase,
+    trackRemoveFromCart,
+    trackSearch,
+    trackViewCart,
+    trackViewItem,
+    trackViewItemList,
+    wasInitiateCheckoutFired,
+} from "./ecommerce/ga4-ecommerce";

package/src/providers/gtm.ts

@@ -0,0 +1,97 @@
+import type {
+    FormSubmittedPayload,
+    ReviewSubmittedPayload,
+    StorefrontAnalyticsAdapter,
+} from "../core/types";
+
+declare global {
+    interface Window {
+        dataLayer?: Record<string, unknown>[];
+    }
+}
+
+export function pushToDataLayer(data: Record<string, unknown>): void {
+    if (typeof window === "undefined") return;
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push(data);
+}
+
+export function trackGtmEvent(eventName: string, params?: Record<string, unknown>): void {
+    pushToDataLayer({
+        event: eventName,
+        ...params,
+    });
+}
+
+export interface GtmAnalyticsAdapterOptions {
+    /** Also push legacy `form_submit` events (for existing GTM triggers) */
+    legacyFormSubmit?: boolean;
+}
+
+/**
+ * Default GTM / dataLayer adapter for Medusa storefronts.
+ */
+export function createGtmAnalyticsAdapter(
+    options: GtmAnalyticsAdapterOptions = {}
+): StorefrontAnalyticsAdapter {
+    const { legacyFormSubmit = true } = options;
+
+    const pushReview = (payload: ReviewSubmittedPayload, eventName: "review_submitted" | "review_updated") => {
+        trackGtmEvent(eventName, {
+            product_id: payload.productId,
+            product_name: payload.productName,
+            rating: payload.rating,
+            review_title: payload.reviewTitle,
+            is_update: payload.isUpdate,
+        });
+
+        if (legacyFormSubmit) {
+            trackGtmEvent("form_submit", {
+                form_type:
+                    eventName === "review_updated"
+                        ? "product_review_update"
+                        : "product_review_submit",
+                product_id: payload.productId,
+                product_name: payload.productName,
+                rating: payload.rating,
+            });
+        }
+    };
+
+    return {
+        trackReviewSubmitted(payload) {
+            pushReview({ ...payload, isUpdate: false }, "review_submitted");
+        },
+        trackReviewUpdated(payload) {
+            pushReview({ ...payload, isUpdate: true }, "review_updated");
+        },
+        trackFormSubmitted(payload: FormSubmittedPayload) {
+            trackGtmEvent("form_submit", payload);
+        },
+        trackEvent: trackGtmEvent,
+    };
+}
+
+/** Default GTM adapter (legacy form_submit + review events). */
+export const defaultStorefrontAnalytics = createGtmAnalyticsAdapter({
+    legacyFormSubmit: true,
+});
+
+/** @deprecated Use createGtmAnalyticsAdapter */
+export const initGTM = (id: string) => {
+    if (typeof window === "undefined") return;
+    pushToDataLayer({
+        "gtm.start": new Date().getTime(),
+        event: "gtm.js",
+    });
+    const firstScript = document.getElementsByTagName("script")[0];
+    const script = document.createElement("script") as HTMLScriptElement;
+    script.async = true;
+    script.src = `https://www.googletagmanager.com/gtm.js?id=${id}`;
+    if (firstScript?.parentNode) {
+        firstScript.parentNode.insertBefore(script, firstScript);
+    }
+};
+
+/** @deprecated Use trackGtmEvent */
+export const trackEvent = trackGtmEvent;

package/src/providers/meta-pixel-guard.ts

@@ -0,0 +1,96 @@
+/**
+ * Blocks Meta automatic mis-classification (e.g. Subscribe on non-newsletter clicks).
+ * Only events fired via fireMetaPixelEvent() include __cm_explicit and pass through.
+ */
+
+export const META_EXPLICIT_KEY = "__cm_explicit";
+
+/** Disable Meta pixel automatic event configuration (button scraping, etc.) */
+export function disableMetaPixelAutoConfig() {
+    if (typeof window === "undefined") return false;
+    const fbq = (window as Window & { fbq?: (...args: unknown[]) => void }).fbq;
+    if (typeof fbq !== "function") return false;
+
+    try {
+        fbq("set", "autoConfig", false);
+    } catch {
+        // Pixel may not be fully initialized yet
+    }
+    return true;
+}
+
+function shouldBlockMetaTrack(eventName: unknown, params: unknown): boolean {
+    if (typeof eventName !== "string") return false;
+    if (eventName === "Subscribe") {
+        const p = params as Record<string, unknown> | undefined;
+        return !p?.[META_EXPLICIT_KEY];
+    }
+    return false;
+}
+
+function patchFbq() {
+    if (typeof window === "undefined") return false;
+    const w = window as Window & {
+        fbq?: (...args: unknown[]) => void;
+        _fbq?: (...args: unknown[]) => void;
+        __cmFbqPatched?: boolean;
+    };
+    const fbq = w.fbq;
+    if (typeof fbq !== "function" || w.__cmFbqPatched) return true;
+
+    const original = fbq;
+    const patched = function (this: unknown, ...args: unknown[]) {
+        if (args[0] === "track" && shouldBlockMetaTrack(args[1], args[2])) {
+            return;
+        }
+        return original.apply(this, args);
+    };
+    Object.assign(patched, original);
+    w.fbq = patched;
+    if (w._fbq) w._fbq = patched;
+    w.__cmFbqPatched = true;
+    return true;
+}
+
+function patchDataLayer() {
+    if (typeof window === "undefined") return false;
+    const w = window as Window & {
+        dataLayer?: unknown[];
+        __cmDataLayerPatched?: boolean;
+    };
+    if (!w.dataLayer || w.__cmDataLayerPatched) return true;
+
+    const originalPush = w.dataLayer.push.bind(w.dataLayer);
+    w.dataLayer.push = function (...items: unknown[]) {
+        const filtered = items.filter((item) => {
+            if (!item || typeof item !== "object") return true;
+            const obj = item as Record<string, unknown>;
+            const metaEvent = obj.meta_event;
+            if (metaEvent === "Subscribe" && !obj[META_EXPLICIT_KEY]) return false;
+            if (obj.event === "subscribe" && !obj[META_EXPLICIT_KEY]) return false;
+            return true;
+        });
+        return originalPush(...filtered);
+    };
+    w.__cmDataLayerPatched = true;
+    return true;
+}
+
+/** Call once on app load; retries until GTM/pixel has initialized fbq */
+export function installMetaPixelGuard() {
+    if (typeof window === "undefined") return;
+
+    patchDataLayer();
+
+    let attempts = 0;
+    const maxAttempts = 60;
+    const tick = () => {
+        patchDataLayer();
+        const fbqReady = patchFbq();
+        if (fbqReady) disableMetaPixelAutoConfig();
+        if (!fbqReady && ++attempts < maxAttempts) {
+            setTimeout(tick, 250);
+        }
+    };
+    tick();
+}

package/src/providers/meta-pixel.ts

@@ -0,0 +1,77 @@
+/**
+ * Meta Pixel standard events — explicit fbq + dedicated dataLayer pushes.
+ */
+
+import {
+    META_STANDARD_EVENTS,
+    type EcommercePayload,
+    type MetaStandardEventName,
+} from "../events/meta-events";
+import { META_EXPLICIT_KEY } from "./meta-pixel-guard";
+
+export { META_STANDARD_EVENTS, type MetaStandardEventName, type EcommercePayload };
+
+export const META_PIXEL_DATALAYER_EVENT = "meta_pixel_track";
+
+type FbqFn = (...args: unknown[]) => void;
+
+function normalizeCurrency(currency?: string) {
+    return (currency ?? "INR").toUpperCase();
+}
+
+function buildMetaParams(payload: EcommercePayload) {
+    const items = payload.items ?? [];
+    const numItems = items.reduce((sum, i) => sum + (i.quantity ?? 1), 0);
+    return {
+        currency: normalizeCurrency(payload.currency),
+        value: payload.value,
+        content_ids: items.map((i) => String(i.item_id)),
+        content_type: "product",
+        contents: items.map((i) => ({
+            id: String(i.item_id),
+            quantity: i.quantity ?? 1,
+            item_price: i.price ?? 0,
+        })),
+        num_items: numItems,
+    };
+}
+
+function pushMetaDataLayer(metaEvent: MetaStandardEventName, params: Record<string, unknown>) {
+    if (typeof window === "undefined") return;
+    const w = window as Window & { dataLayer?: unknown[] };
+    w.dataLayer = w.dataLayer || [];
+    w.dataLayer.push({
+        event: META_PIXEL_DATALAYER_EVENT,
+        meta_event: metaEvent,
+        [META_EXPLICIT_KEY]: true,
+        ...params,
+    });
+}
+
+export function fireMetaPixelEvent(
+    metaEvent: MetaStandardEventName,
+    params: Record<string, unknown> = {}
+) {
+    pushMetaDataLayer(metaEvent, params);
+
+    if (typeof window === "undefined") return;
+    const fbq = (window as Window & { fbq?: FbqFn }).fbq;
+    if (typeof fbq === "function") {
+        fbq("track", metaEvent, { ...params, [META_EXPLICIT_KEY]: true });
+    }
+}
+
+export function fireMetaEcommerceEvent(
+    metaEvent: MetaStandardEventName,
+    payload: EcommercePayload,
+    extra?: Record<string, unknown>
+) {
+    fireMetaPixelEvent(metaEvent, { ...buildMetaParams(payload), ...extra });
+}
+
+export function fireMetaPurchase(payload: EcommercePayload & { transaction_id: string }) {
+    const { transaction_id, ...ecommerce } = payload;
+    fireMetaEcommerceEvent(META_STANDARD_EVENTS.Purchase, ecommerce, {
+        order_id: transaction_id,
+    });
+}