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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.8-alpha.0",
+  "version": "1.1.8-alpha.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reservamos/reservamos-browser-analytics.git"

package/src/events/sharedSchemas/tripSchema.ts

@@ -1,10 +1,5 @@
 import { z } from 'zod';
-import {
-  dateField,
-  intField,
-  numberField,
-  stringField,
-} from '@/util/primitiveFields';
+import { dateField, numberField, stringField } from '@/util/primitiveFields';
 
 const tripSchema = z.object({
   'Departure Arrival': dateField('Departure Arrival'),
@@ -17,7 +12,7 @@ const tripSchema = z.object({
   'Departure Origin Terminal': stringField('Departure Origin Terminal'),
   'Departure Price': numberField('Departure Price'),
   'Departure Route': stringField('Departure Route'),
-  'Departure Stops': intField('Departure Stops'),
+  'Departure Stops': z.number().int(),
   'Departure Time': dateField('Departure Time'),
   'Departure Transport Type': stringField('Departure Transport Type'),
   'Departure Transporter': stringField('Departure Transporter'),
@@ -31,7 +26,7 @@ const tripSchema = z.object({
   'Return Origin Terminal': stringField('Return Origin Terminal').optional(),
   'Return Price': numberField('Return Price').optional(),
   'Return Route': stringField('Return Route').optional(),
-  'Return Stops': intField('Return Stops').optional(),
+  'Return Stops': z.number().int().optional(),
   'Return Time': dateField('Return Time').optional(),
   'Return Transport Type': stringField('Return Transport Type').optional(),
   'Return Transporter': stringField('Return Transporter').optional(),

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/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

@@ -95,6 +95,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(

package/src/services/fingerprint.ts

@@ -5,6 +5,7 @@ import {
   FpjsClient,
 } from '@fingerprintjs/fingerprintjs-pro-spa';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 
 declare global {
   interface Window {
@@ -28,6 +29,22 @@ const PROXY_QUERY_PARAM =
  * "FPJSAgent hasn't loaded yet" until init completes.
  */
 let fingerprintAgentReady = false;
+let initialization = 0;
+const readinessSubscribers = new Set<() => void>();
+
+/** Notifies deferred observations only when the actual provider agent has loaded. */
+function onReady(notify: () => void): () => void {
+  readinessSubscribers.add(notify);
+  return () => {
+    readinessSubscribers.delete(notify);
+  };
+}
+
+/** Prevents a previous configuration or late agent load from serving a new init. */
+function invalidate(): void {
+  initialization++;
+  fingerprintAgentReady = false;
+}
 
 /**
  * Calculates the expiration date based on the cache time.
@@ -116,7 +133,8 @@ async function initFingerprint(
     customScriptEndpointArray.unshift(buildProxyUrl(proxyUrl));
   }
 
-  fingerprintAgentReady = false;
+  invalidate();
+  const attempt = initialization;
   window.fingerprintConfig = {};
   const client = new FpjsClient({
     loadOptions: {
@@ -129,11 +147,12 @@ async function initFingerprint(
 
   try {
     await client.init();
-    if (window.fpClient === client) {
+    if (window.fpClient === client && attempt === initialization) {
       fingerprintAgentReady = true;
+      readinessSubscribers.forEach((notify) => notify());
     }
   } catch (error) {
-    if (window.fpClient === client) {
+    if (window.fpClient === client && attempt === initialization) {
       fingerprintAgentReady = false;
     }
     console.error('Error initializing identification service:', error);
@@ -148,8 +167,11 @@ async function initFingerprint(
  * @returns {Promise<string>} A promise that resolves with the fingerprint, or an empty string when unavailable.
  * @throws {Error} Throws an error if retrieval fails after the agent has loaded.
  */
-async function getFingerprint(cacheOnly = false): Promise<string> {
-  return readFingerprint(cacheOnly);
+async function getFingerprint(
+  cacheOnly = false,
+  context?: IdentifyStageContext,
+): Promise<string> {
+  return readFingerprint(cacheOnly, context);
 }
 
 /** Internal identify path with late-effect suppression and sanitized diagnostics. */
@@ -184,8 +206,9 @@ async function readFingerprint(
  */
 async function identifyVisitor(
   ignoreCache = false,
+  context?: IdentifyStageContext,
 ): Promise<FingerprintIdentification> {
-  return requestIdentification(ignoreCache);
+  return requestIdentification(ignoreCache, context);
 }
 
 async function requestIdentification(
@@ -201,9 +224,8 @@ async function requestIdentification(
     if (!context || context.isActive()) {
       try {
         setCachedFingerprint(result.visitorId);
-      } catch (error) {
-        if (!context) throw error;
-        context.report('cache', 'unavailable');
+      } catch {
+        context?.report('cache', 'unavailable');
       }
       if (typeof result.visitorFound === 'boolean') {
         try {
@@ -245,7 +267,12 @@ const fingerprintService = {
   getFingerprint,
   identifyVisitor,
   isFingerprintReady,
+  onReady,
+  invalidate,
   getCachedFingerprint,
 };
 
+// One module-lifetime listener invalidates the old agent before Mixpanel signals readiness.
+trackingLifecycle.onInitialization(invalidate);
+
 export default fingerprintService;

package/src/services/mixpanel.test.ts

@@ -34,6 +34,7 @@ describe('Mixpanel SDK version metadata', () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllGlobals();
     vi.clearAllTimers();
     vi.useRealTimers();
   });
@@ -87,6 +88,21 @@ describe('Mixpanel SDK version metadata', () => {
     });
   });
 
+  it('completes a repeated init with the installed singleton provider without waiting for another loaded callback', async () => {
+    const complete = vi.fn();
+    void mixpanelService.init('test-sdk-version-token').then(complete);
+    await Promise.resolve();
+    expect(complete).toHaveBeenCalledOnce();
+    expect(mixpanelService.isReady()).toBe(true);
+  });
+
+  it('rejects a different project before disturbing the existing provider session', () => {
+    expect(() => mixpanelService.init('different-project')).toThrow(
+      'new page session',
+    );
+    expect(mixpanelService.isReady()).toBe(true);
+  });
+
   it('still sets people properties when the SDK distinct ID cache is blocked', () => {
     vi.spyOn(transport, '_track_or_batch').mockImplementation(
       ({ data }) => data,
@@ -142,6 +158,32 @@ describe('Mixpanel SDK version metadata', () => {
     expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
   });
 
+  it('uses the live distinct ID first and null fallback when localStorage is null', () => {
+    vi.stubGlobal('localStorage', null);
+    const liveId = vi
+      .spyOn(mixpanel, 'get_distinct_id')
+      .mockReturnValue('live-id');
+    expect(mixpanelService.getMixpanelDistinctId()).toBe('live-id');
+    liveId.mockReturnValue('');
+    expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
+  });
+
+  it('preserves identify diagnostics and people updates when localStorage is null', () => {
+    vi.useFakeTimers();
+    vi.stubGlobal('localStorage', null);
+    vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+    const people = vi
+      .spyOn(mixpanel.people, 'set')
+      .mockImplementation(() => undefined);
+    const report = vi.fn();
+    mixpanelService.identify('null-storage-user', { plan: 'standard' }, report);
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(people).toHaveBeenCalledWith(
+      { plan: 'standard' },
+      expect.any(Function),
+    );
+  });
+
   it('uses the cached distinct ID when Mixpanel has no live ID', () => {
     localStorage.setItem('mp_distinct_id', 'cached-id');
     vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('');

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,6 +102,7 @@ function identify(
   properties: Record<string, unknown>,
   report?: IdentifyReporter,
 ): void {
+  trackingLifecycle.identify(userId);
   mixpanel.identify(userId);
   if (!updateCachedDistinctId(userId)) report?.('cache', 'unavailable');
   if (!report) {
@@ -108,7 +155,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,10 +173,9 @@ 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?.();
@@ -148,6 +194,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 +207,9 @@ function updateCachedDistinctId(distinctId: string): boolean {
 
 const mixpanelService = {
   init,
+  validateConfiguration,
   isReady,
+  onReady,
   track,
   identify,
   attachProperty,