@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/entitlements/aggregate.ts

@@ -1,242 +1,261 @@
-/**
- * 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.
- */
-/**
- * How far the snapshot can be trusted right now.
- *
- * Shared by entitlements and the pending set (FR-103) so the two can never
- * disagree about whether the package knows anything — a paywall that showed
- * "not entitled" next to "nothing pending" from one stale snapshot would offer
- * Buy to a user whose payment is in flight.
- */
-export function snapshotCertainty(input: {
-	config: Pick<ResolvedConfig, 'staleAfterMs'>;
-	snapshot: Pick<PersistedSnapshot, 'lastSyncedAt'>;
-	hasSynced: boolean;
-	now: number;
-}): { isStale: boolean; undetermined: boolean } {
-	const { config, snapshot, hasSynced, now } = input;
-	const isStale =
-		snapshot.lastSyncedAt !== undefined &&
-		now - snapshot.lastSyncedAt > config.staleAfterMs;
-
-	// Both roads lead to `unknown`, never to a confident "no". Never having synced
-	// and having synced too long ago are the same epistemic state: we cannot
-	// currently support a claim either way.
-	return { isStale, undetermined: !hasSynced || isStale };
-}
-
-export function aggregate(input: AggregateInput): EntitlementMap {
-	const { config, snapshot } = input;
-	const { isStale, undetermined } = snapshotCertainty(input);
-
-	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;
-}
+/**
+ * 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 { shallowEqual } from '@chipmobilesdk/rn-core';
+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.
+ */
+/**
+ * How far the snapshot can be trusted right now.
+ *
+ * Shared by entitlements and the pending set (FR-103) so the two can never
+ * disagree about whether the package knows anything — a paywall that showed
+ * "not entitled" next to "nothing pending" from one stale snapshot would offer
+ * Buy to a user whose payment is in flight.
+ */
+export function snapshotCertainty(input: {
+	config: Pick<ResolvedConfig, 'staleAfterMs'>;
+	snapshot: Pick<PersistedSnapshot, 'lastSyncedAt'>;
+	hasSynced: boolean;
+	now: number;
+}): { isStale: boolean; undetermined: boolean } {
+	const { config, snapshot, hasSynced, now } = input;
+	const isStale =
+		snapshot.lastSyncedAt !== undefined && now - snapshot.lastSyncedAt > config.staleAfterMs;
+
+	// Both roads lead to `unknown`, never to a confident "no". Never having synced
+	// and having synced too long ago are the same epistemic state: we cannot
+	// currently support a claim either way.
+	return { isStale, undetermined: !hasSynced || isStale };
+}
+
+export function aggregate(input: AggregateInput): EntitlementMap {
+	const { config, snapshot } = input;
+	const { isStale, undetermined } = snapshotCertainty(input);
+
+	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;
+}
+
+function sameEntitlement(a: EntitlementState, b: EntitlementState): boolean {
+	return (
+		a.status === b.status &&
+		a.isStale === b.isStale &&
+		a.lastSyncedAt === b.lastSyncedAt &&
+		a.sources.length === b.sources.length &&
+		a.sources.every((source, index) => source === b.sources[index]) &&
+		shallowEqual(a.subscription, b.subscription)
+	);
+}
+
+/**
+ * `next`, with every entitlement that did not change replaced by the object it
+ * replaces, and `previous` itself when nothing changed (PERF-03, PAY-08). A hook
+ * selecting one entitlement then sees the same object and does not re-render.
+ */
+export function shareUnchanged(previous: EntitlementMap, next: EntitlementMap): EntitlementMap {
+	const keys = Object.keys(next);
+	let changed = keys.length !== Object.keys(previous).length;
+	const shared: EntitlementMap = {};
+	for (const key of keys) {
+		const before = previous[key];
+		const after = next[key]!;
+		if (before && sameEntitlement(before, after)) {
+			shared[key] = before;
+		} else {
+			shared[key] = after;
+			changed = true;
+		}
+	}
+	return changed ? shared : previous;
+}

package/src/entitlements/mapping.ts

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