@voipsdk/react-native-voipcloud 0.2.1 → 1.0.0

package/android/src/main/java/com/voipcloud/sdk/rn/VoipCloudModule.java

@@ -1,6 +1,5 @@
 package com.voipcloud.sdk.rn;
 
-import android.provider.Settings;
 import androidx.annotation.NonNull;
 
 import com.facebook.react.bridge.Arguments;
@@ -17,294 +16,221 @@ import com.voipcloud.sdk.CallOpParam;
 import com.voipcloud.sdk.CallSendDtmfParam;
 import com.voipcloud.sdk.Endpoint;
 import com.voipcloud.sdk.EpConfig;
-import com.voipcloud.sdk.License;
-import com.voipcloud.sdk.LicenseRefresher;
 import com.voipcloud.sdk.TransportConfig;
 import com.voipcloud.sdk.pjsip_status_code;
 import com.voipcloud.sdk.pjsip_transport_type_e;
 import com.voipcloud.sdk.pjsua_destroy_flag;
 
+import com.voipcloud.sdk.rn.internal.BridgeGuard;
 import com.voipcloud.sdk.rn.internal.Events;
 import com.voipcloud.sdk.rn.internal.ManagedAccount;
 import com.voipcloud.sdk.rn.internal.ManagedCall;
 import com.voipcloud.sdk.rn.internal.ManagedCallRegistry;
 
 import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * React Native bridge for the VoipCloud SDK.  All methods are async
