@chordcommerce/analytics 1.23.0 → 1.23.1

package/dist/cjs/client/consent/index.js

@@ -42,9 +42,12 @@ var ketch_js_1 = require("./ketch.js");
 var onetrust_js_1 = require("./onetrust.js");
 var shopify_js_1 = require("./shopify.js");
 var segment_js_1 = require("./segment.js");
+var persistence_js_1 = require("./persistence.js");
 var addCdpConsent = function (options) {
-    var lastProcessedConsent = null;
     var POLLING_INTERVAL_MS = 50;
+    // Always populated: ChordAnalytics applies a `namespace` default before
+    // constructing the consent manager.
+    var namespace = options.namespace;
     var TIMEOUT_MS = options.awaitConsentTimeout
         ? options.awaitConsentTimeout
         : 60000;
@@ -96,31 +99,49 @@ var addCdpConsent = function (options) {
         });
     }); };
     /**
-     * Tracks consent preference changes.
-     * Note: Per-event consent stamping is handled in ChordAnalytics via stampConsent().
+     * Tracks consent preference *transitions* only, deduped against the last
+     * state we emitted (persisted, so the guard survives navigation).
+     * Per-event consent stamping is handled by configureConsentOnCdp().
      */
     var trackConsentUpdate = function (updatedConsent) { return __awaiter(void 0, void 0, void 0, function () {
-        var chordAnalytics;
+        var chordAnalytics, error_1;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
-                    if (lastProcessedConsent &&
-                        JSON.stringify(lastProcessedConsent) === JSON.stringify(updatedConsent)) {
+                    chordAnalytics = window[namespace];
+                    if (!chordAnalytics ||
+                        typeof chordAnalytics.track !== 'function' ||
+                        updatedConsent.consentCategories === undefined) {
                         return [2 /*return*/];
                     }
-                    lastProcessedConsent = updatedConsent;
-                    chordAnalytics = window[options.namespace];
-                    if (!(chordAnalytics &&
-                        typeof chordAnalytics.track === 'function' &&
-                        updatedConsent.consentCategories !== undefined)) return [3 /*break*/, 2];
-                    return [4 /*yield*/, chordAnalytics.track('Consent Preferences Updated', updatedConsent)];
+                    if (!(0, persistence_js_1.claimConsentEmit)(namespace, updatedConsent)) {
+                        if (options.enableLogging && options.debug) {
+                            console.log('[Chord Analytics DEBUG]: Consent unchanged or emit already in flight, skipping');
+                        }
+                        return [2 /*return*/];
+                    }
+                    _a.label = 1;
                 case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, chordAnalytics.track('Consent Preferences Updated', updatedConsent)
+                        // Only recorded once delivery resolves. Committing before this would
+                        // suppress the event permanently if it were queued and never flushed.
+                    ];
+                case 2:
                     _a.sent();
+                    // Only recorded once delivery resolves. Committing before this would
+                    // suppress the event permanently if it were queued and never flushed.
+                    (0, persistence_js_1.commitConsentEmit)(namespace, updatedConsent);
                     if (options.enableLogging && options.debug) {
                         console.log('[Chord Analytics DEBUG]: Consent preferences updated, sent tracking event');
                     }
-                    _a.label = 2;
-                case 2: return [2 /*return*/];
+                    return [3 /*break*/, 4];
+                case 3:
+                    error_1 = _a.sent();
+                    (0, persistence_js_1.releaseConsentEmit)(namespace, updatedConsent);
+                    console.error('Error tracking consent preferences update:', error_1);
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
             }
         });
     }); };
