@namiml/expo-nami-iap 3.4.0-dev.202605060437

package/android/src/amazon/java/ml/nami/expo/iap/amazon/AmazonProductMapper.kt

@@ -0,0 +1,119 @@
+package ml.nami.expo.iap.amazon
+
+import com.amazon.device.iap.model.Product
+import com.amazon.device.iap.model.ProductType
+
+/**
+ * Maps an Amazon IAP [Product] into a [Map] matching the
+ * `NamiProductDetails` / `ExpoNamiIapProduct` TypeScript type.
+ *
+ * Output keys mirror [ml.nami.expo.iap.ProductMapper] for Google Play:
+ * - `product_ref_id` (String)
+ * - `name` (String)
+ * - `description` (String)
+ * - `product_type` (`"one_time_purchase"` | `"subscription"`)
+ * - `offers` (List<Map<String, Any?>>)
+ *
+ * Amazon does not expose subscription period or structured pricing at the
+ * product level, so `subscription_period` is omitted and the price amount
+ * is best-effort parsed from the display string (e.g. "$9.99").
+ */
+internal object AmazonProductMapper {
+    /**
+     * Regex to extract the first decimal number from a price display string.
+     *
+     * Handles formats like:
+     * - `$9.99`
+     * - `EUR 12.49`
+     * - `9,99 EUR` (comma as decimal separator)
+     * - `1.234,56` (thousands separator + comma decimal)
+     */
+    private val PRICE_REGEX = Regex("""(\d[\d.,]*\d)""")
+
+    /**
+     * Convert an Amazon [Product] to a dictionary suitable for bridging to TypeScript.
+     */
+    fun toMap(product: Product): Map<String, Any?> =
+        mapOf(
+            "product_ref_id" to product.sku,
+            "name" to product.title,
+            "description" to product.description,
+            "product_type" to mapProductType(product.productType),
+            "offers" to buildOffers(product),
+        )
+
+    // ── Product type ────────────────────────────────────────────────────
+
+    private fun mapProductType(type: ProductType): String =
+        when (type) {
+            ProductType.CONSUMABLE,
+            ProductType.ENTITLED,
+            -> "one_time_purchase"
+            ProductType.SUBSCRIPTION -> "subscription"
+        }
+
+    // ── Offers ──────────────────────────────────────────────────────────
+
+    /**
+     * Build a single "default" offer from the Amazon product's price string.
+     *
+     * Amazon does not expose promo/intro offers at the product level, so
+     * the offers list always contains exactly one entry.
+     */
+    private fun buildOffers(product: Product): List<Map<String, Any?>> {
+        val priceAmount = parsePrice(product.price)
+        return listOf(
+            mapOf(
+                "offer_type" to "default",
+                "price" to priceAmount,
+                "price_display" to product.price,
+            ),
+        )
+    }
+
+    // ── Price parsing ──────────────────────────────────────────────────
+
+    /**
+     * Best-effort extraction of a numeric price from Amazon's display string.
+     *
+     * Amazon IAP does not provide structured price data (no `priceAmountMicros`).
+     * The display string varies by locale, e.g. `"$9.99"`, `"EUR 12,49"`.
+     *
+     * Strategy:
+     * 1. Extract the first sequence of digits, dots, and commas.
+     * 2. If the string contains both dot and comma, treat the last one as the
+     *    decimal separator and strip the other (thousands separator).
+     * 3. Replace comma with dot for standard Double parsing.
+     *
+     * Returns 0.0 if parsing fails.
+     */
+    internal fun parsePrice(priceString: String?): Double {
+        if (priceString.isNullOrBlank()) return 0.0
+
+        val match = PRICE_REGEX.find(priceString) ?: return 0.0
+        var numStr = match.groupValues[1]
+
+        val lastDot = numStr.lastIndexOf('.')
+        val lastComma = numStr.lastIndexOf(',')
+
+        numStr =
+            when {
+                // Both dot and comma present — last one is the decimal separator
+                lastDot >= 0 && lastComma >= 0 -> {
+                    if (lastComma > lastDot) {
+                        // e.g. "1.234,56" → comma is decimal
+                        numStr.replace(".", "").replace(",", ".")
+                    } else {
+                        // e.g. "1,234.56" → dot is decimal
+                        numStr.replace(",", "")
+                    }
+                }
+                // Only comma — treat as decimal separator
+                lastComma >= 0 -> numStr.replace(",", ".")
+                // Only dot or neither — already parseable
+                else -> numStr
+            }
+
+        return numStr.toDoubleOrNull() ?: 0.0
+    }
+}

