@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/config/validate.ts

@@ -0,0 +1,232 @@
+/**
+ * Catalog validation (FR-011).
+ *
+ * Runs at `configure`, before any connection is opened, so a bad catalog fails
+ * at configuration time rather than at the moment a user taps Buy. Every failure
+ * **names the offending entry** — "invalid catalog" alone is useless in an app
+ * with thirty products.
+ *
+ * All problems are collected rather than thrown one at a time, so a developer
+ * fixes the catalog in one pass instead of rerunning to find the next fault.
+ */
+
+import { PaymentConfigError } from '../diagnostics/errors';
+import {
+	resolveForegroundSyncMinIntervalMs,
+	resolveProductCacheTtlMs,
+	resolveRetry,
+	resolveStaleAfterMs,
+	resolveTimeouts,
+	type ResolvedRetry,
+	type ResolvedTimeouts,
+} from '../core/timers';
+import type {
+	CatalogEntry,
+	EntitlementKey,
+	LapsePolicy,
+	PaymentConfig,
+	ProductKey,
+	ProductType,
+	ValidationUnavailablePolicy,
+} from './types';
+
+const PRODUCT_TYPES: readonly ProductType[] = [
+	'one_time_permanent',
+	'one_time_consumable',
+	'subscription',
+];
+
+/** The platform whose store identifiers a catalog must supply. */
+export type TargetPlatform = 'android' | 'ios';
+
+/**
+ * A validated, indexed catalog plus every resolved policy value.
+ *
+ * Produced once so the hot paths never re-derive it, and so `getEntitlement` can
+ * stay a synchronous in-memory read (PERF-001).
+ */
+export interface ResolvedConfig {
+	readonly entries: ReadonlyMap<ProductKey, CatalogEntry>;
+	/** productKey → entitlement keys it grants. */
+	readonly grants: ReadonlyMap<ProductKey, readonly EntitlementKey[]>;
+	/** entitlementKey → product keys that can grant it (FR-051, FR-052). */
+	readonly sources: ReadonlyMap<EntitlementKey, readonly ProductKey[]>;
+	/** storeProductId → productKey, for translating store callbacks back (FR-003). */
+	readonly byStoreId: ReadonlyMap<string, ProductKey>;
+	readonly entitlementKeys: readonly EntitlementKey[];
+	readonly platform: TargetPlatform;
+	readonly enabled: boolean;
+	readonly gracePolicy: LapsePolicy;
+	readonly holdPolicy: LapsePolicy;
+	readonly staleAfterMs: number;
+	readonly productCacheTtlMs: number;
+	readonly foregroundSyncMinIntervalMs: number;
+	readonly timeouts: ResolvedTimeouts;
+	readonly retry: ResolvedRetry;
+	readonly onValidationUnavailable: ValidationUnavailablePolicy;
+}
+
+export function validateConfig(
+	config: PaymentConfig,
+	platform: TargetPlatform = 'android',
+): ResolvedConfig {
+	const problems: string[] = [];
+	const offenders: string[] = [];
+
+	const entries = new Map<ProductKey, CatalogEntry>();
+	const grants = new Map<ProductKey, readonly EntitlementKey[]>();
+	const sources = new Map<EntitlementKey, ProductKey[]>();
+	const byStoreId = new Map<string, ProductKey>();
+
+	if (config.catalog.length === 0) {
+		problems.push('catalog is empty');
+		offenders.push('catalog');
+	}
+
+	for (const entry of config.catalog) {
+		const key = entry.productKey;
+
+		if (!key || key.trim() === '') {
+			problems.push('a catalog entry has an empty productKey');
+			offenders.push('(empty productKey)');
+			continue;
+		}
+
+		if (entries.has(key)) {
+			problems.push(`duplicate productKey "${key}"`);
+			offenders.push(key);
+			continue;
+		}
+
+		if (!PRODUCT_TYPES.includes(entry.productType)) {
+			problems.push(
+				`productKey "${key}" has invalid productType "${String(entry.productType)}"`,
+			);
+			offenders.push(key);
+		}
+
+		const storeId = entry.storeProductIds[platform];
+		if (!storeId || storeId.trim() === '') {
+			problems.push(
+				`productKey "${key}" is missing a store product id for platform "${platform}"`,
+			);
+			offenders.push(key);
+		} else {
+			const existing = byStoreId.get(storeId);
+			if (existing !== undefined) {
+				// Two product keys pointing at one store id would make a store callback
+				// ambiguous, so the wrong entitlement could be granted.
+				problems.push(
+					`store product id "${storeId}" is used by both "${existing}" and "${key}"`,
+				);
+				offenders.push(key);
+			} else {
+				byStoreId.set(storeId, key);
+			}
+		}
+
+		if (!Array.isArray(entry.grants) || entry.grants.length === 0) {
+			problems.push(`productKey "${key}" grants no entitlement`);
+			offenders.push(key);
+		}
+
+		entries.set(key, entry);
+		grants.set(key, [...(entry.grants ?? [])]);
+
+		for (const entitlement of entry.grants ?? []) {
+			const list = sources.get(entitlement);
+			if (list) {
+				list.push(key);
+			} else {
+				sources.set(entitlement, [key]);
+			}
+		}
+	}
+
+	// An entitlement the app intends to query but no product can grant is almost
+	// always a typo, and it would otherwise sit at `not_entitled` forever with no
+	// indication why.
+	for (const entitlement of config.entitlements) {
+		if (!sources.has(entitlement)) {
+			problems.push(
+				`entitlement "${entitlement}" is declared but no catalog product grants it`,
+			);
+			offenders.push(entitlement);
+		}
+	}
+
+	// A product granting something the app never declared is the mirror problem:
+	// harmless at runtime, but a strong signal of a rename half-applied.
+	const declared = new Set(config.entitlements);
+	for (const entitlement of sources.keys()) {
+		if (!declared.has(entitlement)) {
+			problems.push(
+				`entitlement "${entitlement}" is granted by a product but not declared in config.entitlements`,
+			);
+			offenders.push(entitlement);
+		}
+	}
+
+	if (problems.length > 0) {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CATALOG',
+			message: `Payment catalog is invalid: ${problems.join('; ')}`,
+			operation: 'configure',
+			offenders: [...new Set(offenders)],
+		});
+	}
+
+	return {
+		entries,
+		grants,
+		sources: new Map([...sources].map(([k, v]) => [k, [...v]])),
+		byStoreId,
+		entitlementKeys: [...config.entitlements],
+		platform,
+		enabled: config.enabled ?? true,
+		gracePolicy: config.gracePolicy ?? 'grant',
+		holdPolicy: config.holdPolicy ?? 'withhold',
+		staleAfterMs: resolveStaleAfterMs(config.staleAfterMs),
+		productCacheTtlMs: resolveProductCacheTtlMs(config.productCacheTtlMs),
+		foregroundSyncMinIntervalMs: resolveForegroundSyncMinIntervalMs(
+			config.foregroundSyncMinIntervalMs,
+		),
+		timeouts: resolveTimeouts(config.timeouts),
+		retry: resolveRetry(config.retry),
+		onValidationUnavailable: config.onValidationUnavailable ?? 'grant_and_queue',
+	};
+}
+
+/**
+ * The fail-closed environment guard (FR-015).
+ *
+ * Separate from catalog validation because it is not about the catalog's shape
+ * but about whether this binary is allowed to move real money at all. Checked
+ * before connecting, and it refuses rather than warns: a non-production build
+ * that declares `production` is one tap away from charging a real card, and
+ * continuing silently is exactly the failure this package exists to prevent.
+ */
+export function assertEnvironmentSafe(config: PaymentConfig): void {
+	if (config.environment === 'production' && !config.isProductionBuild) {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
+			message:
+				'environment is "production" but isProductionBuild is false. Refusing to ' +
+				'initialize: a non-production build must not be able to create a real ' +
+				'transaction.',
+			operation: 'configure',
+			offenders: ['environment'],
+		});
+	}
+}
+
+/**
+ * Whether this configuration may hand a real purchase to a real store (FR-014).
+ *
+ * False outside production regardless of what else is configured. The engine
+ * records each refusal in observable status so a test can assert the block
+ * happened — the difference between a guarantee and a hope.
+ */
+export function mayCreateRealTransaction(config: PaymentConfig): boolean {
+	return config.environment === 'production' && config.isProductionBuild;
+}

