@mpgd/adapter-capacitor 0.17.0 → 0.19.0

package/README.md

@@ -148,14 +148,11 @@ seconds): the sales flag is unknown rather than closed. An answer that
 arrives after the timeout is ignored and never opens the store. A thrown
 `CommerceError` keeps its own code, except a code that claims a launched or
 cancelled sheet (`OUTCOME_UNKNOWN`, `ALREADY_OWNED`, `USER_CANCELLED`), which
-becomes `PURCHASE_GATE_FAILED` because nothing was launched. The reconciler
-journals a refused attempt as terminal `failed` even when it is retryable:
-only trusted presentation facts (`not-started`) keep a key reusable, and the
-Capacitor bridge does not carry them yet, so a later try uses a new
-idempotency key. The store provider deliberately exposes no `presentation`
-that could only ever say `not-started`, because the game runtime's purchase
-coordinator would take it as a closure source and quarantine the game after
-every launched purchase. The gate runs while the gateway already holds the
+becomes `PURCHASE_GATE_FAILED` because nothing was launched. Over an SDK
+with sheet facts (below), a refusal is reported `not-started` before the
+answer, so the reconciler keeps a retryable refusal's key reusable and the
+same key asks again; without sheet facts the reconciler journals the refused
+attempt as terminal `failed`, and a later try uses a new idempotency key. The gate runs while the gateway already holds the
 purchase's external activity (the game is paused, with no sheet shown), so it
 should answer from a flag the game already holds rather than a slow network
 call; the timeout bounds that pause. Recovery, restore, finishing, events, `fetchProducts`, and
@@ -187,6 +184,50 @@ cannot advertise one the SDK lacks: `restore: true` without
 `sdk.restorePurchases`, like `finish: 'client' | 'host'` without
 `sdk.finishTransaction`, is rejected when the provider is created.
 
+### Store sheet facts
+
+A `StoreSdk` that declares `purchasePresentation` reports, for a
+`requestPurchase` call that carries a `presentationId`, when the store sheet
+opens and when it is gone (`open`, then `closed`), or that none opened
+(`not-started`). The Play Billing and StoreKit SDKs declare it by default.
+Only then does the provider offer `CommerceProvider.presentation`, so a new
+adapter over an SDK from before the facts keeps the behavior below, and an
+SDK never receives a `presentationId` from an adapter that predates them.
+
+The provider answers every `requestPurchase` with facts keyed by its
+idempotency key, numbered with one increasing `sequence`:
+
+- `not-started`, delivered before the answer, for a call that opened no
+  sheet: a purchase gate or account binding refusal, an unavailable store,
+  any throw, the SDK's own `not-started`, or an SDK that settled without a
+  fact.
+- `unknown` when the SDK answers while its native flow still runs and has
+  observed nothing (a call timeout): the call keeps waiting for the SDK's
+  `open`, `closed`, or `not-started`, bounded by the safety timeout below,
+  instead of reading the answer as either.
+- Otherwise `open`, then exactly one `closed`: the SDK's, or after
+  `purchasePresentationTimeoutMs` (15 minutes, `reason: 'timeout'`), or on
+  `dispose()` (`reason: 'disposed'`). A `not-started` after `open` becomes
+  `closed`. A result, a pending purchase, an Ask to Buy, or a purchase event
+  is never a `closed` fact.
+
+`createCommerceProviderBridge` serves the facts through
+`subscribePresentation` as `{ protocol: 'mpgd.commerce.presentation.v1',
+sequence, event }` envelopes, apart from the commerce envelopes of
+`subscribe`, so a commerce listener (and the host's buffering of purchase
+events for its first listener) is unchanged. `createBridgeCommerceProvider`
+offers `presentation` only when its input has `subscribePresentation`; it
+validates and renumbers the facts and adds `not-started` for a request the
+bridge refused before the host's provider ran. The gateway passes
+`subscribePresentation` only from a provider bridge that has it. With facts,
+the game runtime's purchase coordination turns on by itself
+(`createGamePlatformRuntime`: `createCoordinatedPlatformGateway` with an ad
+provider, `createCoordinatedCommerceProvider` without one), and the gateway
+keeps a purchase's pause (`beginExternalActivity()`) until the sheet's
+`closed` or `not-started`, whatever the answer, with
+`presentedPurchaseActivityTimeoutMs` as a safety net: an Ask to Buy whose
+sheet closed holds nothing.
+
 `createCommerceServiceProvider({ id, commerce })` wraps the provider as a
 `CapacitorServiceProvider` whose `commerce` field the registry recognizes. It
 declares no `features` and no `methods`: the six `commerce.v2.*` bridge methods
