@chipmobilesdk/rn-ads 0.1.0

package/src/diagnostics/errors.ts

@@ -0,0 +1,210 @@
+/**
+ * Normalized error model (FR-053) and redaction (NFR-006).
+ *
+ * Codes are stable public API: renaming one is a breaking change under LIB-008.
+ * They exist so a consuming app branches on `code` and `retryable` rather than
+ * string-matching a provider message that may change under it.
+ *
+ * `cause` is a redacted string, never the provider's error object. A provider
+ * object reaching a consumer would be a contract leak (FR-002) and a potential
+ * carrier for identifiers the package promises never to emit (FR-021).
+ */
+
+import type { AdFormat } from '../config/types';
+
+export type AdsOperation = 'initialize' | 'load' | 'show' | 'configure';
+
+export type AdsErrorCode =
+	// Configuration — none retryable; the configuration has to change.
+	| 'invalid_config'
+	| 'duplicate_placement_key'
+	| 'missing_ad_unit_id'
+	| 'format_mismatch'
+	| 'placement_not_found'
+	| 'production_in_dev_build'
+	| 'timeout_out_of_bounds'
+	// Availability — none retryable within this process.
+	| 'unsupported_platform'
+	| 'provider_missing'
+	| 'disabled'
+	// Privacy — resolved by consent changing, not by calling again.
+	| 'consent_required'
+	| 'consent_undetermined'
+	| 'requires_reinitialization'
+	// Runtime.
+	| 'no_fill'
+	| 'network_error'
+	| 'load_timeout'
+	| 'show_timeout'
+	| 'ad_expired'
+	| 'not_ready'
+	| 'busy'
+	| 'consumed'
+	| 'app_inactive'
+	| 'provider_error'
+	| 'internal_error';
+
+/**
+ * "Retrying this operation could plausibly succeed" — not "retry immediately".
+ * The package ships no automatic retry in v1; pacing belongs to the app, which
+ * is the only party that knows what a retry costs its users (FR-036).
+ */
+const RETRYABLE: ReadonlySet<AdsErrorCode> = new Set<AdsErrorCode>([
+	'no_fill',
+	'network_error',
+	'load_timeout',
+	'show_timeout',
+	'ad_expired',
+	'not_ready',
+	'busy',
+	'consumed',
+	'app_inactive',
+	'provider_error',
+]);
+
+export interface AdsErrorOptions {
+	readonly message?: string;
+	readonly operation?: AdsOperation;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	readonly cause?: unknown;
+}
+
+export class AdsError extends Error {
+	readonly code: AdsErrorCode;
+	readonly retryable: boolean;
+	readonly operation?: AdsOperation;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	/** Redacted provider detail. Never a provider object. */
+	readonly cause?: string;
+
+	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
+		super(options.message ?? code);
+		this.name = 'AdsError';
+		this.code = code;
+		this.retryable = RETRYABLE.has(code);
+		this.operation = options.operation;
+		this.placementKey = options.placementKey;
+		this.format = options.format;
+		this.cause = options.cause === undefined ? undefined : redact(options.cause);
+		Object.setPrototypeOf(this, AdsError.prototype);
+	}
+}
+
+/**
+ * Configuration faults are thrown rather than returned, because they mean the
+ * app is wired wrong and no runtime result could describe a usable outcome.
+ * Every other failure in the package is a typed result (FR-004).
+ */
+export class AdsConfigError extends AdsError {
+	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
+		super(code, { ...options, operation: options.operation ?? 'configure' });
+		this.name = 'AdsConfigError';
+		Object.setPrototypeOf(this, AdsConfigError.prototype);
+	}
+}
+
+export function isAdsError(value: unknown): value is AdsError {
+	return value instanceof AdsError;
+}
+
+const REDACTED = '[redacted]';
+
+/** An AdMob unit or app id. Redacted so a log never carries a live identifier. */
+const AD_UNIT_PATTERN = /ca-app-pub-\d+[~/]\d+/g;
+/** GAID and any other dashed UUID an SDK might put in a message. */
+const UUID_PATTERN =
+	/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g;
+/** Base64-ish runs long enough to be an encoded payload such as a consent string. */
+const PAYLOAD_PATTERN = /[A-Za-z0-9+/=_-]{40,}/g;
+/** Anything path- or URL-like, which can carry query parameters with identifiers. */
+const URL_PATTERN = /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"']+/g;
+
+/**
+ * Keys dropped wholesale rather than pattern-matched, because their values are
+ * sensitive regardless of shape — a bare advertising id has no separator for a
+ * pattern to catch.
+ */
+const SENSITIVE_KEYS = new Set([
+	'adid',
+	'adUnitId',
+	'advertisingId',
+	'consent',
+	'consentString',
+	'gaid',
+	'idfa',
+	'tcString',
+	'token',
+	'userId',
+]);
+
+function redactString(value: string): string {
+	return value
+		.replace(URL_PATTERN, REDACTED)
+		.replace(AD_UNIT_PATTERN, REDACTED)
+		.replace(UUID_PATTERN, REDACTED)
+		.replace(PAYLOAD_PATTERN, REDACTED);
+}
+
+/**
+ * Reduces an arbitrary provider value to a safe string (FR-053, NFR-006).
+ *
+ * Returns a string rather than a structure on purpose: a redacted object still
+ * hands the consumer a reference into provider-owned memory, and the contract
+ * promises no provider object crosses the boundary.
+ */
+export function redact(value: unknown, depth = 0): string {
+	if (value === null || value === undefined) {
+		return '';
+	}
+	if (typeof value === 'string') {
+		return redactString(value);
+	}
+	if (typeof value === 'number' || typeof value === 'boolean') {
+		return String(value);
+	}
+	if (value instanceof Error) {
+		return redactString(value.message);
+	}
+	if (depth >= 2) {
+		return REDACTED;
+	}
+	if (Array.isArray(value)) {
+		return value.map(item => redact(item, depth + 1)).join(', ');
+	}
+	if (typeof value === 'object') {
+		const parts: string[] = [];
+		for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+			if (SENSITIVE_KEYS.has(key)) {
+				parts.push(`${key}=${REDACTED}`);
+				continue;
+			}
+			parts.push(`${key}=${redact(entry, depth + 1)}`);
+		}
+		return parts.join(' ');
+	}
+	return REDACTED;
+}
+
+/**
+ * Maps a provider failure onto the normalized taxonomy. Provider codes vary by
+ * SDK version, so the match is on substrings that have been stable across
+ * releases, and anything unrecognized becomes a retryable `provider_error`
+ * rather than being silently reshaped into a code that means something specific.
+ */
+export function normalizeProviderError(
+	value: unknown,
+	options: AdsErrorOptions = {},
+): AdsError {
+	const text = value instanceof Error ? value.message : String(value ?? '');
+	const lowered = text.toLowerCase();
+
+	if (lowered.includes('no-fill') || lowered.includes('no fill')) {
+		return new AdsError('no_fill', { ...options, cause: value });
+	}
+	if (lowered.includes('network')) {
+		return new AdsError('network_error', { ...options, cause: value });
+	}
+	return new AdsError('provider_error', { ...options, cause: value });
+}

