@mpgd/capacitor-storekit 0.1.0

package/Package.swift

@@ -0,0 +1,23 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "MpgdCapacitorStoreKit",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "MpgdCapacitorStoreKit", targets: ["MpgdCapacitorStoreKit"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", exact: "8.5.2")
+    ],
+    targets: [
+        .target(
+            name: "MpgdCapacitorStoreKit",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/CapacitorStoreKit"
+        )
+    ]
+)

package/README.md

@@ -0,0 +1,86 @@
+# @mpgd/capacitor-storekit
+
+Private, 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.
+
+Map each logical game product to its App Store Connect product ID and provide
+an authenticated, stable UUID `getAppAccountToken()` value. The game backend
+must resolve the same UUID for the player. Product lookup, purchase results,
+`Transaction.updates`, unfinished transactions, and current non-consumable
+entitlements provide **provisional evidence**, never a wallet or entitlement
+grant. A completed native purchase returns no `authoritativeGrant`.
+
+On startup, account restoration, and after a pending or uncertain checkout,
+call `recoverStoreKitPurchases({ provider, backend, playerId })`. It sends only
+transactions whose `appAccountToken` matches the current authenticated game
+account to the game-owned `backend.recoverPurchase` contract. That backend
+must reuse the original idempotency key from the durable purchase journal, or
+return the existing ledger grant for the same Apple evidence, product and
+player. It must not invent a new key for an already-granted transaction: the
+generic game-services verifier rejects such evidence replay. For new evidence,
+the backend uses the existing App Store Server API/JWS verifier to validate
+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.
+An unknown backend result stays pending and never triggers a
+new purchase sheet automatically.
+
+On the game server, `@mpgd/game-services/app-store-recovery` provides
+`createAppStoreRecoveryBackend(...)` for this contract. Construct it only after
+authenticating the game player, and bind `playerId` to that authenticated
+identity. Pass the same durable `GameServicesStore` instance and
+`createGameServicesBackend(...).purchases` used for checkout. Its optional
+`resolveOriginalIdempotencyKey` callback must query the game's durable
+checkout journal for the **original** key associated with this player and
+transaction. The adapter first checks existing App Store ledger evidence and
+rejects cross-player, cross-product, cross-deployment and key collisions. If
+neither a matching grant nor an original journal key exists, it returns
+`pending` without attempting a new grant. Do not use the in-memory store for
+production recovery. The game's HTTP/RPC endpoint must authenticate the
+request; this helper does not expose one or authenticate clients.
+For restored non-consumables whose new transaction ID differs from the
+original, configure `restoredNonConsumables` with the same catalog and official
+App Store evidence verifier, bundle ID and environment used by the game backend.
+When no prior grant exists, also bind `deploymentTarget` on the server-side
+recovery backend. The client-supplied target is not trusted to select a product;
+without a bound target this restore stays pending until the game backend is
+configured for its deployment. An existing grant can supply its recorded target.
+The bundle/environment identify an existing grant for its deployment target
+before product lookup; they must match the verifier configuration. The helper re-verifies
+the **current** Apple transaction and looks up the prior grant by its canonical
+original-transaction verification ID before reusing the original key. Without
+that verifier, this restore remains pending rather than trusting a client-
+reported original ID. A verifier that exceeds its timeout also remains pending.
+The native provider forwards both IDs and product type.
+For production-scale ledgers, implement the store's indexed
+`findEntitlementTransactionByPlatformEvidence` and
+`findEntitlementTransactionByIdempotency` methods, plus
+`findEntitlementTransactionByEvidenceVerificationId` for restored
+non-consumables. Without them, the helper
+uses the same full-ledger scan fallback as the generic game-services server.
+
+An existing grant is returned by the normal backend idempotent-retry path;
+that path relies on the prior verified ledger record rather than fetching
+fresh Apple status. Continue to process App Store revocations separately.
+Permanently rejected and account-mismatched transactions are reported as
+`rejected` and are **not** finished: the helper cannot prove content delivery
+for them. Persist that terminal result in the game-owned operation journal and
+do not run an automatic retry loop for it. A support flow may recheck a
+corrected account or backend decision later. One malformed transaction is
+reported separately and cannot block valid sibling transactions.
+
+The iOS native plugin also emits `transactionUpdated` for delayed StoreKit
+transactions. Call recovery after this event and on app launch because events
+can be missed while the game is closed. `commerce.restore` intentionally
+invokes user-initiated `AppStore.sync()` before returning no local entitlements;
+call recovery afterward. Subscriptions are not supported by this package;
+they require a separate subscription status and renewal flow.
+
+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
+game-owned account, keys, and device before a production rollout.

