@chipmobilesdk/rn-ads 0.3.0 → 0.5.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/placementMachine.ts

@@ -40,9 +40,19 @@ export const initialPlacement: PlacementSnapshot = {
 	correlationId: null,
 };
 
-/** A load is only legal from a settled state; `loading` is where FR-029 bites. */
+/**
+ * A load is only legal from a settled state; `loading` is where FR-029 bites.
+ * `throttled` is settled too: it records that the last request was refused, and
+ * the throttle itself decides whether the next one may proceed.
+ */
 export function canLoad(state: PlacementState): boolean {
-	return state === 'idle' || state === 'failed' || state === 'consumed' || state === 'ready';
+	return (
+		state === 'idle' ||
+		state === 'failed' ||
+		state === 'consumed' ||
+		state === 'ready' ||
+		state === 'throttled'
+	);
 }
 
 /** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */

package/src/core/privacyGate.ts

@@ -15,7 +15,7 @@
  */
 
 import type { PrivacyBlockReason, PrivacyOptions } from '../config/types';
-import type { EnginePrivacy } from '../engine/port';
+import type { EnginePrivacy, EngineRequestOptions } from '../engine/port';
 
 export type GateDecision =
 	| { readonly allowed: true }
@@ -83,3 +83,12 @@ export function toEnginePrivacy(
 		testDeviceIds,
 	};
 }
+
+/**
+ * What every ad request carries. Unset means personalized, matching the
+ * documented default of `PrivacyOptions.personalizedAds`; only an explicit
+ * `false` opts out.
+ */
+export function toEngineRequest(privacy: PrivacyOptions | null): EngineRequestOptions {
+	return { personalizedAds: privacy?.personalizedAds !== false };
+}

package/src/engine/admobEngine.ts

@@ -27,6 +27,7 @@ import type {
 	EngineConsentInfo,
 	EngineConsentOptions,
 	EnginePrivacy,
+	EngineRequestOptions,
 } from './port';
 
 /** The slice of the bridge this adapter uses. Kept local so nothing else sees it. */
@@ -61,6 +62,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 +71,7 @@ interface ProviderConsentInfo {
 	status?: string;
 	canRequestAds?: boolean;
 	isConsentFormAvailable?: boolean;
+	privacyOptionsRequirementStatus?: string;
 }
 
 /**
@@ -119,9 +122,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;
@@ -209,7 +228,11 @@ export function createAdMobEngine(): AdsEngine {
 			await mobileAds.initialize();
 		},
 
-		async createFullScreen(format: FullScreenFormat, adUnitId: string) {
+		async createFullScreen(
+			format: FullScreenFormat,
+			adUnitId: string,
+			request?: EngineRequestOptions,
+		) {
 			const module = getProvider();
 			if (!module) {
 				throw new Error('provider_missing');
@@ -224,7 +247,7 @@ export function createAdMobEngine(): AdsEngine {
 			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,
+				requestNonPersonalizedAdsOnly: request?.personalizedAds === false,
 			});
 
 			counter += 1;
@@ -362,6 +385,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

@@ -23,6 +23,17 @@ export interface EnginePrivacy {
 	readonly testDeviceIds?: readonly string[];
 }
 
+/**
+ * Privacy that applies to each ad request rather than to initialization.
+ *
+ * `personalizedAds` is here, not only in `EnginePrivacy`, because the provider
+ * reads it per request and `updatePrivacy` may change it without
+ * reinitializing: a request must carry the value current at request time.
+ */
+export interface EngineRequestOptions {
+	readonly personalizedAds: boolean;
+}
+
 /**
  * Provider callbacks, normalized to the vocabulary the core state machines use.
  * `rewarded` and `dismissed` are separate members because they are separate
@@ -52,6 +63,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 +89,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. */
@@ -99,8 +119,16 @@ export interface AdsEngine {
 	 */
 	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>;
+	/**
+	 * Creates and begins loading one full-screen ad. Resolves on request, not on
+	 * load. `request` is optional so engines written against 0.4.0 still satisfy
+	 * the port; an engine that ignores it requests personalized ads.
+	 */
+	createFullScreen(
+		format: FullScreenFormat,
+		adUnitId: string,
+		request?: EngineRequestOptions,
+	): Promise<EngineAdHandle>;
 
 	/** Presents a loaded ad. Rejects if the provider refuses to present. */
 	show(handle: EngineAdHandle): Promise<void>;

package/src/index.ts

@@ -1,101 +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';
-
-// 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,
-	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';