@chipmobilesdk/rn-payment 0.4.1 → 0.6.0

package/src/adapter/iap-adapter.ts

@@ -36,13 +36,23 @@
  * shortcut.
  */
 
+import { createListenerSet, lazyPeer } from '@chipmobilesdk/rn-core';
+
 import type { RequestPurchaseProps, SubscriptionReplacementModeAndroid } from 'react-native-iap';
 
 import type { ProductType, Unsubscribe } from '../config/types';
+import {
+	mapErrorCode,
+	normalizeProduct,
+	normalizePurchase,
+	type RawProduct,
+	type RawPurchase,
+	type RawPurchaseError,
+} from './iapShapes';
+import { PaymentError, redact } from '../diagnostics/errors';
 import type {
 	ProviderCapabilities,
 	ProviderConnectOutcome,
-	ProviderFailureReason,
 	ProviderPort,
 	ProviderPriceChangeOutcome,
 	ProviderProduct,
@@ -53,6 +63,10 @@ import type {
 	StoreProductId,
 } from './port';
 
+// Translation lives in `iapShapes`; it is published from here, where every
+// consumer has always imported it from.
+export { toProviderPurchaseState } from './iapShapes';
+
 /**
  * Exactly what this adapter needs from the binding.
  *
@@ -75,67 +89,6 @@ interface IapModule {
 	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
@@ -190,162 +143,25 @@ export function toRequestProps(request: ProviderPurchaseRequest): RequestPurchas
 	};
 }
 
-/** 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;
+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;
 	}
-	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';
-	}
+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),
+			}),
+	);
 }
 
 const ANDROID_CAPABILITIES: ProviderCapabilities = {
@@ -380,10 +196,10 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 	/** 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>();
+	const connectionListeners = createListenerSet<[boolean, string | undefined]>();
+	const purchaseListeners = createListenerSet<[ProviderPurchase]>();
 	/** Only an in-flight `launchPurchase` listens here; see there. */
-	const purchaseErrorListeners = new Set<(error: RawPurchaseError) => void>();
+	const purchaseErrorListeners = createListenerSet<[RawPurchaseError]>();
 	let updateSub: { remove(): void } | undefined;
 	let errorSub: { remove(): void } | undefined;
 
@@ -399,9 +215,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			return;
 		}
 		connected = next;
-		for (const listener of connectionListeners) {
-			listener(next, reason);
-		}
+		connectionListeners.notify(next, reason);
 	};
 
 	const attachListeners = (): void => {
@@ -411,10 +225,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		detachListeners();
 		const mod = module();
 		updateSub = mod.purchaseUpdatedListener(raw => {
-			const purchase = normalizePurchase(raw);
-			for (const listener of purchaseListeners) {
-				listener(purchase);
-			}
+			purchaseListeners.notify(normalizePurchase(raw));
 		});
 		errorSub = mod.purchaseErrorListener(error => {
 			// A `not-prepared` error is the one signal the binding gives that the
@@ -423,9 +234,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			if (mapErrorCode(error.code) === 'not_ready') {
 				notifyConnection(false, 'not_prepared');
 			}
-			for (const listener of purchaseErrorListeners) {
-				listener(error);
-			}
+			purchaseErrorListeners.notify(error);
 		});
 	};
 
@@ -486,15 +295,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		},
 
 		observeConnection(listener): Unsubscribe {
-			connectionListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				connectionListeners.delete(listener);
-			};
+			return connectionListeners.add(listener);
 		},
 
 		async queryProducts(
@@ -551,13 +352,13 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 					}
 					settled = true;
 					clearTimeout(grace);
-					purchaseListeners.delete(onPurchase);
-					purchaseErrorListeners.delete(onError);
+					stopPurchase();
+					stopError();
 					resolve(outcome);
 				}
 