package/dist/definitions.d.ts

@@ -0,0 +1,53 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+export interface StoreKitProduct {
+  readonly productId: string;
+  readonly type: 'consumable' | 'non_consumable';
+  readonly title: string;
+  readonly description: string;
+  readonly formattedPrice: string;
+  readonly currencyCode: string;
+}
+export interface StoreKitTransaction {
+  readonly transactionId: string;
+  readonly originalTransactionId: string;
+  readonly productId: string;
+  readonly type: 'consumable' | 'non_consumable';
+  readonly appAccountToken?: string;
+  readonly purchasedAt: string;
+  readonly revokedAt?: string;
+  /** StoreKit-verified JWS; the game backend independently verifies Apple data. */
+  readonly signedTransaction: string;
+}
+export type StoreKitPurchaseOutcome = {
+  readonly status: 'purchased';
+  readonly transaction: StoreKitTransaction;
+} | {
+  readonly status: 'pending' | 'cancelled';
+};
+export interface CapacitorStoreKitPlugin {
+  getProducts(input: {
+    readonly productIds: readonly string[];
+  }): Promise<{
+    readonly products: readonly StoreKitProduct[];
+  }>;
+  purchase(input: {
+    readonly productId: string;
+    readonly appAccountToken: string;
+  }): Promise<StoreKitPurchaseOutcome>;
+  /** Includes unfinished consumables and current non-consumable entitlements. */
+  getTransactions(): Promise<{
+    readonly transactions: readonly StoreKitTransaction[];
+  }>;
+  /** User-initiated App Store account synchronization before restore. */
+  sync(): Promise<{
+    readonly synced: boolean;
+  }>;
+  /** Call only after the authenticated backend confirms the ledger grant. */
+  finishTransaction(input: {
+    readonly transactionId: string;
+    readonly ledgerEntryId: string;
+  }): Promise<{
+    readonly finished: boolean;
+  }>;
+  addListener(eventName: 'transactionUpdated', listener: (event: StoreKitTransaction) => void): Promise<PluginListenerHandle>;
+}

package/dist/definitions.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './definitions.js';
+export * from './plugin.js';
+export * from './provider.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './definitions.js';
+export * from './plugin.js';
+export * from './provider.js';

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { CapacitorStoreKitPlugin } from './definitions.js';
+export declare const CapacitorStoreKit: CapacitorStoreKitPlugin;

package/dist/plugin.js

@@ -0,0 +1,2 @@
+import { registerPlugin } from '@capacitor/core';
+export const CapacitorStoreKit = registerPlugin('CapacitorStoreKit');

package/dist/provider.d.ts