@@ -129,24 +150,19 @@ var addCdpConsent = function (options) {
      * Returns the initial consent so it can be tracked after CDP is fully ready (avoiding circular await).
      */
     var setupConsentManagement = function () { return __awaiter(void 0, void 0, void 0, function () {
-        var initialConsent;
         return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0:
-                    if (!adapter)
-                        return [2 /*return*/, null
-                            // Set up the consent update handler first to catch any immediate updates
-                        ];
+            if (!adapter)
+                return [2 /*return*/, null
                     // Set up the consent update handler first to catch any immediate updates
-                    adapter.handleConsentUpdates(function (updatedConsent) {
-                        trackConsentUpdate(updatedConsent);
-                    });
-                    return [4 /*yield*/, adapter.getCurrentConsent()];
-                case 1:
-                    initialConsent = _a.sent();
-                    lastProcessedConsent = initialConsent;
-                    return [2 /*return*/, initialConsent];
-            }
+                ];
+            // Set up the consent update handler first to catch any immediate updates
+            adapter.handleConsentUpdates(function (updatedConsent) {
+                trackConsentUpdate(updatedConsent);
+            });
+            // Return initial consent to be tracked after CDP is fully initialized.
+            // Not marked as processed here: whichever path emits first records the
+            // signature, and the other is then deduped against it.
+            return [2 /*return*/, adapter.getCurrentConsent()];
         });
     }); };
     /**
@@ -155,7 +171,7 @@ var addCdpConsent = function (options) {
      * or null if consent setup failed or was blocked.
      */
     var init = function () { return __awaiter(void 0, void 0, void 0, function () {
-        var canBeTracked, error_1;
+        var canBeTracked, error_2;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -185,8 +201,8 @@ var addCdpConsent = function (options) {
                     return [4 /*yield*/, setupConsentManagement()];
                 case 3: return [2 /*return*/, _a.sent()];
                 case 4:
-                    error_1 = _a.sent();
-                    console.error('Error setting up consent management:', error_1);
+                    error_2 = _a.sent();
+                    console.error('Error setting up consent management:', error_2);
                     return [2 /*return*/, null];
                 case 5: return [2 /*return*/];
             }

package/dist/cjs/client/consent/persistence.d.ts

@@ -0,0 +1,49 @@
+import type { ConsentConfiguration } from '../../types/index.js';
+/**
+ * Build a stable, order-independent signature for a consent configuration.
+ *
+ * Category keys are sorted so a change in the order the consent manager
+ * reports its groups does not read as a change in consent.
+ */
+export declare const consentSignature: (consent: ConsentConfiguration) => string;
+/**
+ * Whether this consent configuration differs from the last one we tracked.
+ *
+ * Returns true when nothing has been stored yet, so every visitor still gets
+ * one baseline `Consent Preferences Updated` event recording their starting
+ * state. Subsequent page loads with unchanged consent return false.
+ */
+export declare const hasConsentChanged: (namespace: string | undefined, consent: ConsentConfiguration) => boolean;
+/**
+ * Claim the right to emit a consent event, atomically.
+ *
+ * Returns false when this state was already tracked, or when an emit for the
+ * same state is already in flight. Callers that get true MUST follow with
+ * `commitConsentEmit` on success or `releaseConsentEmit` on failure.
+ *
+ * The claim is deliberately not persisted: it exists only to dedupe within a
+ * page load. If delivery never completes, the next page load starts clean and
+ * retries rather than suppressing the event forever.
+ */
+export declare const claimConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => boolean;
+/**
+ * Record a consent configuration as tracked, once delivery has actually
+ * completed. Later page loads dedupe against it.
+ */
+export declare const commitConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => void;
+/**
+ * Give up a claim without recording it, so a later attempt can retry. Takes
+ * the consent it claimed so a failing emit cannot clear another state's claim.
+ */
+export declare const releaseConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => void;
+/**
+ * Clear the stored consent signature so the next init emits a fresh baseline.
+ * Called on reset(), where a new anonymous ID would otherwise never get a
+ * consent record of its own.
+ */
+export declare const forgetConsent: (namespace: string | undefined) => void;
+/**
+ * Drop all module-level state. Test-only: `localStorage` is cleared between
+ * tests, but these would otherwise persist and suppress expected events.
+ */
+export declare const clearConsentMemory: () => void;

package/dist/cjs/client/consent/persistence.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearConsentMemory = exports.forgetConsent = exports.releaseConsentEmit = exports.commitConsentEmit = exports.claimConsentEmit = exports.hasConsentChanged = exports.consentSignature = void 0;
+var LAST_CONSENT_STORAGE_KEY = 'chordcommerce/analytics/last-consent';
+/**
+ * In-memory fallback for environments where localStorage is unavailable
+ * (SSR, private browsing, storage disabled). Keyed by namespace so multiple
+ * ChordAnalytics instances on one page don't clobber each other.
+ */
+var memoryStore = {};
+var storageKey = function (namespace) {
+    return "".concat(LAST_CONSENT_STORAGE_KEY, "/").concat(namespace !== null && namespace !== void 0 ? namespace : 'default');
+};
+/**
+ * Build a stable, order-independent signature for a consent configuration.
+ *
+ * Category keys are sorted so a change in the order the consent manager
+ * reports its groups does not read as a change in consent.
+ */
+var consentSignature = function (consent) {
+    var _a;
+    var categories = (_a = consent.consentCategories) !== null && _a !== void 0 ? _a : {};
+    var sorted = Object.keys(categories)
+        .sort()
+        .reduce(function (acc, key) {
+        acc[key] = categories[key];
+        return acc;
+    }, {});
+    return JSON.stringify(sorted);
+};
+exports.consentSignature = consentSignature;
+var readSignature = function (namespace) {
+    var _a;
+    var key = storageKey(namespace);
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return window.localStorage.getItem(key);
+        }
+    }
+    catch (_b) {
+        // localStorage can throw in private browsing; fall through to memory
+    }
+    return (_a = memoryStore[key]) !== null && _a !== void 0 ? _a : null;
+};
+var writeSignature = function (namespace, signature) {
+    var key = storageKey(namespace);
+    memoryStore[key] = signature;
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.setItem(key, signature);
+        }
+    }
+    catch (_a) {
+        // Quota or private browsing; the in-memory copy still dedupes within
+        // this page load.
+    }
+};
+/**
+ * Claims for emits currently mid-delivery, as `<storage key>::<signature>`.
+ * Delivery is awaited and a queued event can stay unresolved for a long time,
+ * so without this two callers in the same tick would both pass the guard and
+ * emit duplicates.
+ *
+ * Keyed by signature, not just namespace, so two different consent states can
+ * be in flight at once without clearing each other's claim.
+ */
+var inFlight = new Set();
+var inFlightKey = function (namespace, signature) {
+    return "".concat(storageKey(namespace), "::").concat(signature);
+};
+/**
+ * Whether this consent configuration differs from the last one we tracked.
+ *
+ * Returns true when nothing has been stored yet, so every visitor still gets
+ * one baseline `Consent Preferences Updated` event recording their starting
+ * state. Subsequent page loads with unchanged consent return false.
+ */
+var hasConsentChanged = function (namespace, consent) { return readSignature(namespace) !== (0, exports.consentSignature)(consent); };
+exports.hasConsentChanged = hasConsentChanged;
+/**
+ * Claim the right to emit a consent event, atomically.
+ *
+ * Returns false when this state was already tracked, or when an emit for the
+ * same state is already in flight. Callers that get true MUST follow with
+ * `commitConsentEmit` on success or `releaseConsentEmit` on failure.
+ *
+ * The claim is deliberately not persisted: it exists only to dedupe within a
+ * page load. If delivery never completes, the next page load starts clean and
+ * retries rather than suppressing the event forever.
+ */
+var claimConsentEmit = function (namespace, consent) {
+    var signature = (0, exports.consentSignature)(consent);
+    if (readSignature(namespace) === signature)
+        return false;
+    if (inFlight.has(inFlightKey(namespace, signature)))
+        return false;
+    inFlight.add(inFlightKey(namespace, signature));
+    return true;
+};
+exports.claimConsentEmit = claimConsentEmit;
+/**
+ * Record a consent configuration as tracked, once delivery has actually
+ * completed. Later page loads dedupe against it.
+ */
+var commitConsentEmit = function (namespace, consent) {
+    var signature = (0, exports.consentSignature)(consent);
+    inFlight.delete(inFlightKey(namespace, signature));
+    writeSignature(namespace, signature);
+};
+exports.commitConsentEmit = commitConsentEmit;
+/**
+ * Give up a claim without recording it, so a later attempt can retry. Takes
+ * the consent it claimed so a failing emit cannot clear another state's claim.
+ */
+var releaseConsentEmit = function (namespace, consent) {
+    inFlight.delete(inFlightKey(namespace, (0, exports.consentSignature)(consent)));
+};
+exports.releaseConsentEmit = releaseConsentEmit;
+/**
+ * Clear the stored consent signature so the next init emits a fresh baseline.
+ * Called on reset(), where a new anonymous ID would otherwise never get a
+ * consent record of its own.
+ */
+var forgetConsent = function (namespace) {
+    var key = storageKey(namespace);
+    delete memoryStore[key];
+    inFlight.forEach(function (claim) {
+        if (claim.startsWith("".concat(key, "::")))
+            inFlight.delete(claim);
+    });
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.removeItem(key);
+        }
+    }
+    catch (_a) {
+        // Nothing to do; the in-memory copy is already gone.
+    }
+};
+exports.forgetConsent = forgetConsent;
+/**
+ * Drop all module-level state. Test-only: `localStorage` is cleared between
+ * tests, but these would otherwise persist and suppress expected events.
+ */
+var clearConsentMemory = function () {
+    Object.keys(memoryStore).forEach(function (key) { return delete memoryStore[key]; });
+    inFlight.clear();
+};
+exports.clearConsentMemory = clearConsentMemory;

