@chipmobilesdk/rn-payment 0.3.1 → 0.4.0

package/src/engine/engine.ts

@@ -186,7 +186,8 @@ export function createEngine(
 	// Both run before anything connects: a bad catalog or an unsafe environment
 	// must fail at configuration time, not when a user taps Buy.
 	assertEnvironmentSafe(config);
-	const resolved = validateConfig(config, deps.platform ?? 'android');
+	const platform = deps.platform ?? 'android';
+	const resolved = validateConfig(config, platform);
 
 	const now = deps.now ?? (() => Date.now());
 	const provider = deps.provider;
@@ -204,6 +205,8 @@ export function createEngine(
 
 	const initFlight = createSingleFlight<InitOutcome>();
 	const syncFlight = createSingleFlight<SyncOutcome>();
+	/** Finalize drain and revalidation, joined the same way but outside the sync flight. */
+	const settleFlight = createSingleFlight<void>();
 	const foregroundLimiter = createRateLimiter(
 		resolved.foregroundSyncMinIntervalMs,
 		now,
@@ -227,6 +230,12 @@ export function createEngine(
 	let purchaseSub: Unsubscribe | undefined;
 	let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
 	let reconnectAttempts = 0;
+	/**
+	 * Set once a connection has succeeded and the watchers are attached. Recovery
+	 * after an exhausted reconnect budget is only meaningful from there; a first
+	 * connection that failed is the app's to retry through `initialize`.
+	 */
+	let everConnected = false;
 	// Exclusive rather than single-flight: a second purchase must be refused, not
 	// joined onto the first, and never queued (FR-031).
 	const purchaseLock = createExclusive();
@@ -425,7 +434,14 @@ export function createEngine(
 	};
 
 	const scheduleReconnect = (): void => {
-		if (disposed || reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+		if (disposed) {
+			return;
+		}
+		if (reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+			// Out of budget for now, not for good. Reported as a retryable failure
+			// rather than left at `connecting`, which promised a reconnect nobody
+			// was going to make; `handleForeground` starts a fresh budget.
+			setStatus({ kind: 'failed', retryable: true, reconnectAttempts });
 			return;
 		}
 		const attempt = reconnectAttempts + 1;
@@ -468,6 +484,7 @@ export function createEngine(
 	const finalizer = createFinalizer({
 		provider,
 		retry: resolved.retry,
+		attemptTimeoutMs: resolved.timeouts.finalizeAttemptMs,
 		snapshot: () => currentSnapshot,
 		commit,
 		emit,
@@ -486,6 +503,7 @@ export function createEngine(
 		config,
 		resolved,
 		provider,
+		platform,
 		finalizer,
 		snapshot: () => currentSnapshot,
 		commit,
@@ -521,6 +539,8 @@ export function createEngine(
 	 * purchase is open.
 	 */
 	const watchPurchases = (): void => {
+		// Replaced, never stacked: a second subscription would ingest every update twice.
+		purchaseSub?.();
 		purchaseSub = provider.observePurchases(purchase => {
 			if (disposed) {
 				return;
@@ -530,6 +550,7 @@ export function createEngine(
 	};
 
 	const watchConnection = (): void => {
+		connectionSub?.();
 		connectionSub = provider.observeConnection((connected, reason) => {
 			if (disposed) {
 				return;
@@ -567,6 +588,13 @@ export function createEngine(
 				};
 			}
 
+			// Already up: answered without reconnecting. `initFlight` only joins
+			// concurrent callers, so a later sequential call used to run the whole
+			// connection again and leave a second set of native listeners behind.
+			if (status.kind === 'ready') {
+				return { ok: true };
+			}
+
 			return initFlight.run(async () => {
 				if (disposed) {
 					return {
@@ -639,6 +667,7 @@ export function createEngine(
 
 				watchConnection();
 				watchPurchases();
+				everConnected = true;
 				setStatus({ kind: 'ready', reconnectAttempts: 0 });
 				await engine.sync('initialize');
 				// Drain after syncing, so a transaction the store still reports as owned
@@ -753,7 +782,7 @@ export function createEngine(
 
 			// Concurrent callers join one flight, so repeated syncs make exactly one
 			// store request (FR-063).
-			return syncFlight.run(async () => {
+			const outcome = await syncFlight.run(async () => {
 				try {
 					const owned = await withTimeout(
 						provider.queryOwned(),
@@ -806,17 +835,6 @@ export function createEngine(
 						trigger,
 					});
 
-					// Every sync is also a chance to settle what a previous session left
-					// owed. A pending purchase that completed while the app was closed
-					// arrives here, and so does a transaction whose acknowledgement failed
-					// last time (FR-039, FR-042).
-					await finalizer.drain();
-
-					// And a chance to settle a backend decision we had to defer. Done on
-					// sync rather than on a timer of ours, so recovery follows the app's
-					// own rhythm (FR-072a).
-					await purchaseFlow.revalidate();
-
 					return { ok: true as const, restoredCount, revokedCount };
 				} catch (error) {
 					const paymentError =
@@ -838,6 +856,23 @@ export function createEngine(
 					return { ok: false as const, error: paymentError };
 				}
 			});
+
+			if (outcome.ok) {
+				// Every sync is also a chance to settle what a previous session left
+				// owed — a pending purchase that completed while the app was closed, a
+				// transaction whose acknowledgement failed last time (FR-039, FR-042) —
+				// and a backend decision we had to defer, on the app's own rhythm
+				// rather than a timer of ours (FR-072a).
+				//
+				// Outside the sync flight on purpose. Inside it, one store call or hook
+				// that never answered held the flight, and every later sync joined that
+				// same stuck promise for the rest of the session.
+				await settleFlight.run(async () => {
+					await finalizer.drain();
+					await purchaseFlow.revalidate();
+				});
+			}
+			return outcome;
 		},
 
 		async restore(): Promise<RestoreOutcome> {
@@ -922,6 +957,19 @@ export function createEngine(
 		},
 
 		async handleForeground(): Promise<void> {
+			// A foreground return is the natural moment to try again after the
+			// reconnect budget ran out: the network the app lost while backgrounded
+			// is usually back. A fresh budget, and one immediate attempt.
+			if (
+				everConnected &&
+				!disposed &&
+				status.kind === 'failed' &&
+				reconnectTimer === undefined
+			) {
+				reconnectAttempts = 0;
+				setStatus({ kind: 'connecting', reconnectAttempts: 0 });
+				await reconnectOnce().catch(() => undefined);
+			}
 			// Rate-limited inside sync, so an app that calls this on every incidental
 			// foreground transition still produces at most one request per interval.
 			await engine.sync('foreground');

package/src/engine/finalize.ts

@@ -25,6 +25,8 @@ import type {
 import type { ProviderPort } from '../adapter/port';
 import type { ResolvedRetry } from '../core/timers';
 import { backoffDelayMs } from '../core/retry';
+import { withTimeout } from '../core/mutex';
+import { PaymentError } from '../diagnostics/errors';
 import {
 	pendingFinalizations,
 	type PersistedPurchase,
@@ -35,6 +37,8 @@ import type { PaymentEventInput } from '../diagnostics/events';
 export interface FinalizerDeps {
 	provider: ProviderPort;
 	retry: ResolvedRetry;
+	/** `timeouts.finalizeAttemptMs`: one acknowledge or consume call may take no longer. */
+	attemptTimeoutMs: number;
 	snapshot: () => PersistedSnapshot;
 	commit: (next: PersistedSnapshot) => void;
 	emit: (event: PaymentEventInput) => void;
@@ -86,6 +90,25 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 		});
 	};
 
+	/**
+	 * One store call under `attemptTimeoutMs`. A call that never settles used to
+	 * hold this transaction's in-flight guard and, through `drain`, the sync that
+	 * awaited it. Timing out counts as a failed attempt, so the retry schedule and
+	 * the next-session drain both still apply.
+	 */
+	const bounded = (call: Promise<void>, operation: 'finalize' | 'consume'): Promise<void> =>
+		withTimeout(
+			call,
+			deps.attemptTimeoutMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_TIMEOUT',
+					message: `The store did not answer the ${operation} call in time`,
+					operation,
+					retryable: true,
+				}),
+		);
+
 	const clearTimer = (transactionId: string): void => {
 		const timer = timers.get(transactionId);
 		if (timer !== undefined) {
@@ -128,7 +151,7 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 
 		let failed = false;
 		try {
-			await deps.provider.acknowledge(record.token);
+			await bounded(deps.provider.acknowledge(record.token), 'finalize');
 		} catch {
 			failed = true;
 		} finally {
@@ -157,7 +180,72 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 		}
 
 		patch(transactionId, { finalizeState: 'failed', attempts });
-		return scheduleRetry(transactionId, record.productKey, attempts);
+		return scheduleRetry(transactionId, record.productKey, attempts, 'acknowledge');
+	};
+
+	/**
+	 * One consume call for a consumable the app has banked (FR-043).
+	 *
+	 * Refuses anything that is not a settled consumable. Consuming a subscription
+	 * or a permanent unlock would tell the store the user used it up, and a
+	 * pending purchase has nothing to consume yet.
+	 */
+	const consumeAttempt = async (transactionId: string): Promise<FinalizeResult> => {
+		if (deps.disposed()) {
+			return { kind: 'failed', code: 'PAYMENT_NOT_CONFIGURED' };
+		}
+		const record = find(transactionId);
+		if (!record) {
+			return { kind: 'unknown_transaction' };
+		}
+		if (record.productType !== 'one_time_consumable') {
+			return { kind: 'failed', code: 'PAYMENT_NOT_CONSUMABLE' };
+		}
+		if (record.state === 'pending') {
+			return { kind: 'failed', code: 'PAYMENT_PENDING' };
+		}
+		if (record.state === 'consumed') {
+			// Consuming twice must grant the item once (FR-044).
+			return { kind: 'already_finalized' };
+		}
+		if (inFlight.has(transactionId)) {
+			// Concurrent consume calls collapse to one, for the same reason.
+			return { kind: 'already_finalized' };
+		}
+
+		inFlight.add(transactionId);
+		patch(transactionId, { finalizeState: 'in_flight' });
+
+		let failed = false;
+		try {
+			await bounded(deps.provider.consume(record.token), 'consume');
+		} catch {
+			failed = true;
+		} finally {
+			// Released before scheduling, for the same reason as in `attempt`.
+			inFlight.delete(transactionId);
+		}
+
+		const attempts = record.attempts + 1;
+
+		if (failed) {
+			patch(transactionId, { finalizeState: 'failed', attempts });
+			return scheduleRetry(transactionId, record.productKey, attempts, 'consume');
+		}
+
+		clearTimer(transactionId);
+		// `consumed` is what stops it being an entitlement source, so a
+		// consumable never becomes a permanent unlock.
+		patch(transactionId, {
+			state: 'consumed',
+			finalizeState: 'done',
+			attempts,
+		});
+		deps.emit({
+			type: 'transaction_consumed',
+			productKey: record.productKey,
+		});
+		return { kind: 'finalized' };
 	};
 
 	/**
@@ -172,6 +260,10 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 		transactionId: string,
 		productKey: ProductKey,
 		attempts: number,
+		// The timer must repeat the call that failed. Retrying a failed consume
+		// through `attempt` was a no-op — `attempt` skips consumables — while the
+		// event still reported a retry as scheduled.
+		operation: 'acknowledge' | 'consume',
 	): FinalizeResult => {
 		if (deps.disposed()) {
 			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
@@ -187,7 +279,8 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 			transactionId,
 			setTimeoutFn(() => {
 				timers.delete(transactionId);
-				attempt(transactionId).catch(() => undefined);
+				const retry = operation === 'consume' ? consumeAttempt : attempt;
+				retry(transactionId).catch(() => undefined);
 			}, delayMs),
 		);
 
@@ -229,53 +322,8 @@ export function createFinalizer(deps: FinalizerDeps): Finalizer {
 			}
 		},
 
-		async consume(ref: TransactionRef): Promise<FinalizeResult> {
-			const record = find(ref.transactionId);
-			if (!record) {
-				return { kind: 'unknown_transaction' };
-			}
-			if (record.state === 'consumed') {
-				// Consuming twice must grant the item once (FR-044).
-				return { kind: 'already_finalized' };
-			}
-			if (inFlight.has(ref.transactionId)) {
-				// Concurrent consume calls collapse to one, for the same reason.
-				return { kind: 'already_finalized' };
-			}
-
-			inFlight.add(ref.transactionId);
-			patch(ref.transactionId, { finalizeState: 'in_flight' });
-
-			let failed = false;
-			try {
-				await deps.provider.consume(record.token);
-			} catch {
-				failed = true;
-			} finally {
-				// Released before scheduling, for the same reason as in `attempt`.
-				inFlight.delete(ref.transactionId);
-			}
-
-			const attempts = record.attempts + 1;
-
-			if (failed) {
-				patch(ref.transactionId, { finalizeState: 'failed', attempts });
-				return scheduleRetry(ref.transactionId, record.productKey, attempts);
-			}
-
-			clearTimer(ref.transactionId);
-			// `consumed` is what stops it being an entitlement source, so a
-			// consumable never becomes a permanent unlock.
-			patch(ref.transactionId, {
-				state: 'consumed',
-				finalizeState: 'done',
-				attempts,
-			});
-			deps.emit({
-				type: 'transaction_consumed',
-				productKey: record.productKey,
-			});
-			return { kind: 'finalized' };
+		consume(ref: TransactionRef): Promise<FinalizeResult> {
+			return consumeAttempt(ref.transactionId);
 		},
 
 		unfinalized(): UnfinalizedSummary[] {

package/src/engine/purchase.ts

@@ -23,7 +23,7 @@ import type {
 	PurchaseResult,
 	TransactionRef,
 } from '../config/types';
-import type { ResolvedConfig } from '../config/validate';
+import type { ResolvedConfig, TargetPlatform } from '../config/validate';
 import type {
 	ProviderFailureReason,
 	ProviderPort,
@@ -34,6 +34,7 @@ import type {
 } from '../adapter/port';
 import type { ExclusiveOutcome } from '../core/mutex';
 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 {
@@ -48,6 +49,7 @@ export interface PurchaseFlowDeps {
 	config: PaymentConfig;
 	resolved: ResolvedConfig;
 	provider: ProviderPort;
+	platform: TargetPlatform;
 	finalizer: Finalizer;
 	snapshot: () => PersistedSnapshot;
 	commit: (next: PersistedSnapshot) => void;
@@ -162,6 +164,29 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 		};
 	};
 
+	/**
+	 * Calls the app's hook under `timeouts.validateMs`.
+	 *
+	 * Unbounded, a hook that never answers held the purchase lock and, through
+	 * 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.
 	 *
@@ -185,11 +210,13 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 
 		const entry = resolved.entries.get(productKey);
 		try {
-			const decision = await hook({
+			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',
@@ -209,6 +236,32 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 		}
 	};
 
+	/**
+	 * Settlements in progress, by transaction.
+	 *
+	 * The Play binding delivers a launched purchase twice: to the launch and, at
+	 * the same moment, to the session-long update listener. Both paths reach
+	 * `settle`, and without this the hook ran twice and the purchase was settled
+	 * twice. The second caller joins the first and gets the same result.
+	 */
+	const inFlightSettle = new Map<string, Promise<PurchaseResult>>();
+
+	const settleOnce = (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<PurchaseResult> => {
+		const running = inFlightSettle.get(purchase.transactionId);
+		if (running) {
+			return running;
+		}
+		const flight = settle(purchase, productKey, correlationId).finally(() => {
+			inFlightSettle.delete(purchase.transactionId);
+		});
+		inFlightSettle.set(purchase.transactionId, flight);
+		return flight;
+	};
+
 	/** Persists a completed purchase, grants it, then finalizes. */
 	const settle = async (
 		purchase: ProviderPurchase,
@@ -264,8 +317,16 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 		purchase: ProviderPurchase,
 		productKey: ProductKey,
 	): PurchaseResult => {
+		// The same pending transaction arrives from the launch and from the update
+		// listener (see `inFlightSettle`). The signal is about a purchase becoming
+		// pending, so it fires once per transaction, not once per delivery.
+		const alreadyPending = deps
+			.snapshot()
+			.purchases.some(p => p.transactionId === purchase.transactionId && p.state === 'pending');
 		upsert(recordFor(purchase, productKey));
-		deps.emit({ type: 'purchase_pending', productKey });
+		if (!alreadyPending) {
+			deps.emit({ type: 'purchase_pending', productKey });
+		}
 		return {
 			kind: 'pending',
 			productKey,
@@ -326,18 +387,16 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 	/**
 	 * The launch timeout covers opening the store surface only; time the user
 	 * spends inside it is the store's, not ours (FR-035). A provider that reports
-	 * nothing until the flow ends gives no "opened" moment to time, so it is not
-	 * timed at all: the timeout would cut into the user's time, and that provider
-	 * always ends the flow with a result.
+	 * nothing until the flow ends gives no "opened" moment to time, so it gets only
+	 * `PURCHASE_FLOW_CEILING_MS`: far beyond any real purchase, there so a binding
+	 * that never answers cannot hold the purchase lock for the whole session.
 	 */
 	const launch = (request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> => {
 		const launched = deps.provider.launchPurchase(request);
-		if (deps.provider.capabilities().purchaseOutcomeIncludesStoreTime) {
-			return launched;
-		}
+		const includesStoreTime = deps.provider.capabilities().purchaseOutcomeIncludesStoreTime;
 		return withTimeout(
 			launched,
-			resolved.timeouts.purchaseLaunchMs,
+			includesStoreTime ? PURCHASE_FLOW_CEILING_MS : resolved.timeouts.purchaseLaunchMs,
 			() =>
 				new PaymentError({
 					code: 'PAYMENT_TIMEOUT',
@@ -447,7 +506,7 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 				}
 
 				deps.emit({ type: 'purchase_succeeded', productKey, correlationId });
-				return settle(outcome.purchase, productKey, correlationId);
+				return settleOnce(outcome.purchase, productKey, correlationId);
 			});
 
 			if (!attempt.acquired) {
@@ -492,7 +551,7 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 				return;
 			}
 
-			await settle(purchase, productKey, deps.nextCorrelationId());
+			await settleOnce(purchase, productKey, deps.nextCorrelationId());
 		},
 
 		async revalidate(): Promise<void> {
@@ -509,14 +568,17 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 				const entry = resolved.entries.get(record.productKey);
 				let approved: boolean;
 				try {
-					const decision = await hook({
+					const decision = await askHook(hook, {
 						productKey: record.productKey,
 						productType: entry?.productType ?? 'one_time_permanent',
 						// Re-validation deliberately carries no payload: the original
 						// verification material is not persisted (FR-056), so the backend
-						// re-checks by transaction against its own record of the purchase.
+						// re-checks by transaction against its own record of the purchase —
+						// which is why the transaction id has to travel with it.
 						verificationPayload: '',
 						correlationId: deps.nextCorrelationId(),
+						transactionId: record.transactionId,
+						platform: deps.platform,
 					});
 					approved = decision.approved;
 				} catch {

package/src/testing/fakeStore.ts

@@ -32,6 +32,13 @@ export interface FakeStoreOptions {
 	capabilities?: Partial<ProviderCapabilities>;
 	products?: ProviderProduct[];
 	owned?: ProviderPurchase[];
+	/**
+	 * `'android-16.7'` mirrors the Play binding the real adapter wraps: a launched
+	 * purchase is also delivered through `observePurchases`, so the engine sees it
+	 * twice, and capabilities match Android's. The default delivers it once, which
+	 * is simpler but hides any double-settle on the device path.
+	 */
+	mode?: 'default' | 'android-16.7';
 }
 
 export interface FakeStore extends ProviderPort {
@@ -127,8 +134,10 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 	let connectOutcome: ProviderConnectOutcome = options.connectOutcome ?? {
 		ok: true,
 	};
+	const androidBinding = options.mode === 'android-16.7';
 	let capabilities: ProviderCapabilities = {
 		...DEFAULT_CAPABILITIES,
+		...(androidBinding ? { supportsPriceChangeConfirmation: false } : {}),
 		...options.capabilities,
 	};
 	let products = [...(options.products ?? [])];
@@ -231,6 +240,13 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 				...script.overrides,
 			});
 			owned = [...owned.filter(p => p.transactionId !== purchase.transactionId), purchase];
+			if (androidBinding) {
+				// The binding's update listener fires for every observer, the session-long
+				// one included, before the launch settles.
+				for (const listener of [...purchaseListeners]) {
+					listener(purchase);
+				}
+			}
 			return { ok: true, purchase };
 		},