@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/src/diagnostics/events.ts

@@ -0,0 +1,257 @@
+/**
+ * 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,
+	ProductKey,
+	Unsubscribe,
+	UnavailableReason,
+	PaymentStatusKind,
+} from '../config/types';
+
+export type PaymentEventType =
+	| 'initialization'
+	| 'connection_changed'
+	| 'products_queried'
+	| 'purchase_started'
+	| 'purchase_succeeded'
+	| 'purchase_cancelled'
+	| 'purchase_pending'
+	| '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_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 };

package/src/diagnostics/messageKeys.ts

@@ -0,0 +1,95 @@
+/**
+ * Stable, localizable message keys with English default copy (FR-084, FR-085).
+ *
+ * The package takes no i18n runtime dependency: consuming apps map these keys to
+ * localized strings through whatever i18n system they already run. This is plain
+ * data, and the package never resolves or renders it.
+ *
+ * Message keys are **public API**: renaming one is a breaking change, on the
+ * same footing as an error code (FR-078).
+ *
+ * User-actionable copy and developer/configuration copy are kept in separate
+ * maps so an app cannot accidentally show "Payment catalog is invalid" to a
+ * customer — a configuration fault is a developer's problem, not a user's.
+ */
+
+/** Copy an end user may reasonably be shown. */
+export interface PaymentUserMessageMap {
+	'payment.state.pending': string;
+	'payment.state.alreadyOwned': string;
+	'payment.action.restore': string;
+	'payment.restore.succeeded': string;
+	'payment.restore.nothingFound': string;
+	'payment.error.cancelled': string;
+	'payment.error.network': string;
+	'payment.error.unavailable': string;
+	'payment.error.disabled': string;
+	'payment.subscription.grace': string;
+	'payment.subscription.hold': string;
+}
+
+/** Copy for developers and operators. **Never** surfaced to an end user. */
+export interface PaymentDeveloperMessageMap {
+	'payment.config.invalidCatalog': string;
+	'payment.config.missingStoreId': string;
+	'payment.config.productionInNonProductionBuild': string;
+	'payment.config.storageUnavailable': string;
+	'payment.config.environmentBlocked': string;
+}
+
+export type PaymentMessageMap = PaymentUserMessageMap &
+	PaymentDeveloperMessageMap;
+
+export type PaymentUserMessageKey = keyof PaymentUserMessageMap;
+export type PaymentDeveloperMessageKey = keyof PaymentDeveloperMessageMap;
+export type PaymentMessageKey = keyof PaymentMessageMap;
+
+export const DEFAULT_USER_MESSAGES: PaymentUserMessageMap = {
+	'payment.state.pending': 'Waiting for your payment to complete',
+	'payment.state.alreadyOwned': 'You already own this',
+	'payment.action.restore': 'Restore purchases',
+	'payment.restore.succeeded': 'Your purchases have been restored',
+	'payment.restore.nothingFound': 'No previous purchases found',
+	'payment.error.cancelled': 'Purchase cancelled',
+	'payment.error.network':
+		"Couldn't reach the store. Check your connection and try again.",
+	'payment.error.unavailable': "Purchases aren't available on this device",
+	'payment.error.disabled': 'Purchases are currently unavailable',
+	'payment.subscription.grace': "There's a problem with your payment method",
+	'payment.subscription.hold':
+		'Your subscription is paused until payment is updated',
+};
+
+export const DEFAULT_DEVELOPER_MESSAGES: PaymentDeveloperMessageMap = {
+	'payment.config.invalidCatalog': 'Payment catalog is invalid',
+	'payment.config.missingStoreId':
+		'Product is missing a store identifier for this platform',
+	'payment.config.productionInNonProductionBuild':
+		'Production payment configuration in a non-production build',
+	'payment.config.storageUnavailable':
+		'Local storage unavailable; entitlements will not survive restart',
+	'payment.config.environmentBlocked':
+		'Purchase blocked: this environment may not create a real transaction',
+};
+
+export const DEFAULT_MESSAGES: PaymentMessageMap = {
+	...DEFAULT_USER_MESSAGES,
+	...DEFAULT_DEVELOPER_MESSAGES,
+};
+
+/** Every user-actionable key, for an app building its translation resource. */
+export const USER_MESSAGE_KEYS = Object.keys(
+	DEFAULT_USER_MESSAGES,
+) as PaymentUserMessageKey[];
+
+/** Every developer-facing key, so an app can exclude them from user-visible bundles. */
+export const DEVELOPER_MESSAGE_KEYS = Object.keys(
+	DEFAULT_DEVELOPER_MESSAGES,
+) as PaymentDeveloperMessageKey[];
+
+/** True for keys safe to show an end user. Lets an app assert that at its boundary. */
+export function isUserMessageKey(
+	key: PaymentMessageKey,
+): key is PaymentUserMessageKey {
+	return key in DEFAULT_USER_MESSAGES;
+}