@@ -210,11 +251,12 @@ read per snapshot (`getCapabilitySnapshot` returns `{ availability, commerce }`,
 three-second timeout, shape validated): a stalled, failing, or invalid
 provider yields a degraded block (`createDegradedCommerceCapabilities`:
 `availability: 'temporarily-unavailable'`, nothing sold) and never rejects the
-capability read. A `launched` purchase keeps `beginExternalActivity()` open
-after the request returns, since the store UI is still up: the gateway releases
-it when the provider reports that product (`purchaseUpdated` or
-`purchaseError`), after `launchedPurchaseActivityTimeoutMs` (two minutes), or
-on `lifecycle.dispose`. The registry does not gate a commerce method by a
+capability read. Without sheet facts, a `launched` purchase keeps
+`beginExternalActivity()` open after the request returns, since the store UI
+may still be up: the gateway releases it when the provider reports that
+product (`purchaseUpdated` or `purchaseError`), after
+`launchedPurchaseActivityTimeoutMs` (two minutes), or on `lifecycle.dispose`.
+With facts, the sheet's own `closed` ends the pause (see above). The registry does not gate a commerce method by a
 snapshot: the provider reads its own `availability` and fails closed before any
 store UI opens. A `commerce.v2.*` request that reaches a transport without a
 provider still answers `COMMERCE_V2_UNAVAILABLE`.

package/dist/commerce-bridge.d.ts

@@ -1,4 +1,4 @@
-import { type BridgeCommerceEvent, type BridgeCommerceV2Method, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type BridgeCommerceEvent, type BridgeCommercePresentationEvent, type BridgeCommerceV2Method, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type CommerceBridgeMethods, type CommerceProvider, type StoreId } from '@mpgd/platform/commerce';
 import type { CapacitorCommerceServiceProvider } from './providers.js';
 /** Bridge error for a commerce v2 payload the typia assert rejected. */
@@ -9,6 +9,16 @@ export interface CommerceProviderBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
   /** Delivers `{ protocol: 'mpgd.commerce.v2', sequence, event }`; `sequence` starts at 0 per bridge. */
   subscribe(listener: (event: BridgeCommerceEvent) => void): () => void;