package/dist/cjs/client/index.js

@@ -59,6 +59,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChordAnalytics = void 0;
 var cdp_js_1 = require("./cdp.js");
 var index_js_1 = require("./consent/index.js");
+var persistence_js_1 = require("./consent/persistence.js");
 var index_js_2 = require("../validators/index.js");
 var utils_js_1 = require("../utils.js");
 var DEBUG_MODE_STORAGE_KEY = 'chordcommerce/analytics/debug';
@@ -777,6 +778,9 @@ var ChordAnalytics = /** @class */ (function () {
                 switch (_b.label) {
                     case 0:
                         _b.trys.push([0, 4, 5, 6]);
+                        // The new identity has no consent event of its own yet, so drop the
+                        // stored signature and let the next init emit a fresh baseline.
+                        (0, persistence_js_1.forgetConsent)(this.options.namespace);
                         a = this.ccdp();
                         if (a && typeof a.reset === 'function') {
                             a.reset();
@@ -1481,7 +1485,7 @@ var ChordAnalytics = /** @class */ (function () {
      */
     ChordAnalytics.prototype.initializeCdp = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var snippetPromise, initialConsent, error_4;
+            var snippetPromise, initialConsent, namespace, error_4, error_5;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -1491,7 +1495,7 @@ var ChordAnalytics = /** @class */ (function () {
                         }
                         _a.label = 1;
                     case 1:
-                        _a.trys.push([1, 6, , 7]);
+                        _a.trys.push([1, 9, , 10]);
                         snippetPromise = (0, cdp_js_1.addCdpSnippet)(this.options);
                         // Create a void promise for cdpReadyPromise that resolves when snippet is done
                         // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -1505,32 +1509,57 @@ var ChordAnalytics = /** @class */ (function () {
                             // eslint-disable-next-line no-console
                             console.log('[Chord Analytics DEBUG]: consentCategories defined?', (initialConsent === null || initialConsent === void 0 ? void 0 : initialConsent.consentCategories) !== undefined);
                         }
-                        if (!(initialConsent && initialConsent.consentCategories !== undefined)) return [3 /*break*/, 4];
+                        namespace = this.options.namespace;
+                        if (!(initialConsent && initialConsent.consentCategories !== undefined)) return [3 /*break*/, 7];
+                        if (!(0, persistence_js_1.claimConsentEmit)(namespace, initialConsent)) {
+                            if (this.options.enableLogging && this.options.debug) {
+                                // eslint-disable-next-line no-console
+                                console.log('[Chord Analytics DEBUG]: Initial consent unchanged or emit already in flight, skipping track');
+                            }
+                            return [2 /*return*/];
+                        }
                         if (this.options.enableLogging && this.options.debug) {
                             // eslint-disable-next-line no-console
                             console.log('[Chord Analytics DEBUG]: About to call this.track() for Consent Preferences Updated');
                         }
-                        return [4 /*yield*/, this.track('Consent Preferences Updated', initialConsent)];
+                        _a.label = 3;
                     case 3:
+                        _a.trys.push([3, 5, , 6]);
+                        return [4 /*yield*/, this.track('Consent Preferences Updated', initialConsent)
+                            // Only recorded once delivery resolves. Committing before this would
+                            // suppress the event permanently if it were queued and never
+                            // flushed — the next page load must be free to retry.
+                        ];
+                    case 4:
                         _a.sent();
+                        // Only recorded once delivery resolves. Committing before this would
+                        // suppress the event permanently if it were queued and never
+                        // flushed — the next page load must be free to retry.
+                        (0, persistence_js_1.commitConsentEmit)(namespace, initialConsent);
+                        return [3 /*break*/, 6];
+                    case 5:
+                        error_4 = _a.sent();
+                        (0, persistence_js_1.releaseConsentEmit)(namespace, initialConsent);
+                        throw error_4;
+                    case 6:
                         if (this.options.enableLogging && this.options.debug) {
                             // eslint-disable-next-line no-console
                             console.log('[Chord Analytics DEBUG]: Initial consent preferences tracked');
                         }
-                        return [3 /*break*/, 5];
-                    case 4:
+                        return [3 /*break*/, 8];
+                    case 7:
                         if (this.options.enableLogging && this.options.debug) {
                             // eslint-disable-next-line no-console
                             console.log('[Chord Analytics DEBUG]: Skipping initial consent track - no consent or no consentCategories');
                         }
-                        _a.label = 5;
-                    case 5: return [3 /*break*/, 7];
-                    case 6:
-                        error_4 = _a.sent();
+                        _a.label = 8;
+                    case 8: return [3 /*break*/, 10];
+                    case 9:
+                        error_5 = _a.sent();
                         // eslint-disable-next-line no-console
-                        console.error('CDP initialization failed:', error_4);
-                        return [3 /*break*/, 7];
-                    case 7: return [2 /*return*/];
+                        console.error('CDP initialization failed:', error_5);
+                        return [3 /*break*/, 10];
+                    case 10: return [2 /*return*/];
                 }
             });
         });

package/dist/cjs/setupTests.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 // eslint-disable-next-line import/no-extraneous-dependencies
 var globals_1 = require("@jest/globals");
+var persistence_js_1 = require("./client/consent/persistence.js");
 // Make jest available globally
 globalThis.jest = globals_1.jest;
-// Mock sessionStorage for tests
-var sessionStorageMock = (function () {
+var createStorageMock = function () {
     var store = {};
     return {
         getItem: function (key) { return store[key] || null; },
@@ -19,11 +19,21 @@ var sessionStorageMock = (function () {
             store = {};
         },
     };
-})();
+};
+var sessionStorageMock = createStorageMock();
+var localStorageMock = createStorageMock();
 Object.defineProperty(window, 'sessionStorage', {
     value: sessionStorageMock,
 });
-// Clear sessionStorage before each test to ensure test isolation
+Object.defineProperty(window, 'localStorage', {
+    value: localStorageMock,
+});
+// Clear storage before each test to ensure test isolation. localStorage now
+// holds the last-tracked consent signature, which would otherwise leak between
+// tests and suppress expected consent events. clearConsentMemory() covers the
+// module-level fallback stores, which localStorage.clear() does not reach.
 beforeEach(function () {
     sessionStorageMock.clear();
+    localStorageMock.clear();
+    (0, persistence_js_1.clearConsentMemory)();
 });

package/dist/client/consent/index.js

@@ -12,9 +12,12 @@ import { ketchConsentAdapter } from './ketch.js';
 import { onetrustConsentAdapter } from './onetrust.js';
 import { shopifyConsentAdapter } from './shopify.js';
 import { segmentConsentAdapter } from './segment.js';
+import { claimConsentEmit, commitConsentEmit, releaseConsentEmit, } from './persistence.js';
 export const addCdpConsent = (options) => {
-    let lastProcessedConsent = null;
     const POLLING_INTERVAL_MS = 50;
+    // Always populated: ChordAnalytics applies a `namespace` default before
+    // constructing the consent manager.
+    const namespace = options.namespace;
     const TIMEOUT_MS = options.awaitConsentTimeout
         ? options.awaitConsentTimeout
         : 60000;
@@ -64,24 +67,36 @@ export const addCdpConsent = (options) => {
         });
     });
     /**
-     * Tracks consent preference changes.
-     * Note: Per-event consent stamping is handled in ChordAnalytics via stampConsent().
+     * Tracks consent preference *transitions* only, deduped against the last
+     * state we emitted (persisted, so the guard survives navigation).
+     * Per-event consent stamping is handled by configureConsentOnCdp().
      */
     const trackConsentUpdate = (updatedConsent) => __awaiter(void 0, void 0, void 0, function* () {
-        if (lastProcessedConsent &&
-            JSON.stringify(lastProcessedConsent) === JSON.stringify(updatedConsent)) {
+        const chordAnalytics = window[namespace];
+        if (!chordAnalytics ||
+            typeof chordAnalytics.track !== 'function' ||
+            updatedConsent.consentCategories === undefined) {
             return;
         }
-        lastProcessedConsent = updatedConsent;
-        const chordAnalytics = window[options.namespace];
-        if (chordAnalytics &&
-            typeof chordAnalytics.track === 'function' &&
-            updatedConsent.consentCategories !== undefined) {
+        if (!claimConsentEmit(namespace, updatedConsent)) {
+            if (options.enableLogging && options.debug) {
+                console.log('[Chord Analytics DEBUG]: Consent unchanged or emit already in flight, skipping');
+            }
+            return;
+        }
+        try {
             yield chordAnalytics.track('Consent Preferences Updated', updatedConsent);
+            // Only recorded once delivery resolves. Committing before this would
+            // suppress the event permanently if it were queued and never flushed.
+            commitConsentEmit(namespace, updatedConsent);
             if (options.enableLogging && options.debug) {
                 console.log('[Chord Analytics DEBUG]: Consent preferences updated, sent tracking event');
             }
         }
+        catch (error) {
+            releaseConsentEmit(namespace, updatedConsent);
+            console.error('Error tracking consent preferences update:', error);
+        }
     });
     /**
      * Sets up consent management by initializing the adapter and handling consent updates.
@@ -94,10 +109,10 @@ export const addCdpConsent = (options) => {
         adapter.handleConsentUpdates((updatedConsent) => {
             trackConsentUpdate(updatedConsent);
         });
-        // Return initial consent to be tracked after CDP is fully initialized
-        const initialConsent = yield adapter.getCurrentConsent();
-        lastProcessedConsent = initialConsent;
-        return initialConsent;
+        // Return initial consent to be tracked after CDP is fully initialized.
+        // Not marked as processed here: whichever path emits first records the
+        // signature, and the other is then deduped against it.
+        return adapter.getCurrentConsent();
     });
     /**
      * Initializes consent management and sets up consent update handlers.

package/dist/client/consent/persistence.d.ts

@@ -0,0 +1,49 @@
+import type { ConsentConfiguration } from '../../types/index.js';
+/**
+ * Build a stable, order-independent signature for a consent configuration.
+ *
+ * Category keys are sorted so a change in the order the consent manager
+ * reports its groups does not read as a change in consent.
+ */
+export declare const consentSignature: (consent: ConsentConfiguration) => string;
+/**
+ * Whether this consent configuration differs from the last one we tracked.
+ *
+ * Returns true when nothing has been stored yet, so every visitor still gets
+ * one baseline `Consent Preferences Updated` event recording their starting
+ * state. Subsequent page loads with unchanged consent return false.
+ */
+export declare const hasConsentChanged: (namespace: string | undefined, consent: ConsentConfiguration) => boolean;
+/**
+ * Claim the right to emit a consent event, atomically.
+ *
+ * Returns false when this state was already tracked, or when an emit for the
+ * same state is already in flight. Callers that get true MUST follow with
+ * `commitConsentEmit` on success or `releaseConsentEmit` on failure.
+ *
+ * The claim is deliberately not persisted: it exists only to dedupe within a
+ * page load. If delivery never completes, the next page load starts clean and
+ * retries rather than suppressing the event forever.
+ */
+export declare const claimConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => boolean;
+/**
+ * Record a consent configuration as tracked, once delivery has actually
+ * completed. Later page loads dedupe against it.
+ */
+export declare const commitConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => void;
+/**
+ * Give up a claim without recording it, so a later attempt can retry. Takes
+ * the consent it claimed so a failing emit cannot clear another state's claim.
+ */
+export declare const releaseConsentEmit: (namespace: string | undefined, consent: ConsentConfiguration) => void;
+/**
+ * Clear the stored consent signature so the next init emits a fresh baseline.
+ * Called on reset(), where a new anonymous ID would otherwise never get a
+ * consent record of its own.
+ */
+export declare const forgetConsent: (namespace: string | undefined) => void;
+/**
+ * Drop all module-level state. Test-only: `localStorage` is cleared between
+ * tests, but these would otherwise persist and suppress expected events.
+ */
+export declare const clearConsentMemory: () => void;

package/dist/client/consent/persistence.js

@@ -0,0 +1,135 @@
+const LAST_CONSENT_STORAGE_KEY = 'chordcommerce/analytics/last-consent';
+/**
+ * In-memory fallback for environments where localStorage is unavailable
+ * (SSR, private browsing, storage disabled). Keyed by namespace so multiple
+ * ChordAnalytics instances on one page don't clobber each other.
+ */
+const memoryStore = {};
+const storageKey = (namespace) => `${LAST_CONSENT_STORAGE_KEY}/${namespace !== null && namespace !== void 0 ? namespace : 'default'}`;
+/**
+ * Build a stable, order-independent signature for a consent configuration.
+ *
+ * Category keys are sorted so a change in the order the consent manager
+ * reports its groups does not read as a change in consent.
+ */
+export const consentSignature = (consent) => {
+    var _a;
+    const categories = (_a = consent.consentCategories) !== null && _a !== void 0 ? _a : {};
+    const sorted = Object.keys(categories)
+        .sort()
+        .reduce((acc, key) => {
+        acc[key] = categories[key];
+        return acc;
+    }, {});
+    return JSON.stringify(sorted);
+};
+const readSignature = (namespace) => {
+    var _a;
+    const key = storageKey(namespace);
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return window.localStorage.getItem(key);
+        }
+    }
+    catch (_b) {
+        // localStorage can throw in private browsing; fall through to memory
+    }
+    return (_a = memoryStore[key]) !== null && _a !== void 0 ? _a : null;
+};
+const writeSignature = (namespace, signature) => {
+    const key = storageKey(namespace);
+    memoryStore[key] = signature;
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.setItem(key, signature);
+        }
+    }
+    catch (_a) {
+        // Quota or private browsing; the in-memory copy still dedupes within
+        // this page load.
+    }
+};
+/**
+ * Claims for emits currently mid-delivery, as `<storage key>::<signature>`.
+ * Delivery is awaited and a queued event can stay unresolved for a long time,
+ * so without this two callers in the same tick would both pass the guard and
+ * emit duplicates.
+ *
+ * Keyed by signature, not just namespace, so two different consent states can
+ * be in flight at once without clearing each other's claim.
+ */
+const inFlight = new Set();
+const inFlightKey = (namespace, signature) => `${storageKey(namespace)}::${signature}`;
+/**
+ * Whether this consent configuration differs from the last one we tracked.
+ *
+ * Returns true when nothing has been stored yet, so every visitor still gets
+ * one baseline `Consent Preferences Updated` event recording their starting
+ * state. Subsequent page loads with unchanged consent return false.
+ */
+export const hasConsentChanged = (namespace, consent) => readSignature(namespace) !== consentSignature(consent);
+/**
+ * Claim the right to emit a consent event, atomically.
+ *
+ * Returns false when this state was already tracked, or when an emit for the
+ * same state is already in flight. Callers that get true MUST follow with
+ * `commitConsentEmit` on success or `releaseConsentEmit` on failure.
+ *
+ * The claim is deliberately not persisted: it exists only to dedupe within a
+ * page load. If delivery never completes, the next page load starts clean and
+ * retries rather than suppressing the event forever.
+ */
+export const claimConsentEmit = (namespace, consent) => {
+    const signature = consentSignature(consent);
+    if (readSignature(namespace) === signature)
+        return false;
+    if (inFlight.has(inFlightKey(namespace, signature)))
+        return false;
+    inFlight.add(inFlightKey(namespace, signature));
+    return true;
+};
+/**
+ * Record a consent configuration as tracked, once delivery has actually
+ * completed. Later page loads dedupe against it.
+ */
+export const commitConsentEmit = (namespace, consent) => {
+    const signature = consentSignature(consent);
+    inFlight.delete(inFlightKey(namespace, signature));
+    writeSignature(namespace, signature);
+};
+/**
+ * Give up a claim without recording it, so a later attempt can retry. Takes
+ * the consent it claimed so a failing emit cannot clear another state's claim.
+ */
+export const releaseConsentEmit = (namespace, consent) => {
+    inFlight.delete(inFlightKey(namespace, consentSignature(consent)));
+};
+/**
+ * Clear the stored consent signature so the next init emits a fresh baseline.
+ * Called on reset(), where a new anonymous ID would otherwise never get a
+ * consent record of its own.
+ */
+export const forgetConsent = (namespace) => {
+    const key = storageKey(namespace);
+    delete memoryStore[key];
+    inFlight.forEach((claim) => {
+        if (claim.startsWith(`${key}::`))
+            inFlight.delete(claim);
+    });
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.removeItem(key);
+        }
+    }
+    catch (_a) {
+        // Nothing to do; the in-memory copy is already gone.
+    }
+};
+/**
+ * Drop all module-level state. Test-only: `localStorage` is cleared between
+ * tests, but these would otherwise persist and suppress expected events.
+ */
+export const clearConsentMemory = () => {
+    Object.keys(memoryStore).forEach((key) => delete memoryStore[key]);
+    inFlight.clear();
+};

