@ninetailed/experience.js 7.11.0 → 7.12.0-beta.0

package/index.esm.js

@@ -54,6 +54,7 @@ const ANONYMOUS_ID = '__nt_anonymous_id__';
 const DEBUG_FLAG = '__nt_debug__';
 const PROFILE_FALLBACK_CACHE = '__nt_profile__';
 const EXPERIENCES_FALLBACK_CACHE = '__nt_experiences__';
+const CHANGES_FALLBACK_CACHE = '__nt_changes__';
 const PROFILE_CHANGE = 'profile-change';
 const PROFILE_RESET = 'profile-reset';
 const CONSENT = '__nt-consent__';
@@ -110,14 +111,12 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
         instance.dispatch({
           type: PROFILE_RESET
         });
-        instance.storage.removeItem(ANONYMOUS_ID);
-        instance.storage.removeItem(PROFILE_FALLBACK_CACHE);
-        instance.storage.removeItem(EXPERIENCES_FALLBACK_CACHE);
+        _this.clearCaches();
         logger.debug('Removed old profile data from localstorage.');
         if (typeof _this.onInitProfileId === 'function') {
           const profileId = await _this.onInitProfileId(undefined);
           if (typeof profileId === 'string') {
-            instance.storage.setItem(ANONYMOUS_ID, profileId);
+            _this.setAnonymousId(profileId);
           }
         }
         await _this.ninetailed.track('nt_reset');
@@ -163,13 +162,13 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
     const legacyAnonymousId = instance.storage.getItem(LEGACY_ANONYMOUS_ID);
     if (legacyAnonymousId) {
       logger.debug('Found legacy anonymousId, migrating to new one.', legacyAnonymousId);
-      instance.storage.setItem(ANONYMOUS_ID, legacyAnonymousId);
+      this.setAnonymousId(legacyAnonymousId);
       instance.storage.removeItem(LEGACY_ANONYMOUS_ID);
     }
     if (typeof this.onInitProfileId === 'function') {
-      const profileId = await this.onInitProfileId(instance.storage.getItem(ANONYMOUS_ID));
+      const profileId = await this.onInitProfileId(this.getAnonymousId());
       if (typeof profileId === 'string') {
-        instance.storage.setItem(ANONYMOUS_ID, profileId);
+        this.setAnonymousId(profileId);
       }
     }
     logger.debug('Ninetailed Core plugin initialized.');
@@ -267,6 +266,61 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
     }
     return this._instance;
   }