- * Promises; license-gate failures rejecting with code "VC_<ENUM>".
+ * React Native bridge for the VoipCloud public SDK (PJSIP, no license gate).
+ * All failures are returned as rejected Promises with VC_* codes — never crash
+ * the host app for API misuse or recoverable PJSIP errors.
  */
 public class VoipCloudModule extends ReactContextBaseJavaModule {
 
-    static {
-        // Load the prebuilt PJSIP + license-layer library.  Names must
-        // match jniLibs path inside the AAR: jni/<abi>/libvoipcloud.so.
-        // libc++_shared is co-located and pulled in implicitly by the
-        // loader as a NEEDED dependency.
-        System.loadLibrary("voipcloud");
-    }
-
     private final ReactApplicationContext ctx;
     private final ManagedCallRegistry calls = new ManagedCallRegistry();
     private final ConcurrentHashMap<Integer, ManagedAccount> accounts = new ConcurrentHashMap<>();
-    private final AtomicInteger nextAccKey = new AtomicInteger(1);
 
     private Endpoint endpoint;
     private boolean inited = false;
-    /** Last token accepted by License.set; reused by the refresher. */
-    private volatile String licenseToken = null;
-    /** Refresh URL currently driving LicenseRefresher.  Used to detect
-     *  when a token rotation also rotates the refresh endpoint. */
-    private volatile String activeRefreshUrl = null;
 
     public VoipCloudModule(ReactApplicationContext ctx) {
         super(ctx);
         this.ctx = ctx;
-
-        // Tell native the consumer app's package up front so subsequent
-        // License.set() can enforce the bundle_id binding embedded in
-        // the token.  Also anchor the clock-skew detector.
-        License.setBundle(ctx.getPackageName());
-        License.setStateDir(ctx.getFilesDir().getAbsolutePath());
     }
 
+    /** Must match NATIVE_MODULE_NAME in src/nativeModule.ts (@voipsdk/react-native-voipcloud). */
     @NonNull
     @Override
-    public String getName() { return "VoipCloud"; }
-
-    // ============== License ============================================
+    public String getName() { return "VoipsdkReactNativeVoipcloud"; }
 
-    @ReactMethod
-    public void setLicense(String token, Promise promise) {
+    private void destroyEndpointQuietly() {
+        if (endpoint == null) return;
         try {
-            License.set(token);
-            licenseToken = token;
-            bootstrapRefresher(License.refreshUrl());
-            promise.resolve(null);
-        } catch (Throwable t) {
-            // Stop any refresher tied to the previous (now-rejected) token.
-            stopRefresherInternal();
-            promise.reject(mapLicenseError(t), t.getMessage(), t);
-        }
-    }
-
-    /**
-     * Start, restart, or no-op the LicenseRefresher to match the URL
-     * embedded in the most recently accepted token.  The consumer app
-     * never specifies a URL — it travels inside the signed token.
-     */
-    private void bootstrapRefresher(String refreshUrl) {
-        if (refreshUrl == null || refreshUrl.isEmpty()) {
-            // Token opted out of refresh.  Stop any leftover loop.
-            stopRefresherInternal();
-            return;
-        }
-        // If the URL is unchanged, the existing refresher is still
-        // correct — just leave it running so its next 24 h fire reuses
-        // the now-updated token via its internal cache.
-        if (refreshUrl.equals(activeRefreshUrl)) return;
-
-        // URL changed (or first start) — restart with the new endpoint.
-        try { LicenseRefresher.stop(); } catch (Throwable ignored) {}
-        LicenseRefresher.start(ctx, refreshUrl, licenseToken, autoDeviceId());
-        activeRefreshUrl = refreshUrl;
-    }
-
-    private void stopRefresherInternal() {
-        try { LicenseRefresher.stop(); } catch (Throwable ignored) {}
-        activeRefreshUrl = null;
-    }
-
-    /**
-     * Stable per-install identifier without asking the consumer.  On
-     * Android 8+ the ANDROID_ID is scoped to package+signing key, so
-     * it survives reinstalls of the same APK but rotates if the app is
-     * sideloaded by another publisher — exactly the semantics a
-     * license server wants.
-     */
-    private String autoDeviceId() {
-        try {
-            String id = Settings.Secure.getString(
-                    ctx.getContentResolver(), Settings.Secure.ANDROID_ID);
-            if (id != null && !id.isEmpty()) return id;
+            endpoint.libDestroy(pjsua_destroy_flag.PJSUA_DESTROY_NO_NETWORK);
         } catch (Throwable ignored) {}
-        // Fall back to a manifest-derived label.
-        return ctx.getPackageName() + ":" + android.os.Build.FINGERPRINT;
-    }
-
-    /** Translate a PJSUA2 Error into the granular VC_* code surfaced to JS. */
-    private static String mapLicenseError(Throwable t) {
-        String msg = t.getMessage();
-        if (msg == null) return "VC_LICENSE";
-        if (msg.contains("license not set"))           return "VC_NO_LICENSE";
-        if (msg.contains("malformed"))                  return "VC_BAD_FORMAT";
-        if (msg.contains("signature invalid"))          return "VC_BAD_SIGNATURE";
-        if (msg.contains("license expired"))            return "VC_EXPIRED";
-        if (msg.contains("not active"))                 return "VC_NOT_ACTIVE";
-        if (msg.contains("revoked"))                    return "VC_REVOKED";
-        if (msg.contains("bundle id mismatch"))         return "VC_BUNDLE_MISMATCH";
-        if (msg.contains("concurrent calls"))           return "VC_CCU_EXCEEDED";
-        if (msg.contains("payload too large"))          return "VC_PAYLOAD_TOO_BIG";
-        if (msg.contains("clock rolled back"))          return "VC_CLOCK_SKEW";
-        return "VC_LICENSE";
-    }
-
-    @ReactMethod
-    public void getLicenseStatus(Promise promise) {
         try {
-            WritableMap m = Arguments.createMap();
-            m.putBoolean("valid",       License.isValid());
-            m.putString ("status",      License.status());
-            m.putString ("customerId",  License.customerId());
-            m.putInt    ("ccu",         License.maxCcu());
-            m.putInt    ("currentCalls",License.currentCalls());
-            m.putDouble ("expiry",      License.expiryUnix());
-            m.putDouble ("serverTime",  License.serverTime());
-            promise.resolve(m);
-        } catch (Throwable t) {
-            promise.reject("VC_STATUS", t.getMessage(), t);
-        }
+            endpoint.delete();
+        } catch (Throwable ignored) {}
+        endpoint = null;
+        inited = false;
     }
 
-    /**
-     * The refresher bootstraps itself from token.ref during
-     * setLicense(); the consumer never starts it manually.  We expose
-     * stop() only so apps can pause refresh during user logout / SDK
-     * shutdown.
-     */
     @ReactMethod
-    public void stopLicenseRefresh(Promise promise) {
-        stopRefresherInternal();
-        promise.resolve(null);
-    }
+    public void init(ReadableMap config, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (inited) { promise.resolve(null); return; }
 
-    // ============== Endpoint lifecycle =================================
+        if (config == null) config = Arguments.createMap();
 
-    @ReactMethod
-    public void init(ReadableMap config, Promise promise) {
+        Endpoint ep = null;
         try {
-            if (inited) { promise.resolve(null); return; }
-            endpoint = new Endpoint();
-            endpoint.libCreate();
+            ep = new Endpoint();
+            ep.libCreate();
 
             EpConfig epCfg = new EpConfig();
-            if (config.hasKey("userAgent"))
+            if (config.hasKey("userAgent") && !config.isNull("userAgent"))
                 epCfg.getUaConfig().setUserAgent(config.getString("userAgent"));
-            if (config.hasKey("stunServer")) {
+            if (config.hasKey("stunServer") && !config.isNull("stunServer")) {
                 com.voipcloud.sdk.StringVector v = new com.voipcloud.sdk.StringVector();
                 v.add(config.getString("stunServer"));
                 epCfg.getUaConfig().setStunServer(v);
             }
-            if (config.hasKey("logLevel"))
+            if (config.hasKey("logLevel") && !config.isNull("logLevel"))
                 epCfg.getLogConfig().setLevel(config.getInt("logLevel"));
 
-            endpoint.libInit(epCfg);
+            ep.libInit(epCfg);
 
-            // Default transports — TLS handled per-account via registrar URI.
             TransportConfig udp = new TransportConfig();
-            endpoint.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_UDP, udp);
+            ep.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_UDP, udp);
             TransportConfig tcp = new TransportConfig();
-            endpoint.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_TCP, tcp);
+            ep.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_TCP, tcp);
 
-            endpoint.libStart();
+            ep.libStart();
+            endpoint = ep;
             inited = true;
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_INIT", t.getMessage(), t);
+            if (ep != null) {
+                try { ep.libDestroy(pjsua_destroy_flag.PJSUA_DESTROY_NO_NETWORK); } catch (Throwable ignored) {}
+                try { ep.delete(); } catch (Throwable ignored) {}
+            }
+            endpoint = null;
+            inited = false;
+            BridgeGuard.reject(promise, "VC_INIT", "Failed to start VoipCloud endpoint", t);
         }
     }
 
     @ReactMethod
     public void shutdown(Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
         try {
             calls.clear();
-            for (ManagedAccount a : accounts.values()) a.delete();
-            accounts.clear();
-            if (endpoint != null) {
-                endpoint.libDestroy(pjsua_destroy_flag.PJSUA_DESTROY_NO_NETWORK);
-                endpoint.delete();
-                endpoint = null;
+            for (ManagedAccount a : accounts.values()) {
+                try { a.setRegistration(false); } catch (Throwable ignored) {}
+                try { a.delete(); } catch (Throwable ignored) {}
             }
-            inited = false;
+            accounts.clear();
+            destroyEndpointQuietly();
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_SHUTDOWN", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_SHUTDOWN", "Failed to shut down VoipCloud", t);
         }
     }
 
