@chipmobilesdk/rn-ads 0.1.0

package/src/engine/testAdUnits.ts

@@ -0,0 +1,58 @@
+/**
+ * Google's official test ad units (FR-013).
+ *
+ * PRIVATE. Never exported from `src/index.ts`.
+ *
+ * FR-013 forbids the package from carrying production identifiers, credentials,
+ * or host-app rules, and explicitly permits official test identifiers provided
+ * they are documented as such — this file is that documentation.
+ *
+ * They are hard-coded rather than read from configuration on purpose: FR-011's
+ * substitution guarantee must hold even when the app's configuration is the
+ * thing that is wrong, so it cannot depend on the app supplying anything. They
+ * are also not re-exported from the provider bridge's own `TestIds`, because
+ * that would put a provider symbol on this package's dependency path for a
+ * value that is really just four documented constants (FR-002).
+ *
+ * Source: Google Mobile Ads "Test ads" documentation, cross-checked against the
+ * bridge's `src/TestIds.ts` at version 16.0.3. These identifiers are public,
+ * are the same for every publisher, and always fill.
+ */
+
+import type { AdFormat } from '../config/types';
+
+/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
+const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
+	// The adaptive-banner unit, not the fixed-size one, because adaptive is the
+	// format this package actually requests (FR-038).
+	banner: 'ca-app-pub-3940256099942544/9214589741',
+	interstitial: 'ca-app-pub-3940256099942544/1033173712',
+	rewarded: 'ca-app-pub-3940256099942544/5224354917',
+};
+
+export function testAdUnitFor(format: AdFormat): string {
+	return ANDROID_TEST_AD_UNITS[format];
+}
+
+/**
+ * Whether an identifier is one of ours.
+ *
+ * This is the structural test that drives substitution: anything that is not a
+ * known official test unit is treated as production-owned. Deliberately not a
+ * parse of AdMob's publisher-id format — a rule like that becomes wrong the day
+ * Google changes the format, and being wrong here means either sending a
+ * production request or blocking a legitimate one.
+ */
+export function isOfficialTestAdUnit(adUnitId: string): boolean {
+	for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
+		if (value === adUnitId) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** Exposed for the package's own tests and for documentation generation. */
+export function allTestAdUnits(): Readonly<Record<AdFormat, string>> {
+	return ANDROID_TEST_AD_UNITS;
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @chipmobilesdk/rn-ads — reusable advertising capability for
+ * ChipMobileSdk-family React Native apps.
+ *
+ * This is the public entrypoint (LIB-003). Modules under `config/`, `core/`,
+ * `engine/`, `react/`, and `diagnostics/` are private; import them only through
+ * this file. The fake engine lives behind `@chipmobilesdk/rn-ads/testing` so
+ * test doubles cannot reach a production bundle.
+ *
+ * Nothing exported here names Google, AdMob, or any provider type (FR-002).
+ * `src/__tests__/public-api.test.ts` asserts that mechanically.
+ *
+ * The package owns capability: a safe, consistent way to request and present
+ * ads. The consuming app owns policy — where ads appear, when, how often, under
+ * what consent, and whether they appear at all. There is no placement rule, no
+ * frequency cap, and no screen name in this package (FR-045).
+ */
+
+// Configuration and state
+export type {
+	AdContentRating,
+	AdFormat,
+	AdsConfig,
+	Environment,
+	FullScreenFormat,
+	InitStatus,
+	PlacementDefinition,
+	PlacementState,
+	PrivacyBlockReason,
+	PrivacyOptions,
+	Reward,
+	TimeoutConfig,
+	UnavailableReason,
+	Unsubscribe,
+} from './config/types';
+export { isFullScreenFormat } from './config/types';
+
+// Timeout policy — exported so a consumer can read the defaults it is bound by
+// rather than discovering them from a timeout in production (FR-032).
+export {
+	AD_VALIDITY_BOUNDS,
+	DEFAULT_AD_VALIDITY_MS,
+	DEFAULT_LOAD_TIMEOUT_MS,
+	DEFAULT_SHOW_TIMEOUT_MS,
+	LOAD_TIMEOUT_BOUNDS,
+	SHOW_TIMEOUT_BOUNDS,
+} from './core/timers';
+
+// Instance, lifecycle, and results
+export { createAds } from './core/adsInstance';
+export type {
+	AdsInstance,
+	InitResult,
+	LoadResult,
+	PrivacyUpdateResult,
+	ShowResult,
+} from './core/adsInstance';
+
+// React surface
+export { AdsBanner } from './react/AdsBanner';
+export type { AdsBannerProps } from './react/AdsBanner';
+export { AdsProvider, useAds } from './react/AdsProvider';
+export type { AdsProviderProps } from './react/AdsProvider';
+export { useAdsEvents, useAdsStatus, usePlacementState } from './react/hooks';
+
+// Diagnostics
+export { AdsConfigError, AdsError, isAdsError } from './diagnostics/errors';
+export type { AdsErrorCode, AdsOperation } from './diagnostics/errors';
+export type { AdEvent, AdEventListener, AdEventType, ImpressionSource } from './diagnostics/events';

package/src/react/AdsBanner.tsx

@@ -0,0 +1,270 @@
+/**
+ * Adaptive banner host (FR-038 – FR-042).
+ *
+ * The app puts this where it wants a banner. The component never inserts itself
+ * into the tree, never overlays app content, and ships no placeholder — the
+ * surrounding layout, and any loading or fallback presentation, belong to the
+ * app and its theme (FR-040, UX-001).
+ *
+ * When ads are disabled or unavailable it renders `null` rather than a
+ * zero-height view. That is not a micro-optimization: a rendered empty view
+ * still sits in the accessibility tree and can take screen-reader focus ahead of
+ * real content. `null` leaves the tree entirely (UX-003).
+ *
+ * The provider owns the banner's whole lifecycle through its own component, so
+ * this adapts those callbacks into the normalized event model instead of routing
+ * a banner through the load/show handle model, which does not fit it.
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { View, type LayoutChangeEvent, type ViewStyle } from 'react-native';
+
+import type { PlacementState } from '../config/types';
+import { AdsError, normalizeProviderError } from '../diagnostics/errors';
+import { useAds } from './AdsProvider';
+import { useAdsStatus } from './hooks';
+
+export interface AdsBannerProps {
+	readonly placementKey: string;
+	/** Called on every state change so the app can hold or reclaim the space. */
+	readonly onStateChange?: (state: PlacementState) => void;
+	/** Applied to the container only. Never to ad content, which is not ours. */
+	readonly style?: ViewStyle;
+}
+
+interface ProviderBannerModule {
+	BannerAd: React.ComponentType<Record<string, unknown>>;
+	BannerAdSize: Record<string, string>;
+}
+
+function loadBannerModule(): ProviderBannerModule | null {
+	try {
+		return require('react-native-google-mobile-ads') as ProviderBannerModule;
+	} catch {
+		return null;
+	}
+}
+
+export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps) {
+	const ads = useAds();
+	// The reported state lives in a ref rather than in component state: the host
+	// itself renders the same tree for every state, so storing it would only
+	// force re-renders the PERF-002 budget does not need to spend. The instance
+	// holds the authoritative value; `onStateChange` tells the app.
+	const stateRef = useRef<PlacementState>('idle');
+	const [containerWidth, setContainerWidth] = useState(0);
+	// A new cycle id remounts the provider component, which is how a width change
+	// produces a genuinely re-adapted banner rather than a stretched old one.
+	const [cycle, setCycle] = useState(0);
+	const correlationRef = useRef<string | null>(null);
+	const startedAtRef = useRef(0);
+
+	const provider = useMemo(loadBannerModule, []);
+	// Initialization is asynchronous and a banner is almost always mounted before
+	// it finishes. Without this the resolution below would be computed once, while
+	// the instance was still `not_started`, be refused, and never be retried — the
+	// banner would sit at `unavailable` forever on a perfectly healthy app.
+	const status = useAdsStatus();
+
+	// Keyed on `cycle` so a genuine width change mints a fresh correlation id and
+	// starts a new, separately traceable load (FR-038, FR-052), and on `status` so
+	// the banner recovers the moment the instance becomes able to request.
+	const resolved = useMemo(
+		() =>
+			ads && status === 'ready'
+				? { cycle, value: ads.internals.resolveBanner(placementKey) }
+				: null,
+		[ads, placementKey, cycle, status],
+	);
+	const resolution = resolved?.value ?? null;
+
+	const move = useCallback(
+		(next: PlacementState) => {
+			if (stateRef.current === next) {
+				return;
+			}
+			stateRef.current = next;
+			ads?.internals.setPlacementState(placementKey, next);
+			onStateChange?.(next);
+		},
+		[ads, onStateChange, placementKey],
+	);
+
+	const usable = Boolean(ads && provider && resolution?.ok && containerWidth > 0);
+
+	useEffect(() => {
+		if (!ads || !provider) {
+			move('unavailable');
+			return;
+		}
+		// `not_started` and `initializing` are transient: the app is still on its
+		// way and the banner will resolve shortly, so report `idle` rather than
+		// `unavailable` and let the app keep its layout decision open. Every other
+		// non-ready status — disabled, blocked, failed, unsupported — means there
+		// will be no ad, and the app should reclaim the space (FR-039, FR-042).
+		if (status !== 'ready') {
+			move(status === 'not_started' || status === 'initializing' ? 'idle' : 'unavailable');
+			return;
+		}
+		if (!resolution?.ok) {
+			move('unavailable');
+			return;
+		}
+		if (containerWidth <= 0) {
+			// FR-039: a zero-width container is reported rather than turned into a
+			// request for an ad at a nonsensical size.
+			move('idle');
+			return;
+		}
+		correlationRef.current = resolution.correlationId;
+		startedAtRef.current = Date.now();
+		move('loading');
+		ads.internals.emit({
+			type: 'load_started',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: resolution.correlationId,
+		});
+		// Deliberately keyed on `cycle`, not on every render: FR-041 forbids a
+		// re-render from producing a second uncontrolled request.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ads, provider, status, resolution, containerWidth, cycle]);
+
+	const onLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const width = Math.round(event.nativeEvent.layout.width);
+			setContainerWidth(previous => {
+				if (previous === width) {
+					return previous;
+				}
+				// FR-038: a genuine width or orientation change re-adapts. The
+				// rounding above stops sub-pixel layout jitter from doing so.
+				if (previous > 0 && width > 0) {
+					setCycle(value => value + 1);
+				}
+				return width;
+			});
+		},
+		[],
+	);
+
+	const emit = useCallback(
+		(event: Parameters<NonNullable<typeof ads>['internals']['emit']>[0]) => {
+			ads?.internals.emit(event);
+		},
+		[ads],
+	);
+
+	const handleLoaded = useCallback(() => {
+		move('ready');
+		emit({
+			type: 'loaded',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+			durationMs: Date.now() - startedAtRef.current,
+		});
+	}, [emit, move, placementKey]);
+
+	const handleFailed = useCallback(
+		(error: unknown) => {
+			const normalized = normalizeProviderError(error, {
+				operation: 'load',
+				placementKey,
+				format: 'banner',
+			});
+			move('failed');
+			emit({
+				type: 'load_failed',
+				timestamp: Date.now(),
+				placementKey,
+				format: 'banner',
+				correlationId: correlationRef.current ?? undefined,
+				error: normalized,
+			});
+		},
+		[emit, move, placementKey],
+	);
+
+	const handleImpression = useCallback(() => {
+		emit({
+			type: 'impression',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+			// A real provider impression, unlike the derived one full-screen
+			// formats get. The distinction is load-bearing for revenue
+			// reconciliation, so it is recorded rather than flattened (R5).
+			source: 'provider',
+		});
+	}, [emit, placementKey]);
+
+	const handleClicked = useCallback(() => {
+		emit({
+			type: 'click',
+			timestamp: Date.now(),
+			placementKey,
+			format: 'banner',
+			correlationId: correlationRef.current ?? undefined,
+		});
+	}, [emit, placementKey]);
+
+	// FR-041: nothing survives unmount. No retained native view, no dangling
+	// correlation, no state written into a disposed instance.
+	useEffect(() => {
+		return () => {
+			correlationRef.current = null;
+		};
+	}, []);
+
+	if (!ads || !provider) {
+		// FR-042, UX-003 — out of the tree entirely, blocking no touch.
+		return null;
+	}
+
+	// A terminal non-ready status means there will be no ad at all, so leave the
+	// tree rather than render an empty host. `not_started` and `initializing` are
+	// excluded on purpose: the host must stay mounted through them, because it is
+	// what measures the container and starts the load once the instance is ready.
+	if (status === 'disabled' || status === 'unavailable' || status === 'failed') {
+		return null;
+	}
+
+	if (resolution && !resolution.ok) {
+		const refusal = resolution.result;
+		if (refusal.status === 'disabled' || refusal.status === 'unavailable') {
+			return null;
+		}
+	}
+
+	const { BannerAd, BannerAdSize } = provider;
+	const adUnitId = resolution?.ok ? resolution.adUnitId : null;
+
+	return (
+		<View style={style} onLayout={onLayout} testID={`ads-banner-${placementKey}`}>
+			{usable && adUnitId ? (
+				<BannerAd
+					key={`${placementKey}-${cycle}`}
+					unitId={adUnitId}
+					size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
+					onAdLoaded={handleLoaded}
+					onAdFailedToLoad={handleFailed}
+					onAdImpression={handleImpression}
+					onAdClicked={handleClicked}
+				/>
+			) : null}
+		</View>
+	);
+}
+
+/** Exposed for tests that assert the failure taxonomy without a renderer. */
+export function bannerUnavailableError(placementKey: string): AdsError {
+	return new AdsError('unsupported_platform', {
+		operation: 'load',
+		placementKey,
+		format: 'banner',
+	});
+}

