@chipmobilesdk/rn-ads 0.2.0 → 0.3.0

package/src/core/requestThrottle.ts

@@ -0,0 +1,176 @@
+/**
+ * Per-placement request throttle (FR-140).
+ *
+ * This exists to protect the **ad account**, not to shape product behaviour, and
+ * that distinction is the whole reason it lives in the package:
+ *
+ * | Decision | Owner |
+ * |---|---|
+ * | How often to *show* an interstitial | the app — product policy |
+ * | How often the same placement may *request* | the package — account safety |
+ *
+ * Rapid repeat requests for one placement are read by ad networks as invalid
+ * traffic, and the penalty is account-level and not recoverable by shipping a
+ * fix. That puts it in the same class as the test-ad substitution the package
+ * already enforces: a safety property the library guarantees rather than
+ * documents and hopes each app remembers.
+ *
+ * ## The pattern it is built for
+ *
+ * A banner mounted inside a view the user navigates between — a day in a
+ * calendar, a tab, a row in a list — is unmounted and remounted by React on every
+ * navigation. Each remount is a fresh provider request. A user swiping quickly
+ * through ten days produces ten requests in a few seconds, and nothing about that
+ * is the app author doing something wrong.
+ *
+ * Full-screen formats do not have this problem: they are loaded by an explicit
+ * call, not mounted by a renderer. That asymmetry is why the default differs by
+ * format — see `defaultMinRequestIntervalMs`.
+ *
+ * The better *architectural* answer is to keep the banner outside the subtree that
+ * remounts. This throttle is the safety net for when that is not possible, not a
+ * licence to ignore the problem; the README says so where an app author will read
+ * it.
+ */
+
+import type { AdFormat } from '../config/types';
+
+/**
+ * AdMob's own documented floor for banner auto-refresh is 60 seconds, so
+ * requesting the same banner placement more often than that is, by the provider's
+ * own standard, more often than it considers reasonable. Taking the provider's
+ * number rather than inventing one means the default is defensible rather than
+ * arbitrary.
+ */
+export const DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = 60_000;
+
+/**
+ * Off by default for full-screen formats.
+ *
+ * `load` → `show` → `load` is the normal, healthy cycle for an interstitial, and
+ * an app that sells three things in two minutes legitimately loads three times.
+ * Throttling that by default would break correct apps to solve a problem those
+ * formats do not have. An app that wants a floor here can set one.
+ */
+export const DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = 0;
+
+export const MIN_REQUEST_INTERVAL_BOUNDS = { min: 0, max: 600_000 } as const;
+
+/** The format-aware default, applied when a placement configures nothing. */
+export function defaultMinRequestIntervalMs(format: AdFormat): number {
+	return format === 'banner'
+		? DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS
+		: DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS;
+}
+
+export type ThrottleDecision =
+	| { readonly allowed: true }
+	/**
+	 * `retryAfterMs` is reported rather than left for the caller to compute,
+	 * because the app needs it to decide between collapsing the space and holding
+	 * it — and a caller recomputing it from a timestamp would drift from the
+	 * clock this throttle actually used.
+	 */
+	| { readonly allowed: false; readonly retryAfterMs: number };
+
+export interface RequestThrottle {
+	/**
+	 * Records a request and reports whether it may proceed.
+	 *
+	 * Call immediately before handing a request to the provider.
+	 *
+	 * `token` makes the acquisition **idempotent for one request cycle**, and the
+	 * banner path depends on it. React may run a `useMemo` or an effect more than
+	 * once for a single committed render — StrictMode does it deliberately — and
+	 * without a token the second run would consume a second slot and be refused,
+	 * so a banner would never appear in development. Passing the cycle's
+	 * correlation id means "this is the same request I already asked about", and
+	 * the previous decision is returned unchanged.
+	 *
+	 * Omit `token` for a genuinely new imperative request, where every call is a
+	 * distinct intent to ask the network.
+	 */
+	tryAcquire(key: string, minIntervalMs: number, token?: string): ThrottleDecision;
+	/**
+	 * Forgets a placement's last request.
+	 *
+	 * Used when a placement's resources are released, so a genuinely new cycle is
+	 * not charged for the previous one.
+	 */
+	reset(key: string): void;
+	clear(): void;
+	/** Diagnostics only: when the placement last requested, or undefined. */
+	lastRequestAt(key: string): number | undefined;
+}
+
+export function createRequestThrottle(now: () => number): RequestThrottle {
+	const lastAt = new Map<string, number>();
+	/** The token and verdict of the most recent acquisition, for idempotency. */
+	const lastToken = new Map<string, { token: string; decision: ThrottleDecision }>();
+
+	const decide = (key: string, minIntervalMs: number): ThrottleDecision => {
+		// Zero is the documented way to turn the throttle off, so it must never
+		// consult the clock — an app that sets 0 should behave exactly as it did
+		// before this feature existed.
+		if (minIntervalMs <= 0) {
+			return { allowed: true };
+		}
+		const previous = lastAt.get(key);
+		if (previous === undefined) {
+			return { allowed: true };
+		}
+		const elapsed = now() - previous;
+		// A clock that moved backwards — a manual time change, or an NTP
+		// correction — must not lock a placement out until the clock catches up.
+		// Treating it as "enough time passed" fails open, which is right: the
+		// throttle protects against bursts, and a backwards clock is not a burst.
+		if (elapsed < 0) {
+			return { allowed: true };
+		}
+		if (elapsed >= minIntervalMs) {
+			return { allowed: true };
+		}
+		return { allowed: false, retryAfterMs: minIntervalMs - elapsed };
+	};
+
+	return {
+		tryAcquire(key, minIntervalMs, token) {
+			if (token !== undefined) {
+				const previous = lastToken.get(key);
+				if (previous?.token === token) {
+					// Same cycle asking again. Replaying the stored verdict keeps a
+					// double-invoked render from charging twice, and keeps a refused
+					// cycle refused rather than letting a retry slip through.
+					return previous.decision;
+				}
+			}
+
+			// Nothing is recorded when the throttle is off for this placement.
+			// Recording would be dead work, and it would also mean that turning the
+			// throttle on later immediately compared against a stale timestamp.
+			if (minIntervalMs <= 0) {
+				return { allowed: true };
+			}
+
+			const decision = decide(key, minIntervalMs);
+			if (decision.allowed) {
+				lastAt.set(key, now());
+			}
+			if (token !== undefined) {
+				lastToken.set(key, { token, decision });
+			}
+			return decision;
+		},
+		reset(key) {
+			lastAt.delete(key);
+			lastToken.delete(key);
+		},
+		clear() {
+			lastAt.clear();
+			lastToken.clear();
+		},
+		lastRequestAt(key) {
+			return lastAt.get(key);
+		},
+	};
+}

