@chipmobilesdk/rn-payment 0.1.0 → 0.2.0

package/src/react/hooks.ts

@@ -1,238 +1,274 @@
-/**
- * Hooks over the engine.
- *
- * Each subscribes on mount and unsubscribes on unmount, so repeated mount/unmount
- * leaves no duplicate subscription and no surviving listener (FR-006, PERF-002).
- *
- * Reads are synchronous: the engine holds entitlements in memory, so a hook never
- * returns a loading placeholder for an entitlement it already knows (PERF-001).
- */
-
-import { useCallback, useEffect, useState } from 'react';
-import { usePaymentEngine } from './PaymentProvider';
-import type {
-	EntitlementKey,
-	FinalizeResult,
-	PaymentStatus,
-	PurchaseOptions,
-	PurchaseResult,
-	TransactionRef,
-} from '../config/types';
-import type {
-	EntitlementMap,
-	EntitlementState,
-} from '../entitlements/aggregate';
-import type { PaymentError } from '../diagnostics/errors';
-import type { MissingProduct, ProductInfo } from '../engine/products';
-import type { RestoreOutcome, SyncOutcome } from '../engine/engine';
-
-/**
- * One entitlement, re-rendering only when that one changes.
- *
- * The returned `status` is `unknown` until the first sync completes. That is the
- * point: an app must be able to tell "not yet known" from "not entitled" so a
- * paying user never sees the unpaid experience flash (FR-047).
- */
-export function useEntitlement(key: EntitlementKey): EntitlementState {
-	const engine = usePaymentEngine();
-	const [state, setState] = useState<EntitlementState>(() =>
-		engine.getEntitlement(key),
-	);
-
-	useEffect(() => {
-		// Re-read on subscribe: the entitlement may have changed between the initial
-		// render and this effect.
-		setState(engine.getEntitlement(key));
-		return engine.subscribeEntitlements(map => {
-			const next = map[key];
-			if (next) {
-				setState(next);
-			}
-		});
-	}, [engine, key]);
-
-	return state;
-}
-
-/** Every entitlement at once, for a screen that shows overall plan state. */
-export function useEntitlements(): EntitlementMap {
-	const engine = usePaymentEngine();
-	const [map, setMap] = useState<EntitlementMap>(() =>
-		engine.getAllEntitlements(),
-	);
-
-	useEffect(() => {
-		setMap(engine.getAllEntitlements());
-		return engine.subscribeEntitlements(setMap);
-	}, [engine]);
-
-	return map;
-}
-
-/** Package status, so an app can tell "cannot sell here" from "not paid" (FR-022). */
-export function usePaymentStatus(): PaymentStatus {
-	const engine = usePaymentEngine();
-	const [status, setStatus] = useState<PaymentStatus>(() => engine.getStatus());
-
-	useEffect(() => {
-		setStatus(engine.getStatus());
-		return engine.subscribeStatus(setStatus);
-	}, [engine]);
-
-	return status;
-}
-
-export interface UsePurchaseResult {
-	purchase: (
-		productKey: EntitlementKey,
-		options?: PurchaseOptions,
-	) => Promise<PurchaseResult>;
-	consume: (ref: TransactionRef) => Promise<FinalizeResult>;
-	isPurchasing: boolean;
-	/** The last outcome, so a screen can render cancellation differently from failure. */
-	lastResult: PurchaseResult | undefined;
-}
-
-/**
- * Starting a purchase.
- *
- * `lastResult` is the full typed union rather than a boolean, because a screen has
- * to treat `user_cancelled` differently from `store_error` — showing an error
- * banner to someone who simply changed their mind is the most common paywall bug.
- */
-export function usePurchase(): UsePurchaseResult {
-	const engine = usePaymentEngine();
-	const [isPurchasing, setIsPurchasing] = useState(false);
-	const [lastResult, setLastResult] = useState<PurchaseResult | undefined>();
-
-	const purchase = useCallback(
-		async (
-			productKey: string,
-			options?: PurchaseOptions,
-		): Promise<PurchaseResult> => {
-			setIsPurchasing(true);
-			try {
-				const result = await engine.purchase(productKey, options);
-				setLastResult(result);
-				return result;
-			} finally {
-				setIsPurchasing(false);
-			}
-		},
-		[engine],
-	);
-
-	const consume = useCallback(
-		(ref: TransactionRef): Promise<FinalizeResult> => engine.consume(ref),
-		[engine],
-	);
-
-	return { purchase, consume, isPurchasing, lastResult };
-}
-
-export interface UseProductsResult {
-	products: ProductInfo[];
-	/** Reported so a paywall explains an absent row instead of rendering a blank. */
-	missing: MissingProduct[];
-	isLoading: boolean;
-	error: PaymentError | undefined;
-	refresh: () => Promise<void>;
-}
-
-/**
- * Store-supplied product information for a paywall.
- *
- * Every price here is already formatted by the store for the user's locale. An app
- * must render `formattedPrice` and never build its own string from
- * `priceAmountMicros` — that field exists for sorting and comparison only
- * (FR-028).
- */
-export function useProducts(productKeys: readonly string[]): UseProductsResult {
-	const engine = usePaymentEngine();
-	const [products, setProducts] = useState<ProductInfo[]>([]);
-	const [missing, setMissing] = useState<MissingProduct[]>([]);
-	const [isLoading, setIsLoading] = useState(false);
-	const [error, setError] = useState<PaymentError | undefined>();
-
-	// Joined so the effect depends on the contents rather than the array identity:
-	// a caller passing a literal would otherwise re-query on every render.
-	const keyToken = productKeys.join('|');
-
-	const load = useCallback(
-		async (fresh: boolean): Promise<void> => {
-			const keys = keyToken === '' ? [] : keyToken.split('|');
-			if (keys.length === 0) {
-				setProducts([]);
-				setMissing([]);
-				return;
-			}
-			setIsLoading(true);
-			try {
-				const result = fresh
-					? await engine.refreshProducts(keys)
-					: await engine.getProducts(keys);
-				if (result.ok) {
-					setProducts(result.products);
-					setMissing(result.missing);
-					setError(undefined);
-				} else {
-					setError(result.error);
-				}
-			} finally {
-				setIsLoading(false);
-			}
-		},
-		[engine, keyToken],
-	);
-
-	useEffect(() => {
-		load(false).catch(() => undefined);
-	}, [load]);
-
-	const refresh = useCallback(() => load(true), [load]);
-
-	return { products, missing, isLoading, error, refresh };
-}
-
-export interface UseSyncResult {
-	sync: () => Promise<SyncOutcome>;
-	restore: () => Promise<RestoreOutcome>;
-	isSyncing: boolean;
-	lastSyncedAt: number | undefined;
-}
-
-/**
- * Sync and restore, for a "Restore purchases" control.
- *
- * `restore`'s outcome distinguishes "restored" from "nothing found", so the app
- * can avoid telling a user their purchases came back when none existed (FR-061).
- */
-export function useSync(): UseSyncResult {
-	const engine = usePaymentEngine();
-	const [isSyncing, setIsSyncing] = useState(false);
-	const [lastSyncedAt, setLastSyncedAt] = useState<number | undefined>(() =>
-		engine.getLastSyncedAt(),
-	);
-
-	const sync = useCallback(async (): Promise<SyncOutcome> => {
-		setIsSyncing(true);
-		try {
-			return await engine.sync('manual');
-		} finally {
-			setIsSyncing(false);
-			setLastSyncedAt(engine.getLastSyncedAt());
-		}
-	}, [engine]);
-
-	const restore = useCallback(async (): Promise<RestoreOutcome> => {
-		setIsSyncing(true);
-		try {
-			return await engine.restore();
-		} finally {
-			setIsSyncing(false);
-			setLastSyncedAt(engine.getLastSyncedAt());
-		}
-	}, [engine]);
-
-	return { sync, restore, isSyncing, lastSyncedAt };
-}
+/**
+ * Hooks over the engine.
+ *
+ * Each subscribes on mount and unsubscribes on unmount, so repeated mount/unmount
+ * leaves no duplicate subscription and no surviving listener (FR-006, PERF-002).
+ *
+ * Reads are synchronous: the engine holds entitlements in memory, so a hook never
+ * returns a loading placeholder for an entitlement it already knows (PERF-001).
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import { usePaymentEngine } from './PaymentProvider';
+import type {
+	EntitlementKey,
+	FinalizeResult,
+	PaymentStatus,
+	PendingPurchasesState,
+	PurchaseOptions,
+	PurchaseResult,
+	TransactionRef,
+} from '../config/types';
+import type {
+	EntitlementMap,
+	EntitlementState,
+} from '../entitlements/aggregate';
+import type { PaymentError } from '../diagnostics/errors';
+import type { MissingProduct, ProductInfo } from '../engine/products';
+import type { RestoreOutcome, SyncOutcome } from '../engine/engine';
+
+/**
+ * One entitlement, re-rendering only when that one changes.
+ *
+ * The returned `status` is `unknown` until the first sync completes. That is the
+ * point: an app must be able to tell "not yet known" from "not entitled" so a
+ * paying user never sees the unpaid experience flash (FR-047).
+ */
+export function useEntitlement(key: EntitlementKey): EntitlementState {
+	const engine = usePaymentEngine();
+	const [state, setState] = useState<EntitlementState>(() =>
+		engine.getEntitlement(key),
+	);
+
+	useEffect(() => {
+		// Re-read on subscribe: the entitlement may have changed between the initial
+		// render and this effect.
+		setState(engine.getEntitlement(key));
+		return engine.subscribeEntitlements(map => {
+			const next = map[key];
+			if (next) {
+				setState(next);
+			}
+		});
+	}, [engine, key]);
+
+	return state;
+}
+
+/** Every entitlement at once, for a screen that shows overall plan state. */
+export function useEntitlements(): EntitlementMap {
+	const engine = usePaymentEngine();
+	const [map, setMap] = useState<EntitlementMap>(() =>
+		engine.getAllEntitlements(),
+	);
+
+	useEffect(() => {
+		setMap(engine.getAllEntitlements());
+		return engine.subscribeEntitlements(setMap);
+	}, [engine]);
+
+	return map;
+}
+
+function narrowPending(
+	state: PendingPurchasesState,
+	keys: readonly string[] | null,
+): PendingPurchasesState {
+	return keys
+		? { ...state, purchases: state.purchases.filter(p => keys.includes(p.productKey)) }
+		: state;
+}
+
+/**
+ * Pending purchases, in this session or an earlier one (FR-101). Added in 0.2.0.
+ *
+ * Pass product keys to narrow it to the products one screen sells. Read
+ * `status` before the list: under `unknown`, an empty list is not "nothing
+ * pending", and a Buy button shown on it could charge a user twice.
+ */
+export function usePendingPurchases(
+	productKeys?: readonly string[],
+): PendingPurchasesState {
+	const engine = usePaymentEngine();
+	// Joined so a caller passing a literal array does not resubscribe each render.
+	const keyToken = productKeys ? productKeys.join('|') : null;
+	const [state, setState] = useState<PendingPurchasesState>(() =>
+		narrowPending(engine.getPendingPurchases(), productKeys ?? null),
+	);
+
+	useEffect(() => {
+		const keys = keyToken === null ? null : keyToken.split('|').filter(Boolean);
+		setState(narrowPending(engine.getPendingPurchases(), keys));
+		return engine.subscribePendingPurchases(next => setState(narrowPending(next, keys)));
+	}, [engine, keyToken]);
+
+	return state;
+}
+
+/** Package status, so an app can tell "cannot sell here" from "not paid" (FR-022). */
+export function usePaymentStatus(): PaymentStatus {
+	const engine = usePaymentEngine();
+	const [status, setStatus] = useState<PaymentStatus>(() => engine.getStatus());
+
+	useEffect(() => {
+		setStatus(engine.getStatus());
+		return engine.subscribeStatus(setStatus);
+	}, [engine]);
+
+	return status;
+}
+
+export interface UsePurchaseResult {
+	purchase: (
+		productKey: EntitlementKey,
+		options?: PurchaseOptions,
+	) => Promise<PurchaseResult>;
+	consume: (ref: TransactionRef) => Promise<FinalizeResult>;
+	isPurchasing: boolean;
+	/** The last outcome, so a screen can render cancellation differently from failure. */
+	lastResult: PurchaseResult | undefined;
+}
+
+/**
+ * Starting a purchase.
+ *
+ * `lastResult` is the full typed union rather than a boolean, because a screen has
+ * to treat `user_cancelled` differently from `store_error` — showing an error
+ * banner to someone who simply changed their mind is the most common paywall bug.
+ */
+export function usePurchase(): UsePurchaseResult {
+	const engine = usePaymentEngine();
+	const [isPurchasing, setIsPurchasing] = useState(false);
+	const [lastResult, setLastResult] = useState<PurchaseResult | undefined>();
+
+	const purchase = useCallback(
+		async (
+			productKey: string,
+			options?: PurchaseOptions,
+		): Promise<PurchaseResult> => {
+			setIsPurchasing(true);
+			try {
+				const result = await engine.purchase(productKey, options);
+				setLastResult(result);
+				return result;
+			} finally {
+				setIsPurchasing(false);
+			}
+		},
+		[engine],
+	);
+
+	const consume = useCallback(
+		(ref: TransactionRef): Promise<FinalizeResult> => engine.consume(ref),
+		[engine],
+	);
+
+	return { purchase, consume, isPurchasing, lastResult };
+}
+
+export interface UseProductsResult {
+	products: ProductInfo[];
+	/** Reported so a paywall explains an absent row instead of rendering a blank. */
+	missing: MissingProduct[];
+	isLoading: boolean;
+	error: PaymentError | undefined;
+	refresh: () => Promise<void>;
+}
+
+/**
+ * Store-supplied product information for a paywall.
+ *
+ * Every price here is already formatted by the store for the user's locale. An app
+ * must render `formattedPrice` and never build its own string from
+ * `priceAmountMicros` — that field exists for sorting and comparison only
+ * (FR-028).
+ */
+export function useProducts(productKeys: readonly string[]): UseProductsResult {
+	const engine = usePaymentEngine();
+	const [products, setProducts] = useState<ProductInfo[]>([]);
+	const [missing, setMissing] = useState<MissingProduct[]>([]);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<PaymentError | undefined>();
+
+	// Joined so the effect depends on the contents rather than the array identity:
+	// a caller passing a literal would otherwise re-query on every render.
+	const keyToken = productKeys.join('|');
+
+	const load = useCallback(
+		async (fresh: boolean): Promise<void> => {
+			const keys = keyToken === '' ? [] : keyToken.split('|');
+			if (keys.length === 0) {
+				setProducts([]);
+				setMissing([]);
+				return;
+			}
+			setIsLoading(true);
+			try {
+				const result = fresh
+					? await engine.refreshProducts(keys)
+					: await engine.getProducts(keys);
+				if (result.ok) {
+					setProducts(result.products);
+					setMissing(result.missing);
+					setError(undefined);
+				} else {
+					setError(result.error);
+				}
+			} finally {
+				setIsLoading(false);
+			}
+		},
+		[engine, keyToken],
+	);
+
+	useEffect(() => {
+		load(false).catch(() => undefined);
+	}, [load]);
+
+	const refresh = useCallback(() => load(true), [load]);
+
+	return { products, missing, isLoading, error, refresh };
+}
+
+export interface UseSyncResult {
+	sync: () => Promise<SyncOutcome>;
+	restore: () => Promise<RestoreOutcome>;
+	isSyncing: boolean;
+	lastSyncedAt: number | undefined;
+}
+
+/**
+ * Sync and restore, for a "Restore purchases" control.
+ *
+ * `restore`'s outcome distinguishes "restored" from "nothing found", so the app
+ * can avoid telling a user their purchases came back when none existed (FR-061).
+ */
+export function useSync(): UseSyncResult {
+	const engine = usePaymentEngine();
+	const [isSyncing, setIsSyncing] = useState(false);
+	const [lastSyncedAt, setLastSyncedAt] = useState<number | undefined>(() =>
+		engine.getLastSyncedAt(),
+	);
+
+	const sync = useCallback(async (): Promise<SyncOutcome> => {
+		setIsSyncing(true);
+		try {
+			return await engine.sync('manual');
+		} finally {
+			setIsSyncing(false);
+			setLastSyncedAt(engine.getLastSyncedAt());
+		}
+	}, [engine]);
+
+	const restore = useCallback(async (): Promise<RestoreOutcome> => {
+		setIsSyncing(true);
+		try {
+			return await engine.restore();
+		} finally {
+			setIsSyncing(false);
+			setLastSyncedAt(engine.getLastSyncedAt());
+		}
+	}, [engine]);
+
+	return { sync, restore, isSyncing, lastSyncedAt };
+}

