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

package/src/services/botDetectionRelay.test.ts

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import configService from '@/services/config';
+import botDetectionRelayService from './botDetectionRelay';
+
+vi.mock('@/services/config', () => ({
+  default: {
+    getCoreAPIConfig: vi.fn(),
+  },
+}));
+
+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();
+    vi.mocked(configService.getCoreAPIConfig).mockReturnValue(coreApiConfig);
+  });
+
+  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('posts the payload to the Core API fingerprint path with keepalive', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    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',
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+      },
+    );
+  });
+
+  it('omits x-app-name when it is not in the core API config', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true });
+    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);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://datalake-api-dev.reservamossaas.com/api/v1/fingerprint/bot-detection',
+      expect.objectContaining({
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      }),
+    );
+  });
+
+  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:',
+      error,
+    );
+
+    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:',
+      expect.objectContaining({
+        message: 'Bot Detection relay failed with status 503',
+      }),
+    );
+
+    consoleError.mockRestore();
+  });
+});

package/src/services/botDetectionRelay.ts

@@ -0,0 +1,64 @@
+import type { BotDetectionRelayPayload } from '@/types/botDetection';
+import configService from '@/services/config';
+
+const BOT_DETECTION_RELAY_PATH = '/v1/fingerprint/bot-detection';
+
+/**
+ * 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 {
+    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,
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(
+        `Bot Detection relay failed with status ${response.status}`,
+      );
+    }
+  } catch (error) {
+    console.error('Error relaying Fingerprint identification:', error);
+  }
+}
+
+const botDetectionRelayService = {
+  isEnabledFor,
+  relay,
+};
+
+export default botDetectionRelayService;

package/src/services/fingerprint.test.ts

@@ -0,0 +1,362 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fingerprintService, { getFingerprintForIdentify } from './fingerprint';
+
+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: clientMock,
+}));
+
+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');
+  });
+
+  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);
+    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-api-key'),
+    ).rejects.toThrow('Agent script blocked');
+    expect(fingerprintService.isFingerprintReady()).toBe(false);
+    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('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'));
+
+    await expect(
+      fingerprintService.initFingerprint('test-api-key'),
+    ).rejects.toThrow('Agent script blocked');
+    await expect(fingerprintService.getFingerprint()).resolves.toBe(
+      'cached-visitor',
+    );
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
+  });
+
+  it('waits for the agent to load before identifying', async () => {
+    let finishInit: () => void = () => undefined;
+    initMock.mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          finishInit = resolve;
+        }),
+    );
+
+    const init = fingerprintService.initFingerprint('test-api-key');
+
+    expect(fingerprintService.isFingerprintReady()).toBe(false);
+    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
+    finishInit();
+    await init;
+
+    expect(fingerprintService.isFingerprintReady()).toBe(true);
+    await expect(fingerprintService.getFingerprint()).resolves.toBe(
+      'visitor-123',
+    );
+    expect(getVisitorDataMock).toHaveBeenCalledOnce();
+  });
+
+  it('does not mark a newer failed client ready when an older init finishes', async () => {
+    let finishFirstInit: () => void = () => undefined;
+    initMock
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            finishFirstInit = resolve;
+          }),
+      )
+      .mockRejectedValueOnce(new Error('New agent script blocked'));
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+
+    const firstInit = fingerprintService.initFingerprint('first-key');
+    await expect(
+      fingerprintService.initFingerprint('second-key'),
+    ).rejects.toThrow('New agent script blocked');
+    finishFirstInit();
+    await firstInit;
+
+    expect(fingerprintService.isFingerprintReady()).toBe(false);
+    await expect(fingerprintService.getFingerprint()).resolves.toBe('');
+    expect(getVisitorDataMock).not.toHaveBeenCalled();
+
+    consoleError.mockRestore();
+  });
+
+  it('keeps a newer loaded client ready when an older init fails', async () => {
+    let failFirstInit: (reason?: unknown) => void = () => undefined;
+    initMock
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((_resolve, reject) => {
+            failFirstInit = reject;
+          }),
+      )
+      .mockResolvedValueOnce(undefined);
+    getVisitorDataMock.mockResolvedValue({
+      ...visitorData,
+      visitorId: 'new-visitor',
+    });
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+
+    const firstInit = fingerprintService.initFingerprint('first-key');
+    await fingerprintService.initFingerprint('second-key');
+    failFirstInit(new Error('Old agent script blocked'));
+    await expect(firstInit).rejects.toThrow('Old agent script blocked');
+
+    expect(fingerprintService.isFingerprintReady()).toBe(true);
+    await expect(fingerprintService.getFingerprint()).resolves.toBe(
+      'new-visitor',
+    );
+
+    consoleError.mockRestore();
+  });
+});