@chordcommerce/analytics 1.21.1 → 1.22.0-beta.1

package/README.md

@@ -168,15 +168,28 @@ This package uses [semantic-release](https://github.com/semantic-release/semanti
 
 ### How it works
 
+The repo has a single CI workflow (`.github/workflows/ci.yml`) with two jobs:
+
+1. **`test`** — Runs lint, prettier, build, and tests for all packages. Triggers on every push to `main`/`beta` and on every pull request.
+2. **`release`** — Runs only on `main` and `beta` branches, after `test` passes. Runs `semantic-release` to determine if a new version should be published.
+
+The release flow:
+
 1. Merge a PR into `main` (stable) or `beta` (pre-release).
-2. The **Test** GitHub Actions workflow runs.
-3. On success, the **Semantic Release** workflow runs automatically.
-4. `semantic-release` analyzes commit messages since the last release and determines the version bump.
-5. The package is published to npm and GitHub Packages, CHANGELOG.md is updated, and a Git tag is created.
+2. The `test` job runs. If it passes, the `release` job starts.
+3. `semantic-release` analyzes commit messages since the last release tag.
+4. If releasable commits exist, the package is published to npm and GitHub Packages, CHANGELOG.md is updated, and a Git tag is created.
+5. If no releasable commits exist, `semantic-release` exits cleanly and nothing is published.
 
-### Commit message conventions
+### When a release happens (and when it doesn't)
 
-This repo enforces [Conventional Commits](https://www.conventionalcommits.org/) via commitlint. The commit message prefix determines the version bump:
+A release is published **only** when all three conditions are met:
+
+1. A push lands on `main` or `beta` (via merged PR or direct push)
+2. Tests pass
+3. There are new commits since the last release tag with a releasable prefix
+
+**Releasable commit prefixes** (these trigger a version bump):
 
 | Prefix                     | Version Bump          | Example                                                   |
 | -------------------------- | --------------------- | --------------------------------------------------------- |
@@ -184,19 +197,35 @@ This repo enforces [Conventional Commits](https://www.conventionalcommits.org/)
 | `feat:`                    | Minor (1.0.0 → 1.1.0) | `feat: add trackOrderCompleted method`                    |
 | `BREAKING CHANGE:` in body | Major (1.0.0 → 2.0.0) | Commit body contains `BREAKING CHANGE: remove legacy API` |
 
-Other prefixes (`chore:`, `ci:`, `docs:`, `refactor:`, `test:`, etc.) do **not** trigger a release.
+**Non-releasable prefixes** (these do NOT trigger a release):
+
+`chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `style:`, `build:`, `perf:`
+
+If a merge to `main` or `beta` contains only non-releasable commits, the release job runs but `semantic-release` determines no release is needed and exits without publishing.
 
 ### Monorepo scoping
 
-This repo uses [semantic-release-monorepo](https://github.com/pmowrer/semantic-release-monorepo) to scope releases to individual packages. Only commits that touch files within a package's directory (e.g., `packages/core/`) are considered when determining the next version. Commits that only modify root-level files like `.github/workflows/`, `.nvmrc`, or other packages will not trigger a release for this package.
+This repo uses [semantic-release-monorepo](https://github.com/pmowrer/semantic-release-monorepo) to scope releases to individual packages. Only commits that touch files within a package's directory (e.g., `packages/core/`) are considered when determining the next version. A `feat:` commit that only modifies `.github/workflows/` or another package's directory will **not** trigger a release for `@chordcommerce/analytics`.
 
 ### Pre-releases
 
-Merging to `beta` creates pre-release versions (e.g., `1.21.0-beta.1`). Use this for testing before promoting to `main`.
+Merging to `beta` creates pre-release versions (e.g., `1.22.0-beta.1`). Use this for testing before promoting to `main`. Only `main` and `beta` are currently configured for automatic releases in the CI workflow. Additional prerelease branches (e.g., `alpha`) can be enabled by adding them to both the workflow's branch filter in `ci.yml` and the semantic-release branch config.
+
+### Beta release workflow
+
+1. Create a feature branch off `beta` and do your work.
+2. Create a PR targeting the `beta` branch and merge it.
+3. The CI workflow runs tests, then `semantic-release` publishes a beta version (e.g., `1.22.0-beta.1`).
+4. Install with: `npm install @chordcommerce/analytics@beta`
+
+### Promoting beta to production
+
+1. Create a PR from `beta` → `main` and merge it.
+2. The CI workflow runs tests, then `semantic-release` publishes a stable version on `main`.
 
 ### Dry run
 
-You can preview what a release would do without publishing by manually triggering the Semantic Release workflow in GitHub Actions with `dryRun` set to `true`.
+You can preview what a release would do without publishing by manually triggering the CI workflow in GitHub Actions with `dryRun` set to `true`.
 
 ## Support
 

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

@@ -0,0 +1,51 @@
+/**
+ * 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 identifiers to Shopify cart attributes.
+ *
+ * This function:
+ * 1. Gets the current cart
+ * 2. Checks if identifiers already exist
+ * 3. If not, updates the cart with the identifiers
+ *
+ * @returns The updated cart, or undefined if no update was needed
+ */
+export declare const syncIdentifiersToCart: (options?: IdentifierSyncOptions) => Promise<ShopifyCart | undefined>;

package/dist/cjs/client/identifiers.js

@@ -0,0 +1,193 @@
+"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 identifiers to Shopify cart attributes.
+ *
+ * This function:
+ * 1. Gets the current cart
+ * 2. Checks if identifiers already exist
+ * 3. If not, updates the cart with the identifiers
+ *
+ * @returns The updated cart, or undefined if no update was needed
+ */
+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 lightweight web pixel (running in Shopify's sandboxed iframe)
+     * to forward analytics events to this ChordAnalytics instance on the storefront.
+     *
+     * The lightweight 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;
         /**
          * 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 lightweight web pixel (running in Shopify's sandboxed iframe)
+         * to forward analytics events to this ChordAnalytics instance on the storefront.
+         *
+         * The lightweight 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,14 @@ var ChordAnalytics = /** @class */ (function () {
             window[this.options.namespace] = (window === null || window === void 0 ? void 0 : window[this.options.namespace]) || this;
             this.initializeCdp();
         }
+        // Automatically set up web pixel listener if enabled
+        if ((_d = this.options) === null || _d === void 0 ? void 0 : _d.enableWebPixelListener) {
+            this.setupWebPixelListener();
+        }
+        // Automatically sync identifiers to cart if enabled
+        if ((_e = this.options) === null || _e === void 0 ? void 0 : _e.enableIdentifierSync) {
+            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,18 @@ export interface ChordAnalyticsOptions<T extends ObjectTypes = ObjectTypes> {
     awaitConsent?: boolean;
     debug?: boolean;
     enableLogging?: boolean;
+    /**
+     * When true, automatically sets up a postMessage listener for events from
+     * the Shopify Custom Web Pixel sandbox. This enables the lightweight web pixel
+     * to forward analytics events to this ChordAnalytics instance.
+     */
+    enableWebPixelListener?: boolean;
+    /**
+     * When true, automatically syncs CDP anonymous ID and Google Client ID
+     * to Shopify cart attributes. This enables server-side events (webhooks)
+     * to correlate with client-side tracking.
+     */
+    enableIdentifierSync?: boolean;
     formatters: ChordAnalyticsFormatters<T>;
     namespace?: string;
     stripNull?: boolean;

package/dist/client/identifiers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 identifiers to Shopify cart attributes.
+ *
+ * This function:
+ * 1. Gets the current cart
+ * 2. Checks if identifiers already exist
+ * 3. If not, updates the cart with the identifiers
+ *
+ * @returns The updated cart, or undefined if no update was needed
+ */
+export declare const syncIdentifiersToCart: (options?: IdentifierSyncOptions) => Promise<ShopifyCart | undefined>;