@chordcommerce/analytics 1.23.0 → 1.25.0-beta.2

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

@@ -31,34 +31,10 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      */
     private cdpReadyPromise;
     private consentConfig;
-    private resetCompletePromise;
-    /**
-     * Queue for events waiting for consent to be ready
-     */
-    private consentEventQueue;
-    /**
-     * Whether we're currently waiting for consent and watching for it
-     */
-    private consentWatcherActive;
-    /**
-     * Promise that resolves when consent is ready (shared across all queued events)
-     */
+    private operationQueue;
+    private resetting;
     private consentReadyPromise;
     constructor(options: ChordAnalyticsOptions<T>);
-    /**
-     * Persist the consent event queue to sessionStorage for recovery on instance recreation.
-     * Validates queue size before storing to prevent QuotaExceededError.
-     */
-    private persistQueueToStorage;
-    /**
-     * Restore pending events from sessionStorage (keeps events less than 5 min old).
-     * Called on new instance initialization.
-     */
-    private restoreQueueFromStorage;
-    /**
-     * Clear the persisted queue from sessionStorage after successful flush.
-     */
-    private clearQueueFromStorage;
     /**
      * Initialize CDP snippet and wait for it to be ready.
      * Fires initial consent track event after CDP is fully initialized to avoid circular await.
@@ -71,29 +47,17 @@ 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 enqueue;
+    private withTimeout;
     private waitForReadyState;
     /**
      * Wait for consent manager to be ready (no timeout - queues indefinitely).
      * Uses a shared promise so multiple events share the same watcher.
      */
     private waitForConsent;
-    /**
-     * Queue an event to be sent when consent is ready.
-     * Persists to sessionStorage for recovery on instance recreation.
-     * Starts a consent watcher if not already active.
-     */
-    private queueEventForConsent;
-    /**
-     * Watch for consent to become ready, then flush the queue.
-     */
-    private watchForConsentAndFlush;
-    /**
-     * Flush all queued events now that consent is ready.
-     * Clears sessionStorage after successful flush.
-     */
-    private flushConsentQueue;
     /**
      * Configure CDP with fresh consent categories before each event.
      * Uses Jitsu's configure() to update privacy.consentCategories.
@@ -152,7 +116,6 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      */
     private sendPageEvent;
     reset: () => Promise<void>;
-    private performReset;
     /**
      * Handler for postMessage events from the Shopify Web Pixel sandbox.
      * Bound to the instance for proper `this` context and cleanup.