@@ -0,0 +1,94 @@
+import type { BridgeRequest, BridgeResponse } from '@mpgd/bridge';
+import type { PurchaseResult } from '@mpgd/platform';
+import type { CapacitorStoreKitPlugin } from './definitions.js';
+export interface StoreKitProductMapping {
+  readonly id: string;
+  readonly storeId: string;
+  readonly type: 'consumable' | 'non_consumable';
+}
+export interface StoreKitProviderOptions {
+  readonly products: readonly StoreKitProductMapping[];
+  /** Must agree with the authenticated backend's resolveAppAccountToken. */
+  readonly getAppAccountToken: () => string | Promise<string>;
+  readonly sdk?: Pick<CapacitorStoreKitPlugin, 'getProducts' | 'purchase' | 'getTransactions' | 'sync' | 'finishTransaction'>;
+  readonly isIos?: () => boolean;
+}
+export interface RecoverableStoreKitTransaction {
+  readonly productId: string;
+  readonly originalTransactionId: string;
+  readonly type: 'consumable' | 'non_consumable';
+  readonly appAccountToken?: string;
+  readonly purchasedAt: string;
+  readonly result: PurchaseResult;
+}
+export interface InvalidStoreKitTransaction {
+  readonly productId: string;
+  readonly transactionId?: string;
+  readonly reason: 'invalid-evidence' | 'revoked';
+}
+export interface StoreKitRecoverySnapshot {
+  readonly transactions: readonly RecoverableStoreKitTransaction[];
+  readonly invalid: readonly InvalidStoreKitTransaction[];
+}
+export interface CapacitorStoreKitProvider {
+  readonly id: 'apple-storekit';
+  readonly features: readonly ['nativeIap'];
+  readonly methods: readonly [
+    'commerce.getProducts',
+    'commerce.purchase',
+    'commerce.restore',
+    'commerce.getEntitlements'
+  ];
+  readonly bridge: {
+    request(input: BridgeRequest): Promise<BridgeResponse>;
+  };
+  getAvailability(): Promise<Readonly<{
+    nativeIap: 'available' | 'configuration-required' | 'temporarily-unavailable' | 'unsupported';
+  }>>;
+  getAppAccountToken(): Promise<string>;
+  getRecoverableTransactions(): Promise<StoreKitRecoverySnapshot>;
+  finishGrantedTransaction(input: {
+    readonly transactionId: string;
+    readonly ledgerEntryId: string;
+  }): Promise<boolean>;
+}
+export interface StoreKitPurchaseVerification {
+  readonly verified: boolean;
+  readonly disposition?: 'pending' | 'rejected';
+  readonly alreadyProcessed: boolean;
+  readonly ledgerEntryId?: string;
+  readonly reason?: string;
+}
+export interface StoreKitRecoveryBackend {
+  /**
+  * Resolve a journaled checkout with its ORIGINAL idempotency key, or return
+  * the already-recorded grant for matching App Store evidence and owner.
+  * The backend must verify Apple data before returning verified=true.
+  */
+  recoverPurchase(input: {
+    readonly target: 'ios';
+    readonly deploymentTarget?: string;
+    readonly playerId: string;
+    readonly productId: string;
+    readonly platformTransactionId: string;
+    readonly originalTransactionId: string;
+    readonly productType: 'consumable' | 'non_consumable';
+    readonly purchasedAt: string;
+  }): Promise<StoreKitPurchaseVerification>;
+}
+export interface RecoveredStoreKitPurchase {
+  readonly productId: string;
+  readonly transactionId?: string;
+  readonly status: 'granted' | 'pending' | 'rejected';
+  readonly reason?: 'invalid-evidence' | 'revoked' | 'account-mismatch';
+  readonly finishPending?: boolean;
+  readonly verification?: StoreKitPurchaseVerification;
+}
+/** Submit unfinished purchases to the backend before asking StoreKit to finish. */
+export declare function recoverStoreKitPurchases(input: {
+  readonly provider: CapacitorStoreKitProvider;
+  readonly backend: StoreKitRecoveryBackend;
+  readonly playerId: string;
+  readonly deploymentTarget?: string;
+}): Promise<readonly RecoveredStoreKitPurchase[]>;
+export declare function createCapacitorStoreKitProvider(options: StoreKitProviderOptions): CapacitorStoreKitProvider;

package/dist/provider.js

