@mpgd/capacitor-storekit 0.6.0 → 0.7.1

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`
@@ -240,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
@@ -256,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
@@ -305,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/definitions.d.ts

@@ -58,6 +58,45 @@ export interface StoreKitPurchasePresentationEvent {
 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: {
     readonly productIds: readonly string[];
@@ -76,6 +115,13 @@ export interface CapacitorStoreKitPlugin {
   * 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[];
@@ -85,21 +131,21 @@ 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>;

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/store-sdk.d.ts

@@ -5,7 +5,7 @@ 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' | 'getPresentationSupport'>;
+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
@@ -102,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,6 +1,7 @@
 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';
 /**
@@ -266,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
@@ -297,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
@@ -312,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' };
@@ -334,17 +357,61 @@ 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 } };
+        }
+        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.');
         }
-        if (bound !== undefined
-            && transaction.type === 'non_consumable'
-            && kinds.get(transaction.productId) === 'durable') {
-            return { verdict: 'finish', appAccountToken: bound };
+        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 { verdict: '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) {
@@ -463,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;
             }
@@ -597,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;
@@ -676,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

@@ -19,7 +19,8 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "getTransactions", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "sync", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "finishTransaction", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "getPresentationSupport", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "getPresentationSupport", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getFinishSupport", returnType: CAPPluginReturnPromise)
     ]
 
     private let connection = OpenIapAppleConnection()
@@ -89,6 +90,15 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         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.
@@ -241,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"
@@ -253,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/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.6.0",
+  "version": "0.7.1",
   "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.18.0",
+    "@mpgd/adapter-capacitor": "^0.19.0",
     "@mpgd/bridge": "^0.18.0",
-    "@mpgd/platform": "^0.34.0"
+    "@mpgd/platform": "^0.35.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
     "ttsc": "0.34.2",
     "typescript": "7.0.2",
-    "@mpgd/adapter-capacitor": "0.18.0",
-    "@mpgd/bridge": "0.18.0",
-    "@mpgd/platform": "0.34.0",
-    "@mpgd/game-services": "0.32.0"
+    "@mpgd/adapter-capacitor": "0.19.1",
+    "@mpgd/bridge": "0.18.1",
+    "@mpgd/game-services": "0.33.1",
+    "@mpgd/platform": "0.35.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",