@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/src/entitlements/aggregate.ts

@@ -0,0 +1,225 @@
+/**
+ * Entitlement aggregation — the package's primary output.
+ *
+ * Everything else exists to make this one answer correct. The most damaging
+ * defect class in a payment SDK lives here: collapsing "not yet synced" into "not
+ * entitled" makes a paying user watch ads flash on cold start or see a purchased
+ * feature sit locked.
+ *
+ * Two rules do most of the work:
+ *
+ * - **A pending purchase is never a source** (FR-037). Enforced here, in
+ *   aggregation, rather than at each call site, so no future code path can grant
+ *   on money that has not arrived.
+ * - **Uncertainty resolves to `unknown`, never `not_entitled`** (FR-047,
+ *   FR-055a). Never synced, stale, or scope-changed all mean "we do not know",
+ *   and the package says so rather than asserting the user did not pay.
+ */
+
+import type { ResolvedConfig } from '../config/validate';
+import type { EntitlementKey, ProductKey } from '../config/types';
+import type { PersistedPurchase, PersistedSnapshot } from '../persistence/snapshot';
+import { entitlementsFor } from './mapping';
+import {
+	deriveRenewalState,
+	grantsUnderPolicy,
+	hasExpired,
+	type RenewalState,
+} from './policy';
+
+export type EntitlementStatus = 'unknown' | 'entitled' | 'not_entitled';
+
+export interface SubscriptionDetail {
+	expiresAt?: number;
+	willAutoRenew: boolean;
+	isCancelledButValid: boolean;
+	renewalState: RenewalState;
+}
+
+export interface EntitlementState {
+	key: EntitlementKey;
+	status: EntitlementStatus;
+	/** The app's own product keys currently granting this. Never raw transactions (FR-051). */
+	sources: ProductKey[];
+	subscription?: SubscriptionDetail;
+	lastSyncedAt?: number;
+	/** True once the snapshot is older than `staleAfterMs`; status is then `unknown`. */
+	isStale: boolean;
+}
+
+export type EntitlementMap = Record<EntitlementKey, EntitlementState>;
+
+export interface AggregateInput {
+	config: ResolvedConfig;
+	snapshot: PersistedSnapshot;
+	/** False until the first successful sync of this session or a hydrated one. */
+	hasSynced: boolean;
+	reportsGraceAndHoldDistinctly: boolean;
+	now: number;
+}
+
+/** A purchase that currently confers its entitlements. */
+function isValidSource(
+	purchase: PersistedPurchase,
+	input: AggregateInput,
+): boolean {
+	// Pending money is not money. No configuration and no code path may grant here.
+	if (purchase.state === 'pending') {
+		return false;
+	}
+	if (purchase.state === 'revoked' || purchase.state === 'consumed') {
+		return false;
+	}
+	// A backend that said no is final (FR-071). A queued re-validation still
+	// grants, which is the documented `grant_and_queue` fallback (FR-072).
+	if (purchase.validationState === 'rejected') {
+		return false;
+	}
+
+	if (purchase.productType === 'subscription') {
+		if (hasExpired(purchase.expiresAt, input.now)) {
+			return false;
+		}
+		const renewalState = deriveRenewalState({
+			expiresAt: purchase.expiresAt,
+			willAutoRenew: purchase.willAutoRenew,
+			reportsGraceAndHoldDistinctly: input.reportsGraceAndHoldDistinctly,
+		});
+		return grantsUnderPolicy(renewalState, {
+			gracePolicy: input.config.gracePolicy,
+			holdPolicy: input.config.holdPolicy,
+		});
+	}
+
+	// A consumable that has not been consumed yet is owned, but it must never
+	// become a permanent entitlement — consumption flips it to `consumed` above.
+	return true;
+}
+
+function subscriptionDetailFor(
+	purchases: PersistedPurchase[],
+	input: AggregateInput,
+): SubscriptionDetail | undefined {
+	const subs = purchases.filter(p => p.productType === 'subscription');
+	if (subs.length === 0) {
+		return undefined;
+	}
+
+	// Where several subscriptions grant one entitlement, the one running longest
+	// is what the user experiences, so report that one.
+	const furthest = subs.reduce((best, candidate) => {
+		const bestAt = best.expiresAt ?? Number.MAX_SAFE_INTEGER;
+		const candidateAt = candidate.expiresAt ?? Number.MAX_SAFE_INTEGER;
+		return candidateAt > bestAt ? candidate : best;
+	});
+
+	const renewalState = deriveRenewalState({
+		expiresAt: furthest.expiresAt,
+		willAutoRenew: furthest.willAutoRenew,
+		reportsGraceAndHoldDistinctly: input.reportsGraceAndHoldDistinctly,
+	});
+
+	return {
+		expiresAt: furthest.expiresAt,
+		willAutoRenew: furthest.willAutoRenew === true,
+		isCancelledButValid: renewalState === 'cancelled_valid',
+		renewalState,
+	};
+}
+
+/**
+ * Computes the full entitlement map.
+ *
+ * Pure and synchronous by design: it runs on render paths, so it must never
+ * touch I/O (PERF-001). The engine calls it after any state change and caches the
+ * result.
+ */
+export function aggregate(input: AggregateInput): EntitlementMap {
+	const { config, snapshot, hasSynced, now } = input;
+
+	const isStale =
+		snapshot.lastSyncedAt !== undefined &&
+		now - snapshot.lastSyncedAt > config.staleAfterMs;
+
+	// Both roads lead to `unknown`, never to `not_entitled`. Never having synced
+	// and having synced too long ago are the same epistemic state: we cannot
+	// currently support a claim either way.
+	const undetermined = !hasSynced || isStale;
+
+	const valid = snapshot.purchases.filter(p => isValidSource(p, input));
+
+	const result: EntitlementMap = {};
+	for (const key of config.entitlementKeys) {
+		const granting = valid.filter(p =>
+			entitlementsFor(config, p.productKey).includes(key),
+		);
+		const sources = [...new Set(granting.map(p => p.productKey))];
+
+		result[key] = {
+			key,
+			// An entitlement stays valid while at least one source remains (FR-052).
+			status: undetermined
+				? 'unknown'
+				: sources.length > 0
+					? 'entitled'
+					: 'not_entitled',
+			sources,
+			subscription: subscriptionDetailFor(granting, input),
+			lastSyncedAt: snapshot.lastSyncedAt,
+			isStale,
+		};
+	}
+
+	return result;
+}
+
+/** The initial map, before anything is known. Every key starts at `unknown` (FR-047). */
+export function initialEntitlements(config: ResolvedConfig): EntitlementMap {
+	const result: EntitlementMap = {};
+	for (const key of config.entitlementKeys) {
+		result[key] = {
+			key,
+			status: 'unknown',
+			sources: [],
+			lastSyncedAt: undefined,
+			isStale: false,
+		};
+	}
+	return result;
+}
+
+export interface EntitlementChange {
+	key: EntitlementKey;
+	previous: EntitlementStatus;
+	next: EntitlementStatus;
+	sources: ProductKey[];
+}
+
+/**
+ * Diffs two maps to produce change signals.
+ *
+ * Emitting from a diff rather than from grant call sites is what makes the
+ * exactly-once guarantees structural (FR-079): a successful subscription renewal
+ * changes no status, so it produces no event and cannot double-signal (FR-068);
+ * and an entitlement with three sources fires once on transition, not once per
+ * source.
+ */
+export function diffEntitlements(
+	previous: EntitlementMap,
+	next: EntitlementMap,
+): EntitlementChange[] {
+	const changes: EntitlementChange[] = [];
+	for (const key of Object.keys(next)) {
+		const before = previous[key]?.status ?? 'unknown';
+		const after = next[key].status;
+		if (before !== after) {
+			changes.push({
+				key,
+				previous: before,
+				next: after,
+				sources: next[key].sources,
+			});
+		}
+	}
+	return changes;
+}