package/src/diagnostics/events.ts

@@ -0,0 +1,179 @@
+/**
+ * Normalized event model and emitter (FR-051, FR-052, FR-054, FR-056).
+ *
+ * Events are the package's only observability surface. They carry no provider
+ * object, no advertising identifier, no consent payload, and nothing that
+ * identifies a user — a consuming app forwards them to whatever logging or
+ * analytics it already has, and the package depends on none (FR-055).
+ *
+ * Dispatch iterates a snapshot of the listener set so subscribing or
+ * unsubscribing during a dispatch neither skips a listener nor double-invokes
+ * one. A listener that throws is caught and reported once; it cannot corrupt a
+ * state machine or starve another listener (FR-056).
+ */
+
+import type { AdFormat, PrivacyBlockReason, Reward, UnavailableReason, Unsubscribe } from '../config/types';
+import { AdsError, type AdsErrorCode, type AdsOperation } from './errors';
+
+export type AdEventType =
+	| 'initialization'
+	| 'load_started'
+	| 'loaded'
+	| 'load_failed'
+	| 'display_started'
+	| 'impression'
+	| 'click'
+	| 'display_failed'
+	| 'dismissed'
+	| 'reward_earned'
+	| 'disabled'
+	| 'unavailable'
+	| 'config_warning'
+	| 'internal_error';
+
+interface BaseEvent {
+	readonly timestamp: number;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	readonly correlationId?: string;
+}
+
+/**
+ * `source` records whether the provider reported a true impression or the
+ * package derived one. Banners get a real impression callback; full-screen
+ * formats have none in the provider's event enum, so theirs is derived from the
+ * ad opening. Flattening that away would make the model quietly wrong for anyone
+ * reconciling these events against revenue reporting.
+ */
+export type ImpressionSource = 'provider' | 'derived';
+
+export type AdEvent = BaseEvent &
+	(
+		| { readonly type: 'initialization'; readonly status: string; readonly retryable?: boolean }
+		| { readonly type: 'load_started' }
+		| { readonly type: 'loaded'; readonly durationMs: number }
+		| { readonly type: 'load_failed'; readonly error: AdsError }
+		| { readonly type: 'display_started' }
+		| { readonly type: 'impression'; readonly source: ImpressionSource }
+		| { readonly type: 'click' }
+		| { readonly type: 'display_failed'; readonly error: AdsError }
+		| { readonly type: 'dismissed'; readonly rewardEarned?: boolean }
+		| { readonly type: 'reward_earned'; readonly reward: Reward }
+		| { readonly type: 'disabled'; readonly operation: AdsOperation }
+		| {
+				readonly type: 'unavailable';
+				readonly operation: AdsOperation;
+				readonly reason: UnavailableReason | PrivacyBlockReason;
+		  }
+		| {
+				readonly type: 'config_warning';
+				readonly warning: 'test_ad_unit_substituted';
+				readonly placementKeys: readonly string[];
+		  }
+		| { readonly type: 'internal_error'; readonly error: AdsError }
+	);
+
+export type AdEventListener = (event: AdEvent) => void;
+
+/** Events that may occur at most once within one correlated cycle (FR-054). */
+const ONCE_PER_CYCLE: ReadonlySet<AdEventType> = new Set<AdEventType>([
+	'loaded',
+	'display_started',
+	'impression',
+	'dismissed',
+	'reward_earned',
+]);
+
+export interface AdEventEmitter {
+	emit(event: AdEvent): void;
+	subscribe(listener: AdEventListener): Unsubscribe;
+	/** Releases every listener and the once-per-cycle bookkeeping (FR-035). */
+	dispose(): void;
+	listenerCount(): number;
+}
+
+export function createEventEmitter(): AdEventEmitter {
+	const listeners = new Set<AdEventListener>();
+	// `${correlationId}:${type}` for everything already emitted in a cycle.
+	const emittedOnce = new Set<string>();
+	let disposed = false;
+	// Guards against an internal_error thrown by a listener re-entering dispatch
+	// and recursing forever.
+	let reportingListenerFailure = false;
+
+	function dispatch(event: AdEvent): void {
+		for (const listener of Array.from(listeners)) {
+			try {
+				listener(event);
+			} catch (error) {
+				if (reportingListenerFailure) {
+					continue;
+				}
+				reportingListenerFailure = true;
+				try {
+					dispatch({
+						type: 'internal_error',
+						timestamp: Date.now(),
+						placementKey: event.placementKey,
+						format: event.format,
+						correlationId: event.correlationId,
+						error: new AdsError('internal_error' as AdsErrorCode, {
+							message: 'consumer event listener threw',
+							cause: error,
+						}),
+					});
+				} finally {
+					reportingListenerFailure = false;
+				}
+			}
+		}
+	}
+
+	return {
+		emit(event) {
+			// After dispose, a late provider callback updates nothing and emits
+			// nothing (FR-035, SC-008).
+			if (disposed) {
+				return;
+			}
+			if (event.correlationId && ONCE_PER_CYCLE.has(event.type)) {
+				const key = `${event.correlationId}:${event.type}`;
+				if (emittedOnce.has(key)) {
+					return;
+				}
+				emittedOnce.add(key);
+			}
+			dispatch(event);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			let active = true;
+			return () => {
+				// Idempotent: a second call is a no-op, not an error (FR-005).
+				if (!active) {
+					return;
+				}
+				active = false;
+				listeners.delete(listener);
+			};
+		},
+		dispose() {
+			disposed = true;
+			listeners.clear();
+			emittedOnce.clear();
+		},
+		listenerCount() {
+			return listeners.size;
+		},
+	};
+}
+
+/** Normalizes a provider reward descriptor. No provider object crosses this (FR-047). */
+export function normalizeReward(value: unknown): Reward {
+	const source = (value ?? {}) as { type?: unknown; amount?: unknown };
+	const amount = Number(source.amount);
+	return {
+		type: typeof source.type === 'string' ? source.type : 'reward',
+		amount: Number.isFinite(amount) ? amount : 0,
+	};
+}

