@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/engine/subscriptions.ts

@@ -1,157 +1,146 @@
-/**
- * Subscription plan changes and the route to the store's management screen (US12).
- *
- * Two platform rules drive this module:
- *
- * - **Proration is the app's decision, inside what the store permits** (FR-065).
- *   Whether a user who upgrades gets charged immediately, keeps their remaining
- *   time, or starts a fresh period is a product and pricing choice, so the
- *   package forwards it rather than picking.
- * - **Cancellation belongs to the store.** Platforms forbid an app presenting its
- *   own cancellation screen, so this module offers only a route to the store's
- *   (FR-066) — there is deliberately no self-built alternative anywhere in the
- *   package.
- */
-
-import type {
-	ProductKey,
-	PurchaseOptions,
-	PurchaseResult,
-} from '../config/types';
-import type { ResolvedConfig } from '../config/validate';
-import type { ProviderPort } from '../adapter/port';
-import { storeIdForProductKey } from '../entitlements/mapping';
-import type { PersistedSnapshot } from '../persistence/snapshot';
-
-/**
- * How already-paid time is handled when a plan changes.
- *
- * Named for the user-visible effect rather than mirroring a store's enum, so the
- * same vocabulary will map onto StoreKit later (FR-004).
- */
-export type ProrationMode =
-	/** Switch now; credit unused time against the new plan. The usual upgrade. */
-	| 'immediate_with_time_proration'
-	/** Switch now; charge the full new price immediately and restart the period. */
-	| 'immediate_and_charge_full_price'
-	/** Switch now; charge the prorated difference for the current period. */
-	| 'immediate_and_charge_prorated_price'
-	/** Keep the current plan until it expires, then start the new one. Usual downgrade. */
-	| 'deferred';
-
-/** Store-specific replacement codes stay here, behind the neutral vocabulary above. */
-const PRORATION_CODES: Record<ProrationMode, string> = {
-	immediate_with_time_proration: 'WITH_TIME_PRORATION',
-	immediate_and_charge_full_price: 'CHARGE_FULL_PRICE',
-	immediate_and_charge_prorated_price: 'CHARGE_PRORATED_PRICE',
-	deferred: 'DEFERRED',
-};
-
-export type PriceChangeResult =
-	| { kind: 'confirmed' }
-	| { kind: 'dismissed' }
-	/** The platform has no client-side flow; it notifies the user itself (FR-067). */
-	| { kind: 'unsupported' }
-	| { kind: 'failed'; code: string };
-
-export interface SubscriptionsDeps {
-	resolved: ResolvedConfig;
-	provider: ProviderPort;
-	snapshot: () => PersistedSnapshot;
-	purchase: (
-		productKey: ProductKey,
-		options?: PurchaseOptions & { replaceProductKey?: ProductKey; prorationMode?: string },
-	) => Promise<PurchaseResult>;
-}
-
-export interface Subscriptions {
-	changePlan(
-		fromProductKey: ProductKey,
-		toProductKey: ProductKey,
-		mode: ProrationMode,
-		options?: PurchaseOptions,
-	): Promise<PurchaseResult>;
-	openManagement(productKey?: ProductKey): Promise<void>;
-	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
-}
-
-export function createSubscriptions(deps: SubscriptionsDeps): Subscriptions {
-	const { resolved } = deps;
-
-	return {
-		async changePlan(
-			fromProductKey,
-			toProductKey,
-			mode,
-			options,
-		): Promise<PurchaseResult> {
-			if (!deps.provider.capabilities().supportsPlanChange) {
-				return { kind: 'unsupported' };
-			}
-
-			const target = resolved.entries.get(toProductKey);
-			if (!target) {
-				return { kind: 'unknown_product', productKey: toProductKey };
-			}
-			if (!resolved.entries.has(fromProductKey)) {
-				return { kind: 'unknown_product', productKey: fromProductKey };
-			}
-
-			// The store needs the *token* of the subscription being replaced, not its
-			// product id — that is how it knows which active purchase to migrate, and
-			// it is why a plan change needs a live local record rather than just two
-			// product keys.
-			const active = deps
-				.snapshot()
-				.purchases.find(
-					p =>
-						p.productKey === fromProductKey &&
-						p.productType === 'subscription' &&
-						p.state === 'purchased',
-				);
-
-			if (!active) {
-				// No subscription to replace. Treated as a plain purchase would be
-				// surprising — the caller asked to *change* something that is not there,
-				// which almost always means its own state is stale.
-				return { kind: 'already_owned', productKey: fromProductKey };
-			}
-
-			// Routed through the normal purchase flow on purpose: a plan change is a
-			// purchase, so it must inherit the single-flight lock, the environment
-			// guard, validation, and the finalization queue rather than reimplementing
-			// any of them.
-			return deps.purchase(toProductKey, {
-				...options,
-				replaceProductKey: fromProductKey,
-				prorationMode: PRORATION_CODES[mode],
-			});
-		},
-
-		async openManagement(productKey?: ProductKey): Promise<void> {
-			const storeProductId = productKey
-				? storeIdForProductKey(resolved, productKey)
-				: undefined;
-			// No-ops rather than throwing where the platform has no such screen: this
-			// is wired to a button, and a button that crashes is worse than one that
-			// does nothing on a platform that cannot honour it.
-			await deps.provider.openSubscriptionManagement(storeProductId);
-		},
-
-		async confirmPriceChange(productKey): Promise<PriceChangeResult> {
-			if (!deps.provider.capabilities().supportsPriceChangeConfirmation) {
-				return { kind: 'unsupported' };
-			}
-			const storeProductId = storeIdForProductKey(resolved, productKey);
-			if (!storeProductId) {
-				return { kind: 'failed', code: 'PAYMENT_UNKNOWN_PRODUCT' };
-			}
-
-			const outcome = await deps.provider.confirmPriceChange(storeProductId);
-			if (!outcome.ok) {
-				return { kind: 'failed', code: 'PAYMENT_STORE_ERROR' };
-			}
-			return outcome.confirmed ? { kind: 'confirmed' } : { kind: 'dismissed' };
-		},
-	};
-}
+/**
+ * Subscription plan changes and the route to the store's management screen (US12).
+ *
+ * Two platform rules drive this module:
+ *
+ * - **Proration is the app's decision, inside what the store permits** (FR-065).
+ *   Whether a user who upgrades gets charged immediately, keeps their remaining
+ *   time, or starts a fresh period is a product and pricing choice, so the
+ *   package forwards it rather than picking.
+ * - **Cancellation belongs to the store.** Platforms forbid an app presenting its
+ *   own cancellation screen, so this module offers only a route to the store's
+ *   (FR-066) — there is deliberately no self-built alternative anywhere in the
+ *   package.
+ */
+
+import type { ProductKey, PurchaseOptions, PurchaseResult } from '../config/types';
+import type { ResolvedConfig } from '../config/validate';
+import type { ProviderPort } from '../adapter/port';
+import { storeIdForProductKey } from '../entitlements/mapping';
+import type { PersistedSnapshot } from '../persistence/snapshot';
+
+/**
+ * How already-paid time is handled when a plan changes.
+ *
+ * Named for the user-visible effect rather than mirroring a store's enum, so the
+ * same vocabulary will map onto StoreKit later (FR-004).
+ */
+export type ProrationMode =
+	/** Switch now; credit unused time against the new plan. The usual upgrade. */
+	| 'immediate_with_time_proration'
+	/** Switch now; charge the full new price immediately and restart the period. */
+	| 'immediate_and_charge_full_price'
+	/** Switch now; charge the prorated difference for the current period. */
+	| 'immediate_and_charge_prorated_price'
+	/** Keep the current plan until it expires, then start the new one. Usual downgrade. */
+	| 'deferred';
+
+/** Store-specific replacement codes stay here, behind the neutral vocabulary above. */
+const PRORATION_CODES: Record<ProrationMode, string> = {
+	immediate_with_time_proration: 'WITH_TIME_PRORATION',
+	immediate_and_charge_full_price: 'CHARGE_FULL_PRICE',
+	immediate_and_charge_prorated_price: 'CHARGE_PRORATED_PRICE',
+	deferred: 'DEFERRED',
+};
+
+export type PriceChangeResult =
+	| { kind: 'confirmed' }
+	| { kind: 'dismissed' }
+	/** The platform has no client-side flow; it notifies the user itself (FR-067). */
+	| { kind: 'unsupported' }
+	| { kind: 'failed'; code: string };
+
+export interface SubscriptionsDeps {
+	resolved: ResolvedConfig;
+	provider: ProviderPort;
+	snapshot: () => PersistedSnapshot;
+	purchase: (
+		productKey: ProductKey,
+		options?: PurchaseOptions & { replaceProductKey?: ProductKey; prorationMode?: string },
+	) => Promise<PurchaseResult>;
+}
+
+export interface Subscriptions {
+	changePlan(
+		fromProductKey: ProductKey,
+		toProductKey: ProductKey,
+		mode: ProrationMode,
+		options?: PurchaseOptions,
+	): Promise<PurchaseResult>;
+	openManagement(productKey?: ProductKey): Promise<void>;
+	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
+}
+
+export function createSubscriptions(deps: SubscriptionsDeps): Subscriptions {
+	const { resolved } = deps;
+
+	return {
+		async changePlan(fromProductKey, toProductKey, mode, options): Promise<PurchaseResult> {
+			if (!deps.provider.capabilities().supportsPlanChange) {
+				return { kind: 'unsupported' };
+			}
+
+			const target = resolved.entries.get(toProductKey);
+			if (!target) {
+				return { kind: 'unknown_product', productKey: toProductKey };
+			}
+			if (!resolved.entries.has(fromProductKey)) {
+				return { kind: 'unknown_product', productKey: fromProductKey };
+			}
+
+			// The store needs the *token* of the subscription being replaced, not its
+			// product id — that is how it knows which active purchase to migrate, and
+			// it is why a plan change needs a live local record rather than just two
+			// product keys.
+			const active = deps
+				.snapshot()
+				.purchases.find(
+					p =>
+						p.productKey === fromProductKey &&
+						p.productType === 'subscription' &&
+						p.state === 'purchased',
+				);
+
+			if (!active) {
+				// No subscription to replace. Treated as a plain purchase would be
+				// surprising — the caller asked to *change* something that is not there,
+				// which almost always means its own state is stale.
+				return { kind: 'already_owned', productKey: fromProductKey };
+			}
+
+			// Routed through the normal purchase flow on purpose: a plan change is a
+			// purchase, so it must inherit the single-flight lock, the environment
+			// guard, validation, and the finalization queue rather than reimplementing
+			// any of them.
+			return deps.purchase(toProductKey, {
+				...options,
+				replaceProductKey: fromProductKey,
+				prorationMode: PRORATION_CODES[mode],
+			});
+		},
+
+		async openManagement(productKey?: ProductKey): Promise<void> {
+			const storeProductId = productKey ? storeIdForProductKey(resolved, productKey) : undefined;
+			// No-ops rather than throwing where the platform has no such screen: this
+			// is wired to a button, and a button that crashes is worse than one that
+			// does nothing on a platform that cannot honour it.
+			await deps.provider.openSubscriptionManagement(storeProductId);
+		},
+
+		async confirmPriceChange(productKey): Promise<PriceChangeResult> {
+			if (!deps.provider.capabilities().supportsPriceChangeConfirmation) {
+				return { kind: 'unsupported' };
+			}
+			const storeProductId = storeIdForProductKey(resolved, productKey);
+			if (!storeProductId) {
+				return { kind: 'failed', code: 'PAYMENT_UNKNOWN_PRODUCT' };
+			}
+
+			const outcome = await deps.provider.confirmPriceChange(storeProductId);
+			if (!outcome.ok) {
+				return { kind: 'failed', code: 'PAYMENT_STORE_ERROR' };
+			}
+			return outcome.confirmed ? { kind: 'confirmed' } : { kind: 'dismissed' };
+		},
+	};
+}