@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/core/placementMachine.ts

@@ -1,124 +1,124 @@
-/**
- * Per-placement lifecycle (FR-026 – FR-031, FR-034).
- *
- * Pure and synchronous, per data-model.md §3.2. Two variants share one reducer:
- *
- *   full-screen — load, show once, become `consumed`, reload before the next show
- *   banner      — continuous; it renders and may refresh, and never reaches
- *                 `consumed`, because a banner is not a single-use resource
- *
- * Staleness is handled here rather than at the show site so that a stale ad can
- * never be *reported* ready either — a consumer that renders a "Watch ad" button
- * from `state === 'ready'` would otherwise offer a button that fails on tap.
- */
-
-import type { AdFormat, PlacementState, UnavailableReason } from '../config/types';
-import type { AdsError } from '../diagnostics/errors';
-
-export type PlacementEvent =
-	| { readonly type: 'LOAD' }
-	| { readonly type: 'LOADED'; readonly atMs: number }
-	| { readonly type: 'LOAD_FAILED'; readonly error: AdsError }
-	| { readonly type: 'SHOW' }
-	| { readonly type: 'SHOW_FAILED'; readonly error: AdsError }
-	| { readonly type: 'DISMISSED' }
-	| { readonly type: 'EXPIRE' }
-	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
-	| { readonly type: 'RESET' };
-
-export interface PlacementSnapshot {
-	readonly state: PlacementState;
-	readonly loadedAtMs: number | null;
-	readonly error: AdsError | null;
-	readonly correlationId: string | null;
-}
-
-export const initialPlacement: PlacementSnapshot = {
-	state: 'idle',
-	loadedAtMs: null,
-	error: null,
-	correlationId: null,
-};
-
-/**
- * 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' ||
-		state === 'throttled'
-	);
-}
-
-/** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */
-export function canShow(state: PlacementState): boolean {
-	return state === 'ready';
-}
-
-export function placementReducer(
-	state: PlacementSnapshot,
-	event: PlacementEvent,
-	format: AdFormat,
-): PlacementSnapshot {
-	switch (event.type) {
-		case 'LOAD':
-			// FR-029: a load while already loading is absorbed. The instance
-			// returns the in-flight promise; the state does not restart.
-			if (state.state === 'loading' || state.state === 'showing') {
-				return state;
-			}
-			if (state.state === 'unavailable') {
-				return state;
-			}
-			return { ...initialPlacement, state: 'loading' };
-
-		case 'LOADED':
-			return state.state === 'loading'
-				? { ...state, state: 'ready', loadedAtMs: event.atMs, error: null }
-				: state;
-
-		case 'LOAD_FAILED':
-			return state.state === 'loading'
-				? { ...initialPlacement, state: 'failed', error: event.error }
-				: state;
-
-		case 'SHOW':
-			return state.state === 'ready' ? { ...state, state: 'showing' } : state;
-
-		case 'SHOW_FAILED':
-			// A failed presentation consumes the ad regardless: the provider has
-			// taken it, and re-showing the same object is what FR-031 forbids.
-			return state.state === 'showing'
-				? { ...initialPlacement, state: 'failed', error: event.error }
-				: state;
-
-		case 'DISMISSED':
-			if (state.state !== 'showing') {
-				return state;
-			}
-			// A banner is continuous — dismissal is not part of its life. A
-			// full-screen ad is spent, and must be reloaded before the next show.
-			return format === 'banner'
-				? { ...initialPlacement, state: 'idle' }
-				: { ...initialPlacement, state: 'consumed' };
-
-		case 'EXPIRE':
-			// FR-034. Only a ready-and-waiting ad can go stale; one being shown is
-			// already in the user's hands.
-			return state.state === 'ready' ? { ...initialPlacement, state: 'idle' } : state;
-
-		case 'UNAVAILABLE':
-			return { ...initialPlacement, state: 'unavailable' };
-
-		case 'RESET':
-			return initialPlacement;
-
-		default:
-			return state;
-	}
-}
+/**
+ * Per-placement lifecycle (FR-026 – FR-031, FR-034).
+ *
+ * Pure and synchronous, per data-model.md §3.2. Two variants share one reducer:
+ *
+ *   full-screen — load, show once, become `consumed`, reload before the next show
+ *   banner      — continuous; it renders and may refresh, and never reaches
+ *                 `consumed`, because a banner is not a single-use resource
+ *
+ * Staleness is handled here rather than at the show site so that a stale ad can
+ * never be *reported* ready either — a consumer that renders a "Watch ad" button
+ * from `state === 'ready'` would otherwise offer a button that fails on tap.
+ */
+
+import type { AdFormat, PlacementState, UnavailableReason } from '../config/types';
+import type { AdsError } from '../diagnostics/errors';
+
+export type PlacementEvent =
+	| { readonly type: 'LOAD' }
+	| { readonly type: 'LOADED'; readonly atMs: number }
+	| { readonly type: 'LOAD_FAILED'; readonly error: AdsError }
+	| { readonly type: 'SHOW' }
+	| { readonly type: 'SHOW_FAILED'; readonly error: AdsError }
+	| { readonly type: 'DISMISSED' }
+	| { readonly type: 'EXPIRE' }
+	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
+	| { readonly type: 'RESET' };
+
+export interface PlacementSnapshot {
+	readonly state: PlacementState;
+	readonly loadedAtMs: number | null;
+	readonly error: AdsError | null;
+	readonly correlationId: string | null;
+}
+
+export const initialPlacement: PlacementSnapshot = {
+	state: 'idle',
+	loadedAtMs: null,
+	error: null,
+	correlationId: null,
+};
+
+/**
+ * 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' ||
+		state === 'throttled'
+	);
+}
+
+/** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */
+export function canShow(state: PlacementState): boolean {
+	return state === 'ready';
+}
+
+export function placementReducer(
+	state: PlacementSnapshot,
+	event: PlacementEvent,
+	format: AdFormat,
+): PlacementSnapshot {
+	switch (event.type) {
+		case 'LOAD':
+			// FR-029: a load while already loading is absorbed. The instance
+			// returns the in-flight promise; the state does not restart.
+			if (state.state === 'loading' || state.state === 'showing') {
+				return state;
+			}
+			if (state.state === 'unavailable') {
+				return state;
+			}
+			return { ...initialPlacement, state: 'loading' };
+
+		case 'LOADED':
+			return state.state === 'loading'
+				? { ...state, state: 'ready', loadedAtMs: event.atMs, error: null }
+				: state;
+
+		case 'LOAD_FAILED':
+			return state.state === 'loading'
+				? { ...initialPlacement, state: 'failed', error: event.error }
+				: state;
+
+		case 'SHOW':
+			return state.state === 'ready' ? { ...state, state: 'showing' } : state;
+
+		case 'SHOW_FAILED':
+			// A failed presentation consumes the ad regardless: the provider has
+			// taken it, and re-showing the same object is what FR-031 forbids.
+			return state.state === 'showing'
+				? { ...initialPlacement, state: 'failed', error: event.error }
+				: state;
+
+		case 'DISMISSED':
+			if (state.state !== 'showing') {
+				return state;
+			}
+			// A banner is continuous — dismissal is not part of its life. A
+			// full-screen ad is spent, and must be reloaded before the next show.
+			return format === 'banner'
+				? { ...initialPlacement, state: 'idle' }
+				: { ...initialPlacement, state: 'consumed' };
+
+		case 'EXPIRE':
+			// FR-034. Only a ready-and-waiting ad can go stale; one being shown is
+			// already in the user's hands.
+			return state.state === 'ready' ? { ...initialPlacement, state: 'idle' } : state;
+
+		case 'UNAVAILABLE':
+			return { ...initialPlacement, state: 'unavailable' };
+
+		case 'RESET':
+			return initialPlacement;
+
+		default:
+			return state;
+	}
+}

