@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/core/timers.ts

@@ -0,0 +1,249 @@
+/**
+ * Timeout, retry, and cache policy.
+ *
+ * Defaults and bounds live here rather than at each call site so there is one
+ * place to read what the package will wait for, and so consumers can read the
+ * values they are bound by instead of discovering them from a timeout in
+ * production.
+ *
+ * Out-of-band values are a configuration error rather than being silently
+ * clamped: quietly turning a 1-second timeout into 3 seconds would tell the app
+ * it configured something it did not.
+ */
+
+import { PaymentConfigError } from '../diagnostics/errors';
+import type {
+	BackoffConfig,
+	RetryConfig,
+	TimeoutConfig,
+} from '../config/types';
+
+/** Local IPC to Play Services. Slower than this means unavailable, not busy. */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/** A network round trip; a paywall that hangs longer should show its error state. */
+export const DEFAULT_PRODUCT_QUERY_TIMEOUT_MS = 15_000;
+/** Runs at startup, so it must not hold the first render hostage. */
+export const DEFAULT_SYNC_TIMEOUT_MS = 20_000;
+/**
+ * Covers opening the store surface only.
+ *
+ * Time the user spends *inside* the store's own UI is deliberately excluded
+ * (FR-035): a user reading the terms, switching to their banking app for an OTP,
+ * or simply hesitating must never have their purchase cancelled by our clock.
+ */
+export const DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS = 30_000;
+/** Per finalize attempt, not per transaction — the queue owns overall persistence. */
+export const DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS = 15_000;
+
+export const CONNECT_TIMEOUT_BOUNDS = { min: 3_000, max: 60_000 } as const;
+export const PRODUCT_QUERY_TIMEOUT_BOUNDS = { min: 3_000, max: 60_000 } as const;
+export const SYNC_TIMEOUT_BOUNDS = { min: 5_000, max: 120_000 } as const;
+export const PURCHASE_LAUNCH_TIMEOUT_BOUNDS = {
+	min: 5_000,
+	max: 120_000,
+} as const;
+export const FINALIZE_ATTEMPT_TIMEOUT_BOUNDS = {
+	min: 3_000,
+	max: 60_000,
+} as const;
+
+/**
+ * Prices and offer eligibility are shown at the moment of purchase, so a short
+ * TTL with on-demand refresh beats a long one (FR-029).
+ */
+export const DEFAULT_PRODUCT_CACHE_TTL_MS = 900_000;
+export const PRODUCT_CACHE_TTL_BOUNDS = { min: 60_000, max: 86_400_000 } as const;
+
+/**
+ * How long a successful sync keeps entitlements trustworthy offline: **7 days**.
+ *
+ * Fixed by the specification (FR-055) after weighing both failure directions.
+ * The realistic offline cases — travel, poor coverage, a device left unused —
+ * resolve within days. Seven days covers a holiday without connectivity while
+ * bounding how long a refunded entitlement can outlive its refund to one week.
+ *
+ * Past this the entitlement becomes `unknown`, never `not_entitled` (FR-055a):
+ * the package stops asserting rather than telling a paying customer they did not
+ * pay.
+ */
+export const DEFAULT_STALE_AFTER_MS = 604_800_000;
+export const STALE_AFTER_BOUNDS = {
+	min: 3_600_000,
+	max: 7_776_000_000,
+} as const;
+
+/** Keeps rapid app switching from becoming a request storm (PERF-002). */
+export const DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS = 60_000;
+export const FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS = {
+	min: 0,
+	max: 3_600_000,
+} as const;
+
+/** Bounded so a dropped billing connection cannot become a retry storm (FR-020). */
+export const DEFAULT_RECONNECT_BACKOFF: Required<BackoffConfig> = {
+	initialDelayMs: 1_000,
+	maxDelayMs: 30_000,
+	factor: 2,
+	maxAttempts: 5,
+	jitter: true,
+};
+
+/**
+ * Finalize retry.
+ *
+ * Bounded **per session** but never permanently abandoned: Google auto-refunds
+ * an unacknowledged purchase after three days, so exhausting this session's
+ * attempts must leave the transaction queued for the next launch, not dropped
+ * (FR-045).
+ */
+export const DEFAULT_FINALIZE_BACKOFF: Required<BackoffConfig> = {
+	initialDelayMs: 2_000,
+	maxDelayMs: 60_000,
+	factor: 2,
+	maxAttempts: 5,
+	jitter: true,
+};
+
+export const BACKOFF_MAX_DELAY_BOUNDS = { min: 5_000, max: 600_000 } as const;
+export const BACKOFF_ATTEMPT_BOUNDS = { min: 1, max: 10 } as const;
+
+interface Bounds {
+	readonly min: number;
+	readonly max: number;
+}
+
+function requireInBounds(
+	label: string,
+	value: number | undefined,
+	fallback: number,
+	bounds: Bounds,
+): number {
+	if (value === undefined) {
+		return fallback;
+	}
+	if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CATALOG',
+			message: `${label} must be between ${bounds.min} and ${bounds.max}ms, received ${value}`,
+			operation: 'configure',
+			offenders: [label],
+		});
+	}
+	return value;
+}
+
+export interface ResolvedTimeouts {
+	connectMs: number;
+	productQueryMs: number;
+	syncMs: number;
+	purchaseLaunchMs: number;
+	finalizeAttemptMs: number;
+}
+
+export function resolveTimeouts(config?: TimeoutConfig): ResolvedTimeouts {
+	return {
+		connectMs: requireInBounds(
+			'timeouts.connectMs',
+			config?.connectMs,
+			DEFAULT_CONNECT_TIMEOUT_MS,
+			CONNECT_TIMEOUT_BOUNDS,
+		),
+		productQueryMs: requireInBounds(
+			'timeouts.productQueryMs',
+			config?.productQueryMs,
+			DEFAULT_PRODUCT_QUERY_TIMEOUT_MS,
+			PRODUCT_QUERY_TIMEOUT_BOUNDS,
+		),
+		syncMs: requireInBounds(
+			'timeouts.syncMs',
+			config?.syncMs,
+			DEFAULT_SYNC_TIMEOUT_MS,
+			SYNC_TIMEOUT_BOUNDS,
+		),
+		purchaseLaunchMs: requireInBounds(
+			'timeouts.purchaseLaunchMs',
+			config?.purchaseLaunchMs,
+			DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS,
+			PURCHASE_LAUNCH_TIMEOUT_BOUNDS,
+		),
+		finalizeAttemptMs: requireInBounds(
+			'timeouts.finalizeAttemptMs',
+			config?.finalizeAttemptMs,
+			DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS,
+			FINALIZE_ATTEMPT_TIMEOUT_BOUNDS,
+		),
+	};
+}
+
+function resolveBackoff(
+	label: string,
+	config: BackoffConfig | undefined,
+	fallback: Required<BackoffConfig>,
+): Required<BackoffConfig> {
+	const maxDelayMs = requireInBounds(
+		`${label}.maxDelayMs`,
+		config?.maxDelayMs,
+		fallback.maxDelayMs,
+		BACKOFF_MAX_DELAY_BOUNDS,
+	);
+	const maxAttempts = requireInBounds(
+		`${label}.maxAttempts`,
+		config?.maxAttempts,
+		fallback.maxAttempts,
+		BACKOFF_ATTEMPT_BOUNDS,
+	);
+	return {
+		initialDelayMs: config?.initialDelayMs ?? fallback.initialDelayMs,
+		maxDelayMs,
+		factor: config?.factor ?? fallback.factor,
+		maxAttempts,
+		jitter: config?.jitter ?? fallback.jitter,
+	};
+}
+
+export interface ResolvedRetry {
+	reconnect: Required<BackoffConfig>;
+	finalize: Required<BackoffConfig>;
+}
+
+export function resolveRetry(config?: RetryConfig): ResolvedRetry {
+	return {
+		reconnect: resolveBackoff(
+			'retry.reconnect',
+			config?.reconnect,
+			DEFAULT_RECONNECT_BACKOFF,
+		),
+		finalize: resolveBackoff(
+			'retry.finalize',
+			config?.finalize,
+			DEFAULT_FINALIZE_BACKOFF,
+		),
+	};
+}
+
+export function resolveStaleAfterMs(value?: number): number {
+	return requireInBounds(
+		'staleAfterMs',
+		value,
+		DEFAULT_STALE_AFTER_MS,
+		STALE_AFTER_BOUNDS,
+	);
+}
+
+export function resolveProductCacheTtlMs(value?: number): number {
+	return requireInBounds(
+		'productCacheTtlMs',
+		value,
+		DEFAULT_PRODUCT_CACHE_TTL_MS,
+		PRODUCT_CACHE_TTL_BOUNDS,
+	);
+}
+
+export function resolveForegroundSyncMinIntervalMs(value?: number): number {
+	return requireInBounds(
+		'foregroundSyncMinIntervalMs',
+		value,
+		DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS,
+		FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS,
+	);
+}