package/android/src/amazon/java/ml/nami/expo/iap/amazon/AmazonPurchasingListener.kt

@@ -0,0 +1,35 @@
+package ml.nami.expo.iap.amazon
+
+import com.amazon.device.iap.PurchasingListener
+import com.amazon.device.iap.model.ProductDataResponse
+import com.amazon.device.iap.model.PurchaseResponse
+import com.amazon.device.iap.model.PurchaseUpdatesResponse
+import com.amazon.device.iap.model.UserDataResponse
+
+/**
+ * Amazon IAP [PurchasingListener] that delegates all callbacks to
+ * [AmazonIapBackend] for request-ID demultiplexing.
+ *
+ * Amazon's IAP SDK uses a single process-global listener registered via
+ * `PurchasingService.registerListener`. This class is a thin adapter that
+ * forwards each response to the backend for promise resolution.
+ */
+internal class AmazonPurchasingListener(
+    private val backend: AmazonIapBackend,
+) : PurchasingListener {
+    override fun onProductDataResponse(response: ProductDataResponse) {
+        backend.handleProductDataResponse(response)
+    }
+
+    override fun onPurchaseResponse(response: PurchaseResponse) {
+        backend.handlePurchaseResponse(response)
+    }
+
+    override fun onPurchaseUpdatesResponse(response: PurchaseUpdatesResponse) {
+        backend.handlePurchaseUpdatesResponse(response)
+    }
+
+    override fun onUserDataResponse(response: UserDataResponse) {
+        // Not used in this module
+    }
+}

package/android/src/amazon/java/ml/nami/expo/iap/amazon/ExpoNamiIapAmazon.kt

@@ -0,0 +1,46 @@
+package ml.nami.expo.iap.amazon
+
+import java.lang.ref.WeakReference
+
+/**
+ * Singleton configuration object for the Amazon IAP backend.
+ *
+ * Provides a mode flag (`autoRegisterListener`) that controls whether
+ * [AmazonIapBackend] automatically calls `PurchasingService.registerListener`
+ * during [AmazonIapBackend.initConnection]. When set to `false` (receiver
+ * mode), the host app is responsible for registering its own
+ * `PurchasingListener` and forwarding events via
+ * [ExpoNamiIapAmazonReceiver].
+ */
+object ExpoNamiIapAmazon {
+    private var autoRegister: Boolean = true
+    internal var backendRef: WeakReference<AmazonIapBackend>? = null
+
+    /**
+     * Enable or disable automatic listener registration.
+     *
+     * When `enabled` is `false`, [AmazonIapBackend] will not call
+     * `PurchasingService.registerListener`. The host app must register its
+     * own listener and forward events through [ExpoNamiIapAmazonReceiver].
+     *
+     * Defaults to `true` (auto-register mode).
+     */
+    @JvmStatic
+    fun setAutoRegisterListener(enabled: Boolean) {
+        autoRegister = enabled
+    }
+
+    internal fun autoRegisterEnabled(): Boolean = autoRegister
+
+    internal fun setBackend(backend: AmazonIapBackend) {
+        backendRef = WeakReference(backend)
+    }
+
+    /**
+     * Reset state for testing. Not part of the public API.
+     */
+    internal fun resetForTesting() {
+        autoRegister = true
+        backendRef = null
+    }
+}

package/android/src/amazon/java/ml/nami/expo/iap/amazon/ExpoNamiIapAmazonReceiver.kt