+  getAnonymousId() {
+    var _ref;
+    return (_ref = this.instance.storage.getItem(ANONYMOUS_ID)) != null ? _ref : undefined;
+  }
+  setAnonymousId(id) {
+    this.instance.storage.setItem(ANONYMOUS_ID, id);
+  }
+  clearAnonymousId() {
+    this.instance.storage.removeItem(ANONYMOUS_ID);
+  }
+  setFallbackProfile(profile) {
+    this.instance.storage.setItem(PROFILE_FALLBACK_CACHE, profile);
+  }
+  getFallbackProfile() {
+    var _ref2;
+    return (_ref2 = this.instance.storage.getItem(PROFILE_FALLBACK_CACHE)) != null ? _ref2 : undefined;
+  }
+  clearFallbackProfile() {
+    this.instance.storage.removeItem(PROFILE_FALLBACK_CACHE);
+  }
+  setFallbackExperiences(experiences) {
+    this.instance.storage.setItem(EXPERIENCES_FALLBACK_CACHE, experiences);
+  }
+  getFallbackExperiences() {
+    return this.instance.storage.getItem(EXPERIENCES_FALLBACK_CACHE) || [];
+  }
+  clearFallbackExperiences() {
+    this.instance.storage.removeItem(EXPERIENCES_FALLBACK_CACHE);
+  }
+  setFallbackChanges(changes) {
+    this.instance.storage.setItem(CHANGES_FALLBACK_CACHE, changes);
+  }
+  getFallbackChanges() {
+    return this.instance.storage.getItem(CHANGES_FALLBACK_CACHE) || [];
+  }
+  clearFallbackChanges() {
+    this.instance.storage.removeItem(CHANGES_FALLBACK_CACHE);
+  }
+  clearCaches() {
+    this.clearAnonymousId();
+    this.clearFallbackProfile();
+    this.clearFallbackExperiences();
+    this.clearFallbackChanges();
+  }
+  populateCaches({
+    experiences,
+    profile,
+    anonymousId,
+    changes
+  }) {
+    this.setAnonymousId(anonymousId);
+    this.setFallbackProfile(profile);
+    this.setFallbackExperiences(experiences);
+    this.setFallbackChanges(changes);
+  }
   async _flush() {
     const events = Object.assign([], this.queue);
     logger.info('Start flushing events.');
@@ -277,10 +331,11 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
       };
     }
     try {
-      const anonymousId = this.instance.storage.getItem(ANONYMOUS_ID);
+      const anonymousId = this.getAnonymousId();
       const {
         profile,
-        experiences
+        experiences,
+        changes
       } = await this.apiClient.upsertProfile({
         profileId: anonymousId,
         events
@@ -288,15 +343,20 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
         locale: this.locale,
         enabledFeatures: this.enabledFeatures
       });
-      this.instance.storage.setItem(ANONYMOUS_ID, profile.id);
-      this.instance.storage.setItem(PROFILE_FALLBACK_CACHE, profile);
-      this.instance.storage.setItem(EXPERIENCES_FALLBACK_CACHE, experiences);
+      this.populateCaches({
+        anonymousId: profile.id,
+        profile,
+        experiences,
+        changes
+      });
       logger.debug('Profile from api: ', profile);
       logger.debug('Experiences from api: ', experiences);
       this.instance.dispatch({
         type: PROFILE_CHANGE,
         profile,
-        experiences
+        experiences,
+        changes,
+        error: undefined
       });
       await delay(20);
       return {
@@ -304,22 +364,26 @@ class NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
       };
     } catch (error) {
       logger.debug('An error occurred during flushing the events: ', error);
-      const fallbackProfile = this.instance.storage.getItem(PROFILE_FALLBACK_CACHE);
-      const fallbackExperiences = this.instance.storage.getItem(EXPERIENCES_FALLBACK_CACHE) || [];
+      const fallbackProfile = this.getFallbackProfile();
+      const fallbackExperiences = this.getFallbackExperiences();
+      const fallbackChanges = this.getFallbackChanges();
       if (fallbackProfile) {
         logger.debug('Found a fallback profile - will use this.');
         this.instance.dispatch({
           type: PROFILE_CHANGE,
           profile: fallbackProfile,
-          experiences: fallbackExperiences
+          experiences: fallbackExperiences,
+          changes: fallbackChanges,
+          error: undefined
         });
       } else {
         logger.debug('No fallback profile found - setting profile to null.');
         this.instance.dispatch({
           type: PROFILE_CHANGE,
           profile: null,
+          changes: fallbackChanges,
           experiences: fallbackExperiences,
-          error
+          error: error
         });
       }
       return {
@@ -400,19 +464,17 @@ const isInterestedInHiddenPage = arg => {
 };
 
 const decodeExperienceVariantsMap = encodedExperienceVariantsMap => {
-  return encodedExperienceVariantsMap.split(',').map(experienceIdWithVariant => {
-    const [experienceId, _variantIndex] = experienceIdWithVariant.split('=');
-    const variantIndex = parseInt(_variantIndex);
+  const experientVariantsAssignments = encodedExperienceVariantsMap.split(',');
+  const experienceVariantsMap = {};
+  for (const experienceVariantAssignment of experientVariantsAssignments) {
+    const [experienceId, variantIndexString] = experienceVariantAssignment.split('=');
+    const variantIndex = parseInt(variantIndexString);
     if (!experienceId || !variantIndex) {
-      return null;
+      continue;
     }
-    return {
-      experienceId,
-      variantIndex
-    };
-  }).filter(x => !!x).reduce((acc, curr) => Object.assign({}, acc, {
-    [curr.experienceId]: curr.variantIndex
-  }), {});
+    experienceVariantsMap[experienceId] = variantIndex;
+  }
+  return experienceVariantsMap;
 };
 
 class OnChangeEmitter {
@@ -474,6 +536,28 @@ const createPassThroughMiddleware = () => {
     };
   };
 };
+function createExperienceSelectionMiddleware({
+  plugins,
+  experiences,
+  baseline,
+  profile
+}) {
+  if (profile === null) {
+    return createPassThroughMiddleware();
+  }
+  const pluginsWithMiddleware = selectPluginsHavingExperienceSelectionMiddleware(plugins);
+  const middlewareFunctions = [];
+  for (const plugin of pluginsWithMiddleware) {
+    const middleware = plugin.getExperienceSelectionMiddleware({
+      experiences,
+      baseline
+    });
+    if (middleware !== undefined) {
+      middlewareFunctions.push(middleware);
+    }
+  }
+  return pipe(...middlewareFunctions);
+}
 const makeExperienceSelectMiddleware = ({
   plugins,
   onChange,
@@ -483,18 +567,12 @@ const makeExperienceSelectMiddleware = ({
 }) => {
   let removeChangeListeners = [];
   const pluginsHavingChangeEmitters = selectPluginsHavingOnChangeEmitter(plugins);
-  const prepareMiddleware = () => {
-    if (profile === null) {
-      return createPassThroughMiddleware();
-    }
-    const pluginsWithMiddleware = selectPluginsHavingExperienceSelectionMiddleware(plugins);
-    const middlewareFunctions = pluginsWithMiddleware.map(plugin => plugin.getExperienceSelectionMiddleware({
-      experiences,
-      baseline
-    })).filter(result => typeof result !== 'undefined');
-    return pipe(...middlewareFunctions);
-  };
-  const middleware = prepareMiddleware();
+  const middleware = createExperienceSelectionMiddleware({
+    plugins,
+    experiences,
+    baseline,
+    profile
+  });
   const addListeners = () => {
     removeChangeListeners = pluginsHavingChangeEmitters.map(plugin => {
       const listener = () => {
@@ -503,8 +581,13 @@ const makeExperienceSelectMiddleware = ({
       return plugin.onChangeEmitter.addListener(listener);
     });
   };
+
+  // WARNING: This specific implementation using forEach is required.
+  // DO NOT replace with for...of or other loop constructs as they will break functionality.
+  // The exact reason is uncertain but appears related to the transplier.
+  // TODO: Come back and find out why this is the case, maybe a version bump is in order.
   const removeListeners = () => {
-    removeChangeListeners.forEach(listener => listener());
+    removeChangeListeners.forEach(removeListener => removeListener());
   };
   return {
     addListeners,
@@ -518,44 +601,36 @@ class EventBuilder {
     this.buildRequestContext = void 0;
     this.buildRequestContext = buildRequestContext || buildClientNinetailedRequestContext;
   }
-  page(properties, data) {
-    return buildPageEvent(Object.assign({
+  buildEventBase(data) {
+    return Object.assign({
       messageId: (data == null ? void 0 : data.messageId) || v4()
     }, data, {
       timestamp: Date.now(),
-      properties: properties || {},
       ctx: this.buildRequestContext()
+    });
+  }
+  page(properties, data) {
+    return buildPageEvent(Object.assign({}, this.buildEventBase(data), {
+      properties: properties || {}
     }));
   }
   track(event, properties, data) {
-    return buildTrackEvent(Object.assign({
-      messageId: (data == null ? void 0 : data.messageId) || v4(),
-      timestamp: Date.now()
-    }, data, {
+    return buildTrackEvent(Object.assign({}, this.buildEventBase(data), {
       event,
-      properties: properties || {},
-      ctx: this.buildRequestContext()
+      properties: properties || {}
     }));
   }
   identify(userId, traits, data) {
-    return buildIdentifyEvent(Object.assign({
-      messageId: (data == null ? void 0 : data.messageId) || v4(),
-      timestamp: Date.now()
-    }, data, {
+    return buildIdentifyEvent(Object.assign({}, this.buildEventBase(data), {
       traits: traits || {},
-      userId: userId || '',
-      ctx: this.buildRequestContext()
+      userId: userId || ''
     }));
   }
   component(componentId, experienceId, variantIndex, data) {
-    return buildComponentViewEvent(Object.assign({
-      messageId: (data == null ? void 0 : data.messageId) || v4(),
-      timestamp: Date.now()
-    }, data, {
+    return buildComponentViewEvent(Object.assign({}, this.buildEventBase(data), {
       componentId,
       experienceId: experienceId || '',
-      variantIndex: variantIndex || 0,
-      ctx: this.buildRequestContext()
+      variantIndex: variantIndex || 0
     }));
   }
 }
@@ -628,11 +703,7 @@ class Ninetailed {
         await _this.instance.page(data, _this.buildOptions(options));
         return _this.ninetailedCorePlugin.flush();
       } catch (error) {
-        logger.error(error);
-        if (error instanceof RangeError) {
-          throw new Error(`[Validation Error] "page" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
-        }
-        throw error;
+        return _this.handleMethodError(error, 'page');
       }
     };
     this.track = async function (event, properties, options) {
@@ -645,11 +716,7 @@ class Ninetailed {
         await _this.instance.track(event.toString(), result.data, _this.buildOptions(options));
         return _this.ninetailedCorePlugin.flush();
       } catch (error) {
-        logger.error(error);
-        if (error instanceof RangeError) {
-          throw new Error(`[Validation Error] "track" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
-        }
-        throw error;
+        _this.handleMethodError(error, 'track');
       }
     };
     this.identify = async function (uid, traits, options) {
@@ -662,11 +729,7 @@ class Ninetailed {
         await _this.instance.identify(uid && uid.toString() !== '' ? uid.toString() : EMPTY_MERGE_ID, result.data, _this.buildOptions(options));
         return _this.ninetailedCorePlugin.flush();
       } catch (error) {
-        logger.error(error);
-        if (error instanceof RangeError) {
-          throw new Error(`[Validation Error] "identify" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
-        }
-        throw error;
+        _this.handleMethodError(error, 'identify');
       }
     };
     this.batch = async function (events) {
@@ -695,11 +758,7 @@ class Ninetailed {
         await Promise.all(promises);
         return _this.ninetailedCorePlugin.flush();
       } catch (error) {
-        logger.error(error);
-        if (error instanceof RangeError) {
-          throw new Error(`[Validation Error] "batch" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
-        }
-        throw error;
+        _this.handleMethodError(error, 'batch');
       }
     };
     this.trackStickyComponentView = async function ({
@@ -717,11 +776,7 @@ class Ninetailed {
         });
         return _this.ninetailedCorePlugin.flush();
       } catch (error) {
-        logger.error(error);
-        if (error instanceof RangeError) {
-          throw new Error(`[Validation Error] "trackStickyComponentView" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
-        }
-        throw error;
+        _this.handleMethodError(error, 'trackStickyComponentView');
       }
     };
     /**
@@ -744,33 +799,13 @@ class Ninetailed {
       const {
           element
         } = payload,
-        remaingPayload = _objectWithoutPropertiesLoose(payload, _excluded2);
+        remainingPayload = _objectWithoutPropertiesLoose(payload, _excluded2);
       if (!(element instanceof Element)) {
-        const isObject = typeof element === 'object' && element !== null;
-        const constructorName = isObject ? element.constructor.name : '';
-        const isConstructorNameNotObject = constructorName && constructorName !== 'Object';
-        logger.warn(`ElementSeenObserver.observeElement was called with an invalid element. Expected an Element but got ${typeof element}${isConstructorNameNotObject ? ` of type ${constructorName}` : ''}. This call will be ignored.`);
-      } else {
-        const existingPayloads = this.observedElements.get(element);
-        const delays = this.pluginsWithCustomComponentViewThreshold.map(plugin => plugin.getComponentViewTrackingThreshold());
-        const uniqueDelays = Array.from(new Set([...delays, options == null ? void 0 : options.delay]));
-        if (!existingPayloads) {
-          this.observedElements.set(element, [remaingPayload]);
-        } else {
-          const isPayloadAlreadyObserved = existingPayloads.some(payload => {
-            return JSON.stringify(payload) === JSON.stringify(remaingPayload);
-          });
-          if (isPayloadAlreadyObserved) {
-            return;
-          }
-          this.observedElements.set(element, [...existingPayloads, remaingPayload]);
-        }
-        uniqueDelays.forEach(delay => {
-          this.elementSeenObserver.observe(element, {
-            delay
-          });
-        });
+        this.logInvalidElement(element);
+        return;
       }
+      this.storeElementPayload(element, remainingPayload);
+      this.setupElementObservation(element, options == null ? void 0 : options.delay);
     };
     this.unobserveElement = element => {
       this.observedElements.delete(element);
@@ -817,6 +852,7 @@ class Ninetailed {
           cb(Object.assign({}, this._profileState, {
             status: 'success',
             profile: payload.profile,
+            changes: payload.changes,
             experiences: payload.experiences,
             error: null
           }));
@@ -985,14 +1021,26 @@ class Ninetailed {
         removeMiddlewareChangeListeners();
       };
     };
-    this.onIsInitialized = onIsInitialized => {
-      if (typeof onIsInitialized === 'function') {
+    /**
+     * Registers a callback to be notified when changes occur in the profile state.
+     *
+     * @param cb - Callback function that receives the changes state
+     * @returns Function to unsubscribe from changes updates
+     */
+    this.onChangesChange = cb => {
+      this.notifyChangesCallback(cb, this._profileState);
+      return this.onProfileChange(profileState => {
+        this.notifyChangesCallback(cb, profileState);
+      });
+    };
+    this.onIsInitialized = onIsInitializedCallback => {
+      if (typeof onIsInitializedCallback === 'function') {
         if (this.isInitialized) {
-          onIsInitialized();
+          onIsInitializedCallback();
         } else {
           const detachOnReadyListener = this.instance.on('ready', () => {
             this.isInitialized = true;
-            onIsInitialized();
+            onIsInitializedCallback();
             detachOnReadyListener();
           });
         }
@@ -1072,6 +1120,7 @@ class Ninetailed {
       status: 'loading',
       profile: null,
       experiences: null,
+      changes: null,
       error: null,
       from: 'api'
     };
@@ -1119,6 +1168,72 @@ class Ninetailed {
   get pluginsWithCustomComponentViewThreshold() {
     return [this.ninetailedCorePlugin, ...this.plugins].filter(plugin => hasComponentViewTrackingThreshold(plugin));
   }
+  logInvalidElement(element) {
+    const isObject = typeof element === 'object' && element !== null;
+    const constructorName = isObject ? element.constructor.name : '';
+    const isConstructorNameNotObject = constructorName && constructorName !== 'Object';
+    logger.warn(`ElementSeenObserver.observeElement was called with an invalid element. Expected an Element but got ${typeof element}${isConstructorNameNotObject ? ` of type ${constructorName}` : ''}. This call will be ignored.`);
+  }
+  storeElementPayload(element, payload) {
+    const existingPayloads = this.observedElements.get(element) || [];
+
+    // Check if the payload is already being observed for this element
+    const isPayloadAlreadyObserved = existingPayloads.some(existingPayload => JSON.stringify(existingPayload) === JSON.stringify(payload));
+    if (isPayloadAlreadyObserved) {
+      return;
+    }
+
+    // Store the new or updated payloads
+    this.observedElements.set(element, [...existingPayloads, payload]);
+  }
+  setupElementObservation(element, delay) {
+    // Get all relevant delays from plugins and the custom delay
+    const pluginDelays = this.pluginsWithCustomComponentViewThreshold.map(plugin => plugin.getComponentViewTrackingThreshold());
+
+    // Ensure we only observe each delay once
+    const uniqueDelays = Array.from(new Set([...pluginDelays, delay]));
+
+    // Set up observation for each delay
+    uniqueDelays.forEach(delay => {
+      this.elementSeenObserver.observe(element, {
+        delay
+      });
+    });
+  }
+  /**
+   * Helper method to extract changes state from profile state and notify callback
+   * @private
+   */
+  notifyChangesCallback(cb, profileState) {
+    if (profileState.status === 'loading') {
+      cb({
+        status: 'loading',
+        changes: null,
+        error: null
+      });
+    } else if (profileState.status === 'error') {
+      cb({
+        status: 'error',
+        changes: null,
+        error: profileState.error
+      });
+    } else {
+      cb({
+        status: 'success',
+        changes: profileState.changes,
+        error: null
+      });
+    }
+  }
+
+  // Always throws, never returns
+  handleMethodError(error, method) {
+    logger.error(error);
+    if (error instanceof RangeError) {
+      throw new Error(`[Validation Error] "${method}" was called with invalid params. Could not validate due to "RangeError: Maximum call stack size exceeded". This can be caused by passing a cyclic data structure as a parameter. Refrain from passing a cyclic data structure or sanitize it beforehand.`);
+    }
+    throw error;
+  }
   get profileState() {
     return this._profileState;
   }
@@ -1228,4 +1343,4 @@ const selectVariant = (baseline, variants, {
   };
 };
 
-export { ANONYMOUS_ID, COMPONENT, COMPONENT_START, CONSENT, DEBUG_FLAG, EMPTY_MERGE_ID, EXPERIENCES_FALLBACK_CACHE, EventBuilder, HAS_SEEN_STICKY_COMPONENT, LEGACY_ANONYMOUS_ID, Ninetailed, NinetailedCorePlugin, OnChangeEmitter, PAGE_HIDDEN, PLUGIN_NAME, PROFILE_CHANGE, PROFILE_FALLBACK_CACHE, PROFILE_RESET, SET_ENABLED_FEATURES, buildClientNinetailedRequestContext, decodeExperienceVariantsMap, makeExperienceSelectMiddleware, selectPluginsHavingExperienceSelectionMiddleware, selectPluginsHavingOnChangeEmitter, selectVariant };
+export { ANONYMOUS_ID, CHANGES_FALLBACK_CACHE, COMPONENT, COMPONENT_START, CONSENT, DEBUG_FLAG, EMPTY_MERGE_ID, EXPERIENCES_FALLBACK_CACHE, EventBuilder, HAS_SEEN_STICKY_COMPONENT, LEGACY_ANONYMOUS_ID, Ninetailed, NinetailedCorePlugin, OnChangeEmitter, PAGE_HIDDEN, PLUGIN_NAME, PROFILE_CHANGE, PROFILE_FALLBACK_CACHE, PROFILE_RESET, SET_ENABLED_FEATURES, buildClientNinetailedRequestContext, decodeExperienceVariantsMap, makeExperienceSelectMiddleware, selectPluginsHavingExperienceSelectionMiddleware, selectPluginsHavingOnChangeEmitter, selectVariant };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninetailed/experience.js",
-  "version": "7.11.0",
+  "version": "7.12.0-beta.0",
   "description": "Ninetailed SDK for javascript",
   "license": "MIT",
   "repository": {
@@ -9,8 +9,8 @@
     "directory": "packages/sdks/javascript"
   },
   "dependencies": {
-    "@ninetailed/experience.js-plugin-analytics": "7.11.0",
-    "@ninetailed/experience.js-shared": "7.11.0",
+    "@ninetailed/experience.js-plugin-analytics": "7.12.0-beta.0",
+    "@ninetailed/experience.js-shared": "7.12.0-beta.0",
     "analytics": "0.8.1",
     "uuid": "9.0.0"
   },

package/src/lib/Ninetailed.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="analytics" />
 import { Locale, Traits, OnLogHandler, OnErrorHandler, Logger, PageviewProperties, Properties, NinetailedApiClient, NinetailedApiClientOptions, NinetailedRequestContext, Reference, Event } from '@ninetailed/experience.js-shared';
 import { OnInitProfileId } from './NinetailedCorePlugin';
-import { EventFunctionOptions, NinetailedInstance, OnIsInitializedCallback, OnProfileChangeCallback, ProfileState, TrackHasSeenComponent, TrackComponentView } from './types';
+import { EventFunctionOptions, NinetailedInstance, OnIsInitializedCallback, OnProfileChangeCallback, ProfileState, TrackHasSeenComponent, TrackComponentView, OnChangesChangeCallback } from './types';
 import { ObserveOptions } from './ElementSeenObserver';
 import { OnSelectVariantArgs, OnSelectVariantCallback } from './types/OnSelectVariant';
 import { ElementSeenPayload, NinetailedPlugin } from '@ninetailed/experience.js-plugin-analytics';
@@ -71,13 +71,29 @@ export declare class Ninetailed implements NinetailedInstance {
     trackComponentView: TrackComponentView;
     private get pluginsWithCustomComponentViewThreshold();
     observeElement: (payload: ElementSeenPayload, options?: ObserveOptions) => void;
+    private logInvalidElement;
+    private storeElementPayload;
+    private setupElementObservation;
     unobserveElement: (element: Element) => void;
     private onElementSeen;
     reset: () => Promise<void>;
     debug: (enabled: boolean) => Promise<void>;
     onProfileChange: (cb: OnProfileChangeCallback) => import("analytics").DetachListeners;
     onSelectVariant: <Baseline extends Reference, Variant extends Reference>({ baseline, experiences }: OnSelectVariantArgs<Baseline, Variant>, cb: OnSelectVariantCallback<Baseline, Variant>) => () => void;
-    onIsInitialized: (onIsInitialized: OnIsInitializedCallback) => void;
+    /**
+     * Registers a callback to be notified when changes occur in the profile state.
+     *
+     * @param cb - Callback function that receives the changes state
+     * @returns Function to unsubscribe from changes updates
+     */
+    onChangesChange: (cb: OnChangesChangeCallback) => import("analytics").DetachListeners;
+    /**
+     * Helper method to extract changes state from profile state and notify callback
+     * @private
+     */
+    private notifyChangesCallback;
+    private handleMethodError;
+    onIsInitialized: (onIsInitializedCallback: OnIsInitializedCallback) => void;
     private waitUntilInitialized;
     get profileState(): ProfileState;
     private buildOptions;

package/src/lib/NinetailedCorePlugin/NinetailedCorePlugin.d.ts

@@ -1,9 +1,10 @@
-import { AnalyticsInstance } from 'analytics';
+import { AnalyticsInstance, DetachListeners } from 'analytics';
 import { Locale, NinetailedApiClient, NinetailedRequestContext } from '@ninetailed/experience.js-shared';
 import { NinetailedAnalyticsPlugin, SanitizedElementSeenPayload } from '@ninetailed/experience.js-plugin-analytics';
 import { SET_ENABLED_FEATURES } from './constants';
 import { NinetailedInstance, FlushResult } from '../types';
 import { HAS_SEEN_STICKY_COMPONENT } from '../constants';
+import { DispatchAction, ActionPayloadMap } from './actions';
 export type OnInitProfileId = (profileId?: string) => Promise<string | undefined> | string | undefined;
 type AnalyticsPluginNinetailedConfig = {
     apiClient: NinetailedApiClient;
@@ -16,14 +17,15 @@ type AnalyticsPluginNinetailedConfig = {
 export declare const PLUGIN_NAME = "ninetailed:core";
 type EventFn = {
     payload: any;
-    instance: InternalAnalyticsInstance;
+    instance: EventHandlerAnalyticsInstance;
 };
 type AbortableFnParams = {
     abort: () => void;
     payload: unknown;
 };
-type InternalAnalyticsInstance = AnalyticsInstance & {
-    dispatch: (action: any) => void;
+export type EventHandlerAnalyticsInstance = Omit<AnalyticsInstance, 'on' | 'dispatch'> & {
+    dispatch: (action: DispatchAction) => Promise<void>;
+    on<T extends DispatchAction['type']>(action: T, handler: (data: ActionPayloadMap[T]) => void): DetachListeners;
 };
 export interface NinetailedCorePlugin extends NinetailedAnalyticsPlugin {
     flush: (args: void) => Promise<FlushResult>;
@@ -40,7 +42,7 @@ export declare class NinetailedCorePlugin extends NinetailedAnalyticsPlugin impl
     private readonly ninetailed;
     constructor({ apiClient, locale, ninetailed, onInitProfileId, buildClientContext, }: AnalyticsPluginNinetailedConfig);
     initialize({ instance, }: {
-        instance: InternalAnalyticsInstance;
+        instance: EventHandlerAnalyticsInstance;
     }): Promise<void>;
     [SET_ENABLED_FEATURES]: ({ payload }: EventFn) => Promise<void>;
     pageStart(params: AbortableFnParams): unknown;
@@ -65,6 +67,20 @@ export declare class NinetailedCorePlugin extends NinetailedAnalyticsPlugin impl
     private static abortNonClientEvents;
     private get instance();
     flush: (args: void) => Promise<FlushResult>;
+    private getAnonymousId;
+    private setAnonymousId;
+    private clearAnonymousId;
+    private setFallbackProfile;
+    private getFallbackProfile;
+    private clearFallbackProfile;
+    private setFallbackExperiences;
+    private getFallbackExperiences;
+    private clearFallbackExperiences;
+    private setFallbackChanges;
+    private getFallbackChanges;
+    private clearFallbackChanges;
+    private clearCaches;
+    private populateCaches;
     private _flush;
 }
 export {};