-    // ============== Account ============================================
-
     @ReactMethod
     public void register(ReadableMap cfg, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
+
+        String uri = BridgeGuard.requireString(cfg, "uri", promise);
+        if (uri == null) return;
+        String registrar = BridgeGuard.requireString(cfg, "registrar", promise);
+        if (registrar == null) return;
+        String username = BridgeGuard.requireString(cfg, "username", promise);
+        if (username == null) return;
+        String password = BridgeGuard.requireString(cfg, "password", promise);
+        if (password == null) return;
+
         try {
             AccountConfig acfg = new AccountConfig();
-            acfg.setIdUri(cfg.getString("uri"));
-            acfg.getRegConfig().setRegistrarUri(cfg.getString("registrar"));
+            acfg.setIdUri(uri);
+            acfg.getRegConfig().setRegistrarUri(registrar);
 
-            AuthCredInfo cred = new AuthCredInfo(
-                    "digest", "*",
-                    cfg.getString("username"), 0,
-                    cfg.getString("password"));
+            AuthCredInfo cred = new AuthCredInfo("digest", "*", username, 0, password);
             acfg.getSipConfig().getAuthCreds().add(cred);
 
             ManagedAccount acc = new ManagedAccount(ctx, calls);
             acc.create(acfg);
             int id = acc.accountId();
+            if (id < 0) {
+                acc.delete();
+                promise.reject("VC_REGISTER", "Account created but returned invalid id");
+                return;
+            }
             accounts.put(id, acc);
             promise.resolve(id);
         } catch (Throwable t) {
-            promise.reject("VC_REGISTER", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_REGISTER", "Failed to register SIP account", t);
         }
     }
 
     @ReactMethod
     public void unregister(int accountId, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
         try {
             ManagedAccount acc = accounts.remove(accountId);
             if (acc != null) {
-                acc.setRegistration(false);
-                acc.delete();
+                try { acc.setRegistration(false); } catch (Throwable ignored) {}
+                try { acc.delete(); } catch (Throwable ignored) {}
             }
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_UNREGISTER", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_UNREGISTER", "Failed to unregister account", t);
         }
     }
 
