@chipmobilesdk/rn-ads 0.1.0 → 0.2.1

package/src/core/consentFlow.ts

@@ -0,0 +1,167 @@
+/**
+ * Consent orchestration and normalization (FR-101 – FR-110).
+ *
+ * This closes the most serious gap in 0.1.0. The package *consumed* a consent
+ * decision but nothing *produced* one, and the flow that produces it lives
+ * inside the very provider library the package promised an app would never have
+ * to import. So any app shipping to a consent-required region had to import the
+ * provider directly — breaking the package's central promise at exactly the
+ * point where it mattered most — and hand-write the same order-sensitive
+ * orchestration every other such app was also writing.
+ *
+ * What this module does **not** do is as load-bearing as what it does:
+ *
+ *   - It renders no consent UI. The form is the provider's (FR-103).
+ *   - It decides nothing about jurisdictions. Which regions require consent is
+ *     the provider's answer and the publisher's console configuration; the
+ *     package forwards it (FR-107).
+ *   - It never infers consent. An error, a cancellation, a dismissed form, a
+ *     network failure — all of them land on `error`, and `error` never carries
+ *     permission (FR-106). This is the invariant the whole module exists to
+ *     protect, because the failure it prevents is invisible: a request that
+ *     should not have happened looks exactly like one that should.
+ *
+ * Pure apart from the port calls it awaits. No React, no provider type crossing
+ * outward.
+ */
+
+import type { ConsentSnapshot, ConsentState, ConsentTestingOptions } from '../config/types';
+import { AdsError } from '../diagnostics/errors';
+import type { ConsentPort, EngineConsentInfo, EngineConsentOptions } from '../engine/port';
+import type { ConsentGateInput } from './gates';
+
+export const INITIAL_CONSENT: ConsentSnapshot = {
+	state: 'undetermined',
+	canRequestAds: false,
+	isFormAvailable: false,
+	error: null,
+};
+
+/**
+ * Maps the engine's status onto the published one.
+ *
+ * `canRequestAds` is taken from the provider rather than derived from the
+ * status. The two are not the same question — a region can be `not_required`
+ * while the provider still withholds permission — and inventing the second
+ * answer from the first is how a package ends up requesting ads it should not.
+ */
+export function normalizeConsent(info: EngineConsentInfo): ConsentSnapshot {
+	const state: ConsentState =
+		info.status === 'obtained'
+			? 'obtained'
+			: info.status === 'required'
+				? 'required'
+				: info.status === 'not_required'
+					? 'not_required'
+					: 'undetermined';
+
+	return {
+		state,
+		canRequestAds: info.canRequestAds === true,
+		isFormAvailable: info.isFormAvailable === true,
+		error: null,
+	};
+}
+
+/**
+ * The snapshot for a failed flow.
+ *
+ * `canRequestAds` is hard-coded false rather than carried through from anywhere.
+ * 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.
+ */
+export function consentFailure(error: AdsError): ConsentSnapshot {
+	return { state: 'error', canRequestAds: false, isFormAvailable: false, error };
+}
+
+export function toConsentError(cause: unknown, message: string): AdsError {
+	return new AdsError('consent_flow_failed', {
+		message,
+		operation: 'configure',
+		cause,
+	});
+}
+
+/**
+ * Projects a snapshot onto the consent gate's second input.
+ *
+ * Only `obtained` and `not_required` open it. `undetermined` and `required` are
+ * both "we do not have permission yet" and are reported as
+ * `consent_flow_required`; `error` gets its own reason so an app can tell a
+ * user who has not answered from a flow that broke.
+ */
+export function toGateInput(snapshot: ConsentSnapshot): ConsentGateInput {
+	if (snapshot.canRequestAds && (snapshot.state === 'obtained' || snapshot.state === 'not_required')) {
+		return { permitted: true };
+	}
+	return {
+		permitted: false,
+		reason: snapshot.state === 'error' ? 'consent_flow_error' : 'consent_flow_required',
+	};
+}
+
+/**
+ * Builds the options for a consent information update.
+ *
+ * `testing` has already been stripped by config validation when the environment
+ * is production, so this function does not re-check. That is deliberate: the
+ * guarantee lives at one point rather than being re-asserted at each call site,
+ * which is the same reason the ad-unit substitution guarantee is provable
+ * (FR-113).
+ */
+export function buildConsentOptions(
+	testing: ConsentTestingOptions | undefined,
+	underAgeOfConsent: boolean | undefined,
+	testDeviceIds: readonly string[],
+): EngineConsentOptions {
+	return {
+		debugGeography: testing?.debugGeography,
+		underAgeOfConsent,
+		testDeviceIds,
+	};
+}
+
+/**
+ * One consent operation, with the never-infer rule applied to every exit.
+ *
+ * Every path out of here is either a normalized snapshot or a normalized error
+ * snapshot. Nothing throws, because a consent failure must not be able to block
+ * app startup or crash the host (FR-108).
+ */
+export async function runConsentStep(
+	step: () => Promise<EngineConsentInfo>,
+	failureMessage: string,
+): Promise<ConsentSnapshot> {
+	try {
+		return normalizeConsent(await step());
+	} catch (cause) {
+		return consentFailure(toConsentError(cause, failureMessage));
+	}
+}
+
+/** Whether a form should be presented, per the provider's own report. */
+export function needsForm(snapshot: ConsentSnapshot): boolean {
+	return (
+		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,
+		getInfo: unavailable,
+		reset: () => undefined,
+	};
+}

