@mpgd/capacitor-storekit 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imjlk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @mpgd/capacitor-storekit
 
-Private, opt-in StoreKit 2 one-time purchase collector for Capacitor 8 on iOS.
+Opt-in StoreKit 2 one-time purchase collector for Capacitor 8 on iOS.
 It does not enable native IAP in the base Capacitor shell. Install it only in a
 game-owned iOS project and register `createCapacitorStoreKitProvider(...)` in
 that game's provider list.
@@ -25,6 +25,19 @@ bundle, product, environment and account binding before the ledger grant.
 The recovery helper calls native `finishTransaction` only after a
 verified response with a ledger entry ID. If finish fails, it reports
 `finishPending: true`; repeat recovery with the original purchase identity.
+`provider.finishGrantedTransaction` accepts only a transaction and ledger
+entry pair that `recoverStoreKitPurchases` recorded from a backend answer in
+the current session. The pair is consumed before the native call, so
+overlapping finishes (for example startup recovery and a `transactionUpdated`
+recovery) share one native call, and a failed native finish restores the pair
+for a retry. Calling it, or the native `finishTransaction` plugin method, with
+any other value is rejected so an unfinished purchase keeps its recovery
+signal. This guard prevents arbitrary or accidental finish calls with
+unverified ledger IDs and binds finishing to the recovery flow; it is **not**
+a trust boundary against code that controls the `backend` object it passes to
+`recoverStoreKitPurchases`. The real control is server-side: the authenticated
+`recoverPurchase` implementation must verify Apple evidence before it grants,
+and finishing a transaction never grants anything by itself.
 An unknown backend result stays pending and never triggers a
 new purchase sheet automatically.
 

package/dist/definitions.d.ts

