@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/config/validate.ts

@@ -1,232 +1,224 @@
-/**
- * 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;
-}
+/**
+ * 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

@@ -1,128 +1,25 @@
-/**
- * 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>;
-}
+/**
+ * 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.
+ */
+
+// The primitives themselves are rn-core's; the reasoning above is why rn-payment
+// uses each where it does.
+export {
+	createExclusive,
+	createRateLimiter,
+	createSingleFlight,
+	withTimeout,
+	type ExclusiveOutcome,
+} from '@chipmobilesdk/rn-core';