@chipmobilesdk/rn-ads 0.5.0 → 0.6.0

package/src/core/timers.ts

@@ -1,208 +1,164 @@
-/**
- * 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;
-
-/**
- * App-open's own window, deliberately shorter than the hour the other
- * full-screen formats get (FR-130).
- *
- * Worth being explicit about why: Google expires app-open ads after **four
- * hours**, which is *longer* than DEFAULT_AD_VALIDITY_MS, so the provider does
- * not constrain this at all. The shorter window is a product decision. An
- * app-open ad shows at the most prominent moment the app has, and a creative
- * cached for an hour is stale by then; thirty minutes still spares a returning
- * user the spinner of a cold load, which is both the worst app-open experience
- * and the specific behavior store policy penalizes.
- */
-export const DEFAULT_APP_OPEN_VALIDITY_MS = 1_800_000;
-
-/**
- * How long `enabled: 'undecided'` may go unresolved before one warning fires.
- *
- * Ten seconds is several times a realistic worst case for the round trip this
- * state exists to cover — asking a store whether the user owns an ad-removal
- * entitlement — so an app doing the right thing essentially never trips it,
- * while an app that forgot to resolve trips it inside a single QA session,
- * which is where it needs to be caught (FR-119).
- */
-export const DEFAULT_UNDECIDED_WARNING_MS = 10_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;
-/** Ceiling is one hour so app-open can never outlive the general window. */
-export const APP_OPEN_VALIDITY_BOUNDS = { min: 60_000, max: 3_600_000 } as const;
-export const UNDECIDED_WARNING_BOUNDS = { min: 1_000, max: 120_000 } as const;
-
-/**
- * Retry defaults (FR-136).
- *
- * Two retries rather than more: each one is a billable request, and two covers
- * the transient network failure and the momentary no-fill — the cases where
- * trying again plausibly helps. A third mostly pays for a failure that was not
- * transient. 2s then 4s keeps both inside a window the user still associates
- * with the action that triggered the load.
- */
-export const DEFAULT_RETRY_POLICY = {
-	maxRetries: 2,
-	initialDelayMs: 2_000,
-	maxDelayMs: 30_000,
-} as const;
-
-export const RETRY_BOUNDS = {
-	maxRetries: { min: 1, max: 5 },
-	initialDelayMs: { min: 500, max: 30_000 },
-	maxDelayMs: { min: 1_000, max: 60_000 },
-} as const;
-
-/**
- * Ad-originated return detection (FR-128).
- *
- * A background transition within CLICK_WINDOW of a click is attributed to a
- * browser the ad opened. An absence longer than MAX_AWAY is no longer
- * attributable to the ad — the user did something else in between. GRACE covers
- * the moment right after the return, where an app-open show would otherwise
- * fire, without outliving it and refusing a genuinely later show.
- */
-export const AD_CLICK_WINDOW_MS = 2_000;
-export const AD_RETURN_MAX_AWAY_MS = 300_000;
-export const AD_RETURN_GRACE_MS = 10_000;
-
-export interface ResolvedTimeouts {
-	readonly load: number;
-	readonly show: number;
-	readonly adValidity: number;
-	readonly appOpenValidity: number;
-	readonly undecidedWarning: number;
-}
-
-export 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 interface TimeoutInput {
-	readonly timeouts?: TimeoutConfig;
-	readonly adValidityMs?: number;
-	readonly appOpenValidityMs?: number;
-	readonly undecidedWarningMs?: number;
-}
-
-export function resolveTimeouts(input: TimeoutInput): ResolvedTimeouts {
-	const { timeouts, adValidityMs, appOpenValidityMs, undecidedWarningMs } = input;
-	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,
-		),
-		appOpenValidity: checkBand(
-			'appOpenValidityMs',
-			appOpenValidityMs ?? DEFAULT_APP_OPEN_VALIDITY_MS,
-			APP_OPEN_VALIDITY_BOUNDS,
-		),
-		undecidedWarning: checkBand(
-			'undecidedWarningMs',
-			undecidedWarningMs ?? DEFAULT_UNDECIDED_WARNING_MS,
-			UNDECIDED_WARNING_BOUNDS,
-		),
-	};
-}
-
-/**
- * How timers are actually scheduled.
- *
- * Injectable so a test can drive retry backoff, app-open expiry, and the
- * undecided warning by moving a clock rather than by waiting. The production
- * default is `setTimeout`; the fake engine supplies a controllable one. Without
- * this, every timing assertion in the suite would either sleep for real or
- * depend on the test runner's timer mocking, and NFR-103's "no device, no
- * network" would quietly become "no device, no network, but several seconds".
- */
-export interface Scheduler {
-	setTimeout(callback: () => void, ms: number): unknown;
-	clearTimeout(handle: unknown): void;
-}
-
-const realScheduler: Scheduler = {
-	setTimeout: (callback, ms) => setTimeout(callback, ms),
-	clearTimeout: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
-
-/**
- * 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(scheduler: Scheduler = realScheduler): TimerSet {
-	const handles = new Set<unknown>();
-
-	return {
-		after(ms, callback) {
-			const handle = scheduler.setTimeout(() => {
-				handles.delete(handle);
-				callback();
-			}, ms);
-			handles.add(handle);
-			let cleared = false;
-			return () => {
-				if (cleared) {
-					return;
-				}
-				cleared = true;
-				scheduler.clearTimeout(handle);
-				handles.delete(handle);
-			};
-		},
-		clearAll() {
-			for (const handle of handles) {
-				scheduler.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;
-}
+/**
+ * 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 { checkRange, type Range } from '@chipmobilesdk/rn-core';
+
+import { AdsConfigError, type AdsErrorCode } from '../diagnostics/errors';
+import type { TimeoutConfig } 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;
+
+/**
+ * App-open's own window, deliberately shorter than the hour the other
+ * full-screen formats get (FR-130).
+ *
+ * Worth being explicit about why: Google expires app-open ads after **four
+ * hours**, which is *longer* than DEFAULT_AD_VALIDITY_MS, so the provider does
+ * not constrain this at all. The shorter window is a product decision. An
+ * app-open ad shows at the most prominent moment the app has, and a creative
+ * cached for an hour is stale by then; thirty minutes still spares a returning
+ * user the spinner of a cold load, which is both the worst app-open experience
+ * and the specific behavior store policy penalizes.
+ */
+export const DEFAULT_APP_OPEN_VALIDITY_MS = 1_800_000;
+
+/**
+ * How long `enabled: 'undecided'` may go unresolved before one warning fires.
+ *
+ * Ten seconds is several times a realistic worst case for the round trip this
+ * state exists to cover — asking a store whether the user owns an ad-removal
+ * entitlement — so an app doing the right thing essentially never trips it,
+ * while an app that forgot to resolve trips it inside a single QA session,
+ * which is where it needs to be caught (FR-119).
+ */
+export const DEFAULT_UNDECIDED_WARNING_MS = 10_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;
+/** Ceiling is one hour so app-open can never outlive the general window. */
+export const APP_OPEN_VALIDITY_BOUNDS = { min: 60_000, max: 3_600_000 } as const;
+export const UNDECIDED_WARNING_BOUNDS = { min: 1_000, max: 120_000 } as const;
+
+/**
+ * Retry defaults (FR-136).
+ *
+ * Two retries rather than more: each one is a billable request, and two covers
+ * the transient network failure and the momentary no-fill — the cases where
+ * trying again plausibly helps. A third mostly pays for a failure that was not
+ * transient. 2s then 4s keeps both inside a window the user still associates
+ * with the action that triggered the load.
+ */
+export const DEFAULT_RETRY_POLICY = {
+	maxRetries: 2,
+	initialDelayMs: 2_000,
+	maxDelayMs: 30_000,
+} as const;
+
+export const RETRY_BOUNDS = {
+	maxRetries: { min: 1, max: 5 },
+	initialDelayMs: { min: 500, max: 30_000 },
+	maxDelayMs: { min: 1_000, max: 60_000 },
+} as const;
+
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * A background transition within CLICK_WINDOW of a click is attributed to a
+ * browser the ad opened. An absence longer than MAX_AWAY is no longer
+ * attributable to the ad — the user did something else in between. GRACE covers
+ * the moment right after the return, where an app-open show would otherwise
+ * fire, without outliving it and refusing a genuinely later show.
+ */
+export const AD_CLICK_WINDOW_MS = 2_000;
+export const AD_RETURN_MAX_AWAY_MS = 300_000;
+export const AD_RETURN_GRACE_MS = 10_000;
+
+export interface ResolvedTimeouts {
+	readonly load: number;
+	readonly show: number;
+	readonly adValidity: number;
+	readonly appOpenValidity: number;
+	readonly undecidedWarning: number;
+}
+
+/**
+ * `value` when it is inside `bounds`, else an `AdsConfigError` with `code`: each
+ * field reports the code its documentation names, so a retry policy out of bounds
+ * is `retry_out_of_bounds`, not a timeout's code (CORE-04, ADS-16).
+ */
+export function checkBand(
+	label: string,
+	value: number,
+	bounds: Range,
+	code: AdsErrorCode = 'timeout_out_of_bounds',
+	unit = 'ms',
+): number {
+	return checkRange(label, value, bounds, message => new AdsConfigError(code, { message }), unit);
+}
+
+export interface TimeoutInput {
+	readonly timeouts?: TimeoutConfig;
+	readonly adValidityMs?: number;
+	readonly appOpenValidityMs?: number;
+	readonly undecidedWarningMs?: number;
+}
+
+export function resolveTimeouts(input: TimeoutInput): ResolvedTimeouts {
+	const { timeouts, adValidityMs, appOpenValidityMs, undecidedWarningMs } = input;
+	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,
+		),
+		appOpenValidity: checkBand(
+			'appOpenValidityMs',
+			appOpenValidityMs ?? DEFAULT_APP_OPEN_VALIDITY_MS,
+			APP_OPEN_VALIDITY_BOUNDS,
+		),
+		undecidedWarning: checkBand(
+			'undecidedWarningMs',
+			undecidedWarningMs ?? DEFAULT_UNDECIDED_WARNING_MS,
+			UNDECIDED_WARNING_BOUNDS,
+		),
+	};
+}
+
+/**
+ * How timers are scheduled, and the set that tracks them so `dispose()` can prove
+ * it released every one (SC-008): rn-core's, injectable so a test drives retry
+ * backoff, app-open expiry and the undecided warning by moving a clock.
+ */
+export { createTimerSet, type Scheduler, type TimerSet } from '@chipmobilesdk/rn-core';
+
+/** 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

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