-    // ============== Call ===============================================
-
     @ReactMethod
     public void makeCall(int accountId, String uri, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
+
+        if (uri == null || uri.trim().isEmpty()) {
+            promise.reject("VC_INVALID_ARGUMENT", "destinationUri must not be empty");
+            return;
+        }
+
         try {
             ManagedAccount acc = accounts.get(accountId);
-            if (acc == null) { promise.reject("VC_NO_ACCOUNT", "unknown accountId"); return; }
+            if (acc == null) {
+                promise.reject("VC_NO_ACCOUNT", "Unknown accountId " + accountId + ". Call register() first.");
+                return;
+            }
             ManagedCall call = new ManagedCall(ctx, acc);
-            call.makeCall(uri, new CallOpParam(true));
+            call.makeCall(uri.trim(), new CallOpParam(true));
+            int callId = call.callId();
+            if (callId < 0) {
+                promise.reject("VC_MAKE_CALL", "Call started but returned invalid callId");
+                return;
+            }
             calls.put(call);
-            promise.resolve(call.callId());
+            promise.resolve(callId);
         } catch (Throwable t) {
-            promise.reject("VC_MAKE_CALL", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_MAKE_CALL", "Failed to place call", t);
         }
     }
 
     @ReactMethod
     public void answer(int callId, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
         try {
             ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
+            if (call == null) {
+                promise.reject("VC_NO_CALL", "Unknown callId " + callId);
+                return;
+            }
             CallOpParam op = new CallOpParam();
             op.setStatusCode(pjsip_status_code.PJSIP_SC_OK);
             call.answer(op);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_ANSWER", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_ANSWER", "Failed to answer call", t);
         }
     }
 
     @ReactMethod
     public void hangup(int callId, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
         try {
             ManagedCall call = calls.get(callId);
             if (call == null) { promise.resolve(null); return; }
@@ -314,48 +240,55 @@ public class VoipCloudModule extends ReactContextBaseJavaModule {
             calls.remove(callId);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_HANGUP", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_HANGUP", "Failed to hang up call", t);
         }
     }
 
     @ReactMethod
     public void hold(int callId, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
         try {
-            ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
+            ManagedCall call = requireCall(callId, promise);
+            if (call == null) return;
             call.setHold(new CallOpParam(true));
             WritableMap ev = Arguments.createMap();
             ev.putInt("callId", callId);
             Events.emit(getReactApplicationContext(), Events.CALL_HOLD, ev);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_HOLD", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_HOLD", "Failed to hold call", t);
         }
     }
 
     @ReactMethod
     public void unhold(int callId, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
         try {
-            ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
-            // PJSUA2 re-INVITE without an explicit hold flag re-offers
-            // sendrecv SDP; that releases the existing hold.
+            ManagedCall call = requireCall(callId, promise);
+            if (call == null) return;
             call.reinvite(new CallOpParam(true));
             WritableMap ev = Arguments.createMap();
             ev.putInt("callId", callId);
             Events.emit(getReactApplicationContext(), Events.CALL_UNHOLD, ev);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_UNHOLD", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_UNHOLD", "Failed to resume call", t);
         }
     }
 
     @ReactMethod
     public void mute(int callId, boolean on, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
         try {
-            ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
-            if (endpoint == null) { promise.reject("VC_INIT", "endpoint not started"); return; }
+            ManagedCall call = requireCall(callId, promise);
+            if (call == null) return;
+            if (endpoint == null) {
+                promise.reject("VC_NOT_INITIALIZED", "VoipCloud.init() must succeed before mute()");
+                return;
+            }
             call.setMuted(endpoint, on);
             WritableMap ev = Arguments.createMap();
             ev.putInt("callId", callId);
@@ -363,15 +296,21 @@ public class VoipCloudModule extends ReactContextBaseJavaModule {
             Events.emit(getReactApplicationContext(), Events.CALL_MUTE, ev);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_MUTE", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_MUTE", "Failed to change mute state", t);
         }
     }
 
     @ReactMethod
     public void sendDtmf(int callId, String digits, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
+        if (digits == null || digits.isEmpty()) {
+            promise.reject("VC_INVALID_ARGUMENT", "digits must not be empty");
+            return;
+        }
         try {
-            ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
+            ManagedCall call = requireCall(callId, promise);
+            if (call == null) return;
             CallSendDtmfParam p = new CallSendDtmfParam();
             p.setDigits(digits);
             call.sendDtmf(p);
@@ -381,48 +320,53 @@ public class VoipCloudModule extends ReactContextBaseJavaModule {
             Events.emit(getReactApplicationContext(), Events.CALL_DTMF_SENT, ev);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_DTMF", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_DTMF", "Failed to send DTMF", t);
         }
     }
 
