@chordcommerce/analytics 1.21.2 → 1.22.0-beta.2

package/dist/cjs/client/identifiers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shopify Identifier Sync
+ *
+ * Syncs CDP anonymous ID and Google Client ID to Shopify cart attributes.
+ * This enables server-side events (webhooks) to correlate with client-side tracking.
+ */
+export interface ShopifyCart {
+    attributes?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface IdentifierSyncOptions {
+    /**
+     * Base URL for Shopify AJAX API calls. Defaults to window.location.origin
+     */
+    baseUrl?: string;
+    /**
+     * Locale path for Shopify routes. Defaults to window.Shopify.routes.root or '/'
+     */
+    localePath?: string;
+    /**
+     * Custom identifier getters. By default, reads CDP anonymous ID and Google Client ID.
+     */
+    identifiers?: () => Record<string, string>;
+}
+/**
+ * Get a cookie value by name
+ */
+export declare const getCookie: (name: string) => string | undefined;
+/**
+ * Get default identifiers (CDP anonymous ID and Google Client ID)
+ */
+export declare const getDefaultIdentifiers: () => Record<string, string>;
+/**
+ * Fetch the current Shopify cart
+ */
+export declare const getShopifyCart: (baseUrl?: string, localePath?: string) => Promise<ShopifyCart>;
+/**
+ * Update Shopify cart attributes
+ */
+export declare const updateShopifyCartAttributes: (attributes: Record<string, string>, baseUrl?: string, localePath?: string) => Promise<ShopifyCart>;
+/**
+ * Sync CDP and analytics identifiers to Shopify cart attributes.
+ *
+ * By default, syncs the Chord CDP anonymous ID (`__eventn_id` cookie) and
+ * Google Analytics client ID (`_ga` cookie) to the cart. These attributes
+ * are included in Shopify order webhooks, enabling server-side events to
+ * correlate with client-side tracking sessions.
+ *
+ * Smart deduplication: only updates the cart if identifiers are missing or
+ * have changed, avoiding unnecessary API calls on repeat page loads.
+ *
+ * @param options - Optional configuration for base URL, locale path, or custom identifier getter
+ * @returns The updated cart, or undefined if no update was needed or an error occurred
+ */
+export declare const syncIdentifiersToCart: (options?: IdentifierSyncOptions) => Promise<ShopifyCart | undefined>;

package/dist/cjs/client/identifiers.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Shopify Identifier Sync
+ *
+ * Syncs CDP anonymous ID and Google Client ID to Shopify cart attributes.
+ * This enables server-side events (webhooks) to correlate with client-side tracking.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncIdentifiersToCart = exports.updateShopifyCartAttributes = exports.getShopifyCart = exports.getDefaultIdentifiers = exports.getCookie = void 0;
+/**
+ * Get a cookie value by name
+ */
+var getCookie = function (name) {
+    var _a;
+    if (typeof document === 'undefined')
+        return undefined;
+    return (_a = document.cookie
+        .split('; ')
+        .find(function (row) { return row.startsWith("".concat(name, "=")); })) === null || _a === void 0 ? void 0 : _a.split('=')[1];
+};
+exports.getCookie = getCookie;
+/**
+ * Get default identifiers (CDP anonymous ID and Google Client ID)
+ */
+var getDefaultIdentifiers = function () {
+    var attributes = {};
+    try {
+        // CDP anonymous ID (Jitsu/Chord CDP)
+        var anonymousId = (0, exports.getCookie)('__eventn_id');
+        if (anonymousId) {
+            // eslint-disable-next-line no-underscore-dangle
+            attributes._cdpAnonymousId = anonymousId;
+        }
+        // Google Client ID (strip the "GA1.1." or similar prefix)
+        var gaCookie = (0, exports.getCookie)('_ga');
+        if (gaCookie) {
+            var googleClientId = gaCookie.substring(6);
+            if (googleClientId) {
+                // eslint-disable-next-line no-underscore-dangle
+                attributes._googleClientId = googleClientId;
+            }
+        }
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[Chord Analytics]: Error getting identifiers:', e);
+    }
+    return attributes;
+};
+exports.getDefaultIdentifiers = getDefaultIdentifiers;
+/**
+ * Construct a URL for Shopify AJAX API calls
+ */
+var constructUrl = function (path, baseUrl, localePath) {
+    var _a, _b;
+    var defaultBaseUrl = typeof window !== 'undefined' ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined;
+    // Access Shopify.routes.root for locale-aware URLs (cast needed as Window.Shopify type is partial)
+    var shopify = window === null || window === void 0 ? void 0 : window.Shopify;
+    var defaultLocalePath = ((_b = shopify === null || shopify === void 0 ? void 0 : shopify.routes) === null || _b === void 0 ? void 0 : _b.root) || '/';
+    var resolvedBaseUrl = baseUrl !== null && baseUrl !== void 0 ? baseUrl : defaultBaseUrl;
+    var resolvedLocalePath = localePath !== null && localePath !== void 0 ? localePath : defaultLocalePath;
+    var pathWithLocale = "".concat(resolvedLocalePath).concat(path);
+    if (!resolvedBaseUrl) {
+        return pathWithLocale.startsWith('/')
+            ? pathWithLocale
+            : "/".concat(pathWithLocale);
+    }
+    return new URL(pathWithLocale, resolvedBaseUrl);
+};
+/**
+ * Fetch the current Shopify cart
+ */
+var getShopifyCart = function (baseUrl, localePath) { return __awaiter(void 0, void 0, void 0, function () {
+    var url, response;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                url = constructUrl('cart.js', baseUrl, localePath);
+                return [4 /*yield*/, fetch(url)];
+            case 1:
+                response = _a.sent();
+                if (!response.ok) {
+                    throw new Error("Failed to fetch cart: ".concat(response.status));
+                }
+                return [2 /*return*/, response.json()];
+        }
+    });
+}); };
+exports.getShopifyCart = getShopifyCart;
+/**
+ * Update Shopify cart attributes
+ */
+var updateShopifyCartAttributes = function (attributes, baseUrl, localePath) { return __awaiter(void 0, void 0, void 0, function () {
+    var url, response;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                url = constructUrl('cart/update.js', baseUrl, localePath);
+                return [4 /*yield*/, fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify({ attributes: attributes }),
+                    })];
+            case 1:
+                response = _a.sent();
+                if (!response.ok) {
+                    throw new Error("Failed to update cart attributes: ".concat(response.status));
+                }
+                return [2 /*return*/, response.json()];
+        }
+    });
+}); };
+exports.updateShopifyCartAttributes = updateShopifyCartAttributes;
+/**
+ * Sync CDP and analytics identifiers to Shopify cart attributes.
+ *
+ * By default, syncs the Chord CDP anonymous ID (`__eventn_id` cookie) and
+ * Google Analytics client ID (`_ga` cookie) to the cart. These attributes
+ * are included in Shopify order webhooks, enabling server-side events to
+ * correlate with client-side tracking sessions.
+ *
+ * Smart deduplication: only updates the cart if identifiers are missing or
+ * have changed, avoiding unnecessary API calls on repeat page loads.
+ *
+ * @param options - Optional configuration for base URL, locale path, or custom identifier getter
+ * @returns The updated cart, or undefined if no update was needed or an error occurred
+ */
+var syncIdentifiersToCart = function (options) {
+    if (options === void 0) { options = {}; }
+    return __awaiter(void 0, void 0, void 0, function () {
+        var baseUrl, localePath, _a, identifiers, cart_1, attributesToAdd_1, identifiersAlreadyExist, updatedCart, e_1;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    _b.trys.push([0, 3, , 4]);
+                    baseUrl = options.baseUrl, localePath = options.localePath, _a = options.identifiers, identifiers = _a === void 0 ? exports.getDefaultIdentifiers : _a;
+                    return [4 /*yield*/, (0, exports.getShopifyCart)(baseUrl, localePath)];
+                case 1:
+                    cart_1 = _b.sent();
+                    attributesToAdd_1 = identifiers();
+                    identifiersAlreadyExist = Object.keys(attributesToAdd_1).every(function (key) { var _a; return ((_a = cart_1 === null || cart_1 === void 0 ? void 0 : cart_1.attributes) === null || _a === void 0 ? void 0 : _a[key]) === attributesToAdd_1[key]; });
+                    if (identifiersAlreadyExist) {
+                        return [2 /*return*/, undefined];
+                    }
+                    return [4 /*yield*/, (0, exports.updateShopifyCartAttributes)(attributesToAdd_1, baseUrl, localePath)];
+                case 2:
+                    updatedCart = _b.sent();
+                    return [2 /*return*/, updatedCart];
+                case 3:
+                    e_1 = _b.sent();
+                    // eslint-disable-next-line no-console
+                    console.error('[Chord Analytics]: Error syncing identifiers to cart:', e_1);
+                    return [2 /*return*/, undefined];
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+};
+exports.syncIdentifiersToCart = syncIdentifiersToCart;

package/dist/cjs/client/index.d.ts

@@ -1,5 +1,6 @@
 import type { AnyAnalytics, EventProperties, Options, ValidateResult, ChordAnalyticsOptions, AnyOptions, CartViewedInput, IdentifyTraits, CheckoutStartedInput, CheckoutStepCompletedInput, CheckoutStepViewedInput, EmailCapturedInput, ProductListViewedInput, ProductListFilteredInput, ProductAddedInput, ProductClickedInput, VariantClickedInput, ProductRemovedInput, ProductViewedInput, ProductsSearchedInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, SignedInInput, SignedOutInput, SignedUpInput, LoginStartedInput, ObjectTypes, OrderCompletedInput, SubscriptionCancelledInput, NavigationClickedInput, PaymentInfoEnteredInput } from '../types/index.js';
 import { AnalyticsMiddleware } from '../types/client.js';
+import { type IdentifierSyncOptions, type ShopifyCart } from './identifiers.js';
 export interface ChordAnalyticsSnippet {
     _loadOptions: ChordAnalyticsOptions<ObjectTypes>;
     invoked: boolean;
@@ -151,6 +152,36 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      */
     private sendPageEvent;
     reset: () => Promise<void>;
+    /**
+     * Handler for postMessage events from the Shopify Web Pixel sandbox.
+     * Bound to the instance for proper `this` context and cleanup.
+     */
+    private webPixelMessageHandler;
+    /**
+     * Set up a listener for postMessage events from the Shopify Web Pixel sandbox.
+     * This allows the web pixel (running in Shopify's sandboxed iframe)
+     * to forward analytics events to this ChordAnalytics instance on the storefront.
+     *
+     * The web pixel sends messages in the format:
+     * - { source: 'chord-web-pixel', type: 'track', payload: [eventName, properties] }
+     * - { source: 'chord-web-pixel', type: 'identify', payload: [userId, traits] }
+     * - { source: 'chord-web-pixel', type: 'page', payload: [properties] }
+     *
+     * @returns A cleanup function to remove the listener
+     */
+    setupWebPixelListener: () => (() => void);
+    /**
+     * Sync CDP anonymous ID and Google Client ID to Shopify cart attributes.
+     * This enables server-side events (webhooks) to correlate with client-side tracking.
+     *
+     * By default, syncs:
+     * - `_cdpAnonymousId`: from the `__eventn_id` cookie (Chord/Jitsu CDP)
+     * - `_googleClientId`: from the `_ga` cookie (Google Analytics)
+     *
+     * @param options - Optional configuration for the sync
+     * @returns The updated cart, or undefined if no update was needed or an error occurred
+     */
+    syncIdentifiersToCart: (options?: IdentifierSyncOptions) => Promise<ShopifyCart | undefined>;
     trackCartViewed: (props: CartViewedInput<T>, options?: AnyOptions) => Promise<void>;
     trackCheckoutStarted: (props: CheckoutStartedInput<T>, options?: AnyOptions) => Promise<void>;
     trackCheckoutStepCompleted: (props: CheckoutStepCompletedInput, options?: AnyOptions) => Promise<void>;

package/dist/cjs/client/index.js

@@ -61,6 +61,7 @@ var cdp_js_1 = require("./cdp.js");
 var index_js_1 = require("./consent/index.js");
 var index_js_2 = require("../validators/index.js");
 var utils_js_1 = require("../utils.js");
+var identifiers_js_1 = require("./identifiers.js");
 var DEBUG_MODE_STORAGE_KEY = 'chordcommerce/analytics/debug';
 var CONSENT_QUEUE_STORAGE_KEY = 'chordcommerce/analytics/consent-queue';
 var CONSENT_QUEUE_TTL_MS = 5 * 60 * 1000; // 5 minutes
@@ -69,7 +70,7 @@ var CONSENT_QUEUE_MAX_EVENTS = 50; // Max number of events to queue
 var ChordAnalytics = /** @class */ (function () {
     function ChordAnalytics(options) {
         var _this = this;
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         /**
          * Allows snippet.js to detect whether this library has been initialized yet.
          */
@@ -791,6 +792,107 @@ var ChordAnalytics = /** @class */ (function () {
                 }
             });
         }); };
+        /**
+         * Handler for postMessage events from the Shopify Web Pixel sandbox.
+         * Bound to the instance for proper `this` context and cleanup.
+         */
+        this.webPixelMessageHandler = null;
+        /**
+         * Set up a listener for postMessage events from the Shopify Web Pixel sandbox.
+         * This allows the web pixel (running in Shopify's sandboxed iframe)
+         * to forward analytics events to this ChordAnalytics instance on the storefront.
+         *
+         * The web pixel sends messages in the format:
+         * - { source: 'chord-web-pixel', type: 'track', payload: [eventName, properties] }
+         * - { source: 'chord-web-pixel', type: 'identify', payload: [userId, traits] }
+         * - { source: 'chord-web-pixel', type: 'page', payload: [properties] }
+         *
+         * @returns A cleanup function to remove the listener
+         */
+        this.setupWebPixelListener = function () {
+            if (typeof window === 'undefined') {
+                _this.logger('[Chord Analytics]: setupWebPixelListener called in non-browser environment');
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                return function () { };
+            }
+            // Remove existing listener if one exists
+            if (_this.webPixelMessageHandler) {
+                window.removeEventListener('message', _this.webPixelMessageHandler);
+            }
+            _this.webPixelMessageHandler = function (event) {
+                // Validate message structure
+                if (!event.data || typeof event.data !== 'object')
+                    return;
+                if (event.data.source !== 'chord-web-pixel')
+                    return;
+                var message = event.data;
+                if (_this.options.enableLogging && _this.options.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log('[Chord Analytics DEBUG]: Received web pixel message:', message.type, message.payload);
+                }
+                try {
+                    switch (message.type) {
+                        case 'track': {
+                            var _a = message.payload, eventName = _a[0], properties = _a[1];
+                            if (eventName) {
+                                _this.track(eventName, properties);
+                            }
+                            break;
+                        }
+                        case 'identify': {
+                            var _b = message.payload, userId = _b[0], traits = _b[1];
+                            _this.identify(userId, traits);
+                            break;
+                        }
+                        case 'page': {
+                            var properties = message.payload[0];
+                            _this.page(properties);
+                            break;
+                        }
+                        default:
+                            _this.logger("[Chord Analytics]: Unknown web pixel message type: ".concat(message.type));
+                    }
+                }
+                catch (error) {
+                    _this.logger('[Chord Analytics]: Error processing web pixel message:', error);
+                }
+            };
+            window.addEventListener('message', _this.webPixelMessageHandler);
+            _this.logger('[Chord Analytics]: Web pixel listener initialized');
+            // Return cleanup function
+            return function () {
+                if (_this.webPixelMessageHandler) {
+                    window.removeEventListener('message', _this.webPixelMessageHandler);
+                    _this.webPixelMessageHandler = null;
+                    _this.logger('[Chord Analytics]: Web pixel listener removed');
+                }
+            };
+        };
+        /**
+         * Sync CDP anonymous ID and Google Client ID to Shopify cart attributes.
+         * This enables server-side events (webhooks) to correlate with client-side tracking.
+         *
+         * By default, syncs:
+         * - `_cdpAnonymousId`: from the `__eventn_id` cookie (Chord/Jitsu CDP)
+         * - `_googleClientId`: from the `_ga` cookie (Google Analytics)
+         *
+         * @param options - Optional configuration for the sync
+         * @returns The updated cart, or undefined if no update was needed or an error occurred
+         */
+        this.syncIdentifiersToCart = function (options) { return __awaiter(_this, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, identifiers_js_1.syncIdentifiersToCart)(options)];
+                    case 1:
+                        result = _a.sent();
+                        if (result) {
+                            this.logger('[Chord Analytics]: Identifiers synced to cart');
+                        }
+                        return [2 /*return*/, result];
+                }
+            });
+        }); };
         // TODO: Add support for props.products
         this.trackCartViewed = function (props, options) { return __awaiter(_this, void 0, void 0, function () {
             var cart, payload, formattedPayload;
@@ -1345,6 +1447,18 @@ var ChordAnalytics = /** @class */ (function () {
             window[this.options.namespace] = (window === null || window === void 0 ? void 0 : window[this.options.namespace]) || this;
             this.initializeCdp();
         }
+        // Set up web pixel listener: explicit true/false takes precedence,
+        // otherwise auto-detect by checking for window.Shopify.shop (Liquid storefront)
+        var shouldEnableWebPixel = (_e = (_d = this.options) === null || _d === void 0 ? void 0 : _d.enableWebPixelListener) !== null && _e !== void 0 ? _e : (typeof window !== 'undefined' && !!((_f = window.Shopify) === null || _f === void 0 ? void 0 : _f.shop));
+        if (shouldEnableWebPixel) {
+            this.setupWebPixelListener();
+        }
+        // Sync identifiers to cart: explicit true/false takes precedence,
+        // otherwise auto-detect by checking for window.Shopify.shop (Liquid storefront)
+        var shouldEnableIdentifierSync = (_h = (_g = this.options) === null || _g === void 0 ? void 0 : _g.enableIdentifierSync) !== null && _h !== void 0 ? _h : (typeof window !== 'undefined' && !!((_j = window.Shopify) === null || _j === void 0 ? void 0 : _j.shop));
+        if (shouldEnableIdentifierSync) {
+            this.syncIdentifiersToCart();
+        }
     }
     /**
      * Initialize CDP snippet and wait for it to be ready.

package/dist/cjs/index.d.ts

@@ -1,2 +1,3 @@
 export * from './client/index.js';
+export * from './client/identifiers.js';
 export * from './types/index.js';

package/dist/cjs/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./client/index.js"), exports);
+__exportStar(require("./client/identifiers.js"), exports);
 __exportStar(require("./types/index.js"), exports);

package/dist/cjs/types/client.d.ts

@@ -34,6 +34,20 @@ export interface ChordAnalyticsOptions<T extends ObjectTypes = ObjectTypes> {
     awaitConsent?: boolean;
     debug?: boolean;
     enableLogging?: boolean;
+    /**
+     * Controls the postMessage listener for events from the Shopify Custom Web
+     * Pixel sandbox. When true, always enables the listener. When false, always
+     * disables it. When undefined (default), auto-detects by checking for
+     * window.Shopify.shop which is present on Shopify Liquid storefronts.
+     */
+    enableWebPixelListener?: boolean;
+    /**
+     * Controls syncing CDP anonymous ID and Google Client ID to Shopify cart
+     * attributes. When true, always enables sync. When false, always disables it.
+     * When undefined (default), auto-detects by checking for window.Shopify.shop
+     * which is present on Shopify Liquid storefronts.
+     */
+    enableIdentifierSync?: boolean;
     formatters: ChordAnalyticsFormatters<T>;
     namespace?: string;
     stripNull?: boolean;

package/dist/client/identifiers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shopify Identifier Sync
+ *
+ * Syncs CDP anonymous ID and Google Client ID to Shopify cart attributes.
+ * This enables server-side events (webhooks) to correlate with client-side tracking.
+ */
+export interface ShopifyCart {
+    attributes?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface IdentifierSyncOptions {
+    /**
+     * Base URL for Shopify AJAX API calls. Defaults to window.location.origin
+     */
+    baseUrl?: string;
+    /**
+     * Locale path for Shopify routes. Defaults to window.Shopify.routes.root or '/'
+     */
+    localePath?: string;
+    /**
+     * Custom identifier getters. By default, reads CDP anonymous ID and Google Client ID.
+     */
+    identifiers?: () => Record<string, string>;
+}
+/**
+ * Get a cookie value by name
+ */
+export declare const getCookie: (name: string) => string | undefined;
+/**
+ * Get default identifiers (CDP anonymous ID and Google Client ID)
+ */
+export declare const getDefaultIdentifiers: () => Record<string, string>;
+/**
+ * Fetch the current Shopify cart
+ */
+export declare const getShopifyCart: (baseUrl?: string, localePath?: string) => Promise<ShopifyCart>;
+/**
+ * Update Shopify cart attributes
+ */
+export declare const updateShopifyCartAttributes: (attributes: Record<string, string>, baseUrl?: string, localePath?: string) => Promise<ShopifyCart>;
+/**
+ * Sync CDP and analytics identifiers to Shopify cart attributes.
+ *
+ * By default, syncs the Chord CDP anonymous ID (`__eventn_id` cookie) and
+ * Google Analytics client ID (`_ga` cookie) to the cart. These attributes
+ * are included in Shopify order webhooks, enabling server-side events to
+ * correlate with client-side tracking sessions.
+ *
+ * Smart deduplication: only updates the cart if identifiers are missing or
+ * have changed, avoiding unnecessary API calls on repeat page loads.
+ *
+ * @param options - Optional configuration for base URL, locale path, or custom identifier getter
+ * @returns The updated cart, or undefined if no update was needed or an error occurred
+ */
+export declare const syncIdentifiersToCart: (options?: IdentifierSyncOptions) => Promise<ShopifyCart | undefined>;

package/dist/client/identifiers.js

@@ -0,0 +1,135 @@
+/**
+ * Shopify Identifier Sync
+ *
+ * Syncs CDP anonymous ID and Google Client ID to Shopify cart attributes.
+ * This enables server-side events (webhooks) to correlate with client-side tracking.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Get a cookie value by name
+ */
+export const getCookie = (name) => {
+    var _a;
+    if (typeof document === 'undefined')
+        return undefined;
+    return (_a = document.cookie
+        .split('; ')
+        .find((row) => row.startsWith(`${name}=`))) === null || _a === void 0 ? void 0 : _a.split('=')[1];
+};
+/**
+ * Get default identifiers (CDP anonymous ID and Google Client ID)
+ */
+export const getDefaultIdentifiers = () => {
+    const attributes = {};
+    try {
+        // CDP anonymous ID (Jitsu/Chord CDP)
+        const anonymousId = getCookie('__eventn_id');
+        if (anonymousId) {
+            // eslint-disable-next-line no-underscore-dangle
+            attributes._cdpAnonymousId = anonymousId;
+        }
+        // Google Client ID (strip the "GA1.1." or similar prefix)
+        const gaCookie = getCookie('_ga');
+        if (gaCookie) {
+            const googleClientId = gaCookie.substring(6);
+            if (googleClientId) {
+                // eslint-disable-next-line no-underscore-dangle
+                attributes._googleClientId = googleClientId;
+            }
+        }
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[Chord Analytics]: Error getting identifiers:', e);
+    }
+    return attributes;
+};
+/**
+ * Construct a URL for Shopify AJAX API calls
+ */
+const constructUrl = (path, baseUrl, localePath) => {
+    var _a, _b;
+    const defaultBaseUrl = typeof window !== 'undefined' ? (_a = window.location) === null || _a === void 0 ? void 0 : _a.origin : undefined;
+    // Access Shopify.routes.root for locale-aware URLs (cast needed as Window.Shopify type is partial)
+    const shopify = window === null || window === void 0 ? void 0 : window.Shopify;
+    const defaultLocalePath = ((_b = shopify === null || shopify === void 0 ? void 0 : shopify.routes) === null || _b === void 0 ? void 0 : _b.root) || '/';
+    const resolvedBaseUrl = baseUrl !== null && baseUrl !== void 0 ? baseUrl : defaultBaseUrl;
+    const resolvedLocalePath = localePath !== null && localePath !== void 0 ? localePath : defaultLocalePath;
+    const pathWithLocale = `${resolvedLocalePath}${path}`;
+    if (!resolvedBaseUrl) {
+        return pathWithLocale.startsWith('/')
+            ? pathWithLocale
+            : `/${pathWithLocale}`;
+    }
+    return new URL(pathWithLocale, resolvedBaseUrl);
+};
+/**
+ * Fetch the current Shopify cart
+ */
+export const getShopifyCart = (baseUrl, localePath) => __awaiter(void 0, void 0, void 0, function* () {
+    const url = constructUrl('cart.js', baseUrl, localePath);
+    const response = yield fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch cart: ${response.status}`);
+    }
+    return response.json();
+});
+/**
+ * Update Shopify cart attributes
+ */
+export const updateShopifyCartAttributes = (attributes, baseUrl, localePath) => __awaiter(void 0, void 0, void 0, function* () {
+    const url = constructUrl('cart/update.js', baseUrl, localePath);
+    const response = yield fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ attributes }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to update cart attributes: ${response.status}`);
+    }
+    return response.json();
+});
+/**
+ * Sync CDP and analytics identifiers to Shopify cart attributes.
+ *
+ * By default, syncs the Chord CDP anonymous ID (`__eventn_id` cookie) and
+ * Google Analytics client ID (`_ga` cookie) to the cart. These attributes
+ * are included in Shopify order webhooks, enabling server-side events to
+ * correlate with client-side tracking sessions.
+ *
+ * Smart deduplication: only updates the cart if identifiers are missing or
+ * have changed, avoiding unnecessary API calls on repeat page loads.
+ *
+ * @param options - Optional configuration for base URL, locale path, or custom identifier getter
+ * @returns The updated cart, or undefined if no update was needed or an error occurred
+ */
+export const syncIdentifiersToCart = (options = {}) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const { baseUrl, localePath, identifiers = getDefaultIdentifiers } = options;
+        const cart = yield getShopifyCart(baseUrl, localePath);
+        const attributesToAdd = identifiers();
+        // Check if all identifiers already exist with correct values
+        const identifiersAlreadyExist = Object.keys(attributesToAdd).every((key) => { var _a; return ((_a = cart === null || cart === void 0 ? void 0 : cart.attributes) === null || _a === void 0 ? void 0 : _a[key]) === attributesToAdd[key]; });
+        if (identifiersAlreadyExist) {
+            return undefined;
+        }
+        // Update cart with new identifiers
+        const updatedCart = yield updateShopifyCartAttributes(attributesToAdd, baseUrl, localePath);
+        return updatedCart;
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[Chord Analytics]: Error syncing identifiers to cart:', e);
+        return undefined;
+    }
+});