@chordcommerce/analytics 1.18.3-beta.1 → 1.19.0

package/dist/client/index.d.ts

@@ -30,10 +30,24 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      * Promise that resolves when CDP is ready
      */
     private cdpReadyPromise;
+    private consentConfig;
     private resetInProgress;
+    /**
+     * 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 consentReadyPromise;
     constructor(options: ChordAnalyticsOptions<T>);
     /**
-     * Initialize CDP snippet and wait for it to be ready
+     * Initialize CDP snippet and wait for it to be ready.
+     * Fires initial consent track event after CDP is fully initialized to avoid circular await.
      */
     private initializeCdp;
     /**
@@ -45,6 +59,29 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
     ccdp: () => AnyAnalytics;
     logger: (message?: any, ...optionalParams: any[]) => void;
     isResetting: () => boolean;
+    /**
+     * 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.
+     * 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.
+     */
+    private flushConsentQueue;
+    /**
+     * Configure CDP with fresh consent categories before each event.
+     * Uses Jitsu's configure() to update privacy.consentCategories.
+     */
+    private configureConsentOnCdp;
     validate: (event: string, props: EventProperties) => ValidateResult[];
     /**
      * Generate the event `meta` property.
@@ -67,21 +104,36 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
     addSourceMiddleware: (func: AnalyticsMiddleware) => void;
     /**
      * Send a `track` event to the CDP with any event name and properties.
+     * If consent is not ready, the event is queued until consent is available.
      */
     track: (event: string, props?: EventProperties, options?: Options) => Promise<void>;
+    /**
+     * Internal method to actually send a track event to CDP.
+     */
+    private sendTrackEvent;
     /**
      * Send an `identify` event to the CDP with user id and traits.
+     * If consent is not ready, the event is queued until consent is available.
      */
     identify: {
         (userId?: string, traits?: IdentifyTraits, options?: AnyOptions): Promise<void>;
         (traits?: IdentifyTraits, options?: AnyOptions): Promise<void>;
     };
+    /**
+     * Internal method to actually send an identify event to CDP.
+     */
+    private sendIdentifyEvent;
     /**
      * Send a `page` event to the CDP.
+     * If consent is not ready, the event is queued until consent is available.
      */
     page: {
-        (props?: Record<string, any>): void;
+        (props?: Record<string, any>, options?: Options): void;
     };
+    /**
+     * Internal method to actually send a page event to CDP.
+     */
+    private sendPageEvent;
     reset: () => Promise<void>;
     trackCartViewed: (props: CartViewedInput<T>, options?: AnyOptions) => Promise<void>;
     trackCheckoutStarted: (props: CheckoutStartedInput<T>, options?: AnyOptions) => Promise<void>;

package/dist/client/index.js

@@ -8,6 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { addCdpSnippet, cdpQueue } from './cdp.js';
+import { addCdpConsent } from './consent/index.js';
 import { eventSchemas } from '../validators/index.js';
 import { pruneNullValues } from '../utils.js';
 const DEBUG_MODE_STORAGE_KEY = 'chordcommerce/analytics/debug';
