@osano/osano-cmp-react-native 0.9.0 → 0.11.0

package/src/iab/gpp/api.js

@@ -0,0 +1,253 @@
+import {
+	formatConsentString,
+	makeFormatPingData,
+	makeParseConsentString,
+} from './consent';
+
+import { EventNames } from './constants';
+import { MAX_DATE } from '../../constants';
+import { getSupportedApis } from './selectors';
+
+/**
+ * An object that contains the client callback and metadata.
+ * @typedef {Object} EventSubscriber
+ * @property {number} version - The version of the API that the subscriber is
+ * listening to.
+ * @property {function} callback - The callback function that the subscriber
+ * provided. The signature should match the API version.
+ */
+
+/**
+ * The listener ID is a number that is used to identify a subscriber. It is both
+ * a key in the eventSubscribers map and a property that is given back to the
+ * subscriber. It must not change for the lifetime of the subscriber.
+ * @typedef {number} ListenerId
+ */
+
+/**
+ * A map of listener IDs to event subscribers.
+ * @type {Map<ListenerId, EventSubscriber>}
+ */
+const eventSubscribers = new Map();
+
+// Allows us to clear the event subscribers in tests
+export const _clearEventSubscribers =
+	process.env.NODE_ENV === 'jest' ? () => eventSubscribers.clear() : undefined;
+
+const createListenerId = () => {
+	let inc = 0;
+	let listenerId = MAX_DATE - Date.now();
+	do {
+		listenerId -= inc++;
+	} while (eventSubscribers.has(listenerId));
+
+	return listenerId;
+};
+
+/**
+ * Responsible for dispatching events to the subscribers.
+ * @param {number} apiVersion  - The version of the API as defined by the IAB.
+ * @param {object} data  - The data to dispatch to the subscribers.
+ */
+const makeDispatch = apiVersion =>
+	function dispatch(data) {
+		eventSubscribers.forEach(({ version, callback }, listenerId) => {
+			apiVersion === version &&
+				callback({
+					...data,
+					listenerId,
+				});
+		});
+	};
+
+/**
+ * The GPP has its own API but it can also call the older APIs. This function
+ * adapts the newer GPP call signature to the older APIs.
+ */
+const adaptedApis = new Map();
+
+// Allows us to clear the event subscribers in tests
+export const _clearAdaptedApis =
+	process.env.NODE_ENV === 'jest' ? () => adaptedApis.clear() : undefined;
+
+const getAdaptedApi = (clientApi, api) => {
+	// cache the adapted API so that we aren't creating a new function on every call
+	const adaptedApi = adaptedApis.get(clientApi);
+	if (adaptedApi) {
+		return adaptedApi;
+	}
+
+	// If the API is not available, throw an error. If the requested API is the
+	// GPP, throw an error (the GPP should never call itself as a sub-API).
+	if (!api || clientApi === 'gpp') {
+		throw new Error(`API ${clientApi} is not available`);
+	}
+
+	switch (clientApi) {
+		// pre-GPP APIs use the signature (command, version, callback, parameter)
+		case 'tcfeuv2':
+			adaptedApis.set(clientApi, (command, callback, parameter) =>
+				api(command, 2, callback, parameter),
+			);
+			break;
+		case 'uspv1':
+			adaptedApis.set(clientApi, (command, callback, parameter) =>
+				api(command, 1, callback, parameter),
+			);
+			break;
+		default:
+			adaptedApis.set(clientApi, api);
+	}
+
+	return adaptedApis.get(clientApi);
+};
+
+export default function makeApi(initOptions) {
+	const formatPingData = makeFormatPingData(initOptions);
+	const parseConsentString = makeParseConsentString(initOptions);
+	const makeEventSubscriber = callback => ({
+		version: initOptions.version,
+		callback,
+	});
+	const eventListenerReturn = (state, eventName, listenerId, data) => ({
+		eventName,
+		listenerId,
+		data,
+		pingData: formatPingData(state),
+	});
+	const dispatch = makeDispatch(initOptions.version);
+
+	function bind(store, allApis) {
+		const subApiSubscribers = new Map();
+		// The GPP spec says that events dispatched from section APIs should be
+		// dispatched from the GPP API. To do that, we'll subscribe to the
+		// events from the other APIs and re-dispatch them from here.
+		const initDispatchAggregator = () => {
+			if (subApiSubscribers.size > 0) {
+				// We have already initialized the dispatch aggregator
+				return;
+			}
+
+			const supportedApis = getSupportedApis(store.getState());
+			allApis.forEach((api, section) => {
+				if (!supportedApis.includes(section)) {
+					return;
+				}
+
+				const subscriber = data => {
+					// remove our own listener ID from the data object
+					// eslint-disable-next-line @typescript-eslint/no-unused-vars
+					const { listenerId, ...rest } = data;
+
+					dispatch({
+						// Other APIs don't currently have event names but if
+						// they are added this field should be dot-separated,
+						// e.g. `${section}.${data.eventName}`
+						eventName: section,
+						data: rest,
+						pingData: formatPingData(store.getState()),
+					});
+				};
+				subApiSubscribers.set(section, subscriber);
+				getAdaptedApi(section, api)('addEventListener', subscriber);
+			});
+		};
+
+		return function gppApi(command, callback, parameter) {
+			const state = store.getState();
+
+			switch (command) {
+				case 'ping': {
+					return formatPingData(state);
+				}
+
+				case 'addEventListener': {
+					// We wait to initialize the dispatch aggregator until there
+					// is at least one client event listener. Saves a little
+					// performance and ensures that all APIs are available.
+					initDispatchAggregator();
+					const listenerId = createListenerId();
+
+					try {
+						if (typeof callback !== 'function') {
+							throw new Error('Callback must be a function');
+						}
+						eventSubscribers.set(listenerId, makeEventSubscriber(callback));
+						const returnObject = eventListenerReturn(
+							state,
+							EventNames.LISTENER_REGISTERED,
+							listenerId,
+							true,
+						);
+
+						return returnObject;
+					} catch {
+						eventSubscribers.delete(listenerId);
+						return eventListenerReturn(
+							state,
+							EventNames.LISTENER_REGISTERED,
+							0,
+							false,
+						);
+					}
+				}
+
+				case 'removeEventListener': {
+					const listenerId = parseInt(parameter, 10);
+					const removed = eventSubscribers.delete(listenerId);
+					return eventListenerReturn(
+						state,
+						EventNames.LISTENER_REMOVED,
+						listenerId,
+						removed,
+					);
+				}
+
+				case 'hasSection': {
+					const section = parameter;
+					return getSupportedApis(state).includes(`${section}`);
+				}
+
+				/** Note that this command throws if the requested section
+				 * doesn't exist. The spec does not define what should happen in
+				 * this case. Returning nothing could be misleading so an error
+				 * is clearer. */
+				case 'getSection': {
+					const clientApi = parameter;
+					const sectionApi = getAdaptedApi(clientApi, allApis.get(clientApi));
+					return sectionApi('getSection');
+				}
+
+				/** Note that as above, this command throws if the requested
+				 * section does not exist and returns undefined if the field
+				 * doesn't exist. The spec is again silent on this case. */
+				case 'getField': {
+					const [clientApi, ...fieldPath] = parameter.split('.');
+					const sectionApi = getAdaptedApi(clientApi, allApis.get(clientApi));
+					return sectionApi('getField', undefined, fieldPath.join('.'));
+				}
+
+				case 'getGPPData': {
+					const gppString = formatConsentString(state);
+					return gppString ? parseConsentString(gppString, state) : undefined;
+				}
+
+				default: {
+					const mark = command.indexOf('.');
+					if (mark < 0) {
+						throw new Error(`Invalid command: ${command}`);
+					}
+					const clientApi = command.substring(0, mark);
+					const apiCommand = command.substring(mark + 1);
+					const sectionApi = getAdaptedApi(clientApi, allApis.get(clientApi));
+					return sectionApi(apiCommand, callback, parameter);
+				}
+			}
+		};
+	}
+
+	return {
+		bind,
+		dispatch,
+	};
+}

