@billdog.io/react-native 1.0.0-beta.2

package/android/src/main/kotlin/io/billdog/reactnative/BillDogModule.kt

@@ -0,0 +1,817 @@
+package io.billdog.reactnative
+
+import android.app.Activity
+import android.net.Uri
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import io.billdog.core.BillDog
+import io.billdog.core.BillDogError
+import io.billdog.core.InterfaceStyle
+import io.billdog.core.PresentationResult
+import io.billdog.core.PurchaseResult
+import io.billdog.core.RestoreResult
+import io.billdog.core.models.CustomerInfo
+import io.billdog.core.models.EntitlementInfo
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * BillDog — core React Native native module for Android (`NativeModules.BillDog`).
+ *
+ * Thin bridge: every `@ReactMethod` here delegates to the native BillDog Android
+ * SDK (`io.billdog.core.BillDog`, a Kotlin `object`) rather than reimplementing
+ * logic in JS. The authoritative JS contract is `src/BillDog.ts`; each
+ * `native.<method>(...)` call there maps to the identically-named method below.
+ *
+ * ⚠️ VERIFICATION: this file cannot be compiled in this environment — there is
+ * no Android/Gradle toolchain present. It needs a Gradle/Android build
+ * (`./gradlew :billdog_react-native:compileDebugKotlin` or the example app
+ * build) to type-check against the resolved `io.billdog:billdog-core` +
+ * kotlinx-coroutines artifacts declared in android/build.gradle. Every native
+ * symbol below is cited to its source file:line in billdog-core.
+ *
+ * Activity acquisition: unlike the Flutter plugin (ActivityAware), the current
+ * Activity is read from `currentActivity` (ReactContextBaseJavaModule). For the
+ * Activity-required calls (registerPlacement, showManageSubscriptions,
+ * showInAppMessages) a null currentActivity rejects with "NO_ACTIVITY".
+ */
+class BillDogModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    private val TAG = "BillDog"
+
+    /** Suspend calls are launched here; cancelled in invalidate()/onCatalystInstanceDestroy(). */
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+
+    /** Guards registerOptionalModules() — `BillDog.use()` does not de-dupe. */
+    private val modulesRegistered = AtomicBoolean(false)
+
+    /**
+     * PUR-364: JS-side PurchaseController active flag. Full JS-PurchaseController
+     * bridging (routing native purchase() through a JS-driven EXTERNAL flow) is
+     * DEFERRED — for now we only remember whether the JS facade has a host
+     * controller registered. When true, the JS facade drives the transaction
+     * itself and never calls native.purchase(), so this is purely informational.
+     */
+    @Volatile
+    private var purchaseControllerActive: Boolean = false
+
+    override fun getName(): String = "BillDog"
+
+    // ── Lifecycle ──────────────────────────────────────────────────────────
+
+    override fun invalidate() {
+        scope.cancel()
+        super.invalidate()
+    }
+
+    @Deprecated("Deprecated in RN; kept for older RN versions that call it instead of invalidate()")
+    override fun onCatalystInstanceDestroy() {
+        scope.cancel()
+        @Suppress("DEPRECATION")
+        super.onCatalystInstanceDestroy()
+    }
+
+    // ── Coroutine helpers ──────────────────────────────────────────────────
+    // Launched on Dispatchers.Main so the suspend body resumes on the main
+    // thread and promise.resolve/reject are invoked there.
+
+    /** Run a suspend [block] that produces a resolve value; map any throwable → promise.reject. */
+    private fun launch(promise: Promise, block: suspend () -> Any?) {
+        scope.launch {
+            try {
+                promise.resolve(block())
+            } catch (e: Throwable) {
+                promise.reject("BILLDOG_ERROR", e.message, e)
+            }
+        }
+    }
+
+    // ── Configuration ──────────────────────────────────────────────────────
+
+    /**
+     * native.configure(apiKey, options) → BillDog.configure(context, apiKey, config)
+     * (BillDog.kt:263). This is what makes the native SDK usable — without it the
+     * native singleton is unconfigured and every delegating call fails. The RN
+     * `Context` comes from `reactContext.applicationContext`.
+     */
+    @ReactMethod
+    fun configure(apiKey: String, options: ReadableMap?, promise: Promise) {
+        try {
+            val enableLogging =
+                options?.let { if (it.hasKey("enableLogging")) it.getBoolean("enableLogging") else true } ?: true
+            val config = io.billdog.core.BillDogConfig(apiKey = apiKey, enableLogging = enableLogging)
+            BillDog.configure(reactApplicationContext.applicationContext, apiKey, config)
+            registerOptionalModules()
+            promise.resolve(true)
+        } catch (e: Throwable) {
+            promise.reject("CONFIGURE_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Register the optional native submodules with the core SDK.
+     *
+     * WHY THIS EXISTS: billdog-core keeps an OPT-IN module registry —
+     * `BillDog.use(module)` (BillDog.kt:415) is the only way to populate it, and
+     * `BillDog.configure()` does NOT auto-register anything. Every bridge module
+     * here resolves its manager per-call out of `BillDog.getModules()`
+     * (BillDog.kt:427), so with an empty registry `BillDogAnalyticsModule` /
+     * `BillDogABTestModule` resolve `null` and silently NO-OP: `track()` reports
+     * success while `BillDog.trackEvent` drops the event at
+     * `findAnalyticsModule()?.track(event)` (BillDog.kt:948), and `getDistinctId()`
+     * returns JS `null` even though the Kotlin signature is non-nullable `String`.
+     * Verified 2026-07-21 on-device: the RN harness emitted events that NEVER
+     * reached ClickHouse.
+     *
+     * A native Kotlin host does this itself (see the Android Inspector's
+     * BillDogBootstrap.kt:145-165) — but an RN app has no Kotlin bootstrap, so the
+     * bridge IS the host and must do it here. Mirrors that reference sequence.
+     *
+     * Idempotent: `use()` is a bare `registeredModules.add()` with NO de-dupe, so
+     * a second configure() would register a second analytics module and every
+     * event would be sent twice.
+     */
+    private fun registerOptionalModules() {
+        if (!modulesRegistered.compareAndSet(false, true)) return
+        val app = reactApplicationContext.applicationContext as? android.app.Application
+        try {
+            // Analytics. `use()` injects the network client + config, but the event
+            // QUEUE is installed separately: track() ends in `val db = database ?:
+            // return@launch` (BillDogAnalytics.kt:690) and `database` is only set by
+            // initializeAutoTracking(). Registering without this call still drops
+            // every event, so both steps are REQUIRED.
+            val analytics = io.billdog.analytics.BillDogAnalytics()
+            BillDog.use(analytics)
+            if (app != null) {
+                analytics.initializeAutoTracking(app)
+            } else {
+                Log.w(TAG, "No Application context — analytics persistence disabled; events will not queue")
+            }
+
+            // A/B test manager — BillDogABTestModule resolves this out of the registry.
+            BillDog.use(io.billdog.abtest.BillDogABTest(reactApplicationContext.applicationContext))
+        } catch (e: Throwable) {
+            // Never fail configure() because an optional module is absent from the
+            // host's classpath — the corresponding bridge just keeps no-oping.
+            modulesRegistered.set(false)
+            Log.w(TAG, "Optional module registration failed: ${e.message}", e)
+        }
+    }
+
+    // ── PUR-350 / PUR-364 — Unified purchase API ───────────────────────────
+
+    /**
+     * native.purchase({ ...params, source }) — JS passes a PurchaseParams object.
+     * We route on `productId`. Delegates to BillDog.purchase(activity, productId)
+     * — BillDog.kt:700 (suspend). Custom-product / package overloads and full
+     * PurchaseController EXTERNAL bridging are DEFERRED (see purchaseControllerActive).
+     */
+    @ReactMethod
+    fun purchase(params: ReadableMap, promise: Promise) {
+        val productId = if (params.hasKey("productId")) params.getString("productId") else null
+        if (productId.isNullOrBlank()) {
+            promise.reject("INVALID_ARGS", "Missing productId", null)
+            return
+        }
+        val activity: Activity? = currentActivity
+        launch(promise) {
+            // Activity-less overload (BillDog.kt:680) is available but only the
+            // Activity-aware entry point (BillDog.kt:700) can launch the Play
+            // billing sheet; fall back to it when no Activity is attached.
+            val result = if (activity != null) {
+                BillDog.purchase(activity, productId)
+            } else {
+                BillDog.purchase(productId)
+            }
+            serializePurchaseResult(result)
+        }
+    }
+
+    /**
+     * native.setPurchaseControllerActive(active) — no native equivalent.
+     * Stores the flag; full JS-PurchaseController bridging is DEFERRED.
+     */
+    @ReactMethod
+    fun setPurchaseControllerActive(active: Boolean, promise: Promise) {
+        purchaseControllerActive = active
+        Log.d(TAG, "setPurchaseControllerActive($active) — flag stored; JS-controller bridging deferred")
+        promise.resolve(null)
+    }
+
+    /** native.restore() → BillDog.restorePurchases() — BillDog.kt:822 (suspend). */
+    @ReactMethod
+    fun restore(promise: Promise) {
+        launch(promise) { serializeRestoreResult(BillDog.restorePurchases()) }
+    }
+
+    // ── PUR-141/224 — CustomerInfo ─────────────────────────────────────────
+
+    /**
+     * native.getCustomerInfo(policy) → BillDog.getCustomerInfo(forceRefresh)
+     * — BillDog.kt:902 (suspend, Result<CustomerInfo>). Only "FETCH_CURRENT"
+     * maps to forceRefresh=true (mirrors the Flutter plugin).
+     */
+    @ReactMethod
+    fun getCustomerInfo(policy: String?, promise: Promise) {
+        val forceRefresh = policy == "FETCH_CURRENT"
+        launch(promise) {
+            val info = BillDog.getCustomerInfo(forceRefresh).getOrElse { throw it }
+            serializeCustomerInfo(info)
+        }
+    }
+
+    /** native.invalidateCustomerInfoCache() → BillDog.invalidateCustomerInfoCache() — BillDog.kt:2516 (suspend). */
+    @ReactMethod
+    fun invalidateCustomerInfoCache(promise: Promise) {
+        launch(promise) { BillDog.invalidateCustomerInfoCache(); null }
+    }
+
+    /** native.clearCache() → BillDog.clearCache() — BillDog.kt:1490. */
+    @ReactMethod
+    fun clearCache(promise: Promise) {
+        try {
+            BillDog.clearCache()
+            promise.resolve(null)
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    // ── Store capability surface ────────────────────────────────────────────
+
+    /** native.canMakePayments() → BillDog.canMakePayments() — BillDog.kt:1296 (Boolean). */
+    @ReactMethod
+    fun canMakePayments(promise: Promise) {
+        try {
+            promise.resolve(BillDog.canMakePayments())
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * native.presentCodeRedemptionSheet() — NO Android equivalent (iOS-only App
+     * Store promo-code sheet). Resolve null (documented no-op).
+     */
+    @ReactMethod
+    fun presentCodeRedemptionSheet(promise: Promise) {
+        Log.d(TAG, "presentCodeRedemptionSheet() — iOS-only; no Android equivalent; no-op")
+        promise.resolve(null)
+    }
+
+    /**
+     * native.checkTrialOrIntroDiscountEligibility(productIds) — NO native
+     * equivalent in billdog-core (no matching method). Resolve a map of
+     * productId → "unknown" (mirrors the JS fallback shape).
+     */
+    @ReactMethod
+    fun checkTrialOrIntroDiscountEligibility(productIds: ReadableArray, promise: Promise) {
+        val out = Arguments.createMap()
+        for (i in 0 until productIds.size()) {
+            productIds.getString(i)?.let { out.putString(it, "unknown") }
+        }
+        Log.d(TAG, "checkTrialOrIntroDiscountEligibility — no native equivalent; returning 'unknown'")
+        promise.resolve(out)
+    }
+
+    /**
+     * native.subscribeStorefront() — NO native equivalent (iOS-only storefront
+     * country observer; Play exposes no country API). Documented no-op.
+     */
+    @ReactMethod
+    fun subscribeStorefront(promise: Promise) {
+        Log.d(TAG, "subscribeStorefront() — iOS-only; no Android equivalent; no-op")
+        promise.resolve(null)
+    }
+
+    // ── PUR-362 — Self-hosted proxy ─────────────────────────────────────────
+
+    /** native.setProxyURL(url) → BillDog.setProxyURL(url) — BillDog.kt:1349. */
+    @ReactMethod
+    fun setProxyURL(url: String?, promise: Promise) {
+        BillDog.setProxyURL(url)
+        promise.resolve(null)
+    }
+
+    /**
+     * native.getProxyURL() → BillDog.getProxyURL() — BillDog.kt:1355 (String?).
+     * BillDog.ts reads this synchronously (`native.getProxyURL() ?? null`), so it must be a
+     * blocking-synchronous method (a Promise would return a truthy object, never the value).
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun getProxyURL(): String? = BillDog.getProxyURL()
+
+    // ── Consent (cross-SDK contract) ────────────────────────────────────────
+
+    /** native.setConsentRequired(required) → BillDog.setConsentRequired(required) — BillDog.kt:1485. */
+    @ReactMethod
+    fun setConsentRequired(required: Boolean, promise: Promise) {
+        BillDog.setConsentRequired(required)
+        promise.resolve(null)
+    }
+
+    /**
+     * native.setConsent(purpose, granted) — NO per-purpose native equivalent;
+     * billdog-core only exposes the global setConsentGiven (BillDog.kt:1486).
+     * Forward as the global toggle when granted for any purpose is set, else
+     * log. Documented mapping limitation; resolve null.
+     */
+    @ReactMethod
+    fun setConsent(purpose: String?, granted: Boolean, promise: Promise) {
+        // billdog-core has no per-purpose consent API; the closest primitive is
+        // the global consent flag. We do NOT collapse per-purpose into global to
+        // avoid over-granting — this is a documented no-op pending a native
+        // per-purpose ConsentManager API.
+        Log.d(TAG, "setConsent(purpose=$purpose, granted=$granted) — no per-purpose native API; no-op")
+        promise.resolve(null)
+    }
+
+    /** native.setConsentGiven(given) → BillDog.setConsentGiven(given) — BillDog.kt:1486. */
+    @ReactMethod
+    fun setConsentGiven(given: Boolean, promise: Promise) {
+        BillDog.setConsentGiven(given)
+        promise.resolve(null)
+    }
+
+    /**
+     * native.consentHeaderValue() — NO native accessor in billdog-core (consent
+     * state is applied to requests internally, not exposed as a header string).
+     * Resolve null (documented no-op).
+     */
+    @ReactMethod
+    fun consentHeaderValue(promise: Promise) {
+        Log.d(TAG, "consentHeaderValue() — no native accessor; returning null")
+        promise.resolve(null)
+    }
+
+    // ── PUR-360 — attribution / device identifiers ──────────────────────────
+
+    /**
+     * native.collectDeviceIdentifiers() → BillDog.collectDeviceIdentifiers()
+     * — BillDog.kt:1367 (suspend, returns DeviceIdentifiers). JS treats it as
+     * void; we resolve null on completion.
+     */
+    @ReactMethod
+    fun collectDeviceIdentifiers(promise: Promise) {
+        launch(promise) { BillDog.collectDeviceIdentifiers(); null }
+    }
+
+    /**
+     * native.setAttribution({ key: id, … }) → the matching native provider setter
+     * (BillDog.kt:2646+). Keys are provider attribution keys; each maps 1:1 to a
+     * consent-gated native setter. Unknown keys are ignored. The JS facade's
+     * named setters (setMixpanelDistinctID etc.) all funnel through here.
+     */
+    @ReactMethod
+    fun setAttribution(data: ReadableMap, promise: Promise) {
+        launch(promise) {
+            val it = data.keySetIterator()
+            while (it.hasNextKey()) {
+                val key = it.nextKey()
+                val value = data.getString(key) ?: continue
+                when (key) {
+                    "cleverTapId" -> BillDog.setCleverTapID(value)
+                    "mixpanelDistinctId" -> BillDog.setMixpanelDistinctID(value)
+                    "onesignalId" -> BillDog.setOnesignalID(value)
+                    "fbAnonymousId" -> BillDog.setFBAnonymousID(value)
+                    "airshipChannelId" -> BillDog.setAirshipChannelID(value)
+                    "moEngageAnonymousId" -> BillDog.setMoEngageAnonymousID(value)
+                    "mparticleId" -> BillDog.setMparticleID(value)
+                    "kochavaId" -> BillDog.setKochavaDeviceID(value)
+                    "tenjinId" -> BillDog.setTenjinAnalyticsInstallationID(value)
+                    "iterableId" -> BillDog.setIterableUserID(value)
+                    "segmentId" -> BillDog.setSegmentAnonymousID(value)
+                    // MMP providers — dedicated native setters.
+                    "adjustId" -> BillDog.setAdjustId(value)
+                    "appsflyerId" -> BillDog.setAppsflyerId(value)
+                    "firebaseAppInstanceId" -> BillDog.setFirebaseAppInstanceId(value)
+                    else -> { /* unknown provider key — ignore */ }
+                }
+            }
+            null
+        }
+    }
+
+    // ── Identity API ────────────────────────────────────────────────────────
+
+    /** native.logIn(appUserId) → BillDog.logIn(appUserId) — BillDog.kt:1169 (suspend, Result<LogInResult>). */
+    @ReactMethod
+    fun logIn(appUserId: String, promise: Promise) {
+        launch(promise) {
+            BillDog.logIn(appUserId).exceptionOrNull()?.let { throw it }
+            null
+        }
+    }
+
+    /** native.logOut() → BillDog.logOut() — BillDog.kt:1209. */
+    @ReactMethod
+    fun logOut(promise: Promise) {
+        try {
+            BillDog.logOut()
+            promise.resolve(null)
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * native.setSandboxMode(enabled) — NO native setter. Sandbox is derived from
+     * the API-key prefix (bd_public_test_* / bd_secret_test_*); documented no-op.
+     */
+    @ReactMethod
+    fun setSandboxMode(enabled: Boolean, promise: Promise) {
+        Log.d(TAG, "setSandboxMode($enabled) — no native setter (sandbox tracked by API-key prefix); no-op")
+        promise.resolve(null)
+    }
+
+    // ── Placement registration ──────────────────────────────────────────────
+
+    /**
+     * native.registerPlacement({ placementId, params }) → BillDog.register(
+     * placementId, activity, params, handler) — BillDog.kt:1377 (suspend).
+     * Requires an Activity; rejects "NO_ACTIVITY" when currentActivity is null.
+     */
+    @ReactMethod
+    fun registerPlacement(args: ReadableMap, promise: Promise) {
+        val placementId = if (args.hasKey("placementId")) args.getString("placementId") else null
+        if (placementId.isNullOrBlank()) {
+            promise.reject("INVALID_ARGS", "Missing placementId", null)
+            return
+        }
+        val activity = currentActivity
+            ?: return promise.reject("NO_ACTIVITY", "No Activity available for registerPlacement", null)
+
+        @Suppress("UNCHECKED_CAST")
+        val params: Map<String, Any>? =
+            if (args.hasKey("params")) args.getMap("params")?.toHashMap() as? Map<String, Any> else null
+
+        val replied = AtomicBoolean(false)
+        scope.launch {
+            try {
+                BillDog.register(placementId, activity, params) { placementResult ->
+                    if (replied.compareAndSet(false, true)) {
+                        promise.resolve(serializePlacementResult(placementResult))
+                    }
+                }
+            } catch (e: Throwable) {
+                if (replied.compareAndSet(false, true)) {
+                    promise.reject("BILLDOG_ERROR", e.message, e)
+                }
+            }
+        }
+    }
+
+    /**
+     * native.hasAccessForPlacement(placementId) → BillDog.hasAccessForPlacement — BillDog.kt:1440 (Boolean).
+     * BillDog.ts reads this synchronously (`!!native.hasAccessForPlacement(id)`), so it must be
+     * blocking-synchronous. On error, default false (JS treats a thrown/false as "no access").
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun hasAccessForPlacement(placementId: String): Boolean =
+        try { BillDog.hasAccessForPlacement(placementId) } catch (e: Throwable) { false }
+
+    /**
+     * native.getPresentationResult(placementId) → BillDog.getPresentationResult(
+     * placementId) — BillDog.kt:2842 (suspend).
+     */
+    @ReactMethod
+    fun getPresentationResult(placementId: String, promise: Promise) {
+        launch(promise) { serializePresentationResult(BillDog.getPresentationResult(placementId)) }
+    }
+
+    // Experiments & feature flags: the paywall-facade shim was removed. Use the
+    // standalone BillDogABTest module (bridged separately) instead.
+
+    // ── In-app messages ─────────────────────────────────────────────────────
+
+    /**
+     * native.showInAppMessages(placementId?) → BillDog.showInAppMessages(activity)
+     * — BillDog.kt:2873. Native has no placement param; placementId is ignored.
+     * Requires an Activity → reject "NO_ACTIVITY" when null.
+     */
+    @ReactMethod
+    fun showInAppMessages(placementId: String?, promise: Promise) {
+        val activity = currentActivity
+            ?: return promise.reject("NO_ACTIVITY", "No Activity available for showInAppMessages", null)
+        try {
+            BillDog.showInAppMessages(activity)
+            promise.resolve(null)
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    // ── Deep linking ────────────────────────────────────────────────────────
+
+    /**
+     * native.handleDeepLink(uri) → BillDog.handleDeepLink(Uri.parse(uri))
+     * — BillDog.kt:883 (returns DeepLinkResult?). Resolve true when handled.
+     */
+    @ReactMethod
+    fun handleDeepLink(uri: String, promise: Promise) {
+        val handled = try {
+            BillDog.handleDeepLink(Uri.parse(uri)) != null
+        } catch (e: Exception) {
+            Log.w(TAG, "handleDeepLink failed: ${e.message}")
+            false
+        }
+        promise.resolve(handled)
+    }
+
+    // ── Component selection state ───────────────────────────────────────────
+
+    /**
+     * native.getSelectedProductIndex(componentId) → BillDog.getSelectedProductIndex — BillDog.kt:1448 (Int?).
+     * BillDog.ts reads this synchronously, so it must be blocking-synchronous.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun getSelectedProductIndex(componentId: String): Int? =
+        BillDog.getSelectedProductIndex(componentId)
+
+    /** native.setSelectedProductIndex(componentId, index) → BillDog.setSelectedProductIndex(componentId, index) — BillDog.kt:1454. */
+    @ReactMethod
+    fun setSelectedProductIndex(componentId: String, index: Int, promise: Promise) {
+        BillDog.setSelectedProductIndex(componentId, index)
+        promise.resolve(null)
+    }
+
+    // ── Theme / interface style ─────────────────────────────────────────────
+
+    /** native.updateTheme(overrides) → BillDog.updateTheme(overrides) — BillDog.kt:212. */
+    @ReactMethod
+    fun updateTheme(overrides: ReadableMap, promise: Promise) {
+        val map = overrides.toHashMap().entries
+            .filter { it.value != null }
+            .associate { it.key to it.value.toString() }
+        BillDog.updateTheme(map)
+        promise.resolve(null)
+    }
+
+    /** native.setInterfaceStyle(style) → BillDog.setInterfaceStyle(InterfaceStyle?) — BillDog.kt:2604. null = follow system. */
+    @ReactMethod
+    fun setInterfaceStyle(style: String?, promise: Promise) {
+        BillDog.setInterfaceStyle(parseInterfaceStyle(style))
+        promise.resolve(null)
+    }
+
+    // ── Subscription management ─────────────────────────────────────────────
+
+    /**
+     * native.showManageSubscriptions(subscriptionId?) → BillDog.showManageSubscriptions(
+     * activity, subscriptionId) — BillDog.kt:2035. Requires an Activity → reject
+     * "NO_ACTIVITY" when null.
+     */
+    @ReactMethod
+    fun showManageSubscriptions(subscriptionId: String?, promise: Promise) {
+        val activity = currentActivity
+            ?: return promise.reject("NO_ACTIVITY", "No Activity available for showManageSubscriptions", null)
+        try {
+            BillDog.showManageSubscriptions(activity, subscriptionId)
+            promise.resolve(null)
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    // ── User attributes ─────────────────────────────────────────────────────
+
+    /** native.setUserAttributes(attributes) → BillDog.setUserAttributes(attributes) — BillDog.kt:2618 (suspend, Result<Unit>). */
+    @ReactMethod
+    fun setUserAttributes(attributes: ReadableMap, promise: Promise) {
+        val map: Map<String, Any?> = attributes.toHashMap()
+        launch(promise) {
+            BillDog.setUserAttributes(map).exceptionOrNull()?.let { throw it }
+            null
+        }
+    }
+
+    /** native.getUserAttributes() → BillDog.getUserAttributes() — BillDog.kt:2633 (Map<String, Any>). */
+    @ReactMethod
+    fun getUserAttributes(promise: Promise) {
+        try {
+            promise.resolve(toWritableMap(BillDog.getUserAttributes()))
+        } catch (e: Throwable) {
+            promise.reject("BILLDOG_ERROR", e.message, e)
+        }
+    }
+
+    // ── External purchase observation ───────────────────────────────────────
+
+    /** native.observePurchaseStart(productId) → BillDog.observePurchaseStart(productId) — BillDog.kt:2768. */
+    @ReactMethod
+    fun observePurchaseStart(productId: String, promise: Promise) {
+        BillDog.observePurchaseStart(productId)
+        promise.resolve(null)
+    }
+
+    /** native.observePurchaseResult(productId, orderId?) → BillDog.observePurchaseResult(productId, orderId) — BillDog.kt:2774. */
+    @ReactMethod
+    fun observePurchaseResult(productId: String, orderId: String?, promise: Promise) {
+        BillDog.observePurchaseResult(productId, orderId)
+        promise.resolve(null)
+    }
+
+    /** native.observePurchaseError(productId, error) → BillDog.observePurchaseError(productId, error) — BillDog.kt:2782. */
+    @ReactMethod
+    fun observePurchaseError(productId: String, error: String, promise: Promise) {
+        BillDog.observePurchaseError(productId, error)
+        promise.resolve(null)
+    }
+
+    // ── Server-side tap actions ─────────────────────────────────────────────
+
+    /**
+     * native.executeAction(paywallId, componentId, actionType, idempotencyKey,
+     * metadata) — NO native equivalent in billdog-core (Route B tap-action
+     * execution has no exposed SDK method). The JS facade already has a direct
+     * fetch fallback to the `execute-paywall-action` Edge Function when native is
+     * absent, so we resolve null here to signal "no native handler" and let the
+     * JS fallback path run. Documented no-op (does NOT reject).
+     */
+    @ReactMethod
+    fun executeAction(
+        paywallId: String?,
+        componentId: String,
+        actionType: String,
+        idempotencyKey: String?,
+        metadata: ReadableMap?,
+        promise: Promise
+    ) {
+        Log.d(TAG, "executeAction($actionType) — no native SDK method; resolving null (JS fetch fallback handles it)")
+        promise.resolve(null)
+    }
+
+    // ── Serializers (shapes match the JS *.ts result unions) ────────────────
+
+    /**
+     * PurchaseResult (PurchaseResult.kt:28) → JS PurchaseResult union.
+     * type ∈ purchased | cancelled | pending | failed | restored.
+     */
+    private fun serializePurchaseResult(r: PurchaseResult): WritableMap = when (r) {
+        is PurchaseResult.Purchased -> toWritableMap(mapOf(
+            "type" to "purchased",
+            "productId" to r.productId,
+            "transactionId" to r.transactionId,
+            "originalTransactionId" to r.originalTransactionId
+        ))
+        is PurchaseResult.Cancelled -> toWritableMap(mapOf("type" to "cancelled"))
+        is PurchaseResult.Pending -> toWritableMap(mapOf("type" to "pending"))
+        is PurchaseResult.Failed -> toWritableMap(mapOf(
+            "type" to "failed",
+            "error" to mapOf(
+                "category" to r.error.category,
+                "message" to r.error.message
+            )
+        ))
+        is PurchaseResult.Restored -> toWritableMap(mapOf(
+            "type" to "restored",
+            "productId" to r.productId,
+            "transactionId" to r.transactionId,
+            "originalTransactionId" to r.originalTransactionId
+        ))
+    }
+
+    /** RestoreResult (PurchaseResult.kt:60) → JS RestoreResult union. */
+    private fun serializeRestoreResult(r: RestoreResult): WritableMap = when (r) {
+        is RestoreResult.Restored -> toWritableMap(mapOf(
+            "type" to "restored",
+            "items" to r.items.map {
+                mapOf(
+                    "productId" to it.productId,
+                    "transactionId" to it.transactionId,
+                    "originalTransactionId" to it.originalTransactionId
+                )
+            }
+        ))
+        is RestoreResult.Failed -> toWritableMap(mapOf(
+            "type" to "failed",
+            "error" to mapOf(
+                "category" to r.error.category,
+                "message" to r.error.message
+            )
+        ))
+    }
+
+    /** PlacementResult (PlacementManager.kt) → JS PlacementResult union. */
+    private fun serializePlacementResult(r: io.billdog.managers.PlacementResult): WritableMap = when (r) {
+        is io.billdog.managers.PlacementResult.Entitled -> toWritableMap(mapOf("type" to "entitled"))
+        is io.billdog.managers.PlacementResult.Purchased ->
+            toWritableMap(mapOf("type" to "purchased", "productId" to r.productId))
+        is io.billdog.managers.PlacementResult.Dismissed -> toWritableMap(mapOf("type" to "dismissed"))
+        is io.billdog.managers.PlacementResult.Restored -> toWritableMap(mapOf("type" to "restored"))
+        is io.billdog.managers.PlacementResult.Error ->
+            toWritableMap(mapOf("type" to "error", "message" to (r.exception.message ?: "Placement error")))
+    }
+
+    /** PresentationResult (BillDog.kt) → JS PresentationResult union. */
+    private fun serializePresentationResult(r: PresentationResult): WritableMap = when (r) {
+        is PresentationResult.Paywall -> toWritableMap(mapOf("type" to "paywall"))
+        is PresentationResult.UserSubscribed -> toWritableMap(mapOf("type" to "userSubscribed"))
+        is PresentationResult.NoPaywall -> toWritableMap(mapOf("type" to "noPaywall", "reason" to r.reason))
+        is PresentationResult.Holdout -> toWritableMap(mapOf("type" to "holdout"))
+        is PresentationResult.Error -> toWritableMap(mapOf("type" to "error", "message" to r.message))
+    }
+
+    /** EntitlementInfo (CustomerModels.kt) → JS EntitlementInfo. */
+    private fun serializeEntitlement(e: EntitlementInfo): Map<String, Any?> = mapOf(
+        "identifier" to e.identifier,
+        "isActive" to e.isActive,
+        "expiresAt" to e.expiresAt,
+        "store" to e.store,
+        "grantedAt" to e.grantedAt,
+        "willRenew" to e.willRenew,
+        "isLifetime" to e.isLifetime,
+        "state" to e.state,
+        "productIds" to e.productIds,
+        "startsAt" to e.startsAt,
+        "renewedAt" to e.renewedAt,
+        "latestProductId" to e.latestProductId
+    )
+
+    /**
+     * CustomerInfo (CustomerModels.kt) → JS CustomerInfo. `subscriptions` is
+     * emitted EMPTY — native activeSubscriptions is only a List<String> of ids
+     * with no per-subscription dates (mirrors the Flutter plugin limitation);
+     * active state is carried by `entitlements`.
+     */
+    private fun serializeCustomerInfo(info: CustomerInfo): WritableMap = toWritableMap(mapOf(
+        "userId" to info.userId,
+        "originalAppUserId" to info.originalAppUserId,
+        "entitlements" to info.entitlements.map { serializeEntitlement(it) },
+        "subscriptions" to emptyList<Any?>(),
+        "productEntitlementMapping" to info.productEntitlementMapping
+    ))
+
+    // ── Parsers ──────────────────────────────────────────────────────────────
+
+    private fun parseInterfaceStyle(value: String?): InterfaceStyle? =
+        when (value?.lowercase()) {
+            "light" -> InterfaceStyle.LIGHT
+            "dark" -> InterfaceStyle.DARK
+            "system" -> InterfaceStyle.SYSTEM
+            else -> null
+        }
+
+    // ── Map<String, Any?> → WritableMap converter ────────────────────────────
+    // RN's Writable* types are the only values the bridge can send to JS. This
+    // recursively converts plain Kotlin maps/lists/scalars produced by the
+    // serializers above. Longs/Floats are widened to Double (JS number).
+
+    private fun toWritableMap(map: Map<String, Any?>): WritableMap {
+        val out = Arguments.createMap()
+        for ((key, value) in map) {
+            when (value) {
+                null -> out.putNull(key)
+                is Boolean -> out.putBoolean(key, value)
+                is Int -> out.putInt(key, value)
+                is Long -> out.putDouble(key, value.toDouble())
+                is Float -> out.putDouble(key, value.toDouble())
+                is Double -> out.putDouble(key, value)
+                is String -> out.putString(key, value)
+                is WritableMap -> out.putMap(key, value)
+                is WritableArray -> out.putArray(key, value)
+                is Map<*, *> -> out.putMap(key, toWritableMap(coerceStringKeys(value)))
+                is List<*> -> out.putArray(key, toWritableArray(value))
+                else -> out.putString(key, value.toString())
+            }
+        }
+        return out
+    }
+
+    private fun toWritableArray(list: List<*>): WritableArray {
+        val out = Arguments.createArray()
+        for (value in list) {
+            when (value) {
+                null -> out.pushNull()
+                is Boolean -> out.pushBoolean(value)
+                is Int -> out.pushInt(value)
+                is Long -> out.pushDouble(value.toDouble())
+                is Float -> out.pushDouble(value.toDouble())
+                is Double -> out.pushDouble(value)
+                is String -> out.pushString(value)
+                is WritableMap -> out.pushMap(value)
+                is WritableArray -> out.pushArray(value)
+                is Map<*, *> -> out.pushMap(toWritableMap(coerceStringKeys(value)))
+                is List<*> -> out.pushArray(toWritableArray(value))
+                else -> out.pushString(value.toString())
+            }
+        }
+        return out
+    }
+
+    private fun coerceStringKeys(map: Map<*, *>): Map<String, Any?> =
+        map.entries.associate { (k, v) -> k.toString() to v }
+}