package/src/testing/fakeStore.ts

@@ -49,6 +49,21 @@ export interface FakeStore extends ProviderPort {
 	pushPurchaseUpdate(purchase: ProviderPurchase): void;
 	/** Stop reporting a transaction as valid — a refund or revocation (FR-064). */
 	revoke(transactionId: string): void;
+
+	// --- Ending a pending purchase (0.2.0) -------------------------------------
+	// Each changes store-side state only, as the real store does: the engine sees
+	// it at its next sync, so it works the same across a simulated app kill. To
+	// deliver a settlement without a sync, `pushPurchaseUpdate` it as well.
+	/** The money arrives: the owned record turns `purchased` (FR-039). */
+	settlePending(transactionId: string): void;
+	/** The payment is declined or abandoned: the store stops reporting it (FR-040). */
+	cancelPending(transactionId: string): void;
+	/**
+	 * The pending window runs out. Reported through `pendingEndReason`, which a
+	 * store that knows implements — Play does not, so on device this is
+	 * indistinguishable from `cancelPending` (FR-102).
+	 */
+	expirePending(transactionId: string): void;
 	setProducts(products: ProviderProduct[]): void;
 
 	// --- Connection ------------------------------------------------------------
@@ -123,6 +138,8 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 
 	let finalizeFails = false;
 	let connected = false;
+	/** Why each pending purchase ended, for the ones `expirePending` or `cancelPending` ended. */
+	const endReasons = new Map<string, 'cancelled' | 'expired'>();
 
 	const acknowledgedTokens: ProviderToken[] = [];
 	const consumedTokens: ProviderToken[] = [];
@@ -263,6 +280,8 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 
 		capabilities: () => capabilities,
 
+		pendingEndReason: transactionId => endReasons.get(transactionId),
+
 		// --- Scripting ---------------------------------------------------------
 		scriptPurchaseSuccess(overrides) {
 			scripted = { kind: 'success', overrides };
@@ -290,6 +309,19 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 		revoke(transactionId) {
 			owned = owned.filter(p => p.transactionId !== transactionId);
 		},
+		settlePending(transactionId) {
+			owned = owned.map(p =>
+				p.transactionId === transactionId ? { ...p, state: 'purchased' } : p,
+			);
+		},
+		cancelPending(transactionId) {
+			owned = owned.filter(p => p.transactionId !== transactionId);
+			endReasons.set(transactionId, 'cancelled');
+		},
+		expirePending(transactionId) {
+			owned = owned.filter(p => p.transactionId !== transactionId);
+			endReasons.set(transactionId, 'expired');
+		},
 		setProducts(next) {
 			products = [...next];
 		},
@@ -327,6 +359,7 @@ export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
 			scripted = undefined;
 			finalizeFails = false;
 			connected = false;
+			endReasons.clear();
 			acknowledgedTokens.length = 0;
 			consumedTokens.length = 0;
 			managementOpenedFor.length = 0;