+  /**
+  * Present when the provider has `presentation`: delivers its purchase
+  * presentation facts as `{ protocol: 'mpgd.commerce.presentation.v1',
+  * sequence, event }`, `sequence` from 0 per bridge. Facts are never
+  * buffered, and a fact of a call that opened no sheet reaches a listener
+  * before that call's answer. Kept apart from `subscribe` so a commerce
+  * listener sees only commerce envelopes, and a bridge without it tells a
+  * consumer that its host has no facts.
+  */
+  subscribePresentation?(listener: (event: BridgeCommercePresentationEvent) => void): () => void;
 }
 export interface CreateCommerceProviderBridgeInput {
   readonly provider: CommerceProvider;
@@ -51,11 +61,32 @@ export interface CreateBridgeCommerceProviderInput {
   * provider does not declare it and callers never send `retry`.
   */
   readonly acceptsFinishRetry?: boolean;
+  /**
+  * The bridge host accepts `FinishTransactionInput.revoked` (same contract,
+  * and its provider declares `acceptsRevokedFinish`). Absent, the provider
+  * does not declare it and callers never send `revoked`.
+  */
+  readonly acceptsRevokedFinish?: boolean;
+  /**
+  * The host's purchase presentation facts
+  * (`CommerceProviderBridge.subscribePresentation`), each fact of a call
+  * that opened no sheet delivered before that call's answer. Only with it
+  * does this provider offer `presentation`: a host built before the
+  * protocol, or one whose provider has no facts, leaves it out, and the
+  * consumer keeps its behavior without them.
+  */
+  readonly subscribePresentation?: (listener: (event: BridgeCommercePresentationEvent) => void) => () => void;
 }
 /**
 * `CommerceProvider` over a bridge that serves the `commerce.v2.*` methods and
 * the event envelope. Results are validated again on this side, so a transport
 * that forgets to is still fail-closed; bridge errors become `CommerceError`s
 * with the bridge code kept as `storeCode` when it is not already a v2 code.
+*
+* With `subscribePresentation`, it offers `presentation`: the host's facts,
+* validated and numbered again on this side, plus `not-started`, delivered
+* before the answer, for a `requestPurchase` that settles without any fact
+* (the bridge refused it before the host's provider ran). Every call it
+* forwards then ends with a fact.
 */
 export declare function createBridgeCommerceProvider(input: CreateBridgeCommerceProviderInput): CommerceProvider;

package/dist/commerce-bridge.js

@@ -1,6 +1,6 @@
-import { bridgeCommerceEventProtocol, createBridgeError, isBridgeCommerceV2Method, } from '@mpgd/bridge';
-import { PlatformOperationError } from '@mpgd/platform';
-import { assertCommerceBridgeFetchProductsPayload, assertCommerceBridgeFetchProductsResult, assertCommerceBridgeFinishTransactionPayload, assertCommerceBridgeFinishTransactionResult, assertCommerceBridgeGetAvailablePurchasesPayload, assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesPayload, assertCommerceBridgeGetCapabilitiesResult, assertCommerceBridgeRequestPurchasePayload, assertCommerceBridgeRequestPurchaseResult, assertCommerceBridgeRestorePurchasesPayload, assertCommerceBridgeRestorePurchasesResult, assertCommerceEventEnvelope, CommerceError, commerceErrorInfoOf, commerceProtocol, commerceProtocolVersion, } from '@mpgd/platform/commerce';
+import { bridgeCommerceEventProtocol, bridgeCommercePresentationEventProtocol, createBridgeError, isBridgeCommerceV2Method, } from '@mpgd/bridge';
+import { createPurchasePresentationRelay, PlatformOperationError, } from '@mpgd/platform';
+import { assertCommerceBridgeFetchProductsPayload, assertCommerceBridgeFetchProductsResult, assertCommerceBridgeFinishTransactionPayload, assertCommerceBridgeFinishTransactionResult, assertCommerceBridgeGetAvailablePurchasesPayload, assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesPayload, assertCommerceBridgeGetCapabilitiesResult, assertCommerceBridgeRequestPurchasePayload, assertCommerceBridgeRequestPurchaseResult, assertCommerceBridgeRestorePurchasesPayload, assertCommerceBridgeRestorePurchasesResult, assertCommerceEventEnvelope, assertCommercePresentationEventEnvelope, CommerceError, commerceErrorInfoOf, commerceProtocol, commerceProtocolVersion, } from '@mpgd/platform/commerce';
 import { namesOtherProtocol } from './bridge-events.js';
 import { normalizeStoreSdkError } from './store-sdk.js';
 /** Bridge error for a commerce v2 payload the typia assert rejected. */
@@ -19,8 +19,11 @@ export const commerceV2MethodUnsupportedBridgeErrorCode = 'COMMERCE_V2_METHOD_UN
 export function createCommerceProviderBridge(input) {
     const { provider } = input;
     const listeners = new Set();
+    const presentationListeners = new Set();
     let sequence = 0;
+    let presentationSequence = 0;
     let detach;
+    let detachPresentation;
     const deliver = (event) => {
         const envelope = { protocol: commerceProtocol, sequence, event };
         sequence += 1;
@@ -28,6 +31,35 @@ export function createCommerceProviderBridge(input) {
             listener(envelope);
         }
     };
+    const deliverPresentation = (event) => {
+        let envelope;
+        try {
+            envelope = assertCommercePresentationEventEnvelope({
+                protocol: bridgeCommercePresentationEventProtocol,
+                sequence: presentationSequence,
+                event,
+            });
+        }
+        catch (error) {
+            // A fact the contract rejects is not delivered; the provider's own
+            // safety timeout still ends a sheet it never reports closed.
+            console.warn('A commerce provider reported an invalid presentation fact.', error);
+            return;
+        }
+        presentationSequence += 1;
+        for (const entry of [...presentationListeners]) {
+            if (!presentationListeners.has(entry)) {
+                continue;
+            }
+            try {
+                entry.listener(envelope);
+            }
+            catch (error) {
+                // A failing listener must not keep a `closed` fact from the others.
+                console.warn('A purchase presentation bridge listener failed.', error);
+            }
+        }
+    };
     const serve = async (request) => {
         const { payload } = request;
         switch (request.method) {
@@ -101,6 +133,22 @@ export function createCommerceProviderBridge(input) {
                 detach = undefined;
             };
         },
+        ...(provider.presentation === undefined ? {} : {
+            subscribePresentation(listener) {
+                const entry = { listener };
+                presentationListeners.add(entry);
+                if (presentationListeners.size === 1) {
+                    detachPresentation = provider.presentation?.subscribe(deliverPresentation);
+                }
+                return () => {
+                    if (!presentationListeners.delete(entry) || presentationListeners.size > 0) {
+                        return;
+                    }
+                    detachPresentation?.();
+                    detachPresentation = undefined;
+                };
+            },
+        }),
     };
 }
 /**
@@ -164,6 +212,12 @@ function isTypiaGuardError(error) {
  * the event envelope. Results are validated again on this side, so a transport
  * that forgets to is still fail-closed; bridge errors become `CommerceError`s
  * with the bridge code kept as `storeCode` when it is not already a v2 code.
+ *
+ * With `subscribePresentation`, it offers `presentation`: the host's facts,
+ * validated and numbered again on this side, plus `not-started`, delivered
+ * before the answer, for a `requestPurchase` that settles without any fact
+ * (the bridge refused it before the host's provider ran). Every call it
+ * forwards then ends with a fact.
  */
 export function createBridgeCommerceProvider(input) {
     const send = async (method, payload) => {
@@ -184,9 +238,10 @@ export function createBridgeCommerceProvider(input) {
             });
         }
     };
