@chipmobilesdk/rn-ads 0.4.0 → 0.5.1

package/src/core/retryPolicy.ts

@@ -1,127 +1,127 @@
-/**
- * Bounded, opt-in retry for failed loads (FR-134 – FR-139).
- *
- * 0.1.0 shipped no retry on purpose, and the reason was sound: every retry is a
- * billable request, and only the app knows what that costs. But the practical
- * result was that every app rewrote the same backoff loop, and the cost of
- * writing it wrong landed on a bill. This ships the loop once, keeps it **off by
- * default**, and makes every attempt visible.
- *
- * Three properties do the work:
- *
- *   - Off unless configured, so upgrading from 0.1.0 issues not one extra
- *     request (FR-134, and the compat test proves it rather than asserting it).
- *   - Only `retryable` errors. Configuration and consent errors, an unsupported
- *     platform, and a disabled or undecided instance are states another attempt
- *     cannot change, so retrying them would spend money on a certainty (FR-135).
- *   - Every attempt is an event carrying the load cycle's correlation id, so a
- *     bill can be reconciled against the event stream alone (FR-138).
- *
- * Pure — the schedule is computed here, the waiting happens in the instance's
- * TimerSet so `dispose()` can prove it released everything.
- */
-
-import { AdsConfigError } from '../diagnostics/errors';
-import { checkBand, DEFAULT_RETRY_POLICY, RETRY_BOUNDS } from './timers';
-import type { RetryPolicy } from '../config/types';
-
-export interface ResolvedRetryPolicy {
-	readonly maxRetries: number;
-	readonly initialDelayMs: number;
-	readonly maxDelayMs: number;
-}
-
-/**
- * Validates one policy against the bounds.
- *
- * Out-of-range values **throw** rather than being clamped, matching the rule
- * `timers.ts` already follows: silently clamping a request for ten retries down
- * to five tells the app it configured something it did not, and the discrepancy
- * only surfaces later as a bill that does not match the code.
- *
- * `label` names the offending field precisely — an error that says only
- * "invalid retry policy" makes an integrator hunt through a catalog by hand.
- */
-export function resolveRetryPolicy(policy: RetryPolicy, label: string): ResolvedRetryPolicy {
-	const maxRetries = checkBand(
-		`${label}.maxRetries`,
-		policy.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
-		RETRY_BOUNDS.maxRetries,
-	);
-	const initialDelayMs = checkBand(
-		`${label}.initialDelayMs`,
-		policy.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs,
-		RETRY_BOUNDS.initialDelayMs,
-	);
-	const maxDelayMs = checkBand(
-		`${label}.maxDelayMs`,
-		policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
-		RETRY_BOUNDS.maxDelayMs,
-	);
-
-	if (!Number.isInteger(maxRetries)) {
-		throw new AdsConfigError('retry_out_of_bounds', {
-			message: `${label}.maxRetries must be a whole number; received ${maxRetries}`,
-		});
-	}
-	if (initialDelayMs > maxDelayMs) {
-		throw new AdsConfigError('retry_out_of_bounds', {
-			message: `${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms); the first retry would already be past the ceiling`,
-		});
-	}
-
-	return { maxRetries, initialDelayMs, maxDelayMs };
-}
-
-/**
- * Resolves the effective policy for one placement.
- *
- * An override **replaces** the instance-wide policy rather than merging into it.
- * Merging would mean the effective policy for a placement could not be read off
- * the configuration — you would have to simulate the merge to know what it was —
- * and a per-field merge makes "this placement retries twice" quietly depend on a
- * value written somewhere else.
- *
- * Both are validated against the same bounds, so an override narrows behavior
- * but can never exceed a ceiling (FR-136a).
- */
-export function resolveEffectiveRetry(
-	instancePolicy: RetryPolicy | undefined,
-	placementPolicy: RetryPolicy | false | undefined,
-	placementKey: string,
-): ResolvedRetryPolicy | null {
-	if (placementPolicy === false) {
-		// Explicit opt-out for this placement alone. A banner retry is cheap and
-		// invisible; a rewarded retry happens with a user waiting on the other
-		// side of it. An app may reasonably want one and not the other.
-		return null;
-	}
-	if (placementPolicy) {
-		return resolveRetryPolicy(placementPolicy, `placements.${placementKey}.retry`);
-	}
-	if (instancePolicy) {
-		return resolveRetryPolicy(instancePolicy, 'retry');
-	}
-	// Nothing configured anywhere: retry is entirely off, which is the default
-	// and the only behavior a 0.1.0 consumer can observe (FR-134).
-	return null;
-}
-
-/**
- * Delay before the given attempt. `attempt` is 1-based — the first retry is 1.
- *
- * Exponential with a fixed x2 multiplier and **no jitter**. Jitter exists to
- * desynchronize a fleet of clients hitting one server; a single device retrying
- * its own load has no herd to avoid. Leaving it out keeps "two retries, 2s then
- * 4s" an exact assertion instead of a statistical one, which matters more here
- * than a property that does not apply.
- */
-export function delayForAttempt(policy: ResolvedRetryPolicy, attempt: number): number {
-	const raw = policy.initialDelayMs * Math.pow(2, Math.max(0, attempt - 1));
-	return Math.min(raw, policy.maxDelayMs);
-}
-
-/** Whether another attempt is permitted. `attemptsMade` counts retries only. */
-export function canRetry(policy: ResolvedRetryPolicy | null, attemptsMade: number): boolean {
-	return policy !== null && attemptsMade < policy.maxRetries;
-}
+/**
+ * Bounded, opt-in retry for failed loads (FR-134 – FR-139).
+ *
+ * 0.1.0 shipped no retry on purpose, and the reason was sound: every retry is a
+ * billable request, and only the app knows what that costs. But the practical
+ * result was that every app rewrote the same backoff loop, and the cost of
+ * writing it wrong landed on a bill. This ships the loop once, keeps it **off by
+ * default**, and makes every attempt visible.
+ *
+ * Three properties do the work:
+ *
+ *   - Off unless configured, so upgrading from 0.1.0 issues not one extra
+ *     request (FR-134, and the compat test proves it rather than asserting it).
+ *   - Only `retryable` errors. Configuration and consent errors, an unsupported
+ *     platform, and a disabled or undecided instance are states another attempt
+ *     cannot change, so retrying them would spend money on a certainty (FR-135).
+ *   - Every attempt is an event carrying the load cycle's correlation id, so a
+ *     bill can be reconciled against the event stream alone (FR-138).
+ *
+ * Pure — the schedule is computed here, the waiting happens in the instance's
+ * TimerSet so `dispose()` can prove it released everything.
+ */
+
+import { AdsConfigError } from '../diagnostics/errors';
+import { checkBand, DEFAULT_RETRY_POLICY, RETRY_BOUNDS } from './timers';
+import type { RetryPolicy } from '../config/types';
+
+export interface ResolvedRetryPolicy {
+	readonly maxRetries: number;
+	readonly initialDelayMs: number;
+	readonly maxDelayMs: number;
+}
+
+/**
+ * Validates one policy against the bounds.
+ *
+ * Out-of-range values **throw** rather than being clamped, matching the rule
+ * `timers.ts` already follows: silently clamping a request for ten retries down
+ * to five tells the app it configured something it did not, and the discrepancy
+ * only surfaces later as a bill that does not match the code.
+ *
+ * `label` names the offending field precisely — an error that says only
+ * "invalid retry policy" makes an integrator hunt through a catalog by hand.
+ */
+export function resolveRetryPolicy(policy: RetryPolicy, label: string): ResolvedRetryPolicy {
+	const maxRetries = checkBand(
+		`${label}.maxRetries`,
+		policy.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+		RETRY_BOUNDS.maxRetries,
+	);
+	const initialDelayMs = checkBand(
+		`${label}.initialDelayMs`,
+		policy.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs,
+		RETRY_BOUNDS.initialDelayMs,
+	);
+	const maxDelayMs = checkBand(
+		`${label}.maxDelayMs`,
+		policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+		RETRY_BOUNDS.maxDelayMs,
+	);
+
+	if (!Number.isInteger(maxRetries)) {
+		throw new AdsConfigError('retry_out_of_bounds', {
+			message: `${label}.maxRetries must be a whole number; received ${maxRetries}`,
+		});
+	}
+	if (initialDelayMs > maxDelayMs) {
+		throw new AdsConfigError('retry_out_of_bounds', {
+			message: `${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms); the first retry would already be past the ceiling`,
+		});
+	}
+
+	return { maxRetries, initialDelayMs, maxDelayMs };
+}
+
+/**
+ * Resolves the effective policy for one placement.
+ *
+ * An override **replaces** the instance-wide policy rather than merging into it.
+ * Merging would mean the effective policy for a placement could not be read off
+ * the configuration — you would have to simulate the merge to know what it was —
+ * and a per-field merge makes "this placement retries twice" quietly depend on a
+ * value written somewhere else.
+ *
+ * Both are validated against the same bounds, so an override narrows behavior
+ * but can never exceed a ceiling (FR-136a).
+ */
+export function resolveEffectiveRetry(
+	instancePolicy: RetryPolicy | undefined,
+	placementPolicy: RetryPolicy | false | undefined,
+	placementKey: string,
+): ResolvedRetryPolicy | null {
+	if (placementPolicy === false) {
+		// Explicit opt-out for this placement alone. A banner retry is cheap and
+		// invisible; a rewarded retry happens with a user waiting on the other
+		// side of it. An app may reasonably want one and not the other.
+		return null;
+	}
+	if (placementPolicy) {
+		return resolveRetryPolicy(placementPolicy, `placements.${placementKey}.retry`);
+	}
+	if (instancePolicy) {
+		return resolveRetryPolicy(instancePolicy, 'retry');
+	}
+	// Nothing configured anywhere: retry is entirely off, which is the default
+	// and the only behavior a 0.1.0 consumer can observe (FR-134).
+	return null;
+}
+
+/**
+ * Delay before the given attempt. `attempt` is 1-based — the first retry is 1.
+ *
+ * Exponential with a fixed x2 multiplier and **no jitter**. Jitter exists to
+ * desynchronize a fleet of clients hitting one server; a single device retrying
+ * its own load has no herd to avoid. Leaving it out keeps "two retries, 2s then
+ * 4s" an exact assertion instead of a statistical one, which matters more here
+ * than a property that does not apply.
+ */
+export function delayForAttempt(policy: ResolvedRetryPolicy, attempt: number): number {
+	const raw = policy.initialDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+	return Math.min(raw, policy.maxDelayMs);
+}
+
+/** Whether another attempt is permitted. `attemptsMade` counts retries only. */
+export function canRetry(policy: ResolvedRetryPolicy | null, attemptsMade: number): boolean {
+	return policy !== null && attemptsMade < policy.maxRetries;
+}

