@chipmobilesdk/rn-payment 0.4.1 → 0.6.0

package/src/engine/state.ts

@@ -0,0 +1,253 @@
+/**
+ * The engine's state and the one way it changes (PAY-10).
+ *
+ * Status, the persisted snapshot, entitlements and pending purchases live here
+ * with the listeners that hear about them. Every change goes through `commit`
+ * (the snapshot) or `setStatus`, so diffing and emission are written once:
+ * an entitlement is granted or revoked exactly once however many sources it has
+ * (FR-079), a renewal that changes nothing emits nothing (FR-068), and an
+ * unchanged map is the same object (PERF-03).
+ */
+import { createListenerSet, type ListenerSet } from '@chipmobilesdk/rn-core';
+
+import type { ProviderPort } from '../adapter/port';
+import type { ResolvedConfig } from '../config/validate';
+import type { PaymentConfig, PaymentStatus, PendingPurchasesState } from '../config/types';
+import { redact } from '../diagnostics/errors';
+import {
+	createEmitter,
+	type PaymentEmitter,
+	type PaymentEvent,
+	type PaymentEventInput,
+} from '../diagnostics/events';
+import {
+	aggregate,
+	diffEntitlements,
+	initialEntitlements,
+	shareUnchanged,
+	type EntitlementMap,
+} from '../entitlements/aggregate';
+import type { SnapshotStore } from '../persistence/mmkv-store';
+import { emptySnapshot, type PersistedSnapshot } from '../persistence/snapshot';
+import { derivePending, pendingTransitions, samePending, UNKNOWN_PENDING } from './pending';
+
+type RevokeReason = 'expired' | 'revoked_by_store' | 'validation_rejected' | 'consumed';
+
+export interface EngineState {
+	readonly config: PaymentConfig;
+	readonly resolved: ResolvedConfig;
+	readonly provider: ProviderPort;
+	readonly store: SnapshotStore;
+	readonly now: () => number;
+	readonly emitter: PaymentEmitter;
+	readonly statusListeners: ListenerSet<[PaymentStatus]>;
+	readonly entitlementListeners: ListenerSet<[EntitlementMap]>;
+	readonly pendingListeners: ListenerSet<[PendingPurchasesState]>;
+
+	disposed: boolean;
+	/** Whether the snapshot comes from a sync that succeeded; until then entitlements are `unknown`. */
+	hasSynced: boolean;
+	snapshot: PersistedSnapshot;
+	entitlements: EntitlementMap;
+	status: PaymentStatus;
+	pending: PendingPurchasesState;
+
+	emit(event: PaymentEventInput): void;
+	setStatus(next: Partial<PaymentStatus>): void;
+	/** Writes the snapshot, reports pending purchases that ended, and recomputes. */
+	commit(next: PersistedSnapshot): void;
+	/** Loads the persisted snapshot at startup (FR-053). */
+	hydrate(): void;
+	/** Forgets everything local, back to `unknown` (FR-057). */
+	forget(): void;
+}
+
+export function createEngineState(
+	config: PaymentConfig,
+	resolved: ResolvedConfig,
+	provider: ProviderPort,
+	store: SnapshotStore,
+	now: () => number,
+): EngineState {
+	// A listener that throws is a consumer bug, so it goes to the app's own logger
+	// rather than back into the event stream (FR-080, FR-081).
+	const emitter = createEmitter((error, event) => {
+		config.logger?.error?.('payment event listener threw', {
+			eventType: event.type,
+			reason: redact(error),
+		});
+	});
+	const listenerOptions = {
+		onListenerError: (error: unknown) =>
+			config.logger?.error?.('payment listener threw', { reason: redact(error) }),
+	};
+
+	/**
+	 * Why an entitlement that was held is held no more, from what its sources left
+	 * behind (PAY-12): a backend rejection, a consumed item, an expired
+	 * subscription — or, when the store simply stopped reporting it, a refund.
+	 */
+	function revokeReason(sources: readonly string[]): RevokeReason {
+		const records = state.snapshot.purchases.filter(record => sources.includes(record.productKey));
+		if (records.some(record => record.validationState === 'rejected')) {
+			return 'validation_rejected';
+		}
+		if (records.some(record => record.state === 'consumed')) {
+			return 'consumed';
+		}
+		const at = now();
+		if (records.some(record => record.expiresAt !== undefined && record.expiresAt <= at)) {
+			return 'expired';
+		}
+		return 'revoked_by_store';
+	}
+
+	function publishPending(next: PendingPurchasesState): void {
+		// Diffed: a sync that changes nothing is the common case, and an app
+		// rendering "payment pending" has no use for a re-render that says the same.
+		if (samePending(state.pending, next)) {
+			return;
+		}
+		state.pending = next;
+		state.pendingListeners.notify(next);
+	}
+
+	function recompute(): void {
+		if (state.disposed) {
+			return;
+		}
+		const previous = state.entitlements;
+		state.entitlements = shareUnchanged(
+			previous,
+			aggregate({
+				config: resolved,
+				snapshot: state.snapshot,
+				hasSynced: state.hasSynced,
+				reportsGraceAndHoldDistinctly: provider.capabilities().reportsGraceAndHoldDistinctly,
+				now: now(),
+			}),
+		);
+		for (const change of diffEntitlements(previous, state.entitlements)) {
+			if (change.next === 'entitled') {
+				state.emit({
+					type: 'entitlement_granted',
+					entitlementKey: change.key,
+					sources: change.sources,
+				});
+			} else if (change.previous === 'entitled') {
+				state.emit({
+					type: 'entitlement_revoked',
+					entitlementKey: change.key,
+					reason: revokeReason(previous[change.key]?.sources ?? []),
+				});
+			}
+		}
+		if (state.entitlements !== previous) {
+			state.entitlementListeners.notify(state.entitlements);
+		}
+		publishPending(
+			derivePending({
+				config: resolved,
+				snapshot: state.snapshot,
+				hasSynced: state.hasSynced,
+				now: now(),
+			}),
+		);
+	}
+
+	const state: EngineState = {
+		config,
+		resolved,
+		provider,
+		store,
+		now,
+		emitter,
+		statusListeners: createListenerSet<[PaymentStatus]>(listenerOptions),
+		entitlementListeners: createListenerSet<[EntitlementMap]>(listenerOptions),
+		pendingListeners: createListenerSet<[PendingPurchasesState]>(listenerOptions),
+
+		disposed: false,
+		hasSynced: false,
+		snapshot: emptySnapshot(config.scopeToken),
+		entitlements: initialEntitlements(resolved),
+		status: { kind: resolved.enabled ? 'not_started' : 'disabled', blockedOperations: [] },
+		pending: UNKNOWN_PENDING,
+
+		emit(event) {
+			emitter.emit({ ...event, timestamp: event.timestamp ?? now() } as PaymentEvent);
+		},
+
+		setStatus(next) {
+			if (state.disposed) {
+				return;
+			}
+			state.status = { ...state.status, ...next };
+			state.emit({
+				type: 'initialization',
+				status: state.status.kind,
+				unavailableReason: state.status.unavailableReason,
+				retryable: state.status.retryable,
+			});
+			state.statusListeners.notify(state.status);
+		},
+
+		commit(next) {
+			// Read before the swap: a transition is "pending before, not pending now",
+			// and only the commit sees both sides (FR-104).
+			const ended = pendingTransitions(state.snapshot, next, resolved, transactionId =>
+				provider.pendingEndReason?.(transactionId),
+			);
+			state.snapshot = next;
+			if (store.save(next) === false) {
+				// The write-intent-first guarantee (FR-042) did not hold for this write.
+				// Said out loud: the app learns its finalize queue may not survive a kill.
+				state.emit({
+					type: 'internal_error',
+					code: 'PAYMENT_STORAGE_UNAVAILABLE',
+					operation: 'persist',
+				});
+			}
+			// Before `recompute`, so `settled` precedes the `entitlement_granted` it
+			// causes (FR-102).
+			for (const transition of ended) {
+				state.emit({
+					type: 'purchase_pending_resolved',
+					productKey: transition.productKey,
+					outcome: transition.outcome,
+				});
+			}
+			recompute();
+		},
+
+		hydrate() {
+			state.snapshot = store.load(config.scopeToken);
+			// A record with `lastSyncedAt` was written by a sync that succeeded, so it
+			// is a basis for asserting entitlement — and the only one a build with
+			// selling disabled will ever have (FR-012, FR-053).
+			if (state.snapshot.lastSyncedAt !== undefined) {
+				state.hasSynced = true;
+			}
+			if (!store.isDurable()) {
+				state.emit({
+					type: 'config_warning',
+					detail: 'Local storage unavailable; entitlements will not survive restart',
+				});
+			}
+			recompute();
+		},
+
+		forget() {
+			store.clearAll();
+			state.snapshot = emptySnapshot(config.scopeToken);
+			state.hasSynced = false;
+			// Back to `unknown`, not `not_entitled`: after a logout there is no basis
+			// for either claim until the next sync.
+			state.entitlements = initialEntitlements(resolved);
+			state.entitlementListeners.notify(state.entitlements);
+			// No `purchase_pending_resolved`: the records were discarded locally, not
+			// ended at the store.
+			publishPending(UNKNOWN_PENDING);
+		},
+	};
+	return state;
+}