-    return {
+    const provider = {
         store: input.store,
         ...(input.acceptsFinishRetry === true ? { acceptsFinishRetry: true } : {}),
+        ...(input.acceptsRevokedFinish === true ? { acceptsRevokedFinish: true } : {}),
         async getCapabilities() {
             return (await send('commerce.v2.getCapabilities', { protocol: commerceProtocol }))
                 .capabilities;
@@ -232,6 +287,43 @@ export function createBridgeCommerceProvider(input) {
             });
         },
     };
+    const subscribePresentation = input.subscribePresentation;
+    return subscribePresentation === undefined
+        ? provider
+        : withBridgePresentation(provider, subscribePresentation);
+}
+/**
+ * `presentation` over the host's facts: validated, then relayed by the
+ * platform's `createPurchasePresentationRelay` (a superseded fact dropped,
+ * the rest numbered again, `not-started` added for a call that settled
+ * without a fact). One attachment to the host serves every listener.
+ */
+function withBridgePresentation(provider, subscribePresentation) {
+    const relay = createPurchasePresentationRelay({
+        subscribe: (listener) => subscribePresentation((envelope) => {
+            if (namesOtherProtocol(envelope, bridgeCommercePresentationEventProtocol)) {
+                return;
+            }
+            let event;
+            try {
+                event = assertCommercePresentationEventEnvelope(envelope).event;
+            }
+            catch (error) {
+                console.warn('The bridge delivered an invalid purchase presentation fact.', error);
+                return;
+            }
+            listener(event);
+        }),
+    }, {
+        onListenerError: (error) => {
+            console.warn('A purchase presentation listener failed.', error);
+        },
+    });
+    return {
+        ...provider,
+        presentation: relay.presentation,
+        requestPurchase: (request) => relay.track(request.idempotencyKey, () => provider.requestPurchase(request)),
+    };
 }
 function toCommerceError(error) {
     if (error instanceof CommerceError) {

package/dist/index.d.ts

@@ -3,19 +3,28 @@ import { type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type Capacit
 import { type CapacitorCrashReportingOptions } from './crash-reporting.js';
 import { type CapacitorServiceProvider, type NativeBridge } from './providers.js';
 export { capacitorCrashlyticsPluginName, capacitorCrashReportingProvider, createCapacitorCrashReporter, createLocalCrashCollectionPreferenceStore, type CrashCollectionPreferenceStore, type CapacitorCrashlyticsPlugin, type CapacitorCrashReporterOptions, type CapacitorCrashReportingOptions, } from './crash-reporting.js';
+export { createNativePurchasePresentation, purchasePresentationTimeoutMs, type NativePurchasePresentation, type NativePurchasePresentationPlugin, } from './purchase-presentation.js';
 export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, createDegradedNotificationCapabilities, type CapacitorCommerceServiceProvider, type CapacitorNotificationServiceProvider, type CapacitorNotificationsV2Service, type CapacitorProviderCapabilitySnapshot, type CapacitorProviderRegistry, type CapacitorServiceProvider, type NativeBridge, } from './providers.js';
 export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, type CommerceProviderBridge, type CreateBridgeCommerceProviderInput, type CreateCommerceProviderBridgeInput, type CreateCommerceServiceProviderInput, } from './commerce-bridge.js';
 export { accountBindingLookupFailedStoreCode, createStoreCommerceProvider, purchaseGateFailedStoreCode, purchaseGateTimeoutMs, purchasesPausedStoreCode, recoverableErrorCodes, type CreateStoreCommerceProviderInput, type StoreCommerceCapabilityOverrides, type StoreCommerceProductMapping, type StoreCommerceProvider, type StorePurchaseGate, type StorePurchaseGateDecision, type StorePurchaseGateRequest, } from './store-commerce-provider.js';
-export { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, type StoreSdk, type StoreSdkCapabilities, type StoreSdkError, type StoreSdkErrorCodeMap, type StoreSdkEvent, type StoreSdkEventName, type StoreSdkEventOf, type StoreSdkFetchProductsInput, type StoreSdkFinishTransactionInput, type StoreSdkFinishTransactionResult, type StoreSdkGetAvailablePurchasesInput, type StoreSdkProduct, type StoreSdkPurchase, type StoreSdkRequestPurchaseInput, type StoreSdkRequestPurchaseResult, } from './store-sdk.js';
+export { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, type StoreSdk, type StoreSdkCapabilities, type StoreSdkError, type StoreSdkErrorCodeMap, type StoreSdkEvent, type StoreSdkEventName, type StoreSdkEventOf, type StoreSdkFetchProductsInput, type StoreSdkFinishTransactionInput, type StoreSdkGrantedFinishTransactionInput, type StoreSdkRevokedFinishTransactionInput, type StoreSdkFinishTransactionResult, type StoreSdkGetAvailablePurchasesInput, type StoreSdkProduct, type StoreSdkPurchase, type StoreSdkRequestPurchaseInput, type StoreSdkRequestPurchaseResult, } from './store-sdk.js';
 export { createCapacitorAppEvents, type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type CapacitorVisibilitySource, } from './app-events.js';
 export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, type CapacitorJsonRequest, type CapacitorJsonResponse, type CapacitorNativeHttpErrorCode, type CapacitorNativeJsonTransport, type CreateCapacitorNativeJsonTransportInput, } from './native-http.js';
 export { createCapacitorViewport, type CapacitorViewportBaseState, type CapacitorOccupiedSurfaceInput, type CapacitorViewportController, type CapacitorViewportHost, } from './viewport.js';
 /**
 * Upper bound on how long a `launched` commerce v2 purchase keeps the game
 * paused when no purchase event for the product arrives (for example a store
-* sheet dismissed without a callback).
+* sheet dismissed without a callback). Only for a provider without sheet
+* facts; see `presentedPurchaseActivityTimeoutMs`.
 */
 export declare const launchedPurchaseActivityTimeoutMs = 120000;
