@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/src/persistence/mmkv-store.ts

@@ -0,0 +1,150 @@
+/**
+ * MMKV-backed snapshot store.
+ *
+ * Every MMKV import is confined to this file, so the rest of the package stays
+ * testable without a native module.
+ *
+ * MMKV is chosen because it is **synchronous**, which is what lets
+ * `getEntitlement` be an in-memory read with no I/O on render paths (PERF-001).
+ * An async store would force either an async entitlement read or a hidden
+ * hydration race on every call.
+ *
+ * Records are partitioned by cache-scope token (FR-057a). The token is a
+ * partition key and nothing more: never interpreted, never transmitted, never
+ * attached to a transaction.
+ */
+
+import {
+	emptySnapshot,
+	migrateSnapshot,
+	type PersistedSnapshot,
+} from './snapshot';
+
+const INSTANCE_ID = 'chipmobilesdk.payment';
+const KEY_PREFIX = 'snapshot';
+
+interface MmkvLike {
+	getString(key: string): string | undefined;
+	set(key: string, value: string): void;
+	delete(key: string): void;
+	clearAll(): void;
+	getAllKeys(): string[];
+}
+
+export interface SnapshotStore {
+	load(scopeToken?: string): PersistedSnapshot;
+	save(snapshot: PersistedSnapshot): void;
+	/** Clears every scope — for logout and data-deletion requests (FR-057). */
+	clearAll(): void;
+	/** Whether writes actually persist. False means the memory fallback is active. */
+	isDurable(): boolean;
+}
+
+function scopeKey(scopeToken?: string): string {
+	// An explicit sentinel rather than an empty segment, so the unscoped record
+	// can never collide with a scope whose token happens to be empty.
+	return `${KEY_PREFIX}:${scopeToken ?? '__default__'}`;
+}
+
+/** In-memory fallback, used when the native module is absent. */
+function createMemoryBacking(): MmkvLike {
+	const map = new Map<string, string>();
+	return {
+		getString: key => map.get(key),
+		set(key, value) {
+			map.set(key, value);
+		},
+		delete(key) {
+			map.delete(key);
+		},
+		clearAll: () => map.clear(),
+		getAllKeys: () => [...map.keys()],
+	};
+}
+
+function resolveBacking(): { backing: MmkvLike; durable: boolean } {
+	try {
+		// Required lazily so the package loads where the native module is absent.
+		const mod = require('react-native-mmkv') as {
+			MMKV: new (config?: { id?: string }) => MmkvLike;
+		};
+		return { backing: new mod.MMKV({ id: INSTANCE_ID }), durable: true };
+	} catch {
+		return { backing: createMemoryBacking(), durable: false };
+	}
+}
+
+/**
+ * Creates the store.
+ *
+ * The memory fallback is a **documented degradation**, not a silent one: without
+ * MMKV the snapshot does not survive a cold start, so entitlements read `unknown`
+ * until the first sync. That is safe by construction — `unknown`, never
+ * `not_entitled` (FR-047) — and FR-059's startup sync repairs it. `isDurable()`
+ * lets the engine warn, so the condition is visible rather than mysterious.
+ */
+export function createSnapshotStore(
+	injected?: { backing: MmkvLike; durable: boolean },
+): SnapshotStore {
+	const { backing, durable } = injected ?? resolveBacking();
+
+	return {
+		load(scopeToken?: string): PersistedSnapshot {
+			const raw = backing.getString(scopeKey(scopeToken));
+			if (raw === undefined) {
+				return emptySnapshot(scopeToken);
+			}
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(raw);
+			} catch {
+				// Corrupt JSON is discarded rather than repaired: the store is the
+				// authoritative source and the next sync rebuilds from it.
+				return emptySnapshot(scopeToken);
+			}
+
+			const outcome = migrateSnapshot(parsed);
+			if (!outcome.ok) {
+				return emptySnapshot(scopeToken);
+			}
+
+			// A record whose stored token disagrees with the requested scope must not
+			// be served: that is precisely the account-switch inheritance FR-057a
+			// exists to prevent.
+			if (outcome.snapshot.scopeToken !== scopeToken) {
+				return emptySnapshot(scopeToken);
+			}
+
+			return outcome.snapshot;
+		},
+
+		save(snapshot: PersistedSnapshot): void {
+			try {
+				backing.set(scopeKey(snapshot.scopeToken), JSON.stringify(snapshot));
+			} catch {
+				// A failed write must never take down a purchase flow. The in-memory
+				// state stays correct for this session and the next sync re-derives it.
+			}
+		},
+
+		clearAll(): void {
+			try {
+				for (const key of backing.getAllKeys()) {
+					if (key.startsWith(`${KEY_PREFIX}:`)) {
+						backing.delete(key);
+					}
+				}
+			} catch {
+				// Best effort; a failure here must not throw into a logout flow.
+			}
+		},
+
+		isDurable: () => durable,
+	};
+}
+
+/** Test seam for driving the store without the native module. */
+export function createMemorySnapshotStore(): SnapshotStore {
+	return createSnapshotStore({ backing: createMemoryBacking(), durable: false });
+}

