coveo.analytics 2.30.55 → 2.31.0

package/src/donottrack.spec.ts

@@ -1,144 +1,222 @@
+import {vi} from 'vitest';
+
+// `vi.mock` is hoisted, so the detector's answers are held in mutable state that
+// each test rewrites. The Jest version instead called `jest.resetModules()` and
+// re-`require`d the module under test, which ESM does not allow.
+const detectorState = vi.hoisted(() => ({
+  hasNavigator: false,
+  hasWindow: false,
+}));
+
+vi.mock('./detector', () => ({
+  hasNavigator: () => detectorState.hasNavigator,
+  hasWindow: () => detectorState.hasWindow,
+}));
+
+import {doNotTrack, shouldDisableAnalyticsForPrivacy} from './donottrack';
+
 describe('doNotTrack', () => {
-    let doNotTrack: () => boolean;
-    function initModule(
-        hasNav: boolean,
-        hasWin: boolean,
-        options?: {
-            navigatorGlobalPrivacyControl?: any;
-            navigatorDoNotTrack?: any;
-            navigatorMsDoNotTrack?: any;
-            windowDoNotTrack?: any;
+  function initModule(
+    hasNav: boolean,
+    hasWin: boolean,
+    options?: {
+      navigatorGlobalPrivacyControl?: any;
+      navigatorDoNotTrack?: any;
+      navigatorMsDoNotTrack?: any;
+      windowDoNotTrack?: any;
+    }
+  ) {
+    detectorState.hasNavigator = hasNav;
+    detectorState.hasWindow = hasWin;
+    if (hasNav) {
+      Object.defineProperty(<any>navigator, 'globalPrivacyControl', {
+        get() {
+          return options!.navigatorGlobalPrivacyControl;
+        },
+        configurable: true,
+      });
+      Object.defineProperty(<any>navigator, 'doNotTrack', {
+        get() {
+          return options!.navigatorDoNotTrack;
+        },
+        configurable: true,
+      });
+      Object.defineProperty(<any>navigator, 'msDoNotTrack', {
+        get() {
+          return options!.navigatorMsDoNotTrack;
+        },
+        configurable: true,
+      });
+    }
+    if (hasWin) {
+      Object.defineProperty(<any>window, 'doNotTrack', {
+        get() {
+          return options!.windowDoNotTrack;
         },
-    ) {
-        jest.resetModules();
-        jest.mock('./detector', () => ({
-            hasNavigator: () => hasNav,
-            hasWindow: () => hasWin,
-        }));
-        if (hasNav) {
-            Object.defineProperty(<any>navigator, 'globalPrivacyControl', {
-                get() {
-                    return options!.navigatorGlobalPrivacyControl;
-                },
-                configurable: true,
-            });
-            Object.defineProperty(<any>navigator, 'doNotTrack', {
-                get() {
-                    return options!.navigatorDoNotTrack;
-                },
-                configurable: true,
-            });
-            Object.defineProperty(<any>navigator, 'msDoNotTrack', {
-                get() {
-                    return options!.navigatorMsDoNotTrack;
-                },
-                configurable: true,
-            });
-        }
-        if (hasWin) {
-            Object.defineProperty(<any>window, 'doNotTrack', {
-                get() {
-                    return options!.windowDoNotTrack;
-                },
-                configurable: true,
-            });
-        }
-        doNotTrack = require('./donottrack').doNotTrack;
+        configurable: true,
+      });
     }
-    describe('without a Navigator and without window', () => {
-        it('should be false', () => {
-            initModule(false, false);
+  }
+  describe('without a Navigator and without window', () => {
+    it('should be false', () => {
+      initModule(false, false);
 
-            expect(doNotTrack()).toBeFalsy();
-        });
+      expect(doNotTrack()).toBeFalsy();
     });
-    describe('with a Navigator', () => {
-        it('should respect GPC false', () => {
-            initModule(true, false, {
-                navigatorGlobalPrivacyControl: false,
-            });
+  });
+  describe('with a Navigator', () => {
+    it('should respect GPC false', () => {
+      initModule(true, false, {
+        navigatorGlobalPrivacyControl: false,
+      });
 
-            expect(doNotTrack()).toBeFalsy();
-        });
-        it('should respect GPC true', () => {
-            initModule(true, false, {
-                navigatorGlobalPrivacyControl: true,
-            });
+      expect(doNotTrack()).toBeFalsy();
+    });
+    it('should respect GPC true', () => {
+      initModule(true, false, {
+        navigatorGlobalPrivacyControl: true,
+      });
+
+      expect(doNotTrack()).toBeTruthy();
+    });
+    it('should respect GPC undefined', () => {
+      initModule(true, false, {
+        navigatorGlobalPrivacyControl: undefined,
+      });
+
+      expect(doNotTrack()).toBeFalsy();
+    });
 
-            expect(doNotTrack()).toBeTruthy();
+    [true, 'yes', '1'].forEach((value) => {
+      it('should fallback on `navigator.doNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(true, false, {
+          navigatorDoNotTrack: value,
         });
-        it('should respect GPC undefined', () => {
-            initModule(true, false, {
-                navigatorGlobalPrivacyControl: undefined,
-            });
 
-            expect(doNotTrack()).toBeFalsy();
+        expect(doNotTrack()).toBeTruthy();
+      });
+
+      it('should fallback on `navigator.msDoNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(true, false, {
+          navigatorMsDoNotTrack: value,
         });
+        expect(doNotTrack()).toBeTruthy();
+      });
+    });
 
-        [true, 'yes', '1'].forEach((value) => {
-            it('should fallback on `navigator.doNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(true, false, {
-                    navigatorDoNotTrack: value,
-                });
-
-                expect(doNotTrack()).toBeTruthy();
-            });
-
-            it('should fallback on `navigator.msDoNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(true, false, {
-                    navigatorMsDoNotTrack: value,
-                });
-                expect(doNotTrack()).toBeTruthy();
-            });
+    [false, 'no', '0', 'unspecified'].forEach((value) => {
+      it('should fallback on `navigator.doNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(true, false, {
+          navigatorDoNotTrack: value,
         });
 
-        [false, 'no', '0', 'unspecified'].forEach((value) => {
-            it('should fallback on `navigator.doNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(true, false, {
-                    navigatorDoNotTrack: value,
-                });
-
-                expect(doNotTrack()).toBeFalsy();
-            });
-
-            it('should fallback on `navigator.msDoNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(true, false, {
-                    navigatorMsDoNotTrack: value,
-                });
-                expect(doNotTrack()).toBeFalsy();
-            });
+        expect(doNotTrack()).toBeFalsy();
+      });
+
+      it('should fallback on `navigator.msDoNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(true, false, {
+          navigatorMsDoNotTrack: value,
         });
