@chipmobilesdk/rn-ads 0.5.0 → 0.6.0

package/src/core/gates.ts

@@ -1,91 +1,94 @@
-/**
- * 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 };
-}
+/**
+ * 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

@@ -1,187 +1,187 @@
-/**
- * Initialization state machine (FR-022 – FR-025).
- *
- * Pure and synchronous: it decides what a transition means; the instance
- * performs the I/O. That split is what makes every rule in data-model.md §3.1
- * testable without a provider.
- *
- * The load-bearing invariant is idempotence. Three consumers calling
- * `initialize()` at once must produce exactly one native initialization and
- * three identical results (SC-005) — the instance holds one in-flight promise,
- * and this machine refuses to leave `initializing` for anything but a terminal
- * outcome.
- */
-
-import type { InitStatus, PrivacyBlockReason, UnavailableReason } from '../config/types';
-import type { AdsError } from '../diagnostics/errors';
-
-export type InitEvent =
-	| { readonly type: 'START' }
-	| { readonly type: 'BLOCK'; readonly reason: PrivacyBlockReason }
-	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
-	| { readonly type: 'DISABLE' }
-	| { readonly type: 'UNDECIDE' }
-	| { readonly type: 'ENABLE' }
-	| { readonly type: 'SUCCEED' }
-	/**
-	 * Back to `ready` with no native call, because the provider was initialized
-	 * earlier and nothing has torn it down since (FR-154). The instance decides
-	 * whether that holds; this machine only refuses to resume from a state a
-	 * fresh start could not leave either.
-	 */
-	| { readonly type: 'RESUME' }
-	| { readonly type: 'FAIL'; readonly error: AdsError };
-
-export interface InitSnapshot {
-	readonly status: InitStatus;
-	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 = {
-	status: 'not_started',
-	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.
- *
- * `blocked` is included because resolving consent and trying again is the
- * documented, expected flow (FR-019). `initializing` is excluded because that is
- * exactly the race idempotence exists to prevent. `ready` is excluded because
- * re-initializing an initialized provider is what FR-022 forbids.
- */
-const STARTABLE: ReadonlySet<InitStatus> = new Set<InitStatus>([
-	'not_started',
-	'blocked',
-	'failed',
-]);
-
-export function canStart(status: InitStatus): boolean {
-	return STARTABLE.has(status);
-}
-
-/** Only `ready` may issue requests. Everything else is a refusal with a reason. */
-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`, `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':
-			// 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
-			// provider — it stops requests. Reporting `blocked` is what the app
-			// acts on; the native SDK stays as it is.
-			return at('blocked', { blockReason: event.reason });
-
-		case 'UNAVAILABLE':
-			return at('unavailable', { unavailableReason: event.reason });
-
-		case 'DISABLE':
-			// 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 '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
-			// after a disable or a block is a late callback, and honoring it would
-			// resurrect a state the app deliberately left.
-			return state.status === 'initializing' ? at('ready') : state;
-
-		case 'RESUME':
-			// Same guard as START, for the same reason: `disabled`, `undecided` and
-			// `unavailable` are not left by a gate reopening. `canStart` excludes
-			// them, and `initializing`, whose own outcome is still on its way.
-			return canStart(state.status) ? at('ready') : state;
-
-		case 'FAIL':
-			return state.status === 'initializing' ? at('failed', { error: event.error }) : state;
-
-		default:
-			return state;
-	}
-}
+/**
+ * Initialization state machine (FR-022 – FR-025).
+ *
+ * Pure and synchronous: it decides what a transition means; the instance
+ * performs the I/O. That split is what makes every rule in data-model.md §3.1
+ * testable without a provider.
+ *
+ * The load-bearing invariant is idempotence. Three consumers calling
+ * `initialize()` at once must produce exactly one native initialization and
+ * three identical results (SC-005) — the instance holds one in-flight promise,
+ * and this machine refuses to leave `initializing` for anything but a terminal
+ * outcome.
+ */
+
+import type { InitStatus, PrivacyBlockReason, UnavailableReason } from '../config/types';
+import type { AdsError } from '../diagnostics/errors';
+
+export type InitEvent =
+	| { readonly type: 'START' }
+	| { readonly type: 'BLOCK'; readonly reason: PrivacyBlockReason }
+	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
+	| { readonly type: 'DISABLE' }
+	| { readonly type: 'UNDECIDE' }
+	| { readonly type: 'ENABLE' }
+	| { readonly type: 'SUCCEED' }
+	/**
+	 * Back to `ready` with no native call, because the provider was initialized
+	 * earlier and nothing has torn it down since (FR-154). The instance decides
+	 * whether that holds; this machine only refuses to resume from a state a
+	 * fresh start could not leave either.
+	 */
+	| { readonly type: 'RESUME' }
+	| { readonly type: 'FAIL'; readonly error: AdsError };
+
+export interface InitSnapshot {
+	readonly status: InitStatus;
+	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 = {
+	status: 'not_started',
+	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.
+ *
+ * `blocked` is included because resolving consent and trying again is the
+ * documented, expected flow (FR-019). `initializing` is excluded because that is
+ * exactly the race idempotence exists to prevent. `ready` is excluded because
+ * re-initializing an initialized provider is what FR-022 forbids.
+ */
+const STARTABLE: ReadonlySet<InitStatus> = new Set<InitStatus>([
+	'not_started',
+	'blocked',
+	'failed',
+]);
+
+export function canStart(status: InitStatus): boolean {
+	return STARTABLE.has(status);
+}
+
+/** Only `ready` may issue requests. Everything else is a refusal with a reason. */
+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`, `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':
+			// 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
+			// provider — it stops requests. Reporting `blocked` is what the app
+			// acts on; the native SDK stays as it is.
+			return at('blocked', { blockReason: event.reason });
+
+		case 'UNAVAILABLE':
+			return at('unavailable', { unavailableReason: event.reason });
+
+		case 'DISABLE':
+			// 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 '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
+			// after a disable or a block is a late callback, and honoring it would
+			// resurrect a state the app deliberately left.
+			return state.status === 'initializing' ? at('ready') : state;
+
+		case 'RESUME':
+			// Same guard as START, for the same reason: `disabled`, `undecided` and
+			// `unavailable` are not left by a gate reopening. `canStart` excludes
+			// them, and `initializing`, whose own outcome is still on its way.
+			return canStart(state.status) ? at('ready') : state;
+
+		case 'FAIL':
+			return state.status === 'initializing' ? at('failed', { error: event.error }) : state;
+
+		default:
+			return state;
+	}
+}