@@ -42,7 +42,16 @@ export interface CapacitorStoreKitPlugin {
   sync(): Promise<{
     readonly synced: boolean;
   }>;
-  /** Call only after the authenticated backend confirms the ledger grant. */
+  /**
+  * Call only after the authenticated backend confirms the ledger grant.
+  * Native validation is intentionally shallow and finishing never grants
+  * anything. The TypeScript provider's finishGrantedTransaction binds this
+  * call to the recoverStoreKitPurchases flow so games cannot finish a
+  * purchase accidentally or with an arbitrary ledger ID; games must not call
+  * this plugin method directly. That binding is not a trust boundary against
+  * code that controls the recovery backend object: the authenticated
+  * server-side recoverPurchase verification is the real control.
+  */
   finishTransaction(input: {
     readonly transactionId: string;
     readonly ledgerEntryId: string;

package/dist/provider.d.ts

@@ -47,6 +47,19 @@ export interface CapacitorStoreKitProvider {
   }>>;
   getAppAccountToken(): Promise<string>;
   getRecoverableTransactions(): Promise<StoreKitRecoverySnapshot>;
+  /**
+  * Finish a transaction the backend already granted. The provider accepts
+  * only a transaction and ledger entry pair that recoverStoreKitPurchases
+  * recorded from a backend answer in this session, and consumes the pair
+  * before the native call so overlapping finishes share one native call;
+  * any other pair is rejected so an unfinished purchase keeps its recovery
+  * signal. A failed native finish restores the pair for a retry.
+  *
+  * The guard prevents arbitrary or accidental finish calls with unverified
+  * ledger IDs. It is not a trust boundary against code that controls the
+  * backend object given to recoverStoreKitPurchases; the authenticated
+  * server-side recoverPurchase implementation is the real control.
+  */
   finishGrantedTransaction(input: {
     readonly transactionId: string;
     readonly ledgerEntryId: string;

package/dist/provider.js

@@ -3,6 +3,20 @@ import { CapacitorStoreKit } from './plugin.js';
 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 productPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const transactionPattern = /^[1-9][0-9]{0,19}$/u;
+/**
+ * Grants recorded by recoverStoreKitPurchases per provider instance:
+ * transaction ID to the ledger entry ID the recovery backend returned. The map
+ * binds finishGrantedTransaction to that recovery flow so a game cannot finish
+ * an unfinished purchase by accident, or with an arbitrary ledger string, and
+ * so each recorded pair reaches the native finish call at most once.
+ *
+ * This is not a trust boundary against a caller who controls the backend
+ * object passed to recoverStoreKitPurchases: such a caller can record any
+ * pair. The real control stays server-side, in the authenticated
+ * recoverPurchase implementation that verifies Apple evidence before it
+ * grants, and in the native plugin never granting anything on finish.
+ */
+const verifiedGrants = new WeakMap();
 /** Submit unfinished purchases to the backend before asking StoreKit to finish. */
 export async function recoverStoreKitPurchases(input) {
     if (input.playerId.trim() === '') {
@@ -43,6 +57,7 @@ export async function recoverStoreKitPurchases(input) {
             if (verification.ledgerEntryId === undefined || verification.ledgerEntryId.trim() === '') {
                 return { productId: item.productId, transactionId, status: 'pending', verification };
             }
+            verifiedGrants.get(input.provider)?.set(transactionId, verification.ledgerEntryId);
             try {
                 const finished = await input.provider.finishGrantedTransaction({
                     transactionId,
@@ -209,7 +224,23 @@ export function createCapacitorStoreKitProvider(options) {
             return failure(input.id, 'STOREKIT_UNAVAILABLE', true);
         }
     }
-    return {
+    const grants = new Map();
+    const inFlight = new Map();
+    async function finishReserved(transactionId, ledgerEntryId) {
+        let finished = false;
+        try {
+            finished = (await sdk.finishTransaction({ transactionId, ledgerEntryId })).finished;
+        }
+        finally {
+            // Restore the pair after a rejected or failed native finish so recovery
+            // can retry it, unless a newer recovery recorded the transaction again.
+            if (!finished && !grants.has(transactionId)) {
+                grants.set(transactionId, ledgerEntryId);
+            }
+        }
+        return finished;
+    }
+    const provider = {
         id: 'apple-storekit',
         features: ['nativeIap'],
         methods: [
@@ -247,10 +278,31 @@ export function createCapacitorStoreKitProvider(options) {
                 || input.ledgerEntryId.trim() === '') {
                 throw new TypeError('StoreKit finish requires a verified grant and transaction ID.');
             }
-            const response = await sdk.finishTransaction(input);
-            return response.finished;
+            const { transactionId, ledgerEntryId } = input;
+            const active = inFlight.get(transactionId);
+            if (active !== undefined && active.ledgerEntryId === ledgerEntryId) {
+                return active.promise;
+            }
+            if (grants.get(transactionId) !== ledgerEntryId) {
+                throw new TypeError('StoreKit finish requires the ledger entry the backend returned for this transaction via recoverStoreKitPurchases.');
+            }
+            // Consume the pair synchronously, before the first await, so an
+            // overlapping finish for the same transaction cannot reach native twice.
+            grants.delete(transactionId);
+            const promise = finishReserved(transactionId, ledgerEntryId);
+            inFlight.set(transactionId, { ledgerEntryId, promise });
+            try {
+                return await promise;
+            }
+            finally {
+                if (inFlight.get(transactionId)?.promise === promise) {
+                    inFlight.delete(transactionId);
+                }
+            }
         },
     };
+    verifiedGrants.set(provider, grants);
+    return provider;
 }
 function convertOutcome(outcome, mapping, expectedAccountToken) {
     if (outcome.status !== 'purchased') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Opt-in StoreKit 2 one-time purchase collector for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,16 @@
     "url": "git+https://github.com/imjlk/mpgd-kit.git",
     "directory": "native-plugins/capacitor-storekit"
   },
+  "bugs": {
+    "url": "https://github.com/imjlk/mpgd-kit/issues"
+  },
+  "homepage": "https://github.com/imjlk/mpgd-kit#readme",
+  "keywords": [
+    "mpgd",
+    "capacitor",
+    "storekit",
+    "game-development"
+  ],
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -21,29 +31,33 @@
       "src": "ios"
     }
   },
-  "files": ["dist", "ios", "Package.swift"],
-  "scripts": {
-    "check": "ttsc --noEmit",
-    "lint": "ttsc --noEmit",
-    "test": "cd ../.. && node tools/run-ttsx.mjs native-plugins/capacitor-storekit/src/provider.test.ts"
-  },
+  "files": [
+    "dist",
+    "ios",
+    "Package.swift"
+  ],
   "peerDependencies": {
     "@capacitor/core": "^8.5.1",
     "@mpgd/bridge": "^0.10.0",
-    "@mpgd/platform": "^0.13.0 || ^0.14.0"
+    "@mpgd/platform": "^0.14.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
-    "@mpgd/adapter-capacitor": "workspace:*",
-    "@mpgd/bridge": "workspace:*",
-    "@mpgd/game-services": "workspace:*",
-    "@mpgd/platform": "workspace:*",
     "ttsc": "0.30.4",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "@mpgd/adapter-capacitor": "0.6.1",
+    "@mpgd/bridge": "0.10.0",
+    "@mpgd/game-services": "0.17.1",
+    "@mpgd/platform": "0.14.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "check": "ttsc --noEmit",
+    "lint": "ttsc --noEmit",
+    "test": "cd ../.. && node tools/run-ttsx.mjs native-plugins/capacitor-storekit/src/provider.test.ts"
   }
-}
+}