package/dist/client/index.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { addCdpSnippet, cdpQueue } from './cdp.js';
 import { addCdpConsent } from './consent/index.js';
+import { claimConsentEmit, commitConsentEmit, forgetConsent, releaseConsentEmit, } from './consent/persistence.js';
 import { eventSchemas } from '../validators/index.js';
 import { pruneNullValues } from '../utils.js';
 const DEBUG_MODE_STORAGE_KEY = 'chordcommerce/analytics/debug';
@@ -600,6 +601,9 @@ export class ChordAnalytics {
         this.performReset = () => __awaiter(this, void 0, void 0, function* () {
             var _e;
             try {
+                // The new identity has no consent event of its own yet, so drop the
+                // stored signature and let the next init emit a fresh baseline.
+                forgetConsent(this.options.namespace);
                 const a = this.ccdp();
                 if (a && typeof a.reset === 'function') {
                     a.reset();
@@ -1235,13 +1239,33 @@ export class ChordAnalytics {
                     // eslint-disable-next-line no-console
                     console.log('[Chord Analytics DEBUG]: consentCategories defined?', (initialConsent === null || initialConsent === void 0 ? void 0 : initialConsent.consentCategories) !== undefined);
                 }
-                // Now that CDP is fully ready, fire the initial consent track event
+                // Now that CDP is fully ready, fire the initial consent track event.
+                // Skipped when consent is unchanged since the last event we emitted —
+                // otherwise this fires once per page load on multi-page storefronts.
+                const { namespace } = this.options;
                 if (initialConsent && initialConsent.consentCategories !== undefined) {
+                    if (!claimConsentEmit(namespace, initialConsent)) {
+                        if (this.options.enableLogging && this.options.debug) {
+                            // eslint-disable-next-line no-console
+                            console.log('[Chord Analytics DEBUG]: Initial consent unchanged or emit already in flight, skipping track');
+                        }
+                        return;
+                    }
                     if (this.options.enableLogging && this.options.debug) {
                         // eslint-disable-next-line no-console
                         console.log('[Chord Analytics DEBUG]: About to call this.track() for Consent Preferences Updated');
                     }
-                    yield this.track('Consent Preferences Updated', initialConsent);
+                    try {
+                        yield this.track('Consent Preferences Updated', initialConsent);
+                        // Only recorded once delivery resolves. Committing before this would
+                        // suppress the event permanently if it were queued and never
+                        // flushed — the next page load must be free to retry.
+                        commitConsentEmit(namespace, initialConsent);
+                    }
+                    catch (error) {
+                        releaseConsentEmit(namespace, initialConsent);
+                        throw error;
+                    }
                     if (this.options.enableLogging && this.options.debug) {
                         // eslint-disable-next-line no-console
                         console.log('[Chord Analytics DEBUG]: Initial consent preferences tracked');

package/dist/setupTests.js

@@ -1,9 +1,9 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { jest } from '@jest/globals';
+import { clearConsentMemory } from './client/consent/persistence.js';
 // Make jest available globally
 globalThis.jest = jest;
-// Mock sessionStorage for tests
-const sessionStorageMock = (() => {
+const createStorageMock = () => {
     let store = {};
     return {
         getItem: (key) => store[key] || null,
@@ -17,11 +17,21 @@ const sessionStorageMock = (() => {
             store = {};
         },
     };
-})();
+};
+const sessionStorageMock = createStorageMock();
+const localStorageMock = createStorageMock();
 Object.defineProperty(window, 'sessionStorage', {
     value: sessionStorageMock,
 });
-// Clear sessionStorage before each test to ensure test isolation
+Object.defineProperty(window, 'localStorage', {
+    value: localStorageMock,
+});
+// Clear storage before each test to ensure test isolation. localStorage now
+// holds the last-tracked consent signature, which would otherwise leak between
+// tests and suppress expected consent events. clearConsentMemory() covers the
+// module-level fallback stores, which localStorage.clear() does not reach.
 beforeEach(() => {
     sessionStorageMock.clear();
+    localStorageMock.clear();
+    clearConsentMemory();
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chordcommerce/analytics",
   "description": "Chord Commerce event tracking",
-  "version": "1.23.0",
+  "version": "1.23.1",
   "author": "Chord Commerce <help@chord.co> (https://www.chord.co)",
   "type": "module",
   "main": "dist/index.js",