package/src/iab/gpp/consent.js

@@ -0,0 +1,114 @@
+import { CmpDisplayStatusCodes, CmpStatusCodes, SECTIONS } from './constants';
+import {
+	decode as base64Decode,
+	encode as base64Encode,
+} from './encoders/CompressedBase64UrlEncoder';
+import {
+	doesGDPRApply,
+	getConsentString,
+	getSupportedApis,
+	isBrowsingFrom,
+	isUiVisible,
+} from './selectors';
+import {
+	decode as fibRangeDecode,
+	encode as fibRangeEncode,
+} from './encoders/FibonacciIntegerRangeEncoder';
+
+import { CMP_ID } from '../constants';
+
+const ERROR_MESSAGE = 'Invalid GPP string';
+
+/* A note on the GPP version number: According to the GPP spec, the GPP string's
+ * header can only contain an integer version number. However, the API spec for
+ * the PingReturn object requires that the GPP version number is in the format
+ * Major.Minor (e.g. 1.0). It's not a problem for now but will be interesting if
+ * and when they introduce a version 1.1.
+ */
+const HEADER_PREFIX = 'DB'; // Section 3 ('D'), GPP v1 ('B')
+
+export const isSectionApplicable = (sectionId, state) => {
+	switch (sectionId) {
+		// case 1 is TCF v1 and is unsupported
+		case 2: // TCF EU v2
+			return doesGDPRApply(state);
+		// cases 3 and 4 are GPP header and integrity sections and are not applicable
+		case 5: // TCF CA
+			return isBrowsingFrom(state, 'ca');
+		case 6: // USPrivacy v1
+			// case 7: // US National
+			return isBrowsingFrom(state, 'us');
+		// We do not implement the GPP US-state spec
+		// case 8: // US California
+		//     return isBrowsingFrom(state, 'us-ca');
+		// case 9: // US Virginia
+		//     return isBrowsingFrom(state, 'us-va');
+		// case 10: // US Colorado
+		//     return isBrowsingFrom(state, 'us-co');
+		// case 11: // US Utah
+		//     return isBrowsingFrom(state, 'us-ut');
+		// case 12: // US Connecticut
+		//     return isBrowsingFrom(state, 'us-ct');
+		default:
+			return false;
+	}
+};
+
+export const makeFormatPingData = initOptions => state => ({
+	gppVersion: initOptions.version, // '1.0', see note above
+	cmpStatus: CmpStatusCodes.LOADED,
+	cmpDisplayStatus: isUiVisible(state)
+		? CmpDisplayStatusCodes.VISIBLE
+		: CmpDisplayStatusCodes.HIDDEN,
+	supportedAPIs: getSupportedApis(state),
+	cmpId: CMP_ID,
+});
+
+export const makeParseConsentString = initOptions => (gppString, state) => {
+	const [header, ...sections] = gppString.split('~');
+
+	// All GPPv1 strings must start with 'DB'
+	if (header.substring(0, 2) !== HEADER_PREFIX) {
+		throw new Error(`${ERROR_MESSAGE}: Invalid header`);
+	}
+
+	const expectedSections = fibRangeDecode(base64Decode(header.substring(2)));
+
+	if (sections.length !== expectedSections.length) {
+		throw new Error(
+			`${ERROR_MESSAGE}: Number of sections does not match header`,
+		);
+	}
+
+	return {
+		sectionId: 3,
+		gppVersion: 1, // see note above
+		sectionList: expectedSections,
+		applicableSections: expectedSections.filter(sectionId =>
+			isSectionApplicable(sectionId, state),
+		),
+		gppString,
+		pingData: makeFormatPingData(initOptions)(state),
+	};
+};
+
+export const formatConsentString = state => {
+	const consentStrings = getSupportedApis(state)
+		.map(section => ({
+			sectionId: SECTIONS[`${section}`],
+			consentString: getConsentString(state, section),
+		}))
+		.filter(({ consentString }) => consentString !== undefined)
+		.sort((a, b) => a.sectionId - b.sectionId);
+
+	const header = `${HEADER_PREFIX}${base64Encode(
+		fibRangeEncode(consentStrings.map(({ sectionId }) => sectionId)),
+	)}`;
+
+	const sections = [
+		header,
+		...consentStrings.map(({ consentString }) => consentString),
+	];
+
+	return sections.join('~');
+};

