@chordcommerce/analytics 1.23.0 → 1.24.1

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/cjs/types/client.d.ts

@@ -88,10 +88,23 @@ type MiddlewarePayload = {
             page: PageContext;
         };
     };
+    /**
+     * The current user and anonymous ids, read from the CDP at send time.
+     * Segment's middleware payload exposes these as `userId()`/`anonymousId()`
+     * methods on a facade; they are plain values here.
+     */
+    userId?: string;
+    anonymousId?: string;
 };
 type MiddlewareArgs = {
     payload: MiddlewarePayload;
     next: <T>(arg: T) => T;
 };
-export type AnalyticsMiddleware = (args: MiddlewareArgs) => Partial<EventProperties> | void;
+export type MiddlewareResult = Partial<EventProperties> | void;
+/**
+ * A source middleware may be synchronous or asynchronous. An asynchronous one
+ * is awaited before the event is dispatched, bounded by a timeout — see
+ * `addSourceMiddleware` in the README.
+ */
+export type AnalyticsMiddleware = (args: MiddlewareArgs) => MiddlewareResult | Promise<MiddlewareResult>;
 export {};

package/dist/cjs/utils.d.ts

@@ -1,2 +1,21 @@
 import type { EventProperties } from './types/index.js';
 export declare const pruneNullValues: (props: EventProperties) => EventProperties;
+/**
+ * How long a single asynchronous source middleware may take before its
+ * contribution is abandoned.
+ *
+ * Middleware runs on the path to the CDP, so an unbounded wait would let one
+ * slow lookup hold up delivery indefinitely. `Order Completed` in particular
+ * fires on a confirmation page shoppers close, so a late event is a lost one.
+ */
+export declare const MIDDLEWARE_TIMEOUT_MS = 1000;
+/** Returned by {@link withTimeout} when the promise did not settle in time. */
+export declare const TIMED_OUT: unique symbol;
+export declare const isPromise: (value: unknown) => value is Promise<unknown>;
+/**
+ * Resolve `promise`, or {@link TIMED_OUT} if it has not settled within `ms`.
+ *
+ * The timer is cleared either way, so a promise that settles quickly does not
+ * leave a pending timeout behind.
+ */
+export declare const withTimeout: <T>(promise: Promise<T>, ms: number) => Promise<typeof TIMED_OUT | T>;

package/dist/cjs/utils.js

@@ -1,6 +1,42 @@
 "use strict";
+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.pruneNullValues = void 0;
+exports.withTimeout = exports.isPromise = exports.TIMED_OUT = exports.MIDDLEWARE_TIMEOUT_MS = exports.pruneNullValues = void 0;
 var pruneNullValues = function (props) {
     if (typeof props !== 'object' || props === null)
         return props;
@@ -23,3 +59,45 @@ var pruneNullValues = function (props) {
     return props;
 };
 exports.pruneNullValues = pruneNullValues;
+/**
+ * How long a single asynchronous source middleware may take before its
+ * contribution is abandoned.
+ *
+ * Middleware runs on the path to the CDP, so an unbounded wait would let one
+ * slow lookup hold up delivery indefinitely. `Order Completed` in particular
+ * fires on a confirmation page shoppers close, so a late event is a lost one.
+ */
+exports.MIDDLEWARE_TIMEOUT_MS = 1000;
+/** Returned by {@link withTimeout} when the promise did not settle in time. */
+exports.TIMED_OUT = Symbol('timed-out');
+var isPromise = function (value) {
+    return typeof (value === null || value === void 0 ? void 0 : value.then) === 'function';
+};
+exports.isPromise = isPromise;
+/**
+ * Resolve `promise`, or {@link TIMED_OUT} if it has not settled within `ms`.
+ *
+ * The timer is cleared either way, so a promise that settles quickly does not
+ * leave a pending timeout behind.
+ */
+var withTimeout = function (promise, ms) { return __awaiter(void 0, void 0, void 0, function () {
+    var timer, timeout;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                timeout = new Promise(function (resolve) {
+                    timer = setTimeout(function () { return resolve(exports.TIMED_OUT); }, ms);
+                });
+                _a.label = 1;
+            case 1:
+                _a.trys.push([1, , 3, 4]);
+                return [4 /*yield*/, Promise.race([promise, timeout])];
+            case 2: return [2 /*return*/, _a.sent()];
+            case 3:
+                clearTimeout(timer);
+                return [7 /*endfinally*/];
+            case 4: return [2 /*return*/];
+        }
+    });
+}); };
+exports.withTimeout = withTimeout;

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.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/client/index.js

