@chipmobilesdk/rn-ads 0.5.1 → 0.7.0

package/src/core/instance/types.ts

@@ -0,0 +1,198 @@
+/**
+ * The ads instance's public contract: what `createAds` returns and what each
+ * operation reports. Implementation lives beside this file, one module per
+ * responsibility (ADS-10).
+ */
+import type { AdsError } from '../../diagnostics/errors';
+import type {
+	ConsentSnapshot,
+	Enablement,
+	InitStatus,
+	PlacementState,
+	PrivacyBlockReason,
+	PrivacyOptions,
+	UnavailableReason,
+	Unsubscribe,
+} from '../../config/types';
+import type { AdEventListener } from '../../diagnostics/events';
+import type { AdsEngine } from '../../engine/port';
+import type { EnablementResult } from '../enablement';
+import type { Scheduler } from '../timers';
+
+export type InitResult =
+	| { readonly status: 'ready' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'disabled' }
+	/** The app has not decided whether ads are on. Nothing was requested (FR-115). */
+	| { readonly status: 'undecided' }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export type PrivacyUpdateResult =
+	| { readonly status: 'applied' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'requires_reinitialization' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	/**
+	 * The initialization this update triggered failed (added in 0.5.0). Before,
+	 * it was reported as `applied`, so the app never retried and no ad ever
+	 * showed, with nothing to say why.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export type LoadResult =
+	| { readonly status: 'loaded'; readonly correlationId: string }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'no_fill' }
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Nothing was requested and nothing is broken — this placement asked too
+	 * recently. Distinct from `no_fill` on purpose: no-fill means the network had
+	 * nothing to give, this means we did not ask. An app that treats them the same
+	 * will misdiagnose the first time a banner goes quiet.
+	 */
+	| ThrottledResult
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export interface ThrottledResult {
+	readonly status: 'throttled';
+	readonly retryAfterMs: number;
+}
+
+/** A gate refusal: what a load gets when it may not ask at all. */
+export type LoadRefusal = Extract<
+	LoadResult,
+	{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
+>;
+
+export type ShowResult =
+	| { readonly status: 'shown'; readonly correlationId: string }
+	| { readonly status: 'not_ready' }
+	| { readonly status: 'busy' }
+	| { readonly status: 'consumed' }
+	| { readonly status: 'app_inactive' }
+	/**
+	 * The user came back to the app from an ad, or from a browser an ad opened,
+	 * so an app-open ad would be an ad immediately after an ad. Distinct from
+	 * `busy` and `not_ready` because the app cannot detect this itself and
+	 * therefore cannot infer it from either of those (FR-128).
+	 */
+	| { readonly status: 'ad_originated_return' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+/**
+ * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ *
+ * Every refusal is its own member, so an app can tell "there is nothing to
+ * offer here" from "you asked too early" from "it broke" without parsing an
+ * error. None of them throws.
+ */
+export type PrivacyOptionsFormResult =
+	/**
+	 * The provider's form was presented and has closed. `consent` is the state it
+	 * left behind, already applied to the gate. A user who closed the form without
+	 * changing anything lands here too, with the state they already had.
+	 */
+	| { readonly status: 'shown'; readonly consent: ConsentSnapshot }
+	/** The provider does not require privacy options here. Nothing was presented. */
+	| { readonly status: 'not_required' }
+	/**
+	 * The requirement is not known yet: no successful `requestInfoUpdate()` since
+	 * the instance was created or reset, or the last one failed. Nothing was
+	 * presented.
+	 */
+	| { readonly status: 'info_update_required' }
+	/** A consent form is already on screen. Nothing was presented. */
+	| { readonly status: 'busy' }
+	/**
+	 * The form could not be presented or failed while open. The consent state is
+	 * whatever the provider reports it still holds, and never a new grant.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+
+/**
+ * The optional consent capability (FR-101).
+ *
+ * Grouped under its own namespace rather than flattened onto the instance so
+ * that FR-102's optionality stays legible: an app that never touches
+ * `ads.consent` never starts a flow. Five loose methods on the instance would
+ * invite the assumption that they are part of the normal path.
+ */
+export interface ConsentApi {
+	/** Refreshes consent information from the provider. */
+	requestInfoUpdate(): Promise<ConsentSnapshot>;
+	/** Presents the provider's form if one is required. Renders nothing itself. */
+	showFormIfRequired(): Promise<ConsentSnapshot>;
+	/**
+	 * Presents the provider's privacy options form, so a user can change an
+	 * answer already given (FR-151). Added in 0.4.0.
+	 *
+	 * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
+	 * the entry point lives, and what it says, stay the app's. The outcome feeds
+	 * the privacy gate by itself, exactly as `showFormIfRequired` does.
+	 */
+	showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
+	getState(): ConsentSnapshot;
+	subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
+	/** Clears the stored decision. Inert in production (FR-113). */
+	reset(): Promise<void>;
+}
+
+export interface AdsInstance {
+	initialize(privacy: PrivacyOptions): Promise<InitResult>;
+	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+	/**
+	 * Turns ads on or off. Returns a result rather than `void` (FR-122).
+	 *
+	 * 0.1.0 returned nothing, which meant an app re-enabling ads after a lapsed
+	 * subscription had no way to learn that it also had to re-initialize — and
+	 * every load and show after that was refused in silence.
+	 */
+	setEnabled(enabled: boolean): EnablementResult;
+	/** The same, including the third state the app has not resolved yet. */
+	setEnablement(next: Enablement): EnablementResult;
+	setAppActive(active: boolean): void;
+	readonly consent: ConsentApi;
+	getStatus(): InitStatus;
+	subscribeStatus(listener: (status: InitStatus) => void): Unsubscribe;
+
+	load(placementKey: string): Promise<LoadResult>;
+	show(placementKey: string): Promise<ShowResult>;
+	getPlacementState(placementKey: string): PlacementState;
+	subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
+
+	subscribeEvents(listener: AdEventListener): Unsubscribe;
+
+	/** FR-011a — substitution is observable state, not only a log line. */
+	getSubstitutedPlacements(): readonly string[];
+	/** FR-113 — the same treatment for consent tools dropped in production. */
+	getIgnoredConsentTools(): readonly string[];
+	dispose(): void;
+}
+
+export interface CreateAdsOptions {
+	/** Injected in tests; the AdMob adapter is the default in production. */
+	readonly engine?: AdsEngine;
+	/** Injected so the FR-012 rule is testable without touching a global. */
+	readonly isDevBuild?: boolean;
+	readonly now?: () => number;
+	/**
+	 * Injected so retry backoff, app-open expiry, and the undecided warning can
+	 * be driven by a test clock instead of by waiting. Production uses real
+	 * timers.
+	 */
+	readonly scheduler?: Scheduler;
+}

package/src/core/requestThrottle.ts

@@ -83,24 +83,21 @@ export interface RequestThrottle {
 	 * 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.
+	 * so a banner would never appear in development. Passing the banner mount's
+	 * token 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.
+	 * How long until this placement may ask again, without taking a slot: 0 when
+	 * it may ask now. A load retry waits at least this long, so a retry policy
+	 * cannot request faster than the floor allows (ADS-07).
 	 */
-	reset(key: string): void;
+	waitFor(key: string, minIntervalMs: number): number;
 	clear(): void;
-	/** Diagnostics only: when the placement last requested, or undefined. */
-	lastRequestAt(key: string): number | undefined;
 }
 
 export function createRequestThrottle(now: () => number): RequestThrottle {
@@ -134,6 +131,10 @@ export function createRequestThrottle(now: () => number): RequestThrottle {
 	};
 
 	return {
+		waitFor(key, minIntervalMs) {
+			const decision = decide(key, minIntervalMs);
+			return decision.allowed ? 0 : decision.retryAfterMs;
+		},
 		tryAcquire(key, minIntervalMs, token) {
 			if (token !== undefined) {
 				const previous = lastToken.get(key);
@@ -161,16 +162,9 @@ export function createRequestThrottle(now: () => number): RequestThrottle {
 			}
 			return decision;
 		},
-		reset(key) {
-			lastAt.delete(key);
-			lastToken.delete(key);
-		},
 		clear() {
 			lastAt.clear();
 			lastToken.clear();
 		},
-		lastRequestAt(key) {
-			return lastAt.get(key);
-		},
 	};
 }

package/src/core/retryPolicy.ts

@@ -21,6 +21,8 @@
  * TimerSet so `dispose()` can prove it released everything.
  */
 
+import { computeBackoff } from '@chipmobilesdk/rn-core';
+
 import { AdsConfigError } from '../diagnostics/errors';
 import { checkBand, DEFAULT_RETRY_POLICY, RETRY_BOUNDS } from './timers';
 import type { RetryPolicy } from '../config/types';
@@ -47,16 +49,20 @@ export function resolveRetryPolicy(policy: RetryPolicy, label: string): Resolved
 		`${label}.maxRetries`,
 		policy.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
 		RETRY_BOUNDS.maxRetries,
+		'retry_out_of_bounds',
+		'',
 	);
 	const initialDelayMs = checkBand(
 		`${label}.initialDelayMs`,
 		policy.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs,
 		RETRY_BOUNDS.initialDelayMs,
+		'retry_out_of_bounds',
 	);
 	const maxDelayMs = checkBand(
 		`${label}.maxDelayMs`,
 		policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
 		RETRY_BOUNDS.maxDelayMs,
+		'retry_out_of_bounds',
 	);
 
 	if (!Number.isInteger(maxRetries)) {
@@ -117,8 +123,12 @@ export function resolveEffectiveRetry(
  * 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);
+	return computeBackoff(attempt, {
+		initialDelayMs: policy.initialDelayMs,
+		maxDelayMs: policy.maxDelayMs,
+		factor: 2,
+		jitter: 'none',
+	});
 }
 
 /** Whether another attempt is permitted. `attemptsMade` counts retries only. */

package/src/core/timers.ts

@@ -8,8 +8,10 @@
  * something it did not (FR-008).
  */
 
-import { AdsConfigError } from '../diagnostics/errors';
-import type { TimeoutConfig, Unsubscribe } from '../config/types';
+import { checkRange, type Range } from '@chipmobilesdk/rn-core';
+
+import { AdsConfigError, type AdsErrorCode } from '../diagnostics/errors';
+import type { TimeoutConfig } from '../config/types';
 
 /** Comfortably longer than a normal fill on a slow mobile network, still bounded. */
 export const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
@@ -96,17 +98,19 @@ export interface ResolvedTimeouts {
 	readonly undecidedWarning: number;
 }
 
+/**
+ * `value` when it is inside `bounds`, else an `AdsConfigError` with `code`: each
+ * field reports the code its documentation names, so a retry policy out of bounds
+ * is `retry_out_of_bounds`, not a timeout's code (CORE-04, ADS-16).
+ */
 export function checkBand(
 	label: string,
 	value: number,
-	bounds: { readonly min: number; readonly max: number },
+	bounds: Range,
+	code: AdsErrorCode = 'timeout_out_of_bounds',
+	unit = 'ms',
 ): number {
-	if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
-		throw new AdsConfigError('timeout_out_of_bounds', {
-			message: `${label} must be between ${bounds.min}ms and ${bounds.max}ms; received ${value}`,
-		});
-	}
-	return value;
+	return checkRange(label, value, bounds, message => new AdsConfigError(code, { message }), unit);
 }
 
 export interface TimeoutInput {
@@ -148,67 +152,11 @@ export function resolveTimeouts(input: TimeoutInput): ResolvedTimeouts {
 }
 
 /**
- * How timers are actually scheduled.
- *
- * Injectable so a test can drive retry backoff, app-open expiry, and the
- * undecided warning by moving a clock rather than by waiting. The production
- * default is `setTimeout`; the fake engine supplies a controllable one. Without
- * this, every timing assertion in the suite would either sleep for real or
- * depend on the test runner's timer mocking, and NFR-103's "no device, no
- * network" would quietly become "no device, no network, but several seconds".
+ * How timers are scheduled, and the set that tracks them so `dispose()` can prove
+ * it released every one (SC-008): rn-core's, injectable so a test drives retry
+ * backoff, app-open expiry and the undecided warning by moving a clock.
  */
-export interface Scheduler {
-	setTimeout(callback: () => void, ms: number): unknown;
-	clearTimeout(handle: unknown): void;
-}
-
-const realScheduler: Scheduler = {
-	setTimeout: (callback, ms) => setTimeout(callback, ms),
-	clearTimeout: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
-
-/**
- * Tracks every timer the instance owns so `dispose()` can prove it released
- * them. Counting is not incidental — SC-008 asserts the count reaches zero, and
- * a leaked timer is otherwise invisible until it fires into a disposed consumer.
- */
-export interface TimerSet {
-	after(ms: number, callback: () => void): Unsubscribe;
-	clearAll(): void;
-	size(): number;
-}
-
-export function createTimerSet(scheduler: Scheduler = realScheduler): TimerSet {
-	const handles = new Set<unknown>();
-
-	return {
-		after(ms, callback) {
-			const handle = scheduler.setTimeout(() => {
-				handles.delete(handle);
-				callback();
-			}, ms);
-			handles.add(handle);
-			let cleared = false;
-			return () => {
-				if (cleared) {
-					return;
-				}
-				cleared = true;
-				scheduler.clearTimeout(handle);
-				handles.delete(handle);
-			};
-		},
-		clearAll() {
-			for (const handle of handles) {
-				scheduler.clearTimeout(handle);
-			}
-			handles.clear();
-		},
-		size() {
-			return handles.size;
-		},
-	};
-}
+export { createTimerSet, type Scheduler, type TimerSet } from '@chipmobilesdk/rn-core';
 
 /** A loaded ad past its validity window must never be reported ready (FR-034). */
 export function isStale(loadedAtMs: number, nowMs: number, adValidityMs: number): boolean {

package/src/diagnostics/errors.ts

@@ -10,6 +10,8 @@
  * carrier for identifiers the package promises never to emit (FR-021).
  */
 
+import { SdkError, createRedactor } from '@chipmobilesdk/rn-core';
+
 import type { AdFormat } from '../config/types';
 
 export type AdsOperation = 'initialize' | 'load' | 'show' | 'configure';
@@ -58,6 +60,10 @@ export type AdsErrorCode =
 	// is a show refusal that resolves with time rather than with another attempt.
 	| 'ad_originated_return'
 	| 'provider_error'
+	// The provider refused the request itself: an invalid ad unit or request, a
+	// missing app id. Not retryable — the same request fails the same way, and
+	// retrying would spend billable requests on a certainty (FR-135, ADS-08).
+	| 'provider_rejected'
 	| 'internal_error'
 	// Configuration — a retry policy outside its bounds. Rejected rather than
 	// clamped, matching `timeout_out_of_bounds`: silently clamping tells the app
@@ -94,9 +100,8 @@ export interface AdsErrorOptions {
 	readonly cause?: unknown;
 }
 
-export class AdsError extends Error {
-	readonly code: AdsErrorCode;
-	readonly retryable: boolean;
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-ads'`. */
+export class AdsError extends SdkError<AdsErrorCode> {
 	readonly operation?: AdsOperation;
 	readonly placementKey?: string;
 	readonly format?: AdFormat;
@@ -104,15 +109,17 @@ export class AdsError extends Error {
 	readonly cause?: string;
 
 	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
-		super(options.message ?? code);
+		const cause = options.cause === undefined ? undefined : redact(options.cause);
+		super('rn-ads', code, {
+			message: options.message,
+			retryable: RETRYABLE.has(code),
+			redactedCause: cause,
+		});
 		this.name = 'AdsError';
-		this.code = code;
-		this.retryable = RETRYABLE.has(code);
 		this.operation = options.operation;
 		this.placementKey = options.placementKey;
 		this.format = options.format;
-		this.cause = options.cause === undefined ? undefined : redact(options.cause);
-		Object.setPrototypeOf(this, AdsError.prototype);
+		this.cause = cause;
 	}
 }
 
@@ -125,7 +132,6 @@ export class AdsConfigError extends AdsError {
 	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
 		super(code, { ...options, operation: options.operation ?? 'configure' });
 		this.name = 'AdsConfigError';
-		Object.setPrototypeOf(this, AdsConfigError.prototype);
 	}
 }
 
@@ -133,23 +139,15 @@ export function isAdsError(value: unknown): value is AdsError {
 	return value instanceof AdsError;
 }
 
-const REDACTED = '[redacted]';
-
 /** An AdMob unit or app id. Redacted so a log never carries a live identifier. */
 const AD_UNIT_PATTERN = /ca-app-pub-\d+[~/]\d+/g;
-/** GAID and any other dashed UUID an SDK might put in a message. */
-const UUID_PATTERN = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g;
-/** Base64-ish runs long enough to be an encoded payload such as a consent string. */
-const PAYLOAD_PATTERN = /[A-Za-z0-9+/=_-]{40,}/g;
-/** Anything path- or URL-like, which can carry query parameters with identifiers. */
-const URL_PATTERN = /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"']+/g;
 
 /**
  * Keys dropped wholesale rather than pattern-matched, because their values are
  * sensitive regardless of shape — a bare advertising id has no separator for a
  * pattern to catch.
  */
-const SENSITIVE_KEYS = new Set([
+const SENSITIVE_KEYS = [
 	'adid',
 	'adUnitId',
 	'advertisingId',
@@ -160,63 +158,54 @@ const SENSITIVE_KEYS = new Set([
 	'tcString',
 	'token',
 	'userId',
-]);
+];
 
-function redactString(value: string): string {
-	return value
-		.replace(URL_PATTERN, REDACTED)
-		.replace(AD_UNIT_PATTERN, REDACTED)
-		.replace(UUID_PATTERN, REDACTED)
-		.replace(PAYLOAD_PATTERN, REDACTED);
-}
+/**
+ * rn-core's pattern redaction (URLs, JWTs, e-mail addresses, UUIDs, payload-sized
+ * runs) plus ad unit ids, with the keys above dropped. Provider messages are kept
+ * readable: they describe the failure, and every identifier in them is shaped.
+ */
+const redactor = createRedactor({
+	text: 'patterns',
+	patterns: [AD_UNIT_PATTERN],
+	dropKeys: SENSITIVE_KEYS,
+	maxDepth: 2,
+});
 
 /**
  * Reduces an arbitrary provider value to a safe string (FR-053, NFR-006).
  *
  * Returns a string rather than a structure on purpose: a redacted object still
  * hands the consumer a reference into provider-owned memory, and the contract
- * promises no provider object crosses the boundary.
+ * promises no provider object crosses the boundary. An `AdsError` reduces to its
+ * code.
  */
-export function redact(value: unknown, depth = 0): string {
-	if (value === null || value === undefined) {
-		return '';
-	}
-	if (typeof value === 'string') {
-		return redactString(value);
-	}
-	if (typeof value === 'number' || typeof value === 'boolean') {
-		return String(value);
-	}
-	if (value instanceof Error) {
-		return redactString(value.message);
-	}
-	if (depth >= 2) {
-		return REDACTED;
-	}
-	if (Array.isArray(value)) {
-		return value.map(item => redact(item, depth + 1)).join(', ');
-	}
-	if (typeof value === 'object') {
-		const parts: string[] = [];
-		for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-			if (SENSITIVE_KEYS.has(key)) {
-				parts.push(`${key}=${REDACTED}`);
-				continue;
-			}
-			parts.push(`${key}=${redact(entry, depth + 1)}`);
-		}
-		return parts.join(' ');
-	}
-	return REDACTED;
+export function redact(value: unknown): string {
+	return redactor.text(value);
 }
 
 /**
- * Maps a provider failure onto the normalized taxonomy. Provider codes vary by
- * SDK version, so the match is on substrings that have been stable across
- * releases, and anything unrecognized becomes a retryable `provider_error`
- * rather than being silently reshaped into a code that means something specific.
+ * Maps a provider failure onto the normalized taxonomy.
+ *
+ * The adapter's classification wins when it gave one (ADS-08). Otherwise the
+ * match is on substrings that have been stable across provider releases, and
+ * anything unrecognized becomes a retryable `provider_error` rather than being
+ * reshaped into a code that means something specific.
  */
-export function normalizeProviderError(value: unknown, options: AdsErrorOptions = {}): AdsError {
+export function normalizeProviderError(
+	value: unknown,
+	options: AdsErrorOptions = {},
+	kind?: 'no_fill' | 'network' | 'rejected',
+): AdsError {
+	switch (kind) {
+		case 'no_fill':
+			return new AdsError('no_fill', { ...options, cause: value });
+		case 'network':
+			return new AdsError('network_error', { ...options, cause: value });
+		case 'rejected':
+			return new AdsError('provider_rejected', { ...options, cause: value });
+		default:
+	}
 	const text = value instanceof Error ? value.message : String(value ?? '');
 	const lowered = text.toLowerCase();