@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/src/core/consentFlow.ts

@@ -27,7 +27,7 @@
 
 import type { ConsentSnapshot, ConsentState, ConsentTestingOptions } from '../config/types';
 import { AdsError } from '../diagnostics/errors';
-import type { ConsentPort, EngineConsentInfo, EngineConsentOptions } from '../engine/port';
+import type { EngineConsentInfo, EngineConsentOptions } from '../engine/port';
 import type { ConsentGateInput } from './gates';
 
 export const INITIAL_CONSENT: ConsentSnapshot = {
@@ -161,22 +161,3 @@ export function needsForm(snapshot: ConsentSnapshot): boolean {
 		snapshot.isFormAvailable && (snapshot.state === 'required' || snapshot.state === 'undetermined')
 	);
 }
-
-export function createConsentPortGuard(port: ConsentPort | undefined): ConsentPort {
-	if (port) {
-		return port;
-	}
-	// An engine without a consent port cannot serve the capability. Reporting it
-	// as a normalized failure keeps FR-108 true — the app does not crash, it
-	// learns the flow is unavailable and can fall back to its own gate.
-	const unavailable = async (): Promise<EngineConsentInfo> => {
-		throw new Error('provider_missing');
-	};
-	return {
-		requestInfoUpdate: unavailable,
-		showFormIfRequired: unavailable,
-		showPrivacyOptionsForm: unavailable,
-		getInfo: unavailable,
-		reset: () => undefined,
-	};
-}

package/src/core/instance/consent.ts