package/src/diagnostics/errors.ts

@@ -0,0 +1,110 @@
+/**
+ * Normalized public errors.
+ *
+ * Error codes are **public API**: renaming one is a breaking change (FR-078,
+ * LIB-008). They are the vocabulary an app branches on, so they must outlive any
+ * internal refactor and must never leak a store's own code.
+ */
+
+export const PAYMENT_ERROR_CODES = [
+	'PAYMENT_NOT_CONFIGURED',
+	'PAYMENT_INVALID_CATALOG',
+	'PAYMENT_NOT_READY',
+	'PAYMENT_DISABLED',
+	'PAYMENT_UNAVAILABLE',
+	'PAYMENT_UNSUPPORTED_PLATFORM',
+	'PAYMENT_ENVIRONMENT_BLOCKED',
+	'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
+	'PAYMENT_PURCHASE_IN_PROGRESS',
+	'PAYMENT_USER_CANCELLED',
+	'PAYMENT_PENDING',
+	'PAYMENT_ALREADY_OWNED',
+	'PAYMENT_INELIGIBLE',
+	'PAYMENT_UNKNOWN_PRODUCT',
+	'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION',
+	'PAYMENT_TIMEOUT',
+	'PAYMENT_NETWORK_ERROR',
+	'PAYMENT_STORE_ERROR',
+	'PAYMENT_FINALIZE_FAILED',
+	'PAYMENT_VALIDATION_REJECTED',
+	'PAYMENT_VALIDATION_UNAVAILABLE',
+	'PAYMENT_STORAGE_UNAVAILABLE',
+] as const;
+
+export type PaymentErrorCode = (typeof PAYMENT_ERROR_CODES)[number];
+
+/** Which operation produced an error. Part of the public error shape (FR-078). */
+export type PaymentOperation =
+	| 'configure'
+	| 'initialize'
+	| 'getProducts'
+	| 'purchase'
+	| 'finalize'
+	| 'consume'
+	| 'sync'
+	| 'restore'
+	| 'changePlan'
+	| 'validate'
+	| 'persist';
+
+export class PaymentError extends Error {
+	readonly code: PaymentErrorCode;
+	readonly operation: PaymentOperation;
+	readonly retryable: boolean;
+	/** Redacted where appropriate — never a raw receipt, token, or store object (FR-074). */
+	readonly cause?: string;
+
+	constructor(init: {
+		code: PaymentErrorCode;
+		message: string;
+		operation: PaymentOperation;
+		retryable?: boolean;
+		cause?: string;
+	}) {
+		super(init.message);
+		this.name = 'PaymentError';
+		this.code = init.code;
+		this.operation = init.operation;
+		this.retryable = init.retryable ?? false;
+		this.cause = init.cause;
+	}
+}
+
+/**
+ * A configuration problem the app can act on.
+ *
+ * Separate from `PaymentError` because configuration faults are developer-facing
+ * and must never be shown to an end user — the message-key map keeps that
+ * separation explicit (FR-085).
+ */
+export class PaymentConfigError extends PaymentError {
+	/** The offending catalog entries or entitlement keys, named (FR-011). */
+	readonly offenders: string[];
+
+	constructor(init: {
+		code: PaymentErrorCode;
+		message: string;
+		operation: PaymentOperation;
+		offenders?: string[];
+	}) {
+		super({ ...init, retryable: false });
+		this.name = 'PaymentConfigError';
+		this.offenders = init.offenders ?? [];
+	}
+}
+
+/**
+ * Strips anything that must never reach a log or event.
+ *
+ * Applied at the boundary rather than trusted to call sites: a single forgotten
+ * interpolation is how receipts end up in logs (NFR-006).
+ */
+export function redact(value: unknown): string {
+	if (value instanceof Error) {
+		return value.message;
+	}
+	if (typeof value === 'string') {
+		return value;
+	}
+	return '[redacted]';
+}

package/src/diagnostics/events.ts

@@ -0,0 +1,266 @@
+/**
+ * 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 };