@@ -0,0 +1,48 @@
+package ml.nami.expo.iap.amazon
+
+import com.amazon.device.iap.model.ProductDataResponse
+import com.amazon.device.iap.model.PurchaseResponse
+import com.amazon.device.iap.model.PurchaseUpdatesResponse
+import com.amazon.device.iap.model.UserDataResponse
+
+/**
+ * Public forwarding surface for receiver mode.
+ *
+ * When the host app owns `PurchasingService.registerListener`, it should
+ * forward every callback to the corresponding `@JvmStatic` method here.
+ * Each method delegates to the active [AmazonIapBackend] instance via the
+ * weak reference held by [ExpoNamiIapAmazon].
+ *
+ * Example (Java):
+ * ```java
+ * PurchasingService.registerListener(context, new PurchasingListener() {
+ *     @Override public void onProductDataResponse(ProductDataResponse r) {
+ *         ExpoNamiIapAmazonReceiver.onProductDataResponse(r);
+ *     }
+ *     // … other callbacks …
+ * });
+ * ```
+ */
+object ExpoNamiIapAmazonReceiver {
+    @JvmStatic
+    fun onProductDataResponse(response: ProductDataResponse) {
+        ExpoNamiIapAmazon.backendRef?.get()?.handleProductDataResponse(response)
+    }
+
+    @JvmStatic
+    fun onPurchaseResponse(response: PurchaseResponse) {
+        ExpoNamiIapAmazon.backendRef?.get()?.handlePurchaseResponse(response)
+    }
+
+    @JvmStatic
+    fun onPurchaseUpdatesResponse(response: PurchaseUpdatesResponse) {
+        ExpoNamiIapAmazon.backendRef?.get()?.handlePurchaseUpdatesResponse(response)
+    }
+
+    @JvmStatic
+    fun onUserDataResponse(
+        @Suppress("UNUSED_PARAMETER") response: UserDataResponse,
+    ) {
+        // No-op for now — user data is not consumed by this module.
+    }
+}

package/android/src/google/java/ml/nami/expo/iap/google/PlayBillingBackend.kt

