@osano/osano-cmp-react-native 0.18.4 → 0.18.5

package/src/ConsentManager.ts

@@ -683,12 +683,22 @@ export class ConsentManager {
 	private _translator: Translator = new Translator(this);
 	private _overridePalette?: Palette;
 	private _googleConsentModeCallback?: GoogleConsentModeCallback;
+	private _consentExpirationTestingSeconds?: number;
 
 	private _deviceId = '';
 	public get deviceId(): string {
 		return this._deviceId;
 	}
 
+	/**
+	 * The debug-only consent expiration testing window, in seconds, or
+	 * `undefined` when testing mode is disabled. Read by the consent service to
+	 * decide whether stored consent should be treated as expired.
+	 */
+	public get consentExpirationTestingSeconds(): number | undefined {
+		return this._consentExpirationTestingSeconds;
+	}
+
 	public get customerId(): string {
 		return this._config.customerId;
 	}
@@ -727,8 +737,28 @@ export class ConsentManager {
 	}
 
 	constructor(options?: OsanoOverrides, extUsrData?: string) {
-		const { locale, flavor, iabEnabled, iabFrameworks, iabVersions, palette } =
-			options || {};
+		const {
+			locale,
+			flavor,
+			iabEnabled,
+			iabFrameworks,
+			iabVersions,
+			palette,
+			consentExpirationTestingSeconds,
+		} = options || {};
+
+		// Debug-only: allow a short consent expiration window for testing. Held
+		// in memory only (never persisted), and ignored outside __DEV__.
+		if (
+			__DEV__ &&
+			consentExpirationTestingSeconds != null &&
+			consentExpirationTestingSeconds > 0
+		) {
+			this._consentExpirationTestingSeconds = consentExpirationTestingSeconds;
+			OsanoLogger.warn(
+				`⚠️ TESTING MODE - Consent will expire in ${consentExpirationTestingSeconds} seconds`,
+			);
+		}
 
 		this._config.iabEnabled = iabEnabled ?? undefined;
 		this._config.iabFrameworks = iabFrameworks || this._config.iabFrameworks;
@@ -994,6 +1024,42 @@ export class ConsentManager {
 		return this;
 	}
 
+	/**
+	 * Debug-only. Force stored consent to expire after `expirationSeconds` so the
+	 * consent banner can be re-triggered quickly during testing. Pass `null` (or a
+	 * non-positive value) to disable. The value is held in memory only and is
+	 * never persisted. Outside `__DEV__` this is a no-op (mirrors the Android
+	 * SDK's `setConsentExpirationTestingMode`, which is only available in debug
+	 * builds).
+	 *
+	 * Note: the expiration check runs while consent is loaded, so setting this at
+	 * init time (via `overrides.consentExpirationTestingSeconds`) is the reliable
+	 * path for a reload-and-reprompt test. A runtime call takes effect on the
+	 * next consent load.
+	 *
+	 * @param expirationSeconds - Seconds until consent expires, or `null` to disable.
+	 * @returns this ConsentManager instance for method chaining
+	 */
+	public setConsentExpirationTestingMode(
+		expirationSeconds: number | null,
+	): this {
+		if (!__DEV__) {
+			// Documented as a no-op outside debug builds — stay completely silent
+			// so production callers see no logging or side effects.
+			return this;
+		}
+		if (expirationSeconds == null || expirationSeconds <= 0) {
+			this._consentExpirationTestingSeconds = undefined;
+			OsanoLogger.info('Consent expiration testing mode disabled');
+		} else {
+			this._consentExpirationTestingSeconds = expirationSeconds;
+			OsanoLogger.warn(
+				`⚠️ TESTING MODE - Consent will expire in ${expirationSeconds} seconds`,
+			);
+		}
+		return this;
+	}
+
 	/**
 	 * Trigger Google Consent Mode update with current consent categories
 	 *

package/src/context.ts

@@ -32,6 +32,7 @@ type OsanoPublicContextType = {
 	setLocale: (locale: string) => void;
 	showBanner: () => void;
 	showDrawer: () => void;
+	setConsentExpirationTestingMode: (expirationSeconds: number | null) => void;
 	isReady: boolean;
 };
 
@@ -70,6 +71,7 @@ export const OsanoPublicContext = React.createContext<OsanoPublicContextType>({
 	setLocale: noop,
 	showBanner: noop,
 	showDrawer: noop,
+	setConsentExpirationTestingMode: noop,
 	isReady: false,
 });
 

package/src/index.tsx

@@ -161,6 +161,15 @@ export const Osano: React.FunctionComponent<
 			return consentManager.current.jurisdiction;
 		}, []);
 
+		const handleSetConsentExpirationTestingMode = useCallback(
+			(expirationSeconds: number | null) => {
+				consentManager.current.setConsentExpirationTestingMode(
+					expirationSeconds,
+				);
+			},
+			[],
+		);
+
 		const context = useMemo(() => {
 			return {
 				locale: consentManager.current.translator.locale,
@@ -172,6 +181,7 @@ export const Osano: React.FunctionComponent<
 				setLocale: handleSetLocale,
 				showBanner: handleShowDialog,
 				showDrawer: handleShowDrawer,
+				setConsentExpirationTestingMode: handleSetConsentExpirationTestingMode,
 				isReady: consentManager.current.loaded,
 			};
 		}, [

package/src/services/consent.ts

@@ -10,6 +10,7 @@ import {
 	makeConsentFromCategories,
 } from '../constants';
 import { clearStorage, getStorage, setStorage } from '../native/OsanoCmp';
+import { getConsentExpirationSeconds } from './gdprMappings';
 import type { Config } from '../types/consent-config';
 import { merge } from '../utils';
 import API from '../utils/API';
@@ -83,6 +84,15 @@ function createConsentRecordPayload(
 
 const STORAGE_KEY = 'osano_consentmanager';
 
+// The consent timestamp is scoped by configId so it tracks the consent record
+// for that config (both also carry the userSuffix). Older builds wrote a single
+// un-scoped key shared across configs; retrieveLastConsentTimestamp falls back
+// to it so existing installs keep their recorded date until the next write.
+const lastConsentDateKey = (configId: string, userSuffix: string) =>
+	`${STORAGE_KEY}_last_recorded_consent_date_${configId}${userSuffix}`;
+const legacyLastConsentDateKey = (userSuffix: string) =>
+	`${STORAGE_KEY}_last_recorded_consent_date${userSuffix}`;
+
 function consentRecordedRemotely(
 	configId: string,
 	success: boolean,
@@ -105,6 +115,10 @@ export const storeConsent = async (
 	cmp: ConsentManager,
 	consent?: ConsentCategoryType[],
 	recordedRemotely?: boolean,
+	// When restoring a remote record, the server's consent timestamp. Preserving
+	// it (instead of defaulting to "now") stops an old remote record from being
+	// re-dated as fresh. Defaults to now for locally-made choices.
+	consentDate?: string | Date,
 ): Promise<ConsentCategoryType[]> => {
 	cmp.consent = consent ?? cmp.consent;
 	return new Promise<ConsentCategoryType[]>((resolve, reject) => {
@@ -118,13 +132,17 @@ export const storeConsent = async (
 			cmp.extUsrData,
 		);
 		const userSuffix = hashedExtUsrData ? `_${hashedExtUsrData}` : '';
+		const parsedDate = consentDate ? new Date(consentDate) : new Date();
+		const recordedDate = Number.isNaN(parsedDate.getTime())
+			? new Date()
+			: parsedDate;
 		switch (Platform.OS) {
 			case 'ios':
 			case 'android':
 			default: {
 				setStorage(
-					`${STORAGE_KEY}_last_recorded_consent_date${userSuffix}`,
-					JSON.stringify(new Date()),
+					lastConsentDateKey(cmp.configId, userSuffix),
+					JSON.stringify(recordedDate),
 				)
 					.then(() => {
 						setStorage(
@@ -246,7 +264,27 @@ const clearToFirstLoadDefault = async (
 	return seed;
 };
 
+// After an expired/invalid record, settle on a persisted essential-only state.
+// Persisting (rather than only clearing the payload with clearConsent) keeps a
+// subsequent load in this safe state instead of falling back to the first-load
+// default — which, for Flavor 7, would re-enable analytics. This matters
+// because a later load may resolve no expiration window (testing off, offline
+// with no mappings cache, or a country with no interval), in which case empty
+// storage would otherwise re-seed the first-load default.
+const settleEssentialOnly = (
+	cmp: ConsentManager,
+): Promise<ConsentCategoryType[]> =>
+	storeConsent(cmp, [ConsentCategory.ESSENTIAL]);
+
 const retrieveConsent = async (cmp: ConsentManager) => {
+	// If stored consent has aged past its expiration window (production
+	// per-country interval, or the debug testing override), settle on a persisted
+	// essential-only state so callers see essential-only and a later load stays
+	// here (mirrors Android's clearExpiredConsent() + essential-only
+	// getConsentedCategories()).
+	if (await isConsentExpired(cmp)) {
+		return settleEssentialOnly(cmp);
+	}
 	return new Promise<ConsentCategoryType[]>((resolve) => {
 		const resConsent = (consentJson: string | null | undefined) => {
 			if (consentJson) {
@@ -298,34 +336,99 @@ const retrieveConsent = async (cmp: ConsentManager) => {
 	});
 };
 
-const retrieveLastConsentTimestamp = async (cmp: ConsentManager) => {
-	return new Promise<string>((resolve) => {
-		const resValue = (consentJson: string | null | undefined) => {
-			if (consentJson) {
-				const timestamp = JSON.parse(consentJson);
-				resolve(timestamp);
-				return timestamp;
-			} else {
-				resolve('');
-				return '';
-			}
-		};
-		const hashedExtUsrData = hashExtUsrData(
-			cmp.customerId,
-			cmp.configId,
-			cmp.extUsrData,
+const retrieveLastConsentTimestamp = async (
+	cmp: ConsentManager,
+): Promise<string> => {
+	const hashedExtUsrData = hashExtUsrData(
+		cmp.customerId,
+		cmp.configId,
+		cmp.extUsrData,
+	);
+	const userSuffix = hashedExtUsrData ? `_${hashedExtUsrData}` : '';
+
+	const parse = (json: string | null | undefined): string => {
+		if (!json) {
+			return '';
+		}
+		try {
+			return JSON.parse(json) as string;
+		} catch {
+			return '';
+		}
+	};
+
+	try {
+		const scoped = parse(
+			await getStorage(lastConsentDateKey(cmp.configId, userSuffix)),
 		);
-		const userSuffix = hashedExtUsrData ? `_${hashedExtUsrData}` : '';
-		switch (Platform.OS) {
-			case 'ios':
-			case 'android':
-			default:
-				getStorage(
-					`${STORAGE_KEY}_last_recorded_consent_date${userSuffix}`,
-				).then(resValue);
-				break;
+		if (scoped) {
+			return scoped;
 		}
-	});
+		// Fall back to the legacy un-scoped key for installs written before the
+		// timestamp was scoped by configId.
+		return parse(await getStorage(legacyLastConsentDateKey(userSuffix)));
+	} catch {
+		// Fail closed: a storage rejection resolves to no timestamp instead of
+		// hanging the consent load.
+		return '';
+	}
+};
+
+/**
+ * Resolves the effective expiration window in seconds, mirroring the Android
+ * SDK's single path:
+ *
+ *   debug testing override  ??  production interval (per-country, from the GDPR
+ *   mappings served at /mappings.json)
+ *
+ * Testing mode does not create a separate expiration path — it overrides the
+ * production interval. Returns null when neither is configured, in which case
+ * consent has no expiration.
+ */
+const effectiveExpirationSeconds = async (
+	cmp: ConsentManager,
+): Promise<number | null> => {
+	const testingSeconds = cmp.consentExpirationTestingSeconds;
+	// Testing override short-circuits the production lookup entirely, so debug
+	// runs never depend on the mappings fetch.
+	const seconds =
+		testingSeconds ?? (await getConsentExpirationSeconds(cmp.config?.country));
+	return seconds && seconds > 0 ? seconds : null;
+};
+
+/**
+ * True when `timestamp` is older than the `seconds` window. Fails closed
+ * (returns false) for a missing or unparseable timestamp, or when no window is
+ * configured, so a storage hiccup or a null window never wrongly expires
+ * consent.
+ */
+const isTimestampExpired = (
+	timestamp: string | number | Date | null | undefined,
+	seconds: number | null,
+): boolean => {
+	if (!seconds || !timestamp) {
+		return false;
+	}
+	const consentedAtMs = new Date(timestamp).getTime();
+	if (Number.isNaN(consentedAtMs)) {
+		return false;
+	}
+	return Date.now() - consentedAtMs > seconds * 1000;
+};
+
+/**
+ * Returns true when the locally stored consent has aged past its expiration
+ * window (see {@link effectiveExpirationSeconds}).
+ */
+export const isConsentExpired = async (
+	cmp: ConsentManager,
+): Promise<boolean> => {
+	const seconds = await effectiveExpirationSeconds(cmp);
+	if (!seconds) {
+		return false;
+	}
+	const timestamp = await retrieveLastConsentTimestamp(cmp);
+	return isTimestampExpired(timestamp, seconds);
 };
 
 export const recordConsent = (
@@ -399,17 +502,40 @@ export const fetchConsent = async (cmp: ConsentManager) => {
 			response as ConsentLookupResponseType;
 
 		if (!consented || !lastConsentTimestamp) {
-			// No remote consent found, use local consent
-			await storeConsent(cmp, consent);
+			// No remote record — keep the local consent as-is. Re-storing it here
+			// would reset the recorded-consent timestamp to "now" on every load, so
+			// expiration would never fire for remote + extUsrData users, and it
+			// could re-persist an essential-only clear. The local consent is already
+			// stored with its real timestamp (or is a first-load default that stays
+			// re-seeded).
 			return consent;
 		}
 
+		// Evaluate the remote record against the server's own timestamp (when the
+		// visitor actually consented), not "now", so an already-expired remote
+		// record is never restored and re-dated as fresh.
+		const seconds = await effectiveExpirationSeconds(cmp);
+		const remoteExpired = isTimestampExpired(lastConsentTimestamp, seconds);
+
 		// If extUsrData is not null and not empty, always use remote consent (cross-device consent enabled)
 		if (extUsrData && extUsrData.trim() !== '') {
+			if (remoteExpired) {
+				// The authoritative remote record has expired; settle on a persisted
+				// essential-only state rather than restoring stale consent, so a
+				// subsequent load stays here instead of falling back to the
+				// first-load default.
+				return settleEssentialOnly(cmp);
+			}
 			const remoteConsentCategories = consented.map(
 				(category) => ConsentCategory[category as keyof typeof ConsentCategory],
 			);
-			await storeConsent(cmp, remoteConsentCategories, true);
+			// Preserve the server timestamp so restoring can't re-date the record.
+			await storeConsent(
+				cmp,
+				remoteConsentCategories,
+				true,
+				lastConsentTimestamp,
+			);
 			return remoteConsentCategories;
 		}
 
@@ -417,14 +543,21 @@ export const fetchConsent = async (cmp: ConsentManager) => {
 		const internalTimestamp = await retrieveLastConsentTimestamp(cmp);
 		try {
 			if (
-				new Date(lastConsentTimestamp) > new Date(internalTimestamp) ||
-				internalTimestamp === ''
+				!remoteExpired &&
+				(new Date(lastConsentTimestamp) > new Date(internalTimestamp) ||
+					internalTimestamp === '')
 			) {
-				// Remote consent is newer or we haven't recorded any consent yet. Store remote consent.
+				// Remote consent is newer, unexpired, or we haven't recorded any
+				// consent yet. Store it, preserving the server timestamp.
 				const remoteConsentCategories = formatConsentArray(
 					makeConsentFromCategories(consented),
 				);
-				await storeConsent(cmp, remoteConsentCategories, true);
+				await storeConsent(
+					cmp,
+					remoteConsentCategories,
+					true,
+					lastConsentTimestamp,
+				);
 
 				return remoteConsentCategories;
 			}

package/src/services/gdprMappings.ts

@@ -0,0 +1,126 @@
+import { env } from '../constants';
+import { getStorage, setStorage } from '../native/OsanoCmp';
+import { osanoLogger } from '../utils/OsanoLogger';
+
+const { OSANO_ORIGIN } = env;
+
+const STORAGE_KEY = 'osano_consentmanager';
+const MAPPINGS_KEY = `${STORAGE_KEY}_gdpr_mappings`;
+const MAPPINGS_LAST_FETCHED_KEY = `${STORAGE_KEY}_gdpr_mappings_last_fetched`;
+
+// Refresh the mappings at most once a day, matching the Android SDK's
+// GdprCountryCache cache window.
+const CACHE_DURATION_MS = 24 * 60 * 60 * 1000;
+
+// Fallback bucket in the mappings document, used when the visitor's country has
+// no entry of its own. Mirrors the Android SDK's DEFAULT_GDPR_COUNTRY_KEY.
+const DEFAULT_COUNTRY_KEY = 'defaults';
+
+/**
+ * Per-country GDPR metadata served at `/mappings.json`. Only the fields the SDK
+ * consumes are typed here; the document may carry more (e.g. forced
+ * classifications) that we intentionally ignore.
+ */
+export type GdprCountryInfo = {
+	gdprApplies?: boolean;
+	flavor?: string;
+	// Production consent lifetime, in seconds, measured from when the visitor
+	// consented. Consumed as seconds to match the Android SDK.
+	consentExpiration?: number;
+};
+
+export type GdprMappings = Record<string, GdprCountryInfo>;
+
+const readCachedMappings = async (): Promise<GdprMappings | null> => {
+	try {
+		const raw = await getStorage(MAPPINGS_KEY);
+		return raw ? (JSON.parse(raw) as GdprMappings) : null;
+	} catch {
+		return null;
+	}
+};
+
+const isCacheFresh = async (): Promise<boolean> => {
+	try {
+		const raw = await getStorage(MAPPINGS_LAST_FETCHED_KEY);
+		if (!raw) {
+			return false;
+		}
+		const lastFetched = Number(JSON.parse(raw));
+		if (Number.isNaN(lastFetched)) {
+			return false;
+		}
+		return Date.now() - lastFetched < CACHE_DURATION_MS;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * Returns the GDPR country mappings, preferring a fresh (<24h) cache and
+ * otherwise fetching `${OSANO_ORIGIN}/mappings.json`. On a network/parse error
+ * it falls back to any stale cache rather than losing production expiration.
+ * Returns null only when there is neither a usable network response nor a
+ * cached copy.
+ */
+export const fetchGdprMappings = async (): Promise<GdprMappings | null> => {
+	if (await isCacheFresh()) {
+		const cached = await readCachedMappings();
+		if (cached) {
+			return cached;
+		}
+	}
+
+	try {
+		const response = await fetch(`${OSANO_ORIGIN}/mappings.json`, {
+			method: 'GET',
+			headers: {
+				Accept: 'application/json',
+				'Content-Type': 'application/json',
+			},
+			mode: 'cors',
+			referrer: 'no-referrer',
+		});
+
+		if (!response.ok) {
+			throw response;
+		}
+
+		const mappings = (await response.json()) as GdprMappings;
+		await Promise.all([
+			setStorage(MAPPINGS_KEY, JSON.stringify(mappings)),
+			setStorage(MAPPINGS_LAST_FETCHED_KEY, JSON.stringify(Date.now())),
+		]);
+		return mappings;
+	} catch (error) {
+		osanoLogger.error('Error fetching GDPR mappings:', error as Error);
+		// Serve stale data over nothing so production expiration keeps working
+		// while offline.
+		return readCachedMappings();
+	}
+};
+
+/**
+ * Resolves the production consent-expiration interval (in seconds) for a
+ * country from the GDPR mappings: the country's own value, falling back to the
+ * `defaults` bucket. Returns null when no positive interval is configured — in
+ * that case consent has no production expiration.
+ *
+ * Note: unlike the Android SDK, there is no hardcoded numeric fallback here.
+ * Android returns `365` when nothing is configured, but consumes it as seconds
+ * (~6 minutes), which would silently expire production consent; failing open is
+ * the safer behavior.
+ */
+export const getConsentExpirationSeconds = async (
+	country: string | undefined,
+): Promise<number | null> => {
+	const mappings = await fetchGdprMappings();
+	if (!mappings) {
+		return null;
+	}
+	const key = (country ?? '').toLowerCase();
+	const value =
+		mappings[key]?.consentExpiration ??
+		mappings[DEFAULT_COUNTRY_KEY]?.consentExpiration;
+	return typeof value === 'number' && value > 0 ? value : null;
+};

package/src/types/index.d.ts

@@ -19,6 +19,15 @@ export type OsanoOverrides = {
 		usp?: UspVersionType;
 	};
 	palette?: Palette;
+	/**
+	 * Debug-only. Overrides the production consent-expiration interval with this
+	 * many seconds so the consent banner can be re-triggered quickly during
+	 * testing. This does not create a separate expiration path — production
+	 * consent expires on the per-country interval from the GDPR mappings, and
+	 * this simply substitutes a shorter window. Ignored outside `__DEV__`.
+	 * Mirrors the Android SDK's builder `setConsentExpirationTestingMode`.
+	 */
+	consentExpirationTestingSeconds?: number;
 };
 
 export interface OsanoProps {