@chipmobilesdk/rn-ads 0.3.0 → 0.4.0

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';

package/src/testing/index.ts

@@ -97,9 +97,27 @@ export function createTestClock(startMs = 1_000_000): TestClock {
 export type FakeConsentCall =
 	| { readonly kind: 'requestInfoUpdate'; readonly options: EngineConsentOptions }
 	| { readonly kind: 'showFormIfRequired' }
+	| { readonly kind: 'showPrivacyOptionsForm' }
 	| { readonly kind: 'getInfo' }
 	| { readonly kind: 'reset' };
 
+/**
+ * A privacy options form the test is holding open (0.4.0).
+ *
+ * Settle it whenever the test chooses, which is what lets `busy`, a second
+ * call, a consent update, and `dispose()` all be exercised *while* the form is
+ * on screen — in any order, rather than only the one a resolved promise allows.
+ */
+export interface HeldPrivacyOptionsForm {
+	/**
+	 * The user closes the form. `info` is what the provider reports afterwards,
+	 * merged over the current information; omit it for a user who changed nothing.
+	 */
+	close(info?: Partial<EngineConsentInfo>): void;
+	/** The form fails while open. */
+	fail(cause?: unknown): void;
+}
+
 export type FakeEngineCall =
 	| { readonly kind: 'initialize'; readonly privacy: EnginePrivacy }
 	| {
@@ -133,6 +151,7 @@ const DEFAULT_CONSENT: EngineConsentInfo = {
 	status: 'not_required',
 	canRequestAds: true,
 	isFormAvailable: false,
+	privacyOptions: 'not_required',
 };
 
 export interface FakeAdsEngine extends AdsEngine {
@@ -166,6 +185,19 @@ export interface FakeAdsEngine extends AdsEngine {
 	failConsentRequest(cause?: unknown): void;
 	/** Makes `showFormIfRequired` reject — dismissal is not consent (FR-106). */
 	failConsentForm(cause?: unknown): void;
+
+	/**
+	 * What the privacy options form reports when the user closes it, merged over
+	 * the current information. Unset, the form closes with nothing changed — the
+	 * same as a user who opens it and backs out.
+	 */
+	setPrivacyOptionsFormResult(info: Partial<EngineConsentInfo>): void;
+	/** Makes `showPrivacyOptionsForm` reject — a failure is never consent (FR-106). */
+	failPrivacyOptionsForm(cause?: unknown): void;
+	/** Holds the next privacy options form open until the test settles it. */
+	holdPrivacyOptionsForm(): HeldPrivacyOptionsForm;
+	/** Makes `getInfo` reject, for the case where even the re-read after a failed form fails. */
+	failConsentInfoRead(cause?: unknown): void;
 }
 
 export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
@@ -175,6 +207,11 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 	let consentInfo: EngineConsentInfo = { ...DEFAULT_CONSENT, ...options.consentInfo };
 	let consentRequestFailure: unknown;
 	let consentFormFailure: unknown;
+	let privacyFormFailure: unknown;
+	let privacyFormResult: Partial<EngineConsentInfo> = {};
+	let consentReadFailure: unknown;
+	/** Set by `holdPrivacyOptionsForm`; consumed by the next form. */
+	let heldForm: Promise<Partial<EngineConsentInfo>> | null = null;
 
 	const consent: ConsentPort = {
 		async requestInfoUpdate(consentOptions) {
@@ -192,18 +229,49 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 			// A presented form that the user completes moves the status on. The
 			// fake only does this when a form was actually required, mirroring the
 			// provider: showing nothing cannot change an answer.
+			// A region that required a form is one that requires a way back into
+			// it, which is what the provider reports once consent is obtained.
 			if (consentInfo.status === 'required' && consentInfo.isFormAvailable) {
-				consentInfo = { status: 'obtained', canRequestAds: true, isFormAvailable: false };
+				consentInfo = {
+					status: 'obtained',
+					canRequestAds: true,
+					isFormAvailable: false,
+					privacyOptions: 'required',
+				};
+			}
+			return consentInfo;
+		},
+		async showPrivacyOptionsForm() {
+			consentCalls.push({ kind: 'showPrivacyOptionsForm' });
+			const held = heldForm;
+			heldForm = null;
+			if (held) {
+				// Rejects if the test calls `fail`, which is exactly the provider's
+				// failure path; resolves with what the user left behind otherwise.
+				consentInfo = { ...consentInfo, ...(await held) };
+				return consentInfo;
 			}
+			if (privacyFormFailure !== undefined) {
+				throw privacyFormFailure;
+			}
+			consentInfo = { ...consentInfo, ...privacyFormResult };
 			return consentInfo;
 		},
 		async getInfo() {
 			consentCalls.push({ kind: 'getInfo' });
+			if (consentReadFailure !== undefined) {
+				throw consentReadFailure;
+			}
 			return consentInfo;
 		},
 		reset() {
 			consentCalls.push({ kind: 'reset' });
-			consentInfo = { status: 'unknown', canRequestAds: false, isFormAvailable: true };
+			consentInfo = {
+				status: 'unknown',
+				canRequestAds: false,
+				isFormAvailable: true,
+				privacyOptions: 'unknown',
+			};
 		},
 	};
 	const listeners = new Map<string, Set<(event: EngineAdEvent) => void>>();
@@ -238,6 +306,37 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 			consentFormFailure = cause;
 		},
 
+		setPrivacyOptionsFormResult(info) {
+			privacyFormResult = info;
+		},
+
+		failPrivacyOptionsForm(cause = new Error('privacy options form failed')) {
+			privacyFormFailure = cause;
+		},
+
+		holdPrivacyOptionsForm() {
+			let settle!: {
+				resolve: (info: Partial<EngineConsentInfo>) => void;
+				reject: (cause: unknown) => void;
+			};
+			const promise = new Promise<Partial<EngineConsentInfo>>((resolve, reject) => {
+				settle = { resolve, reject };
+			});
+			heldForm = promise;
+			return {
+				close(info = {}) {
+					settle.resolve(info);
+				},
+				fail(cause = new Error('privacy options form failed')) {
+					settle.reject(cause);
+				},
+			};
+		},
+
+		failConsentInfoRead(cause = new Error('consent information read failed')) {
+			consentReadFailure = cause;
+		},
+
 		isAvailable() {
 			return options.available !== false;
 		},