@@ -0,0 +1,446 @@
+package ml.nami.expo.iap.google
+
+import android.app.Activity
+import android.content.Context
+import com.android.billingclient.api.AcknowledgePurchaseParams
+import com.android.billingclient.api.BillingClient
+import com.android.billingclient.api.BillingClient.BillingResponseCode
+import com.android.billingclient.api.BillingClient.ProductType
+import com.android.billingclient.api.BillingFlowParams
+import com.android.billingclient.api.BillingResult
+import com.android.billingclient.api.ConsumeParams
+import com.android.billingclient.api.ProductDetails
+import com.android.billingclient.api.Purchase
+import com.android.billingclient.api.PurchasesUpdatedListener
+import com.android.billingclient.api.QueryProductDetailsParams
+import com.android.billingclient.api.QueryPurchasesParams
+import com.android.billingclient.api.acknowledgePurchase
+import com.android.billingclient.api.consumePurchase
+import com.android.billingclient.api.queryProductDetails
+import com.android.billingclient.api.queryPurchasesAsync
+import kotlinx.coroutines.CancellableContinuation
+import kotlinx.coroutines.async
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.suspendCancellableCoroutine
+import ml.nami.expo.iap.Errors
+import ml.nami.expo.iap.ExpoNamiIapException
+import ml.nami.expo.iap.IapBackend
+import ml.nami.expo.iap.ProductMapper
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * Google Play Billing implementation of [IapBackend].
+ *
+ * Handles product queries, eligibility checks, purchase orchestration,
+ * transaction finishing, and purchase restoration using the Play Billing
+ * v7 KTX suspend extensions.
+ */
+class PlayBillingBackend : IapBackend {
+    private var connection: PlayBillingConnection? = null
+    private val productCache = ConcurrentHashMap<String, ProductDetails>()
+    private val purchaseCache = ConcurrentHashMap<String, Purchase>()
+    private val pendingPurchases =
+        ConcurrentHashMap<String, CancellableContinuation<Map<String, Any?>>>()
+    private var transactionListener: ((Map<String, Any?>) -> Unit)? = null
+    private var errorListener: ((Map<String, Any?>) -> Unit)? = null
+
+    // ── Lifecycle ──────────────────────────────────────────────────────
+
+    override suspend fun initConnection(context: Context) {
+        val listener =
+            PurchasesUpdatedListener { result: BillingResult, purchases: List<Purchase>? ->
+                handlePurchasesUpdated(result, purchases)
+            }
+        connection = PlayBillingConnection(context, listener)
+        connection!!.ensureConnected()
+    }
+
+    override suspend fun endConnection() {
+        connection?.close()
+        connection = null
+        productCache.clear()
+        purchaseCache.clear()
+        pendingPurchases.clear()
+    }
+
+    // ── Products ───────────────────────────────────────────────────────
+
+    override suspend fun getProducts(skuIds: List<String>): List<Map<String, Any?>> {
+        val client = connection?.ensureConnected() ?: error("Not connected")
+
+        // Issue SUBS + INAPP queries in parallel
+        val allDetails =
+            coroutineScope {
+                val subsDeferred =
+                    async {
+                        queryByType(client, skuIds, ProductType.SUBS)
+                    }
+                val inappDeferred =
+                    async {
+                        queryByType(client, skuIds, ProductType.INAPP)
+                    }
+                subsDeferred.await() + inappDeferred.await()
+            }
+
+        // Cache all fetched products
+        for (pd in allDetails) {
+            productCache[pd.productId] = pd
+        }
+
+        // Preserve input order: build a lookup map by productId
+        val detailsByProductId = allDetails.associateBy { it.productId }
+        return skuIds.mapNotNull { skuId ->
+            detailsByProductId[skuId]?.let { ProductMapper.toMap(it) }
+        }
+    }
+
+    // ── Eligibility ────────────────────────────────────────────────────
+
+    override suspend fun checkEligibility(skuIds: List<String>): List<Map<String, Any?>> {
+        val client = connection?.ensureConnected() ?: error("Not connected")
+
+        // Fetch active subscription purchases
+        val subsParams =
+            QueryPurchasesParams
+                .newBuilder()
+                .setProductType(ProductType.SUBS)
+                .build()
+        val purchasesResult = client.queryPurchasesAsync(subsParams)
+        val activePurchases = purchasesResult.purchasesList
+
+        // Cache all returned purchases
+        for (purchase in activePurchases) {
+            purchaseCache[purchase.purchaseToken] = purchase
+        }
+
+        // Build a set of owned product IDs from active purchases
+        val ownedProductIds =
+            activePurchases
+                .filter { it.purchaseState == Purchase.PurchaseState.PURCHASED }
+                .flatMap { it.products }
+                .toSet()
+
+        return skuIds.map { skuId ->
+            val cached = productCache[skuId]
+            val hasActivePurchase = skuId in ownedProductIds
+            val hasIntroOrTrial = cached?.let { hasIntroOrTrialOffer(it) } ?: false
+
+            mapOf(
+                "product_ref_id" to skuId,
+                "intro_eligible" to (hasIntroOrTrial && !hasActivePurchase),
+                "promo_eligible" to !hasActivePurchase,
+            )
+        }
+    }
+
+    // ── Listeners ──────────────────────────────────────────────────────
+
+    override fun onTransactionUpdate(callback: (Map<String, Any?>) -> Unit) {
+        transactionListener = callback
+    }
+
+    override fun onError(callback: (Map<String, Any?>) -> Unit) {
+        errorListener = callback
+    }
+
+    // ── Purchase ────────────────────────────────────────────────────────
+
+    override suspend fun purchase(
+        activity: Activity,
+        skuId: String,
+        offerId: String?,
+        offerSignature: String?,
+        appAccountToken: String?,
+    ): Map<String, Any?> {
+        val client = connection?.ensureConnected() ?: error("Not connected")
+
+        // Look up cached ProductDetails; fetch if missing
+        val pd =
+            productCache[skuId] ?: run {
+                getProducts(listOf(skuId))
+                productCache[skuId]
+                    ?: throw ExpoNamiIapException.ItemUnavailable(
+                        "Product not found: $skuId",
+                    )
+            }
+
+        // Build ProductDetailsParams with optional offer token
+        val productDetailsParams = buildProductDetailsParams(pd, offerId)
+
+        // Build BillingFlowParams
+        val flowParamsBuilder =
+            BillingFlowParams
+                .newBuilder()
+                .setProductDetailsParamsList(listOf(productDetailsParams))
+        if (!appAccountToken.isNullOrEmpty()) {
+            flowParamsBuilder.setObfuscatedAccountId(appAccountToken)
+        }
+        val flowParams = flowParamsBuilder.build()
+
+        // Suspend until the PurchasesUpdatedListener resolves the continuation
+        return suspendCancellableCoroutine { cont ->
+            pendingPurchases[skuId] = cont
+            cont.invokeOnCancellation { pendingPurchases.remove(skuId) }
+
+            val launchResult = client.launchBillingFlow(activity, flowParams)
+            if (launchResult.responseCode != BillingResponseCode.OK) {
+                pendingPurchases.remove(skuId)
+                cont.resumeWithException(
+                    Errors.toException(launchResult.responseCode, launchResult.debugMessage),
+                )
+            }
+        }
+    }
+
+    // ── Restore ─────────────────────────────────────────────────────────
+
+    override suspend fun restorePurchases(): List<Map<String, Any?>> {
+        val client = connection?.ensureConnected() ?: error("Not connected")
+
+        val (subs, inapp) =
+            coroutineScope {
+                val subsDeferred =
+                    async {
+                        client.queryPurchasesAsync(
+                            QueryPurchasesParams
+                                .newBuilder()
+                                .setProductType(ProductType.SUBS)
+                                .build(),
+                        )
+                    }
+                val inappDeferred =
+                    async {
+                        client.queryPurchasesAsync(
+                            QueryPurchasesParams
+                                .newBuilder()
+                                .setProductType(ProductType.INAPP)
+                                .build(),
+                        )
+                    }
+                subsDeferred.await() to inappDeferred.await()
+            }
+
+        val all =
+            (subs.purchasesList + inapp.purchasesList).filter {
+                it.purchaseState == Purchase.PurchaseState.PURCHASED
+            }
+
+        // Cache every returned purchase
+        for (purchase in all) {
+            purchaseCache[purchase.purchaseToken] = purchase
+        }
+
+        return all.flatMap { purchase ->
+            purchase.products.map { productId -> purchaseToDict(purchase, productId) }
+        }
+    }
+
+    // ── Finish ─────────────────────────────────────────────────────────
+
+    /**
+     * Finish a transaction identified by [transactionId] (the purchase token).
+     *
+     * - Subscriptions (`"subs"`) are acknowledged via [BillingClient.acknowledgePurchase].
+     * - In-app products (`"inapp"`) are consumed via [BillingClient.consumePurchase],
+     *   which also implicitly acknowledges the purchase.
+     *
+     * If the purchase token is not found in the cache, this is a no-op (matching iOS behaviour).
+     */
+    override suspend fun finishTransaction(transactionId: String) {
+        val client = connection?.ensureConnected() ?: error("Not connected")
+
+        val purchase = purchaseCache[transactionId] ?: return
+        val productId = purchase.products.firstOrNull() ?: return
+        val productType = productCache[productId]?.productType
+
+        when (productType) {
+            ProductType.SUBS -> {
+                val params =
+                    AcknowledgePurchaseParams
+                        .newBuilder()
+                        .setPurchaseToken(transactionId)
+                        .build()
+                client.acknowledgePurchase(params)
+            }
+            ProductType.INAPP -> {
+                val params =
+                    ConsumeParams
+                        .newBuilder()
+                        .setPurchaseToken(transactionId)
+                        .build()
+                client.consumePurchase(params)
+            }
+            else -> {
+                // Unknown product type — acknowledge as a safe default
+                val params =
+                    AcknowledgePurchaseParams
+                        .newBuilder()
+                        .setPurchaseToken(transactionId)
+                        .build()
+                client.acknowledgePurchase(params)
+            }
+        }
+    }
+
+    // ── Internals ──────────────────────────────────────────────────────
+
+    /**
+     * Query Google Play for product details of a specific [productType].
+     */
+    private suspend fun queryByType(
+        client: BillingClient,
+        skuIds: List<String>,
+        productType: String,
+    ): List<ProductDetails> {
+        val productList =
+            skuIds.map { skuId ->
+                QueryProductDetailsParams.Product
+                    .newBuilder()
+                    .setProductId(skuId)
+                    .setProductType(productType)
+                    .build()
+            }
+        val params =
+            QueryProductDetailsParams
+                .newBuilder()
+                .setProductList(productList)
+                .build()
+        val result = client.queryProductDetails(params)
+        return if (result.billingResult.responseCode == BillingResponseCode.OK) {
+            result.productDetailsList ?: emptyList()
+        } else {
+            emptyList()
+        }
+    }
+
+    /**
+     * Check whether a [ProductDetails] has any introductory or free-trial offer.
+     *
+     * An intro/trial offer is a subscription offer (with a non-null offerId)
+     * that contains at least one pricing phase with a price lower than the
+     * base plan's standard price, or a free (0-price) phase.
+     */
+    private fun hasIntroOrTrialOffer(pd: ProductDetails): Boolean {
+        if (pd.productType != ProductType.SUBS) return false
+        val subOffers = pd.subscriptionOfferDetails ?: return false
+
+        // Find the base plan's standard price
+        val basePlan = subOffers.firstOrNull { it.offerId == null }
+        val basePriceMicros =
+            basePlan
+                ?.pricingPhases
+                ?.pricingPhaseList
+                ?.firstOrNull { it.priceAmountMicros > 0 }
+                ?.priceAmountMicros ?: return false
+
+        // Check for offers with free-trial or intro pricing phases
+        return subOffers.any { offer ->
+            offer.offerId != null &&
+                offer.pricingPhases.pricingPhaseList.any { phase ->
+                    phase.priceAmountMicros == 0L ||
+                        phase.priceAmountMicros in 1 until basePriceMicros
+                }
+        }
+    }
+
+    /**
+     * Build [BillingFlowParams.ProductDetailsParams] for the given [ProductDetails].
+     *
+     * For subscriptions, an offer token is required:
+     * - If [offerId] is specified, select the matching offer.
+     * - Otherwise, select the base plan (the entry with `offerId == null`).
+     *
+     * For in-app products, no offer token is set.
+     */
+    private fun buildProductDetailsParams(
+        pd: ProductDetails,
+        offerId: String?,
+    ): BillingFlowParams.ProductDetailsParams {
+        val builder =
+            BillingFlowParams.ProductDetailsParams
+                .newBuilder()
+                .setProductDetails(pd)
+
+        if (pd.productType == ProductType.SUBS) {
+            val subOffers = pd.subscriptionOfferDetails ?: emptyList()
+            val selectedOffer =
+                if (offerId != null) {
+                    subOffers.firstOrNull { it.offerId == offerId }
+                } else {
+                    // Pick the base plan (offerId == null)
+                    subOffers.firstOrNull { it.offerId == null }
+                }
+            selectedOffer?.let { builder.setOfferToken(it.offerToken) }
+        }
+
+        return builder.build()
+    }
+
+    /**
+     * Handles purchases updated callback from [PurchasesUpdatedListener].
+     *
+     * On success, emits each purchase via [transactionListener] and resolves
+     * any pending continuation in [pendingPurchases].
+     *
+     * On failure, fires [errorListener] and rejects all pending continuations.
+     */
+    private fun handlePurchasesUpdated(
+        result: BillingResult,
+        purchases: List<Purchase>?,
+    ) {
+        if (result.responseCode == BillingResponseCode.OK && purchases != null) {
+            for (purchase in purchases) {
+                // Cache for later finishTransaction lookup
+                purchaseCache[purchase.purchaseToken] = purchase
+                for (productId in purchase.products) {
+                    val dict = purchaseToDict(purchase, productId)
+                    transactionListener?.invoke(dict)
+                    pendingPurchases.remove(productId)?.resume(dict)
+                }
+            }
+        } else {
+            val ex = Errors.toException(result.responseCode, result.debugMessage)
+            val errDict =
+                mapOf(
+                    "code" to ex.code,
+                    "message" to ex.message,
+                    "nativeCode" to ex.nativeCode,
+                )
+            errorListener?.invoke(errDict)
+            // Reject all pending continuations — we cannot reliably identify which SKU
+            val pending = pendingPurchases.values.toList()
+            pendingPurchases.clear()
+            pending.forEach { cont -> cont.resumeWithException(ex) }
+        }
+    }
+
+    /**
+     * Convert a [Purchase] into a dictionary matching the `ExpoNamiIapTransaction`
+     * TypeScript type.
+     */
+    internal fun purchaseToDict(
+        purchase: Purchase,
+        productId: String,
+    ): Map<String, Any?> =
+        mapOf(
+            "skuId" to productId,
+            "transactionId" to purchase.orderId,
+            "originalTransactionId" to null,
+            "receipt" to purchase.originalJson,
+            "purchaseToken" to purchase.purchaseToken,
+            "purchaseTime" to purchase.purchaseTime,
+            "isAcknowledged" to purchase.isAcknowledged,
+        )
+
+    // ── Testing ────────────────────────────────────────────────────────
+
+    /**
+     * Inject a [PlayBillingConnection] for testing purposes.
+     * @suppress This method is for testing only.
+     */
+    internal fun setConnectionForTesting(conn: PlayBillingConnection) {
+        connection = conn
+    }
+}