@mpgd/capacitor-storekit 0.5.0 → 0.7.0

package/README.md

@@ -59,14 +59,19 @@ over `getTransactions`, listing unfinished transactions and finished durables
 once (a current non-consumable entitlement the native side marks
 `unfinished: false` stays listed so a finish that raced the ledger grant can
 still be verified; the server ledger dedupes. A finished consumable is not
-listed. A `revokedAt` maps to `state: 'revoked'`, and one malformed
+listed. A `revokedAt` maps to `state: 'revoked'`, and an unfinished revoked
+transaction stays listed in that state so a refund before the finish can be
+finished later (see Recovery); one malformed
 transaction is reported as a `purchaseError` without blocking its siblings);
-`finishTransaction({ transactionId, ledgerEntryId, isConsumable, retry? })`
+`finishTransaction({ transactionId, ledgerEntryId, isConsumable, retry?, revoked? })`
 resolves the session app account token and finishes only a listed,
-non-revoked transaction bound to that token, or a durable of another token a
-restore shared to this player (see Recovery), and on a retry (`retry: true`)
+non-revoked transaction bound to that token, or a durable of another token or
+of no token a restore shared to this player (see Recovery), and on a retry (`retry: true`)
 answers `finished: true` without a native call for a consumable the list no
-longer carries (a lost acknowledgement, see Recovery);
+longer carries (a lost acknowledgement, see Recovery); with `revoked: true`
+(the SDK declares `acceptsRevokedFinish`; `ledgerEntryId` may then be
+absent) it finishes only a listed, revoked consumable bound to that token (a
+refund before the finish, see Recovery);
 `restorePurchases` over `sync`; `transactionUpdated` as `purchaseUpdated`;
 and an availability probe as `getAvailability`, probing the configured
 SKUs batch by batch until one is sold. Every purchase carries the
@@ -116,7 +121,9 @@ where `signedTransaction` is the same JWS as `StorePurchase.token`.
 its `signedTransactionVerifier` (authenticity and transaction id binding)
 and then, by default, decides the grant on the transaction's current status
 from the App Store Server API, so a JWS retained from before a refund never
-grants; see the backend guide for the opt-in offline-only mode. Subscription
+grants; see the backend guide for the opt-in offline-only mode, which instead
+refuses a refund the backend recorded from App Store Server Notifications
+(its `revocations` registry is required). Subscription
 mappings are rejected at construction. `getAppAccountToken` also filters
 recovery and finishing to the current player, so it must keep answering
 while sales are paused: pause new sales with the optional `purchaseGate`
@@ -162,6 +169,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
@@ -201,7 +247,7 @@ existing ledger grant, and calls `finishTransaction` only after a verified
 response with a ledger entry id. The StoreKit SDK and the native plugin both
 refuse to call `transaction.finish()` on a transaction whose app account
 token is missing or does not match the token they are given; the SDK gives the
-session's, except for a durable of another token (below). A caller who can read the token from the plugin can
+session's, except for a durable of another token or of no token (below). A caller who can read the token from the plugin can
 still present it with a forged ledger entry id; that remaining hole needs a
 signed server finish capability. A listed, non-revoked durable StoreKit
 already finished (`unfinished: false`) answers `{ finished: true }` without a
@@ -217,8 +263,38 @@ durable takes nothing from the earlier guest: StoreKit keeps it in
 (`unfinished: false`). The native plugin is unchanged and still filters
 nothing by token on reads. A webview caller can therefore finish another
 token's unfinished durable, which, for the same reason, grants or removes
