feat: ✅ skip queue for zaraz.consent methods, increase tests

src/consent/get-all-checkboxes.spec.ts

@@ -9,17 +9,27 @@ declare global {
 
 let windowObj: Window & typeof globalThis;
 
+const warnSpy = jest.spyOn(console, 'warn');
+
 beforeAll(() => {
   windowObj = window;
+  warnSpy.mockImplementation();
 });
 
 afterAll(() => {
   window = windowObj;
+  warnSpy.mockRestore();
 });
 
 describe('getAllCheckboxes()', () => {
-  it('should return all checkboxes from zaraz consent', () => {
+  it("should return an empty object when the Zaraz consent API hasn't been initialised", () => {
+    const checkboxes = getAllCheckboxes();
+    expect(checkboxes).toEqual({});
+  });
+
+  it('should return an object of checkboxes when the Zaraz consent API has been initialised', () => {
     const checkboxesMock = { key1: true, key2: false };
+
     window.zaraz = {
       consent: {
         getAllCheckboxes: jest.fn().mockReturnValue(checkboxesMock),

src/consent/get-all-checkboxes.ts

@@ -1,8 +1,21 @@
 import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
+
+export type CheckboxStatuses = {
+  [key: string]: undefined | boolean; // The key is equal to the ID in Zaraz, e.g. "OVAL" or "DVEA".
+};
 
 /**
  * Returns an object with the checkbox status of all purposes.
  */
-export function getAllCheckboxes(): { [key: string]: boolean } {
-  return getZaraz().consent.getAllCheckboxes();
+export function getAllCheckboxes(): CheckboxStatuses {
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.getAllCheckboxes === 'function') {
+    return zaraz.consent.getAllCheckboxes();
+  }
+
+  showWarning(`getAllCheckBoxes()`);
+
+  return {};
 }

src/consent/get-all.spec.ts

@@ -9,17 +9,31 @@ declare global {
 
 let windowObj: Window & typeof globalThis;
 
+const warnSpy = jest.spyOn(console, 'warn');
+
 beforeAll(() => {
   windowObj = window;
+  warnSpy.mockImplementation();
 });
 
 afterAll(() => {
   window = windowObj;
+  warnSpy.mockRestore();
 });
 
 describe('getAll()', () => {
-  it('should return all consents from zaraz consent', () => {
-    const consentsMock = { key1: true, key2: false };
+  it("should return an empty object when the Zaraz consent API hasn't been initialised", () => {
+    const consents = getAll();
+    expect(consents).toEqual({});
+  });
+
+  it('should return an object of consents when the Zaraz consent API has been initialised', () => {
+    const consentsMock = {
+      key1: true,
+      key2: false,
+      key3: undefined,
+    };
+
     window.zaraz = {
       consent: {
         getAll: jest.fn().mockReturnValue(consentsMock),

src/consent/get-all.ts

@@ -1,8 +1,30 @@
 import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
+
+export type PurposeStatuses = {
+  [key: string]: undefined | boolean; // The key is equal to the ID in Zaraz, e.g. "OVAL" or "DVEA".
+};
 
 /**
- * Returns an object with the consent status of all purposes.
+ * Returns an object with the status of all purposes.
+ *
+ * ```
+ * true: the consent has been given
+ * false: the consent has been denied
+ * undefined: the consent has never been given or seen
+ * ```
+ *
+ * When Zaraz hasn't been initalised, it returns an empty object.
  */
-export function getAll(): { [key: string]: boolean } {
-  return getZaraz().consent.getAll();
+
+export function getAll(): PurposeStatuses {
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.getAll === 'function') {
+    return zaraz.consent.getAll();
+  }
+
+  showWarning(`getAll()`);
+
+  return {};
 }

src/consent/get-api-ready.spec.ts

@@ -0,0 +1,41 @@
+import { getAPIReady } from './get-api-ready';
+
+declare global {
+  interface Window {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    zaraz: any;
+  }
+}
+
+let windowObj: Window & typeof globalThis;
+
+const warnSpy = jest.spyOn(console, 'warn');
+
+beforeAll(() => {
+  windowObj = window;
+  warnSpy.mockImplementation();
+});
+
+afterAll(() => {
+  window = windowObj;
+  warnSpy.mockRestore();
+});
+
+describe('getAPIReady()', () => {
+  it("should return false when the Zaraz consent API hasn't been initialised", () => {
+    const apiReady = getAPIReady();
+    expect(apiReady).toEqual(false);
+  });
+
+  it('should return true when the Zaraz consent API has been initialised', () => {
+    window.zaraz = {
+      consent: {
+        APIReady: true,
+      },
+    };
+
+    const apiReady = getAPIReady();
+
+    expect(apiReady).toEqual(true);
+  });
+});

src/consent/get-api-ready.ts

@@ -0,0 +1,22 @@
+import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
+
+/**
+ * Indicates whether the Consent API is currently available on the page.
+ *
+ * ```
+ * true: the Zaraz consent API is ready to be used with e.g. getAll(), getAllCheckboxes() etc.
+ * false: the Zaraz consent API is not ready to be used
+ * ```
+ */
+export function getAPIReady(): boolean {
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.APIReady === 'boolean') {
+    return zaraz.consent.APIReady;
+  }
+
+  showWarning(`getAPIReady()`);
+
+  return false;
+}

src/consent/get-purposes.spec.ts

@@ -1,4 +1,4 @@
-import { getPurposes } from './get-purposes';
+import { getPurposes, Purposes } from './get-purposes';
 
 declare global {
   interface Window {
@@ -9,20 +9,38 @@ declare global {
 
 let windowObj: Window & typeof globalThis;
 
+const warnSpy = jest.spyOn(console, 'warn');
+
 beforeAll(() => {
   windowObj = window;
+  warnSpy.mockImplementation();
 });
 
 afterAll(() => {
   window = windowObj;
+  warnSpy.mockRestore();
 });
 
 describe('getPurposes()', () => {
-  it('should return all purposes from zaraz consent', () => {
-    const purposesMock = {
-      key1: { name: 'Name 1', description: 'Description 1', order: 1 },
-      key2: { name: 'Name 2', description: 'Description 2', order: 2 },
+  it("should return an empty object when the Zaraz consent API isn't initialised", () => {
+    const purposes = getPurposes();
+    expect(purposes).toEqual({});
+  });
+
+  it('should return an object of purposes from the Zaraz consent API when Zaraz is initialised', () => {
+    const purposesMock: Purposes = {
+      ORFL: {
+        name: { en: 'Name 1' },
+        description: { en: 'Description 1' },
+        order: 100,
+      },
+      OAVL: {
+        name: { en: 'Name 2' },
+        description: { en: 'Description 2' },
+        order: 200,
+      },
     };
+
     window.zaraz = {
       consent: {
         purposes: purposesMock,

src/consent/get-purposes.ts

@@ -1,14 +1,31 @@
 import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
 
-type Purpose = {
-  name: string;
-  description: string;
+export type Purpose = {
   order: number;
+  name: {
+    [key: string]: string; // the key is the language set in Zaraz (e.g. "en")
+  };
+  description: {
+    [key: string]: string; // the key is the language set in Zaraz (e.g. "en")
+  };
+};
+
+export type Purposes = {
+  [key: string]: Purpose; // the key is also the ID visible in Zaraz (e.g. "OrGL" or "OAVL")
 };
 
 /**
  * An object containing all configured purposes, with their ID, name, description, and order.
  */
-export function getPurposes(): { [key: string]: Purpose } {
-  return getZaraz().consent.purposes;
+export function getPurposes(): Purposes {
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.purposes === 'object') {
+    return zaraz.consent.purposes;
+  }
+
+  showWarning(`getPurposes()`);
+
+  return {};
 }

src/consent/get.spec.ts

@@ -9,17 +9,27 @@ declare global {
 
 let windowObj: Window & typeof globalThis;
 
+const warnSpy = jest.spyOn(console, 'warn');
+
 beforeAll(() => {
   windowObj = window;
+  warnSpy.mockImplementation();
 });
 
 afterAll(() => {
   window = windowObj;
+  warnSpy.mockRestore();
 });
 
 describe('get()', () => {
-  it('should return the consent status for a purpose from zaraz consent', () => {
+  it("should return undefined when the Zaraz consent API hasn't been initialised", () => {
+    const consentStatus = get('key');
+    expect(consentStatus).toBe(undefined);
+  });
+
+  it('should return the consent status for a purpose when the Zaraz consent API has been initialised', () => {
     const getMock = jest.fn().mockReturnValue(true);
+
     window.zaraz = {
       consent: {
         get: getMock,

src/consent/get.ts

@@ -1,7 +1,8 @@
 import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
 
 /**
- * Get the current consent status for a purpose using the purpose ID.
+ * Get the consent status for a specific purpose using the purpose ID.
  *
  * ```
  * true: The consent was granted.
@@ -10,5 +11,13 @@ import { getZaraz } from '../helpers/get-zaraz';
  * ```
  */
 export function get(purposeId: string): boolean | undefined {
-  return getZaraz().consent.get(purposeId);
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.get === 'function') {
+    return zaraz.consent.get(purposeId);
+  }
+
+  showWarning(`get()`);
+
+  return undefined;
 }

src/consent/index.spec.ts

@@ -9,6 +9,7 @@ describe('consent', () => {
       setAll: expect.any(Function),
       getAllCheckboxes: expect.any(Function),
       getPurposes: expect.any(Function),
+      getAPIReady: expect.any(Function),
       setCheckboxes: expect.any(Function),
       setAllCheckboxes: expect.any(Function),
       sendQueuedEvents: expect.any(Function),

src/consent/index.ts

@@ -1,6 +1,7 @@
 import { get } from './get';
 import { getAll } from './get-all';
 import { getAllCheckboxes } from './get-all-checkboxes';
+import { getAPIReady } from './get-api-ready';
 import { getPurposes } from './get-purposes';
 import { sendQueuedEvents } from './send-queued-events';
 import { set } from './set';
@@ -14,6 +15,7 @@ export const consent = {
   getAll,
   setAll,
   getPurposes,
+  getAPIReady,
   getAllCheckboxes,
   setCheckboxes,
   setAllCheckboxes,

src/consent/send-queued-event.spec.ts

@@ -9,17 +9,28 @@ declare global {
 
 let windowObj: Window & typeof globalThis;
 
+const warnSpy = jest.spyOn(console, 'warn');
+
 beforeAll(() => {
   windowObj = window;
+  warnSpy.mockImplementation();
 });
 
 afterAll(() => {
   window = windowObj;
+  warnSpy.mockRestore();
 });
 
 describe('sendQueuedEvents()', () => {
-  it('should call sendQueuedEvents method on zaraz consent', () => {
+  it("should not break when the Zaraz consent API hasn't been initialised", () => {
+    const sendQueuedEventsMock = jest.fn();
+    sendQueuedEvents();
+    expect(sendQueuedEventsMock).toHaveBeenCalledTimes(0);
+  });
+
+  it('should call sendQueuedEventsMock when the Zaraz consent API has been initialised', () => {
     const sendQueuedEventsMock = jest.fn();
+
     window.zaraz = {
       consent: {
         sendQueuedEvents: sendQueuedEventsMock,

src/consent/send-queued-events.ts

@@ -1,8 +1,15 @@
 import { getZaraz } from '../helpers/get-zaraz';
+import { showWarning } from '../helpers/show-warning';
 
 /**
  * If some Pageview-based events were not sent due to a lack of consent, they can be sent using this method after consent was granted.
  */
 export function sendQueuedEvents(): void {
-  getZaraz().consent.sendQueuedEvents();
+  const zaraz = getZaraz({ skipQueue: true });
+
+  if (typeof zaraz?.consent?.sendQueuedEvents === 'function') {
+    zaraz.consent.sendQueuedEvents();
+  } else {
+    showWarning(`sendQueuedEvents()`);
+  }
 }