@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/engine/finalize.ts

@@ -0,0 +1,298 @@
+/**
+ * The finalization queue — the package's hardest invariant (FR-041, FR-042).
+ *
+ * Google auto-refunds and revokes a purchase that is not acknowledged within
+ * **three days**. So finalization cannot be a step the app might forget, and it
+ * cannot live only in memory: the failure case FR-042 names is the app being
+ * force-killed in the instant between payment and acknowledgement.
+ *
+ * The ordering that makes this work is: **write the intent, then call the store.**
+ * A crash before the write means the purchase is still owned and the next sync
+ * re-queues it from `queryOwned`. A crash after the write means the queue has a
+ * record and the next startup drains it. There is no window where a paid
+ * transaction is forgotten.
+ *
+ * Consumption stays app-triggered (FR-043), because only the app knows whether
+ * the item was actually banked in its own data.
+ */
+
+import type {
+	FinalizeResult,
+	ProductKey,
+	TransactionRef,
+	UnfinalizedSummary,
+} from '../config/types';
+import type { ProviderPort } from '../adapter/port';
+import type { ResolvedRetry } from '../core/timers';
+import { backoffDelayMs } from '../core/retry';
+import {
+	pendingFinalizations,
+	type PersistedPurchase,
+	type PersistedSnapshot,
+} from '../persistence/snapshot';
+import type { PaymentEventInput } from '../diagnostics/events';
+
+export interface FinalizerDeps {
+	provider: ProviderPort;
+	retry: ResolvedRetry;
+	snapshot: () => PersistedSnapshot;
+	commit: (next: PersistedSnapshot) => void;
+	emit: (event: PaymentEventInput) => void;
+	now: () => number;
+	disposed: () => boolean;
+	/** Injected so a test can run the retry schedule without waiting it out. */
+	setTimeoutFn?: (fn: () => void, ms: number) => FinalizeTimerHandle;
+	clearTimeoutFn?: (handle: FinalizeTimerHandle) => void;
+}
+
+/** A Node `Timeout` and a browser numeric id are both valid here. */
+type FinalizeTimerHandle = ReturnType<typeof setTimeout> | number;
+
+export interface Finalizer {
+	/** Records the intent to finalize, then attempts it. Safe to call repeatedly. */
+	enqueue(transactionId: string): Promise<FinalizeResult>;
+	/** Drains every outstanding finalization. Runs at startup and on foreground. */
+	drain(): Promise<void>;
+	/** App-triggered consumption of a consumable (FR-043). */
+	consume(ref: TransactionRef): Promise<FinalizeResult>;
+	/** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
+	unfinalized(): UnfinalizedSummary[];
+	/** Cancels pending retries. Idempotent, called from cleanup. */
+	dispose(): void;
+}
+
+export function createFinalizer(deps: FinalizerDeps): Finalizer {
+	const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+
+	/** One timer per transaction, so two transactions retry independently. */
+	const timers = new Map<string, FinalizeTimerHandle>();
+	/** Guards against two drains racing the same transaction. */
+	const inFlight = new Set<string>();
+
+	const find = (transactionId: string): PersistedPurchase | undefined =>
+		deps.snapshot().purchases.find(p => p.transactionId === transactionId);
+
+	const patch = (
+		transactionId: string,
+		changes: Partial<PersistedPurchase>,
+	): void => {
+		const snapshot = deps.snapshot();
+		deps.commit({
+			...snapshot,
+			purchases: snapshot.purchases.map(p =>
+				p.transactionId === transactionId ? { ...p, ...changes } : p,
+			),
+		});
+	};
+
+	const clearTimer = (transactionId: string): void => {
+		const timer = timers.get(transactionId);
+		if (timer !== undefined) {
+			clearTimeoutFn(timer);
+			timers.delete(transactionId);
+		}
+	};
+
+	/**
+	 * Attempts one finalize call.
+	 *
+	 * A consumable is **not** acknowledged here: it waits for the app's explicit
+	 * `consume`. Acknowledging it now would tell the store the entitlement was
+	 * delivered before the app has recorded the item, and a crash in between would
+	 * lose a paid item with no way to recover it.
+	 */
+	const attempt = 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.finalizeState === 'done') {
+			// Idempotent by design: calling twice is a success, not an error (FR-044).
+			return { kind: 'already_finalized' };
+		}
+		if (record.productType === 'one_time_consumable') {
+			// The app owns this moment. Nothing to do until it calls consume().
+			return { kind: 'already_finalized' };
+		}
+		if (inFlight.has(transactionId)) {
+			return { kind: 'retry_scheduled', attempts: record.attempts };
+		}
+
+		inFlight.add(transactionId);
+		patch(transactionId, { finalizeState: 'in_flight' });
+
+		let failed = false;
+		try {
+			await deps.provider.acknowledge(record.token);
+		} catch {
+			failed = true;
+		} finally {
+			// Released before scheduling the retry, deliberately. The guard exists to
+			// stop two concurrent store calls for one transaction, nothing more — if
+			// it were still held here, the next scheduled attempt would be refused by
+			// our own lock and the retry schedule would silently stall after one try.
+			inFlight.delete(transactionId);
+		}
+
+		const attempts = record.attempts + 1;
+
+		if (!failed) {
+			clearTimer(transactionId);
+			patch(transactionId, {
+				finalizeState: 'done',
+				state: 'purchased',
+				attempts,
+			});
+			deps.emit({
+				type: 'transaction_finalized',
+				productKey: record.productKey,
+				attempts,
+			});
+			return { kind: 'finalized' };
+		}
+
+		patch(transactionId, { finalizeState: 'failed', attempts });
+		return scheduleRetry(transactionId, record.productKey, attempts);
+	};
+
+	/**
+	 * Schedules the next attempt inside the per-session budget.
+	 *
+	 * Exhausting the budget is **not** giving up. The record stays `failed`, which
+	 * `pendingFinalizations` still returns, so the next startup or foreground drain
+	 * picks it up again. That is what keeps the package inside Play's three-day
+	 * window without hammering a store that is currently refusing.
+	 */
+	const scheduleRetry = (
+		transactionId: string,
+		productKey: ProductKey,
+		attempts: number,
+	): FinalizeResult => {
+		if (deps.disposed()) {
+			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
+		}
+		if (attempts >= deps.retry.finalize.maxAttempts) {
+			// Left queued deliberately — resumed next session, never abandoned.
+			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
+		}
+
+		const delayMs = backoffDelayMs(attempts + 1, deps.retry.finalize);
+		clearTimer(transactionId);
+		timers.set(
+			transactionId,
+			setTimeoutFn(() => {
+				timers.delete(transactionId);
+				attempt(transactionId).catch(() => undefined);
+			}, delayMs),
+		);
+
+		deps.emit({
+			type: 'finalize_retry_scheduled',
+			productKey,
+			attempt: attempts + 1,
+			delayMs,
+		});
+		return { kind: 'retry_scheduled', attempts };
+	};
+
+	return {
+		async enqueue(transactionId: string): Promise<FinalizeResult> {
+			const record = find(transactionId);
+			if (!record) {
+				return { kind: 'unknown_transaction' };
+			}
+			if (record.finalizeState === 'done') {
+				return { kind: 'already_finalized' };
+			}
+
+			// The write happens BEFORE the store call. This single ordering is what
+			// makes a kill between payment and acknowledgement recoverable.
+			if (record.finalizeState !== 'in_flight') {
+				patch(transactionId, { finalizeState: 'queued' });
+			}
+			return attempt(transactionId);
+		},
+
+		async drain(): Promise<void> {
+			// Runs regardless of whether a purchase happened this session: the record
+			// it is looking for was probably written by a session that died.
+			for (const record of pendingFinalizations(deps.snapshot())) {
+				if (deps.disposed()) {
+					return;
+				}
+				await attempt(record.transactionId).catch(() => undefined);
+			}
+		},
+
+		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' };
+		},
+
+		unfinalized(): UnfinalizedSummary[] {
+			return pendingFinalizations(deps.snapshot()).map(p => ({
+				productKey: p.productKey,
+				transactionId: p.transactionId,
+				attempts: p.attempts,
+				purchasedAt: p.purchasedAt,
+			}));
+		},
+
+		dispose(): void {
+			for (const timer of timers.values()) {
+				clearTimeoutFn(timer);
+			}
+			timers.clear();
+			inFlight.clear();
+		},
+	};
+}

