@chipmobilesdk/rn-payment 0.1.0 → 0.2.1

package/src/engine/subscriptions.ts

@@ -1,157 +1,157 @@
-/**
- * Subscription plan changes and the route to the store's management screen (US12).
- *
- * Two platform rules drive this module:
- *
- * - **Proration is the app's decision, inside what the store permits** (FR-065).
- *   Whether a user who upgrades gets charged immediately, keeps their remaining
- *   time, or starts a fresh period is a product and pricing choice, so the
- *   package forwards it rather than picking.
- * - **Cancellation belongs to the store.** Platforms forbid an app presenting its
- *   own cancellation screen, so this module offers only a route to the store's
- *   (FR-066) — there is deliberately no self-built alternative anywhere in the
- *   package.
- */
-
-import type {
-	ProductKey,
-	PurchaseOptions,
-	PurchaseResult,
-} from '../config/types';
-import type { ResolvedConfig } from '../config/validate';
-import type { ProviderPort } from '../adapter/port';
-import { storeIdForProductKey } from '../entitlements/mapping';
-import type { PersistedSnapshot } from '../persistence/snapshot';
-
-/**
- * How already-paid time is handled when a plan changes.
- *
- * Named for the user-visible effect rather than mirroring a store's enum, so the
- * same vocabulary will map onto StoreKit later (FR-004).
- */
-export type ProrationMode =
-	/** Switch now; credit unused time against the new plan. The usual upgrade. */
-	| 'immediate_with_time_proration'
-	/** Switch now; charge the full new price immediately and restart the period. */
-	| 'immediate_and_charge_full_price'
-	/** Switch now; charge the prorated difference for the current period. */
-	| 'immediate_and_charge_prorated_price'
-	/** Keep the current plan until it expires, then start the new one. Usual downgrade. */
-	| 'deferred';
-
-/** Store-specific replacement codes stay here, behind the neutral vocabulary above. */
-const PRORATION_CODES: Record<ProrationMode, string> = {
-	immediate_with_time_proration: 'WITH_TIME_PRORATION',
-	immediate_and_charge_full_price: 'CHARGE_FULL_PRICE',
-	immediate_and_charge_prorated_price: 'CHARGE_PRORATED_PRICE',
-	deferred: 'DEFERRED',
-};
-
-export type PriceChangeResult =
-	| { kind: 'confirmed' }
-	| { kind: 'dismissed' }
-	/** The platform has no client-side flow; it notifies the user itself (FR-067). */
-	| { kind: 'unsupported' }
-	| { kind: 'failed'; code: string };
-
-export interface SubscriptionsDeps {
-	resolved: ResolvedConfig;
-	provider: ProviderPort;
-	snapshot: () => PersistedSnapshot;
-	purchase: (
-		productKey: ProductKey,
-		options?: PurchaseOptions & { replaceProductKey?: ProductKey; prorationMode?: string },
-	) => Promise<PurchaseResult>;
-}
-
-export interface Subscriptions {
-	changePlan(
-		fromProductKey: ProductKey,
-		toProductKey: ProductKey,
-		mode: ProrationMode,
-		options?: PurchaseOptions,
-	): Promise<PurchaseResult>;
-	openManagement(productKey?: ProductKey): Promise<void>;
-	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
-}
-
-export function createSubscriptions(deps: SubscriptionsDeps): Subscriptions {
-	const { resolved } = deps;
-
-	return {
-		async changePlan(
-			fromProductKey,
-			toProductKey,
-			mode,
-			options,
-		): Promise<PurchaseResult> {
-			if (!deps.provider.capabilities().supportsPlanChange) {
-				return { kind: 'unsupported' };
-			}
-
-			const target = resolved.entries.get(toProductKey);
-			if (!target) {
-				return { kind: 'unknown_product', productKey: toProductKey };
-			}
-			if (!resolved.entries.has(fromProductKey)) {
-				return { kind: 'unknown_product', productKey: fromProductKey };
-			}
-
-			// The store needs the *token* of the subscription being replaced, not its
-			// product id — that is how it knows which active purchase to migrate, and
-			// it is why a plan change needs a live local record rather than just two
-			// product keys.
-			const active = deps
-				.snapshot()
-				.purchases.find(
-					p =>
-						p.productKey === fromProductKey &&
-						p.productType === 'subscription' &&
-						p.state === 'purchased',
-				);
-
-			if (!active) {
-				// No subscription to replace. Treated as a plain purchase would be
-				// surprising — the caller asked to *change* something that is not there,
-				// which almost always means its own state is stale.
-				return { kind: 'already_owned', productKey: fromProductKey };
-			}
-
-			// Routed through the normal purchase flow on purpose: a plan change is a
-			// purchase, so it must inherit the single-flight lock, the environment
-			// guard, validation, and the finalization queue rather than reimplementing
-			// any of them.
-			return deps.purchase(toProductKey, {
-				...options,
-				replaceProductKey: fromProductKey,
-				prorationMode: PRORATION_CODES[mode],
-			});
-		},
-
-		async openManagement(productKey?: ProductKey): Promise<void> {
-			const storeProductId = productKey
-				? storeIdForProductKey(resolved, productKey)
-				: undefined;
-			// No-ops rather than throwing where the platform has no such screen: this
-			// is wired to a button, and a button that crashes is worse than one that
-			// does nothing on a platform that cannot honour it.
-			await deps.provider.openSubscriptionManagement(storeProductId);
-		},
-
-		async confirmPriceChange(productKey): Promise<PriceChangeResult> {
-			if (!deps.provider.capabilities().supportsPriceChangeConfirmation) {
-				return { kind: 'unsupported' };
-			}
-			const storeProductId = storeIdForProductKey(resolved, productKey);
-			if (!storeProductId) {
-				return { kind: 'failed', code: 'PAYMENT_UNKNOWN_PRODUCT' };
-			}
-
-			const outcome = await deps.provider.confirmPriceChange(storeProductId);
-			if (!outcome.ok) {
-				return { kind: 'failed', code: 'PAYMENT_STORE_ERROR' };
-			}
-			return outcome.confirmed ? { kind: 'confirmed' } : { kind: 'dismissed' };
-		},
-	};
-}
+/**
+ * Subscription plan changes and the route to the store's management screen (US12).
+ *
+ * Two platform rules drive this module:
+ *
+ * - **Proration is the app's decision, inside what the store permits** (FR-065).
+ *   Whether a user who upgrades gets charged immediately, keeps their remaining
+ *   time, or starts a fresh period is a product and pricing choice, so the
+ *   package forwards it rather than picking.
+ * - **Cancellation belongs to the store.** Platforms forbid an app presenting its
+ *   own cancellation screen, so this module offers only a route to the store's
+ *   (FR-066) — there is deliberately no self-built alternative anywhere in the
+ *   package.
+ */
+
+import type {
+	ProductKey,
+	PurchaseOptions,
+	PurchaseResult,
+} from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import type { ProviderPort } from '../adapter/port';
+import { storeIdForProductKey } from '../entitlements/mapping';
+import type { PersistedSnapshot } from '../persistence/snapshot';
+
+/**
+ * How already-paid time is handled when a plan changes.
+ *
+ * Named for the user-visible effect rather than mirroring a store's enum, so the
+ * same vocabulary will map onto StoreKit later (FR-004).
+ */
+export type ProrationMode =
+	/** Switch now; credit unused time against the new plan. The usual upgrade. */
+	| 'immediate_with_time_proration'
+	/** Switch now; charge the full new price immediately and restart the period. */
+	| 'immediate_and_charge_full_price'
+	/** Switch now; charge the prorated difference for the current period. */
+	| 'immediate_and_charge_prorated_price'
+	/** Keep the current plan until it expires, then start the new one. Usual downgrade. */
+	| 'deferred';
+
+/** Store-specific replacement codes stay here, behind the neutral vocabulary above. */
+const PRORATION_CODES: Record<ProrationMode, string> = {
+	immediate_with_time_proration: 'WITH_TIME_PRORATION',
+	immediate_and_charge_full_price: 'CHARGE_FULL_PRICE',
+	immediate_and_charge_prorated_price: 'CHARGE_PRORATED_PRICE',
+	deferred: 'DEFERRED',
+};
+
+export type PriceChangeResult =
+	| { kind: 'confirmed' }
+	| { kind: 'dismissed' }
+	/** The platform has no client-side flow; it notifies the user itself (FR-067). */
+	| { kind: 'unsupported' }
+	| { kind: 'failed'; code: string };
+
+export interface SubscriptionsDeps {
+	resolved: ResolvedConfig;
+	provider: ProviderPort;
+	snapshot: () => PersistedSnapshot;
+	purchase: (
+		productKey: ProductKey,
+		options?: PurchaseOptions & { replaceProductKey?: ProductKey; prorationMode?: string },
+	) => Promise<PurchaseResult>;
+}
+
+export interface Subscriptions {
+	changePlan(
+		fromProductKey: ProductKey,
+		toProductKey: ProductKey,
+		mode: ProrationMode,
+		options?: PurchaseOptions,
+	): Promise<PurchaseResult>;
+	openManagement(productKey?: ProductKey): Promise<void>;
+	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
+}
+
+export function createSubscriptions(deps: SubscriptionsDeps): Subscriptions {
+	const { resolved } = deps;
+
+	return {
+		async changePlan(
+			fromProductKey,
+			toProductKey,
+			mode,
+			options,
+		): Promise<PurchaseResult> {
+			if (!deps.provider.capabilities().supportsPlanChange) {
+				return { kind: 'unsupported' };
+			}
+
+			const target = resolved.entries.get(toProductKey);
+			if (!target) {
+				return { kind: 'unknown_product', productKey: toProductKey };
+			}
+			if (!resolved.entries.has(fromProductKey)) {
+				return { kind: 'unknown_product', productKey: fromProductKey };
+			}
+
+			// The store needs the *token* of the subscription being replaced, not its
+			// product id — that is how it knows which active purchase to migrate, and
+			// it is why a plan change needs a live local record rather than just two
+			// product keys.
+			const active = deps
+				.snapshot()
+				.purchases.find(
+					p =>
+						p.productKey === fromProductKey &&
+						p.productType === 'subscription' &&
+						p.state === 'purchased',
+				);
+
+			if (!active) {
+				// No subscription to replace. Treated as a plain purchase would be
+				// surprising — the caller asked to *change* something that is not there,
+				// which almost always means its own state is stale.
+				return { kind: 'already_owned', productKey: fromProductKey };
+			}
+
+			// Routed through the normal purchase flow on purpose: a plan change is a
+			// purchase, so it must inherit the single-flight lock, the environment
+			// guard, validation, and the finalization queue rather than reimplementing
+			// any of them.
+			return deps.purchase(toProductKey, {
+				...options,
+				replaceProductKey: fromProductKey,
+				prorationMode: PRORATION_CODES[mode],
+			});
+		},
+
+		async openManagement(productKey?: ProductKey): Promise<void> {
+			const storeProductId = productKey
+				? storeIdForProductKey(resolved, productKey)
+				: undefined;
+			// No-ops rather than throwing where the platform has no such screen: this
+			// is wired to a button, and a button that crashes is worse than one that
+			// does nothing on a platform that cannot honour it.
+			await deps.provider.openSubscriptionManagement(storeProductId);
+		},
+
+		async confirmPriceChange(productKey): Promise<PriceChangeResult> {
+			if (!deps.provider.capabilities().supportsPriceChangeConfirmation) {
+				return { kind: 'unsupported' };
+			}
+			const storeProductId = storeIdForProductKey(resolved, productKey);
+			if (!storeProductId) {
+				return { kind: 'failed', code: 'PAYMENT_UNKNOWN_PRODUCT' };
+			}
+
+			const outcome = await deps.provider.confirmPriceChange(storeProductId);
+			if (!outcome.ok) {
+				return { kind: 'failed', code: 'PAYMENT_STORE_ERROR' };
+			}
+			return outcome.confirmed ? { kind: 'confirmed' } : { kind: 'dismissed' };
+		},
+	};
+}

