@mpgd/capacitor-storekit 0.3.9 → 0.4.0

package/Package.swift

@@ -1,19 +1,49 @@
 // swift-tools-version: 5.9
 import PackageDescription
 
+// `MPGD_STOREKIT_BRIDGE_TESTS=1 swift test` builds only the store-neutral
+// bridge and its XCTests on a Mac. Capacitor ships iOS-only binaries, so the
+// plugin target is left out of that host build. Consumers never set it.
+let bridgeTestsOnly = Context.environment["MPGD_STOREKIT_BRIDGE_TESTS"] == "1"
+
+let openIap = Target.Dependency.product(name: "OpenIAP", package: "openiap")
+
+let bridge = Target.target(
+    name: "MpgdStoreKitBridge",
+    dependencies: [openIap],
+    path: "ios/Sources/MpgdStoreKitBridge"
+)
+
 let package = Package(
     name: "MpgdCapacitorStoreKit",
-    platforms: [.iOS(.v15)],
-    products: [
-        .library(name: "MpgdCapacitorStoreKit", targets: ["MpgdCapacitorStoreKit"])
+    platforms: bridgeTestsOnly ? [.iOS(.v15), .macOS(.v14)] : [.iOS(.v15)],
+    products: bridgeTestsOnly ? [] : [
+        .library(name: "MpgdCapacitorStoreKit", targets: ["MpgdCapacitorStoreKit"]),
+        // `cap sync ios` derives the product it links from the npm package
+        // name (`@mpgd/capacitor-storekit` -> `MpgdCapacitorStorekit`).
+        .library(name: "MpgdCapacitorStorekit", targets: ["MpgdCapacitorStoreKit"])
     ],
-    dependencies: [
+    dependencies: (bridgeTestsOnly ? [] : [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", exact: "8.5.2")
+    ]) + [
+        // OpenIAP Apple core (StoreKit 2), pinned exactly. See
+        // docs/specs/commerce/openiap-migration.md before changing it.
+        .package(url: "https://github.com/hyodotdev/openiap.git", exact: "4.0.5")
     ],
-    targets: [
+    targets: bridgeTestsOnly ? [
+        bridge,
+        .testTarget(
+            name: "MpgdStoreKitBridgeTests",
+            dependencies: ["MpgdStoreKitBridge", openIap],
+            path: "ios/Tests/MpgdStoreKitBridgeTests"
+        )
+    ] : [
+        bridge,
         .target(
             name: "MpgdCapacitorStoreKit",
             dependencies: [
+                "MpgdStoreKitBridge",
+                openIap,
                 .product(name: "Capacitor", package: "capacitor-swift-pm"),
                 .product(name: "Cordova", package: "capacitor-swift-pm")
             ],

package/README.md

@@ -1,6 +1,7 @@
 # @mpgd/capacitor-storekit
 
-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, built
+on the [OpenIAP](https://github.com/hyodotdev/openiap) Apple core (4.0.5).
 It does not enable native IAP in the base Capacitor shell. Install it only in a
 game-owned iOS project and register `createCapacitorStoreKitServiceProvider(...)`
 in that game's provider list.
@@ -93,7 +94,12 @@ type disagrees with the catalog kind is never listed or emitted, so the
 reconciler never journals a purchase it cannot resolve or that belongs to
 another player, and never blocks a valid sibling on one. Each exclusion is
 reported through `onDiagnostic` (`unmapped-sku`, `account-mismatch`,
-`kind-mismatch`); diagnostics are never a grant signal. The native
+`kind-mismatch`); diagnostics are never a grant signal. One exception: the
+player's Restore Purchases read (`getAvailablePurchases({ restore: true })`,
+sent only by the reconciler's `restorePurchases`) also lists a durable bound
+to another or no token, the state of every earlier purchase after a reinstall
+or on a new iPhone or iPad, so the backend's restore sharing can decide;
+consumables of another token stay excluded. The native
 `transactionUpdated` listener is attached while either a `purchaseUpdated`
 or a `purchaseError` subscriber exists.
 
@@ -146,8 +152,11 @@ C3): the service provider is registered for every catalog product whose
 `platformProductIds.ios` names an App Store product id (subscriptions are
 skipped), and `getAppAccountToken` is the reference binding in
 `src/platform/commerceAccountBinding.ts`, a UUID (version 5 layout) over the
-SHA-256 of `mpgd-commerce-account:<playerId>` for the authenticated player;
-a guest session throws, so no sheet opens without a binding. The backend's
+SHA-256 of `mpgd-commerce-account:<playerId>` for the server session's
+player (the generated game's `guestIdentity.ts` signs in a server-issued
+guest when `VITE_MPGD_IDENTITY_URL` is set) or an authenticated platform
+player; the native shell's local player throws an error naming the missing
+server session, so no sheet opens without a binding. The backend's
 `resolveAppAccountToken` must derive the same UUID, or both are replaced
 together.
 
@@ -172,10 +181,13 @@ of truth. The reconciler sends only transactions whose
 each one on the backend under its original idempotency key or returns the
 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 finish a transaction whose app account token is missing or does
-not match that session. A caller who can read the token from the plugin can
+refuse to call `transaction.finish()` on a transaction whose app account
+token is missing or does not match that session. 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. Permanently rejected and account-mismatched
+signed server finish capability. A listed, non-revoked durable StoreKit
+already finished (`unfinished: false`) answers `{ finished: true }` without a
+native call whatever its token, so a purchase shared to this guest from an
+earlier guest's restore ends there. 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
@@ -198,8 +210,31 @@ Commerce v2 PR C4 removed the v1 provider and its recovery driver.
 | `gateway.commerceV2`, the v1 `commerce.*` bridge methods | `gateway.commerce` and the `commerce.v2.*` methods |
 | `features: ['nativeIap']` on the registry entry | none: the entry declares no `features` and its readiness is `getCapabilities().commerce` |
 
-The Kit tests use mocked StoreKit responses and a syntax-only local Swift
-parse. The macOS CI job compiles the optional Swift package against an iOS
-Simulator SDK. Neither check proves a signed App Store purchase, sandbox
-checkout, TestFlight installation, or device grant. Validate those with a
+## Native engine
+
+The Swift package keeps its 0.3 Capacitor contract (methods,
+`transactionUpdated`, payload fields, `STOREKIT_*` codes, the finish gate)
+over OpenIAP's `OpenIapModule`; the
+[migration record](../../docs/specs/commerce/openiap-migration.md) lists the
+contract, the call mapping, and every behavior difference. Two points to know
+when integrating:
+
+- `getTransactions` and the `finishTransaction` lookup read StoreKit's
+  verified lists directly (a read-only shim), because OpenIAP's queries fail
+  as a whole on one unverifiable transaction; an unverified entry is skipped
+  on its own, as in 0.3. The lists carry every app account token; the
+  TypeScript SDK admits the session account.
+- OpenIAP does not deliver revoked transactions, so a small shim forwards
+  verified revocations from `Transaction.updates`; it never finishes anything.
+
+The package declares the products `MpgdCapacitorStoreKit` and
+`MpgdCapacitorStorekit` (the spelling `cap sync ios` links). SwiftPM clones
+the OpenIAP monorepo on first resolution.
+
+The Kit tests use mocked StoreKit responses, Swift XCTests of the native
+policy (`MPGD_STOREKIT_BRIDGE_TESTS=1 swift test` on a Mac), and simulator
+builds of the workspace and the packed package
+(`pnpm smoke:native-packed-store-plugins ios`). None of these checks proves a
+signed App Store purchase, sandbox checkout, TestFlight installation, or
+device grant. Validate those with a
 game-owned account, keys, and device before a production rollout.

package/dist/store-sdk.d.ts

@@ -39,7 +39,8 @@ export interface CreateCapacitorStoreKitStoreSdkInput {
   readonly products: readonly CapacitorStoreKitStoreSdkProduct[];
   /**
   * The active player's app account token (a UUID). Transactions bound to any
-  * other token are never listed or emitted; the backend binds the same value.
+  * other token are never emitted and never listed, except a durable on the
+  * player's Restore Purchases read; the backend binds the same value.
   */
   readonly getAppAccountToken: () => string | Promise<string>;
   readonly sdk?: CapacitorStoreKitStoreSdkPlugin;
@@ -60,7 +61,11 @@ export interface CreateCapacitorStoreKitStoreSdkInput {
 * StoreKit type disagrees with the catalog kind is reported through
 * `onDiagnostic` and never reaches `getAvailablePurchases` or an event, so
 * the reconciler never journals a purchase it cannot resolve or that belongs
-* to another player.
+* to another player. One exception: the player's Restore Purchases read
+* (`getAvailablePurchases({ restore: true })`) also lists durables bound to
+* another or no token, the state of every earlier purchase after a reinstall
+* 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 { storeKitStoreSdkCapabilities };

package/dist/store-sdk.js

@@ -15,7 +15,11 @@ import { CapacitorStoreKit } from './plugin.js';
  * StoreKit type disagrees with the catalog kind is reported through
  * `onDiagnostic` and never reaches `getAvailablePurchases` or an event, so
  * the reconciler never journals a purchase it cannot resolve or that belongs
- * to another player.
+ * to another player. One exception: the player's Restore Purchases read
+ * (`getAvailablePurchases({ restore: true })`) also lists durables bound to
+ * another or no token, the state of every earlier purchase after a reinstall
+ * or on a new device; the reconciler sends them with `intent: 'restore'` and
+ * the backend's restore sharing decides (RFC "Restore sharing").
  */
 export function createCapacitorStoreKitStoreSdk(input) {
     const sdk = input.sdk ?? CapacitorStoreKit;
@@ -69,8 +73,13 @@ export function createCapacitorStoreKitStoreSdk(input) {
     /**
      * Keeps a verified transaction only when it is sellable to the active
      * player: configured SKU, declared kind, and the active account token.
+     * `restore` (the player's Restore Purchases read) also keeps a durable
+     * bound to another or no token: after a reinstall or on a new device every
+     * earlier purchase carries the earlier guest's token, and the backend's
+     * restore sharing decides whether this player may hold it. A consumable
+     * bound to another token is never kept.
      */
-    const admit = (transaction, appAccountToken) => {
+    const admit = (transaction, appAccountToken, restore = false) => {
         const expected = kinds.get(transaction.productId);
         if (expected === undefined) {
             onDiagnostic({
@@ -80,7 +89,10 @@ export function createCapacitorStoreKitStoreSdk(input) {
             });
             return false;
         }
-        if (transaction.appAccountToken?.toLowerCase() !== appAccountToken) {
+        const restorable = restore
+            && expected === 'durable'
+            && kindOf(transaction.type) === 'durable';
+        if (transaction.appAccountToken?.toLowerCase() !== appAccountToken && !restorable) {
             onDiagnostic({
                 type: 'account-mismatch',
                 sku: transaction.productId,
@@ -247,7 +259,11 @@ export function createCapacitorStoreKitStoreSdk(input) {
     /**
      * 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".
+     * an invalid response, not a quiet "not finished". A listed, non-revoked
+     * durable StoreKit already finished (`unfinished: false`) has nothing left
+     * to finish whatever its token: a restore shared to this player from an
+     * earlier guest's purchase ends there instead of retrying a finish the
+     * native token match refuses.
      */
     const finishPermitted = async (transactionId, appAccountToken) => {
         const response = await sdk.getTransactions();
@@ -255,9 +271,13 @@ export function createCapacitorStoreKitStoreSdk(input) {
             throw evidenceInvalid('StoreKit returned an invalid transaction list.');
         }
         const transaction = response.transactions.find((candidate) => isValidStoreKitTransaction(candidate) && candidate.transactionId === transactionId);
-        return transaction !== undefined
-            && transaction.revokedAt === undefined
-            && transaction.appAccountToken?.toLowerCase() === appAccountToken;
+        if (transaction === undefined || transaction.revokedAt !== undefined) {
+            return 'refused';
+        }
+        if (transaction.type === 'non_consumable' && transaction.unfinished === false) {
+            return 'finished';
+        }
+        return transaction.appAccountToken?.toLowerCase() === appAccountToken ? 'finish' : 'refused';
     };
     return {
         store: appStoreStoreId,
@@ -310,10 +330,11 @@ export function createCapacitorStoreKitStoreSdk(input) {
                     throw evidenceInvalid('StoreKit returned an invalid purchase result.');
             }
         },
-        async getAvailablePurchases() {
+        async getAvailablePurchases(request) {
             // Pending (Ask to Buy) transactions never appear in `Transaction.unfinished`
             // before approval, so `includePending` has nothing to filter here.
             requireIos();
+            const restore = request?.restore === true;
             const appAccountToken = await resolveAppAccountToken();
             const response = await sdk.getTransactions();
             if (!isRecord(response) || !Array.isArray(response.transactions)) {
@@ -341,7 +362,7 @@ export function createCapacitorStoreKitStoreSdk(input) {
                     continue;
                 }
                 seen.add(transaction.transactionId);
-                if (admit(transaction, appAccountToken)) {
+                if (admit(transaction, appAccountToken, restore)) {
                     purchases.push(toSdkPurchase(transaction));
                 }
             }
@@ -364,8 +385,9 @@ export function createCapacitorStoreKitStoreSdk(input) {
             const promise = (async () => {
                 // Same match the native plugin applies: missing, revoked, unbound, or
                 // another account never reaches `transaction.finish()`.
-                if (!(await finishPermitted(transactionId, appAccountToken))) {
-                    return { finished: false };
+                const permitted = await finishPermitted(transactionId, appAccountToken);
+                if (permitted !== 'finish') {
+                    return { finished: permitted === 'finished' };
                 }
                 const reported = await sdk.finishTransaction({
                     transactionId,

package/ios/Sources/CapacitorStoreKit/CapacitorStoreKitPlugin.swift

@@ -1,7 +1,14 @@
 import Capacitor
 import Foundation
-import StoreKit
+import MpgdStoreKitBridge
+import OpenIAP
 
+/// The `CapacitorStoreKit` plugin: the 0.3 JavaScript contract over the
+/// OpenIAP Apple core. OpenIAP talks to StoreKit 2; this class only parses
+/// Capacitor calls, applies `StoreKitTransactionPolicy`, and answers in the
+/// payload shapes the 0.3 plugin defined. Nothing here grants, and nothing
+/// here finishes a transaction except `finishTransaction`, which the game
+/// calls only after its backend confirmed the ledger grant.
 @objc(CapacitorStoreKitPlugin)
 public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
     public let identifier = "CapacitorStoreKitPlugin"
@@ -14,45 +21,57 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "finishTransaction", returnType: CAPPluginReturnPromise)
     ]
 
-    private var updatesTask: Task<Void, Never>?
+    private let connection = OpenIapAppleConnection()
+    private let revocations = RevocationUpdatesShim()
+
+    private var module: OpenIapModule { connection.module }
 
     @objc override public func load() {
         super.load()
-        updatesTask = Task { @MainActor [weak self] in
-            for await result in Transaction.updates {
-                guard !Task.isCancelled else { return }
-                if let payload = Self.verifiedPayload(result) {
-                    self?.notifyListeners("transactionUpdated", data: payload)
+        // OpenIAP delivers verified, non-revoked updates (and the result of a
+        // purchase call, which StoreSdk and the reconciler deduplicate); the
+        // shim delivers verified revocations OpenIAP skips. Neither is
+        // retained for a listener that attaches later: `getTransactions` is
+        // the authoritative recovery query.
+        connection.start { [weak self] purchase in
+            guard let transaction = StoreKitTransactionPolicy.transaction(from: purchase) else { return }
+            self?.notifyListeners("transactionUpdated", data: StoreKitTransactionPolicy.payload(transaction))
+        }
+        if connection.providerError == nil {
+            revocations.start { [weak self] transaction in
+                // Delivered on the main actor, as OpenIAP's listener and the
+                // 0.3 update loop were, never from the shim's detached task.
+                Task { @MainActor in
+                    self?.notifyListeners("transactionUpdated", data: StoreKitTransactionPolicy.payload(transaction))
                 }
             }
         }
     }
 
     deinit {
-        updatesTask?.cancel()
+        revocations.stop()
+        connection.stop()
+    }
+
+    /// Rejects the call when OpenIAP did not select the Apple provider.
+    private func providerReady(_ call: CAPPluginCall) -> Bool {
+        guard let message = connection.providerError else { return true }
+        call.reject(message, "STOREKIT_CONFIGURATION_ERROR")
+        return false
     }
 
     @objc func getProducts(_ call: CAPPluginCall) {
         guard let identifiers = call.options["productIds"] as? [String],
               !identifiers.isEmpty, identifiers.count <= 100,
-              identifiers.allSatisfy({ Self.validProductId($0) }) else {
+              identifiers.allSatisfy({ StoreKitTransactionPolicy.isValidProductId($0) }) else {
             call.reject("Provide 1-100 valid product IDs.", "STOREKIT_INVALID_PRODUCTS")
             return
         }
-        Task { @MainActor in
+        guard providerReady(call) else { return }
+        Task { @MainActor [module] in
             do {
-                let products = try await Product.products(for: identifiers)
-                let values: [[String: Any]] = products.compactMap { product in
-                    guard let type = Self.oneTimeType(product.type) else { return nil }
-                    return [
-                        "productId": product.id,
-                        "type": type,
-                        "title": product.displayName,
-                        "description": product.description,
-                        "formattedPrice": product.displayPrice,
-                        "currencyCode": product.priceFormatStyle.currencyCode
-                    ]
-                }
+                let result = try await module.fetchProducts(ProductRequest(skus: identifiers, type: .inApp))
+                let values = Self.iosProducts(result).compactMap(StoreKitTransactionPolicy.productPayload)
                 call.resolve(["products": values])
             } catch {
                 call.reject("StoreKit product lookup failed.", "STOREKIT_UNAVAILABLE", error)
@@ -61,46 +80,60 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func purchase(_ call: CAPPluginCall) {
-        guard let productId = call.getString("productId"), Self.validProductId(productId),
-              let rawAccountToken = call.getString("appAccountToken"),
-              let accountToken = UUID(uuidString: rawAccountToken) else {
+        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")
             return
         }
-        Task { @MainActor in
-            let product: Product
+        guard providerReady(call) else { return }
+        Task { @MainActor [module] in
             do {
-                guard let found = try await Product.products(for: [productId]).first,
-                      found.id == productId,
-                      Self.oneTimeType(found.type) != nil else {
+                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")
                     return
                 }
-                product = found
             } catch {
                 call.reject("StoreKit product lookup failed.", "STOREKIT_PRODUCT_LOOKUP_FAILED", error)
                 return
             }
-            do {
-                let result = try await product.purchase(options: [.appAccountToken(accountToken)])
-                switch result {
-                case .success(let verification):
-                    guard let payload = Self.verifiedPayload(verification),
-                          payload["productId"] as? String == productId,
-                          (payload["appAccountToken"] as? String)?.lowercased()
-                            == accountToken.uuidString.lowercased() else {
-                        call.reject("StoreKit transaction failed verification or account binding.",
-                                    "STOREKIT_TRANSACTION_UNVERIFIED")
-                        return
-                    }
+            let request = RequestPurchaseProps(
+                request: .purchase(RequestPurchasePropsByPlatforms(apple: RequestPurchaseIosProps(
                     // Never finish here: the game backend must commit its ledger grant first.
-                    call.resolve(["status": "purchased", "transaction": payload])
+                    andDangerouslyFinishTransactionAutomatically: false,
+                    appAccountToken: accountToken,
+                    sku: productId
+                ))),
+                type: .inApp
+            )
+            do {
+                let outcome = try await module.requestPurchase(request)
+                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")
+                    return
+                }
+                call.resolve([
+                    "status": "purchased",
+                    "transaction": StoreKitTransactionPolicy.payload(transaction)
+                ])
+            } catch let error as PurchaseError {
+                switch StoreKitTransactionPolicy.purchaseFailure(error.code) {
+                case .cancelled:
+                    call.resolve(["status": "cancelled"])
                 case .pending:
+                    // Ask to Buy: the approved transaction arrives through
+                    // `transactionUpdated` or `getTransactions` later.
                     call.resolve(["status": "pending"])
-                case .userCancelled:
-                    call.resolve(["status": "cancelled"])
-                @unknown default:
-                    call.reject("StoreKit returned an unknown purchase result.", "STOREKIT_UNKNOWN_RESULT")
+                case .rejected(let code, let message):
+                    call.reject(message, code, error)
                 }
             } catch {
                 // The purchase sheet may have completed before an error reached us.
@@ -111,36 +144,28 @@ public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func getTransactions(_ call: CAPPluginCall) {
+        guard providerReady(call) else { return }
         Task {
-            var byId: [String: [String: Any]] = [:]
-            for await result in Transaction.unfinished {
-                if var payload = Self.verifiedPayload(result),
-                   let id = payload["transactionId"] as? String {
-                    payload["unfinished"] = true
-                    byId[id] = payload
-                }
-            }
-            // Current non-consumable entitlements are listed too.
-            // `unfinished: false` means StoreKit already finished them; the SDK
-            // still lists those durables so a finish that raced the ledger
-            // grant can be verified. The server ledger dedupes.
-            for await result in Transaction.currentEntitlements {
-                if var payload = Self.verifiedPayload(result),
-                   payload["type"] as? String == "non_consumable",
-                   let id = payload["transactionId"] as? String,
-                   byId[id] == nil {
-                    payload["unfinished"] = false
-                    byId[id] = payload
-                }
-            }
-            call.resolve(["transactions": Array(byId.values)])
+            // Verified `Transaction.unfinished`, then current entitlements, read
+            // by `RecoveryReadShim`: an unverified entry is skipped on its own
+            // (0.3 behavior) instead of failing the whole OpenIAP query. Never
+            // `Transaction.all`: finished consumables must not return to the
+            // recovery list. No account filter: the TypeScript SDK admits.
+            let unfinished = await RecoveryReadShim.unfinished()
+            let entitlements = await RecoveryReadShim.currentEntitlements()
+            call.resolve(["transactions": StoreKitTransactionPolicy.listedTransactions(
+                unfinished: unfinished,
+                entitlements: entitlements
+            )])
         }
     }
 
     @objc func sync(_ call: CAPPluginCall) {
-        Task { @MainActor in
+        guard providerReady(call) else { return }
+        // User-initiated restore only (`AppStore.sync` may show sign-in UI).
+        Task { @MainActor [module] in
             do {
-                try await AppStore.sync()
+                _ = try await module.syncIOS()
                 call.resolve(["synced": true])
             } catch {
                 call.reject("StoreKit account synchronization failed.", "STOREKIT_SYNC_FAILED", error)
@@ -155,67 +180,56 @@ 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`.
-        guard let rawId = call.getString("transactionId"), let id = UInt64(rawId),
+        guard let transactionId = call.getString("transactionId"), UInt64(transactionId) != nil,
               let ledgerEntryId = call.getString("ledgerEntryId"),
               !ledgerEntryId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
-              let rawAccountToken = call.getString("appAccountToken"),
-              let accountToken = UUID(uuidString: rawAccountToken),
-              accountToken.uuidString.lowercased()
-                != "00000000-0000-0000-0000-000000000000" else {
+              let accountToken = StoreKitTransactionPolicy.normalizedAccountToken(
+                call.getString("appAccountToken")) else {
             call.reject(
                 "A transaction ID, confirmed ledger entry, and app account token are required.",
                 "STOREKIT_FINISH_REQUIRES_GRANT"
             )
             return
         }
-        let expectedToken = accountToken.uuidString.lowercased()
-        Task {
-            for await result in Transaction.all {
-                guard case .verified(let transaction) = result,
-                      transaction.id == id,
-                      transaction.revocationDate == nil,
-                      Self.oneTimeType(transaction.productType) != nil,
-                      transaction.appAccountToken?.uuidString.lowercased() == expectedToken
-                else { continue }
-                await transaction.finish()
+        guard providerReady(call) else { return }
+        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 {
+                    candidate = StoreKitTransactionPolicy.finishable(
+                        transactionId: transactionId,
+                        appAccountToken: accountToken,
+                        in: await RecoveryReadShim.history())
+                }
+                guard let match = candidate else {
+                    call.resolve(["finished": false])
+                    return
+                }
+                // OpenIAP finishes it (and checks the Apple storeId).
+                try await module.finishTransaction(
+                    purchase: .purchaseIos(StoreKitTransactionPolicy.finishInput(match)),
+                    isConsumable: match.type == .consumable)
                 call.resolve(["finished": true])
-                return
+            } catch {
+                call.reject("StoreKit could not finish the transaction.",
+                            StoreKitTransactionPolicy.queryFailureCode(error), error)
             }
-            call.resolve(["finished": false])
         }
     }
 
-    private static func verifiedPayload(
-        _ result: VerificationResult<Transaction>
-    ) -> [String: Any]? {
-        guard case .verified(let transaction) = result,
-              let type = oneTimeType(transaction.productType) else { return nil }
-        var payload: [String: Any] = [
-            "transactionId": String(transaction.id),
-            "originalTransactionId": String(transaction.originalID),
-            "productId": transaction.productID,
-            "type": type,
-            "purchasedAt": ISO8601DateFormatter().string(from: transaction.purchaseDate),
-            "signedTransaction": result.jwsRepresentation
-        ]
-        if let accountToken = transaction.appAccountToken {
-            payload["appAccountToken"] = accountToken.uuidString.lowercased()
-        }
-        if let revocationDate = transaction.revocationDate {
-            payload["revokedAt"] = ISO8601DateFormatter().string(from: revocationDate)
+    private static func iosProducts(_ result: FetchProductsResult) -> [ProductIOS] {
+        guard case .products(let products?) = result else { return [] }
+        return products.compactMap { product in
+            if case .productIos(let ios) = product { return ios }
+            return nil
         }
-        return payload
-    }
-
-    private static func oneTimeType(_ type: Product.ProductType) -> String? {
-        switch type {
-        case .consumable: return "consumable"
-        case .nonConsumable: return "non_consumable"
-        default: return nil
-        }
-    }
-
-    private static func validProductId(_ value: String) -> Bool {
-        value.range(of: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", options: .regularExpression) != nil
     }
 }

package/ios/Sources/MpgdStoreKitBridge/OpenIapAppleConnection.swift

@@ -0,0 +1,68 @@
+import Foundation
+import OpenIAP
+
+/// The OpenIAP Apple connection one Capacitor plugin instance owns.
+///
+/// This is the store-neutral half of the bridge: it selects the Apple
+/// provider explicitly, checks that the selected provider really is `apple`,
+/// keeps one OpenIAP purchase listener for the plugin's lifetime, and closes
+/// the connection when the plugin goes away. mpgd policy (which transactions
+/// are reported and finished) lives in `StoreKitTransactionPolicy`.
+public final class OpenIapAppleConnection {
+    public let module: OpenIapModule
+    private var purchaseSubscription: Subscription?
+    private var started = false
+
+    /// The Apple provider is selected explicitly rather than through the
+    /// `dev.hyo.openiap.PROVIDER` Info.plist key, so a host app cannot route
+    /// mpgd's App Store evidence through another store's provider.
+    public init(module: OpenIapModule = OpenIapModule(factory: OpenIapAppleProviderFactory())) {
+        self.module = module
+    }
+
+    /// The provider error, or nil when OpenIAP selected the Apple provider.
+    /// Every plugin method rejects while this is non-nil.
+    public var providerError: String? {
+        guard let storeId = module.storeId else {
+            return "The OpenIAP Apple provider could not be selected."
+        }
+        guard storeId == StoreKitTransactionPolicy.appleStoreId else {
+            return "OpenIAP selected the \(storeId) provider; this plugin requires apple."
+        }
+        return nil
+    }
+
+    /// Opens the connection and attaches the single purchase listener. Safe to
+    /// call more than once; later calls are no-ops. `onPurchase` receives every
+    /// verified purchase OpenIAP reports, replays included
+    /// (`dedupeTransactionIOS: false`), so the plugin keeps forwarding each
+    /// StoreKit update the way the 0.3 `Transaction.updates` loop did.
+    public func start(onPurchase: @escaping @Sendable (PurchaseIOS) -> Void) {
+        guard !started, providerError == nil else { return }
+        started = true
+        purchaseSubscription = module.purchaseUpdatedListener({ purchase in
+            if case .purchaseIos(let ios) = purchase {
+                onPurchase(ios)
+            }
+        }, options: PurchaseUpdatedListenerOptions(dedupeTransactionIOS: false))
+        Task { [module] in
+            // Every OpenIAP call also ensures the connection; this only starts
+            // the transaction listener at launch, as the 0.3 plugin did.
+            _ = try? await module.initConnection()
+        }
+    }
+
+    /// Removes the listener and ends the connection. The plugin calls this
+    /// from `deinit`; nothing is finished or cancelled in StoreKit.
+    public func stop() {
+        if let subscription = purchaseSubscription {
+            module.removeListener(subscription)
+            purchaseSubscription = nil
+        }
+        guard started else { return }
+        started = false
+        Task { [module] in
+            _ = try? await module.endConnection()
+        }
+    }
+}

package/ios/Sources/MpgdStoreKitBridge/RecoveryReadShim.swift

@@ -0,0 +1,85 @@
+import Foundation
+import StoreKit
+
+/// Compatibility shim: the verified, read-only transaction lists behind
+/// `getTransactions` and the `finishTransaction` lookup.
+///
+/// Why: OpenIAP Apple 4.0.5's `getPendingTransactionsIOS` and
+/// `getAvailablePurchases` throw on the first transaction StoreKit cannot
+/// verify (`OpenIapStoreKitModule.checkVerified`), so one unverifiable
+/// transaction on a device would hide every verified one from recovery and
+/// block finishing them. The 0.3 plugin skipped an unverified transaction on
+/// its own. This shim reads `Transaction.unfinished`,
+/// `Transaction.currentEntitlements`, and `Transaction.all` the same way and
+/// classifies each entry (`StoreKitTransactionPolicy.ReadEntry`).
+///
+/// Scope: reads only. It never purchases, finishes, or filters by account
+/// (the TypeScript SDK admits transactions for the session account). Purchase,
+/// finish, and the update listener stay on OpenIAP; the finish itself is
+/// `OpenIapModule.finishTransaction`, whose own `Transaction.unfinished` scan
+/// skips unverified entries.
+///
+/// Errors: these StoreKit sequences do not throw. Nothing here turns a
+/// failure into an empty list; an empty list means StoreKit returned none.
+///
+/// Removal: delete this shim once the pinned OpenIAP release offers a
+/// verified-only read that skips (and reports) unverified entries (upstream
+/// request 3 in `docs/specs/commerce/openiap-upstream-proposal.md`).
+public enum RecoveryReadShim {
+    /// `Transaction.unfinished`.
+    public static func unfinished() async -> [StoreKitTransactionPolicy.ReadEntry] {
+        await read(StoreKit.Transaction.unfinished)
+    }
+
+    /// `Transaction.currentEntitlements` (active non-consumables and
+    /// subscriptions; revoked ones are not entitlements).
+    public static func currentEntitlements() async -> [StoreKitTransactionPolicy.ReadEntry] {
+        await read(StoreKit.Transaction.currentEntitlements)
+    }
+
+    /// `Transaction.all`, the history the 0.3 finish searched.
+    public static func history() async -> [StoreKitTransactionPolicy.ReadEntry] {
+        await read(StoreKit.Transaction.all)
+    }
+
+    static func read(_ sequence: StoreKit.Transaction.Transactions) async -> [StoreKitTransactionPolicy.ReadEntry] {
+        var entries: [StoreKitTransactionPolicy.ReadEntry] = []
+        for await result in sequence {
+            entries.append(entry(result))
+        }
+        return entries
+    }
+
+    static func entry(
+        _ result: VerificationResult<StoreKit.Transaction>
+    ) -> StoreKitTransactionPolicy.ReadEntry {
+        guard case .verified(let transaction) = result else { return .unverified }
+        guard let mapped = MpgdStoreKitTransaction(verified: transaction, jws: result.jwsRepresentation) else {
+            return .notOneTime
+        }
+        return .oneTime(mapped)
+    }
+}
+
+extension MpgdStoreKitTransaction {
+    /// The 0.3 fields of a StoreKit-verified one-time transaction; nil for a
+    /// subscription. Shared by the read and revocation shims.
+    init?(verified transaction: StoreKit.Transaction, jws: String) {
+        let type: MpgdOneTimeType
+        switch transaction.productType {
+        case .consumable: type = .consumable
+        case .nonConsumable: type = .nonConsumable
+        default: return nil
+        }
+        self.init(
+            transactionId: String(transaction.id),
+            originalTransactionId: String(transaction.originalID),
+            productId: transaction.productID,
+            type: type,
+            appAccountToken: transaction.appAccountToken?.uuidString,
+            purchasedAtMillis: transaction.purchaseDate.timeIntervalSince1970 * 1000,
+            revokedAtMillis: transaction.revocationDate.map { $0.timeIntervalSince1970 * 1000 },
+            signedTransaction: jws
+        )
+    }
+}

package/ios/Sources/MpgdStoreKitBridge/RevocationUpdatesShim.swift

@@ -0,0 +1,57 @@
+import Foundation
+import StoreKit
+
+/// Compatibility shim: forwards verified **revoked** one-time transactions.
+///
+/// Why: OpenIAP Apple 4.0.5's `Transaction.updates` listener skips any
+/// transaction with a `revocationDate` (`OpenIapStoreKitModule`
+/// `startTransactionListener`, "Skipping revoked transaction"). The 0.3 mpgd
+/// plugin forwarded those updates as `transactionUpdated` with `revokedAt`,
+/// and `StoreSdk` turns them into `state: 'revoked'` so the game asks its
+/// server to re-check the grant. Dropping them would silently remove the
+/// refund signal.
+///
+/// Scope: this observes `Transaction.updates` only to read revocations. It
+/// never purchases, lists, or finishes anything, and it ignores every
+/// non-revoked update (OpenIAP's listener delivers those). The signal is a
+/// prompt for the server to re-verify, never a ledger clawback by itself.
+///
+/// Removal: delete this shim once the pinned OpenIAP release can deliver
+/// revoked transactions to its purchase listener (the upstream proposal in
+/// `docs/specs/commerce/openiap-upstream-proposal.md` asks for that).
+public final class RevocationUpdatesShim {
+    private var task: Task<Void, Never>?
+
+    public init() {}
+
+    public func start(onRevoked: @escaping @Sendable (MpgdStoreKitTransaction) -> Void) {
+        guard task == nil else { return }
+        task = Task.detached(priority: .utility) {
+            for await result in StoreKit.Transaction.updates {
+                if Task.isCancelled { return }
+                guard case .verified(let transaction) = result,
+                      let revoked = Self.revokedTransaction(transaction, jws: result.jwsRepresentation) else {
+                    continue
+                }
+                onRevoked(revoked)
+            }
+        }
+    }
+
+    public func stop() {
+        task?.cancel()
+        task = nil
+    }
+
+    deinit {
+        task?.cancel()
+    }
+
+    static func revokedTransaction(
+        _ transaction: StoreKit.Transaction,
+        jws: String
+    ) -> MpgdStoreKitTransaction? {
+        guard transaction.revocationDate != nil else { return nil }
+        return MpgdStoreKitTransaction(verified: transaction, jws: jws)
+    }
+}

package/ios/Sources/MpgdStoreKitBridge/StoreKitTransactionPolicy.swift

@@ -0,0 +1,356 @@
+import Foundation
+import OpenIAP
+
+/// The one-time product kinds the mpgd StoreKit plugin sells and reports.
+/// Raw values are the plugin's wire values (`StoreKitTransaction.type`).
+public enum MpgdOneTimeType: String, Equatable, Sendable {
+    case consumable = "consumable"
+    case nonConsumable = "non_consumable"
+
+    /// The App Store product kind as StoreKit and OpenIAP describe a product.
+    public init?(productType: ProductTypeIOS) {
+        switch productType {
+        case .consumable: self = .consumable
+        case .nonConsumable: self = .nonConsumable
+        default: return nil
+        }
+    }
+
+    /// The `type` claim of a StoreKit-verified JWS transaction
+    /// (`JWSTransactionDecodedPayload.type`): `Consumable` or `Non-Consumable`.
+    /// Subscriptions and unknown values are not one-time purchases.
+    public init?(transactionTypeClaim: String) {
+        switch transactionTypeClaim {
+        case "Consumable": self = .consumable
+        case "Non-Consumable": self = .nonConsumable
+        default: return nil
+        }
+    }
+}
+
+/// The fields of one verified StoreKit transaction the mpgd plugin reports.
+/// Both the OpenIAP purchase path and the revocation shim build this value,
+/// so every `transactionUpdated` and `getTransactions` entry has one shape.
+public struct MpgdStoreKitTransaction: Equatable, Sendable {
+    public let transactionId: String
+    public let originalTransactionId: String
+    public let productId: String
+    public let type: MpgdOneTimeType
+    /// Lowercased UUID, as the 0.3 native plugin reported it.
+    public let appAccountToken: String?
+    public let purchasedAtMillis: Double
+    public let revokedAtMillis: Double?
+    /// The StoreKit-verified JWS; the backend verifies it again.
+    public let signedTransaction: String
+
+    public init(
+        transactionId: String,
+        originalTransactionId: String,
+        productId: String,
+        type: MpgdOneTimeType,
+        appAccountToken: String?,
+        purchasedAtMillis: Double,
+        revokedAtMillis: Double?,
+        signedTransaction: String
+    ) {
+        self.transactionId = transactionId
+        self.originalTransactionId = originalTransactionId
+        self.productId = productId
+        self.type = type
+        self.appAccountToken = appAccountToken?.lowercased()
+        self.purchasedAtMillis = purchasedAtMillis
+        self.revokedAtMillis = revokedAtMillis
+        self.signedTransaction = signedTransaction
+    }
+}
+
+/// mpgd policy over OpenIAP's canonical Apple purchase: which transactions the
+/// plugin reports, the payload shape it reports them in, which ones it may
+/// finish, and how OpenIAP errors become the plugin's existing codes. Nothing
+/// here calls StoreKit; the Capacitor plugin and tests drive it directly.
+public enum StoreKitTransactionPolicy {
+    /// The provider the plugin requires. OpenIAP's Apple provider reports
+    /// `apple`; mpgd names the same store `app-store` on the JavaScript side.
+    public static let appleStoreId = StoreIds.Apple
+
+    // MARK: - Mapping
+
+    /// What the plugin makes of one OpenIAP Apple purchase (the `purchase`
+    /// result and listener events).
+    public enum Classification: Equatable {
+        /// A verified consumable or non-consumable the plugin reports.
+        case oneTime(MpgdStoreKitTransaction)
+        /// A subscription (its JWS `type` claim says so); never reported.
+        case notOneTime
+        /// No readable StoreKit JWS, no `type` claim, another provider, or no
+        /// id. Never reported from the OpenIAP purchase and listener paths.
+        case unreadable
+    }
+
+    public static func classify(_ purchase: PurchaseIOS) -> Classification {
+        guard purchase.storeId == appleStoreId, purchase.store == .apple,
+              !purchase.id.isEmpty, !purchase.productId.isEmpty,
+              let jws = purchase.purchaseToken, isCompactJws(jws),
+              let claims = jwsPayload(jws),
+              let typeClaim = claims["type"] as? String else {
+            return .unreadable
+        }
+        guard let type = MpgdOneTimeType(transactionTypeClaim: typeClaim) else {
+            return .notOneTime
+        }
+        return .oneTime(MpgdStoreKitTransaction(
+            transactionId: purchase.id,
+            // OpenIAP omits an original id of 0; the 0.3 plugin always sent one.
+            originalTransactionId: purchase.originalTransactionIdentifierIOS ?? purchase.id,
+            productId: purchase.productId,
+            type: type,
+            appAccountToken: purchase.appAccountToken,
+            purchasedAtMillis: purchase.transactionDate,
+            revokedAtMillis: purchase.revocationDateIOS,
+            signedTransaction: jws
+        ))
+    }
+
+    /// The verified one-time transaction an OpenIAP Apple purchase describes,
+    /// or nil for anything the plugin does not report.
+    public static func transaction(from purchase: PurchaseIOS) -> MpgdStoreKitTransaction? {
+        if case .oneTime(let transaction) = classify(purchase) { return transaction }
+        return nil
+    }
+
+    /// The `StoreKitTransaction` payload of the 0.3 native plugin, key for key.
+    /// `unfinished` is set only on `getTransactions` entries.
+    public static func payload(
+        _ transaction: MpgdStoreKitTransaction,
+        unfinished: Bool? = nil
+    ) -> [String: Any] {
+        var payload: [String: Any] = [
+            "transactionId": transaction.transactionId,
+            "originalTransactionId": transaction.originalTransactionId,
+            "productId": transaction.productId,
+            "type": transaction.type.rawValue,
+            "purchasedAt": isoTimestamp(milliseconds: transaction.purchasedAtMillis),
+            "signedTransaction": transaction.signedTransaction
+        ]
+        if let token = transaction.appAccountToken {
+            payload["appAccountToken"] = token
+        }
+        if let revoked = transaction.revokedAtMillis {
+            payload["revokedAt"] = isoTimestamp(milliseconds: revoked)
+        }
+        if let unfinished {
+            payload["unfinished"] = unfinished
+        }
+        return payload
+    }
+
+    /// The `StoreKitProduct` payload of a one-time product, or nil for a
+    /// subscription the plugin does not sell.
+    public static func productPayload(_ product: ProductIOS) -> [String: Any]? {
+        guard let type = MpgdOneTimeType(productType: product.typeIOS) else {
+            return nil
+        }
+        return [
+            "productId": product.id,
+            "type": type.rawValue,
+            "title": product.displayNameIOS,
+            "description": product.description,
+            "formattedPrice": product.displayPrice,
+            "currencyCode": product.currency
+        ]
+    }
+
+    /// One entry of a StoreKit read (`RecoveryReadShim`): a verified one-time
+    /// transaction, a verified subscription the plugin never reports, or a
+    /// transaction StoreKit could not verify, which is skipped on its own as
+    /// the 0.3 plugin did, so it never hides or blocks a verified sibling.
+    public enum ReadEntry: Equatable, Sendable {
+        case oneTime(MpgdStoreKitTransaction)
+        case notOneTime
+        case unverified
+    }
+
+    /// `getTransactions`: every verified unfinished one-time transaction
+    /// (`unfinished: true`), then every current non-consumable entitlement not
+    /// already listed (`unfinished: false`), merged by transaction id.
+    /// Finished consumables are never added: they are not current
+    /// entitlements, and the game reads a consumable leaving this list as
+    /// evidence that its finish landed. No account filter here: the
+    /// TypeScript SDK admits transactions for the session account (and
+    /// restore handling needs to see the others).
+    public static func listedTransactions(
+        unfinished: [ReadEntry],
+        entitlements: [ReadEntry]
+    ) -> [[String: Any]] {
+        var seen = Set<String>()
+        var listed: [[String: Any]] = []
+        for entry in unfinished {
+            guard case .oneTime(let transaction) = entry,
+                  seen.insert(transaction.transactionId).inserted else { continue }
+            listed.append(payload(transaction, unfinished: true))
+        }
+        for entry in entitlements {
+            guard case .oneTime(let transaction) = entry,
+                  transaction.type == .nonConsumable,
+                  seen.insert(transaction.transactionId).inserted else { continue }
+            listed.append(payload(transaction, unfinished: false))
+        }
+        return listed
+    }
+
+    /// The transaction `finishTransaction` may finish: the verified one-time
+    /// transaction with this id that is not revoked and whose app account
+    /// token equals the session token. OpenIAP finishes whatever it is given,
+    /// so this is the plugin's local gate; it is still not a signed server
+    /// capability (see `finishTransaction` in the plugin definitions).
+    public static func finishable(
+        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.appAccountToken == expected 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
+    /// `Transaction.latest(for:)`) after checking `storeId`; these are the
+    /// fields it reads.
+    public static func finishInput(_ transaction: MpgdStoreKitTransaction) -> PurchaseIOS {
+        PurchaseIOS(
+            appAccountToken: transaction.appAccountToken,
+            id: transaction.transactionId,
+            isAutoRenewing: false,
+            originalTransactionIdentifierIOS: transaction.originalTransactionId,
+            productId: transaction.productId,
+            purchaseState: .purchased,
+            purchaseToken: transaction.signedTransaction,
+            quantity: 1,
+            revocationDateIOS: transaction.revokedAtMillis,
+            store: .apple,
+            storeId: appleStoreId,
+            transactionDate: transaction.purchasedAtMillis,
+            transactionId: transaction.transactionId
+        )
+    }
+
+    /// Whether a just-purchased transaction is the one the call asked for:
+    /// same product and bound to the token the purchase was started with.
+    public static func matchesPurchaseRequest(
+        _ transaction: MpgdStoreKitTransaction,
+        productId: String,
+        appAccountToken: String
+    ) -> Bool {
+        transaction.productId == productId
+            && transaction.appAccountToken == appAccountToken.lowercased()
+            && transaction.revokedAtMillis == nil
+    }
+
+    // MARK: - Errors
+
+    /// How a `requestPurchase` failure answers the plugin's `purchase` call.
+    public enum PurchaseFailure: Equatable {
+        case cancelled
+        /// Ask to Buy or another deferred payment: never a cancellation.
+        case pending
+        case rejected(code: String, message: String)
+    }
+
+    /// Maps an OpenIAP purchase error to the 0.3 plugin outcome. Anything that
+    /// may have happened after the purchase sheet opened stays
+    /// `STOREKIT_PURCHASE_UNCERTAIN`, so the game requeries instead of
+    /// assuming nothing was bought.
+    public static func purchaseFailure(_ code: ErrorCode) -> PurchaseFailure {
+        switch code {
+        case .userCancelled:
+            return .cancelled
+        case .deferredPayment, .pending:
+            return .pending
+        case .transactionValidationFailed:
+            return .rejected(code: "STOREKIT_TRANSACTION_UNVERIFIED",
+                             message: "StoreKit transaction failed verification or account binding.")
+        case .skuNotFound, .itemUnavailable, .emptySkuList:
+            return .rejected(code: "STOREKIT_PRODUCT_UNAVAILABLE",
+                             message: "The one-time product is unavailable.")
+        case .queryProduct:
+            return .rejected(code: "STOREKIT_PRODUCT_LOOKUP_FAILED",
+                             message: "StoreKit product lookup failed.")
+        case .developerError:
+            return .rejected(code: "STOREKIT_INVALID_PURCHASE",
+                             message: "A product ID and app account token are required.")
+        case .iapNotAvailable, .notPrepared, .initConnection:
+            // Raised before any purchase sheet: nothing was bought.
+            return .rejected(code: "STOREKIT_UNAVAILABLE",
+                             message: "StoreKit purchases are unavailable on this device.")
+        case .unknown:
+            return .rejected(code: "STOREKIT_UNKNOWN_RESULT",
+                             message: "StoreKit returned an unknown purchase result.")
+        default:
+            return .rejected(code: "STOREKIT_PURCHASE_UNCERTAIN",
+                             message: "StoreKit purchase result is uncertain; requery transactions.")
+        }
+    }
+
+    /// The code an OpenIAP failure rejects with (`finishTransaction`). The
+    /// transaction lists come from `RecoveryReadShim`, which skips an
+    /// unverified entry instead of failing.
+    public static func queryFailureCode(_ error: Error) -> String {
+        if let purchaseError = error as? PurchaseError,
+           purchaseError.code == .transactionValidationFailed {
+            return "STOREKIT_TRANSACTION_UNVERIFIED"
+        }
+        return "STOREKIT_UNAVAILABLE"
+    }
+
+    // MARK: - Validation and formatting
+
+    public static func isValidProductId(_ value: String) -> Bool {
+        value.range(of: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", options: .regularExpression) != nil
+    }
+
+    /// A UUID app account token, lowercased; nil when invalid. `finish`
+    /// also refuses the nil UUID, as the 0.3 plugin did; `purchase` accepted
+    /// any UUID in 0.3 and still does (the StoreKit SDK never sends the nil one).
+    public static func normalizedAccountToken(_ value: String?, allowNil: Bool = false) -> String? {
+        guard let value, let uuid = UUID(uuidString: value) else { return nil }
+        let normalized = uuid.uuidString.lowercased()
+        return !allowNil && normalized == "00000000-0000-0000-0000-000000000000" ? nil : normalized
+    }
+
+    /// The 0.3 plugin's timestamp format: `ISO8601DateFormatter` defaults.
+    public static func isoTimestamp(milliseconds: Double) -> String {
+        ISO8601DateFormatter().string(from: Date(timeIntervalSince1970: milliseconds / 1000))
+    }
+
+    static func isCompactJws(_ value: String) -> Bool {
+        let parts = value.split(separator: ".", omittingEmptySubsequences: false)
+        return parts.count == 3 && parts.allSatisfy { !$0.isEmpty }
+    }
+
+    /// The claims of a compact JWS StoreKit already verified. Only read for
+    /// the `type` claim OpenIAP's `PurchaseIOS` does not carry.
+    static func jwsPayload(_ jws: String) -> [String: Any]? {
+        let parts = jws.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count == 3 else { return nil }
+        var base64 = String(parts[1])
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        while base64.count % 4 != 0 {
+            base64.append("=")
+        }
+        guard let data = Data(base64Encoded: base64),
+              let object = try? JSONSerialization.jsonObject(with: data),
+              let claims = object as? [String: Any] else {
+            return nil
+        }
+        return claims
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "Opt-in StoreKit 2 one-time purchase collector and commerce v2 provider for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -33,23 +33,23 @@
   },
   "files": [
     "dist",
-    "ios",
+    "ios/Sources",
     "Package.swift"
   ],
   "peerDependencies": {
     "@capacitor/core": "^8.5.1",
-    "@mpgd/adapter-capacitor": "^0.12.0",
+    "@mpgd/adapter-capacitor": "^0.14.0",
     "@mpgd/bridge": "^0.16.0",
-    "@mpgd/platform": "^0.28.0"
+    "@mpgd/platform": "^0.30.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
-    "@mpgd/adapter-capacitor": "0.12.5",
-    "@mpgd/bridge": "0.16.0",
-    "@mpgd/game-services": "0.28.1",
-    "@mpgd/platform": "0.28.0"
+    "@mpgd/adapter-capacitor": "0.14.0",
+    "@mpgd/game-services": "0.30.0",
+    "@mpgd/platform": "0.30.0",
+    "@mpgd/bridge": "0.16.2"
   },
   "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"
+    "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"
   }
 }