package/src/engine/pending.ts

@@ -0,0 +1,118 @@
+/**
+ * The pending set, and how a pending purchase ends (FR-101 – FR-104), added in
+ * 0.2.0.
+ *
+ * 0.1.0 handled pending purchases correctly on the grant side — pending never
+ * grants, a settled one is granted at the next sync, an abandoned one is removed
+ * — but an app could only *see* one in the session it started in. The record
+ * was already persisted with a `pending` state; this module is the read side of
+ * it, and nothing more. It decides nothing about granting: that stays in
+ * `entitlements/aggregate.ts`, where pending is refused unconditionally.
+ *
+ * Pure: no provider, no I/O, no React. The engine calls it from `commit`.
+ */
+
+import type { ResolvedConfig } from '../config/validate';
+import type {
+	PendingPurchase,
+	PendingPurchasesState,
+	PendingResolution,
+	ProductKey,
+} from '../config/types';
+import type { PersistedSnapshot } from '../persistence/snapshot';
+import { snapshotCertainty } from '../entitlements/aggregate';
+
+export const UNKNOWN_PENDING: PendingPurchasesState = {
+	status: 'unknown',
+	purchases: [],
+	isStale: false,
+};
+
+/**
+ * Derives the pending set from the snapshot.
+ *
+ * Read from the persisted record, so it survives an app kill and an offline
+ * restart, and judged by the very staleness rule entitlements use (FR-103).
+ * Products no longer in the catalog are left out: an app cannot render a row,
+ * or withhold a Buy button, for a product key it no longer has.
+ */
+export function derivePending(input: {
+	config: ResolvedConfig;
+	snapshot: PersistedSnapshot;
+	hasSynced: boolean;
+	now: number;
+}): PendingPurchasesState {
+	const { config, snapshot } = input;
+	const { isStale, undetermined } = snapshotCertainty(input);
+
+	const earliest = new Map<ProductKey, number>();
+	for (const purchase of snapshot.purchases) {
+		if (purchase.state !== 'pending' || !config.entries.has(purchase.productKey)) {
+			continue;
+		}
+		const known = earliest.get(purchase.productKey);
+		if (known === undefined || purchase.purchasedAt < known) {
+			earliest.set(purchase.productKey, purchase.purchasedAt);
+		}
+	}
+
+	const purchases: PendingPurchase[] = [...earliest]
+		.map(([productKey, since]) => ({ productKey, since }))
+		.sort((a, b) => a.since - b.since || a.productKey.localeCompare(b.productKey));
+
+	return { status: undetermined ? 'unknown' : 'known', purchases, isStale };
+}
+
+export interface PendingTransition {
+	readonly productKey: ProductKey;
+	readonly outcome: PendingResolution;
+}
+
+/**
+ * Every pending transaction that stopped being pending between two snapshots.
+ *
+ * Computed from the commit itself rather than at each call site that might end
+ * a pending purchase — sync, a store push, a purchase — which is what makes
+ * "exactly once" structural (FR-104, FR-079). A store push and a sync racing on
+ * one settling purchase both commit, but only the first commit sees it leave
+ * the pending set.
+ *
+ * A record that disappeared ended without payment. Why is the store's to say;
+ * when it says nothing, `cancelled` (see `PendingResolution`).
+ */
+export function pendingTransitions(
+	previous: PersistedSnapshot,
+	next: PersistedSnapshot,
+	config: ResolvedConfig,
+	endReason: (transactionId: string) => 'cancelled' | 'expired' | undefined,
+): PendingTransition[] {
+	const transitions: PendingTransition[] = [];
+	for (const before of previous.purchases) {
+		if (before.state !== 'pending' || !config.entries.has(before.productKey)) {
+			continue;
+		}
+		const after = next.purchases.find(p => p.transactionId === before.transactionId);
+		if (after?.state === 'pending') {
+			continue;
+		}
+		transitions.push({
+			productKey: before.productKey,
+			outcome: after ? 'settled' : (endReason(before.transactionId) ?? 'cancelled'),
+		});
+	}
+	return transitions;
+}
+
+/** Whether a listener has anything new to hear. */
+export function samePending(a: PendingPurchasesState, b: PendingPurchasesState): boolean {
+	return (
+		a.status === b.status &&
+		a.isStale === b.isStale &&
+		a.purchases.length === b.purchases.length &&
+		a.purchases.every(
+			(purchase, index) =>
+				purchase.productKey === b.purchases[index].productKey &&
+				purchase.since === b.purchases[index].since,
+		)
+	);
+}