package/src/core/rewardedSession.ts

@@ -1,84 +1,84 @@
-/**
- * Rewarded session bookkeeping (FR-046 – FR-049).
- *
- * Two independent booleans, never derived from one another:
- *
- *              rewardConfirmed=false        rewardConfirmed=true
- *   dismissed=false   in progress           reward emitted, awaiting dismissal
- *   dismissed=true    dismissed_no_reward   earned
- *
- * The defect this exists to prevent is inferring "earned" from dismissal. It is
- * the most common way rewarded integrations go wrong, and it is a direct revenue
- * and fairness fault: a user who closed the ad after two seconds gets the prize,
- * and the publisher is billed for nothing.
- *
- * Tracking two flags and deriving the outcome makes both callback orderings
- * produce the same result *by construction* rather than by the provider
- * happening to fire in a convenient order (SC-007).
- */
-
-import type { Reward } from '../config/types';
-
-export type RewardedOutcome = 'in_progress' | 'earned' | 'dismissed_without_reward';
-
-export interface RewardedSession {
-	/**
-	 * Records a provider reward confirmation. Returns the reward the first time
-	 * and `null` on every repeat, which is what collapses a duplicate provider
-	 * emission into exactly one public event (FR-054).
-	 */
-	confirmReward(reward: Reward): Reward | null;
-	/** Records dismissal. Returns true the first time only. */
-	dismiss(): boolean;
-	outcome(): RewardedOutcome;
-	/** True only once the provider actually confirmed. Never inferred (FR-046). */
-	get rewardEarned(): boolean;
-	get dismissed(): boolean;
-	reward(): Reward | null;
-}
-
-export function createRewardedSession(): RewardedSession {
-	let confirmed = false;
-	let dismissed = false;
-	let earnedReward: Reward | null = null;
-
-	return {
-		confirmReward(reward) {
-			if (confirmed) {
-				return null;
-			}
-			confirmed = true;
-			earnedReward = reward;
-			return reward;
-		},
-
-		dismiss() {
-			if (dismissed) {
-				return false;
-			}
-			dismissed = true;
-			return true;
-		},
-
-		outcome() {
-			if (!dismissed) {
-				return 'in_progress';
-			}
-			// Read at dismissal time, so a reward that arrived first is honored and
-			// one that never arrives is not invented.
-			return confirmed ? 'earned' : 'dismissed_without_reward';
-		},
-
-		get rewardEarned() {
-			return confirmed;
-		},
-
-		get dismissed() {
-			return dismissed;
-		},
-
-		reward() {
-			return earnedReward;
-		},
-	};
-}
+/**
+ * Rewarded session bookkeeping (FR-046 – FR-049).
+ *
+ * Two independent booleans, never derived from one another:
+ *
+ *              rewardConfirmed=false        rewardConfirmed=true
+ *   dismissed=false   in progress           reward emitted, awaiting dismissal
+ *   dismissed=true    dismissed_no_reward   earned
+ *
+ * The defect this exists to prevent is inferring "earned" from dismissal. It is
+ * the most common way rewarded integrations go wrong, and it is a direct revenue
+ * and fairness fault: a user who closed the ad after two seconds gets the prize,
+ * and the publisher is billed for nothing.
+ *
+ * Tracking two flags and deriving the outcome makes both callback orderings
+ * produce the same result *by construction* rather than by the provider
+ * happening to fire in a convenient order (SC-007).
+ */
+
+import type { Reward } from '../config/types';
+
+export type RewardedOutcome = 'in_progress' | 'earned' | 'dismissed_without_reward';
+
+export interface RewardedSession {
+	/**
+	 * Records a provider reward confirmation. Returns the reward the first time
+	 * and `null` on every repeat, which is what collapses a duplicate provider
+	 * emission into exactly one public event (FR-054).
+	 */
+	confirmReward(reward: Reward): Reward | null;
+	/** Records dismissal. Returns true the first time only. */
+	dismiss(): boolean;
+	outcome(): RewardedOutcome;
+	/** True only once the provider actually confirmed. Never inferred (FR-046). */
+	get rewardEarned(): boolean;
+	get dismissed(): boolean;
+	reward(): Reward | null;
+}
+
+export function createRewardedSession(): RewardedSession {
+	let confirmed = false;
+	let dismissed = false;
+	let earnedReward: Reward | null = null;
+
+	return {
+		confirmReward(reward) {
+			if (confirmed) {
+				return null;
+			}
+			confirmed = true;
+			earnedReward = reward;
+			return reward;
+		},
+
+		dismiss() {
+			if (dismissed) {
+				return false;
+			}
+			dismissed = true;
+			return true;
+		},
+
+		outcome() {
+			if (!dismissed) {
+				return 'in_progress';
+			}
+			// Read at dismissal time, so a reward that arrived first is honored and
+			// one that never arrives is not invented.
+			return confirmed ? 'earned' : 'dismissed_without_reward';
+		},
+
+		get rewardEarned() {
+			return confirmed;
+		},
+
+		get dismissed() {
+			return dismissed;
+		},
+
+		reward() {
+			return earnedReward;
+		},
+	};
+}