@chipmobilesdk/rn-ads 0.1.0

package/src/core/fullScreenLock.ts

@@ -0,0 +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;
+		},
+	};
+}

package/src/core/initMachine.ts

@@ -0,0 +1,108 @@
+/**
+ * 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: 'ENABLE' }
+	| { readonly type: 'SUCCEED' }
+	| { readonly type: 'FAIL'; readonly error: AdsError };
+
+export interface InitSnapshot {
+	readonly status: InitStatus;
+	readonly blockReason: PrivacyBlockReason | null;
+	readonly unavailableReason: UnavailableReason | null;
+	readonly error: AdsError | null;
+}
+
+export const initialInit: InitSnapshot = {
+	status: 'not_started',
+	blockReason: null,
+	unavailableReason: null,
+	error: null,
+};
+
+function at(status: InitStatus, patch: Partial<InitSnapshot> = {}): InitSnapshot {
+	return { ...initialInit, status, ...patch };
+}
+
+/**
+ * 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';
+}
+
+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') {
+				return state;
+			}
+			return canStart(state.status) ? at('initializing') : state;
+
+		case 'BLOCK':
+			if (state.status === 'disabled' || 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':
+			return at('disabled');
+
+		case 'ENABLE':
+			return state.status === 'disabled' ? at('not_started') : state;
+
+		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 'FAIL':
+			return state.status === 'initializing' ? at('failed', { error: event.error }) : state;
+
+		default:
+			return state;
+	}
+}

package/src/core/placementMachine.ts

@@ -0,0 +1,114 @@
+/**
+ * Per-placement lifecycle (FR-026 – FR-031, FR-034).
+ *
+ * Pure and synchronous, per data-model.md §3.2. Two variants share one reducer:
+ *
+ *   full-screen — load, show once, become `consumed`, reload before the next show
+ *   banner      — continuous; it renders and may refresh, and never reaches
+ *                 `consumed`, because a banner is not a single-use resource
+ *
+ * Staleness is handled here rather than at the show site so that a stale ad can
+ * never be *reported* ready either — a consumer that renders a "Watch ad" button
+ * from `state === 'ready'` would otherwise offer a button that fails on tap.
+ */
+
+import type { AdFormat, PlacementState, UnavailableReason } from '../config/types';
+import type { AdsError } from '../diagnostics/errors';
+
+export type PlacementEvent =
+	| { readonly type: 'LOAD' }
+	| { readonly type: 'LOADED'; readonly atMs: number }
+	| { readonly type: 'LOAD_FAILED'; readonly error: AdsError }
+	| { readonly type: 'SHOW' }
+	| { readonly type: 'SHOW_FAILED'; readonly error: AdsError }
+	| { readonly type: 'DISMISSED' }
+	| { readonly type: 'EXPIRE' }
+	| { readonly type: 'UNAVAILABLE'; readonly reason: UnavailableReason }
+	| { readonly type: 'RESET' };
+
+export interface PlacementSnapshot {
+	readonly state: PlacementState;
+	readonly loadedAtMs: number | null;
+	readonly error: AdsError | null;
+	readonly correlationId: string | null;
+}
+
+export const initialPlacement: PlacementSnapshot = {
+	state: 'idle',
+	loadedAtMs: null,
+	error: null,
+	correlationId: null,
+};
+
+/** A load is only legal from a settled state; `loading` is where FR-029 bites. */
+export function canLoad(state: PlacementState): boolean {
+	return state === 'idle' || state === 'failed' || state === 'consumed' || state === 'ready';
+}
+
+/** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */
+export function canShow(state: PlacementState): boolean {
+	return state === 'ready';
+}
+
+export function placementReducer(
+	state: PlacementSnapshot,
+	event: PlacementEvent,
+	format: AdFormat,
+): PlacementSnapshot {
+	switch (event.type) {
+		case 'LOAD':
+			// FR-029: a load while already loading is absorbed. The instance
+			// returns the in-flight promise; the state does not restart.
+			if (state.state === 'loading' || state.state === 'showing') {
+				return state;
+			}
+			if (state.state === 'unavailable') {
+				return state;
+			}
+			return { ...initialPlacement, state: 'loading' };
+
+		case 'LOADED':
+			return state.state === 'loading'
+				? { ...state, state: 'ready', loadedAtMs: event.atMs, error: null }
+				: state;
+
+		case 'LOAD_FAILED':
+			return state.state === 'loading'
+				? { ...initialPlacement, state: 'failed', error: event.error }
+				: state;
+
+		case 'SHOW':
+			return state.state === 'ready' ? { ...state, state: 'showing' } : state;
+
+		case 'SHOW_FAILED':
+			// A failed presentation consumes the ad regardless: the provider has
+			// taken it, and re-showing the same object is what FR-031 forbids.
+			return state.state === 'showing'
+				? { ...initialPlacement, state: 'failed', error: event.error }
+				: state;
+
+		case 'DISMISSED':
+			if (state.state !== 'showing') {
+				return state;
+			}
+			// A banner is continuous — dismissal is not part of its life. A
+			// full-screen ad is spent, and must be reloaded before the next show.
+			return format === 'banner'
+				? { ...initialPlacement, state: 'idle' }
+				: { ...initialPlacement, state: 'consumed' };
+
+		case 'EXPIRE':
+			// FR-034. Only a ready-and-waiting ad can go stale; one being shown is
+			// already in the user's hands.
+			return state.state === 'ready' ? { ...initialPlacement, state: 'idle' } : state;
+
+		case 'UNAVAILABLE':
+			return { ...initialPlacement, state: 'unavailable' };
+
+		case 'RESET':
+			return initialPlacement;
+
+		default:
+			return state;
+	}
+}

