@mpgd/capacitor-storekit 0.5.0 → 0.6.0

package/README.md

@@ -162,6 +162,45 @@ and lists each skipped vector with its reason (host or server finish,
 quantity, server-push, an asynchronous store error event StoreKit never
 emits, and a pending transaction state StoreKit never reports).
 
+### Purchase sheet facts
+
+The provider offers `CommerceProvider.presentation` (see "Store sheet facts"
+in the `@mpgd/adapter-capacitor` README), so the gateway keeps the game
+paused, and the game runtime keeps ads out, for the life of the purchase
+sheet rather than until a result event. The native plugin reports `open`
+right before OpenIAP calls `Product.purchase()` and `closed` when that call
+returns or throws, before it answers; a call it refuses earlier (invalid
+input, provider not ready, product unavailable) is `not-started`. An Ask to
+Buy (`pending`) is `closed` when the call returns; its purchase still arrives
+later through `transactionUpdated`. Facts reach JavaScript as
+`purchasePresentation` events (retained, keyed by a random id per call) and
+in the `presentation` field of the `purchase` answer or rejection data. The
+adapter adds a 15-minute safety timeout.
+
+Apple documents that `purchase(options:)` "displays the confirmation sheet"
+and returns a `PurchaseResult`
+([purchase(options:)](https://developer.apple.com/documentation/storekit/product/purchase(options:)),
+[purchase(confirmIn:options:)](https://developer.apple.com/documentation/storekit/product/purchase(confirmin:options:)-6dj6y)),
+but not that it returns only once the sheet is dismissed. `closed` therefore
+means "the purchase call ended"; that the sheet is gone by then is unverified
+until device testing.
+
+`getPresentationSupport` declares the facts. A web bundle running on a native
+build from before them (a live update) gets `UNIMPLEMENTED` there: while an
+adapter follows the facts, the store then reads `configuration-required` (the
+shop sells nothing and the reconciler spends no idempotency key), and a
+purchase that still gets through is refused with `CONFIGURATION_REQUIRED` /
+`STOREKIT_PRESENTATION_UNSUPPORTED` instead of opening a sheet the game would
+wait on; recovery is unaffected. `purchasePresentation: false` on the
+provider keeps the result-based pause of earlier releases.
+
+Device acceptance (not run; no device was available): the sheet cancelled, a
+completed purchase, an Ask to Buy request, the app backgrounded with the
+sheet up and resumed, and an iPad (sheet as a form sheet). Each must pause
+the game from `open` to `closed`, and `closed` must not arrive while the sheet
+is still visible. The steps and expected signals are in the kit's
+[purchase device acceptance checklist](https://github.com/imjlk/mpgd-kit/blob/main/docs/PURCHASE_DEVICE_ACCEPTANCE.md).
+
 ### Generated games
 
 Games generated by `mpgd game create` (and the kit's private starter) ship

package/dist/commerce-provider.d.ts

@@ -39,6 +39,16 @@ export interface CreateCapacitorStoreKitCommerceProviderInput {
   * types that disagree with the catalog kind. Diagnostics only.
   */
   readonly onDiagnostic?: (diagnostic: CapacitorStoreKitDiagnostic) => void;
+  /**
+  * Purchase sheet facts (default true): the provider offers `presentation`
+  * (`open` before `Product.purchase()`, `closed` when it returns or
+  * throws), so the gateway and the game runtime pause until the sheet is
+  * done, not until a result. Needs an app built with this package's native
+  * code (otherwise new purchases are refused with
+  * `STOREKIT_PRESENTATION_UNSUPPORTED`). False keeps the result-based pause
+  * of earlier releases.
+  */
+  readonly purchasePresentation?: boolean;
 }
 /**
 * Commerce v2 `CommerceProvider` for the App Store: `createStoreCommerceProvider`

package/dist/commerce-provider.js

@@ -42,6 +42,9 @@ export function createCapacitorStoreKitCommerceProvider(input) {
         ...(input.sdk === undefined ? {} : { sdk: input.sdk }),
         ...(input.isIos === undefined ? {} : { isIos: input.isIos }),
         ...(input.onDiagnostic === undefined ? {} : { onDiagnostic: input.onDiagnostic }),
+        ...(input.purchasePresentation === undefined
+            ? {}
+            : { purchasePresentation: input.purchasePresentation }),
     });
     return refuseNewPurchasesUnlessGated(createStoreCommerceProvider({
         sdk,

package/dist/definitions.d.ts

@@ -26,12 +26,38 @@ export interface StoreKitTransaction {
   */
   readonly unfinished?: boolean;
 }
-export type StoreKitPurchaseOutcome = {
+export type StoreKitPurchaseOutcome = ({
   readonly status: 'purchased';
   readonly transaction: StoreKitTransaction;
 } | {
   readonly status: 'pending' | 'cancelled';
+}) & {
+  /**
+  * The purchase sheet when a `purchase` call with a `presentationId`
+  * answered (also in a rejection's `data`): `closed` once
+  * `Product.purchase()` returned or threw, `not-started` when the plugin
+  * refused before calling it.
+  */
+  readonly presentation?: StoreKitPurchaseAnswerPresentation;
 };
+export type StoreKitPurchasePresentationState = 'open' | 'closed' | 'not-started';
+export type StoreKitPurchaseAnswerPresentation = StoreKitPurchasePresentationState | 'requested';
+/**
+* A sheet fact for the `purchase` call that sent `presentationId`: `open`
+* right before `Product.purchase()`, `closed` when it returns or throws,
+* `not-started` when the plugin refused before it. Apple documents that the
+* call presents the confirmation sheet, not that it returns only once the
+* sheet is gone; see the README.
+*/
+export interface StoreKitPurchasePresentationEvent {
+  readonly presentationId: string;
+  readonly state: StoreKitPurchasePresentationState;
+  readonly reason?: 'interrupted';
+}
+/** What `getPresentationSupport` declares; `purchasePresentation` is the facts protocol version. */
+export interface StoreKitPresentationSupport {
+  readonly purchasePresentation: number;
+}
 export interface CapacitorStoreKitPlugin {
   getProducts(input: {
     readonly productIds: readonly string[];
@@ -41,7 +67,15 @@ export interface CapacitorStoreKitPlugin {
   purchase(input: {
     readonly productId: string;
     readonly appAccountToken: string;
+    /** Asks for this call's sheet facts (`purchasePresentation`); 1-64 of `[A-Za-z0-9-]`. */
+    readonly presentationId?: string;
   }): Promise<StoreKitPurchaseOutcome>;
+  /**
+  * Declares the sheet facts the native code reports. A native build from
+  * before them answers `UNIMPLEMENTED`; optional so a plugin double without
+  * it still type-checks, and then the SDK refuses purchases that need facts.
+  */
+  getPresentationSupport?(): Promise<StoreKitPresentationSupport>;
   /** Includes unfinished consumables and current non-consumable entitlements. */
   getTransactions(): Promise<{
     readonly transactions: readonly StoreKitTransaction[];
@@ -69,4 +103,6 @@ export interface CapacitorStoreKitPlugin {
     readonly finished: boolean;
   }>;
   addListener(eventName: 'transactionUpdated', listener: (event: StoreKitTransaction) => void): Promise<PluginListenerHandle>;
+  /** Sheet facts of `purchase` calls that sent a `presentationId`. */
+  addListener(eventName: 'purchasePresentation', listener: (event: StoreKitPurchasePresentationEvent) => void): Promise<PluginListenerHandle>;
 }

package/dist/purchase-presentation.d.ts

@@ -0,0 +1,27 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+export type StoreKitPurchasePresentationState = 'open' | 'closed' | 'not-started' | 'unknown';
+/** A sheet fact of one `requestPurchase` call; see `StoreSdkPurchasePresentationEvent`. */
+export interface StoreKitSdkPurchasePresentationEvent {
+  readonly presentationId: string;
+  readonly state: StoreKitPurchasePresentationState;
+  readonly reason?: 'interrupted' | 'timeout';
+}
+/** The SDK's `purchasePresentation`; see `StoreSdkPurchasePresentation` in `@mpgd/adapter-capacitor`. */
+export interface StoreKitSdkPurchasePresentation {
+  subscribe(listener: (event: StoreKitSdkPurchasePresentationEvent) => void): () => void;
+}
+/** See `NativePurchasePresentation` in `@mpgd/adapter-capacitor`. */
+export interface StoreKitNativePurchasePresentation {
+  readonly purchasePresentation: StoreKitSdkPurchasePresentation;
+  supported(): Promise<boolean>;
+  followed(): boolean;
+  begin(presentationId: string): void;
+  answered(presentationId: string, answerOrError: unknown): void;
+}
+/** The native surface the facts need: the plugin's event and support check. */
+export interface StoreKitNativePresentationPlugin {
+  addListener(eventName: 'purchasePresentation', listener: (event: unknown) => void): Promise<PluginListenerHandle>;
+  readonly getPresentationSupport?: () => Promise<unknown>;
+}
+/** The adapter's facts helper over `native`, or undefined with an adapter from before it. */
+export declare function resolveStoreKitNativePurchasePresentation(native: StoreKitNativePresentationPlugin, adapterExports?: object): StoreKitNativePurchasePresentation | undefined;

package/dist/purchase-presentation.js

@@ -0,0 +1,9 @@
+import * as adapterCapacitor from '@mpgd/adapter-capacitor';
+/** The adapter's facts helper over `native`, or undefined with an adapter from before it. */
+export function resolveStoreKitNativePurchasePresentation(native, adapterExports = adapterCapacitor) {
+    const factory = adapterExports.createNativePurchasePresentation;
+    if (typeof factory !== 'function') {
+        return undefined;
+    }
+    return factory(native);
+}

package/dist/store-sdk.d.ts

@@ -2,8 +2,18 @@ import { type StoreSdk, type StoreSdkErrorCodeMap, type StoreSdkPurchase } from
 import type { StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
 import type { CapacitorStoreKitPlugin, StoreKitTransaction } from './definitions.js';
 import { storeKitStoreSdkCapabilities } from './commerce-profile.js';
+import { type StoreKitSdkPurchasePresentation } from './purchase-presentation.js';
+export type { StoreKitSdkPurchasePresentation, StoreKitSdkPurchasePresentationEvent, } from './purchase-presentation.js';
 /** The plugin surface the commerce v2 SDK drives; `CapacitorStoreKit` by default. */
-export type CapacitorStoreKitStoreSdkPlugin = Pick<CapacitorStoreKitPlugin, 'getProducts' | 'purchase' | 'getTransactions' | 'sync' | 'finishTransaction' | 'addListener'>;
+export type CapacitorStoreKitStoreSdkPlugin = Pick<CapacitorStoreKitPlugin, 'getProducts' | 'purchase' | 'getTransactions' | 'sync' | 'finishTransaction' | 'addListener' | 'getPresentationSupport'>;
+/**
+* The code of a purchase refused because the native plugin in the app binary
+* reports no sheet facts (a web bundle newer than its native build). The
+* provider offers `presentation`, so a purchase it could not follow is not
+* sold; rebuilding the app with this package's native code, or
+* `purchasePresentation: false`, sells again. Recovery is unaffected.
+*/
+export declare const storeKitPresentationUnsupportedCode: 'STOREKIT_PRESENTATION_UNSUPPORTED';
 /** One-time kinds the App Store sells; `durable` is a StoreKit non-consumable. */
 export type StoreKitOneTimeKind = 'consumable' | 'durable';
 /** A store SKU the SDK is configured to sell and the kind the catalog declares for it. */
@@ -47,7 +57,20 @@ export interface CreateCapacitorStoreKitStoreSdkInput {
   readonly isIos?: () => boolean;
   /** Observes transactions the SDK excludes; never a grant signal. */
   readonly onDiagnostic?: (diagnostic: CapacitorStoreKitDiagnostic) => void;
+  /**
+  * Report the purchase sheet's facts (`purchasePresentation`), so the
+  * adapter's provider offers `CommerceProvider.presentation` and the game
+  * pauses until `Product.purchase()` returns rather than until a result
+  * event. Defaults to true. A native build without the facts then refuses
+  * new purchases with `STOREKIT_PRESENTATION_UNSUPPORTED`; false keeps the
+  * result-based pause of earlier releases.
+  */
+  readonly purchasePresentation?: boolean;
 }
+/** The StoreKit `StoreSdk`, with the sheet facts it declares unless turned off. */
+export type CapacitorStoreKitStoreSdk = StoreSdk & {
+  readonly purchasePresentation?: StoreKitSdkPurchasePresentation;
+};
 /**
 * Capacitor StoreKit `StoreSdk`: the commerce v2 surface over the native
 * StoreKit 2 collector (RFC B3). The App Store profile is consumable plus
@@ -67,7 +90,7 @@ export interface CreateCapacitorStoreKitStoreSdkInput {
 * or on a new device; the reconciler sends them with `intent: 'restore'` and
 * the backend's restore sharing decides (RFC "Restore sharing").
 */
-export declare function createCapacitorStoreKitStoreSdk(input: CreateCapacitorStoreKitStoreSdkInput): StoreSdk;
+export declare function createCapacitorStoreKitStoreSdk(input: CreateCapacitorStoreKitStoreSdkInput): CapacitorStoreKitStoreSdk;
 export { storeKitStoreSdkCapabilities };
 /**
 * StoreKit plugin codes merged over `defaultStoreSdkErrorCodeMap`. Codes the

package/dist/store-sdk.js

@@ -2,6 +2,15 @@ import { Capacitor } from '@capacitor/core';
 import { defaultStoreSdkErrorCodeMap, } from '@mpgd/adapter-capacitor';
 import { appStoreStoreId, storeKitStoreSdkCapabilities } from './commerce-profile.js';
 import { CapacitorStoreKit } from './plugin.js';
+import { resolveStoreKitNativePurchasePresentation, } from './purchase-presentation.js';
+/**
+ * The code of a purchase refused because the native plugin in the app binary
+ * reports no sheet facts (a web bundle newer than its native build). The
+ * provider offers `presentation`, so a purchase it could not follow is not
+ * sold; rebuilding the app with this package's native code, or
+ * `purchasePresentation: false`, sells again. Recovery is unaffected.
+ */
+export const storeKitPresentationUnsupportedCode = 'STOREKIT_PRESENTATION_UNSUPPORTED';
 /**
  * Capacitor StoreKit `StoreSdk`: the commerce v2 surface over the native
  * StoreKit 2 collector (RFC B3). The App Store profile is consumable plus
@@ -23,6 +32,10 @@ import { CapacitorStoreKit } from './plugin.js';
  */
 export function createCapacitorStoreKitStoreSdk(input) {
     const sdk = input.sdk ?? CapacitorStoreKit;
+    // Sheet facts of `purchase` calls that carry a presentation id.
+    const presentation = input.purchasePresentation === false
+        ? undefined
+        : resolveStoreKitNativePurchasePresentation(sdk);
     const isIos = input.isIos ?? (() => Capacitor.getPlatform() === 'ios');
     const onDiagnostic = input.onDiagnostic ?? (() => undefined);
     if (typeof input.getAppAccountToken !== 'function') {
@@ -332,6 +345,7 @@ export function createCapacitorStoreKitStoreSdk(input) {
     };
     return {
         store: appStoreStoreId,
+        ...(presentation === undefined ? {} : { purchasePresentation: presentation.purchasePresentation }),
         capabilities: storeKitStoreSdkCapabilities,
         async fetchProducts(request) {
             requireIos();
@@ -354,7 +368,33 @@ export function createCapacitorStoreKitStoreSdk(input) {
             requireIos();
             const appAccountToken = readAppAccountToken(request.accountBinding);
             const expected = await assertSellable(request.sku);
-            const outcome = await sdk.purchase({ productId: request.sku, appAccountToken });
+            // Only an adapter that reads sheet facts sends an id (one from before
+            // them never does, and the purchase runs as in earlier releases).
+            const presentationId = presentation === undefined ? undefined : request.presentationId;
+            if (presentation !== undefined && presentationId !== undefined) {
+                if (!(await presentation.supported())) {
+                    throw storeKitError(storeKitPresentationUnsupportedCode, 'The app was built with a StoreKit plugin that reports no purchase sheet facts; '
+                        + "rebuild it with this package's native code.", false);
+                }
+                presentation.begin(presentationId);
+            }
+            let outcome;
+            try {
+                outcome = await sdk.purchase({
+                    productId: request.sku,
+                    appAccountToken,
+                    ...(presentationId === undefined ? {} : { presentationId }),
+                });
+            }
+            catch (error) {
+                if (presentationId !== undefined) {
+                    presentation?.answered(presentationId, error);
+                }
+                throw error;
+            }
+            if (presentationId !== undefined) {
+                presentation?.answered(presentationId, outcome);
+            }
             if (!isRecord(outcome)) {
                 throw evidenceInvalid('StoreKit returned an invalid purchase result.');
             }
@@ -494,6 +534,12 @@ export function createCapacitorStoreKitStoreSdk(input) {
             if (productIds.length === 0) {
                 return 'configuration-required';
             }
+            // An adapter that reads sheet facts over a native build without them
+            // would refuse every purchase: report the store as needing a rebuild,
+            // so the shop sells nothing and no idempotency key is spent.
+            if (presentation !== undefined && presentation.followed() && !(await presentation.supported())) {
+                return 'configuration-required';
+            }
             try {
                 // Probe batch by batch until one configured product is sold; only a
                 // catalog with no sellable product at all is a configuration problem.
@@ -543,6 +589,7 @@ export const storeKitStoreSdkErrorCodeMap = Object.freeze({
     STOREKIT_FINISH_REQUIRES_GRANT: 'CONFIGURATION_REQUIRED',
     STOREKIT_EVIDENCE_INVALID: 'INVALID_RESPONSE',
     STOREKIT_TRANSACTION_UNVERIFIED: 'INVALID_RESPONSE',
+    STOREKIT_PRESENTATION_UNSUPPORTED: 'CONFIGURATION_REQUIRED',
 });
 /** The default table plus every StoreKit code; what the provider uses. */
 export const capacitorStoreKitErrorCodeMap = Object.freeze({

package/ios/Sources/CapacitorStoreKit/CapacitorStoreKitPlugin.swift

@@ -18,7 +18,8 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "purchase", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getTransactions", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "sync", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "finishTransaction", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "finishTransaction", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getPresentationSupport", returnType: CAPPluginReturnPromise)
     ]
 
     private let connection = OpenIapAppleConnection()
@@ -79,25 +80,57 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    /// Declares the sheet facts this native code reports
+    /// (`purchasePresentation` events and the `presentation` field of
+    /// `purchase` answers). A build without this method answers
+    /// `UNIMPLEMENTED`, and the TypeScript SDK then sells nothing that would
+    /// wait for facts.
+    @objc func getPresentationSupport(_ call: CAPPluginCall) {
+        call.resolve(["purchasePresentation": MpgdPurchaseSheet.protocolVersion])
+    }
+
     @objc func purchase(_ call: CAPPluginCall) {
+        // Correlates this call's sheet facts; sent only by a TypeScript SDK
+        // that reads them. Without it the call reports no facts, as before.
+        let presentationId = call.getString("presentationId")
+        if presentationId != nil && !MpgdPurchaseSheet.isValidPresentationId(presentationId) {
+            call.reject("The presentation id is invalid.", "STOREKIT_INVALID_PURCHASE", nil,
+                        ["presentation": MpgdPurchaseSheet.Fact.notStarted.rawValue])
+            return
+        }
+        let sheet = presentationId.map { id in
+            MpgdPurchaseSheet(presentationId: id) { [weak self] id, fact in
+                self?.notifyPresentation(id, fact)
+            }
+        }
         guard let productId = call.getString("productId"),
               StoreKitTransactionPolicy.isValidProductId(productId),
               let accountToken = StoreKitTransactionPolicy.normalizedAccountToken(
                 call.getString("appAccountToken"), allowNil: true) else {
-            call.reject("A product ID and app account token are required.", "STOREKIT_INVALID_PURCHASE")
+            sheet?.end()
+            call.reject("A product ID and app account token are required.", "STOREKIT_INVALID_PURCHASE",
+                        nil, Self.presentationData(sheet))
+            return
+        }
+        if let message = connection.providerError {
+            sheet?.end()
+            call.reject(message, "STOREKIT_CONFIGURATION_ERROR", nil, Self.presentationData(sheet))
             return
         }
-        guard providerReady(call) else { return }
         Task { @MainActor [module] in
             do {
                 let result = try await module.fetchProducts(ProductRequest(skus: [productId], type: .inApp))
                 guard let product = Self.iosProducts(result).first(where: { $0.id == productId }),
                       MpgdOneTimeType(productType: product.typeIOS) != nil else {
-                    call.reject("The one-time product is unavailable.", "STOREKIT_PRODUCT_UNAVAILABLE")
+                    sheet?.end()
+                    call.reject("The one-time product is unavailable.", "STOREKIT_PRODUCT_UNAVAILABLE",
+                                nil, Self.presentationData(sheet))
                     return
                 }
             } catch {
-                call.reject("StoreKit product lookup failed.", "STOREKIT_PRODUCT_LOOKUP_FAILED", error)
+                sheet?.end()
+                call.reject("StoreKit product lookup failed.", "STOREKIT_PRODUCT_LOOKUP_FAILED", error,
+                            Self.presentationData(sheet))
                 return
             }
             let request = RequestPurchaseProps(
@@ -109,40 +142,68 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
                 ))),
                 type: .inApp
             )
+            // `open` right before OpenIAP calls `Product.purchase()`, which
+            // presents the sheet; `closed` once that call returned or threw,
+            // before the answer, which carries the same fact.
+            sheet?.open()
             do {
                 let outcome = try await module.requestPurchase(request)
+                sheet?.end()
                 guard case .purchase(let purchased?) = outcome,
                       case .purchaseIos(let ios) = purchased,
                       let transaction = StoreKitTransactionPolicy.transaction(from: ios),
                       StoreKitTransactionPolicy.matchesPurchaseRequest(
                         transaction, productId: productId, appAccountToken: accountToken) else {
                     call.reject("StoreKit transaction failed verification or account binding.",
-                                "STOREKIT_TRANSACTION_UNVERIFIED")
+                                "STOREKIT_TRANSACTION_UNVERIFIED", nil, Self.presentationData(sheet))
                     return
                 }
-                call.resolve([
+                call.resolve(Self.withPresentation([
                     "status": "purchased",
                     "transaction": StoreKitTransactionPolicy.payload(transaction)
-                ])
+                ], sheet))
             } catch let error as PurchaseError {
+                sheet?.end()
                 switch StoreKitTransactionPolicy.purchaseFailure(error.code) {
                 case .cancelled:
-                    call.resolve(["status": "cancelled"])
+                    call.resolve(Self.withPresentation(["status": "cancelled"], sheet))
                 case .pending:
                     // Ask to Buy: the approved transaction arrives through
-                    // `transactionUpdated` or `getTransactions` later.
-                    call.resolve(["status": "pending"])
+                    // `transactionUpdated` or `getTransactions` later. The
+                    // sheet itself is done.
+                    call.resolve(Self.withPresentation(["status": "pending"], sheet))
                 case .rejected(let code, let message):
-                    call.reject(message, code, error)
+                    call.reject(message, code, error, Self.presentationData(sheet))
                 }
             } catch {
+                sheet?.end()
                 // The purchase sheet may have completed before an error reached us.
                 call.reject("StoreKit purchase result is uncertain; requery transactions.",
-                            "STOREKIT_PURCHASE_UNCERTAIN", error)
+                            "STOREKIT_PURCHASE_UNCERTAIN", error, Self.presentationData(sheet))
             }
         }
     }
 
+    /// Retained until a listener consumes it; the random id keeps a fact of
+    /// an earlier web session from matching a new call.
+    private func notifyPresentation(_ presentationId: String, _ fact: MpgdPurchaseSheet.Fact) {
+        notifyListeners("purchasePresentation",
+                        data: ["presentationId": presentationId, "state": fact.rawValue],
+                        retainUntilConsumed: true)
+    }
+
+    private static func presentationData(_ sheet: MpgdPurchaseSheet?) -> [String: Any]? {
+        guard let sheet else { return nil }
+        return ["presentation": sheet.answer]
+    }
+
+    private static func withPresentation(_ answer: [String: Any], _ sheet: MpgdPurchaseSheet?) -> [String: Any] {
+        guard let sheet else { return answer }
+        var answered = answer
+        answered["presentation"] = sheet.answer
+        return answered
+    }
+
     @objc func getTransactions(_ call: CAPPluginCall) {
         guard providerReady(call) else { return }
         Task {

package/ios/Sources/MpgdStoreKitBridge/PurchaseSheet.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+/// The purchase sheet facts of one `purchase` call that sent a presentation
+/// id. The plugin reports `open` right before OpenIAP calls
+/// `Product.purchase()` and `closed` when that returns or throws; a call it
+/// refuses before then is `not-started`. Each sheet reports at most one
+/// `open` and exactly one terminal fact, whatever order the plugin calls
+/// these in. Apple documents that `Product.purchase()` presents the
+/// confirmation sheet, not that it returns only once the sheet is dismissed,
+/// so `closed` is "the purchase call ended" until device testing proves more.
+public final class MpgdPurchaseSheet {
+    public enum Fact: String, Sendable {
+        case open
+        case closed
+        case notStarted = "not-started"
+    }
+
+    /// The facts protocol version `getPresentationSupport` declares.
+    public static let protocolVersion = 1
+
+    public let presentationId: String
+    private let emit: (String, Fact) -> Void
+    private var opened = false
+    public private(set) var ended: Fact?
+
+    public init(presentationId: String, emit: @escaping (String, Fact) -> Void) {
+        self.presentationId = presentationId
+        self.emit = emit
+    }
+
+    /// The `presentation` value of the call's answer: the terminal fact, or
+    /// `open` while the sheet is up, or `requested` before anything happened.
+    public var answer: String {
+        if let ended { return ended.rawValue }
+        return opened ? Fact.open.rawValue : "requested"
+    }
+
+    public func open() {
+        guard ended == nil, !opened else { return }
+        opened = true
+        emit(presentationId, .open)
+    }
+
+    /// The purchase call ended: `closed` after `open`, otherwise `not-started`.
+    public func end() {
+        guard ended == nil else { return }
+        let fact: Fact = opened ? .closed : .notStarted
+        ended = fact
+        emit(presentationId, fact)
+    }
+
+    /// 1-64 characters of `[A-Za-z0-9-]`, as the TypeScript SDK sends (a UUID).
+    public static func isValidPresentationId(_ value: String?) -> Bool {
+        guard let value, !value.isEmpty, value.count <= 64 else { return false }
+        return value.unicodeScalars.allSatisfy { scalar in
+            (scalar.value >= 0x30 && scalar.value <= 0x39)
+                || (scalar.value >= 0x41 && scalar.value <= 0x5A)
+                || (scalar.value >= 0x61 && scalar.value <= 0x7A)
+                || scalar == "-"
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Opt-in StoreKit 2 one-time purchase collector and commerce v2 provider for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -38,18 +38,18 @@
   ],
   "peerDependencies": {
     "@capacitor/core": "^8.5.1",
-    "@mpgd/adapter-capacitor": "^0.17.0",
-    "@mpgd/bridge": "^0.17.0",
-    "@mpgd/platform": "^0.33.0"
+    "@mpgd/adapter-capacitor": "^0.18.0",
+    "@mpgd/bridge": "^0.18.0",
+    "@mpgd/platform": "^0.34.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
     "ttsc": "0.34.2",
     "typescript": "7.0.2",
-    "@mpgd/adapter-capacitor": "0.17.0",
-    "@mpgd/bridge": "0.17.0",
-    "@mpgd/game-services": "0.31.0",
-    "@mpgd/platform": "0.33.0"
+    "@mpgd/adapter-capacitor": "0.18.0",
+    "@mpgd/bridge": "0.18.0",
+    "@mpgd/platform": "0.34.0",
+    "@mpgd/game-services": "0.32.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,6 +59,6 @@
   "scripts": {
     "check": "ttsc --noEmit",
     "lint": "ttsc --noEmit",
-    "test": "cd ../.. && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/store-sdk.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-profile.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-provider.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-provider.conformance.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-reconciler-storekit-smoke.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/openiap-engine-swap.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-restore-reinstall.test.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/store-sdk.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-profile.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-provider.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-provider.conformance.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-reconciler-storekit-smoke.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/openiap-engine-swap.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/commerce-restore-reinstall.test.ts && node tools/run-ttsx.mjs --project native-plugins/capacitor-storekit/tsconfig.json native-plugins/capacitor-storekit/src/purchase-presentation.test.ts"
   }
 }