@chipmobilesdk/rn-ads 0.5.1 → 0.7.0

package/src/diagnostics/events.ts

@@ -19,7 +19,14 @@ import type {
 	UnavailableReason,
 	Unsubscribe,
 } from '../config/types';
-import { AdsError, type AdsErrorCode, type AdsOperation } from './errors';
+import {
+	createDiagnosticChannel,
+	createEmitter,
+	type DiagnosticSeverity,
+	type Emitter,
+} from '@chipmobilesdk/rn-core';
+
+import { AdsError, type AdsOperation } from './errors';
 
 export type AdEventType =
 	| 'initialization'
@@ -151,79 +158,83 @@ export interface AdEventEmitter {
 	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;
-				}
-			}
-		}
+/**
+ * How many once-per-cycle keys the emitter remembers. A cycle's duplicates arrive
+ * within that cycle, so forgetting the oldest keys past this bound loses nothing,
+ * and memory stays flat however long the instance lives (CORE-12, ADS-05).
+ */
+const DEDUPE_CAPACITY = 256;
+
+/** Every delivered event also goes to the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<AdEventType>('rn-ads');
+
+function severityOf(event: AdEvent): DiagnosticSeverity {
+	switch (event.type) {
+		case 'internal_error':
+			return 'error';
+		case 'load_failed':
+		case 'display_failed':
+		case 'config_warning':
+			return 'warn';
+		default:
+			return 'info';
 	}
+}
+
+/** What a sink may see: where and which cycle, and an error's code. Never a payload. */
+function contextOf(event: AdEvent): Record<string, unknown> {
+	return {
+		...(event.placementKey === undefined ? {} : { placementKey: event.placementKey }),
+		...(event.format === undefined ? {} : { format: event.format }),
+		...('error' in event ? { code: event.error.code, retryable: event.error.retryable } : {}),
+	};
+}
+
+export function createEventEmitter(): AdEventEmitter {
+	// The event whose listeners are running, so a listener's failure is reported
+	// against the placement and cycle it broke (FR-056).
+	let dispatching: AdEvent | null = null;
+	const emitter: Emitter<AdEvent> = createEmitter<AdEvent>({
+		onListenerError(error) {
+			emitter.emit({
+				type: 'internal_error',
+				timestamp: Date.now(),
+				placementKey: dispatching?.placementKey,
+				format: dispatching?.format,
+				correlationId: dispatching?.correlationId,
+				error: new AdsError('internal_error', {
+					message: 'consumer event listener threw',
+					cause: error,
+				}),
+			});
+		},
+		dedupe: {
+			key: event =>
+				event.correlationId && ONCE_PER_CYCLE.has(event.type)
+					? `${event.correlationId}:${event.type}`
+					: undefined,
+			capacity: DEDUPE_CAPACITY,
+		},
+	});
 
 	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;
+			// nothing (FR-035, SC-008); the rn-core emitter enforces both.
+			const previous = dispatching;
+			dispatching = event;
+			try {
+				if (emitter.emit(event)) {
+					channel.emit(event.type, severityOf(event), contextOf(event), event.correlationId);
 				}
-				emittedOnce.add(key);
+			} finally {
+				dispatching = previous;
 			}
-			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;
 		},
+		// Idempotent unsubscribe (FR-005).
+		subscribe: listener => emitter.subscribe(listener),
+		dispose: () => emitter.dispose(),
+		listenerCount: () => emitter.listenerCount(),
 	};
 }
 

package/src/engine/admobBanner.tsx

@@ -0,0 +1,55 @@
+/**
+ * The AdMob adaptive banner behind the engine port (ADS-12).
+ *
+ * `AdsBanner` renders whatever banner component the engine offers and passes
+ * neutral props; this file is where they become AdMob's. So the banner host no
+ * longer requires the bridge itself, a fake engine can render a banner in a test
+ * without mocking a native module, and an iOS or other-provider engine supplies
+ * its own component.
+ */
+import React from 'react';
+import type { ComponentType } from 'react';
+
+import { classifyProviderFailure } from './admobErrors';
+import type { EngineBanner, EngineBannerProps } from './port';
+
+/** The slice of the bridge the banner uses. */
+interface ProviderBannerModule {
+	readonly BannerAd?: ComponentType<Record<string, unknown>>;
+	readonly BannerAdSize?: Record<string, string>;
+}
+
+export function createAdMobBanner(getProvider: () => ProviderBannerModule | null): EngineBanner {
+	function AdMobBanner({
+		adUnitId,
+		personalizedAds,
+		onLoaded,
+		onFailed,
+		onImpression,
+		onClicked,
+	}: EngineBannerProps) {
+		const provider = getProvider();
+		const BannerAd = provider?.BannerAd;
+		if (!BannerAd) {
+			return null;
+		}
+		return (
+			<BannerAd
+				unitId={adUnitId}
+				// Adaptive, so the banner fills the container the app measured (FR-038).
+				size={provider.BannerAdSize?.ANCHORED_ADAPTIVE_BANNER}
+				// The provider's polarity is the inverse of the consumer-facing option.
+				requestOptions={{ requestNonPersonalizedAdsOnly: !personalizedAds }}
+				onAdLoaded={() => onLoaded()}
+				onAdFailedToLoad={(error: unknown) => onFailed(error, classifyProviderFailure(error))}
+				onAdImpression={() => onImpression()}
+				onAdClicked={() => onClicked()}
+			/>
+		);
+	}
+
+	return {
+		isAvailable: () => Boolean(getProvider()?.BannerAd),
+		Component: AdMobBanner,
+	};
+}