@@ -30,7 +31,20 @@ export class ChordAnalytics {
          * Promise that resolves when CDP is ready
          */
         this.cdpReadyPromise = null;
+        this.consentConfig = null;
         this.resetInProgress = false;
+        /**
+         * Queue for events waiting for consent to be ready
+         */
+        this.consentEventQueue = [];
+        /**
+         * Whether we're currently waiting for consent and watching for it
+         */
+        this.consentWatcherActive = false;
+        /**
+         * Promise that resolves when consent is ready (shared across all queued events)
+         */
+        this.consentReadyPromise = null;
         /**
          * Set debug mode for Chord Analytics
          * @param enabled - Whether debug mode should be enabled
@@ -72,6 +86,102 @@ export class ChordAnalytics {
         this.isResetting = () => {
             return this.resetInProgress;
         };
+        /**
+         * Wait for consent manager to be ready (no timeout - queues indefinitely).
+         * Uses a shared promise so multiple events share the same watcher.
+         */
+        this.waitForConsent = () => __awaiter(this, void 0, void 0, function* () {
+            if (!this.consentConfig)
+                return;
+            if (this.consentConfig.isConsentReady())
+                return;
+            // If already waiting, return the existing promise
+            if (this.consentReadyPromise) {
+                yield this.consentReadyPromise;
+                return;
+            }
+            // Start a new consent watcher - polls until consent is ready
+            this.consentReadyPromise = new Promise((resolve) => {
+                const interval = setInterval(() => {
+                    var _a;
+                    if ((_a = this.consentConfig) === null || _a === void 0 ? void 0 : _a.isConsentReady()) {
+                        clearInterval(interval);
+                        this.consentReadyPromise = null;
+                        resolve(true);
+                    }
+                }, 100);
+            });
+            yield this.consentReadyPromise;
+        });
+        /**
+         * Queue an event to be sent when consent is ready.
+         * Starts a consent watcher if not already active.
+         */
+        this.queueEventForConsent = (type, args) => {
+            return new Promise((resolve) => {
+                this.consentEventQueue.push({ type, args, resolve });
+                // Start watching for consent if not already
+                if (!this.consentWatcherActive) {
+                    this.consentWatcherActive = true;
+                    this.watchForConsentAndFlush();
+                }
+            });
+        };
+        /**
+         * Watch for consent to become ready, then flush the queue.
+         */
+        this.watchForConsentAndFlush = () => __awaiter(this, void 0, void 0, function* () {
+            yield this.waitForConsent();
+            yield this.flushConsentQueue();
+            this.consentWatcherActive = false;
+        });
+        /**
+         * Flush all queued events now that consent is ready.
+         */
+        this.flushConsentQueue = () => __awaiter(this, void 0, void 0, function* () {
+            const queue = [...this.consentEventQueue];
+            this.consentEventQueue = [];
+            const sendPromises = queue.map((item) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    switch (item.type) {
+                        case 'track':
+                            yield this.sendTrackEvent(item.args[0], item.args[1], item.args[2]);
+                            break;
+                        case 'page':
+                            yield this.sendPageEvent(item.args[0], item.args[1]);
+                            break;
+                        case 'identify':
+                            yield this.sendIdentifyEvent(item.args[0], item.args[1], item.args[2]);
+                            break;
+                        default:
+                            break;
+                    }
+                }
+                catch (error) {
+                    this.logger('[Chord Analytics]: Error sending queued event:', error);
+                }
+                item.resolve();
+            }));
+            yield Promise.all(sendPromises);
+        });
+        /**
+         * Configure CDP with fresh consent categories before each event.
+         * Uses Jitsu's configure() to update privacy.consentCategories.
+         */
+        this.configureConsentOnCdp = () => {
+            if (!this.consentConfig)
+                return;
+            const categories = this.consentConfig.getCategories();
+            const privacyConfig = { privacy: { consentCategories: categories } };
+            const a = this.ccdp();
+            if (a && typeof a.configure === 'function') {
+                a.configure(privacyConfig);
+            }
+            const b = this.cdp();
+            if (b && typeof b.configure === 'function') {
+                b.configure(privacyConfig);
+            }
+        };
         this.validate = (event, props) => {
             if (!event) {
                 this.logger('No event name provided');
@@ -104,14 +214,46 @@ export class ChordAnalytics {
         };
         /**
          * Send a `track` event to the CDP with any event name and properties.
+         * If consent is not ready, the event is queued until consent is available.
          */
         this.track = (event, props, options) => __awaiter(this, void 0, void 0, function* () {
+            if (this.options.enableLogging && this.options.debug) {
+                // eslint-disable-next-line no-console
+                console.log(`[Chord Analytics DEBUG]: track() called with event: "${event}"`);
+            }
             if (!event)
                 this.logger('No event name provided');
             // Wait for CDP to be ready before sending track events
             if (this.cdpReadyPromise) {
+                if (this.options.enableLogging && this.options.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[Chord Analytics DEBUG]: track("${event}") waiting for cdpReadyPromise`);
+                }
                 yield this.cdpReadyPromise;
+                if (this.options.enableLogging && this.options.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[Chord Analytics DEBUG]: track("${event}") cdpReadyPromise resolved`);
+                }
             }
+            // If consent is configured but not ready, queue the event
+            if (this.consentConfig && !this.consentConfig.isConsentReady()) {
+                if (this.options.enableLogging && this.options.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[Chord Analytics DEBUG]: track("${event}") consent not ready, queuing event`);
+                }
+                return this.queueEventForConsent('track', [event, props, options]);
+            }
+            if (this.options.enableLogging && this.options.debug) {
+                // eslint-disable-next-line no-console
+                console.log(`[Chord Analytics DEBUG]: track("${event}") sending event now`);
+            }
+            // Consent ready (or not configured) - send immediately
+            return this.sendTrackEvent(event, props, options);
+        });
+        /**
+         * Internal method to actually send a track event to CDP.
+         */
+        this.sendTrackEvent = (event, props, options) => __awaiter(this, void 0, void 0, function* () {
             const formattedProps = this.options.stripNull && props ? pruneNullValues(props) : props;
             let middlewareProps = {};
             if (this.middleware.length > 0) {
@@ -153,7 +295,9 @@ export class ChordAnalytics {
                     }
                 });
             }
-            return new Promise((resolve) => {
+            // Configure CDP with fresh consent before sending
+            this.configureConsentOnCdp();
+            yield new Promise((resolve) => {
                 const cdpPromises = [];
                 try {
                     const a = this.ccdp();
@@ -188,24 +332,65 @@ export class ChordAnalytics {
         });
         /**
          * Send an `identify` event to the CDP with user id and traits.
+         * If consent is not ready, the event is queued until consent is available.
          */
-        this.identify = (...props) => __awaiter(this, void 0, void 0, function* () {
+        this.identify = (userIdOrTraits, traitsOrOptions, options) => __awaiter(this, void 0, void 0, function* () {
             // Wait for CDP to be ready before sending identify events
             if (this.cdpReadyPromise) {
                 yield this.cdpReadyPromise;
             }
+            // If consent is configured but not ready, queue the event
+            if (this.consentConfig && !this.consentConfig.isConsentReady()) {
+                return this.queueEventForConsent('identify', [
+                    userIdOrTraits,
+                    traitsOrOptions,
+                    options,
+                ]);
+            }
+            // Consent ready (or not configured) - send immediately
+            return this.sendIdentifyEvent(userIdOrTraits, traitsOrOptions, options);
+        });
+        /**
+         * Internal method to actually send an identify event to CDP.
+         */
+        this.sendIdentifyEvent = (userIdOrTraits, traitsOrOptions, options) => __awaiter(this, void 0, void 0, function* () {
+            // Parse arguments to extract userId, traits, and options
+            let userId;
+            let traits;
+            let opts;
+            if (typeof userIdOrTraits === 'string') {
+                userId = userIdOrTraits;
+                traits = traitsOrOptions;
+                opts = options;
+            }
+            else {
+                traits = userIdOrTraits;
+                opts = traitsOrOptions;
+            }
+            // Configure CDP with fresh consent before sending
+            this.configureConsentOnCdp();
             try {
                 const identifyPromises = [];
                 const a = this.ccdp();
                 if (a && typeof a.identify === 'function') {
                     identifyPromises.push(new Promise((resolve) => {
-                        a.identify(...props, () => resolve());
+                        if (userId) {
+                            a.identify(userId, traits, opts, () => resolve());
+                        }
+                        else {
+                            a.identify(traits, opts, () => resolve());
+                        }
                     }));
                 }
                 const b = this.cdp();
                 if (b && typeof b.identify === 'function') {
                     identifyPromises.push(new Promise((resolve) => {
-                        b.identify(...props, () => resolve());
+                        if (userId) {
+                            b.identify(userId, traits, opts, () => resolve());
+                        }
+                        else {
+                            b.identify(traits, opts, () => resolve());
+                        }
                     }));
                 }
                 const results = yield Promise.allSettled(identifyPromises);
@@ -217,24 +402,38 @@ export class ChordAnalytics {
         });
         /**
          * Send a `page` event to the CDP.
+         * If consent is not ready, the event is queued until consent is available.
          */
-        this.page = (props = {}) => __awaiter(this, void 0, void 0, function* () {
+        this.page = (options, props = {}) => __awaiter(this, void 0, void 0, function* () {
             // Wait for CDP to be ready before sending page events
             if (this.cdpReadyPromise) {
                 yield this.cdpReadyPromise;
             }
+            // If consent is configured but not ready, queue the event
+            if (this.consentConfig && !this.consentConfig.isConsentReady()) {
+                return this.queueEventForConsent('page', [options, props]);
+            }
+            // Consent ready (or not configured) - send immediately
+            return this.sendPageEvent(options, props);
+        });
+        /**
+         * Internal method to actually send a page event to CDP.
+         */
+        this.sendPageEvent = (options, props = {}) => __awaiter(this, void 0, void 0, function* () {
+            // Configure CDP with fresh consent before sending
+            this.configureConsentOnCdp();
             try {
                 const pagePromises = [];
                 const a = this.ccdp();
                 if (a && typeof a.page === 'function') {
                     pagePromises.push(new Promise((resolve) => {
-                        a.page(Object.assign(Object.assign({}, props), { meta: this.meta() }), () => resolve());
+                        a.page(Object.assign(Object.assign({}, props), { meta: this.meta() }), options, () => resolve());
                     }));
                 }
                 const b = this.cdp();
                 if (b && typeof b.page === 'function') {
                     pagePromises.push(new Promise((resolve) => {
-                        b.page(Object.assign(Object.assign({}, props), { meta: this.meta() }), () => resolve());
+                        b.page(Object.assign(Object.assign({}, props), { meta: this.meta() }), options, () => resolve());
                     }));
                 }
                 // We don't return the promise to maintain the void return type
@@ -680,21 +879,56 @@ export class ChordAnalytics {
             stripNull: true,
         };
         this.options = Object.assign(Object.assign({}, defaults), options);
+        if (this.options.consent) {
+            const consentManager = addCdpConsent(this.options);
+            this.consentConfig = consentManager.getConsentConfig() || null;
+        }
         if (((_b = this.options) === null || _b === void 0 ? void 0 : _b.cdpDomain) && ((_c = this.options) === null || _c === void 0 ? void 0 : _c.cdpWriteKey) && window) {
             window[this.options.namespace] = (window === null || window === void 0 ? void 0 : window[this.options.namespace]) || this;
             this.initializeCdp();
         }
     }
     /**
-     * Initialize CDP snippet and wait for it to be ready
+     * Initialize CDP snippet and wait for it to be ready.
+     * Fires initial consent track event after CDP is fully initialized to avoid circular await.
      */
     initializeCdp() {
         return __awaiter(this, void 0, void 0, function* () {
+            if (this.options.enableLogging && this.options.debug) {
+                // eslint-disable-next-line no-console
+                console.log('[Chord Analytics DEBUG]: initializeCdp() started');
+            }
             try {
-                this.cdpReadyPromise = addCdpSnippet(this.options);
-                yield this.cdpReadyPromise;
+                const snippetPromise = addCdpSnippet(this.options);
+                // Create a void promise for cdpReadyPromise that resolves when snippet is done
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                this.cdpReadyPromise = snippetPromise.then(() => { });
+                const { initialConsent } = yield snippetPromise;
+                if (this.options.enableLogging && this.options.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log('[Chord Analytics DEBUG]: snippetPromise resolved, initialConsent:', JSON.stringify(initialConsent));
+                    // 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
+                if (initialConsent && initialConsent.consentCategories !== undefined) {
+                    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);
+                    if (this.options.enableLogging && this.options.debug) {
+                        // eslint-disable-next-line no-console
+                        console.log('[Chord Analytics DEBUG]: Initial consent preferences tracked');
+                    }
+                }
+                else 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');
+                }
             }
             catch (error) {
+                // eslint-disable-next-line no-console
                 console.error('CDP initialization failed:', error);
             }
         });

package/dist/types/consent.d.ts

@@ -1,11 +1,22 @@
 export interface ConsentAdapter {
     getCurrentConsent: () => ConsentConfiguration | Promise<ConsentConfiguration>;
-    handleConsentUpdates: (fn: (ConsentConfiguration: any) => void) => void;
+    handleConsentUpdates: (fn: (consent: ConsentConfiguration) => void) => void;
     userCanBeTracked: () => boolean | Promise<boolean>;
+    /**
+     * Get current consent categories - called FRESH on every event, no caching!
+     */
+    getCategories?: () => Record<string, boolean>;
+    /**
+     * Check if consent manager is ready (duck typing check)
+     */
+    isConsentReady?: () => boolean;
+    /**
+     * Get the consent model ('opt-in' or 'opt-out')
+     */
+    getConsentModel?: () => 'opt-in' | 'opt-out';
 }
 export interface ConsentConfiguration {
     consentCategories?: {
         [key: string]: boolean;
     };
-    dontSend?: boolean;
 }

package/package.json

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