package/src/iab/gpp/constants.js

@@ -0,0 +1,49 @@
+// Comment-out the sections that we do not implement as they aren't necessary
+// for functionality.
+export const SECTIONS = {
+	// tcfeuv1: 1,
+	tcfeuv2: 2,
+	// GPP header section is ID 3
+	// GPP signal integrity section is ID 4
+	tcfcav1: 5,
+	uspv1: 6,
+	// usnatv1: 7,
+	// uscav1: 8,
+	// usvav1: 9,
+	// uscov1: 10,
+	// usutv1: 11,
+	// usctv1: 12,
+};
+
+/**
+ * GPP's defined CMP status codes
+ * @enum {string}
+ */
+export const CmpStatusCodes = {
+	STUB: 'stub',
+	LOADED: 'loaded',
+	ERROR: 'error',
+};
+
+/**
+ * GPP's defined CMP display status codes
+ * @enum {string}
+ */
+export const CmpDisplayStatusCodes = {
+	VISIBLE: 'visible',
+	HIDDEN: 'hidden',
+	DISABLED: 'disabled',
+};
+
+/**
+ * The GPP API's events
+ * @enum {string}
+ */
+export const EventNames = {
+	LISTENER_REGISTERED: 'listenerRegistered',
+	LISTENER_REMOVED: 'listenerRemoved',
+	CMP_STATUS_CHANGED: 'cmpStatus',
+	CMP_DISPLAY_STATUS_CHANGED: 'cmpDisplayStatus',
+	ERROR: 'error',
+	SECTION_CHANGED: 'sectionChange',
+};