package/src/core/privacyGate.ts

@@ -0,0 +1,85 @@
+/**
+ * The privacy gate (FR-016 – FR-021).
+ *
+ * The package enforces ordering; the app owns policy. It renders no consent UI,
+ * writes no legal copy, and decides nothing about a jurisdiction — it accepts a
+ * gate outcome and refuses to let any request precede it.
+ *
+ * That refusal is the whole value. Consent ordering is easy to get wrong by
+ * accident, and the failure is invisible: an ad request that should not have
+ * happened looks exactly like one that should. A package that enforces the order
+ * is worth more than documentation that describes it.
+ *
+ * Pure — no provider, no React, no I/O. The engine adapter translates the
+ * outcome into provider configuration.
+ */
+
+import type { PrivacyBlockReason, PrivacyOptions } from '../config/types';
+import type { EnginePrivacy } from '../engine/port';
+
+export type GateDecision =
+	| { readonly allowed: true }
+	| { readonly allowed: false; readonly reason: PrivacyBlockReason };
+
+export function evaluateGate(privacy: PrivacyOptions | null): GateDecision {
+	if (!privacy) {
+		return { allowed: false, reason: 'consent_required' };
+	}
+	if (privacy.canRequestAds) {
+		return { allowed: true };
+	}
+	// Distinguishing "not asked yet" from "asked and refused" matters: the first
+	// is a prompt the app still owes the user, the second is a settled answer.
+	// Collapsing them would leave the app unable to tell which (FR-018).
+	return {
+		allowed: false,
+		reason: privacy.consentUndetermined ? 'consent_undetermined' : 'consent_required',
+	};
+}
+
+/**
+ * Flags the provider only honors at initialization time.
+ *
+ * Changing one of these after `initialize()` cannot take effect, which is why
+ * `updatePrivacy` reports `requires_reinitialization` instead of accepting the
+ * change and leaving the package in a state that is half old and half new
+ * (FR-020).
+ *
+ * `canRequestAds` is absent on purpose: resolving the gate after being blocked
+ * is the normal, supported flow, not a reinitialization (FR-019).
+ */
+const INIT_TIME_ONLY = [
+	'childDirected',
+	'underAgeOfConsent',
+	'maxAdContentRating',
+] as const satisfies readonly (keyof PrivacyOptions)[];
+
+export function requiresReinitialization(
+	applied: PrivacyOptions | null,
+	next: PrivacyOptions,
+): boolean {
+	if (!applied) {
+		return false;
+	}
+	return INIT_TIME_ONLY.some(field => applied[field] !== next[field]);
+}
+
+/**
+ * Projects consumer privacy options onto what the engine needs.
+ *
+ * `personalizedAds` is carried through rather than inverted here; the adapter
+ * owns the translation to the provider's `requestNonPersonalizedAdsOnly`, so
+ * the polarity flip lives next to the API that requires it.
+ */
+export function toEnginePrivacy(
+	privacy: PrivacyOptions,
+	testDeviceIds: readonly string[],
+): EnginePrivacy {
+	return {
+		childDirected: privacy.childDirected,
+		underAgeOfConsent: privacy.underAgeOfConsent,
+		maxAdContentRating: privacy.maxAdContentRating,
+		personalizedAds: privacy.personalizedAds,
+		testDeviceIds,
+	};
+}

