@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/adapter/iap-adapter.ts

@@ -1,660 +1,627 @@
-/**
- * Android adapter over `react-native-iap` (Play Billing).
- *
- * **The only file in this package that touches the billing library.** Everything
- * above it talks to `ProviderPort`, which is what keeps the binding replaceable
- * and lets an iOS adapter be added without changing a consumer call (FR-002,
- * FR-007). ESLint enforces that boundary.
- *
- * ## Verified against react-native-iap 16.7.3
- *
- * 0.3.0 was written before the binding was installed, from its documentation, and
- * no purchase could complete on a device. Checked against the installed 16.7.3
- * source for 0.3.1, two facts shape the purchase path:
- *
- * - The request is keyed by store: `google` / `apple`. 0.3.0 sent `android`, which
- *   the binding rejects (`empty-sku-list`) before Play opens. The request type is
- *   now the binding's own `RequestPurchaseProps`, so a renamed key fails to
- *   typecheck here instead of failing on a user's device.
- * - On Android `requestPurchase` resolves with an **empty list** once the flow
- *   ends, whatever happened. The outcome (bought, pending, cancelled, failed)
- *   arrives only through `purchaseUpdatedListener` / `purchaseErrorListener`, so
- *   `launchPurchase` waits for those events.
- *
- * The module is still required lazily, and `IapModule` still names exactly the
- * surface used. `__tests__/iap-adapter.test.ts` drives this file through a fake
- * binding that behaves as 16.7.3 does; the rest of the suite uses the fake store.
- *
- * ## Known upstream defect this guards against
- *
- * openiap#408: the Android bridge did not clear its internal `isInitialized` flag
- * on disconnect, so `connected` stayed true, later calls failed with
- * `E_NOT_PREPARED`, and `reconnect()` reported success without rebuilding
- * anything. This adapter therefore (a) tracks connection state itself rather than
- * trusting the binding's flag, and (b) always performs a full
- * `endConnection` + `initConnection` cycle instead of calling any reconnect
- * shortcut.
- */
-
-import type {
-	RequestPurchaseProps,
-	SubscriptionReplacementModeAndroid,
-} from 'react-native-iap';
-
-import type { ProductType, Unsubscribe } from '../config/types';
-import type {
-	ProviderCapabilities,
-	ProviderConnectOutcome,
-	ProviderFailureReason,
-	ProviderPort,
-	ProviderPriceChangeOutcome,
-	ProviderProduct,
-	ProviderPurchase,
-	ProviderPurchaseOutcome,
-	ProviderPurchaseRequest,
-	ProviderToken,
-	StoreProductId,
-} from './port';
-
-/**
- * Exactly what this adapter needs from the binding.
- *
- * Declared narrowly on purpose: it documents the coupling, and it means a binding
- * upgrade that changes one of these shapes fails to typecheck here instead of
- * failing silently at runtime on a user's device.
- */
-interface IapModule {
-	initConnection(): Promise<boolean>;
-	endConnection(): Promise<void>;
-	fetchProducts(params: {
-		skus: string[];
-		type: 'in-app' | 'subs';
-	}): Promise<RawProduct[]>;
-	getAvailablePurchases(): Promise<RawPurchase[]>;
-	/** Typed by the binding itself, so a renamed request key fails to compile. */
-	requestPurchase(params: RequestPurchaseProps): Promise<unknown>;
-	finishTransaction(params: {
-		purchase: unknown;
-		isConsumable?: boolean;
-	}): Promise<unknown>;
-	purchaseUpdatedListener(
-		listener: (purchase: RawPurchase) => void,
-	): { remove(): void };
-	purchaseErrorListener(listener: (error: RawPurchaseError) => void): {
-		remove(): void;
-	};
-	deepLinkToSubscriptions?(params: { skuAndroid?: string }): Promise<void>;
-}
-
-interface RawProduct {
-	id?: string;
-	productId?: string;
-	title?: string;
-	name?: string;
-	description?: string;
-	displayPrice?: string;
-	localizedPrice?: string;
-	currency?: string;
-	currencyCode?: string;
-	price?: string | number;
-	oneTimePurchaseOfferDetails?: {
-		formattedPrice?: string;
-		priceAmountMicros?: string | number;
-		priceCurrencyCode?: string;
-	};
-	subscriptionOfferDetails?: RawSubscriptionOffer[];
-}
-
-interface RawSubscriptionOffer {
-	offerToken?: string;
-	offerId?: string;
-	basePlanId?: string;
-	pricingPhases?: {
-		pricingPhaseList?: Array<{
-			formattedPrice?: string;
-			priceAmountMicros?: string | number;
-			priceCurrencyCode?: string;
-			billingPeriod?: string;
-			recurrenceMode?: number;
-			billingCycleCount?: number;
-		}>;
-	};
-}
-
-interface RawPurchase {
-	id?: string;
-	transactionId?: string;
-	productId?: string;
-	ids?: string[];
-	purchaseToken?: string;
-	purchaseStateAndroid?: number | null;
-	/** A string in the 16.x binding: `'pending' | 'purchased' | 'unknown'`. */
-	purchaseState?: number | string;
-	transactionDate?: number;
-	isAcknowledgedAndroid?: boolean;
-	isAcknowledged?: boolean;
-	autoRenewingAndroid?: boolean;
-	isAutoRenewing?: boolean;
-	expirationDateAndroid?: number;
-	transactionReceipt?: string;
-	dataAndroid?: string;
-}
-
-/** What `purchaseErrorListener` delivers. */
-interface RawPurchaseError {
-	code?: string;
-	message?: string;
-	productId?: string | null;
-}
-
-/**
- * How long to wait for the outcome event after `requestPurchase` has resolved.
- * The binding emits the event before or as it resolves, so this only bounds the
- * case where none ever comes; it never runs while the user is in Play's UI.
- */
-const RESULT_EVENT_GRACE_MS = 2_000;
-
-/** Play's replacement modes, by the codes the engine passes (`engine/subscriptions.ts`). */
-const REPLACEMENT_MODES: Record<string, SubscriptionReplacementModeAndroid> = {
-	WITH_TIME_PRORATION: 'with-time-proration',
-	CHARGE_FULL_PRICE: 'charge-full-price',
-	CHARGE_PRORATED_PRICE: 'charge-prorated-price',
-	DEFERRED: 'deferred',
-};
-
-/** The request in the binding's 16.7 shape: keyed `google`, not `android`. */
-export function toRequestProps(request: ProviderPurchaseRequest): RequestPurchaseProps {
-	const google = {
-		skus: [request.storeProductId],
-		...(request.obfuscatedAccountId
-			? { obfuscatedAccountId: request.obfuscatedAccountId }
-			: {}),
-	};
-	if (request.productType !== 'subscription') {
-		return { request: { google }, type: 'in-app' };
-	}
-
-	const replacementMode = request.prorationMode
-		? REPLACEMENT_MODES[request.prorationMode]
-		: undefined;
-	return {
-		request: {
-			google: {
-				...google,
-				...(request.offerKey
-					? {
-							subscriptionOffers: [
-								{ sku: request.storeProductId, offerToken: request.offerKey },
-							],
-						}
-					: {}),
-				// A plan change: the token of the purchase being replaced, and — for
-				// the replacement mode to apply — its product id (Billing 8.1+).
-				...(request.replacePurchaseToken
-					? { purchaseToken: request.replacePurchaseToken }
-					: {}),
-				...(request.replacePurchaseToken &&
-				request.replaceStoreProductId &&
-				replacementMode
-					? {
-							subscriptionProductReplacementParams: {
-								oldProductId: request.replaceStoreProductId,
-								replacementMode,
-							},
-						}
-					: {}),
-			},
-		},
-		type: 'subs',
-	};
-}
-
-/** Play's `PurchaseState`: 0 unspecified, 1 purchased, 2 pending. */
-const PLAY_STATE_PURCHASED = 1;
-const PLAY_STATE_PENDING = 2;
-
-function loadModule(): IapModule {
-	// Required lazily so importing the package does not require the native module.
-	const mod = require('react-native-iap') as IapModule;
-	return mod;
-}
-
-function toMicros(value: string | number | undefined): number {
-	if (typeof value === 'number') {
-		return value;
-	}
-	if (typeof value === 'string') {
-		const parsed = Number.parseInt(value, 10);
-		return Number.isFinite(parsed) ? parsed : 0;
-	}
-	return 0;
-}
-
-function normalizeProduct(
-	raw: RawProduct,
-	productType: ProductType,
-): ProviderProduct {
-	const oneTime = raw.oneTimePurchaseOfferDetails;
-	const currencyCode =
-		oneTime?.priceCurrencyCode ?? raw.currencyCode ?? raw.currency ?? '';
-
-	return {
-		storeProductId: raw.id ?? raw.productId ?? '',
-		productType,
-		title: raw.title ?? raw.name ?? '',
-		description: raw.description ?? '',
-		// Store-formatted, never built here: only the store knows the right currency
-		// symbol, separator, and placement for the user's locale (FR-028).
-		formattedPrice:
-			oneTime?.formattedPrice ?? raw.displayPrice ?? raw.localizedPrice ?? '',
-		currencyCode,
-		priceAmountMicros: toMicros(oneTime?.priceAmountMicros ?? raw.price),
-		offers: (raw.subscriptionOfferDetails ?? []).map(offer =>
-			normalizeOffer(offer, currencyCode),
-		),
-	};
-}
-
-function normalizeOffer(
-	offer: RawSubscriptionOffer,
-	fallbackCurrency: string,
-): ProviderProduct['offers'][number] {
-	const phases = offer.pricingPhases?.pricingPhaseList ?? [];
-	// The last phase is the recurring price; earlier ones are trial or
-	// introductory. Play orders them that way.
-	const recurring = phases[phases.length - 1];
-	const intro = phases.length > 1 ? phases[0] : undefined;
-	const isFreeTrial = intro !== undefined && toMicros(intro.priceAmountMicros) === 0;
-
-	return {
-		offerKey: offer.offerToken ?? offer.offerId ?? offer.basePlanId ?? '',
-		billingPeriod: recurring?.billingPeriod ?? '',
-		formattedPrice: recurring?.formattedPrice ?? '',
-		priceAmountMicros: toMicros(recurring?.priceAmountMicros),
-		currencyCode: recurring?.priceCurrencyCode ?? fallbackCurrency,
-		trialPeriod: isFreeTrial ? intro?.billingPeriod : undefined,
-		introductoryPrice:
-			intro && !isFreeTrial
-				? {
-						formattedPrice: intro.formattedPrice ?? '',
-						period: intro.billingPeriod ?? '',
-						cycles: intro.billingCycleCount ?? 1,
-					}
-				: undefined,
-		// Play decides eligibility by only returning offers the user qualifies for,
-		// so forwarding `true` reports the store's determination rather than
-		// computing our own (FR-026).
-		isEligible: true,
-	};
-}
-
-/**
- * Reads the purchase state from whichever field the binding filled.
- *
- * Pending is preserved, never flattened to purchased: that distinction is what
- * stops an entitlement being granted for money that has not arrived (FR-037).
- * And an unrecognized or missing state is `unspecified`, never `purchased`.
- *
- * 0.1.0 read only Play's numeric state and treated anything else as purchased.
- * The 16.x binding hands JavaScript the *string* state and does not carry the
- * numeric one across, so on a device every pending purchase arrived as a string,
- * fell through to the default, and was granted. Unit tests could not see it: they
- * drive the fake store, which never passes through here.
- */
-export function toProviderPurchaseState(
-	raw: Pick<RawPurchase, 'purchaseStateAndroid' | 'purchaseState'>,
-): ProviderPurchase['state'] {
-	let numeric: number | undefined;
-	if (typeof raw.purchaseStateAndroid === 'number') {
-		numeric = raw.purchaseStateAndroid;
-	} else if (typeof raw.purchaseState === 'number') {
-		numeric = raw.purchaseState;
-	}
-	if (numeric !== undefined) {
-		if (numeric === PLAY_STATE_PENDING) {
-			return 'pending';
-		}
-		return numeric === PLAY_STATE_PURCHASED ? 'purchased' : 'unspecified';
-	}
-
-	switch (typeof raw.purchaseState === 'string' ? raw.purchaseState.toLowerCase() : '') {
-		case 'purchased':
-		case 'restored':
-			return 'purchased';
-		case 'pending':
-		case 'deferred':
-			return 'pending';
-		default:
-			return 'unspecified';
-	}
-}
-
-function normalizePurchase(raw: RawPurchase): ProviderPurchase {
-	return {
-		storeProductId: raw.productId ?? raw.ids?.[0] ?? '',
-		transactionId: raw.id ?? raw.transactionId ?? raw.purchaseToken ?? '',
-		token: raw.purchaseToken ?? '',
-		state: toProviderPurchaseState(raw),
-		purchasedAt: raw.transactionDate ?? Date.now(),
-		isAcknowledged: raw.isAcknowledgedAndroid ?? raw.isAcknowledged ?? false,
-		expiresAt: raw.expirationDateAndroid,
-		willAutoRenew: raw.autoRenewingAndroid ?? raw.isAutoRenewing,
-		// Opaque material for the app's backend. Carried here and handed to the
-		// validation hook only — never logged or put in an event (FR-074).
-		verificationPayload: raw.transactionReceipt ?? raw.dataAndroid,
-	};
-}
-
-/** Maps a binding error code onto the port's vocabulary, so no store code escapes. */
-function mapErrorCode(code: string | undefined): ProviderFailureReason {
-	switch (code) {
-		case 'E_USER_CANCELLED':
-		case 'user-cancelled':
-			return 'user_cancelled';
-		case 'E_ALREADY_OWNED':
-		case 'already-owned':
-		case 'item-already-owned':
-			return 'already_owned';
-		case 'E_ITEM_UNAVAILABLE':
-		case 'item-unavailable':
-		case 'sku-not-found':
-			return 'unknown_product';
-		case 'E_NOT_PREPARED':
-		case 'not-prepared':
-			return 'not_ready';
-		case 'E_NETWORK_ERROR':
-		case 'network-error':
-			return 'network_error';
-		case 'E_DEFERRED_PAYMENT':
-			// Not a failure — a pending purchase. The caller resolves it from the
-			// purchase update rather than from this error.
-			return 'store_error';
-		default:
-			return 'store_error';
-	}
-}
-
-const ANDROID_CAPABILITIES: ProviderCapabilities = {
-	supportsSubscriptions: true,
-	supportsPlanChange: true,
-	supportsPriceChangeConfirmation: false,
-	/**
-	 * False, and this is a platform fact rather than a gap in this adapter.
-	 *
-	 * Client-side Play Billing cannot separate grace period from account 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. The entitlement layer reads this flag and reports
-	 * `indeterminate` rather than inventing a distinction (research.md R5).
-	 */
-	reportsGraceAndHoldDistinctly: false,
-	supportsExternalTransactions: false,
-	/** This one really does move money, which is what arms the environment guard. */
-	createsRealTransactions: true,
-	/** The outcome event comes only when the user leaves Play's purchase UI. */
-	purchaseOutcomeIncludesStoreTime: true,
-};
-
-export interface IapAdapterOptions {
-	/** Injected in tests that need to drive the mapping without the native module. */
-	module?: IapModule;
-}
-
-export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort {
-	let iap: IapModule | undefined = options.module;
-
-	/** Tracked here, never read from the binding — see the openiap#408 note above. */
-	let connected = false;
-
-	const connectionListeners = new Set<
-		(connected: boolean, reason?: string) => void
-	>();
-	const purchaseListeners = new Set<(purchase: ProviderPurchase) => void>();
-	/** Only an in-flight `launchPurchase` listens here; see there. */
-	const purchaseErrorListeners = new Set<(error: RawPurchaseError) => void>();
-	let updateSub: { remove(): void } | undefined;
-	let errorSub: { remove(): void } | undefined;
-
-	const module = (): IapModule => {
-		if (!iap) {
-			iap = loadModule();
-		}
-		return iap;
-	};
-
-	const notifyConnection = (next: boolean, reason?: string): void => {
-		if (connected === next) {
-			return;
-		}
-		connected = next;
-		for (const listener of connectionListeners) {
-			listener(next, reason);
-		}
-	};
-
-	const attachListeners = (): void => {
-		// Every connect attaches, so whatever an earlier connect left must go first.
-		// Overwriting the handles orphaned the old native listeners, which kept
-		// firing — every purchase update reached the engine once per connect.
-		detachListeners();
-		const mod = module();
-		updateSub = mod.purchaseUpdatedListener(raw => {
-			const purchase = normalizePurchase(raw);
-			for (const listener of purchaseListeners) {
-				listener(purchase);
-			}
-		});
-		errorSub = mod.purchaseErrorListener(error => {
-			// A `not-prepared` error is the one signal the binding gives that the
-			// service went away underneath us, so it is treated as a disconnect
-			// rather than as a purchase failure.
-			if (mapErrorCode(error.code) === 'not_ready') {
-				notifyConnection(false, 'not_prepared');
-			}
-			for (const listener of purchaseErrorListeners) {
-				listener(error);
-			}
-		});
-	};
-
-	const detachListeners = (): void => {
-		updateSub?.remove();
-		updateSub = undefined;
-		errorSub?.remove();
-		errorSub = undefined;
-	};
-
-	return {
-		async connect(): Promise<ProviderConnectOutcome> {
-			try {
-				const mod = module();
-				// Always a full cycle. The binding's own reconnect has reported success
-				// without rebuilding anything, so we never rely on it (openiap#408).
-				if (connected) {
-					await mod.endConnection().catch(() => undefined);
-					connected = false;
-				}
-				const ok = await mod.initConnection();
-				if (!ok) {
-					return {
-						ok: false,
-						reason: 'no_billing_service',
-						retryable: true,
-					};
-				}
-				attachListeners();
-				notifyConnection(true);
-				return { ok: true };
-			} catch (error) {
-				const code = (error as { code?: string }).code;
-				// A missing or too-old Play Services install is not the same as a
-				// transient error, and the app shows different things for each (FR-021).
-				if (code === 'E_IAP_NOT_AVAILABLE' || code === 'iap-not-available') {
-					return { ok: false, reason: 'no_billing_service', retryable: false };
-				}
-				if (code === 'E_SERVICE_ERROR') {
-					return {
-						ok: false,
-						reason: 'billing_service_outdated',
-						retryable: true,
-					};
-				}
-				return { ok: false, reason: 'store_error', retryable: true };
-			}
-		},
-
-		async disconnect(): Promise<void> {
-			detachListeners();
-			try {
-				await module().endConnection();
-			} catch {
-				// Already down; nothing to tear down.
-			}
-			notifyConnection(false, 'disconnect');
-		},
-
-		observeConnection(listener): Unsubscribe {
-			connectionListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				connectionListeners.delete(listener);
-			};
-		},
-
-		async queryProducts(
-			storeProductIds: StoreProductId[],
-			productType: ProductType,
-		): Promise<ProviderProduct[]> {
-			const raw = await module().fetchProducts({
-				skus: storeProductIds,
-				type: productType === 'subscription' ? 'subs' : 'in-app',
-			});
-			return raw.map(product => normalizeProduct(product, productType));
-		},
-
-		async queryOwned(): Promise<ProviderPurchase[]> {
-			const raw = await module().getAvailablePurchases();
-			// Pending purchases are mapped through, flagged rather than filtered: the
-			// engine needs to see them to raise the pending signal (FR-038).
-			return raw.map(normalizePurchase);
-		},
-
-		/**
-		 * Settles on the first outcome event for this product: a purchase update
-		 * (bought or pending) or a purchase error (cancelled, already owned, …).
-		 *
-		 * The binding's promise is not the outcome: on Android it resolves with an
-		 * empty list when the flow ends, whatever happened. Its listeners also feed
-		 * `observePurchases`, so the engine sees a bought purchase twice — here and
-		 * as a store update — and grants it once (FR-044).
-		 */
-		launchPurchase(request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> {
-			const sku = request.storeProductId;
-			return new Promise<ProviderPurchaseOutcome>(resolve => {
-				let settled = false;
-				let grace: ReturnType<typeof setTimeout> | undefined;
-
-				const onPurchase = (purchase: ProviderPurchase): void => {
-					if (purchase.storeProductId === sku) {
-						finish({ ok: true, purchase });
-					}
-				};
-				const onError = (error: RawPurchaseError): void => {
-					if (error.productId && error.productId !== sku) {
-						return;
-					}
-					finish({ ok: false, reason: mapErrorCode(error.code), detail: error.code });
-				};
-				const fail = (error: unknown): void => {
-					const code = (error as { code?: string } | undefined)?.code;
-					finish({ ok: false, reason: mapErrorCode(code), detail: code });
-				};
-				function finish(outcome: ProviderPurchaseOutcome): void {
-					if (settled) {
-						return;
-					}
-					settled = true;
-					clearTimeout(grace);
-					purchaseListeners.delete(onPurchase);
-					purchaseErrorListeners.delete(onError);
-					resolve(outcome);
-				}
-
-				purchaseListeners.add(onPurchase);
-				purchaseErrorListeners.add(onError);
-				try {
-					module()
-						.requestPurchase(toRequestProps(request))
-						.then(() => {
-							if (!settled) {
-								grace = setTimeout(
-									() =>
-										finish({
-											ok: false,
-											reason: 'store_error',
-											detail: 'no purchase event',
-										}),
-									RESULT_EVENT_GRACE_MS,
-								);
-							}
-						}, fail);
-				} catch (error) {
-					fail(error);
-				}
-			});
-		},
-
-		observePurchases(listener): Unsubscribe {
-			purchaseListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				purchaseListeners.delete(listener);
-			};
-		},
-
-		async acknowledge(token: ProviderToken): Promise<void> {
-			// Idempotent at the store: acknowledging an already-acknowledged purchase
-			// is accepted, which is what FR-044 relies on.
-			await module().finishTransaction({
-				purchase: { purchaseToken: token },
-				isConsumable: false,
-			});
-		},
-
-		async consume(token: ProviderToken): Promise<void> {
-			await module().finishTransaction({
-				purchase: { purchaseToken: token },
-				isConsumable: true,
-			});
-		},
-
-		async openSubscriptionManagement(
-			storeProductId?: StoreProductId,
-		): Promise<void> {
-			// The store's own screen. Platforms forbid a self-built cancellation
-			// screen, so there is deliberately no alternative path here (FR-066).
-			const mod = module();
-			if (!mod.deepLinkToSubscriptions) {
-				return;
-			}
-			await mod.deepLinkToSubscriptions({ skuAndroid: storeProductId });
-		},
-
-		async confirmPriceChange(): Promise<ProviderPriceChangeOutcome> {
-			// Play has no client-side price-change confirmation flow; it notifies the
-			// user itself. Reported as unsupported rather than faked, matching
-			// `supportsPriceChangeConfirmation: false` (FR-067).
-			return { ok: false, reason: 'store_error' };
-		},
-
-		capabilities: () => ANDROID_CAPABILITIES,
-	};
-}
+/**
+ * Android adapter over `react-native-iap` (Play Billing).
+ *
+ * **The only file in this package that touches the billing library.** Everything
+ * above it talks to `ProviderPort`, which is what keeps the binding replaceable
+ * and lets an iOS adapter be added without changing a consumer call (FR-002,
+ * FR-007). ESLint enforces that boundary.
+ *
+ * ## Verified against react-native-iap 16.7.3
+ *
+ * 0.3.0 was written before the binding was installed, from its documentation, and
+ * no purchase could complete on a device. Checked against the installed 16.7.3
+ * source for 0.3.1, two facts shape the purchase path:
+ *
+ * - The request is keyed by store: `google` / `apple`. 0.3.0 sent `android`, which
+ *   the binding rejects (`empty-sku-list`) before Play opens. The request type is
+ *   now the binding's own `RequestPurchaseProps`, so a renamed key fails to
+ *   typecheck here instead of failing on a user's device.
+ * - On Android `requestPurchase` resolves with an **empty list** once the flow
+ *   ends, whatever happened. The outcome (bought, pending, cancelled, failed)
+ *   arrives only through `purchaseUpdatedListener` / `purchaseErrorListener`, so
+ *   `launchPurchase` waits for those events.
+ *
+ * The module is still required lazily, and `IapModule` still names exactly the
+ * surface used. `__tests__/iap-adapter.test.ts` drives this file through a fake
+ * binding that behaves as 16.7.3 does; the rest of the suite uses the fake store.
+ *
+ * ## Known upstream defect this guards against
+ *
+ * openiap#408: the Android bridge did not clear its internal `isInitialized` flag
+ * on disconnect, so `connected` stayed true, later calls failed with
+ * `E_NOT_PREPARED`, and `reconnect()` reported success without rebuilding
+ * anything. This adapter therefore (a) tracks connection state itself rather than
+ * trusting the binding's flag, and (b) always performs a full
+ * `endConnection` + `initConnection` cycle instead of calling any reconnect
+ * shortcut.
+ */
+
+import { createListenerSet, lazyPeer } from '@chipmobilesdk/rn-core';
+
+import type { RequestPurchaseProps, SubscriptionReplacementModeAndroid } from 'react-native-iap';
+
+import type { ProductType, Unsubscribe } from '../config/types';
+import { PaymentError, redact } from '../diagnostics/errors';
+import type {
+	ProviderCapabilities,
+	ProviderConnectOutcome,
+	ProviderFailureReason,
+	ProviderPort,
+	ProviderPriceChangeOutcome,
+	ProviderProduct,
+	ProviderPurchase,
+	ProviderPurchaseOutcome,
+	ProviderPurchaseRequest,
+	ProviderToken,
+	StoreProductId,
+} from './port';
+
+/**
+ * Exactly what this adapter needs from the binding.
+ *
+ * Declared narrowly on purpose: it documents the coupling, and it means a binding
+ * upgrade that changes one of these shapes fails to typecheck here instead of
+ * failing silently at runtime on a user's device.
+ */
+interface IapModule {
+	initConnection(): Promise<boolean>;
+	endConnection(): Promise<void>;
+	fetchProducts(params: { skus: string[]; type: 'in-app' | 'subs' }): Promise<RawProduct[]>;
+	getAvailablePurchases(): Promise<RawPurchase[]>;
+	/** Typed by the binding itself, so a renamed request key fails to compile. */
+	requestPurchase(params: RequestPurchaseProps): Promise<unknown>;
+	finishTransaction(params: { purchase: unknown; isConsumable?: boolean }): Promise<unknown>;
+	purchaseUpdatedListener(listener: (purchase: RawPurchase) => void): { remove(): void };
+	purchaseErrorListener(listener: (error: RawPurchaseError) => void): {
+		remove(): void;
+	};
+	deepLinkToSubscriptions?(params: { skuAndroid?: string }): Promise<void>;
+}
+
+interface RawProduct {
+	id?: string;
+	productId?: string;
+	title?: string;
+	name?: string;
+	description?: string;
+	displayPrice?: string;
+	localizedPrice?: string;
+	currency?: string;
+	currencyCode?: string;
+	price?: string | number;
+	oneTimePurchaseOfferDetails?: {
+		formattedPrice?: string;
+		priceAmountMicros?: string | number;
+		priceCurrencyCode?: string;
+	};
+	subscriptionOfferDetails?: RawSubscriptionOffer[];
+}
+
+interface RawSubscriptionOffer {
+	offerToken?: string;
+	offerId?: string;
+	basePlanId?: string;
+	pricingPhases?: {
+		pricingPhaseList?: Array<{
+			formattedPrice?: string;
+			priceAmountMicros?: string | number;
+			priceCurrencyCode?: string;
+			billingPeriod?: string;
+			recurrenceMode?: number;
+			billingCycleCount?: number;
+		}>;
+	};
+}
+
+interface RawPurchase {
+	id?: string;
+	transactionId?: string;
+	productId?: string;
+	ids?: string[];
+	purchaseToken?: string;
+	purchaseStateAndroid?: number | null;
+	/** A string in the 16.x binding: `'pending' | 'purchased' | 'unknown'`. */
+	purchaseState?: number | string;
+	transactionDate?: number;
+	isAcknowledgedAndroid?: boolean;
+	isAcknowledged?: boolean;
+	autoRenewingAndroid?: boolean;
+	isAutoRenewing?: boolean;
+	expirationDateAndroid?: number;
+	transactionReceipt?: string;
+	dataAndroid?: string;
+}
+
+/** What `purchaseErrorListener` delivers. */
+interface RawPurchaseError {
+	code?: string;
+	message?: string;
+	productId?: string | null;
+}
+
+/**
+ * How long to wait for the outcome event after `requestPurchase` has resolved.
+ * The binding emits the event before or as it resolves, so this only bounds the
+ * case where none ever comes; it never runs while the user is in Play's UI.
+ */
+const RESULT_EVENT_GRACE_MS = 2_000;
+
+/** Play's replacement modes, by the codes the engine passes (`engine/subscriptions.ts`). */
+const REPLACEMENT_MODES: Record<string, SubscriptionReplacementModeAndroid> = {
+	WITH_TIME_PRORATION: 'with-time-proration',
+	CHARGE_FULL_PRICE: 'charge-full-price',
+	CHARGE_PRORATED_PRICE: 'charge-prorated-price',
+	DEFERRED: 'deferred',
+};
+
+/** The request in the binding's 16.7 shape: keyed `google`, not `android`. */
+export function toRequestProps(request: ProviderPurchaseRequest): RequestPurchaseProps {
+	const google = {
+		skus: [request.storeProductId],
+		...(request.obfuscatedAccountId ? { obfuscatedAccountId: request.obfuscatedAccountId } : {}),
+	};
+	if (request.productType !== 'subscription') {
+		return { request: { google }, type: 'in-app' };
+	}
+
+	const replacementMode = request.prorationMode
+		? REPLACEMENT_MODES[request.prorationMode]
+		: undefined;
+	return {
+		request: {
+			google: {
+				...google,
+				...(request.offerKey
+					? {
+							subscriptionOffers: [{ sku: request.storeProductId, offerToken: request.offerKey }],
+						}
+					: {}),
+				// A plan change: the token of the purchase being replaced, and — for
+				// the replacement mode to apply — its product id (Billing 8.1+).
+				...(request.replacePurchaseToken ? { purchaseToken: request.replacePurchaseToken } : {}),
+				...(request.replacePurchaseToken && request.replaceStoreProductId && replacementMode
+					? {
+							subscriptionProductReplacementParams: {
+								oldProductId: request.replaceStoreProductId,
+								replacementMode,
+							},
+						}
+					: {}),
+			},
+		},
+		type: 'subs',
+	};
+}
+
+/** Play's `PurchaseState`: 0 unspecified, 1 purchased, 2 pending. */
+const PLAY_STATE_PURCHASED = 1;
+const PLAY_STATE_PENDING = 2;
+
+// Required lazily (rn-core's lazy peer) so importing the package does not require
+// the native module.
+const iapPeer = lazyPeer('react-native-iap', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-iap') as IapModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function loadModule(): IapModule {
+	return iapPeer.require(
+		(peer, cause) =>
+			new PaymentError({
+				code: 'PAYMENT_UNAVAILABLE',
+				message: `${peer} is not installed or its native module is not linked`,
+				operation: 'initialize',
+				cause: redact(cause),
+			}),
+	);
+}
+
+function toMicros(value: string | number | undefined): number {
+	if (typeof value === 'number') {
+		return value;
+	}
+	if (typeof value === 'string') {
+		const parsed = Number.parseInt(value, 10);
+		return Number.isFinite(parsed) ? parsed : 0;
+	}
+	return 0;
+}
+
+function normalizeProduct(raw: RawProduct, productType: ProductType): ProviderProduct {
+	const oneTime = raw.oneTimePurchaseOfferDetails;
+	const currencyCode = oneTime?.priceCurrencyCode ?? raw.currencyCode ?? raw.currency ?? '';
+
+	return {
+		storeProductId: raw.id ?? raw.productId ?? '',
+		productType,
+		title: raw.title ?? raw.name ?? '',
+		description: raw.description ?? '',
+		// Store-formatted, never built here: only the store knows the right currency
+		// symbol, separator, and placement for the user's locale (FR-028).
+		formattedPrice: oneTime?.formattedPrice ?? raw.displayPrice ?? raw.localizedPrice ?? '',
+		currencyCode,
+		priceAmountMicros: toMicros(oneTime?.priceAmountMicros ?? raw.price),
+		offers: (raw.subscriptionOfferDetails ?? []).map(offer => normalizeOffer(offer, currencyCode)),
+	};
+}
+
+function normalizeOffer(
+	offer: RawSubscriptionOffer,
+	fallbackCurrency: string,
+): ProviderProduct['offers'][number] {
+	const phases = offer.pricingPhases?.pricingPhaseList ?? [];
+	// The last phase is the recurring price; earlier ones are trial or
+	// introductory. Play orders them that way.
+	const recurring = phases[phases.length - 1];
+	const intro = phases.length > 1 ? phases[0] : undefined;
+	const isFreeTrial = intro !== undefined && toMicros(intro.priceAmountMicros) === 0;
+
+	return {
+		offerKey: offer.offerToken ?? offer.offerId ?? offer.basePlanId ?? '',
+		billingPeriod: recurring?.billingPeriod ?? '',
+		formattedPrice: recurring?.formattedPrice ?? '',
+		priceAmountMicros: toMicros(recurring?.priceAmountMicros),
+		currencyCode: recurring?.priceCurrencyCode ?? fallbackCurrency,
+		trialPeriod: isFreeTrial ? intro?.billingPeriod : undefined,
+		introductoryPrice:
+			intro && !isFreeTrial
+				? {
+						formattedPrice: intro.formattedPrice ?? '',
+						period: intro.billingPeriod ?? '',
+						cycles: intro.billingCycleCount ?? 1,
+					}
+				: undefined,
+		// Play decides eligibility by only returning offers the user qualifies for,
+		// so forwarding `true` reports the store's determination rather than
+		// computing our own (FR-026).
+		isEligible: true,
+	};
+}
+
+/**
+ * Reads the purchase state from whichever field the binding filled.
+ *
+ * Pending is preserved, never flattened to purchased: that distinction is what
+ * stops an entitlement being granted for money that has not arrived (FR-037).
+ * And an unrecognized or missing state is `unspecified`, never `purchased`.
+ *
+ * 0.1.0 read only Play's numeric state and treated anything else as purchased.
+ * The 16.x binding hands JavaScript the *string* state and does not carry the
+ * numeric one across, so on a device every pending purchase arrived as a string,
+ * fell through to the default, and was granted. Unit tests could not see it: they
+ * drive the fake store, which never passes through here.
+ */
+export function toProviderPurchaseState(
+	raw: Pick<RawPurchase, 'purchaseStateAndroid' | 'purchaseState'>,
+): ProviderPurchase['state'] {
+	let numeric: number | undefined;
+	if (typeof raw.purchaseStateAndroid === 'number') {
+		numeric = raw.purchaseStateAndroid;
+	} else if (typeof raw.purchaseState === 'number') {
+		numeric = raw.purchaseState;
+	}
+	if (numeric !== undefined) {
+		if (numeric === PLAY_STATE_PENDING) {
+			return 'pending';
+		}
+		return numeric === PLAY_STATE_PURCHASED ? 'purchased' : 'unspecified';
+	}
+
+	switch (typeof raw.purchaseState === 'string' ? raw.purchaseState.toLowerCase() : '') {
+		case 'purchased':
+		case 'restored':
+			return 'purchased';
+		case 'pending':
+		case 'deferred':
+			return 'pending';
+		default:
+			return 'unspecified';
+	}
+}
+
+function normalizePurchase(raw: RawPurchase): ProviderPurchase {
+	return {
+		storeProductId: raw.productId ?? raw.ids?.[0] ?? '',
+		transactionId: raw.id ?? raw.transactionId ?? raw.purchaseToken ?? '',
+		token: raw.purchaseToken ?? '',
+		state: toProviderPurchaseState(raw),
+		purchasedAt: raw.transactionDate ?? Date.now(),
+		isAcknowledged: raw.isAcknowledgedAndroid ?? raw.isAcknowledged ?? false,
+		expiresAt: raw.expirationDateAndroid,
+		willAutoRenew: raw.autoRenewingAndroid ?? raw.isAutoRenewing,
+		// Opaque material for the app's backend. Carried here and handed to the
+		// validation hook only — never logged or put in an event (FR-074).
+		verificationPayload: raw.transactionReceipt ?? raw.dataAndroid,
+	};
+}
+
+/** Maps a binding error code onto the port's vocabulary, so no store code escapes. */
+function mapErrorCode(code: string | undefined): ProviderFailureReason {
+	switch (code) {
+		case 'E_USER_CANCELLED':
+		case 'user-cancelled':
+			return 'user_cancelled';
+		case 'E_ALREADY_OWNED':
+		case 'already-owned':
+		case 'item-already-owned':
+			return 'already_owned';
+		case 'E_ITEM_UNAVAILABLE':
+		case 'item-unavailable':
+		case 'sku-not-found':
+			return 'unknown_product';
+		case 'E_NOT_PREPARED':
+		case 'not-prepared':
+			return 'not_ready';
+		case 'E_NETWORK_ERROR':
+		case 'network-error':
+			return 'network_error';
+		case 'E_DEFERRED_PAYMENT':
+			// Not a failure — a pending purchase. The caller resolves it from the
+			// purchase update rather than from this error.
+			return 'store_error';
+		default:
+			return 'store_error';
+	}
+}
+
+const ANDROID_CAPABILITIES: ProviderCapabilities = {
+	supportsSubscriptions: true,
+	supportsPlanChange: true,
+	supportsPriceChangeConfirmation: false,
+	/**
+	 * False, and this is a platform fact rather than a gap in this adapter.
+	 *
+	 * Client-side Play Billing cannot separate grace period from account 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. The entitlement layer reads this flag and reports
+	 * `indeterminate` rather than inventing a distinction (research.md R5).
+	 */
+	reportsGraceAndHoldDistinctly: false,
+	supportsExternalTransactions: false,
+	/** This one really does move money, which is what arms the environment guard. */
+	createsRealTransactions: true,
+	/** The outcome event comes only when the user leaves Play's purchase UI. */
+	purchaseOutcomeIncludesStoreTime: true,
+};
+
+export interface IapAdapterOptions {
+	/** Injected in tests that need to drive the mapping without the native module. */
+	module?: IapModule;
+}
+
+export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort {
+	let iap: IapModule | undefined = options.module;
+
+	/** Tracked here, never read from the binding — see the openiap#408 note above. */
+	let connected = false;
+
+	const connectionListeners = createListenerSet<[boolean, string | undefined]>();
+	const purchaseListeners = createListenerSet<[ProviderPurchase]>();
+	/** Only an in-flight `launchPurchase` listens here; see there. */
+	const purchaseErrorListeners = createListenerSet<[RawPurchaseError]>();
+	let updateSub: { remove(): void } | undefined;
+	let errorSub: { remove(): void } | undefined;
+
+	const module = (): IapModule => {
+		if (!iap) {
+			iap = loadModule();
+		}
+		return iap;
+	};
+
+	const notifyConnection = (next: boolean, reason?: string): void => {
+		if (connected === next) {
+			return;
+		}
+		connected = next;
+		connectionListeners.notify(next, reason);
+	};
+
+	const attachListeners = (): void => {
+		// Every connect attaches, so whatever an earlier connect left must go first.
+		// Overwriting the handles orphaned the old native listeners, which kept
+		// firing — every purchase update reached the engine once per connect.
+		detachListeners();
+		const mod = module();
+		updateSub = mod.purchaseUpdatedListener(raw => {
+			purchaseListeners.notify(normalizePurchase(raw));
+		});
+		errorSub = mod.purchaseErrorListener(error => {
+			// A `not-prepared` error is the one signal the binding gives that the
+			// service went away underneath us, so it is treated as a disconnect
+			// rather than as a purchase failure.
+			if (mapErrorCode(error.code) === 'not_ready') {
+				notifyConnection(false, 'not_prepared');
+			}
+			purchaseErrorListeners.notify(error);
+		});
+	};
+
+	const detachListeners = (): void => {
+		updateSub?.remove();
+		updateSub = undefined;
+		errorSub?.remove();
+		errorSub = undefined;
+	};
+
+	return {
+		async connect(): Promise<ProviderConnectOutcome> {
+			try {
+				const mod = module();
+				// Always a full cycle. The binding's own reconnect has reported success
+				// without rebuilding anything, so we never rely on it (openiap#408).
+				if (connected) {
+					await mod.endConnection().catch(() => undefined);
+					connected = false;
+				}
+				const ok = await mod.initConnection();
+				if (!ok) {
+					return {
+						ok: false,
+						reason: 'no_billing_service',
+						retryable: true,
+					};
+				}
+				attachListeners();
+				notifyConnection(true);
+				return { ok: true };
+			} catch (error) {
+				const code = (error as { code?: string }).code;
+				// A missing or too-old Play Services install is not the same as a
+				// transient error, and the app shows different things for each (FR-021).
+				if (code === 'E_IAP_NOT_AVAILABLE' || code === 'iap-not-available') {
+					return { ok: false, reason: 'no_billing_service', retryable: false };
+				}
+				if (code === 'E_SERVICE_ERROR') {
+					return {
+						ok: false,
+						reason: 'billing_service_outdated',
+						retryable: true,
+					};
+				}
+				return { ok: false, reason: 'store_error', retryable: true };
+			}
+		},
+
+		async disconnect(): Promise<void> {
+			detachListeners();
+			try {
+				await module().endConnection();
+			} catch {
+				// Already down; nothing to tear down.
+			}
+			notifyConnection(false, 'disconnect');
+		},
+
+		observeConnection(listener): Unsubscribe {
+			return connectionListeners.add(listener);
+		},
+
+		async queryProducts(
+			storeProductIds: StoreProductId[],
+			productType: ProductType,
+		): Promise<ProviderProduct[]> {
+			const raw = await module().fetchProducts({
+				skus: storeProductIds,
+				type: productType === 'subscription' ? 'subs' : 'in-app',
+			});
+			return raw.map(product => normalizeProduct(product, productType));
+		},
+
+		async queryOwned(): Promise<ProviderPurchase[]> {
+			const raw = await module().getAvailablePurchases();
+			// Pending purchases are mapped through, flagged rather than filtered: the
+			// engine needs to see them to raise the pending signal (FR-038).
+			return raw.map(normalizePurchase);
+		},
+
+		/**
+		 * Settles on the first outcome event for this product: a purchase update
+		 * (bought or pending) or a purchase error (cancelled, already owned, …).
+		 *
+		 * The binding's promise is not the outcome: on Android it resolves with an
+		 * empty list when the flow ends, whatever happened. Its listeners also feed
+		 * `observePurchases`, so the engine sees a bought purchase twice — here and
+		 * as a store update — and grants it once (FR-044).
+		 */
+		launchPurchase(request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> {
+			const sku = request.storeProductId;
+			return new Promise<ProviderPurchaseOutcome>(resolve => {
+				let settled = false;
+				let grace: ReturnType<typeof setTimeout> | undefined;
+
+				const onPurchase = (purchase: ProviderPurchase): void => {
+					if (purchase.storeProductId === sku) {
+						finish({ ok: true, purchase });
+					}
+				};
+				const onError = (error: RawPurchaseError): void => {
+					if (error.productId && error.productId !== sku) {
+						return;
+					}
+					finish({ ok: false, reason: mapErrorCode(error.code), detail: error.code });
+				};
+				const fail = (error: unknown): void => {
+					const code = (error as { code?: string } | undefined)?.code;
+					finish({ ok: false, reason: mapErrorCode(code), detail: code });
+				};
+				function finish(outcome: ProviderPurchaseOutcome): void {
+					if (settled) {
+						return;
+					}
+					settled = true;
+					clearTimeout(grace);
+					stopPurchase();
+					stopError();
+					resolve(outcome);
+				}
+
+				const stopPurchase = purchaseListeners.add(onPurchase);
+				const stopError = purchaseErrorListeners.add(onError);
+				try {
+					module()
+						.requestPurchase(toRequestProps(request))
+						.then(() => {
+							if (!settled) {
+								grace = setTimeout(
+									() =>
+										finish({
+											ok: false,
+											reason: 'store_error',
+											detail: 'no purchase event',
+										}),
+									RESULT_EVENT_GRACE_MS,
+								);
+							}
+						}, fail);
+				} catch (error) {
+					fail(error);
+				}
+			});
+		},
+
+		observePurchases(listener): Unsubscribe {
+			return purchaseListeners.add(listener);
+		},
+
+		async acknowledge(token: ProviderToken): Promise<void> {
+			// Idempotent at the store: acknowledging an already-acknowledged purchase
+			// is accepted, which is what FR-044 relies on.
+			await module().finishTransaction({
+				purchase: { purchaseToken: token },
+				isConsumable: false,
+			});
+		},
+
+		async consume(token: ProviderToken): Promise<void> {
+			await module().finishTransaction({
+				purchase: { purchaseToken: token },
+				isConsumable: true,
+			});
+		},
+
+		async openSubscriptionManagement(storeProductId?: StoreProductId): Promise<void> {
+			// The store's own screen. Platforms forbid a self-built cancellation
+			// screen, so there is deliberately no alternative path here (FR-066).
+			const mod = module();
+			if (!mod.deepLinkToSubscriptions) {
+				return;
+			}
+			await mod.deepLinkToSubscriptions({ skuAndroid: storeProductId });
+		},
+
+		async confirmPriceChange(): Promise<ProviderPriceChangeOutcome> {
+			// Play has no client-side price-change confirmation flow; it notifies the
+			// user itself. Reported as unsupported rather than faked, matching
+			// `supportsPriceChangeConfirmation: false` (FR-067).
+			return { ok: false, reason: 'store_error' };
+		},
+
+		capabilities: () => ANDROID_CAPABILITIES,
+	};
+}