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

package/src/init.botDetection.test.ts

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fingerprintService from '@/services/fingerprint';
+import { trackEvent } from '@/track';
+import init from './init';
+
+const mocks = vi.hoisted(() => ({
+  track: vi.fn(),
+  observation: vi.fn(),
+  fingerprintInit: vi.fn(),
+  visitorData: vi.fn(),
+  geolocationInit: vi.fn(),
+}));
+
+vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
+  FingerprintJSPro: {
+    defaultEndpoint: 'https://fp.example.test',
+    defaultScriptUrlPattern: 'https://fp.example.test/agent',
+  },
+  FpjsClient: vi.fn().mockImplementation(() => ({
+    init: mocks.fingerprintInit,
+    getVisitorData: mocks.visitorData,
+  })),
+}));
+vi.mock('@/services/mixpanel', () => ({
+  default: {
+    init: vi.fn().mockResolvedValue(undefined),
+    validateConfiguration: vi.fn(),
+    setPeopleProperties: vi.fn(),
+    isReady: vi.fn().mockReturnValue(true),
+    getMixpanelDistinctId: vi.fn().mockReturnValue('distinct-id'),
+    track: mocks.track,
+  },
+}));
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    init: mocks.geolocationInit,
+    getCoordinates: vi.fn().mockReturnValue(null),
+    getGeolocationSource: vi.fn().mockReturnValue(null),
+  },
+}));
+vi.mock('@reservamos/js-api-client/core', () => ({
+  default: {
+    setConfig: vi.fn(),
+    fingerprint: { sendObservation: mocks.observation },
+  },
+}));
+
+const search = {
+  'Departure': '2026-10-14',
+  'Departure Delta': 1,
+  'Origin': 'A',
+  'Origin Terminal': 'A',
+  'Destination': 'B',
+  'Destination Terminal': 'B',
+  'Route': 'A-B',
+  'Passengers': 1,
+  'Bus count': 1,
+  'product': 'web',
+};
+const purchase = {
+  'Trips': [
+    {
+      'Departure Arrival': '2026-10-15',
+      'Departure Destination': 'B',
+      'Departure Destination Terminal': 'B',
+      'Departure Line': 'Line',
+      'Departure Origin': 'A',
+      'Departure Origin Terminal': 'A',
+      'Departure Price': 100,
+      'Departure Route': 'A-B',
+      'Departure Stops': 1,
+      'Departure Time': '2026-10-14',
+      'Departure Transport Type': 'bus',
+      'Departure Transporter': 'Line',
+      'Recommended Trip': false,
+    },
+  ],
+  'Passenger Count': 1,
+  'Trip Count': 1,
+  'Total': 100,
+  'product': 'web',
+};
+
+// Keep tracking, validation, Fingerprint readiness and the relay service real.
+describe('Bot Detection from Tracker Ready', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    let request = 0;
+    mocks.visitorData.mockImplementation(async () => ({
+      visitorId: 'fresh-visitor',
+      requestId: `request-${++request}`,
+      confidence: { score: 0.99 },
+      visitorFound: true,
+      cacheHit: false,
+    }));
+    mocks.observation.mockResolvedValue(true);
+    localStorage.clear();
+    Reflect.deleteProperty(window, 'fpClient');
+    Reflect.deleteProperty(window, 'fingerprintConfig');
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it.each([null, 'cached-visitor'])(
+    'submits original events with cache %s and defers one observation per event',
+    async (visitorId) => {
+      if (visitorId) {
+        localStorage.setItem(
+          'default_fingerprint_cache',
+          JSON.stringify({
+            fingerprint: visitorId,
+            expiresAt: Date.now() + 60_000,
+          }),
+        );
+      }
+      let finishFingerprint!: () => void;
+      let finishGeolocation!: () => void;
+      mocks.fingerprintInit.mockReturnValue(
+        new Promise<void>((resolve) => {
+          finishFingerprint = resolve;
+        }),
+      );
+      mocks.geolocationInit.mockReturnValue(
+        new Promise<void>((resolve) => {
+          finishGeolocation = resolve;
+        }),
+      );
+      let tracked!: Promise<unknown[]>;
+      window.addEventListener(
+        'Tracker Ready',
+        () => {
+          expect(fingerprintService.isFingerprintReady()).toBe(false);
+          expect(mocks.fingerprintInit).not.toHaveBeenCalled();
+          tracked = Promise.all([
+            trackEvent('Search', search),
+            trackEvent('Payment Attempt', {
+              ...purchase,
+              'Payment Type': 'credit_card',
+            }),
+            trackEvent('Purchase Attempt', purchase),
+          ]);
+        },
+        { once: true },
+      );
+
+      const initializing = init({
+        mixpanelToken: 'token',
+        identificationKey: 'key',
+      });
+      await vi.advanceTimersByTimeAsync(0);
+      await tracked;
+      expect(mocks.track.mock.calls.map(([name]) => name)).toEqual([
+        'Search',
+        'Payment Attempt',
+        'Purchase Attempt',
+      ]);
+      for (const [, properties] of mocks.track.mock.calls) {
+        expect(properties['User Fingerprint']).toBe(visitorId ?? '');
+      }
+      expect(mocks.visitorData).not.toHaveBeenCalled();
+      expect(mocks.observation).not.toHaveBeenCalled();
+
+      finishFingerprint();
+      finishGeolocation();
+      await initializing;
+      await vi.advanceTimersByTimeAsync(5000);
+      expect(fingerprintService.isFingerprintReady()).toBe(true);
+      expect(mocks.track).toHaveBeenCalledTimes(3);
+      expect(mocks.visitorData).toHaveBeenCalledTimes(3);
+      expect(mocks.observation).toHaveBeenCalledTimes(3);
+      expect(
+        new Set(
+          mocks.observation.mock.calls.map(([payload]) => payload.requestId),
+        ).size,
+      ).toBe(3);
+      for (const [payload] of mocks.observation.mock.calls) {
+        expect(payload.distinctId).toBe('distinct-id');
+        expect(payload.visitorId).toBe('fresh-visitor');
+      }
+      expect(vi.getTimerCount()).toBe(0);
+    },
+  );
+});

