@chipmobilesdk/rn-ads 0.4.0 → 0.5.1

package/src/core/consentFlow.ts

@@ -1,180 +1,182 @@
-/**
- * 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,
-	privacyOptionsRequirement: 'unknown',
-	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,
-		privacyOptionsRequirement: info.privacyOptions,
-		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.
- *
- * The privacy-options requirement is `unknown` for the same reason: a broken
- * flow has no provider verdict to forward, and reporting `not_required` would be
- * the package deciding the user has no right to change their mind (FR-150).
- */
-export function consentFailure(error: AdsError): ConsentSnapshot {
-	return {
-		state: 'error',
-		canRequestAds: false,
-		isFormAvailable: false,
-		privacyOptionsRequirement: 'unknown',
-		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,
-		showPrivacyOptionsForm: unavailable,
-		getInfo: unavailable,
-		reset: () => undefined,
-	};
-}
+/**
+ * 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,
+	privacyOptionsRequirement: 'unknown',
+	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,
+		privacyOptionsRequirement: info.privacyOptions,
+		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.
+ *
+ * The privacy-options requirement is `unknown` for the same reason: a broken
+ * flow has no provider verdict to forward, and reporting `not_required` would be
+ * the package deciding the user has no right to change their mind (FR-150).
+ */
+export function consentFailure(error: AdsError): ConsentSnapshot {
+	return {
+		state: 'error',
+		canRequestAds: false,
+		isFormAvailable: false,
+		privacyOptionsRequirement: 'unknown',
+		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,
+		showPrivacyOptionsForm: unavailable,
+		getInfo: unavailable,
+		reset: () => undefined,
+	};
+}

package/src/core/enablement.ts

@@ -1,76 +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';
-}
+/**
+ * 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/fullScreenLock.ts

@@ -1,54 +1,54 @@
-/**
- * The single full-screen lock (FR-030).
- *
- * One token per instance, not per placement, because the constraint is about the
- * screen rather than about any particular ad: two full-screen ads stacked on top
- * of each other is a broken app regardless of which placements produced them.
- *
- * **There is no queue.** A refused show is refused, and the caller is told so
- * immediately. Queueing would mean an ad opening at a moment the app never
- * chose — seconds later, on a different screen, after the user moved on — which
- * is exactly the behavior FR-045 forbids the package from deciding on its own.
- */
-
-export interface FullScreenLock {
-	/** Takes the lock, or returns false if another full-screen ad holds it. */
-	acquire(placementKey: string): boolean;
-	/** Releases only if this placement holds it; a stale release is a no-op. */
-	release(placementKey: string): void;
-	/** Whichever placement currently holds it, if any. */
-	holder(): string | null;
-	isHeld(): boolean;
-	/** Drops the lock unconditionally. For dispose only. */
-	reset(): void;
-}
-
-export function createFullScreenLock(): FullScreenLock {
-	let held: string | null = null;
-
-	return {
-		acquire(placementKey) {
-			if (held !== null) {
-				return false;
-			}
-			held = placementKey;
-			return true;
-		},
-		release(placementKey) {
-			// Guarded so a late dismissal from an earlier ad cannot release the
-			// lock out from under the ad currently on screen.
-			if (held === placementKey) {
-				held = null;
-			}
-		},
-		holder() {
-			return held;
-		},
-		isHeld() {
-			return held !== null;
-		},
-		reset() {
-			held = null;
-		},
-	};
-}
+/**
+ * The single full-screen lock (FR-030).
+ *
+ * One token per instance, not per placement, because the constraint is about the
+ * screen rather than about any particular ad: two full-screen ads stacked on top
+ * of each other is a broken app regardless of which placements produced them.
+ *
+ * **There is no queue.** A refused show is refused, and the caller is told so
+ * immediately. Queueing would mean an ad opening at a moment the app never
+ * chose — seconds later, on a different screen, after the user moved on — which
+ * is exactly the behavior FR-045 forbids the package from deciding on its own.
+ */
+
+export interface FullScreenLock {
+	/** Takes the lock, or returns false if another full-screen ad holds it. */
+	acquire(placementKey: string): boolean;
+	/** Releases only if this placement holds it; a stale release is a no-op. */
+	release(placementKey: string): void;
+	/** Whichever placement currently holds it, if any. */
+	holder(): string | null;
+	isHeld(): boolean;
+	/** Drops the lock unconditionally. For dispose only. */
+	reset(): void;
+}
+
+export function createFullScreenLock(): FullScreenLock {
+	let held: string | null = null;
+
+	return {
+		acquire(placementKey) {
+			if (held !== null) {
+				return false;
+			}
+			held = placementKey;
+			return true;
+		},
+		release(placementKey) {
+			// Guarded so a late dismissal from an earlier ad cannot release the
+			// lock out from under the ad currently on screen.
+			if (held === placementKey) {
+				held = null;
+			}
+		},
+		holder() {
+			return held;
+		},
+		isHeld() {
+			return held !== null;
+		},
+		reset() {
+			held = null;
+		},
+	};
+}