package/src/engine/products.ts

@@ -0,0 +1,259 @@
+/**
+ * Product query, normalization, and the in-memory price cache (US11).
+ *
+ * Two rules shape this module:
+ *
+ * - **Prices come from the store, formatted.** An app must never build a price
+ *   string (FR-028): only the store knows the right currency symbol, its
+ *   placement, the decimal separator, and the grouping for the user's locale. A
+ *   hand-built "$9.99" is wrong in most of the world.
+ * - **Offer eligibility is reported, never computed.** The store decides who
+ *   qualifies for a trial or an introductory price (FR-026). Guessing locally
+ *   would promise a trial the store then refuses at checkout.
+ *
+ * The cache is in **memory only** and short-lived. Persisting prices would risk
+ * showing a stale one as current in a later session, and a paywall is exactly
+ * where that matters.
+ */
+
+import type { ProductKey, ProductType } from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import type { ProviderPort, ProviderProduct } from '../adapter/port';
+import { PaymentError } from '../diagnostics/errors';
+import { withTimeout } from '../core/mutex';
+import type { PaymentEventInput } from '../diagnostics/events';
+import { storeIdForProductKey } from '../entitlements/mapping';
+
+export interface Offer {
+	offerKey: string;
+	billingPeriod: string;
+	formattedPrice: string;
+	priceAmountMicros: number;
+	currencyCode: string;
+	trialPeriod?: string;
+	introductoryPrice?: {
+		formattedPrice: string;
+		period: string;
+		cycles: number;
+	};
+	/** As the store determined it. Never computed here (FR-026). */
+	isEligible: boolean;
+}
+
+export interface ProductInfo {
+	productKey: ProductKey;
+	productType: ProductType;
+	title: string;
+	description: string;
+	/** Store-formatted and locale-correct. For display (FR-024). */
+	formattedPrice: string;
+	currencyCode: string;
+	/** For comparison and sorting only — never for display (FR-028). */
+	priceAmountMicros: number;
+	offers: Offer[];
+}
+
+/** Why a requested product produced nothing, kept distinct from a network error. */
+export type MissingProductReason =
+	| 'not_in_catalog'
+	/** Does not exist, is unapproved, or is not sold in this country (FR-027). */
+	| 'not_available_from_store';
+
+export interface MissingProduct {
+	productKey: ProductKey;
+	reason: MissingProductReason;
+}
+
+export type ProductQueryResult =
+	| {
+			ok: true;
+			products: ProductInfo[];
+			/** Reported separately so an app shows an explanation, not an empty row. */
+			missing: MissingProduct[];
+			fromCache: boolean;
+	  }
+	| { ok: false; error: PaymentError };
+
+export interface ProductsDeps {
+	resolved: ResolvedConfig;
+	provider: ProviderPort;
+	emit: (event: PaymentEventInput) => void;
+	now: () => number;
+}
+
+export interface Products {
+	get(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+	/** Bypasses the cache; for a pull-to-refresh on a paywall (FR-029). */
+	refresh(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+	/** Drops the cache, e.g. after a locale or account change. */
+	invalidate(): void;
+}
+
+interface CacheEntry {
+	product: ProductInfo;
+	cachedAt: number;
+}
+
+function normalize(
+	raw: ProviderProduct,
+	productKey: ProductKey,
+	productType: ProductType,
+): ProductInfo {
+	return {
+		productKey,
+		productType,
+		title: raw.title,
+		description: raw.description,
+		formattedPrice: raw.formattedPrice,
+		currencyCode: raw.currencyCode,
+		priceAmountMicros: raw.priceAmountMicros,
+		offers: raw.offers.map(offer => ({
+			offerKey: offer.offerKey,
+			billingPeriod: offer.billingPeriod,
+			formattedPrice: offer.formattedPrice,
+			priceAmountMicros: offer.priceAmountMicros,
+			currencyCode: offer.currencyCode,
+			trialPeriod: offer.trialPeriod,
+			introductoryPrice: offer.introductoryPrice,
+			isEligible: offer.isEligible,
+		})),
+	};
+}
+
+export function createProducts(deps: ProductsDeps): Products {
+	const { resolved } = deps;
+	const cache = new Map<ProductKey, CacheEntry>();
+
+	const isFresh = (entry: CacheEntry): boolean =>
+		deps.now() - entry.cachedAt < resolved.productCacheTtlMs;
+
+	const query = async (
+		productKeys: ProductKey[],
+		useCache: boolean,
+	): Promise<ProductQueryResult> => {
+		const missing: MissingProduct[] = [];
+		const resolvedProducts: ProductInfo[] = [];
+		const toFetch: Array<{
+			productKey: ProductKey;
+			storeProductId: string;
+			productType: ProductType;
+		}> = [];
+
+		for (const productKey of productKeys) {
+			const entry = resolved.entries.get(productKey);
+			const storeProductId = storeIdForProductKey(resolved, productKey);
+			if (!entry || !storeProductId) {
+				// A configuration problem, not a store one. Distinguishing them tells a
+				// developer whether to fix the catalog or check Play Console.
+				missing.push({ productKey, reason: 'not_in_catalog' });
+				continue;
+			}
+
+			const cached = useCache ? cache.get(productKey) : undefined;
+			if (cached && isFresh(cached)) {
+				resolvedProducts.push(cached.product);
+				continue;
+			}
+
+			toFetch.push({
+				productKey,
+				storeProductId,
+				productType: entry.productType,
+			});
+		}
+
+		if (toFetch.length === 0) {
+			deps.emit({
+				type: 'products_queried',
+				productKeys,
+				found: resolvedProducts.length,
+				missing: missing.map(m => m.productKey),
+				fromCache: true,
+			});
+			return {
+				ok: true,
+				products: resolvedProducts,
+				missing,
+				fromCache: true,
+			};
+		}
+
+		// Grouped by product type because the store queries in-app products and
+		// subscriptions through separate calls.
+		const byType = new Map<ProductType, typeof toFetch>();
+		for (const item of toFetch) {
+			const list = byType.get(item.productType) ?? [];
+			list.push(item);
+			byType.set(item.productType, list);
+		}
+
+		try {
+			for (const [productType, items] of byType) {
+				const 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,
+						}),
+				);
+
+				const returned = new Map(raw.map(p => [p.storeProductId, p]));
+				for (const item of items) {
+					const found = returned.get(item.storeProductId);
+					if (!found) {
+						// The store knows the id but will not sell it here: unapproved, or
+						// not available in this country. Never conflated with a network
+						// failure (FR-027).
+						missing.push({
+							productKey: item.productKey,
+							reason: 'not_available_from_store',
+						});
+						continue;
+					}
+					const product = normalize(found, item.productKey, item.productType);
+					cache.set(item.productKey, { product, cachedAt: deps.now() });
+					resolvedProducts.push(product);
+				}
+			}
+		} catch (error) {
+			const paymentError =
+				error instanceof PaymentError
+					? error
+					: new PaymentError({
+							code: 'PAYMENT_NETWORK_ERROR',
+							message: 'Could not reach the store to query products',
+							operation: 'getProducts',
+							retryable: true,
+						});
+			deps.emit({
+				type: 'internal_error',
+				code: paymentError.code,
+				operation: 'getProducts',
+			});
+			return { ok: false, error: paymentError };
+		}
+
+		deps.emit({
+			type: 'products_queried',
+			productKeys,
+			found: resolvedProducts.length,
+			missing: missing.map(m => m.productKey),
+			fromCache: false,
+		});
+
+		return { ok: true, products: resolvedProducts, missing, fromCache: false };
+	};
+
+	return {
+		get: productKeys => query(productKeys, true),
+		refresh: productKeys => query(productKeys, false),
+		invalidate: () => cache.clear(),
+	};
+}