@reservamos/browser-analytics 1.1.8-alpha.0 → 1.2.0-alpha.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,142 @@
+import coreApi from '@reservamos/js-api-client/core';
+import mixpanel from 'mixpanel-browser';
+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(),
+}));
+
+const { provider } = vi.hoisted(() => ({
+  provider: {
+    init: vi.fn((_token: string, config: { loaded: () => void }) =>
+      config.loaded(),
+    ),
+    register: vi.fn(),
+    set_config: vi.fn(),
+    identify: vi.fn(),
+    track: vi.fn(),
+    get_distinct_id: vi.fn(() => 'live-id'),
+    people: { set: vi.fn(), union: vi.fn() },
+  },
+}));
+vi.mock('mixpanel-browser', () => ({ default: provider }));
+
+// Keep the SDK Fingerprint cache, Mixpanel service, 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();
+    await mixpanelService.init('test-storage-token');
+    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(mixpanel, 'get_distinct_id').mockReturnValue('live-id');
+    vi.spyOn(mixpanel.people, 'set').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(mixpanel.track).toHaveBeenCalledOnce();
+      expect(mixpanel.track).toHaveBeenCalledWith(
+        eventName,
+        expect.objectContaining({
+          'User Fingerprint': expect.any(String),
+          'product': 'web',
+        }),
+      );
+      /**
+       * Checks effects that may finish after event submission during background refresh.
+       * @returns {void} Throws until the expected profile and relay effects are observed.
+       */
+      const verifyIdentificationEffects = () => {
+        expect(mixpanel.people.set).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);
+    },
+  );
+});

package/src/track.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import botDetectionRelayService from '@/services/botDetectionRelay';
 import fingerprintService from '@/services/fingerprint';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import validator from '@/services/validator';
 import { trackEvent, trackEventError, tryTrackEvent } from './track';
 
@@ -18,6 +19,7 @@ vi.mock('@/services/fingerprint', () => ({
     getCachedFingerprint: vi.fn(),
     identifyVisitor: vi.fn(),
     isFingerprintReady: vi.fn(),
+    onReady: vi.fn().mockReturnValue(() => undefined),
   },
 }));
 