package/src/engine/admobEngine.ts

@@ -0,0 +1,231 @@
+/**
+ * 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, EngineAdEvent, EngineAdHandle, EnginePrivacy } 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;
+	};
+	AdEventType: Record<string, string>;
+	RewardedAdEventType: Record<string, string>;
+	MaxAdContentRating: Record<string, string>;
+}
+
+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) {
+			const module = getProvider();
+			if (!module) {
+				throw new Error('provider_missing');
+			}
+
+			const factory = format === 'rewarded' ? module.RewardedAd : 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: 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);
+		},
+	};
+}

package/src/engine/port.ts

@@ -0,0 +1,72 @@
+/**
+ * The internal engine port (NFR-008, FR-006).
+ *
+ * This interface names no platform and no ad provider. That is what makes an
+ * iOS adapter an additive change: it implements this, and nothing in the public
+ * contract moves. `core/` talks only to this shape; the AdMob bridge exists
+ * behind exactly one implementation of it, in `admobEngine.ts`.
+ *
+ * Banners are absent on purpose. The provider owns a banner's whole lifecycle
+ * through a React component, so `react/AdsBanner` adapts those callbacks
+ * directly rather than routing them through a handle model that would have to
+ * pretend a banner is a load-then-show resource.
+ */
+
+import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
+
+/** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
+export interface EnginePrivacy {
+	readonly childDirected?: boolean;
+	readonly underAgeOfConsent?: boolean;
+	readonly maxAdContentRating?: AdContentRating;
+	readonly personalizedAds?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * Provider callbacks, normalized to the vocabulary the core state machines use.
+ * `rewarded` and `dismissed` are separate members because they are separate
+ * facts that can arrive in either order (FR-049).
+ */
+export type EngineAdEvent =
+	| { readonly type: 'loaded' }
+	| { readonly type: 'failed'; readonly cause: unknown }
+	| { readonly type: 'opened' }
+	| { readonly type: 'clicked' }
+	| { readonly type: 'dismissed' }
+	| { readonly type: 'rewarded'; readonly reward: Reward };
+
+/** An opaque reference to one loaded ad. Never exposed publicly. */
+export interface EngineAdHandle {
+	readonly id: string;
+}
+
+export interface AdsEngine {
+	/**
+	 * True when this platform has a working adapter. Checked before anything
+	 * else so an unsupported platform never loads the provider at all (FR-025).
+	 */
+	isAvailable(): boolean;
+
+	/**
+	 * Applies privacy configuration and then initializes the provider. The order
+	 * matters: child-directed and under-age flags only take effect if they reach
+	 * the provider before it initializes (FR-017, R9).
+	 *
+	 * The caller guarantees this is invoked at most once per instance; the
+	 * engine does not have to be idempotent itself.
+	 */
+	initialize(privacy: EnginePrivacy): Promise<void>;
+
+	/** Creates and begins loading one full-screen ad. Resolves on request, not on load. */
+	createFullScreen(format: FullScreenFormat, adUnitId: string): Promise<EngineAdHandle>;
+
+	/** Presents a loaded ad. Rejects if the provider refuses to present. */
+	show(handle: EngineAdHandle): Promise<void>;
+
+	/** Provider callbacks for one handle. Returns an unsubscribe (FR-005). */
+	subscribe(handle: EngineAdHandle, listener: (event: EngineAdEvent) => void): Unsubscribe;
+
+	/** Releases the handle's provider resources. Safe to call more than once. */
+	dispose(handle: EngineAdHandle): void;
+}