package/src/core/enablement.ts

@@ -0,0 +1,76 @@
+/**
+ * Three-state enablement and the typed result of changing it (FR-114 – FR-125).
+ *
+ * 0.1.0 had a boolean, which forced an app selling an ad-removal tier to lie at
+ * startup. It does not yet know whether this user has paid — that answer arrives
+ * after a store sync — and both available answers are wrong: `true` flashes ads
+ * at someone who paid to never see them, `false` delays ads for everyone else
+ * and then runs into the silent re-enable trap below. The missing third state
+ * was a hole in the contract, not an omission in the app.
+ *
+ * The package still knows nothing about payments, entitlements, or why the app
+ * decided anything (FR-120). It only stops insisting the decision already exists
+ * at construction time.
+ *
+ * Pure — no provider, no React, no I/O.
+ */
+
+import type { Enablement, InitStatus, UnavailableReason } from '../config/types';
+
+/**
+ * Normalizes the configured value. `true`/`false` keep their exact 0.1.0
+ * meaning, which is what makes the widened config type additive (BC-003).
+ */
+export function toEnablement(value: boolean | 'undecided'): Enablement {
+	if (value === 'undecided') {
+		return 'undecided';
+	}
+	return value ? 'enabled' : 'disabled';
+}
+
+/** Neither `disabled` nor `undecided` may reach the provider (FR-115). */
+export function permitsRequests(enablement: Enablement): boolean {
+	return enablement === 'enabled';
+}
+
+/**
+ * The outcome of an enablement change.
+ *
+ * 0.1.0 returned `void`, which is the defect FR-122 supersedes. Re-enabling
+ * after a disable sent the init status back to `not_started`, so the app *had*
+ * to call `initialize()` again or every later load and show was refused — and
+ * nothing said so. Not the result, not the status, not the documentation. An app
+ * whose user's subscription lapsed would turn ads back on and silently show
+ * none.
+ */
+export type EnablementResult =
+	/**
+	 * Returned to the status held before disabling, with zero provider calls.
+	 * The common case: disabling never un-initializes the provider, so there is
+	 * genuinely nothing to redo.
+	 */
+	| { readonly status: 'resumed'; readonly initStatus: InitStatus }
+	/**
+	 * The instance never reached `ready`, privacy options changed, or the
+	 * platform became unavailable. The caller must initialize; the package will
+	 * not do it implicitly, because that would hide an asynchronous, billable
+	 * operation behind a setter the caller may not be awaiting (FR-121).
+	 */
+	| { readonly status: 'requires_initialization' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	/** The requested state was already the current one. No work, no event. */
+	| { readonly status: 'unchanged' }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+
+/**
+ * Whether re-enabling can resume, given what the instance was doing when it was
+ * turned off.
+ *
+ * Only `ready` resumes. Everything else — never started, still initializing,
+ * blocked, failed — has no completed initialization to return to, so claiming a
+ * resume would put the instance in a state it never actually reached.
+ */
+export function canResume(resumeTo: InitStatus | null): resumeTo is 'ready' {
+	return resumeTo === 'ready';
+}

package/src/core/gates.ts

@@ -0,0 +1,91 @@
+/**
+ * The one place that decides why a request was refused (FR-140, FR-141).
+ *
+ * After 0.2.0 there are three independent ways to be blocked — platform
+ * availability, the app's three-state enable flag, and consent — and they can be
+ * closed in any combination. A precedence spread across four call sites is not a
+ * precedence; it is four coincidences that currently agree. So every refusal
+ * path in the package routes through `evaluateGates` and nothing else compares
+ * gate state.
+ *
+ * **The order is availability, then enablement, then consent — most immovable
+ * first.** Two reasons, and they agree:
+ *
+ * 1. It is what 0.1.0 already did. `initMachine`'s BLOCK transition is refused
+ *    outright when the status is `disabled` or `unavailable`, so consent was
+ *    already the weakest of the three. Any other order would change observable
+ *    behavior for a consumer who configured nothing new.
+ * 2. It is the most useful order for whoever is debugging. An unsupported
+ *    platform makes the other two unfixable, so reporting "consent required" on
+ *    a platform that can never serve an ad sends a developer off to build a flow
+ *    that will never help. Reporting `unavailable` to an app that has also
+ *    disabled ads costs nothing — that app was not going to show an ad either
+ *    way.
+ *
+ * The accepted cost is that an app which *deliberately* disabled ads on an
+ * unsupported platform is told about the platform rather than about its own
+ * switch. That is fine: neither answer changes what the app does next.
+ *
+ * Pure. No provider, no React, no I/O — which is what lets the full combination
+ * table be a unit test rather than an integration one.
+ */
+
+import type { Enablement, PrivacyBlockReason, UnavailableReason } from '../config/types';
+
+/** What the consent flow contributes, or `null` when the app never opted in. */
+export type ConsentGateInput =
+	| { readonly permitted: true }
+	| { readonly permitted: false; readonly reason: 'consent_flow_required' | 'consent_flow_error' }
+	| null;
+
+export interface GateInput {
+	readonly available: { readonly ok: true } | { readonly ok: false; readonly reason: UnavailableReason };
+	readonly enablement: Enablement;
+	/** The app's own gate, from `PrivacyOptions.canRequestAds`. */
+	readonly appGate: { readonly permitted: true } | { readonly permitted: false; readonly reason: PrivacyBlockReason };
+	/** The package's consent flow. `null` when unused — then the app's gate alone decides. */
+	readonly consentGate: ConsentGateInput;
+}
+
+export type GateDecision =
+	| { readonly allowed: true }
+	| { readonly allowed: false; readonly kind: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly allowed: false; readonly kind: 'disabled' }
+	| { readonly allowed: false; readonly kind: 'undecided' }
+	| { readonly allowed: false; readonly kind: 'blocked'; readonly reason: PrivacyBlockReason };
+
+export function evaluateGates(input: GateInput): GateDecision {
+	// 1. Availability. Nothing downstream can be fixed while this is closed.
+	if (!input.available.ok) {
+		return { allowed: false, kind: 'unavailable', reason: input.available.reason };
+	}
+
+	// 2. Enablement. `undecided` is reported separately from `disabled` because
+	// that distinction is the entire reason the third state exists (FR-116).
+	if (input.enablement === 'disabled') {
+		return { allowed: false, kind: 'disabled' };
+	}
+	if (input.enablement === 'undecided') {
+		return { allowed: false, kind: 'undecided' };
+	}
+
+	// 3. Consent, whose two inputs combine as most-restrictive-wins (FR-105a).
+	//
+	// Requesting is permitted only when both permit it, and neither can widen
+	// what the other allows. The case this protects is an app that obtained
+	// consent successfully but independently blocked ads for a reason of its own
+	// — a reason FR-120 forbids the package from knowing, and therefore one it
+	// must never overrule.
+	//
+	// When both are closed the app's own gate is reported: it is the input the
+	// app controls directly, and the flow's state is separately readable through
+	// `consent.getState()` at any time.
+	if (!input.appGate.permitted) {
+		return { allowed: false, kind: 'blocked', reason: input.appGate.reason };
+	}
+	if (input.consentGate && !input.consentGate.permitted) {
+		return { allowed: false, kind: 'blocked', reason: input.consentGate.reason };
+	}
+
+	return { allowed: true };
+}

package/src/core/initMachine.ts

@@ -20,6 +20,7 @@ export type InitEvent =
 	| { readonly type: 'BLOCK'; readonly reason: PrivacyBlockReason }
 	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
 	| { readonly type: 'DISABLE' }
+	| { readonly type: 'UNDECIDE' }
 	| { readonly type: 'ENABLE' }
 	| { readonly type: 'SUCCEED' }
 	| { readonly type: 'FAIL'; readonly error: AdsError };
@@ -29,6 +30,16 @@ export interface InitSnapshot {
 	readonly blockReason: PrivacyBlockReason | null;
 	readonly unavailableReason: UnavailableReason | null;
 	readonly error: AdsError | null;
+	/**
+	 * The status held when ads were switched off, so re-enabling can return to
+	 * it instead of silently dropping to `not_started`.
+	 *
+	 * 0.1.0's `ENABLE` sent a disabled instance to `not_started`, which meant the
+	 * app had to call `initialize()` again or every later load and show was
+	 * refused — and nothing said so. Remembering one value is the whole fix
+	 * (FR-121).
+	 */
+	readonly resumeTo: InitStatus | null;
 }
 
 export const initialInit: InitSnapshot = {
@@ -36,12 +47,24 @@ export const initialInit: InitSnapshot = {
 	blockReason: null,
 	unavailableReason: null,
 	error: null,
+	resumeTo: null,
 };
 
 function at(status: InitStatus, patch: Partial<InitSnapshot> = {}): InitSnapshot {
 	return { ...initialInit, status, ...patch };
 }
 
+/**
+ * States that behave as "switched off" for everything downstream.
+ *
+ * `undecided` is grouped with `disabled` for request handling — neither may
+ * reach the provider — while staying a distinct reported status, which is the
+ * only reason the third state is worth having (FR-115, FR-116).
+ */
+function isSwitchedOff(status: InitStatus): boolean {
+	return status === 'disabled' || status === 'undecided';
+}
+
 /**
  * States a fresh start may leave from.
  *
@@ -65,18 +88,38 @@ export function canRequest(status: InitStatus): boolean {
 	return status === 'ready';
 }
 
+/**
+ * What to remember when switching off.
+ *
+ * Only a completed initialization is worth keeping. A `blocked` or `failed`
+ * instance has nothing to resume to, and remembering `initializing` would mean
+ * resuming into a state whose in-flight operation was already abandoned.
+ */
+function rememberFor(state: InitSnapshot): InitStatus | null {
+	if (state.status === 'ready') {
+		return 'ready';
+	}
+	// Preserve an earlier memory across an off -> off transition, so
+	// disable -> undecided -> enable still resumes.
+	return isSwitchedOff(state.status) ? state.resumeTo : null;
+}
+
 export function initReducer(state: InitSnapshot, event: InitEvent): InitSnapshot {
 	switch (event.type) {
 		case 'START':
-			// `disabled` and `unavailable` are terminal for the instance: a config
-			// change means a new instance, not a resurrected one.
-			if (state.status === 'disabled' || state.status === 'unavailable') {
+			// `disabled`, `undecided`, and `unavailable` all refuse a start:
+			// nothing may reach the provider while any of them holds.
+			if (isSwitchedOff(state.status) || state.status === 'unavailable') {
 				return state;
 			}
 			return canStart(state.status) ? at('initializing') : state;
 
 		case 'BLOCK':
-			if (state.status === 'disabled' || state.status === 'unavailable') {
+			// Consent is the weakest of the three gates, so it never overwrites a
+			// stronger one. This guard is the 0.1.0 behavior that settled the
+			// precedence question: availability and enablement already outranked
+			// consent, and FR-140 makes that explicit rather than inventing it.
+			if (isSwitchedOff(state.status) || state.status === 'unavailable') {
 				return state;
 			}
 			// A gate withdrawn after initialization does not un-initialize the
@@ -88,10 +131,33 @@ export function initReducer(state: InitSnapshot, event: InitEvent): InitSnapshot
 			return at('unavailable', { unavailableReason: event.reason });
 
 		case 'DISABLE':
-			return at('disabled');
+			// Availability outranks enablement (FR-140a). 0.1.0 left these two
+			// unguarded against each other, so whichever arrived last won and the
+			// reported reason depended on timing — exactly the incidental ordering
+			// FR-140 forbids. Availability winning is deterministic and is the
+			// more useful answer: an unsupported platform cannot be fixed by
+			// turning ads back on.
+			if (state.status === 'unavailable') {
+				return state;
+			}
+			return at('disabled', { resumeTo: rememberFor(state) });
 
-		case 'ENABLE':
-			return state.status === 'disabled' ? at('not_started') : state;
+		case 'UNDECIDE':
+			if (state.status === 'unavailable') {
+				return state;
+			}
+			return at('undecided', { resumeTo: rememberFor(state) });
+
+		case 'ENABLE': {
+			if (!isSwitchedOff(state.status)) {
+				return state;
+			}
+			// Resume only from a completed initialization. Anything else has no
+			// ready state to return to, and claiming one would put the instance in
+			// a state it never actually reached — so the caller is told to
+			// initialize instead, explicitly (FR-121).
+			return state.resumeTo === 'ready' ? at('ready') : at('not_started');
+		}
 
 		case 'SUCCEED':
 			// Only a transition out of `initializing` counts. A `SUCCEED` arriving

package/src/core/retryPolicy.ts

@@ -0,0 +1,127 @@
+/**
+ * Bounded, opt-in retry for failed loads (FR-134 – FR-139).
+ *
+ * 0.1.0 shipped no retry on purpose, and the reason was sound: every retry is a
+ * billable request, and only the app knows what that costs. But the practical
+ * result was that every app rewrote the same backoff loop, and the cost of
+ * writing it wrong landed on a bill. This ships the loop once, keeps it **off by
+ * default**, and makes every attempt visible.
+ *
+ * Three properties do the work:
+ *
+ *   - Off unless configured, so upgrading from 0.1.0 issues not one extra
+ *     request (FR-134, and the compat test proves it rather than asserting it).
+ *   - Only `retryable` errors. Configuration and consent errors, an unsupported
+ *     platform, and a disabled or undecided instance are states another attempt
+ *     cannot change, so retrying them would spend money on a certainty (FR-135).
+ *   - Every attempt is an event carrying the load cycle's correlation id, so a
+ *     bill can be reconciled against the event stream alone (FR-138).
+ *
+ * Pure — the schedule is computed here, the waiting happens in the instance's
+ * TimerSet so `dispose()` can prove it released everything.
+ */
+
+import { AdsConfigError } from '../diagnostics/errors';
+import { checkBand, DEFAULT_RETRY_POLICY, RETRY_BOUNDS } from './timers';
+import type { RetryPolicy } from '../config/types';
+
+export interface ResolvedRetryPolicy {
+	readonly maxRetries: number;
+	readonly initialDelayMs: number;
+	readonly maxDelayMs: number;
+}
+
+/**
+ * Validates one policy against the bounds.
+ *
+ * Out-of-range values **throw** rather than being clamped, matching the rule
+ * `timers.ts` already follows: silently clamping a request for ten retries down
+ * to five tells the app it configured something it did not, and the discrepancy
+ * only surfaces later as a bill that does not match the code.
+ *
+ * `label` names the offending field precisely — an error that says only
+ * "invalid retry policy" makes an integrator hunt through a catalog by hand.
+ */
+export function resolveRetryPolicy(policy: RetryPolicy, label: string): ResolvedRetryPolicy {
+	const maxRetries = checkBand(
+		`${label}.maxRetries`,
+		policy.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+		RETRY_BOUNDS.maxRetries,
+	);
+	const initialDelayMs = checkBand(
+		`${label}.initialDelayMs`,
+		policy.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs,
+		RETRY_BOUNDS.initialDelayMs,
+	);
+	const maxDelayMs = checkBand(
+		`${label}.maxDelayMs`,
+		policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+		RETRY_BOUNDS.maxDelayMs,
+	);
+
+	if (!Number.isInteger(maxRetries)) {
+		throw new AdsConfigError('retry_out_of_bounds', {
+			message: `${label}.maxRetries must be a whole number; received ${maxRetries}`,
+		});
+	}
+	if (initialDelayMs > maxDelayMs) {
+		throw new AdsConfigError('retry_out_of_bounds', {
+			message: `${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms); the first retry would already be past the ceiling`,
+		});
+	}
+
+	return { maxRetries, initialDelayMs, maxDelayMs };
+}
+
+/**
+ * Resolves the effective policy for one placement.
+ *
+ * An override **replaces** the instance-wide policy rather than merging into it.
+ * Merging would mean the effective policy for a placement could not be read off
+ * the configuration — you would have to simulate the merge to know what it was —
+ * and a per-field merge makes "this placement retries twice" quietly depend on a
+ * value written somewhere else.
+ *
+ * Both are validated against the same bounds, so an override narrows behavior
+ * but can never exceed a ceiling (FR-136a).
+ */
+export function resolveEffectiveRetry(
+	instancePolicy: RetryPolicy | undefined,
+	placementPolicy: RetryPolicy | false | undefined,
+	placementKey: string,
+): ResolvedRetryPolicy | null {
+	if (placementPolicy === false) {
+		// Explicit opt-out for this placement alone. A banner retry is cheap and
+		// invisible; a rewarded retry happens with a user waiting on the other
+		// side of it. An app may reasonably want one and not the other.
+		return null;
+	}
+	if (placementPolicy) {
+		return resolveRetryPolicy(placementPolicy, `placements.${placementKey}.retry`);
+	}
+	if (instancePolicy) {
+		return resolveRetryPolicy(instancePolicy, 'retry');
+	}
+	// Nothing configured anywhere: retry is entirely off, which is the default
+	// and the only behavior a 0.1.0 consumer can observe (FR-134).
+	return null;
+}
+
+/**
+ * Delay before the given attempt. `attempt` is 1-based — the first retry is 1.
+ *
+ * Exponential with a fixed x2 multiplier and **no jitter**. Jitter exists to
+ * desynchronize a fleet of clients hitting one server; a single device retrying
+ * its own load has no herd to avoid. Leaving it out keeps "two retries, 2s then
+ * 4s" an exact assertion instead of a statistical one, which matters more here
+ * than a property that does not apply.
+ */
+export function delayForAttempt(policy: ResolvedRetryPolicy, attempt: number): number {
+	const raw = policy.initialDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+	return Math.min(raw, policy.maxDelayMs);
+}
+
+/** Whether another attempt is permitted. `attemptsMade` counts retries only. */
+export function canRetry(policy: ResolvedRetryPolicy | null, attemptsMade: number): boolean {
+	return policy !== null && attemptsMade < policy.maxRetries;
+}