@chipmobilesdk/rn-ads 0.1.0

package/src/config/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Public configuration and state types (FR-001, FR-003, FR-004).
+ *
+ * Nothing here names a platform or an ad provider. That is the whole point:
+ * adding an iOS adapter later contributes an optional `iosAdUnitId` and a second
+ * engine implementation, and changes nothing a consumer already wrote (FR-006).
+ *
+ * The package persists none of this. Every value below lives for the lifetime of
+ * one instance and is released by `dispose()`.
+ */
+
+/** Formats supported in v1. App-open, native, and rewarded-interstitial are deferred. */
+export type AdFormat = 'banner' | 'interstitial' | 'rewarded';
+
+/** Formats that take over the screen, and so contend for the single-show lock. */
+export type FullScreenFormat = Extract<AdFormat, 'interstitial' | 'rewarded'>;
+
+export function isFullScreenFormat(format: AdFormat): format is FullScreenFormat {
+	return format === 'interstitial' || format === 'rewarded';
+}
+
+/**
+ * Declared by the app, because the package cannot depend on any particular
+ * configuration mechanism (FR-015). Cross-checked against the runtime dev flag
+ * so a debug build claiming `production` is caught rather than trusted (FR-012).
+ */
+export type Environment = 'development' | 'test' | 'production';
+
+/**
+ * One logical ad slot. `key` is the app's own stable name — `home_footer`, not
+ * an AdMob unit. Provider identifiers appear here in configuration and nowhere
+ * else in consumer code (FR-003, FR-007).
+ */
+export interface PlacementDefinition {
+	readonly key: string;
+	readonly format: AdFormat;
+	readonly androidAdUnitId: string;
+	/**
+	 * Additive placeholder for FR-006. Unused in v1 and never read by the Android
+	 * adapter — present so that adding iOS is a configuration change rather than a
+	 * type change for every existing consumer.
+	 */
+	readonly iosAdUnitId?: string;
+}
+
+/** Bounds exist because an unbounded timeout is the same defect as no timeout. */
+export interface TimeoutConfig {
+	readonly load?: number;
+	readonly show?: number;
+}
+
+export interface AdsConfig {
+	/** FR-009. When false, every operation is a safe no-op reporting `disabled`. */
+	readonly enabled: boolean;
+	readonly environment: Environment;
+	readonly placements: readonly PlacementDefinition[];
+	readonly timeouts?: TimeoutConfig;
+	/** How long a loaded full-screen ad stays presentable (FR-034). */
+	readonly adValidityMs?: number;
+	/** Ignored entirely in `production` (FR-014). */
+	readonly testDeviceIds?: readonly string[];
+}
+
+/** Content ratings, normalized. Maps onto the provider's own rating scale. */
+export type AdContentRating = 'G' | 'PG' | 'T' | 'MA';
+
+/**
+ * Supplied before initialization (FR-016). Never logged, never persisted
+ * (FR-021). Everything except `canRequestAds` must reach the provider before it
+ * initializes, which is why changing one afterwards reports
+ * `requires_reinitialization` rather than pretending it applied (FR-020).
+ */
+export interface PrivacyOptions {
+	/** The gate itself. False means no request may be made, for any reason. */
+	readonly canRequestAds: boolean;
+	/** Distinguishes "the user said no" from "we have not asked yet" (FR-018). */
+	readonly consentUndetermined?: boolean;
+	readonly childDirected?: boolean;
+	readonly underAgeOfConsent?: boolean;
+	readonly maxAdContentRating?: AdContentRating;
+	/** When false, the package requests non-personalized ads. */
+	readonly personalizedAds?: boolean;
+}
+
+export type PrivacyBlockReason = 'consent_required' | 'consent_undetermined';
+
+export type UnavailableReason = 'unsupported_platform' | 'provider_missing';
+
+/** FR-023. One per instance, observable without holding a provider object. */
+export type InitStatus =
+	| 'not_started'
+	| 'blocked'
+	| 'initializing'
+	| 'ready'
+	| 'disabled'
+	| 'unavailable'
+	| 'failed';
+
+/**
+ * FR-026. One per placement. Banners never reach `consumed` — they are
+ * continuous, not single-use.
+ */
+export type PlacementState =
+	| 'idle'
+	| 'loading'
+	| 'ready'
+	| 'showing'
+	| 'consumed'
+	| 'failed'
+	| 'unavailable';
+
+/** FR-047. The provider's reward descriptor, normalized. */
+export interface Reward {
+	readonly type: string;
+	readonly amount: number;
+}
+
+/** FR-005. Returned by every subscription; safe to call more than once. */
+export type Unsubscribe = () => void;

package/src/config/validate.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 type { AdFormat, AdsConfig, Environment, PlacementDefinition } from './types';
+
+const FORMATS: ReadonlySet<string> = new Set<AdFormat>(['banner', 'interstitial', 'rewarded']);
+
+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 enabled: boolean;
+	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[];
+}
+
+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)}"; v1 supports banner, interstitial, and rewarded`,
+				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(config.timeouts, config.adValidityMs);
+	const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
+
+	return {
+		enabled: config.enabled !== false,
+		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: config.environment === 'production' ? [] : [...(config.testDeviceIds ?? [])],
+	};
+}