package/src/entitlements/aggregate.ts

@@ -134,17 +134,34 @@ function subscriptionDetailFor(
  * touch I/O (PERF-001). The engine calls it after any state change and caches the
  * result.
  */
-export function aggregate(input: AggregateInput): EntitlementMap {
+/**
+ * How far the snapshot can be trusted right now.
+ *
+ * Shared by entitlements and the pending set (FR-103) so the two can never
+ * disagree about whether the package knows anything — a paywall that showed
+ * "not entitled" next to "nothing pending" from one stale snapshot would offer
+ * Buy to a user whose payment is in flight.
+ */
+export function snapshotCertainty(input: {
+	config: Pick<ResolvedConfig, 'staleAfterMs'>;
+	snapshot: Pick<PersistedSnapshot, 'lastSyncedAt'>;
+	hasSynced: boolean;
+	now: number;
+}): { isStale: boolean; undetermined: boolean } {
 	const { config, snapshot, hasSynced, now } = input;
-
 	const isStale =
 		snapshot.lastSyncedAt !== undefined &&
 		now - snapshot.lastSyncedAt > config.staleAfterMs;
 
-	// Both roads lead to `unknown`, never to `not_entitled`. Never having synced
+	// Both roads lead to `unknown`, never to a confident "no". Never having synced
 	// and having synced too long ago are the same epistemic state: we cannot
 	// currently support a claim either way.
-	const undetermined = !hasSynced || isStale;
+	return { isStale, undetermined: !hasSynced || isStale };
+}
+
+export function aggregate(input: AggregateInput): EntitlementMap {
+	const { config, snapshot } = input;
+	const { isStale, undetermined } = snapshotCertainty(input);
 
 	const valid = snapshot.purchases.filter(p => isValidSource(p, input));
 

package/src/index.ts

@@ -35,6 +35,9 @@ export type {
 	PaymentConfig,
 	PaymentStatus,
 	PaymentStatusKind,
+	PendingPurchase,
+	PendingPurchasesState,
+	PendingResolution,
 	ProductKey,
 	ProductType,
 	PurchaseOptions,
@@ -127,6 +130,7 @@ export {
 	useEntitlement,
 	useEntitlements,
 	usePaymentStatus,
+	usePendingPurchases,
 	useProducts,
 	usePurchase,
 	useSync,

package/src/persistence/mmkv-store.ts

@@ -23,10 +23,11 @@ import {
 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;
-	delete(key: string): void;
+	remove(key: string): unknown;
 	clearAll(): void;
 	getAllKeys(): string[];
 }
@@ -54,21 +55,28 @@ function createMemoryBacking(): MmkvLike {
 		set(key, value) {
 			map.set(key, value);
 		},
-		delete(key) {
-			map.delete(key);
-		},
+		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 mod = require('react-native-mmkv') as {
-			MMKV: new (config?: { id?: string }) => MmkvLike;
+		const { createMMKV } = require('react-native-mmkv') as {
+			createMMKV: (config?: { id?: string }) => MmkvLike;
 		};
-		return { backing: new mod.MMKV({ id: INSTANCE_ID }), durable: true };
+		return { backing: createMMKV({ id: INSTANCE_ID }), durable: true };
 	} catch {
 		return { backing: createMemoryBacking(), durable: false };
 	}
@@ -132,7 +140,7 @@ export function createSnapshotStore(
 			try {
 				for (const key of backing.getAllKeys()) {
 					if (key.startsWith(`${KEY_PREFIX}:`)) {
-						backing.delete(key);
+						backing.remove(key);
 					}
 				}
 			} catch {