@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/engine/finalize.ts

@@ -1,346 +1,343 @@
-/**
- * The finalization queue — the package's hardest invariant (FR-041, FR-042).
- *
- * Google auto-refunds and revokes a purchase that is not acknowledged within
- * **three days**. So finalization cannot be a step the app might forget, and it
- * cannot live only in memory: the failure case FR-042 names is the app being
- * force-killed in the instant between payment and acknowledgement.
- *
- * The ordering that makes this work is: **write the intent, then call the store.**
- * A crash before the write means the purchase is still owned and the next sync
- * re-queues it from `queryOwned`. A crash after the write means the queue has a
- * record and the next startup drains it. There is no window where a paid
- * transaction is forgotten.
- *
- * Consumption stays app-triggered (FR-043), because only the app knows whether
- * the item was actually banked in its own data.
- */
-
-import type {
-	FinalizeResult,
-	ProductKey,
-	TransactionRef,
-	UnfinalizedSummary,
-} from '../config/types';
-import type { ProviderPort } from '../adapter/port';
-import type { ResolvedRetry } from '../core/timers';
-import { backoffDelayMs } from '../core/retry';
-import { withTimeout } from '../core/mutex';
-import { PaymentError } from '../diagnostics/errors';
-import {
-	pendingFinalizations,
-	type PersistedPurchase,
-	type PersistedSnapshot,
-} from '../persistence/snapshot';
-import type { PaymentEventInput } from '../diagnostics/events';
-
-export interface FinalizerDeps {
-	provider: ProviderPort;
-	retry: ResolvedRetry;
-	/** `timeouts.finalizeAttemptMs`: one acknowledge or consume call may take no longer. */
-	attemptTimeoutMs: number;
-	snapshot: () => PersistedSnapshot;
-	commit: (next: PersistedSnapshot) => void;
-	emit: (event: PaymentEventInput) => void;
-	now: () => number;
-	disposed: () => boolean;
-	/** Injected so a test can run the retry schedule without waiting it out. */
-	setTimeoutFn?: (fn: () => void, ms: number) => FinalizeTimerHandle;
-	clearTimeoutFn?: (handle: FinalizeTimerHandle) => void;
-}
-
-/** A Node `Timeout` and a browser numeric id are both valid here. */
-type FinalizeTimerHandle = ReturnType<typeof setTimeout> | number;
-
-export interface Finalizer {
-	/** Records the intent to finalize, then attempts it. Safe to call repeatedly. */
-	enqueue(transactionId: string): Promise<FinalizeResult>;
-	/** Drains every outstanding finalization. Runs at startup and on foreground. */
-	drain(): Promise<void>;
-	/** App-triggered consumption of a consumable (FR-043). */
-	consume(ref: TransactionRef): Promise<FinalizeResult>;
-	/** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
-	unfinalized(): UnfinalizedSummary[];
-	/** Cancels pending retries. Idempotent, called from cleanup. */
-	dispose(): void;
-}
-
-export function createFinalizer(deps: FinalizerDeps): Finalizer {
-	const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
-	const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
-
-	/** One timer per transaction, so two transactions retry independently. */
-	const timers = new Map<string, FinalizeTimerHandle>();
-	/** Guards against two drains racing the same transaction. */
-	const inFlight = new Set<string>();
-
-	const find = (transactionId: string): PersistedPurchase | undefined =>
-		deps.snapshot().purchases.find(p => p.transactionId === transactionId);
-
-	const patch = (
-		transactionId: string,
-		changes: Partial<PersistedPurchase>,
-	): void => {
-		const snapshot = deps.snapshot();
-		deps.commit({
-			...snapshot,
-			purchases: snapshot.purchases.map(p =>
-				p.transactionId === transactionId ? { ...p, ...changes } : p,
-			),
-		});
-	};
-
-	/**
-	 * One store call under `attemptTimeoutMs`. A call that never settles used to
-	 * hold this transaction's in-flight guard and, through `drain`, the sync that
-	 * awaited it. Timing out counts as a failed attempt, so the retry schedule and
-	 * the next-session drain both still apply.
-	 */
-	const bounded = (call: Promise<void>, operation: 'finalize' | 'consume'): Promise<void> =>
-		withTimeout(
-			call,
-			deps.attemptTimeoutMs,
-			() =>
-				new PaymentError({
-					code: 'PAYMENT_TIMEOUT',
-					message: `The store did not answer the ${operation} call in time`,
-					operation,
-					retryable: true,
-				}),
-		);
-
-	const clearTimer = (transactionId: string): void => {
-		const timer = timers.get(transactionId);
-		if (timer !== undefined) {
-			clearTimeoutFn(timer);
-			timers.delete(transactionId);
-		}
-	};
-
-	/**
-	 * Attempts one finalize call.
-	 *
-	 * A consumable is **not** acknowledged here: it waits for the app's explicit
-	 * `consume`. Acknowledging it now would tell the store the entitlement was
-	 * delivered before the app has recorded the item, and a crash in between would
-	 * lose a paid item with no way to recover it.
-	 */
-	const attempt = async (transactionId: string): Promise<FinalizeResult> => {
-		if (deps.disposed()) {
-			return { kind: 'failed', code: 'PAYMENT_NOT_CONFIGURED' };
-		}
-
-		const record = find(transactionId);
-		if (!record) {
-			return { kind: 'unknown_transaction' };
-		}
-		if (record.finalizeState === 'done') {
-			// Idempotent by design: calling twice is a success, not an error (FR-044).
-			return { kind: 'already_finalized' };
-		}
-		if (record.productType === 'one_time_consumable') {
-			// The app owns this moment. Nothing to do until it calls consume().
-			return { kind: 'already_finalized' };
-		}
-		if (inFlight.has(transactionId)) {
-			return { kind: 'retry_scheduled', attempts: record.attempts };
-		}
-
-		inFlight.add(transactionId);
-		patch(transactionId, { finalizeState: 'in_flight' });
-
-		let failed = false;
-		try {
-			await bounded(deps.provider.acknowledge(record.token), 'finalize');
-		} catch {
-			failed = true;
-		} finally {
-			// Released before scheduling the retry, deliberately. The guard exists to
-			// stop two concurrent store calls for one transaction, nothing more — if
-			// it were still held here, the next scheduled attempt would be refused by
-			// our own lock and the retry schedule would silently stall after one try.
-			inFlight.delete(transactionId);
-		}
-
-		const attempts = record.attempts + 1;
-
-		if (!failed) {
-			clearTimer(transactionId);
-			patch(transactionId, {
-				finalizeState: 'done',
-				state: 'purchased',
-				attempts,
-			});
-			deps.emit({
-				type: 'transaction_finalized',
-				productKey: record.productKey,
-				attempts,
-			});
-			return { kind: 'finalized' };
-		}
-
-		patch(transactionId, { finalizeState: 'failed', attempts });
-		return scheduleRetry(transactionId, record.productKey, attempts, 'acknowledge');
-	};
-
-	/**
-	 * One consume call for a consumable the app has banked (FR-043).
-	 *
-	 * Refuses anything that is not a settled consumable. Consuming a subscription
-	 * or a permanent unlock would tell the store the user used it up, and a
-	 * pending purchase has nothing to consume yet.
-	 */
-	const consumeAttempt = async (transactionId: string): Promise<FinalizeResult> => {
-		if (deps.disposed()) {
-			return { kind: 'failed', code: 'PAYMENT_NOT_CONFIGURED' };
-		}
-		const record = find(transactionId);
-		if (!record) {
-			return { kind: 'unknown_transaction' };
-		}
-		if (record.productType !== 'one_time_consumable') {
-			return { kind: 'failed', code: 'PAYMENT_NOT_CONSUMABLE' };
-		}
-		if (record.state === 'pending') {
-			return { kind: 'failed', code: 'PAYMENT_PENDING' };
-		}
-		if (record.state === 'consumed') {
-			// Consuming twice must grant the item once (FR-044).
-			return { kind: 'already_finalized' };
-		}
-		if (inFlight.has(transactionId)) {
-			// Concurrent consume calls collapse to one, for the same reason.
-			return { kind: 'already_finalized' };
-		}
-
-		inFlight.add(transactionId);
-		patch(transactionId, { finalizeState: 'in_flight' });
-
-		let failed = false;
-		try {
-			await bounded(deps.provider.consume(record.token), 'consume');
-		} catch {
-			failed = true;
-		} finally {
-			// Released before scheduling, for the same reason as in `attempt`.
-			inFlight.delete(transactionId);
-		}
-
-		const attempts = record.attempts + 1;
-
-		if (failed) {
-			patch(transactionId, { finalizeState: 'failed', attempts });
-			return scheduleRetry(transactionId, record.productKey, attempts, 'consume');
-		}
-
-		clearTimer(transactionId);
-		// `consumed` is what stops it being an entitlement source, so a
-		// consumable never becomes a permanent unlock.
-		patch(transactionId, {
-			state: 'consumed',
-			finalizeState: 'done',
-			attempts,
-		});
-		deps.emit({
-			type: 'transaction_consumed',
-			productKey: record.productKey,
-		});
-		return { kind: 'finalized' };
-	};
-
-	/**
-	 * Schedules the next attempt inside the per-session budget.
-	 *
-	 * Exhausting the budget is **not** giving up. The record stays `failed`, which
-	 * `pendingFinalizations` still returns, so the next startup or foreground drain
-	 * picks it up again. That is what keeps the package inside Play's three-day
-	 * window without hammering a store that is currently refusing.
-	 */
-	const scheduleRetry = (
-		transactionId: string,
-		productKey: ProductKey,
-		attempts: number,
-		// The timer must repeat the call that failed. Retrying a failed consume
-		// through `attempt` was a no-op — `attempt` skips consumables — while the
-		// event still reported a retry as scheduled.
-		operation: 'acknowledge' | 'consume',
-	): FinalizeResult => {
-		if (deps.disposed()) {
-			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
-		}
-		if (attempts >= deps.retry.finalize.maxAttempts) {
-			// Left queued deliberately — resumed next session, never abandoned.
-			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
-		}
-
-		const delayMs = backoffDelayMs(attempts + 1, deps.retry.finalize);
-		clearTimer(transactionId);
-		timers.set(
-			transactionId,
-			setTimeoutFn(() => {
-				timers.delete(transactionId);
-				const retry = operation === 'consume' ? consumeAttempt : attempt;
-				retry(transactionId).catch(() => undefined);
-			}, delayMs),
-		);
-
-		deps.emit({
-			type: 'finalize_retry_scheduled',
-			productKey,
-			attempt: attempts + 1,
-			delayMs,
-		});
-		return { kind: 'retry_scheduled', attempts };
-	};
-
-	return {
-		async enqueue(transactionId: string): Promise<FinalizeResult> {
-			const record = find(transactionId);
-			if (!record) {
-				return { kind: 'unknown_transaction' };
-			}
-			if (record.finalizeState === 'done') {
-				return { kind: 'already_finalized' };
-			}
-
-			// The write happens BEFORE the store call. This single ordering is what
-			// makes a kill between payment and acknowledgement recoverable.
-			if (record.finalizeState !== 'in_flight') {
-				patch(transactionId, { finalizeState: 'queued' });
-			}
-			return attempt(transactionId);
-		},
-
-		async drain(): Promise<void> {
-			// Runs regardless of whether a purchase happened this session: the record
-			// it is looking for was probably written by a session that died.
-			for (const record of pendingFinalizations(deps.snapshot())) {
-				if (deps.disposed()) {
-					return;
-				}
-				await attempt(record.transactionId).catch(() => undefined);
-			}
-		},
-
-		consume(ref: TransactionRef): Promise<FinalizeResult> {
-			return consumeAttempt(ref.transactionId);
-		},
-
-		unfinalized(): UnfinalizedSummary[] {
-			return pendingFinalizations(deps.snapshot()).map(p => ({
-				productKey: p.productKey,
-				transactionId: p.transactionId,
-				attempts: p.attempts,
-				purchasedAt: p.purchasedAt,
-			}));
-		},
-
-		dispose(): void {
-			for (const timer of timers.values()) {
-				clearTimeoutFn(timer);
-			}
-			timers.clear();
-			inFlight.clear();
-		},
-	};
-}
+/**
+ * The finalization queue — the package's hardest invariant (FR-041, FR-042).
+ *
+ * Google auto-refunds and revokes a purchase that is not acknowledged within
+ * **three days**. So finalization cannot be a step the app might forget, and it
+ * cannot live only in memory: the failure case FR-042 names is the app being
+ * force-killed in the instant between payment and acknowledgement.
+ *
+ * The ordering that makes this work is: **write the intent, then call the store.**
+ * A crash before the write means the purchase is still owned and the next sync
+ * re-queues it from `queryOwned`. A crash after the write means the queue has a
+ * record and the next startup drains it. There is no window where a paid
+ * transaction is forgotten.
+ *
+ * Consumption stays app-triggered (FR-043), because only the app knows whether
+ * the item was actually banked in its own data.
+ */
+
+import type {
+	FinalizeResult,
+	ProductKey,
+	TransactionRef,
+	UnfinalizedSummary,
+} from '../config/types';
+import type { ProviderPort } from '../adapter/port';
+import type { ResolvedRetry } from '../core/timers';
+import { backoffDelayMs } from '../core/retry';
+import { withTimeout } from '../core/mutex';
+import { PaymentError } from '../diagnostics/errors';
+import {
+	pendingFinalizations,
+	type PersistedPurchase,
+	type PersistedSnapshot,
+} from '../persistence/snapshot';
+import type { PaymentEventInput } from '../diagnostics/events';
+
+export interface FinalizerDeps {
+	provider: ProviderPort;
+	retry: ResolvedRetry;
+	/** `timeouts.finalizeAttemptMs`: one acknowledge or consume call may take no longer. */
+	attemptTimeoutMs: number;
+	snapshot: () => PersistedSnapshot;
+	commit: (next: PersistedSnapshot) => void;
+	emit: (event: PaymentEventInput) => void;
+	now: () => number;
+	disposed: () => boolean;
+	/** Injected so a test can run the retry schedule without waiting it out. */
+	setTimeoutFn?: (fn: () => void, ms: number) => FinalizeTimerHandle;
+	clearTimeoutFn?: (handle: FinalizeTimerHandle) => void;
+}
+
+/** A Node `Timeout` and a browser numeric id are both valid here. */
+type FinalizeTimerHandle = ReturnType<typeof setTimeout> | number;
+
+export interface Finalizer {
+	/** Records the intent to finalize, then attempts it. Safe to call repeatedly. */
+	enqueue(transactionId: string): Promise<FinalizeResult>;
+	/** Drains every outstanding finalization. Runs at startup and on foreground. */
+	drain(): Promise<void>;
+	/** App-triggered consumption of a consumable (FR-043). */
+	consume(ref: TransactionRef): Promise<FinalizeResult>;
+	/** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
+	unfinalized(): UnfinalizedSummary[];
+	/** Cancels pending retries. Idempotent, called from cleanup. */
+	dispose(): void;
+}
+
+export function createFinalizer(deps: FinalizerDeps): Finalizer {
+	const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+
+	/** One timer per transaction, so two transactions retry independently. */
+	const timers = new Map<string, FinalizeTimerHandle>();
+	/** Guards against two drains racing the same transaction. */
+	const inFlight = new Set<string>();
+
+	const find = (transactionId: string): PersistedPurchase | undefined =>
+		deps.snapshot().purchases.find(p => p.transactionId === transactionId);
+
+	const patch = (transactionId: string, changes: Partial<PersistedPurchase>): void => {
+		const snapshot = deps.snapshot();
+		deps.commit({
+			...snapshot,
+			purchases: snapshot.purchases.map(p =>
+				p.transactionId === transactionId ? { ...p, ...changes } : p,
+			),
+		});
+	};
+
+	/**
+	 * One store call under `attemptTimeoutMs`. A call that never settles used to
+	 * hold this transaction's in-flight guard and, through `drain`, the sync that
+	 * awaited it. Timing out counts as a failed attempt, so the retry schedule and
+	 * the next-session drain both still apply.
+	 */
+	const bounded = (call: Promise<void>, operation: 'finalize' | 'consume'): Promise<void> =>
+		withTimeout(
+			call,
+			deps.attemptTimeoutMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_TIMEOUT',
+					message: `The store did not answer the ${operation} call in time`,
+					operation,
+					retryable: true,
+				}),
+		);
+
+	const clearTimer = (transactionId: string): void => {
+		const timer = timers.get(transactionId);
+		if (timer !== undefined) {
+			clearTimeoutFn(timer);
+			timers.delete(transactionId);
+		}
+	};
+
+	/**
+	 * Attempts one finalize call.
+	 *
+	 * A consumable is **not** acknowledged here: it waits for the app's explicit
+	 * `consume`. Acknowledging it now would tell the store the entitlement was
+	 * delivered before the app has recorded the item, and a crash in between would
+	 * lose a paid item with no way to recover it.
+	 */
+	const attempt = async (transactionId: string): Promise<FinalizeResult> => {
+		if (deps.disposed()) {
+			return { kind: 'failed', code: 'PAYMENT_NOT_CONFIGURED' };
+		}
+
+		const record = find(transactionId);
+		if (!record) {
+			return { kind: 'unknown_transaction' };
+		}
+		if (record.finalizeState === 'done') {
+			// Idempotent by design: calling twice is a success, not an error (FR-044).
+			return { kind: 'already_finalized' };
+		}
+		if (record.productType === 'one_time_consumable') {
+			// The app owns this moment. Nothing to do until it calls consume().
+			return { kind: 'already_finalized' };
+		}
+		if (inFlight.has(transactionId)) {
+			return { kind: 'retry_scheduled', attempts: record.attempts };
+		}
+
+		inFlight.add(transactionId);
+		patch(transactionId, { finalizeState: 'in_flight' });
+
+		let failed = false;
+		try {
+			await bounded(deps.provider.acknowledge(record.token), 'finalize');
+		} catch {
+			failed = true;
+		} finally {
+			// Released before scheduling the retry, deliberately. The guard exists to
+			// stop two concurrent store calls for one transaction, nothing more — if
+			// it were still held here, the next scheduled attempt would be refused by
+			// our own lock and the retry schedule would silently stall after one try.
+			inFlight.delete(transactionId);
+		}
+
+		const attempts = record.attempts + 1;
+
+		if (!failed) {
+			clearTimer(transactionId);
+			patch(transactionId, {
+				finalizeState: 'done',
+				state: 'purchased',
+				attempts,
+			});
+			deps.emit({
+				type: 'transaction_finalized',
+				productKey: record.productKey,
+				attempts,
+			});
+			return { kind: 'finalized' };
+		}
+
+		patch(transactionId, { finalizeState: 'failed', attempts });
+		return scheduleRetry(transactionId, record.productKey, attempts, 'acknowledge');
+	};
+
+	/**
+	 * One consume call for a consumable the app has banked (FR-043).
+	 *
+	 * Refuses anything that is not a settled consumable. Consuming a subscription
+	 * or a permanent unlock would tell the store the user used it up, and a
+	 * pending purchase has nothing to consume yet.
+	 */
+	const consumeAttempt = async (transactionId: string): Promise<FinalizeResult> => {
+		if (deps.disposed()) {
+			return { kind: 'failed', code: 'PAYMENT_NOT_CONFIGURED' };
+		}
+		const record = find(transactionId);
+		if (!record) {
+			return { kind: 'unknown_transaction' };
+		}
+		if (record.productType !== 'one_time_consumable') {
+			return { kind: 'failed', code: 'PAYMENT_NOT_CONSUMABLE' };
+		}
+		if (record.state === 'pending') {
+			return { kind: 'failed', code: 'PAYMENT_PENDING' };
+		}
+		if (record.state === 'consumed') {
+			// Consuming twice must grant the item once (FR-044).
+			return { kind: 'already_finalized' };
+		}
+		if (inFlight.has(transactionId)) {
+			// Concurrent consume calls collapse to one, for the same reason.
+			return { kind: 'already_finalized' };
+		}
+
+		inFlight.add(transactionId);
+		patch(transactionId, { finalizeState: 'in_flight' });
+
+		let failed = false;
+		try {
+			await bounded(deps.provider.consume(record.token), 'consume');
+		} catch {
+			failed = true;
+		} finally {
+			// Released before scheduling, for the same reason as in `attempt`.
+			inFlight.delete(transactionId);
+		}
+
+		const attempts = record.attempts + 1;
+
+		if (failed) {
+			patch(transactionId, { finalizeState: 'failed', attempts });
+			return scheduleRetry(transactionId, record.productKey, attempts, 'consume');
+		}
+
+		clearTimer(transactionId);
+		// `consumed` is what stops it being an entitlement source, so a
+		// consumable never becomes a permanent unlock.
+		patch(transactionId, {
+			state: 'consumed',
+			finalizeState: 'done',
+			attempts,
+		});
+		deps.emit({
+			type: 'transaction_consumed',
+			productKey: record.productKey,
+		});
+		return { kind: 'finalized' };
+	};
+
+	/**
+	 * Schedules the next attempt inside the per-session budget.
+	 *
+	 * Exhausting the budget is **not** giving up. The record stays `failed`, which
+	 * `pendingFinalizations` still returns, so the next startup or foreground drain
+	 * picks it up again. That is what keeps the package inside Play's three-day
+	 * window without hammering a store that is currently refusing.
+	 */
+	const scheduleRetry = (
+		transactionId: string,
+		productKey: ProductKey,
+		attempts: number,
+		// The timer must repeat the call that failed. Retrying a failed consume
+		// through `attempt` was a no-op — `attempt` skips consumables — while the
+		// event still reported a retry as scheduled.
+		operation: 'acknowledge' | 'consume',
+	): FinalizeResult => {
+		if (deps.disposed()) {
+			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
+		}
+		if (attempts >= deps.retry.finalize.maxAttempts) {
+			// Left queued deliberately — resumed next session, never abandoned.
+			return { kind: 'failed', code: 'PAYMENT_FINALIZE_FAILED' };
+		}
+
+		const delayMs = backoffDelayMs(attempts + 1, deps.retry.finalize);
+		clearTimer(transactionId);
+		timers.set(
+			transactionId,
+			setTimeoutFn(() => {
+				timers.delete(transactionId);
+				const retry = operation === 'consume' ? consumeAttempt : attempt;
+				retry(transactionId).catch(() => undefined);
+			}, delayMs),
+		);
+
+		deps.emit({
+			type: 'finalize_retry_scheduled',
+			productKey,
+			attempt: attempts + 1,
+			delayMs,
+		});
+		return { kind: 'retry_scheduled', attempts };
+	};
+
+	return {
+		async enqueue(transactionId: string): Promise<FinalizeResult> {
+			const record = find(transactionId);
+			if (!record) {
+				return { kind: 'unknown_transaction' };
+			}
+			if (record.finalizeState === 'done') {
+				return { kind: 'already_finalized' };
+			}
+
+			// The write happens BEFORE the store call. This single ordering is what
+			// makes a kill between payment and acknowledgement recoverable.
+			if (record.finalizeState !== 'in_flight') {
+				patch(transactionId, { finalizeState: 'queued' });
+			}
+			return attempt(transactionId);
+		},
+
+		async drain(): Promise<void> {
+			// Runs regardless of whether a purchase happened this session: the record
+			// it is looking for was probably written by a session that died.
+			for (const record of pendingFinalizations(deps.snapshot())) {
+				if (deps.disposed()) {
+					return;
+				}
+				await attempt(record.transactionId).catch(() => undefined);
+			}
+		},
+
+		consume(ref: TransactionRef): Promise<FinalizeResult> {
+			return consumeAttempt(ref.transactionId);
+		},
+
+		unfinalized(): UnfinalizedSummary[] {
+			return pendingFinalizations(deps.snapshot()).map(p => ({
+				productKey: p.productKey,
+				transactionId: p.transactionId,
+				attempts: p.attempts,
+				purchasedAt: p.purchasedAt,
+			}));
+		},
+
+		dispose(): void {
+			for (const timer of timers.values()) {
+				clearTimeoutFn(timer);
+			}
+			timers.clear();
+			inFlight.clear();
+		},
+	};
+}