@mpgd/adapter-capacitor 0.16.3 → 0.18.0

package/README.md

@@ -133,6 +133,44 @@ normalizes every SDK failure through `mapError` into a `CommerceError` whose
 `storeCode` keeps the store's own code. It never grants and never sets
 `settlement`; the backend ledger decides.
 
+`purchaseGate` is an optional sales switch for new purchases, separate from
+the account binding (and from StoreKit's `appAccountToken`). It is asked once
+per `requestPurchase`, after the product, availability, and kind checks and
+before `accountBinding`, with `{ store, logicalId, storeSku, kind, source }`,
+and answers `{ allowed: true }` or `{ allowed: false, storeCode?, message?,
+retryable? }`. A refusal never opens the store UI and is answered as data:
+`{ outcome: 'failed', error: { code: 'ITEM_UNAVAILABLE', storeCode:
+'PURCHASES_PAUSED' } }` (or the gate's own `storeCode`), `retryable` false
+unless the gate says otherwise. A gate that could not answer refuses too,
+with `PURCHASE_GATE_FAILED` and always retryable, whether it threw, returned
+something malformed, or did not answer within `purchaseGateTimeoutMs` (three
+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. 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
+`getAvailablePurchases` never
+ask the gate, so purchases already paid for keep reconciling while new sales
+are refused. A failed or missing account binding is a `failed` result too,
+not a throw: a thrown `CommerceError` keeps its code (with the same exception
+for launched or cancelled codes), and anything else is
+`ACCOUNT_BINDING_REQUIRED` with `ACCOUNT_BINDING_LOOKUP_FAILED`, retryable.
+Over the bridge a thrown error keeps only `code`, `message`, and
+`retryable`, while a result keeps `storeCode`, so the game can tell
+`PURCHASES_PAUSED` from `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED`. The gate is not
+reflected in `getCapabilities()`: `availability` describes the store and
+gates the reconciler (a paused gate there would read as `STORE_UNAVAILABLE`
+and lose the reason), and a capability read stays free of server round trips.
+A shop hides its buy buttons from the same server flag it hands the gate,
+for example the sales flag of its account binding response.
+
 Two failure classes are not terminal. When `requestPurchase` throws or
 returns a code that normalizes to `OUTCOME_UNKNOWN` (for example
 `PLAY_BILLING_TIMEOUT`, `PLAY_BILLING_INTERRUPTED`,
@@ -146,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
@@ -169,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;
@@ -45,11 +55,32 @@ export interface CreateBridgeCommerceProviderInput {
   /** Sends one validated bridge request; the gateway's `request` fits. */
   readonly request: <TData>(method: BridgeCommerceV2Method, payload: unknown) => Promise<TData>;
   readonly subscribe: (listener: (event: BridgeCommerceEvent) => void) => () => void;
+  /**
+  * The bridge host accepts `FinishTransactionInput.retry` (it is built on the
+  * same contract and its provider declares `acceptsFinishRetry`). Absent, the
+  * provider does not declare it and callers never send `retry`.
+  */
+  readonly acceptsFinishRetry?: 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,8 +238,9 @@ export function createBridgeCommerceProvider(input) {
             });
         }
     };
-    return {
+    const provider = {
         store: input.store,
+        ...(input.acceptsFinishRetry === true ? { acceptsFinishRetry: true } : {}),
         async getCapabilities() {
             return (await send('commerce.v2.getCapabilities', { protocol: commerceProtocol }))
                 .capabilities;
@@ -231,6 +286,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,9 +3,10 @@ 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 { createStoreCommerceProvider, recoverableErrorCodes, type CreateStoreCommerceProviderInput, type StoreCommerceCapabilityOverrides, type StoreCommerceProductMapping, type StoreCommerceProvider, } from './store-commerce-provider.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 { 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';
@@ -13,9 +14,17 @@ export { createCapacitorViewport, type CapacitorViewportBaseState, type Capacito
 /**
 * 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,15 +4,17 @@ 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 { createStoreCommerceProvider, recoverableErrorCodes, } from './store-commerce-provider.js';
+export { accountBindingLookupFailedStoreCode, createStoreCommerceProvider, purchaseGateFailedStoreCode, purchaseGateTimeoutMs, purchasesPausedStoreCode, recoverableErrorCodes, } from './store-commerce-provider.js';
 export { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, } from './store-sdk.js';
 export { createCapacitorAppEvents, } from './app-events.js';
 export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, } from './native-http.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,10 +69,13 @@ 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,
             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
@@ -73,6 +86,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
@@ -135,6 +152,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')
@@ -146,11 +179,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;
                 }
@@ -166,10 +203,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;