package/src/engine/sync.ts

@@ -0,0 +1,161 @@
+/**
+ * Syncing with the store, and the one translation from a store purchase to a
+ * persisted record (PAY-10).
+ *
+ * The purchase flow and sync both build records here, so they cannot disagree
+ * about what a transaction still owes: a disagreement is how a paid purchase
+ * goes unacknowledged and is refunded three days later.
+ */
+import type { ProviderPurchase } from '../adapter/port';
+import type { ProductKey } from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import { PaymentError } from '../diagnostics/errors';
+import type { SyncTrigger } from '../diagnostics/events';
+import { productKeyForStoreId } from '../entitlements/mapping';
+import { createRateLimiter, createSingleFlight, withTimeout } from '../core/mutex';
+import { resolveFinalizeState, type PersistedPurchase } from '../persistence/snapshot';
+import type { EngineState } from './state';
+
+export type SyncOutcome =
+	{ ok: true; restoredCount: number; revokedCount: number } | { ok: false; error: PaymentError };
+
+/** The persisted record for one store purchase, keeping what we already knew about it. */
+export function toPersistedRecord(
+	resolved: ResolvedConfig,
+	purchase: ProviderPurchase,
+	productKey: ProductKey,
+	existing: PersistedPurchase | undefined,
+): PersistedPurchase {
+	return {
+		transactionId: purchase.transactionId,
+		productKey,
+		productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
+		token: purchase.token,
+		state: purchase.state === 'pending' ? 'pending' : 'purchased',
+		purchasedAt: purchase.purchasedAt,
+		// Finalize progress survives: a sync must never reset a queued
+		// acknowledgement and lose the paid transaction.
+		finalizeState: resolveFinalizeState(purchase, existing),
+		attempts: existing?.attempts ?? 0,
+		validationState: existing?.validationState ?? 'not_required',
+		expiresAt: purchase.expiresAt,
+		willAutoRenew: purchase.willAutoRenew,
+	};
+}
+
+/** Store purchases as records, dropping products this catalog does not know. */
+function toPersisted(
+	resolved: ResolvedConfig,
+	purchases: readonly ProviderPurchase[],
+	known: readonly PersistedPurchase[],
+): PersistedPurchase[] {
+	const records: PersistedPurchase[] = [];
+	for (const purchase of purchases) {
+		// Legitimately possible: a user owns something from a build whose catalog
+		// has since changed. Ignored rather than treated as impossible.
+		const productKey = productKeyForStoreId(resolved, purchase.storeProductId);
+		if (!productKey || !resolved.entries.has(productKey)) {
+			continue;
+		}
+		const existing = known.find(p => p.transactionId === purchase.transactionId);
+		if (purchase.state === 'unspecified') {
+			// No basis for granting, finalizing or ending anything: a new transaction
+			// waits until the store says what it is, a known one keeps what we knew.
+			if (existing) {
+				records.push(existing);
+			}
+			continue;
+		}
+		records.push(toPersistedRecord(resolved, purchase, productKey, existing));
+	}
+	return records;
+}
+
+function purchasedIds(records: readonly PersistedPurchase[]): Set<string> {
+	return new Set(records.filter(p => p.state === 'purchased').map(p => p.transactionId));
+}
+
+export interface Sync {
+	sync(trigger?: SyncTrigger): Promise<SyncOutcome>;
+}
+
+/**
+ * `settle` runs after every successful sync, outside the sync flight: the finalize
+ * drain and backend revalidation (FR-039, FR-042, FR-072a). Inside the flight, one
+ * store call or hook that never answered held it, and every later sync joined
+ * that stuck promise for the rest of the session.
+ */
+export function createSync(state: EngineState, settle: () => Promise<void>): Sync {
+	const { resolved, provider, now } = state;
+	const syncFlight = createSingleFlight<SyncOutcome>();
+	const settleFlight = createSingleFlight<void>();
+	const foregroundLimiter = createRateLimiter(resolved.foregroundSyncMinIntervalMs, now);
+
+	async function querySnapshot(trigger: SyncTrigger): Promise<SyncOutcome> {
+		try {
+			const owned = await withTimeout(
+				provider.queryOwned(),
+				resolved.timeouts.syncMs,
+				() =>
+					new PaymentError({
+						code: 'PAYMENT_TIMEOUT',
+						message: 'Syncing entitlements timed out',
+						operation: 'sync',
+						retryable: true,
+					}),
+			);
+			const before = purchasedIds(state.snapshot.purchases);
+			const records = toPersisted(resolved, owned, state.snapshot.purchases);
+			const after = purchasedIds(records);
+			// A transaction the store no longer reports is revoked — a refund. The
+			// cache must not resurrect it (FR-064, FR-055).
+			const revokedCount = [...before].filter(id => !after.has(id)).length;
+			const restoredCount = [...after].filter(id => !before.has(id)).length;
+
+			state.hasSynced = true;
+			state.commit({ ...state.snapshot, purchases: records, lastSyncedAt: now() });
+			state.emit({ type: 'sync_completed', restoredCount, revokedCount, trigger });
+			return { ok: true, restoredCount, revokedCount };
+		} catch (error) {
+			const paymentError =
+				error instanceof PaymentError
+					? error
+					: new PaymentError({
+							code: 'PAYMENT_STORE_ERROR',
+							message: 'Sync failed',
+							operation: 'sync',
+							retryable: true,
+						});
+			// A failed sync leaves the previous snapshot in place, so offline
+			// entitlements survive rather than being wiped (FR-053).
+			state.emit({ type: 'internal_error', code: paymentError.code, operation: 'sync' });
+			return { ok: false, error: paymentError };
+		}
+	}
+
+	return {
+		async sync(trigger = 'manual') {
+			if (state.disposed || !resolved.enabled) {
+				return {
+					ok: false,
+					error: new PaymentError({
+						code: 'PAYMENT_DISABLED',
+						message: 'Payments are disabled',
+						operation: 'sync',
+					}),
+				};
+			}
+			// Rejected rather than deferred: the next foreground event tries again,
+			// whereas queueing would fire a burst once the interval elapsed (PERF-002).
+			if (trigger === 'foreground' && !foregroundLimiter.tryAcquire()) {
+				return { ok: true, restoredCount: 0, revokedCount: 0 };
+			}
+			// Concurrent callers join one flight: one store request (FR-063).
+			const outcome = await syncFlight.run(() => querySnapshot(trigger));
+			if (outcome.ok) {
+				await settleFlight.run(settle);
+			}
+			return outcome;
+		},
+	};
+}

