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

package/src/services/botDetectionRelay.test.ts

@@ -0,0 +1,154 @@
+import coreApi from '@reservamos/js-api-client/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import botDetectionRelayService from './botDetectionRelay';
+
+const payload = {
+  requestId: 'request-123',
+  visitorId: 'visitor-123',
+  distinctId: 'distinct-123',
+  eventName: 'Payment Attempt',
+};
+
+const coreApiConfig = {
+  baseUrl: 'https://data-lake.reservamossaas.com/api',
+  defaultHeaders: {
+    'Authorization': 'Bearer test-token',
+    'Origin': 'https://example.com',
+    'x-app-name': 'reservamos-web',
+  },
+};
+
+describe('botDetectionRelayService', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    coreApi.setConfig(coreApiConfig);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('enables only the SDK-owned Bot Detection events', () => {
+    expect(botDetectionRelayService.isEnabledFor('Search')).toBe(true);
+    expect(botDetectionRelayService.isEnabledFor('Payment Attempt')).toBe(true);
+    expect(botDetectionRelayService.isEnabledFor('Purchase Attempt')).toBe(
+      true,
+    );
+    expect(botDetectionRelayService.isEnabledFor('View Results')).toBe(false);
+    expect(
+      botDetectionRelayService.isEnabledFor('Purchase Confirmation Viewed'),
+    ).toBe(false);
+  });
+
+  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);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://data-lake.reservamossaas.com/api/v1/fingerprint/bot-detection',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-app-name': 'reservamos-web',
+          'Authorization': 'Bearer test-token',
+        },
+        body: JSON.stringify({
+          requestId: payload.requestId,
+          visitorId: payload.visitorId,
+          distinctId: payload.distinctId,
+          eventName: 'Fingerprint Requested',
+        }),
+        signal: expect.any(AbortSignal),
+      },
+    );
+  });
+
+  it('omits distinctId when unavailable', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 202 });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await botDetectionRelayService.relay({
+      requestId: payload.requestId,
+      visitorId: payload.visitorId,
+      eventName: 'Search',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        body: JSON.stringify({
+          requestId: payload.requestId,
+          visitorId: payload.visitorId,
+          eventName: 'Fingerprint Requested',
+        }),
+      }),
+    );
+  });
+
+  it('contains rejected requests and reports the failure', async () => {
+    const error = new Error('Network unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(error));
+
+    await expect(
+      botDetectionRelayService.relay(payload),
+    ).resolves.toBeUndefined();
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error relaying Fingerprint identification:',
+      { httpStatus: null, reason: 'network_or_cors' },
+    );
+
+    consoleError.mockRestore();
+  });
+
+  it('contains non-success responses and reports their status', async () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({ ok: false, status: 503 }),
+    );
+
+    await expect(
+      botDetectionRelayService.relay(payload),
+    ).resolves.toBeUndefined();
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error relaying Fingerprint identification:',
+      { 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

@@ -0,0 +1,54 @@
+import type { BotDetectionRelayPayload } from '@/types/botDetection';
+import coreApi from '@reservamos/js-api-client/core';
+
+/**
+ * Events that require a fresh Fingerprint identification and Core API relay.
+ * Owned by the SDK so consumers do not choose which events participate.
+ */
+const BOT_DETECTION_EVENTS = [
+  'Search',
+  'Payment Attempt',
+  'Purchase Attempt',
+] as const;
+
+/**
+ * Checks whether an event is eligible for Bot Detection.
+ * @param {string} eventName - Mixpanel event name.
+ * @returns {boolean} Whether the event should obtain and relay a fresh identification.
+ */
+function isEnabledFor(eventName: string): boolean {
+  return (BOT_DETECTION_EVENTS as readonly string[]).includes(eventName);
+}
+
+/**
+ * Relays Fingerprint identification context to Core API.
+ * Failures are contained so they cannot affect an event already submitted to Mixpanel.
+ * @param {BotDetectionRelayPayload} payload - Request correlation data.
+ * @returns {Promise<void>} Resolves after the relay attempt completes.
+ */
+async function relay(payload: BotDetectionRelayPayload): Promise<void> {
+  try {
+    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,
+          );
+        }
+      },
+    });
+  } catch (error) {
+    console.error('Error relaying Fingerprint identification:', error);
+  }
+}
+
+const botDetectionRelayService = {
+  isEnabledFor,
+  relay,
+};
+
+export default botDetectionRelayService;

package/src/services/fingerprint.test.ts

@@ -1,66 +1,279 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import fingerprintService from './fingerprint';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fingerprintService, { getFingerprintForIdentify } from './fingerprint';
 