+        expect(doNotTrack()).toBeFalsy();
+      });
     });
+  });
 
-    describe('with a Window', () => {
-        [true, 'yes', '1'].forEach((value) => {
-            it('should fallback on `window.doNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(false, true, {
-                    windowDoNotTrack: value,
-                });
-                expect(doNotTrack()).toBeTruthy();
-            });
+  describe('with a Window', () => {
+    [true, 'yes', '1'].forEach((value) => {
+      it('should fallback on `window.doNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(false, true, {
+          windowDoNotTrack: value,
         });
+        expect(doNotTrack()).toBeTruthy();
+      });
+    });
 
-        [false, 'no', '0', 'unspecified'].forEach((value) => {
-            it('should fallback on `window.doNotTrack`: ' + JSON.stringify(value), () => {
-                initModule(false, true, {
-                    windowDoNotTrack: value,
-                });
-                expect(doNotTrack()).toBeFalsy();
-            });
+    [false, 'no', '0', 'unspecified'].forEach((value) => {
+      it('should fallback on `window.doNotTrack`: ' + JSON.stringify(value), () => {
+        initModule(false, true, {
+          windowDoNotTrack: value,
         });
+        expect(doNotTrack()).toBeFalsy();
+      });
     });
+  });
 
-    describe('with a Navigator and a Window', () => {
-        it('should fallback on `window.doNotTrack` if all navigator properties are falsy', () => {
-            initModule(true, true, {
-                navigatorDoNotTrack: false,
-                navigatorGlobalPrivacyControl: undefined,
-                navigatorMsDoNotTrack: '0',
-                windowDoNotTrack: 1,
-            });
-            expect(doNotTrack()).toBeTruthy();
-        });
+  describe('with a Navigator and a Window', () => {
+    it('should fallback on `window.doNotTrack` if all navigator properties are falsy', () => {
+      initModule(true, true, {
+        navigatorDoNotTrack: false,
+        navigatorGlobalPrivacyControl: undefined,
+        navigatorMsDoNotTrack: '0',
+        windowDoNotTrack: 1,
+      });
+      expect(doNotTrack()).toBeTruthy();
+    });
+  });
+});
+
+describe('shouldDisableAnalyticsForPrivacy', () => {
+  function initModule(signal: {navigatorGlobalPrivacyControl?: any; navigatorDoNotTrack?: any}) {
+    detectorState.hasNavigator = true;
+    detectorState.hasWindow = true;
+    Object.defineProperty(<any>navigator, 'globalPrivacyControl', {
+      get() {
+        return signal.navigatorGlobalPrivacyControl;
+      },
+      configurable: true,
+    });
+    Object.defineProperty(<any>navigator, 'doNotTrack', {
+      get() {
+        return signal.navigatorDoNotTrack;
+      },
+      configurable: true,
+    });
+    Object.defineProperty(<any>navigator, 'msDoNotTrack', {
+      get() {
+        return undefined;
+      },
+      configurable: true,
     });
+    Object.defineProperty(<any>window, 'doNotTrack', {
+      get() {
+        return undefined;
+      },
+      configurable: true,
+    });
+  }
+
+  it('disables when DNT is active and the option is omitted', () => {
+    initModule({navigatorDoNotTrack: '1'});
+    expect(shouldDisableAnalyticsForPrivacy()).toBe(true);
+  });
+
+  it('disables when GPC is active and the option is omitted', () => {
+    initModule({navigatorGlobalPrivacyControl: true});
+    expect(shouldDisableAnalyticsForPrivacy()).toBe(true);
+  });
+
+  it('keeps analytics when DNT is active but the option is true', () => {
+    initModule({navigatorDoNotTrack: '1'});
+    expect(shouldDisableAnalyticsForPrivacy(true)).toBe(false);
+  });
+
+  it('keeps analytics when GPC is active but the option is true (umbrella overrides GPC)', () => {
+    initModule({navigatorGlobalPrivacyControl: true});
+    expect(shouldDisableAnalyticsForPrivacy(true)).toBe(false);
+  });
+
+  it('keeps analytics when both DNT and GPC are active but the option is true', () => {
+    initModule({navigatorDoNotTrack: '1', navigatorGlobalPrivacyControl: true});
+    expect(shouldDisableAnalyticsForPrivacy(true)).toBe(false);
+  });
+
+  it('does not disable when no signal is active and the option is omitted', () => {
+    initModule({});
+    expect(shouldDisableAnalyticsForPrivacy()).toBe(false);
+  });
+
+  it('treats a false option the same as omitting it', () => {
+    initModule({navigatorDoNotTrack: '1'});
+    expect(shouldDisableAnalyticsForPrivacy(false)).toBe(true);
+  });
 });

