@mpgd/adapter-capacitor 0.17.0 → 0.18.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,26 @@ export interface CreateBridgeCommerceProviderInput {
   * 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,7 +238,7 @@ export function createBridgeCommerceProvider(input) {
             });
         }
     };
-    return {
+    const provider = {
         store: input.store,
         ...(input.acceptsFinishRetry === true ? { acceptsFinishRetry: true } : {}),
         async getCapabilities() {
@@ -232,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,6 +3,7 @@ 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';
@@ -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,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,6 +69,7 @@ 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({
@@ -75,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
@@ -137,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')
@@ -148,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;
                 }
@@ -168,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;

package/dist/purchase-presentation.js

@@ -0,0 +1,170 @@
+/**
+ * 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 const purchasePresentationTimeoutMs = 15 * 60_000;
+/**
+ * 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 function createNativePurchasePresentation(native) {
+    const listeners = new Set();
+    const sheets = new Map();
+    let handle;
+    let generation = 0;
+    let support;
+    const report = (presentationId, state, reason) => {
+        const current = sheets.get(presentationId);
+        if (current === undefined || current === state || (state === 'unknown' && current === 'open')) {
+            return;
+        }
+        if (state === 'open' || state === 'unknown') {
+            sheets.set(presentationId, state);
+        }
+        else {
+            sheets.delete(presentationId);
+        }
+        const event = {
+            presentationId,
+            state,
+            ...(reason === undefined ? {} : { reason }),
+        };
+        for (const entry of [...listeners]) {
+            if (!listeners.has(entry)) {
+                continue;
+            }
+            // One failing listener must not keep a later one (the commerce
+            // provider) from its `closed` fact.
+            try {
+                entry.listener(event);
+            }
+            catch (error) {
+                console.warn('A purchase presentation listener failed.', error);
+            }
+        }
+    };
+    const onNativeFact = (event) => {
+        if (!isRecord(event) || typeof event.presentationId !== 'string') {
+            return;
+        }
+        const { state, reason } = event;
+        if (state === 'open' || state === 'closed' || state === 'not-started') {
+            report(event.presentationId, state, state === 'closed' && (reason === 'interrupted' || reason === 'timeout')
+                ? reason
+                : undefined);
+        }
+    };
+    const attach = () => {
+        if (handle !== undefined) {
+            return;
+        }
+        const attached = generation;
+        let added;
+        try {
+            added = native.addListener('purchasePresentation', (event) => {
+                if (attached === generation) {
+                    onNativeFact(event);
+                }
+            });
+        }
+        catch {
+            return;
+        }
+        handle = added;
+        added.catch(() => {
+            if (handle === added) {
+                handle = undefined;
+            }
+        });
+    };
+    const detach = () => {
+        const current = handle;
+        if (current === undefined) {
+            return;
+        }
+        handle = undefined;
+        generation += 1;
+        current.then((resolved) => resolved.remove()).catch(() => undefined);
+    };
+    return {
+        purchasePresentation: {
+            subscribe(listener) {
+                const entry = { listener };
+                listeners.add(entry);
+                attach();
+                return () => {
+                    if (listeners.delete(entry) && listeners.size === 0) {
+                        detach();
+                    }
+                };
+            },
+        },
+        followed() {
+            return listeners.size > 0;
+        },
+        supported() {
+            if (support !== undefined) {
+                return support;
+            }
+            const check = native.getPresentationSupport;
+            if (typeof check !== 'function') {
+                return Promise.resolve(false);
+            }
+            const attempt = Promise.resolve()
+                .then(() => check.call(native))
+                .then((answer) => isRecord(answer)
+                && typeof answer.purchasePresentation === 'number'
+                && answer.purchasePresentation >= 1, (error) => {
+                if (!isRecord(error) || error.code !== 'UNIMPLEMENTED') {
+                    support = undefined;
+                }
+                return false;
+            });
+            support = attempt;
+            return attempt;
+        },
+        begin(presentationId) {
+            sheets.set(presentationId, 'requested');
+        },
+        answered(presentationId, answerOrError) {
+            const presentation = answeredPresentation(answerOrError);
+            if (presentation === 'open' || presentation === 'closed' || presentation === 'not-started') {
+                report(presentationId, presentation);
+            }
+            else if (presentation === 'requested') {
+                report(presentationId, 'unknown');
+            }
+            else if (sheets.get(presentationId) === 'requested') {
+                // No sheet state from native code that declared facts: nothing was
+                // seen opening, which the provider reads as not-started.
+                sheets.delete(presentationId);
+            }
+        },
+    };
+}
+/** The `presentation` of a `purchase` answer or of a rejection's `data`. */
+function answeredPresentation(answer) {
+    if (!isRecord(answer)) {
+        return undefined;
+    }
+    if ('presentation' in answer) {
+        return answer.presentation;
+    }
+    return isRecord(answer.data) ? answer.data.presentation : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/store-commerce-provider.d.ts

@@ -1,4 +1,4 @@
-import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type PlatformEvidenceEnvelope } from '@mpgd/platform';
 import { type CommerceAuthorityCapabilities, type CommerceCatalogCapabilities, type CommerceErrorCode, type CommerceLifecycleCapabilities, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseCapabilities, type PurchaseKind, type PurchaseSource, type StoreId, type StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
 import { type StoreSdk, type StoreSdkErrorCodeMap, type StoreSdkPurchase } from './store-sdk.js';
 /** One catalog product sold through the store under `storeSku`. */
@@ -77,7 +77,10 @@ export interface CreateStoreCommerceProviderInput {
   readonly mapError?: StoreSdkErrorCodeMap;
 }
 export interface StoreCommerceProvider extends CommerceProvider {
-  /** Detaches the SDK listeners; buffered events are dropped. */
+  /**
+  * Detaches the SDK listeners; buffered events are dropped. A store sheet
+  * still open gets its `closed` fact (reason `disposed`) first.
+  */
   dispose(): void;
 }
 /**
@@ -93,6 +96,17 @@ export declare const purchaseGateTimeoutMs = 3000;
 * declaration, builds `StorePurchase` evidence, buffers SDK events until the
 * first subscriber, and normalizes every SDK failure into a `CommerceError`.
 * It never grants and never sets `settlement`; the backend ledger decides.
+*
+* Over an SDK that declares `purchasePresentation`, the provider offers
+* `presentation` and answers every `requestPurchase` call with facts keyed
+* by its idempotency key: `not-started`, delivered before the call settles,
+* for any call that opened no sheet (a purchase gate or account binding
+* refusal, an unavailable store, a throw, or the SDK's own `not-started`);
+* otherwise `open` and exactly one `closed` when the SDK reports the sheet
+* gone, or after `purchasePresentationTimeoutMs` (reason `timeout`), or on
+* `dispose` (reason `disposed`). A result, a pending purchase, or a purchase
+* event never closes a sheet. An SDK without the declaration leaves the
+* provider without `presentation`, as before.
 */
 export declare function createStoreCommerceProvider(input: CreateStoreCommerceProviderInput): StoreCommerceProvider;
 /**

package/dist/store-commerce-provider.js

@@ -1,4 +1,6 @@
+import { createPurchasePresentationChannel, isPurchasePresentationReason, } from '@mpgd/platform';
 import { assertFinishTransactionInput, assertFinishTransactionResult, assertRequestPurchaseSupported, assertStoreProduct, assertStorePurchase, CommerceError, createCommerceEventBuffer, } from '@mpgd/platform/commerce';
+import { purchasePresentationTimeoutMs, } from './purchase-presentation.js';
 import { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, } from './store-sdk.js';
 /** `storeCode` of a purchase the gate refused without naming its own. */
 export const purchasesPausedStoreCode = 'PURCHASES_PAUSED';
@@ -27,6 +29,17 @@ const availabilitySet = new Set([
  * declaration, builds `StorePurchase` evidence, buffers SDK events until the
  * first subscriber, and normalizes every SDK failure into a `CommerceError`.
  * It never grants and never sets `settlement`; the backend ledger decides.
+ *
+ * Over an SDK that declares `purchasePresentation`, the provider offers
+ * `presentation` and answers every `requestPurchase` call with facts keyed
+ * by its idempotency key: `not-started`, delivered before the call settles,
+ * for any call that opened no sheet (a purchase gate or account binding
+ * refusal, an unavailable store, a throw, or the SDK's own `not-started`);
+ * otherwise `open` and exactly one `closed` when the SDK reports the sheet
+ * gone, or after `purchasePresentationTimeoutMs` (reason `timeout`), or on
+ * `dispose` (reason `disposed`). A result, a pending purchase, or a purchase
+ * event never closes a sheet. An SDK without the declaration leaves the
+ * provider without `presentation`, as before.
  */
 export function createStoreCommerceProvider(input) {
     const { sdk } = input;
@@ -147,6 +160,77 @@ export function createStoreCommerceProvider(input) {
             });
         }),
     ];
+    // Presentation: SDK facts by presentation id, published by idempotency key.
+    const sdkPresentation = sdk.purchasePresentation;
+    const presentation = sdkPresentation === undefined
+        ? undefined
+        : createPurchasePresentationChannel({
+            onListenerError: (error) => {
+                // A failing listener must not keep a `closed` fact from the others.
+                console.warn('A purchase presentation listener failed.', error);
+            },
+        });
+    const flights = new Map();
+    let disposed = false;
+    const endFlight = (flight, state, reason) => {
+        if (flights.get(flight.presentationId) !== flight) {
+            return;
+        }
+        flights.delete(flight.presentationId);
+        if (flight.timer !== undefined) {
+            clearTimeout(flight.timer);
+        }
+        // A sheet that opened can only close; `not-started` after `open` would
+        // tell a consumer the sheet never showed.
+        const fact = flight.open ? 'closed' : state;
+        presentation?.publish({
+            idempotencyKey: flight.idempotencyKey,
+            state: fact,
+            ...(reason === undefined || fact !== 'closed' ? {} : { reason }),
+        });
+    };
+    const onPresentationFact = (event) => {
+        if (!isRecord(event) || typeof event.presentationId !== 'string') {
+            return;
+        }
+        const flight = flights.get(event.presentationId);
+        if (flight === undefined) {
+            // Another call's, an already ended call's, or an earlier session's fact.
+            return;
+        }
+        const armSafetyTimeout = () => {
+            flight.timer ??= setTimeout(() => endFlight(flight, 'closed', 'timeout'), purchasePresentationTimeoutMs);
+        };
+        switch (event.state) {
+            case 'open':
+                if (!flight.open) {
+                    flight.open = true;
+                    presentation?.publish({ idempotencyKey: flight.idempotencyKey, state: 'open' });
+                    armSafetyTimeout();
+                }
+                return;
+            case 'unknown':
+                // The sheet may still open: the call's answer does not end it.
+                if (!flight.open && !flight.pending) {
+                    flight.pending = true;
+                    presentation?.publish({ idempotencyKey: flight.idempotencyKey, state: 'unknown' });
+                    armSafetyTimeout();
+                }
+                return;
+            case 'closed':
+                endFlight(flight, 'closed', isPurchasePresentationReason(event.reason) ? event.reason : undefined);
+                return;
+            case 'not-started':
+                endFlight(flight, 'not-started');
+                return;
+            default:
+                // An unknown fact proves nothing; the safety timeout still bounds the sheet.
+                return;
+        }
+    };
+    if (sdkPresentation !== undefined) {
+        detachers.push(sdkPresentation.subscribe(onPresentationFact));
+    }
     const getAvailability = sdk.getAvailability;
     const readAvailability = async () => {
         if (getAvailability === undefined) {
@@ -185,10 +269,89 @@ export function createStoreCommerceProvider(input) {
         authority: { ...input.authority },
         availability: await readAvailability(),
     });
+    const requestStorePurchase = async (request, presentationId) => {
+        const mapping = byLogicalId.get(request.logicalId);
+        if (mapping === undefined) {
+            throw new CommerceError('ITEM_UNAVAILABLE', {
+                message: `Store ${store} does not sell ${request.logicalId}.`,
+            });
+        }
+        const capabilities = await getCapabilities();
+        assertAvailable(capabilities.availability, store);
+        assertRequestPurchaseSupported(capabilities, request, mapping.kind);
+        // Pre-launch refusals below are data, not throws: a `failed` result
+        // keeps its `storeCode` across the bridge, a thrown error does not.
+        if (input.purchaseGate !== undefined) {
+            const refusal = await askPurchaseGate(input.purchaseGate, {
+                store,
+                logicalId: mapping.logicalId,
+                storeSku: mapping.storeSku,
+                kind: mapping.kind,
+                source: request.source,
+            });
+            if (refusal !== undefined) {
+                return { outcome: 'failed', error: refusal };
+            }
+        }
+        let accountBinding;
+        try {
+            accountBinding = await input.accountBinding?.();
+        }
+        catch (error) {
+            return { outcome: 'failed', error: accountBindingFailure(error, store) };
+        }
+        if (input.authority.accountBinding === 'required' && accountBinding === undefined) {
+            return {
+                outcome: 'failed',
+                error: new CommerceError('ACCOUNT_BINDING_REQUIRED', {
+                    message: `Store ${store} requires an account binding before a purchase.`,
+                }).toCommerceErrorInfo(),
+            };
+        }
+        const offerId = request.offerId ?? mapping.offerId;
+        if (disposed) {
+            // Its listeners are gone: a sheet opened now could never be reported.
+            throw new CommerceError('NOT_PREPARED', {
+                message: `Store ${store} was disposed before the purchase opened.`,
+            });
+        }
+        const flight = presentationId === undefined ? undefined : flights.get(presentationId);
+        if (flight !== undefined) {
+            flight.launched = true;
+        }
+        let result;
+        try {
+            result = await sdk.requestPurchase({
+                sku: mapping.storeSku,
+                ...(offerId === undefined ? {} : { offerId }),
+                ...(request.quantity === undefined ? {} : { quantity: request.quantity }),
+                ...(accountBinding === undefined ? {} : { accountBinding }),
+                ...(presentationId === undefined ? {} : { presentationId }),
+            });
+        }
+        catch (error) {
+            return failureOutcome(undefined, normalize(error).toCommerceErrorInfo());
+        }
+        if (!isRecord(result)) {
+            throw invalidRequestResult(store);
+        }
+        switch (result.outcome) {
+            case 'launched':
+                return { outcome: 'launched' };
+            case 'purchased':
+                return { outcome: 'purchased', purchase: toStorePurchase(result.purchase) };
+            case 'cancelled':
+            case 'failed':
+                return failureOutcome(result.outcome, normalize(result.error).toCommerceErrorInfo());
+            default:
+                throw invalidRequestResult(store);
+        }
+    };
     const finishTransaction = sdk.finishTransaction;
     const restorePurchases = sdk.restorePurchases;
     const provider = {
         store,
+        ...(presentation === undefined ? {} : { presentation: presentation.presentation }),
         // `retry` is forwarded to the SDK below.
         ...(finishTransaction === undefined ? {} : { acceptsFinishRetry: true }),
         getCapabilities,
@@ -251,70 +414,41 @@ export function createStoreCommerceProvider(input) {
             return products;
         },
         async requestPurchase(request) {
-            const mapping = byLogicalId.get(request.logicalId);
-            if (mapping === undefined) {
-                throw new CommerceError('ITEM_UNAVAILABLE', {
-                    message: `Store ${store} does not sell ${request.logicalId}.`,
-                });
+            if (presentation === undefined) {
+                return requestStorePurchase(request, undefined);
             }
-            const capabilities = await getCapabilities();
-            assertAvailable(capabilities.availability, store);
-            assertRequestPurchaseSupported(capabilities, request, mapping.kind);
-            // Pre-launch refusals below are data, not throws: a `failed` result
-            // keeps its `storeCode` across the bridge, a thrown error does not.
-            if (input.purchaseGate !== undefined) {
-                const refusal = await askPurchaseGate(input.purchaseGate, {
-                    store,
-                    logicalId: mapping.logicalId,
-                    storeSku: mapping.storeSku,
-                    kind: mapping.kind,
-                    source: request.source,
-                });
-                if (refusal !== undefined) {
-                    return { outcome: 'failed', error: refusal };
-                }
-            }
-            let accountBinding;
-            try {
-                accountBinding = await input.accountBinding?.();
-            }
-            catch (error) {
-                return { outcome: 'failed', error: accountBindingFailure(error, store) };
-            }
-            if (input.authority.accountBinding === 'required' && accountBinding === undefined) {
+            if ([...flights.values()].some((live) => live.idempotencyKey === request.idempotencyKey)) {
+                // Facts are keyed by idempotency key: a second sheet for a key whose
+                // sheet is still in flight could not be told apart from the first,
+                // and its end would end the first one's pause. Answered as data and
+                // without a fact; the first call's facts stay the key's truth.
                 return {
                     outcome: 'failed',
-                    error: new CommerceError('ACCOUNT_BINDING_REQUIRED', {
-                        message: `Store ${store} requires an account binding before a purchase.`,
+                    error: new CommerceError('IN_PROGRESS', {
+                        message: `A purchase for ${request.idempotencyKey} is still in flight.`,
                     }).toCommerceErrorInfo(),
                 };
             }
-            const offerId = request.offerId ?? mapping.offerId;
-            let result;
+            const flight = {
+                idempotencyKey: request.idempotencyKey,
+                presentationId: crypto.randomUUID(),
+                open: false,
+                pending: false,
+                launched: false,
+            };
+            flights.set(flight.presentationId, flight);
             try {
-                result = await sdk.requestPurchase({
-                    sku: mapping.storeSku,
-                    ...(offerId === undefined ? {} : { offerId }),
-                    ...(request.quantity === undefined ? {} : { quantity: request.quantity }),
-                    ...(accountBinding === undefined ? {} : { accountBinding }),
-                });
-            }
-            catch (error) {
-                return failureOutcome(undefined, normalize(error).toCommerceErrorInfo());
+                return await requestStorePurchase(request, flight.presentationId);
             }
-            if (!isRecord(result)) {
-                throw invalidRequestResult(store);
-            }
-            switch (result.outcome) {
-                case 'launched':
-                    return { outcome: 'launched' };
-                case 'purchased':
-                    return { outcome: 'purchased', purchase: toStorePurchase(result.purchase) };
-                case 'cancelled':
-                case 'failed':
-                    return failureOutcome(result.outcome, normalize(result.error).toCommerceErrorInfo());
-                default:
-                    throw invalidRequestResult(store);
+            finally {
+                // Settled without an `open` fact: no sheet opened. Published before
+                // the caller sees the answer, so a consumer that frees a retryable
+                // refusal's key (the reconciler) reads it with the result. A call
+                // whose SDK reported `unknown` keeps waiting for the native verdict
+                // (bounded by the safety timeout, which reports `closed`).
+                if (!flight.open && !flight.pending) {
+                    endFlight(flight, 'not-started');
+                }
             }
         },
         async getAvailablePurchases(request = {}) {
@@ -400,6 +534,15 @@ export function createStoreCommerceProvider(input) {
             for (const detach of detachers.splice(0, detachers.length)) {
                 detach();
             }
+            // No SDK fact arrives any more, and the listeners go below: every call
+            // in flight gets its terminal fact now. A sheet that is (or may be)
+            // up is reported closed; a call still before its sheet is not-started,
+            // and it will not open one.
+            disposed = true;
+            for (const flight of [...flights.values()]) {
+                endFlight(flight, flight.open || flight.pending || flight.launched ? 'closed' : 'not-started', 'disposed');
+            }
+            presentation?.clear();
             listeners.clear();
             buffer.drain(() => undefined);
         },

package/dist/store-sdk.d.ts

@@ -1,4 +1,4 @@
-import type { PlatformProviderAvailability } from '@mpgd/platform';
+import type { PlatformProviderAvailability, PlatformPurchasePresentationReason } from '@mpgd/platform';
 import { CommerceError, type CommerceErrorCode, type CommerceFinishOwner, type CommercePurchaseCapabilities, type FetchProductsType, type PurchaseKind, type StoreId, type StoreOffer, type StorePrice, type StorePurchaseAccountBinding, type StorePurchaseState } from '@mpgd/platform/commerce';
 /**
 * In-process surface a store plugin exposes to `createStoreCommerceProvider`.
@@ -26,6 +26,39 @@ export interface StoreSdk {
   addListener<TEvent extends StoreSdkEventName>(eventName: TEvent, listener: (event: StoreSdkEventOf<TEvent>) => void): () => void;
   /** Current readiness; omitted means the SDK is in-process and ready. */
   getAvailability?(): Promise<PlatformProviderAvailability>;
+  /**
+  * Native facts about the store's purchase sheet. Present only when the SDK
+  * (and the native code under it) reports them for every `requestPurchase`
+  * that carries a `presentationId`; `createStoreCommerceProvider` then
+  * offers `CommerceProvider.presentation`. An SDK without it keeps the
+  * provider without presentation, as before.
+  */
+  readonly purchasePresentation?: StoreSdkPurchasePresentation;
+}
+/**
+* The purchase sheet facts of one SDK. For a `requestPurchase` call with a
+* `presentationId` the SDK reports, by that id: `open` once the store sheet
+* is up, then exactly one `closed` when it is gone (which may come after the
+* call settled), or `not-started` when no sheet opened. A fact the call
+* settles without (the sheet never opened) means `not-started`, so an SDK
+* reports `open` before it settles whenever a sheet opened, and `unknown`
+* before it settles when it cannot tell yet (a terminal fact then follows). A transaction
+* update, a pending purchase, or a result is not a `closed` fact.
+*/
+export interface StoreSdkPurchasePresentation {
+  subscribe(listener: (event: StoreSdkPurchasePresentationEvent) => void): () => void;
+}
+export interface StoreSdkPurchasePresentationEvent {
+  readonly presentationId: string;
+  /**
+  * `unknown`: the call is answering while the native flow still runs and
+  * nothing was observed yet; the sheet may still open, and a terminal fact
+  * (`closed` or `not-started`) follows. The provider keeps the call waiting
+  * for it instead of reading the answer as a sheet that never opened.
+  */
+  readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
+  /** On a `closed` fact no native observation proved, why; see `PlatformPurchasePresentationReason`. */
+  readonly reason?: PlatformPurchasePresentationReason;
 }
 export interface StoreSdkCapabilities {
   readonly purchase: CommercePurchaseCapabilities;
@@ -55,6 +88,11 @@ export interface StoreSdkRequestPurchaseInput {
   readonly offerId?: string;
   readonly quantity?: number;
   readonly accountBinding?: StorePurchaseAccountBinding;
+  /**
+  * Correlates this call's `purchasePresentation` facts. Sent only to an SDK
+  * that declares `purchasePresentation`; unique per call.
+  */
+  readonly presentationId?: string;
 }
 export type StoreSdkRequestPurchaseResult = {
   readonly outcome: 'launched';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Capacitor platform adapter for mpgd Android and iOS shells.",
   "license": "MIT",
   "repository": {
@@ -51,11 +51,11 @@
   ],
   "dependencies": {
     "@capacitor/app": "8.1.1",
-    "@mpgd/capacitor-game-services": "0.9.4",
-    "@mpgd/game-services": "0.31.0",
-    "@mpgd/platform": "0.33.0",
-    "@mpgd/bridge": "0.17.0",
-    "@mpgd/target-config": "0.24.4"
+    "@mpgd/capacitor-game-services": "0.9.5",
+    "@mpgd/game-services": "0.32.0",
+    "@mpgd/target-config": "0.24.5",
+    "@mpgd/platform": "0.34.0",
+    "@mpgd/bridge": "0.18.0"
   },
   "peerDependencies": {
     "@capacitor-community/admob": "^8.1.0",
@@ -92,7 +92,7 @@
     "ttsc": "0.34.2",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/game-runtime": "0.8.10"
+    "@mpgd/game-runtime": "0.9.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",