@chipmobilesdk/rn-payment 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,71 @@ product keys, error codes, event names, state values, message keys, and the
 public API shape are this package's contract: renaming any of them is a breaking
 change.
 
+## [0.3.1] — 2026-10-25
+
+Patch release. **Upgrade before shipping on Android**: with `0.3.0` no purchase could
+complete on a device. Found on a Galaxy S25 Ultra with a licence-tester account, in the
+first app to buy through this package (Task Manager, internal testing track).
+
+### Fixed
+
+- **Every purchase failed before Play opened.** The adapter sent
+  `request: { android: { skus, obfuscatedAccountIdAndroid } }`, the request shape from
+  `react-native-iap`'s documentation before 16.7. The 16.7 binding reads
+  `request.google` and rejected the call with `empty-sku-list`; the app saw a store
+  error. The request now uses `google` and `obfuscatedAccountId`, and is typed with the
+  binding's own `RequestPurchaseProps`, so a renamed key fails to typecheck.
+- **A completed purchase would have been reported as a store error.** On Android
+  `requestPurchase` resolves with an empty list when the flow ends, whatever happened;
+  the outcome arrives only through `purchaseUpdatedListener` / `purchaseErrorListener`.
+  The adapter read the resolved value, so it would have reported `store_error` for
+  every purchase, while Play delivered the purchase separately. `launchPurchase` now
+  settles on the first outcome event for the product (bought, pending, or an error).
+- **"Already owned" was a generic store error.** The adapter matched
+  `item-already-owned`; 16.7 sends `already-owned`. A reinstall that taps Buy again
+  now gets `already_owned` and the self-repairing sync (FR-033). `sku-not-found` now
+  maps to `unknown_product`.
+- **The launch timeout cut into the user's time in Play (FR-035).** Because the
+  binding reports nothing until the flow ends, the 30-second "opening the store
+  surface" timeout covered the time the user spends choosing a payment method. The
+  engine no longer applies it to a provider whose outcome includes that time (the Play
+  adapter); the binding always ends the flow with an event, so the call cannot hang.
+- **Plan changes sent the removed 16.6 fields.** A plan change now sends the replaced
+  purchase's token as `purchaseToken` and, with a proration mode,
+  `subscriptionProductReplacementParams` (old product id + replacement mode).
+
+### Changed
+
+- Peer `react-native-iap` is now `>=16.7.3 <17`, the version this adapter was verified
+  against (was `>=16.6.1 <17`, never verified).
+- Internal: `ProviderPurchaseRequest.replaceStoreProductId` now holds the replaced
+  product's id and the token moved to `replacePurchaseToken` (it held the token before);
+  `ProviderCapabilities` gained `purchaseOutcomeIncludesStoreTime`. Neither type is
+  public API. The fake store keeps `false`, so launch-timeout tests behave as before.
+
+### Added
+
+- `__tests__/iap-adapter.test.ts`: the adapter against a fake binding that validates
+  and resolves as 16.7.3 does — request shape, event-based outcomes, error mapping, the
+  no-event fallback.
+
+## [0.3.0] — 2026-10-13
+
+Documentation release: the README and the agent skill now match the code `0.2.1` shipped.
+**No code, API, storage or behaviour change** — upgrading from `0.2.1` changes nothing at
+runtime. Released as its own version so the skill a consuming app syncs (`packageVersion`)
+always matches the package it came from.
+
+### Changed
+
+- README `### Migrating 0.1.0 to 0.2.0`: no longer claims `0.1.0` persisted pending records.
+  On a device nothing persisted before `0.2.1`; the section now says to use `0.2.1` or
+  later and what a device first running it does (empty record, `unknown` until the first
+  sync, never a false `not_entitled`).
+- README intro: "Android only for now" instead of a version-pinned phrase.
+- Skill: "Require `0.2.1` or later" under the upgrade notes, with the reason; the public
+  API heading names `v0.3.0` (the surface is unchanged since `0.2.0`).
+
 ## [0.2.1] — 2026-10-12
 
 Patch release. **Upgrade before shipping**: on a device, `0.2.0` and earlier persisted