@@ -0,0 +1,297 @@
+import { Capacitor } from '@capacitor/core';
+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;
+/** Submit unfinished purchases to the backend before asking StoreKit to finish. */
+export async function recoverStoreKitPurchases(input) {
+    if (input.playerId.trim() === '') {
+        throw new TypeError('StoreKit recovery requires an authenticated player ID.');
+    }
+    const token = await input.provider.getAppAccountToken();
+    const snapshot = await input.provider.getRecoverableTransactions();
+    const recovered = await Promise.all(snapshot.transactions.map(async (item) => {
+        const transactionId = item.result.transactionId;
+        if (transactionId === undefined) {
+            return { productId: item.productId, status: 'rejected', reason: 'invalid-evidence' };
+        }
+        if (item.appAccountToken?.toLowerCase() !== token) {
+            // Shared Apple IDs can expose a transaction owned by another game user.
+            return {
+                productId: item.productId, transactionId, status: 'rejected', reason: 'account-mismatch',
+            };
+        }
+        try {
+            const verification = await input.backend.recoverPurchase({
+                target: 'ios',
+                ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+                playerId: input.playerId,
+                productId: item.productId,
+                platformTransactionId: transactionId,
+                originalTransactionId: item.originalTransactionId,
+                productType: item.type,
+                purchasedAt: item.purchasedAt,
+            });
+            if (!verification.verified) {
+                return {
+                    productId: item.productId,
+                    transactionId,
+                    status: verification.disposition ?? 'pending',
+                    verification,
+                };
+            }
+            if (verification.ledgerEntryId === undefined || verification.ledgerEntryId.trim() === '') {
+                return { productId: item.productId, transactionId, status: 'pending', verification };
+            }
+            try {
+                const finished = await input.provider.finishGrantedTransaction({
+                    transactionId,
+                    ledgerEntryId: verification.ledgerEntryId,
+                });
+                return {
+                    productId: item.productId,
+                    transactionId,
+                    status: 'granted',
+                    finishPending: !finished,
+                    verification,
+                };
+            }
+            catch {
+                return {
+                    productId: item.productId,
+                    transactionId,
+                    status: 'granted',
+                    finishPending: true,
+                    verification,
+                };
+            }
+        }
+        catch {
+            return { productId: item.productId, transactionId, status: 'pending' };
+        }
+    }));
+    return [
+        ...recovered,
+        ...snapshot.invalid.map((item) => ({ ...item, status: 'rejected' })),
+    ];
+}
+export function createCapacitorStoreKitProvider(options) {
+    const sdk = options.sdk ?? CapacitorStoreKit;
+    const isIos = options.isIos ?? (() => Capacitor.getPlatform() === 'ios');
+    const byLogicalId = new Map();
+    const byStoreId = new Map();
+    for (const product of options.products) {
+        if (!productPattern.test(product.id)
+            || !productPattern.test(product.storeId)
+            || byLogicalId.has(product.id)
+            || byStoreId.has(product.storeId)) {
+            throw new TypeError('StoreKit product mappings must be unique and valid.');
+        }
+        byLogicalId.set(product.id, product);
+        byStoreId.set(product.storeId, product);
+    }
+    if (byLogicalId.size === 0 || byLogicalId.size > 100) {
+        throw new TypeError('StoreKit requires 1-100 one-time product mappings.');
+    }
+    async function getAppAccountToken() {
+        const token = (await options.getAppAccountToken()).toLowerCase();
+        if (!uuidPattern.test(token)) {
+            throw new TypeError('StoreKit requires a UUID app account token.');
+        }
+        return token;
+    }
+    async function getRecoverableTransactions() {
+        if (!isIos()) {
+            throw new Error('StoreKit is only available on iOS.');
+        }
+        const response = await sdk.getTransactions();
+        const owned = [];
+        const invalid = [];
+        const seen = new Set();
+        for (const transaction of response.transactions) {
+            const mapping = byStoreId.get(transaction.productId);
+            if (mapping === undefined) {
+                continue;
+            }
+            if (mapping.type !== transaction.type || !validTransaction(transaction)) {
+                invalid.push({
+                    productId: mapping.id,
+                    transactionId: transaction.transactionId,
+                    reason: 'invalid-evidence',
+                });
+                continue;
+            }
+            if (transaction.revokedAt !== undefined) {
+                invalid.push({
+                    productId: mapping.id,
+                    transactionId: transaction.transactionId,
+                    reason: 'revoked',
+                });
+                continue;
+            }
+            if (seen.has(transaction.transactionId)) {
+                continue;
+            }
+            seen.add(transaction.transactionId);
+            owned.push({
+                productId: mapping.id,
+                originalTransactionId: transaction.originalTransactionId,
+                type: transaction.type,
+                ...(transaction.appAccountToken === undefined
+                    ? {} : { appAccountToken: transaction.appAccountToken }),
+                purchasedAt: transaction.purchasedAt,
+                result: toPurchaseResult(transaction),
+            });
+        }
+        return { transactions: owned, invalid };
+    }
+    async function request(input) {
+        if (!isIos()) {
+            return failure(input.id, 'STOREKIT_IOS_REQUIRED');
+        }
+        try {
+            switch (input.method) {
+                case 'commerce.getProducts': {
+                    const response = await sdk.getProducts({ productIds: [...byStoreId.keys()] });
+                    const products = [];
+                    for (const item of response.products) {
+                        const mapping = byStoreId.get(item.productId);
+                        if (mapping === undefined || mapping.type !== item.type) {
+                            continue;
+                        }
+                        products.push({
+                            id: mapping.id,
+                            type: mapping.type,
+                            title: item.title,
+                            description: item.description,
+                            price: { formatted: item.formattedPrice, currencyCode: item.currencyCode },
+                        });
+                    }
+                    return success(input.id, products);
+                }
+                case 'commerce.purchase': {
+                    const payload = input.payload;
+                    const productId = isRecord(payload) ? payload.productId : undefined;
+                    const mapping = typeof productId === 'string' ? byLogicalId.get(productId) : undefined;
+                    if (mapping === undefined) {
+                        return failure(input.id, 'STOREKIT_PRODUCT_UNKNOWN');
+                    }
+                    const appAccountToken = await getAppAccountToken();
+                    const outcome = await sdk.purchase({
+                        productId: mapping.storeId,
+                        appAccountToken,
+                    });
+                    return success(input.id, convertOutcome(outcome, mapping, appAccountToken));
+                }
+                case 'commerce.restore':
+                    await sdk.sync();
+                    return success(input.id, { restoredEntitlements: [] });
+                case 'commerce.getEntitlements':
+                    return success(input.id, []);
+                default:
+                    return failure(input.id, 'STOREKIT_METHOD_UNSUPPORTED');
+            }
+        }
+        catch (error) {
+            const code = isRecord(error) ? error.code : undefined;
+            if (input.method === 'commerce.purchase' && code === 'STOREKIT_PURCHASE_UNCERTAIN') {
+                return success(input.id, { status: 'pending', entitlementIds: [] });
+            }
+            if (typeof code === 'string' && /^STOREKIT_[A-Z_]+$/u.test(code)) {
+                const retryable = code === 'STOREKIT_UNAVAILABLE'
+                    || code === 'STOREKIT_PRODUCT_LOOKUP_FAILED'
+                    || code === 'STOREKIT_SYNC_FAILED';
+                return failure(input.id, code, retryable);
+            }
+            if (error instanceof TypeError) {
+                return failure(input.id, 'STOREKIT_CONFIGURATION_ERROR');
+            }
+            return failure(input.id, 'STOREKIT_UNAVAILABLE', true);
+        }
+    }
+    return {
+        id: 'apple-storekit',
+        features: ['nativeIap'],
+        methods: [
+            'commerce.getProducts',
+            'commerce.purchase',
+            'commerce.restore',
+            'commerce.getEntitlements',
+        ],
+        bridge: { request },
+        async getAvailability() {
+            if (!isIos()) {
+                return { nativeIap: 'unsupported' };
+            }
+            try {
+                await getAppAccountToken();
+                const response = await sdk.getProducts({ productIds: [...byStoreId.keys()] });
+                const available = response.products.some((item) => {
+                    const mapping = byStoreId.get(item.productId);
+                    return mapping !== undefined && mapping.type === item.type;
+                });
+                return { nativeIap: available ? 'available' : 'configuration-required' };
+            }
+            catch (error) {
+                const code = isRecord(error) ? error.code : undefined;
+                return { nativeIap: code === 'STOREKIT_INVALID_PRODUCTS'
+                        || code === 'STOREKIT_PRODUCT_UNAVAILABLE'
+                        || error instanceof TypeError
+                        ? 'configuration-required' : 'temporarily-unavailable' };
+            }
+        },
+        getAppAccountToken,
+        getRecoverableTransactions,
+        async finishGrantedTransaction(input) {
+            if (!isIos() || !transactionPattern.test(input.transactionId)
+                || input.ledgerEntryId.trim() === '') {
+                throw new TypeError('StoreKit finish requires a verified grant and transaction ID.');
+            }
+            const response = await sdk.finishTransaction(input);
+            return response.finished;
+        },
+    };
+}
+function convertOutcome(outcome, mapping, expectedAccountToken) {
+    if (outcome.status !== 'purchased') {
+        return { status: outcome.status, entitlementIds: [] };
+    }
+    if (outcome.transaction.productId !== mapping.storeId
+        || outcome.transaction.type !== mapping.type
+        || outcome.transaction.appAccountToken?.toLowerCase() !== expectedAccountToken
+        || !validTransaction(outcome.transaction)) {
+        throw Object.assign(new Error('StoreKit purchase evidence is invalid.'), {
+            code: 'STOREKIT_EVIDENCE_INVALID',
+        });
+    }
+    return toPurchaseResult(outcome.transaction);
+}
+function toPurchaseResult(transaction) {
+    return {
+        status: 'completed',
+        transactionId: transaction.transactionId,
+        entitlementIds: [],
+    };
+}
+function validTransaction(value) {
+    return transactionPattern.test(value.transactionId)
+        && /^[0-9]{1,20}$/u.test(value.originalTransactionId)
+        && productPattern.test(value.productId)
+        && (value.type === 'consumable' || value.type === 'non_consumable')
+        && Number.isFinite(Date.parse(value.purchasedAt))
+        && typeof value.signedTransaction === 'string'
+        && value.signedTransaction.length > 0
+        && value.signedTransaction.length <= 128 * 1024
+        && value.signedTransaction.split('.').length === 3
+        && (value.revokedAt === undefined || Number.isFinite(Date.parse(value.revokedAt)))
+        && (value.appAccountToken === undefined || uuidPattern.test(value.appAccountToken));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function success(id, data) {
+    return { id, ok: true, data };
+}
+function failure(id, code, retryable = false) {
+    return { id, ok: false, error: { code, message: code, retryable } };
+}

package/ios/Sources/CapacitorStoreKit/CapacitorStoreKitPlugin.swift

@@ -0,0 +1,199 @@
+import Capacitor
+import Foundation
+import StoreKit
+
+@objc(CapacitorStoreKitPlugin)
+public class CapacitorStoreKitPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "CapacitorStoreKitPlugin"
+    public let jsName = "CapacitorStoreKit"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "getProducts", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "purchase", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getTransactions", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "sync", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "finishTransaction", returnType: CAPPluginReturnPromise)
+    ]
+
+    private var updatesTask: Task<Void, Never>?
+
+    @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)
+                }
+            }
+        }
+    }
+
+    deinit {
+        updatesTask?.cancel()
+    }
+
+    @objc func getProducts(_ call: CAPPluginCall) {
+        guard let identifiers = call.options["productIds"] as? [String],
+              !identifiers.isEmpty, identifiers.count <= 100,
+              identifiers.allSatisfy({ Self.validProductId($0) }) else {
+            call.reject("Provide 1-100 valid product IDs.", "STOREKIT_INVALID_PRODUCTS")
+            return
+        }
+        Task { @MainActor 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
+                    ]
+                }
+                call.resolve(["products": values])
+            } catch {
+                call.reject("StoreKit product lookup failed.", "STOREKIT_UNAVAILABLE", error)
+            }
+        }
+    }
+
+    @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 {
+            call.reject("A product ID and app account token are required.", "STOREKIT_INVALID_PURCHASE")
+            return
+        }
+        Task { @MainActor in
+            let product: Product
+            do {
+                guard let found = try await Product.products(for: [productId]).first,
+                      found.id == productId,
+                      Self.oneTimeType(found.type) != 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
+                    }
+                    // Never finish here: the game backend must commit its ledger grant first.
+                    call.resolve(["status": "purchased", "transaction": payload])
+                case .pending:
+                    call.resolve(["status": "pending"])
+                case .userCancelled:
+                    call.resolve(["status": "cancelled"])
+                @unknown default:
+                    call.reject("StoreKit returned an unknown purchase result.", "STOREKIT_UNKNOWN_RESULT")
+                }
+            } catch {
+                // The purchase sheet may have completed before an error reached us.
+                call.reject("StoreKit purchase result is uncertain; requery transactions.",
+                            "STOREKIT_PURCHASE_UNCERTAIN", error)
+            }
+        }
+    }
+
+    @objc func getTransactions(_ call: CAPPluginCall) {
+        Task {
+            var byId: [String: [String: Any]] = [:]
+            for await result in Transaction.unfinished {
+                if let payload = Self.verifiedPayload(result),
+                   let id = payload["transactionId"] as? String {
+                    byId[id] = payload
+                }
+            }
+            for await result in Transaction.currentEntitlements {
+                if let payload = Self.verifiedPayload(result),
+                   payload["type"] as? String == "non_consumable",
+                   let id = payload["transactionId"] as? String {
+                    byId[id] = payload
+                }
+            }
+            call.resolve(["transactions": Array(byId.values)])
+        }
+    }
+
+    @objc func sync(_ call: CAPPluginCall) {
+        Task { @MainActor in
+            do {
+                try await AppStore.sync()
+                call.resolve(["synced": true])
+            } catch {
+                call.reject("StoreKit account synchronization failed.", "STOREKIT_SYNC_FAILED", error)
+            }
+        }
+    }
+
+    @objc func finishTransaction(_ call: CAPPluginCall) {
+        guard let rawId = call.getString("transactionId"), let id = UInt64(rawId),
+              let ledgerEntryId = call.getString("ledgerEntryId"),
+              !ledgerEntryId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            call.reject("A transaction ID and confirmed ledger entry are required.",
+                        "STOREKIT_FINISH_REQUIRES_GRANT")
+            return
+        }
+        Task {
+            for await result in Transaction.all {
+                guard case .verified(let transaction) = result,
+                      transaction.id == id,
+                      transaction.revocationDate == nil,
+                      Self.oneTimeType(transaction.productType) != nil else { continue }
+                await transaction.finish()
+                call.resolve(["finished": true])
+                return
+            }
+            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)
+        }
+        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/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mpgd/capacitor-storekit",
+  "version": "0.1.0",
+  "description": "Opt-in StoreKit 2 one-time purchase collector for mpgd Capacitor games.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/mpgd-kit.git",
+    "directory": "native-plugins/capacitor-storekit"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "capacitor": {
+    "ios": {
+      "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"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.5.1",
+    "@mpgd/bridge": "^0.10.0",
+    "@mpgd/platform": "^0.13.0 || ^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"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}