@mpgd/capacitor-play-billing 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @mpgd/capacitor-play-billing
+
+Android-only, opt-in Google Play one-time purchase collection for Capacitor 8.
+The native module uses Google Play Billing Library 9.1.0. It queries product
+details, launches a purchase, listens for purchase updates, and requeries
+currently owned, unconsumed purchases. It intentionally does **not** call
+BillingClient acknowledge or consume. The game-owned backend must verify the
+purchase via Google Play Publisher, commit the mpgd ledger grant, and perform
+acknowledge/consume after the grant. A device callback alone never grants a
+purchase.
+
+The published package has passed mocked contract checks, an Android compile,
+and external tarball consumer checks. It has not yet passed a live Play purchase
+on a signed game; validate that path before a production rollout.
+
+The provider maps game logical product IDs to Play product IDs and requires a
+stable obfuscated account ID that agrees with the backend account resolver.
+When Play returns multiple eligible one-time offers, map an explicit
+`offerToken`; otherwise product lookup reports `PLAY_BILLING_OFFER_REQUIRED`
+instead of displaying a price for the wrong offer.
+`getOwnedPurchases()` returns provisional evidence for recovery after a missed
+callback or process restart. `recoverOwnedPlayPurchases({ provider, backend:
+backend.purchases, playerId })` submits completed owned purchases to the same
+authenticated backend using stable token-derived idempotency keys. Backend
+uncertainty stays pending for retry; `commerce.restore` deliberately returns
+no local entitlements. Pending Play purchases remain pending until Google
+reports purchased. The caller must not grant based on a native callback,
+`getOwnedPurchases()` result, or `commerce.restore` alone.
+If a launched purchase times out, is interrupted, or reports an already-owned
+item without a matching callback, the provider returns `pending`. Requery and
+recover owned purchases before offering another billing flow.
+
+The Kit reference app includes an opt-in Gradle compile target, without
+bundling Billing into the base app:
+
+```sh
+cd apps/mobile-capacitor/android
+./gradlew -PmpgdPlayBillingPluginTest=true \
+  :mpgd-capacitor-play-billing:compileDebugJavaWithJavac
+```
+
+This compile and the TypeScript fixture do not prove a live Play purchase,
+license-test configuration, or device behavior. Validate those in a game-owned
+Play Console project before enabling commerce for players.

package/android/build.gradle

@@ -0,0 +1,22 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace 'dev.mpgd.capacitor.playbilling'
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation 'com.android.billingclient:billing:9.1.0'
+    compileOnly 'androidx.appcompat:appcompat:1.7.1'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="com.android.vending.BILLING" />
+</manifest>

package/android/src/main/java/dev/mpgd/capacitor/playbilling/CapacitorPlayBillingPlugin.java

