@mpgd/adapter-capacitor 0.17.0 → 0.19.0

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,12 +269,95 @@ 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;
+    /** The SDK reads `revoked` and has a finish to take it. */
+    const revokedFinish = finishTransaction !== undefined && sdk.acceptsRevokedFinish === true;
     const provider = {
         store,
+        ...(presentation === undefined ? {} : { presentation: presentation.presentation }),
         // `retry` is forwarded to the SDK below.
         ...(finishTransaction === undefined ? {} : { acceptsFinishRetry: true }),
+        // `revoked` is forwarded only to an SDK that reads it.
+        ...(revokedFinish ? { acceptsRevokedFinish: true } : {}),
         getCapabilities,
         async fetchProducts(request = {}) {
             const type = request.type ?? 'all';
@@ -251,70 +418,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}.`,
-                });
-            }
-            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 (presentation === undefined) {
+                return requestStorePurchase(request, undefined);
             }
-            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 }),
-                });
+                return await requestStorePurchase(request, flight.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);
+            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 = {}) {
@@ -342,7 +480,14 @@ export function createStoreCommerceProvider(input) {
                 const purchase = toStorePurchase(candidate);
                 // A revoked purchase is not recoverable, and a pending one is listed
                 // only on request; both still reach the reconciler through events.
-                if (purchase.state === 'revoked' || (purchase.state === 'pending' && !includePending)) {
+                // An SDK that finishes revoked transactions keeps its unfinished
+                // revoked consumables listed (the only kind a revoked finish takes):
+                // the reconciler finishes them once the backend answered for them,
+                // and verifies or grants none of them. A revoked purchase of another
+                // kind, or of a SKU the catalog does not map, stays filtered.
+                if ((purchase.state === 'revoked'
+                    && !(revokedFinish && bySku.get(candidate.sku)?.kind === 'consumable'))
+                    || (purchase.state === 'pending' && !includePending)) {
                     continue;
                 }
                 purchases.push(purchase);
@@ -354,14 +499,26 @@ export function createStoreCommerceProvider(input) {
                 // Finishing is authorized by a ledger entry only; the id is validated
                 // before the store hears about it.
                 const finish = assertFinishTransactionInput(request);
+                if (finish.revoked === true && !revokedFinish) {
+                    // Never an ordinary finish in its place: the SDK cannot tell the
+                    // two apart, and this one would run without a grant.
+                    return { finished: false };
+                }
                 let reported;
                 try {
-                    reported = await finishTransaction.call(sdk, {
-                        transactionId: finish.transactionId,
-                        isConsumable: finish.isConsumable,
-                        ledgerEntryId: finish.ledgerEntryId,
-                        ...(finish.retry === true ? { retry: true } : {}),
-                    });
+                    reported = await finishTransaction.call(sdk, finish.revoked === true
+                        ? {
+                            transactionId: finish.transactionId,
+                            isConsumable: true,
+                            revoked: true,
+                            ...(finish.ledgerEntryId === undefined ? {} : { ledgerEntryId: finish.ledgerEntryId }),
+                        }
+                        : {
+                            transactionId: finish.transactionId,
+                            isConsumable: finish.isConsumable,
+                            ledgerEntryId: finish.ledgerEntryId,
+                            ...(finish.retry === true ? { retry: true } : {}),
+                        });
                 }
                 catch (error) {
                     throw normalize(error);
@@ -400,6 +557,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`.
@@ -21,11 +21,54 @@ export interface StoreSdk {
   getAvailablePurchases(input: StoreSdkGetAvailablePurchasesInput): Promise<readonly StoreSdkPurchase[]>;
   /** Present when `capabilities.finish` is 'client' or 'host'. Called only after a ledger grant. */
   finishTransaction?(input: StoreSdkFinishTransactionInput): Promise<StoreSdkFinishTransactionResult>;
+  /**
+  * `finishTransaction` reads `revoked`: it finishes a transaction it still
+  * lists as revoked, and only that. `createStoreCommerceProvider` then
+  * declares `CommerceProvider.acceptsRevokedFinish` and keeps the revoked
+  * consumables `getAvailablePurchases` reports (still unfinished in the
+  * store) in its list, so the reconciler can finish them on a later launch; an SDK
+  * without it never receives the field, so a store that would read the call
+  * as an ordinary finish (a consume) is never asked.
+  */
+  readonly acceptsRevokedFinish?: boolean;
   /** Asks the store to resynchronize, for example `AppStore.sync`. */
   restorePurchases?(): Promise<void>;
   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 +98,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';
@@ -88,13 +136,29 @@ export interface StoreSdkPurchase {
   /** Store-specific detail the provider never reads; kept for diagnostics only. */
   readonly raw?: Readonly<Record<string, unknown>>;
 }
-export interface StoreSdkFinishTransactionInput {
+/**
+* What `StoreSdk.finishTransaction` is asked to finish: a purchase the
+* backend ledger granted, or (only for an SDK that declares
+* `acceptsRevokedFinish`) a consumable the store revoked while it was still
+* unfinished, which no grant stands for.
+*/
+export type StoreSdkFinishTransactionInput = StoreSdkGrantedFinishTransactionInput | StoreSdkRevokedFinishTransactionInput;
+export interface StoreSdkGrantedFinishTransactionInput {
   readonly transactionId: string;
   readonly isConsumable: boolean;
   /** `FinishTransactionInput.retry`: an earlier finish of this purchase was asked for. */
   readonly retry?: boolean;
   /** The ledger entry that authorized the finish; a plugin may record it. */
   readonly ledgerEntryId: string;
+  readonly revoked?: false;
+}
+/** `RevokedFinishTransactionInput`: finish a revoked consumable, granting nothing. */
+export interface StoreSdkRevokedFinishTransactionInput {
+  readonly transactionId: string;
+  readonly isConsumable: true;
+  readonly revoked: true;
+  /** The reversed grant's ledger entry; absent when nothing was ever granted. */
+  readonly ledgerEntryId?: string;
 }
 export interface StoreSdkFinishTransactionResult {
   readonly finished: boolean;