-    /**
-     * Blind-transfer a call (REFER).  The Promise resolves once the
-     * REFER is *sent* — progress of the remote-side INVITE comes
-     * through `callTransferStatus` events (statusCode + finalNotify).
-     */
     @ReactMethod
     public void transferCall(int callId, String destinationUri, Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
+        if (!BridgeGuard.ensureInited(inited, promise)) return;
+        if (destinationUri == null || destinationUri.trim().isEmpty()) {
+            promise.reject("VC_INVALID_ARGUMENT", "destinationUri must not be empty");
+            return;
+        }
         try {
-            ManagedCall call = calls.get(callId);
-            if (call == null) { promise.reject("VC_NO_CALL", "unknown callId"); return; }
-            call.xfer(destinationUri, new CallOpParam(true));
+            ManagedCall call = requireCall(callId, promise);
+            if (call == null) return;
+            call.xfer(destinationUri.trim(), new CallOpParam(true));
             WritableMap ev = Arguments.createMap();
             ev.putInt("callId", callId);
-            ev.putString("destinationUri", destinationUri);
+            ev.putString("destinationUri", destinationUri.trim());
             Events.emit(getReactApplicationContext(), Events.CALL_TRANSFER, ev);
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_TRANSFER", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_TRANSFER", "Failed to transfer call", t);
         }
     }
 
-    /**
-     * End every active call in one shot.  Useful for SDK shutdown or
-     * a global "end all" UI action.  Each call still emits its own
-     * DISCONNECTED callState.
-     */
     @ReactMethod
     public void hangupAllCalls(Promise promise) {
+        if (!BridgeGuard.ensureNative(promise)) return;
         try {
-            if (endpoint != null) endpoint.hangupAllCalls();
+            if (endpoint != null && inited) endpoint.hangupAllCalls();
+            calls.clear();
             promise.resolve(null);
         } catch (Throwable t) {
-            promise.reject("VC_HANGUP_ALL", t.getMessage(), t);
+            BridgeGuard.reject(promise, "VC_HANGUP_ALL", "Failed to hang up all calls", t);
+        }
+    }
+
+    private ManagedCall requireCall(int callId, Promise promise) {
+        ManagedCall call = calls.get(callId);
+        if (call == null) {
+            promise.reject("VC_NO_CALL", "Unknown callId " + callId);
+            return null;
         }
+        return call;
     }
 
