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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.7",
+  "version": "1.1.8-alpha.0",
   "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/init.test.ts

@@ -0,0 +1,287 @@
+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,
+    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

@@ -15,7 +15,7 @@ export type InitConfig = z.infer<typeof InitConfigSchema>;
  * 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 +24,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) {
@@ -41,17 +42,6 @@ async function init(config: InitConfig) {
 
   await mixpanelService.init(mixpanelToken, debug, mixpanelProxyUrl);
 
-  try {
-    await fingerprintService.initFingerprint(
-      identificationKey,
-      identifyProxyUrl,
-    );
-  } catch (error) {
-    console.error('Error initializing identification service:', error);
-  }
-
-  await geolocationService.init();
-
   configService.setEnvironment(isSandbox ? 'sandbox' : 'prod');
   if (appName) {
     configService.setAppName(appName);
@@ -60,6 +50,38 @@ async function init(config: InitConfig) {
 
   // Dispatch the 'Tracker Ready' event
   onLoaded();
+
+  await Promise.all([
+    initializeOptionalStage('fingerprint', () =>
+      fingerprintService.initFingerprint(identificationKey, identifyProxyUrl),
+    ),
+    initializeOptionalStage('geolocation', () => geolocationService.init()),
+  ]);
+}
+
+/** 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/fingerprint.test.ts

@@ -65,6 +65,24 @@ describe('fingerprintService', () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([null, 'cached-visitor'])(
+    'reads the default cache before fingerprint configuration exists: %s',
+    (visitorId) => {
+      Reflect.deleteProperty(window, 'fingerprintConfig');
+      if (visitorId) {
+        localStorage.setItem(
+          'default_fingerprint_cache',
+          JSON.stringify({
+            fingerprint: visitorId,
+            expiresAt: Date.now() + 60_000,
+          }),
+        );
+      }
+      expect(fingerprintService.getCachedFingerprint()).toBe(visitorId);
+      expect(getVisitorDataMock).not.toHaveBeenCalled();
+    },
+  );
+
   it('omits unavailable Visitor Found metadata without blocking identification', async () => {
     getVisitorDataMock.mockResolvedValue({
       ...visitorData,

package/src/services/fingerprint.ts

@@ -51,9 +51,8 @@ const getCachedFingerprint = (): string | null => {
 };
 
 function readCachedFingerprint(context?: IdentifyStageContext): string | null {
-  const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig;
-
   try {
+    const { cacheName = DEFAULT_CACHE_NAME } = window.fingerprintConfig ?? {};
     const cachedData = JSON.parse(localStorage.getItem(cacheName) || 'null');
     if (cachedData && cachedData.expiresAt > Date.now()) {
       return cachedData.fingerprint;
@@ -164,20 +163,12 @@ async function readFingerprint(
   cacheOnly: boolean,
   context?: IdentifyStageContext,
 ): Promise<string> {
-  if (!window.fingerprintConfig) {
-    if (cacheOnly) {
-      return '';
-    }
-
-    throw new Error('Fingerprint configuration is not initialized.');
-  }
-
   const cachedFingerprint = readCachedFingerprint(context);
   if (cachedFingerprint) {
     return cachedFingerprint;
   }
 
-  if (cacheOnly || !isFingerprintReady()) {
+  if (cacheOnly || !window.fingerprintConfig || !isFingerprintReady()) {
     return '';
   }
 

package/src/services/mixpanel.test.ts

@@ -9,6 +9,7 @@ import {
   it,
   vi,
 } from 'vitest';
+import { trackEvent } from '@/track';
 import { version } from '../../package.json';
 import mixpanelService from './mixpanel';
 
@@ -100,6 +101,66 @@ describe('Mixpanel SDK version metadata', () => {
     expect(people).toHaveBeenCalledWith({});
   });
 
+  it.each(['getItem', 'setItem'] as const)(
+    'keeps the live distinct ID when SDK storage %s fails',
+    (method) => {
+      vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('live-id');
+      vi.spyOn(Storage.prototype, method).mockImplementation(() => {
+        throw new DOMException('Blocked', 'SecurityError');
+      });
+      expect(mixpanelService.getMixpanelDistinctId()).toBe('live-id');
+    },
+  );
+
+  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(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',
+        }),
+      });
+    },
+  );
+
+  it('returns null when no live distinct ID is available and the cache is blocked', () => {
+    vi.spyOn(mixpanel, 'get_distinct_id').mockReturnValue('');
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+    expect(mixpanelService.getMixpanelDistinctId()).toBeNull();
+  });
+
+  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('');
+    expect(mixpanelService.getMixpanelDistinctId()).toBe('cached-id');
+  });
+
+  it('preserves identify cache diagnostics and people updates on a write failure', () => {
+    vi.spyOn(mixpanel, 'identify').mockImplementation(() => undefined);
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('Blocked', 'SecurityError');
+    });
+    vi.spyOn(mixpanel.people, 'set').mockImplementation(() => undefined);
+    vi.useFakeTimers();
+    const report = vi.fn();
+    mixpanelService.identify('user-id', {}, report);
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(mixpanel.people.set).toHaveBeenCalled();
+  });
+
   it.each([
     1,
     0,

package/src/services/mixpanel.ts

@@ -57,11 +57,7 @@ function identify(
   report?: IdentifyReporter,
 ): void {
   mixpanel.identify(userId);
-  try {
-    updateCachedDistinctId(userId);
-  } catch {
-    report?.('cache', 'unavailable');
-  }
+  if (!updateCachedDistinctId(userId)) report?.('cache', 'unavailable');
   if (!report) {
     mixpanel.people.set(properties);
     return;
@@ -136,26 +132,30 @@ function track(eventName: string, properties: Record<string, unknown>): void {
  * @returns {string | null} The distinct ID if available, or null if Mixpanel is not initialized.
  */
 export const getMixpanelDistinctId = (): string | null => {
-  const cachedId = localStorage.getItem(MIXPANEL_DISTINCT_ID_CACHE_KEY);
-
-  if (mixpanel && mixpanel.get_distinct_id) {
-    const distinctId = mixpanel.get_distinct_id();
-
+  const distinctId = mixpanel?.get_distinct_id?.();
+  if (distinctId) {
     updateCachedDistinctId(distinctId);
-
     return distinctId;
-  } else if (cachedId) {
-    return cachedId;
   }
-  return null;
+
+  try {
+    return localStorage.getItem(MIXPANEL_DISTINCT_ID_CACHE_KEY);
+  } catch {
+    return 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
  */
-function updateCachedDistinctId(distinctId: string): void {
-  localStorage.setItem(MIXPANEL_DISTINCT_ID_CACHE_KEY, distinctId);
+function updateCachedDistinctId(distinctId: string): boolean {
+  try {
+    localStorage.setItem(MIXPANEL_DISTINCT_ID_CACHE_KEY, distinctId);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 const mixpanelService = {