@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/react/hooks.ts

@@ -0,0 +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,
+	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

@@ -0,0 +1,374 @@
+/**
+ * Fake store — a full `ProviderPort` implementation for automated tests.
+ *
+ * Lives behind `@chipmobilesdk/rn-payment/testing` so test doubles cannot reach a
+ * production bundle.
+ *
+ * Nearly every requirement in this package concerns a rare ordering or failure
+ * path — a pending purchase settling two sessions later, an app killed between
+ * payment and acknowledgement, a billing connection dropping mid-sync. None of
+ * those are reachable on a real device on demand, so this is what makes them
+ * testable at all (NFR-007, SC-008).
+ */
+
+import type {
+	ProviderCapabilities,
+	ProviderConnectOutcome,
+	ProviderFailureReason,
+	ProviderPort,
+	ProviderPriceChangeOutcome,
+	ProviderProduct,
+	ProviderPurchase,
+	ProviderPurchaseOutcome,
+	ProviderPurchaseRequest,
+	ProviderToken,
+	StoreProductId,
+} from '../adapter/port';
+import type { ProductType, Unsubscribe } from '../config/types';
+
+export interface FakeStoreOptions {
+	/** Fails `connect` until `setConnectOutcome` says otherwise. */
+	connectOutcome?: ProviderConnectOutcome;
+	capabilities?: Partial<ProviderCapabilities>;
+	products?: ProviderProduct[];
+	owned?: ProviderPurchase[];
+}
+
+export interface FakeStore extends ProviderPort {
+	// --- Scripting the next purchase -------------------------------------------
+	/** Next `launchPurchase` succeeds and yields this purchase. */
+	scriptPurchaseSuccess(overrides?: Partial<ProviderPurchase>): void;
+	/** Next `launchPurchase` fails with this reason — cancellation included (FR-032). */
+	scriptPurchaseFailure(reason: ProviderFailureReason): void;
+	/** Next `launchPurchase` returns a purchase in the pending state (FR-037). */
+	scriptPurchasePending(overrides?: Partial<ProviderPurchase>): void;
+
+	// --- Store-side state ------------------------------------------------------
+	setOwned(purchases: ProviderPurchase[]): void;
+	/** Push a purchase through `observePurchases`, as a settling pending one does. */
+	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 ------------------------------------------------------------
+	setConnectOutcome(outcome: ProviderConnectOutcome): void;
+	/** Drop the connection, as the billing service does (FR-020). */
+	dropConnection(reason?: string): void;
+	restoreConnection(): void;
+
+	// --- Finalization ----------------------------------------------------------
+	/** Make `acknowledge`/`consume` fail, to exercise bounded retry (FR-045). */
+	setFinalizeFailure(failing: boolean): void;
+
+	// --- Inspection ------------------------------------------------------------
+	acknowledged(): ProviderToken[];
+	consumed(): ProviderToken[];
+	connectCount(): number;
+	launchCount(): number;
+	queryOwnedCount(): number;
+	disconnectCount(): number;
+	subscriptionManagementOpenedFor(): (StoreProductId | undefined)[];
+	reset(): void;
+}
+
+const DEFAULT_CAPABILITIES: ProviderCapabilities = {
+	supportsSubscriptions: true,
+	supportsPlanChange: true,
+	supportsPriceChangeConfirmation: true,
+	// Matches Android reality: grace and hold are not separable client-side.
+	reportsGraceAndHoldDistinctly: false,
+	supportsExternalTransactions: false,
+	// The whole point of the fake: it moves no money, so the environment guard
+	// lets a test complete a purchase while still blocking the real adapter
+	// outside production (FR-014).
+	createsRealTransactions: false,
+};
+
+let sequence = 0;
+
+/** A purchase with sensible defaults, so tests state only what they care about. */
+export function makePurchase(
+	overrides: Partial<ProviderPurchase> = {},
+): ProviderPurchase {
+	sequence += 1;
+	return {
+		storeProductId: overrides.storeProductId ?? 'store.product.default',
+		transactionId: overrides.transactionId ?? `txn_${sequence}`,
+		token: overrides.token ?? `token_${sequence}`,
+		state: overrides.state ?? 'purchased',
+		purchasedAt: overrides.purchasedAt ?? 1_700_000_000_000,
+		isAcknowledged: overrides.isAcknowledged ?? false,
+		expiresAt: overrides.expiresAt,
+		willAutoRenew: overrides.willAutoRenew,
+		verificationPayload: overrides.verificationPayload ?? 'fake-verification',
+	};
+}
+
+export function createFakeStore(options: FakeStoreOptions = {}): FakeStore {
+	let connectOutcome: ProviderConnectOutcome = options.connectOutcome ?? {
+		ok: true,
+	};
+	let capabilities: ProviderCapabilities = {
+		...DEFAULT_CAPABILITIES,
+		...options.capabilities,
+	};
+	let products = [...(options.products ?? [])];
+	let owned = [...(options.owned ?? [])];
+
+	let scripted:
+		| { kind: 'success' | 'pending'; overrides?: Partial<ProviderPurchase> }
+		| { kind: 'failure'; reason: ProviderFailureReason }
+		| undefined;
+
+	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[] = [];
+	const managementOpenedFor: (StoreProductId | undefined)[] = [];
+	const connectionListeners = new Set<
+		(connected: boolean, reason?: string) => void
+	>();
+	const purchaseListeners = new Set<(purchase: ProviderPurchase) => void>();
+
+	let connectCalls = 0;
+	let launchCalls = 0;
+	let queryOwnedCalls = 0;
+	let disconnectCalls = 0;
+
+	const notifyConnection = (next: boolean, reason?: string): void => {
+		connected = next;
+		for (const listener of [...connectionListeners]) {
+			listener(next, reason);
+		}
+	};
+
+	return {
+		// --- ProviderPort ------------------------------------------------------
+		async connect(): Promise<ProviderConnectOutcome> {
+			connectCalls += 1;
+			if (connectOutcome.ok) {
+				notifyConnection(true);
+			}
+			return connectOutcome;
+		},
+
+		async disconnect(): Promise<void> {
+			disconnectCalls += 1;
+			if (connected) {
+				notifyConnection(false, 'disconnect');
+			}
+		},
+
+		observeConnection(listener): Unsubscribe {
+			connectionListeners.add(listener);
+			let removed = false;
+			return () => {
+				if (removed) {
+					return;
+				}
+				removed = true;
+				connectionListeners.delete(listener);
+			};
+		},
+
+		async queryProducts(
+			storeProductIds: StoreProductId[],
+			productType: ProductType,
+		): Promise<ProviderProduct[]> {
+			return products.filter(
+				p =>
+					storeProductIds.includes(p.storeProductId) &&
+					p.productType === productType,
+			);
+		},
+
+		async queryOwned(): Promise<ProviderPurchase[]> {
+			queryOwnedCalls += 1;
+			// Pending purchases are returned flagged, never filtered out: the engine
+			// must see them to raise the pending signal while never granting.
+			return [...owned];
+		},
+
+		async launchPurchase(
+			request: ProviderPurchaseRequest,
+		): Promise<ProviderPurchaseOutcome> {
+			launchCalls += 1;
+			const script = scripted;
+			scripted = undefined;
+
+			if (!script) {
+				return { ok: false, reason: 'store_error', detail: 'no script set' };
+			}
+			if (script.kind === 'failure') {
+				return { ok: false, reason: script.reason };
+			}
+
+			const purchase = makePurchase({
+				storeProductId: request.storeProductId,
+				state: script.kind === 'pending' ? 'pending' : 'purchased',
+				...script.overrides,
+			});
+			owned = [...owned.filter(p => p.transactionId !== purchase.transactionId), purchase];
+			return { ok: true, purchase };
+		},
+
+		observePurchases(listener): Unsubscribe {
+			purchaseListeners.add(listener);
+			let removed = false;
+			return () => {
+				if (removed) {
+					return;
+				}
+				removed = true;
+				purchaseListeners.delete(listener);
+			};
+		},
+
+		async acknowledge(token: ProviderToken): Promise<void> {
+			if (finalizeFails) {
+				throw new Error('fake acknowledge failure');
+			}
+			// Safe to call for an already-acknowledged transaction (FR-044).
+			if (!acknowledgedTokens.includes(token)) {
+				acknowledgedTokens.push(token);
+			}
+			owned = owned.map(p =>
+				p.token === token ? { ...p, isAcknowledged: true } : p,
+			);
+		},
+
+		async consume(token: ProviderToken): Promise<void> {
+			if (finalizeFails) {
+				throw new Error('fake consume failure');
+			}
+			if (!consumedTokens.includes(token)) {
+				consumedTokens.push(token);
+			}
+			// A consumed purchase stops being owned, which is what lets the same
+			// product be bought again (FR-043).
+			owned = owned.filter(p => p.token !== token);
+		},
+
+		async openSubscriptionManagement(
+			storeProductId?: StoreProductId,
+		): Promise<void> {
+			managementOpenedFor.push(storeProductId);
+		},
+
+		async confirmPriceChange(): Promise<ProviderPriceChangeOutcome> {
+			return { ok: true, confirmed: true };
+		},
+
+		capabilities: () => capabilities,
+
+		pendingEndReason: transactionId => endReasons.get(transactionId),
+
+		// --- Scripting ---------------------------------------------------------
+		scriptPurchaseSuccess(overrides) {
+			scripted = { kind: 'success', overrides };
+		},
+		scriptPurchaseFailure(reason) {
+			scripted = { kind: 'failure', reason };
+		},
+		scriptPurchasePending(overrides) {
+			scripted = { kind: 'pending', overrides };
+		},
+
+		// --- Store state -------------------------------------------------------
+		setOwned(purchases) {
+			owned = [...purchases];
+		},
+		pushPurchaseUpdate(purchase) {
+			owned = [
+				...owned.filter(p => p.transactionId !== purchase.transactionId),
+				purchase,
+			];
+			for (const listener of [...purchaseListeners]) {
+				listener(purchase);
+			}
+		},
+		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];
+		},
+
+		// --- Connection --------------------------------------------------------
+		setConnectOutcome(outcome) {
+			connectOutcome = outcome;
+		},
+		dropConnection(reason = 'service_disconnected') {
+			notifyConnection(false, reason);
+		},
+		restoreConnection() {
+			notifyConnection(true);
+		},
+
+		// --- Finalization ------------------------------------------------------
+		setFinalizeFailure(failing) {
+			finalizeFails = failing;
+		},
+
+		// --- Inspection --------------------------------------------------------
+		acknowledged: () => [...acknowledgedTokens],
+		consumed: () => [...consumedTokens],
+		connectCount: () => connectCalls,
+		launchCount: () => launchCalls,
+		queryOwnedCount: () => queryOwnedCalls,
+		disconnectCount: () => disconnectCalls,
+		subscriptionManagementOpenedFor: () => [...managementOpenedFor],
+
+		reset() {
+			connectOutcome = { ok: true };
+			capabilities = { ...DEFAULT_CAPABILITIES, ...options.capabilities };
+			products = [];
+			owned = [];
+			scripted = undefined;
+			finalizeFails = false;
+			connected = false;
+			endReasons.clear();
+			acknowledgedTokens.length = 0;
+			consumedTokens.length = 0;
+			managementOpenedFor.length = 0;
+			connectionListeners.clear();
+			purchaseListeners.clear();
+			connectCalls = 0;
+			launchCalls = 0;
+			queryOwnedCalls = 0;
+			disconnectCalls = 0;
+		},
+	};
+}

package/src/testing/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@chipmobilesdk/rn-payment/testing` — test doubles.
+ *
+ * A separate entrypoint so the fake store cannot reach a production bundle
+ * (LIB-003). Nothing here is part of the package's public runtime contract.
+ */
+
+export { createFakeStore, makePurchase } from './fakeStore';
+export type { FakeStore, FakeStoreOptions } from './fakeStore';
+export { createMemorySnapshotStore } from '../persistence/mmkv-store';