-    // RN event-emitter contract — required on RN 0.65+ when used with
-    // NativeEventEmitter on the JS side.
     @ReactMethod public void addListener(String eventName)   { /* no-op */ }
     @ReactMethod public void removeListeners(int count)      { /* no-op */ }
 }

package/android/src/main/java/com/voipcloud/sdk/rn/internal/BridgeGuard.java

@@ -0,0 +1,74 @@
+package com.voipcloud.sdk.rn.internal;
+
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReadableMap;
+
+/**
+ * Shared guards and input validation for the RN bridge — reject with clear
+ * VC_* codes instead of letting native/JNI exceptions crash the app.
+ */
+public final class BridgeGuard {
+
+    private static volatile boolean nativeLoaded = false;
+    private static volatile String nativeLoadError =
+            "libvoipcloud.so failed to load (missing ABI, stale build, or AAR not packaged)";
+
+    /** Loads libvoipcloud.so before any SWIG type (Endpoint, voipcloudJNI). */
+    static {
+        try {
+            System.loadLibrary("voipcloud");
+            nativeLoaded = true;
+        } catch (UnsatisfiedLinkError e) {
+            nativeLoadError = "Failed to load libvoipcloud.so: " + e.getMessage()
+                    + ". Ensure voipcloud-release.aar is included and the app was rebuilt.";
+        } catch (Throwable t) {
+            nativeLoadError = "Failed to load libvoipcloud.so: " + t.getMessage();
+        }
+    }
+
+    private BridgeGuard() {}
+
+    public static boolean isNativeLoaded() { return nativeLoaded; }
+
+    public static String nativeLoadError() { return nativeLoadError; }
+
+    /** Reject the promise if native .so did not load. Returns false when rejected. */
+    public static boolean ensureNative(Promise promise) {
+        if (nativeLoaded) return true;
+        promise.reject("VC_NATIVE_LOAD", nativeLoadError);
+        return false;
+    }
+
+    /** Reject if {@link VoipCloudModule} endpoint is not running. */
+    public static boolean ensureInited(boolean inited, Promise promise) {
+        if (inited) return true;
+        promise.reject("VC_NOT_INITIALIZED",
+                "VoipCloud.init() must succeed before calling this method.");
+        return false;
+    }
+
+    /**
+     * Read a required non-empty string field from a JS config object.
+     * Rejects with VC_INVALID_ARGUMENT and returns null on failure.
+     */
+    public static String requireString(ReadableMap map, String key, Promise promise) {
+        if (map == null || !map.hasKey(key) || map.isNull(key)) {
+            promise.reject("VC_INVALID_ARGUMENT", "Missing required field: " + key);
+            return null;
+        }
+        String value = map.getString(key);
+        if (value == null || value.trim().isEmpty()) {
+            promise.reject("VC_INVALID_ARGUMENT", "Field must not be empty: " + key);
+            return null;
+        }
+        return value.trim();
+    }
+
+    /** Reject with a stable code; message includes PJSIP detail when available. */
+    public static void reject(Promise promise, String code, String context, Throwable t) {
+        String detail = (t != null && t.getMessage() != null && !t.getMessage().isEmpty())
+                ? t.getMessage()
+                : (t != null ? t.getClass().getSimpleName() : "unknown error");
+        promise.reject(code, context + ": " + detail, t);
+    }
+}

package/android/src/main/java/com/voipcloud/sdk/rn/internal/Events.java

@@ -32,7 +32,12 @@ public final class Events {
 
     public static void emit(ReactContext ctx, String name, WritableMap payload) {
         if (ctx == null || !ctx.hasActiveReactInstance()) return;
-        ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
-           .emit(name, payload);
+        // PJSIP fires callbacks on its worker thread — hop to the RN UI queue
+        // so DeviceEventEmitter does not crash the app on some RN versions.
+        ctx.runOnUiQueueThread(() -> {
+            if (!ctx.hasActiveReactInstance()) return;
+            ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
+               .emit(name, payload);
+        });
     }
 }