@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/entitlements/policy.ts

@@ -1,129 +1,121 @@
-/**
- * Grace and hold entitlement policy.
- *
- * This is a **business decision, not a technical constant** (FR-049), so it is
- * configurable with documented defaults.
- *
- * ## The defaults, and why
- *
- * `gracePolicy: 'grant'` — a grace period means the store is still retrying a
- * payment method that failed for reasons usually outside the user's control: an
- * expired card, a bank decline, a temporary hold. Revoking immediately punishes a
- * paying customer for a billing hiccup they may not know about yet.
- *
- * `holdPolicy: 'withhold'` — account hold means the store has given up retrying.
- * The subscription is effectively unpaid, and continuing to serve paid features
- * indefinitely is giving away the product.
- *
- * ## What Android can actually tell us
- *
- * Client-side Play Billing **cannot** separate grace from hold: a grace-period
- * subscription is still returned as active, and one in account hold stops being
- * returned at all — indistinguishable from expired, cancelled, or refunded.
- *
- * Fortunately the platform's own behavior matches the defaults above. Play keeps
- * returning a grace-period purchase, so the entitlement holds. Play stops
- * returning a held one, so it lapses at the next sync. **The default policy is
- * therefore correct with no backend at all.**
- *
- * What is *not* achievable client-side is a non-default policy — withholding
- * during grace, or granting during hold — because that needs the state the client
- * cannot see. Such an app supplies it through the validation hook (FR-069). This
- * limitation is documented rather than papered over (FR-058).
- */
-
-import type { LapsePolicy } from '../config/types';
-
-/**
- * A subscription's renewal state as far as the package can honestly tell.
- *
- * `indeterminate` is not a failure — it is the truthful answer when the platform
- * reports a subscription as active but cannot say whether that is a healthy
- * renewal, a cancelled-but-still-paid period, or a grace period.
- */
-export type RenewalState =
-	| 'active'
-	| 'cancelled_valid'
-	| 'grace'
-	| 'hold'
-	| 'indeterminate';
-
-export interface LapsePolicyConfig {
-	gracePolicy: LapsePolicy;
-	holdPolicy: LapsePolicy;
-}
-
-export interface SubscriptionFacts {
-	expiresAt?: number;
-	willAutoRenew?: boolean;
-	/** True only where the provider genuinely distinguishes grace/hold. */
-	reportsGraceAndHoldDistinctly: boolean;
-	/** Provider-reported, only meaningful when the flag above is true. */
-	providerRenewalState?: 'active' | 'grace' | 'hold';
-}
-
-/**
- * Derives the renewal state without inventing information.
- *
- * The temptation is to read `willAutoRenew === false` as "grace period", but that
- * same value is what a deliberate cancellation looks like. Guessing would mean
- * showing "there's a problem with your payment method" to someone who simply
- * chose not to renew — so when the provider cannot distinguish, neither do we.
- */
-export function deriveRenewalState(facts: SubscriptionFacts): RenewalState {
-	if (facts.reportsGraceAndHoldDistinctly && facts.providerRenewalState) {
-		switch (facts.providerRenewalState) {
-			case 'grace':
-				return 'grace';
-			case 'hold':
-				return 'hold';
-			case 'active':
-				return facts.willAutoRenew === false ? 'cancelled_valid' : 'active';
-		}
-	}
-
-	if (facts.willAutoRenew === false) {
-		// Still inside a paid period with auto-renew off. Genuinely ambiguous
-		// between "cancelled" and "in grace", so report the one that is certainly
-		// true — the period is paid for — and let the app decide how to present it.
-		return 'cancelled_valid';
-	}
-
-	if (facts.willAutoRenew === true) {
-		return 'active';
-	}
-
-	return 'indeterminate';
-}
-
-/**
- * Whether a subscription in this state should confer its entitlement.
- *
- * `hold` reaching this function at all requires a provider that reports it,
- * which Android does not. On Android a held subscription simply stops being
- * returned, so it never becomes a source and the entitlement lapses — the same
- * result the `withhold` default expresses.
- */
-export function grantsUnderPolicy(
-	state: RenewalState,
-	policy: LapsePolicyConfig,
-): boolean {
-	switch (state) {
-		case 'active':
-		case 'cancelled_valid':
-			return true;
-		case 'grace':
-			return policy.gracePolicy === 'grant';
-		case 'hold':
-			return policy.holdPolicy === 'grant';
-		case 'indeterminate':
-			// The store is still reporting the purchase as owned. Withholding here
-			// would revoke from a paying user because of our own uncertainty.
-			return true;
-	}
-}
-
-/** True once a subscription's paid period has genuinely elapsed (FR-048). */
-export function hasExpired(expiresAt: number | undefined, now: number): boolean {
-	return expiresAt !== undefined && expiresAt <= now;
-}
+/**
+ * Grace and hold entitlement policy.
+ *
+ * This is a **business decision, not a technical constant** (FR-049), so it is
+ * configurable with documented defaults.
+ *
+ * ## The defaults, and why
+ *
+ * `gracePolicy: 'grant'` — a grace period means the store is still retrying a
+ * payment method that failed for reasons usually outside the user's control: an
+ * expired card, a bank decline, a temporary hold. Revoking immediately punishes a
+ * paying customer for a billing hiccup they may not know about yet.
+ *
+ * `holdPolicy: 'withhold'` — account hold means the store has given up retrying.
+ * The subscription is effectively unpaid, and continuing to serve paid features
+ * indefinitely is giving away the product.
+ *
+ * ## What Android can actually tell us
+ *
+ * Client-side Play Billing **cannot** separate grace from hold: a grace-period
+ * subscription is still returned as active, and one in account hold stops being
+ * returned at all — indistinguishable from expired, cancelled, or refunded.
+ *
+ * Fortunately the platform's own behavior matches the defaults above. Play keeps
+ * returning a grace-period purchase, so the entitlement holds. Play stops
+ * returning a held one, so it lapses at the next sync. **The default policy is
+ * therefore correct with no backend at all.**
+ *
+ * What is *not* achievable client-side is a non-default policy — withholding
+ * during grace, or granting during hold — because that needs the state the client
+ * cannot see. Such an app supplies it through the validation hook (FR-069). This
+ * limitation is documented rather than papered over (FR-058).
+ */
+
+import type { LapsePolicy } from '../config/types';
+
+/**
+ * A subscription's renewal state as far as the package can honestly tell.
+ *
+ * `indeterminate` is not a failure — it is the truthful answer when the platform
+ * reports a subscription as active but cannot say whether that is a healthy
+ * renewal, a cancelled-but-still-paid period, or a grace period.
+ */
+export type RenewalState = 'active' | 'cancelled_valid' | 'grace' | 'hold' | 'indeterminate';
+
+export interface LapsePolicyConfig {
+	gracePolicy: LapsePolicy;
+	holdPolicy: LapsePolicy;
+}
+
+export interface SubscriptionFacts {
+	expiresAt?: number;
+	willAutoRenew?: boolean;
+	/** True only where the provider genuinely distinguishes grace/hold. */
+	reportsGraceAndHoldDistinctly: boolean;
+	/** Provider-reported, only meaningful when the flag above is true. */
+	providerRenewalState?: 'active' | 'grace' | 'hold';
+}
+
+/**
+ * Derives the renewal state without inventing information.
+ *
+ * The temptation is to read `willAutoRenew === false` as "grace period", but that
+ * same value is what a deliberate cancellation looks like. Guessing would mean
+ * showing "there's a problem with your payment method" to someone who simply
+ * chose not to renew — so when the provider cannot distinguish, neither do we.
+ */
+export function deriveRenewalState(facts: SubscriptionFacts): RenewalState {
+	if (facts.reportsGraceAndHoldDistinctly && facts.providerRenewalState) {
+		switch (facts.providerRenewalState) {
+			case 'grace':
+				return 'grace';
+			case 'hold':
+				return 'hold';
+			case 'active':
+				return facts.willAutoRenew === false ? 'cancelled_valid' : 'active';
+		}
+	}
+
+	if (facts.willAutoRenew === false) {
+		// Still inside a paid period with auto-renew off. Genuinely ambiguous
+		// between "cancelled" and "in grace", so report the one that is certainly
+		// true — the period is paid for — and let the app decide how to present it.
+		return 'cancelled_valid';
+	}
+
+	if (facts.willAutoRenew === true) {
+		return 'active';
+	}
+
+	return 'indeterminate';
+}
+
+/**
+ * Whether a subscription in this state should confer its entitlement.
+ *
+ * `hold` reaching this function at all requires a provider that reports it,
+ * which Android does not. On Android a held subscription simply stops being
+ * returned, so it never becomes a source and the entitlement lapses — the same
+ * result the `withhold` default expresses.
+ */
+export function grantsUnderPolicy(state: RenewalState, policy: LapsePolicyConfig): boolean {
+	switch (state) {
+		case 'active':
+		case 'cancelled_valid':
+			return true;
+		case 'grace':
+			return policy.gracePolicy === 'grant';
+		case 'hold':
+			return policy.holdPolicy === 'grant';
+		case 'indeterminate':
+			// The store is still reporting the purchase as owned. Withholding here
+			// would revoke from a paying user because of our own uncertainty.
+			return true;
+	}
+}
+
+/** True once a subscription's paid period has genuinely elapsed (FR-048). */
+export function hasExpired(expiresAt: number | undefined, now: number): boolean {
+	return expiresAt !== undefined && expiresAt <= now;
+}

