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

package/src/services/fingerprint.ts

@@ -30,7 +30,16 @@ const PROXY_QUERY_PARAM =
  */
 let fingerprintAgentReady = false;
 let initialization = 0;
+let startedInitialization = -1;
 const readinessSubscribers = new Set<() => void>();
+const waitingConsumers = new Set<() => void>();
+let pendingIdentification:
+  | {
+      promise: Promise<FingerprintIdentification>;
+      contexts: Set<IdentifyStageContext | undefined>;
+      isCurrent: () => boolean;
+    }
+  | undefined;
 
 /** Notifies deferred observations only when the actual provider agent has loaded. */
 function onReady(notify: () => void): () => void {
@@ -44,6 +53,8 @@ function onReady(notify: () => void): () => void {
 function invalidate(): void {
   initialization++;
   fingerprintAgentReady = false;
+  pendingIdentification = undefined;
+  waitingConsumers.forEach((cancel) => cancel());
 }
 
 /**
@@ -133,7 +144,8 @@ async function initFingerprint(
     customScriptEndpointArray.unshift(buildProxyUrl(proxyUrl));
   }
 
-  invalidate();
+  if (startedInitialization === initialization) invalidate();
+  startedInitialization = initialization;
   const attempt = initialization;
   window.fingerprintConfig = {};
   const client = new FpjsClient({
@@ -154,6 +166,7 @@ async function initFingerprint(
   } catch (error) {
     if (window.fpClient === client && attempt === initialization) {
       fingerprintAgentReady = false;
+      waitingConsumers.forEach((cancel) => cancel());
     }
     console.error('Error initializing identification service:', error);
     throw error;
@@ -214,6 +227,50 @@ async function identifyVisitor(
 async function requestIdentification(
   ignoreCache: boolean,
   context?: IdentifyStageContext,
+): Promise<FingerprintIdentification> {
+  if (!ignoreCache && pendingIdentification?.isCurrent()) {
+    for (const participant of pendingIdentification.contexts) {
+      if (participant && !participant.isActive())
+        pendingIdentification.contexts.delete(participant);
+    }
+    pendingIdentification.contexts.add(context);
+    return pendingIdentification.promise;
+  }
+  const contexts = new Set([context]);
+  const attempt = initialization;
+  const currentLifecycle = trackingLifecycle.capture();
+  const isCurrent = () => attempt === initialization && currentLifecycle();
+  const sharedContext: IdentifyStageContext = {
+    isActive: () =>
+      isCurrent() &&
+      [...contexts].some(
+        (participant) => !participant || participant.isActive(),
+      ),
+    report: (...args) => {
+      for (const participant of contexts) {
+        if (participant?.isActive()) participant.report(...args);
+      }
+    },
+  };
+  const request = {
+    contexts,
+    isCurrent,
+    promise: performIdentification(ignoreCache, sharedContext, () =>
+      contexts.has(undefined),
+    ),
+  };
+  pendingIdentification = request;
+  const clear = () => {
+    if (pendingIdentification === request) pendingIdentification = undefined;
+  };
+  void request.promise.then(clear, clear);
+  return request.promise;
+}
+
+async function performIdentification(
+  ignoreCache: boolean,
+  context: IdentifyStageContext,
+  hasUnscopedConsumer: () => boolean,
 ): Promise<FingerprintIdentification> {
   if (!isFingerprintReady()) {
     throw new Error('Identification service is not initialized.');
@@ -221,7 +278,7 @@ async function requestIdentification(
 
   try {
     const result = await window.fpClient.getVisitorData({}, ignoreCache);
-    if (!context || context.isActive()) {
+    if (context.isActive()) {
       try {
         setCachedFingerprint(result.visitorId);
       } catch {
@@ -233,8 +290,9 @@ async function requestIdentification(
             'Visitor Found': result.visitorFound,
           });
         } catch (error) {
-          if (context) context.report('fingerprint', 'failed');
-          else console.error('Error updating Mixpanel visitor profile:', error);
+          context.report('fingerprint', 'failed');
+          if (hasUnscopedConsumer())
+            console.error('Error updating Mixpanel visitor profile:', error);
         }
       }
     }
@@ -249,11 +307,53 @@ async function requestIdentification(
       cacheHit: result.cacheHit,
     };
   } catch (error) {
-    if (!context) console.error('Error retrieving fingerprint:', error);
+    if (hasUnscopedConsumer())
+      console.error('Error retrieving fingerprint:', error);
     throw error;
   }
 }
 
+/**
+ * Waits for cached or in-flight identity without forcing a fresh provider request.
+ * @param {number} timeoutMs - Maximum wait in milliseconds; defaults to 2000.
+ * @returns {Promise<string | null>} Visitor ID, or null when unavailable within the budget.
+ */
+function waitForFingerprintId(timeoutMs = 2000): Promise<string | null> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 2147483647)
+    return Promise.resolve(null);
+  const cached = getCachedFingerprint();
+  if (cached) return Promise.resolve(cached);
+  return new Promise((resolve) => {
+    let active = true;
+    let started = false;
+    const finish = (visitorId: string | null) => {
+      if (!active) return;
+      active = false;
+      clearTimeout(timer);
+      stopReady();
+      stopLifecycle();
+      waitingConsumers.delete(cancel);
+      resolve(visitorId);
+    };
+    const cancel = () => finish(null);
+    const start = () => {
+      if (!active || started || !isFingerprintReady()) return;
+      started = true;
+      const identity = getFingerprint(false, {
+        // Caller timeout ends waiting; the shared request still checks its lifecycle.
+        isActive: () => true,
+        report: () => undefined,
+      });
+      void identity.then((visitorId) => finish(visitorId || null), cancel);
+    };
+    const timer = setTimeout(cancel, timeoutMs);
+    const stopReady = onReady(start);
+    const stopLifecycle = trackingLifecycle.onChange(cancel);
+    waitingConsumers.add(cancel);
+    start();
+  });
+}
+
 /**
  * Checks if the Fingerprint agent finished loading and can identify visitors.
  * @returns {boolean} True only after `initFingerprint()` has successfully loaded the agent.
@@ -270,6 +370,7 @@ const fingerprintService = {
   onReady,
   invalidate,
   getCachedFingerprint,
+  waitForFingerprintId,
 };
 
 // One module-lifetime listener invalidates the old agent before Mixpanel signals readiness.

package/src/services/fingerprint.wait.integration.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import identify from '@/events/identify';
+import init from '@/init';
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
+import { trackEvent } from '@/track';
+
+const mocks = vi.hoisted(() => ({ load: vi.fn(), get: vi.fn() }));
+const visitor = {
+  visitorId: 'shared-visitor',
+  requestId: 'request',
+  visitorFound: true,
+  confidence: { score: 1 },
+  cacheHit: false,
+};
+vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
+  FingerprintJSPro: {
+    defaultEndpoint: 'https://fp.test',
+    defaultScriptUrlPattern: 'https://fp.test/agent',
+  },
+  FpjsClient: vi.fn(() => ({ init: mocks.load, getVisitorData: mocks.get })),
+}));
+vi.mock('@reservamos/js-api-client/core', () => ({
+  default: {
+    setConfig: vi.fn(),
+    profiles: { createAnonymousProfile: vi.fn().mockResolvedValue(undefined) },
+  },
+}));
+vi.mock('@/services/config', () => ({
+  default: {
+    setEnvironment: vi.fn(),
+    setAppName: vi.fn(),
+    getCoreAPIConfig: vi
+      .fn()
+      .mockReturnValue({ baseUrl: 'https://core.test', defaultHeaders: {} }),
+  },
+}));
+vi.mock('@/services/geolocation', () => ({
+  default: {
+    init: vi.fn().mockResolvedValue(undefined),
+    getCoordinates: vi.fn().mockReturnValue(null),
+    getGeolocationSource: vi.fn().mockReturnValue(null),
+  },
+}));
+vi.mock('@/services/mixpanel', () => ({
+  default: {
+    validateConfiguration: vi.fn(),
+    init: vi.fn(async () => {
+      trackingLifecycle.beginInitialization();
+    }),
+    isReady: vi.fn().mockReturnValue(true),
+    identify: vi.fn((user: string) => trackingLifecycle.identify(user)),
+    setPeopleProperties: vi.fn(),
+    attachProperty: vi.fn(),
+    getMixpanelDistinctId: vi.fn().mockReturnValue('user'),
+    track: vi.fn(),
+  },
+}));
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.clearAllMocks();
+  localStorage.clear();
+  mocks.load.mockResolvedValue(undefined);
+  mocks.get.mockResolvedValue(visitor);
+});
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+  localStorage.clear();
+});
+
+it('preserves a waiter registered by Tracker Ready during that same initialization', async () => {
+  let loaded!: () => void;
+  mocks.load.mockReturnValue(
+    new Promise<void>((resolve) => {
+      loaded = resolve;
+    }),
+  );
+  let waiting: Promise<string | null> | undefined;
+  let settled = false;
+  window.addEventListener(
+    'Tracker Ready',
+    () => {
+      waiting = fingerprintService.waitForFingerprintId(1000).then((value) => {
+        settled = true;
+        return value;
+      });
+    },
+    { once: true },
+  );
+  const initialization = init({
+    mixpanelToken: 'test',
+    identificationKey: 'test',
+  });
+  await vi.advanceTimersByTimeAsync(0);
+  expect(waiting).toBeDefined();
+  expect(settled).toBe(false);
+  loaded();
+  await initialization;
+  await expect(waiting).resolves.toBe('shared-visitor');
+  expect(mocks.get).toHaveBeenCalledTimes(1);
+});
+
+it('keeps cache and profile effects for a current Identify joining a superseded request', async () => {
+  await init({ mixpanelToken: 'test', identificationKey: 'test' });
+  let finish!: (value: typeof visitor) => void;
+  mocks.get.mockReturnValue(
+    new Promise((resolve) => {
+      finish = resolve;
+    }),
+  );
+  await identify('user', { email: 'test@example.com' });
+  await identify('user', { email: 'test@example.com' });
+  finish(visitor);
+  await vi.advanceTimersByTimeAsync(0);
+  expect(mocks.get).toHaveBeenCalledTimes(1);
+  expect(fingerprintService.getCachedFingerprint()).toBe('shared-visitor');
+  expect(mixpanelService.setPeopleProperties).toHaveBeenCalledWith({
+    'Visitor Found': true,
+  });
+  expect(mixpanelService.attachProperty).toHaveBeenCalledTimes(1);
+  await trackEvent('Cache Check', { step: 'after identify' });
+  expect(mixpanelService.track).toHaveBeenCalledWith(
+    'Cache Check',
+    expect.objectContaining({ 'User Fingerprint': 'shared-visitor' }),
+  );
+});

package/src/services/mixpanel.batch.test.ts

@@ -0,0 +1,108 @@
+import mixpanel from 'mixpanel-browser';
+import { afterAll, beforeAll, expect, it, vi } from 'vitest';
+import mixpanelService from './mixpanel';
+
+interface BatchPayload {
+  event?: string;
+  properties?: Record<string, unknown>;
+  $distinct_id?: string;
+  $set?: Record<string, unknown>;
+}
+
+// Keep the real identity handling, batching, storage, and timers; replace HTTP only.
+const transport = mixpanel as unknown as {
+  _send_request(
+    url: string,
+    data: { data: string },
+    options: object,
+    callback?: (response: number) => void,
+  ): boolean;
+  stop_batch_senders(): void;
+  _flags: { identify_called: boolean };
+};
+const batches: { url: string; payload: BatchPayload[] }[] = [];
+
+beforeAll(async () => {
+  vi.useFakeTimers();
+  localStorage.clear();
+  await mixpanelService.init('one-second-batching-token');
+  vi.spyOn(transport, '_send_request').mockImplementation(
+    (url, data, _options, callback) => {
+      if (url.endsWith('/track/') || url.endsWith('/engage/')) {
+        batches.push({
+          url,
+          payload: JSON.parse(data.data) as BatchPayload[],
+        });
+      }
+      callback?.(1);
+      return true;
+    },
+  );
+});
+
+afterAll(() => {
+  transport.stop_batch_senders();
+  vi.restoreAllMocks();
+  vi.clearAllTimers();
+  vi.useRealTimers();
+  localStorage.clear();
+});
+
+it('batches native identity and people updates within one second', async () => {
+  mixpanelService.identify('redirect-user', { $email: 'redirect@example.com' });
+
+  await vi.advanceTimersByTimeAsync(999);
+  expect(batches).toEqual([]);
+
+  await vi.advanceTimersByTimeAsync(1);
+  expect(batches).toHaveLength(2);
+  expect(batches.find(({ url }) => url.endsWith('/track/'))?.payload).toEqual([
+    expect.objectContaining({
+      event: '$identify',
+      properties: expect.objectContaining({ distinct_id: 'redirect-user' }),
+    }),
+  ]);
+  expect(
+    batches.find(({ url }) => url.endsWith('/engage/'))?.payload,
+  ).toContainEqual(
+    expect.objectContaining({
+      $distinct_id: 'redirect-user',
+      $set: expect.objectContaining({ $email: 'redirect@example.com' }),
+    }),
+  );
+});
+
+it('restores people readiness for the unchanged user without another native identity event', async () => {
+  mixpanelService.identify('restored-user', {});
+  await vi.advanceTimersByTimeAsync(1000);
+  batches.length = 0;
+  transport._flags.identify_called = false;
+  const accepted = vi.fn();
+  const report = vi.fn();
+
+  mixpanelService.restorePeopleProperties(
+    'other-user',
+    { reservamos_one_id: 'wrong' },
+    report,
+    accepted,
+  );
+  expect(accepted).not.toHaveBeenCalled();
+
+  mixpanelService.restorePeopleProperties(
+    'restored-user',
+    { reservamos_one_id: 42 },
+    report,
+    accepted,
+  );
+  expect(accepted).toHaveBeenCalledTimes(1);
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(batches).toHaveLength(1);
+  expect(batches[0].url).toContain('/engage/');
+  expect(batches[0].payload).toContainEqual(
+    expect.objectContaining({
+      $distinct_id: 'restored-user',
+      $set: expect.objectContaining({ reservamos_one_id: 42 }),
+    }),
+  );
+  expect(report).not.toHaveBeenCalled();
+});

package/src/services/mixpanel.test.ts

@@ -1,5 +1,4 @@
 import mixpanel from 'mixpanel-browser';
-import { version as mixpanelVersion } from 'mixpanel-browser/package.json';
 import {
   afterAll,
   afterEach,
@@ -13,23 +12,61 @@ import { trackEvent } from '@/track';
 import { version } from '../../package.json';
 import mixpanelService from './mixpanel';
 
-interface TransportData {
-  event?: string;
-  properties?: Record<string, unknown>;
-}
+const { provider } = vi.hoisted(() => ({
+  provider: {
+    init: vi.fn((_token: string, config: { loaded: () => void }) =>
+      config.loaded(),
+    ),
+    register: vi.fn(),
+    set_config: vi.fn(),
+    identify: vi.fn(),
+    track: vi.fn(),
+    get_distinct_id: vi.fn(() => 'live-id'),
+    people: { set: vi.fn(), union: vi.fn() },
+  },
+}));
 
-// 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;
-};
+// Exercise SDK service methods while replacing the vendor before initialization.
+vi.mock('mixpanel-browser', () => ({ default: provider }));
+
+describe('distinct ID lookup before initialization', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    localStorage.clear();
+  });
+
+  it.each(['cached', 'empty', 'blocked'])(
+    'uses the %s cache without calling the uninitialized provider',
+    (mode) => {
+      const previous = window.mixpanel;
+      Reflect.deleteProperty(window, 'mixpanel');
+      const lookup = vi
+        .spyOn(mixpanel, 'get_distinct_id')
+        .mockImplementation(() => {
+          throw new Error('Provider persistence is not initialized');
+        });
+      if (mode === 'cached')
+        localStorage.setItem('mp_distinct_id', 'cached-id');
+      if (mode === 'blocked')
+        vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+          throw new DOMException('Blocked', 'SecurityError');
+        });
+      try {
+        expect(mixpanelService.getMixpanelDistinctId()).toBe(
+          mode === 'cached' ? 'cached-id' : null,
+        );
+        expect(lookup).not.toHaveBeenCalled();
+      } finally {
+        if (previous) window.mixpanel = previous;
+      }
+    },
+  );
+});
 
 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(() => {
@@ -37,54 +74,30 @@ describe('Mixpanel SDK version metadata', () => {
     vi.unstubAllGlobals();
     vi.clearAllTimers();
     vi.useRealTimers();
+    vi.clearAllMocks();
   });
 
   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,
-      }),
+  it('registers SDK metadata before identifying at the provider boundary', () => {
+    expect(mixpanel.register).toHaveBeenCalledWith({
+      'Event Source': 'sdk',
+      'Reservamos Version': version,
     });
-
-    send.mockClear();
+    expect(mixpanel.register).not.toHaveBeenCalledWith(
+      expect.objectContaining({ $lib_version: expect.anything() }),
+    );
     mixpanelService.identify('sdk-version-user', {});
-    expect(send.mock.calls.some(([options]) => options.data.event)).toBe(false);
+    expect(mixpanel.identify).toHaveBeenCalledWith('sdk-version-user');
+    expect(mixpanel.people.set).toHaveBeenCalledWith({});
   });
 
   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,
-      }),
+    expect(mixpanel.track).toHaveBeenCalledWith('Test', {
+      'Reservamos Version': version,
     });
   });
 
@@ -104,17 +117,12 @@ describe('Mixpanel SDK version metadata', () => {
   });
 
   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({});
+    expect(mixpanel.identify).toHaveBeenCalledWith('cache-blocked-user');
+    expect(mixpanel.people.set).toHaveBeenCalledWith({});
   });
 
   it.each(['getItem', 'setItem'] as const)(
@@ -131,31 +139,33 @@ describe('Mixpanel SDK version metadata', () => {
   it.each(['getItem', 'setItem'] as const)(
     'submits the original event when SDK storage %s is blocked',
     async (method) => {
-      const send = vi
-        .spyOn(transport, '_track_or_batch')
-        .mockImplementation(({ data }) => data);
-      mixpanel.identify('storage-test-id');
-      send.mockClear();
+      vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('storage-test-id');
       vi.spyOn(Storage.prototype, method).mockImplementation(() => {
         throw new DOMException('Blocked', 'SecurityError');
       });
       await trackEvent('Storage Failure Test', { source: 'checkout' });
-      expect(send.mock.calls.map(([options]) => options.data)).toContainEqual({
-        event: 'Storage Failure Test',
-        properties: expect.objectContaining({
-          source: 'checkout',
-          distinct_id: 'storage-test-id',
+      expect(mixpanel.track).toHaveBeenCalledWith(
+        'Storage Failure Test',
+        expect.objectContaining({
+          'source': 'checkout',
+          'Reservamos Version': version,
         }),
-      });
+      );
+      expect(mixpanelService.getMixpanelDistinctId()).toBe('storage-test-id');
     },
   );
 
-  it('returns null when no live distinct ID is available and the cache is blocked', () => {
+  it('submits the original event when no live distinct ID is available and the cache is blocked', async () => {
     vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('');
     vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
       throw new DOMException('Blocked', 'SecurityError');
     });
     expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
+    await trackEvent('Storage Failure Test', { source: 'checkout' });
+    expect(mixpanel.track).toHaveBeenCalledWith(
+      'Storage Failure Test',
+      expect.objectContaining({ source: 'checkout' }),
+    );
   });
 
   it('uses the live distinct ID first and null fallback when localStorage is null', () => {
@@ -214,9 +224,6 @@ describe('Mixpanel SDK version metadata', () => {
     (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;
@@ -245,9 +252,6 @@ describe('Mixpanel SDK version metadata', () => {
   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;