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

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);
+  });
+});

package/src/track.recovery.test.ts

@@ -0,0 +1,339 @@
+import coreApi from '@reservamos/js-api-client/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const provider = vi.hoisted(() => ({
+  initMixpanel: vi.fn(),
+  track: vi.fn(),
+  identify: vi.fn(),
+  distinctId: vi.fn(),
+  register: vi.fn(),
+  setPeople: vi.fn(),
+  setConfig: vi.fn(),
+  initFingerprint: vi.fn(),
+  getVisitorData: vi.fn(),
+  client: vi.fn(),
+}));
+vi.mock('mixpanel-browser', () => ({
+  default: {
+    init: provider.initMixpanel,
+    track: provider.track,
+    identify: provider.identify,
+    get_distinct_id: provider.distinctId,
+    register: provider.register,
+    set_config: provider.setConfig,
+    people: { set: provider.setPeople },
+  },
+}));
+vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
+  FingerprintJSPro: {
+    defaultEndpoint: 'endpoint',
+    defaultScriptUrlPattern: 'agent',
+  },
+  FpjsClient: provider.client,
+}));
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    init: async () => undefined,
+    getCoordinates: () => null,
+    getGeolocationSource: () => null,
+  },
+}));
+
+const search = {
+  'Departure': '2026-11-01',
+  'Departure Delta': 1,
+  'Destination': 'Puebla',
+  'Destination Terminal': 'CAPU',
+  'Origin': 'Mexico City',
+  'Origin Terminal': 'TAPO',
+  'Passengers': 1,
+  'Route': 'Mexico City-Puebla',
+  'product': 'web' as const,
+};
+const visitor = {
+  visitorId: 'visitor',
+  requestId: 'request',
+  visitorFound: true,
+  confidence: { score: 0.99 },
+  cacheHit: false,
+};
+
+describe('tracking recovery through real SDK services and validation', () => {
+  let tracking: typeof import('./track');
+  let mixpanel: typeof import('@/services/mixpanel').default;
+  let fingerprint: typeof import('@/services/fingerprint').default;
+  let lifecycle: typeof import('@/services/trackingLifecycle').default;
+  let loaded: () => void;
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    vi.resetAllMocks();
+    localStorage.clear();
+    Reflect.deleteProperty(window, 'mixpanel');
+    Reflect.deleteProperty(window, 'fingerprintConfig');
+    Reflect.deleteProperty(window, 'fpClient');
+    provider.distinctId.mockReturnValue('anonymous');
+    provider.initMixpanel.mockImplementation(
+      (_token, options: { loaded: () => void }) => {
+        loaded = options.loaded;
+      },
+    );
+    provider.initFingerprint.mockResolvedValue(undefined);
+    provider.getVisitorData.mockResolvedValue(visitor);
+    provider.client.mockImplementation(() => ({
+      init: provider.initFingerprint,
+      getVisitorData: provider.getVisitorData,
+    }));
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    vi.spyOn(coreApi.fingerprint, 'sendObservation').mockResolvedValue(true);
+    tracking = await import('./track');
+    mixpanel = (await import('@/services/mixpanel')).default;
+    fingerprint = (await import('@/services/fingerprint')).default;
+    lifecycle = (await import('@/services/trackingLifecycle')).default;
+  });
+  afterEach(async () => {
+    lifecycle.beginInitialization();
+    lifecycle.beginInitialization();
+    await vi.advanceTimersByTimeAsync(0);
+    vi.clearAllTimers();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+  async function readyMixpanel() {
+    const pending = mixpanel.init('test');
+    loaded();
+    await pending;
+  }
+
+  it('recovers at 5.2 seconds with the original snapshot and exactly one provider call', async () => {
+    const properties = { source: 'original', values: [1, 2] };
+    const pending = tracking.trackEvent('Recovery Test', properties);
+    properties.source = 'mutated';
+    properties.values.push(3);
+    await vi.advanceTimersByTimeAsync(5200);
+    await pending;
+    expect(provider.track).not.toHaveBeenCalled();
+    await readyMixpanel();
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.track).toHaveBeenCalledOnce();
+    expect(provider.track).toHaveBeenCalledWith(
+      'Recovery Test',
+      expect.objectContaining({ source: 'original', values: [1, 2] }),
+    );
+    await vi.advanceTimersByTimeAsync(60000);
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('never replays an accepted event after its provider throws and later recovers', async () => {
+    await readyMixpanel();
+    const accepted: string[] = [];
+    provider.track.mockImplementationOnce((event: string) => {
+      accepted.push(event);
+      throw new Error('accepted');
+    });
+    await tracking.trackEvent('Recovery Test', { source: 'checkout' });
+    provider.track.mockImplementation(() => undefined);
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await vi.advanceTimersByTimeAsync(60000);
+    expect(accepted).toEqual(['Recovery Test']);
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('keeps two legitimate identical calls and does not collapse them', async () => {
+    const first = tracking.trackEvent('Recovery Test', { value: 1 });
+    const second = tracking.trackEvent('Recovery Test', { value: 1 });
+    await readyMixpanel();
+    await Promise.all([first, second]);
+    expect(provider.track).toHaveBeenCalledTimes(2);
+  });
+
+  it('preserves allowed undefined array values instead of revalidating them as null', async () => {
+    const pending = tracking.trackEvent('Recovery Test', {
+      values: [undefined],
+      source: 'checkout',
+    });
+    await readyMixpanel();
+    await pending;
+    expect(provider.track).toHaveBeenCalledOnce();
+    expect(provider.track).toHaveBeenCalledWith(
+      'Recovery Test',
+      expect.objectContaining({ source: 'checkout' }),
+    );
+  });
+
+  it('drops expired entries and invalidates waiting work on reinitialization', async () => {
+    const expired = tracking.trackEvent('Expired', {});
+    await vi.advanceTimersByTimeAsync(60000);
+    await expired;
+    void mixpanel.init('first');
+    const stale = tracking.trackEvent('Stale', {});
+    const currentInit = mixpanel.init('second');
+    loaded();
+    await currentInit;
+    await stale;
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.track).not.toHaveBeenCalled();
+  });
+
+  it('sends the original at tracker readiness and observes only after Fingerprint loads', async () => {
+    await readyMixpanel();
+    await tracking.trackEvent('Search', search);
+    expect(provider.track).toHaveBeenCalledOnce();
+    expect(provider.getVisitorData).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(5200);
+    await fingerprint.initFingerprint('test-key');
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.getVisitorData).toHaveBeenCalledOnce();
+    expect(coreApi.fingerprint.sendObservation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        requestId: 'request',
+        distinctId: 'anonymous',
+      }),
+    );
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('suppresses late cache, profile and relay effects after observation expiry', async () => {
+    await readyMixpanel();
+    await fingerprint.initFingerprint('test-key');
+    let finish!: (value: typeof visitor) => void;
+    provider.getVisitorData.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    await tracking.trackEvent('Search', search);
+    await vi.advanceTimersByTimeAsync(10000);
+    finish(visitor);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.setPeople).not.toHaveBeenCalled();
+    expect(fingerprint.getCachedFingerprint()).toBeNull();
+    expect(coreApi.fingerprint.sendObservation).not.toHaveBeenCalled();
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('suppresses old observation effects when identify switches user', async () => {
+    await readyMixpanel();
+    await tracking.trackEvent('Search', search);
+    mixpanel.identify('new-user', {});
+    provider.setPeople.mockClear();
+    await fingerprint.initFingerprint('test-key');
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.getVisitorData).not.toHaveBeenCalled();
+    expect(coreApi.fingerprint.sendObservation).not.toHaveBeenCalled();
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('caps actual concurrent identification requests even after their local deadlines expire', async () => {
+    await readyMixpanel();
+    await fingerprint.initFingerprint('test-key');
+    provider.getVisitorData.mockReturnValue(new Promise(() => undefined));
+    for (let i = 0; i < 5; i++) await tracking.trackEvent('Search', search);
+    expect(provider.getVisitorData).toHaveBeenCalledTimes(3);
+    await vi.advanceTimersByTimeAsync(10000);
+    await tracking.trackEvent('Search', search);
+    expect(provider.getVisitorData).toHaveBeenCalledTimes(3);
+    expect(provider.track).toHaveBeenCalledTimes(6);
+  });
+
+  it('waits for the current init instead of using the old provider or a stale loaded callback', async () => {
+    void mixpanel.init('superseded');
+    const staleLoaded = loaded;
+    const currentInit = mixpanel.init('current');
+    const pending = tracking.trackEvent('Current', {});
+    staleLoaded();
+    window.dispatchEvent(new CustomEvent('Tracker Ready'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.track).not.toHaveBeenCalled();
+    loaded();
+    await currentInit;
+    await pending;
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('invalidates an event whose identity changes before its asynchronous cache read completes', async () => {
+    await readyMixpanel();
+    const pending = tracking.trackEvent('Old User', {});
+    mixpanel.identify('new-user', {});
+    await pending;
+    expect(provider.track).not.toHaveBeenCalled();
+  });
+
+  it('uses the public Search wrapper from Tracker Ready and observes after the real agent loads', async () => {
+    let finish!: () => void;
+    provider.initFingerprint.mockReturnValue(
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+    );
+    const analytics = (await import('./index')).default;
+    const onReady = () => {
+      analytics.track.search(search);
+    };
+    window.addEventListener('Tracker Ready', onReady, { once: true });
+    const initialized = analytics.init({
+      mixpanelToken: 'test',
+      identificationKey: 'test-key',
+    });
+    loaded();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.track).toHaveBeenCalledOnce();
+    expect(provider.getVisitorData).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(5200);
+    await initialized;
+    finish();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(coreApi.fingerprint.sendObservation).toHaveBeenCalledOnce();
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+
+  it('prevents an older public init from replacing the newer Core API and agent configuration', async () => {
+    const configure = vi.spyOn(coreApi, 'setConfig');
+    const analytics = (await import('./index')).default;
+    const oldInit = analytics.init({
+      mixpanelToken: 'test',
+      identificationKey: 'old-agent',
+      appName: 'old-app',
+    });
+    const oldLoaded = loaded;
+    const currentInit = analytics.init({
+      mixpanelToken: 'test',
+      identificationKey: 'new-agent',
+      appName: 'new-app',
+    });
+    loaded();
+    await currentInit;
+    oldLoaded();
+    await oldInit;
+    expect(configure).toHaveBeenCalledOnce();
+    expect(configure.mock.calls[0][0]?.defaultHeaders?.['x-app-name']).toBe(
+      'new-app',
+    );
+    expect(provider.client).toHaveBeenCalledOnce();
+    expect(provider.client).toHaveBeenCalledWith(
+      expect.objectContaining({
+        loadOptions: expect.objectContaining({ apiKey: 'new-agent' }),
+      }),
+    );
+  });
+
+  it('suppresses expired View Results refresh effects without replaying the event', async () => {
+    await readyMixpanel();
+    await fingerprint.initFingerprint('test-key');
+    let finish!: (value: typeof visitor) => void;
+    provider.getVisitorData.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    await tracking.trackEvent('View Results', { ...search, 'Bus count': 10 });
+    await vi.advanceTimersByTimeAsync(10000);
+    finish(visitor);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(provider.setPeople).not.toHaveBeenCalled();
+    expect(fingerprint.getCachedFingerprint()).toBeNull();
+    expect(provider.track).toHaveBeenCalledOnce();
+  });
+});

package/src/track.storage.test.ts

@@ -0,0 +1,127 @@
+import coreApi from '@reservamos/js-api-client/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import { trackEvent } from './track';
+
+const { getVisitorData, init, client } = vi.hoisted(() => ({
+  getVisitorData: vi.fn(),
+  init: vi.fn(),
+  client: vi.fn(),
+}));
+
+// Keep the SDK Fingerprint cache, tracking, validation, and relay real.
+vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
+  FingerprintJSPro: {
+    defaultEndpoint: 'https://fpjscdn.net',
+    defaultScriptUrlPattern: 'https://fpjscdn.net/agent',
+  },
+  FpjsClient: client,
+}));
+
+const search = {
+  'Departure': '2026-11-01',
+  'Departure Delta': 1,
+  'Destination': 'Puebla',
+  'Destination Terminal': 'CAPU',
+  'Origin': 'Mexico City',
+  'Origin Terminal': 'TAPO',
+  'Passengers': 1,
+  'Route': 'Mexico City-Puebla',
+  'product': 'web',
+};
+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': 1,
+      '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('tracking with blocked SDK Fingerprint cache writes', () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    client.mockImplementation(() => ({ init, getVisitorData }));
+    init.mockResolvedValue(undefined);
+    getVisitorData.mockResolvedValue({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidence: { score: 0.99 },
+      cacheHit: false,
+    });
+    await fingerprintService.initFingerprint('test-api-key');
+    vi.spyOn(mixpanelService, 'isReady').mockReturnValue(true);
+    vi.spyOn(mixpanelService, 'getMixpanelDistinctId').mockReturnValue(
+      'live-id',
+    );
+    vi.spyOn(mixpanelService, 'track').mockImplementation(() => undefined);
+    vi.spyOn(mixpanelService, 'setPeopleProperties').mockImplementation(
+      () => undefined,
+    );
+    vi.spyOn(coreApi.fingerprint, 'sendObservation').mockResolvedValue(true);
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+  });
+
+  it.each([
+    ['Search', search, true],
+    ['View Results', { ...search, 'Bus count': 10 }, false],
+    ['Purchase Attempt', checkout, true],
+    ['Payment Attempt', { ...checkout, 'Payment Type': 'credit_card' }, true],
+  ] as const)(
+    'preserves valid %s and its eligible observation',
+    async (eventName, properties, eligible) => {
+      await trackEvent(eventName, properties);
+
+      expect(mixpanelService.track).toHaveBeenCalledOnce();
+      expect(mixpanelService.track).toHaveBeenCalledWith(
+        eventName,
+        expect.objectContaining({
+          'User Fingerprint': expect.any(String),
+          'product': 'web',
+        }),
+      );
+      const verifyIdentificationEffects = () => {
+        expect(mixpanelService.setPeopleProperties).toHaveBeenCalledWith({
+          'Visitor Found': true,
+        });
+        expect(coreApi.fingerprint.sendObservation).toHaveBeenCalledTimes(
+          eligible ? 1 : 0,
+        );
+        if (eligible) {
+          expect(coreApi.fingerprint.sendObservation).toHaveBeenCalledWith(
+            expect.objectContaining({
+              requestId: 'request-123',
+              visitorId: 'visitor-123',
+              distinctId: 'live-id',
+            }),
+          );
+        }
+      };
+      await vi.waitFor(verifyIdentificationEffects);
+    },
+  );
+});