package/src/init.test.ts

@@ -20,6 +20,7 @@ const mocks = vi.hoisted(() => ({
 vi.mock('@/services/mixpanel', () => ({
   default: {
     init: mocks.mixpanel,
+    validateConfiguration: vi.fn(),
     getMixpanelDistinctId: mocks.distinctId,
     isReady: mocks.ready,
     track: mocks.track,

package/src/init.ts

@@ -10,6 +10,7 @@ import validator, { InitConfigSchema } from '@/services/validator';
  * Configuration object for initializing the tracking library.
  */
 export type InitConfig = z.infer<typeof InitConfigSchema>;
+let initialization = 0;
 
 /**
  * Dispatches a 'Tracker Ready' event to the window object.
@@ -40,7 +41,11 @@ async function init(config: InitConfig) {
     appName,
   } = config;
 
+  mixpanelService.validateConfiguration(mixpanelToken, mixpanelProxyUrl);
+  const attempt = ++initialization;
+  const isCurrent = () => attempt === initialization;
   await mixpanelService.init(mixpanelToken, debug, mixpanelProxyUrl);
+  if (!isCurrent()) return;
 
   configService.setEnvironment(isSandbox ? 'sandbox' : 'prod');
   if (appName) {
@@ -50,12 +55,20 @@ async function init(config: InitConfig) {
 
   // Dispatch the 'Tracker Ready' event
   onLoaded();
+  if (!isCurrent()) return;
 
   await Promise.all([
     initializeOptionalStage('fingerprint', () =>
-      fingerprintService.initFingerprint(identificationKey, identifyProxyUrl),
+      isCurrent()
+        ? fingerprintService.initFingerprint(
+            identificationKey,
+            identifyProxyUrl,
+          )
+        : Promise.resolve(),
+    ),
+    initializeOptionalStage('geolocation', () =>
+      isCurrent() ? geolocationService.init() : Promise.resolve(),
     ),
-    initializeOptionalStage('geolocation', () => geolocationService.init()),
   ]);
 }
 

package/src/services/botDetectionRelay.test.ts

@@ -50,7 +50,7 @@ describe('botDetectionRelayService', () => {
 
     expect(fetchMock).toHaveBeenCalledWith(
       'https://data-lake.reservamossaas.com/api/v1/fingerprint/bot-detection',
-      {
+      expect.objectContaining({
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -64,7 +64,8 @@ describe('botDetectionRelayService', () => {
           eventName: 'Fingerprint Requested',
         }),
         signal: expect.any(AbortSignal),
-      },
+        keepalive: true,
+      }),
     );
   });
 

package/src/services/deferredBotDetection.ts

@@ -0,0 +1,60 @@
+import botDetectionRelayService from '@/services/botDetectionRelay';
+import fingerprintService from '@/services/fingerprint';
+import trackingLifecycle from '@/services/trackingLifecycle';
+import { createPendingWorkQueue } from '@/util/pendingWork';
+
+const observations = createPendingWorkQueue({
+  isReady: () => fingerprintService.isFingerprintReady(),
+  subscribe(notify) {
+    const stopReady = fingerprintService.onReady(notify);
+    const stopIdentity = trackingLifecycle.onChange(notify);
+    return () => {
+      stopReady();
+      stopIdentity();
+    };
+  },
+  maxEntries: 100,
+  maxBytes: 1024 * 1024,
+  maxActive: 3,
+  lifetime: 10000,
+  wait: 0,
+  stage: 'fingerprint',
+});
+
+/** Defers only observation work; this function never submits a Mixpanel event. */
+export function deferBotDetection(
+  eventName: string,
+  distinctId: string | null,
+  isCurrent: () => boolean,
+): void {
+  void observations.enqueue({
+    eventName,
+    bytes: new Blob([eventName, distinctId ?? '']).size,
+    isCurrent,
+    async run(isActive) {
+      let stage: 'fingerprint' | 'relay' = 'fingerprint';
+      try {
+        const identification = await fingerprintService.identifyVisitor(true, {
+          isActive,
+          report: () => undefined,
+        });
+        if (!isActive() || !identification.requestId) return;
+        stage = 'relay';
+        await botDetectionRelayService.relay({
+          requestId: identification.requestId,
+          visitorId: identification.visitorId,
+          ...(distinctId && { distinctId }),
+          eventName,
+        });
+      } catch {
+        if (isActive()) {
+          console.error('Bot Detection diagnostic', {
+            eventName,
+            stage,
+            reason: 'failed',
+          });
+        }
+      }
+    },
+  });
+}

package/src/services/fingerprint.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import fingerprintService, { getFingerprintForIdentify } from './fingerprint';
 
 const visitorData = {
@@ -95,6 +96,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(
@@ -378,3 +397,174 @@ describe('fingerprintService', () => {
     consoleError.mockRestore();
   });
 });
+
+describe('bounded fingerprint waiting', () => {
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    localStorage.clear();
+    initMock.mockResolvedValue(undefined);
+    getVisitorDataMock.mockReset().mockResolvedValue(visitorData);
+    clientMock.mockImplementation(() => ({
+      init: initMock,
+      getVisitorData: getVisitorDataMock,
+    }));
+    await fingerprintService.initFingerprint('wait-key');
+  });
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    localStorage.clear();
+  });
+
+  it('returns cache without a provider request', async () => {
+    localStorage.setItem(
+      'default_fingerprint_cache',
+      JSON.stringify({ fingerprint: 'cached', expiresAt: Date.now() + 1000 }),
+    );
+    await expect(fingerprintService.waitForFingerprintId()).resolves.toBe(
+      'cached',
+    );
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+  });
+  it('joins a fresh request already in flight and serves concurrent waiters', async () => {
+    let finish!: (value: typeof visitorData) => void;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    const existing = fingerprintService.identifyVisitor(true);
+    const first = fingerprintService.waitForFingerprintId();
+    const second = fingerprintService.waitForFingerprintId();
+    finish(visitorData);
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      'visitor-123',
+      'visitor-123',
+    ]);
+    await existing;
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('waits for an agent still loading, then identifies only once', async () => {
+    let finish!: () => void;
+    initMock.mockReturnValue(
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+    );
+    const initialization = fingerprintService.initFingerprint('late-key');
+    const first = fingerprintService.waitForFingerprintId();
+    const second = fingerprintService.waitForFingerprintId();
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+    finish();
+    await initialization;
+    await expect(Promise.all([first, second])).resolves.toEqual([
+      'visitor-123',
+      'visitor-123',
+    ]);
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(getVisitorDataMock).toHaveBeenCalledWith({}, false);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('resolves null when the pending agent fails to load', async () => {
+    let fail!: (error: Error) => void;
+    initMock.mockReturnValue(
+      new Promise((_resolve, reject) => {
+        fail = reject;
+      }),
+    );
+    const initialization = fingerprintService.initFingerprint('blocked-key');
+    const pending = fingerprintService.waitForFingerprintId();
+    const rejected = expect(initialization).rejects.toThrow('blocked');
+    fail(new Error('blocked'));
+    await rejected;
+    await expect(pending).resolves.toBeNull();
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+  });
+  it.each([-1, Infinity, NaN])(
+    'resolves null for invalid budget %s',
+    async (budget) => {
+      await expect(
+        fingerprintService.waitForFingerprintId(budget),
+      ).resolves.toBeNull();
+      expect(getVisitorDataMock).not.toHaveBeenCalled();
+    },
+  );
+  it('keeps a late successful result after the caller times out without another lookup', async () => {
+    let finish!: (value: typeof visitorData) => void;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    setPeoplePropertiesMock.mockClear();
+    const pending = fingerprintService.waitForFingerprintId(2000);
+    await vi.advanceTimersByTimeAsync(2000);
+    await expect(pending).resolves.toBeNull();
+    await vi.advanceTimersByTimeAsync(500);
+    finish(visitorData);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fingerprintService.getCachedFingerprint()).toBe('visitor-123');
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': true,
+    });
+    await expect(fingerprintService.waitForFingerprintId()).resolves.toBe(
+      'visitor-123',
+    );
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('suppresses a timed-out request after its user lifecycle changes', async () => {
+    let finish!: (value: typeof visitorData) => void;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    setPeoplePropertiesMock.mockClear();
+    const pending = fingerprintService.waitForFingerprintId(2000);
+    await vi.advanceTimersByTimeAsync(2000);
+    await expect(pending).resolves.toBeNull();
+    trackingLifecycle.identify('replacement-user-after-timeout');
+    finish(visitorData);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fingerprintService.getCachedFingerprint()).toBeNull();
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('resolves null at its timeout and consumes late rejection', async () => {
+    let fail!: (error: Error) => void;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((_resolve, reject) => {
+        fail = reject;
+      }),
+    );
+    const pending = fingerprintService.waitForFingerprintId(100);
+    await vi.advanceTimersByTimeAsync(100);
+    await expect(pending).resolves.toBeNull();
+    fail(new Error('offline'));
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+  it('cancels when initialization changes and ignores an old result', async () => {
+    let finish!: (value: typeof visitorData) => void;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    const pending = fingerprintService.waitForFingerprintId();
+    await fingerprintService.initFingerprint('replacement');
+    await expect(pending).resolves.toBeNull();
+    finish(visitorData);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fingerprintService.getCachedFingerprint()).toBeNull();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});