package/src/react/AdsProvider.tsx

@@ -0,0 +1,57 @@
+/**
+ * Instance context (US1).
+ *
+ * Supplies one `AdsInstance` to the tree so `AdsBanner` and the hooks can reach
+ * it without every screen threading it through props.
+ *
+ * The provider does not create the instance. The app does, and passes it in —
+ * because `createAds` throws on a misconfigured catalog (FR-008, FR-012), and a
+ * throw during render is a far worse place to discover that than a throw at
+ * startup where the app can decide what to do about it.
+ */
+
+import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+import type { AdsInstance } from '../core/adsInstance';
+
+const AdsContext = createContext<AdsInstance | null>(null);
+
+export interface AdsProviderProps {
+	readonly instance: AdsInstance;
+	/**
+	 * Whether the provider forwards foreground/background transitions to the
+	 * instance. On by default: FR-034's "never show while inactive" and
+	 * "re-evaluate a stale ad on return" both depend on the instance being told.
+	 * Turn it off only when the app already drives `setAppActive` itself.
+	 */
+	readonly trackAppState?: boolean;
+	readonly children: ReactNode;
+}
+
+export function AdsProvider({ instance, trackAppState = true, children }: AdsProviderProps) {
+	useEffect(() => {
+		if (!trackAppState) {
+			return;
+		}
+		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
+			instance.setAppActive(status === 'active');
+		});
+		return () => {
+			subscription.remove();
+		};
+	}, [instance, trackAppState]);
+
+	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;
+}
+
+/**
+ * Returns the instance, or null outside a provider.
+ *
+ * Null rather than a throw on purpose: a screen that renders a banner should
+ * degrade to rendering nothing when ads are not wired up, not take the screen
+ * down with it (NFR-005).
+ */
+export function useAds(): AdsInstance | null {
+	return useContext(AdsContext);
+}

