@chipmobilesdk/rn-ads 0.2.0 → 0.3.0

package/src/config/validate.ts

@@ -1,188 +1,211 @@
-/**
- * Catalog and configuration validation (FR-008), plus the fail-closed check
- * that substitution cannot cover (FR-012).
- *
- * Configuration faults throw rather than returning a result. They mean the app
- * is wired wrong, and no runtime status could describe a usable outcome — every
- * other failure in this package is a typed result instead.
- *
- * Every message names the offending placement key. An error that says only
- * "invalid configuration" makes the integrator hunt through a catalog by hand.
- */
-
-import { AdsConfigError } from '../diagnostics/errors';
-import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
-import { resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
-import { toEnablement } from '../core/enablement';
-import { resolveEffectiveRetry, type ResolvedRetryPolicy } from '../core/retryPolicy';
-import type {
-	AdFormat,
-	AdsConfig,
-	ConsentTestingOptions,
-	Enablement,
-	Environment,
-	PlacementDefinition,
-} from './types';
-
-const FORMATS: ReadonlySet<string> = new Set<AdFormat>([
-	'banner',
-	'interstitial',
-	'rewarded',
-	'app_open',
-]);
-
-export interface ValidateOptions {
-	/**
-	 * Whether this is a debug build. Injected rather than read from `__DEV__`
-	 * directly so the fail-closed rule is testable without manipulating a global
-	 * the test runner also depends on.
-	 */
-	readonly isDevBuild: boolean;
-}
-
-export interface ResolvedConfig {
-	readonly enablement: Enablement;
-	readonly environment: Environment;
-	readonly placements: ReadonlyMap<string, PlacementDefinition>;
-	readonly catalog: ResolvedCatalog;
-	readonly timeouts: ResolvedTimeouts;
-	/** Empty in production regardless of what was configured (FR-014). */
-	readonly testDeviceIds: readonly string[];
-	/** Effective retry per placement. `null` means retry is off there (FR-134). */
-	readonly retryByKey: ReadonlyMap<string, ResolvedRetryPolicy | null>;
-	/** Stripped entirely in production (FR-113). */
-	readonly consentTesting: ConsentTestingOptions | undefined;
-	/**
-	 * Which consent tools were dropped because the environment is production.
-	 * Surfaced so the inertness is observable rather than merely documented —
-	 * the same treatment FR-011a gives substituted ad units.
-	 */
-	readonly ignoredConsentTools: readonly string[];
-}
-
-export function validateConfig(config: AdsConfig, options: ValidateOptions): ResolvedConfig {
-	// FR-012. Substitution deliberately does not apply in production, so a debug
-	// build declaring `production` is the one case it cannot make safe: it would
-	// send real requests from a build that should never generate traffic. Fail
-	// closed rather than continue.
-	if (config.environment === 'production' && options.isDevBuild) {
-		throw new AdsConfigError('production_in_dev_build', {
-			message:
-				'environment is "production" but this is a development build. ' +
-				'Non-production builds must declare "development" or "test" so the package can ' +
-				'substitute official Google test ad units and keep production traffic impossible.',
-		});
-	}
-
-	if (!Array.isArray(config.placements) || config.placements.length === 0) {
-		throw new AdsConfigError('invalid_config', {
-			message: 'placements must be a non-empty array; the package can show nothing without one',
-		});
-	}
-
-	const byKey = new Map<string, PlacementDefinition>();
-
-	for (const placement of config.placements) {
-		const key = typeof placement?.key === 'string' ? placement.key.trim() : '';
-
-		if (!key) {
-			throw new AdsConfigError('invalid_config', {
-				message: 'every placement needs a non-empty key',
-			});
-		}
-
-		if (byKey.has(key)) {
-			// Rejecting the whole catalog rather than picking a winner: a repeated
-			// key means the app's own naming produced two placements for one slot,
-			// and the package has no basis to guess which was meant.
-			throw new AdsConfigError('duplicate_placement_key', {
-				message: `duplicate placement key "${key}"`,
-				placementKey: key,
-			});
-		}
-
-		if (!FORMATS.has(placement.format)) {
-			throw new AdsConfigError('invalid_config', {
-				message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
-				placementKey: key,
-			});
-		}
-
-		if (!placement.androidAdUnitId || !placement.androidAdUnitId.trim()) {
-			throw new AdsConfigError('missing_ad_unit_id', {
-				message: `placement "${key}" is missing androidAdUnitId`,
-				placementKey: key,
-				format: placement.format,
-			});
-		}
-
-		byKey.set(key, { ...placement, key });
-	}
-
-	const timeouts = resolveTimeouts({
-		timeouts: config.timeouts,
-		adValidityMs: config.adValidityMs,
-		appOpenValidityMs: config.appOpenValidityMs,
-		undecidedWarningMs: config.undecidedWarningMs,
-	});
-	const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
-
-	// Resolved eagerly, for every placement, so an out-of-bounds override fails
-	// at construction rather than on the first failed load in production — which
-	// is the one moment nobody is watching for a configuration error.
-	const retryByKey = new Map<string, ResolvedRetryPolicy | null>();
-	for (const [key, placement] of byKey) {
-		retryByKey.set(key, resolveEffectiveRetry(config.retry, placement.retry, key));
-	}
-
-	const isProduction = config.environment === 'production';
-	const { consentTesting, ignoredConsentTools } = resolveConsentTesting(
-		config.consentTesting,
-		isProduction,
-	);
-
-	return {
-		enablement: toEnablement(config.enabled),
-		environment: config.environment,
-		placements: byKey,
-		catalog,
-		timeouts,
-		// FR-014: debug and test-device settings must not be able to alter
-		// production behavior, so they are dropped rather than carried and
-		// conditionally ignored somewhere further down.
-		testDeviceIds: isProduction ? [] : [...(config.testDeviceIds ?? [])],
-		retryByKey,
-		consentTesting,
-		ignoredConsentTools,
-	};
-}
-
-/**
- * Neutralizes the consent testing tools in production (FR-113).
- *
- * Dropped here, at the single validation point, rather than checked wherever
- * they are used. That is what makes the guarantee provable: a rule enforced in
- * one place can be asserted by a test, while one spread across the consent
- * module's call sites is a hope. It is the same reasoning that makes the ad-unit
- * substitution guarantee hold, and it is why both are enforced identically.
- *
- * The names of what was dropped are returned rather than only logged, so an
- * automated test — and the demo app's diagnostics screen — can see it.
- */
-function resolveConsentTesting(
-	testing: ConsentTestingOptions | undefined,
-	isProduction: boolean,
-): { consentTesting: ConsentTestingOptions | undefined; ignoredConsentTools: readonly string[] } {
-	if (!testing || !isProduction) {
-		return { consentTesting: testing, ignoredConsentTools: [] };
-	}
-
-	const ignored: string[] = [];
-	if (testing.debugGeography !== undefined && testing.debugGeography !== 'disabled') {
-		ignored.push('debugGeography');
-	}
-	if (testing.resetOnStart === true) {
-		ignored.push('resetOnStart');
-	}
-	return { consentTesting: undefined, ignoredConsentTools: ignored };
-}
+/**
+ * Catalog and configuration validation (FR-008), plus the fail-closed check
+ * that substitution cannot cover (FR-012).
+ *
+ * Configuration faults throw rather than returning a result. They mean the app
+ * is wired wrong, and no runtime status could describe a usable outcome — every
+ * other failure in this package is a typed result instead.
+ *
+ * Every message names the offending placement key. An error that says only
+ * "invalid configuration" makes the integrator hunt through a catalog by hand.
+ */
+
+import { AdsConfigError } from '../diagnostics/errors';
+import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
+import { checkBand, resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
+import {
+	defaultMinRequestIntervalMs,
+	MIN_REQUEST_INTERVAL_BOUNDS,
+} from '../core/requestThrottle';
+import { toEnablement } from '../core/enablement';
+import { resolveEffectiveRetry, type ResolvedRetryPolicy } from '../core/retryPolicy';
+import type {
+	AdFormat,
+	AdsConfig,
+	ConsentTestingOptions,
+	Enablement,
+	Environment,
+	PlacementDefinition,
+} from './types';
+
+const FORMATS: ReadonlySet<string> = new Set<AdFormat>([
+	'banner',
+	'interstitial',
+	'rewarded',
+	'app_open',
+]);
+
+export interface ValidateOptions {
+	/**
+	 * Whether this is a debug build. Injected rather than read from `__DEV__`
+	 * directly so the fail-closed rule is testable without manipulating a global
+	 * the test runner also depends on.
+	 */
+	readonly isDevBuild: boolean;
+}
+
+export interface ResolvedConfig {
+	readonly enablement: Enablement;
+	readonly environment: Environment;
+	readonly placements: ReadonlyMap<string, PlacementDefinition>;
+	readonly catalog: ResolvedCatalog;
+	readonly timeouts: ResolvedTimeouts;
+	/** Empty in production regardless of what was configured (FR-014). */
+	readonly testDeviceIds: readonly string[];
+	/** Effective retry per placement. `null` means retry is off there (FR-134). */
+	readonly retryByKey: ReadonlyMap<string, ResolvedRetryPolicy | null>;
+	/**
+	 * Effective minimum interval between provider requests, per placement
+	 * (FR-140). Zero means the throttle is off for that placement.
+	 */
+	readonly minRequestIntervalByKey: ReadonlyMap<string, number>;
+	/** Stripped entirely in production (FR-113). */
+	readonly consentTesting: ConsentTestingOptions | undefined;
+	/**
+	 * Which consent tools were dropped because the environment is production.
+	 * Surfaced so the inertness is observable rather than merely documented —
+	 * the same treatment FR-011a gives substituted ad units.
+	 */
+	readonly ignoredConsentTools: readonly string[];
+}
+
+export function validateConfig(config: AdsConfig, options: ValidateOptions): ResolvedConfig {
+	// FR-012. Substitution deliberately does not apply in production, so a debug
+	// build declaring `production` is the one case it cannot make safe: it would
+	// send real requests from a build that should never generate traffic. Fail
+	// closed rather than continue.
+	if (config.environment === 'production' && options.isDevBuild) {
+		throw new AdsConfigError('production_in_dev_build', {
+			message:
+				'environment is "production" but this is a development build. ' +
+				'Non-production builds must declare "development" or "test" so the package can ' +
+				'substitute official Google test ad units and keep production traffic impossible.',
+		});
+	}
+
+	if (!Array.isArray(config.placements) || config.placements.length === 0) {
+		throw new AdsConfigError('invalid_config', {
+			message: 'placements must be a non-empty array; the package can show nothing without one',
+		});
+	}
+
+	const byKey = new Map<string, PlacementDefinition>();
+
+	for (const placement of config.placements) {
+		const key = typeof placement?.key === 'string' ? placement.key.trim() : '';
+
+		if (!key) {
+			throw new AdsConfigError('invalid_config', {
+				message: 'every placement needs a non-empty key',
+			});
+		}
+
+		if (byKey.has(key)) {
+			// Rejecting the whole catalog rather than picking a winner: a repeated
+			// key means the app's own naming produced two placements for one slot,
+			// and the package has no basis to guess which was meant.
+			throw new AdsConfigError('duplicate_placement_key', {
+				message: `duplicate placement key "${key}"`,
+				placementKey: key,
+			});
+		}
+
+		if (!FORMATS.has(placement.format)) {
+			throw new AdsConfigError('invalid_config', {
+				message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
+				placementKey: key,
+			});
+		}
+
+		if (!placement.androidAdUnitId || !placement.androidAdUnitId.trim()) {
+			throw new AdsConfigError('missing_ad_unit_id', {
+				message: `placement "${key}" is missing androidAdUnitId`,
+				placementKey: key,
+				format: placement.format,
+			});
+		}
+
+		byKey.set(key, { ...placement, key });
+	}
+
+	const timeouts = resolveTimeouts({
+		timeouts: config.timeouts,
+		adValidityMs: config.adValidityMs,
+		appOpenValidityMs: config.appOpenValidityMs,
+		undecidedWarningMs: config.undecidedWarningMs,
+	});
+	const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
+
+	// Resolved eagerly, for every placement, so an out-of-bounds override fails
+	// at construction rather than on the first failed load in production — which
+	// is the one moment nobody is watching for a configuration error.
+	const retryByKey = new Map<string, ResolvedRetryPolicy | null>();
+	// Resolved in the same loop and for the same reason: an out-of-bounds floor
+	// must fail at construction, not silently refuse every request in production.
+	const minRequestIntervalByKey = new Map<string, number>();
+	for (const [key, placement] of byKey) {
+		retryByKey.set(key, resolveEffectiveRetry(config.retry, placement.retry, key));
+		minRequestIntervalByKey.set(
+			key,
+			placement.minRequestIntervalMs === undefined
+				? defaultMinRequestIntervalMs(placement.format)
+				: checkBand(
+						`placements["${key}"].minRequestIntervalMs`,
+						placement.minRequestIntervalMs,
+						MIN_REQUEST_INTERVAL_BOUNDS,
+					),
+		);
+	}
+
+	const isProduction = config.environment === 'production';
+	const { consentTesting, ignoredConsentTools } = resolveConsentTesting(
+		config.consentTesting,
+		isProduction,
+	);
+
+	return {
+		enablement: toEnablement(config.enabled),
+		environment: config.environment,
+		placements: byKey,
+		catalog,
+		timeouts,
+		// FR-014: debug and test-device settings must not be able to alter
+		// production behavior, so they are dropped rather than carried and
+		// conditionally ignored somewhere further down.
+		testDeviceIds: isProduction ? [] : [...(config.testDeviceIds ?? [])],
+		retryByKey,
+		minRequestIntervalByKey,
+		consentTesting,
+		ignoredConsentTools,
+	};
+}
+
+/**
+ * Neutralizes the consent testing tools in production (FR-113).
+ *
+ * Dropped here, at the single validation point, rather than checked wherever
+ * they are used. That is what makes the guarantee provable: a rule enforced in
+ * one place can be asserted by a test, while one spread across the consent
+ * module's call sites is a hope. It is the same reasoning that makes the ad-unit
+ * substitution guarantee hold, and it is why both are enforced identically.
+ *
+ * The names of what was dropped are returned rather than only logged, so an
+ * automated test — and the demo app's diagnostics screen — can see it.
+ */
+function resolveConsentTesting(
+	testing: ConsentTestingOptions | undefined,
+	isProduction: boolean,
+): { consentTesting: ConsentTestingOptions | undefined; ignoredConsentTools: readonly string[] } {
+	if (!testing || !isProduction) {
+		return { consentTesting: testing, ignoredConsentTools: [] };
+	}
+
+	const ignored: string[] = [];
+	if (testing.debugGeography !== undefined && testing.debugGeography !== 'disabled') {
+		ignored.push('debugGeography');
+	}
+	if (testing.resetOnStart === true) {
+		ignored.push('resetOnStart');
+	}
+	return { consentTesting: undefined, ignoredConsentTools: ignored };
+}