@chipmobilesdk/rn-ads 0.5.1 → 0.7.0

package/src/core/instance/init.ts

@@ -0,0 +1,262 @@
+/**
+ * Initialization, privacy updates and enablement (FR-017 – FR-022, FR-115 –
+ * FR-125).
+ *
+ * One native initialization however many callers race (FR-022), none before
+ * the whole gate permits it (FR-017), and a gate that closes and reopens
+ * resumes instead of initializing again (FR-154).
+ */
+import { normalizeProviderError } from '../../diagnostics/errors';
+import { canResume, type EnablementResult } from '../enablement';
+import { canStart, initReducer } from '../initMachine';
+import { requiresReinitialization, evaluateGate, toEnginePrivacy } from '../privacyGate';
+import type { Enablement, PrivacyOptions } from '../../config/types';
+import type { InstanceContext } from './context';
+import {
+	armUndecidedWarning,
+	cancelAllRetries,
+	closeGate,
+	currentGate,
+	disarmUndecidedWarning,
+	refusalFor,
+} from './gate';
+import type { InitResult, PrivacyUpdateResult } from './types';
+
+export interface InitController {
+	initialize(privacy: PrivacyOptions): Promise<InitResult>;
+	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+	setEnablement(next: Enablement): EnablementResult;
+	/** Applies a consent outcome to the gate, initializing at most once (FR-105). */
+	reevaluateAfterConsent(): Promise<void>;
+}
+
+export function createInitController(context: InstanceContext): InitController {
+	const { state, engine, events, resolved, now } = context;
+
+	function warnSubstitutionOnce(): void {
+		if (state.warnedSubstitution || resolved.catalog.substitutedKeys.length === 0) {
+			return;
+		}
+		state.warnedSubstitution = true;
+		events.emit({
+			type: 'config_warning',
+			timestamp: now(),
+			warning: 'test_ad_unit_substituted',
+			placementKeys: resolved.catalog.substitutedKeys,
+		});
+	}
+
+	async function doInitialize(privacy: PrivacyOptions): Promise<InitResult> {
+		try {
+			// The adapter applies privacy configuration before initializing the
+			// provider; that ordering is the whole reason FR-017 is enforceable.
+			await engine.initialize(toEnginePrivacy(privacy, resolved.testDeviceIds));
+			// Recorded before the status moves, and whether or not it moves: a gate
+			// that closed while this was in flight leaves the status `blocked`, but
+			// the provider is initialized all the same and must not be again.
+			state.providerInitialized = true;
+			state.appliedPrivacy = privacy;
+			context.setInit(initReducer(state.init, { type: 'SUCCEED' }));
+			warnSubstitutionOnce();
+			return { status: 'ready' };
+		} catch (error) {
+			const normalized = normalizeProviderError(error, { operation: 'initialize' });
+			context.setInit(initReducer(state.init, { type: 'FAIL', error: normalized }));
+			return { status: 'failed', error: normalized };
+		} finally {
+			state.inFlightInit = null;
+		}
+	}
+
+	/**
+	 * Answers `initialize` without a native call when the provider is already up
+	 * (FR-022, FR-154), or returns `null` to let a real initialization proceed.
+	 * Init-time-only flags that changed meanwhile fall through to a real
+	 * initialization: it is the only way they can take effect.
+	 */
+	function resumeInitialized(privacy: PrivacyOptions): InitResult | null {
+		if (
+			!state.providerInitialized ||
+			!canStart(state.init.status) ||
+			requiresReinitialization(state.appliedPrivacy, privacy)
+		) {
+			return null;
+		}
+		context.setInit(initReducer(state.init, { type: 'RESUME' }));
+		return { status: 'ready' };
+	}
+
+	const controller: InitController = {
+		async initialize(privacy) {
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			state.currentPrivacy = privacy;
+
+			// Availability, then enablement, then consent — the one order, evaluated
+			// in the one place (FR-140). Nothing provider-facing happens on any
+			// refusal: not a configuration call, not an initialization (FR-017,
+			// FR-158). The consent flow opening the gate later initializes, through
+			// `reevaluateAfterConsent`.
+			const decision = currentGate(context);
+			if (!decision.allowed) {
+				const refusal = refusalFor(decision);
+				switch (refusal.status) {
+					case 'unavailable':
+						context.setInit(
+							initReducer(state.init, { type: 'UNAVAILABLE', reason: refusal.reason }),
+						);
+						break;
+					case 'disabled':
+						context.setInit(initReducer(state.init, { type: 'DISABLE' }));
+						break;
+					case 'undecided':
+						// FR-115: the status says `undecided`, so a banner host can hold
+						// its space instead of reclaiming it.
+						context.setInit(initReducer(state.init, { type: 'UNDECIDE' }));
+						armUndecidedWarning(context);
+						break;
+					default:
+						context.setInit(initReducer(state.init, { type: 'BLOCK', reason: refusal.reason }));
+				}
+				context.emitRefusal('initialize', refusal);
+				return refusal;
+			}
+
+			if (state.init.status === 'ready') {
+				return { status: 'ready' };
+			}
+			const resumed = resumeInitialized(privacy);
+			if (resumed) {
+				return resumed;
+			}
+			// FR-022, SC-005. Racing callers share one operation.
+			if (state.inFlightInit) {
+				return state.inFlightInit;
+			}
+			if (!canStart(state.init.status)) {
+				return { status: 'ready' };
+			}
+			context.setInit(initReducer(state.init, { type: 'START' }));
+			state.inFlightInit = doInitialize(privacy);
+			return state.inFlightInit;
+		},
+
+		async updatePrivacy(privacy) {
+			if (state.disposed) {
+				// The same answer initialize and load give a disposed instance.
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			if (state.enablement === 'undecided') {
+				return { status: 'undecided' };
+			}
+			if (state.enablement === 'disabled') {
+				return { status: 'disabled' };
+			}
+			if (!engine.isAvailable()) {
+				return { status: 'unavailable', reason: 'unsupported_platform' };
+			}
+			// FR-020: a flag the provider only honors at initialization cannot be
+			// applied now. Say so, rather than accepting it and running half-old.
+			if (requiresReinitialization(state.appliedPrivacy, privacy)) {
+				return { status: 'requires_reinitialization' };
+			}
+
+			state.currentPrivacy = privacy;
+			const gate = evaluateGate(privacy);
+			if (!gate.allowed) {
+				// FR-017, FR-137, FR-153: the same teardown as a consent withdrawal.
+				closeGate(context, { status: 'blocked', reason: gate.reason });
+				return { status: 'blocked', reason: gate.reason };
+			}
+			// FR-019: resolving consent after a block must not initialize twice.
+			if (state.init.status === 'ready') {
+				return { status: 'applied' };
+			}
+			// Exhaustive on purpose (ADS-04): a new InitResult member fails to
+			// compile here instead of falling through to `applied`.
+			const result = await controller.initialize(privacy);
+			switch (result.status) {
+				case 'ready':
+					return { status: 'applied' };
+				case 'blocked':
+				case 'disabled':
+				case 'undecided':
+				case 'unavailable':
+				case 'failed':
+					return result;
+				default: {
+					const unreachable: never = result;
+					return unreachable;
+				}
+			}
+		},
+
+		setEnablement(next) {
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			if (state.enablement === next) {
+				return { status: 'unchanged' };
+			}
+			const previous = state.enablement;
+			state.enablement = next;
+
+			if (next === 'disabled' || next === 'undecided') {
+				// FR-037, FR-125: new work stops and in-flight resources are released;
+				// an ad already on screen is left to finish.
+				closeGate(context, { status: next });
+				if (next === 'undecided') {
+					armUndecidedWarning(context);
+					return { status: 'undecided' };
+				}
+				disarmUndecidedWarning(context);
+				return { status: 'disabled' };
+			}
+
+			// Turning ads on. 0.1.0 dropped the status to `not_started` and returned
+			// nothing, so every later load was refused in silence (FR-121).
+			disarmUndecidedWarning(context);
+			const resumable = canResume(state.init.resumeTo);
+			context.setInit(initReducer(state.init, { type: 'ENABLE' }));
+			const { init } = state;
+			if (init.status === 'unavailable') {
+				return { status: 'unavailable', reason: init.unavailableReason ?? 'unsupported_platform' };
+			}
+			// The provider was never un-initialized, and FR-022 forbids doing it twice.
+			if (init.status === 'ready' && (resumable || previous === 'undecided')) {
+				return { status: 'resumed', initStatus: init.status };
+			}
+			// Said out loud: the package will not hide an asynchronous, billable
+			// initialization behind a setter the caller may not be awaiting.
+			return { status: 'requires_initialization' };
+		},
+
+		/**
+		 * When consent opens the gate and the instance was blocked, it initializes —
+		 * once, because `initialize` shares one in-flight operation (FR-022,
+		 * SC-102). When consent closes it, requests stop, pending retries are
+		 * cancelled (FR-137), and a `ready` instance moves to `blocked` so a banner
+		 * host keyed on `ready` stops requesting (FR-153).
+		 */
+		async reevaluateAfterConsent() {
+			if (state.disposed || !state.currentPrivacy) {
+				return;
+			}
+			const decision = currentGate(context);
+			if (!decision.allowed) {
+				if (decision.kind === 'blocked') {
+					closeGate(context, { status: 'blocked', reason: decision.reason });
+				} else {
+					cancelAllRetries(context);
+				}
+				return;
+			}
+			if (state.init.status === 'ready' || state.init.status === 'initializing') {
+				return;
+			}
+			await controller.initialize(state.currentPrivacy);
+		},
+	};
+	return controller;
+}

package/src/core/instance/internals.ts

@@ -0,0 +1,138 @@
+/**
+ * What `AdsBanner` needs from an instance, held off the public type (ADS-13).
+ *
+ * 0.5.0 exposed this as `AdsInstance.internals`, so any consumer could emit an
+ * `impression` or a `reward_earned` into the stream used for revenue
+ * reconciliation, and every change here was a breaking type change. It now
+ * lives in a WeakMap keyed by the instance: the banner host looks it up, and an
+ * instance an app wrote by hand simply has none.
+ */
+import type { PlacementState } from '../../config/types';
+import { AdsError } from '../../diagnostics/errors';
+import type { AdEvent } from '../../diagnostics/events';
+import type { EngineBanner } from '../../engine/port';
+import { permitsRequests } from '../enablement';
+import { canRequest } from '../initMachine';
+import { toEngineRequest } from '../privacyGate';
+import type { InstanceContext } from './context';
+import { gateRefusal } from './gate';
+import type { AdsInstance, LoadResult, ThrottledResult } from './types';
+
+export interface InstanceInternals {
+	/**
+	 * Whether a banner for this placement may request now, and with what. Pure:
+	 * it mints nothing, so the host can call it during render (ADS-20).
+	 */
+	resolveBanner(placementKey: string):
+		| {
+				readonly ok: true;
+				readonly adUnitId: string;
+				/** Current at resolution time, so a banner request honors `updatePrivacy`. */
+				readonly personalizedAds: boolean;
+		  }
+		| { readonly ok: false; readonly result: LoadResult };
+	/**
+	 * Takes the throttle slot for a banner mount (FR-140).
+	 *
+	 * Called during render, immediately before the provider component mounts:
+	 * that component requests as part of the same render, so an effect would be
+	 * too late. Idempotent for one `token`, so a render that runs twice charges
+	 * one slot. Emits nothing and sets no state; the host reports a refusal from
+	 * its effect.
+	 */
+	commitBannerRequest(placementKey: string, token: string): ThrottledResult | null;
+	/** The configured floor for a placement, so the host can report the cause. */
+	throttleFloorFor(placementKey: string): number;
+	/** The engine's banner when it can render here, or null (ADS-12). */
+	banner(): EngineBanner | null;
+	emit(event: AdEvent): void;
+	setPlacementState(key: string, state: PlacementState): void;
+	isReady(): boolean;
+	nextCorrelationId(): string;
+	/** The instance's clock, so banner events and full-screen events agree (ADS-20). */
+	now(): number;
+	/**
+	 * Runs `task` after `delayMs` on the instance's timers, so a test clock drives
+	 * it and dispose() cancels it. Returns a cancel.
+	 */
+	schedule(delayMs: number, task: () => void): () => void;
+	timerCount(): number;
+}
+
+const registry = new WeakMap<AdsInstance, InstanceInternals>();
+
+/** The banner host's view of an instance `createAds` made; null for any other. */
+export function getInternals(instance: AdsInstance): InstanceInternals | null {
+	return registry.get(instance) ?? null;
+}
+
+export function attachInternals(instance: AdsInstance, internals: InstanceInternals): void {
+	registry.set(instance, internals);
+}
+
+export function createInternals(context: InstanceContext): InstanceInternals {
+	const { state, engine, resolved, events, timers, requestThrottle, now } = context;
+	return {
+		resolveBanner(placementKey) {
+			const definition = resolved.placements.get(placementKey);
+			if (!definition || definition.format !== 'banner') {
+				const code = definition ? 'format_mismatch' : 'placement_not_found';
+				return {
+					ok: false,
+					result: {
+						status: 'failed',
+						error: new AdsError(code, {
+							operation: 'load',
+							placementKey,
+							format: definition?.format,
+							message: definition
+								? `"${placementKey}" is not a banner placement`
+								: `unknown placement "${placementKey}"`,
+						}),
+					},
+				};
+			}
+			const refusal = gateRefusal(context);
+			if (refusal) {
+				return { ok: false, result: refusal };
+			}
+			if (!canRequest(state.init.status)) {
+				return { ok: false, result: { status: 'blocked', reason: 'consent_required' } };
+			}
+			// The throttle is deliberately not consulted here: a fresh mount must be
+			// throttled while a width re-adaptation of a mounted banner must not be,
+			// and only the host knows which it is (FR-140).
+			return {
+				ok: true,
+				adUnitId: resolved.catalog.byKey.get(placementKey) ?? '',
+				personalizedAds: toEngineRequest(state.currentPrivacy).personalizedAds,
+			};
+		},
+		commitBannerRequest(placementKey, token) {
+			if (!resolved.placements.has(placementKey)) {
+				return null;
+			}
+			const decision = requestThrottle.tryAcquire(
+				placementKey,
+				resolved.minRequestIntervalByKey.get(placementKey) ?? 0,
+				token,
+			);
+			return decision.allowed ? null : { status: 'throttled', retryAfterMs: decision.retryAfterMs };
+		},
+		throttleFloorFor: placementKey => resolved.minRequestIntervalByKey.get(placementKey) ?? 0,
+		banner: () => (engine.banner?.isAvailable() ? engine.banner : null),
+		emit: event => events.emit(event),
+		setPlacementState(key, next) {
+			const runtime = context.placements.get(key);
+			if (runtime) {
+				context.setPlacement(key, { ...runtime.snapshot, state: next });
+			}
+		},
+		isReady: () =>
+			permitsRequests(state.enablement) && engine.isAvailable() && canRequest(state.init.status),
+		nextCorrelationId: () => context.correlation.next(),
+		now,
+		schedule: (delayMs, task) => timers.after(delayMs, task),
+		timerCount: () => timers.size(),
+	};
+}