@binoban/react-native 1.0.0

package/BinobanReactNative.podspec

@@ -0,0 +1,23 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "BinobanReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/binoban/binoban-example-react-native.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.exclude_files = "ios/build/**"
+  s.private_header_files = "ios/**/*.h"
+
+  s.dependency "binoban", "~> 1.0.0"
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 farhan
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @binoban/react-native
+
+React Native SDK for Binoban. A TurboModule bridge to the [Binoban KMP SDK](../kotlin/) — Android delegates to `io.binoban.sdk:sdk-android`, iOS delegates to the `binoban` XCFramework via CocoaPods.
+
+## Installation
+
+```sh
+npm install @binoban/react-native
+```
+
+## Compatibility
+
+| Surface | Supported |
+|---|---|
+| React Native | >= 0.71. **New Architecture (TurboModules) recommended.** On the old architecture the native module resolves to `null`, so the SDK becomes an inert no-op rather than crashing. |
+| React | >= 18 |
+| Android | `minSdkVersion 24`, `compileSdkVersion 36`, `targetSdkVersion 36` |
+| iOS | deployment target = React Native's `min_ios_version_supported` |
+| Node (development) | >= 20 |
+
+### Safety contract
+
+Every bridge call is wrapped so it can never crash or throw into the host app —
+on any device or OS version. Failures are swallowed and logged only when
+`debug: true`. To observe failures, pass an `onError` callback:
+
+```ts
+const client = createClient({
+  apiHost: 'stage-api.binoban.io',
+  credentials: { android: { /* ... */ }, iOS: { /* ... */ } },
+  onError: (e) => console.warn('Binoban:', e.method, e.message),
+});
+```
+
+`onError` receives both JS-side failures and errors the native SDK reports (for
+those, `e.method` is `"native"` or `"native:<ThrowableClass>"`) — e.g. a disabled
+instance from invalid config.
+
+## Usage
+
+```ts
+import { createClient, BinobanProvider, useBinoban } from '@binoban/react-native';
+
+const client = createClient({
+  credentials: {
+    android: { apiKey: 'YOUR_ANDROID_KEY', sourceIdentifier: 'YOUR_ANDROID_SOURCE' },
+    iOS:     { apiKey: 'YOUR_IOS_KEY',     sourceIdentifier: 'YOUR_IOS_SOURCE' },
+  },
+  apiHost: 'your-api-host.example.com',
+});
+
+// Wrap your app
+<BinobanProvider client={client}>
+  <App />
+</BinobanProvider>
+
+// Inside a component
+const { track, identify, flush, reset, anonymousId, userId, deviceId, notify, setDeviceToken } = useBinoban();
+```
+
+> **Not yet supported:** `screen()`, `group()`, and `alias()` are not exposed
+> through this bridge yet. `track()`, `identify()`, `flush()`, `reset()`,
+> `anonymousId()`, `userId()`, `deviceId()`, `notify()`, and `setDeviceToken()`
+> are all available, plus the notification-interaction API below.
+
+### Notification interactions
+
+Subscribe to taps (body and per-action-button), dismissals, and delivery. Each
+interaction carries `{ notificationUuid, type, actionId, uri, customData, reason }`,
+where `type` is one of `DELIVERED | CLICKED | CLOSED | FAILED | OPENED`. Backend
+tracking is preserved automatically — the bridge extends the SDK's default handler.
+
+```ts
+const { onNotificationInteraction, getInitialNotificationInteraction } = useBinoban();
+
+useEffect(() => {
+  // Cold start: a tap that launched the app before JS subscribed. Call once.
+  getInitialNotificationInteraction().then((i) => {
+    if (i?.uri) navigateTo(i.uri);
+  });
+
+  // Live interactions while the app runs.
+  const sub = onNotificationInteraction((i) => {
+    if (i.type === 'CLICKED' && i.uri) navigateTo(i.uri);
+    // i.customData is the developer-supplied string→string map from the push.
+  });
+  return () => sub.remove();
+}, []);
+```
+
+**Note:** the SDK does not open URLs itself on iOS — read `interaction.uri` and route
+it in your handler.
+
+**Platform wiring:**
+
+- **Android** — nothing extra. The SDK's notification trampoline delivers interactions,
+  so they reach JS automatically once you subscribe.
+- **iOS** — the SDK never registers its own `UNUserNotificationCenterDelegate`, so the host
+  must forward its notification callbacks. Either:
+  - **From JS** (e.g. when a JS push library gives you the tap): call
+    `didReceiveNotificationResponse(userInfo, actionId, dismissed)`,
+    `willPresentNotification(userInfo)`, or `didReceiveRemoteNotification(userInfo)` on the
+    client. These are no-ops on Android.
+  - **From the native AppDelegate** — forward straight to the SDK's KMP functions
+    (`onDidReceiveForwarded`, `onWillPresentForwarded`,
+    `onApplicationDidReceiveRemoteNotification`, `onNewToken`); the bridge's installed
+    handler still emits the interaction to JS.
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node >= 20 (`nvm use` to switch automatically)
+- Yarn 4 (`corepack enable` if needed)
+- **iOS only:** Ruby via `rbenv` or `rvm`, CocoaPods managed through Bundler
+
+### First-time setup
+
+```sh
+# 1. Install JS dependencies
+yarn
+
+# 2. iOS only — install the Bundler-locked version of CocoaPods and run pod install
+cd example/ios
+bundle install
+bundle exec pod install
+cd ../..
+```
+
+> Always use `bundle exec pod install` (not bare `pod install`) to use the exact CocoaPods version from the Gemfile.lock.
+
+---
+
+## Running the example app
+
+### Android
+
+```sh
+yarn example android
+```
+
+### iOS
+
+```sh
+yarn example ios
+```
+
+`automaticPodsInstallation` is enabled in `example/react-native.config.js`, so `yarn example ios` will trigger `pod install` automatically when Pods are out of date. If it doesn't pick up your changes, run manually:
+
+```sh
+cd example/ios && bundle exec pod install && cd ../..
+```
+
+To start Metro separately (useful for attach/reload without rebuilding):
+
+```sh
+yarn example start
+```
+
+---
+
+## What to do after common changes
+
+### Changing `src/NativeBinobanReactNative.ts` (the TurboModule spec)
+
+The spec drives ObjC++ codegen on iOS and Kotlin codegen on Android.
+
+**iOS** — regenerate codegen by running pod install:
+```sh
+cd example/ios && bundle exec pod install && cd ../..
+```
+The generated files land in `example/ios/build/generated/ios/ReactCodegen/BinobanReactNativeSpec/`. Then rebuild the app normally with `yarn example ios`.
+
+**Android** — no manual step. The Android Gradle plugin regenerates the spec automatically during the next build (`yarn example android`).
+
+### Changing native code (`ios/*.mm` / `android/src/**/*.kt`)
+
+A full native rebuild is required. Just run:
+```sh
+yarn example ios     # or android
+```
+
+Metro hot-reload does **not** pick up native changes.
+
+### Changing JS/TS source only (`src/*.ts`, `src/*.tsx`)
+
+Metro picks these up automatically — no rebuild needed. If the example app is already running, save the file and Metro will hot-reload.
+
+---
+
+## Troubleshooting
+
+### iOS: `fmt` fails to compile — "call to consteval function … is not a constant expression"
+
+React Native 0.83 pulls in `fmt` 11.0.2, which does not compile under Xcode 16.3+ / 26 because of stricter `consteval` handling in the newer Clang. This is a React Native toolchain issue, not a binoban one — it affects any RN 0.83 project on these Xcode versions.
+
+The fix is already wired into `example/ios/Podfile`: its `post_install` hook patches `Pods/fmt/include/fmt/base.h` to disable `fmt`'s `consteval` path (compile-time format-string checking off; runtime formatting unchanged). It re-applies automatically on every `pod install`. If you still hit the error, re-run `pod install` and confirm you see `Patched fmt base.h …` in the output, then clean the build folder (Xcode → Product → Clean Build Folder) and rebuild.
+
+---
+
+## Opening native code in an IDE
+
+**Xcode (iOS):**
+Open `example/ios/BinobanReactNativeExample.xcworkspace` (the `.xcworkspace`, not `.xcodeproj`). The bridge source files are under `Pods > Development Pods > binoban-react-native`.
+
+**Android Studio:**
+Open `example/android`. The bridge source files appear under `binoban-react-native` in the project tree.
+
+---
+
+## Other commands
+
+```sh
+yarn typecheck        # TypeScript type check
+yarn lint             # ESLint
+yarn lint --fix       # Auto-fix lint issues
+yarn test             # Jest unit tests
+yarn prepare          # Build the library (outputs to lib/)
+yarn release          # Publish to npm (bumps version, tags, creates GitHub release)
+```
+
+---
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,77 @@
+buildscript {
+  ext.BinobanReactNative = [
+    kotlinVersion: "2.1.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return BinobanReactNative[prop]
+  }
+
+  repositories {
+    mavenLocal()
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+repositories {
+  mavenLocal()
+  google()
+  mavenCentral()
+}
+
+android {
+  namespace "io.binoban.sdk.reactNative"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "io.binoban.sdk:sdk-android:1.0.1"
+  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1"
+  testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/io/binoban/sdk/reactNative/BinobanReactNativeModule.kt

@@ -0,0 +1,248 @@
+package io.binoban.sdk.reactNative
+
+import android.content.pm.PackageManager
+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.ReadableMap
+import com.facebook.react.bridge.ReadableMapKeySetIterator
+import com.facebook.react.bridge.ReadableType
+import com.facebook.react.bridge.WritableMap
+import io.binoban.sdk.core.Binoban
+import io.binoban.sdk.core.Notification
+import io.binoban.sdk.core.platform.notifier.notification.DefaultNotificationInteractionHandler
+import io.binoban.sdk.core.platform.notifier.notification.NotificationInteraction
+import io.binoban.sdk.core.platform.notifier.notification.NotificationInteractionManager
+import io.binoban.sdk.core.platform.notifier.notification.NotificationInteractionType
+import io.binoban.sdk.core.platform.notifier.notification.configuration.NotificationPlatformConfiguration
+import io.binoban.sdk.core.platform.plugins.setDeviceToken
+import io.binoban.sdk.core.platform.policies.CountBasedFlushPolicy
+import io.binoban.sdk.core.platform.policies.FrequencyFlushPolicy
+import kotlinx.serialization.json.JsonObject
+
+
+class BinobanReactNativeModule(reactContext: ReactApplicationContext) :
+  NativeBinobanReactNativeSpec(reactContext) {
+
+  lateinit var binoban: Binoban
+  var initializing = false
+  var initialized = false
+
+  // Holds a cold-start interaction (a tap that arrived before JS subscribed) until
+  // getInitialNotificationInteraction() consumes it. Only one is retained.
+  private var initialInteraction: NotificationInteraction? = null
+
+  override fun setup(config: ReadableMap): Boolean {
+    if (initialized || initializing) return false
+    initializing = true
+    val ok = BinobanSafe.safe(false) {
+      BinobanSafe.debug = config.getBoolean("debug") == true
+      val module = this@BinobanReactNativeModule
+      binoban = Binoban(
+        config.getString("apiKey").toString(),
+        config.getString("sourceIdentifier").toString()
+      ) {
+        // Route the KMP SDK's internal errors to JS (createClient's onError).
+        this.errorHandler = { t -> module.emitNativeError(t) }
+        this.collectDeviceId = config.getBoolean("collectDeviceId") == true
+        this.trackApplicationLifecycleEvents = config.getBoolean("trackAppLifecycleEvents") == true
+        this.useLifecycleObserver =
+          if (config.hasKey("useLifecycleObserver")) config.getBoolean("useLifecycleObserver") else true
+        this.trackDeepLinks = config.getBoolean("trackDeepLinks") == true
+        this.apiHost = config.getString("apiHost").toString()
+        this.autoAddSegmentDestination =
+          if (config.hasKey("autoAddSegmentDestination")) config.getBoolean("autoAddSegmentDestination") else true
+        // Telemetry (var since sdk 1.0.0 — now at parity with iOS)
+        this.disableTelemetry = config.getBoolean("disableTelemetry") == true
+        config.getString("telemetryHost")?.takeIf { it.isNotEmpty() }?.let { this.telemetryHost = it }
+        // Upload resilience tunables (sdk 1.0.0). Fall back to KMP defaults when a key is absent.
+        if (config.hasKey("uploadMaxRetries")) this.uploadMaxRetries = config.getInt("uploadMaxRetries")
+        if (config.hasKey("backoffBaseMillis")) this.backoffBaseMillis = config.getDouble("backoffBaseMillis").toLong()
+        if (config.hasKey("backoffFactor")) this.backoffFactor = config.getDouble("backoffFactor")
+        if (config.hasKey("backoffMaxMillis")) this.backoffMaxMillis = config.getDouble("backoffMaxMillis").toLong()
+        if (config.hasKey("maxFilesPerFlush")) this.maxFilesPerFlush = config.getInt("maxFilesPerFlush")
+        this.flushPolicies = listOf(
+          CountBasedFlushPolicy(config.getInt("flushAt")),
+          FrequencyFlushPolicy(config.getInt("flushInterval").toLong() * 1000L),
+        )
+      }
+      Binoban.debugLogsEnabled = BinobanSafe.debug
+      installInteractionHandler()
+      true
+    }
+    initialized = ok
+    initializing = false
+    return ok
+  }
+
+  // Install a handler that preserves the SDK's default backend tracking (via super)
+  // and additionally forwards each interaction to JS. The trampoline delivers taps
+  // on its own, so no host wiring is needed on Android.
+  private fun installInteractionHandler() {
+    NotificationInteractionManager.setHandler(object : DefaultNotificationInteractionHandler() {
+      override fun onNotificationInteraction(interaction: NotificationInteraction) {
+        super.onNotificationInteraction(interaction)
+        BinobanSafe.safe(Unit) {
+          initialInteraction = interaction
+          emitOnNotificationInteraction(interaction.toWritableMap())
+        }
+      }
+    })
+    // Recover a cold-start tap the notification trampoline delivered during process
+    // startup, before this handler was installed (process start -> trampoline -> setup).
+    // Tracking already happened via the default handler; surface it to JS only through
+    // getInitialNotificationInteraction(). Keep the most recent actual tap.
+    BinobanSafe.safe(Unit) {
+      NotificationInteractionManager.drainPendingInteractions()
+        .lastOrNull {
+          it.type == NotificationInteractionType.CLICKED ||
+            it.type == NotificationInteractionType.OPENED
+        }
+        ?.let { initialInteraction = it }
+    }
+  }
+
+  private fun emitNativeError(t: Throwable) {
+    BinobanSafe.safe(Unit) {
+      val map = Arguments.createMap()
+      map.putString("message", t.message ?: t.toString())
+      map.putString("name", t::class.simpleName)
+      emitOnNativeError(map)
+    }
+  }
+
+  private fun NotificationInteraction.toWritableMap(): WritableMap {
+    val map = Arguments.createMap()
+    map.putString("notificationUuid", notificationUuid)
+    map.putString("type", type.name)
+    map.putString("actionId", actionId)
+    map.putString("uri", uri)
+    map.putString("reason", reason)
+    val cd = customData
+    if (cd != null) {
+      val cdMap = Arguments.createMap()
+      cd.forEach { (k, v) -> cdMap.putString(k, v) }
+      map.putMap("customData", cdMap)
+    } else {
+      map.putNull("customData")
+    }
+    return map
+  }
+
+  override fun track(eventName: String?, properties: ReadableMap?) {
+    BinobanSafe.safe(Unit) {
+      if (!initialized || eventName == null) return@safe
+      binoban.track(eventName, properties?.toJsonObject() ?: JsonObject(emptyMap()))
+    }
+  }
+
+  override fun identify(userId: String?, userTraits: ReadableMap?) {
+    BinobanSafe.safe(Unit) {
+      if (!initialized || userId == null) return@safe
+      binoban.identify(userId, userTraits?.toJsonObject() ?: JsonObject(emptyMap()))
+    }
+  }
+
+  override fun flush() {
+    BinobanSafe.safe(Unit) { if (initialized) binoban.flush() }
+  }
+
+  override fun reset() {
+    BinobanSafe.safe(Unit) { if (initialized) binoban.reset() }
+  }
+
+  override fun anonymousId(): String =
+    BinobanSafe.safe("") { if (initialized) binoban.anonymousId() else "" }
+
+  override fun userId(): String? =
+    BinobanSafe.safe<String?>(null) { if (initialized) binoban.userId() else null }
+
+  override fun deviceId(): String? =
+    BinobanSafe.safe<String?>(null) { if (initialized) binoban.deviceId() else null }
+
+  override fun setDeviceToken(token: String) {
+    BinobanSafe.safe(Unit) { if (initialized) binoban.setDeviceToken(token) }
+  }
+
+  override fun notify(payloadData: ReadableMap) {
+    BinobanSafe.safe(Unit) {
+      if (payloadData.getString("source") != "binoban") return@safe
+
+      val remoteMessage: MutableMap<String, String> = HashMap()
+      val iterator: ReadableMapKeySetIterator = payloadData.keySetIterator()
+      while (iterator.hasNextKey()) {
+        val key = iterator.nextKey()
+        val type: ReadableType = payloadData.getType(key)
+        if (type == ReadableType.String) {
+          payloadData.getString(key)?.let { remoteMessage.put(key, it) }
+        }
+      }
+
+      var icon: Int = reactApplicationContext.applicationInfo.icon
+      var channelId = "DEFAULT_NOTIFICATION_CHANNEL_ID"
+      var channelName = "General"
+      var channelDescription = ""
+
+      try {
+        val app = reactApplicationContext.packageManager
+          .getApplicationInfo(reactApplicationContext.packageName, PackageManager.GET_META_DATA)
+        val bundle = app.metaData
+        icon = bundle.getInt(BINOBAN_PUSH_DEFAULT_ICON, reactApplicationContext.applicationInfo.icon)
+        channelId = bundle.getString(BINOBAN_PUSH_CHANNEL_ID, channelId)
+        channelName = bundle.getString(BINOBAN_PUSH_CHANNEL_NAME, channelName)
+        channelDescription = bundle.getString(BINOBAN_PUSH_CHANNEL_DESCRIPTION, channelDescription)
+      } catch (e: PackageManager.NameNotFoundException) {
+        if (BinobanSafe.debug) Log.w("Binoban", "notification meta-data lookup failed", e)
+      }
+
+      try {
+        Notification.initialize(
+          NotificationPlatformConfiguration.Android(
+            notificationIconResId = icon,
+            notificationChannelData = NotificationPlatformConfiguration.Android.NotificationChannelData(
+              channelId,
+              channelName,
+              channelDescription
+            )
+          )
+        )
+        Notification.notify(remoteMessage)
+      } catch (_: Exception) {}
+    }
+  }
+
+  override fun getInitialNotificationInteraction(promise: Promise) {
+    BinobanSafe.safe(Unit) {
+      val interaction = initialInteraction
+      initialInteraction = null
+      promise.resolve(interaction?.toWritableMap())
+    }
+  }
+
+  // iOS-only host forwarding. On Android the trampoline delivers interactions
+  // directly, so these are no-ops kept for a single cross-platform JS surface.
+  override fun didReceiveNotificationResponse(
+    userInfo: ReadableMap,
+    actionId: String?,
+    dismissed: Boolean?
+  ) {
+    // no-op on Android
+  }
+
+  override fun willPresentNotification(userInfo: ReadableMap) {
+    // no-op on Android
+  }
+
+  override fun didReceiveRemoteNotification(userInfo: ReadableMap) {
+    // no-op on Android
+  }
+
+  override fun getName(): String {
+    return NAME
+  }
+
+  companion object {
+    const val NAME = "BinobanReactNative"
+  }
+}

package/android/src/main/java/io/binoban/sdk/reactNative/BinobanReactNativePackage.kt

@@ -0,0 +1,32 @@
+package io.binoban.sdk.reactNative
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class BinobanReactNativePackage : TurboReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == BinobanReactNativeModule.NAME) {
+      BinobanReactNativeModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      BinobanReactNativeModule.NAME to ReactModuleInfo(
+        BinobanReactNativeModule.NAME,
+        BinobanReactNativeModule::class.java.name,
+        false,
+        false,
+        true,
+        false,
+        true
+      )
+    )
+  }
+}

package/android/src/main/java/io/binoban/sdk/reactNative/BinobanSafe.kt

@@ -0,0 +1,22 @@
+package io.binoban.sdk.reactNative
+
+import android.util.Log
+
+/**
+ * Central safety wrapper for every bridge call. Never lets a Throwable escape
+ * to React Native / the host app; logs only when [debug] is enabled.
+ */
+object BinobanSafe {
+  private const val TAG = "Binoban"
+
+  @Volatile
+  var debug: Boolean = false
+
+  fun <T> safe(fallback: T, block: () -> T): T =
+    try {
+      block()
+    } catch (e: Throwable) {
+      if (debug) Log.w(TAG, "binoban bridge call failed", e)
+      fallback
+    }
+}