@chordcommerce/analytics 1.23.0 → 1.24.1

package/README.md

@@ -121,8 +121,16 @@ export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
 addSourceMiddleware(func: AnalyticsMiddleware)
 
 Registers a middleware function to modify event properties before they are
-sent to analytics providers. Middleware functions are executed
-synchronously in the order they were added during event tracking.
+sent to analytics providers. Middleware functions are invoked in the order they
+were added during event tracking, and each one's properties are merged into the
+event in that order.
+
+A middleware may be synchronous or asynchronous. Synchronous middleware is never
+awaited, so it adds no delay to event delivery. Asynchronous middleware is
+awaited before the event is sent, capped at one second — a middleware that has
+not resolved by then is abandoned, a warning is logged, and the event is sent
+without its properties. A middleware that throws or rejects is logged and
+skipped. A middleware never prevents an event from being sent.
 
 Parameters
 
@@ -135,6 +143,15 @@ The middleware function can return:
 
 - Partial<EventProperties> - Properties to merge into the event payload
 - void - No additional properties to add
+- A Promise of either of the above - Awaited before the event is sent
+
+The `payload` argument carries `payload.obj` (the event's properties, name and
+page context) plus `payload.userId` and `payload.anonymousId` as the CDP
+currently knows them — either may be undefined.
+
+Note that middleware contributes properties by **returning** them. Mutating the
+`payload` argument has no effect; `next` is accepted for signature
+compatibility and does nothing.
 
 Useage Example
 
@@ -156,6 +173,15 @@ Useage Example
       timestamp: Date.now()
     };
   });
