@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/engine/purchase.ts

@@ -0,0 +1,526 @@
+/**
+ * The purchase flow.
+ *
+ * Ordering here is deliberate and load-bearing:
+ *
+ * 1. Refuse early and cheaply — disabled, not ready, already busy, environment
+ *    blocked, unknown product — so nothing reaches the store that should not.
+ * 2. Launch, and map every store outcome onto a typed result (FR-005).
+ * 3. Pending stops here: it is persisted and signalled, but **never granted**
+ *    (FR-037).
+ * 4. Validate with the app's backend, if one is configured, and only for a
+ *    **newly completed** purchase (FR-069a).
+ * 5. Grant the entitlement, then finalize. In that order — the user gets what
+ *    they paid for before the bookkeeping completes, so a finalize failure never
+ *    withholds a paid entitlement. Finalization is still guaranteed, by the
+ *    persisted queue.
+ */
+
+import type {
+	PaymentConfig,
+	ProductKey,
+	PurchaseOptions,
+	PurchaseResult,
+	TransactionRef,
+} from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import type {
+	ProviderFailureReason,
+	ProviderPort,
+	ProviderPurchase,
+} from '../adapter/port';
+import type { ExclusiveOutcome } from '../core/mutex';
+import { withTimeout } from '../core/mutex';
+import { PaymentError } from '../diagnostics/errors';
+import type { PaymentEventInput } from '../diagnostics/events';
+import {
+	resolveFinalizeState,
+	type PersistedPurchase,
+	type PersistedSnapshot,
+} from '../persistence/snapshot';
+import { storeIdForProductKey } from '../entitlements/mapping';
+import type { Finalizer } from './finalize';
+
+export interface PurchaseFlowDeps {
+	config: PaymentConfig;
+	resolved: ResolvedConfig;
+	provider: ProviderPort;
+	finalizer: Finalizer;
+	snapshot: () => PersistedSnapshot;
+	commit: (next: PersistedSnapshot) => void;
+	emit: (event: PaymentEventInput) => void;
+	now: () => number;
+	nextCorrelationId: () => string;
+	statusKind: () => PaymentStatusKindLike;
+	mayCreateRealTransaction: () => boolean;
+	recordBlockedOperation: (productKey: ProductKey) => void;
+	requestSync: (trigger: 'already_owned') => void;
+	runExclusive: <T>(operation: () => Promise<T>) => Promise<ExclusiveOutcome<T>>;
+}
+
+type PaymentStatusKindLike =
+	| 'not_started'
+	| 'connecting'
+	| 'ready'
+	| 'disabled'
+	| 'unavailable'
+	| 'failed';
+
+/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
+function mapFailure(
+	reason: ProviderFailureReason,
+	productKey: ProductKey,
+): PurchaseResult {
+	switch (reason) {
+		case 'user_cancelled':
+			return { kind: 'user_cancelled', productKey };
+		case 'already_owned':
+			return { kind: 'already_owned', productKey };
+		case 'ineligible':
+			return { kind: 'ineligible', productKey };
+		case 'unknown_product':
+			return { kind: 'unknown_product', productKey };
+		case 'product_unavailable_in_region':
+			return { kind: 'product_unavailable_in_region', productKey };
+		case 'not_ready':
+			return { kind: 'not_ready', status: 'connecting' };
+		case 'network_error':
+			return { kind: 'network_error', productKey };
+		case 'timeout':
+			return { kind: 'timeout', productKey };
+		case 'store_error':
+			return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
+	}
+}
+
+/** Plan-change parameters, which only `subscriptions.ts` supplies. */
+export interface InternalPurchaseOptions extends PurchaseOptions {
+	replaceProductKey?: ProductKey;
+	prorationMode?: string;
+}
+
+export interface PurchaseFlow {
+	purchase(
+		productKey: ProductKey,
+		options?: InternalPurchaseOptions,
+	): Promise<PurchaseResult>;
+	/** Handles a store-pushed update, e.g. a pending purchase settling (FR-039). */
+	ingest(purchase: ProviderPurchase): Promise<void>;
+	/**
+	 * Re-runs the backend check for transactions granted under the
+	 * failure-fallback (FR-072a).
+	 *
+	 * Called on sync, so recovery happens on the app's own rhythm rather than on a
+	 * timer of ours. A rejection here revokes, which is what bounds the exposure
+	 * that `grant_and_queue` accepts.
+	 */
+	revalidate(): Promise<void>;
+}
+
+export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
+	const { resolved } = deps;
+
+	const toRef = (record: PersistedPurchase): TransactionRef => ({
+		transactionId: record.transactionId,
+		productKey: record.productKey,
+	});
+
+	/** Writes or replaces the record for one transaction. */
+	const upsert = (record: PersistedPurchase): void => {
+		const snapshot = deps.snapshot();
+		const others = snapshot.purchases.filter(
+			p => p.transactionId !== record.transactionId,
+		);
+		deps.commit({ ...snapshot, purchases: [...others, record] });
+	};
+
+	const recordFor = (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+	): PersistedPurchase => {
+		const entry = resolved.entries.get(productKey);
+		const existing = deps
+			.snapshot()
+			.purchases.find(p => p.transactionId === purchase.transactionId);
+		return {
+			transactionId: purchase.transactionId,
+			productKey,
+			productType: entry?.productType ?? 'one_time_permanent',
+			token: purchase.token,
+			state: purchase.state === 'pending' ? 'pending' : 'purchased',
+			purchasedAt: purchase.purchasedAt,
+			// Shared with the sync path so the two cannot disagree about what is still
+			// owed a finalize call.
+			finalizeState: resolveFinalizeState(purchase, existing),
+			attempts: existing?.attempts ?? 0,
+			validationState: existing?.validationState ?? 'not_required',
+			expiresAt: purchase.expiresAt,
+			willAutoRenew: purchase.willAutoRenew,
+		};
+	};
+
+	/**
+	 * Runs the app's backend check, if configured.
+	 *
+	 * Called for newly completed purchases only (FR-069a) — sync and restore trust
+	 * a decision already made, which is what keeps restore working while the
+	 * backend is unreachable.
+	 */
+	const validate = async (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<
+		| { outcome: 'approved' }
+		| { outcome: 'rejected'; reason?: string }
+		| { outcome: 'granted_pending_revalidation' }
+	> => {
+		const hook = deps.config.validateTransaction;
+		if (!hook) {
+			return { outcome: 'approved' };
+		}
+
+		const entry = resolved.entries.get(productKey);
+		try {
+			const decision = await hook({
+				productKey,
+				productType: entry?.productType ?? 'one_time_permanent',
+				verificationPayload: purchase.verificationPayload ?? '',
+				correlationId,
+			});
+			deps.emit({
+				type: 'validation_decided',
+				productKey,
+				decision: decision.approved ? 'approved' : 'rejected',
+			});
+			return decision.approved
+				? { outcome: 'approved' }
+				: { outcome: 'rejected', reason: decision.reason };
+		} catch {
+			// A hook that throws is unavailable, never an implicit approval (FR-072b).
+			const fallback = resolved.onValidationUnavailable;
+			deps.emit({ type: 'validation_unavailable', productKey, fallback });
+			return fallback === 'grant_and_queue'
+				? { outcome: 'granted_pending_revalidation' }
+				: { outcome: 'rejected', reason: 'validation_unavailable' };
+		}
+	};
+
+	/** Persists a completed purchase, grants it, then finalizes. */
+	const settle = async (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<PurchaseResult> => {
+		const decision = await validate(purchase, productKey, correlationId);
+
+		if (decision.outcome === 'rejected') {
+			upsert({
+				...recordFor(purchase, productKey),
+				validationState: 'rejected',
+				finalizeState: 'queued',
+			});
+			// Still finalized with the store: the money moved, so leaving it
+			// unacknowledged would have Google refund it while our backend has
+			// already decided the user is not entitled. Refunding is the app owner's
+			// call, not a side effect of a bookkeeping omission.
+			await deps.finalizer.enqueue(purchase.transactionId);
+			return {
+				kind: 'validation_rejected',
+				productKey,
+				reason: decision.reason,
+			};
+		}
+
+		upsert({
+			...recordFor(purchase, productKey),
+			validationState:
+				decision.outcome === 'granted_pending_revalidation'
+					? 'queued_for_revalidation'
+					: 'approved',
+			finalizeState: 'queued',
+		});
+
+		// Grant is already live at this point: `commit` recomputed entitlements.
+		// Finalize second, so a store hiccup cannot withhold what was paid for.
+		await deps.finalizer.enqueue(purchase.transactionId);
+
+		const record = deps
+			.snapshot()
+			.purchases.find(p => p.transactionId === purchase.transactionId);
+		return {
+			kind: 'success',
+			productKey,
+			transaction: record
+				? toRef(record)
+				: { transactionId: purchase.transactionId, productKey },
+		};
+	};
+
+	const handlePending = (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+	): PurchaseResult => {
+		upsert(recordFor(purchase, productKey));
+		deps.emit({ type: 'purchase_pending', productKey });
+		return {
+			kind: 'pending',
+			productKey,
+			transaction: { transactionId: purchase.transactionId, productKey },
+		};
+	};
+
+	/**
+	 * The store returned a purchase in a state it could not name — neither paid
+	 * nor pending. Nothing is granted, persisted or acknowledged on it.
+	 *
+	 * Retrying is the repair path: if the money did move, the store answers
+	 * `already_owned`, which re-syncs and grants (FR-033).
+	 */
+	const handleUnspecified = (
+		productKey: ProductKey,
+		correlationId: string,
+	): PurchaseResult => {
+		deps.emit({
+			type: 'purchase_failed',
+			productKey,
+			code: 'PAYMENT_STORE_ERROR',
+			retryable: true,
+			correlationId,
+		});
+		return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
+	};
+
+	return {
+		async purchase(
+			productKey: ProductKey,
+			options?: InternalPurchaseOptions,
+		): Promise<PurchaseResult> {
+			if (!resolved.enabled) {
+				return { kind: 'disabled' };
+			}
+
+			const status = deps.statusKind();
+			if (status !== 'ready') {
+				return { kind: 'not_ready', status };
+			}
+
+			const storeProductId = storeIdForProductKey(resolved, productKey);
+			if (!storeProductId) {
+				return { kind: 'unknown_product', productKey };
+			}
+
+			// The block that makes a developer mistake unable to move real money.
+			// Gated on the provider actually being one that would: the fake store
+			// must still be able to complete a purchase in a test (FR-014).
+			if (
+				deps.provider.capabilities().createsRealTransactions &&
+				!deps.mayCreateRealTransaction()
+			) {
+				deps.recordBlockedOperation(productKey);
+				return {
+					kind: 'environment_blocked',
+					productKey,
+					environment: deps.config.environment,
+				};
+			}
+
+			const entry = resolved.entries.get(productKey);
+			const correlationId = deps.nextCorrelationId();
+
+			// Exclusive, not single-flight: a second purchase is refused rather than
+			// joined or queued, so no second store surface opens (FR-031).
+			const attempt = await deps.runExclusive(async () => {
+				deps.emit({ type: 'purchase_started', productKey, correlationId });
+
+				let outcome;
+				try {
+					outcome = await withTimeout(
+						deps.provider.launchPurchase({
+							storeProductId,
+							productType: entry?.productType ?? 'one_time_permanent',
+							offerKey: options?.offerKey,
+							obfuscatedAccountId: options?.obfuscatedAccountId,
+							// Present only for a plan change. The store needs the token of
+							// the subscription being replaced so it migrates the existing
+							// purchase instead of creating a second one (FR-065).
+							replaceStoreProductId: options?.replaceProductKey
+								? deps
+										.snapshot()
+										.purchases.find(
+											p =>
+												p.productKey === options.replaceProductKey &&
+												p.state === 'purchased',
+										)?.token
+								: undefined,
+							prorationMode: options?.prorationMode,
+						}),
+						// Covers opening the store surface only. Time the user spends
+						// inside it is the store's, not ours (FR-035).
+						resolved.timeouts.purchaseLaunchMs,
+						() =>
+							new PaymentError({
+								code: 'PAYMENT_TIMEOUT',
+								message: 'Opening the purchase surface timed out',
+								operation: 'purchase',
+								retryable: true,
+							}),
+					);
+				} catch {
+					deps.emit({
+						type: 'purchase_failed',
+						productKey,
+						code: 'PAYMENT_TIMEOUT',
+						retryable: true,
+						correlationId,
+					});
+					return { kind: 'timeout', productKey } as PurchaseResult;
+				}
+
+				if (!outcome.ok) {
+					const mapped = mapFailure(outcome.reason, productKey);
+
+					if (mapped.kind === 'user_cancelled') {
+						// A normal outcome. Reported on its own channel so it is never
+						// counted as a technical failure (FR-032).
+						deps.emit({ type: 'purchase_cancelled', productKey, correlationId });
+						return mapped;
+					}
+
+					if (mapped.kind === 'already_owned') {
+						// How a reinstall or a new device repairs itself (FR-033).
+						deps.requestSync('already_owned');
+						return mapped;
+					}
+
+					deps.emit({
+						type: 'purchase_failed',
+						productKey,
+						code:
+							mapped.kind === 'network_error'
+								? 'PAYMENT_NETWORK_ERROR'
+								: mapped.kind === 'unknown_product'
+									? 'PAYMENT_UNKNOWN_PRODUCT'
+									: mapped.kind === 'ineligible'
+										? 'PAYMENT_INELIGIBLE'
+										: mapped.kind === 'product_unavailable_in_region'
+											? 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
+											: 'PAYMENT_STORE_ERROR',
+						retryable: mapped.kind === 'network_error',
+						correlationId,
+					});
+					return mapped;
+				}
+
+				if (outcome.purchase.state === 'pending') {
+					return handlePending(outcome.purchase, productKey);
+				}
+
+				if (outcome.purchase.state === 'unspecified') {
+					return handleUnspecified(productKey, correlationId);
+				}
+
+				deps.emit({ type: 'purchase_succeeded', productKey, correlationId });
+				return settle(outcome.purchase, productKey, correlationId);
+			});
+
+			if (!attempt.acquired) {
+				return { kind: 'purchase_in_progress' };
+			}
+			return attempt.value;
+		},
+
+		/**
+		 * A store-pushed update.
+		 *
+		 * This is how a pending purchase that settled between sessions is granted
+		 * without the user buying again (FR-039). It runs outside the exclusive lock
+		 * because it is not a user-initiated purchase and must not be refused just
+		 * because one is open.
+		 */
+		async ingest(purchase: ProviderPurchase): Promise<void> {
+			const productKey = resolved.byStoreId.get(purchase.storeProductId);
+			if (!productKey) {
+				return;
+			}
+
+			if (purchase.state === 'pending') {
+				handlePending(purchase, productKey);
+				return;
+			}
+
+			if (purchase.state === 'unspecified') {
+				// No basis to grant or to end anything. The next sync reports what
+				// the store actually holds.
+				return;
+			}
+
+			const existing = deps
+				.snapshot()
+				.purchases.find(p => p.transactionId === purchase.transactionId);
+
+			// Already settled and validated: nothing to redo, and re-running the hook
+			// here would break FR-069a's "new purchases only" rule.
+			if (existing && existing.state === 'purchased' && existing.validationState !== 'not_required') {
+				await deps.finalizer.enqueue(purchase.transactionId);
+				return;
+			}
+
+			await settle(purchase, productKey, deps.nextCorrelationId());
+		},
+
+		async revalidate(): Promise<void> {
+			const hook = deps.config.validateTransaction;
+			if (!hook) {
+				return;
+			}
+
+			const queued = deps
+				.snapshot()
+				.purchases.filter(p => p.validationState === 'queued_for_revalidation');
+
+			for (const record of queued) {
+				const entry = resolved.entries.get(record.productKey);
+				let approved: boolean;
+				try {
+					const decision = await hook({
+						productKey: record.productKey,
+						productType: entry?.productType ?? 'one_time_permanent',
+						// Re-validation deliberately carries no payload: the original
+						// verification material is not persisted (FR-056), so the backend
+						// re-checks by transaction against its own record of the purchase.
+						verificationPayload: '',
+						correlationId: deps.nextCorrelationId(),
+					});
+					approved = decision.approved;
+				} catch {
+					// Still unreachable. Leave it queued and try again next sync rather
+					// than revoking from a paying user because our backend is down.
+					continue;
+				}
+
+				const snapshot = deps.snapshot();
+				deps.commit({
+					...snapshot,
+					purchases: snapshot.purchases.map(p =>
+						p.transactionId === record.transactionId
+							? {
+									...p,
+									validationState: approved ? 'approved' : 'rejected',
+									// A rejection on recovery revokes, which is the bound on the
+									// exposure `grant_and_queue` accepts (FR-072a).
+									state: approved ? p.state : 'revoked',
+								}
+							: p,
+					),
+				});
+
+				deps.emit({
+					type: 'validation_decided',
+					productKey: record.productKey,
+					decision: approved ? 'approved' : 'rejected',
+				});
+			}
+		},
+	};
+}

package/src/engine/subscriptions.ts

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