package/src/iab/gpp/encoders/AbstractBase64UrlEncoder.ts

@@ -0,0 +1,89 @@
+/**
+ * Adapted from IABTechLab's GPP JavaScript Reference Implementation
+ *
+ * https://github.com/IABTechLab/iabgpp-es/blob/42060d7ac2b6d0ee70fc1b5bcd33fc447bf5123c/modules/cmpapi/src/encoder/datatype/encoder/AbstractBase64UrlEncoder.ts
+ *
+ * @license
+ * Copyright 2023 IABTechLab
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+import { InvalidBase64UrlError, InvalidBitStringError } from './errors';
+import {
+	decode as intDecode,
+	encode as intEncode,
+} from './FixedIntegerEncoder';
+
+/**
+ * Base 64 URL character set. Different from standard Base64 char set in that
+ * '+' and '/' are replaced with '-' and '_'.
+ */
+const DICT = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+// prettier-ignore
+const REVERSE_DICT: Record<string,number> = Object.freeze({
+    0: 52, 1: 53, 2: 54, 3: 55, 4: 56, 5: 57, 6: 58, 7: 59, 8: 60, 9: 61, A: 0,
+    B: 1, C: 2, D: 3, E: 4, F: 5, G: 6, H: 7, I: 8, J: 9, K: 10, L: 11, M: 12,
+    N: 13, O: 14, P: 15, Q: 16, R: 17, S: 18, T: 19, U: 20, V: 21, W: 22, X: 23,
+    Y: 24, Z: 25, a: 26, b: 27, c: 28, d: 29, e: 30, f: 31, g: 32, h: 33, i: 34,
+    j: 35, k: 36, l: 37, m: 38, n: 39, o: 40, p: 41, q: 42, r: 43, s: 44, t: 45,
+    u: 46, v: 47, w: 48, x: 49, y: 50, z: 51, '-': 62, _: 63,
+});
+
+export const makeEncode =
+	(pad: (str: string) => string) => (bitString: string) => {
+		// should only be 0 or 1
+		if (!/^[01]*$/.test(bitString)) {
+			throw new InvalidBitStringError(bitString);
+		}
+
+		bitString = pad(bitString);
+
+		let str = '';
+
+		let index = 0;
+		while (index <= bitString.length - 6) {
+			const s = bitString.substring(index, index + 6);
+			const n = intDecode(s);
+			const c = DICT.charAt(n);
+			str += c;
+
+			index += 6;
+		}
+
+		return str;
+	};
+
+export const decode = (str: string) => {
+	// should contain only characters from the base64url set
+	if (!/^[A-Za-z0-9\-_]*$/.test(str)) {
+		throw new InvalidBase64UrlError(str);
+	}
+
+	let bitString = '';
+
+	for (let i = 0; i < str.length; i++) {
+		const c = str.charAt(i);
+
+		const n = REVERSE_DICT[`${c}`]!;
+		const s = intEncode(n, 6);
+		bitString += s;
+	}
+
+	return bitString;
+};
+
+export default {
+	decode,
+	makeEncode,
+};

