@chipmobilesdk/rn-ads 0.4.0 → 0.5.1

package/src/config/resolveAdUnit.ts

@@ -1,85 +1,85 @@
-/**
- * The production-traffic guarantee (FR-011, FR-011a).
- *
- * A pure function, deliberately. This is the single point where a production ad
- * unit can be replaced by an official test one, which is what makes SC-002
- * provable rather than merely intended: a guarantee enforced in one place can be
- * asserted; one spread across three call sites is a hope.
- *
- * The rule, from the 2026-09-02 clarification session:
- *
- *   production            -> use what the app configured, always, no exceptions
- *   development / test    -> if it is not one of our own official test units,
- *                            replace it and say so, loudly, naming the key
- *
- * Substitution rather than rejection is a deliberate trade. Rejecting would
- * block a developer whose only mistake was pulling a teammate's environment
- * file, and turn a configuration smell into a broken integration at every
- * startup. Substituting keeps the app working — which is what a non-production
- * build is for — and reports the problem as a first-class signal. The accepted
- * cost is that a warning can be ignored; it is bounded because production never
- * substitutes, so the misconfiguration surfaces there as ordinary behavior
- * rather than as hidden state.
- */
-
-import type { Environment, PlacementDefinition } from './types';
-import { isOfficialTestAdUnit, testAdUnitFor } from '../engine/testAdUnits';
-
-export interface ResolvedAdUnit {
-	readonly effectiveAdUnitId: string;
-	/** True when the configured identifier was replaced. Drives FR-011a's warning. */
-	readonly substituted: boolean;
-}
-
-export function resolveAdUnit(
-	placement: PlacementDefinition,
-	environment: Environment,
-): ResolvedAdUnit {
-	const configured = placement.androidAdUnitId;
-
-	// Production is the one environment where the package must not second-guess
-	// the app. Substituting here would silently rewrite configuration that was
-	// asked for on purpose, and would cost the publisher live revenue.
-	if (environment === 'production') {
-		return { effectiveAdUnitId: configured, substituted: false };
-	}
-
-	// Structural detection: anything that is not a known official test unit is
-	// treated as production-owned. Not a parse of AdMob's publisher-id format —
-	// see the note in engine/testAdUnits.ts on why that rule would be a liability.
-	if (isOfficialTestAdUnit(configured)) {
-		return { effectiveAdUnitId: configured, substituted: false };
-	}
-
-	return { effectiveAdUnitId: testAdUnitFor(placement.format), substituted: true };
-}
-
-export interface ResolvedCatalog {
-	/** Placement key to the ad unit that will actually be requested. */
-	readonly byKey: ReadonlyMap<string, string>;
-	/** Every key whose identifier was replaced, in catalog order (FR-011a). */
-	readonly substitutedKeys: readonly string[];
-}
-
-/**
- * Resolves a whole catalog at once, so the warning can name every affected
- * placement in a single event rather than trickling one out per load — an
- * integrator wants to fix the whole file, not discover it a placement at a time.
- */
-export function resolvePlacementAdUnits(
-	placements: readonly PlacementDefinition[],
-	environment: Environment,
-): ResolvedCatalog {
-	const byKey = new Map<string, string>();
-	const substitutedKeys: string[] = [];
-
-	for (const placement of placements) {
-		const resolved = resolveAdUnit(placement, environment);
-		byKey.set(placement.key, resolved.effectiveAdUnitId);
-		if (resolved.substituted) {
-			substitutedKeys.push(placement.key);
-		}
-	}
-
-	return { byKey, substitutedKeys };
-}
+/**
+ * The production-traffic guarantee (FR-011, FR-011a).
+ *
+ * A pure function, deliberately. This is the single point where a production ad
+ * unit can be replaced by an official test one, which is what makes SC-002
+ * provable rather than merely intended: a guarantee enforced in one place can be
+ * asserted; one spread across three call sites is a hope.
+ *
+ * The rule, from the 2026-09-02 clarification session:
+ *
+ *   production            -> use what the app configured, always, no exceptions
+ *   development / test    -> if it is not one of our own official test units,
+ *                            replace it and say so, loudly, naming the key
+ *
+ * Substitution rather than rejection is a deliberate trade. Rejecting would
+ * block a developer whose only mistake was pulling a teammate's environment
+ * file, and turn a configuration smell into a broken integration at every
+ * startup. Substituting keeps the app working — which is what a non-production
+ * build is for — and reports the problem as a first-class signal. The accepted
+ * cost is that a warning can be ignored; it is bounded because production never
+ * substitutes, so the misconfiguration surfaces there as ordinary behavior
+ * rather than as hidden state.
+ */
+
+import type { Environment, PlacementDefinition } from './types';
+import { isOfficialTestAdUnit, testAdUnitFor } from '../engine/testAdUnits';
+
+export interface ResolvedAdUnit {
+	readonly effectiveAdUnitId: string;
+	/** True when the configured identifier was replaced. Drives FR-011a's warning. */
+	readonly substituted: boolean;
+}
+
+export function resolveAdUnit(
+	placement: PlacementDefinition,
+	environment: Environment,
+): ResolvedAdUnit {
+	const configured = placement.androidAdUnitId;
+
+	// Production is the one environment where the package must not second-guess
+	// the app. Substituting here would silently rewrite configuration that was
+	// asked for on purpose, and would cost the publisher live revenue.
+	if (environment === 'production') {
+		return { effectiveAdUnitId: configured, substituted: false };
+	}
+
+	// Structural detection: anything that is not a known official test unit is
+	// treated as production-owned. Not a parse of AdMob's publisher-id format —
+	// see the note in engine/testAdUnits.ts on why that rule would be a liability.
+	if (isOfficialTestAdUnit(configured)) {
+		return { effectiveAdUnitId: configured, substituted: false };
+	}
+
+	return { effectiveAdUnitId: testAdUnitFor(placement.format), substituted: true };
+}
+
+export interface ResolvedCatalog {
+	/** Placement key to the ad unit that will actually be requested. */
+	readonly byKey: ReadonlyMap<string, string>;
+	/** Every key whose identifier was replaced, in catalog order (FR-011a). */
+	readonly substitutedKeys: readonly string[];
+}
+
+/**
+ * Resolves a whole catalog at once, so the warning can name every affected
+ * placement in a single event rather than trickling one out per load — an
+ * integrator wants to fix the whole file, not discover it a placement at a time.
+ */
+export function resolvePlacementAdUnits(
+	placements: readonly PlacementDefinition[],
+	environment: Environment,
+): ResolvedCatalog {
+	const byKey = new Map<string, string>();
+	const substitutedKeys: string[] = [];
+
+	for (const placement of placements) {
+		const resolved = resolveAdUnit(placement, environment);
+		byKey.set(placement.key, resolved.effectiveAdUnitId);
+		if (resolved.substituted) {
+			substitutedKeys.push(placement.key);
+		}
+	}
+
+	return { byKey, substitutedKeys };
+}