@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/diagnostics/errors.ts

@@ -1,234 +1,230 @@
-/**
- * Normalized error model (FR-053) and redaction (NFR-006).
- *
- * Codes are stable public API: renaming one is a breaking change under LIB-008.
- * They exist so a consuming app branches on `code` and `retryable` rather than
- * string-matching a provider message that may change under it.
- *
- * `cause` is a redacted string, never the provider's error object. A provider
- * object reaching a consumer would be a contract leak (FR-002) and a potential
- * carrier for identifiers the package promises never to emit (FR-021).
- */
-
-import type { AdFormat } from '../config/types';
-
-export type AdsOperation = 'initialize' | 'load' | 'show' | 'configure';
-
-export type AdsErrorCode =
-	// Configuration — none retryable; the configuration has to change.
-	| 'invalid_config'
-	| 'duplicate_placement_key'
-	| 'missing_ad_unit_id'
-	| 'format_mismatch'
-	| 'placement_not_found'
-	| 'production_in_dev_build'
-	| 'timeout_out_of_bounds'
-	// Availability — none retryable within this process.
-	| 'unsupported_platform'
-	| 'provider_missing'
-	| 'disabled'
-	// The app has not decided whether ads are on. Sibling of `disabled`, and
-	// non-retryable for the same reason: calling again changes nothing until the
-	// app resolves it (FR-115).
-	| 'undecided'
-	// Privacy — resolved by consent changing, not by calling again.
-	| 'consent_required'
-	| 'consent_undetermined'
-	| 'requires_reinitialization'
-	// The package's own consent flow has not produced permission. Distinct from
-	// `consent_required`, which means the app's own gate is closed — a refusal
-	// has to name which of the two inputs is blocking (FR-105a).
-	| 'consent_flow_required'
-	// The consent flow failed. Never retried by the package: FR-135 excludes
-	// consent errors, and re-running the flow is the app's call, not a backoff's.
-	| 'consent_flow_failed'
-	// Runtime.
-	| 'no_fill'
-	| 'network_error'
-	| 'load_timeout'
-	| 'show_timeout'
-	| 'ad_expired'
-	| 'not_ready'
-	| 'busy'
-	| 'consumed'
-	| 'app_inactive'
-	// The user came back to the app from an ad, or from a browser an ad opened.
-	// Only the package can know this, which is why refusing it is a capability
-	// rather than a policy (FR-128). Not retryable: retry covers load, and this
-	// is a show refusal that resolves with time rather than with another attempt.
-	| 'ad_originated_return'
-	| 'provider_error'
-	| 'internal_error'
-	// Configuration — a retry policy outside its bounds. Rejected rather than
-	// clamped, matching `timeout_out_of_bounds`: silently clamping tells the app
-	// it configured something it did not.
-	| 'retry_out_of_bounds';
-
-/**
- * "Retrying this operation could plausibly succeed" — not "retry immediately".
- *
- * 0.2.0 added an opt-in retry policy, and this set is what it is allowed to act
- * on. Everything outside it is excluded deliberately: configuration and consent
- * errors, an unsupported platform, and a disabled or undecided instance are all
- * states another attempt cannot change, so retrying them would spend a billable
- * request on a certainty (FR-135).
- */
-const RETRYABLE: ReadonlySet<AdsErrorCode> = new Set<AdsErrorCode>([
-	'no_fill',
-	'network_error',
-	'load_timeout',
-	'show_timeout',
-	'ad_expired',
-	'not_ready',
-	'busy',
-	'consumed',
-	'app_inactive',
-	'provider_error',
-]);
-
-export interface AdsErrorOptions {
-	readonly message?: string;
-	readonly operation?: AdsOperation;
-	readonly placementKey?: string;
-	readonly format?: AdFormat;
-	readonly cause?: unknown;
-}
-
-export class AdsError extends Error {
-	readonly code: AdsErrorCode;
-	readonly retryable: boolean;
-	readonly operation?: AdsOperation;
-	readonly placementKey?: string;
-	readonly format?: AdFormat;
-	/** Redacted provider detail. Never a provider object. */
-	readonly cause?: string;
-
-	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
-		super(options.message ?? code);
-		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);
-	}
-}
-
-/**
- * Configuration faults are thrown rather than returned, because they mean the
- * app is wired wrong and no runtime result could describe a usable outcome.
- * Every other failure in the package is a typed result (FR-004).
- */
-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);
-	}
-}
-
-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([
-	'adid',
-	'adUnitId',
-	'advertisingId',
-	'consent',
-	'consentString',
-	'gaid',
-	'idfa',
-	'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);
-}
-
-/**
- * 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.
- */
-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;
-}
-
-/**
- * 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.
- */
-export function normalizeProviderError(
-	value: unknown,
-	options: AdsErrorOptions = {},
-): AdsError {
-	const text = value instanceof Error ? value.message : String(value ?? '');
-	const lowered = text.toLowerCase();
-
-	if (lowered.includes('no-fill') || lowered.includes('no fill')) {
-		return new AdsError('no_fill', { ...options, cause: value });
-	}
-	if (lowered.includes('network')) {
-		return new AdsError('network_error', { ...options, cause: value });
-	}
-	return new AdsError('provider_error', { ...options, cause: value });
-}
+/**
+ * Normalized error model (FR-053) and redaction (NFR-006).
+ *
+ * Codes are stable public API: renaming one is a breaking change under LIB-008.
+ * They exist so a consuming app branches on `code` and `retryable` rather than
+ * string-matching a provider message that may change under it.
+ *
+ * `cause` is a redacted string, never the provider's error object. A provider
+ * object reaching a consumer would be a contract leak (FR-002) and a potential
+ * carrier for identifiers the package promises never to emit (FR-021).
+ */
+
+import type { AdFormat } from '../config/types';
+
+export type AdsOperation = 'initialize' | 'load' | 'show' | 'configure';
+
+export type AdsErrorCode =
+	// Configuration — none retryable; the configuration has to change.
+	| 'invalid_config'
+	| 'duplicate_placement_key'
+	| 'missing_ad_unit_id'
+	| 'format_mismatch'
+	| 'placement_not_found'
+	| 'production_in_dev_build'
+	| 'timeout_out_of_bounds'
+	// Availability — none retryable within this process.
+	| 'unsupported_platform'
+	| 'provider_missing'
+	| 'disabled'
+	// The app has not decided whether ads are on. Sibling of `disabled`, and
+	// non-retryable for the same reason: calling again changes nothing until the
+	// app resolves it (FR-115).
+	| 'undecided'
+	// Privacy — resolved by consent changing, not by calling again.
+	| 'consent_required'
+	| 'consent_undetermined'
+	| 'requires_reinitialization'
+	// The package's own consent flow has not produced permission. Distinct from
+	// `consent_required`, which means the app's own gate is closed — a refusal
+	// has to name which of the two inputs is blocking (FR-105a).
+	| 'consent_flow_required'
+	// The consent flow failed. Never retried by the package: FR-135 excludes
+	// consent errors, and re-running the flow is the app's call, not a backoff's.
+	| 'consent_flow_failed'
+	// Runtime.
+	| 'no_fill'
+	| 'network_error'
+	| 'load_timeout'
+	| 'show_timeout'
+	| 'ad_expired'
+	| 'not_ready'
+	| 'busy'
+	| 'consumed'
+	| 'app_inactive'
+	// The user came back to the app from an ad, or from a browser an ad opened.
+	// Only the package can know this, which is why refusing it is a capability
+	// rather than a policy (FR-128). Not retryable: retry covers load, and this
+	// is a show refusal that resolves with time rather than with another attempt.
+	| 'ad_originated_return'
+	| 'provider_error'
+	| 'internal_error'
+	// Configuration — a retry policy outside its bounds. Rejected rather than
+	// clamped, matching `timeout_out_of_bounds`: silently clamping tells the app
+	// it configured something it did not.
+	| 'retry_out_of_bounds';
+
+/**
+ * "Retrying this operation could plausibly succeed" — not "retry immediately".
+ *
+ * 0.2.0 added an opt-in retry policy, and this set is what it is allowed to act
+ * on. Everything outside it is excluded deliberately: configuration and consent
+ * errors, an unsupported platform, and a disabled or undecided instance are all
+ * states another attempt cannot change, so retrying them would spend a billable
+ * request on a certainty (FR-135).
+ */
+const RETRYABLE: ReadonlySet<AdsErrorCode> = new Set<AdsErrorCode>([
+	'no_fill',
+	'network_error',
+	'load_timeout',
+	'show_timeout',
+	'ad_expired',
+	'not_ready',
+	'busy',
+	'consumed',
+	'app_inactive',
+	'provider_error',
+]);
+
+export interface AdsErrorOptions {
+	readonly message?: string;
+	readonly operation?: AdsOperation;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	readonly cause?: unknown;
+}
+
+export class AdsError extends Error {
+	readonly code: AdsErrorCode;
+	readonly retryable: boolean;
+	readonly operation?: AdsOperation;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	/** Redacted provider detail. Never a provider object. */
+	readonly cause?: string;
+
+	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
+		super(options.message ?? code);
+		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);
+	}
+}
+
+/**
+ * Configuration faults are thrown rather than returned, because they mean the
+ * app is wired wrong and no runtime result could describe a usable outcome.
+ * Every other failure in the package is a typed result (FR-004).
+ */
+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);
+	}
+}
+
+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([
+	'adid',
+	'adUnitId',
+	'advertisingId',
+	'consent',
+	'consentString',
+	'gaid',
+	'idfa',
+	'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);
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+export function normalizeProviderError(value: unknown, options: AdsErrorOptions = {}): AdsError {
+	const text = value instanceof Error ? value.message : String(value ?? '');
+	const lowered = text.toLowerCase();
+
+	if (lowered.includes('no-fill') || lowered.includes('no fill')) {
+		return new AdsError('no_fill', { ...options, cause: value });
+	}
+	if (lowered.includes('network')) {
+		return new AdsError('network_error', { ...options, cause: value });
+	}
+	return new AdsError('provider_error', { ...options, cause: value });
+}