package/README.md

@@ -1,7 +1,7 @@
 # @chipmobilesdk/rn-payment
 
 Reusable in-app payment and entitlement capability for ChipMobileSdk-family React
-Native apps. Android only in 0.2.0, via Google Play Billing, behind a contract
+Native apps. Android only for now, via Google Play Billing, behind a contract
 that is neutral with respect to platform and store.
 
 **The package owns capability. Your app owns policy.** The package gives you a
@@ -112,7 +112,7 @@ Verified against this repository's toolchain, not assumed:
 | Node | >= 22.11.0 |
 | Android `minSdk` / `compileSdk` / `targetSdk` | 24 / 36 / 36 |
 | Kotlin | 2.1.20 |
-| `react-native-iap` | >= 16.6.1 < 17 |
+| `react-native-iap` | >= 16.7.3 < 17 (verified 16.7.3) |
 | `react-native-mmkv` | >= 4.0.0 |
 | `react-native-nitro-modules` | >= 0.36.5 |
 
@@ -120,16 +120,18 @@ Verified against this repository's toolchain, not assumed:
 requirement and the bundled Play Billing version move on majors, so a major bump
 needs re-verification rather than silent adoption.
 
-> ⚠️ **The Android adapter is written but not yet verified on a device.** Its call
-> shapes follow `react-native-iap` 16.x as documented, and the surface it depends on
-> is declared explicitly in a local `IapModule` interface so a mismatch fails at
-> typecheck rather than at runtime on a user's device. Verify it on a device before
-> shipping.
+> ⚠️ **Use `0.3.1` or later.** Up to `0.3.0` the Android adapter followed
+> `react-native-iap` 16.x as documented, not as installed, and on a device **no
+> purchase could complete**: the request used the pre-16.7 `android` key, which the
+> binding rejects before Play opens. `0.3.1` was checked call by call against the
+> installed 16.7.3 source, types its request with the binding's own
+> `RequestPurchaseProps` (a renamed key now fails to typecheck), and is tested
+> against a fake binding that behaves as 16.7.3 does. Still confirm one licence-tester
+> purchase on a device before shipping.
 >
-> One part *has* been checked against an installed binding (16.7.3): how a purchase's
-> state is read. That check found a defect in `0.1.0` — the binding sends the state as
-> a string, the adapter expected a number, and a pending purchase was granted. Fixed
-> in `0.2.0`; see the changelog.
+> Earlier, the same check of how a purchase's state is read found a defect in `0.1.0`
+> — the binding sends the state as a string, the adapter expected a number, and a
+> pending purchase was granted. Fixed in `0.2.0`; see the changelog.
 
 ---
 
@@ -874,9 +876,12 @@ Everything else is additive, and `0.1.0` call sites compile and behave unchanged
 A hand-written `PaymentEngine` implementation, typically a test mock, needs the two
 new methods.
 
-**No storage migration.** The schema stays at version 1: pending records were
-already persisted by `0.1.0`, and `0.2.0` only reads them. A device upgrading with
-a payment in flight sees it in the pending set at first launch.
+**No storage migration.** The schema stays at version 1, and `0.2.0` reads the
+pending records the engine already wrote. **Use `0.2.1` or later**, though: before
+`0.2.1` the store fell back to memory on every device (react-native-mmkv v4 has no
+`MMKV` constructor), so nothing — entitlements included — survived a cold start. A
+device first running `0.2.1` starts from an empty record and rebuilds it at the first
+sync, with `unknown` meanwhile, never a false `not_entitled`.
 
 **Replacing an app-side workaround.** If you kept your own "pending since" marker
 because `0.1.0` could not show a pending payment in a later session, drop it for

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-payment",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"private": false,
 	"license": "UNLICENSED",
 	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",
