@chordcommerce/analytics 1.18.3-beta.1 → 1.19.0-beta.1

package/dist/client/consent/index.d.ts

@@ -1,11 +1,9 @@
 import type { ChordAnalyticsOptions, ConsentConfiguration } from '../../types/index.js';
-declare global {
-    interface Window {
-        jitsuConfig: {
-            privacy: ConsentConfiguration;
-        };
-    }
-}
 export declare const addCdpConsent: (options: ChordAnalyticsOptions) => {
-    init: () => Promise<boolean>;
+    init: () => Promise<ConsentConfiguration | null>;
+    getConsentConfig: () => {
+        getCategories: () => Record<string, boolean>;
+        isConsentReady: () => boolean;
+        debug: boolean;
+    };
 };

package/dist/client/consent/index.js

@@ -12,7 +12,6 @@ import { onetrustConsentAdapter } from './onetrust.js';
 import { shopifyConsentAdapter } from './shopify.js';
 import { segmentConsentAdapter } from './segment.js';
 export const addCdpConsent = (options) => {
-    let adapter = null;
     let lastProcessedConsent = null;
     const POLLING_INTERVAL_MS = 50;
     const TIMEOUT_MS = options.awaitConsentTimeout
@@ -36,6 +35,8 @@ export const addCdpConsent = (options) => {
                 return null;
         }
     };
+    // Initialize adapter immediately so getConsentConfig() works
+    const adapter = getAdapter();
     /**
      * Polls if user can be tracked based on consent
      * @returns Promise that resolves to true if condition is met within timeout, false otherwise
@@ -60,105 +61,92 @@ export const addCdpConsent = (options) => {
         });
     });
     /**
-     * Attempts to configure CDP with retry logic.
+     * Tracks consent preference changes.
+     * Note: Per-event consent stamping is handled in ChordAnalytics via stampConsent().
      */
