@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/engine/foreground.ts

@@ -0,0 +1,29 @@
+/**
+ * Opt-in foreground sync over rn-core's shared lifecycle port (PERF-07, FR-059).
+ *
+ * `handleForeground()` stays the app's to call: the engine does not decide what a
+ * foreground return is. An app that is happy with "back from the background" calls
+ * this once instead of wiring `AppState` itself, and shares the one native
+ * subscription every package uses. A trip through `inactive` alone (a biometric
+ * prompt, iOS Control Center) is not a return. On Android the Play purchase sheet
+ * does send the app to the background, so a purchase is followed by a sync; the
+ * engine's foreground rate limit keeps that to one request per interval.
+ */
+import {
+	appLifecycle,
+	onForeground,
+	type AppLifecyclePort,
+	type Unsubscribe,
+} from '@chipmobilesdk/rn-core';
+
+import type { PaymentEngine } from './engine';
+
+export function syncOnForeground(
+	engine: Pick<PaymentEngine, 'handleForeground'>,
+	lifecycle: AppLifecyclePort = appLifecycle(),
+): Unsubscribe {
+	return onForeground(() => {
+		// Sync reports its own failures through status and diagnostics.
+		engine.handleForeground().catch(() => undefined);
+	}, lifecycle);
+}

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(),
+	};
+}