@chipmobilesdk/rn-payment 0.1.0 → 0.2.1

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

@@ -1,259 +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(),
-	};
-}
+/**
+ * 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(),
+	};
+}