package/src/engine/admobEngine.ts

@@ -16,9 +16,15 @@
  * applied.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import type { ComponentType } from 'react';
 import { Platform } from 'react-native';
 
 import type { AdContentRating, FullScreenFormat, Unsubscribe } from '../config/types';
+import { normalizeReward } from '../diagnostics/events';
+import { createAdMobBanner } from './admobBanner';
+import { classifyProviderFailure } from './admobErrors';
 import type {
 	AdsEngine,
 	ConsentPort,
@@ -56,6 +62,8 @@ interface ProviderModule {
 	MaxAdContentRating: Record<string, string>;
 	AdsConsent: ProviderConsent;
 	AdsConsentDebugGeography: Record<string, number>;
+	BannerAd?: ComponentType<Record<string, unknown>>;
+	BannerAdSize?: Record<string, string>;
 }
 
 /** The slice of the bridge's consent module this adapter uses. */
@@ -141,15 +149,24 @@ function toEnginePrivacyOptions(value: string | undefined): EngineConsentInfo['p
 	}
 }
 
-function loadProvider(): ProviderModule | null {
+/**
+ * The provider bridge, loaded on first use (rn-core's lazy peer). It 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). The banner component reaches it through the same loader.
+ */
+export const admobProvider = lazyPeer('react-native-google-mobile-ads', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
 	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;
+	} catch (cause) {
+		throw cause;
 	}
+});
+
+function loadProvider(): ProviderModule | null {
+	const result = admobProvider.get();
+	return result.ok ? result.module : null;
 }
 
 function toProviderRating(
@@ -207,6 +224,10 @@ export function createAdMobEngine(): AdsEngine {
 			return supported && getProvider() !== null;
 		},
 
+		// The adaptive banner renders through the engine like every other format
+		// (ADS-12), so the banner host never names the provider.
+		banner: createAdMobBanner(getProvider),
+
 		async initialize(privacy: EnginePrivacy) {
 			const module = getProvider();
 			if (!module) {
@@ -297,7 +318,11 @@ export function createAdMobEngine(): AdsEngine {
 			};
 
 			on(AdEventType.LOADED, () => ({ type: 'loaded' }));
-			on(AdEventType.ERROR, cause => ({ type: 'failed', cause }));
+			on(AdEventType.ERROR, cause => ({
+				type: 'failed',
+				cause,
+				kind: classifyProviderFailure(cause),
+			}));
 			on(AdEventType.OPENED, () => ({ type: 'opened' }));
 			on(AdEventType.CLICKED, () => ({ type: 'clicked' }));
 			on(AdEventType.CLOSED, () => ({ type: 'dismissed' }));
@@ -312,17 +337,10 @@ export function createAdMobEngine(): AdsEngine {
 			}
 
 			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,
-					},
-				};
-			});
+			on(RewardedAdEventType.EARNED_REWARD, payload => ({
+				type: 'rewarded',
+				reward: normalizeReward(payload),
+			}));
 
 			return makeUnsubscribe(removers);
 		},
@@ -397,3 +415,5 @@ function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPo
 		},
 	};
 }
+
+export { classifyProviderFailure } from './admobErrors';

package/src/engine/admobErrors.ts