package/src/core/rewardedSession.ts

@@ -0,0 +1,84 @@
+/**
+ * Rewarded session bookkeeping (FR-046 – FR-049).
+ *
+ * Two independent booleans, never derived from one another:
+ *
+ *              rewardConfirmed=false        rewardConfirmed=true
+ *   dismissed=false   in progress           reward emitted, awaiting dismissal
+ *   dismissed=true    dismissed_no_reward   earned
+ *
+ * The defect this exists to prevent is inferring "earned" from dismissal. It is
+ * the most common way rewarded integrations go wrong, and it is a direct revenue
+ * and fairness fault: a user who closed the ad after two seconds gets the prize,
+ * and the publisher is billed for nothing.
+ *
+ * Tracking two flags and deriving the outcome makes both callback orderings
+ * produce the same result *by construction* rather than by the provider
+ * happening to fire in a convenient order (SC-007).
+ */
+
+import type { Reward } from '../config/types';
+
+export type RewardedOutcome = 'in_progress' | 'earned' | 'dismissed_without_reward';
+
+export interface RewardedSession {
+	/**
+	 * Records a provider reward confirmation. Returns the reward the first time
+	 * and `null` on every repeat, which is what collapses a duplicate provider
+	 * emission into exactly one public event (FR-054).
+	 */
+	confirmReward(reward: Reward): Reward | null;
+	/** Records dismissal. Returns true the first time only. */
+	dismiss(): boolean;
+	outcome(): RewardedOutcome;
+	/** True only once the provider actually confirmed. Never inferred (FR-046). */
+	get rewardEarned(): boolean;
+	get dismissed(): boolean;
+	reward(): Reward | null;
+}
+
+export function createRewardedSession(): RewardedSession {
+	let confirmed = false;
+	let dismissed = false;
+	let earnedReward: Reward | null = null;
+
+	return {
+		confirmReward(reward) {
+			if (confirmed) {
+				return null;
+			}
+			confirmed = true;
+			earnedReward = reward;
+			return reward;
+		},
+
+		dismiss() {
+			if (dismissed) {
+				return false;
+			}
+			dismissed = true;
+			return true;
+		},
+
+		outcome() {
+			if (!dismissed) {
+				return 'in_progress';
+			}
+			// Read at dismissal time, so a reward that arrived first is honored and
+			// one that never arrives is not invented.
+			return confirmed ? 'earned' : 'dismissed_without_reward';
+		},
+
+		get rewardEarned() {
+			return confirmed;
+		},
+
+		get dismissed() {
+			return dismissed;
+		},
+
+		reward() {
+			return earnedReward;
+		},
+	};
+}

package/src/core/timers.ts

