@chipmobilesdk/rn-payment 0.1.0 → 0.2.0

package/src/adapter/iap-adapter.ts

@@ -1,516 +1,547 @@
-/**
- * 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.
- *
- * ## Verification status
- *
- * The binding is **not yet installed** — the root `react-native-nitro-modules`
- * bump it requires is held pending approval (see specs/013-rn-payment-sdk/plan.md,
- * Post-Implementation Notes). So the call shapes below are written against
- * `react-native-iap` 16.x as documented, and **every one must be verified against
- * the installed package** before this adapter is trusted on a device. The module
- * is required lazily and the surface it needs is declared explicitly in
- * `IapModule`, so a mismatch surfaces here rather than deep in the engine.
- *
- * No test exercises this file: the whole suite runs against the fake store, and
- * the IAP test double throws on every call precisely so that reaching this code in
- * a test fails loudly instead of passing against a stub.
- *
- * ## 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 { 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[]>;
-	requestPurchase(params: unknown): Promise<unknown>;
-	finishTransaction(params: {
-		purchase: unknown;
-		isConsumable?: boolean;
-	}): Promise<unknown>;
-	purchaseUpdatedListener(
-		listener: (purchase: RawPurchase) => void,
-	): { remove(): void };
-	purchaseErrorListener(
-		listener: (error: { code?: string; message?: string }) => 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;
-	purchaseState?: number | string;
-	transactionDate?: number;
-	isAcknowledgedAndroid?: boolean;
-	isAcknowledged?: boolean;
-	autoRenewingAndroid?: boolean;
-	isAutoRenewing?: boolean;
-	expirationDateAndroid?: number;
-	transactionReceipt?: string;
-	dataAndroid?: string;
-}
-
-/** 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,
-	};
-}
-
-function normalizePurchase(raw: RawPurchase): ProviderPurchase {
-	const state = raw.purchaseStateAndroid ?? raw.purchaseState;
-	const numericState = typeof state === 'number' ? state : PLAY_STATE_PURCHASED;
-
-	return {
-		storeProductId: raw.productId ?? raw.ids?.[0] ?? '',
-		transactionId: raw.id ?? raw.transactionId ?? raw.purchaseToken ?? '',
-		token: raw.purchaseToken ?? '',
-		// Pending is preserved, never flattened to purchased: that distinction is
-		// what stops an entitlement being granted for money that has not arrived
-		// (FR-037).
-		state:
-			numericState === PLAY_STATE_PENDING
-				? 'pending'
-				: numericState === PLAY_STATE_PURCHASED
-					? 'purchased'
-					: 'unspecified',
-		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 'item-already-owned':
-			return 'already_owned';
-		case 'E_ITEM_UNAVAILABLE':
-		case 'item-unavailable':
-			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,
-};
-
-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>();
-	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 => {
-		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');
-			}
-		});
-	};
-
-	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);
-		},
-
-		async launchPurchase(
-			request: ProviderPurchaseRequest,
-		): Promise<ProviderPurchaseOutcome> {
-			try {
-				const isSubscription = request.productType === 'subscription';
-				const result = await module().requestPurchase({
-					request: {
-						android: {
-							skus: [request.storeProductId],
-							obfuscatedAccountIdAndroid: request.obfuscatedAccountId,
-							...(isSubscription && request.offerKey
-								? {
-										subscriptionOffers: [
-											{
-												sku: request.storeProductId,
-												offerToken: request.offerKey,
-											},
-										],
-									}
-								: {}),
-							...(request.replaceStoreProductId
-								? {
-										purchaseTokenAndroid: request.replaceStoreProductId,
-										replacementModeAndroid: request.prorationMode,
-									}
-								: {}),
-						},
-					},
-					type: isSubscription ? 'subs' : 'in-app',
-				});
-
-				// The binding may resolve with the purchase, or resolve empty and deliver
-				// it through the update listener. Both are handled: the engine also
-				// ingests listener-delivered purchases, so neither path loses one.
-				const raw = Array.isArray(result) ? result[0] : result;
-				if (!raw) {
-					return { ok: false, reason: 'store_error', detail: 'no purchase returned' };
-				}
-				return { ok: true, purchase: normalizePurchase(raw as RawPurchase) };
-			} catch (error) {
-				const code = (error as { code?: string }).code;
-				return { ok: false, reason: mapErrorCode(code), detail: code };
-			}
-		},
-
-		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.
+ *
+ * ## Verification status
+ *
+ * The binding is **not yet installed** — the root `react-native-nitro-modules`
+ * bump it requires is held pending approval (see specs/013-rn-payment-sdk/plan.md,
+ * Post-Implementation Notes). So the call shapes below are written against
+ * `react-native-iap` 16.x as documented, and **every one must be verified against
+ * the installed package** before this adapter is trusted on a device. The module
+ * is required lazily and the surface it needs is declared explicitly in
+ * `IapModule`, so a mismatch surfaces here rather than deep in the engine.
+ *
+ * No test exercises this file: the whole suite runs against the fake store, and
+ * the IAP test double throws on every call precisely so that reaching this code in
+ * a test fails loudly instead of passing against a stub.
+ *
+ * ## 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 { 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[]>;
+	requestPurchase(params: unknown): Promise<unknown>;
+	finishTransaction(params: {
+		purchase: unknown;
+		isConsumable?: boolean;
+	}): Promise<unknown>;
+	purchaseUpdatedListener(
+		listener: (purchase: RawPurchase) => void,
+	): { remove(): void };
+	purchaseErrorListener(
+		listener: (error: { code?: string; message?: string }) => 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;
+}
+
+/** 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 'item-already-owned':
+			return 'already_owned';
+		case 'E_ITEM_UNAVAILABLE':
+		case 'item-unavailable':
+			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,
+};
+
+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>();
+	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 => {
+		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');
+			}
+		});
+	};
+
+	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);
+		},
+
+		async launchPurchase(
+			request: ProviderPurchaseRequest,
+		): Promise<ProviderPurchaseOutcome> {
+			try {
+				const isSubscription = request.productType === 'subscription';
+				const result = await module().requestPurchase({
+					request: {
+						android: {
+							skus: [request.storeProductId],
+							obfuscatedAccountIdAndroid: request.obfuscatedAccountId,
+							...(isSubscription && request.offerKey
+								? {
+										subscriptionOffers: [
+											{
+												sku: request.storeProductId,
+												offerToken: request.offerKey,
+											},
+										],
+									}
+								: {}),
+							...(request.replaceStoreProductId
+								? {
+										purchaseTokenAndroid: request.replaceStoreProductId,
+										replacementModeAndroid: request.prorationMode,
+									}
+								: {}),
+						},
+					},
+					type: isSubscription ? 'subs' : 'in-app',
+				});
+
+				// The binding may resolve with the purchase, or resolve empty and deliver
+				// it through the update listener. Both are handled: the engine also
+				// ingests listener-delivered purchases, so neither path loses one.
+				const raw = Array.isArray(result) ? result[0] : result;
+				if (!raw) {
+					return { ok: false, reason: 'store_error', detail: 'no purchase returned' };
+				}
+				return { ok: true, purchase: normalizePurchase(raw as RawPurchase) };
+			} catch (error) {
+				const code = (error as { code?: string }).code;
+				return { ok: false, reason: mapErrorCode(code), detail: code };
+			}
+		},
+
+		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,
+	};
+}