package/src/entitlements/mapping.ts

@@ -0,0 +1,67 @@
+/**
+ * Product ↔ entitlement indexing.
+ *
+ * The relation is many-to-many (FR-010): monthly, yearly, and lifetime products
+ * may all grant `no_ads`, and one bundle product may grant several entitlements.
+ *
+ * Both directions are indexed once at configure time. The reverse direction is
+ * what makes two requirements cheap on hot paths: naming which product currently
+ * grants an entitlement (FR-051), and keeping an entitlement valid while *any*
+ * source remains (FR-052).
+ */
+
+import type { ResolvedConfig } from '../config/validate';
+import type { EntitlementKey, ProductKey } from '../config/types';
+
+/** Entitlements a product confers. Empty for an unknown key rather than throwing. */
+export function entitlementsFor(
+	config: ResolvedConfig,
+	productKey: ProductKey,
+): readonly EntitlementKey[] {
+	return config.grants.get(productKey) ?? [];
+}
+
+/** Products that could grant an entitlement, whether or not any is currently valid. */
+export function sourcesFor(
+	config: ResolvedConfig,
+	entitlementKey: EntitlementKey,
+): readonly ProductKey[] {
+	return config.sources.get(entitlementKey) ?? [];
+}
+
+/**
+ * Translates a store product id back to the app's own product key.
+ *
+ * Needed because store callbacks and `queryOwned` speak in store ids, while
+ * everything above the adapter speaks in product keys (FR-003). Returns
+ * `undefined` for an id absent from the catalog — which happens legitimately when
+ * a user owns something from a build whose catalog has since changed, so it must
+ * be handled rather than treated as impossible.
+ */
+export function productKeyForStoreId(
+	config: ResolvedConfig,
+	storeProductId: string,
+): ProductKey | undefined {
+	return config.byStoreId.get(storeProductId);
+}
+
+export function storeIdForProductKey(
+	config: ResolvedConfig,
+	productKey: ProductKey,
+): string | undefined {
+	return config.entries.get(productKey)?.storeProductIds[config.platform];
+}
+
+/** Which entitlements a set of granting products covers, de-duplicated. */
+export function entitlementsCoveredBy(
+	config: ResolvedConfig,
+	productKeys: Iterable<ProductKey>,
+): Set<EntitlementKey> {
+	const covered = new Set<EntitlementKey>();
+	for (const productKey of productKeys) {
+		for (const entitlement of entitlementsFor(config, productKey)) {
+			covered.add(entitlement);
+		}
+	}
+	return covered;
+}

