@chipmobilesdk/rn-payment 0.5.0 → 0.6.0

package/src/engine/internals.ts

@@ -0,0 +1,40 @@
+/**
+ * What tests and diagnostics need from an engine, off its public type (PAY-11).
+ *
+ * Until 0.6.0 these were methods of `PaymentEngine`, so any consumer could commit
+ * a snapshot of its own and grant itself an entitlement the store never sold,
+ * and a hand-written engine double had to implement all of them. They live in a
+ * WeakMap keyed by the engine now, and this module is not exported from the
+ * package entrypoint.
+ */
+import type { ProductKey } from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import type { PaymentEmitter } from '../diagnostics/events';
+import type { PersistedSnapshot } from '../persistence/snapshot';
+import type { PaymentEngine } from './engine';
+
+export interface EngineInternals {
+	resolvedConfig(): ResolvedConfig;
+	nextCorrelationId(): string;
+	emitter(): PaymentEmitter;
+	snapshot(): PersistedSnapshot;
+	commitSnapshot(next: PersistedSnapshot): void;
+	mayCreateRealTransaction(): boolean;
+	/** Records a purchase refused because this environment may not move real money (FR-014). */
+	recordBlockedOperation(productKey: ProductKey): void;
+}
+
+const registry = new WeakMap<PaymentEngine, EngineInternals>();
+
+export function attachEngineInternals(engine: PaymentEngine, internals: EngineInternals): void {
+	registry.set(engine, internals);
+}
+
+/** The internals of an engine `createEngine` made. Throws for any other object. */
+export function engineInternals(engine: PaymentEngine): EngineInternals {
+	const internals = registry.get(engine);
+	if (!internals) {
+		throw new Error('engineInternals: this engine was not created by createEngine');
+	}
+	return internals;
+}

package/src/engine/products.ts

