@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/engine/admobEngine.ts

@@ -1,404 +1,399 @@
-/**
- * Default AdsEngine adapter for Google AdMob on Android.
- *
- * **This is the only module in the package that knows an ad provider exists.**
- * It lazily requires `react-native-google-mobile-ads`, mirroring
- * `packages/rn-camera/src/native/cameraEngine.ts`, so unit tests that inject the
- * fake never load native code and an unsupported platform never loads it at all.
- *
- * Targets bridge 16.0.3, whose ads SDK (24.9.0) predates the Kotlin 2.3 metadata
- * bump that makes newer releases uncompilable under React Native 0.85's pinned
- * Kotlin compiler — see specs/011-rn-advertising-sdk/research.md (R2).
- *
- * Ordering note: `setRequestConfiguration` must run *before* `initialize`, or
- * the child-directed and under-age flags do not take effect. That is why FR-020
- * treats a later change as requiring re-initialization rather than pretending it
- * applied.
- */
-
-import { Platform } from 'react-native';
-
-import type { AdContentRating, FullScreenFormat, Unsubscribe } from '../config/types';
-import type {
-	AdsEngine,
-	ConsentPort,
-	EngineAdEvent,
-	EngineAdHandle,
-	EngineConsentInfo,
-	EngineConsentOptions,
-	EnginePrivacy,
-	EngineRequestOptions,
-} from './port';
-
-/** The slice of the bridge this adapter uses. Kept local so nothing else sees it. */
-interface ProviderFullScreenAd {
-	load(): void;
-	show(): Promise<unknown>;
-	addAdEventListener(type: string, listener: (payload?: unknown) => void): () => void;
-}
-
-interface ProviderModule {
-	MobileAds: () => {
-		initialize(): Promise<unknown>;
-		setRequestConfiguration(config: Record<string, unknown>): Promise<unknown>;
-	};
-	InterstitialAd: {
-		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
-	};
-	RewardedAd: {
-		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
-	};
-	AppOpenAd: {
-		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
-	};
-	AdEventType: Record<string, string>;
-	RewardedAdEventType: Record<string, string>;
-	MaxAdContentRating: Record<string, string>;
-	AdsConsent: ProviderConsent;
-	AdsConsentDebugGeography: Record<string, number>;
-}
-
-/** The slice of the bridge's consent module this adapter uses. */
-interface ProviderConsent {
-	requestInfoUpdate(options?: Record<string, unknown>): Promise<ProviderConsentInfo>;
-	loadAndShowConsentFormIfRequired(): Promise<ProviderConsentInfo>;
-	showPrivacyOptionsForm(): Promise<ProviderConsentInfo>;
-	getConsentInfo(): Promise<ProviderConsentInfo>;
-	reset(): void;
-}
-
-interface ProviderConsentInfo {
-	status?: string;
-	canRequestAds?: boolean;
-	isConsentFormAvailable?: boolean;
-	privacyOptionsRequirementStatus?: string;
-}
-
-/**
- * The provider's geography enum is numeric and its spelling is the provider's.
- * Translating here rather than in `core/` is the same rule the rest of this file
- * follows: the one module that knows a provider exists is the one that speaks
- * its vocabulary.
- */
-function toProviderGeography(
-	geography: EngineConsentOptions['debugGeography'],
-	values: Record<string, number>,
-): number | undefined {
-	switch (geography) {
-		case 'eea':
-			return values.EEA;
-		case 'not_eea':
-			return values.NOT_EEA;
-		case 'regulated_us_state':
-			return values.REGULATED_US_STATE;
-		case 'other':
-			return values.OTHER;
-		case 'disabled':
-			return values.DISABLED;
-		default:
-			return undefined;
-	}
-}
-
-/**
- * Normalizes the provider's consent shape into the engine's.
- *
- * `canRequestAds` is taken as reported and never inferred from the status: the
- * provider is the authority on whether a request is permitted, and second-
- * guessing it here is how a package ends up requesting ads it should not
- * (FR-106, FR-107).
- */
-function toEngineConsentInfo(info: ProviderConsentInfo): EngineConsentInfo {
-	const status = String(info.status ?? 'UNKNOWN').toUpperCase();
-	const normalized: EngineConsentInfo['status'] =
-		status === 'OBTAINED'
-			? 'obtained'
-			: status === 'REQUIRED'
-				? 'required'
-				: status === 'NOT_REQUIRED'
-					? 'not_required'
-					: 'unknown';
-	return {
-		status: normalized,
-		canRequestAds: info.canRequestAds === true,
-		isFormAvailable: info.isConsentFormAvailable === true,
-		privacyOptions: toEnginePrivacyOptions(info.privacyOptionsRequirementStatus),
-	};
-}
-
-/**
- * Same rule as the status: an unrecognized value is `unknown`, never a guess in
- * either direction (FR-150).
- */
-function toEnginePrivacyOptions(value: string | undefined): EngineConsentInfo['privacyOptions'] {
-	switch (String(value ?? 'UNKNOWN').toUpperCase()) {
-		case 'REQUIRED':
-			return 'required';
-		case 'NOT_REQUIRED':
-			return 'not_required';
-		default:
-			return 'unknown';
-	}
-}
-
-function loadProvider(): ProviderModule | null {
-	try {
-		return require('react-native-google-mobile-ads') as ProviderModule;
-	} catch {
-		// The bridge is a required peer, but a consumer can still have it missing
-		// mid-install or excluded from a build. Reporting `provider_missing`
-		// beats crashing the host app's launch (FR-025, NFR-005).
-		return null;
-	}
-}
-
-function toProviderRating(
-	rating: AdContentRating | undefined,
-	ratings: Record<string, string>,
-): string | undefined {
-	return rating ? ratings[rating] : undefined;
-}
-
-/** One unsubscribe covering every listener that was actually registered. */
-function makeUnsubscribe(removers: readonly (() => void)[]): Unsubscribe {
-	let active = true;
-	return () => {
-		if (!active) {
-			return;
-		}
-		active = false;
-		for (const remove of removers) {
-			try {
-				remove();
-			} catch {
-				// A provider that throws on removal must not prevent the rest of
-				// cleanup from running (FR-035).
-			}
-		}
-	};
-}
-
-export function createAdMobEngine(): AdsEngine {
-	// v1 is Android-only. On any other platform this stays null and every
-	// operation resolves to `unsupported_platform` (SC-004, scenario 12).
-	const supported = Platform.OS === 'android';
-	let provider: ProviderModule | null = null;
-	let providerResolved = false;
-
-	function getProvider(): ProviderModule | null {
-		if (!supported) {
-			return null;
-		}
-		if (!providerResolved) {
-			providerResolved = true;
-			provider = loadProvider();
-		}
-		return provider;
-	}
-
-	// The format is kept alongside the ad because the provider validates which
-	// event types a given ad object accepts, and rejects the rewarded ones on an
-	// interstitial by throwing (see `subscribe`).
-	const ads = new Map<string, { ad: ProviderFullScreenAd; format: FullScreenFormat }>();
-	let counter = 0;
-
-	return {
-		isAvailable() {
-			return supported && getProvider() !== null;
-		},
-
-		async initialize(privacy: EnginePrivacy) {
-			const module = getProvider();
-			if (!module) {
-				throw new Error('provider_missing');
-			}
-			const mobileAds = module.MobileAds();
-
-			// Before initialize(), deliberately. See the ordering note above.
-			await mobileAds.setRequestConfiguration({
-				tagForChildDirectedTreatment: privacy.childDirected,
-				tagForUnderAgeOfConsent: privacy.underAgeOfConsent,
-				maxAdContentRating: toProviderRating(
-					privacy.maxAdContentRating,
-					module.MaxAdContentRating,
-				),
-				testDeviceIdentifiers: privacy.testDeviceIds ? [...privacy.testDeviceIds] : undefined,
-			});
-
-			await mobileAds.initialize();
-		},
-
-		async createFullScreen(
-			format: FullScreenFormat,
-			adUnitId: string,
-			request?: EngineRequestOptions,
-		) {
-			const module = getProvider();
-			if (!module) {
-				throw new Error('provider_missing');
-			}
-
-			const factory =
-				format === 'rewarded'
-					? module.RewardedAd
-					: format === 'app_open'
-						? module.AppOpenAd
-						: module.InterstitialAd;
-			const ad = factory.createForAdRequest(adUnitId, {
-				// The consumer-facing polarity is `personalizedAds`; the provider's
-				// is the inverse. The flip lives here, next to the API needing it.
-				requestNonPersonalizedAdsOnly: request?.personalizedAds === false,
-			});
-
-			counter += 1;
-			const id = `admob-${counter}`;
-			ads.set(id, { ad, format });
-			// The provider loads asynchronously; callbacks arrive through subscribe.
-			ad.load();
-			return { id } satisfies EngineAdHandle;
-		},
-
-		async show(handle) {
-			const entry = ads.get(handle.id);
-			if (!entry) {
-				throw new Error('ad handle disposed');
-			}
-			await entry.ad.show();
-		},
-
-		subscribe(handle, listener): Unsubscribe {
-			const module = getProvider();
-			const entry = ads.get(handle.id);
-			if (!module || !entry) {
-				return () => undefined;
-			}
-
-			const { ad, format } = entry;
-			const { AdEventType, RewardedAdEventType } = module;
-			const removers: Array<() => void> = [];
-
-			const on = (type: string | undefined, map: (payload?: unknown) => EngineAdEvent | null) => {
-				if (!type) {
-					return;
-				}
-				try {
-					removers.push(
-						ad.addAdEventListener(type, payload => {
-							const event = map(payload);
-							if (event) {
-								listener(event);
-							}
-						}),
-					);
-				} catch {
-					// The provider validates event types per ad object and throws on
-					// one it does not accept. Skipping the listener keeps a single
-					// rejected type from tearing down the whole subscription — which
-					// would fail the load outright while the ad went on to load fine,
-					// reporting a `provider_error` for an ad that was never broken.
-				}
-			};
-
-			on(AdEventType.LOADED, () => ({ type: 'loaded' }));
-			on(AdEventType.ERROR, cause => ({ type: 'failed', cause }));
-			on(AdEventType.OPENED, () => ({ type: 'opened' }));
-			on(AdEventType.CLICKED, () => ({ type: 'clicked' }));
-			on(AdEventType.CLOSED, () => ({ type: 'dismissed' }));
-
-			// Rewarded-only, and gated on the format because the provider REJECTS
-			// these types on an interstitial. The rewarded loaded event is distinct
-			// from AdEventType.LOADED, and EARNED_REWARD is distinct from CLOSED —
-			// which is precisely what makes FR-046 and FR-048 enforceable rather
-			// than a guess about ordering.
-			if (format !== 'rewarded') {
-				return makeUnsubscribe(removers);
-			}
-
-			on(RewardedAdEventType.LOADED, () => ({ type: 'loaded' }));
-			on(RewardedAdEventType.EARNED_REWARD, payload => {
-				const source = (payload ?? {}) as { type?: unknown; amount?: unknown };
-				const amount = Number(source.amount);
-				return {
-					type: 'rewarded',
-					reward: {
-						type: typeof source.type === 'string' ? source.type : 'reward',
-						amount: Number.isFinite(amount) ? amount : 0,
-					},
-				};
-			});
-
-			return makeUnsubscribe(removers);
-		},
-
-		dispose(handle) {
-			ads.delete(handle.id);
-		},
-
-		consent: createAdMobConsent(getProvider),
-	};
-}
-
-/**
- * The consent platform adapter.
- *
- * It is deliberately thin. Every decision that could be made here — whether a
- * region requires consent, whether an error means "no", whether a dismissed form
- * counts — is made elsewhere or not at all: the provider owns the first, and
- * `core/consentFlow.ts` owns the second and third. This file's only job is to
- * call the right method and hand back a shape that names nothing Google.
- */
-function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPort {
-	function requireConsent(): ProviderConsent {
-		const module = getProvider();
-		if (!module?.AdsConsent) {
-			throw new Error('provider_missing');
-		}
-		return module.AdsConsent;
-	}
-
-	return {
-		async requestInfoUpdate(options: EngineConsentOptions) {
-			const module = getProvider();
-			if (!module?.AdsConsent) {
-				throw new Error('provider_missing');
-			}
-			const debugGeography = toProviderGeography(
-				options.debugGeography,
-				module.AdsConsentDebugGeography ?? {},
-			);
-			const info = await module.AdsConsent.requestInfoUpdate({
-				// Passing `undefined` rather than omitting keeps the call shape
-				// stable; the bridge treats an absent value as "no override".
-				debugGeography,
-				tagForUnderAgeOfConsent: options.underAgeOfConsent,
-				testDeviceIdentifiers: options.testDeviceIds
-					? [...options.testDeviceIds]
-					: undefined,
-			});
-			return toEngineConsentInfo(info);
-		},
-
-		async showFormIfRequired() {
-			// The provider decides whether a form is needed and renders it. The
-			// package never draws consent UI of its own (FR-103).
-			const info = await requireConsent().loadAndShowConsentFormIfRequired();
-			return toEngineConsentInfo(info);
-		},
-
-		async showPrivacyOptionsForm() {
-			// Present in the pinned bridge 16.0.3, so no range change (FR-155).
-			// Resolves with the consent information as it stands once the form
-			// closes, whether the user changed anything or not.
-			const info = await requireConsent().showPrivacyOptionsForm();
-			return toEngineConsentInfo(info);
-		},
-
-		async getInfo() {
-			return toEngineConsentInfo(await requireConsent().getConsentInfo());
-		},
-
-		reset() {
-			requireConsent().reset();
-		},
-	};
-}
+/**
+ * Default AdsEngine adapter for Google AdMob on Android.
+ *
+ * **This is the only module in the package that knows an ad provider exists.**
+ * It lazily requires `react-native-google-mobile-ads`, mirroring
+ * `packages/rn-camera/src/native/cameraEngine.ts`, so unit tests that inject the
+ * fake never load native code and an unsupported platform never loads it at all.
+ *
+ * Targets bridge 16.0.3, whose ads SDK (24.9.0) predates the Kotlin 2.3 metadata
+ * bump that makes newer releases uncompilable under React Native 0.85's pinned
+ * Kotlin compiler — see specs/011-rn-advertising-sdk/research.md (R2).
+ *
+ * Ordering note: `setRequestConfiguration` must run *before* `initialize`, or
+ * the child-directed and under-age flags do not take effect. That is why FR-020
+ * treats a later change as requiring re-initialization rather than pretending it
+ * applied.
+ */
+
+import { Platform } from 'react-native';
+
+import type { AdContentRating, FullScreenFormat, Unsubscribe } from '../config/types';
+import type {
+	AdsEngine,
+	ConsentPort,
+	EngineAdEvent,
+	EngineAdHandle,
+	EngineConsentInfo,
+	EngineConsentOptions,
+	EnginePrivacy,
+	EngineRequestOptions,
+} from './port';
+
+/** The slice of the bridge this adapter uses. Kept local so nothing else sees it. */
+interface ProviderFullScreenAd {
+	load(): void;
+	show(): Promise<unknown>;
+	addAdEventListener(type: string, listener: (payload?: unknown) => void): () => void;
+}
+
+interface ProviderModule {
+	MobileAds: () => {
+		initialize(): Promise<unknown>;
+		setRequestConfiguration(config: Record<string, unknown>): Promise<unknown>;
+	};
+	InterstitialAd: {
+		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
+	};
+	RewardedAd: {
+		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
+	};
+	AppOpenAd: {
+		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
+	};
+	AdEventType: Record<string, string>;
+	RewardedAdEventType: Record<string, string>;
+	MaxAdContentRating: Record<string, string>;
+	AdsConsent: ProviderConsent;
+	AdsConsentDebugGeography: Record<string, number>;
+}
+
+/** The slice of the bridge's consent module this adapter uses. */
+interface ProviderConsent {
+	requestInfoUpdate(options?: Record<string, unknown>): Promise<ProviderConsentInfo>;
+	loadAndShowConsentFormIfRequired(): Promise<ProviderConsentInfo>;
+	showPrivacyOptionsForm(): Promise<ProviderConsentInfo>;
+	getConsentInfo(): Promise<ProviderConsentInfo>;
+	reset(): void;
+}
+
+interface ProviderConsentInfo {
+	status?: string;
+	canRequestAds?: boolean;
+	isConsentFormAvailable?: boolean;
+	privacyOptionsRequirementStatus?: string;
+}
+
+/**
+ * The provider's geography enum is numeric and its spelling is the provider's.
+ * Translating here rather than in `core/` is the same rule the rest of this file
+ * follows: the one module that knows a provider exists is the one that speaks
+ * its vocabulary.
+ */
+function toProviderGeography(
+	geography: EngineConsentOptions['debugGeography'],
+	values: Record<string, number>,
+): number | undefined {
+	switch (geography) {
+		case 'eea':
+			return values.EEA;
+		case 'not_eea':
+			return values.NOT_EEA;
+		case 'regulated_us_state':
+			return values.REGULATED_US_STATE;
+		case 'other':
+			return values.OTHER;
+		case 'disabled':
+			return values.DISABLED;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Normalizes the provider's consent shape into the engine's.
+ *
+ * `canRequestAds` is taken as reported and never inferred from the status: the
+ * provider is the authority on whether a request is permitted, and second-
+ * guessing it here is how a package ends up requesting ads it should not
+ * (FR-106, FR-107).
+ */
+function toEngineConsentInfo(info: ProviderConsentInfo): EngineConsentInfo {
+	const status = String(info.status ?? 'UNKNOWN').toUpperCase();
+	const normalized: EngineConsentInfo['status'] =
+		status === 'OBTAINED'
+			? 'obtained'
+			: status === 'REQUIRED'
+				? 'required'
+				: status === 'NOT_REQUIRED'
+					? 'not_required'
+					: 'unknown';
+	return {
+		status: normalized,
+		canRequestAds: info.canRequestAds === true,
+		isFormAvailable: info.isConsentFormAvailable === true,
+		privacyOptions: toEnginePrivacyOptions(info.privacyOptionsRequirementStatus),
+	};
+}
+
+/**
+ * Same rule as the status: an unrecognized value is `unknown`, never a guess in
+ * either direction (FR-150).
+ */
+function toEnginePrivacyOptions(value: string | undefined): EngineConsentInfo['privacyOptions'] {
+	switch (String(value ?? 'UNKNOWN').toUpperCase()) {
+		case 'REQUIRED':
+			return 'required';
+		case 'NOT_REQUIRED':
+			return 'not_required';
+		default:
+			return 'unknown';
+	}
+}
+
+function loadProvider(): ProviderModule | null {
+	try {
+		return require('react-native-google-mobile-ads') as ProviderModule;
+	} catch {
+		// The bridge is a required peer, but a consumer can still have it missing
+		// mid-install or excluded from a build. Reporting `provider_missing`
+		// beats crashing the host app's launch (FR-025, NFR-005).
+		return null;
+	}
+}
+
+function toProviderRating(
+	rating: AdContentRating | undefined,
+	ratings: Record<string, string>,
+): string | undefined {
+	return rating ? ratings[rating] : undefined;
+}
+
+/** One unsubscribe covering every listener that was actually registered. */
+function makeUnsubscribe(removers: readonly (() => void)[]): Unsubscribe {
+	let active = true;
+	return () => {
+		if (!active) {
+			return;
+		}
+		active = false;
+		for (const remove of removers) {
+			try {
+				remove();
+			} catch {
+				// A provider that throws on removal must not prevent the rest of
+				// cleanup from running (FR-035).
+			}
+		}
+	};
+}
+
+export function createAdMobEngine(): AdsEngine {
+	// v1 is Android-only. On any other platform this stays null and every
+	// operation resolves to `unsupported_platform` (SC-004, scenario 12).
+	const supported = Platform.OS === 'android';
+	let provider: ProviderModule | null = null;
+	let providerResolved = false;
+
+	function getProvider(): ProviderModule | null {
+		if (!supported) {
+			return null;
+		}
+		if (!providerResolved) {
+			providerResolved = true;
+			provider = loadProvider();
+		}
+		return provider;
+	}
+
+	// The format is kept alongside the ad because the provider validates which
+	// event types a given ad object accepts, and rejects the rewarded ones on an
+	// interstitial by throwing (see `subscribe`).
+	const ads = new Map<string, { ad: ProviderFullScreenAd; format: FullScreenFormat }>();
+	let counter = 0;
+
+	return {
+		isAvailable() {
+			return supported && getProvider() !== null;
+		},
+
+		async initialize(privacy: EnginePrivacy) {
+			const module = getProvider();
+			if (!module) {
+				throw new Error('provider_missing');
+			}
+			const mobileAds = module.MobileAds();
+
+			// Before initialize(), deliberately. See the ordering note above.
+			await mobileAds.setRequestConfiguration({
+				tagForChildDirectedTreatment: privacy.childDirected,
+				tagForUnderAgeOfConsent: privacy.underAgeOfConsent,
+				maxAdContentRating: toProviderRating(privacy.maxAdContentRating, module.MaxAdContentRating),
+				testDeviceIdentifiers: privacy.testDeviceIds ? [...privacy.testDeviceIds] : undefined,
+			});
+
+			await mobileAds.initialize();
+		},
+
+		async createFullScreen(
+			format: FullScreenFormat,
+			adUnitId: string,
+			request?: EngineRequestOptions,
+		) {
+			const module = getProvider();
+			if (!module) {
+				throw new Error('provider_missing');
+			}
+
+			const factory =
+				format === 'rewarded'
+					? module.RewardedAd
+					: format === 'app_open'
+						? module.AppOpenAd
+						: module.InterstitialAd;
+			const ad = factory.createForAdRequest(adUnitId, {
+				// The consumer-facing polarity is `personalizedAds`; the provider's
+				// is the inverse. The flip lives here, next to the API needing it.
+				requestNonPersonalizedAdsOnly: request?.personalizedAds === false,
+			});
+
+			counter += 1;
+			const id = `admob-${counter}`;
+			ads.set(id, { ad, format });
+			// The provider loads asynchronously; callbacks arrive through subscribe.
+			ad.load();
+			return { id } satisfies EngineAdHandle;
+		},
+
+		async show(handle) {
+			const entry = ads.get(handle.id);
+			if (!entry) {
+				throw new Error('ad handle disposed');
+			}
+			await entry.ad.show();
+		},
+
+		subscribe(handle, listener): Unsubscribe {
+			const module = getProvider();
+			const entry = ads.get(handle.id);
+			if (!module || !entry) {
+				return () => undefined;
+			}
+
+			const { ad, format } = entry;
+			const { AdEventType, RewardedAdEventType } = module;
+			const removers: Array<() => void> = [];
+
+			const on = (type: string | undefined, map: (payload?: unknown) => EngineAdEvent | null) => {
+				if (!type) {
+					return;
+				}
+				try {
+					removers.push(
+						ad.addAdEventListener(type, payload => {
+							const event = map(payload);
+							if (event) {
+								listener(event);
+							}
+						}),
+					);
+				} catch {
+					// The provider validates event types per ad object and throws on
+					// one it does not accept. Skipping the listener keeps a single
+					// rejected type from tearing down the whole subscription — which
+					// would fail the load outright while the ad went on to load fine,
+					// reporting a `provider_error` for an ad that was never broken.
+				}
+			};
+
+			on(AdEventType.LOADED, () => ({ type: 'loaded' }));
+			on(AdEventType.ERROR, cause => ({ type: 'failed', cause }));
+			on(AdEventType.OPENED, () => ({ type: 'opened' }));
+			on(AdEventType.CLICKED, () => ({ type: 'clicked' }));
+			on(AdEventType.CLOSED, () => ({ type: 'dismissed' }));
+
+			// Rewarded-only, and gated on the format because the provider REJECTS
+			// these types on an interstitial. The rewarded loaded event is distinct
+			// from AdEventType.LOADED, and EARNED_REWARD is distinct from CLOSED —
+			// which is precisely what makes FR-046 and FR-048 enforceable rather
+			// than a guess about ordering.
+			if (format !== 'rewarded') {
+				return makeUnsubscribe(removers);
+			}
+
+			on(RewardedAdEventType.LOADED, () => ({ type: 'loaded' }));
+			on(RewardedAdEventType.EARNED_REWARD, payload => {
+				const source = (payload ?? {}) as { type?: unknown; amount?: unknown };
+				const amount = Number(source.amount);
+				return {
+					type: 'rewarded',
+					reward: {
+						type: typeof source.type === 'string' ? source.type : 'reward',
+						amount: Number.isFinite(amount) ? amount : 0,
+					},
+				};
+			});
+
+			return makeUnsubscribe(removers);
+		},
+
+		dispose(handle) {
+			ads.delete(handle.id);
+		},
+
+		consent: createAdMobConsent(getProvider),
+	};
+}
+
+/**
+ * The consent platform adapter.
+ *
+ * It is deliberately thin. Every decision that could be made here — whether a
+ * region requires consent, whether an error means "no", whether a dismissed form
+ * counts — is made elsewhere or not at all: the provider owns the first, and
+ * `core/consentFlow.ts` owns the second and third. This file's only job is to
+ * call the right method and hand back a shape that names nothing Google.
+ */
+function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPort {
+	function requireConsent(): ProviderConsent {
+		const module = getProvider();
+		if (!module?.AdsConsent) {
+			throw new Error('provider_missing');
+		}
+		return module.AdsConsent;
+	}
+
+	return {
+		async requestInfoUpdate(options: EngineConsentOptions) {
+			const module = getProvider();
+			if (!module?.AdsConsent) {
+				throw new Error('provider_missing');
+			}
+			const debugGeography = toProviderGeography(
+				options.debugGeography,
+				module.AdsConsentDebugGeography ?? {},
+			);
+			const info = await module.AdsConsent.requestInfoUpdate({
+				// Passing `undefined` rather than omitting keeps the call shape
+				// stable; the bridge treats an absent value as "no override".
+				debugGeography,
+				tagForUnderAgeOfConsent: options.underAgeOfConsent,
+				testDeviceIdentifiers: options.testDeviceIds ? [...options.testDeviceIds] : undefined,
+			});
+			return toEngineConsentInfo(info);
+		},
+
+		async showFormIfRequired() {
+			// The provider decides whether a form is needed and renders it. The
+			// package never draws consent UI of its own (FR-103).
+			const info = await requireConsent().loadAndShowConsentFormIfRequired();
+			return toEngineConsentInfo(info);
+		},
+
+		async showPrivacyOptionsForm() {
+			// Present in the pinned bridge 16.0.3, so no range change (FR-155).
+			// Resolves with the consent information as it stands once the form
+			// closes, whether the user changed anything or not.
+			const info = await requireConsent().showPrivacyOptionsForm();
+			return toEngineConsentInfo(info);
+		},
+
+		async getInfo() {
+			return toEngineConsentInfo(await requireConsent().getConsentInfo());
+		},
+
+		reset() {
+			requireConsent().reset();
+		},
+	};
+}