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

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

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',

package/src/track.ts

@@ -4,10 +4,14 @@ import type {
   EventMetadata,
 } from './types/eventData';
 import botDetectionRelayService from '@/services/botDetectionRelay';
+import { deferBotDetection } from '@/services/deferredBotDetection';
 import fingerprintService from '@/services/fingerprint';
 import geolocationService from '@/services/geolocation';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import validator from '@/services/validator';
+import { createPendingWorkQueue } from '@/util/pendingWork';
+import { snapshotEventData } from '@/util/snapshotEventData';
 
 /**
  * List of events that trigger the fingerprint to be sent with the event. other events will only fetch the cached fingerprint.
@@ -99,12 +103,14 @@ export async function tryTrackEvent(
       const finish = (isReady: boolean) => {
         clearTimeout(timer);
         window.removeEventListener('Tracker Ready', onReady);
+        unsubscribe();
         resolve(isReady);
       };
       const onReady = () => {
         if (mixpanelService.isReady()) finish(true);
       };
       const timer = setTimeout(() => finish(mixpanelService.isReady()), 5000);
+      const unsubscribe = mixpanelService.onReady(onReady);
       window.addEventListener('Tracker Ready', onReady);
       onReady();
     });
@@ -135,25 +141,96 @@ export async function tryTrackEvent(
  * @param {string} eventName - The name of the event to track.
  * @param {object} eventProperties - The properties of the event to track.
  * @param {EventMetadata} meta - Additional metadata to include in the event.
- * Waits up to five seconds for Mixpanel readiness before event submission.
- * Optional fingerprint failure does not discard an otherwise valid event.
+ * Retains unsent events for up to sixty seconds without retrying a started submission.
  */
+const pendingEvents = createPendingWorkQueue({
+  isReady: () => mixpanelService.isReady(),
+  subscribe(notify) {
+    const stopReady = mixpanelService.onReady(notify);
+    const stopIdentity = trackingLifecycle.onChange(notify);
+    window.addEventListener('Tracker Ready', notify);
+    return () => {
+      stopReady();
+      stopIdentity();
+      window.removeEventListener('Tracker Ready', notify);
+    };
+  },
+  maxEntries: 100,
+  maxBytes: 1024 * 1024,
+  maxActive: 100,
+  lifetime: 60000,
+  wait: 5000,
+  stage: 'readiness',
+});
+
+/** Resolves within the initial five-second wait; unsent events can remain pending for 60 seconds. */
 export function trackEvent(
   eventName: string,
   eventProperties: object,
   meta: EventMetadata = {},
 ): Promise<void> {
-  return tryTrackEvent(
-    () => submitEvent(eventName, eventProperties, meta),
+  const isCurrent = trackingLifecycle.capture();
+  const trackingParams = extractTrackingParams();
+  if (mixpanelService.isReady()) {
+    return submitEvent(
+      eventName,
+      eventProperties,
+      meta,
+      isCurrent,
+      trackingParams,
+    );
+  }
+  try {
+    validator.parseEventProps(eventName, eventProperties);
+  } catch (error) {
+    trackEventError(eventName, error, eventProperties);
+    return Promise.resolve();
+  }
+  let snapshot: { eventProperties: object; meta: EventMetadata };
+  let bytes: number;
+  try {
+    const serialized = JSON.stringify(
+      { eventName, eventProperties, meta, trackingParams },
+      (_key, value: unknown) => {
+        if (typeof value === 'function' || typeof value === 'symbol')
+          throw new Error();
+        return value === undefined ? null : value;
+      },
+    );
+    bytes = new Blob([serialized]).size;
+    if (bytes > 1024 * 1024) throw new Error();
+    snapshot = snapshotEventData({ eventProperties, meta });
+  } catch {
+    console.error('Tracking recovery diagnostic', {
+      eventName,
+      stage: 'readiness',
+      reason: 'snapshot_unavailable',
+    });
+    return Promise.resolve();
+  }
+  return pendingEvents.enqueue({
     eventName,
-  );
+    bytes,
+    isCurrent,
+    run: (isActive) =>
+      submitEvent(
+        eventName,
+        snapshot.eventProperties,
+        snapshot.meta,
+        isActive,
+        trackingParams,
+      ),
+  });
 }
 
 async function submitEvent(
   eventName: string,
   eventProperties: object,
   meta: EventMetadata,
+  isCurrent: () => boolean,
+  trackingParams: Record<string, string>,
 ): Promise<void> {
+  const observationContext = trackingLifecycle.capture();
   try {
     validator.parseEventProps(eventName, eventProperties);
     // Call the Mixpanel service to store the distinct ID in the cache
@@ -162,16 +239,15 @@ async function submitEvent(
       botDetectionRelayService.isEnabledFor(eventName);
     let fingerprint = '';
 
-    if (botDetectionEnabled) {
+    if (botDetectionEnabled || FP_TRIGGER_EVENTS.includes(eventName)) {
       try {
         fingerprint = fingerprintService.getCachedFingerprint() ?? '';
       } catch (error) {
         console.error('Error reading cached fingerprint:', error);
       }
     } else {
-      const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
       try {
-        fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+        fingerprint = await fingerprintService.getFingerprint(true);
       } catch {
         console.error('Tracking diagnostic', {
           eventName,
@@ -193,7 +269,6 @@ async function submitEvent(
     const defaultProperties = {
       'User Fingerprint': fingerprint,
     };
-    const trackingParams = extractTrackingParams();
 
     const simplifiedData = flattenEventData(eventProperties);
     const properties = {
@@ -204,10 +279,22 @@ async function submitEvent(
       ...meta,
     };
 
-    mixpanelService.track(eventName, properties);
+    if (!isCurrent()) return;
+    try {
+      mixpanelService.track(eventName, properties);
+    } catch {
+      console.error('Tracking diagnostic', {
+        eventName,
+        stage: 'submission',
+        reason: 'uncertain',
+      });
+      return;
+    }
 
     if (botDetectionEnabled) {
-      void identifyAndRelayFingerprint(eventName, distinctId);
+      deferBotDetection(eventName, distinctId, observationContext);
+    } else if (FP_TRIGGER_EVENTS.includes(eventName)) {
+      void refreshFingerprint(eventName, observationContext);
     }
   } catch (error) {
     console.error(`Error tracking event '${eventName}':`, error);
@@ -215,25 +302,23 @@ async function submitEvent(
   }
 }
 
-/** Identifies and relays only after the original event has been submitted. */
-async function identifyAndRelayFingerprint(
+/** Refreshes optional identity after submission without delaying the event. */
+async function refreshFingerprint(
   eventName: string,
-  distinctId: string | null,
+  isCurrent: () => boolean,
 ): Promise<void> {
+  const deadline = Date.now() + 10000;
   try {
-    if (!fingerprintService.isFingerprintReady()) return;
-
-    const identification = await fingerprintService.identifyVisitor(true);
-    if (!identification.requestId) return;
-
-    await botDetectionRelayService.relay({
-      requestId: identification.requestId,
-      visitorId: identification.visitorId,
-      ...(distinctId && { distinctId }),
+    await fingerprintService.getFingerprint(false, {
+      isActive: () => isCurrent() && Date.now() < deadline,
+      report: () => undefined,
+    });
+  } catch {
+    console.error('Tracking diagnostic', {
       eventName,
+      stage: 'fingerprint',
+      reason: 'failed',
     });
-  } catch (error) {
-    console.error(`Error running Bot Detection for '${eventName}':`, error);
   }
 }