package/src/core/mutex.ts

@@ -0,0 +1,128 @@
+/**
+ * Concurrency primitives.
+ *
+ * These are what make three of the specification's guarantees structurally true
+ * rather than hoped for: concurrent initialization opens exactly one connection
+ * (FR-018), concurrent syncs make exactly one store request (FR-063), and a
+ * second purchase while one is open is refused rather than queued (FR-031).
+ *
+ * The distinction between the two primitives matters. `singleFlight` **joins**
+ * concurrent callers onto one operation — correct for init and sync, where every
+ * caller wants the same answer. `exclusive` **refuses** the second caller —
+ * correct for purchase, where joining would silently give two callers one
+ * transaction, and queueing would open a store surface the user no longer
+ * expects.
+ */
+
+/**
+ * Joins concurrent callers onto one in-flight operation.
+ *
+ * Callers arriving during the flight receive the same promise. Once it settles
+ * the slot clears, so a later call starts fresh — this is de-duplication, not
+ * caching.
+ */
+export function createSingleFlight<T>(): {
+	run(operation: () => Promise<T>): Promise<T>;
+	inFlight(): boolean;
+} {
+	let current: Promise<T> | undefined;
+
+	return {
+		run(operation: () => Promise<T>): Promise<T> {
+			if (current) {
+				return current;
+			}
+			const flight = operation().finally(() => {
+				if (current === flight) {
+					current = undefined;
+				}
+			});
+			current = flight;
+			return flight;
+		},
+		inFlight: () => current !== undefined,
+	};
+}
+
+/** Distinguishes "refused because busy" from any other failure, without throwing. */
+export type ExclusiveOutcome<T> =
+	| { acquired: true; value: T }
+	| { acquired: false };
+
+/**
+ * Admits one operation at a time and refuses the rest.
+ *
+ * Refusal is returned, not thrown, because for a purchase it is a normal
+ * outcome the app reports to the user — not an error to be caught.
+ */
+export function createExclusive(): {
+	run<T>(operation: () => Promise<T>): Promise<ExclusiveOutcome<T>>;
+	busy(): boolean;
+} {
+	let held = false;
+
+	return {
+		async run<T>(operation: () => Promise<T>): Promise<ExclusiveOutcome<T>> {
+			if (held) {
+				return { acquired: false };
+			}
+			held = true;
+			try {
+				return { acquired: true, value: await operation() };
+			} finally {
+				held = false;
+			}
+		},
+		busy: () => held,
+	};
+}
+
+/**
+ * Rate limiter for automatic foreground sync (PERF-002).
+ *
+ * Rejects rather than defers: a skipped automatic sync costs nothing because the
+ * next foreground event will try again, whereas a queue of deferred syncs would
+ * fire a burst the moment the interval elapsed — the exact storm this prevents.
+ */
+export function createRateLimiter(
+	minIntervalMs: number,
+	now: () => number = Date.now,
+): { tryAcquire(): boolean; reset(): void } {
+	let lastAt: number | undefined;
+
+	return {
+		tryAcquire(): boolean {
+			const at = now();
+			if (lastAt !== undefined && at - lastAt < minIntervalMs) {
+				return false;
+			}
+			lastAt = at;
+			return true;
+		},
+		reset(): void {
+			lastAt = undefined;
+		},
+	};
+}
+
+/**
+ * Rejects with a `PAYMENT_TIMEOUT`-shaped error after `ms`.
+ *
+ * Always clears its timer, including on the success path: a package that leaks a
+ * timer per operation fails the cleanup guarantee (FR-082, PERF-002).
+ */
+export function withTimeout<T>(
+	promise: Promise<T>,
+	ms: number,
+	onTimeout: () => Error,
+): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(onTimeout()), ms);
+	});
+	return Promise.race([promise, timeout]).finally(() => {
+		if (timer !== undefined) {
+			clearTimeout(timer);
+		}
+	}) as Promise<T>;
+}

