@reservamos/browser-analytics 1.1.8-alpha.0 → 1.1.8-alpha.2

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,23 +102,10 @@ function identify(
   properties: Record<string, unknown>,
   report?: IdentifyReporter,
 ): void {
+  trackingLifecycle.identify(userId);
   mixpanel.identify(userId);
   if (!updateCachedDistinctId(userId)) report?.('cache', 'unavailable');
-  if (!report) {
-    mixpanel.people.set(properties);
-    return;
-  }
-  const observer = observeIdentifyResult('people', report);
-  try {
-    mixpanel.people.set(properties, (response) => {
-      const status = typeof response === 'number' ? response : response?.status;
-      observer.complete(
-        status === 1 ? undefined : status === 0 ? 'failed' : 'unconfirmed',
-      );
-    });
-  } catch {
-    observer.complete('failed');
-  }
+  writePeopleProperties(properties, report);
 }
 
 /**
@@ -95,12 +128,36 @@ function attachProperty(key: string, value: unknown): void {
  * Sets people properties for the current Mixpanel user without changing their distinct ID.
  * @param {Record<string, unknown>} properties - Profile properties to set on the current user.
  */
-function setPeopleProperties(properties: Record<string, unknown>): void {
+function setPeopleProperties(
+  properties: Record<string, unknown>,
+  report?: IdentifyReporter,
+): void {
   if (!isReady()) {
     return;
   }
 
-  mixpanel.people.set(properties);
+  writePeopleProperties(properties, report);
+}
+
+function writePeopleProperties(
+  properties: Record<string, unknown>,
+  report?: IdentifyReporter,
+): void {
+  if (!report) {
+    mixpanel.people.set(properties);
+    return;
+  }
+  const observer = observeIdentifyResult('people', report);
+  try {
+    mixpanel.people.set(properties, (response) => {
+      const status = typeof response === 'number' ? response : response?.status;
+      observer.complete(
+        status === 1 ? undefined : status === 0 ? 'failed' : 'unconfirmed',
+      );
+    });
+  } catch {
+    observer.complete('failed');
+  }
 }
 
 /**
@@ -108,7 +165,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.
@@ -126,13 +183,12 @@ 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 distinctId = mixpanel?.get_distinct_id?.();
+  const distinctId = isReady() ? mixpanel.get_distinct_id() : null;
   if (distinctId) {
     updateCachedDistinctId(distinctId);
     return distinctId;
@@ -148,6 +204,7 @@ export const getMixpanelDistinctId = (): string | 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): boolean {
   try {
@@ -160,7 +217,9 @@ function updateCachedDistinctId(distinctId: string): boolean {
 
 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.

package/src/track.readiness.test.ts

@@ -0,0 +1,131 @@
+import type { Mock } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import mixpanelService from '@/services/mixpanel';
+import { trackEvent } from './track';
+
+const transport = vi.hoisted(() => ({
+  loaded: undefined as (() => void) | undefined,
+  register: vi.fn(),
+  track: vi.fn(),
+}));
+
+// Keep the actual Mixpanel service and its readiness notification. Only the
+// browser client and unrelated enrichment are replaced at their boundaries.
+vi.mock('mixpanel-browser', () => ({
+  default: {
+    init: vi.fn((_token: string, config: { loaded: () => void }) => {
+      transport.loaded = config.loaded;
+    }),
+    register: transport.register,
+    track: transport.track,
+    get_distinct_id: vi.fn().mockReturnValue('distinct-123'),
+  },
+}));
+vi.mock('@/services/botDetectionRelay', () => ({
+  default: { isEnabledFor: vi.fn().mockReturnValue(false) },
+}));
+vi.mock('@/services/fingerprint', () => ({
+  default: {
+    getFingerprint: vi.fn().mockResolvedValue(''),
+    getCachedFingerprint: vi.fn().mockReturnValue(null),
+  },
+}));
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    getCoordinates: vi.fn().mockReturnValue(null),
+    getGeolocationSource: vi.fn().mockReturnValue(null),
+  },
+}));
+vi.mock('@/services/validator', () => ({
+  default: { parseEventProps: vi.fn() },
+}));
+
+describe('tracking with the actual Mixpanel readiness service', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    Reflect.deleteProperty(window, 'mixpanel');
+    transport.loaded = undefined;
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    Reflect.deleteProperty(window, 'mixpanel');
+    localStorage.clear();
+  });
+
+  function observeUnsubscriptions() {
+    const subscribe = mixpanelService.onReady;
+    const unsubscribers: Mock<[], void>[] = [];
+    vi.spyOn(mixpanelService, 'onReady').mockImplementation((callback) => {
+      const unsubscribe = vi.fn(subscribe(callback));
+      unsubscribers.push(unsubscribe);
+      return unsubscribe;
+    });
+    return unsubscribers;
+  }
+
+  it('releases early Search on loaded before later View Results without Tracker Ready', async () => {
+    const unsubscribers = observeUnsubscriptions();
+    const remove = vi.spyOn(window, 'removeEventListener');
+    const dispatch = vi.spyOn(window, 'dispatchEvent');
+    const earlySearch = trackEvent('Search', { source: 'early' });
+    const initialization = mixpanelService.init('test-token');
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(transport.track).not.toHaveBeenCalled();
+
+    transport.loaded?.();
+    await initialization;
+    await earlySearch;
+    await vi.advanceTimersByTimeAsync(0);
+    expect(
+      vi.mocked(transport.register).mock.invocationCallOrder[0],
+    ).toBeLessThan(vi.mocked(transport.track).mock.invocationCallOrder[0]);
+    expect(transport.track).toHaveBeenCalledWith(
+      'Search',
+      expect.objectContaining({ source: 'early' }),
+    );
+    expect(unsubscribers[0]).toHaveBeenCalledOnce();
+    expect(remove).toHaveBeenCalledWith('Tracker Ready', expect.any(Function));
+    expect(vi.getTimerCount()).toBe(0);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await trackEvent('View Results', { source: 'later' });
+    expect(vi.mocked(transport.track).mock.calls.map(([name]) => name)).toEqual(
+      ['Search', 'View Results'],
+    );
+    expect(
+      dispatch.mock.calls.some(([event]) => event.type === 'Tracker Ready'),
+    ).toBe(false);
+    transport.loaded?.();
+    expect(transport.track).toHaveBeenCalledTimes(2);
+    expect(unsubscribers[0]).toHaveBeenCalledOnce();
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribes on expiry and does not replay on late Mixpanel loaded', async () => {
+    const unsubscribers = observeUnsubscriptions();
+    const initialization = mixpanelService.init('test-token');
+    const pending = trackEvent('Search', { secret: 'private-payload' });
+    await vi.advanceTimersByTimeAsync(60000);
+    await pending;
+    expect(unsubscribers[0]).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+    expect(console.error).toHaveBeenCalledWith('Tracking recovery diagnostic', {
+      eventName: 'Search',
+      stage: 'readiness',
+      reason: 'timeout',
+    });
+
+    transport.loaded?.();
+    await initialization;
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await Promise.resolve();
+    expect(transport.track).not.toHaveBeenCalled();
+    expect(unsubscribers[0]).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});