@mpgd/capacitor-play-billing 0.3.9 → 0.4.0

package/README.md

@@ -1,10 +1,12 @@
 # @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
+The Kotlin native module runs on the [OpenIAP](https://github.com/hyodotdev/openiap)
+Google core (`io.github.hyochan.openiap:openiap-google` 4.0.6, which brings
+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** acknowledge, consume, or
+call OpenIAP's `finishTransaction`. 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.
@@ -69,7 +71,13 @@ when `includePending` is set; each carries `token = purchaseToken` and
 `transactionId = orderId`, or the `play-token-sha256:<hex>` token key until
 Play assigns an order id, so the same purchase deduplicates in the ledger. A
 purchased entry whose `isAcknowledged` flag is absent counts as unfinished so a
-paid purchase is never dropped. A purchase for a SKU that is not in `products`
+paid purchase is never dropped. The player's Restore Purchases read
+(`restore: true`, sent only by the reconciler's `restorePurchases`) also lists
+every `purchased` entry of exactly one configured durable, acknowledged or
+not: after a reinstall or on a new device the backend acknowledged it long
+ago under an earlier guest, and only this read hands it to the backend's
+restore sharing. Acknowledged consumables, unmapped SKUs, and multi-line
+purchases are not added. A purchase for a SKU that is not in `products`
 (a retired product) is still listed and emitted, with that product id as
 `sku` and the purchase token intact, so the reconciler can submit it when a
 logical id is still known. A multi-line purchase is listed the same way,
@@ -142,8 +150,10 @@ PR C3): the service provider is registered for every catalog product whose
 `platformProductIds.android` names a Play SKU (subscriptions are skipped),
 and `accountBinding` is the reference binding in
 `src/platform/commerceAccountBinding.ts`, the 64-character hex SHA-256 of
-`mpgd-commerce-account:<playerId>` for the authenticated player (a guest
-session binds nothing, so the purchase is refused with
+`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 binds nothing, so the purchase is refused with
 `ACCOUNT_BINDING_REQUIRED`). The backend's `resolveObfuscatedAccountId`
 must derive the same value, or both are replaced together.
 
@@ -173,17 +183,31 @@ owned purchases over the fake plugin: a purchased token is verified once, a
 pending purchase is never sent, a rejection is terminal, and an outage stays
 retryable.
 
-## Native compile check
+## Native engine
 
-The Kit reference app includes an opt-in Gradle compile target, without
-bundling Billing into the base app:
+The plugin keeps its 0.3 Capacitor contract (methods, the `purchaseUpdated`
+event, payload fields, `PLAY_BILLING_*` codes) over OpenIAP; the
+[migration record](../../docs/specs/commerce/openiap-migration.md) lists the
+contract, the call mapping, and every behavior difference. A shell needs the
+Kotlin Gradle plugin (2.2.20 unless the root project sets `kotlin_version`;
+OpenIAP needs 2.1.20 or newer), and the merged manifest gains OpenIAP's
+`dev.hyo.openiap.PROVIDER` entry and `INTERNET`. The plugin refuses to run
+unless OpenIAP's provider is `play`.
+
+## Native build check
+
+The Kit reference app includes an opt-in Gradle target, without bundling
+Billing into the base app. It compiles the Kotlin plugin, runs its JVM
+policy tests, and assembles the release AAR:
 
 ```sh
 cd apps/mobile-capacitor/android
 ./gradlew -PmpgdPlayBillingPluginTest=true \
-  :mpgd-capacitor-play-billing:compileDebugJavaWithJavac
+  :mpgd-capacitor-play-billing:testDebugUnitTest \
+  :mpgd-capacitor-play-billing:assembleRelease
 ```
 
-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
+`pnpm smoke:native-packed-store-plugins android` assembles the packed npm
+copy the same way. These builds 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

@@ -1,4 +1,23 @@
+buildscript {
+    // Same Kotlin line as the Capacitor 8 community plugins; a shell that pins
+    // `kotlin_version` in its root project wins. OpenIAP Google 4.0.6 needs a
+    // 2.1.20+ Kotlin compiler.
+    ext.kotlin_version = project.hasProperty('kotlin_version') ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
 apply plugin: 'com.android.library'
+// AGP 9 ships built-in Kotlin; only older AGP needs the Kotlin Android plugin.
+if (project.extensions.findByName('kotlin') == null) {
+    apply plugin: 'kotlin-android'
+}
 
 android {
     namespace 'dev.mpgd.capacitor.playbilling'
@@ -8,6 +27,21 @@ android {
         minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
     }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21
+    }
 }
 
 repositories {
@@ -17,6 +51,13 @@ repositories {
 
 dependencies {
     implementation project(':capacitor-android')
-    implementation 'com.android.billingclient:billing:9.1.0'
+    // OpenIAP Google core, Play flavor, pinned exactly. It brings Play Billing
+    // 9.1.0 as an API dependency, so the plugin no longer declares Billing
+    // itself. See docs/specs/commerce/openiap-migration.md before changing it.
+    implementation 'io.github.hyochan.openiap:openiap-google:4.0.6'
+    // OpenIAP publishes coroutines as a runtime dependency; the plugin calls
+    // its suspend API directly, so it needs them at compile time too.
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0'
     compileOnly 'androidx.appcompat:appcompat:1.7.1'
+    testImplementation 'junit:junit:4.13.2'
 }

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

@@ -0,0 +1,378 @@
+package dev.mpgd.capacitor.playbilling
+
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+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 dev.hyo.openiap.OpenIapError
+import dev.hyo.openiap.PurchaseAndroid
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineExceptionHandler
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import org.json.JSONException
+
+/**
+ * Purchase collection only, over the OpenIAP Google core. Finalization is
+ * server-owned after the mpgd ledger grant: this plugin never finishes,
+ * acknowledges, or consumes a purchase, and the encoded `isAcknowledged` flag
+ * lets the TypeScript provider list unfinished purchases for the backend
+ * finalizer. All plugin state is touched on the main thread only.
+ */
+@CapacitorPlugin(name = "CapacitorPlayBilling")
+class CapacitorPlayBillingPlugin : Plugin() {
+    private val mainHandler = Handler(Looper.getMainLooper())
+    // Every coroutine below answers its own call; the handler only keeps a
+    // billing failure that escapes them (an Error) from crashing the game.
+    private val scope = CoroutineScope(
+        SupervisorJob() + Dispatchers.Main.immediate + CoroutineExceptionHandler { _, error ->
+            Log.e(TAG, "Unhandled Google Play Billing failure: ${error.javaClass.name}")
+        },
+    )
+    private var connection: OpenIapPlayConnection? = null
+    private var providerError: String? = null
+    private var activePurchase: PluginCall? = null
+    private var activeProductId: String? = null
+    private var purchaseTimeout: Job? = null
+
+    /** True from the start of an OpenIAP purchase flow until OpenIAP returns. */
+    private var flowInProgress = false
+
+    /**
+     * Product of a purchase call that timed out while the Play UI was still
+     * up. When OpenIAP later reports that flow's cancel or failure, it is
+     * delivered as a `purchaseUpdated` event so the JavaScript attempt the
+     * timeout left open can close.
+     */
+    private var timedOutProductId: String? = null
+
+    override fun load() {
+        try {
+            connection = OpenIapPlayConnection.open(context) { purchase ->
+                onMain { onPurchaseUpdated(purchase) }
+            }
+        } catch (error: OpenIapError) {
+            providerError = error.message
+        } catch (error: Exception) {
+            logUnexpected("provider load", error)
+            providerError = "OpenIAP could not load the Google Play provider."
+        }
+    }
+
+    override fun handleOnDestroy() {
+        activePurchase?.let { call ->
+            clearActivePurchase(call)
+            call.reject("Purchase flow was interrupted.", "PLAY_BILLING_INTERRUPTED")
+        }
+        scope.cancel()
+        connection?.close()
+        connection = null
+        super.handleOnDestroy()
+    }
+
+    @PluginMethod
+    fun getProducts(call: PluginCall) {
+        onMain { getProductsOnMain(call) }
+    }
+
+    private fun getProductsOnMain(call: PluginCall) {
+        val ids = call.getArray("productIds")
+        if (ids == null || ids.length() == 0 || ids.length() > 100) {
+            call.reject("Provide 1-100 product IDs.", "PLAY_BILLING_INVALID_PRODUCTS")
+            return
+        }
+        val productIds = mutableListOf<String>()
+        try {
+            for (index in 0 until ids.length()) {
+                val productId = ids.getString(index)
+                if (productId == null || productId.trim().isEmpty()) {
+                    call.reject("Product ID is invalid.", "PLAY_BILLING_INVALID_PRODUCT")
+                    return
+                }
+                productIds += productId
+            }
+        } catch (error: JSONException) {
+            call.reject("Product IDs are invalid.", "PLAY_BILLING_INVALID_PRODUCTS")
+            return
+        }
+        val active = connectionOrReject(call) ?: return
+        launchCall(call) {
+            if (!active.connect()) {
+                rejectUnavailable(call)
+                return@launchCall
+            }
+            val products = JSArray()
+            for (product in active.fetchInAppProducts(productIds)) {
+                PlayBillingPolicy.productPayload(product)?.let { products.put(toJs(it)) }
+            }
+            call.resolve(JSObject().put("products", products))
+        }
+    }
+
+    @PluginMethod
+    fun purchase(call: PluginCall) {
+        onMain { purchaseOnMain(call) }
+    }
+
+    private fun purchaseOnMain(call: PluginCall) {
+        val productId = call.getString("productId")
+        val accountId = call.getString("obfuscatedAccountId")
+        val 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
+        }
+        val active = connectionOrReject(call) ?: return
+        // OpenIAP holds one flow at a time, including one whose call already
+        // timed out here; a second flow is busy until OpenIAP releases it.
+        if (activePurchase != null || flowInProgress) {
+            call.reject("Another purchase is already in progress.", "PLAY_BILLING_BUSY")
+            return
+        }
+        activePurchase = call
+        activeProductId = productId
+        timedOutProductId = null
+        flowInProgress = true
+        purchaseTimeout = scope.launch {
+            delay(PURCHASE_TIMEOUT_MILLIS)
+            if (activePurchase === call) {
+                timedOutProductId = activeProductId
+                clearActivePurchase(call)
+                call.reject("Purchase confirmation timed out; requery owned purchases.", "PLAY_BILLING_TIMEOUT")
+            }
+        }
+        scope.launch {
+            val resolution = try {
+                runPurchase(active, productId, accountId, selectedOfferToken)
+            } catch (error: CancellationException) {
+                throw error
+            } catch (error: OpenIapError) {
+                if (PlayBillingPolicy.isCancellation(error)) {
+                    PurchaseResolution.Cancelled
+                } else {
+                    PurchaseResolution.Failed(PlayBillingPolicy.errorCode(error), billingMessage(error))
+                }
+            } catch (error: Exception) {
+                logUnexpected("purchase", error)
+                PurchaseResolution.Failed("PLAY_BILLING_ERROR", "Google Play Billing failed.")
+            } finally {
+                // Released on every path, so one failure never leaves later
+                // purchases answering PLAY_BILLING_BUSY until a restart.
+                flowInProgress = false
+            }
+            settlePurchase(call, productId, resolution)
+        }
+    }
+
+    private suspend fun runPurchase(
+        active: OpenIapPlayConnection,
+        productId: String,
+        accountId: String,
+        selectedOfferToken: String?,
+    ): PurchaseResolution {
+        if (!active.connect()) {
+            return PurchaseResolution.Failed("PLAY_BILLING_SERVICE_UNAVAILABLE", UNAVAILABLE_MESSAGE)
+        }
+        val product = active.fetchInAppProducts(listOf(productId))
+            .filter { it.id == productId && PlayBillingPolicy.isAvailable(it) }
+            .singleOrNull()
+            ?: return PurchaseResolution.Failed("PLAY_BILLING_PRODUCT_UNAVAILABLE", "Product is unavailable.")
+        val offer = PlayBillingPolicy.selectOffer(PlayBillingPolicy.eligibleOffers(product), selectedOfferToken)
+            ?: return PurchaseResolution.Failed("PLAY_BILLING_OFFER_REQUIRED", "Select an eligible one-time offer.")
+        val activity = activity
+            ?: return PurchaseResolution.Failed("PLAY_BILLING_ACTIVITY_REQUIRED", "Billing requires a foreground activity.")
+        // Tokens Play already reports. OpenIAP answers ITEM_ALREADY_OWNED with
+        // the owned purchase; the 0.3 contract rejects instead, and the owned
+        // purchase still reaches JavaScript through `purchaseUpdated`.
+        val ownedBefore = active.inAppPurchases().mapNotNullTo(HashSet()) { it.purchaseToken }
+        val (purchases, error) = active.purchase(activity, productId, offer.offerTokenAndroid.orEmpty(), accountId)
+        val matched = purchases.firstOrNull { it.ids.orEmpty().contains(productId) }
+        if (matched != null) {
+            if (matched.purchaseToken in ownedBefore) {
+                return PurchaseResolution.Failed("PLAY_BILLING_ALREADY_OWNED", "The product is already owned.")
+            }
+            val payload = PlayBillingPolicy.purchasePayload(matched)
+                ?: return PurchaseResolution.Failed("PLAY_BILLING_EMPTY_PURCHASE", EMPTY_MESSAGE)
+            return PurchaseResolution.Reported(PlayBillingPolicy.outcomePayload(payload))
+        }
+        return when {
+            error == null -> PurchaseResolution.Failed("PLAY_BILLING_EMPTY_PURCHASE", EMPTY_MESSAGE)
+            PlayBillingPolicy.isCancellation(error) -> PurchaseResolution.Cancelled
+            else -> PurchaseResolution.Failed(PlayBillingPolicy.errorCode(error), billingMessage(error))
+        }
+    }
+
+    private fun settlePurchase(call: PluginCall, productId: String, resolution: PurchaseResolution) {
+        if (activePurchase === call) {
+            clearActivePurchase(call)
+            when (resolution) {
+                is PurchaseResolution.Reported -> call.resolve(toJs(resolution.outcome))
+                PurchaseResolution.Cancelled -> call.resolve(JSObject().put("status", "cancelled"))
+                is PurchaseResolution.Failed -> call.reject(resolution.message, resolution.code)
+            }
+            return
+        }
+        // The call already timed out. A purchase reached JavaScript through
+        // `purchaseUpdated`; a cancel or failure closes the open attempt.
+        if (timedOutProductId != productId) return
+        when (resolution) {
+            is PurchaseResolution.Reported -> timedOutProductId = null
+            PurchaseResolution.Cancelled -> notifyLateTerminalResult("cancelled", null)
+            is PurchaseResolution.Failed ->
+                if (resolution.code != "PLAY_BILLING_EMPTY_PURCHASE") {
+                    notifyLateTerminalResult("failed", resolution.code)
+                }
+        }
+    }
+
+    @PluginMethod
+    fun getPurchases(call: PluginCall) {
+        onMain {
+            val active = connectionOrReject(call) ?: return@onMain
+            launchCall(call) {
+                if (!active.connect()) {
+                    rejectUnavailable(call)
+                    return@launchCall
+                }
+                val purchases = JSArray()
+                for (purchase in active.inAppPurchases()) {
+                    PlayBillingPolicy.purchasePayload(purchase)?.let { purchases.put(toJs(it)) }
+                }
+                call.resolve(JSObject().put("purchases", purchases))
+            }
+        }
+    }
+
+    private fun onPurchaseUpdated(purchase: PurchaseAndroid) {
+        val payload = PlayBillingPolicy.purchasePayload(purchase) ?: return
+        // Retained until a listener consumes it: a purchase that completes
+        // after the purchase call timed out, or before the web view attached
+        // its listener, must still reach the provider's subscription.
+        notifyListeners("purchaseUpdated", toJs(PlayBillingPolicy.outcomePayload(payload)), true)
+        val timedOut = timedOutProductId
+        if (timedOut != null && purchase.ids.orEmpty().contains(timedOut)) {
+            timedOutProductId = null
+        }
+    }
+
+    /**
+     * A cancel or failure that arrives after the purchase call already timed
+     * out has no call to answer; without this event the JavaScript attempt
+     * would stay open and block another purchase of the product.
+     */
+    private fun notifyLateTerminalResult(status: String, code: String?) {
+        val productId = timedOutProductId ?: return
+        timedOutProductId = null
+        val outcome = JSObject().put("status", status).put("productId", productId)
+        if (code != null) {
+            outcome.put("code", code)
+        }
+        notifyListeners("purchaseUpdated", outcome, true)
+    }
+
+    private fun connectionOrReject(call: PluginCall): OpenIapPlayConnection? {
+        connection?.let { return it }
+        call.reject(providerError ?: "Google Play Billing is not configured.", "PLAY_BILLING_CONFIGURATION_ERROR")
+        return null
+    }
+
+    /** Runs a query on the main thread and answers every outcome, interruption included. */
+    private fun launchCall(call: PluginCall, block: suspend () -> Unit) {
+        scope.launch {
+            try {
+                block()
+            } catch (error: CancellationException) {
+                call.reject("Billing connection was interrupted.", "PLAY_BILLING_INTERRUPTED")
+                throw error
+            } catch (error: OpenIapError) {
+                call.reject(billingMessage(error), PlayBillingPolicy.errorCode(error))
+            } catch (error: Exception) {
+                logUnexpected(call.methodName ?: "query", error)
+                call.reject("Google Play Billing failed.", "PLAY_BILLING_ERROR")
+            }
+        }
+    }
+
+    /**
+     * The exception class only: a message or stack trace can carry a
+     * purchase token or account id, so neither is logged.
+     */
+    private fun logUnexpected(operation: String, error: Exception) {
+        Log.w(TAG, "Unexpected Google Play Billing failure in $operation: ${error.javaClass.name}")
+    }
+
+    private fun rejectUnavailable(call: PluginCall) {
+        call.reject(UNAVAILABLE_MESSAGE, "PLAY_BILLING_SERVICE_UNAVAILABLE")
+    }
+
+    private fun clearActivePurchase(call: PluginCall) {
+        if (activePurchase === call) {
+            activePurchase = null
+            activeProductId = null
+            purchaseTimeout?.cancel()
+            purchaseTimeout = null
+        }
+    }
+
+    private fun onMain(task: () -> Unit) {
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            task()
+        } else {
+            mainHandler.post(task)
+        }
+    }
+
+    private sealed class PurchaseResolution {
+        data class Reported(val outcome: Map<String, Any>) : PurchaseResolution()
+        object Cancelled : PurchaseResolution()
+        data class Failed(val code: String, val message: String) : PurchaseResolution()
+    }
+
+    private companion object {
+        const val TAG = "CapacitorPlayBilling"
+        const val PURCHASE_TIMEOUT_MILLIS = 180_000L
+        const val UNAVAILABLE_MESSAGE = "Google Play Billing is unavailable."
+        const val EMPTY_MESSAGE = "Purchase callback was empty; requery owned purchases."
+
+        fun billingMessage(error: OpenIapError): String =
+            "Google Play Billing is unavailable (${error.code})."
+
+        @Suppress("UNCHECKED_CAST")
+        fun toJs(value: Map<String, Any>): JSObject {
+            val result = JSObject()
+            for ((key, item) in value) {
+                when (item) {
+                    is Map<*, *> -> result.put(key, toJs(item as Map<String, Any>))
+                    is List<*> -> result.put(key, toJsArray(item))
+                    else -> result.put(key, item)
+                }
+            }
+            return result
+        }
+
+        @Suppress("UNCHECKED_CAST")
+        fun toJsArray(values: List<*>): JSArray {
+            val result = JSArray()
+            for (item in values) {
+                when (item) {
+                    is Map<*, *> -> result.put(toJs(item as Map<String, Any>))
+                    is List<*> -> result.put(toJsArray(item))
+                    else -> result.put(item)
+                }
+            }
+            return result
+        }
+    }
+}

package/android/src/main/java/dev/mpgd/capacitor/playbilling/OpenIapPlayConnection.kt

@@ -0,0 +1,146 @@
+package dev.mpgd.capacitor.playbilling
+
+import android.app.Activity
+import android.content.Context
+import dev.hyo.openiap.FetchProductsResultProducts
+import dev.hyo.openiap.OpenIapError
+import dev.hyo.openiap.OpenIapProtocol
+import dev.hyo.openiap.OpenIapProvider
+import dev.hyo.openiap.ProductAndroid
+import dev.hyo.openiap.ProductQueryType
+import dev.hyo.openiap.ProductRequest
+import dev.hyo.openiap.PurchaseAndroid
+import dev.hyo.openiap.RequestPurchaseAndroidProps
+import dev.hyo.openiap.RequestPurchaseProps
+import dev.hyo.openiap.RequestPurchasePropsByPlatforms
+import dev.hyo.openiap.RequestPurchaseResultPurchase
+import dev.hyo.openiap.RequestPurchaseResultPurchases
+import dev.hyo.openiap.listener.OpenIapPurchaseErrorListener
+import dev.hyo.openiap.listener.OpenIapPurchaseUpdateListener
+import dev.hyo.openiap.store.OpenIapStore
+import java.util.concurrent.atomic.AtomicReference
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+
+/**
+ * The OpenIAP Google connection one Capacitor plugin instance owns: the
+ * store-neutral half of the bridge.
+ *
+ * The provider comes from OpenIAP's own discovery (the merged
+ * `dev.hyo.openiap.PROVIDER` manifest entry), not from a hard-coded Play
+ * class, and the plugin refuses to run unless that provider is `play`: a
+ * receipt from another store must never reach the Google Play verifier.
+ * `OpenIapStore` is the public facade for connection, products, and purchase
+ * flows; the provider module is kept only for the in-app-only ownership
+ * query (`getAvailableItems(InApp)`), which the facade does not expose.
+ *
+ * The connection never finishes a purchase. `OpenIapStore.finishTransaction`,
+ * `acknowledgePurchaseAndroid`, and `consumePurchaseAndroid` are not called
+ * anywhere in this plugin: the mpgd backend finalizer consumes or
+ * acknowledges after its ledger grant.
+ */
+internal class OpenIapPlayConnection private constructor(
+    private val module: OpenIapProtocol,
+    private val store: OpenIapStore,
+    onPurchase: (PurchaseAndroid) -> Unit,
+) {
+    private val errorSink = AtomicReference<((OpenIapError) -> Unit)?>(null)
+    private val updateListener = OpenIapPurchaseUpdateListener { purchase ->
+        (purchase as? PurchaseAndroid)?.let(onPurchase)
+    }
+    private val errorListener = OpenIapPurchaseErrorListener { error ->
+        errorSink.get()?.invoke(error)
+    }
+
+    init {
+        store.addPurchaseUpdateListener(updateListener)
+        store.addPurchaseErrorListener(errorListener)
+    }
+
+    /** Connects, or confirms the live connection. False when Play Billing is unavailable. */
+    suspend fun connect(): Boolean = store.initConnection(null)
+
+    suspend fun fetchInAppProducts(productIds: List<String>): List<ProductAndroid> {
+        val result = store.fetchProducts(ProductRequest(skus = productIds, type = ProductQueryType.InApp))
+        return (result as? FetchProductsResultProducts)?.value.orEmpty().filterIsInstance<ProductAndroid>()
+    }
+
+    /** Every in-app purchase Play reports (`queryPurchasesAsync(INAPP)`), never subscriptions. */
+    suspend fun inAppPurchases(): List<PurchaseAndroid> =
+        module.getAvailableItems(ProductQueryType.InApp).filterIsInstance<PurchaseAndroid>()
+
+    /**
+     * Runs one purchase flow and returns the purchases OpenIAP matched to it,
+     * with the error OpenIAP published for it when it matched none. OpenIAP
+     * reports most flow failures (cancel included) through its error listener
+     * and an empty result rather than by throwing.
+     */
+    suspend fun purchase(
+        activity: Activity,
+        productId: String,
+        offerToken: String,
+        obfuscatedAccountId: String,
+    ): Pair<List<PurchaseAndroid>, OpenIapError?> {
+        // OpenIAP publishes one error per purchase request, tagged with its
+        // product; an untagged error counts only until a tagged one arrives.
+        val captured = AtomicReference<OpenIapError?>(null)
+        errorSink.set { error ->
+            when (error.requestProductId) {
+                productId -> captured.set(error)
+                null -> captured.compareAndSet(null, error)
+            }
+        }
+        try {
+            store.setActivity(activity)
+            val result = store.requestPurchase(
+                RequestPurchaseProps(
+                    request = RequestPurchaseProps.Request.Purchase(
+                        RequestPurchasePropsByPlatforms(
+                            google = RequestPurchaseAndroidProps(
+                                obfuscatedAccountId = obfuscatedAccountId,
+                                offerToken = offerToken,
+                                skus = listOf(productId),
+                            ),
+                        ),
+                    ),
+                    type = ProductQueryType.InApp,
+                ),
+            )
+            val purchases = when (result) {
+                is RequestPurchaseResultPurchases -> result.value.orEmpty()
+                is RequestPurchaseResultPurchase -> listOfNotNull(result.value)
+                else -> emptyList()
+            }.filterIsInstance<PurchaseAndroid>()
+            return purchases to captured.get()
+        } finally {
+            errorSink.set(null)
+        }
+    }
+
+    fun close() {
+        store.removePurchaseUpdateListener(updateListener)
+        store.removePurchaseErrorListener(errorListener)
+        errorSink.set(null)
+        store.clear()
+        // Ending the connection never touches a purchase; it only releases Play.
+        CoroutineScope(SupervisorJob() + Dispatchers.IO).launch {
+            runCatching { store.endConnection() }
+        }
+    }
+
+    companion object {
+        /** Throws `OpenIapError.ProviderConfiguration` unless OpenIAP links the Play provider. */
+        fun open(context: Context, onPurchase: (PurchaseAndroid) -> Unit): OpenIapPlayConnection {
+            val factory = OpenIapProvider.factory(context)
+            if (factory.storeId != PlayBillingPolicy.PLAY_STORE_ID) {
+                throw OpenIapError.ProviderConfiguration(
+                    "OpenIAP links the ${factory.storeId} provider; this plugin requires play.",
+                )
+            }
+            val module = OpenIapProvider.create(context, factory)
+            return OpenIapPlayConnection(module, OpenIapStore(module), onPurchase)
+        }
+    }
+}