package/src/core/privacyGate.ts

@@ -1,94 +1,93 @@
-/**
- * The privacy gate (FR-016 – FR-021).
- *
- * The package enforces ordering; the app owns policy. It renders no consent UI,
- * writes no legal copy, and decides nothing about a jurisdiction — it accepts a
- * gate outcome and refuses to let any request precede it.
- *
- * That refusal is the whole value. Consent ordering is easy to get wrong by
- * accident, and the failure is invisible: an ad request that should not have
- * happened looks exactly like one that should. A package that enforces the order
- * is worth more than documentation that describes it.
- *
- * Pure — no provider, no React, no I/O. The engine adapter translates the
- * outcome into provider configuration.
- */
-
-import type { PrivacyBlockReason, PrivacyOptions } from '../config/types';
-import type { EnginePrivacy, EngineRequestOptions } from '../engine/port';
-
-export type GateDecision =
-	| { readonly allowed: true }
-	| { readonly allowed: false; readonly reason: PrivacyBlockReason };
-
-export function evaluateGate(privacy: PrivacyOptions | null): GateDecision {
-	if (!privacy) {
-		return { allowed: false, reason: 'consent_required' };
-	}
-	if (privacy.canRequestAds) {
-		return { allowed: true };
-	}
-	// Distinguishing "not asked yet" from "asked and refused" matters: the first
-	// is a prompt the app still owes the user, the second is a settled answer.
-	// Collapsing them would leave the app unable to tell which (FR-018).
-	return {
-		allowed: false,
-		reason: privacy.consentUndetermined ? 'consent_undetermined' : 'consent_required',
-	};
-}
-
-/**
- * Flags the provider only honors at initialization time.
- *
- * Changing one of these after `initialize()` cannot take effect, which is why
- * `updatePrivacy` reports `requires_reinitialization` instead of accepting the
- * change and leaving the package in a state that is half old and half new
- * (FR-020).
- *
- * `canRequestAds` is absent on purpose: resolving the gate after being blocked
- * is the normal, supported flow, not a reinitialization (FR-019).
- */
-const INIT_TIME_ONLY = [
-	'childDirected',
-	'underAgeOfConsent',
-	'maxAdContentRating',
-] as const satisfies readonly (keyof PrivacyOptions)[];
-
-export function requiresReinitialization(
-	applied: PrivacyOptions | null,
-	next: PrivacyOptions,
-): boolean {
-	if (!applied) {
-		return false;
-	}
-	return INIT_TIME_ONLY.some(field => applied[field] !== next[field]);
-}
-
-/**
- * Projects consumer privacy options onto what the engine needs.
- *
- * `personalizedAds` is carried through rather than inverted here; the adapter
- * owns the translation to the provider's `requestNonPersonalizedAdsOnly`, so
- * the polarity flip lives next to the API that requires it.
- */
-export function toEnginePrivacy(
-	privacy: PrivacyOptions,
-	testDeviceIds: readonly string[],
-): EnginePrivacy {
-	return {
-		childDirected: privacy.childDirected,
-		underAgeOfConsent: privacy.underAgeOfConsent,
-		maxAdContentRating: privacy.maxAdContentRating,
-		personalizedAds: privacy.personalizedAds,
-		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 };
-}
+/**
+ * The privacy gate (FR-016 – FR-021).
+ *
+ * The package enforces ordering; the app owns policy. It renders no consent UI,
+ * writes no legal copy, and decides nothing about a jurisdiction — it accepts a
+ * gate outcome and refuses to let any request precede it.
+ *
+ * That refusal is the whole value. Consent ordering is easy to get wrong by
+ * accident, and the failure is invisible: an ad request that should not have
+ * happened looks exactly like one that should. A package that enforces the order
+ * is worth more than documentation that describes it.
+ *
+ * Pure — no provider, no React, no I/O. The engine adapter translates the
+ * outcome into provider configuration.
+ */
+
+import type { PrivacyBlockReason, PrivacyOptions } from '../config/types';
+import type { EnginePrivacy, EngineRequestOptions } from '../engine/port';
+
+export type GateDecision =
+	{ readonly allowed: true } | { readonly allowed: false; readonly reason: PrivacyBlockReason };
+
+export function evaluateGate(privacy: PrivacyOptions | null): GateDecision {
+	if (!privacy) {
+		return { allowed: false, reason: 'consent_required' };
+	}
+	if (privacy.canRequestAds) {
+		return { allowed: true };
+	}
+	// Distinguishing "not asked yet" from "asked and refused" matters: the first
+	// is a prompt the app still owes the user, the second is a settled answer.
+	// Collapsing them would leave the app unable to tell which (FR-018).
+	return {
+		allowed: false,
+		reason: privacy.consentUndetermined ? 'consent_undetermined' : 'consent_required',
+	};
+}
+
+/**
+ * Flags the provider only honors at initialization time.
+ *
+ * Changing one of these after `initialize()` cannot take effect, which is why
+ * `updatePrivacy` reports `requires_reinitialization` instead of accepting the
+ * change and leaving the package in a state that is half old and half new
+ * (FR-020).
+ *
+ * `canRequestAds` is absent on purpose: resolving the gate after being blocked
+ * is the normal, supported flow, not a reinitialization (FR-019).
+ */
+const INIT_TIME_ONLY = [
+	'childDirected',
+	'underAgeOfConsent',
+	'maxAdContentRating',
+] as const satisfies readonly (keyof PrivacyOptions)[];
+
+export function requiresReinitialization(
+	applied: PrivacyOptions | null,
+	next: PrivacyOptions,
+): boolean {
+	if (!applied) {
+		return false;
+	}
+	return INIT_TIME_ONLY.some(field => applied[field] !== next[field]);
+}
+
+/**
+ * Projects consumer privacy options onto what the engine needs.
+ *
+ * `personalizedAds` is carried through rather than inverted here; the adapter
+ * owns the translation to the provider's `requestNonPersonalizedAdsOnly`, so
+ * the polarity flip lives next to the API that requires it.
+ */
+export function toEnginePrivacy(
+	privacy: PrivacyOptions,
+	testDeviceIds: readonly string[],
+): EnginePrivacy {
+	return {
+		childDirected: privacy.childDirected,
+		underAgeOfConsent: privacy.underAgeOfConsent,
+		maxAdContentRating: privacy.maxAdContentRating,
+		personalizedAds: privacy.personalizedAds,
+		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 };
+}