@@ -9,8 +9,9 @@ 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';
+import { isPromise, MIDDLEWARE_TIMEOUT_MS, pruneNullValues, TIMED_OUT, withTimeout, } from '../utils.js';
 const DEBUG_MODE_STORAGE_KEY = 'chordcommerce/analytics/debug';
 const CONSENT_QUEUE_STORAGE_KEY = 'chordcommerce/analytics/consent-queue';
 const CONSENT_QUEUE_TTL_MS = 5 * 60 * 1000; // 5 minutes
@@ -197,6 +198,32 @@ export class ChordAnalytics {
                 return null;
             return (window === null || window === void 0 ? void 0 : window[`_${namespace}`]) || 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 = () => {
+            const read = (analytics) => {
+                var _a, _b, _c;
+                try {
+                    const user = (_a = analytics === null || analytics === void 0 ? void 0 : analytics.user) === null || _a === void 0 ? void 0 : _a.call(analytics);
+                    if (!user)
+                        return undefined;
+                    const userId = (_b = user.userId) !== null && _b !== void 0 ? _b : undefined;
+                    const anonymousId = (_c = user.anonymousId) !== null && _c !== void 0 ? _c : undefined;
+                    if (userId === undefined && anonymousId === undefined)
+                        return undefined;
+                    return { userId, anonymousId };
+                }
+                catch (_d) {
+                    return undefined;
+                }
+            };
+            return read(this.ccdp()) || read(this.cdp()) || {};
+        };
         /*
          * Log a message to the console if `options.enableLogging` is true.
          */
@@ -403,11 +430,13 @@ export class ChordAnalytics {
                 const searchParams = typeof window !== 'undefined' ? window.location.search : '';
                 const urlSearchParams = new URLSearchParams(searchParams);
                 const searchData = Object.fromEntries(urlSearchParams.entries());
-                // process middleware synchronously
-                this.middleware.forEach((func) => {
+                const { userId, anonymousId } = this.currentUser();
+                const invoke = (func) => {
                     try {
-                        const result = func({
+                        return func({
                             payload: {
+                                userId,
+                                anonymousId,
                                 obj: {
                                     properties: props,
                                     event,
@@ -421,12 +450,44 @@ export class ChordAnalytics {
                             },
                             next: (_) => _,
                         });
-                        if (result && typeof result === 'object') {
-                            middlewareProps = Object.assign(Object.assign({}, middlewareProps), result);
-                        }
                     }
                     catch (error) {
                         console.warn('Middleware error:', error);
+                        return undefined;
+                    }
+                };
+                /**
+                 * Give an asynchronous middleware until MIDDLEWARE_TIMEOUT_MS to produce
+                 * its properties. Neither a timeout nor a rejection is allowed to reach
+                 * the caller: a middleware must never cost the event.
+                 */
+                const settle = (returned) => {
+                    if (!isPromise(returned))
+                        return returned;
+                    return withTimeout(returned, MIDDLEWARE_TIMEOUT_MS)
+                        .then((settled) => {
+                        if (settled === TIMED_OUT) {
+                            console.warn(`Middleware timed out after ${MIDDLEWARE_TIMEOUT_MS}ms; its properties were dropped`);
+                            return undefined;
+                        }
+                        return settled;
+                    })
+                        .catch((error) => {
+                        console.warn('Middleware error:', error);
+                        return undefined;
+                    });
+                };
+                // Every middleware is invoked in registration order, as before. Only if
+                // one actually returned a promise is anything awaited -- so a set of
+                // purely synchronous middleware reaches the CDP on the same tick it
+                // always has, and callers that never await `track()` are unaffected.
+                const returned = this.middleware.map(invoke);
+                const results = returned.some(isPromise)
+                    ? yield Promise.all(returned.map(settle))
+                    : returned;
+                results.forEach((result) => {
+                    if (result && typeof result === 'object') {
+                        middlewareProps = Object.assign(Object.assign({}, middlewareProps), result);
                     }
                 });
             }
@@ -600,6 +661,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 +1299,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/dist/types/client.d.ts

@@ -88,10 +88,23 @@ type MiddlewarePayload = {
             page: PageContext;
         };
     };
+    /**
+     * The current user and anonymous ids, read from the CDP at send time.
+     * Segment's middleware payload exposes these as `userId()`/`anonymousId()`
+     * methods on a facade; they are plain values here.
+     */
+    userId?: string;
+    anonymousId?: string;
 };
 type MiddlewareArgs = {
     payload: MiddlewarePayload;
     next: <T>(arg: T) => T;
 };
-export type AnalyticsMiddleware = (args: MiddlewareArgs) => Partial<EventProperties> | void;
+export type MiddlewareResult = Partial<EventProperties> | void;
+/**
+ * A source middleware may be synchronous or asynchronous. An asynchronous one
+ * is awaited before the event is dispatched, bounded by a timeout — see
+ * `addSourceMiddleware` in the README.
+ */
+export type AnalyticsMiddleware = (args: MiddlewareArgs) => MiddlewareResult | Promise<MiddlewareResult>;
 export {};