-nothing. A consumable of another token and a transaction bound to no token
-are never finished. Permanently rejected and account-mismatched
+nothing.
+
+A durable of the configured catalog still unfinished and bound to no token
+(an offer code redeemed in the App Store, or another purchase made outside
+the app, then restored; the backend's restore sharing grants it as
+`APP_STORE_ACCOUNT_TOKEN_MISSING`) is finished with the explicit no-token
+match: `finishTransaction({ transactionId, ledgerEntryId,
+withoutAppAccountToken: true })`, with no `appAccountToken` field at all.
+The native plugin then matches only a verified, non-revoked non-consumable
+bound to no token; a missing token without the flag is still refused
+(`STOREKIT_FINISH_REQUIRES_GRANT`), never read as "any token". The SDK sends
+it only for a durable its catalog declares, for a record the reconciler
+holds a ledger grant for, and only when the native build declares the match
+through `getFinishSupport` (`{ withoutAppAccountToken: 1 }`). A native build
+from before it answers that method with `UNIMPLEMENTED` (remembered) and would
+refuse the call, so the SDK leaves the durable unfinished there and the record
+keeps retrying `finishing`, as in earlier releases; the entitlement is
+unaffected. Rebuild the app with this package's native code to finish it.
+The catalog and ledger-grant conditions are the SDK's and the reconciler's;
+the native match checks only the transaction itself and, like the token
+match, is not a signed server capability, so a webview caller could finish
+such a durable too, which grants or removes nothing.
+Finishing takes nothing from anyone for the same reason as above:
+StoreKit keeps a finished non-consumable in `Transaction.currentEntitlements`
+([Apple](https://developer.apple.com/documentation/storekit/transaction/currententitlements)).
+
+A consumable of another token or of no token is never finished: the SDK
+never admits it, the backend refuses one bound to no token for every
+player (`APP_STORE_ACCOUNT_TOKEN_MISSING`), and it stays in
+`Transaction.unfinished`, reported as an `account-mismatch` diagnostic on each
+read. Subscriptions are never reported or finished by this plugin.
+Permanently rejected and account-mismatched
 transactions are not finished: the client cannot prove content delivery for
 them, so persist that terminal result in the game-owned operation journal and
 do not run an automatic retry loop for it. An unknown backend result stays
@@ -266,6 +342,43 @@ until it is approved, so its `launched` record holds no ledger grant and is
 never finished; the approved transaction arrives through `transactionUpdated`
 and is verified and finished once.
 
+A consumable the App Store refunds while it is still unfinished (the app
+closed between the grant and the finish, or before the verify answered, and
+the refund came first) stays in `Transaction.unfinished`, which StoreKit
+redelivers at every launch until `finish()`, and the ordinary finish refuses
+a revoked transaction. The SDK keeps it listed as `revoked` (its launch-time
+`transactionUpdated` usually fires before the web listener attaches), and
+the reconciler finishes it with `revoked: true` once the backend has
+answered for it without a standing grant: the ledger reversed the grant
+(App Store Server Notifications `REFUND`, read through
+`getPurchaseLedgerStatus`), or the verify was refused as revoked
+(`APP_STORE_TRANSACTION_REVOKED` or `LEDGER_GRANT_REVERSED`). A refunded
+consumable of the session's own app account token that the journal holds no
+record of is finished at once, without a verify. Nothing is granted or
+verified again, and `REFUND_REVERSED` never re-grants. A revoked finish
+names the reversed grant's ledger entry, or none when nothing was granted;
+the native method requires a non-empty `ledgerEntryId`, so the SDK then
+sends `revokedLedgerEntryIdPrefix` plus the transaction id, which names no
+ledger entry and which the native code never reads. The SDK and the native
+plugin (`StoreKitTransactionPolicy.finishableRevoked`, over
+`Transaction.unfinished` only) finish only a revoked consumable bound to the
+session token; a transaction still paid, a durable, another or no token,
+and a malformed entry stay refused. So does one the list does not carry
+(`finished: false`, no native call): the list cannot tell a consumable
+already finished from one an early read does not carry yet, or from an
+entry the native read skipped as unverifiable. The reconciler does not
+count that answer as asked, so the next report asks again. Only revoked
+consumables of the catalog are listed; a refunded durable is not. OpenIAP's finish takes the transaction by id and
+does not check the revocation date. While the grant stands (a backend
+without the ledger status read, or a refund not recorded yet) the
+transaction stays unfinished, as before, and so does one the backend
+refused for another reason. Version mixes keep the earlier behaviour: a
+native build from before `revoked` ignores the flag and its ordinary gate
+refuses the revoked transaction (`finished: false`, reported as a `finish`
+failure and asked again on the next launch), an older adapter neither lists
+revoked purchases nor forwards the flag, and an older reconciler never
+sends it.
+
 ### Migrating from v1
 
 Commerce v2 PR C4 removed the v1 provider and its recovery driver.

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,11 +26,76 @@ 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;
+}
+/**
+* What `getFinishSupport` declares: `withoutAppAccountToken` is the protocol
+* version of the explicit no-token finish, absent from a build before it.
+*/
+export interface StoreKitFinishSupport {
+  readonly withoutAppAccountToken?: number;
+}
+/**
+* One `finishTransaction` call: the session app account token, or explicitly
+* none (`withoutAppAccountToken: true`, no token field at all), which matches
+* only a non-consumable bound to no token. Never both, never neither.
+*/
+export type StoreKitFinishTransactionInput = {
+  readonly transactionId: string;
+  readonly ledgerEntryId: string;
+  /** Session app account token; must match the verified transaction. */
+  readonly appAccountToken: string;
+  readonly withoutAppAccountToken?: never;
+  /**
+  * Finish a transaction StoreKit lists as revoked (refunded) instead:
+  * only an unfinished, revoked consumable bound to `appAccountToken`, and
+  * nothing else. Grants nothing; it stops StoreKit redelivering it. Never
+  * combined with `withoutAppAccountToken`. A native build from before the
+  * flag ignores it and refuses the revoked transaction (`finished: false`).
+  */
+  readonly revoked?: boolean;
+} | {
+  readonly transactionId: string;
+  readonly ledgerEntryId: string;
+  readonly appAccountToken?: never;
+  readonly revoked?: never;
+  /**
+  * Finish a verified, non-revoked non-consumable bound to no app account
+  * token (bought or redeemed outside the app). Only a build whose
+  * `getFinishSupport` declares it accepts this; an earlier one rejects
+  * the call with `STOREKIT_FINISH_REQUIRES_GRANT`.
+  */
+  readonly withoutAppAccountToken: true;
 };
 export interface CapacitorStoreKitPlugin {
   getProducts(input: {
@@ -41,7 +106,22 @@ 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>;
+  /**
+  * Declares the finish matches beyond the session token. A native build
+  * from before it answers `UNIMPLEMENTED`; optional so a plugin double
+  * without it still type-checks, and then the SDK never finishes a
+  * transaction bound to no token.
+  */
+  getFinishSupport?(): Promise<StoreKitFinishSupport>;
   /** Includes unfinished consumables and current non-consumable entitlements. */
   getTransactions(): Promise<{
     readonly transactions: readonly StoreKitTransaction[];
@@ -51,22 +131,24 @@ export interface CapacitorStoreKitPlugin {
     readonly synced: boolean;
   }>;
   /**
-  * Call only after the authenticated backend confirms the ledger grant.
-  * Finishing never grants. Native finishes only a verified, non-revoked,
-  * one-time transaction whose app account token matches `appAccountToken`.
+  * Call only after the authenticated backend confirms the ledger grant
+  * (with `revoked`: after it answered for a refunded transaction without a
+  * standing grant). Finishing never grants. Native finishes only a
+  * verified, non-revoked, one-time transaction whose app account token
+  * matches `appAccountToken`, or, with `withoutAppAccountToken: true`, a
+  * verified, non-revoked non-consumable bound to no token, or, with
+  * `revoked: true`, only a revoked consumable bound to `appAccountToken`.
   * The StoreKit SDK injects the session token and applies the same match
   * before this call, including for `commerce.v2.finishTransaction`. Games
   * must not call this plugin method directly. The token match is not a
   * signed server capability: a caller who can read `getTransactions` can
-  * still supply that token with a forged ledger entry id.
+  * still supply that token (or the no-token flag) with a forged ledger
+  * entry id.
   */
-  finishTransaction(input: {
-    readonly transactionId: string;
-    readonly ledgerEntryId: string;
-    /** Session app account token; must match the verified transaction. */
-    readonly appAccountToken: string;
-  }): Promise<{
+  finishTransaction(input: StoreKitFinishTransactionInput): Promise<{
     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/native-support.d.ts

@@ -0,0 +1,17 @@
+/**
+* A native support probe: asks the plugin once whether its build declares a
+* feature, and answers every later caller from that answer. The rule matches
+* the sheet-facts probe of `@mpgd/adapter-capacitor`
+* (`createNativePurchasePresentation().supported()`), kept here so this
+* package does not depend on that adapter's version for it:
+*
+* - `read` runs inside the promise chain, so a plugin proxy that throws on
+*   access is answered like a call that failed.
+* - Any answer is passed to `declared` and remembered (a build without the
+*   method answers `undefined`).
+* - `UNIMPLEMENTED` (a native build from before the method) is remembered as
+*   "not supported".
+* - Any other failure answers "not supported" for this caller and is asked
+*   again by the next one.
+*/
+export declare function probeNativeSupport(read: () => unknown, declared: (answer: unknown) => boolean): () => Promise<boolean>;

package/dist/native-support.js

@@ -0,0 +1,37 @@
+/**
+ * A native support probe: asks the plugin once whether its build declares a
+ * feature, and answers every later caller from that answer. The rule matches
+ * the sheet-facts probe of `@mpgd/adapter-capacitor`
+ * (`createNativePurchasePresentation().supported()`), kept here so this
+ * package does not depend on that adapter's version for it:
+ *
+ * - `read` runs inside the promise chain, so a plugin proxy that throws on
+ *   access is answered like a call that failed.
+ * - Any answer is passed to `declared` and remembered (a build without the
+ *   method answers `undefined`).
+ * - `UNIMPLEMENTED` (a native build from before the method) is remembered as
+ *   "not supported".
+ * - Any other failure answers "not supported" for this caller and is asked
+ *   again by the next one.
+ */
+export function probeNativeSupport(read, declared) {
+    let support;
+    return () => {
+        if (support !== undefined) {
+            return support;
+        }
+        const attempt = Promise.resolve()
+            .then(read)
+            .then(declared, (error) => {
+            if (!isRecord(error) || error.code !== 'UNIMPLEMENTED') {
+                support = undefined;
+            }
+            return false;
+        });
+        support = attempt;
+        return attempt;
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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' | 'getFinishSupport'>;
+/**
+* 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
@@ -79,6 +102,12 @@ export { storeKitStoreSdkCapabilities };
 export declare const storeKitStoreSdkErrorCodeMap: StoreSdkErrorCodeMap;
 /** The default table plus every StoreKit code; what the provider uses. */
 export declare const capacitorStoreKitErrorCodeMap: StoreSdkErrorCodeMap;
+/**
+* The `ledgerEntryId` the SDK sends the native plugin for a revoked finish
+* that names no ledger entry (a refund of a purchase never granted). The
+* native method requires the field on every call; it is not a ledger entry.
+*/
+export declare const revokedLedgerEntryIdPrefix = "revoked-without-grant:";
 /** Normalizes a required `app-account-token` binding to the lowercase UUID StoreKit expects. */
 export declare function readAppAccountToken(binding: StorePurchaseAccountBinding | undefined): string;
 /** Maps a verified StoreKit transaction to the SDK purchase: the JWS is the token. */

package/dist/store-sdk.js

@@ -1,7 +1,17 @@
 import { Capacitor } from '@capacitor/core';
 import { defaultStoreSdkErrorCodeMap, } from '@mpgd/adapter-capacitor';
 import { appStoreStoreId, storeKitStoreSdkCapabilities } from './commerce-profile.js';
+import { probeNativeSupport } from './native-support.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 +33,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') {
@@ -253,13 +267,27 @@ export function createCapacitorStoreKitStoreSdk(input) {
         }
         return expected;
     };
+    /**
+     * Whether the native build declares the explicit no-token finish
+     * (`getFinishSupport`). A build from before it answers `UNIMPLEMENTED`,
+     * which is remembered; any other failure is asked again on the next
+     * finish, and both answer "not supported" for this one, so the durable is
+     * left unfinished (as before) rather than sent a call the build refuses.
+     */
+    const finishWithoutTokenSupported = probeNativeSupport(() => {
+        const check = sdk.getFinishSupport;
+        return typeof check === 'function' ? check.call(sdk) : undefined;
+    }, (answer) => isRecord(answer)
+        && typeof answer.withoutAppAccountToken === 'number'
+        && answer.withoutAppAccountToken >= 1);
     // Overlapping finishes for the same transaction and ledger entry share one
     // native call; the v2 reconciler is the gate that authorizes the call.
     const inFlightFinishes = new Map();
     /**
      * Mirrors the native finish gate: the transaction must be listed, not
-     * revoked, and bound to the session app account token. A missing list is
-     * an invalid response, not a quiet "not finished".
+     * revoked, and bound to the session app account token (exceptions for a
+     * durable below). A missing list is an invalid response, not a quiet "not
+     * finished".
      *
      * On a retried finish (`retry`: the caller asked to finish this purchase
      * before, in an earlier attempt or session), a consumable the list no
@@ -284,8 +312,8 @@ export function createCapacitorStoreKitStoreSdk(input) {
      * reconciler cannot hold a grant for it from this SDK, and the answer
      * neither grants nor takes anything.
      *
-     * Two exceptions for a listed, non-revoked durable, the only kind the
-     * restore read admits from another token:
+     * Three exceptions for a listed, non-revoked durable, the only kind the
+     * restore read admits from another token or from none:
      *
      * - StoreKit already finished it (`unfinished: false`): nothing is left to
      *   finish whatever its token, so a restore shared to this player ends
@@ -299,16 +327,24 @@ export function createCapacitorStoreKitStoreSdk(input) {
      *   finishing it takes nothing from any player: the earlier guest's next
      *   read still lists it (`unfinished: false`) for its own verification. It
      *   is finished with its own token, which the native gate matches.
+     * - It is unfinished (or the build omits the flag), the catalog declares
+     *   its SKU durable, and it is bound to no token (bought or redeemed
+     *   outside the app, such as an offer code, then restored): the same
+     *   reasoning holds, since the caller holds this player's ledger grant and
+     *   StoreKit keeps the finished durable as a current entitlement. It is
+     *   finished with the explicit no-token match (`withoutAppAccountToken`),
+     *   which matches only a non-consumable bound to no token, and only when
+     *   the native build declares it (`getFinishSupport`); an earlier build
+     *   leaves it unfinished, and the caller retries as before.
+     *
+     * A consumable of another token or of no token, or a durable whose SKU the
+     * catalog does not declare durable, is never finished here.
      *
-     * A consumable of another token, or a transaction bound to no token, is
-     * never finished here.
+     * A revoked finish (`revoked`, see `revokedFinishPermitted`) has its own
+     * gate; an ordinary finish of a revoked transaction stays refused.
      */
     const finishPermitted = async (transactionId, appAccountToken, lostAcknowledgement) => {
-        const response = await sdk.getTransactions();
-        if (!isRecord(response) || !Array.isArray(response.transactions)) {
-            throw evidenceInvalid('StoreKit returned an invalid transaction list.');
-        }
-        const entries = response.transactions.filter((candidate) => isRecord(candidate) && candidate.transactionId === transactionId);
+        const entries = await listedEntries(transactionId);
         const transaction = entries.find(isValidStoreKitTransaction);
         if (transaction === undefined) {
             return { verdict: entries.length === 0 && lostAcknowledgement ? 'finished' : 'refused' };
@@ -321,17 +357,62 @@ export function createCapacitorStoreKitStoreSdk(input) {
         }
         const bound = transaction.appAccountToken?.toLowerCase();
         if (bound === appAccountToken) {
-            return { verdict: 'finish', appAccountToken };
+            return { verdict: 'finish', binding: { appAccountToken } };
+        }
+        if (transaction.type !== 'non_consumable' || kinds.get(transaction.productId) !== 'durable') {
+            return { verdict: 'refused' };
+        }
+        if (bound !== undefined) {
+            return { verdict: 'finish', binding: { appAccountToken: bound } };
         }
-        if (bound !== undefined
-            && transaction.type === 'non_consumable'
-            && kinds.get(transaction.productId) === 'durable') {
-            return { verdict: 'finish', appAccountToken: bound };
+        return await finishWithoutTokenSupported()
+            ? { verdict: 'finish', binding: { withoutAppAccountToken: true } }
+            : { verdict: 'refused' };
+    };
+    /** The native list's entries of one transaction id, in any shape. */
+    const listedEntries = async (transactionId) => {
+        const response = await sdk.getTransactions();
+        if (!isRecord(response) || !Array.isArray(response.transactions)) {
+            throw evidenceInvalid('StoreKit returned an invalid transaction list.');
         }
-        return { verdict: 'refused' };
+        return response.transactions.filter((candidate) => isRecord(candidate) && candidate.transactionId === transactionId);
+    };
+    /**
+     * The gate of a revoked finish (`revoked`): a consumable the App Store
+     * refunded while it was still unfinished, which StoreKit keeps in
+     * `Transaction.unfinished` and redelivers at every launch until `finish()`.
+     * The caller (the reconciler) asks only once the backend answered for it
+     * without a standing grant, and finishing it grants nothing: it only stops
+     * the redelivery. It is finished only when the native list carries it as
+     * revoked (`revokedAt`), as a consumable of a SKU the catalog declares
+     * consumable, bound to the session token. A transaction that is not
+     * revoked (still a paid purchase), a durable, or a consumable of another
+     * or no token stays refused, as does an entry of the id in a malformed
+     * shape. One the list does not carry is refused too (`finished: false`,
+     * no native call): the list cannot tell a consumable already finished
+     * (a refund of a finished consumable is reported as well) from one a read
+     * early in the launch does not carry yet, and answering finished would
+     * report a finish that never happened. The reconciler does not count that
+     * answer as asked, so a later report of the transaction asks again.
+     */
+    const revokedFinishPermitted = async (transactionId, appAccountToken) => {
+        const entries = await listedEntries(transactionId);
+        const transaction = entries.find(isValidStoreKitTransaction);
+        if (transaction === undefined) {
+            return 'refused';
+        }
+        return transaction.revokedAt !== undefined
+            && transaction.type === 'consumable'
+            && kinds.get(transaction.productId) === 'consumable'
+            && transaction.appAccountToken?.toLowerCase() === appAccountToken
+            ? 'finish'
+            : 'refused';
     };
     return {
         store: appStoreStoreId,
+        // `finishTransaction` reads `revoked` (see `revokedFinishPermitted`).
+        acceptsRevokedFinish: true,
+        ...(presentation === undefined ? {} : { purchasePresentation: presentation.purchasePresentation }),
         capabilities: storeKitStoreSdkCapabilities,
         async fetchProducts(request) {
             requireIos();
@@ -354,7 +435,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.');
             }
@@ -423,38 +530,70 @@ export function createCapacitorStoreKitStoreSdk(input) {
             requireIos();
             // The session token is the binding. A bridge or plugin caller cannot
             // substitute another account's token on this path: the only other
-            // token used is a durable's own, read from the native list.
+            // bindings used are a durable's own token, read from the native list,
+            // and the explicit no-token match for a durable the list shows unbound.
             const appAccountToken = await Promise.resolve(resolveAppAccountToken());
-            const { transactionId, ledgerEntryId } = request;
+            const { transactionId } = request;
+            const revoked = request.revoked === true;
+            // A revoked finish may name no ledger entry (nothing was ever granted);
+            // a given one must still be non-empty, and an ordinary finish needs it.
+            const given = request.ledgerEntryId;
             if (typeof transactionId !== 'string' || !transactionPattern.test(transactionId)
-                || typeof ledgerEntryId !== 'string' || ledgerEntryId.trim() === '') {
+                || (given === undefined
+                    ? !revoked
+                    : typeof given !== 'string' || given.trim() === '')) {
                 throw storeKitError('STOREKIT_FINISH_REQUIRES_GRANT', 'StoreKit finish requires a transaction id and the ledger entry that granted it.', false);
             }
+            // Native detail: the plugin's `finishTransaction` requires a non-empty
+            // `ledgerEntryId` on every call. A revoked finish without a ledger entry
+            // sends `revokedLedgerEntryIdPrefix` + the transaction id there; it names
+            // no ledger entry and the native code never reads it.
+            const ledgerEntryId = typeof given === 'string'
+                ? given
+                : `${revokedLedgerEntryIdPrefix}${transactionId}`;
             const active = inFlightFinishes.get(transactionId);
-            if (active !== undefined && active.ledgerEntryId === ledgerEntryId) {
+            if (active !== undefined
+                && active.ledgerEntryId === ledgerEntryId
+                && active.revoked === revoked) {
                 return active.promise;
             }
             const promise = (async () => {
-                // Same match the native plugin applies: missing, revoked, unbound, or
-                // another account never reaches `transaction.finish()`, except a
-                // durable of another token (see `finishPermitted`). On a retry, a
+                if (revoked) {
+                    if (request.isConsumable !== true) {
+                        return { finished: false };
+                    }
+                    if (await revokedFinishPermitted(transactionId, appAccountToken) !== 'finish') {
+                        return { finished: false };
+                    }
+                    // Always the session token, never the no-token match. A native
+                    // build from before the flag ignores it and applies its ordinary
+                    // gate, which refuses a revoked transaction: `finished: false`.
+                    return readFinishResult(await sdk.finishTransaction({
+                        transactionId,
+                        ledgerEntryId,
+                        appAccountToken,
+                        revoked: true,
+                    }));
+                }
+                // Same match the native plugin applies: missing, revoked, or another
+                // account never reaches `transaction.finish()`, except a durable of
+                // another token or of none (see `finishPermitted`). On a retry, a
                 // consumable that left the unfinished list is already finished (a
                 // lost acknowledgement).
                 const permitted = await finishPermitted(transactionId, appAccountToken, request.isConsumable === true && request.retry === true);
                 if (permitted.verdict !== 'finish') {
                     return { finished: permitted.verdict === 'finished' };
                 }
-                const reported = await sdk.finishTransaction({
-                    transactionId,
-                    ledgerEntryId,
-                    appAccountToken: permitted.appAccountToken,
-                });
-                if (!isRecord(reported) || typeof reported.finished !== 'boolean') {
-                    throw evidenceInvalid('StoreKit returned an invalid finish result.');
-                }
-                return { finished: reported.finished };
+                const { binding } = permitted;
+                return readFinishResult('withoutAppAccountToken' in binding
+                    ? await sdk.finishTransaction({ transactionId, ledgerEntryId, withoutAppAccountToken: true })
+                    : await sdk.finishTransaction({
+                        transactionId,
+                        ledgerEntryId,
+                        appAccountToken: binding.appAccountToken,
+                    }));
             })();
-            inFlightFinishes.set(transactionId, { ledgerEntryId, promise });
+            inFlightFinishes.set(transactionId, { ledgerEntryId, revoked, promise });
             try {
                 return await promise;
             }
@@ -494,6 +633,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 +688,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({
@@ -550,6 +696,12 @@ export const capacitorStoreKitErrorCodeMap = Object.freeze({
     ...storeKitStoreSdkErrorCodeMap,
 });
 const maxProductIdsPerLookup = 100;
+/**
+ * The `ledgerEntryId` the SDK sends the native plugin for a revoked finish
+ * that names no ledger entry (a refund of a purchase never granted). The
+ * native method requires the field on every call; it is not a ledger entry.
+ */
+export const revokedLedgerEntryIdPrefix = 'revoked-without-grant:';
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const nilUuid = '00000000-0000-0000-0000-000000000000';
 const productPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
@@ -629,6 +781,12 @@ function isValidStoreKitProduct(value) {
         && typeof value.formattedPrice === 'string'
         && typeof value.currencyCode === 'string' && value.currencyCode.length > 0;
 }
+function readFinishResult(reported) {
+    if (!isRecord(reported) || typeof reported.finished !== 'boolean') {
+        throw evidenceInvalid('StoreKit returned an invalid finish result.');
+    }
+    return { finished: reported.finished };
+}
 function storeKitError(code, message, retryable) {
     return Object.assign(new Error(message), { code, retryable });
 }

package/ios/Sources/CapacitorStoreKit/CapacitorStoreKitPlugin.swift

@@ -18,7 +18,9 @@ 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),
+        CAPPluginMethod(name: "getFinishSupport", returnType: CAPPluginReturnPromise)
     ]
 
     private let connection = OpenIapAppleConnection()
@@ -79,25 +81,66 @@ 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])
+    }
+
+    /// Declares the finish matches this native code applies beyond the
+    /// session token: `withoutAppAccountToken`, the explicit no-token match
+    /// for a non-consumable bound to no token. A build without this method
+    /// answers `UNIMPLEMENTED`, and the TypeScript SDK then leaves such a
+    /// transaction unfinished, as before.
+    @objc func getFinishSupport(_ call: CAPPluginCall) {
+        call.resolve(["withoutAppAccountToken": StoreKitTransactionPolicy.finishWithoutAppAccountTokenVersion])
+    }
+
     @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 +152,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 {
@@ -180,11 +251,15 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         // SDK supplies the session token and applies the same match before
         // calling. A signed server finish capability is still required to stop
         // a webview caller who read the token from `getTransactions`.
+        // `withoutAppAccountToken: true` (and no token argument) instead
+        // matches only a non-consumable bound to no token; a missing token
+        // without it is refused, as before.
         guard let transactionId = call.getString("transactionId"), UInt64(transactionId) != nil,
               let ledgerEntryId = call.getString("ledgerEntryId"),
               !ledgerEntryId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
-              let accountToken = StoreKitTransactionPolicy.normalizedAccountToken(
-                call.getString("appAccountToken")) else {
+              let binding = StoreKitTransactionPolicy.finishBinding(
+                appAccountToken: call.options["appAccountToken"],
+                withoutAppAccountToken: call.options["withoutAppAccountToken"]) else {
             call.reject(
                 "A transaction ID, confirmed ledger entry, and app account token are required.",
                 "STOREKIT_FINISH_REQUIRES_GRANT"
@@ -192,28 +267,52 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
         guard providerReady(call) else { return }
+        // `revoked`: finish a consumable the App Store refunded while it was
+        // unfinished, so StoreKit stops redelivering it. Grants nothing; the
+        // StoreKit SDK asks only once the game backend answered for it
+        // without a standing grant. Only a verified, revoked, unfinished
+        // consumable bound to the session token matches
+        // (`StoreKitTransactionPolicy.finishableRevoked`), read from
+        // `Transaction.unfinished` only; anything else answers
+        // `finished: false` and is left alone.
+        let revoked = call.getBool("revoked") == true
         Task { [module] in
             do {
-                // The verified transaction behind the id, through the same read
-                // as `getTransactions` (an unverified sibling never blocks it):
-                // unfinished first, then the StoreKit history
-                // (`Transaction.all`) the 0.3 plugin searched, so finishing an
-                // already-finished durable stays an idempotent `finished: true`.
-                var candidate = StoreKitTransactionPolicy.finishable(
-                    transactionId: transactionId,
-                    appAccountToken: accountToken,
-                    in: await RecoveryReadShim.unfinished())
-                if candidate == nil {
+                var candidate: MpgdStoreKitTransaction?
+                if revoked {
+                    // Only the session token, never the no-token match: a
+                    // revoked finish of a call without a token finds nothing.
+                    if case .appAccountToken(let token) = binding {
+                        candidate = StoreKitTransactionPolicy.finishableRevoked(
+                            transactionId: transactionId,
+                            appAccountToken: token,
+                            in: await RecoveryReadShim.unfinished())
+                    }
+                } else {
+                    // The verified transaction behind the id, through the same
+                    // read as `getTransactions` (an unverified sibling never
+                    // blocks it): unfinished first, then the StoreKit history
+                    // (`Transaction.all`) the 0.3 plugin searched, so finishing
+                    // an already-finished durable stays an idempotent
+                    // `finished: true`.
                     candidate = StoreKitTransactionPolicy.finishable(
                         transactionId: transactionId,
-                        appAccountToken: accountToken,
-                        in: await RecoveryReadShim.history())
+                        binding: binding,
+                        in: await RecoveryReadShim.unfinished())
+                    if candidate == nil {
+                        candidate = StoreKitTransactionPolicy.finishable(
+                            transactionId: transactionId,
+                            binding: binding,
+                            in: await RecoveryReadShim.history())
+                    }
                 }
                 guard let match = candidate else {
                     call.resolve(["finished": false])
                     return
                 }
-                // OpenIAP finishes it (and checks the Apple storeId).
+                // OpenIAP finishes it by id from `Transaction.unfinished` (and
+                // checks the Apple storeId); it does not check the revocation
+                // date.
                 try await module.finishTransaction(
                     purchase: .purchaseIos(StoreKitTransactionPolicy.finishInput(match)),
                     isConsumable: match.type == .consumable)

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/ios/Sources/MpgdStoreKitBridge/StoreKitTransactionPolicy.swift

@@ -219,6 +219,95 @@ public enum StoreKitTransactionPolicy {
         return nil
     }
 
+    /// The transaction a revoked finish (`finishTransaction` with `revoked`)
+    /// may finish: the verified, **revoked** consumable with this id whose app
+    /// account token equals the session token. The App Store refunded it while
+    /// it was unfinished, so StoreKit keeps it in `Transaction.unfinished` and
+    /// redelivers it at every launch until `finish()`; finishing it grants
+    /// nothing. A transaction that is not revoked (still paid), a durable, and
+    /// another or no token never match, so this path never finishes a
+    /// purchase the player still holds. Read from `Transaction.unfinished`
+    /// only: a finished one has nothing left to finish.
+    public static func finishableRevoked(
+        transactionId: String,
+        appAccountToken: String,
+        in entries: [ReadEntry]
+    ) -> MpgdStoreKitTransaction? {
+        let expected = appAccountToken.lowercased()
+        for entry in entries {
+            guard case .oneTime(let transaction) = entry,
+                  transaction.transactionId == transactionId,
+                  transaction.revokedAtMillis != nil,
+                  transaction.type == .consumable,
+                  transaction.appAccountToken == expected else { continue }
+            return transaction
+        }
+        return nil
+    }
+
+    /// The protocol version of the explicit no-token finish
+    /// (`finishTransaction` with `withoutAppAccountToken: true`), declared by
+    /// `getFinishSupport`. A build from before it answers `UNIMPLEMENTED`
+    /// there and refuses such a call, so the TypeScript SDK never sends one.
+    public static let finishWithoutAppAccountTokenVersion = 1
+
+    /// Which app account token one `finishTransaction` call matches.
+    public enum FinishBinding: Equatable, Sendable {
+        /// The caller's (lowercased, non-nil UUID) token; see `finishable`.
+        case appAccountToken(String)
+        /// Explicitly none: matches only a non-consumable bound to no token.
+        case withoutAppAccountToken
+    }
+
+    /// The binding a `finishTransaction` call asks for, from its raw
+    /// arguments; nil refuses the call. Without `withoutAppAccountToken` it is
+    /// the token path of earlier builds (a valid, non-nil UUID). With it, only
+    /// the literal `true` and no `appAccountToken` argument at all (not even
+    /// null) select the no-token match. A missing token is never read as "no
+    /// token", and never as a wildcard.
+    public static func finishBinding(appAccountToken: Any?, withoutAppAccountToken: Any?) -> FinishBinding? {
+        guard let flag = withoutAppAccountToken else {
+            guard let token = normalizedAccountToken(appAccountToken as? String) else { return nil }
+            return .appAccountToken(token)
+        }
+        guard isBooleanTrue(flag), appAccountToken == nil else { return nil }
+        return .withoutAppAccountToken
+    }
+
+    /// A JSON `true` as Capacitor hands it over (a CFBoolean). A number such
+    /// as `1` is an `NSNumber` that `as? Bool` would also read as true.
+    static func isBooleanTrue(_ value: Any) -> Bool {
+        guard let number = value as? NSNumber else { return false }
+        return CFGetTypeID(number) == CFBooleanGetTypeID() && number.boolValue
+    }
+
+    /// `finishable` for either binding. A token matches only a transaction
+    /// bound to that token (`finishable(transactionId:appAccountToken:in:)`).
+    /// `withoutAppAccountToken` matches only a verified, non-revoked
+    /// non-consumable bound to no token (one bought or redeemed outside the
+    /// app); never a consumable and never a transaction that carries a token.
+    /// The TypeScript SDK sends it only for a durable of its catalog after the
+    /// backend's ledger grant; StoreKit keeps a finished non-consumable in
+    /// `Transaction.currentEntitlements`, so the finish takes nothing away.
+    public static func finishable(
+        transactionId: String,
+        binding: FinishBinding,
+        in entries: [ReadEntry]
+    ) -> MpgdStoreKitTransaction? {
+        if case .appAccountToken(let token) = binding {
+            return finishable(transactionId: transactionId, appAccountToken: token, in: entries)
+        }
+        for entry in entries {
+            guard case .oneTime(let transaction) = entry,
+                  transaction.transactionId == transactionId,
+                  transaction.revokedAtMillis == nil,
+                  transaction.type == .nonConsumable,
+                  transaction.appAccountToken == nil else { continue }
+            return transaction
+        }
+        return nil
+    }
+
     /// The OpenIAP purchase handed to `OpenIapModule.finishTransaction` for a
     /// transaction the read resolved. OpenIAP finishes by transaction id
     /// (looking it up in `Transaction.unfinished`, then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.5.0",
+  "version": "0.7.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.19.0",
+    "@mpgd/bridge": "^0.18.0",
+    "@mpgd/platform": "^0.35.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.19.0",
+    "@mpgd/bridge": "0.18.1",
+    "@mpgd/platform": "0.35.0",
+    "@mpgd/game-services": "0.33.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"
   }
 }