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

package/README.md

@@ -0,0 +1,121 @@
+# @namiml/expo-nami-iap
+
+Thin Expo native module providing cross-platform IAP primitives for the Nami SDK. It wraps platform-specific purchase APIs behind a single TypeScript interface that `@namiml/expo-sdk` consumes via its `ExpoPurchaseAdapter`.
+
+This module is **not intended for standalone use** -- it is an internal dependency of `@namiml/expo-sdk`.
+
+## Supported Platforms
+
+| Platform | Backend |
+|---|---|
+| iOS | StoreKit 2 |
+| Android (Google Play) | Google Play Billing Library 7 |
+| Android (Amazon Fire OS) | Amazon IAP SDK 3.x |
+| Amazon Vega / Kepler | `@amazon-devices/keplerscript-appstore-iap-lib` |
+
+## Public TypeScript API
+
+### Functions
+
+| Function | Signature | Description |
+|---|---|---|
+| `configure` | `(options: ConfigureOptions) => void` | Set module-level options (e.g., Amazon listener mode) |
+| `initConnection` | `() => Promise<void>` | Initialize the native billing client |
+| `endConnection` | `() => Promise<void>` | Tear down the native billing client |
+| `getProducts` | `(skuIds: string[]) => Promise<ExpoNamiIapProduct[]>` | Fetch product details by SKU |
+| `checkEligibility` | `(skuIds: string[]) => Promise<EligibilityResult[]>` | Check intro/promo offer eligibility |
+| `purchase` | `(options: PurchaseOptions) => Promise<ExpoNamiIapTransaction>` | Initiate a purchase |
+| `restorePurchases` | `() => Promise<ExpoNamiIapTransaction[]>` | Restore previously completed purchases |
+| `finishTransaction` | `(transactionId: string) => Promise<void>` | Acknowledge/finish a transaction |
+| `addTransactionListener` | `(cb) => { remove: () => void }` | Subscribe to real-time transaction updates |
+| `addErrorListener` | `(cb) => { remove: () => void }` | Subscribe to error events |
+
+### Types
+
+| Type | Kind | Description |
+|---|---|---|
+| `ExpoNamiIapProduct` | interface | Product details (extends `NamiProductDetails` from sdk-core) |
+| `ExpoNamiIapTransaction` | interface | Transaction result with IDs, receipt, and token |
+| `ExpoNamiIapError` | interface | Error with normalized `code` and `message` |
+| `ExpoNamiIapErrorCode` | union | `'user_cancelled' \| 'network' \| 'item_unavailable' \| 'already_owned' \| 'not_allowed' \| 'unknown'` |
+| `EligibilityResult` | interface | Per-SKU intro/promo eligibility flags |
+| `ConfigureOptions` | interface | Module configuration (Amazon listener mode) |
+| `PurchaseOptions` | interface | Purchase request parameters (SKU, offer, signature) |
+
+## Installation
+
+This module is an internal dependency resolved by Expo autolinking. In `@namiml/expo-sdk`, it is declared as a dependency and automatically linked at prebuild time. No manual installation step is required for consumers of `@namiml/expo-sdk`.
+
+## Android Gradle Flavor Selection
+
+The Android build uses product flavors to select between Google Play and Amazon backends:
+
+```groovy
+flavorDimensions += "store"
+productFlavors {
+    google { dimension "store"; isDefault true }
+    amazon { dimension "store" }
+}
+```
+
+Set the active flavor in your app's `build.gradle` or via `--variant` when running `expo prebuild` / `expo run:android`.
+
+## Amazon Single-Listener Constraint
+
+Amazon IAP SDK enforces a single `PurchasingListener` per process. By default, this module registers its own listener automatically. If your app needs to own the listener (e.g., you have other Amazon IAP integrations), use receiver mode:
+
+```kotlin
+// In your Application.onCreate() — before any Nami calls
+ExpoNamiIapAmazon.setAutoRegisterListener(false)
+
+// Register your own listener and forward events:
+PurchasingService.registerListener(context, object : PurchasingListener {
+    override fun onProductDataResponse(r: ProductDataResponse) {
+        ExpoNamiIapAmazonReceiver.onProductDataResponse(r)
+        // ... your own handling
+    }
+    override fun onPurchaseResponse(r: PurchaseResponse) {
+        ExpoNamiIapAmazonReceiver.onPurchaseResponse(r)
+    }
+    override fun onPurchaseUpdatesResponse(r: PurchaseUpdatesResponse) {
+        ExpoNamiIapAmazonReceiver.onPurchaseUpdatesResponse(r)
+    }
+    override fun onUserDataResponse(r: UserDataResponse) {
+        ExpoNamiIapAmazonReceiver.onUserDataResponse(r)
+    }
+})
+```
+
+## Kepler / Vega Behavior
+
+On Vega (Fire TV with KeplerScript), Metro resolves `ExpoNamiIapModule.kepler.ts` instead of the native module bridge. This implementation is entirely promise-based using `@amazon-devices/keplerscript-appstore-iap-lib`:
+
+- `initConnection` / `endConnection` are no-ops
+- `configure` is a no-op
+- `checkEligibility` returns best-effort results based on existing purchase receipts
+- Prices are returned in micro-units divided by 1,000,000
+
+## Normalized Error Codes
+
+| Code | Meaning |
+|---|---|
+| `user_cancelled` | User dismissed the purchase dialog |
+| `network` | Network connectivity issue |
+| `item_unavailable` | Product not found or not available in region |
+| `already_owned` | User already owns the item (non-consumable) |
+| `not_allowed` | Purchases not allowed on this device/account |
+| `unknown` | Unrecognized native error |
+
+## Testing / Local Dev
+
+From the monorepo root:
+
+```bash
+make build-expo     # Build the Expo SDK (includes this module)
+make test-expo      # Run Jest tests (includes module tests)
+make lint-expo      # Lint TypeScript and Kotlin
+```
+
+## Versioning
+
+This module is versioned in lock-step with the monorepo `VERSION` file. See the [monorepo README](../../../../README.md) for release workflow details.