@@ -30,6 +32,7 @@ vi.mock('@/services/geolocation', () => ({
 
 vi.mock('@/services/mixpanel', () => ({
   default: {
+    onReady: vi.fn().mockReturnValue(() => undefined),
     isReady: vi.fn().mockReturnValue(true),
     getMixpanelDistinctId: vi.fn().mockReturnValue('distinct-123'),
     track: vi.fn(),
@@ -42,9 +45,12 @@ vi.mock('@/services/validator', () => ({
   },
 }));
 
+let testIdentity = 0;
 describe('trackEvent Bot Detection relay', () => {
   beforeEach(() => {
+    trackingLifecycle.identify(`test-${testIdentity++}`);
     vi.resetAllMocks();
+    vi.mocked(fingerprintService.onReady).mockReturnValue(() => undefined);
     vi.mocked(mixpanelService.isReady).mockReturnValue(true);
     vi.mocked(mixpanelService.getMixpanelDistinctId).mockReturnValue(
       'distinct-123',
@@ -97,7 +103,10 @@ describe('trackEvent Bot Detection relay', () => {
           expect(mixpanelService.track).toHaveBeenCalledTimes(1);
           await completion;
           expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
-          expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
+          expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(
+            true,
+            expect.objectContaining({ isActive: expect.any(Function) }),
+          );
           await vi.waitFor(() =>
             expect(botDetectionRelayService.relay).toHaveBeenCalledOnce(),
           );
@@ -248,13 +257,64 @@ describe('trackEvent Bot Detection relay', () => {
     expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
   });
 
+  it('submits View Results while identification remains pending beyond 5.2 seconds', async () => {
+    vi.useFakeTimers();
+    try {
+      vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+      vi.mocked(fingerprintService.getCachedFingerprint).mockReturnValue(null);
+      vi.mocked(fingerprintService.getFingerprint).mockReturnValue(
+        new Promise(() => undefined),
+      );
+      const onComplete = vi.fn();
+      void trackEvent('View Results', { 'Results Count': 2 }).then(onComplete);
+      await vi.advanceTimersByTimeAsync(5200);
+      expect(mixpanelService.track).toHaveBeenCalledWith('View Results', {
+        'User Fingerprint': '',
+        'Results Count': 2,
+      });
+      expect(onComplete).toHaveBeenCalledOnce();
+      expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('keeps cached View Results identity and does not replay after late identification', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+    let finish!: (visitor: string) => void;
+    vi.mocked(fingerprintService.getFingerprint).mockImplementation(() => {
+      expect(mixpanelService.track).toHaveBeenCalledOnce();
+      return new Promise((resolve) => {
+        finish = resolve;
+      });
+    });
+    await trackEvent('View Results', { 'Results Count': 2 }, { source: 'web' });
+    expect(mixpanelService.track).toHaveBeenCalledWith('View Results', {
+      'User Fingerprint': 'cached-visitor',
+      'Results Count': 2,
+      'source': 'web',
+    });
+    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(
+      false,
+      expect.objectContaining({ isActive: expect.any(Function) }),
+    );
+    finish('late-visitor');
+    await Promise.resolve();
+    expect(mixpanelService.track).toHaveBeenCalledOnce();
+    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  });
+
   it('submits View Results with an empty fingerprint if identification rejects', async () => {
     vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+    vi.mocked(fingerprintService.getCachedFingerprint).mockReturnValue(null);
     vi.mocked(fingerprintService.getFingerprint).mockRejectedValue(
       new Error('Fingerprint failed'),
     );
     await trackEvent('View Results', { 'Results Count': 2 }, { source: 'web' });
-    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(false);
+    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(
+      false,
+      expect.objectContaining({ isActive: expect.any(Function) }),
+    );
     expect(mixpanelService.track).toHaveBeenCalledTimes(1);
     expect(mixpanelService.track).toHaveBeenCalledWith('View Results', {
       'User Fingerprint': '',
@@ -277,6 +337,70 @@ describe('trackEvent Bot Detection relay', () => {
     });
     expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
   });
+
+  it('keeps the original event exactly once when identification omits requestId', async () => {
+    const identification = {
+      visitorId: 'fresh-visitor',
+      confidenceScore: 0.99,
+      cacheHit: false,
+    } as Awaited<ReturnType<typeof fingerprintService.identifyVisitor>>;
+    vi.mocked(fingerprintService.identifyVisitor).mockResolvedValue(
+      identification,
+    );
+    await trackEvent('Search', {});
+    await Promise.resolve();
+    expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+    expect(mixpanelService.track).toHaveBeenCalledWith('Search', {
+      'User Fingerprint': 'cached-visitor',
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  });
+
+  it('omits an unavailable distinctId from the background relay', async () => {
+    vi.mocked(mixpanelService.getMixpanelDistinctId).mockReturnValue(null);
+    await trackEvent('Search', {});
+    await Promise.resolve();
+    await vi.waitFor(() => {
+      expect(botDetectionRelayService.relay).toHaveBeenCalledTimes(1);
+      expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+        requestId: 'fresh-request',
+        visitorId: 'fresh-visitor',
+        eventName: 'Search',
+      });
+    });
+    expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['fingerprint', 'relay'] as const)(
+    'reports a controlled local diagnostic for a background %s failure',
+    async (stage) => {
+      const error = new Error('private visitor identifier');
+      if (stage === 'fingerprint') {
+        vi.mocked(fingerprintService.identifyVisitor).mockRejectedValue(error);
+      } else {
+        vi.mocked(botDetectionRelayService.relay).mockRejectedValue(error);
+      }
+      const diagnostic = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => undefined);
+      try {
+        await trackEvent('Search', {});
+        await Promise.resolve();
+        await vi.waitFor(() => {
+          expect(diagnostic).toHaveBeenCalledWith('Bot Detection diagnostic', {
+            eventName: 'Search',
+            stage,
+            reason: 'failed',
+          });
+        });
+        expect(diagnostic.mock.calls.flat()).not.toContain(error);
+        expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+      } finally {
+        diagnostic.mockRestore();
+      }
+    },
+  );
 });
 
 describe('bounded tracking readiness', () => {
@@ -284,6 +408,7 @@ describe('bounded tracking readiness', () => {
     vi.useFakeTimers();
     vi.resetAllMocks();
     vi.mocked(mixpanelService.isReady).mockReturnValue(false);
+    vi.mocked(mixpanelService.onReady).mockReturnValue(() => undefined);
     vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
     vi.mocked(fingerprintService.getFingerprint).mockResolvedValue('');
     vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(false);
@@ -336,15 +461,15 @@ describe('bounded tracking readiness', () => {
     expect(vi.getTimerCount()).toBe(0);
   });
 
-  it('expires cleanly, reports a controlled diagnostic, and ignores late readiness', async () => {
+  it('expires after the retention deadline and ignores later readiness', async () => {
     const remove = vi.spyOn(window, 'removeEventListener');
     const pending = trackEvent('Payment Attempt', {
       secret: 'private-payload',
     });
     void pending.catch(() => undefined);
-    await vi.advanceTimersByTimeAsync(5000);
+    await vi.advanceTimersByTimeAsync(60000);
     await expect(pending).resolves.toBeUndefined();
-    expect(console.error).toHaveBeenCalledWith('Tracking diagnostic', {
+    expect(console.error).toHaveBeenCalledWith('Tracking recovery diagnostic', {
       eventName: 'Payment Attempt',
       stage: 'readiness',
       reason: 'timeout',