package/src/iab/gpp/encoders/BooleanEncoder.ts

@@ -0,0 +1,39 @@
+/**
+ * Adapted from IABTechLab's GPP JavaScript Reference Implementation
+ *
+ * https://github.com/IABTechLab/iabgpp-es/blob/42060d7ac2b6d0ee70fc1b5bcd33fc447bf5123c/modules/cmpapi/src/encoder/datatype/encoder/BooleanEncoder.ts
+ *
+ * @license
+ * Copyright 2023 IABTechLab
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+/**
+ * encode a TCString boolean
+ */
+export const encode = (bool: boolean) => {
+	return bool ? '1' : '0';
+};
+/**
+ * decode a TCString boolean
+ */
+export const decode = (bitString: string) => {
+	// fewer operations than !!parseInt(value, 2)
+	return bitString === '1';
+};
+
+export default {
+	decode,
+	encode,
+};

package/src/iab/gpp/encoders/CompressedBase64UrlEncoder.ts

@@ -0,0 +1,41 @@
+/**
+ * Adapted from IABTechLab's GPP JavaScript Reference Implementation
+ *
+ * https://github.com/IABTechLab/iabgpp-es/blob/42060d7ac2b6d0ee70fc1b5bcd33fc447bf5123c/modules/cmpapi/src/encoder/datatype/encoder/CompressedBase64UrlEncoder.ts
+ *
+ * @license
+ * Copyright 2023 IABTechLab
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+import { decode, makeEncode } from './AbstractBase64UrlEncoder';
+
+const pad = (bitString: string) => {
+	while (bitString.length % 8 > 0) {
+		bitString += '0';
+	}
+	while (bitString.length % 6 > 0) {
+		bitString += '0';
+	}
+	return bitString;
+};
+
+export const encode = makeEncode(pad);
+
+export { decode } from './AbstractBase64UrlEncoder';
+
+export default {
+	decode,
+	encode,
+};

package/src/iab/gpp/encoders/DatetimeEncoder.ts

@@ -0,0 +1,46 @@
+/**
+ * Adapted from IABTechLab's GPP JavaScript Reference Implementation
+ *
+ * https://github.com/IABTechLab/iabgpp-es/blob/42060d7ac2b6d0ee70fc1b5bcd33fc447bf5123c/modules/cmpapi/src/encoder/datatype/encoder/DatetimeEncoder.ts
+ *
+ * @license
+ * Copyright 2023 IABTechLab
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+import {
+	decode as intDecode,
+	encode as intEncode,
+} from './FixedIntegerEncoder';
+
+export const encode = (date: Date | number, numBits: number = 36) => {
+	let deciseconds: number;
+	if (date instanceof Date) {
+		deciseconds = Math.round(date.getTime() / 100);
+	} else {
+		deciseconds = date;
+	}
+	return intEncode(deciseconds, numBits);
+};
+
+export const decode = (bitString: string) => {
+	const date = new Date(intDecode(bitString) * 100);
+
+	return date;
+};
+
+export default {
+	decode,
+	encode,
+};