@@ -0,0 +1,109 @@
+/**
+ * Timeout and staleness policy (FR-032, FR-034).
+ *
+ * Defaults and bounds live here rather than at each call site so there is one
+ * place to read what the package will wait for. Values outside a band are a
+ * configuration error rather than being silently clamped: silently clamping a
+ * one-second load timeout to five would mean the app is told it configured
+ * something it did not (FR-008).
+ */
+
+import { AdsConfigError } from '../diagnostics/errors';
+import type { TimeoutConfig, Unsubscribe } from '../config/types';
+
+/** Comfortably longer than a normal fill on a slow mobile network, still bounded. */
+export const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
+/** Generous for what is essentially a local presentation. */
+export const DEFAULT_SHOW_TIMEOUT_MS = 10_000;
+/**
+ * Google documents that a loaded ad object expires about an hour after load.
+ * Sixty minutes is the provider's own number; choosing anything else would be
+ * inventing a constraint (R7).
+ */
+export const DEFAULT_AD_VALIDITY_MS = 3_600_000;
+
+export const LOAD_TIMEOUT_BOUNDS = { min: 5_000, max: 120_000 } as const;
+export const SHOW_TIMEOUT_BOUNDS = { min: 5_000, max: 30_000 } as const;
+export const AD_VALIDITY_BOUNDS = { min: 60_000, max: 3_600_000 } as const;
+
+export interface ResolvedTimeouts {
+	readonly load: number;
+	readonly show: number;
+	readonly adValidity: number;
+}
+
+function checkBand(
+	label: string,
+	value: number,
+	bounds: { readonly min: number; readonly max: number },
+): number {
+	if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
+		throw new AdsConfigError('timeout_out_of_bounds', {
+			message: `${label} must be between ${bounds.min}ms and ${bounds.max}ms; received ${value}`,
+		});
+	}
+	return value;
+}
+
+export function resolveTimeouts(
+	timeouts: TimeoutConfig | undefined,
+	adValidityMs: number | undefined,
+): ResolvedTimeouts {
+	return {
+		load: checkBand('timeouts.load', timeouts?.load ?? DEFAULT_LOAD_TIMEOUT_MS, LOAD_TIMEOUT_BOUNDS),
+		show: checkBand('timeouts.show', timeouts?.show ?? DEFAULT_SHOW_TIMEOUT_MS, SHOW_TIMEOUT_BOUNDS),
+		adValidity: checkBand(
+			'adValidityMs',
+			adValidityMs ?? DEFAULT_AD_VALIDITY_MS,
+			AD_VALIDITY_BOUNDS,
+		),
+	};
+}
+
+/**
+ * Tracks every timer the instance owns so `dispose()` can prove it released
+ * them. Counting is not incidental — SC-008 asserts the count reaches zero, and
+ * a leaked timer is otherwise invisible until it fires into a disposed consumer.
+ */
+export interface TimerSet {
+	after(ms: number, callback: () => void): Unsubscribe;
+	clearAll(): void;
+	size(): number;
+}
+
+export function createTimerSet(): TimerSet {
+	const handles = new Set<ReturnType<typeof setTimeout>>();
+
+	return {
+		after(ms, callback) {
+			const handle = setTimeout(() => {
+				handles.delete(handle);
+				callback();
+			}, ms);
+			handles.add(handle);
+			let cleared = false;
+			return () => {
+				if (cleared) {
+					return;
+				}
+				cleared = true;
+				clearTimeout(handle);
+				handles.delete(handle);
+			};
+		},
+		clearAll() {
+			for (const handle of handles) {
+				clearTimeout(handle);
+			}
+			handles.clear();
+		},
+		size() {
+			return handles.size;
+		},
+	};
+}
+
+/** A loaded ad past its validity window must never be reported ready (FR-034). */
+export function isStale(loadedAtMs: number, nowMs: number, adValidityMs: number): boolean {
+	return nowMs - loadedAtMs >= adValidityMs;
+}

package/src/diagnostics/correlation.ts

@@ -0,0 +1,31 @@
+/**
+ * Correlation identifiers (FR-052).
+ *
+ * One value is minted when a load begins and carried by every event of that
+ * load/show cycle through its terminal event. It is what lets a consumer
+ * reconstruct a single ad's life from an event stream alone (SC-009) without the
+ * package having to store any history of its own.
+ *
+ * Opaque and monotonic per instance. Not a UUID, and deliberately not derived
+ * from anything about the device or the user — it exists to group events, and
+ * anything with more meaning than that would be a payload the package has
+ * promised not to carry (FR-021).
+ */
+
+export interface CorrelationIssuer {
+	next(): string;
+}
+
+export function createCorrelationIssuer(prefix = 'ad'): CorrelationIssuer {
+	let counter = 0;
+	// Distinguishes cycles from two instances in one process, which otherwise
+	// both start at 1 and would collide in a merged log.
+	const instance = Math.random().toString(36).slice(2, 8);
+
+	return {
+		next() {
+			counter += 1;
+			return `${prefix}-${instance}-${counter}`;
+		},
+	};
+}