@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/diagnostics/events.ts

@@ -1,266 +1,282 @@
-/**
- * Typed events and the emitter.
- *
- * The bar is FR-077: the event stream **alone** must be enough to reconstruct a
- * transaction's full lifecycle, so that "the user says they paid but has no
- * entitlement" can be investigated from logs without a reproduction.
- *
- * Forbidden in every payload, without exception (FR-076, FR-074): store objects,
- * raw receipts, verification payloads, backend tokens, payment details, the
- * obfuscated account identifier, and the cache-scope token.
- */
-
-import { redact, type PaymentErrorCode, type PaymentOperation } from './errors';
-import type {
-	EntitlementKey,
-	Environment,
-	PendingResolution,
-	ProductKey,
-	Unsubscribe,
-	UnavailableReason,
-	PaymentStatusKind,
-} from '../config/types';
-
-export type PaymentEventType =
-	| 'initialization'
-	| 'connection_changed'
-	| 'products_queried'
-	| 'purchase_started'
-	| 'purchase_succeeded'
-	| 'purchase_cancelled'
-	| 'purchase_pending'
-	// How a pending purchase ended, once per transaction. `settled` precedes the
-	// `entitlement_granted` it leads to (FR-102), added in 0.2.0.
-	| 'purchase_pending_resolved'
-	| 'purchase_failed'
-	| 'transaction_finalized'
-	| 'transaction_consumed'
-	| 'finalize_retry_scheduled'
-	| 'sync_completed'
-	| 'entitlement_granted'
-	| 'entitlement_revoked'
-	| 'validation_decided'
-	| 'validation_unavailable'
-	| 'environment_blocked'
-	| 'config_warning'
-	| 'internal_error';
-
-interface BaseEvent {
-	timestamp: number;
-	/** Ties one purchase cycle together end to end. Absent for lifecycle events. */
-	correlationId?: string;
-}
-
-export type SyncTrigger = 'initialize' | 'foreground' | 'manual' | 'already_owned';
-
-export type PaymentEvent = BaseEvent &
-	(
-		| {
-				type: 'initialization';
-				status: PaymentStatusKind;
-				unavailableReason?: UnavailableReason;
-				retryable?: boolean;
-		  }
-		| {
-				type: 'connection_changed';
-				connected: boolean;
-				reason?: string;
-				attempt?: number;
-		  }
-		| {
-				type: 'products_queried';
-				productKeys: ProductKey[];
-				found: number;
-				missing: ProductKey[];
-				fromCache: boolean;
-		  }
-		| { type: 'purchase_started'; productKey: ProductKey }
-		| { type: 'purchase_succeeded'; productKey: ProductKey }
-		| { type: 'purchase_cancelled'; productKey: ProductKey }
-		| { type: 'purchase_pending'; productKey: ProductKey }
-		| {
-				type: 'purchase_pending_resolved';
-				productKey: ProductKey;
-				outcome: PendingResolution;
-		  }
-		| {
-				type: 'purchase_failed';
-				productKey: ProductKey;
-				code: PaymentErrorCode;
-				retryable: boolean;
-		  }
-		| {
-				type: 'transaction_finalized';
-				productKey: ProductKey;
-				attempts: number;
-		  }
-		| { type: 'transaction_consumed'; productKey: ProductKey }
-		| {
-				type: 'finalize_retry_scheduled';
-				productKey: ProductKey;
-				attempt: number;
-				delayMs: number;
-		  }
-		| {
-				type: 'sync_completed';
-				restoredCount: number;
-				revokedCount: number;
-				trigger: SyncTrigger;
-		  }
-		| {
-				type: 'entitlement_granted';
-				entitlementKey: EntitlementKey;
-				sources: ProductKey[];
-		  }
-		| {
-				type: 'entitlement_revoked';
-				entitlementKey: EntitlementKey;
-				reason: 'expired' | 'revoked_by_store' | 'validation_rejected' | 'consumed';
-		  }
-		| {
-				type: 'validation_decided';
-				productKey: ProductKey;
-				decision: 'approved' | 'rejected';
-		  }
-		| {
-				type: 'validation_unavailable';
-				productKey: ProductKey;
-				fallback: 'grant_and_queue' | 'withhold';
-		  }
-		| {
-				type: 'environment_blocked';
-				productKey: ProductKey;
-				environment: Environment;
-		  }
-		| { type: 'config_warning'; detail: string }
-		| {
-				type: 'internal_error';
-				code: PaymentErrorCode;
-				operation: PaymentOperation;
-		  }
-	);
-
-export type PaymentEventListener = (event: PaymentEvent) => void;
-
-/**
- * A `PaymentEvent` with the timestamp left to the emitter.
- *
- * Distributive on purpose: a plain `Omit<PaymentEvent, 'timestamp'>` collapses the
- * discriminated union into one object type with only the shared keys, which would
- * reject every variant-specific field. `T extends unknown` forces the mapping to
- * apply per member and keeps the union discriminated.
- */
-type WithOptionalTimestamp<T> = T extends unknown
-	? Omit<T, 'timestamp'> & { timestamp?: number }
-	: never;
-
-export type PaymentEventInput = WithOptionalTimestamp<PaymentEvent>;
-
-export interface PaymentEmitter {
-	emit(event: PaymentEvent): void;
-	subscribe(listener: PaymentEventListener): Unsubscribe;
-	/** Disarms permanently. After this nothing is emitted (FR-082). */
-	dispose(): void;
-	listenerCount(): number;
-	disposed(): boolean;
-}
-
-/**
- * Creates the emitter.
- *
- * Two properties are deliberate:
- *
- * 1. **A throwing listener cannot break anything** (FR-081). Each listener is
- *    invoked defensively, the throw is handed to `onListenerError`, and delivery
- *    continues to the remaining listeners. One app's broken analytics callback
- *    must not stop the package granting an entitlement or stop another listener
- *    hearing about it.
- *
- *    The failure is **not** re-emitted as an event, deliberately. A consumer's own
- *    bug is not a payment-lifecycle event, and reporting it through the channel
- *    that just failed would both invite recursion and double event traffic for
- *    every event while that listener stays broken. It goes to the logger instead.
- *
- * 2. **After `dispose`, nothing is emitted** (FR-082). A store callback can
- *    arrive after cleanup; it must be dropped silently rather than reach a
- *    listener whose component is gone.
- */
-export function createEmitter(
-	onListenerError?: (error: unknown, event: PaymentEvent) => void,
-): PaymentEmitter {
-	const listeners = new Set<PaymentEventListener>();
-	let isDisposed = false;
-
-	const emit = (event: PaymentEvent): void => {
-		if (isDisposed) {
-			return;
-		}
-		// Snapshot first: a listener that subscribes or unsubscribes during
-		// delivery must not mutate the set being iterated.
-		for (const listener of [...listeners]) {
-			try {
-				listener(event);
-			} catch (error) {
-				try {
-					onListenerError?.(error, event);
-				} catch {
-					// Even the error reporter is not trusted to behave.
-				}
-			}
-		}
-	};
-
-	return {
-		emit,
-		subscribe(listener: PaymentEventListener): Unsubscribe {
-			if (isDisposed) {
-				return () => undefined;
-			}
-			listeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				listeners.delete(listener);
-			};
-		},
-		dispose(): void {
-			isDisposed = true;
-			listeners.clear();
-		},
-		listenerCount: () => listeners.size,
-		disposed: () => isDisposed,
-	};
-}
-
-/**
- * Fields that must never appear in an event payload.
- *
- * Used by `__tests__/redaction.test.ts` to walk every emitted event across the
- * whole suite. Enumerating the ban here rather than in the test keeps the rule
- * next to the type it constrains.
- */
-export const FORBIDDEN_EVENT_FIELDS: readonly string[] = [
-	'verificationPayload',
-	'receipt',
-	'purchaseToken',
-	'transactionReceipt',
-	'obfuscatedAccountId',
-	'scopeToken',
-	'token',
-	'signature',
-];
-
-/** Correlation ids tie one purchase cycle together; no user data goes into them. */
-export function createCorrelationId(
-	counter: { next: number },
-	prefix = 'pc',
-): string {
-	const id = `${prefix}_${counter.next.toString(36)}`;
-	counter.next += 1;
-	return id;
-}
-
-export { redact };
+/**
+ * Typed events and the emitter.
+ *
+ * The bar is FR-077: the event stream **alone** must be enough to reconstruct a
+ * transaction's full lifecycle, so that "the user says they paid but has no
+ * entitlement" can be investigated from logs without a reproduction.
+ *
+ * Forbidden in every payload, without exception (FR-076, FR-074): store objects,
+ * raw receipts, verification payloads, backend tokens, payment details, the
+ * obfuscated account identifier, and the cache-scope token.
+ */
+
+import {
+	createDiagnosticChannel,
+	createEmitter as createCoreEmitter,
+} from '@chipmobilesdk/rn-core';
+
+/** Every delivered event also goes to the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<PaymentEvent['type'] | 'listener_reporter_failed'>(
+	'rn-payment',
+);
+
+import { redact, type PaymentErrorCode, type PaymentOperation } from './errors';
+import type {
+	EntitlementKey,
+	Environment,
+	PendingResolution,
+	ProductKey,
+	Unsubscribe,
+	UnavailableReason,
+	PaymentStatusKind,
+} from '../config/types';
+
+export type PaymentEventType =
+	| 'initialization'
+	| 'connection_changed'
+	| 'products_queried'
+	| 'purchase_started'
+	| 'purchase_succeeded'
+	| 'purchase_cancelled'
+	| 'purchase_pending'
+	// How a pending purchase ended, once per transaction. `settled` precedes the
+	// `entitlement_granted` it leads to (FR-102), added in 0.2.0.
+	| 'purchase_pending_resolved'
+	| 'purchase_failed'
+	| 'transaction_finalized'
+	| 'transaction_consumed'
+	| 'finalize_retry_scheduled'
+	| 'sync_completed'
+	| 'entitlement_granted'
+	| 'entitlement_revoked'
+	| 'validation_decided'
+	| 'validation_unavailable'
+	| 'environment_blocked'
+	| 'config_warning'
+	| 'internal_error';
+
+interface BaseEvent {
+	timestamp: number;
+	/** Ties one purchase cycle together end to end. Absent for lifecycle events. */
+	correlationId?: string;
+}
+
+export type SyncTrigger = 'initialize' | 'foreground' | 'manual' | 'already_owned';
+
+export type PaymentEvent = BaseEvent &
+	(
+		| {
+				type: 'initialization';
+				status: PaymentStatusKind;
+				unavailableReason?: UnavailableReason;
+				retryable?: boolean;
+		  }
+		| {
+				type: 'connection_changed';
+				connected: boolean;
+				reason?: string;
+				attempt?: number;
+		  }
+		| {
+				type: 'products_queried';
+				productKeys: ProductKey[];
+				found: number;
+				missing: ProductKey[];
+				fromCache: boolean;
+		  }
+		| { type: 'purchase_started'; productKey: ProductKey }
+		| { type: 'purchase_succeeded'; productKey: ProductKey }
+		| { type: 'purchase_cancelled'; productKey: ProductKey }
+		| { type: 'purchase_pending'; productKey: ProductKey }
+		| {
+				type: 'purchase_pending_resolved';
+				productKey: ProductKey;
+				outcome: PendingResolution;
+		  }
+		| {
+				type: 'purchase_failed';
+				productKey: ProductKey;
+				code: PaymentErrorCode;
+				retryable: boolean;
+		  }
+		| {
+				type: 'transaction_finalized';
+				productKey: ProductKey;
+				attempts: number;
+		  }
+		| { type: 'transaction_consumed'; productKey: ProductKey }
+		| {
+				type: 'finalize_retry_scheduled';
+				productKey: ProductKey;
+				attempt: number;
+				delayMs: number;
+		  }
+		| {
+				type: 'sync_completed';
+				restoredCount: number;
+				revokedCount: number;
+				trigger: SyncTrigger;
+		  }
+		| {
+				type: 'entitlement_granted';
+				entitlementKey: EntitlementKey;
+				sources: ProductKey[];
+		  }
+		| {
+				type: 'entitlement_revoked';
+				entitlementKey: EntitlementKey;
+				reason: 'expired' | 'revoked_by_store' | 'validation_rejected' | 'consumed';
+		  }
+		| {
+				type: 'validation_decided';
+				productKey: ProductKey;
+				decision: 'approved' | 'rejected';
+		  }
+		| {
+				type: 'validation_unavailable';
+				productKey: ProductKey;
+				fallback: 'grant_and_queue' | 'withhold';
+		  }
+		| {
+				type: 'environment_blocked';
+				productKey: ProductKey;
+				environment: Environment;
+		  }
+		| { type: 'config_warning'; detail: string }
+		| {
+				type: 'internal_error';
+				code: PaymentErrorCode;
+				operation: PaymentOperation;
+		  }
+	);
+
+export type PaymentEventListener = (event: PaymentEvent) => void;
+
+/**
+ * A `PaymentEvent` with the timestamp left to the emitter.
+ *
+ * Distributive on purpose: a plain `Omit<PaymentEvent, 'timestamp'>` collapses the
+ * discriminated union into one object type with only the shared keys, which would
+ * reject every variant-specific field. `T extends unknown` forces the mapping to
+ * apply per member and keeps the union discriminated.
+ */
+type WithOptionalTimestamp<T> = T extends unknown
+	? Omit<T, 'timestamp'> & { timestamp?: number }
+	: never;
+
+export type PaymentEventInput = WithOptionalTimestamp<PaymentEvent>;
+
+export interface PaymentEmitter {
+	emit(event: PaymentEvent): void;
+	subscribe(listener: PaymentEventListener): Unsubscribe;
+	/** Disarms permanently. After this nothing is emitted (FR-082). */
+	dispose(): void;
+	listenerCount(): number;
+	disposed(): boolean;
+}
+
+/**
+ * Creates the emitter.
+ *
+ * Two properties are deliberate:
+ *
+ * 1. **A throwing listener cannot break anything** (FR-081). Each listener is
+ *    invoked defensively, the throw is handed to `onListenerError`, and delivery
+ *    continues to the remaining listeners. One app's broken analytics callback
+ *    must not stop the package granting an entitlement or stop another listener
+ *    hearing about it.
+ *
+ *    The failure is **not** re-emitted as an event, deliberately. A consumer's own
+ *    bug is not a payment-lifecycle event, and reporting it through the channel
+ *    that just failed would both invite recursion and double event traffic for
+ *    every event while that listener stays broken. It goes to the logger instead.
+ *
+ * 2. **After `dispose`, nothing is emitted** (FR-082). A store callback can
+ *    arrive after cleanup; it must be dropped silently rather than reach a
+ *    listener whose component is gone.
+ */
+export function createEmitter(
+	onListenerError?: (error: unknown, event: PaymentEvent) => void,
+): PaymentEmitter {
+	// The event whose listeners are running, so a failure is reported against it.
+	let dispatching: PaymentEvent | null = null;
+	let isDisposed = false;
+	// rn-core's emitter: a snapshot per emit, each listener isolated, idempotent
+	// unsubscribe. Even the error reporter is isolated: if it throws, rn-core
+	// rethrows that on a fresh task rather than into the emit.
+	const emitter = createCoreEmitter<PaymentEvent>({
+		onListenerError: error => {
+			if (!dispatching) return;
+			try {
+				onListenerError?.(error, dispatching);
+			} catch {
+				// The app's own reporter failed: nothing in the app is left to tell, so
+				// the failure goes to the SDK sinks rather than becoming an uncaught
+				// error on some later tick (FR-080).
+				channel.emit('listener_reporter_failed', 'error', {
+					eventType: dispatching.type,
+				});
+			}
+		},
+	});
+
+	return {
+		emit(event) {
+			if (isDisposed) {
+				return;
+			}
+			const previous = dispatching;
+			dispatching = event;
+			try {
+				if (emitter.emit(event)) {
+					// The type and the cycle only: payment events carry product and
+					// entitlement keys an app may treat as personal.
+					channel.emit(
+						event.type,
+						/failed|error|blocked|rejected|revoked/.test(event.type) ? 'warn' : 'info',
+						undefined,
+						event.correlationId,
+					);
+				}
+			} finally {
+				dispatching = previous;
+			}
+		},
+		subscribe(listener: PaymentEventListener): Unsubscribe {
+			return isDisposed ? () => undefined : emitter.subscribe(listener);
+		},
+		dispose(): void {
+			isDisposed = true;
+			emitter.dispose();
+		},
+		listenerCount: () => emitter.listenerCount(),
+		disposed: () => isDisposed,
+	};
+}
+
+/**
+ * Fields that must never appear in an event payload.
+ *
+ * Used by `__tests__/redaction.test.ts` to walk every emitted event across the
+ * whole suite. Enumerating the ban here rather than in the test keeps the rule
+ * next to the type it constrains.
+ */
+export const FORBIDDEN_EVENT_FIELDS: readonly string[] = [
+	'verificationPayload',
+	'receipt',
+	'purchaseToken',
+	'transactionReceipt',
+	'obfuscatedAccountId',
+	'scopeToken',
+	'token',
+	'signature',
+];
+
+/** Correlation ids tie one purchase cycle together; no user data goes into them. */
+export function createCorrelationId(counter: { next: number }, prefix = 'pc'): string {
+	const id = `${prefix}_${counter.next.toString(36)}`;
+	counter.next += 1;
+	return id;
+}
+
+export { redact };