@chipmobilesdk/rn-ads 0.5.0 → 0.5.1

package/src/diagnostics/events.ts

@@ -1,232 +1,238 @@
-/**
- * Normalized event model and emitter (FR-051, FR-052, FR-054, FR-056).
- *
- * Events are the package's only observability surface. They carry no provider
- * object, no advertising identifier, no consent payload, and nothing that
- * identifies a user — a consuming app forwards them to whatever logging or
- * analytics it already has, and the package depends on none (FR-055).
- *
- * Dispatch iterates a snapshot of the listener set so subscribing or
- * unsubscribing during a dispatch neither skips a listener nor double-invokes
- * one. A listener that throws is caught and reported once; it cannot corrupt a
- * state machine or starve another listener (FR-056).
- */
-
-import type { AdFormat, PrivacyBlockReason, Reward, UnavailableReason, Unsubscribe } from '../config/types';
-import { AdsError, type AdsErrorCode, type AdsOperation } from './errors';
-
-export type AdEventType =
-	| 'initialization'
-	| 'load_started'
-	| 'loaded'
-	| 'load_failed'
-	| 'display_started'
-	| 'impression'
-	| 'click'
-	| 'display_failed'
-	| 'dismissed'
-	| 'reward_earned'
-	| 'disabled'
-	| 'unavailable'
-	| 'config_warning'
-	// Emitted once per retry attempt, carrying the correlation id of the load
-	// 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 {
-	readonly timestamp: number;
-	readonly placementKey?: string;
-	readonly format?: AdFormat;
-	readonly correlationId?: string;
-}
-
-/**
- * `source` records whether the provider reported a true impression or the
- * package derived one. Banners get a real impression callback; full-screen
- * formats have none in the provider's event enum, so theirs is derived from the
- * ad opening. Flattening that away would make the model quietly wrong for anyone
- * reconciling these events against revenue reporting.
- */
-export type ImpressionSource = 'provider' | 'derived';
-
-export type AdEvent = BaseEvent &
-	(
-		| { readonly type: 'initialization'; readonly status: string; readonly retryable?: boolean }
-		| { readonly type: 'load_started' }
-		| { readonly type: 'loaded'; readonly durationMs: number }
-		| { readonly type: 'load_failed'; readonly error: AdsError }
-		| { readonly type: 'display_started' }
-		| { readonly type: 'impression'; readonly source: ImpressionSource }
-		| { readonly type: 'click' }
-		| { readonly type: 'display_failed'; readonly error: AdsError }
-		| { readonly type: 'dismissed'; readonly rewardEarned?: boolean }
-		| { readonly type: 'reward_earned'; readonly reward: Reward }
-		| { readonly type: 'disabled'; readonly operation: AdsOperation }
-		| {
-				readonly type: 'unavailable';
-				readonly operation: AdsOperation;
-				readonly reason: UnavailableReason | PrivacyBlockReason;
-		  }
-		| {
-				readonly type: 'retry_scheduled';
-				/** 1-based: the first retry is attempt 1, not 0. */
-				readonly attempt: number;
-				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;
-				/**
-				 * Placements the warning concerns. Empty for warnings that are not
-				 * placement-scoped.
-				 *
-				 * Present on every config warning rather than only on the one that
-				 * uses it, so that 0.1.0 code which reads `placementKeys` after
-				 * checking `type === 'config_warning'` keeps compiling. Splitting
-				 * this into one variant per warning would have been tidier and
-				 * would have broken every such consumer for no behavioral gain.
-				 */
-				readonly placementKeys: readonly string[];
-				/** Consent tools ignored, for `consent_tool_ignored_in_production`. */
-				readonly tools?: readonly string[];
-				/** How long the app left the state unresolved, for the undecided warning. */
-				readonly elapsedMs?: number;
-		  }
-		| { readonly type: 'internal_error'; readonly error: AdsError }
-	);
-
-/**
- * Configuration problems worth telling the app about, all under one event type.
- *
- * One type rather than three because FR-132 forbids a parallel vocabulary, and
- * because a consumer already routing `config_warning` into its logging should
- * not have to subscribe again to keep seeing everything.
- */
-export type ConfigWarning =
-	/** A production ad unit was replaced with an official test unit (FR-011a). */
-	| 'test_ad_unit_substituted'
-	/** The app left `enabled: 'undecided'` unresolved past its window (FR-119). */
-	| 'enablement_undecided_timeout'
-	/** Consent testing tools were supplied in production and ignored (FR-113). */
-	| 'consent_tool_ignored_in_production';
-
-export type AdEventListener = (event: AdEvent) => void;
-
-/** Events that may occur at most once within one correlated cycle (FR-054). */
-const ONCE_PER_CYCLE: ReadonlySet<AdEventType> = new Set<AdEventType>([
-	'loaded',
-	'display_started',
-	'impression',
-	'dismissed',
-	'reward_earned',
-]);
-
-export interface AdEventEmitter {
-	emit(event: AdEvent): void;
-	subscribe(listener: AdEventListener): Unsubscribe;
-	/** Releases every listener and the once-per-cycle bookkeeping (FR-035). */
-	dispose(): void;
-	listenerCount(): number;
-}
-
-export function createEventEmitter(): AdEventEmitter {
-	const listeners = new Set<AdEventListener>();
-	// `${correlationId}:${type}` for everything already emitted in a cycle.
-	const emittedOnce = new Set<string>();
-	let disposed = false;
-	// Guards against an internal_error thrown by a listener re-entering dispatch
-	// and recursing forever.
-	let reportingListenerFailure = false;
-
-	function dispatch(event: AdEvent): void {
-		for (const listener of Array.from(listeners)) {
-			try {
-				listener(event);
-			} catch (error) {
-				if (reportingListenerFailure) {
-					continue;
-				}
-				reportingListenerFailure = true;
-				try {
-					dispatch({
-						type: 'internal_error',
-						timestamp: Date.now(),
-						placementKey: event.placementKey,
-						format: event.format,
-						correlationId: event.correlationId,
-						error: new AdsError('internal_error' as AdsErrorCode, {
-							message: 'consumer event listener threw',
-							cause: error,
-						}),
-					});
-				} finally {
-					reportingListenerFailure = false;
-				}
-			}
-		}
-	}
-
-	return {
-		emit(event) {
-			// After dispose, a late provider callback updates nothing and emits
-			// nothing (FR-035, SC-008).
-			if (disposed) {
-				return;
-			}
-			if (event.correlationId && ONCE_PER_CYCLE.has(event.type)) {
-				const key = `${event.correlationId}:${event.type}`;
-				if (emittedOnce.has(key)) {
-					return;
-				}
-				emittedOnce.add(key);
-			}
-			dispatch(event);
-		},
-		subscribe(listener) {
-			listeners.add(listener);
-			let active = true;
-			return () => {
-				// Idempotent: a second call is a no-op, not an error (FR-005).
-				if (!active) {
-					return;
-				}
-				active = false;
-				listeners.delete(listener);
-			};
-		},
-		dispose() {
-			disposed = true;
-			listeners.clear();
-			emittedOnce.clear();
-		},
-		listenerCount() {
-			return listeners.size;
-		},
-	};
-}
-
-/** Normalizes a provider reward descriptor. No provider object crosses this (FR-047). */
-export function normalizeReward(value: unknown): Reward {
-	const source = (value ?? {}) as { type?: unknown; amount?: unknown };
-	const amount = Number(source.amount);
-	return {
-		type: typeof source.type === 'string' ? source.type : 'reward',
-		amount: Number.isFinite(amount) ? amount : 0,
-	};
-}
+/**
+ * Normalized event model and emitter (FR-051, FR-052, FR-054, FR-056).
+ *
+ * Events are the package's only observability surface. They carry no provider
+ * object, no advertising identifier, no consent payload, and nothing that
+ * identifies a user — a consuming app forwards them to whatever logging or
+ * analytics it already has, and the package depends on none (FR-055).
+ *
+ * Dispatch iterates a snapshot of the listener set so subscribing or
+ * unsubscribing during a dispatch neither skips a listener nor double-invokes
+ * one. A listener that throws is caught and reported once; it cannot corrupt a
+ * state machine or starve another listener (FR-056).
+ */
+
+import type {
+	AdFormat,
+	PrivacyBlockReason,
+	Reward,
+	UnavailableReason,
+	Unsubscribe,
+} from '../config/types';
+import { AdsError, type AdsErrorCode, type AdsOperation } from './errors';
+
+export type AdEventType =
+	| 'initialization'
+	| 'load_started'
+	| 'loaded'
+	| 'load_failed'
+	| 'display_started'
+	| 'impression'
+	| 'click'
+	| 'display_failed'
+	| 'dismissed'
+	| 'reward_earned'
+	| 'disabled'
+	| 'unavailable'
+	| 'config_warning'
+	// Emitted once per retry attempt, carrying the correlation id of the load
+	// 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 {
+	readonly timestamp: number;
+	readonly placementKey?: string;
+	readonly format?: AdFormat;
+	readonly correlationId?: string;
+}
+
+/**
+ * `source` records whether the provider reported a true impression or the
+ * package derived one. Banners get a real impression callback; full-screen
+ * formats have none in the provider's event enum, so theirs is derived from the
+ * ad opening. Flattening that away would make the model quietly wrong for anyone
+ * reconciling these events against revenue reporting.
+ */
+export type ImpressionSource = 'provider' | 'derived';
+
+export type AdEvent = BaseEvent &
+	(
+		| { readonly type: 'initialization'; readonly status: string; readonly retryable?: boolean }
+		| { readonly type: 'load_started' }
+		| { readonly type: 'loaded'; readonly durationMs: number }
+		| { readonly type: 'load_failed'; readonly error: AdsError }
+		| { readonly type: 'display_started' }
+		| { readonly type: 'impression'; readonly source: ImpressionSource }
+		| { readonly type: 'click' }
+		| { readonly type: 'display_failed'; readonly error: AdsError }
+		| { readonly type: 'dismissed'; readonly rewardEarned?: boolean }
+		| { readonly type: 'reward_earned'; readonly reward: Reward }
+		| { readonly type: 'disabled'; readonly operation: AdsOperation }
+		| {
+				readonly type: 'unavailable';
+				readonly operation: AdsOperation;
+				readonly reason: UnavailableReason | PrivacyBlockReason;
+		  }
+		| {
+				readonly type: 'retry_scheduled';
+				/** 1-based: the first retry is attempt 1, not 0. */
+				readonly attempt: number;
+				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;
+				/**
+				 * Placements the warning concerns. Empty for warnings that are not
+				 * placement-scoped.
+				 *
+				 * Present on every config warning rather than only on the one that
+				 * uses it, so that 0.1.0 code which reads `placementKeys` after
+				 * checking `type === 'config_warning'` keeps compiling. Splitting
+				 * this into one variant per warning would have been tidier and
+				 * would have broken every such consumer for no behavioral gain.
+				 */
+				readonly placementKeys: readonly string[];
+				/** Consent tools ignored, for `consent_tool_ignored_in_production`. */
+				readonly tools?: readonly string[];
+				/** How long the app left the state unresolved, for the undecided warning. */
+				readonly elapsedMs?: number;
+		  }
+		| { readonly type: 'internal_error'; readonly error: AdsError }
+	);
+
+/**
+ * Configuration problems worth telling the app about, all under one event type.
+ *
+ * One type rather than three because FR-132 forbids a parallel vocabulary, and
+ * because a consumer already routing `config_warning` into its logging should
+ * not have to subscribe again to keep seeing everything.
+ */
+export type ConfigWarning =
+	/** A production ad unit was replaced with an official test unit (FR-011a). */
+	| 'test_ad_unit_substituted'
+	/** The app left `enabled: 'undecided'` unresolved past its window (FR-119). */
+	| 'enablement_undecided_timeout'
+	/** Consent testing tools were supplied in production and ignored (FR-113). */
+	| 'consent_tool_ignored_in_production';
+
+export type AdEventListener = (event: AdEvent) => void;
+
+/** Events that may occur at most once within one correlated cycle (FR-054). */
+const ONCE_PER_CYCLE: ReadonlySet<AdEventType> = new Set<AdEventType>([
+	'loaded',
+	'display_started',
+	'impression',
+	'dismissed',
+	'reward_earned',
+]);
+
+export interface AdEventEmitter {
+	emit(event: AdEvent): void;
+	subscribe(listener: AdEventListener): Unsubscribe;
+	/** Releases every listener and the once-per-cycle bookkeeping (FR-035). */
+	dispose(): void;
+	listenerCount(): number;
+}
+
+export function createEventEmitter(): AdEventEmitter {
+	const listeners = new Set<AdEventListener>();
+	// `${correlationId}:${type}` for everything already emitted in a cycle.
+	const emittedOnce = new Set<string>();
+	let disposed = false;
+	// Guards against an internal_error thrown by a listener re-entering dispatch
+	// and recursing forever.
+	let reportingListenerFailure = false;
+
+	function dispatch(event: AdEvent): void {
+		for (const listener of Array.from(listeners)) {
+			try {
+				listener(event);
+			} catch (error) {
+				if (reportingListenerFailure) {
+					continue;
+				}
+				reportingListenerFailure = true;
+				try {
+					dispatch({
+						type: 'internal_error',
+						timestamp: Date.now(),
+						placementKey: event.placementKey,
+						format: event.format,
+						correlationId: event.correlationId,
+						error: new AdsError('internal_error' as AdsErrorCode, {
+							message: 'consumer event listener threw',
+							cause: error,
+						}),
+					});
+				} finally {
+					reportingListenerFailure = false;
+				}
+			}
+		}
+	}
+
+	return {
+		emit(event) {
+			// After dispose, a late provider callback updates nothing and emits
+			// nothing (FR-035, SC-008).
+			if (disposed) {
+				return;
+			}
+			if (event.correlationId && ONCE_PER_CYCLE.has(event.type)) {
+				const key = `${event.correlationId}:${event.type}`;
+				if (emittedOnce.has(key)) {
+					return;
+				}
+				emittedOnce.add(key);
+			}
+			dispatch(event);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			let active = true;
+			return () => {
+				// Idempotent: a second call is a no-op, not an error (FR-005).
+				if (!active) {
+					return;
+				}
+				active = false;
+				listeners.delete(listener);
+			};
+		},
+		dispose() {
+			disposed = true;
+			listeners.clear();
+			emittedOnce.clear();
+		},
+		listenerCount() {
+			return listeners.size;
+		},
+	};
+}
+
+/** Normalizes a provider reward descriptor. No provider object crosses this (FR-047). */
+export function normalizeReward(value: unknown): Reward {
+	const source = (value ?? {}) as { type?: unknown; amount?: unknown };
+	const amount = Number(source.amount);
+	return {
+		type: typeof source.type === 'string' ? source.type : 'reward',
+		amount: Number.isFinite(amount) ? amount : 0,
+	};
+}