@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/react/hooks.ts

@@ -1,274 +1,236 @@
-/**
- * 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 };
-}
+/**
+ * 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 { useExternalStore } from '@chipmobilesdk/rn-core/react';
+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();
+	// The engine keeps an unchanged entitlement's object across recomputes, so this
+	// selection only changes, and the component only re-renders, when it changes.
+	const select = useCallback(
+		(map: EntitlementMap) => map[key] ?? engine.getEntitlement(key),
+		[engine, key],
+	);
+	return useExternalStore(engine.subscribeEntitlements, engine.getAllEntitlements, select);
+}
+
+/** Every entitlement at once, for a screen that shows overall plan state. */
+export function useEntitlements(): EntitlementMap {
+	const engine = usePaymentEngine();
+	return useExternalStore(engine.subscribeEntitlements, engine.getAllEntitlements);
+}
+
+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();
+	return useExternalStore(engine.subscribeStatus, engine.getStatus);
+}
+
+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 };
+}