package/src/persistence/snapshot.ts

@@ -0,0 +1,247 @@
+/**
+ * The persisted snapshot: schema, versioning, and migration.
+ *
+ * What is stored here is **exhaustively** what the package keeps on the device,
+ * and the README repeats this list so an app owner can complete a Data safety
+ * declaration accurately (FR-056, POL-002).
+ *
+ * Deliberately absent: payment details, card data, billing address, user
+ * identity, raw receipts, verification payloads, and backend tokens.
+ */
+
+import type {
+	EntitlementKey,
+	ProductKey,
+	ProductType,
+} from '../config/types';
+
+export const SNAPSHOT_SCHEMA_VERSION = 1;
+
+/** Where a transaction stands with the store. */
+export type PersistedPurchaseState =
+	| 'pending'
+	| 'purchased'
+	| 'finalized'
+	| 'consumed'
+	| 'revoked';
+
+/**
+ * Where a transaction stands in the finalization queue.
+ *
+ * `queued` is the load-bearing value: it is written **before** the store call is
+ * attempted, so an app killed mid-finalize leaves a recoverable record rather
+ * than a paid purchase that Google will auto-refund (FR-041, FR-042).
+ */
+export type PersistedFinalizeState =
+	| 'not_required'
+	| 'queued'
+	| 'in_flight'
+	| 'done'
+	| 'failed';
+
+/** Whether the app's backend has ruled on this transaction (FR-072a). */
+export type PersistedValidationState =
+	| 'not_required'
+	| 'approved'
+	| 'rejected'
+	| 'queued_for_revalidation';
+
+export interface PersistedPurchase {
+	transactionId: string;
+	productKey: ProductKey;
+	productType: ProductType;
+	token: string;
+	state: PersistedPurchaseState;
+	purchasedAt: number;
+	finalizeState: PersistedFinalizeState;
+	/** Attempts consumed. Carried across sessions so retry stays bounded per session. */
+	attempts: number;
+	validationState: PersistedValidationState;
+	expiresAt?: number;
+	willAutoRenew?: boolean;
+}
+
+export interface PersistedEntitlement {
+	sources: ProductKey[];
+	expiresAt?: number;
+	willAutoRenew?: boolean;
+	isCancelledButValid?: boolean;
+}
+
+export interface PersistedSnapshot {
+	schemaVersion: number;
+	/** Opaque partition key. Stored only to scope this record (FR-057a). */
+	scopeToken?: string;
+	entitlements: Record<EntitlementKey, PersistedEntitlement>;
+	purchases: PersistedPurchase[];
+	lastSyncedAt?: number;
+}
+
+export function emptySnapshot(scopeToken?: string): PersistedSnapshot {
+	return {
+		schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+		scopeToken,
+		entitlements: {},
+		purchases: [],
+		lastSyncedAt: undefined,
+	};
+}
+
+/**
+ * A migration from one schema version to the next.
+ *
+ * Kept as an ordered chain rather than a switch so each step stays small and
+ * independently testable, and so a device several versions behind is carried
+ * forward one hop at a time (NFR-009).
+ */
+export interface SnapshotMigration {
+	from: number;
+	to: number;
+	migrate(input: Record<string, unknown>): Record<string, unknown>;
+}
+
+/**
+ * Registered migrations.
+ *
+ * Empty at v1 by definition — there is no earlier shipped version to migrate
+ * from. The chain exists now so the first real migration is a one-entry change
+ * rather than a refactor under time pressure.
+ */
+export const SNAPSHOT_MIGRATIONS: readonly SnapshotMigration[] = [];
+
+export type MigrationOutcome =
+	| { ok: true; snapshot: PersistedSnapshot; migrated: boolean }
+	/**
+	 * Unreadable records are discarded, not repaired.
+	 *
+	 * Safe because discarding yields `unknown`, never a false `not_entitled`
+	 * (FR-055a), and the next sync rebuilds from the store — the authoritative
+	 * source anyway. Guessing at a corrupt record risks granting or withholding
+	 * wrongly, which is worse than a short `unknown` window.
+	 */
+	| { ok: false; reason: 'unreadable' | 'unsupported_version' };
+
+export function migrateSnapshot(raw: unknown): MigrationOutcome {
+	if (typeof raw !== 'object' || raw === null) {
+		return { ok: false, reason: 'unreadable' };
+	}
+
+	let working = { ...(raw as Record<string, unknown>) };
+	const version = working.schemaVersion;
+
+	if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+		return { ok: false, reason: 'unreadable' };
+	}
+
+	if (version > SNAPSHOT_SCHEMA_VERSION) {
+		// A newer app version wrote this. Downgrading cannot know what was added,
+		// so refuse rather than silently drop fields.
+		return { ok: false, reason: 'unsupported_version' };
+	}
+
+	let current = version;
+	let migrated = false;
+	while (current < SNAPSHOT_SCHEMA_VERSION) {
+		const step = SNAPSHOT_MIGRATIONS.find(m => m.from === current);
+		if (!step) {
+			return { ok: false, reason: 'unsupported_version' };
+		}
+		working = step.migrate(working);
+		current = step.to;
+		migrated = true;
+	}
+
+	const snapshot = coerceSnapshot(working);
+	return snapshot
+		? { ok: true, snapshot, migrated }
+		: { ok: false, reason: 'unreadable' };
+}
+
+/**
+ * Validates shape after migration.
+ *
+ * Runs even on a non-migrated record because the bytes came off a device where
+ * anything could have happened to them — a partial write, a rooted user, a
+ * truncated file.
+ */
+function coerceSnapshot(input: Record<string, unknown>): PersistedSnapshot | null {
+	const entitlements = input.entitlements;
+	const purchases = input.purchases;
+
+	if (typeof entitlements !== 'object' || entitlements === null) {
+		return null;
+	}
+	if (!Array.isArray(purchases)) {
+		return null;
+	}
+
+	const lastSyncedAt =
+		typeof input.lastSyncedAt === 'number' ? input.lastSyncedAt : undefined;
+	const scopeToken =
+		typeof input.scopeToken === 'string' ? input.scopeToken : undefined;
+
+	return {
+		schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+		scopeToken,
+		entitlements: entitlements as Record<EntitlementKey, PersistedEntitlement>,
+		purchases: purchases as PersistedPurchase[],
+		lastSyncedAt,
+	};
+}
+
+/**
+ * Decides a purchase's finalization state from the store's view plus what we
+ * already knew.
+ *
+ * Shared by the sync path and the purchase path so they cannot drift — and they
+ * must not, because a disagreement here is how a paid transaction goes
+ * unacknowledged and gets auto-refunded three days later.
+ *
+ * The subtle case is a **pending purchase that settles**. Its record was written
+ * with `not_required`, which was correct while the money had not arrived. Once the
+ * store reports it `purchased`, that value must be re-evaluated rather than
+ * preserved — otherwise the transaction is never queued, never acknowledged, and
+ * Google revokes it. Progress is preserved only for a transaction that was
+ * already in the queue.
+ */
+export function resolveFinalizeState(
+	incoming: { state: 'purchased' | 'pending' | 'unspecified'; isAcknowledged: boolean },
+	existing: { finalizeState: PersistedFinalizeState } | undefined,
+): PersistedFinalizeState {
+	if (incoming.state === 'pending') {
+		// Nothing to settle: there is no entitlement to report as delivered.
+		return 'not_required';
+	}
+
+	// Already settled at the store, whatever we thought locally.
+	if (incoming.isAcknowledged) {
+		return 'done';
+	}
+
+	// Genuine in-queue progress is preserved, so a sync cannot reset an attempt
+	// count or lose an in-flight finalize.
+	if (
+		existing &&
+		existing.finalizeState !== 'not_required' &&
+		existing.finalizeState !== 'done'
+	) {
+		return existing.finalizeState;
+	}
+
+	// Covers both a brand-new purchase and a previously-pending one that just
+	// settled. Either way it is now owed a finalize call.
+	return 'queued';
+}
+
+/** Transactions still owed a finalize call, drained at startup and on foreground (FR-042). */
+export function pendingFinalizations(
+	snapshot: PersistedSnapshot,
+): PersistedPurchase[] {
+	return snapshot.purchases.filter(
+		p =>
+			(p.finalizeState === 'queued' ||
+				p.finalizeState === 'in_flight' ||
+				p.finalizeState === 'failed') &&
+			p.state !== 'revoked',
+	);
+}

