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

package/src/services/fingerprint.ts

@@ -1,7 +1,10 @@
+import type { FingerprintIdentification } from '@/types/botDetection';
+import type { IdentifyStageContext } from '@/util/identifyAttempt';
 import {
   FingerprintJSPro,
   FpjsClient,
 } from '@fingerprintjs/fingerprintjs-pro-spa';
+import mixpanelService from '@/services/mixpanel';
 
 declare global {
   interface Window {
@@ -19,6 +22,13 @@ const DEFAULT_CACHE_TIME_IN_DAYS = 7;
 const PROXY_QUERY_PARAM =
   'apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>';
 
+/**
+ * True only after `fpClient.init()` succeeds. `window.fpClient` exists as soon as
+ * the client is constructed, but that instance still uses a stub agent that throws
+ * "FPJSAgent hasn't loaded yet" until init completes.
+ */
+let fingerprintAgentReady = false;
+
 /**
  * Calculates the expiration date based on the cache time.
  * @param {number} cacheTimeInDays - The cache time in days.
@@ -37,6 +47,10 @@ const getExpirationDate = (cacheTimeInDays: number): number => {
  * @returns {string | null} - The cached fingerprint or null if it is expired or not found.
  */
 const getCachedFingerprint = (): string | null => {
+  return readCachedFingerprint();
+};
+
+function readCachedFingerprint(context?: IdentifyStageContext): string | null {
   const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig;
 
   try {
@@ -47,9 +61,10 @@ const getCachedFingerprint = (): string | null => {
     localStorage.removeItem(cacheName);
     return null;
   } catch {
+    context?.report('cache', 'unavailable');
     return null;
   }
-};
+}
 
 /**
  * Sets the cached fingerprint in local storage.
@@ -102,18 +117,26 @@ async function initFingerprint(
     customScriptEndpointArray.unshift(buildProxyUrl(proxyUrl));
   }
 
+  fingerprintAgentReady = false;
   window.fingerprintConfig = {};
-  window.fpClient = new FpjsClient({
+  const client = new FpjsClient({
     loadOptions: {
       apiKey,
       endpoint: customEndpointArray,
       scriptUrlPattern: customScriptEndpointArray,
     },
   });
+  window.fpClient = client;
 
   try {
-    await window.fpClient.init();
+    await client.init();
+    if (window.fpClient === client) {
+      fingerprintAgentReady = true;
+    }
   } catch (error) {
+    if (window.fpClient === client) {
+      fingerprintAgentReady = false;
+    }
     console.error('Error initializing identification service:', error);
     throw error;
   }
@@ -121,11 +144,26 @@ async function initFingerprint(
 
 /**
  * Retrieves the fingerprint, first checking the cache and then querying the identification service if not found.
+ * Returns an empty string when the Fingerprint agent has not loaded, so callers like identify() can continue.
  * @param {boolean} cacheOnly - Optional flag to retrieve the fingerprint only from the cache.
- * @returns {Promise<string>} A promise that resolves with the fingerprint.
- * @throws {Error} Throws an error if retrieval fails.
+ * @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);
+}
+
+/** Internal identify path with late-effect suppression and sanitized diagnostics. */
+export function getFingerprintForIdentify(
+  context: IdentifyStageContext,
+): Promise<string> {
+  return readFingerprint(false, context);
+}
+
+async function readFingerprint(
+  cacheOnly: boolean,
+  context?: IdentifyStageContext,
+): Promise<string> {
   if (!window.fingerprintConfig) {
     if (cacheOnly) {
       return '';
@@ -134,44 +172,87 @@ async function getFingerprint(cacheOnly = false): Promise<string> {
     throw new Error('Fingerprint configuration is not initialized.');
   }
 
-  const cachedFingerprint = getCachedFingerprint();
+  const cachedFingerprint = readCachedFingerprint(context);
   if (cachedFingerprint) {
     return cachedFingerprint;
   }
 
-  if (cacheOnly) {
+  if (cacheOnly || !isFingerprintReady()) {
     return '';
   }
 
+  const { visitorId } = await requestIdentification(false, context);
+  return visitorId;
+}
+
+/**
+ * Requests detailed visitor identification data from Fingerprint.
+ * @param {boolean} ignoreCache - Whether the Fingerprint SPA cache must be bypassed.
+ * @returns {Promise<FingerprintIdentification>} Request-scoped identification data.
+ * @throws {Error} If the identification service is not ready or retrieval fails.
+ */
+async function identifyVisitor(
+  ignoreCache = false,
+): Promise<FingerprintIdentification> {
+  return requestIdentification(ignoreCache);
+}
+
+async function requestIdentification(
+  ignoreCache: boolean,
+  context?: IdentifyStageContext,
+): Promise<FingerprintIdentification> {
   if (!isFingerprintReady()) {
     throw new Error('Identification service is not initialized.');
   }
 
   try {
-    const fpClient = window.fpClient;
-    const { visitorId: fingerprint } = await fpClient.getVisitorData();
-    setCachedFingerprint(fingerprint);
-    return fingerprint;
+    const result = await window.fpClient.getVisitorData({}, ignoreCache);
+    if (!context || context.isActive()) {
+      try {
+        setCachedFingerprint(result.visitorId);
+      } catch (error) {
+        if (!context) throw error;
+        context.report('cache', 'unavailable');
+      }
+      if (typeof result.visitorFound === 'boolean') {
+        try {
+          mixpanelService.setPeopleProperties({
+            'Visitor Found': result.visitorFound,
+          });
+        } catch (error) {
+          if (context) context.report('fingerprint', 'failed');
+          else console.error('Error updating Mixpanel visitor profile:', error);
+        }
+      }
+    }
+
+    return {
+      visitorId: result.visitorId,
+      requestId: result.requestId,
+      ...(typeof result.visitorFound === 'boolean'
+        ? { visitorFound: result.visitorFound }
+        : {}),
+      confidenceScore: result.confidence.score,
+      cacheHit: result.cacheHit,
+    };
   } catch (error) {
-    console.error('Error retrieving fingerprint:', error);
+    if (!context) console.error('Error retrieving fingerprint:', error);
     throw error;
   }
 }
 
 /**
- * Checks if the identification service is ready.
- *
- * This function verifies whether the identification service has been initialized
- * and is ready to use by checking if the `fpClient` instance exists on the window object.
- * @returns {boolean} Returns true if the identification service is ready, otherwise false.
+ * Checks if the Fingerprint agent finished loading and can identify visitors.
+ * @returns {boolean} True only after `initFingerprint()` has successfully loaded the agent.
  */
 function isFingerprintReady(): boolean {
-  return window.fpClient !== undefined;
+  return window.fpClient !== undefined && fingerprintAgentReady;
 }
 
 const fingerprintService = {
   initFingerprint,
   getFingerprint,
+  identifyVisitor,
   isFingerprintReady,
   getCachedFingerprint,
 };

package/src/services/mixpanel.test.ts

@@ -0,0 +1,160 @@
+import mixpanel from 'mixpanel-browser';
+import { version as mixpanelVersion } from 'mixpanel-browser/package.json';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+import { version } from '../../package.json';
+import mixpanelService from './mixpanel';
+
+interface TransportData {
+  event?: string;
+  properties?: Record<string, unknown>;
+}
+
+// Intercept transport only: identify, track, register, and property merging stay real.
+const transport = mixpanel as unknown as {
+  _track_or_batch(options: { data: TransportData }): TransportData;
+  stop_batch_senders(): void;
+};
+
+describe('Mixpanel SDK version metadata', () => {
+  beforeAll(async () => {
+    localStorage.clear();
+    await mixpanelService.init('test-sdk-version-token');
+    transport.stop_batch_senders();
+    mixpanel.set_config({ disable_persistence: true });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  afterAll(() => {
+    transport.stop_batch_senders();
+    localStorage.clear();
+  });
+
+  it('registers SDK metadata and propagates it to the native $identify event', () => {
+    expect(mixpanel.get_property('Event Source')).toBe('sdk');
+    expect(mixpanel.get_property('Reservamos Version')).toBe(version);
+
+    const send = vi
+      .spyOn(transport, '_track_or_batch')
+      .mockImplementation(({ data }) => data);
+
+    mixpanelService.identify('sdk-version-user', {});
+    const events = send.mock.calls
+      .map(([options]) => options.data)
+      .filter((data) => data.event);
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({
+      event: '$identify',
+      properties: expect.objectContaining({
+        'Event Source': 'sdk',
+        'Reservamos Version': version,
+        '$lib_version': mixpanelVersion,
+      }),
+    });
+
+    send.mockClear();
+    mixpanelService.identify('sdk-version-user', {});
+    expect(send.mock.calls.some(([options]) => options.data.event)).toBe(false);
+  });
+
+  it('keeps the SDK version authoritative for SDK-tracked events', () => {
+    const send = vi
+      .spyOn(transport, '_track_or_batch')
+      .mockImplementation(({ data }) => data);
+
+    mixpanelService.track('Test', { 'Reservamos Version': 'caller-version' });
+
+    expect(send.mock.calls[0][0].data).toEqual({
+      event: 'Test',
+      properties: expect.objectContaining({
+        'Event Source': 'sdk',
+        'Reservamos Version': version,
+      }),
+    });
+  });
+
+  it('still sets people properties when the SDK distinct ID cache is blocked', () => {
+    vi.spyOn(transport, '_track_or_batch').mockImplementation(
+      ({ data }) => data,
+    );
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+    const people = vi
+      .spyOn(mixpanel.people, 'set')
+      .mockImplementation(() => undefined);
+    mixpanelService.identify('cache-blocked-user', {});
+    expect(people).toHaveBeenCalledWith({});
+  });
+
+  it.each([
+    1,
+    0,
+    { status: 1, error: null },
+    { status: 0, error: 'private-id' },
+    -1,
+  ])(
+    'observes the people callback %j with controlled diagnostics',
+    (response) => {
+      vi.useFakeTimers();
+      vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+      vi.spyOn(transport, '_track_or_batch').mockImplementation(
+        ({ data }) => data,
+      );
+      let callback: ((response: unknown) => void) | undefined;
+      vi.spyOn(mixpanel.people, 'set').mockImplementation((...args) => {
+        callback = args[1] as (response: unknown) => void;
+      });
+      const report = vi.fn();
+      const schedule = vi.spyOn(globalThis, 'setTimeout');
+      const cancel = vi.spyOn(globalThis, 'clearTimeout');
+      mixpanelService.identify('callback-user', {}, report);
+      expect(schedule).toHaveBeenCalledWith(expect.any(Function), 5000);
+      const timeout = schedule.mock.results.at(-1)?.value;
+      callback?.(response);
+      expect(cancel).toHaveBeenCalledWith(timeout);
+      const status = typeof response === 'number' ? response : response.status;
+      if (status === 1) expect(report).not.toHaveBeenCalled();
+      else
+        expect(report).toHaveBeenCalledWith(
+          'people',
+          status === 0 ? 'failed' : 'unconfirmed',
+          undefined,
+        );
+      vi.advanceTimersByTime(5000);
+      expect(report).toHaveBeenCalledTimes(status === 1 ? 0 : 1);
+    },
+  );
+
+  it('reports missing people callback as unobserved and ignores a late result', () => {
+    vi.useFakeTimers();
+    vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+    vi.spyOn(transport, '_track_or_batch').mockImplementation(
+      ({ data }) => data,
+    );
+    let callback: ((response: unknown) => void) | undefined;
+    vi.spyOn(mixpanel.people, 'set').mockImplementation((...args) => {
+      callback = args[1] as (response: unknown) => void;
+    });
+    const report = vi.fn();
+    mixpanelService.identify('callback-user', {}, report);
+    vi.advanceTimersByTime(5000);
+    callback?.(0);
+    expect(report).toHaveBeenCalledOnce();
+    expect(report).toHaveBeenCalledWith('people', 'unobserved', undefined);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/services/mixpanel.ts

@@ -1,4 +1,6 @@
+import type { IdentifyReporter } from '@/util/identifyAttempt';
 import mixpanel from 'mixpanel-browser';
+import { observeIdentifyResult } from '@/util/identifyAttempt';
 import { version } from '../../package.json';
 
 declare global {
@@ -10,10 +12,11 @@ declare global {
 const MIXPANEL_DISTINCT_ID_CACHE_KEY = 'mp_distinct_id';
 
 /**
- * Super property sent on every Mixpanel event. Fixed SDK marker; not configurable via the public API.
+ * SDK metadata sent on every Mixpanel event, including native identification events.
  */
-const EVENT_SOURCE_SUPER_PROPERTY = {
+const SDK_SUPER_PROPERTIES = {
   'Event Source': 'sdk',
+  'Reservamos Version': version,
 } as const;
 
 /**
@@ -33,7 +36,7 @@ function init(
       debug,
       loaded: () => {
         window.mixpanel = mixpanel;
-        mixpanel.register({ ...EVENT_SOURCE_SUPER_PROPERTY });
+        mixpanel.register({ ...SDK_SUPER_PROPERTIES });
         resolve();
       },
       ...(proxyUrl && { api_host: proxyUrl }),
@@ -48,10 +51,32 @@ function init(
  * @returns {void}
  * @throws {Error} If Mixpanel is not initialized (handled internally).
  */
-function identify(userId: string, properties: Record<string, unknown>): void {
+function identify(
+  userId: string,
+  properties: Record<string, unknown>,
+  report?: IdentifyReporter,
+): void {
   mixpanel.identify(userId);
-  updateCachedDistinctId(userId);
-  mixpanel.people.set(properties);
+  try {
+    updateCachedDistinctId(userId);
+  } catch {
+    report?.('cache', 'unavailable');
+  }
+  if (!report) {
+    mixpanel.people.set(properties);
+    return;
+  }
+  const observer = observeIdentifyResult('people', report);
+  try {
+    mixpanel.people.set(properties, (response) => {
+      const status = typeof response === 'number' ? response : response?.status;
+      observer.complete(
+        status === 1 ? undefined : status === 0 ? 'failed' : 'unconfirmed',
+      );
+    });
+  } catch {
+    observer.complete('failed');
+  }
 }
 
 /**
@@ -100,6 +125,7 @@ function track(eventName: string, properties: Record<string, unknown>): void {
   if (!isReady()) {
     return;
   }
+  // Event properties override superproperties; keep the SDK version authoritative.
   mixpanel.track(eventName, { ...properties, 'Reservamos Version': version });
 }
 

package/src/track.test.ts

@@ -0,0 +1,156 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import botDetectionRelayService from '@/services/botDetectionRelay';
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import { trackEvent } from './track';
+
+vi.mock('@/services/botDetectionRelay', () => ({
+  default: {
+    isEnabledFor: vi.fn(),
+    relay: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+vi.mock('@/services/fingerprint', () => ({
+  default: {
+    getFingerprint: vi.fn(),
+    identifyVisitor: vi.fn(),
+    isFingerprintReady: vi.fn(),
+  },
+}));
+
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    getCoordinates: vi.fn().mockReturnValue(null),
+    getGeolocationSource: vi.fn().mockReturnValue(null),
+  },
+}));
+
+vi.mock('@/services/mixpanel', () => ({
+  default: {
+    isReady: vi.fn().mockReturnValue(true),
+    getMixpanelDistinctId: vi.fn().mockReturnValue('distinct-123'),
+    track: vi.fn(),
+  },
+}));
+
+vi.mock('@/services/validator', () => ({
+  default: {
+    parseEventProps: vi.fn(),
+  },
+}));
+
+describe('trackEvent Bot Detection relay', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(mixpanelService.isReady).mockReturnValue(true);
+    vi.mocked(mixpanelService.getMixpanelDistinctId).mockReturnValue(
+      'distinct-123',
+    );
+    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(true);
+  });
+
+  it('uses a fresh identification and relays a configured event', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
+    vi.mocked(fingerprintService.identifyVisitor).mockResolvedValue({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+
+    await trackEvent('Payment Attempt', { 'Payment Type': 'credit_card' });
+
+    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
+    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
+    expect(mixpanelService.track).toHaveBeenCalledWith('Payment Attempt', {
+      'User Fingerprint': 'visitor-123',
+      'Payment Type': 'credit_card',
+    });
+    expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+      requestId: 'request-123',
+      visitorId: 'visitor-123',
+      distinctId: 'distinct-123',
+      eventName: 'Payment Attempt',
+    });
+  });
+
+  it('reports a failed fresh identification without tracking or relaying the configured event', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
+    vi.mocked(fingerprintService.identifyVisitor).mockRejectedValue(
+      new Error('Fingerprint identification failed'),
+    );
+    const eventProperties = { 'Payment Type': 'credit_card' };
+
+    await trackEvent('Payment Attempt', eventProperties);
+
+    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
+    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
+    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+    expect(mixpanelService.track).toHaveBeenCalledTimes(1);
+    expect(mixpanelService.track).toHaveBeenCalledWith('Track Event Error', {
+      'Failed Event Name': 'Payment Attempt',
+      'Error Message': 'Fingerprint identification failed',
+      'Validation Errors': [],
+      'Event Payload': eventProperties,
+    });
+  });
+
+  it('preserves existing fingerprint behavior for an unconfigured event', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(false);
+    vi.mocked(fingerprintService.getFingerprint).mockResolvedValue(
+      'cached-visitor',
+    );
+
+    await trackEvent('Payment Attempt', { 'Payment Type': 'credit_card' });
+
+    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(true);
+    expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
+    expect(mixpanelService.track).toHaveBeenCalledWith('Payment Attempt', {
+      'User Fingerprint': 'cached-visitor',
+      'Payment Type': 'credit_card',
+    });
+    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  });
+
+  it('uses a fresh identification and relays Search', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
+    vi.mocked(fingerprintService.identifyVisitor).mockResolvedValue({
+      visitorId: 'visitor-123',
+      requestId: 'search-request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+
+    await trackEvent('Search', {});
+
+    expect(fingerprintService.identifyVisitor).toHaveBeenCalledWith(true);
+    expect(fingerprintService.getFingerprint).not.toHaveBeenCalled();
+    expect(mixpanelService.track).toHaveBeenCalledWith('Search', {
+      'User Fingerprint': 'visitor-123',
+    });
+    expect(botDetectionRelayService.relay).toHaveBeenCalledWith({
+      requestId: 'search-request-123',
+      visitorId: 'visitor-123',
+      distinctId: 'distinct-123',
+      eventName: 'Search',
+    });
+  });
+
+  it('tracks Search without a relay when Fingerprint is not ready', async () => {
+    vi.mocked(botDetectionRelayService.isEnabledFor).mockReturnValue(true);
+    vi.mocked(fingerprintService.isFingerprintReady).mockReturnValue(false);
+    vi.mocked(fingerprintService.getFingerprint).mockResolvedValue('');
+
+    await trackEvent('Search', {});
+
+    expect(fingerprintService.identifyVisitor).not.toHaveBeenCalled();
+    expect(fingerprintService.getFingerprint).toHaveBeenCalledWith(false);
+    expect(mixpanelService.track).toHaveBeenCalledWith('Search', {
+      'User Fingerprint': '',
+    });
+    expect(botDetectionRelayService.relay).not.toHaveBeenCalled();
+  });
+});

package/src/track.ts

@@ -3,6 +3,7 @@ import type {
   EventData,
   EventMetadata,
 } from './types/eventData';
+import botDetectionRelayService from '@/services/botDetectionRelay';
 import fingerprintService from '@/services/fingerprint';
 import geolocationService from '@/services/geolocation';
 import mixpanelService from '@/services/mixpanel';
@@ -117,12 +118,21 @@ export async function trackEvent(
 
   try {
     validator.parseEventProps(eventName, eventProperties);
-    const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
-
     // Call the Mixpanel service to store the distinct ID in the cache
-    mixpanelService.getMixpanelDistinctId();
-
-    const fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+    const distinctId = mixpanelService.getMixpanelDistinctId();
+    const botDetectionEnabled =
+      botDetectionRelayService.isEnabledFor(eventName);
+    let fingerprint: string;
+    let fingerprintRequestId: string | undefined;
+
+    if (botDetectionEnabled && fingerprintService.isFingerprintReady()) {
+      const identification = await fingerprintService.identifyVisitor(true);
+      fingerprint = identification.visitorId;
+      fingerprintRequestId = identification.requestId;
+    } else {
+      const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
+      fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+    }
     const defaultCoordinates: Record<string, string | number> = {};
     const coordinates = geolocationService.getCoordinates();
     const geolocationSource = geolocationService.getGeolocationSource();
@@ -148,6 +158,15 @@ export async function trackEvent(
     };
 
     mixpanelService.track(eventName, properties);
+
+    if (fingerprintRequestId) {
+      void botDetectionRelayService.relay({
+        requestId: fingerprintRequestId,
+        visitorId: fingerprint,
+        ...(distinctId && { distinctId }),
+        eventName,
+      });
+    }
   } catch (error) {
     console.error(`Error tracking event '${eventName}':`, error);
     trackEventError(eventName, error, eventProperties);

package/src/types/botDetection.ts

@@ -0,0 +1,16 @@
+interface FingerprintIdentification {
+  visitorId: string;
+  requestId: string;
+  visitorFound?: boolean;
+  confidenceScore: number;
+  cacheHit: boolean;
+}
+
+interface BotDetectionRelayPayload {
+  requestId: string;
+  visitorId: string;
+  distinctId?: string;
+  eventName: string;
+}
+
+export type { BotDetectionRelayPayload, FingerprintIdentification };