package/src/entitlements/policy.ts

@@ -0,0 +1,129 @@
+/**
+ * Grace and hold entitlement policy.
+ *
+ * This is a **business decision, not a technical constant** (FR-049), so it is
+ * configurable with documented defaults.
+ *
+ * ## The defaults, and why
+ *
+ * `gracePolicy: 'grant'` — a grace period means the store is still retrying a
+ * payment method that failed for reasons usually outside the user's control: an
+ * expired card, a bank decline, a temporary hold. Revoking immediately punishes a
+ * paying customer for a billing hiccup they may not know about yet.
+ *
+ * `holdPolicy: 'withhold'` — account hold means the store has given up retrying.
+ * The subscription is effectively unpaid, and continuing to serve paid features
+ * indefinitely is giving away the product.
+ *
+ * ## What Android can actually tell us
+ *
+ * Client-side Play Billing **cannot** separate grace from hold: a grace-period
+ * subscription is still returned as active, and one in account hold stops being
+ * returned at all — indistinguishable from expired, cancelled, or refunded.
+ *
+ * Fortunately the platform's own behavior matches the defaults above. Play keeps
+ * returning a grace-period purchase, so the entitlement holds. Play stops
+ * returning a held one, so it lapses at the next sync. **The default policy is
+ * therefore correct with no backend at all.**
+ *
+ * What is *not* achievable client-side is a non-default policy — withholding
+ * during grace, or granting during hold — because that needs the state the client
+ * cannot see. Such an app supplies it through the validation hook (FR-069). This
+ * limitation is documented rather than papered over (FR-058).
+ */
+
+import type { LapsePolicy } from '../config/types';
+
+/**
+ * A subscription's renewal state as far as the package can honestly tell.
+ *
+ * `indeterminate` is not a failure — it is the truthful answer when the platform
+ * reports a subscription as active but cannot say whether that is a healthy
+ * renewal, a cancelled-but-still-paid period, or a grace period.
+ */
+export type RenewalState =
+	| 'active'
+	| 'cancelled_valid'
+	| 'grace'
+	| 'hold'
+	| 'indeterminate';
+
+export interface LapsePolicyConfig {
+	gracePolicy: LapsePolicy;
+	holdPolicy: LapsePolicy;
+}
+
+export interface SubscriptionFacts {
+	expiresAt?: number;
+	willAutoRenew?: boolean;
+	/** True only where the provider genuinely distinguishes grace/hold. */
+	reportsGraceAndHoldDistinctly: boolean;
+	/** Provider-reported, only meaningful when the flag above is true. */
+	providerRenewalState?: 'active' | 'grace' | 'hold';
+}
+
+/**
+ * Derives the renewal state without inventing information.
+ *
+ * The temptation is to read `willAutoRenew === false` as "grace period", but that
+ * same value is what a deliberate cancellation looks like. Guessing would mean
+ * showing "there's a problem with your payment method" to someone who simply
+ * chose not to renew — so when the provider cannot distinguish, neither do we.
+ */
+export function deriveRenewalState(facts: SubscriptionFacts): RenewalState {
+	if (facts.reportsGraceAndHoldDistinctly && facts.providerRenewalState) {
+		switch (facts.providerRenewalState) {
+			case 'grace':
+				return 'grace';
+			case 'hold':
+				return 'hold';
+			case 'active':
+				return facts.willAutoRenew === false ? 'cancelled_valid' : 'active';
+		}
+	}
+
+	if (facts.willAutoRenew === false) {
+		// Still inside a paid period with auto-renew off. Genuinely ambiguous
+		// between "cancelled" and "in grace", so report the one that is certainly
+		// true — the period is paid for — and let the app decide how to present it.
+		return 'cancelled_valid';
+	}
+
+	if (facts.willAutoRenew === true) {
+		return 'active';
+	}
+
+	return 'indeterminate';
+}
+
+/**
+ * Whether a subscription in this state should confer its entitlement.
+ *
+ * `hold` reaching this function at all requires a provider that reports it,
+ * which Android does not. On Android a held subscription simply stops being
+ * returned, so it never becomes a source and the entitlement lapses — the same
+ * result the `withhold` default expresses.
+ */
+export function grantsUnderPolicy(
+	state: RenewalState,
+	policy: LapsePolicyConfig,
+): boolean {
+	switch (state) {
+		case 'active':
+		case 'cancelled_valid':
+			return true;
+		case 'grace':
+			return policy.gracePolicy === 'grant';
+		case 'hold':
+			return policy.holdPolicy === 'grant';
+		case 'indeterminate':
+			// The store is still reporting the purchase as owned. Withholding here
+			// would revoke from a paying user because of our own uncertainty.
+			return true;
+	}
+}
+
+/** True once a subscription's paid period has genuinely elapsed (FR-048). */
+export function hasExpired(expiresAt: number | undefined, now: number): boolean {
+	return expiresAt !== undefined && expiresAt <= now;
+}