@@ -188,22 +188,28 @@ export function createProducts(deps: ProductsDeps): Products {
 		}
 
 		try {
-			for (const [productType, items] of byType) {
-				const raw = await withTimeout(
-					deps.provider.queryProducts(
-						items.map(i => i.storeProductId),
-						productType,
+			// In parallel: a paywall offering a subscription and a one-time purchase
+			// used to wait for one store round-trip after the other (PAY-20).
+			const groups = await Promise.all(
+				[...byType].map(async ([productType, items]) => ({
+					items,
+					raw: await withTimeout(
+						deps.provider.queryProducts(
+							items.map(i => i.storeProductId),
+							productType,
+						),
+						resolved.timeouts.productQueryMs,
+						() =>
+							new PaymentError({
+								code: 'PAYMENT_TIMEOUT',
+								message: 'Querying products timed out',
+								operation: 'getProducts',
+								retryable: true,
+							}),
 					),
-					resolved.timeouts.productQueryMs,
-					() =>
-						new PaymentError({
-							code: 'PAYMENT_TIMEOUT',
-							message: 'Querying products timed out',
-							operation: 'getProducts',
-							retryable: true,
-						}),
-				);
-
+				})),
+			);
+			for (const { items, raw } of groups) {
 				const returned = new Map(raw.map(p => [p.storeProductId, p]));
 				for (const item of items) {
 					const found = returned.get(item.storeProductId);
@@ -251,9 +257,25 @@ export function createProducts(deps: ProductsDeps): Products {
 		return { ok: true, products: resolvedProducts, missing, fromCache: false };
 	};
 
+	/**
+	 * Identical requests in flight share one store call (PAY-20): several screens
+	 * mounting `useProducts` for the same paywall ask once.
+	 */
+	const flights = new Map<string, Promise<ProductQueryResult>>();
+	const joined = (productKeys: ProductKey[], useCache: boolean): Promise<ProductQueryResult> => {
+		const key = `${useCache ? 'get' : 'refresh'}:${productKeys.join('|')}`;
+		const running = flights.get(key);
+		if (running) {
+			return running;
+		}
+		const promise = query(productKeys, useCache).finally(() => flights.delete(key));
+		flights.set(key, promise);
+		return promise;
+	};
+
 	return {
-		get: productKeys => query(productKeys, true),
-		refresh: productKeys => query(productKeys, false),
+		get: productKeys => joined(productKeys, true),
+		refresh: productKeys => joined(productKeys, false),
 		invalidate: () => cache.clear(),
 	};
 }

package/src/engine/purchase.ts

@@ -18,6 +18,7 @@
 
 import type {
 	PaymentConfig,
+	PaymentStatusKind,
 	ProductKey,
 	PurchaseOptions,
 	PurchaseResult,
@@ -25,7 +26,6 @@ import type {
 } from '../config/types';
 import type { ResolvedConfig, TargetPlatform } from '../config/validate';
 import type {
-	ProviderFailureReason,
 	ProviderPort,
 	ProviderPurchase,
 	ProviderPurchaseOutcome,
@@ -37,13 +37,10 @@ import { withTimeout } from '../core/mutex';
 import { PURCHASE_FLOW_CEILING_MS } from '../core/timers';
 import { PaymentError } from '../diagnostics/errors';
 import type { PaymentEventInput } from '../diagnostics/events';
-import {
-	resolveFinalizeState,
-	type PersistedPurchase,
-	type PersistedSnapshot,
-} from '../persistence/snapshot';
+import type { PersistedPurchase, PersistedSnapshot } from '../persistence/snapshot';
 import { storeIdForProductKey } from '../entitlements/mapping';
 import type { Finalizer } from './finalize';
+import { toPersistedRecord } from './sync';
 
 export interface PurchaseFlowDeps {
 	config: PaymentConfig;
@@ -56,41 +53,17 @@ export interface PurchaseFlowDeps {
 	emit: (event: PaymentEventInput) => void;
 	now: () => number;
 	nextCorrelationId: () => string;
-	statusKind: () => PaymentStatusKindLike;
+	statusKind: () => PaymentStatusKind;
 	mayCreateRealTransaction: () => boolean;
 	recordBlockedOperation: (productKey: ProductKey) => void;
 	requestSync: (trigger: 'already_owned') => void;
 	runExclusive: <T>(operation: () => Promise<T>) => Promise<ExclusiveOutcome<T>>;
 }
 
-type PaymentStatusKindLike =
-	'not_started' | 'connecting' | 'ready' | 'disabled' | 'unavailable' | 'failed';
-
-/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
-function mapFailure(reason: ProviderFailureReason, productKey: ProductKey): PurchaseResult {
-	switch (reason) {
-		case 'user_cancelled':
-			return { kind: 'user_cancelled', productKey };
-		case 'already_owned':
-			return { kind: 'already_owned', productKey };
-		case 'ineligible':
-			return { kind: 'ineligible', productKey };
-		case 'unknown_product':
-			return { kind: 'unknown_product', productKey };
-		case 'product_unavailable_in_region':
-			return { kind: 'product_unavailable_in_region', productKey };
-		case 'not_ready':
-			return { kind: 'not_ready', status: 'connecting' };
-		case 'network_error':
-			return { kind: 'network_error', productKey };
-		case 'timeout':
-			return { kind: 'timeout', productKey };
-		case 'store_error':
-			return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
-	}
-}
+/** The error code each failed purchase kind is reported under (PAY-19). */
+import { createReceiptValidation } from './receiptValidation';
+import { FAILURE_CODES, mapFailure } from './purchaseFailure';
 
-/** Plan-change parameters, which only `subscriptions.ts` supplies. */
 export interface InternalPurchaseOptions extends PurchaseOptions {
 	replaceProductKey?: ProductKey;
 	prorationMode?: string;
@@ -113,6 +86,13 @@ export interface PurchaseFlow {
 
 export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 	const { resolved } = deps;
+	// The backend check and what to do when it cannot answer (receiptValidation).
+	const { askHook, validate } = createReceiptValidation({
+		config: deps.config,
+		platform: deps.platform,
+		resolved,
+		emit: deps.emit as never,
+	});
 
 	const toRef = (record: PersistedPurchase): TransactionRef => ({
 		transactionId: record.transactionId,
@@ -126,27 +106,13 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 		deps.commit({ ...snapshot, purchases: [...others, record] });
 	};
 
-	const recordFor = (purchase: ProviderPurchase, productKey: ProductKey): PersistedPurchase => {
-		const entry = resolved.entries.get(productKey);
-		const existing = deps
-			.snapshot()
-			.purchases.find(p => p.transactionId === purchase.transactionId);
-		return {
-			transactionId: purchase.transactionId,
+	const recordFor = (purchase: ProviderPurchase, productKey: ProductKey): PersistedPurchase =>
+		toPersistedRecord(
+			resolved,
+			purchase,
 			productKey,
-			productType: entry?.productType ?? 'one_time_permanent',
-			token: purchase.token,
-			state: purchase.state === 'pending' ? 'pending' : 'purchased',
-			purchasedAt: purchase.purchasedAt,
-			// Shared with the sync path so the two cannot disagree about what is still
-			// owed a finalize call.
-			finalizeState: resolveFinalizeState(purchase, existing),
-			attempts: existing?.attempts ?? 0,
-			validationState: existing?.validationState ?? 'not_required',
-			expiresAt: purchase.expiresAt,
-			willAutoRenew: purchase.willAutoRenew,
-		};
-	};
+			deps.snapshot().purchases.find(p => p.transactionId === purchase.transactionId),
+		);
 
 	/**
 	 * Calls the app's hook under `timeouts.validateMs`.
@@ -155,71 +121,6 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 	 * revalidation, the sync flight for the rest of the session. A timeout rejects,
 	 * so callers treat it exactly like a hook that throws: unavailable (FR-072b).
 	 */
-	const askHook = (
-		hook: NonNullable<PaymentConfig['validateTransaction']>,
-		candidate: Parameters<NonNullable<PaymentConfig['validateTransaction']>>[0],
-	) =>
-		withTimeout(
-			hook(candidate),
-			resolved.timeouts.validateMs,
-			() =>
-				new PaymentError({
-					code: 'PAYMENT_VALIDATION_UNAVAILABLE',
-					message: 'The validation hook did not answer in time',
-					operation: 'validate',
-					retryable: true,
-				}),
-		);
-
-	/**
-	 * Runs the app's backend check, if configured.
-	 *
-	 * Called for newly completed purchases only (FR-069a) — sync and restore trust
-	 * a decision already made, which is what keeps restore working while the
-	 * backend is unreachable.
-	 */
-	const validate = async (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-		correlationId: string,
-	): Promise<
-		| { outcome: 'approved' }
-		| { outcome: 'rejected'; reason?: string }
-		| { outcome: 'granted_pending_revalidation' }
-	> => {
-		const hook = deps.config.validateTransaction;
-		if (!hook) {
-			return { outcome: 'approved' };
-		}
-
-		const entry = resolved.entries.get(productKey);
-		try {
-			const decision = await askHook(hook, {
-				productKey,
-				productType: entry?.productType ?? 'one_time_permanent',
-				verificationPayload: purchase.verificationPayload ?? '',
-				correlationId,
-				transactionId: purchase.transactionId,
-				platform: deps.platform,
-			});
-			deps.emit({
-				type: 'validation_decided',
-				productKey,
-				decision: decision.approved ? 'approved' : 'rejected',
-			});
-			return decision.approved
-				? { outcome: 'approved' }
-				: { outcome: 'rejected', reason: decision.reason };
-		} catch {
-			// A hook that throws is unavailable, never an implicit approval (FR-072b).
-			const fallback = resolved.onValidationUnavailable;
-			deps.emit({ type: 'validation_unavailable', productKey, fallback });
-			return fallback === 'grant_and_queue'
-				? { outcome: 'granted_pending_revalidation' }
-				: { outcome: 'rejected', reason: 'validation_unavailable' };
-		}
-	};
-
 	/**
 	 * Settlements in progress, by transaction.
 	 *
@@ -434,7 +335,7 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 				}
 
 				if (!outcome.ok) {
-					const mapped = mapFailure(outcome.reason, productKey);
+					const mapped = mapFailure(outcome.reason, productKey, deps.statusKind());
 
 					if (mapped.kind === 'user_cancelled') {
 						// A normal outcome. Reported on its own channel so it is never
@@ -452,16 +353,7 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 					deps.emit({
 						type: 'purchase_failed',
 						productKey,
-						code:
-							mapped.kind === 'network_error'
-								? 'PAYMENT_NETWORK_ERROR'
-								: mapped.kind === 'unknown_product'
-									? 'PAYMENT_UNKNOWN_PRODUCT'
-									: mapped.kind === 'ineligible'
-										? 'PAYMENT_INELIGIBLE'
-										: mapped.kind === 'product_unavailable_in_region'
-											? 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
-											: 'PAYMENT_STORE_ERROR',
+						code: FAILURE_CODES[mapped.kind] ?? 'PAYMENT_STORE_ERROR',
 						retryable: mapped.kind === 'network_error',
 						correlationId,
 					});

package/src/engine/purchaseFailure.ts

@@ -0,0 +1,48 @@
+/**
+ * What a refused purchase means to the app (PAY-19).
+ *
+ * The store answers with a reason of its own; this turns it into the result the
+ * app sees, under the code it can branch on, so no store vocabulary leaks out.
+ * Split from the flow next door, which is about the sequence of calls.
+ */
+import type { ProviderFailureReason } from '../adapter/port';
+import type { PaymentStatusKind, ProductKey, PurchaseResult } from '../config/types';
+import type { PaymentErrorCode } from '../diagnostics/errors';
+
+export const FAILURE_CODES: Partial<Record<PurchaseResult['kind'], PaymentErrorCode>> = {
+	network_error: 'PAYMENT_NETWORK_ERROR',
+	unknown_product: 'PAYMENT_UNKNOWN_PRODUCT',
+	ineligible: 'PAYMENT_INELIGIBLE',
+	product_unavailable_in_region: 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION',
+};
+
+/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
+export function mapFailure(
+	reason: ProviderFailureReason,
+	productKey: ProductKey,
+	status: PaymentStatusKind,
+): PurchaseResult {
+	switch (reason) {
+		case 'user_cancelled':
+			return { kind: 'user_cancelled', productKey };
+		case 'already_owned':
+			return { kind: 'already_owned', productKey };
+		case 'ineligible':
+			return { kind: 'ineligible', productKey };
+		case 'unknown_product':
+			return { kind: 'unknown_product', productKey };
+		case 'product_unavailable_in_region':
+			return { kind: 'product_unavailable_in_region', productKey };
+		case 'not_ready':
+			// The engine's real status, not a guess (PAY-19).
+			return { kind: 'not_ready', status };
+		case 'network_error':
+			return { kind: 'network_error', productKey };
+		case 'timeout':
+			return { kind: 'timeout', productKey };
+		case 'store_error':
+			return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
+	}
+}
+
+/** Plan-change parameters, which only `subscriptions.ts` supplies. */

package/src/engine/receiptValidation.ts

@@ -0,0 +1,101 @@
+/**
+ * Asking the app's backend whether a purchase is real (FR-069a, FR-072b).
+ *
+ * The hook is optional and bounded by a timeout, and its answer decides whether
+ * an entitlement is granted — so what happens when it throws, times out, or is
+ * absent is the whole point of this module. Split from the flow next door,
+ * which is about the sequence of store calls.
+ *
+ * A hook that could not answer is never an implicit approval: the configured
+ * `onValidationUnavailable` decides, and the default refuses.
+ */
+import type { ProviderPurchase } from '../adapter/port';
+import type { PaymentConfig, ProductKey } from '../config/types';
+import type { ResolvedConfig, TargetPlatform } from '../config/validate';
+import type { PaymentEventInput } from '../diagnostics/events';
+import { withTimeout } from '../core/mutex';
+import { PaymentError } from '../diagnostics/errors';
+
+export interface ReceiptValidationDeps {
+	config: PaymentConfig;
+	platform: TargetPlatform;
+	resolved: ResolvedConfig;
+	emit: (event: PaymentEventInput) => void;
+}
+
+/** What the backend decided about one purchase. */
+export type ValidationOutcome =
+	| { outcome: 'approved' }
+	| { outcome: 'rejected'; reason?: string }
+	| { outcome: 'granted_pending_revalidation' };
+
+export function createReceiptValidation(deps: ReceiptValidationDeps) {
+	const { resolved } = deps;
+
+	const askHook = (
+		hook: NonNullable<PaymentConfig['validateTransaction']>,
+		candidate: Parameters<NonNullable<PaymentConfig['validateTransaction']>>[0],
+	) =>
+		withTimeout(
+			hook(candidate),
+			resolved.timeouts.validateMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_VALIDATION_UNAVAILABLE',
+					message: 'The validation hook did not answer in time',
+					operation: 'validate',
+					retryable: true,
+				}),
+		);
+
+	/**
+	 * Runs the app's backend check, if configured.
+	 *
+	 * Called for newly completed purchases only (FR-069a) — sync and restore trust
+	 * a decision already made, which is what keeps restore working while the
+	 * backend is unreachable.
+	 */
+	const validate = async (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<
+		| { outcome: 'approved' }
+		| { outcome: 'rejected'; reason?: string }
+		| { outcome: 'granted_pending_revalidation' }
+	> => {
+		const hook = deps.config.validateTransaction;
+		if (!hook) {
+			return { outcome: 'approved' };
+		}
+
+		const entry = resolved.entries.get(productKey);
+		try {
+			const decision = await askHook(hook, {
+				productKey,
+				productType: entry?.productType ?? 'one_time_permanent',
+				verificationPayload: purchase.verificationPayload ?? '',
+				correlationId,
+				transactionId: purchase.transactionId,
+				platform: deps.platform,
+			});
+			deps.emit({
+				type: 'validation_decided',
+				productKey,
+				decision: decision.approved ? 'approved' : 'rejected',
+			});
+			return decision.approved
+				? { outcome: 'approved' }
+				: { outcome: 'rejected', reason: decision.reason };
+		} catch {
+			// A hook that throws is unavailable, never an implicit approval (FR-072b).
+			const fallback = resolved.onValidationUnavailable;
+			deps.emit({ type: 'validation_unavailable', productKey, fallback });
+			return fallback === 'grant_and_queue'
+				? { outcome: 'granted_pending_revalidation' }
+				: { outcome: 'rejected', reason: 'validation_unavailable' };
+		}
+	};
+
+	return { askHook, validate };
+}