package/android/build.gradle

@@ -0,0 +1,46 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'expo-module-gradle-plugin'
+
+group = 'ml.nami.expo.iap'
+version = '3.4.0-dev.202605060442'
+
+android {
+    namespace 'ml.nami.expo.iap'
+    compileSdk 34
+
+    defaultConfig {
+        minSdk 24
+        targetSdk 34
+    }
+
+    flavorDimensions += "store"
+    productFlavors {
+        google { dimension "store"; isDefault true }
+        amazon { dimension "store" }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+dependencies {
+    implementation project(':expo-modules-core')
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0'
+
+    googleImplementation 'com.android.billingclient:billing-ktx:7.0.0'
+    // Amazon IAP SDK — the jar is not yet vendored into android/libs/.
+    // The actual SDK will be added (or switched to a Maven coordinate) in Task 18.
+    amazonCompileOnly files('libs/amazon-iap-3.0.3.jar')
+
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation 'org.robolectric:robolectric:4.11.1'
+    testImplementation 'io.mockk:mockk:1.13.9'
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0'
+}

package/android/gradle.properties

@@ -0,0 +1 @@
+# Android module properties for @namiml/expo-nami-iap

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

@@ -0,0 +1,427 @@
+package ml.nami.expo.iap.amazon
+
+import android.app.Activity
+import android.content.Context
+import android.util.Log
+import com.amazon.device.iap.PurchasingService
+import com.amazon.device.iap.model.FulfillmentResult
+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.Receipt
+import kotlinx.coroutines.CancellableContinuation
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import ml.nami.expo.iap.ExpoNamiIapException
+import ml.nami.expo.iap.IapBackend
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * Amazon Fire OS implementation of [IapBackend].
+ *
+ * Uses Amazon's IAP SDK v3 (`PurchasingService`) for product queries,
+ * purchases, restore, eligibility checks, and transaction finishing.
+ * Responses arrive asynchronously via [AmazonPurchasingListener] and are
+ * correlated back to the originating suspend call using request-ID
+ * demultiplexing through pending-request maps.
+ *
+ * **Note:** The Amazon IAP jar (`libs/amazon-iap-3.0.3.jar`) is not yet
+ * vendored into the module. This code will not compile until the jar is
+ * added or replaced with a Maven coordinate. ktlint validation passes.
+ */
+class AmazonIapBackend(
+    internal val scope: CoroutineScope = CoroutineScope(Dispatchers.Default + SupervisorJob()),
+) : IapBackend {
+    private val pendingProductReqs =
+        ConcurrentHashMap<String, CancellableContinuation<List<Map<String, Any?>>>>()
+    private val pendingPurchaseReqs =
+        ConcurrentHashMap<String, CancellableContinuation<Map<String, Any?>>>()
+    private val pendingPurchaseUpdatesReqs =
+        ConcurrentHashMap<String, CancellableContinuation<List<Receipt>>>()
+
+    private var listener: AmazonPurchasingListener? = null
+    private var context: Context? = null
+    private var listenerRegistered = false
+
+    private var transactionListener: ((Map<String, Any?>) -> Unit)? = null
+    private var errorListener: ((Map<String, Any?>) -> Unit)? = null
+
+    // ── Lifecycle ──────────────────────────────────────────────────────
+
+    override suspend fun initConnection(context: Context) {
+        this.context = context
+        ExpoNamiIapAmazon.setBackend(this)
+        ensureListenerRegistered(context)
+    }
+
+    override fun configure(options: Map<String, Any?>) {
+        val amazon = options["amazon"] as? Map<*, *> ?: return
+        val auto = amazon["autoRegisterListener"] as? Boolean ?: true
+        ExpoNamiIapAmazon.setAutoRegisterListener(auto)
+    }
+
+    override suspend fun endConnection() {
+        pendingProductReqs.clear()
+        pendingPurchaseReqs.clear()
+        pendingPurchaseUpdatesReqs.clear()
+        listener = null
+        context = null
+        listenerRegistered = false
+    }
+
+    // ── Products ───────────────────────────────────────────────────────
+
+    override suspend fun getProducts(skuIds: List<String>): List<Map<String, Any?>> {
+        ensureListenerRegistered(
+            context ?: error(
+                "Context not available. Call initConnection() or setContextForTesting() first.",
+            ),
+        )
+
+        return suspendCancellableCoroutine { cont ->
+            val reqId = PurchasingService.getProductData(skuIds.toSet())
+            val key = reqId.toString()
+            pendingProductReqs[key] = cont
+            cont.invokeOnCancellation { pendingProductReqs.remove(key) }
+
+            if (!ExpoNamiIapAmazon.autoRegisterEnabled()) {
+                scope.launch {
+                    delay(TIMEOUT_MS)
+                    pendingProductReqs.remove(key)?.resumeWithException(
+                        ExpoNamiIapException.Unknown(
+                            "Amazon request timed out (receiver mode" +
+                                " — ensure host app calls" +
+                                " ExpoNamiIapAmazonReceiver.onProductDataResponse)",
+                        ),
+                    )
+                }
+            }
+        }
+    }
+
+    // ── Eligibility ────────────────────────────────────────────────────
+
+    /**
+     * Check eligibility for each SKU by querying current purchase receipts.
+     *
+     * For each [skuIds] entry, if an active (non-cancelled) receipt exists,
+     * both `intro_eligible` and `promo_eligible` are false; otherwise both
+     * are true. This is a best-effort approximation — Amazon does not
+     * expose intro/promo offer metadata.
+     */
+    override suspend fun checkEligibility(skuIds: List<String>): List<Map<String, Any?>> {
+        val receipts = fetchPurchaseUpdates()
+
+        // Build a set of active (non-cancelled) SKU IDs
+        val activeSkus =
+            receipts
+                .filter { it.cancelDate == null }
+                .map { it.sku }
+                .toSet()
+
+        return skuIds.map { skuId ->
+            val hasActive = skuId in activeSkus
+            mapOf(
+                "product_ref_id" to skuId,
+                "intro_eligible" to !hasActive,
+                "promo_eligible" to !hasActive,
+            )
+        }
+    }
+
+    // ── Purchase ───────────────────────────────────────────────────────
+
+    /**
+     * Initiate a purchase for the given [skuId].
+     *
+     * Amazon IAP does not support offer selection, offer signatures, or
+     * app account tokens — those parameters are ignored with a debug log.
+     */
+    override suspend fun purchase(
+        activity: Activity,
+        skuId: String,
+        offerId: String?,
+        offerSignature: String?,
+        appAccountToken: String?,
+    ): Map<String, Any?> {
+        ensureListenerRegistered(
+            context ?: error(
+                "Context not available. Call initConnection() or setContextForTesting() first.",
+            ),
+        )
+
+        if (offerId != null || offerSignature != null || appAccountToken != null) {
+            Log.d(
+                TAG,
+                "Amazon IAP ignoring unsupported options: " +
+                    "offerId=$offerId, offerSignature=$offerSignature, " +
+                    "appAccountToken=$appAccountToken",
+            )
+        }
+
+        return suspendCancellableCoroutine { cont ->
+            val reqId = PurchasingService.purchase(skuId)
+            val key = reqId.toString()
+            pendingPurchaseReqs[key] = cont
+            cont.invokeOnCancellation { pendingPurchaseReqs.remove(key) }
+
+            if (!ExpoNamiIapAmazon.autoRegisterEnabled()) {
+                scope.launch {
+                    delay(TIMEOUT_MS)
+                    pendingPurchaseReqs.remove(key)?.resumeWithException(
+                        ExpoNamiIapException.Unknown(
+                            "Amazon request timed out (receiver mode" +
+                                " — ensure host app calls" +
+                                " ExpoNamiIapAmazonReceiver.onPurchaseResponse)",
+                        ),
+                    )
+                }
+            }
+        }
+    }
+
+    // ── Restore ────────────────────────────────────────────────────────
+
+    /**
+     * Restore purchases by fetching all purchase update receipts.
+     *
+     * Each receipt is mapped to a transaction dictionary and emitted
+     * via [transactionListener].
+     */
+    override suspend fun restorePurchases(): List<Map<String, Any?>> {
+        val receipts = fetchPurchaseUpdates()
+        return receipts.map { receipt ->
+            val dict = receiptToDict(receipt)
+            transactionListener?.invoke(dict)
+            dict
+        }
+    }
+
+    // ── Finish ─────────────────────────────────────────────────────────
+
+    /**
+     * Notify Amazon that a transaction has been fulfilled.
+     *
+     * This is fire-and-forget — Amazon IAP does not provide a callback
+     * for `notifyFulfillment`.
+     */
+    override suspend fun finishTransaction(transactionId: String) {
+        PurchasingService.notifyFulfillment(transactionId, FulfillmentResult.FULFILLED)
+    }
+
+    // ── Listeners ──────────────────────────────────────────────────────
+
+    override fun onTransactionUpdate(callback: (Map<String, Any?>) -> Unit) {
+        transactionListener = callback
+    }
+
+    override fun onError(callback: (Map<String, Any?>) -> Unit) {
+        errorListener = callback
+    }
+
+    // ── Response handling (called by AmazonPurchasingListener) ─────────
+
+    /**
+     * Handle a product data response from Amazon IAP.
+     *
+     * Looks up the pending continuation by request ID and resolves it
+     * with the mapped product list, or rejects on failure/not-supported.
+     */
+    internal fun handleProductDataResponse(response: ProductDataResponse) {
+        val cont = pendingProductReqs.remove(response.requestId.toString()) ?: return
+        when (response.requestStatus) {
+            ProductDataResponse.RequestStatus.SUCCESSFUL -> {
+                val products =
+                    response.productData.values.map { AmazonProductMapper.toMap(it) }
+                cont.resume(products)
+            }
+            ProductDataResponse.RequestStatus.FAILED,
+            ProductDataResponse.RequestStatus.NOT_SUPPORTED,
+            -> {
+                cont.resumeWithException(
+                    ExpoNamiIapException.Unknown(
+                        "Product data failed: ${response.requestStatus}",
+                    ),
+                )
+            }
+        }
+    }
+
+    /**
+     * Handle a purchase response from Amazon IAP.
+     *
+     * Resolves or rejects the pending continuation stored in [pendingPurchaseReqs]
+     * based on [PurchaseResponse.RequestStatus].
+     */
+    internal fun handlePurchaseResponse(response: PurchaseResponse) {
+        val cont = pendingPurchaseReqs.remove(response.requestId.toString()) ?: return
+        when (response.requestStatus) {
+            PurchaseResponse.RequestStatus.SUCCESSFUL -> {
+                val receipt = response.receipt
+                val dict = receiptToDict(receipt)
+                transactionListener?.invoke(dict)
+                cont.resume(dict)
+            }
+            PurchaseResponse.RequestStatus.FAILED -> {
+                val ex = ExpoNamiIapException.Unknown("Purchase failed", "FAILED")
+                errorListener?.invoke(exceptionToDict(ex))
+                cont.resumeWithException(ex)
+            }
+            PurchaseResponse.RequestStatus.INVALID_SKU -> {
+                val ex =
+                    ExpoNamiIapException.ItemUnavailable(
+                        "Invalid SKU",
+                        "INVALID_SKU",
+                    )
+                errorListener?.invoke(exceptionToDict(ex))
+                cont.resumeWithException(ex)
+            }
+            PurchaseResponse.RequestStatus.ALREADY_PURCHASED -> {
+                val ex = ExpoNamiIapException.AlreadyOwned("ALREADY_PURCHASED")
+                errorListener?.invoke(exceptionToDict(ex))
+                cont.resumeWithException(ex)
+            }
+            PurchaseResponse.RequestStatus.NOT_SUPPORTED -> {
+                val ex =
+                    ExpoNamiIapException.NotAllowed(
+                        "Purchase not supported",
+                        "NOT_SUPPORTED",
+                    )
+                errorListener?.invoke(exceptionToDict(ex))
+                cont.resumeWithException(ex)
+            }
+        }
+    }
+
+    /**
+     * Handle a purchase updates response from Amazon IAP.
+     *
+     * Resolves the pending continuation in [pendingPurchaseUpdatesReqs]
+     * with the list of [Receipt]s, or rejects on failure.
+     */
+    internal fun handlePurchaseUpdatesResponse(response: PurchaseUpdatesResponse) {
+        val cont = pendingPurchaseUpdatesReqs.remove(response.requestId.toString()) ?: return
+        when (response.requestStatus) {
+            PurchaseUpdatesResponse.RequestStatus.SUCCESSFUL -> {
+                cont.resume(response.receipts ?: emptyList())
+            }
+            PurchaseUpdatesResponse.RequestStatus.FAILED,
+            PurchaseUpdatesResponse.RequestStatus.NOT_SUPPORTED,
+            -> {
+                cont.resumeWithException(
+                    ExpoNamiIapException.Unknown(
+                        "Purchase updates failed: ${response.requestStatus}",
+                    ),
+                )
+            }
+        }
+    }
+
+    // ── Internals ──────────────────────────────────────────────────────
+
+    /**
+     * Ensure the [AmazonPurchasingListener] is registered with
+     * `PurchasingService`. This is idempotent — Amazon's SDK uses a
+     * last-writer-wins model, so repeated calls are safe.
+     *
+     * In receiver mode ([ExpoNamiIapAmazon.autoRegisterEnabled] == false),
+     * listener registration is skipped. The host app is responsible for
+     * calling `PurchasingService.registerListener` and forwarding events
+     * via [ExpoNamiIapAmazonReceiver].
+     */
+    private fun ensureListenerRegistered(ctx: Context) {
+        if (listenerRegistered) return
+        if (!ExpoNamiIapAmazon.autoRegisterEnabled()) {
+            listenerRegistered = true
+            return
+        }
+        val newListener = AmazonPurchasingListener(this)
+        PurchasingService.registerListener(ctx, newListener)
+        listener = newListener
+        listenerRegistered = true
+    }
+
+    /**
+     * Fetch purchase update receipts via `PurchasingService.getPurchaseUpdates(false)`.
+     *
+     * Used by both [restorePurchases] and [checkEligibility].
+     */
+    private suspend fun fetchPurchaseUpdates(): List<Receipt> {
+        ensureListenerRegistered(
+            context ?: error(
+                "Context not available. Call initConnection() or setContextForTesting() first.",
+            ),
+        )
+
+        return suspendCancellableCoroutine { cont ->
+            val reqId = PurchasingService.getPurchaseUpdates(false)
+            val key = reqId.toString()
+            pendingPurchaseUpdatesReqs[key] = cont
+            cont.invokeOnCancellation { pendingPurchaseUpdatesReqs.remove(key) }
+
+            if (!ExpoNamiIapAmazon.autoRegisterEnabled()) {
+                scope.launch {
+                    delay(TIMEOUT_MS)
+                    pendingPurchaseUpdatesReqs.remove(key)?.resumeWithException(
+                        ExpoNamiIapException.Unknown(
+                            "Amazon request timed out (receiver mode" +
+                                " — ensure host app calls" +
+                                " ExpoNamiIapAmazonReceiver" +
+                                ".onPurchaseUpdatesResponse)",
+                        ),
+                    )
+                }
+            }
+        }
+    }
+
+    /**
+     * Convert an Amazon IAP [Receipt] into a dictionary matching the
+     * `ExpoNamiIapTransaction` TypeScript type.
+     *
+     * Amazon does not distinguish `transactionId` from `originalTransactionId`,
+     * so both are set to [Receipt.getReceiptId].
+     */
+    internal fun receiptToDict(receipt: Receipt): Map<String, Any?> =
+        mapOf(
+            "skuId" to receipt.sku,
+            "transactionId" to receipt.receiptId,
+            "originalTransactionId" to receipt.receiptId,
+            "receipt" to receipt.receiptId,
+            "purchaseToken" to receipt.receiptId,
+            "purchaseTime" to receipt.purchaseDate?.time,
+        )
+
+    /**
+     * Convert an [ExpoNamiIapException] to an error dictionary for listener dispatch.
+     */
+    private fun exceptionToDict(ex: ExpoNamiIapException): Map<String, Any?> =
+        mapOf(
+            "code" to ex.code,
+            "message" to ex.message,
+            "nativeCode" to ex.nativeCode,
+        )
+
+    // ── Testing ────────────────────────────────────────────────────────
+
+    /**
+     * Set a [Context] for testing purposes without calling [initConnection].
+     * This allows testing auto-registration in [getProducts] without a
+     * prior [initConnection] call.
+     * @suppress This method is for testing only.
+     */
+    internal fun setContextForTesting(ctx: Context) {
+        this.context = ctx
+    }
+
+    companion object {
+        private const val TAG = "AmazonIapBackend"
+        internal const val TIMEOUT_MS = 30_000L
+    }
+}