package/src/index.ts

@@ -0,0 +1,168 @@
+/**
+ * `@chipmobilesdk/rn-payment` — reusable in-app payment and entitlement
+ * capability for ChipMobileSdk-family React Native apps.
+ *
+ * This is the public entrypoint (LIB-003). Modules under `config/`, `core/`,
+ * `engine/`, `entitlements/`, `persistence/`, `adapter/`, `diagnostics/`, and
+ * `react/` are private; import them only through this file. The fake store lives
+ * behind `@chipmobilesdk/rn-payment/testing` so test doubles cannot reach a
+ * production bundle.
+ *
+ * Nothing exported here names Google, Play Billing, or `react-native-iap`
+ * (FR-002). `src/__tests__/public-api.test.ts` asserts that mechanically.
+ *
+ * The package owns **capability**: a safe, consistent way to sell, finalize,
+ * restore, and report entitlements. The consuming app owns **policy** — what is
+ * sold, at what price, on which screen, at which moment, what each entitlement
+ * unlocks, and how generous the grace policy is. There is no product identifier,
+ * no screen name, and no business rule in this package (FR-016).
+ *
+ * The one output that matters most is the **entitlement key**: an app-chosen key
+ * such as `no_ads`. Business logic asks about entitlement keys and never about
+ * store product identifiers, product types, or which store sold the thing.
+ */
+
+// --- Configuration and catalog ---------------------------------------------
+export type {
+	BackoffConfig,
+	BlockedOperation,
+	CatalogEntry,
+	EntitlementKey,
+	Environment,
+	FinalizeResult,
+	LapsePolicy,
+	LoggerAdapter,
+	PaymentConfig,
+	PaymentStatus,
+	PaymentStatusKind,
+	ProductKey,
+	ProductType,
+	PurchaseOptions,
+	PurchaseResult,
+	RetryConfig,
+	StoreProductIds,
+	TimeoutConfig,
+	TransactionRef,
+	UnavailableReason,
+	UnfinalizedSummary,
+	Unsubscribe,
+	ValidationCandidate,
+	ValidationDecision,
+	ValidationHook,
+	ValidationUnavailablePolicy,
+} from './config/types';
+
+// --- Policy defaults and bounds --------------------------------------------
+// Exported so a consumer can read the values it is bound by rather than
+// discovering them from a timeout in production.
+export {
+	BACKOFF_ATTEMPT_BOUNDS,
+	BACKOFF_MAX_DELAY_BOUNDS,
+	CONNECT_TIMEOUT_BOUNDS,
+	DEFAULT_CONNECT_TIMEOUT_MS,
+	DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS,
+	DEFAULT_FINALIZE_BACKOFF,
+	DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS,
+	DEFAULT_PRODUCT_CACHE_TTL_MS,
+	DEFAULT_PRODUCT_QUERY_TIMEOUT_MS,
+	DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS,
+	DEFAULT_RECONNECT_BACKOFF,
+	DEFAULT_STALE_AFTER_MS,
+	DEFAULT_SYNC_TIMEOUT_MS,
+	FINALIZE_ATTEMPT_TIMEOUT_BOUNDS,
+	FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS,
+	PRODUCT_CACHE_TTL_BOUNDS,
+	PRODUCT_QUERY_TIMEOUT_BOUNDS,
+	PURCHASE_LAUNCH_TIMEOUT_BOUNDS,
+	STALE_AFTER_BOUNDS,
+	SYNC_TIMEOUT_BOUNDS,
+} from './core/timers';
+
+// --- Products, pricing, and offers -----------------------------------------
+export type {
+	MissingProduct,
+	MissingProductReason,
+	Offer,
+	ProductInfo,
+	ProductQueryResult,
+} from './engine/products';
+
+// --- Subscriptions ---------------------------------------------------------
+export type {
+	PriceChangeResult,
+	ProrationMode,
+} from './engine/subscriptions';
+
+// --- Entitlements ----------------------------------------------------------
+export type {
+	EntitlementMap,
+	EntitlementState,
+	EntitlementStatus,
+	SubscriptionDetail,
+} from './entitlements/aggregate';
+export type { RenewalState } from './entitlements/policy';
+
+// --- Store provider --------------------------------------------------------
+// Named for the concept, not the store: the same call returns the StoreKit
+// adapter once iOS exists, so no consumer line changes (FR-004, FR-007). On a
+// platform with no adapter it returns a stub that reports `unavailable` rather
+// than throwing, so a host app still starts and runs (FR-021, FR-023).
+export { createStoreProvider } from './adapter/createStoreProvider';
+export type { StoreProviderOptions } from './adapter/createStoreProvider';
+
+// --- Engine ----------------------------------------------------------------
+export { createEngine } from './engine/engine';
+export type {
+	EngineDeps,
+	InitOutcome,
+	PaymentEngine,
+	RestoreOutcome,
+	SyncOutcome,
+} from './engine/engine';
+
+// --- React -----------------------------------------------------------------
+export { PaymentProvider, usePaymentEngine } from './react/PaymentProvider';
+export type { PaymentProviderProps } from './react/PaymentProvider';
+export {
+	useEntitlement,
+	useEntitlements,
+	usePaymentStatus,
+	useProducts,
+	usePurchase,
+	useSync,
+} from './react/hooks';
+export type {
+	UseProductsResult,
+	UsePurchaseResult,
+	UseSyncResult,
+} from './react/hooks';
+
+// --- Diagnostics -----------------------------------------------------------
+export { PaymentConfigError, PaymentError, PAYMENT_ERROR_CODES } from './diagnostics/errors';
+export type { PaymentErrorCode, PaymentOperation } from './diagnostics/errors';
+export type {
+	PaymentEvent,
+	PaymentEventListener,
+	PaymentEventType,
+	SyncTrigger,
+} from './diagnostics/events';
+
+// --- Localizable copy ------------------------------------------------------
+// Keys and English defaults only. The package takes no i18n dependency and
+// resolves nothing itself; apps map these through their own i18n (FR-085).
+export {
+	DEFAULT_DEVELOPER_MESSAGES,
+	DEFAULT_MESSAGES,
+	DEFAULT_USER_MESSAGES,
+	DEVELOPER_MESSAGE_KEYS,
+	USER_MESSAGE_KEYS,
+	isUserMessageKey,
+} from './diagnostics/messageKeys';
+export type {
+	PaymentDeveloperMessageKey,
+	PaymentDeveloperMessageMap,
+	PaymentMessageKey,
+	PaymentMessageMap,
+	PaymentUserMessageKey,
+	PaymentUserMessageMap,
+} from './diagnostics/messageKeys';