+/**
+* Safety bound on how long a purchase whose provider reports sheet facts
+* keeps the game paused after the purchase call answered with the sheet
+* still open. The sheet's `closed` fact normally ends the pause; the
+* provider's own `purchasePresentationTimeoutMs` reports one first.
+*/
+export declare const presentedPurchaseActivityTimeoutMs: number;
 export declare function createCapacitorPlatformGateway(input: {
   readonly target: Extract<PlatformTarget, 'android' | 'ios'>;
   readonly appVersion: string;

package/dist/index.js

@@ -4,12 +4,14 @@ import { PlatformOperationError, } from '@mpgd/platform';
 import { withShareIntentCheck } from '@mpgd/platform/routes';
 import { createCapacitorAppEvents, } from './app-events.js';
 import { namesOtherProtocol } from './bridge-events.js';
+import { purchasePresentationTimeoutMs } from './purchase-presentation.js';
 import { createBridgeCommerceProvider } from './commerce-bridge.js';
 import { createCapacitorGatewayCrashReporting, } from './crash-reporting.js';
 import { assertProviderResponseData, createCapacitorProviderRegistry, } from './providers.js';
 import { assertNotificationsV2Served, externalActivityMethods } from './request-policy.js';
 import { createCapacitorViewport } from './viewport.js';
 export { capacitorCrashlyticsPluginName, capacitorCrashReportingProvider, createCapacitorCrashReporter, createLocalCrashCollectionPreferenceStore, } from './crash-reporting.js';
+export { createNativePurchasePresentation, purchasePresentationTimeoutMs, } from './purchase-presentation.js';
 export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, createDegradedNotificationCapabilities, } from './providers.js';
 export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, } from './commerce-bridge.js';
 export { accountBindingLookupFailedStoreCode, createStoreCommerceProvider, purchaseGateFailedStoreCode, purchaseGateTimeoutMs, purchasesPausedStoreCode, recoverableErrorCodes, } from './store-commerce-provider.js';