package/src/index.ts

@@ -91,10 +91,7 @@ export type {
 } from './engine/products';
 
 // --- Subscriptions ---------------------------------------------------------
-export type {
-	PriceChangeResult,
-	ProrationMode,
-} from './engine/subscriptions';
+export type { PriceChangeResult, ProrationMode } from './engine/subscriptions';
 
 // --- Entitlements ----------------------------------------------------------
 export type {
@@ -123,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';
@@ -135,11 +134,7 @@ export {
 	usePurchase,
 	useSync,
 } from './react/hooks';
-export type {
-	UseProductsResult,
-	UsePurchaseResult,
-	UseSyncResult,
-} from './react/hooks';
+export type { UseProductsResult, UsePurchaseResult, UseSyncResult } from './react/hooks';
 
 // --- Diagnostics -----------------------------------------------------------
 export { PaymentConfigError, PaymentError, PAYMENT_ERROR_CODES } from './diagnostics/errors';
@@ -157,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

@@ -1,158 +1,158 @@
-/**
- * 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';
-
-/** 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[];
-}
-
-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);
-		},
-		remove: key => map.delete(key),
-		clearAll: () => map.clear(),
-		getAllKeys: () => [...map.keys()],
-	};
-}
-
-/**
- * Opens the MMKV instance through v4's `createMMKV`.
- *
- * Up to 0.2.0 this called `new MMKV()`, the v3 constructor. In v4 — the only
- * major the peer range allows — `MMKV` is a type, not a value, so the call threw
- * and the store fell back to memory on every device: entitlements read `unknown`
- * after each cold start, and a pending purchase was forgotten after an app kill.
- * 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 };
-	}
-}
-
-/**
- * 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.remove(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 });
-}
+/**
+ * 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 { 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';
+
+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;
+	/** 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__'}`;
+}
+
+/**
+ * Opens the MMKV instance through v4's `createMMKV`.
+ *
+ * Up to 0.2.0 this called `new MMKV()`, the v3 constructor. In v4 — the only
+ * major the peer range allows — `MMKV` is a type, not a value, so the call threw
+ * and the store fell back to memory on every device: entitlements read `unknown`
+ * after each cold start, and a pending purchase was forgotten after an app kill.
+ * Tests could not see it, because the test double still exported a v3 class.
+ */
+function resolveBacking(): { backing: MmkvLike; durable: boolean } {
+	// 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,
+	};
+}
+
+/**
+ * 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.remove(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 {
+	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,
+	});
+}