@@ -0,0 +1,44 @@
+/**
+ * AdMob's error vocabulary, translated into the port's neutral failure kinds
+ * (ADS-08). Shared by the full-screen engine and the banner component, which
+ * are the only two places that see a provider error.
+ */
+import type { EngineFailureKind } from './port';
+
+/**
+ * The bridge's error codes that say the provider refused the request itself, so
+ * that asking again cannot help (ADS-08). Kept to codes the bridge has reported
+ * the same way across releases. `internal-error` is deliberately absent: AdMob
+ * uses it for an invalid server response too, which a later request can survive.
+ */
+const REJECTED_CODES: ReadonlySet<string> = new Set([
+	'invalid-request',
+	'invalid-argument',
+	'app-id-missing',
+	'request-id-mismatch',
+]);
+
+/** The bridge's code for an error: `error.code`, or the `[googleMobileAds/<code>]` prefix. */
+function providerCodeOf(cause: unknown): string | null {
+	const code = (cause as { code?: unknown } | null)?.code;
+	if (typeof code === 'string') {
+		return code.replace(/^googleMobileAds\//, '');
+	}
+	const message = cause instanceof Error ? cause.message : typeof cause === 'string' ? cause : '';
+	return /\[googleMobileAds\/([a-z-]+)\]/.exec(message)?.[1] ?? null;
+}
+
+/** Classifies a provider failure in neutral terms; undefined when it cannot tell. */
+export function classifyProviderFailure(cause: unknown): EngineFailureKind | undefined {
+	const code = providerCodeOf(cause);
+	if (code === null) {
+		return undefined;
+	}
+	if (code === 'no-fill' || code === 'mediation-no-fill') {
+		return 'no_fill';
+	}
+	if (code === 'network-error') {
+		return 'network';
+	}
+	return REJECTED_CODES.has(code) ? 'rejected' : undefined;
+}

package/src/engine/port.ts

@@ -12,6 +12,8 @@
  * pretend a banner is a load-then-show resource.
  */
 
+import type { ComponentType } from 'react';
+
 import type { AdContentRating, FullScreenFormat, Reward, Unsubscribe } from '../config/types';
 
 /** Privacy state as the engine needs it — no consumer-facing shape leaks in. */
@@ -39,9 +41,45 @@ export interface EngineRequestOptions {
  * `rewarded` and `dismissed` are separate members because they are separate
  * facts that can arrive in either order (FR-049).
  */
+/**
+ * What kind of failure the provider reported, in words that name no provider
+ * (ADS-08). Only the adapter knows its provider's error vocabulary, so it
+ * classifies; core decides what each kind means for retrying.
+ *
+ * - `no_fill`: the network had nothing to give.
+ * - `network`: the request did not get through.
+ * - `rejected`: the provider refused the request itself — an invalid ad unit, a
+ *   missing app id. The same request will fail the same way.
+ */
+export type EngineFailureKind = 'no_fill' | 'network' | 'rejected';
+
+/** What an engine's banner component receives. Names no provider (ADS-12). */
+export interface EngineBannerProps {
+	readonly adUnitId: string;
+	/** False asks the provider for non-personalized ads only (FR-017). */
+	readonly personalizedAds: boolean;
+	readonly onLoaded: () => void;
+	readonly onFailed: (cause: unknown, kind?: EngineFailureKind) => void;
+	/** A real provider impression, as opposed to the derived full-screen one (R5). */
+	readonly onImpression: () => void;
+	readonly onClicked: () => void;
+}
+
+/** An engine's banner: one adaptive banner filling its container's width (FR-038). */
+export interface EngineBanner {
+	/** Whether the provider's banner can render here, e.g. its native module is linked. */
+	isAvailable(): boolean;
+	readonly Component: ComponentType<EngineBannerProps>;
+}
+
 export type EngineAdEvent =
 	| { readonly type: 'loaded' }
-	| { readonly type: 'failed'; readonly cause: unknown }
+	| {
+			readonly type: 'failed';
+			readonly cause: unknown;
+			/** Optional, so an engine that does not classify keeps working. */
+			readonly kind?: EngineFailureKind;
+	  }
 	| { readonly type: 'opened' }
 	| { readonly type: 'clicked' }
 	| { readonly type: 'dismissed' }
@@ -141,4 +179,11 @@ export interface AdsEngine {
 
 	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
 	readonly consent: ConsentPort;
+
+	/**
+	 * The adaptive banner, rendered by `AdsBanner` (ADS-12). Optional, so an
+	 * engine written against 0.6.0 still satisfies the port; without it banners
+	 * report `unavailable`.
+	 */
+	readonly banner?: EngineBanner;
 }

package/src/engine/testAdUnits.ts

@@ -54,8 +54,3 @@ export function isOfficialTestAdUnit(adUnitId: string): boolean {
 	}
 	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

@@ -16,6 +16,14 @@
  * frequency cap, and no screen name in this package (FR-045).
  */
 
+import type { AdsConfig } from './config/types';
+import {
+	createAds as createInstance,
+	type AdsInstance,
+	type CreateAdsOptions,
+} from './core/adsInstance';
+import { createAdMobEngine } from './engine/admobEngine';
+
 // Configuration and state
 export type {
 	AdContentRating,
@@ -73,7 +81,17 @@ export {
 export type { EnablementResult } from './core/enablement';
 
 // Instance, lifecycle, and results
-export { createAds } from './core/adsInstance';
+
+/**
+ * Creates an ads instance. This is the composition root: core's instance with
+ * the AdMob adapter as its default engine, so core/ itself never loads an
+ * adapter (ADS-14). The adapter resolves the provider bridge only on first use,
+ * so importing the package where there is no adapter, or no bridge, costs
+ * nothing and crashes nothing (FR-025, SC-004).
+ */
+export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): AdsInstance {
+	return createInstance(config, options, createAdMobEngine);
+}
 export type {
 	AdsInstance,
 	ConsentApi,