@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/persistence/snapshot.ts

@@ -1,247 +1,220 @@
-/**
- * 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',
-	);
-}
+/**
+ * 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

@@ -1,79 +1,90 @@
-/**
- * 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;
-}
+/**
+ * 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 { syncOnForeground as watchForeground } from '../engine/foreground';
+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;
+	/**
+	 * Call `handleForeground()` each time the app returns from the background, through
+	 * rn-core's shared lifecycle port. Off by default: what counts as a foreground
+	 * return is the app's decision (FR-059).
+	 */
+	syncOnForeground?: boolean;
+}
+
+export function PaymentProvider({
+	config,
+	deps,
+	autoInitialize = true,
+	syncOnForeground = false,
+	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]);
+
+	useEffect(
+		() => (syncOnForeground ? watchForeground(engine) : undefined),
+		[engine, syncOnForeground],
+	);
+
+	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;
+}