@@ -41,7 +41,7 @@
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",
-		"react-native-iap": ">=16.6.1 <17",
+		"react-native-iap": ">=16.7.3 <17",
 		"react-native-mmkv": ">=4.0.0",
 		"react-native-nitro-modules": ">=0.36.5"
 	},

package/skills/sdk-rn-payment/SKILL.md

@@ -3,7 +3,7 @@ name: sdk-rn-payment
 description: "In-app payments via @chipmobilesdk/rn-payment: Play Billing one-time/consumable/subscription behind a store-neutral contract, entitlement keys with a required unknown state, pending purchases visible across sessions, guaranteed transaction finalization, per-environment production-transaction blocking. Use when selling a feature, gating on an entitlement, showing a payment still pending after a restart, debugging a purchase that returns environment_blocked or an entitlement stuck at unknown, mapping Play products to entitlement keys, or answering a Data safety question about purchases."
 metadata:
   package: "@chipmobilesdk/rn-payment"
-  packageVersion: "0.2.1"
+  packageVersion: "0.3.1"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -93,7 +93,7 @@ Unlike `@chipmobilesdk/rn-ads`, there is **no test-id substitution**: Play has n
 Call `handleForeground()` yourself on app resume — the package will not guess what
 "foreground" means for a host backgrounded by its own modal or the store's purchase sheet.
 
-## Public API (v0.2.0)
+## Public API (v0.3.1)
 
 Runtime: `createEngine` (throws `PaymentConfigError` on a bad catalog or an unsafe
 environment; everything else returns a typed result) · `createStoreProvider` ·
@@ -131,8 +131,18 @@ Types: `PaymentConfig`, `CatalogEntry`, `ProductType`, `StoreProductIds`,
 
 One compile-time change: `PaymentEventType` gained `'purchase_pending_resolved'`, so an
 exhaustive `switch` needs the case or a `default`. A hand-written `PaymentEngine` mock
-needs the two pending methods. No storage migration — `0.1.0` already persisted pending
-records. Replace any app-side "pending since" marker with `usePendingPurchases`.
+needs the two pending methods. No storage migration (schema unchanged). Replace any
+app-side "pending since" marker with `usePendingPurchases`.
+
+**Require `0.3.1` or later on Android.** Up to `0.3.0` no purchase could complete on a
+device: the adapter sent `react-native-iap`'s pre-16.7 request key (`android`), rejected
+before Play opens, and read the binding's always-empty resolved value instead of its
+outcome events. `0.3.1` needs `react-native-iap` >= 16.7.3. If a purchase returns
+`store_error` at once, check the installed binding against that range first.
+
+**Require `0.2.1` or later.** Earlier versions opened MMKV with the v3 constructor, which
+react-native-mmkv v4 does not have, so on a device nothing persisted: owners read
+`unknown` after every cold start and pending payments vanished after a kill.
 
 **Upgrade before shipping on Android.** In `0.1.0` the adapter misread `react-native-iap`
 16.x's string purchase state, so on a device a pending purchase was granted. `0.2.0`

package/src/adapter/createStoreProvider.ts

@@ -33,6 +33,7 @@ const UNSUPPORTED_CAPABILITIES: ProviderCapabilities = {
 	supportsExternalTransactions: false,
 	/** Nothing here can charge anyone, so the environment guard has nothing to block. */
 	createsRealTransactions: false,
+	purchaseOutcomeIncludesStoreTime: false,
 };
 
 /**

package/src/adapter/iap-adapter.ts

@@ -6,19 +6,24 @@
  * and lets an iOS adapter be added without changing a consumer call (FR-002,
  * FR-007). ESLint enforces that boundary.
  *
- * ## Verification status
+ * ## Verified against react-native-iap 16.7.3
  *
- * 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.
+ * 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:
  *
- * 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.
+ * - 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
  *
@@ -31,6 +36,11 @@
  * shortcut.
  */
 
