@reservamos/browser-analytics 1.1.7 → 1.1.8-alpha.1

package/src/services/fingerprint.test.ts

@@ -65,6 +65,24 @@ describe('fingerprintService', () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([null, 'cached-visitor'])(
+    'reads the default cache before fingerprint configuration exists: %s',
+    (visitorId) => {
+      Reflect.deleteProperty(window, 'fingerprintConfig');
+      if (visitorId) {
+        localStorage.setItem(
+          'default_fingerprint_cache',
+          JSON.stringify({
+            fingerprint: visitorId,
+            expiresAt: Date.now() + 60_000,
+          }),
+        );
+      }
+      expect(fingerprintService.getCachedFingerprint()).toBe(visitorId);
+      expect(getVisitorDataMock).not.toHaveBeenCalled();
+    },
+  );
+
   it('omits unavailable Visitor Found metadata without blocking identification', async () => {
     getVisitorDataMock.mockResolvedValue({
       ...visitorData,
@@ -77,6 +95,24 @@ describe('fingerprintService', () => {
     expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
   });
 
+  it('does not announce readiness when an invalidated agent finishes loading late', async () => {
+    let finish!: () => void;
+    initMock.mockReturnValue(
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+    );
+    const notify = vi.fn();
+    const stop = fingerprintService.onReady(notify);
+    const pending = fingerprintService.initFingerprint('old-key');
+    fingerprintService.invalidate();
+    finish();
+    await pending;
+    expect(fingerprintService.isFingerprintReady()).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+    stop();
+  });
+
   it('suppresses identify-specific cache and profile effects after its scope closes', async () => {
     let finish: (value: typeof visitorData) => void = () => undefined;
     getVisitorDataMock.mockReturnValue(

package/src/services/fingerprint.ts

@@ -5,6 +5,7 @@ import {
   FpjsClient,
 } from '@fingerprintjs/fingerprintjs-pro-spa';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 
 declare global {
   interface Window {
@@ -28,6 +29,22 @@ const PROXY_QUERY_PARAM =
  * "FPJSAgent hasn't loaded yet" until init completes.
  */
 let fingerprintAgentReady = false;
+let initialization = 0;
+const readinessSubscribers = new Set<() => void>();
+
+/** Notifies deferred observations only when the actual provider agent has loaded. */
+function onReady(notify: () => void): () => void {
+  readinessSubscribers.add(notify);
+  return () => {
+    readinessSubscribers.delete(notify);
+  };
+}
+
+/** Prevents a previous configuration or late agent load from serving a new init. */
+function invalidate(): void {
+  initialization++;
+  fingerprintAgentReady = false;
+}
 
 /**
  * Calculates the expiration date based on the cache time.
@@ -51,9 +68,8 @@ const getCachedFingerprint = (): string | null => {
 };
 
 function readCachedFingerprint(context?: IdentifyStageContext): string | null {
-  const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig;
-
   try {
+    const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig ?? {};
     const cachedData = JSON.parse(localStorage.getItem(cacheName) || 'null');
     if (cachedData && cachedData.expiresAt > Date.now()) {
       return cachedData.fingerprint;
@@ -117,7 +133,8 @@ async function initFingerprint(
     customScriptEndpointArray.unshift(buildProxyUrl(proxyUrl));
   }
 
-  fingerprintAgentReady = false;
+  invalidate();
+  const attempt = initialization;
   window.fingerprintConfig = {};
   const client = new FpjsClient({
     loadOptions: {
@@ -130,11 +147,12 @@ async function initFingerprint(
 
   try {
     await client.init();
-    if (window.fpClient === client) {
+    if (window.fpClient === client && attempt === initialization) {
       fingerprintAgentReady = true;
+      readinessSubscribers.forEach((notify) => notify());
     }
   } catch (error) {
-    if (window.fpClient === client) {
+    if (window.fpClient === client && attempt === initialization) {
       fingerprintAgentReady = false;
     }
     console.error('Error initializing identification service:', error);
@@ -149,8 +167,11 @@ async function initFingerprint(
  * @returns {Promise<string>} A promise that resolves with the fingerprint, or an empty string when unavailable.
  * @throws {Error} Throws an error if retrieval fails after the agent has loaded.
  */
-async function getFingerprint(cacheOnly = false): Promise<string> {
-  return readFingerprint(cacheOnly);
+async function getFingerprint(
+  cacheOnly = false,
+  context?: IdentifyStageContext,
+): Promise<string> {
+  return readFingerprint(cacheOnly, context);
 }
 
 /** Internal identify path with late-effect suppression and sanitized diagnostics. */
@@ -164,20 +185,12 @@ async function readFingerprint(
   cacheOnly: boolean,
   context?: IdentifyStageContext,
 ): Promise<string> {
-  if (!window.fingerprintConfig) {
-    if (cacheOnly) {
-      return '';
-    }
-
-    throw new Error('Fingerprint configuration is not initialized.');
-  }
-
   const cachedFingerprint = readCachedFingerprint(context);
   if (cachedFingerprint) {
     return cachedFingerprint;
   }
 
-  if (cacheOnly || !isFingerprintReady()) {
+  if (cacheOnly || !window.fingerprintConfig || !isFingerprintReady()) {
     return '';
   }
 
@@ -193,8 +206,9 @@ async function readFingerprint(
  */
 async function identifyVisitor(
   ignoreCache = false,
+  context?: IdentifyStageContext,
 ): Promise<FingerprintIdentification> {
-  return requestIdentification(ignoreCache);
+  return requestIdentification(ignoreCache, context);
 }
 
 async function requestIdentification(
@@ -210,9 +224,8 @@ async function requestIdentification(
     if (!context || context.isActive()) {
       try {
         setCachedFingerprint(result.visitorId);
-      } catch (error) {
-        if (!context) throw error;
-        context.report('cache', 'unavailable');
+      } catch {
+        context?.report('cache', 'unavailable');
       }
       if (typeof result.visitorFound === 'boolean') {
         try {
@@ -254,7 +267,12 @@ const fingerprintService = {
   getFingerprint,
   identifyVisitor,
   isFingerprintReady,
+  onReady,
+  invalidate,
   getCachedFingerprint,
 };
 
+// One module-lifetime listener invalidates the old agent before Mixpanel signals readiness.
+trackingLifecycle.onInitialization(invalidate);
+
 export default fingerprintService;

package/src/services/mixpanel.test.ts

@@ -9,6 +9,7 @@ import {
   it,
   vi,
 } from 'vitest';
+import { trackEvent } from '@/track';
 import { version } from '../../package.json';
 import mixpanelService from './mixpanel';
 
@@ -33,6 +34,7 @@ describe('Mixpanel SDK version metadata', () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllGlobals();
     vi.clearAllTimers();
     vi.useRealTimers();
   });
@@ -86,6 +88,21 @@ describe('Mixpanel SDK version metadata', () => {
     });
   });
 
+  it('completes a repeated init with the installed singleton provider without waiting for another loaded callback', async () => {
+    const complete = vi.fn();
+    void mixpanelService.init('test-sdk-version-token').then(complete);
+    await Promise.resolve();
+    expect(complete).toHaveBeenCalledOnce();
+    expect(mixpanelService.isReady()).toBe(true);
+  });
+
+  it('rejects a different project before disturbing the existing provider session', () => {
+    expect(() => mixpanelService.init('different-project')).toThrow(
+      'new page session',
+    );
+    expect(mixpanelService.isReady()).toBe(true);
+  });
+
   it('still sets people properties when the SDK distinct ID cache is blocked', () => {
     vi.spyOn(transport, '_track_or_batch').mockImplementation(
       ({ data }) => data,
@@ -100,6 +117,92 @@ describe('Mixpanel SDK version metadata', () => {
     expect(people).toHaveBeenCalledWith({});
   });
 
+  it.each(['getItem', 'setItem'] as const)(
+    'keeps the live distinct ID when SDK storage %s fails',
+    (method) => {
+      vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('live-id');
+      vi.spyOn(Storage.prototype, method).mockImplementation(() => {
+        throw new DOMException('Blocked', 'SecurityError');
+      });
+      expect(mixpanelService.getMixpanelDistinctId()).toBe('live-id');
+    },
+  );
+
+  it.each(['getItem', 'setItem'] as const)(
+    'submits the original event when SDK storage %s is blocked',
+    async (method) => {
+      const send = vi
+        .spyOn(transport, '_track_or_batch')
+        .mockImplementation(({ data }) => data);
+      mixpanel.identify('storage-test-id');
+      send.mockClear();
+      vi.spyOn(Storage.prototype, method).mockImplementation(() => {
+        throw new DOMException('Blocked', 'SecurityError');
+      });
+      await trackEvent('Storage Failure Test', { source: 'checkout' });
+      expect(send.mock.calls.map(([options]) => options.data)).toContainEqual({
+        event: 'Storage Failure Test',
+        properties: expect.objectContaining({
+          source: 'checkout',
+          distinct_id: 'storage-test-id',
+        }),
+      });
+    },
+  );
+
+  it('returns null when no live distinct ID is available and the cache is blocked', () => {
+    vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('');
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+    expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
+  });
+
+  it('uses the live distinct ID first and null fallback when localStorage is null', () => {
+    vi.stubGlobal('localStorage', null);
+    const liveId = vi
+      .spyOn(mixpanel, 'get_distinct_id')
+      .mockReturnValue('live-id');
+    expect(mixpanelService.getMixpanelDistinctId()).toBe('live-id');
+    liveId.mockReturnValue('');
+    expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
+  });
+
+  it('preserves identify diagnostics and people updates when localStorage is null', () => {
+    vi.useFakeTimers();
+    vi.stubGlobal('localStorage', null);
+    vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+    const people = vi
+      .spyOn(mixpanel.people, 'set')
+      .mockImplementation(() => undefined);
+    const report = vi.fn();
+    mixpanelService.identify('null-storage-user', { plan: 'standard' }, report);
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(people).toHaveBeenCalledWith(
+      { plan: 'standard' },
+      expect.any(Function),
+    );
+  });
+
+  it('uses the cached distinct ID when Mixpanel has no live ID', () => {
+    localStorage.setItem('mp_distinct_id', 'cached-id');
+    vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('');
+    expect(mixpanelService.getMixpanelDistinctId()).toBe('cached-id');
+  });
+
+  it('preserves identify cache diagnostics and people updates on a write failure', () => {
+    vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+    vi.spyOn(mixpanel.people, 'set').mockImplementation(() => undefined);
+    vi.useFakeTimers();
+    const report = vi.fn();
+    mixpanelService.identify('user-id', {}, report);
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(mixpanel.people.set).toHaveBeenCalled();
+  });
+
   it.each([
     1,
     0,

package/src/services/mixpanel.ts

@@ -1,5 +1,6 @@
 import type { IdentifyReporter } from '@/util/identifyAttempt';
 import mixpanel from 'mixpanel-browser';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import { observeIdentifyResult } from '@/util/identifyAttempt';
 import { version } from '../../package.json';
 
@@ -11,6 +12,19 @@ declare global {
 
 const MIXPANEL_DISTINCT_ID_CACHE_KEY = 'mp_distinct_id';
 
+const readinessSubscribers = new Set<() => void>();
+let initializing = false;
+let initialization = 0;
+let initializedConfig: { token: string; proxyUrl?: string } | undefined;
+
+/** Subscribes to internal Mixpanel readiness; callers own unsubscription. */
+function onReady(callback: () => void): () => void {
+  readinessSubscribers.add(callback);
+  return () => {
+    readinessSubscribers.delete(callback);
+  };
+}
+
 /**
  * SDK metadata sent on every Mixpanel event, including native identification events.
  */
@@ -31,12 +45,30 @@ function init(
   debug = false,
   proxyUrl?: string,
 ): Promise<void> {
+  validateConfiguration(mixpanelToken, proxyUrl);
+  const attempt = ++initialization;
+  initializing = true;
+  trackingLifecycle.beginInitialization();
+  // The installed singleton does not call loaded again after its first init.
+  if (initializedConfig && window.mixpanel === mixpanel) {
+    mixpanel.set_config({ debug });
+    initializing = false;
+    readinessSubscribers.forEach((notify) => notify());
+    return Promise.resolve();
+  }
   return new Promise<void>((resolve) => {
     mixpanel.init(mixpanelToken, {
       debug,
       loaded: () => {
+        if (attempt !== initialization) {
+          resolve();
+          return;
+        }
         window.mixpanel = mixpanel;
         mixpanel.register({ ...SDK_SUPER_PROPERTIES });
+        initializedConfig = { token: mixpanelToken, proxyUrl };
+        initializing = false;
+        readinessSubscribers.forEach((notify) => notify());
         resolve();
       },
       ...(proxyUrl && { api_host: proxyUrl }),
@@ -44,6 +76,20 @@ function init(
   });
 }
 
+/** Rejects unsupported singleton reconfiguration before changing the active session. */
+function validateConfiguration(token: string, proxyUrl?: string): void {
+  if (
+    initializedConfig &&
+    window.mixpanel === mixpanel &&
+    (initializedConfig.token !== token ||
+      initializedConfig.proxyUrl !== proxyUrl)
+  ) {
+    throw new Error(
+      'Changing the Mixpanel project or proxy requires a new page session.',
+    );
+  }
+}
+
 /**
  * Identifies a user in Mixpanel and sets their properties.
  * @param {string} userId - The unique identifier for the user.
@@ -56,12 +102,9 @@ function identify(
   properties: Record<string, unknown>,
   report?: IdentifyReporter,
 ): void {
+  trackingLifecycle.identify(userId);
   mixpanel.identify(userId);
-  try {
-    updateCachedDistinctId(userId);
-  } catch {
-    report?.('cache', 'unavailable');
-  }
+  if (!updateCachedDistinctId(userId)) report?.('cache', 'unavailable');
   if (!report) {
     mixpanel.people.set(properties);
     return;
@@ -112,7 +155,7 @@ function setPeopleProperties(properties: Record<string, unknown>): void {
  * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
  */
 function isReady(): boolean {
-  return window.mixpanel !== undefined;
+  return !initializing && window.mixpanel !== undefined;
 }
 /**
  * Tracks an event in Mixpanel with the given name and properties.
@@ -130,37 +173,43 @@ function track(eventName: string, properties: Record<string, unknown>): void {
 }
 
 /**
- * Retrieves the distinct ID from Mixpanel.
- * This function checks if Mixpanel is initialized and returns the current user's
- * distinct ID. If Mixpanel is not initialized, it returns null.
- * @returns {string | null} The distinct ID if available, or null if Mixpanel is not initialized.
+ * Retrieves the live Mixpanel distinct ID first, caching it on a best-effort basis.
+ * Falls back to the SDK cache only when no live ID is available.
+ * @returns {string | null} The live or cached distinct ID, or null when neither is available.
  */
 export const getMixpanelDistinctId = (): string | null => {
-  const cachedId = localStorage.getItem(MIXPANEL_DISTINCT_ID_CACHE_KEY);
-
-  if (mixpanel && mixpanel.get_distinct_id) {
-    const distinctId = mixpanel.get_distinct_id();
-
+  const distinctId = mixpanel?.get_distinct_id?.();
+  if (distinctId) {
     updateCachedDistinctId(distinctId);
-
     return distinctId;
-  } else if (cachedId) {
-    return cachedId;
   }
-  return null;
+
+  try {
+    return localStorage.getItem(MIXPANEL_DISTINCT_ID_CACHE_KEY);
+  } catch {
+    return null;
+  }
 };
 /**
  * Updates the cached Mixpanel distinct ID.
  * Should be called when identifying a user to ensure cache stays in sync.
  * @param {string} distinctId - The distinct ID to cache
+ * @returns {boolean} Whether the cache write succeeded.
  */
-function updateCachedDistinctId(distinctId: string): void {
-  localStorage.setItem(MIXPANEL_DISTINCT_ID_CACHE_KEY, distinctId);
+function updateCachedDistinctId(distinctId: string): boolean {
+  try {
+    localStorage.setItem(MIXPANEL_DISTINCT_ID_CACHE_KEY, distinctId);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 const mixpanelService = {
   init,
+  validateConfiguration,
   isReady,
+  onReady,
   track,
   identify,
   attachProperty,

package/src/services/trackingLifecycle.ts

@@ -0,0 +1,54 @@
+let generation = 0;
+let initialized = false;
+let userId: string | undefined;
+const subscribers = new Set<() => void>();
+const initializationSubscribers = new Set<() => void>();
+
+function invalidate(): void {
+  generation++;
+  subscribers.forEach((notify) => notify());
+}
+
+/** Pre-init events may join the first initialization; later configurations replace them. */
+function beginInitialization(): void {
+  if (initialized) invalidate();
+  initialized = true;
+  userId = undefined;
+  initializationSubscribers.forEach((notify) => notify());
+}
+
+/** Invalidates retained work before the provider changes the active user. */
+function identify(nextUserId: string): void {
+  if (userId !== nextUserId) {
+    userId = nextUserId;
+    invalidate();
+  }
+}
+
+/** Captures a predicate shared by waiting work and late provider effects. */
+function capture(): () => boolean {
+  const captured = generation;
+  return () => captured === generation;
+}
+
+function onChange(notify: () => void): () => void {
+  subscribers.add(notify);
+  return () => {
+    subscribers.delete(notify);
+  };
+}
+
+function onInitialization(notify: () => void): () => void {
+  initializationSubscribers.add(notify);
+  return () => {
+    initializationSubscribers.delete(notify);
+  };
+}
+
+export default {
+  beginInitialization,
+  identify,
+  capture,
+  onChange,
+  onInitialization,
+};

package/src/services/validator/validator.test.ts

@@ -36,6 +36,85 @@ describe('InitConfigSchema', () => {
 });
 
 describe('parseEventProps', () => {
+  const checkout = {
+    'Trips': [
+      {
+        'Departure Arrival': '2026-11-01T12:00:00',
+        'Departure Destination': 'Puebla',
+        'Departure Destination Terminal': 'CAPU',
+        'Departure Line': 'Bus line',
+        'Departure Origin': 'Mexico City',
+        'Departure Origin Terminal': 'TAPO',
+        'Departure Price': 100,
+        'Departure Route': 'Mexico City-Puebla',
+        'Departure Stops': 0,
+        'Departure Time': '2026-11-01T10:00:00',
+        'Departure Transport Type': 'bus',
+        'Departure Transporter': 'Carrier',
+        'Recommended Trip': false,
+      },
+    ],
+    'Passenger Count': 1,
+    'Trip Count': 1,
+    'Total': 100,
+    'product': 'web',
+  };
+
+  describe.each(['Purchase Attempt', 'Payment Attempt'])(
+    '%s stops',
+    (eventName) => {
+      const properties = {
+        ...checkout,
+        ...(eventName === 'Payment Attempt' && {
+          'Payment Type': 'credit_card',
+        }),
+      };
+
+      it.each([0, 1, 2])('accepts %i departure and return stops', (stops) => {
+        expect(() =>
+          validatorService.parseEventProps(eventName, {
+            ...properties,
+            Trips: [
+              {
+                ...checkout.Trips[0],
+                'Departure Stops': stops,
+                'Return Stops': stops,
+              },
+            ],
+          }),
+        ).not.toThrow();
+      });
+
+      it.each(['Departure Stops', 'Return Stops'])(
+        'rejects invalid %s without coercion',
+        (field) => {
+          for (const stops of [0.5, '0', null, NaN]) {
+            expect(() =>
+              validatorService.parseEventProps(eventName, {
+                ...properties,
+                Trips: [{ ...checkout.Trips[0], [field]: stops }],
+              }),
+            ).toThrow();
+          }
+        },
+      );
+
+      it('requires departure stops and keeps return stops optional', () => {
+        const { 'Departure Stops': omitted, ...trip } = checkout.Trips[0];
+        expect(omitted).toBe(0);
+        expect(() =>
+          validatorService.parseEventProps(eventName, {
+            ...properties,
+            Trips: [trip],
+          }),
+        ).toThrow();
+        expect(() =>
+          validatorService.parseEventProps(eventName, properties),
+        ).not.toThrow();
+      });
+    },
+  );
+
   /**
    * This test supposes that unknownEvent is not a known event.
    * And that the customEventSchema does not support objects as values for a field.