package/src/donottrack.ts

@@ -9,14 +9,37 @@ import {hasNavigator, hasWindow} from './detector';
 const doNotTrackValues = ['1', 1, 'yes', true];
 
 export function doNotTrack(): boolean {
-    const checks: any[] = [];
-    if (hasWindow()) {
-        checks.push((<any>window).doNotTrack);
-    }
-    if (hasNavigator()) {
-        checks.push((<any>navigator).doNotTrack, (<any>navigator).msDoNotTrack, (<any>navigator).globalPrivacyControl);
-    }
-    return checks.some((value) => doNotTrackValues.indexOf(value) !== -1);
+  const checks: any[] = [];
+  if (hasWindow()) {
+    checks.push((<any>window).doNotTrack);
+  }
+  if (hasNavigator()) {
+    checks.push(
+      (<any>navigator).doNotTrack,
+      (<any>navigator).msDoNotTrack,
+      (<any>navigator).globalPrivacyControl
+    );
+  }
+  return checks.some((value) => doNotTrackValues.indexOf(value) !== -1);
+}
+
+/**
+ * Effective analytics-suppression policy for browser privacy signals.
+ *
+ * By default, any active browser privacy signal (Do Not Track or Global Privacy
+ * Control) suppresses analytics. When `disableBrowserPrivacySignals` is explicitly
+ * `true`, the integration takes ownership of privacy decisions and no browser
+ * signal is honored.
+ *
+ * @param disableBrowserPrivacySignals When `true`, browser privacy signals (DNT and
+ * GPC) are ignored. The default (`false`/`undefined`) preserves the privacy-friendly
+ * behavior of honoring them.
+ */
+export function shouldDisableAnalyticsForPrivacy(disableBrowserPrivacySignals?: boolean): boolean {
+  if (disableBrowserPrivacySignals === true) {
+    return false;
+  }
+  return doNotTrack();
 }
 
 export default doNotTrack;

