@dashx/react-native 1.4.0 → 1.5.0

package/.claude/worktrees/autocapture-conventions-review-78f665/android/src/main/java/com/dashx/rn/sdk/DashXReactNativeModuleImpl.kt

@@ -0,0 +1,445 @@
+package com.dashx.rn.sdk
+
+import android.Manifest
+import android.app.Activity
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.provider.Settings
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import com.dashx.rn.sdk.util.*
+import com.dashx.android.DashX
+import com.dashx.android.DashXActivityLifecycleCallbacks
+import com.dashx.android.DashXLog
+import com.dashx.android.DashXLog.LogLevel
+import com.dashx.android.data.Asset
+import com.facebook.react.bridge.*
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.modules.core.PermissionListener
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.encodeToJsonElement
+import kotlinx.serialization.json.jsonObject
+
+class DashXReactNativeModuleImpl(private val reactContext: ReactApplicationContext) {
+    private val tag = DashXReactNativeModuleImpl::class.java.simpleName
+
+    // Bridges SDK notification-click callbacks to the JS
+    // `DashX.onNotificationClicked` listener. Registered in `initialize`,
+    // removed in `invalidate` so we don't leak across RN reloads.
+    private val notificationClickedListener = DashXNotificationClickedListener(reactContext)
+
+    fun initialize() {
+        MessageReceivedEventHolder.reactContext = reactContext
+        DashX.registerNotificationListener(notificationClickedListener)
+    }
+
+    fun invalidate() {
+        MessageReceivedEventHolder.reactContext = null
+        DashX.unregisterNotificationListener(notificationClickedListener)
+    }
+
+    fun setLogLevel(level: Double) {
+        // JS contract: 0 = off, 1 = errors, 2 = debug
+        // Native SDK:  OFF = -1, ERROR = 0, INFO = 1, DEBUG = 2
+        val logLevel = when (level.toInt()) {
+            0 -> LogLevel.OFF
+            1 -> LogLevel.ERROR
+            2 -> LogLevel.DEBUG
+            else -> LogLevel.OFF
+        }
+        DashXLog.setLogLevel(logLevel)
+    }
+
+    fun configure(options: ReadableMap) {
+        createDefaultNotificationChannel()
+        DashX.configure(
+            reactContext,
+            options.getString("publicKey")!!,
+            options.getStringIfPresent("baseURI"),
+            options.getStringIfPresent("targetEnvironment")
+        )
+    }
+
+    private fun createDefaultNotificationChannel() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val notificationManager = reactContext.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager ?: return
+
+        val existing = notificationManager.getNotificationChannel(DEFAULT_CHANNEL_ID)
+        if (existing != null) return
+
+        val channel = NotificationChannel(
+            DEFAULT_CHANNEL_ID,
+            DEFAULT_CHANNEL_NAME,
+            NotificationManager.IMPORTANCE_HIGH
+        ).apply {
+            enableVibration(true)
+            setShowBadge(true)
+            lockscreenVisibility = android.app.Notification.VISIBILITY_PUBLIC
+        }
+        notificationManager.createNotificationChannel(channel)
+    }
+
+    fun identify(options: ReadableMap?) {
+        val optionsHashMap = options?.toHashMap()
+            ?.filterValues { it != null }
+            ?.mapValues { it.value.toString() }
+        DashX.identify(optionsHashMap?.let { HashMap(it) })
+    }
+
+    fun setIdentity(uid: String?, token: String?) {
+        DashX.setIdentity(uid, token)
+    }
+
+    fun reset() {
+        DashX.reset()
+    }
+
+    fun track(event: String, data: ReadableMap?) {
+        val jsonData = try {
+            data?.toHashMap()
+                ?.filterValues { it != null }
+                ?.mapValues { it.value.toString() }
+                ?.let { HashMap(it) }
+        } catch (e: Exception) {
+            DashXLog.d(tag, "Failed to convert track data, sending event without data: ${e.message}")
+            null
+        }
+
+        DashX.track(event, jsonData)
+    }
+
+    fun screen(screenName: String, data: ReadableMap?) {
+        val screenData = data?.toHashMap()
+            ?.filterValues { it != null }
+            ?.mapValues { it.value.toString() }
+            ?.let { HashMap(it) }
+            ?: HashMap()
+        DashX.screen(screenName, screenData)
+    }
+
+    fun fetchRecord(urn: String, options: ReadableMap?, promise: Promise) {
+        val preview = options?.getBooleanIfPresent("preview")
+        val language = options?.getStringIfPresent("language")
+        val fields = try {
+            convertReadableArrayToKJsonList(options?.getArray("fields"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing fields: ${e.message}")
+            return
+        }
+        val include = try {
+            convertReadableArrayToKJsonList(options?.getArray("include"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing include: ${e.message}")
+            return
+        }
+        val exclude = try {
+            convertReadableArrayToKJsonList(options?.getArray("exclude"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing exclude: ${e.message}")
+            return
+        }
+
+        DashX.fetchRecord(
+            urn = urn,
+            preview = preview,
+            language = language,
+            fields = fields,
+            include = include,
+            exclude = exclude,
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            },
+            onSuccess = {
+                promise.resolve(convertJsonToMap(it))
+            }
+        )
+    }
+
+    fun searchRecords(resource: String, options: ReadableMap?, promise: Promise) {
+        val jsonFilter = try {
+            convertMapToJson(options?.getMap("filter"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing filter: ${e.message}")
+            return
+        }
+        val order = try {
+            convertReadableArrayToKJsonList(options?.getArray("order"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing order: ${e.message}")
+            return
+        }
+        val limit = options?.getIntIfPresent("limit")
+        val preview = options?.getBooleanIfPresent("preview")
+        val language = options?.getStringIfPresent("language")
+        val fields = try {
+            convertReadableArrayToKJsonList(options?.getArray("fields"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing fields: ${e.message}")
+            return
+        }
+        val include = try {
+            convertReadableArrayToKJsonList(options?.getArray("include"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing include: ${e.message}")
+            return
+        }
+        val exclude = try {
+            convertReadableArrayToKJsonList(options?.getArray("exclude"))
+        } catch (e: Exception) {
+            DashXLog.d(tag, e.message)
+            promise.reject(E_UNSPECIFIED, "Error parsing exclude: ${e.message}")
+            return
+        }
+
+        DashX.searchRecords(
+            resource = resource,
+            filter = jsonFilter,
+            order = order,
+            limit = limit,
+            preview = preview,
+            language = language,
+            fields = fields,
+            include = include,
+            exclude = exclude,
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            },
+            onSuccess = { records ->
+                val readableArray = Arguments.createArray()
+                records.forEach {
+                    readableArray.pushMap(convertJsonToMap(it))
+                }
+                promise.resolve(readableArray)
+            }
+        )
+    }
+
+    fun fetchStoredPreferences(promise: Promise) {
+        DashX.fetchStoredPreferences(
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            },
+            // The SDK hands back a typed wrapper whose `preferenceData`
+            // field is the raw kotlinx `JsonObject`. Unwrap and flatten so
+            // the JS side receives the prefs directly — matches how the iOS
+            // bridge resolves `DashXClient.fetchStoredPreferences`.
+            onSuccess = { content ->
+                promise.resolve(convertJsonToMap(content.preferenceData))
+            }
+        )
+    }
+
+    fun saveStoredPreferences(preferenceData: ReadableMap?, promise: Promise) {
+        // A null/empty payload maps to an empty JSON object — matches the
+        // SDK's "I received preferences but they're empty" contract and
+        // replaces a pre-migration NPE path that crashed when the caller
+        // passed `null`.
+        val preferencesJson = convertMapToJson(preferenceData) ?: buildJsonObject { }
+
+        DashX.saveStoredPreferences(
+            preferencesJson,
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            },
+            // Mutation response is just `{ success: Boolean }` — resolve the
+            // Promise with that Boolean, matching what the iOS bridge does.
+            onSuccess = { content ->
+                promise.resolve(content.success)
+            }
+        )
+    }
+
+    fun subscribe() {
+        DashX.subscribe()
+    }
+
+    fun unsubscribe(promise: Promise) {
+        DashX.unsubscribe(
+            onSuccess = { didUnsubscribe ->
+                val result = Arguments.createMap().apply {
+                    putBoolean("success", didUnsubscribe)
+                }
+                promise.resolve(result)
+            },
+            onError = { promise.reject(E_UNSPECIFIED, it.message) }
+        )
+    }
+
+    fun enableLifecycleTracking() {
+        // The SDK's tracking flags are unsynchronized statics read on the main thread.
+        val application = reactContext.applicationContext
+        UiThreadUtil.runOnUiThread {
+            DashXActivityLifecycleCallbacks.enableActivityLifecycleTracking(application)
+        }
+    }
+
+    // --- iOS-only methods: no-op stubs on Android (JS guards prevent these from being called) ---
+
+    fun enableAdTracking() {
+        // iOS-only; no-op on Android
+    }
+
+    fun processURL(url: String, source: String?, forwardToLinkHandler: Boolean) {
+        // iOS-only; no-op on Android
+    }
+
+    fun trackNotificationNavigation(action: ReadableMap?, notificationId: String?) {
+        // iOS-only; no-op on Android
+    }
+
+    fun uploadAsset(filePath: String, resource: String, attribute: String, promise: Promise) {
+        val file = java.io.File(filePath)
+        DashX.uploadAsset(
+            file = file,
+            resource = resource,
+            attribute = attribute,
+            onSuccess = { asset ->
+                try {
+                    // `Asset` is `@Serializable` — go straight to a
+                    // `JsonElement` tree without the string + parser hop.
+                    promise.resolve(convertJsonToMap(Json.encodeToJsonElement(asset).jsonObject))
+                } catch (e: Exception) {
+                    promise.resolve(null)
+                }
+            },
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            }
+        )
+    }
+
+    fun fetchAsset(assetId: String, promise: Promise) {
+        DashX.fetchAsset(
+            assetId = assetId,
+            onSuccess = { asset ->
+                try {
+                    promise.resolve(convertJsonToMap(Json.encodeToJsonElement(asset).jsonObject))
+                } catch (e: Exception) {
+                    promise.resolve(null)
+                }
+            },
+            onError = {
+                promise.reject(E_UNSPECIFIED, it.message)
+            }
+        )
+    }
+
+    fun requestNotificationPermission(fallbackToSettings: Boolean, promise: Promise) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            promise.resolve(PERMISSION_AUTHORIZED)
+            return
+        }
+
+        val alreadyGranted = ContextCompat.checkSelfPermission(
+            reactContext,
+            Manifest.permission.POST_NOTIFICATIONS
+        ) == PackageManager.PERMISSION_GRANTED
+        if (alreadyGranted) {
+            promise.resolve(PERMISSION_AUTHORIZED)
+            return
+        }
+
+        val activity = reactContext.currentActivity
+        if (activity == null) {
+            promise.reject(E_UNSPECIFIED, "No current activity to request permission from")
+            return
+        }
+
+        // "Permanently denied" detection on Android 13+: we asked at least
+        // once before AND the system says we shouldn't show a rationale.
+        // In that state `requestPermissions()` auto-resolves DENIED without
+        // any UI, so re-prompting is futile — Settings is the only path.
+        val prefs = reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val previouslyRequested = prefs.getBoolean(KEY_PERMISSION_REQUESTED, false)
+        val permanentlyDenied = previouslyRequested && !ActivityCompat.shouldShowRequestPermissionRationale(
+            activity,
+            Manifest.permission.POST_NOTIFICATIONS
+        )
+
+        if (fallbackToSettings && permanentlyDenied) {
+            openAppNotificationSettings()
+            promise.resolve(PERMISSION_DENIED)
+            return
+        }
+
+        val permAwareActivity = activity as? PermissionAwareActivity
+        if (permAwareActivity == null) {
+            promise.reject(E_UNSPECIFIED, "Activity does not support permission requests")
+            return
+        }
+
+        prefs.edit()
+            .putBoolean(KEY_PERMISSION_REQUESTED, true)
+            .apply()
+
+        val listener = PermissionListener { requestCode, _, grantResults ->
+            if (requestCode != NOTIFICATION_PERMISSION_REQUEST_CODE) return@PermissionListener false
+            val granted = grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED
+            promise.resolve(if (granted) PERMISSION_AUTHORIZED else PERMISSION_DENIED)
+            true
+        }
+
+        permAwareActivity.requestPermissions(
+            arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+            NOTIFICATION_PERMISSION_REQUEST_CODE,
+            listener
+        )
+    }
+
+    private fun openAppNotificationSettings() {
+        val intent = Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).apply {
+            putExtra(Settings.EXTRA_APP_PACKAGE, reactContext.packageName)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+        reactContext.startActivity(intent)
+    }
+
+    fun getNotificationPermissionStatus(promise: Promise) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            promise.resolve(PERMISSION_AUTHORIZED)
+            return
+        }
+        val granted = ContextCompat.checkSelfPermission(
+            reactContext,
+            Manifest.permission.POST_NOTIFICATIONS
+        ) == PackageManager.PERMISSION_GRANTED
+        if (granted) {
+            promise.resolve(PERMISSION_AUTHORIZED)
+        } else {
+            val wasRequested = reactContext
+                .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .getBoolean(KEY_PERMISSION_REQUESTED, false)
+            promise.resolve(if (wasRequested) PERMISSION_DENIED else PERMISSION_NOT_DETERMINED)
+        }
+    }
+
+    companion object {
+        const val NAME = "DashXReactNative"
+        private const val E_UNSPECIFIED = "EUNSPECIFIED"
+        private const val DEFAULT_CHANNEL_ID = "default_dashx_notification_channel"
+        private const val DEFAULT_CHANNEL_NAME = "Notifications"
+
+        private const val NOTIFICATION_PERMISSION_REQUEST_CODE = 3571
+
+        private const val PREFS_NAME = "dashx_rn_prefs"
+        private const val KEY_PERMISSION_REQUESTED = "notification_permission_requested"
+
+        // Mirrors iOS UNAuthorizationStatus values used by the JS layer.
+        private const val PERMISSION_NOT_DETERMINED = 0
+        private const val PERMISSION_DENIED = 1
+        private const val PERMISSION_AUTHORIZED = 2
+    }
+}

package/.claude/worktrees/autocapture-conventions-review-78f665/android/src/main/java/com/dashx/rn/sdk/MessageReceivedEventHolder.kt

@@ -0,0 +1,14 @@
+package com.dashx.rn.sdk
+
+import com.facebook.react.bridge.ReactApplicationContext
+
+/**
+ * Holds a reference to the React context so that [DashXReactNativeFirebaseMessagingService]
+ * can emit "messageReceived" events to JS when FCM messages arrive.
+ * Set by [DashXReactNativeModule], cleared when the module is invalidated.
+ */
+object MessageReceivedEventHolder {
+    @Volatile
+    var reactContext: ReactApplicationContext? = null
+        internal set
+}

package/.claude/worktrees/autocapture-conventions-review-78f665/android/src/main/java/com/dashx/rn/sdk/ReactNativeLibraryInfoProvider.kt

@@ -0,0 +1,8 @@
+package com.dashx.rn.sdk
+
+import com.dashx.android.DashXLibraryInfoProvider
+
+class ReactNativeLibraryInfoProvider : DashXLibraryInfoProvider {
+    override val name = "@dashx/react-native"
+    override val version: String = BuildConfig.VERSION_NAME
+}

package/.claude/worktrees/autocapture-conventions-review-78f665/android/src/main/java/com/dashx/rn/sdk/util/Utils.kt

@@ -0,0 +1,208 @@
+@file:JvmName("Utils")
+
+package com.dashx.rn.sdk.util
+
+import com.facebook.react.bridge.*
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.add
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.doubleOrNull
+import kotlinx.serialization.json.put
+
+// JSON conversion helpers between React Native's ReadableMap/ReadableArray/
+// WritableMap/WritableArray types and kotlinx.serialization's JsonObject/
+// JsonArray. Kept kotlinx-only on purpose — the DashX Android SDK uses
+// kotlinx-serialization end-to-end (see `mapScalar("JSON", "kotlinx...JsonObject")`
+// in dashx-android/dashx/build.gradle), so threading a single JSON library
+// through the bridge avoids string round-trips and the type-confusion class
+// of bugs that arose when Gson/org.json/kotlinx all coexisted.
+
+/**
+ * Factory seam for Writable instances. Production defaults to the JNI-backed
+ * `WritableNativeMap` / `WritableNativeArray`. JVM unit tests swap these to
+ * `JavaOnlyMap` / `JavaOnlyArray` (pure-Java, no JNI) — the native writables
+ * crash in a plain JUnit harness because their constructors call into
+ * `initHybrid()`. `internal` visibility keeps the seam invisible to SDK
+ * consumers.
+ */
+internal object WritableFactory {
+    var createMap: () -> WritableMap = { WritableNativeMap() }
+    var createArray: () -> WritableArray = { WritableNativeArray() }
+}
+
+/**
+ * Convert a [ReadableMap] (RN → native boundary) into a kotlinx [JsonObject].
+ * Returns `null` when [readableMap] is null, so callers can distinguish
+ * "absent" from "empty".
+ *
+ * Numbers are coerced to [Double] on purpose — RN has a single JS `Number`
+ * type and the DashX backend's JSON scalars are agnostic to int/double.
+ */
+fun convertMapToJson(readableMap: ReadableMap?): JsonObject? {
+    val iterator = readableMap?.keySetIterator() ?: return null
+    return buildJsonObject {
+        while (iterator.hasNextKey()) {
+            val key = iterator.nextKey()
+            when (readableMap.getType(key)) {
+                ReadableType.Null -> put(key, JsonNull)
+                ReadableType.Boolean -> put(key, readableMap.getBoolean(key))
+                ReadableType.Number -> put(key, readableMap.getDouble(key))
+                ReadableType.String -> put(key, readableMap.getString(key))
+                ReadableType.Map -> put(key, convertMapToJson(readableMap.getMap(key)) ?: JsonNull)
+                ReadableType.Array -> put(key, convertArrayToJson(readableMap.getArray(key)) ?: JsonNull)
+            }
+        }
+    }
+}
+
+/**
+ * Convert a [ReadableArray] into a kotlinx [JsonArray]. Mirrors
+ * [convertMapToJson] — null in, null out.
+ */
+fun convertArrayToJson(readableArray: ReadableArray?): JsonArray? {
+    if (readableArray == null) return null
+    return buildJsonArray {
+        for (i in 0 until readableArray.size()) {
+            when (readableArray.getType(i)) {
+                ReadableType.Null -> add(JsonNull)
+                ReadableType.Boolean -> add(readableArray.getBoolean(i))
+                ReadableType.Number -> add(readableArray.getDouble(i))
+                ReadableType.String -> add(readableArray.getString(i))
+                ReadableType.Map -> add(convertMapToJson(readableArray.getMap(i)) ?: JsonNull)
+                ReadableType.Array -> add(convertArrayToJson(readableArray.getArray(i)) ?: JsonNull)
+            }
+        }
+    }
+}
+
+/**
+ * Convert a [ReadableArray] of maps into a list of [JsonObject]s. Used for
+ * the `fields` / `include` / `exclude` / `order` option arrays on
+ * `fetchRecord` / `searchRecords`. Non-map entries are silently dropped to
+ * preserve the behaviour of the pre-migration helper.
+ */
+fun convertReadableArrayToKJsonList(readableArray: ReadableArray?): List<JsonObject>? {
+    if (readableArray == null || readableArray.size() == 0) return null
+    return (0 until readableArray.size()).mapNotNull { i ->
+        if (readableArray.getType(i) == ReadableType.Map) {
+            readableArray.getMap(i)?.let { convertMapToJson(it) }
+        } else {
+            null
+        }
+    }.ifEmpty { null }
+}
+
+/**
+ * Convert a kotlinx [JsonObject] (native → RN boundary) into a [WritableMap].
+ * Returns `null` when [jsonObject] is null.
+ *
+ * Numeric primitives are coerced to [Double] (`putDouble`) to match JS's
+ * single `Number` type. JSON nulls map to `putNull(key)`. Non-finite /
+ * non-numeric primitives fall back to string form.
+ */
+fun convertJsonToMap(jsonObject: JsonObject?): WritableMap? {
+    jsonObject ?: return null
+    val map: WritableMap = WritableFactory.createMap()
+    for ((key, element) in jsonObject) {
+        when (element) {
+            is JsonNull -> map.putNull(key)
+            is JsonPrimitive -> putPrimitive(map, key, element)
+            is JsonObject -> map.putMap(key, convertJsonToMap(element))
+            is JsonArray -> map.putArray(key, convertJsonToArray(element))
+        }
+    }
+    return map
+}
+
+/**
+ * Convert a kotlinx [JsonArray] into a [WritableArray]. Mirrors
+ * [convertJsonToMap]. Null-safe.
+ */
+fun convertJsonToArray(jsonArray: JsonArray?): WritableArray? {
+    jsonArray ?: return null
+    val array: WritableArray = WritableFactory.createArray()
+    for (element in jsonArray) {
+        when (element) {
+            is JsonNull -> array.pushNull()
+            is JsonPrimitive -> pushPrimitive(array, element)
+            is JsonObject -> array.pushMap(convertJsonToMap(element))
+            is JsonArray -> array.pushArray(convertJsonToArray(element))
+        }
+    }
+    return array
+}
+
+// Shared primitive dispatch — keeps the two public functions free of repeated
+// isString / booleanOrNull / doubleOrNull ladders. [primitive] is guaranteed
+// not to be [JsonNull] by the caller (JsonNull is a subtype of JsonPrimitive).
+private fun putPrimitive(map: WritableMap, key: String, primitive: JsonPrimitive) {
+    when {
+        primitive.isString -> map.putString(key, primitive.content)
+        primitive.booleanOrNull != null -> map.putBoolean(key, primitive.booleanOrNull!!)
+        primitive.doubleOrNull != null -> map.putDouble(key, primitive.doubleOrNull!!)
+        else -> map.putString(key, primitive.content)
+    }
+}
+
+private fun pushPrimitive(array: WritableArray, primitive: JsonPrimitive) {
+    when {
+        primitive.isString -> array.pushString(primitive.content)
+        primitive.booleanOrNull != null -> array.pushBoolean(primitive.booleanOrNull!!)
+        primitive.doubleOrNull != null -> array.pushDouble(primitive.doubleOrNull!!)
+        else -> array.pushString(primitive.content)
+    }
+}
+
+/**
+ * Generic `Map<*, *>` → `WritableMap` converter. Preserved from the original
+ * [Utils] surface — no JSON libraries involved, but used by callers that
+ * need to hand arbitrary Kotlin maps to the RN bridge.
+ */
+@JvmOverloads
+@Throws(Exception::class)
+fun convertToWritableMap(
+    map: Map<*, *>,
+    blacklist: List<String> = emptyList<String>()
+): WritableMap {
+    val writableMap: WritableMap = WritableFactory.createMap()
+    val iterator: Iterator<String> = map.keys.iterator() as Iterator<String>
+    while (iterator.hasNext()) {
+        val key = iterator.next()
+
+        if (blacklist.contains(key)) {
+            continue
+        }
+
+        when (val value = map[key]) {
+            is Boolean -> writableMap.putBoolean(key, value)
+            is Int -> writableMap.putInt(key, value)
+            is Double -> writableMap.putDouble(key, value)
+            is String -> writableMap.putString(key, value)
+            else -> writableMap.putString(key, value.toString())
+        }
+    }
+    return writableMap
+}
+
+// --- ReadableMap convenience accessors (unchanged from the previous Utils). ---
+
+fun ReadableMap.getMapIfPresent(key: String): ReadableMap? {
+    return if (this.hasKey(key)) this.getMap(key) else null
+}
+
+fun ReadableMap.getIntIfPresent(key: String): Int? {
+    return if (this.hasKey(key)) this.getInt(key) else null
+}
+
+fun ReadableMap.getStringIfPresent(key: String): String? {
+    return if (this.hasKey(key)) this.getString(key) else null
+}
+
+fun ReadableMap.getBooleanIfPresent(key: String): Boolean? {
+    return if (this.hasKey(key)) this.getBoolean(key) else null
+}