@chipmobilesdk/rn-ads 0.6.0 → 0.7.0

package/src/core/instance/types.ts

@@ -0,0 +1,198 @@
+/**
+ * The ads instance's public contract: what `createAds` returns and what each
+ * operation reports. Implementation lives beside this file, one module per
+ * responsibility (ADS-10).
+ */
+import type { AdsError } from '../../diagnostics/errors';
+import type {
+	ConsentSnapshot,
+	Enablement,
+	InitStatus,
+	PlacementState,
+	PrivacyBlockReason,
+	PrivacyOptions,
+	UnavailableReason,
+	Unsubscribe,
+} from '../../config/types';
+import type { AdEventListener } from '../../diagnostics/events';
+import type { AdsEngine } from '../../engine/port';
+import type { EnablementResult } from '../enablement';
+import type { Scheduler } from '../timers';
+
+export type InitResult =
+	| { readonly status: 'ready' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'disabled' }
+	/** The app has not decided whether ads are on. Nothing was requested (FR-115). */
+	| { readonly status: 'undecided' }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export type PrivacyUpdateResult =
+	| { readonly status: 'applied' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'requires_reinitialization' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	/**
+	 * The initialization this update triggered failed (added in 0.5.0). Before,
+	 * it was reported as `applied`, so the app never retried and no ad ever
+	 * showed, with nothing to say why.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export type LoadResult =
+	| { readonly status: 'loaded'; readonly correlationId: string }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'no_fill' }
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Nothing was requested and nothing is broken — this placement asked too
+	 * recently. Distinct from `no_fill` on purpose: no-fill means the network had
+	 * nothing to give, this means we did not ask. An app that treats them the same
+	 * will misdiagnose the first time a banner goes quiet.
+	 */
+	| ThrottledResult
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export interface ThrottledResult {
+	readonly status: 'throttled';
+	readonly retryAfterMs: number;
+}
+
+/** A gate refusal: what a load gets when it may not ask at all. */
+export type LoadRefusal = Extract<
+	LoadResult,
+	{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
+>;
+
+export type ShowResult =
+	| { readonly status: 'shown'; readonly correlationId: string }
+	| { readonly status: 'not_ready' }
+	| { readonly status: 'busy' }
+	| { readonly status: 'consumed' }
+	| { readonly status: 'app_inactive' }
+	/**
+	 * The user came back to the app from an ad, or from a browser an ad opened,
+	 * so an app-open ad would be an ad immediately after an ad. Distinct from
+	 * `busy` and `not_ready` because the app cannot detect this itself and
+	 * therefore cannot infer it from either of those (FR-128).
+	 */
+	| { readonly status: 'ad_originated_return' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+/**
+ * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ *
+ * Every refusal is its own member, so an app can tell "there is nothing to
+ * offer here" from "you asked too early" from "it broke" without parsing an
+ * error. None of them throws.
+ */
+export type PrivacyOptionsFormResult =
+	/**
+	 * The provider's form was presented and has closed. `consent` is the state it
+	 * left behind, already applied to the gate. A user who closed the form without
+	 * changing anything lands here too, with the state they already had.
+	 */
+	| { readonly status: 'shown'; readonly consent: ConsentSnapshot }
+	/** The provider does not require privacy options here. Nothing was presented. */
+	| { readonly status: 'not_required' }
+	/**
+	 * The requirement is not known yet: no successful `requestInfoUpdate()` since
+	 * the instance was created or reset, or the last one failed. Nothing was
+	 * presented.
+	 */
+	| { readonly status: 'info_update_required' }
+	/** A consent form is already on screen. Nothing was presented. */
+	| { readonly status: 'busy' }
+	/**
+	 * The form could not be presented or failed while open. The consent state is
+	 * whatever the provider reports it still holds, and never a new grant.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+
+/**
+ * The optional consent capability (FR-101).
+ *
+ * Grouped under its own namespace rather than flattened onto the instance so
+ * that FR-102's optionality stays legible: an app that never touches
+ * `ads.consent` never starts a flow. Five loose methods on the instance would
+ * invite the assumption that they are part of the normal path.
+ */
+export interface ConsentApi {
+	/** Refreshes consent information from the provider. */
+	requestInfoUpdate(): Promise<ConsentSnapshot>;
+	/** Presents the provider's form if one is required. Renders nothing itself. */
+	showFormIfRequired(): Promise<ConsentSnapshot>;
+	/**
+	 * Presents the provider's privacy options form, so a user can change an
+	 * answer already given (FR-151). Added in 0.4.0.
+	 *
+	 * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
+	 * the entry point lives, and what it says, stay the app's. The outcome feeds
+	 * the privacy gate by itself, exactly as `showFormIfRequired` does.
+	 */
+	showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
+	getState(): ConsentSnapshot;
+	subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
+	/** Clears the stored decision. Inert in production (FR-113). */
+	reset(): Promise<void>;
+}
+
+export interface AdsInstance {
+	initialize(privacy: PrivacyOptions): Promise<InitResult>;
+	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+	/**
+	 * Turns ads on or off. Returns a result rather than `void` (FR-122).
+	 *
+	 * 0.1.0 returned nothing, which meant an app re-enabling ads after a lapsed
+	 * subscription had no way to learn that it also had to re-initialize — and
+	 * every load and show after that was refused in silence.
+	 */
+	setEnabled(enabled: boolean): EnablementResult;
+	/** The same, including the third state the app has not resolved yet. */
+	setEnablement(next: Enablement): EnablementResult;
+	setAppActive(active: boolean): void;
+	readonly consent: ConsentApi;
+	getStatus(): InitStatus;
+	subscribeStatus(listener: (status: InitStatus) => void): Unsubscribe;
+
+	load(placementKey: string): Promise<LoadResult>;
+	show(placementKey: string): Promise<ShowResult>;
+	getPlacementState(placementKey: string): PlacementState;
+	subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
+
+	subscribeEvents(listener: AdEventListener): Unsubscribe;
+
+	/** FR-011a — substitution is observable state, not only a log line. */
+	getSubstitutedPlacements(): readonly string[];
+	/** FR-113 — the same treatment for consent tools dropped in production. */
+	getIgnoredConsentTools(): readonly string[];
+	dispose(): void;
+}
+
+export interface CreateAdsOptions {
+	/** Injected in tests; the AdMob adapter is the default in production. */
+	readonly engine?: AdsEngine;
+	/** Injected so the FR-012 rule is testable without touching a global. */
+	readonly isDevBuild?: boolean;
+	readonly now?: () => number;
+	/**
+	 * Injected so retry backoff, app-open expiry, and the undecided warning can
+	 * be driven by a test clock instead of by waiting. Production uses real
+	 * timers.
+	 */
+	readonly scheduler?: Scheduler;
+}

package/src/core/requestThrottle.ts

@@ -83,24 +83,21 @@ export interface RequestThrottle {
 	 * banner path depends on it. React may run a `useMemo` or an effect more than
 	 * once for a single committed render — StrictMode does it deliberately — and
 	 * without a token the second run would consume a second slot and be refused,
-	 * so a banner would never appear in development. Passing the cycle's
-	 * correlation id means "this is the same request I already asked about", and
-	 * the previous decision is returned unchanged.
+	 * so a banner would never appear in development. Passing the banner mount's
+	 * token means "this is the same request I already asked about", and the
+	 * previous decision is returned unchanged.
 	 *
 	 * Omit `token` for a genuinely new imperative request, where every call is a
 	 * distinct intent to ask the network.
 	 */
 	tryAcquire(key: string, minIntervalMs: number, token?: string): ThrottleDecision;
 	/**
-	 * Forgets a placement's last request.
-	 *
-	 * Used when a placement's resources are released, so a genuinely new cycle is
-	 * not charged for the previous one.
+	 * How long until this placement may ask again, without taking a slot: 0 when
+	 * it may ask now. A load retry waits at least this long, so a retry policy
+	 * cannot request faster than the floor allows (ADS-07).
 	 */
-	reset(key: string): void;
+	waitFor(key: string, minIntervalMs: number): number;
 	clear(): void;
-	/** Diagnostics only: when the placement last requested, or undefined. */
-	lastRequestAt(key: string): number | undefined;
 }
 
 export function createRequestThrottle(now: () => number): RequestThrottle {
@@ -134,6 +131,10 @@ export function createRequestThrottle(now: () => number): RequestThrottle {
 	};
 
 	return {
+		waitFor(key, minIntervalMs) {
+			const decision = decide(key, minIntervalMs);
+			return decision.allowed ? 0 : decision.retryAfterMs;
+		},
 		tryAcquire(key, minIntervalMs, token) {
 			if (token !== undefined) {
 				const previous = lastToken.get(key);
@@ -161,16 +162,9 @@ export function createRequestThrottle(now: () => number): RequestThrottle {
 			}
 			return decision;
 		},
-		reset(key) {
-			lastAt.delete(key);
-			lastToken.delete(key);
-		},
 		clear() {
 			lastAt.clear();
 			lastToken.clear();
 		},
-		lastRequestAt(key) {
-			return lastAt.get(key);
-		},
 	};
 }

package/src/diagnostics/errors.ts

@@ -60,6 +60,10 @@ export type AdsErrorCode =
 	// is a show refusal that resolves with time rather than with another attempt.
 	| 'ad_originated_return'
 	| 'provider_error'
+	// The provider refused the request itself: an invalid ad unit or request, a
+	// missing app id. Not retryable — the same request fails the same way, and
+	// retrying would spend billable requests on a certainty (FR-135, ADS-08).
+	| 'provider_rejected'
 	| 'internal_error'
 	// Configuration — a retry policy outside its bounds. Rejected rather than
 	// clamped, matching `timeout_out_of_bounds`: silently clamping tells the app
@@ -181,12 +185,27 @@ export function redact(value: unknown): string {
 }
 
 /**
- * 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.
+ * Maps a provider failure onto the normalized taxonomy.
+ *
+ * The adapter's classification wins when it gave one (ADS-08). Otherwise the
+ * match is on substrings that have been stable across provider releases, and
+ * anything unrecognized becomes a retryable `provider_error` rather than being
+ * reshaped into a code that means something specific.
  */
-export function normalizeProviderError(value: unknown, options: AdsErrorOptions = {}): AdsError {
+export function normalizeProviderError(
+	value: unknown,
+	options: AdsErrorOptions = {},
+	kind?: 'no_fill' | 'network' | 'rejected',
+): AdsError {
+	switch (kind) {
+		case 'no_fill':
+			return new AdsError('no_fill', { ...options, cause: value });
+		case 'network':
+			return new AdsError('network_error', { ...options, cause: value });
+		case 'rejected':
+			return new AdsError('provider_rejected', { ...options, cause: value });
+		default:
+	}
 	const text = value instanceof Error ? value.message : String(value ?? '');
 	const lowered = text.toLowerCase();
 

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

@@ -18,9 +18,13 @@
 
 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,
@@ -58,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. */
@@ -218,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) {
@@ -308,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' }));
@@ -323,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);
 		},
@@ -408,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;
-}