-    const configureCdpWithRetry = (updatedConsent, maxRetries = 5, baseDelay = 100) => __awaiter(void 0, void 0, void 0, function* () {
-        let attempt = 0;
-        const tryConfigure = () => __awaiter(void 0, void 0, void 0, function* () {
-            const cdp = window[`_${options.namespace}`];
-            if (cdp && typeof cdp.configure === 'function') {
-                try {
-                    if (Object.keys(updatedConsent).length > 0) {
-                        cdp.configure({ privacy: updatedConsent });
-                    }
-                    return true;
-                }
-                catch (error) {
-                    // Continue to retry on error
-                }
-            }
-            if (attempt < maxRetries) {
-                const delay = baseDelay * Math.pow(2, attempt); // Exponential backoff
-                yield new Promise((resolve) => {
-                    setTimeout(resolve, delay);
-                });
-                attempt++;
-                return tryConfigure();
-            }
-            console.warn('CDP configuration failed after all retries, falling back to jitsuConfig');
-            return false;
-        });
-        return tryConfigure();
-    });
-    /**
-     * Updates consent for all future events.
-     */
-    const updateCdpConsent = (updatedConsent) => __awaiter(void 0, void 0, void 0, function* () {
+    const trackConsentUpdate = (updatedConsent) => __awaiter(void 0, void 0, void 0, function* () {
         if (lastProcessedConsent &&
             JSON.stringify(lastProcessedConsent) === JSON.stringify(updatedConsent)) {
             return;
         }
         lastProcessedConsent = updatedConsent;
         const chordAnalytics = window[options.namespace];
-        const shouldTrackConsentUpdate = chordAnalytics &&
+        if (chordAnalytics &&
             typeof chordAnalytics.track === 'function' &&
-            updatedConsent.consentCategories !== undefined;
-        if (shouldTrackConsentUpdate &&
-            // we have to send this BEFORE the CDP is reconfigured or else the track will not be sent, usually in the case of a user opting out
-            updatedConsent.dontSend === true) {
-            yield chordAnalytics.track('Consent Preferences Updated', updatedConsent);
-        }
-        const cdpConfigured = yield configureCdpWithRetry(updatedConsent);
-        if (!cdpConfigured) {
-            // CDP has not yet loaded via the snippet or all retries failed.
-            window.jitsuConfig = { privacy: updatedConsent };
-        }
-        if (shouldTrackConsentUpdate &&
-            // we have to send this AFTER the CDP is reconfigured to ensure the track is sent, usually in the case of a user opting in
-            updatedConsent.dontSend === false) {
+            updatedConsent.consentCategories !== undefined) {
             yield chordAnalytics.track('Consent Preferences Updated', updatedConsent);
+            if (options.enableLogging && options.debug) {
+                console.log('[Chord Analytics DEBUG]: Consent preferences updated, sent tracking event');
+            }
         }
     });
     /**
      * Sets up consent management by initializing the adapter and handling consent updates.
+     * Returns the initial consent so it can be tracked after CDP is fully ready (avoiding circular await).
      */
     const setupConsentManagement = () => __awaiter(void 0, void 0, void 0, function* () {
         if (!adapter)
-            return;
+            return null;
         // Set up the consent update handler first to catch any immediate updates
         adapter.handleConsentUpdates((updatedConsent) => {
-            updateCdpConsent(updatedConsent);
+            trackConsentUpdate(updatedConsent);
         });
-        // Process initial consent - this will be skipped if the adapter already triggered an update
+        // Return initial consent to be tracked after CDP is fully initialized
         const initialConsent = yield adapter.getCurrentConsent();
-        yield updateCdpConsent(initialConsent);
+        lastProcessedConsent = initialConsent;
+        return initialConsent;
     });
     /**
-     * Initializes consent management.
-     * Returns a promise that resolves to true if CDP should be loaded, false otherwise.
+     * Initializes consent management and sets up consent update handlers.
+     * Returns initial consent configuration to be tracked after CDP is fully ready,
+     * or null if consent setup failed or was blocked.
      */
     const init = () => __awaiter(void 0, void 0, void 0, function* () {
-        adapter = getAdapter();
+        if (options.debug && options.enableLogging) {
+            console.log('[Chord Analytics DEBUG]: consent init() called, adapter:', adapter ? options.consent : 'null');
+        }
         if (adapter === null) {
             console.error(`Consent management adapter "${options.consent}" is not supported.`);
-            return false;
+            return null;
         }
         if (options.awaitConsent) {
+            if (options.debug && options.enableLogging) {
+                console.log('[Chord Analytics DEBUG]: awaitConsent is true, checking if user can be tracked');
+            }
             const canBeTracked = yield checkUserCanBeTracked();
-            if (!canBeTracked)
-                return false;
+            if (!canBeTracked) {
+                if (options.debug && options.enableLogging) {
+                    console.log('[Chord Analytics DEBUG]: User cannot be tracked, returning null');
+                }
+                return null;
+            }
         }
         try {
-            yield setupConsentManagement();
+            const result = yield setupConsentManagement();
+            if (options.debug && options.enableLogging) {
+                console.log('[Chord Analytics DEBUG]: setupConsentManagement() returned:', JSON.stringify(result));
+            }
+            return result;
         }
         catch (error) {
             if (options.debug && options.enableLogging) {
-                console.error('Error setting up consent management:', error);
+                console.error('[Chord Analytics DEBUG]: Error setting up consent management:', error);
             }
+            return null;
         }
-        return true;
     });
+    const getConsentConfig = () => {
+        if (!(adapter === null || adapter === void 0 ? void 0 : adapter.getCategories) || !(adapter === null || adapter === void 0 ? void 0 : adapter.isConsentReady)) {
+            return undefined;
+        }
+        return {
+            getCategories: () => adapter.getCategories(),
+            isConsentReady: () => adapter.isConsentReady(),
+            debug: options.debug && options.enableLogging,
+        };
+    };
     return {
         init,
+        getConsentConfig,
     };
 };

package/dist/client/consent/ketch.d.ts

@@ -12,5 +12,7 @@ export declare const ketchConsentAdapter: () => {
     getCurrentConsent: () => ConsentConfiguration;
     handleConsentUpdates: (updateCdpConsent: (consent: ConsentConfiguration) => void) => void;
     userCanBeTracked: () => boolean;
+    getCategories: () => Record<string, boolean>;
+    isConsentReady: () => boolean;
 };
 export {};

package/dist/client/consent/ketch.js

@@ -18,7 +18,6 @@ const getCurrentConsent = () => {
         return {};
     return {
         consentCategories: Object.assign({}, api),
-        dontSend: !userCanBeTracked(),
     };
 };
 /**
@@ -34,5 +33,10 @@ export const ketchConsentAdapter = () => {
         getCurrentConsent,
         handleConsentUpdates,
         userCanBeTracked,
+        getCategories: () => {
+            const api = getApi();
+            return api ? Object.assign({}, api) : {};
+        },
+        isConsentReady: () => !!getApi(),
     };
 };

package/dist/client/consent/onetrust-api.d.ts

@@ -0,0 +1,103 @@
+/**
+ * OneTrust API Utilities
+ *
+ * Provides type-safe access to OneTrust's global API with proper duck typing
+ * to ensure the API is fully loaded before use.
+ *
+ * Modeled after analytics-next's onetrust-api.ts
+ */
+/**
+ * OneTrust consent model types
+ */
+export declare enum OtConsentModel {
+    optIn = "opt-in",
+    optOut = "opt-out",
+    implied = "implied consent"
+}
+/**
+ * OneTrust domain data structure
+ */
+export interface OneTrustDomainData {
+    ShowAlertNotice: boolean;
+    Groups: OneTrustGroup[];
+    ConsentModel: {
+        Name: OtConsentModel | string;
+    };
+}
+export interface OneTrustGroup {
+    CustomGroupId: string;
+}
+/**
+ * OneTrust consent changed event
+ */
+type OtConsentChangedEvent = CustomEvent<string[]>;
+/**
+ * OneTrust global API interface
+ */
+export interface OneTrustGlobal {
+    GetDomainData: () => OneTrustDomainData;
+    OnConsentChanged: (cb: (event: OtConsentChangedEvent) => void) => void;
+    IsAlertBoxClosed: () => boolean;
+}
+declare global {
+    interface Window {
+        OneTrust?: OneTrustGlobal | Record<string, unknown>;
+        OnetrustActiveGroups?: string;
+    }
+}
+/**
+ * Get the OneTrust global API if it's ready.
+ *
+ * Uses duck typing to check if OneTrust is fully loaded.
+ * window.OneTrust may exist but not be ready (e.g., just has geolocationResponse).
+ *
+ * @returns OneTrustGlobal if ready, undefined otherwise
+ */
+export declare const getOneTrustGlobal: () => OneTrustGlobal | undefined;
+/**
+ * Get the raw OnetrustActiveGroups string.
+ *
+ * @returns Comma-separated string of active group IDs, or undefined
+ */
+export declare const getOneTrustActiveGroups: () => string | undefined;
+/**
+ * Get normalized active group IDs as an array.
+ * Reads FRESH from window.OnetrustActiveGroups each time - no caching!
+ *
+ * @returns Array of active group IDs
+ *
+ * @example
+ * // window.OnetrustActiveGroups = ",C0001,C0003,"
+ * getNormalizedActiveGroupIds() // ["C0001", "C0003"]
+ */
+export declare const getNormalizedActiveGroupIds: () => string[];
+/**
+ * Get all configured consent groups from OneTrust.
+ *
+ * @returns Array of group info objects
+ */
+export declare const getAllGroups: () => {
+    groupId: string;
+}[];
+/**
+ * Get normalized consent categories.
+ * Reads FRESH from OneTrust globals each time - NO CACHING!
+ *
+ * This ensures if a user changes consent between two track() calls,
+ * each event reflects the consent state AT THAT MOMENT.
+ *
+ * @returns Record of category ID to consent boolean
+ *
+ * @example
+ * getNormalizedCategories()
+ * // { "C0001": true, "C0002": false, "C0003": true }
+ */
+export declare const getNormalizedCategories: () => Record<string, boolean>;
+/**
+ * Coerce OneTrust consent model name to our simplified model.
+ *
+ * @param model - OneTrust consent model name
+ * @returns 'opt-in' or 'opt-out'
+ */
+export declare const coerceConsentModel: (model: OtConsentModel | string) => 'opt-in' | 'opt-out';
+export {};

package/dist/client/consent/onetrust-api.js

@@ -0,0 +1,119 @@
+/**
+ * OneTrust API Utilities
+ *
+ * Provides type-safe access to OneTrust's global API with proper duck typing
+ * to ensure the API is fully loaded before use.
+ *
+ * Modeled after analytics-next's onetrust-api.ts
+ */
+/**
+ * OneTrust consent model types
+ */
+// eslint-disable-next-line no-shadow
+export var OtConsentModel;
+(function (OtConsentModel) {
+    OtConsentModel["optIn"] = "opt-in";
+    OtConsentModel["optOut"] = "opt-out";
+    OtConsentModel["implied"] = "implied consent";
+})(OtConsentModel || (OtConsentModel = {}));
+/**
+ * Get the OneTrust global API if it's ready.
+ *
+ * Uses duck typing to check if OneTrust is fully loaded.
+ * window.OneTrust may exist but not be ready (e.g., just has geolocationResponse).
+ *
+ * @returns OneTrustGlobal if ready, undefined otherwise
+ */
+export const getOneTrustGlobal = () => {
+    const oneTrust = window.OneTrust;
+    if (!oneTrust)
+        return undefined;
+    // Duck typing - check for required methods to ensure OneTrust is fully loaded
+    if (typeof oneTrust === 'object' &&
+        'OnConsentChanged' in oneTrust &&
+        'IsAlertBoxClosed' in oneTrust &&
+        'GetDomainData' in oneTrust) {
+        return oneTrust;
+    }
+    return undefined;
+};
+/**
+ * Get the raw OnetrustActiveGroups string.
+ *
+ * @returns Comma-separated string of active group IDs, or undefined
+ */
+export const getOneTrustActiveGroups = () => {
+    const groups = window.OnetrustActiveGroups;
+    if (!groups || typeof groups !== 'string')
+        return undefined;
+    return groups;
+};
+/**
+ * Get normalized active group IDs as an array.
+ * Reads FRESH from window.OnetrustActiveGroups each time - no caching!
+ *
+ * @returns Array of active group IDs
+ *
+ * @example
+ * // window.OnetrustActiveGroups = ",C0001,C0003,"
+ * getNormalizedActiveGroupIds() // ["C0001", "C0003"]
+ */
+export const getNormalizedActiveGroupIds = () => {
+    const groups = getOneTrustActiveGroups();
+    if (!groups)
+        return [];
+    return groups.trim().split(',').filter(Boolean);
+};
+/**
+ * Get all configured consent groups from OneTrust.
+ *
+ * @returns Array of group info objects
+ */
+export const getAllGroups = () => {
+    const oneTrust = getOneTrustGlobal();
+    if (!oneTrust)
+        return [];
+    return oneTrust.GetDomainData().Groups.map((group) => ({
+        groupId: group.CustomGroupId.trim(),
+    }));
+};
+/**
+ * Get normalized consent categories.
+ * Reads FRESH from OneTrust globals each time - NO CACHING!
+ *
+ * This ensures if a user changes consent between two track() calls,
+ * each event reflects the consent state AT THAT MOMENT.
+ *
+ * @returns Record of category ID to consent boolean
+ *
+ * @example
+ * getNormalizedCategories()
+ * // { "C0001": true, "C0002": false, "C0003": true }
+ */
+export const getNormalizedCategories = () => {
+    const activeGroupIds = getNormalizedActiveGroupIds();
+    return getAllGroups().reduce((acc, group) => {
+        acc[group.groupId] = activeGroupIds.includes(group.groupId);
+        return acc;
+    }, {});
+};
+/**
+ * Coerce OneTrust consent model name to our simplified model.
+ *
+ * @param model - OneTrust consent model name
+ * @returns 'opt-in' or 'opt-out'
+ */
+export const coerceConsentModel = (model) => {
+    switch (model) {
+        case OtConsentModel.optIn:
+        case OtConsentModel.implied:
+        case 'opt-in':
+        case 'implied consent':
+            return 'opt-in';
+        case OtConsentModel.optOut:
+        case 'opt-out':
+        default:
+            // Default to opt-out for unknown models (e.g., 'custom', 'notice')
+            return 'opt-out';
+    }
+};

package/dist/client/consent/onetrust.d.ts

@@ -1,22 +1,10 @@
 import type { ChordAnalyticsOptions, ConsentConfiguration } from '../../types/index.js';
-declare global {
-    interface Window {
-        OneTrust?: OneTrustApi;
-        OnetrustActiveGroups?: string;
-    }
-}
-interface OneTrustApi {
-    OnConsentChanged: (callback: () => void) => void;
-    GetDomainData: () => {
-        Groups: OneTrustGroup[];
-    };
-}
-interface OneTrustGroup {
-    CustomGroupId: string;
-}
 export declare const onetrustConsentAdapter: (options: ChordAnalyticsOptions) => {
     getCurrentConsent: () => ConsentConfiguration;
     handleConsentUpdates: (updateCdpConsent: (consent: ConsentConfiguration) => void) => void;
     userCanBeTracked: () => boolean;
+    getCategories: () => Record<string, boolean>;
+    isConsentReady: () => boolean;
+    getConsentModel: () => 'opt-in' | 'opt-out';
+    getApi: () => import("./onetrust-api.js").OneTrustGlobal;
 };
-export {};

package/dist/client/consent/onetrust.js

@@ -1,80 +1,72 @@
-/**
- * Returns OneTrust's API.
- */
-const getApi = () => {
-    const oneTrust = window.OneTrust;
-    if (oneTrust &&
-        typeof oneTrust === 'object' &&
-        'OnConsentChanged' in oneTrust &&
-        'GetDomainData' in oneTrust) {
-        return oneTrust;
-    }
-    return undefined;
-};
+import { getOneTrustGlobal, getNormalizedCategories, coerceConsentModel, } from './onetrust-api.js';
 /**
  * Returns whether the user can currently be tracked.
+ * Uses duck typing to check if OneTrust is fully loaded.
  */
 const userCanBeTracked = () => {
-    // Always loads, a la `consentModel: 'opt-out'` in the Segment wrapper.
-    const api = getApi();
-    return !!api;
+    // Always loads when OneTrust is ready, a la `consentModel: 'opt-out'`
+    return !!getOneTrustGlobal();
 };
 /**
  * Returns the user's current consent configuration.
+ * Reads FRESH from OneTrust - no caching!
  */
 const getCurrentConsent = () => {
-    const api = getApi();
-    const activeGroups = window.OnetrustActiveGroups;
-    if (!api || !activeGroups || typeof activeGroups !== 'string')
+    const api = getOneTrustGlobal();
+    if (!api)
         return {};
-    const activeGroupIds = new Set(activeGroups.trim().split(',').filter(Boolean));
     return {
-        consentCategories: api
-            .GetDomainData()
-            .Groups.reduce((acc, { CustomGroupId }) => {
-            const groupId = CustomGroupId.trim();
-            acc[groupId] = activeGroupIds.has(groupId);
-            return acc;
-        }, {}),
-        dontSend: !userCanBeTracked(),
+        consentCategories: getNormalizedCategories(),
     };
 };
 /**
  * Handles subsequent changes to consent configuration.
+ * Sets up OnConsentChanged listener with retry logic.
  */
 const handleConsentUpdates = (updateCdpConsent, options) => {
     const maxRetries = 100;
     const retryInterval = 50;
     let attempts = 0;
     const setupHandler = () => {
-        const api = getApi();
+        const api = getOneTrustGlobal();
         if (!api) {
             attempts++;
             if (attempts < maxRetries) {
                 if (options.debug && options.enableLogging) {
-                    // eslint-disable-next-line no-console
-                    console.log('OneTrust API not found, retrying...');
+                    console.log('[Chord Analytics DEBUG]: OneTrust API not found, retrying...');
                 }
                 setTimeout(setupHandler, retryInterval);
             }
             return;
         }
         if (options.debug && options.enableLogging) {
-            // eslint-disable-next-line no-console
-            console.log('OneTrust API found, setting up consent changed handler');
+            console.log('[Chord Analytics DEBUG]: OneTrust API found, setting up consent changed handler');
         }
         api.OnConsentChanged(() => {
             updateCdpConsent(getCurrentConsent());
+            if (options.debug && options.enableLogging) {
+                console.log('[Chord Analytics DEBUG]: OneTrust consent changed, sending Consent Preferences Updated track event');
+            }
         });
     };
     setupHandler();
 };
 export const onetrustConsentAdapter = (options) => {
     return {
+        // Existing methods for backwards compatibility
         getCurrentConsent,
         handleConsentUpdates: (updateCdpConsent) => {
             handleConsentUpdates(updateCdpConsent, options);
         },
         userCanBeTracked,
+        getCategories: () => getNormalizedCategories(),
+        isConsentReady: () => !!getOneTrustGlobal(),
+        getConsentModel: () => {
+            const api = getOneTrustGlobal();
+            if (!api)
+                return 'opt-out';
+            return coerceConsentModel(api.GetDomainData().ConsentModel.Name);
+        },
+        getApi: getOneTrustGlobal,
     };
 };

package/dist/client/consent/segment.d.ts

@@ -13,5 +13,7 @@ export declare const segmentConsentAdapter: () => {
     getCurrentConsent: () => Promise<ConsentConfiguration>;
     handleConsentUpdates: (updateCdpConsent: (consent: ConsentConfiguration) => void) => void;
     userCanBeTracked: () => Promise<boolean>;
+    getCategories: () => Record<string, boolean>;
+    isConsentReady: () => boolean;
 };
 export {};

package/dist/client/consent/segment.js

@@ -33,8 +33,6 @@ const waitForApi = (maxRetries = 10, baseDelay = 100) => __awaiter(void 0, void
         return null;
     });
     return checkAndWait();
-    console.warn('Segment API failed to load after all retries');
-    return null;
 });
 /**
  * Returns whether the user can currently be tracked.
@@ -54,7 +52,6 @@ const getCurrentConsent = () => __awaiter(void 0, void 0, void 0, function* () {
         return {};
     return {
         consentCategories: Object.assign(Object.assign({}, api.customPreferences), api.destinationPreferences),
-        dontSend: !(yield userCanBeTracked()),
     };
 });
 /**
@@ -70,5 +67,15 @@ export const segmentConsentAdapter = () => {
         getCurrentConsent,
         handleConsentUpdates,
         userCanBeTracked,
+        getCategories: () => {
+            const api = getApi();
+            if (!(api === null || api === void 0 ? void 0 : api.customPreferences))
+                return {};
+            return Object.assign(Object.assign({}, api.customPreferences), api.destinationPreferences);
+        },
+        isConsentReady: () => {
+            const api = getApi();
+            return !!((api === null || api === void 0 ? void 0 : api.customPreferences) && Object.keys(api.customPreferences).length > 0);
+        },
     };
 };

package/dist/client/consent/shopify.d.ts

@@ -17,5 +17,7 @@ export declare const shopifyConsentAdapter: () => {
     getCurrentConsent: () => ConsentConfiguration;
     handleConsentUpdates: (updateCdpConsent: (consent: ConsentConfiguration) => void) => void;
     userCanBeTracked: () => boolean;
+    getCategories: () => Record<string, boolean>;
+    isConsentReady: () => boolean;
 };
 export {};

package/dist/client/consent/shopify.js

@@ -27,7 +27,6 @@ const getCurrentConsent = () => {
             preferences: api.preferencesProcessingAllowed(),
             sale_of_data: api.saleOfDataAllowed(),
         },
-        dontSend: !userCanBeTracked(),
     };
 };
 /**
@@ -43,5 +42,17 @@ export const shopifyConsentAdapter = () => {
         getCurrentConsent,
         handleConsentUpdates,
         userCanBeTracked,
+        getCategories: () => {
+            const api = getApi();
+            if (!api)
+                return {};
+            return {
+                analytics: api.analyticsProcessingAllowed(),
+                marketing: api.marketingAllowed(),
+                preferences: api.preferencesProcessingAllowed(),
+                sale_of_data: api.saleOfDataAllowed(),
+            };
+        },
+        isConsentReady: () => !!getApi(),
     };
 };