package/src/react/hooks.ts

@@ -0,0 +1,75 @@
+/**
+ * React bindings (US1, FR-027).
+ *
+ * Each hook subscribes to exactly what it reads. `usePlacementState` subscribes
+ * to one placement rather than to the whole event stream, which is what keeps a
+ * banner from re-rendering because an unrelated interstitial was clicked —
+ * PERF-002's bounded re-render assertion depends on it.
+ *
+ * None of these hand back an ad object. A consumer queries and subscribes to
+ * state; it never holds provider-owned memory (FR-027).
+ */
+
+import { useEffect, useState } from 'react';
+
+import type { InitStatus, PlacementState } from '../config/types';
+import type { AdEventListener } from '../diagnostics/events';
+import { useAds } from './AdsProvider';
+
+/** Live state for one placement. `unavailable` outside a provider. */
+export function usePlacementState(placementKey: string): PlacementState {
+	const ads = useAds();
+	const [state, setState] = useState<PlacementState>(() =>
+		ads ? ads.getPlacementState(placementKey) : 'unavailable',
+	);
+
+	useEffect(() => {
+		if (!ads) {
+			setState('unavailable');
+			return;
+		}
+		// Re-read on subscribe: the state may have moved between the initial
+		// render and this effect, and dropping that transition would leave the
+		// UI showing a state the instance has already left.
+		setState(ads.getPlacementState(placementKey));
+		return ads.subscribePlacement(placementKey, setState);
+	}, [ads, placementKey]);
+
+	return state;
+}
+
+/** Live initialization status. `unavailable` outside a provider. */
+export function useAdsStatus(): InitStatus {
+	const ads = useAds();
+	const [status, setStatus] = useState<InitStatus>(() => (ads ? ads.getStatus() : 'unavailable'));
+
+	useEffect(() => {
+		if (!ads) {
+			setStatus('unavailable');
+			return;
+		}
+		setStatus(ads.getStatus());
+		return ads.subscribeStatus(setStatus);
+	}, [ads]);
+
+	return status;
+}
+
+/**
+ * Forwards every event to a listener without causing a render.
+ *
+ * Deliberately does not accumulate events into state: a package that kept an
+ * event log would be persisting exactly the kind of history it promises not to
+ * (FR-021), and re-rendering on every impression would defeat PERF-002. A screen
+ * that wants a visible log keeps its own.
+ */
+export function useAdsEvents(listener: AdEventListener): void {
+	const ads = useAds();
+
+	useEffect(() => {
+		if (!ads) {
+			return;
+		}
+		return ads.subscribeEvents(listener);
+	}, [ads, listener]);
+}