package/src/diagnostics/events.ts

@@ -33,6 +33,12 @@ export type AdEventType =
 	// cycle that triggered it. Each attempt is a billable request, so it has to
 	// be reconcilable against a bill from the event stream alone (FR-138).
 	| 'retry_scheduled'
+	// Emitted when the per-placement throttle refuses a request (FR-140). Carries
+	// no correlation id because no cycle began: nothing was requested, so there is
+	// nothing to correlate. Present so a throttled placement is visible in
+	// whatever logging the app already has, rather than looking like a silent
+	// absence of ads.
+	| 'request_throttled'
 	| 'internal_error';
 
 interface BaseEvent {
@@ -76,6 +82,13 @@ export type AdEvent = BaseEvent &
 				readonly delayMs: number;
 				readonly error: AdsError;
 		  }
+		| {
+				readonly type: 'request_throttled';
+				/** How long until this placement may request again. */
+				readonly retryAfterMs: number;
+				/** The configured floor that refused it, so the cause is readable. */
+				readonly minRequestIntervalMs: number;
+		  }
 		| {
 				readonly type: 'config_warning';
 				readonly warning: ConfigWarning;

package/src/index.ts

@@ -57,6 +57,16 @@ export {
 	UNDECIDED_WARNING_BOUNDS,
 } from './core/timers';
 
+// Request throttle — account safety, added in 0.3.0 (FR-140). Exported so an app
+// can read the floor it is bound by, and so the format-aware default is legible
+// rather than something to discover from a `throttled` state in production.
+export {
+	DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS,
+	DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS,
+	MIN_REQUEST_INTERVAL_BOUNDS,
+	defaultMinRequestIntervalMs,
+} from './core/requestThrottle';
+
 // Enablement. `EnablementResult` is what `setEnabled` returns in place of
 // 0.1.0's `void` — the defect that let a re-enable fail in silence (FR-122).
 export type { EnablementResult } from './core/enablement';