@@ -0,0 +1,433 @@
+package dev.mpgd.capacitor.playbilling;
+
+import android.os.Handler;
+import android.os.Looper;
+import com.android.billingclient.api.BillingClient;
+import com.android.billingclient.api.BillingClientStateListener;
+import com.android.billingclient.api.BillingFlowParams;
+import com.android.billingclient.api.BillingResult;
+import com.android.billingclient.api.PendingPurchasesParams;
+import com.android.billingclient.api.ProductDetails;
+import com.android.billingclient.api.Purchase;
+import com.android.billingclient.api.QueryProductDetailsParams;
+import com.android.billingclient.api.QueryPurchasesParams;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import org.json.JSONException;
+
+/** Purchase collection only. Finalization is server-owned after the mpgd ledger grant. */
+@CapacitorPlugin(name = "CapacitorPlayBilling")
+public class CapacitorPlayBillingPlugin extends Plugin {
+    private BillingClient billingClient;
+    private final List<PendingOperation> afterConnection = new ArrayList<>();
+    private final Handler mainHandler = new Handler(Looper.getMainLooper());
+    private boolean connecting;
+    private PluginCall activePurchase;
+    private String activeProductId;
+    private Runnable purchaseTimeout;
+
+    @Override
+    public void load() {
+        billingClient = BillingClient.newBuilder(getContext())
+            .setListener((result, purchases) ->
+                mainHandler.post(() -> onPurchasesUpdated(result, purchases)))
+            .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
+            .enableAutoServiceReconnection()
+            .build();
+    }
+
+    @Override
+    protected void handleOnDestroy() {
+        if (activePurchase != null) {
+            activePurchase.reject("Purchase flow was interrupted.", "PLAY_BILLING_INTERRUPTED");
+            clearActivePurchase(activePurchase);
+        }
+        for (PendingOperation operation : afterConnection) {
+            operation.call.reject("Billing connection was interrupted.", "PLAY_BILLING_INTERRUPTED");
+        }
+        afterConnection.clear();
+        if (billingClient != null) {
+            billingClient.endConnection();
+        }
+        super.handleOnDestroy();
+    }
+
+    @PluginMethod
+    public void getProducts(PluginCall call) {
+        mainHandler.post(() -> getProductsOnMain(call));
+    }
+
+    private void getProductsOnMain(PluginCall call) {
+        JSArray productIds = call.getArray("productIds");
+        if (productIds == null || productIds.length() == 0 || productIds.length() > 100) {
+            call.reject("Provide 1-100 product IDs.", "PLAY_BILLING_INVALID_PRODUCTS");
+            return;
+        }
+        List<QueryProductDetailsParams.Product> products = new ArrayList<>();
+        try {
+            for (int index = 0; index < productIds.length(); index++) {
+                String productId = productIds.getString(index);
+                if (productId == null || productId.trim().isEmpty()) {
+                    call.reject("Product ID is invalid.", "PLAY_BILLING_INVALID_PRODUCT");
+                    return;
+                }
+                products.add(QueryProductDetailsParams.Product.newBuilder()
+                    .setProductId(productId)
+                    .setProductType(BillingClient.ProductType.INAPP)
+                    .build());
+            }
+        } catch (JSONException error) {
+            call.reject("Product IDs are invalid.", "PLAY_BILLING_INVALID_PRODUCTS");
+            return;
+        }
+        connected(call, () -> billingClient.queryProductDetailsAsync(
+            QueryProductDetailsParams.newBuilder().setProductList(products).build(),
+            (result, detailsResult) -> {
+                if (!isOk(result)) {
+                    rejectBilling(call, result);
+                    return;
+                }
+                JSArray found = new JSArray();
+                for (ProductDetails details : detailsResult.getProductDetailsList()) {
+                    List<ProductDetails.OneTimePurchaseOfferDetails> offers =
+                        details.getOneTimePurchaseOfferDetailsList();
+                    if (offers == null || offers.isEmpty()) {
+                        continue;
+                    }
+                    JSArray eligibleOffers = new JSArray();
+                    for (ProductDetails.OneTimePurchaseOfferDetails offer : offers) {
+                        if (offer.getRentalDetails() == null && offer.getPreorderDetails() == null) {
+                            eligibleOffers.put(new JSObject()
+                                .put("offerToken", offer.getOfferToken())
+                                .put("formattedPrice", offer.getFormattedPrice())
+                                .put("currencyCode", offer.getPriceCurrencyCode()));
+                        }
+                    }
+                    if (eligibleOffers.length() == 0) {
+                        continue;
+                    }
+                    found.put(new JSObject()
+                        .put("productId", details.getProductId())
+                        .put("title", details.getTitle())
+                        .put("description", details.getDescription())
+                        .put("offers", eligibleOffers));
+                }
+                call.resolve(new JSObject().put("products", found));
+            }
+        ));
+    }
+
+    @PluginMethod
+    public void purchase(PluginCall call) {
+        mainHandler.post(() -> purchaseOnMain(call));
+    }
+
+    private void purchaseOnMain(PluginCall call) {
+        String productId = call.getString("productId");
+        String accountId = call.getString("obfuscatedAccountId");
+        String selectedOfferToken = call.getString("offerToken");
+        if (productId == null || productId.trim().isEmpty() || accountId == null
+            || accountId.trim().isEmpty() || accountId.length() > 64) {
+            call.reject("Product and account identifiers are required.", "PLAY_BILLING_INVALID_REQUEST");
+            return;
+        }
+        if (activePurchase != null) {
+            call.reject("Another purchase is already in progress.", "PLAY_BILLING_BUSY");
+            return;
+        }
+        activePurchase = call;
+        activeProductId = productId;
+        purchaseTimeout = () -> {
+            if (activePurchase == call) {
+                clearActivePurchase(call);
+                call.reject("Purchase confirmation timed out; requery owned purchases.",
+                    "PLAY_BILLING_TIMEOUT");
+            }
+        };
+        mainHandler.postDelayed(purchaseTimeout, 180_000);
+        connected(call, () -> {
+            if (activePurchase != call) {
+                return;
+            }
+            billingClient.queryProductDetailsAsync(
+                QueryProductDetailsParams.newBuilder().setProductList(Collections.singletonList(
+                    QueryProductDetailsParams.Product.newBuilder()
+                        .setProductId(productId)
+                        .setProductType(BillingClient.ProductType.INAPP)
+                        .build()
+                )).build(),
+                (result, detailsResult) -> {
+                if (activePurchase != call) {
+                    return;
+                }
+                if (!isOk(result)) {
+                    clearActivePurchase(call);
+                    rejectBilling(call, result);
+                    return;
+                }
+                if (detailsResult.getProductDetailsList().size() != 1) {
+                    clearActivePurchase(call);
+                    call.reject("Product is unavailable.", "PLAY_BILLING_PRODUCT_UNAVAILABLE");
+                    return;
+                }
+                ProductDetails details = detailsResult.getProductDetailsList().get(0);
+                List<ProductDetails.OneTimePurchaseOfferDetails> offers =
+                    details.getOneTimePurchaseOfferDetailsList();
+                ProductDetails.OneTimePurchaseOfferDetails selected = selectOffer(
+                    offers, selectedOfferToken);
+                if (selected == null) {
+                    clearActivePurchase(call);
+                    call.reject("Select an eligible one-time offer.", "PLAY_BILLING_OFFER_REQUIRED");
+                    return;
+                }
+                BillingFlowParams.ProductDetailsParams productParams =
+                    BillingFlowParams.ProductDetailsParams.newBuilder()
+                        .setProductDetails(details)
+                        .setOfferToken(selected.getOfferToken())
+                        .build();
+                BillingFlowParams flow = BillingFlowParams.newBuilder()
+                    .setProductDetailsParamsList(Collections.singletonList(productParams))
+                    .setObfuscatedAccountId(accountId)
+                    .build();
+                if (getActivity() == null) {
+                    clearActivePurchase(call);
+                    call.reject("Billing requires a foreground activity.",
+                        "PLAY_BILLING_ACTIVITY_REQUIRED");
+                    return;
+                }
+                BillingResult launched = billingClient.launchBillingFlow(getActivity(), flow);
+                if (!isOk(launched)) {
+                    clearActivePurchase(call);
+                    if (launched.getResponseCode() == BillingClient.BillingResponseCode.USER_CANCELED) {
+                        call.resolve(new JSObject().put("status", "cancelled"));
+                    } else {
+                        rejectBilling(call, launched);
+                    }
+                }
+                }
+            );
+        });
+    }
+
+    @PluginMethod
+    public void getPurchases(PluginCall call) {
+        mainHandler.post(() -> getPurchasesOnMain(call));
+    }
+
+    private void getPurchasesOnMain(PluginCall call) {
+        connected(call, () -> billingClient.queryPurchasesAsync(
+            QueryPurchasesParams.newBuilder().setProductType(BillingClient.ProductType.INAPP).build(),
+            (result, purchases) -> {
+                if (!isOk(result)) {
+                    rejectBilling(call, result);
+                    return;
+                }
+                JSArray found = new JSArray();
+                for (Purchase purchase : purchases) {
+                    JSObject encoded = encodePurchase(purchase);
+                    if (encoded != null) {
+                        found.put(encoded);
+                    }
+                }
+                call.resolve(new JSObject().put("purchases", found));
+            }
+        ));
+    }
+
+    private void onPurchasesUpdated(BillingResult result, List<Purchase> purchases) {
+        PluginCall pending = activePurchase;
+        String expectedProductId = activeProductId;
+        if (result.getResponseCode() == BillingClient.BillingResponseCode.USER_CANCELED) {
+            if (pending != null) {
+                clearActivePurchase(pending);
+                pending.resolve(new JSObject().put("status", "cancelled"));
+            }
+            return;
+        }
+        if (!isOk(result)) {
+            if (pending != null) {
+                clearActivePurchase(pending);
+                rejectBilling(pending, result);
+            }
+            return;
+        }
+        if (purchases == null || purchases.isEmpty()) {
+            if (pending != null) {
+                clearActivePurchase(pending);
+                pending.reject("Purchase callback was empty; requery owned purchases.",
+                    "PLAY_BILLING_EMPTY_PURCHASE");
+            }
+            return;
+        }
+        for (Purchase purchase : purchases) {
+            JSObject encoded = encodePurchase(purchase);
+            if (encoded == null) {
+                continue;
+            }
+            JSObject outcome = new JSObject()
+                .put("status", encoded.optString("state"))
+                .put("purchase", encoded);
+            notifyListeners("purchaseUpdated", outcome);
+            if (pending != null && purchase.getProducts().contains(expectedProductId)) {
+                clearActivePurchase(pending);
+                pending.resolve(outcome);
+                pending = null;
+            }
+        }
+    }
+
+    private JSObject encodePurchase(Purchase purchase) {
+        int state = purchase.getPurchaseState();
+        if (state != Purchase.PurchaseState.PURCHASED
+            && state != Purchase.PurchaseState.PENDING) {
+            return null;
+        }
+        String token = purchase.getPurchaseToken();
+        if (token == null || token.trim().isEmpty() || purchase.getProducts().isEmpty()) {
+            return null;
+        }
+        JSArray productIds = new JSArray();
+        for (String productId : purchase.getProducts()) {
+            productIds.put(productId);
+        }
+        JSObject encoded = new JSObject()
+            .put("productIds", productIds)
+            .put("purchaseToken", token)
+            .put("state", state == Purchase.PurchaseState.PURCHASED ? "purchased" : "pending");
+        if (purchase.getPurchaseTime() > 0) {
+            encoded.put("purchaseTimeMillis", purchase.getPurchaseTime());
+        }
+        if (purchase.getOrderId() != null) {
+            encoded.put("orderId", purchase.getOrderId());
+        }
+        return encoded;
+    }
+
+    private ProductDetails.OneTimePurchaseOfferDetails selectOffer(
+        List<ProductDetails.OneTimePurchaseOfferDetails> offers,
+        String offerToken
+    ) {
+        if (offers == null) {
+            return null;
+        }
+        ProductDetails.OneTimePurchaseOfferDetails only = null;
+        int eligibleCount = 0;
+        for (ProductDetails.OneTimePurchaseOfferDetails offer : offers) {
+            if (offer.getRentalDetails() != null || offer.getPreorderDetails() != null) {
+                continue;
+            }
+            if (offerToken != null && offerToken.equals(offer.getOfferToken())) {
+                return offer;
+            }
+            eligibleCount++;
+            only = offer;
+        }
+        return offerToken == null && eligibleCount == 1 ? only : null;
+    }
+
+    private void connected(PluginCall call, Runnable task) {
+        if (billingClient.isReady()) {
+            task.run();
+            return;
+        }
+        afterConnection.add(new PendingOperation(call, task));
+        if (connecting) {
+            return;
+        }
+        connecting = true;
+        billingClient.startConnection(new BillingClientStateListener() {
+            @Override
+            public void onBillingSetupFinished(BillingResult result) {
+                connecting = false;
+                List<PendingOperation> queued = new ArrayList<>(afterConnection);
+                afterConnection.clear();
+                if (!isOk(result)) {
+                    for (PendingOperation operation : queued) {
+                        clearActivePurchase(operation.call);
+                        rejectBilling(operation.call, result);
+                    }
+                    return;
+                }
+                for (PendingOperation operation : queued) {
+                    operation.task.run();
+                }
+            }
+
+            @Override
+            public void onBillingServiceDisconnected() {
+                connecting = false;
+                List<PendingOperation> queued = new ArrayList<>(afterConnection);
+                afterConnection.clear();
+                for (PendingOperation operation : queued) {
+                    clearActivePurchase(operation.call);
+                    operation.call.reject("Billing service disconnected.", "PLAY_BILLING_DISCONNECTED");
+                }
+            }
+        });
+    }
+
+    private boolean isOk(BillingResult result) {
+        return result.getResponseCode() == BillingClient.BillingResponseCode.OK;
+    }
+
+    private void rejectBilling(PluginCall call, BillingResult result) {
+        int responseCode = result.getResponseCode();
+        String code;
+        switch (responseCode) {
+            case BillingClient.BillingResponseCode.SERVICE_DISCONNECTED:
+                code = "PLAY_BILLING_DISCONNECTED";
+                break;
+            case BillingClient.BillingResponseCode.SERVICE_UNAVAILABLE:
+            case BillingClient.BillingResponseCode.SERVICE_TIMEOUT:
+                code = "PLAY_BILLING_SERVICE_UNAVAILABLE";
+                break;
+            case BillingClient.BillingResponseCode.NETWORK_ERROR:
+                code = "PLAY_BILLING_NETWORK_ERROR";
+                break;
+            case BillingClient.BillingResponseCode.ERROR:
+                code = "PLAY_BILLING_TRANSIENT_ERROR";
+                break;
+            case BillingClient.BillingResponseCode.ITEM_ALREADY_OWNED:
+                code = "PLAY_BILLING_ALREADY_OWNED";
+                break;
+            case BillingClient.BillingResponseCode.ITEM_UNAVAILABLE:
+                code = "PLAY_BILLING_PRODUCT_UNAVAILABLE";
+                break;
+            case BillingClient.BillingResponseCode.DEVELOPER_ERROR:
+                code = "PLAY_BILLING_CONFIGURATION_ERROR";
+                break;
+            default:
+                code = "PLAY_BILLING_ERROR";
+        }
+        call.reject("Google Play Billing is unavailable (" + result.getResponseCode() + ").",
+            code);
+    }
+
+    private void clearActivePurchase(PluginCall call) {
+        if (activePurchase == call) {
+            activePurchase = null;
+            activeProductId = null;
+            if (purchaseTimeout != null) {
+                mainHandler.removeCallbacks(purchaseTimeout);
+                purchaseTimeout = null;
+            }
+        }
+    }
+
+    private static final class PendingOperation {
+        final PluginCall call;
+        final Runnable task;
+
+        PendingOperation(PluginCall call, Runnable task) {
+            this.call = call;
+            this.task = task;
+        }
+    }
+}

