medusa-storefront-analytics 1.2.0 → 1.4.0

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();
+}