-const { initMock, getVisitorDataMock } = vi.hoisted(() => ({
-  initMock: vi.fn(),
-  getVisitorDataMock: vi.fn(),
-}));
+const visitorData = {
+  visitorId: 'visitor-123',
+  requestId: 'request-123',
+  visitorFound: true,
+  confidence: { score: 0.99 },
+  cacheHit: false,
+};
+
+const { getVisitorDataMock, initMock, setPeoplePropertiesMock, clientMock } =
+  vi.hoisted(() => ({
+    clientMock: vi.fn(),
+    getVisitorDataMock: vi.fn(),
+    initMock: vi.fn(),
+    setPeoplePropertiesMock: vi.fn(),
+  }));
 
 vi.mock('@fingerprintjs/fingerprintjs-pro-spa', () => ({
   FingerprintJSPro: {
     defaultEndpoint: 'https://fpjscdn.net',
     defaultScriptUrlPattern: 'https://fpjscdn.net/agent',
   },
-  FpjsClient: vi.fn().mockImplementation(() => ({
-    init: initMock,
-    getVisitorData: getVisitorDataMock,
-  })),
+  FpjsClient: clientMock,
 }));
 
-describe('fingerprintService readiness', () => {
-  beforeEach(() => {
-    localStorage.clear();
-    initMock.mockReset();
+vi.mock('@/services/mixpanel', () => ({
+  default: { setPeopleProperties: setPeoplePropertiesMock },
+}));
+
+describe('fingerprintService', () => {
+  let storage: Record<string, string>;
+
+  beforeEach(async () => {
+    clientMock.mockImplementation(() => ({
+      init: initMock,
+      getVisitorData: getVisitorDataMock,
+    }));
+    storage = {};
+    vi.stubGlobal('localStorage', {
+      getItem: (key: string) => storage[key] ?? null,
+      setItem: (key: string, value: string) => {
+        storage[key] = value;
+      },
+      removeItem: (key: string) => {
+        storage = Object.fromEntries(
+          Object.entries(storage).filter(([entryKey]) => entryKey !== key),
+        );
+      },
+      clear: () => {
+        storage = {};
+      },
+    });
     getVisitorDataMock.mockReset();
+    initMock.mockReset();
+    setPeoplePropertiesMock.mockReset();
+    getVisitorDataMock.mockResolvedValue(visitorData);
+    initMock.mockResolvedValue(undefined);
+    await fingerprintService.initFingerprint('test-api-key');
   });
 
-  it('does not identify with a client whose agent failed to load', async () => {
-    const initError = new Error('Agent script blocked');
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('omits unavailable Visitor Found metadata without blocking identification', async () => {
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorFound: undefined,
+    });
+    const result = await fingerprintService.identifyVisitor();
+    expect(result.visitorId).toBe('visitor-123');
+    expect(result.requestId).toBe('request-123');
+    expect(result).not.toHaveProperty('visitorFound');
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+  });
+
+  it('suppresses identify-specific cache and profile effects after its scope closes', async () => {
+    let finish: (value: typeof visitorData) => void = () => undefined;
+    getVisitorDataMock.mockReturnValue(
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    );
+    let active = true;
+    const pending = getFingerprintForIdentify({
+      isActive: () => active,
+      report: vi.fn(),
+    });
+    active = false;
+    finish(visitorData);
+    await pending;
+    expect(fingerprintService.getCachedFingerprint()).toBeNull();
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+  });
+
+  it('continues the identify path when fingerprint cache writes fail', async () => {
+    vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
+      throw new Error('private-id');
+    });
+    const report = vi.fn();
+    await expect(
+      getFingerprintForIdentify({ isActive: () => true, report }),
+    ).resolves.toBe('visitor-123');
+    expect(report).toHaveBeenCalledWith('cache', 'unavailable');
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': true,
+    });
+  });
+
+  it('sanitizes errors only on the identify-specific fingerprint path', async () => {
+    const error = new Error('private-id');
+    getVisitorDataMock.mockRejectedValue(error);
     const consoleError = vi
       .spyOn(console, 'error')
       .mockImplementation(() => undefined);
-    initMock.mockRejectedValue(initError);
-    getVisitorDataMock.mockRejectedValue(
-      new Error(
-        "FPJSAgent hasn't loaded yet. Make sure to call the init() method first.",
-      ),
+    await expect(
+      getFingerprintForIdentify({ isActive: () => true, report: vi.fn() }),
+    ).rejects.toBe(error);
+    expect(consoleError).not.toHaveBeenCalled();
+  });
+
+  it('returns request-scoped identification data and bypasses the SPA cache', async () => {
+    await expect(fingerprintService.identifyVisitor(true)).resolves.toEqual({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+
+    expect(getVisitorDataMock).toHaveBeenCalledWith({}, true);
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': true,
+    });
+  });
+
+  it('writes a false visitor match to the Mixpanel profile', async () => {
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorFound: false,
+    });
+
+    await expect(
+      fingerprintService.identifyVisitor(true),
+    ).resolves.toMatchObject({ visitorFound: false });
+    expect(setPeoplePropertiesMock).toHaveBeenCalledWith({
+      'Visitor Found': false,
+    });
+    expect(setPeoplePropertiesMock).toHaveBeenCalledTimes(1);
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps identification data when the Mixpanel profile update fails', async () => {
+    const error = new Error('Mixpanel unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    setPeoplePropertiesMock.mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(fingerprintService.identifyVisitor(true)).resolves.toEqual({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+      visitorFound: true,
+      confidenceScore: 0.99,
+      cacheHit: false,
+    });
+    expect(fingerprintService.getCachedFingerprint()).toBe('visitor-123');
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error updating Mixpanel visitor profile:',
+      error,
+    );
+
+    consoleError.mockRestore();
+  });
+
+  it('preserves the visitor-only SDK cache contract', async () => {
+    await fingerprintService.identifyVisitor(true);
+
+    expect(fingerprintService.getCachedFingerprint()).toBe('visitor-123');
+    await expect(fingerprintService.getFingerprint(true)).resolves.toBe(
+      'visitor-123',
     );
+    expect(getVisitorDataMock).toHaveBeenCalledTimes(1);
+    expect(setPeoplePropertiesMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not reuse a legacy cached visitor ID as a request-scoped result', async () => {
+    localStorage.setItem(
+      'default_fingerprint_cache',
+      JSON.stringify({
+        fingerprint: 'legacy-visitor',
+        expiresAt: Date.now() + 60_000,
+      }),
+    );
+
+    await expect(
+      fingerprintService.identifyVisitor(true),
+    ).resolves.toMatchObject({
+      visitorId: 'visitor-123',
+      requestId: 'request-123',
+    });
+    expect(getVisitorDataMock).toHaveBeenCalledWith({}, true);
+  });
+
+  it('reports and rethrows identification errors', async () => {
+    const error = new Error('Fingerprint unavailable');
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    getVisitorDataMock.mockRejectedValue(error);
+
+    await expect(fingerprintService.identifyVisitor(true)).rejects.toThrow(
+      'Fingerprint unavailable',
+    );
+    expect(consoleError).toHaveBeenCalledWith(
+      'Error retrieving fingerprint:',
+      error,
+    );
+    expect(setPeoplePropertiesMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
+  });
+
+  it('does not treat a constructed client as ready until the agent loads', async () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    const initError = new Error('Agent script blocked');
+    initMock.mockRejectedValue(initError);
 
     await expect(
-      fingerprintService.initFingerprint('test-key'),
+      fingerprintService.initFingerprint('test-api-key'),
     ).rejects.toThrow('Agent script blocked');
     expect(fingerprintService.isFingerprintReady()).toBe(false);
-    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
-    expect(getVisitorDataMock).not.toHaveBeenCalled();
     expect(consoleError).toHaveBeenCalledWith(
       'Error initializing identification service:',
       initError,
     );
 
+    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
+    await expect(fingerprintService.identifyVisitor(true)).rejects.toThrow(
+      'Identification service is not initialized.',
+    );
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
     consoleError.mockRestore();
   });
 
-  it('identifies after the agent loads successfully', async () => {
-    initMock.mockResolvedValue(undefined);
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'visitor-123' });
-
-    await fingerprintService.initFingerprint('test-key');
+  it('returns a cached visitor ID when the agent failed to load', async () => {
+    localStorage.setItem(
+      'default_fingerprint_cache',
+      JSON.stringify({
+        fingerprint: 'cached-visitor',
+        expiresAt: Date.now() + 60_000,
+      }),
+    );
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+    initMock.mockRejectedValue(new Error('Agent script blocked'));
 
-    expect(fingerprintService.isFingerprintReady()).toBe(true);
+    await expect(
+      fingerprintService.initFingerprint('test-api-key'),
+    ).rejects.toThrow('Agent script blocked');
     await expect(fingerprintService.getFingerprint()).resolves.toBe(
-      'visitor-123',
+      'cached-visitor',
     );
-    expect(getVisitorDataMock).toHaveBeenCalledOnce();
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
   });
 
   it('waits for the agent to load before identifying', async () => {
@@ -71,9 +284,8 @@ describe('fingerprintService readiness', () => {
           finishInit = resolve;
         }),
     );
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'visitor-123' });
 
-    const init = fingerprintService.initFingerprint('test-key');
+    const init = fingerprintService.initFingerprint('test-api-key');
 
     expect(fingerprintService.isFingerprintReady()).toBe(false);
     await expect(fingerprintService.getFingerprint()).resolves.toBe('');
@@ -127,7 +339,10 @@ describe('fingerprintService readiness', () => {
           }),
       )
       .mockResolvedValueOnce(undefined);
-    getVisitorDataMock.mockResolvedValue({ visitorId: 'new-visitor' });
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorId: 'new-visitor',
+    });
     const consoleError = vi
       .spyOn(console, 'error')
       .mockImplementation(() => undefined);