package/src/entitlements/aggregate.ts

@@ -16,6 +16,7 @@
  *   and the package says so rather than asserting the user did not pay.
  */
 
+import { shallowEqual } from '@chipmobilesdk/rn-core';
 import type { ResolvedConfig } from '../config/validate';
 import type { EntitlementKey, ProductKey } from '../config/types';
 import type { PersistedPurchase, PersistedSnapshot } from '../persistence/snapshot';
@@ -55,11 +56,9 @@ export interface AggregateInput {
 
 /** A purchase that currently confers its entitlements. */
 function isValidSource(purchase: PersistedPurchase, input: AggregateInput): boolean {
-	// Pending money is not money. No configuration and no code path may grant here.
-	if (purchase.state === 'pending') {
-		return false;
-	}
-	if (purchase.state === 'revoked' || purchase.state === 'consumed') {
+	// Only a purchase the store confirmed grants. Pending money is not money, and a
+	// state this version does not know is no basis for a grant either (PAY-13).
+	if (purchase.state !== 'purchased') {
 		return false;
 	}
 	// A backend that said no is final (FR-071). A queued re-validation still
@@ -225,3 +224,36 @@ export function diffEntitlements(
 	}
 	return changes;
 }
+
+function sameEntitlement(a: EntitlementState, b: EntitlementState): boolean {
+	return (
+		a.status === b.status &&
+		a.isStale === b.isStale &&
+		a.lastSyncedAt === b.lastSyncedAt &&
+		a.sources.length === b.sources.length &&
+		a.sources.every((source, index) => source === b.sources[index]) &&
+		shallowEqual(a.subscription, b.subscription)
+	);
+}
+
+/**
+ * `next`, with every entitlement that did not change replaced by the object it
+ * replaces, and `previous` itself when nothing changed (PERF-03, PAY-08). A hook
+ * selecting one entitlement then sees the same object and does not re-render.
+ */
+export function shareUnchanged(previous: EntitlementMap, next: EntitlementMap): EntitlementMap {
+	const keys = Object.keys(next);
+	let changed = keys.length !== Object.keys(previous).length;
+	const shared: EntitlementMap = {};
+	for (const key of keys) {
+		const before = previous[key];
+		const after = next[key]!;
+		if (before && sameEntitlement(before, after)) {
+			shared[key] = before;
+		} else {
+			shared[key] = after;
+			changed = true;
+		}
+	}
+	return changed ? shared : previous;
+}

package/src/entitlements/mapping.ts

@@ -21,14 +21,6 @@ export function entitlementsFor(
 	return config.grants.get(productKey) ?? [];
 }
 
-/** Products that could grant an entitlement, whether or not any is currently valid. */
-export function sourcesFor(
-	config: ResolvedConfig,
-	entitlementKey: EntitlementKey,
-): readonly ProductKey[] {
-	return config.sources.get(entitlementKey) ?? [];
-}
-
 /**
  * Translates a store product id back to the app's own product key.
  *
@@ -51,17 +43,3 @@ export function storeIdForProductKey(
 ): string | undefined {
 	return config.entries.get(productKey)?.storeProductIds[config.platform];
 }
-
-/** Which entitlements a set of granting products covers, de-duplicated. */
-export function entitlementsCoveredBy(
-	config: ResolvedConfig,
-	productKeys: Iterable<ProductKey>,
-): Set<EntitlementKey> {
-	const covered = new Set<EntitlementKey>();
-	for (const productKey of productKeys) {
-		for (const entitlement of entitlementsFor(config, productKey)) {
-			covered.add(entitlement);
-		}
-	}
-	return covered;
-}

package/src/index.ts

@@ -120,6 +120,8 @@ export type {
 	SyncOutcome,
 } from './engine/engine';
 
+export { syncOnForeground } from './engine/foreground';
+
 // --- React -----------------------------------------------------------------
 export { PaymentProvider, usePaymentEngine } from './react/PaymentProvider';
 export type { PaymentProviderProps } from './react/PaymentProvider';
@@ -150,6 +152,7 @@ export type {
 export {
 	DEFAULT_DEVELOPER_MESSAGES,
 	DEFAULT_MESSAGES,
+	paymentMessages,
 	DEFAULT_USER_MESSAGES,
 	DEVELOPER_MESSAGE_KEYS,
 	USER_MESSAGE_KEYS,

package/src/persistence/mmkv-store.ts

@@ -14,23 +14,29 @@
  * attached to a transaction.
  */
 
+import { createMemoryKeyValue, lazyPeer, openDurable, type MmkvLike } from '@chipmobilesdk/rn-core';
+
 import { emptySnapshot, migrateSnapshot, type PersistedSnapshot } from './snapshot';
 
 const INSTANCE_ID = 'chipmobilesdk.payment';
 const KEY_PREFIX = 'snapshot';
 
-/** The slice of a react-native-mmkv v4 instance this store uses (v4 names). */
-interface MmkvLike {
-	getString(key: string): string | undefined;
-	set(key: string, value: string): void;
-	remove(key: string): unknown;
-	clearAll(): void;
-	getAllKeys(): string[];
-}
+const mmkv = lazyPeer('react-native-mmkv', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-mmkv') as { createMMKV: (config?: { id?: string }) => MmkvLike };
+	} catch (cause) {
+		throw cause;
+	}
+});
 
 export interface SnapshotStore {
 	load(scopeToken?: string): PersistedSnapshot;
-	save(snapshot: PersistedSnapshot): void;
+	/**
+	 * Writes the snapshot. Returns false when the write failed, so the engine can
+	 * say so; a store returning nothing is taken to have succeeded.
+	 */
+	save(snapshot: PersistedSnapshot): boolean | 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. */
@@ -43,20 +49,6 @@ function scopeKey(scopeToken?: string): string {
 	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);
-		},
-		remove: key => map.delete(key),
-		clearAll: () => map.clear(),
-		getAllKeys: () => [...map.keys()],
-	};
-}
-
 /**
  * Opens the MMKV instance through v4's `createMMKV`.
  *
@@ -67,15 +59,20 @@ function createMemoryBacking(): MmkvLike {
  * Tests could not see it, because the test double still exported a v3 class.
  */
 function resolveBacking(): { backing: MmkvLike; durable: boolean } {
-	try {
-		// Required lazily so the package loads where the native module is absent.
-		const { createMMKV } = require('react-native-mmkv') as {
-			createMMKV: (config?: { id?: string }) => MmkvLike;
-		};
-		return { backing: createMMKV({ id: INSTANCE_ID }), durable: true };
-	} catch {
-		return { backing: createMemoryBacking(), durable: false };
-	}
+	// rn-core's port: MMKV when it opens, otherwise memory with `durable: false`.
+	const port = openDurable(() =>
+		mmkv.require(peer => new Error(`${peer} is not installed`)).createMMKV({ id: INSTANCE_ID }),
+	);
+	return {
+		backing: {
+			getString: key => port.getString(key),
+			set: (key, value) => port.set(key, value),
+			remove: key => port.remove(key),
+			clearAll: () => port.clearAll(),
+			getAllKeys: () => port.keys(),
+		},
+		durable: port.durable,
+	};
 }
 
 /**
@@ -124,12 +121,15 @@ export function createSnapshotStore(injected?: {
 			return outcome.snapshot;
 		},
 
-		save(snapshot: PersistedSnapshot): void {
+		save(snapshot: PersistedSnapshot): boolean {
 			try {
 				backing.set(scopeKey(snapshot.scopeToken), JSON.stringify(snapshot));
+				return true;
 			} 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.
+				// state stays correct for this session and the next sync re-derives it;
+				// the engine reports it (PAY-13).
+				return false;
 			}
 		},
 
@@ -151,5 +151,15 @@ export function createSnapshotStore(injected?: {
 
 /** Test seam for driving the store without the native module. */
 export function createMemorySnapshotStore(): SnapshotStore {
-	return createSnapshotStore({ backing: createMemoryBacking(), durable: false });
+	const memory = createMemoryKeyValue();
+	return createSnapshotStore({
+		backing: {
+			getString: key => memory.getString(key),
+			set: (key, value) => memory.set(key, value),
+			remove: key => memory.remove(key),
+			clearAll: () => memory.clearAll(),
+			getAllKeys: () => memory.keys(),
+		},
+		durable: false,
+	});
 }