-				purchaseListeners.add(onPurchase);
-				purchaseErrorListeners.add(onError);
+				const stopPurchase = purchaseListeners.add(onPurchase);
+				const stopError = purchaseErrorListeners.add(onError);
 				try {
 					module()
 						.requestPurchase(toRequestProps(request))
@@ -581,15 +382,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		},
 
 		observePurchases(listener): Unsubscribe {
-			purchaseListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				purchaseListeners.delete(listener);
-			};
+			return purchaseListeners.add(listener);
 		},
 
 		async acknowledge(token: ProviderToken): Promise<void> {

package/src/adapter/iapShapes.ts

@@ -0,0 +1,232 @@
+/**
+ * The binding's shapes, and their translation into the port's vocabulary
+ * (PAY-12).
+ *
+ * The binding speaks Google Play: prices as micros in strings, offer tokens,
+ * numeric purchase states, store error codes. The port speaks this package's
+ * own. Keeping the translation here, with no I/O, no listeners and no module
+ * loading, is what makes it checkable against recorded payloads — and leaves
+ * the adapter next door about the calls it actually makes.
+ *
+ * The raw types are declared narrowly on purpose: they document the coupling,
+ * and a binding upgrade that changes one of these shapes fails to typecheck
+ * here rather than failing silently on a user's device.
+ */
+import type { ProductType } from '../config/types';
+import type { ProviderFailureReason, ProviderProduct, ProviderPurchase } from './port';
+
+export 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[];
+}
+
+export interface RawSubscriptionOffer {
+	offerToken?: string;
+	offerId?: string;
+	basePlanId?: string;
+	pricingPhases?: {
+		pricingPhaseList?: Array<{
+			formattedPrice?: string;
+			priceAmountMicros?: string | number;
+			priceCurrencyCode?: string;
+			billingPeriod?: string;
+			recurrenceMode?: number;
+			billingCycleCount?: number;
+		}>;
+	};
+}
+
+export 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. */
+export interface RawPurchaseError {
+	code?: string;
+	message?: string;
+	productId?: string | null;
+}
+
+/** 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.
+
+export 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;
+}
+
+export 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)),
+	};
+}
+
+export 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';
+	}
+}
+
+export 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. */
+export 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';
+	}
+}

package/src/config/types.ts

@@ -130,6 +130,14 @@ export interface PaymentConfig {
 	 * proceed (FR-015).
 	 */
 	isProductionBuild: boolean;
+	/**
+	 * Lets a non-production build complete purchases through the real store, so a
+	 * Play license tester can buy on a debug build (PAY-16). Accepted only with
+	 * `environment: 'test'`; any other environment rejects it at startup. License
+	 * testers are not charged; any other account on the device would be, so keep
+	 * it out of builds that reach real users.
+	 */
+	allowStoreTestPurchases?: boolean;
 	/**
 	 * Global sell switch. When false, purchases report `disabled` but entitlements
 	 * already held stay readable — turning off selling is not the same as taking

package/src/config/validate.ts

@@ -199,6 +199,16 @@ export function validateConfig(
  * continuing silently is exactly the failure this package exists to prevent.
  */
 export function assertEnvironmentSafe(config: PaymentConfig): void {
+	if (config.allowStoreTestPurchases === true && config.environment !== 'test') {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CONFIG',
+			message:
+				`allowStoreTestPurchases is only accepted with environment "test", not ` +
+				`"${config.environment}": it exists for license testers, not for real users.`,
+			operation: 'configure',
+			offenders: ['allowStoreTestPurchases'],
+		});
+	}
 	if (config.environment === 'production' && !config.isProductionBuild) {
 		throw new PaymentConfigError({
 			code: 'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
@@ -213,12 +223,17 @@ export function assertEnvironmentSafe(config: PaymentConfig): void {
 }
 
 /**
- * Whether this configuration may hand a real purchase to a real store (FR-014).
+ * Whether this configuration may hand a purchase to a real store (FR-014).
  *
- * False outside production regardless of what else is configured. The engine
- * records each refusal in observable status so a test can assert the block
- * happened — the difference between a guarantee and a hope.
+ * True in a production build configured for production, and in a `test`
+ * environment that opted in with `allowStoreTestPurchases` (PAY-16). False
+ * everywhere else. The engine records each refusal in observable status so a
+ * test can assert the block happened — the difference between a guarantee and a
+ * hope.
  */
 export function mayCreateRealTransaction(config: PaymentConfig): boolean {
+	if (config.environment === 'test' && config.allowStoreTestPurchases === true) {
+		return true;
+	}
 	return config.environment === 'production' && config.isProductionBuild;
 }