package/dist/definitions.d.ts

@@ -0,0 +1,41 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+export type PlayPurchaseState = 'purchased' | 'pending';
+export interface PlayProduct {
+  readonly productId: string;
+  readonly title: string;
+  readonly description: string;
+  /** Explicit offer selection is required when Google returns multiple offers. */
+  readonly offers: readonly {
+    readonly offerToken: string;
+    readonly formattedPrice: string;
+    readonly currencyCode: string;
+  }[];
+}
+export interface PlayPurchase {
+  readonly productIds: readonly string[];
+  readonly purchaseToken: string;
+  readonly orderId?: string;
+  readonly purchaseTimeMillis?: number;
+  readonly state: PlayPurchaseState;
+}
+export interface PlayPurchaseOutcome {
+  readonly status: 'purchased' | 'pending' | 'cancelled';
+  readonly purchase?: PlayPurchase;
+}
+export interface CapacitorPlayBillingPlugin {
+  getProducts(input: {
+    readonly productIds: readonly string[];
+  }): Promise<{
+    readonly products: readonly PlayProduct[];
+  }>;
+  purchase(input: {
+    readonly productId: string;
+    readonly offerToken?: string;
+    readonly obfuscatedAccountId: string;
+  }): Promise<PlayPurchaseOutcome>;
+  /** Requeries owned, unconsumed purchases after restart or missed callbacks. */
+  getPurchases(): Promise<{
+    readonly purchases: readonly PlayPurchase[];
+  }>;
+  addListener(eventName: 'purchaseUpdated', listener: (event: PlayPurchaseOutcome) => 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 { CapacitorPlayBillingPlugin } from './definitions.js';
+export declare const CapacitorPlayBilling: CapacitorPlayBillingPlugin;

package/dist/plugin.js

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

package/dist/provider.d.ts

@@ -0,0 +1,79 @@
+import type { BridgeRequest, BridgeResponse } from '@mpgd/bridge';
+import type { PurchaseResult } from '@mpgd/platform';
+import type { CapacitorPlayBillingPlugin } from './definitions.js';
+export interface PlayBillingProductMapping {
+  readonly id: string;
+  readonly type: 'consumable' | 'non_consumable';
+  readonly storeId: string;
+  /** Required when Play lists multiple eligible purchase options or offers. */
+  readonly offerToken?: string;
+}
+export interface PlayBillingProviderOptions {
+  readonly products: readonly PlayBillingProductMapping[];
+  /** Must agree with the server's resolveObfuscatedAccountId mapping. */
+  readonly getObfuscatedAccountId: () => Promise<string> | string;
+  readonly sdk?: Pick<CapacitorPlayBillingPlugin, 'getProducts' | 'purchase' | 'getPurchases'>;
+  readonly isAndroid?: () => boolean;
+}
+export interface OwnedPlayPurchase {
+  readonly productId: string;
+  readonly result: PurchaseResult;
+  readonly purchasedAt?: string;
+}
+export type PlayBillingAvailability = 'available' | 'configuration-required' | 'temporarily-unavailable' | 'unsupported';
+export interface CapacitorPlayBillingProvider {
+  readonly id: 'google-play-billing';
+  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: PlayBillingAvailability;
+  }>>;
+  /** Requery owned, non-consumed transactions for game-owned backend recovery. */
+  getOwnedPurchases(): Promise<readonly OwnedPlayPurchase[]>;
+}
+export interface RecoveredPlayPurchase {
+  readonly productId: string;
+  readonly status: 'granted' | 'pending' | 'rejected';
+  readonly verification?: PlayPurchaseVerification;
+}
+export interface PlayPurchaseVerification {
+  readonly verified: boolean;
+  readonly disposition?: 'pending' | 'rejected';
+  readonly alreadyProcessed: boolean;
+  readonly ledgerEntryId?: string;
+  readonly reason?: string;
+}
+export interface PlayPurchaseRecoveryBackend {
+  verifyPurchase(input: {
+    readonly target: 'android';
+    readonly deploymentTarget?: string;
+    readonly playerId: string;
+    readonly productId: string;
+    readonly platformTransactionId: string;
+    readonly idempotencyKey: string;
+    readonly purchasedAt: string;
+    readonly evidence: NonNullable<PurchaseResult['evidence']>;
+  }): Promise<PlayPurchaseVerification>;
+}
+/**
+* Resubmit owned purchases after a callback was missed or the app restarted.
+* A native purchase is never credited locally; only the backend response grants it.
+*/
+export declare function recoverOwnedPlayPurchases(input: {
+  readonly provider: CapacitorPlayBillingProvider;
+  readonly backend: PlayPurchaseRecoveryBackend;
+  readonly playerId: string;
+  readonly deploymentTarget?: string;
+  readonly now?: () => string;
+}): Promise<readonly RecoveredPlayPurchase[]>;
+export declare function createCapacitorPlayBillingProvider(options: PlayBillingProviderOptions): CapacitorPlayBillingProvider;
+/** Must remain byte-for-byte compatible with the server's token transaction ID. */
+export declare function createGooglePlayTokenTransactionId(purchaseToken: string): Promise<string>;

package/dist/provider.js

@@ -0,0 +1,299 @@
+import { Capacitor } from '@capacitor/core';
+import { CapacitorPlayBilling } from './plugin.js';
+const googlePlayProductPurchaseEvidenceSchema = 'google-play.product-purchase.v2';
+class PlayPurchaseIntegrityError extends Error {
+}
+function isValidPurchaseToken(value) {
+    return typeof value === 'string'
+        && value.length > 0
+        && value.length <= 4096
+        && value.trim() === value
+        && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+/**
+ * Resubmit owned purchases after a callback was missed or the app restarted.
+ * A native purchase is never credited locally; only the backend response grants it.
+ */
+export async function recoverOwnedPlayPurchases(input) {
+    if (input.playerId.trim() === '') {
+        throw new TypeError('Recovery requires an authenticated player ID.');
+    }
+    const owned = await input.provider.getOwnedPurchases();
+    return Promise.all(owned.map(async ({ productId, result, purchasedAt }) => {
+        if (result.status === 'pending') {
+            return { productId, status: 'pending' };
+        }
+        if (result.status !== 'completed' || result.transactionId === undefined
+            || result.evidence === undefined) {
+            return { productId, status: 'rejected' };
+        }
+        const token = result.evidence.payload.purchaseToken;
+        if (typeof token !== 'string') {
+            return { productId, status: 'rejected' };
+        }
+        try {
+            const verification = await input.backend.verifyPurchase({
+                target: 'android',
+                ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+                playerId: input.playerId,
+                productId,
+                platformTransactionId: result.transactionId,
+                idempotencyKey: await createGooglePlayTokenTransactionId(token),
+                purchasedAt: purchasedAt ?? input.now?.() ?? new Date().toISOString(),
+                evidence: result.evidence,
+            });
+            return {
+                productId,
+                status: verification.verified ? 'granted' : (verification.disposition ?? 'pending'),
+                verification,
+            };
+        }
+        catch {
+            // Network or backend uncertainty must remain retryable, never rejected.
+            return { productId, status: 'pending' };
+        }
+    }));
+}
+export function createCapacitorPlayBillingProvider(options) {
+    const sdk = options.sdk ?? CapacitorPlayBilling;
+    const isAndroid = options.isAndroid ?? (() => Capacitor.getPlatform() === 'android');
+    const byLogicalId = new Map();
+    const byStoreId = new Map();
+    for (const product of options.products) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(product.id)
+            || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(product.storeId)
+            || byLogicalId.has(product.id)
+            || byStoreId.has(product.storeId)) {
+            throw new TypeError('Play Billing product mappings must be unique and valid.');
+        }
+        byLogicalId.set(product.id, product);
+        byStoreId.set(product.storeId, product);
+    }
+    if (byLogicalId.size === 0) {
+        throw new TypeError('Play Billing requires at least one one-time product.');
+    }
+    if (byLogicalId.size > 100) {
+        throw new TypeError('Play Billing supports at most 100 products per provider.');
+    }
+    async function getOwnedPurchases() {
+        if (!isAndroid()) {
+            throw new Error('Play Billing is only available on Android.');
+        }
+        const response = await sdk.getPurchases();
+        const owned = [];
+        for (const purchase of response.purchases) {
+            if (purchase.productIds.length !== 1) {
+                continue;
+            }
+            const mapping = byStoreId.get(purchase.productIds[0] ?? '');
+            if (mapping !== undefined) {
+                const timestamp = purchase.purchaseTimeMillis;
+                const purchasedAt = typeof timestamp === 'number'
+                    && Number.isSafeInteger(timestamp)
+                    && timestamp > 0
+                    && timestamp <= 8_640_000_000_000_000
+                    ? new Date(timestamp).toISOString()
+                    : undefined;
+                owned.push({
+                    productId: mapping.id,
+                    result: await convertPurchase(purchase),
+                    ...(purchasedAt === undefined ? {} : { purchasedAt }),
+                });
+            }
+        }
+        return owned;
+    }
+    function selectOffer(mapping, found) {
+        if (mapping.offerToken === undefined) {
+            return found.offers.length === 1 ? found.offers[0] : undefined;
+        }
+        return found.offers.find((item) => item.offerToken === mapping.offerToken);
+    }
+    async function request(input) {
+        try {
+            if (!isAndroid()) {
+                return failure(input.id, 'PLAY_BILLING_ANDROID_REQUIRED');
+            }
+            switch (input.method) {
+                case 'commerce.getProducts': {
+                    const response = await sdk.getProducts({
+                        productIds: [...byStoreId.keys()],
+                    });
+                    const products = [];
+                    for (const found of response.products) {
+                        const mapping = byStoreId.get(found.productId);
+                        if (mapping === undefined) {
+                            continue;
+                        }
+                        const offer = selectOffer(mapping, found);
+                        if (offer === undefined) {
+                            return failure(input.id, 'PLAY_BILLING_OFFER_REQUIRED');
+                        }
+                        products.push({
+                            id: mapping.id,
+                            type: mapping.type,
+                            title: found.title,
+                            description: found.description,
+                            price: {
+                                formatted: offer.formattedPrice,
+                                currencyCode: offer.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, 'PLAY_BILLING_PRODUCT_UNKNOWN');
+                    }
+                    let obfuscatedAccountId;
+                    try {
+                        obfuscatedAccountId = await options.getObfuscatedAccountId();
+                    }
+                    catch {
+                        return failure(input.id, 'PLAY_BILLING_ACCOUNT_LOOKUP_FAILED');
+                    }
+                    if (!/^[A-Za-z0-9._-]{1,64}$/u.test(obfuscatedAccountId)) {
+                        return failure(input.id, 'PLAY_BILLING_ACCOUNT_REQUIRED');
+                    }
+                    const outcome = await sdk.purchase({
+                        productId: mapping.storeId,
+                        obfuscatedAccountId,
+                        ...(mapping.offerToken === undefined ? {} : { offerToken: mapping.offerToken }),
+                    });
+                    return success(input.id, await convertOutcome(outcome, mapping.storeId));
+                }
+                case 'commerce.restore':
+                    // Native ownership is not an authoritative entitlement. The game
+                    // must submit getOwnedPurchases() results to its backend separately.
+                    return success(input.id, { restoredEntitlements: [] });
+                case 'commerce.getEntitlements':
+                    return success(input.id, []);
+                default:
+                    return failure(input.id, 'PLAY_BILLING_METHOD_UNSUPPORTED');
+            }
+        }
+        catch (error) {
+            if (error instanceof PlayPurchaseIntegrityError) {
+                return failure(input.id, 'PLAY_BILLING_EVIDENCE_INVALID');
+            }
+            const code = isRecord(error) ? error.code : undefined;
+            if (typeof code === 'string' && /^PLAY_BILLING_[A-Z_]+$/u.test(code)) {
+                if (input.method === 'commerce.purchase'
+                    && (code === 'PLAY_BILLING_TIMEOUT'
+                        || code === 'PLAY_BILLING_INTERRUPTED'
+                        || code === 'PLAY_BILLING_EMPTY_PURCHASE'
+                        || code === 'PLAY_BILLING_ALREADY_OWNED')) {
+                    // The purchase may have completed without an observed callback.
+                    // Requery owned purchases; never launch another flow blindly.
+                    return success(input.id, { status: 'pending', entitlementIds: [] });
+                }
+                const retryable = code === 'PLAY_BILLING_DISCONNECTED'
+                    || code === 'PLAY_BILLING_SERVICE_UNAVAILABLE'
+                    || code === 'PLAY_BILLING_NETWORK_ERROR'
+                    || code === 'PLAY_BILLING_TRANSIENT_ERROR';
+                return failure(input.id, code, retryable);
+            }
+            return failure(input.id, 'PLAY_BILLING_UNAVAILABLE', true);
+        }
+    }
+    return {
+        id: 'google-play-billing',
+        features: ['nativeIap'],
+        methods: [
+            'commerce.getProducts',
+            'commerce.purchase',
+            'commerce.restore',
+            'commerce.getEntitlements',
+        ],
+        bridge: { request },
+        async getAvailability() {
+            if (!isAndroid()) {
+                return { nativeIap: 'unsupported' };
+            }
+            try {
+                const response = await sdk.getProducts({ productIds: [...byStoreId.keys()] });
+                const hasPurchasableProduct = response.products.some((found) => {
+                    const mapping = byStoreId.get(found.productId);
+                    return mapping !== undefined && selectOffer(mapping, found) !== undefined;
+                });
+                return { nativeIap: hasPurchasableProduct ? 'available' : 'configuration-required' };
+            }
+            catch (error) {
+                const code = isRecord(error) ? error.code : undefined;
+                const configurationError = code === 'PLAY_BILLING_CONFIGURATION_ERROR'
+                    || code === 'PLAY_BILLING_PRODUCT_UNAVAILABLE'
+                    || code === 'PLAY_BILLING_OFFER_REQUIRED'
+                    || code === 'PLAY_BILLING_INVALID_PRODUCTS'
+                    || code === 'PLAY_BILLING_INVALID_PRODUCT';
+                return { nativeIap: configurationError
+                        ? 'configuration-required'
+                        : 'temporarily-unavailable' };
+            }
+        },
+        getOwnedPurchases,
+    };
+}
+async function convertOutcome(outcome, expectedStoreId) {
+    if (outcome.status === 'cancelled') {
+        return { status: 'cancelled', entitlementIds: [] };
+    }
+    const purchase = outcome.purchase;
+    if (purchase === undefined
+        || purchase.productIds.length !== 1
+        || purchase.productIds[0] !== expectedStoreId) {
+        throw new PlayPurchaseIntegrityError('Play purchase did not match the requested product.');
+    }
+    if ((outcome.status === 'purchased' && purchase.state !== 'purchased')
+        || (outcome.status === 'pending' && purchase.state !== 'pending')) {
+        throw new PlayPurchaseIntegrityError('Play purchase state is inconsistent.');
+    }
+    return convertPurchase(purchase);
+}
+async function convertPurchase(purchase) {
+    if (purchase.state !== 'pending' && purchase.state !== 'purchased') {
+        throw new PlayPurchaseIntegrityError('Play purchase state is invalid.');
+    }
+    if (!isValidPurchaseToken(purchase.purchaseToken)) {
+        throw new PlayPurchaseIntegrityError('Play purchase token is invalid.');
+    }
+    const evidence = {
+        schema: googlePlayProductPurchaseEvidenceSchema,
+        payload: { purchaseToken: purchase.purchaseToken },
+    };
+    if (purchase.state === 'pending') {
+        return { status: 'pending', entitlementIds: [], evidence };
+    }
+    const transactionId = purchase.orderId?.trim()
+        || await createGooglePlayTokenTransactionId(purchase.purchaseToken);
+    return {
+        status: 'completed',
+        transactionId,
+        entitlementIds: [],
+        evidence,
+    };
+}
+/** Must remain byte-for-byte compatible with the server's token transaction ID. */
+export async function createGooglePlayTokenTransactionId(purchaseToken) {
+    if (!isValidPurchaseToken(purchaseToken)) {
+        throw new TypeError('Google Play purchase token is invalid.');
+    }
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        throw new Error('Web Crypto is required to hash Google Play purchase tokens.');
+    }
+    const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(purchaseToken)));
+    return `play-token-sha256:${[...digest].map((value) => value.toString(16).padStart(2, '0')).join('')}`;
+}
+function success(id, data) {
+    return { id, ok: true, data };
+}
+function failure(id, code, retryable = false) {
+    return { id, ok: false, error: { code, message: code, retryable } };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mpgd/capacitor-play-billing",
+  "version": "0.1.0",
+  "description": "Opt-in Android Google Play Billing purchase collector for mpgd Capacitor games.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/mpgd-kit.git",
+    "directory": "native-plugins/capacitor-play-billing"
+  },
+  "bugs": {
+    "url": "https://github.com/imjlk/mpgd-kit/issues"
+  },
+  "homepage": "https://github.com/imjlk/mpgd-kit#readme",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "capacitor": {
+    "android": {
+      "src": "android"
+    }
+  },
+  "files": ["dist", "android/build.gradle", "android/src"],
+  "scripts": {
+    "check": "ttsc --noEmit",
+    "lint": "ttsc --noEmit",
+    "test": "cd ../.. && node tools/run-ttsx.mjs native-plugins/capacitor-play-billing/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/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"
+  }
+}