package/src/core/retry.ts

@@ -0,0 +1,133 @@
+/**
+ * Bounded backoff.
+ *
+ * "Bounded" is the whole point (FR-020, FR-045): an unbounded reconnect loop
+ * against a billing service that is down drains battery and hammers a system
+ * service, and an unbounded finalize loop hides a real failure behind noise.
+ *
+ * Delay computation is pure and separated from waiting so tests can assert the
+ * schedule without burning real time.
+ */
+
+import type { BackoffConfig } from '../config/types';
+
+/** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
+type TimerHandle = ReturnType<typeof setTimeout> | number;
+
+/**
+ * Delay before `attempt` (1-based), capped and optionally jittered.
+ *
+ * Jitter is full jitter over [0, capped]: several devices that lost the billing
+ * connection at the same moment should not retry in lockstep.
+ */
+export function backoffDelayMs(
+	attempt: number,
+	config: Required<BackoffConfig>,
+	random: () => number = Math.random,
+): number {
+	const raw = config.initialDelayMs * Math.pow(config.factor, attempt - 1);
+	const capped = Math.min(raw, config.maxDelayMs);
+	return config.jitter ? Math.floor(capped * random()) : capped;
+}
+
+/** The full schedule, for asserting a retry policy without waiting for it. */
+export function backoffSchedule(config: Required<BackoffConfig>): number[] {
+	const delays: number[] = [];
+	for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
+		delays.push(backoffDelayMs(attempt, config, () => 1));
+	}
+	return delays;
+}
+
+export interface RetryHandle {
+	/** Cancels any pending attempt. Idempotent, so cleanup can call it freely (FR-082). */
+	cancel(): void;
+	/** Attempts consumed so far, so a retry storm is observable rather than inferred. */
+	attempts(): number;
+	/** True once the per-session budget is spent. */
+	exhausted(): boolean;
+}
+
+export interface RetryRunnerOptions {
+	config: Required<BackoffConfig>;
+	/** Return true when the attempt succeeded and retrying should stop. */
+	attempt: (attemptNumber: number) => Promise<boolean>;
+	/** Called once the per-session budget is spent without success. */
+	onExhausted?: (attempts: number) => void;
+	/**
+	 * Injected so a test can run the whole schedule synchronously instead of
+	 * waiting minutes of real backoff. The handle is opaque, because a Node
+	 * `Timeout` and a browser numeric id are both valid here.
+	 */
+	setTimeoutFn?: (fn: () => void, ms: number) => TimerHandle;
+	clearTimeoutFn?: (handle: TimerHandle) => void;
+	random?: () => number;
+}
+
+/**
+ * Runs `attempt` under the bounded schedule.
+ *
+ * Exhaustion is reported rather than thrown: for finalization, a spent session
+ * budget is not a failure but a handoff to the next launch, and the caller is
+ * the only one that knows which of the two it is.
+ */
+export function runWithRetry(options: RetryRunnerOptions): RetryHandle {
+	const {
+		config,
+		attempt,
+		onExhausted,
+		setTimeoutFn = setTimeout,
+		clearTimeoutFn = clearTimeout,
+		random = Math.random,
+	} = options;
+
+	let attemptCount = 0;
+	let cancelled = false;
+	let pending: TimerHandle | undefined;
+
+	const schedule = (delayMs: number): void => {
+		pending = setTimeoutFn(() => {
+			pending = undefined;
+			run().catch(() => undefined);
+		}, delayMs);
+	};
+
+	const run = async (): Promise<void> => {
+		if (cancelled) {
+			return;
+		}
+		attemptCount += 1;
+		let succeeded = false;
+		try {
+			succeeded = await attempt(attemptCount);
+		} catch {
+			// A throwing attempt is a failed attempt, nothing more. Letting it escape
+			// would abandon the schedule and, for finalization, silently drop a paid
+			// transaction.
+			succeeded = false;
+		}
+		if (cancelled || succeeded) {
+			return;
+		}
+		if (attemptCount >= config.maxAttempts) {
+			onExhausted?.(attemptCount);
+			return;
+		}
+		schedule(backoffDelayMs(attemptCount + 1, config, random));
+	};
+
+	// Fire the first attempt immediately; the schedule owns everything after it.
+	run().catch(() => undefined);
+
+	return {
+		cancel(): void {
+			cancelled = true;
+			if (pending !== undefined) {
+				clearTimeoutFn(pending);
+				pending = undefined;
+			}
+		},
+		attempts: () => attemptCount,
+		exhausted: () => attemptCount >= config.maxAttempts,
+	};
+}