@chordcommerce/analytics 1.23.0 → 1.25.0-beta.2

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

@@ -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.