package/src/react/PaymentProvider.tsx

@@ -0,0 +1,79 @@
+/**
+ * React integration.
+ *
+ * The provider owns the engine's lifecycle so an app does not have to remember to
+ * clean up. It renders nothing of its own — no paywall, no price table, no
+ * button. Every surface belongs to the app (UX-001).
+ */
+
+import React, {
+	createContext,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+	type PropsWithChildren,
+} from 'react';
+import { createEngine, type EngineDeps, type PaymentEngine } from '../engine/engine';
+import type { PaymentConfig } from '../config/types';
+
+const PaymentContext = createContext<PaymentEngine | null>(null);
+
+export interface PaymentProviderProps {
+	config: PaymentConfig;
+	/**
+	 * Provider injection.
+	 *
+	 * Required until the real adapter ships; also how a test or the demo app
+	 * supplies the fake store. Keeping it explicit rather than defaulting to a
+	 * lazily-required binding means a missing native module is a clear
+	 * configuration error instead of a mysterious runtime failure.
+	 */
+	deps: EngineDeps;
+	/** Skip automatic initialization when the app wants to control the moment. */
+	autoInitialize?: boolean;
+}
+
+export function PaymentProvider({
+	config,
+	deps,
+	autoInitialize = true,
+	children,
+}: PropsWithChildren<PaymentProviderProps>): React.ReactElement {
+	// Built once per config identity. Rebuilding on every render would reconnect
+	// to the billing service repeatedly, which FR-018 exists to prevent.
+	const engine = useMemo(() => createEngine(config, deps), [config, deps]);
+	const engineRef = useRef<PaymentEngine>(engine);
+	engineRef.current = engine;
+
+	useEffect(() => {
+		if (autoInitialize) {
+			engine.initialize().catch(() => undefined);
+		}
+		// Cleanup on unmount is the whole reason the provider owns the engine:
+		// after it, no event fires and no timer survives (FR-082).
+		return () => engine.cleanup();
+	}, [engine, autoInitialize]);
+
+	return (
+		<PaymentContext.Provider value={engine}>{children}</PaymentContext.Provider>
+	);
+}
+
+/**
+ * The engine from context.
+ *
+ * Throws when used outside a provider, deliberately: returning null would push a
+ * null check into every consumer and let a genuine wiring mistake read as "no
+ * entitlement" — the exact conflation this package exists to prevent.
+ */
+export function usePaymentEngine(): PaymentEngine {
+	const engine = useContext(PaymentContext);
+	if (!engine) {
+		throw new Error(
+			'usePaymentEngine must be used inside a <PaymentProvider>. Wrap your app ' +
+				'or the screen that reads entitlements.',
+		);
+	}
+	return engine;
+}

package/src/react/hooks.ts

@@ -0,0 +1,238 @@
+/**
+ * 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 };
+}