@@ -0,0 +1,162 @@
+/**
+ * The optional consent capability (FR-101 – FR-113, FR-150 – FR-157).
+ *
+ * Every outcome feeds the gate through `reevaluate`, so the app never wires
+ * consent to requests by hand (FR-105), and a failure is never a grant
+ * (FR-106).
+ */
+import type { ConsentSnapshot } from '../../config/types';
+import type { AdsError } from '../../diagnostics/errors';
+import {
+	buildConsentOptions,
+	INITIAL_CONSENT,
+	needsForm,
+	normalizeConsent,
+	runConsentStep,
+	toConsentError,
+} from '../consentFlow';
+import type { InstanceContext } from './context';
+import type { ConsentApi } from './types';
+
+export function createConsentApi(
+	context: InstanceContext,
+	reevaluate: () => Promise<void>,
+): ConsentApi {
+	const { state, engine, resolved } = context;
+
+	/** Applies an outcome unless the instance went away while it was pending. */
+	async function settle(next: ConsentSnapshot): Promise<ConsentSnapshot> {
+		if (state.disposed) {
+			return state.consent;
+		}
+		context.setConsent(next);
+		await reevaluate();
+		return next;
+	}
+
+	return {
+		async requestInfoUpdate() {
+			if (state.disposed) {
+				return state.consent;
+			}
+			// Marks the flow as in use. Until this is called the gate sees no consent
+			// input at all, which is how an app that supplies its own gate keeps
+			// 0.1.0 behavior without opting out of anything (FR-102).
+			state.consentStarted = true;
+			if (resolved.consentTesting?.resetOnStart) {
+				try {
+					engine.consent.reset();
+				} catch {
+					// A failed reset must not abort the update; the flow continues
+					// against whatever state is stored.
+				}
+			}
+			const next = await runConsentStep(
+				() =>
+					engine.consent.requestInfoUpdate(
+						buildConsentOptions(
+							resolved.consentTesting,
+							state.currentPrivacy?.underAgeOfConsent,
+							resolved.testDeviceIds,
+						),
+					),
+				'consent information update failed',
+			);
+			return settle(next);
+		},
+
+		async showFormIfRequired() {
+			if (state.disposed) {
+				return state.consent;
+			}
+			state.consentStarted = true;
+			// Nothing to present is not an error: a region that does not require
+			// consent is the normal case (FR-107). Nor is a privacy options form
+			// already on screen — one provider form at a time.
+			if (!needsForm(state.consent) || state.privacyOptionsFormOpen) {
+				return state.consent;
+			}
+			state.consentFormsOpen += 1;
+			let next: ConsentSnapshot;
+			try {
+				next = await runConsentStep(
+					() => engine.consent.showFormIfRequired(),
+					'consent form failed',
+				);
+			} finally {
+				state.consentFormsOpen -= 1;
+			}
+			return settle(next);
+		},
+
+		async showPrivacyOptionsForm() {
+			// The refusals, most immovable first — the same reading order as the
+			// request gates, so the answer is the most useful one.
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			if (!engine.isAvailable()) {
+				return { status: 'unavailable', reason: 'unsupported_platform' };
+			}
+			if (state.privacyOptionsFormOpen || state.consentFormsOpen > 0) {
+				return { status: 'busy' };
+			}
+			if (state.consent.privacyOptionsRequirement === 'unknown') {
+				return { status: 'info_update_required' };
+			}
+			if (state.consent.privacyOptionsRequirement !== 'required') {
+				// The provider's verdict, not a region guess of ours (FR-150).
+				return { status: 'not_required' };
+			}
+
+			state.privacyOptionsFormOpen = true;
+			let next: ConsentSnapshot;
+			let failure: AdsError | null = null;
+			try {
+				next = normalizeConsent(await engine.consent.showPrivacyOptionsForm());
+			} catch (cause) {
+				failure = toConsentError(cause, 'privacy options form failed');
+				// The form did not complete, so the stored decision is the provider's
+				// to report — ask rather than assume. Collapsing to `error` the way a
+				// failed first-time form does would revoke a consent the user never
+				// changed. If the provider cannot answer either, the gate closes: a
+				// failure is never consent (FR-106).
+				next = state.disposed
+					? state.consent
+					: await runConsentStep(
+							() => engine.consent.getInfo(),
+							'consent information could not be read after the privacy options form failed',
+						);
+			} finally {
+				state.privacyOptionsFormOpen = false;
+			}
+			// dispose() during the form: the form stays until the user closes it, but
+			// its outcome reaches nobody (FR-157).
+			if (state.disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			await settle(next);
+			return failure ? { status: 'failed', error: failure } : { status: 'shown', consent: next };
+		},
+
+		getState() {
+			return state.consent;
+		},
+
+		subscribe: listener => context.consentListeners.add(listener),
+
+		async reset() {
+			// Config validation strips the testing tools in production, so this is
+			// inert there without a check here (FR-113).
+			if (state.disposed || !resolved.consentTesting) {
+				return;
+			}
+			try {
+				engine.consent.reset();
+			} catch {
+				// The stored state is the provider's; a failed reset leaves it as it was.
+			}
+			context.setConsent(INITIAL_CONSENT);
+		},
+	};
+}

package/src/core/instance/context.ts

@@ -0,0 +1,328 @@
+/**
+ * What every part of an ads instance shares (ADS-10).
+ *
+ * 0.5.0 kept all of this as `let` bindings inside one 1,500-line closure, and
+ * each path that closed a gate re-implemented its own teardown — which is how
+ * ADS-01, ADS-02 and ADS-04 happened. Here the state is one object, the
+ * placement runtimes are one map, and the helpers that change them are defined
+ * once. The controllers (gate, init, load, show, consent, banner) each take this
+ * context and nothing else.
+ */
+import {
+	createListenerSet,
+	isDevBuild as detectDevBuild,
+	type ListenerSet,
+} from '@chipmobilesdk/rn-core';
+
+import {
+	type AdFormat,
+	type AdsConfig,
+	type ConsentSnapshot,
+	type Enablement,
+	type InitStatus,
+	type PlacementDefinition,
+	type PlacementState,
+	type PrivacyOptions,
+	type Unsubscribe,
+} from '../../config/types';
+import { validateConfig, type ResolvedConfig } from '../../config/validate';
+import { createCorrelationIssuer, type CorrelationIssuer } from '../../diagnostics/correlation';
+import { AdsError } from '../../diagnostics/errors';
+import { createEventEmitter, type AdEventEmitter } from '../../diagnostics/events';
+import type { AdsEngine, EngineAdHandle } from '../../engine/port';
+import { createAdOriginatedTracker, type AdOriginatedTracker } from '../adOriginatedReturn';
+import { INITIAL_CONSENT } from '../consentFlow';
+import { createFullScreenLock, type FullScreenLock } from '../fullScreenLock';
+import { initialInit, initReducer, type InitSnapshot } from '../initMachine';
+import { initialPlacement, placementReducer, type PlacementSnapshot } from '../placementMachine';
+import { createRequestThrottle, type RequestThrottle } from '../requestThrottle';
+import type { RewardedSession } from '../rewardedSession';
+import { createTimerSet, type TimerSet } from '../timers';
+import type { CreateAdsOptions, InitResult, LoadRefusal, LoadResult } from './types';
+
+export interface PlacementRuntime {
+	snapshot: PlacementSnapshot;
+	/**
+	 * The cycle's correlation id, held here rather than read from the snapshot:
+	 * the reducer resets the snapshot on dismissal, and events emitted around
+	 * that transition must still carry the id of the cycle they belong to.
+	 */
+	correlationId: string | null;
+	/**
+	 * Whether this cycle already reported a dismissal. Format-independent — the
+	 * rewarded session guards its own, but interstitials need the same guard and
+	 * would otherwise report a repeated provider callback twice.
+	 */
+	dismissed: boolean;
+	handle: EngineAdHandle | null;
+	unsubscribeEngine: Unsubscribe | null;
+	inFlightLoad: Promise<LoadResult> | null;
+	/**
+	 * Settles the in-flight load with a given result. Only a gate closing uses it
+	 * (FR-153): the caller awaiting `load()` is told the refusal instead of
+	 * waiting on a request that has been abandoned.
+	 */
+	abortLoad: ((result: LoadResult) => void) | null;
+	cancelLoadTimer: Unsubscribe | null;
+	cancelShowTimer: Unsubscribe | null;
+	rewarded: RewardedSession | null;
+	listeners: ListenerSet<[PlacementState]>;
+	/** Retries already spent in this load cycle. Reset when a new cycle starts. */
+	retryAttempts: number;
+	/** Cancels a scheduled retry. Called by disable, undecided, and dispose. */
+	cancelRetry: Unsubscribe | null;
+}
+
+/** Everything about the instance that changes after creation. */
+export interface InstanceState {
+	init: InitSnapshot;
+	enablement: Enablement;
+	appActive: boolean;
+	consent: ConsentSnapshot;
+	/** Whether the app ever used the consent flow; until then the gate ignores it (FR-102). */
+	consentStarted: boolean;
+	/**
+	 * Consent forms currently on screen. A count rather than a flag because
+	 * `showFormIfRequired` has never refused a concurrent call; only the privacy
+	 * options form reads it, to report `busy`.
+	 */
+	consentFormsOpen: number;
+	privacyOptionsFormOpen: boolean;
+	/**
+	 * Whether the provider has been natively initialized, ever, by this instance.
+	 *
+	 * Tracked apart from the init status because the status can leave `ready` —
+	 * a withdrawn consent moves it to `blocked` — while the native SDK stays
+	 * initialized. Re-granting must resume, not initialize again (FR-022, FR-154).
+	 */
+	providerInitialized: boolean;
+	undecidedWarned: boolean;
+	cancelUndecidedTimer: Unsubscribe | null;
+	appliedPrivacy: PrivacyOptions | null;
+	currentPrivacy: PrivacyOptions | null;
+	inFlightInit: Promise<InitResult> | null;
+	disposed: boolean;
+	warnedSubstitution: boolean;
+}
+
+export interface InstanceContext {
+	readonly resolved: ResolvedConfig;
+	readonly engine: AdsEngine;
+	readonly now: () => number;
+	readonly events: AdEventEmitter;
+	readonly correlation: CorrelationIssuer;
+	/** FR-140. Account safety, not product policy — see core/requestThrottle.ts. */
+	readonly requestThrottle: RequestThrottle;
+	readonly timers: TimerSet;
+	readonly lock: FullScreenLock;
+	readonly adReturn: AdOriginatedTracker;
+	readonly state: InstanceState;
+	readonly placements: ReadonlyMap<string, PlacementRuntime>;
+	readonly statusListeners: ListenerSet<[InitStatus]>;
+	readonly consentListeners: ListenerSet<[ConsentSnapshot]>;
+	/** A placement's runtime and definition together, or null for an unknown key (ADS-18). */
+	placement(key: string): { runtime: PlacementRuntime; definition: PlacementDefinition } | null;
+	setInit(next: InitSnapshot): void;
+	setPlacement(key: string, next: PlacementSnapshot): void;
+	dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void;
+	setConsent(next: ConsentSnapshot): void;
+	releasePlacementResources(key: string): void;
+	emitRefusal(
+		operation: 'initialize' | 'load' | 'show',
+		result: LoadRefusal,
+		placementKey?: string,
+		format?: AdFormat,
+	): void;
+}
+
+export function createInstanceContext(
+	config: AdsConfig,
+	options: CreateAdsOptions,
+	defaultEngine: () => AdsEngine,
+): InstanceContext {
+	const isDevBuild = options.isDevBuild ?? detectDevBuild();
+	const now = options.now ?? (() => Date.now());
+
+	// Throws on a structural fault or the FR-012 fail-closed case. Deliberately
+	// before anything else: a misconfigured instance should not exist at all.
+	const resolved = validateConfig(config, { isDevBuild });
+	const engine = options.engine ?? defaultEngine();
+	const events = createEventEmitter();
+
+	/**
+	 * Status, consent and placement listeners are consumer code. A failure is
+	 * isolated from the rest and reported the way an event listener's is: as an
+	 * `internal_error` event (FR-056).
+	 */
+	const listenerOptions = {
+		onListenerError(error: unknown) {
+			events.emit({
+				type: 'internal_error',
+				timestamp: now(),
+				error: new AdsError('internal_error', { message: 'consumer listener threw', cause: error }),
+			});
+		},
+	};
+
+	const placements = new Map<string, PlacementRuntime>();
+	for (const key of resolved.placements.keys()) {
+		placements.set(key, {
+			snapshot: initialPlacement,
+			correlationId: null,
+			dismissed: false,
+			handle: null,
+			unsubscribeEngine: null,
+			inFlightLoad: null,
+			abortLoad: null,
+			cancelLoadTimer: null,
+			cancelShowTimer: null,
+			rewarded: null,
+			listeners: createListenerSet(listenerOptions),
+			retryAttempts: 0,
+			cancelRetry: null,
+		});
+	}
+
+	const state: InstanceState = {
+		/**
+		 * An instance told it is `undecided` says so from the moment it exists, or
+		 * it would report `not_started` until `initialize()` runs — which looks like
+		 * a disabled instance at exactly the point an app decides whether to reserve
+		 * the banner's space (FR-116). `disabled` keeps 0.1.0's `not_started`
+		 * (BC-004).
+		 */
+		init:
+			resolved.enablement === 'undecided'
+				? initReducer(initialInit, { type: 'UNDECIDE' })
+				: initialInit,
+		enablement: resolved.enablement,
+		appActive: true,
+		consent: INITIAL_CONSENT,
+		consentStarted: false,
+		consentFormsOpen: 0,
+		privacyOptionsFormOpen: false,
+		providerInitialized: false,
+		undecidedWarned: false,
+		cancelUndecidedTimer: null,
+		appliedPrivacy: null,
+		currentPrivacy: null,
+		inFlightInit: null,
+		disposed: false,
+		warnedSubstitution: false,
+	};
+
+	const statusListeners = createListenerSet<[InitStatus]>(listenerOptions);
+	const consentListeners = createListenerSet<[ConsentSnapshot]>(listenerOptions);
+
+	const context: InstanceContext = {
+		resolved,
+		engine,
+		now,
+		events,
+		correlation: createCorrelationIssuer(),
+		requestThrottle: createRequestThrottle(now),
+		timers: createTimerSet(options.scheduler),
+		lock: createFullScreenLock(),
+		adReturn: createAdOriginatedTracker(),
+		state,
+		placements,
+		statusListeners,
+		consentListeners,
+
+		placement(key) {
+			const runtime = placements.get(key);
+			const definition = resolved.placements.get(key);
+			return runtime && definition ? { runtime, definition } : null;
+		},
+
+		setInit(next) {
+			const previous = state.init;
+			state.init = next;
+			if (next === previous || next.status === previous.status) {
+				return;
+			}
+			events.emit({
+				type: 'initialization',
+				timestamp: now(),
+				status: next.status,
+				retryable: next.error?.retryable,
+			});
+			statusListeners.notify(next.status);
+		},
+
+		setPlacement(key, next) {
+			const runtime = placements.get(key);
+			if (!runtime) {
+				return;
+			}
+			const changed = runtime.snapshot.state !== next.state;
+			runtime.snapshot = next;
+			if (changed) {
+				runtime.listeners.notify(next.state);
+			}
+		},
+
+		dispatchPlacement(key, event) {
+			const found = context.placement(key);
+			if (found) {
+				context.setPlacement(
+					key,
+					placementReducer(found.runtime.snapshot, event, found.definition.format),
+				);
+			}
+		},
+
+		setConsent(next) {
+			state.consent = next;
+			consentListeners.notify(next);
+		},
+
+		releasePlacementResources(key) {
+			const runtime = placements.get(key);
+			if (!runtime) {
+				return;
+			}
+			runtime.cancelLoadTimer?.();
+			runtime.cancelLoadTimer = null;
+			runtime.cancelShowTimer?.();
+			runtime.cancelShowTimer = null;
+			runtime.unsubscribeEngine?.();
+			runtime.unsubscribeEngine = null;
+			if (runtime.handle) {
+				engine.dispose(runtime.handle);
+				runtime.handle = null;
+			}
+			runtime.inFlightLoad = null;
+			runtime.abortLoad = null;
+			runtime.rewarded = null;
+			runtime.cancelRetry?.();
+			runtime.cancelRetry = null;
+		},
+
+		emitRefusal(operation, result, placementKey, format) {
+			if (result.status === 'disabled' || result.status === 'undecided') {
+				// `undecided` reuses the `disabled` event: for an observer of the
+				// stream the fact is the same — no request was made — and the
+				// distinction is carried by the typed result and the init status.
+				events.emit({ type: 'disabled', timestamp: now(), operation, placementKey, format });
+				return;
+			}
+			events.emit({
+				type: 'unavailable',
+				timestamp: now(),
+				operation,
+				placementKey,
+				format,
+				reason: result.reason,
+			});
+		},
+	};
+	return context;
+}
+
+/** App-open expires on its own, shorter window (FR-130). */
+export function validityFor(context: InstanceContext, format: AdFormat): number {
+	return format === 'app_open'
+		? context.resolved.timeouts.appOpenValidity
+		: context.resolved.timeouts.adValidity;
+}

package/src/core/instance/gate.ts

@@ -0,0 +1,147 @@
+/**
+ * The request gate, evaluated in one place, and closed in one place (FR-140,
+ * ADS-10).
+ *
+ * Every path that closes the gate — ads turned off or undecided, the app's
+ * privacy input withdrawn, the consent flow withdrawn — goes through
+ * `closeGate`. In 0.5.0 each of those paths wrote its own teardown, and the one
+ * that forgot to cancel retries let a request reach the provider after consent
+ * was withdrawn (ADS-02).
+ */
+import { toGateInput } from '../consentFlow';
+import { evaluateGates, type GateDecision } from '../gates';
+import { initReducer } from '../initMachine';
+import { evaluateGate } from '../privacyGate';
+import type { InstanceContext } from './context';
+import type { LoadRefusal } from './types';
+
+/**
+ * Assembles the gate's inputs and defers the precedence entirely to
+ * `evaluateGates`: availability, then enablement, then the app's privacy input,
+ * then the consent flow. Nothing else compares gate state.
+ *
+ * The consent flow contributes `null` until the app opts into it, which is what
+ * makes FR-102 structural: with no flow started the gate sees only the app's
+ * own input and behaves exactly as 0.1.0 did.
+ */
+export function currentGate(context: InstanceContext): GateDecision {
+	const { engine, state } = context;
+	const appGate = evaluateGate(state.currentPrivacy);
+	return evaluateGates({
+		available: engine.isAvailable() ? { ok: true } : { ok: false, reason: 'unsupported_platform' },
+		enablement: state.enablement,
+		appGate: appGate.allowed ? { permitted: true } : { permitted: false, reason: appGate.reason },
+		consentGate: state.consentStarted ? toGateInput(state.consent) : null,
+	});
+}
+
+/** Maps a closed gate onto the refusal shape load, show, and the banner share. */
+export function refusalFor(decision: Extract<GateDecision, { allowed: false }>): LoadRefusal {
+	switch (decision.kind) {
+		case 'unavailable':
+			return { status: 'unavailable', reason: decision.reason };
+		case 'disabled':
+			return { status: 'disabled' };
+		case 'undecided':
+			return { status: 'undecided' };
+		default:
+			return { status: 'blocked', reason: decision.reason };
+	}
+}
+
+/** The refusal that applies now, or null when a request may go ahead. */
+export function gateRefusal(context: InstanceContext): LoadRefusal | null {
+	const decision = currentGate(context);
+	return decision.allowed ? null : refusalFor(decision);
+}
+
+/** Cancels every pending retry, everywhere (FR-137). */
+export function cancelAllRetries(context: InstanceContext): void {
+	for (const runtime of context.placements.values()) {
+		runtime.cancelRetry?.();
+		runtime.cancelRetry = null;
+	}
+}
+
+/**
+ * Stops every request a gate that just closed forbids (FR-125, FR-153, FR-159).
+ *
+ * In-flight loads are abandoned and their resources released, a loaded ad that
+ * may no longer be shown is released with them, and an ad already on screen is
+ * left alone — the provider offers no safe way to close it.
+ *
+ * An abandoned load *settles*: its caller gets `refusal`, the same answer a load
+ * started now would get, and a handle the provider hands back afterwards is
+ * disposed rather than adopted.
+ */
+function haltPlacements(context: InstanceContext, refusal: LoadRefusal): void {
+	for (const [key, runtime] of context.placements) {
+		if (runtime.snapshot.state === 'showing') {
+			continue;
+		}
+		const abort = runtime.abortLoad;
+		context.releasePlacementResources(key);
+		context.dispatchPlacement(key, { type: 'RESET' });
+		if (abort) {
+			context.emitRefusal('load', refusal, key, context.resolved.placements.get(key)?.format);
+			abort(refusal);
+		}
+	}
+}
+
+/**
+ * The one teardown for a gate that closed to `refusal`: retries cancelled,
+ * placements halted, and the init status moved to match.
+ */
+export function closeGate(
+	context: InstanceContext,
+	refusal: Exclude<LoadRefusal, { status: 'unavailable' }>,
+): void {
+	cancelAllRetries(context);
+	haltPlacements(context, refusal);
+	const { init } = context.state;
+	switch (refusal.status) {
+		case 'disabled':
+			context.setInit(initReducer(init, { type: 'DISABLE' }));
+			return;
+		case 'undecided':
+			context.setInit(initReducer(init, { type: 'UNDECIDE' }));
+			return;
+		default:
+			context.setInit(initReducer(init, { type: 'BLOCK', reason: refusal.reason }));
+	}
+}
+
+/**
+ * Warns once if the app leaves `undecided` unresolved (FR-119).
+ *
+ * Once, not repeatedly: a warning that fires every ten seconds becomes noise.
+ * And it only warns — resolving the state would mean guessing the business
+ * decision FR-120 forbids the package from knowing.
+ */
+export function armUndecidedWarning(context: InstanceContext): void {
+	const { state, timers, resolved, events, now } = context;
+	if (state.enablement !== 'undecided' || state.undecidedWarned || state.cancelUndecidedTimer) {
+		return;
+	}
+	const armedAt = now();
+	state.cancelUndecidedTimer = timers.after(resolved.timeouts.undecidedWarning, () => {
+		state.cancelUndecidedTimer = null;
+		if (state.disposed || state.enablement !== 'undecided' || state.undecidedWarned) {
+			return;
+		}
+		state.undecidedWarned = true;
+		events.emit({
+			type: 'config_warning',
+			timestamp: now(),
+			warning: 'enablement_undecided_timeout',
+			placementKeys: [],
+			elapsedMs: now() - armedAt,
+		});
+	});
+}
+
+export function disarmUndecidedWarning(context: InstanceContext): void {
+	context.state.cancelUndecidedTimer?.();
+	context.state.cancelUndecidedTimer = null;
+}