@chipmobilesdk/rn-ads 0.2.1 → 0.4.0

package/src/core/consentFlow.ts

@@ -34,6 +34,7 @@ export const INITIAL_CONSENT: ConsentSnapshot = {
 	state: 'undetermined',
 	canRequestAds: false,
 	isFormAvailable: false,
+	privacyOptionsRequirement: 'unknown',
 	error: null,
 };
 
@@ -59,6 +60,7 @@ export function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot {
 		state,
 		canRequestAds: info.canRequestAds === true,
 		isFormAvailable: info.isFormAvailable === true,
+		privacyOptionsRequirement: info.privacyOptions,
 		error: null,
 	};
 }
@@ -70,9 +72,19 @@ export function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot {
  * There is no failure mode in which "the flow broke" should mean "go ahead", and
  * making that structural rather than conditional means no future edit can
  * accidentally reintroduce the inference.
+ *
+ * The privacy-options requirement is `unknown` for the same reason: a broken
+ * flow has no provider verdict to forward, and reporting `not_required` would be
+ * the package deciding the user has no right to change their mind (FR-150).
  */
 export function consentFailure(error: AdsError): ConsentSnapshot {
-	return { state: 'error', canRequestAds: false, isFormAvailable: false, error };
+	return {
+		state: 'error',
+		canRequestAds: false,
+		isFormAvailable: false,
+		privacyOptionsRequirement: 'unknown',
+		error,
+	};
 }
 
 export function toConsentError(cause: unknown, message: string): AdsError {
@@ -161,6 +173,7 @@ export function createConsentPortGuard(port: ConsentPort | undefined): ConsentPo
 	return {
 		requestInfoUpdate: unavailable,
 		showFormIfRequired: unavailable,
+		showPrivacyOptionsForm: unavailable,
 		getInfo: unavailable,
 		reset: () => undefined,
 	};

package/src/core/initMachine.ts

@@ -23,6 +23,13 @@ export type InitEvent =
 	| { readonly type: 'UNDECIDE' }
 	| { readonly type: 'ENABLE' }
 	| { readonly type: 'SUCCEED' }
+	/**
+	 * Back to `ready` with no native call, because the provider was initialized
+	 * earlier and nothing has torn it down since (FR-154). The instance decides
+	 * whether that holds; this machine only refuses to resume from a state a
+	 * fresh start could not leave either.
+	 */
+	| { readonly type: 'RESUME' }
 	| { readonly type: 'FAIL'; readonly error: AdsError };
 
 export interface InitSnapshot {
@@ -165,6 +172,12 @@ export function initReducer(state: InitSnapshot, event: InitEvent): InitSnapshot
 			// resurrect a state the app deliberately left.
 			return state.status === 'initializing' ? at('ready') : state;
 
+		case 'RESUME':
+			// Same guard as START, for the same reason: `disabled`, `undecided` and
+			// `unavailable` are not left by a gate reopening. `canStart` excludes
+			// them, and `initializing`, whose own outcome is still on its way.
+			return canStart(state.status) ? at('ready') : state;
+
 		case 'FAIL':
 			return state.status === 'initializing' ? at('failed', { error: event.error }) : state;
 

package/src/core/requestThrottle.ts

@@ -0,0 +1,176 @@
+/**
+ * Per-placement request throttle (FR-140).
+ *
+ * This exists to protect the **ad account**, not to shape product behaviour, and
+ * that distinction is the whole reason it lives in the package:
+ *
+ * | Decision | Owner |
+ * |---|---|
+ * | How often to *show* an interstitial | the app — product policy |
+ * | How often the same placement may *request* | the package — account safety |
+ *
+ * Rapid repeat requests for one placement are read by ad networks as invalid
+ * traffic, and the penalty is account-level and not recoverable by shipping a
+ * fix. That puts it in the same class as the test-ad substitution the package
+ * already enforces: a safety property the library guarantees rather than
+ * documents and hopes each app remembers.
+ *
+ * ## The pattern it is built for
+ *
+ * A banner mounted inside a view the user navigates between — a day in a
+ * calendar, a tab, a row in a list — is unmounted and remounted by React on every
+ * navigation. Each remount is a fresh provider request. A user swiping quickly
+ * through ten days produces ten requests in a few seconds, and nothing about that
+ * is the app author doing something wrong.
+ *
+ * Full-screen formats do not have this problem: they are loaded by an explicit
+ * call, not mounted by a renderer. That asymmetry is why the default differs by
+ * format — see `defaultMinRequestIntervalMs`.
+ *
+ * The better *architectural* answer is to keep the banner outside the subtree that
+ * remounts. This throttle is the safety net for when that is not possible, not a
+ * licence to ignore the problem; the README says so where an app author will read
+ * it.
+ */
+
+import type { AdFormat } from '../config/types';
+
+/**
+ * AdMob's own documented floor for banner auto-refresh is 60 seconds, so
+ * requesting the same banner placement more often than that is, by the provider's
+ * own standard, more often than it considers reasonable. Taking the provider's
+ * number rather than inventing one means the default is defensible rather than
+ * arbitrary.
+ */
+export const DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = 60_000;
+
+/**
+ * Off by default for full-screen formats.
+ *
+ * `load` → `show` → `load` is the normal, healthy cycle for an interstitial, and
+ * an app that sells three things in two minutes legitimately loads three times.
+ * Throttling that by default would break correct apps to solve a problem those
+ * formats do not have. An app that wants a floor here can set one.
+ */
+export const DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = 0;
+
+export const MIN_REQUEST_INTERVAL_BOUNDS = { min: 0, max: 600_000 } as const;
+
+/** The format-aware default, applied when a placement configures nothing. */
+export function defaultMinRequestIntervalMs(format: AdFormat): number {
+	return format === 'banner'
+		? DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS
+		: DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS;
+}
+
+export type ThrottleDecision =
+	| { readonly allowed: true }
+	/**
+	 * `retryAfterMs` is reported rather than left for the caller to compute,
+	 * because the app needs it to decide between collapsing the space and holding
+	 * it — and a caller recomputing it from a timestamp would drift from the
+	 * clock this throttle actually used.
+	 */
+	| { readonly allowed: false; readonly retryAfterMs: number };
+
+export interface RequestThrottle {
+	/**
+	 * Records a request and reports whether it may proceed.
+	 *
+	 * Call immediately before handing a request to the provider.
+	 *
+	 * `token` makes the acquisition **idempotent for one request cycle**, and the
+	 * 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.
+	 *
+	 * 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.
+	 */
+	reset(key: string): void;
+	clear(): void;
+	/** Diagnostics only: when the placement last requested, or undefined. */
+	lastRequestAt(key: string): number | undefined;
+}
+
+export function createRequestThrottle(now: () => number): RequestThrottle {
+	const lastAt = new Map<string, number>();
+	/** The token and verdict of the most recent acquisition, for idempotency. */
+	const lastToken = new Map<string, { token: string; decision: ThrottleDecision }>();
+
+	const decide = (key: string, minIntervalMs: number): ThrottleDecision => {
+		// Zero is the documented way to turn the throttle off, so it must never
+		// consult the clock — an app that sets 0 should behave exactly as it did
+		// before this feature existed.
+		if (minIntervalMs <= 0) {
+			return { allowed: true };
+		}
+		const previous = lastAt.get(key);
+		if (previous === undefined) {
+			return { allowed: true };
+		}
+		const elapsed = now() - previous;
+		// A clock that moved backwards — a manual time change, or an NTP
+		// correction — must not lock a placement out until the clock catches up.
+		// Treating it as "enough time passed" fails open, which is right: the
+		// throttle protects against bursts, and a backwards clock is not a burst.
+		if (elapsed < 0) {
+			return { allowed: true };
+		}
+		if (elapsed >= minIntervalMs) {
+			return { allowed: true };
+		}
+		return { allowed: false, retryAfterMs: minIntervalMs - elapsed };
+	};
+
+	return {
+		tryAcquire(key, minIntervalMs, token) {
+			if (token !== undefined) {
+				const previous = lastToken.get(key);
+				if (previous?.token === token) {
+					// Same cycle asking again. Replaying the stored verdict keeps a
+					// double-invoked render from charging twice, and keeps a refused
+					// cycle refused rather than letting a retry slip through.
+					return previous.decision;
+				}
+			}
+
+			// Nothing is recorded when the throttle is off for this placement.
+			// Recording would be dead work, and it would also mean that turning the
+			// throttle on later immediately compared against a stale timestamp.
+			if (minIntervalMs <= 0) {
+				return { allowed: true };
+			}
+
+			const decision = decide(key, minIntervalMs);
+			if (decision.allowed) {
+				lastAt.set(key, now());
+			}
+			if (token !== undefined) {
+				lastToken.set(key, { token, decision });
+			}
+			return decision;
+		},
+		reset(key) {
+			lastAt.delete(key);
+			lastToken.delete(key);
+		},
+		clear() {
+			lastAt.clear();
+			lastToken.clear();
+		},
+		lastRequestAt(key) {
+			return lastAt.get(key);
+		},
+	};
+}

package/src/diagnostics/events.ts

@@ -33,6 +33,12 @@ export type AdEventType =
 	// cycle that triggered it. Each attempt is a billable request, so it has to
 	// be reconcilable against a bill from the event stream alone (FR-138).
 	| 'retry_scheduled'
+	// Emitted when the per-placement throttle refuses a request (FR-140). Carries
+	// no correlation id because no cycle began: nothing was requested, so there is
+	// nothing to correlate. Present so a throttled placement is visible in
+	// whatever logging the app already has, rather than looking like a silent
+	// absence of ads.
+	| 'request_throttled'
 	| 'internal_error';
 
 interface BaseEvent {
@@ -76,6 +82,13 @@ export type AdEvent = BaseEvent &
 				readonly delayMs: number;
 				readonly error: AdsError;
 		  }
+		| {
+				readonly type: 'request_throttled';
+				/** How long until this placement may request again. */
+				readonly retryAfterMs: number;
+				/** The configured floor that refused it, so the cause is readable. */
+				readonly minRequestIntervalMs: number;
+		  }
 		| {
 				readonly type: 'config_warning';
 				readonly warning: ConfigWarning;

package/src/engine/admobEngine.ts

@@ -61,6 +61,7 @@ interface ProviderModule {
 interface ProviderConsent {
 	requestInfoUpdate(options?: Record<string, unknown>): Promise<ProviderConsentInfo>;
 	loadAndShowConsentFormIfRequired(): Promise<ProviderConsentInfo>;
+	showPrivacyOptionsForm(): Promise<ProviderConsentInfo>;
 	getConsentInfo(): Promise<ProviderConsentInfo>;
 	reset(): void;
 }
@@ -69,6 +70,7 @@ interface ProviderConsentInfo {
 	status?: string;
 	canRequestAds?: boolean;
 	isConsentFormAvailable?: boolean;
+	privacyOptionsRequirementStatus?: string;
 }
 
 /**
@@ -119,9 +121,25 @@ function toEngineConsentInfo(info: ProviderConsentInfo): EngineConsentInfo {
 		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;
@@ -362,6 +380,14 @@ function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPo
 			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());
 		},

package/src/engine/port.ts

@@ -52,6 +52,8 @@ export interface EngineConsentInfo {
 	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
 	readonly canRequestAds: boolean;
 	readonly isFormAvailable: boolean;
+	/** Whether the provider requires a "change my choice" entry point (FR-150). */
+	readonly privacyOptions: 'unknown' | 'required' | 'not_required';
 }
 
 export interface EngineConsentOptions {
@@ -76,6 +78,13 @@ export interface ConsentPort {
 	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
 	/** Presents the provider's form if one is required; a no-op otherwise. */
 	showFormIfRequired(): Promise<EngineConsentInfo>;
+	/**
+	 * Presents the provider's privacy options form, through which a user changes
+	 * an answer already given (FR-151). Resolves when the form closes, whether or
+	 * not anything changed; rejects if it could not be presented. The caller has
+	 * already checked the requirement, so the adapter does not re-check.
+	 */
+	showPrivacyOptionsForm(): Promise<EngineConsentInfo>;
 	/** Last known information without contacting the network. */
 	getInfo(): Promise<EngineConsentInfo>;
 	/** Clears the stored decision. Inert in production by configuration. */

package/src/index.ts

@@ -1,91 +1,103 @@
-/**
- * @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,
-	ConsentSnapshot,
-	ConsentState,
-	ConsentTestingOptions,
-	Enablement,
-	Environment,
-	FullScreenFormat,
-	InitStatus,
-	PlacementDefinition,
-	PlacementState,
-	PrivacyBlockReason,
-	PrivacyOptions,
-	RetryPolicy,
-	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,
-	APP_OPEN_VALIDITY_BOUNDS,
-	DEFAULT_AD_VALIDITY_MS,
-	DEFAULT_APP_OPEN_VALIDITY_MS,
-	DEFAULT_LOAD_TIMEOUT_MS,
-	DEFAULT_RETRY_POLICY,
-	DEFAULT_SHOW_TIMEOUT_MS,
-	DEFAULT_UNDECIDED_WARNING_MS,
-	LOAD_TIMEOUT_BOUNDS,
-	RETRY_BOUNDS,
-	SHOW_TIMEOUT_BOUNDS,
-	UNDECIDED_WARNING_BOUNDS,
-} from './core/timers';
-
-// Enablement. `EnablementResult` is what `setEnabled` returns in place of
-// 0.1.0's `void` — the defect that let a re-enable fail in silence (FR-122).
-export type { EnablementResult } from './core/enablement';
-
-// Instance, lifecycle, and results
-export { createAds } from './core/adsInstance';
-export type {
-	AdsInstance,
-	ConsentApi,
-	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,
-	ConfigWarning,
-	ImpressionSource,
-} from './diagnostics/events';
+/**
+ * @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,
+	ConsentSnapshot,
+	ConsentState,
+	ConsentTestingOptions,
+	Enablement,
+	Environment,
+	FullScreenFormat,
+	InitStatus,
+	PlacementDefinition,
+	PlacementState,
+	PrivacyBlockReason,
+	PrivacyOptions,
+	PrivacyOptionsRequirement,
+	RetryPolicy,
+	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,
+	APP_OPEN_VALIDITY_BOUNDS,
+	DEFAULT_AD_VALIDITY_MS,
+	DEFAULT_APP_OPEN_VALIDITY_MS,
+	DEFAULT_LOAD_TIMEOUT_MS,
+	DEFAULT_RETRY_POLICY,
+	DEFAULT_SHOW_TIMEOUT_MS,
+	DEFAULT_UNDECIDED_WARNING_MS,
+	LOAD_TIMEOUT_BOUNDS,
+	RETRY_BOUNDS,
+	SHOW_TIMEOUT_BOUNDS,
+	UNDECIDED_WARNING_BOUNDS,
+} from './core/timers';
+
+// Request throttle — account safety, added in 0.3.0 (FR-140). Exported so an app
+// can read the floor it is bound by, and so the format-aware default is legible
+// rather than something to discover from a `throttled` state in production.
+export {
+	DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS,
+	DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS,
+	MIN_REQUEST_INTERVAL_BOUNDS,
+	defaultMinRequestIntervalMs,
+} from './core/requestThrottle';
+
+// Enablement. `EnablementResult` is what `setEnabled` returns in place of
+// 0.1.0's `void` — the defect that let a re-enable fail in silence (FR-122).
+export type { EnablementResult } from './core/enablement';
+
+// Instance, lifecycle, and results
+export { createAds } from './core/adsInstance';
+export type {
+	AdsInstance,
+	ConsentApi,
+	InitResult,
+	LoadResult,
+	PrivacyOptionsFormResult,
+	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,
+	ConfigWarning,
+	ImpressionSource,
+} from './diagnostics/events';