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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "1.1.7-alpha.1",
+  "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",
@@ -74,6 +74,7 @@
   "devDependencies": {
     "@eslint/js": "^9.9.1",
     "@ianvs/prettier-plugin-sort-imports": "^4.3.1",
+    "@reservamos/js-api-client": "6.28.0",
     "@types/eslint__js": "^8.42.3",
     "@types/jsdom": "^21.1.6",
     "@types/mixpanel-browser": "^2.50.0",
@@ -93,7 +94,6 @@
     "typescript-eslint": "^8.4.0",
     "upgradeps": "^2.0.6",
     "vite": "^5.0.12",
-    "vitest": "^1.2.1",
-    "@reservamos/js-api-client": "6.0.1"
+    "vitest": "^1.2.1"
   }
 }

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/botDetectionRelay.test.ts

@@ -1,13 +1,7 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import configService from '@/services/config';
+import coreApi from '@reservamos/js-api-client/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import botDetectionRelayService from './botDetectionRelay';
 
-vi.mock('@/services/config', () => ({
-  default: {
-    getCoreAPIConfig: vi.fn(),
-  },
-}));
-
 const payload = {
   requestId: 'request-123',
   visitorId: 'visitor-123',
@@ -27,7 +21,13 @@ const coreApiConfig = {
 describe('botDetectionRelayService', () => {
   beforeEach(() => {
     vi.unstubAllGlobals();
-    vi.mocked(configService.getCoreAPIConfig).mockReturnValue(coreApiConfig);
+    coreApi.setConfig(coreApiConfig);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
   });
 
   it('enables only the SDK-owned Bot Detection events', () => {
@@ -42,8 +42,8 @@ describe('botDetectionRelayService', () => {
     ).toBe(false);
   });
 
-  it('posts the payload to the Core API fingerprint path with keepalive', async () => {
-    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+  it('sends an observation through the configured client', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 202 });
     vi.stubGlobal('fetch', fetchMock);
 
     await botDetectionRelayService.relay(payload);
@@ -55,32 +55,37 @@ describe('botDetectionRelayService', () => {
         headers: {
           'Content-Type': 'application/json',
           'x-app-name': 'reservamos-web',
+          'Authorization': 'Bearer test-token',
         },
-        body: JSON.stringify(payload),
-        keepalive: true,
+        body: JSON.stringify({
+          requestId: payload.requestId,
+          visitorId: payload.visitorId,
+          distinctId: payload.distinctId,
+          eventName: 'Fingerprint Requested',
+        }),
+        signal: expect.any(AbortSignal),
       },
     );
   });
 
-  it('omits x-app-name when it is not in the core API config', async () => {
-    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+  it('omits distinctId when unavailable', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 202 });
     vi.stubGlobal('fetch', fetchMock);
-    vi.mocked(configService.getCoreAPIConfig).mockReturnValue({
-      baseUrl: 'https://datalake-api-dev.reservamossaas.com/api',
-      defaultHeaders: {
-        Authorization: 'Bearer test-token',
-        Origin: 'https://example.com',
-      },
-    });
 
-    await botDetectionRelayService.relay(payload);
+    await botDetectionRelayService.relay({
+      requestId: payload.requestId,
+      visitorId: payload.visitorId,
+      eventName: 'Search',
+    });
 
     expect(fetchMock).toHaveBeenCalledWith(
-      'https://datalake-api-dev.reservamossaas.com/api/v1/fingerprint/bot-detection',
+      expect.any(String),
       expect.objectContaining({
-        headers: {
-          'Content-Type': 'application/json',
-        },
+        body: JSON.stringify({
+          requestId: payload.requestId,
+          visitorId: payload.visitorId,
+          eventName: 'Fingerprint Requested',
+        }),
       }),
     );
   });
@@ -97,7 +102,7 @@ describe('botDetectionRelayService', () => {
     ).resolves.toBeUndefined();
     expect(consoleError).toHaveBeenCalledWith(
       'Error relaying Fingerprint identification:',
-      error,
+      { httpStatus: null, reason: 'network_or_cors' },
     );
 
     consoleError.mockRestore();
@@ -117,11 +122,33 @@ describe('botDetectionRelayService', () => {
     ).resolves.toBeUndefined();
     expect(consoleError).toHaveBeenCalledWith(
       'Error relaying Fingerprint identification:',
-      expect.objectContaining({
-        message: 'Bot Detection relay failed with status 503',
-      }),
+      { httpStatus: 503, reason: 'service_unavailable' },
     );
 
     consoleError.mockRestore();
   });
+
+  it('contains client timeouts and reports a sanitized diagnostic', async () => {
+    vi.useFakeTimers();
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    const fetchMock = vi.fn(
+      (_url: string, { signal }: { signal: AbortSignal }) =>
+        new Promise<Response>((_resolve, reject) => {
+          signal.addEventListener('abort', () => reject(new Error('Aborted')));
+        }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const attempt = botDetectionRelayService.relay(payload);
+    await vi.advanceTimersByTimeAsync(5000);
+
+    await expect(attempt).resolves.toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error relaying Fingerprint identification:',
+      { httpStatus: null, reason: 'timeout' },
+    );
+  });
 });

package/src/services/botDetectionRelay.ts

@@ -1,7 +1,5 @@
 import type { BotDetectionRelayPayload } from '@/types/botDetection';
-import configService from '@/services/config';
-
-const BOT_DETECTION_RELAY_PATH = '/v1/fingerprint/bot-detection';
+import coreApi from '@reservamos/js-api-client/core';
 
 /**
  * Events that require a fresh Fingerprint identification and Core API relay.
@@ -30,27 +28,19 @@ function isEnabledFor(eventName: string): boolean {
  */
 async function relay(payload: BotDetectionRelayPayload): Promise<void> {
   try {
-    const coreApiConfig = configService.getCoreAPIConfig();
-    const response = await fetch(
-      `${coreApiConfig.baseUrl}${BOT_DETECTION_RELAY_PATH}`,
-      {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          ...(coreApiConfig.defaultHeaders?.['x-app-name']
-            ? { 'x-app-name': coreApiConfig.defaultHeaders['x-app-name'] }
-            : {}),
-        },
-        body: JSON.stringify(payload),
-        keepalive: true,
+    await coreApi.fingerprint.sendObservation({
+      requestId: payload.requestId,
+      visitorId: payload.visitorId,
+      distinctId: payload.distinctId,
+      onDiagnostic(diagnostic) {
+        if (diagnostic.reason !== 'http_accepted') {
+          console.error(
+            'Error relaying Fingerprint identification:',
+            diagnostic,
+          );
+        }
       },
-    );
-
-    if (!response.ok) {
-      throw new Error(
-        `Bot Detection relay failed with status ${response.status}`,
-      );
-    }
+    });
   } catch (error) {
     console.error('Error relaying Fingerprint identification:', error);
   }

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 '';
   }