@@ -23,9 +25,17 @@ function isRecord(value) {
 /**
  * Upper bound on how long a `launched` commerce v2 purchase keeps the game
  * paused when no purchase event for the product arrives (for example a store
- * sheet dismissed without a callback).
+ * sheet dismissed without a callback). Only for a provider without sheet
+ * facts; see `presentedPurchaseActivityTimeoutMs`.
  */
 export const launchedPurchaseActivityTimeoutMs = 120_000;
+/**
+ * Safety bound on how long a purchase whose provider reports sheet facts
+ * keeps the game paused after the purchase call answered with the sheet
+ * still open. The sheet's `closed` fact normally ends the pause; the
+ * provider's own `purchasePresentationTimeoutMs` reports one first.
+ */
+export const presentedPurchaseActivityTimeoutMs = purchasePresentationTimeoutMs;
 const safeFallbackMethods = new Set([
     'identity.getPlayer',
     'identity.getSession',
@@ -59,12 +69,14 @@ export function createCapacitorPlatformGateway(input) {
     // other provider method, so the bridge envelope, response validation, and
     // external activity bookkeeping are exercised in process exactly as over a
     // transport.
+    const subscribePresentation = commerceProvider?.bridge.subscribePresentation?.bind(commerceProvider.bridge);
     const commerce = commerceProvider === undefined
         ? undefined
         : createBridgeCommerceProvider({
             store: commerceProvider.commerce.store,
             // The host below is this package's, on the same contract.
             acceptsFinishRetry: commerceProvider.commerce.acceptsFinishRetry === true,
+            acceptsRevokedFinish: commerceProvider.commerce.acceptsRevokedFinish === true,
             request: (method, payload) => request(method, payload),
             // The provider's channel (`NativeBridge`) may carry other protocols.
             // Only an envelope that names another protocol is dropped; anything
@@ -75,6 +87,10 @@ export function createCapacitorPlatformGateway(input) {
                     listener(envelope);
                 }
             }),
+            // Facts only from a bridge that serves them (`createCommerceServiceProvider`
+            // over a provider with `presentation`); otherwise `commerce` has no
+            // `presentation` and purchases keep the result-based pause below.
+            ...(subscribePresentation === undefined ? {} : { subscribePresentation }),
         });
     const notificationsProvider = providers.notifications;
     // Served through the same request path as every other provider method, as
@@ -137,6 +153,22 @@ export function createCapacitorPlatformGateway(input) {
             ? lifecycle.beginExternalActivity?.()
             : undefined;
         let holdActivity = false;
+        // Watched before the request is sent: a provider reports a sheet that
+        // never opened before it answers.
+        const presentation = releaseExternalActivity !== undefined
+            && method === 'commerce.v2.requestPurchase'
+            ? watchPurchasePresentation(payload)
+            : undefined;
+        // Released once: by the sheet's own end (which may come while the call
+        // still runs, for example a safety-timeout `closed`), or after the call.
+        let released = false;
+        const release = () => {
+            if (!released) {
+                released = true;
+                releaseExternalActivity?.();
+            }
+        };
+        presentation?.onEnd(release);
         try {
             const provider = leaderboardRoute === 'remote'
                 && (method === 'leaderboard.submitScore' || method === 'leaderboard.open')
@@ -148,11 +180,15 @@ export function createCapacitorPlatformGateway(input) {
                     const data = await sendRequest(method, payload, provider);
                     if (releaseExternalActivity !== undefined
                         && method === 'commerce.v2.requestPurchase'
-                        && isRecord(data) && data.outcome === 'launched') {
-                        // The store UI is still open: stay paused until this product's
-                        // purchase event arrives or the safety timeout ends.
+                        && isRecord(data) && data.outcome === 'launched'
+                        && presentation?.reported() !== true) {
+                        // No sheet facts for this purchase: the store UI may still be
+                        // open, so stay paused until this product's purchase event
+                        // arrives or the safety timeout ends. With facts, the sheet's
+                        // own `closed` ends the pause (below), and a pending purchase
+                        // whose sheet closed holds nothing.
                         holdActivity = true;
-                        holdLaunchedPurchaseActivity(releaseExternalActivity, isRecord(payload) ? payload.logicalId : undefined);
+                        holdLaunchedPurchaseActivity(release, isRecord(payload) ? payload.logicalId : undefined);
                     }
                     return data;
                 }
@@ -168,10 +204,106 @@ export function createCapacitorPlatformGateway(input) {
             return await sendRequest(method, payload, undefined);
         }
         finally {
-            if (!holdActivity) {
-                releaseExternalActivity?.();
+            if (holdActivity) {
+                presentation?.dispose();
+            }
+            else if (!released && presentation?.open() === true) {
+                // The sheet is still up, whatever the answer (a result, a pending
+                // purchase, or a throw): stay paused until its `closed` fact.
+                holdPresentedPurchaseActivity(release, presentation);
+            }
+            else {
+                presentation?.dispose();
+                release();
+            }
+        }
+    }
+    /**
+     * Follows one purchase's presentation facts (by its idempotency key) from
+     * `commerce.presentation`: the bridge's facts already validated, with a
+     * superseded or replayed one dropped, so a stale fact cannot end the hold
+     * while the sheet is up. Undefined when the bridge serves no facts or the
+     * payload has no key.
+     */
+    function watchPurchasePresentation(payload) {
+        const idempotencyKey = isRecord(payload) ? payload.idempotencyKey : undefined;
+        const facts = commerce?.presentation;
+        if (facts === undefined || typeof idempotencyKey !== 'string') {
+            return undefined;
+        }
+        // `held`: the sheet is (`open`) or may be (`unknown`) up; `opened`: seen open.
+        let held = false;
+        let opened = false;
+        let ended = false;
+        let onEnd;
+        let unsubscribe;
+        let disposed = false;
+        const dispose = () => {
+            disposed = true;
+            onEnd = undefined;
+            unsubscribe?.();
+            unsubscribe = undefined;
+        };
+        const subscription = facts.subscribe((event) => {
+            if (event.idempotencyKey !== idempotencyKey || ended) {
+                return;
+            }
+            const { state } = event;
+            if (state === 'open' || state === 'unknown') {
+                // `unknown`: the sheet may still be up; hold as for an open one.
+                held = true;
+                opened ||= state === 'open';
             }
+            else if (state === 'closed' || (state === 'not-started' && !opened)) {
+                // A sheet seen open ends only with `closed` (its provider turns a
+                // later `not-started` into `closed`); a `not-started` then belongs
+                // to another call of the same key.
+                ended = true;
+                const end = onEnd;
+                dispose();
+                end?.();
+            }
+        });
+        if (disposed) {
+            subscription();
+        }
+        else {
+            unsubscribe = subscription;
         }
+        return {
+            reported: () => held || ended,
+            open: () => held && !ended,
+            onEnd(callback) {
+                if (ended) {
+                    callback();
+                }
+                else {
+                    onEnd = callback;
+                }
+            },
+            dispose,
+        };
+    }
+    /**
+     * Keeps a purchase's external activity open while its store sheet is up:
+     * until the sheet's `closed` fact, the safety timeout, or dispose. A
+     * result, a pending purchase, or a purchase event does not end it.
+     */
+    function holdPresentedPurchaseActivity(release, presentation) {
+        let done = false;
+        const finish = () => {
+            if (done) {
+                return;
+            }
+            done = true;
+            launchedPurchaseHolds.delete(finish);
+            clearTimeout(timer);
+            presentation.dispose();
+            release();
+        };
+        launchedPurchaseHolds.add(finish);
+        const timer = setTimeout(finish, presentedPurchaseActivityTimeoutMs);
+        presentation.onEnd(finish);
     }
     /**
      * Keeps the external activity of a `launched` purchase open until the

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-import { type BridgeEvent, type BridgeMethod, type BridgeNotificationsEvent, type BridgeNotificationsV2Method, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type BridgeCommercePresentationEvent, type BridgeEvent, type BridgeMethod, type BridgeNotificationsEvent, type BridgeNotificationsV2Method, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import type { AdProvider } from '@mpgd/platform/ads';
 import { type CommerceCapabilities, type NotificationSubscriptionAdapter, type PlatformProviderAvailability, type PlatformProviderFeature } from '@mpgd/platform';
 import { type CommerceProvider } from '@mpgd/platform/commerce';
@@ -86,7 +86,15 @@ export interface CapacitorNotificationServiceProvider extends CapacitorServicePr
 /** The provider the registry serves commerce v2 from. */
 export interface CapacitorCommerceServiceProvider extends CapacitorServiceProvider {
   readonly commerce: CommerceProvider;
-  readonly bridge: NativeBridge & Required<Pick<NativeBridge, 'subscribe'>>;
+  readonly bridge: NativeBridge & Required<Pick<NativeBridge, 'subscribe'>> & {
+    /**
+    * The provider's purchase presentation facts
+    * (`CommerceProviderBridge.subscribePresentation`). Only with it does
+    * `gateway.commerce` offer `presentation`, and the gateway keep a
+    * purchase's pause until the sheet's `closed` fact.
+    */
+    subscribePresentation?(listener: (event: BridgeCommercePresentationEvent) => void): () => void;
+  };
 }
 export interface CapacitorProviderCapabilitySnapshot {
   readonly availability: Readonly<Record<PlatformProviderFeature, PlatformProviderAvailability>>;

package/dist/purchase-presentation.d.ts

@@ -0,0 +1,55 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+import type { StoreSdkPurchasePresentation } from './store-sdk.js';
+/**
+* Upper bound on how long one store sheet counts as open (or possibly open)
+* without a native `closed` fact. Past it the provider reports `closed` with
+* reason `timeout`, so a lost native observation can pause the game, but
+* never forever. It matches the purchase flow timeout of the OpenIAP Google
+* core (15 minutes).
+*/
+export declare const purchasePresentationTimeoutMs: number;
+/** A store plugin's native surface for sheet facts (Play Billing, StoreKit). */
+export interface NativePurchasePresentationPlugin {
+  addListener(eventName: 'purchasePresentation', listener: (event: unknown) => void): Promise<PluginListenerHandle>;
+  readonly getPresentationSupport?: () => Promise<unknown>;
+}
+/** What a store plugin's `StoreSdk` uses to report its native sheet facts. */
+export interface NativePurchasePresentation {
+  /** The SDK's `purchasePresentation` declaration. */
+  readonly purchasePresentation: StoreSdkPurchasePresentation;
+  /**
+  * Whether the native code in the app reports facts (`getPresentationSupport`).
+  * A build from before them answers `UNIMPLEMENTED`, which is remembered;
+  * any other failure is asked again next time.
+  */
+  supported(): Promise<boolean>;
+  /**
+  * Someone follows the facts: an adapter that reads them subscribes when it
+  * builds its provider (one from before them never does).
+  */
+  followed(): boolean;
+  /** Follows facts for a `purchase` call about to be sent with this id. */
+  begin(presentationId: string): void;
+  /**
+  * Applies the sheet state a `purchase` answer, or a rejection's `data`,
+  * carried (`presentation`): `open`, `closed`, `not-started`, or
+  * `requested` (native code still runs the flow and has observed nothing
+  * yet; its facts follow as events).
+  */
+  answered(presentationId: string, answerOrError: unknown): void;
+}
+/**
+* Sheet facts by presentation id from the plugin's `purchasePresentation`
+* events and the `presentation` field of its `purchase` answers, whichever
+* arrives first; each call gets at most one `open` and one terminal fact.
+* A `requested` answer is reported as `unknown`: the sheet may still come,
+* so the provider keeps the call waiting for the native `open`, `closed`, or
+* `not-started` instead of reading the answer as a sheet that never opened
+* or inventing one that did. The native listener is attached with the first
+* subscriber and removed with the last.
+*
+* Exported for the store plugins, which peer on this package. A plugin reads
+* it through the module namespace, so with an adapter from before it the
+* plugin declares no facts (and that adapter never asks for them).
+*/
+export declare function createNativePurchasePresentation(native: NativePurchasePresentationPlugin): NativePurchasePresentation;