+import type {
+	RequestPurchaseProps,
+	SubscriptionReplacementModeAndroid,
+} from 'react-native-iap';
+
 import type { ProductType, Unsubscribe } from '../config/types';
 import type {
 	ProviderCapabilities,
@@ -61,7 +71,8 @@ interface IapModule {
 		type: 'in-app' | 'subs';
 	}): Promise<RawProduct[]>;
 	getAvailablePurchases(): Promise<RawPurchase[]>;
-	requestPurchase(params: unknown): Promise<unknown>;
+	/** Typed by the binding itself, so a renamed request key fails to compile. */
+	requestPurchase(params: RequestPurchaseProps): Promise<unknown>;
 	finishTransaction(params: {
 		purchase: unknown;
 		isConsumable?: boolean;
@@ -69,9 +80,9 @@ interface IapModule {
 	purchaseUpdatedListener(
 		listener: (purchase: RawPurchase) => void,
 	): { remove(): void };
-	purchaseErrorListener(
-		listener: (error: { code?: string; message?: string }) => void,
-	): { remove(): void };
+	purchaseErrorListener(listener: (error: RawPurchaseError) => void): {
+		remove(): void;
+	};
 	deepLinkToSubscriptions?(params: { skuAndroid?: string }): Promise<void>;
 }
 
@@ -129,6 +140,75 @@ interface RawPurchase {
 	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;
@@ -272,10 +352,12 @@ function mapErrorCode(code: string | undefined): ProviderFailureReason {
 		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':
@@ -309,6 +391,8 @@ const ANDROID_CAPABILITIES: ProviderCapabilities = {
 	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 {
@@ -326,6 +410,8 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		(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;
 
@@ -361,6 +447,9 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			if (mapErrorCode(error.code) === 'not_ready') {
 				notifyConnection(false, 'not_prepared');
 			}
+			for (const listener of purchaseErrorListeners) {
+				listener(error);
+			}
 		});
 	};
 
@@ -450,49 +539,69 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			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' };
+		/**
+		 * 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);
 				}
-				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 };
-			}
+
+				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 {

package/src/adapter/port.ts

@@ -102,7 +102,12 @@ export interface ProviderPurchaseRequest {
 	offerKey?: string;
 	/** App-supplied, passed straight through. Never generated or stored (FR-034). */
 	obfuscatedAccountId?: string;
-	/** Plan change: the currently-active subscription being replaced. */
+	/**
+	 * Plan change: the token of the active subscription being replaced. The store
+	 * migrates *that* purchase rather than creating a second one (FR-065).
+	 */
+	replacePurchaseToken?: ProviderToken;
+	/** Plan change: the store product id of the subscription being replaced. */
 	replaceStoreProductId?: StoreProductId;
 	prorationMode?: string;
 }
@@ -138,6 +143,18 @@ export interface ProviderCapabilities {
 	 * a development build.
 	 */
 	createsRealTransactions: boolean;
+	/**
+	 * Whether `launchPurchase` settles only once the user has left the store's
+	 * purchase surface.
+	 *
+	 * `true` for the Play adapter: the binding gives no "surface opened" signal and
+	 * reports the outcome only when the flow ends, so the time the user spends in
+	 * Play is inside the call. The engine then does not apply its launch timeout,
+	 * which would otherwise cancel a user still choosing a payment method (FR-035).
+	 * The binding always ends the flow with a result or an error, so the call
+	 * cannot hang. `false` for the fake store, whose launch returns at once.
+	 */
+	purchaseOutcomeIncludesStoreTime: boolean;
 }
 
 export interface ProviderPort {

package/src/engine/purchase.ts

@@ -28,6 +28,9 @@ import type {
 	ProviderFailureReason,
 	ProviderPort,
 	ProviderPurchase,
+	ProviderPurchaseOutcome,
+	ProviderPurchaseRequest,
+	StoreProductId,
 } from '../adapter/port';
 import type { ExclusiveOutcome } from '../core/mutex';
 import { withTimeout } from '../core/mutex';
@@ -291,6 +294,60 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 		return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
 	};
 
+	/** What the store is asked for: the product and, for a plan change, what it replaces. */
+	const launchRequest = (
+		productKey: ProductKey,
+		storeProductId: StoreProductId,
+		options?: InternalPurchaseOptions,
+	): ProviderPurchaseRequest => {
+		const replaceKey = options?.replaceProductKey;
+		return {
+			storeProductId,
+			productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
+			offerKey: options?.offerKey,
+			obfuscatedAccountId: options?.obfuscatedAccountId,
+			// Present only for a plan change. The store needs the token of the
+			// subscription being replaced so it migrates the existing purchase instead
+			// of creating a second one (FR-065), and its product id to apply the
+			// replacement mode.
+			replacePurchaseToken: replaceKey
+				? deps
+						.snapshot()
+						.purchases.find(p => p.productKey === replaceKey && p.state === 'purchased')
+						?.token
+				: undefined,
+			replaceStoreProductId: replaceKey
+				? storeIdForProductKey(resolved, replaceKey)
+				: undefined,
+			prorationMode: options?.prorationMode,
+		};
+	};
+
+	/**
+	 * The launch timeout covers opening the store surface only; time the user
+	 * spends inside it is the store's, not ours (FR-035). A provider that reports
+	 * nothing until the flow ends gives no "opened" moment to time, so it is not
+	 * timed at all: the timeout would cut into the user's time, and that provider
+	 * always ends the flow with a result.
+	 */
+	const launch = (request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> => {
+		const launched = deps.provider.launchPurchase(request);
+		if (deps.provider.capabilities().purchaseOutcomeIncludesStoreTime) {
+			return launched;
+		}
+		return withTimeout(
+			launched,
+			resolved.timeouts.purchaseLaunchMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_TIMEOUT',
+					message: 'Opening the purchase surface timed out',
+					operation: 'purchase',
+					retryable: true,
+				}),
+		);
+	};
+
 	return {
 		async purchase(
 			productKey: ProductKey,
@@ -325,7 +382,6 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 				};
 			}
 
-			const entry = resolved.entries.get(productKey);
 			const correlationId = deps.nextCorrelationId();
 
 			// Exclusive, not single-flight: a second purchase is refused rather than
@@ -335,37 +391,7 @@ export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
 
 				let outcome;
 				try {
-					outcome = await withTimeout(
-						deps.provider.launchPurchase({
-							storeProductId,
-							productType: entry?.productType ?? 'one_time_permanent',
-							offerKey: options?.offerKey,
-							obfuscatedAccountId: options?.obfuscatedAccountId,
-							// Present only for a plan change. The store needs the token of
-							// the subscription being replaced so it migrates the existing
-							// purchase instead of creating a second one (FR-065).
-							replaceStoreProductId: options?.replaceProductKey
-								? deps
-										.snapshot()
-										.purchases.find(
-											p =>
-												p.productKey === options.replaceProductKey &&
-												p.state === 'purchased',
-										)?.token
-								: undefined,
-							prorationMode: options?.prorationMode,
-						}),
-						// Covers opening the store surface only. Time the user spends
-						// inside it is the store's, not ours (FR-035).
-						resolved.timeouts.purchaseLaunchMs,
-						() =>
-							new PaymentError({
-								code: 'PAYMENT_TIMEOUT',
-								message: 'Opening the purchase surface timed out',
-								operation: 'purchase',
-								retryable: true,
-							}),
-					);
+					outcome = await launch(launchRequest(productKey, storeProductId, options));
 				} catch {
 					deps.emit({
 						type: 'purchase_failed',

package/src/testing/fakeStore.ts

@@ -98,6 +98,9 @@ const DEFAULT_CAPABILITIES: ProviderCapabilities = {
 	// lets a test complete a purchase while still blocking the real adapter
 	// outside production (FR-014).
 	createsRealTransactions: false,
+	// Its launch returns at once, so the engine's launch timeout applies and stays
+	// testable (FR-035).
+	purchaseOutcomeIncludesStoreTime: false,
 };
 
 let sequence = 0;