+
+  // Asynchronous middleware: the event waits for the lookup, up to one second.
+  analytics.addSourceMiddleware(async ({ payload }) => {
+    if (payload.obj.event !== 'Order Completed') return;
+
+    const isNewCustomer = await fetchIsNewCustomer();
+
+    return { is_new_customer: isNewCustomer ? 1 : 0 };
+  });
 ```
 
 ## API Reference

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.d.ts

@@ -71,6 +71,7 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
     setDebugMode: (enabled: boolean) => void;
     cdp: () => AnyAnalytics;
     ccdp: () => AnyAnalytics;
+    private currentUser;
     logger: (message?: any, ...optionalParams: any[]) => void;
     isResetting: () => boolean;
     private waitForReadyState;

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';
@@ -248,6 +249,32 @@ var ChordAnalytics = /** @class */ (function () {
                 return null;
             return (window === null || window === void 0 ? void 0 : window["_".concat(namespace)]) || (0, cdp_js_1.cdpQueue)(namespace);
         };
+        /*
+         * The current user and anonymous ids as the CDP knows them.
+         *
+         * Exposed to source middleware, which on Segment could read these from the
+         * event facade. Either CDP may be absent or may not implement `user()`, so
+         * every step is guarded and an unknown id is simply undefined.
+         */
+        this.currentUser = function () {
+            var read = function (analytics) {
+                var _a, _b, _c;
+                try {
+                    var user = (_a = analytics === null || analytics === void 0 ? void 0 : analytics.user) === null || _a === void 0 ? void 0 : _a.call(analytics);
+                    if (!user)
+                        return undefined;
+                    var userId = (_b = user.userId) !== null && _b !== void 0 ? _b : undefined;
+                    var anonymousId = (_c = user.anonymousId) !== null && _c !== void 0 ? _c : undefined;
+                    if (userId === undefined && anonymousId === undefined)
+                        return undefined;
+                    return { userId: userId, anonymousId: anonymousId };
+                }
+                catch (_d) {
+                    return undefined;
+                }
+            };
+            return read(_this.ccdp()) || read(_this.cdp()) || {};
+        };
         /*
          * Log a message to the console if `options.enableLogging` is true.
          */
@@ -509,44 +536,77 @@ var ChordAnalytics = /** @class */ (function () {
          * Internal method to actually send a track event to CDP.
          */
         this.sendTrackEvent = function (event, props, options) { return __awaiter(_this, void 0, void 0, function () {
-            var formattedProps, middlewareProps, searchParams_1, urlSearchParams, searchData_1, finalEventProps;
+            var formattedProps, middlewareProps, searchParams_1, urlSearchParams, searchData_1, _a, userId_1, anonymousId_1, invoke, settle, returned, results, _b, finalEventProps;
             var _this = this;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         formattedProps = this.options.stripNull && props ? (0, utils_js_1.pruneNullValues)(props) : props;
                         middlewareProps = {};
-                        if (this.middleware.length > 0) {
-                            searchParams_1 = typeof window !== 'undefined' ? window.location.search : '';
-                            urlSearchParams = new URLSearchParams(searchParams_1);
-                            searchData_1 = Object.fromEntries(urlSearchParams.entries());
-                            // process middleware synchronously
-                            this.middleware.forEach(function (func) {
-                                try {
-                                    var result = func({
-                                        payload: {
-                                            obj: {
-                                                properties: props,
-                                                event: event,
-                                                context: {
-                                                    page: {
-                                                        search: searchParams_1,
-                                                        searchParams: searchData_1,
-                                                    },
+                        if (!(this.middleware.length > 0)) return [3 /*break*/, 4];
+                        searchParams_1 = typeof window !== 'undefined' ? window.location.search : '';
+                        urlSearchParams = new URLSearchParams(searchParams_1);
+                        searchData_1 = Object.fromEntries(urlSearchParams.entries());
+                        _a = this.currentUser(), userId_1 = _a.userId, anonymousId_1 = _a.anonymousId;
+                        invoke = function (func) {
+                            try {
+                                return func({
+                                    payload: {
+                                        userId: userId_1,
+                                        anonymousId: anonymousId_1,
+                                        obj: {
+                                            properties: props,
+                                            event: event,
+                                            context: {
+                                                page: {
+                                                    search: searchParams_1,
+                                                    searchParams: searchData_1,
                                                 },
                                             },
                                         },
-                                        next: function (_) { return _; },
-                                    });
-                                    if (result && typeof result === 'object') {
-                                        middlewareProps = __assign(__assign({}, middlewareProps), result);
-                                    }
-                                }
-                                catch (error) {
-                                    console.warn('Middleware error:', error);
+                                    },
+                                    next: function (_) { return _; },
+                                });
+                            }
+                            catch (error) {
+                                console.warn('Middleware error:', error);
+                                return undefined;
+                            }
+                        };
+                        settle = function (returned) {
+                            if (!(0, utils_js_1.isPromise)(returned))
+                                return returned;
+                            return (0, utils_js_1.withTimeout)(returned, utils_js_1.MIDDLEWARE_TIMEOUT_MS)
+                                .then(function (settled) {
+                                if (settled === utils_js_1.TIMED_OUT) {
+                                    console.warn("Middleware timed out after ".concat(utils_js_1.MIDDLEWARE_TIMEOUT_MS, "ms; its properties were dropped"));
+                                    return undefined;
                                 }
+                                return settled;
+                            })
+                                .catch(function (error) {
+                                console.warn('Middleware error:', error);
+                                return undefined;
                             });
-                        }
+                        };
+                        returned = this.middleware.map(invoke);
+                        if (!returned.some(utils_js_1.isPromise)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, Promise.all(returned.map(settle))];
+                    case 1:
+                        _b = _c.sent();
+                        return [3 /*break*/, 3];
+                    case 2:
+                        _b = returned;
+                        _c.label = 3;
+                    case 3:
+                        results = _b;
+                        results.forEach(function (result) {
+                            if (result && typeof result === 'object') {
+                                middlewareProps = __assign(__assign({}, middlewareProps), result);
+                            }
+                        });
+                        _c.label = 4;
+                    case 4:
                         finalEventProps = __assign(__assign(__assign({}, formattedProps), middlewareProps), { meta: this.meta() });
                         if (this.options.debug) {
                             this.validate(event, finalEventProps).forEach(function (valid) {
@@ -584,8 +644,8 @@ var ChordAnalytics = /** @class */ (function () {
                                     resolve();
                                 }
                             })];
-                    case 1:
-                        _a.sent();
+                    case 5:
+                        _c.sent();
                         return [2 /*return*/];
                 }
             });
@@ -777,6 +837,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 +1544,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 +1554,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 +1568,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*/];
                 }
             });
         });