package/src/events.ts

@@ -1,90 +1,90 @@
 export type IRequestPayload = Record<string, any>;
 
 export enum EventType {
-    search = 'search',
-    click = 'click',
-    custom = 'custom',
-    view = 'view',
-    collect = 'collect',
+  search = 'search',
+  click = 'click',
+  custom = 'custom',
+  view = 'view',
+  collect = 'collect',
 }
 
 export interface SearchDocument {
-    documentUri: string;
-    documentUriHash: string;
+  documentUri: string;
+  documentUriHash: string;
 }
 
 export type SendEventArguments = [EventType, ...any[]];
 
 export type VariableArgumentsPayload =
-    | []
-    | [any]
-    | [string, any]
-    | [string, string, any]
-    | [string, string, string, any]
-    | [string, string, string, string, any];
+  | []
+  | [any]
+  | [string, any]
+  | [string, string, any]
+  | [string, string, string, any]
+  | [string, string, string, string, any];
 
 export interface EventBaseRequest {
-    language?: string;
-    userAgent?: string;
-    customData?: Record<string, any>;
-    anonymous?: boolean;
-    username?: string;
-    userDisplayName?: any;
-    splitTestRunName?: string;
-    splitTestRunVersion?: string;
-    clientId?: string;
-    originContext?: string;
-    originLevel1?: string;
-    originLevel2?: string;
-    originLevel3?: string;
+  language?: string;
+  userAgent?: string;
+  customData?: Record<string, any>;
+  anonymous?: boolean;
+  username?: string;
+  userDisplayName?: any;
+  splitTestRunName?: string;
+  splitTestRunVersion?: string;
+  clientId?: string;
+  originContext?: string;
+  originLevel1?: string;
+  originLevel2?: string;
+  originLevel3?: string;
 }
 
 export interface FacetStateRequest {
-    field: string;
-    id: string;
-    value: string;
-    valuePosition: number;
-    displayValue: string;
-    facetType: 'specific' | 'dateRange' | 'numericalRange' | 'hierarchical';
-    state: 'selected' | 'idle' | 'excluded';
-    facetPosition: number;
-    title: string;
-    start?: string;
-    end?: string;
-    endInclusive?: boolean;
+  field: string;
+  id: string;
+  value: string;
+  valuePosition: number;
+  displayValue: string;
+  facetType: 'specific' | 'dateRange' | 'numericalRange' | 'hierarchical';
+  state: 'selected' | 'idle' | 'excluded';
+  facetPosition: number;
+  title: string;
+  start?: string;
+  end?: string;
+  endInclusive?: boolean;
 }
 
 export interface SearchEventRequest extends EventBaseRequest {
-    searchQueryUid: string;
-    queryText: string;
-    actionCause: string;
-    responseTime: number;
-    advancedQuery?: string;
-    numberOfResults?: number;
-    contextual?: boolean;
-    results?: SearchDocument[];
-    queryPipeline?: string;
-    userGroups?: string[];
-    facetState?: FacetStateRequest[];
+  searchQueryUid: string;
+  queryText: string;
+  actionCause: string;
+  responseTime: number;
+  advancedQuery?: string;
+  numberOfResults?: number;
+  contextual?: boolean;
+  results?: SearchDocument[];
+  queryPipeline?: string;
+  userGroups?: string[];
+  facetState?: FacetStateRequest[];
 }
 
 export interface PreparedSearchEventRequest extends Omit<SearchEventRequest, 'searchQueryUid'> {}
 
 export interface DocumentInformation {
-    documentUri?: string;
-    documentUriHash?: string;
-    collectionName?: string;
-    sourceName: string;
-    documentPosition: number;
-    actionCause: string;
-
-    searchQueryUid: string;
-    documentTitle?: string;
-    documentUrl?: string;
-    documentAuthor?: string;
-    queryPipeline?: string;
-    rankingModifier?: string;
-    documentCategory?: string;
+  documentUri?: string;
+  documentUriHash?: string;
+  collectionName?: string;
+  sourceName: string;
+  documentPosition: number;
+  actionCause: string;
+
+  searchQueryUid: string;
+  documentTitle?: string;
+  documentUrl?: string;
+  documentAuthor?: string;
+  queryPipeline?: string;
+  rankingModifier?: string;
+  documentCategory?: string;
 }
 
 export interface ClickEventRequest extends EventBaseRequest, DocumentInformation {}
