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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.7",
+  "version": "1.1.8-alpha.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reservamos/reservamos-browser-analytics.git"
@@ -54,7 +54,7 @@
     "validate": "./validate.sh",
     "validate:full": "./validate.sh --full",
     "upgrade": "upgradeps",
-    "release": "npm run build && np"
+    "release": "gh workflow run publish.yml --ref main"
   },
   "type": "module",
   "types": "./dist/browser-analytics.d.ts",

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

@@ -0,0 +1,288 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import createAnonymousProfile from '@/profiles/createAnonymousProfile/createAnonymousProfile';
+import { trackEvent } from '@/track';
+import init from './init';
+
+const mocks = vi.hoisted(() => ({
+  mixpanel: vi.fn(),
+  fingerprint: vi.fn(),
+  geolocation: vi.fn(),
+  validate: vi.fn(),
+  environment: vi.fn(),
+  appName: vi.fn(),
+  config: vi.fn(),
+  core: vi.fn(),
+  distinctId: vi.fn(),
+  profile: vi.fn(),
+  track: vi.fn(),
+  ready: vi.fn(),
+}));
+vi.mock('@/services/mixpanel', () => ({
+  default: {
+    init: mocks.mixpanel,
+    validateConfiguration: vi.fn(),
+    getMixpanelDistinctId: mocks.distinctId,
+    isReady: mocks.ready,
+    track: mocks.track,
+  },
+}));
+vi.mock('@/services/fingerprint', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@/services/fingerprint')>();
+  return {
+    ...actual,
+    default: { ...actual.default, initFingerprint: mocks.fingerprint },
+  };
+});
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    init: mocks.geolocation,
+    getCoordinates: vi.fn().mockReturnValue(null),
+    getGeolocationSource: vi.fn().mockReturnValue(null),
+  },
+}));
+vi.mock('@/services/validator', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/services/validator')>();
+  return {
+    ...actual,
+    default: { ...actual.default, parseInitProps: mocks.validate },
+  };
+});
+vi.mock('@/services/config', () => ({
+  default: {
+    setEnvironment: mocks.environment,
+    setAppName: mocks.appName,
+    getCoreAPIConfig: mocks.config,
+  },
+}));
+vi.mock('@reservamos/js-api-client/core', () => ({
+  default: {
+    setConfig: mocks.core,
+    profiles: { createAnonymousProfile: mocks.profile },
+  },
+}));
+
+const config = {
+  mixpanelToken: 'test-token',
+  identificationKey: 'test-key',
+  appName: 'test-app',
+  isSandbox: true,
+};
+
+describe('init optional enrichment', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    Object.values(mocks).forEach((mock) => mock.mockReset());
+    localStorage.clear();
+    Reflect.deleteProperty(window, 'fingerprintConfig');
+    mocks.distinctId.mockReturnValue('live-id');
+    mocks.ready.mockReturnValue(true);
+    mocks.profile.mockResolvedValue({ id: 'profile-id' });
+    mocks.mixpanel.mockResolvedValue(undefined);
+    mocks.fingerprint.mockResolvedValue(undefined);
+    mocks.geolocation.mockResolvedValue(null);
+    mocks.config.mockReturnValue({ baseUrl: 'https://example.test' });
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('configures Core API and emits readiness while both optional stages are pending', async () => {
+    mocks.fingerprint.mockReturnValue(new Promise(() => undefined));
+    mocks.geolocation.mockReturnValue(new Promise(() => undefined));
+    const dispatch = vi
+      .spyOn(window, 'dispatchEvent')
+      .mockImplementation((event) => {
+        if (event.type === 'Tracker Ready') {
+          expect(mocks.environment).toHaveBeenCalledWith('sandbox');
+          expect(mocks.appName).toHaveBeenCalledWith('test-app');
+          expect(mocks.core).toHaveBeenCalledWith({
+            baseUrl: 'https://example.test',
+          });
+        }
+        return true;
+      });
+    const completed = vi.fn();
+    const pending = init(config).then(completed);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'Tracker Ready' }),
+    );
+    expect(mocks.fingerprint).toHaveBeenCalledOnce();
+    expect(mocks.geolocation).toHaveBeenCalledOnce();
+    expect(completed).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(3000);
+    await pending;
+    expect(completed).toHaveBeenCalledOnce();
+    expect(console.error).toHaveBeenCalledWith(
+      'SDK initialization diagnostic',
+      { stage: 'fingerprint', reason: 'timeout' },
+    );
+    expect(console.error).toHaveBeenCalledWith(
+      'SDK initialization diagnostic',
+      { stage: 'geolocation', reason: 'timeout' },
+    );
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each([null, 'cached-visitor'])(
+    'supports profile calls from readiness before fingerprint init with cache %s',
+    async (cachedId) => {
+      if (cachedId) {
+        localStorage.setItem(
+          'default_fingerprint_cache',
+          JSON.stringify({
+            fingerprint: cachedId,
+            expiresAt: Date.now() + 60_000,
+          }),
+        );
+      }
+      let outcome: Promise<unknown> | undefined;
+      window.addEventListener(
+        'Tracker Ready',
+        () => {
+          outcome = createAnonymousProfile({ email: 'test@example.com' }).then(
+            (response) => ({ response }),
+            (error: unknown) => ({ error }),
+          );
+        },
+        { once: true },
+      );
+      await init(config);
+      await expect(outcome).resolves.toEqual({
+        response: { id: 'profile-id' },
+      });
+      expect(mocks.profile).toHaveBeenCalledWith({
+        identifier_key: 'email',
+        identifier_value: 'test@example.com',
+        details: {},
+        identifiers: [
+          ...(cachedId ? [{ key: 'fingerprint', value: cachedId }] : []),
+          { key: 'distinct_id', value: 'live-id' },
+        ],
+      });
+    },
+  );
+
+  describe.each(['Search', 'View Results'])(
+    '%s from early readiness',
+    (eventName) => {
+      it.each([null, 'cached-visitor'])(
+        'submits before Fingerprint config with cache %s',
+        async (visitorId) => {
+          if (visitorId)
+            localStorage.setItem(
+              'default_fingerprint_cache',
+              JSON.stringify({
+                fingerprint: visitorId,
+                expiresAt: Date.now() + 60_000,
+              }),
+            );
+          const properties = {
+            'Departure': '2026-10-14',
+            'Departure Delta': 0,
+            'Origin': 'A',
+            'Origin Terminal': 'A',
+            'Destination': 'B',
+            'Destination Terminal': 'B',
+            'Route': 'A-B',
+            'Passengers': 1,
+            'Bus count': 1,
+            'product': 'web',
+          };
+          let tracked: Promise<void> | undefined;
+          window.addEventListener(
+            'Tracker Ready',
+            () => {
+              tracked = trackEvent(eventName, properties);
+            },
+            { once: true },
+          );
+          await init(config);
+          await tracked;
+          expect(mocks.track).toHaveBeenCalledTimes(1);
+          expect(mocks.track).toHaveBeenCalledWith(
+            eventName,
+            expect.objectContaining({
+              'User Fingerprint': visitorId ?? '',
+              'Route': 'A-B',
+            }),
+          );
+        },
+      );
+    },
+  );
+
+  it('waits for required Mixpanel initialization before configuring or signaling readiness', async () => {
+    let finishMixpanel!: () => void;
+    mocks.mixpanel.mockReturnValue(
+      new Promise<void>((resolve) => {
+        finishMixpanel = resolve;
+      }),
+    );
+    const dispatch = vi.spyOn(window, 'dispatchEvent');
+    const pending = init(config);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(mocks.core).not.toHaveBeenCalled();
+    expect(dispatch).not.toHaveBeenCalled();
+    finishMixpanel();
+    await pending;
+    expect(dispatch).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each(['fingerprint', 'geolocation'] as const)(
+    'continues after %s rejects without leaking raw errors',
+    async (stage) => {
+      mocks[stage].mockRejectedValue(new Error('private-stage-error'));
+      const dispatch = vi.spyOn(window, 'dispatchEvent');
+      await expect(init(config)).resolves.toBeUndefined();
+      expect(dispatch).toHaveBeenCalledOnce();
+      expect(mocks.fingerprint).toHaveBeenCalledOnce();
+      expect(mocks.geolocation).toHaveBeenCalledOnce();
+      expect(console.error).toHaveBeenCalledWith(
+        'SDK initialization diagnostic',
+        { stage, reason: 'failed' },
+      );
+      expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+        'private-stage-error',
+      );
+      expect(vi.getTimerCount()).toBe(0);
+    },
+  );
+
+  it('continues to geolocation if fingerprint initialization throws synchronously', async () => {
+    mocks.fingerprint.mockImplementation(() => {
+      throw new Error('private-stage-error');
+    });
+    await expect(init(config)).resolves.toBeUndefined();
+    expect(mocks.geolocation).toHaveBeenCalledOnce();
+    expect(console.error).toHaveBeenCalledWith(
+      'SDK initialization diagnostic',
+      { stage: 'fingerprint', reason: 'failed' },
+    );
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('consumes late rejection after the optional deadline without another diagnostic', async () => {
+    let rejectFingerprint!: (reason: Error) => void;
+    mocks.fingerprint.mockReturnValue(
+      new Promise<void>((_resolve, reject) => {
+        rejectFingerprint = reject;
+      }),
+    );
+    const dispatch = vi.spyOn(window, 'dispatchEvent');
+    const pending = init(config);
+    await vi.advanceTimersByTimeAsync(3000);
+    await pending;
+    expect(console.error).toHaveBeenCalledTimes(1);
+    rejectFingerprint(new Error('private-late-error'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(console.error).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/init.ts

@@ -10,12 +10,13 @@ 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.
  *
  * This function creates and dispatches a custom event named 'Tracker Ready'
- * to signal that the tracking library has been successfully initialized and is ready to use.
+ * after Mixpanel and Core API configuration are ready; optional enrichment may still be pending.
  */
 function onLoaded() {
   window.dispatchEvent(new CustomEvent('Tracker Ready'));
@@ -24,6 +25,7 @@ function onLoaded() {
 /**
  * Initializes the tracking library with the provided configuration.
  * @param {InitConfig} config - The configuration object for initialization.
+ * Optional enrichment runs concurrently, with a three-second waiting limit per stage.
  * @throws {Error} Throws an error if the configuration is invalid.
  */
 async function init(config: InitConfig) {
@@ -39,18 +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);
-
-  try {
-    await fingerprintService.initFingerprint(
-      identificationKey,
-      identifyProxyUrl,
-    );
-  } catch (error) {
-    console.error('Error initializing identification service:', error);
-  }
-
-  await geolocationService.init();
+  if (!isCurrent()) return;
 
   configService.setEnvironment(isSandbox ? 'sandbox' : 'prod');
   if (appName) {
@@ -60,6 +55,46 @@ async function init(config: InitConfig) {
 
   // Dispatch the 'Tracker Ready' event
   onLoaded();
+  if (!isCurrent()) return;
+
+  await Promise.all([
+    initializeOptionalStage('fingerprint', () =>
+      isCurrent()
+        ? fingerprintService.initFingerprint(
+            identificationKey,
+            identifyProxyUrl,
+          )
+        : Promise.resolve(),
+    ),
+    initializeOptionalStage('geolocation', () =>
+      isCurrent() ? geolocationService.init() : Promise.resolve(),
+    ),
+  ]);
+}
+
+/** Bounds the wait for optional work without cancelling future enrichment. */
+function initializeOptionalStage(
+  stage: 'fingerprint' | 'geolocation',
+  initialize: () => Promise<unknown>,
+): Promise<void> {
+  return new Promise((resolve) => {
+    let active = true;
+    const finish = (reason?: 'timeout' | 'failed') => {
+      if (!active) return;
+      active = false;
+      clearTimeout(timer);
+      if (reason)
+        console.error('SDK initialization diagnostic', { stage, reason });
+      resolve();
+    };
+    const timer = setTimeout(() => finish('timeout'), 3000);
+    void Promise.resolve()
+      .then(initialize)
+      .then(
+        () => finish(),
+        () => finish('failed'),
+      );
+  });
 }
 
 /**

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