@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/src/config/types.ts

@@ -0,0 +1,255 @@
+/**
+ * Public configuration and catalog types.
+ *
+ * Nothing here names Google Play Billing, `react-native-iap`, or any store
+ * concept (FR-002). Apps speak in **product keys** and **entitlement keys** they
+ * chose themselves; store product identifiers appear only inside catalog
+ * configuration, never in app logic (FR-003).
+ */
+
+/** An app-chosen logical entitlement, e.g. `no_ads`. What business logic asks about. */
+export type EntitlementKey = string;
+
+/** An app-chosen logical product, e.g. `premium_yearly`. Never a store identifier. */
+export type ProductKey = string;
+
+/**
+ * How a product behaves once bought.
+ *
+ * `one_time_permanent` — bought once, kept forever.
+ * `one_time_consumable` — bought, used up by the app, buyable again (FR-043).
+ * `subscription` — recurring, with its own lifecycle (FR-048).
+ */
+export type ProductType =
+	| 'one_time_permanent'
+	| 'one_time_consumable'
+	| 'subscription';
+
+/** Store identifiers per platform. iOS is optional and additive (FR-007). */
+export interface StoreProductIds {
+	android?: string;
+	ios?: string;
+}
+
+/** One product the app sells, and what it unlocks. */
+export interface CatalogEntry {
+	productKey: ProductKey;
+	productType: ProductType;
+	storeProductIds: StoreProductIds;
+	/** Entitlement keys this product confers. Many-to-many is supported (FR-010). */
+	grants: EntitlementKey[];
+}
+
+/** Separately configurable, and the basis of the production-transaction guard. */
+export type Environment = 'development' | 'test' | 'production';
+
+/**
+ * Entitlement policy for a subscription whose renewal payment failed.
+ *
+ * Kept configurable because it is a business decision, not a technical constant
+ * (FR-049). See `entitlements/policy.ts` for the defaults and why.
+ */
+export type LapsePolicy = 'grant' | 'withhold';
+
+/** What to do when a configured validation hook cannot be reached (FR-072). */
+export type ValidationUnavailablePolicy = 'grant_and_queue' | 'withhold';
+
+/** Returned by every subscribe call. Idempotent and safe to call twice (FR-006). */
+export type Unsubscribe = () => void;
+
+export interface TimeoutConfig {
+	connectMs?: number;
+	productQueryMs?: number;
+	syncMs?: number;
+	/** Covers opening the store surface only. Time the user spends in it is not counted (FR-035). */
+	purchaseLaunchMs?: number;
+	finalizeAttemptMs?: number;
+}
+
+export interface RetryConfig {
+	reconnect?: BackoffConfig;
+	finalize?: BackoffConfig;
+}
+
+export interface BackoffConfig {
+	initialDelayMs?: number;
+	maxDelayMs?: number;
+	factor?: number;
+	/** Attempts per session. Finalize is resumed next session rather than abandoned (FR-045). */
+	maxAttempts?: number;
+	jitter?: boolean;
+}
+
+/** What the app's backend is asked to decide about (FR-069). */
+export interface ValidationCandidate {
+	productKey: ProductKey;
+	productType: ProductType;
+	/** Opaque verification material for the backend. Never logged (FR-074). */
+	verificationPayload: string;
+	/** Ties this decision to one purchase cycle in the event stream (FR-076). */
+	correlationId: string;
+}
+
+export interface ValidationDecision {
+	approved: boolean;
+	/** Optional app-supplied reason, surfaced as a distinguishable outcome (FR-071). */
+	reason?: string;
+}
+
+export type ValidationHook = (
+	candidate: ValidationCandidate,
+) => Promise<ValidationDecision>;
+
+/** Diagnostics sink. Deliberately not tied to any analytics vendor (FR-080). */
+export interface LoggerAdapter {
+	debug?(message: string, meta?: Record<string, unknown>): void;
+	warn?(message: string, meta?: Record<string, unknown>): void;
+	error?(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface PaymentConfig {
+	catalog: CatalogEntry[];
+	/** Entitlement keys the app intends to query. Used for orphan detection (FR-011). */
+	entitlements: EntitlementKey[];
+	environment: Environment;
+	/**
+	 * Whether the running binary is a production build.
+	 *
+	 * Supplied by the app because only the app knows how it was built. Drives the
+	 * fail-closed guard: a non-production build declaring `production` must not
+	 * proceed (FR-015).
+	 */
+	isProductionBuild: boolean;
+	/**
+	 * Global sell switch. When false, purchases report `disabled` but entitlements
+	 * already held stay readable — turning off selling is not the same as taking
+	 * away what someone bought (FR-012).
+	 */
+	enabled?: boolean;
+	gracePolicy?: LapsePolicy;
+	holdPolicy?: LapsePolicy;
+	staleAfterMs?: number;
+	productCacheTtlMs?: number;
+	foregroundSyncMinIntervalMs?: number;
+	timeouts?: TimeoutConfig;
+	retry?: RetryConfig;
+	/**
+	 * Opaque cache-partition key (FR-057a).
+	 *
+	 * Not a user identifier: the package never interprets it, transmits it, or
+	 * attaches it to a transaction. Changing it makes the previous snapshot
+	 * unreadable, so a second app-account user cannot inherit the first one's
+	 * entitlements even if the app forgets to call `clearLocalData`.
+	 */
+	scopeToken?: string;
+	validateTransaction?: ValidationHook;
+	onValidationUnavailable?: ValidationUnavailablePolicy;
+	logger?: LoggerAdapter;
+}
+
+/** Opaque handle for a transaction. Exposes no raw store record (FR-051). */
+export interface TransactionRef {
+	readonly transactionId: string;
+	readonly productKey: ProductKey;
+}
+
+export interface PurchaseOptions {
+	/**
+	 * The app's obfuscated account identifier, passed straight through to the
+	 * store for fraud prevention. Never generated, inferred, or persisted by the
+	 * package (FR-034), and distinct from `scopeToken`.
+	 */
+	obfuscatedAccountId?: string;
+	/** Which pricing option to buy, for a subscription with several offers. */
+	offerKey?: string;
+}
+
+/**
+ * Every way a purchase can end (FR-005).
+ *
+ * A discriminated union rather than a boolean plus an error, because the app has
+ * to tell these apart: `user_cancelled` is a normal outcome to stay quiet about,
+ * `pending` means wait, `already_owned` means re-sync, and `store_error` means
+ * show something. Collapsing them is how apps end up reporting a cancellation as
+ * a failure.
+ */
+export type PurchaseResult =
+	| { kind: 'success'; productKey: ProductKey; transaction: TransactionRef }
+	/** Money has not arrived. No entitlement is granted (FR-037). */
+	| { kind: 'pending'; productKey: ProductKey; transaction: TransactionRef }
+	/** Normal, not an error. Must never be recorded as a technical failure (FR-032). */
+	| { kind: 'user_cancelled'; productKey: ProductKey }
+	/** Triggers a re-sync: this is how a reinstall repairs itself (FR-033). */
+	| { kind: 'already_owned'; productKey: ProductKey }
+	| { kind: 'ineligible'; productKey: ProductKey }
+	| { kind: 'unknown_product'; productKey: ProductKey }
+	| { kind: 'product_unavailable_in_region'; productKey: ProductKey }
+	/** Global sell switch is off (FR-012). */
+	| { kind: 'disabled' }
+	| { kind: 'not_ready'; status: PaymentStatusKind }
+	| { kind: 'unsupported' }
+	/** A second purchase while one is open. Refused, never queued (FR-031). */
+	| { kind: 'purchase_in_progress' }
+	/** Refused because this build may not create a production transaction (FR-014). */
+	| { kind: 'environment_blocked'; productKey: ProductKey; environment: Environment }
+	/** The app's backend said no (FR-071). Distinguishable from a network failure. */
+	| { kind: 'validation_rejected'; productKey: ProductKey; reason?: string }
+	| { kind: 'timeout'; productKey: ProductKey }
+	| { kind: 'network_error'; productKey: ProductKey }
+	| { kind: 'store_error'; productKey: ProductKey; code: string };
+
+/** Outcome of finalizing or consuming a transaction (FR-044). */
+export type FinalizeResult =
+	| { kind: 'finalized' }
+	/** Already done. Idempotent by design, so this is a success, not an error. */
+	| { kind: 'already_finalized' }
+	| { kind: 'unknown_transaction' }
+	/** Queued for bounded retry; the condition stays observable (FR-045). */
+	| { kind: 'retry_scheduled'; attempts: number }
+	| { kind: 'failed'; code: string };
+
+/** A paid transaction not yet settled with the store, surfaced so it is not swallowed. */
+export interface UnfinalizedSummary {
+	productKey: ProductKey;
+	transactionId: string;
+	attempts: number;
+	purchasedAt: number;
+}
+
+/** Observable package status (FR-019). */
+export type PaymentStatusKind =
+	| 'not_started'
+	| 'connecting'
+	| 'ready'
+	| 'disabled'
+	| 'unavailable'
+	| 'failed';
+
+/** Why selling is impossible here, kept distinguishable so apps can tell users why (FR-021). */
+export type UnavailableReason =
+	| 'no_billing_service'
+	| 'billing_service_outdated'
+	| 'platform_unsupported';
+
+/**
+ * A purchase the package refused because it could have been a real charge
+ * outside production (FR-014).
+ *
+ * Exposed in status rather than only logged so an automated test can assert the
+ * block happened, which is the difference between a guarantee and a hope.
+ */
+export interface BlockedOperation {
+	productKey: ProductKey;
+	environment: Environment;
+	at: number;
+}
+
+export interface PaymentStatus {
+	kind: PaymentStatusKind;
+	unavailableReason?: UnavailableReason;
+	/** Whether retrying initialization could plausibly help (FR-024). */
+	retryable?: boolean;
+	/** Reconnect attempts made in this session, so a retry storm is visible (FR-020). */
+	reconnectAttempts?: number;
+	blockedOperations: BlockedOperation[];
+}

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>;
+}