@@ -92,27 +92,30 @@ export interface ClickEventRequest extends EventBaseRequest, DocumentInformation
 export interface PreparedClickEventRequest extends Omit<ClickEventRequest, 'searchQueryUid'> {}
 
 export interface CustomEventRequest extends EventBaseRequest {
-    eventType: string;
-    eventValue: string;
-    lastSearchQueryUid?: string;
+  eventType: string;
+  eventValue: string;
+  lastSearchQueryUid?: string;
 }
 
-export interface PreparedCustomEventRequest extends Omit<CustomEventRequest, 'lastSearchQueryUid'> {}
+export interface PreparedCustomEventRequest extends Omit<
+  CustomEventRequest,
+  'lastSearchQueryUid'
+> {}
 
 export interface ViewEventRequest extends EventBaseRequest {
-    location?: string;
-    referrer?: string;
-    title?: string;
-    contentIdKey: string;
-    contentIdValue: string;
-    contentType?: string;
+  location?: string;
+  referrer?: string;
+  title?: string;
+  contentIdKey: string;
+  contentIdValue: string;
+  contentType?: string;
 }
 
 export interface PreparedViewEventRequest extends ViewEventRequest {}
 
 export interface DefaultEventResponse {
-    visitId: string;
-    visitorId: string;
+  visitId: string;
+  visitorId: string;
 }
 
 export interface SearchEventResponse extends DefaultEventResponse {}
@@ -120,12 +123,16 @@ export interface ClickEventResponse extends DefaultEventResponse {}
 export interface CustomEventResponse extends DefaultEventResponse {}
 export interface ViewEventResponse extends DefaultEventResponse {}
 
-export type AnyEventResponse = SearchEventResponse | ClickEventResponse | CustomEventResponse | ViewEventResponse;
+export type AnyEventResponse =
+  | SearchEventResponse
+  | ClickEventResponse
+  | CustomEventResponse
+  | ViewEventResponse;
 
 export interface VisitResponse {
-    id: string;
-    visitorId: string;
+  id: string;
+  visitorId: string;
 }
 export interface HealthResponse {
-    status: string;
+  status: string;
 }

package/src/formatting/format-array-for-coveo-custom-data.spec.ts

@@ -1,18 +1,19 @@
 import {formatArrayForCoveoCustomData} from './format-array-for-coveo-custom-data';
 
 describe('#formatArrayForCoveoCustomData', () => {
-    it('returns an empty string for an empty array', () => {
-        expect(formatArrayForCoveoCustomData([])).toEqual('');
-    });
+  it('returns an empty string for an empty array', () => {
+    expect(formatArrayForCoveoCustomData([])).toEqual('');
+  });
 
-    it('returns the correct string for a valid array', () => {
-        expect(formatArrayForCoveoCustomData(['t', 'test'])).toEqual('t;test');
-    });
+  it('returns the correct string for a valid array', () => {
+    expect(formatArrayForCoveoCustomData(['t', 'test'])).toEqual('t;test');
+  });
 
-    it('correctly truncates the data when it contains more than 256 characters', () => {
-        const longString =
-            'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis,';
-        const rawData = ['1', longString];
-        expect(formatArrayForCoveoCustomData(rawData)).toEqual(longString);
-    });
+  it('correctly truncates the data when it contains more than 256 characters', () => {
+    const longString =
+      /* cspell:disable-next-line */
+      'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis,';
+    const rawData = ['1', longString];
+    expect(formatArrayForCoveoCustomData(rawData)).toEqual(longString);
+  });
 });