react-native-nitro-location-tracking 0.1.12 → 0.1.14

package/README.md

@@ -453,6 +453,36 @@ NitroLocationModule.onProviderStatusChange((gps, network) => {
 });
 ```
 
+### Prompt user to enable GPS
+
+Ask the user to turn on device location. On Android this shows the native
+Google Play Services in-app dialog ("For better experience, turn on device
+location…") without leaving the app. On iOS there is no equivalent system
+dialog, so this opens your app's Settings page and resolves after the user
+returns to the app.
+
+```tsx
+import NitroLocationModule from 'react-native-nitro-location-tracking';
+
+async function ensureGpsOn() {
+  if (NitroLocationModule.isLocationServicesEnabled()) {
+    return true;
+  }
+  const enabled = await NitroLocationModule.openLocationSettings();
+  if (enabled) {
+    NitroLocationModule.startTracking();
+  } else {
+    // User declined the dialog (Android) or did not enable GPS (iOS)
+  }
+  return enabled;
+}
+```
+
+**Platform behavior:**
+
+- **Android** — Uses `SettingsClient.checkLocationSettings()` + `startResolutionForResult`. Resolves `true` if GPS is already on or if the user accepts the dialog, `false` if the user declines or the dialog cannot be shown.
+- **iOS** — Opens the app's Settings page via `UIApplication.openSettingsURLString` and listens for `UIApplication.didBecomeActiveNotification` to detect the return to foreground. Resolves `true` if `CLLocationManager.locationServicesEnabled()` is on after the user returns, `false` otherwise.
+
 ### Permission Status
 
 Check the current location permission status without prompting the user:
@@ -704,7 +734,10 @@ type PermissionStatus =
 | `getTripStats()`                             | `TripStats`                 | Get current trip stats without stopping                                                  |
 | `resetTripCalculation()`                     | `void`                      | Reset trip calculator                                                                    |
 | `isLocationServicesEnabled()`                | `boolean`                   | Check if GPS/location is enabled on device                                               |
+| `openLocationSettings()`                     | `Promise<boolean>`          | Prompt user to enable GPS. Resolves `true` if enabled, `false` if not                    |
 | `onProviderStatusChange(callback)`           | `void`                      | Register GPS/network provider status callback                                            |
+| `isAirplaneModeEnabled()`                    | `boolean`                   | Check if Airplane mode is active on Android                                              |
+| `onAirplaneModeChange(callback)`             | `void`                      | Register Airplane mode state-transition callback                                         |
 | `getLocationPermissionStatus()`              | `PermissionStatus`          | Check current location permission without prompting                                      |
 | `requestLocationPermission()`                | `Promise<PermissionStatus>` | Request location permission and return the resulting status                              |
 | `onPermissionStatusChange(callback)`         | `void`                      | Register a callback that fires when location permission status changes                   |
@@ -721,6 +754,25 @@ type PermissionStatus =
 | `shortestRotation(from, to)`  | Calculate shortest rotation path to avoid spinning         |
 | `requestLocationPermission()` | Request location + notification permissions (Android)      |
 
+### Pure C++ Math Engine
+
+For computationally heavy tasks like array slicing and trip mapping, use the pure C++ Math Engine to bypass the JS thread entirely.
+
+```typescript
+import { NitroLocationCalculations } from 'react-native-nitro-location-tracking';
+
+// Instantly compute heavy math directly in C++
+const stats = NitroLocationCalculations.calculateTotalTripStats(points);
+```
+
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `calculateTotalTripStats(points)` | `TripMathStats` | Instantly computes exact Haversine distance, time, and max/average speed over an array of thousands of points. |
+| `filterAnomalousPoints(points, maxSpeedMps)` | `LocationPoint[]` | Cleans an array of points by mathematically stripping out teleportation jumps that exceed the given speed limit. |
+| `smoothPath(points, toleranceMeters)` | `LocationPoint[]` | Simplifies a highly dense GPS path into perfect drawing lines using the Ramer-Douglas-Peucker algorithm. |
+| `calculateBearing(lat1, lon1, lat2, lon2)` | `number` | Lightning fast C++ trigonometric bearing computation for raw coordinates. |
+| `encodeGeohash(lat, lon, precision)` | `string` | Converts coordinates into a Geohash string instantly representing geological boundaries. |
+
 ## Publishing to npm
 
 ### Prerequisites

package/android/CMakeLists.txt

@@ -6,7 +6,10 @@ set(CMAKE_VERBOSE_MAKEFILE ON)
 set(CMAKE_CXX_STANDARD 20)
 
 # Define C++ library and add all sources
-add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+add_library(${PACKAGE_NAME} SHARED 
+  src/main/cpp/cpp-adapter.cpp
+  ../cpp/HybridNitroLocationComplexLogicsCalculation.cpp
+)
 
 # Add Nitrogen specs :)
 include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/nitrolocationtracking+autolinking.cmake)

package/android/src/main/java/com/margelo/nitro/nitrolocationtracking/AirplaneModeMonitor.kt

@@ -0,0 +1,72 @@
+package com.margelo.nitro.nitrolocationtracking
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.Build
+import android.provider.Settings
+import android.util.Log
+
+class AirplaneModeMonitor(private val context: Context) {
+
+    companion object {
+        private const val TAG = "AirplaneModeMonitor"
+    }
+
+    private var callback: ((Boolean) -> Unit)? = null
+    private var lastState: Boolean? = null
+    private var receiver: BroadcastReceiver? = null
+
+    fun setCallback(callback: (Boolean) -> Unit) {
+        this.callback = callback
+        
+        // Emit current state immediately
+        val current = isAirplaneModeEnabled()
+        lastState = current
+        callback.invoke(current)
+        
+        registerReceiver()
+    }
+
+    fun isAirplaneModeEnabled(): Boolean {
+        return Settings.Global.getInt(
+            context.contentResolver,
+            Settings.Global.AIRPLANE_MODE_ON, 0
+        ) != 0
+    }
+
+    private fun registerReceiver() {
+        if (receiver != null) return
+
+        receiver = object : BroadcastReceiver() {
+            override fun onReceive(context: Context?, intent: Intent?) {
+                if (intent?.action == Intent.ACTION_AIRPLANE_MODE_CHANGED) {
+                    val isAirplaneModeOn = intent.getBooleanExtra("state", false)
+                    if (isAirplaneModeOn != lastState) {
+                        lastState = isAirplaneModeOn
+                        Log.d(TAG, "Airplane mode changed: $isAirplaneModeOn")
+                        callback?.invoke(isAirplaneModeOn)
+                    }
+                }
+            }
+        }
+
+        val filter = IntentFilter(Intent.ACTION_AIRPLANE_MODE_CHANGED)
+        context.registerReceiver(receiver, filter)
+        Log.d(TAG, "Airplane mode receiver registered")
+    }
+
+    fun destroy() {
+        receiver?.let {
+            try {
+                context.unregisterReceiver(it)
+            } catch (e: Exception) {
+                Log.w(TAG, "Error unregistering receiver: ${e.message}")
+            }
+        }
+        receiver = null
+        callback = null
+        lastState = null
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrolocationtracking/LocationEngine.kt

@@ -34,7 +34,7 @@ class LocationEngine(private val context: Context) {
   val isTracking: Boolean get() = tracking
 
   @SuppressLint("MissingPermission")
-  fun start(config: LocationConfig) {
+  fun start(config: LocationConfig): Boolean {
     if (tracking) {
       locationCallback?.let { fusedClient.removeLocationUpdates(it) }
     }
@@ -59,9 +59,25 @@ class LocationEngine(private val context: Context) {
         Log.d(TAG, "onLocationAvailability — isLocationAvailable=${availability.isLocationAvailable}")
       }
     }
-    fusedClient.requestLocationUpdates(
-      request, locationCallback!!, Looper.getMainLooper())
-    tracking = true
+    return try {
+      fusedClient.requestLocationUpdates(
+        request, locationCallback!!, Looper.getMainLooper())
+      tracking = true
+      true
+    } catch (e: SecurityException) {
+      // Permission was revoked between our caller's check and this call, or
+      // the FusedLocationProvider is otherwise refusing access. Fail closed
+      // instead of crashing the process.
+      Log.w(TAG, "requestLocationUpdates refused — permission missing: ${e.message}")
+      locationCallback = null
+      tracking = false
+      false
+    } catch (e: Exception) {
+      Log.e(TAG, "requestLocationUpdates failed: ${e.message}")
+      locationCallback = null
+      tracking = false
+      false
+    }
   }
 
   fun stop() {
@@ -72,13 +88,18 @@ class LocationEngine(private val context: Context) {
 
   @SuppressLint("MissingPermission")
   fun getCurrentLocation(callback: (LocationData?) -> Unit) {
-    fusedClient.lastLocation.addOnSuccessListener { location ->
-      if (location != null) {
-        callback(locationToData(location))
-      } else {
+    try {
+      fusedClient.lastLocation.addOnSuccessListener { location ->
+        if (location != null) {
+          callback(locationToData(location))
+        } else {
+          callback(null)
+        }
+      }.addOnFailureListener {
         callback(null)
       }
-    }.addOnFailureListener {
+    } catch (e: SecurityException) {
+      Log.w(TAG, "getCurrentLocation refused — permission missing: ${e.message}")
       callback(null)
     }
   }

package/android/src/main/java/com/margelo/nitro/nitrolocationtracking/NitroLocationTracking.kt

@@ -1,13 +1,17 @@
 package com.margelo.nitro.nitrolocationtracking
 
+import android.app.Activity
+import android.content.Intent
 import android.content.pm.PackageManager
 import android.util.Log
 import androidx.core.app.ActivityCompat
 import androidx.core.content.ContextCompat
 import com.facebook.proguard.annotations.DoNotStrip
+import com.facebook.react.bridge.BaseActivityEventListener
 import com.facebook.react.bridge.ReactContext
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
+import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 import kotlin.coroutines.suspendCoroutine
@@ -18,6 +22,7 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
     companion object {
         private const val TAG = "NitroLocationTracking"
         private const val PERMISSION_REQUEST_CODE = 9001
+        private const val GPS_RESOLUTION_REQUEST_CODE = 9002
     }
 
     private var locationEngine: LocationEngine? = null
@@ -28,6 +33,7 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
     private var providerStatusMonitor: ProviderStatusMonitor? = null
     private var permissionStatusMonitor: PermissionStatusMonitor? = null
     private var mockLocationMonitor: MockLocationMonitor? = null
+    private var airplaneModeMonitor: AirplaneModeMonitor? = null
 
     private var locationCallback: ((LocationData) -> Unit)? = null
     private var motionCallback: ((Boolean) -> Unit)? = null
@@ -38,6 +44,7 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
     private var providerStatusCallback: ((LocationProviderStatus, LocationProviderStatus) -> Unit)? = null
     private var permissionStatusCallback: ((PermissionStatus) -> Unit)? = null
     private var mockLocationCallback: ((Boolean) -> Unit)? = null
+    private var airplaneModeCallback: ((Boolean) -> Unit)? = null
 
     private var locationConfig: LocationConfig? = null
 
@@ -56,8 +63,29 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
         providerStatusMonitor = ProviderStatusMonitor(context)
         permissionStatusMonitor = PermissionStatusMonitor(context)
         mockLocationMonitor = MockLocationMonitor(context)
+        airplaneModeMonitor = AirplaneModeMonitor(context)
         locationEngine?.dbWriter = dbWriter
         connectionManager.dbWriter = dbWriter
+
+        // Always watch for permission revocation so we can proactively tear
+        // down tracking + the foreground service before the OS kills us for
+        // holding a location-type FGS without the matching permission.
+        permissionStatusMonitor?.setInternalCallback { status ->
+            if (status == PermissionStatus.DENIED || status == PermissionStatus.RESTRICTED) {
+                Log.w(TAG, "Location permission revoked — stopping tracking and foreground service")
+                try {
+                    locationEngine?.stop()
+                } catch (e: Exception) {
+                    Log.w(TAG, "Error stopping location engine: ${e.message}")
+                }
+                try {
+                    notificationService?.stopForegroundService()
+                } catch (e: Exception) {
+                    Log.w(TAG, "Error stopping foreground service: ${e.message}")
+                }
+            }
+        }
+
         Log.d(TAG, "Components initialized successfully")
         return true
     }
@@ -78,6 +106,20 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
             Log.e(TAG, "startTracking failed — could not initialize components")
             return
         }
+
+        // Permission guard. Starting a foreground service of type `location`
+        // without holding ACCESS_FINE_LOCATION throws SecurityException on
+        // Android 14+. And even on older versions, requestLocationUpdates
+        // will throw SecurityException. Fail closed and notify JS instead
+        // of crashing the process.
+        val permissionStatus = getLocationPermissionStatus()
+        if (permissionStatus == PermissionStatus.DENIED ||
+            permissionStatus == PermissionStatus.RESTRICTED) {
+            Log.w(TAG, "startTracking aborted — location permission is $permissionStatus")
+            permissionStatusCallback?.invoke(permissionStatus)
+            return
+        }
+
         val engine = locationEngine ?: return
         engine.onLocation = { data ->
             locationCallback?.invoke(data)
@@ -85,7 +127,14 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
         engine.onMotionChange = { isMoving ->
             motionCallback?.invoke(isMoving)
         }
-        engine.start(config)
+        val started = engine.start(config)
+        if (!started) {
+            // engine.start() already logged the reason. Don't start the FGS
+            // if tracking itself could not be started — the FGS would just
+            // be killed immediately by the OS.
+            Log.w(TAG, "startTracking aborted — location engine refused to start")
+            return
+        }
 
         try {
             notificationService?.startForegroundService(
@@ -94,6 +143,12 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
             )
         } catch (e: SecurityException) {
             Log.w(TAG, "Could not start foreground service — missing runtime permissions: ${e.message}")
+            // Roll back the tracking session so we don't leak a location
+            // request with no owning foreground service.
+            try { engine.stop() } catch (_: Exception) {}
+        } catch (e: Exception) {
+            Log.w(TAG, "Could not start foreground service: ${e.message}")
+            try { engine.stop() } catch (_: Exception) {}
         }
     }
 
@@ -364,6 +419,122 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
         }
     }
 
+    override fun openLocationSettings(): Promise<Boolean> {
+        return Promise.async {
+            suspendCoroutine { cont ->
+                val context = NitroModules.applicationContext
+                if (context == null) {
+                    cont.resume(false)
+                    return@suspendCoroutine
+                }
+
+                val reactContext = context as? ReactContext
+                val activity = reactContext?.currentActivity
+                if (reactContext == null || activity == null) {
+                    Log.w(TAG, "openLocationSettings — no current Activity, using fallback")
+                    openLocationSettingsFallback(context)
+                    cont.resume(isLocationServicesEnabled())
+                    return@suspendCoroutine
+                }
+
+                // Use a high-accuracy location request for the settings check.
+                // These values are internal to the SettingsClient call — they do
+                // not affect the tracking configuration.
+                val locationRequest = com.google.android.gms.location.LocationRequest.Builder(
+                    com.google.android.gms.location.Priority.PRIORITY_HIGH_ACCURACY,
+                    10_000L
+                ).build()
+
+                val settingsRequest = com.google.android.gms.location.LocationSettingsRequest.Builder()
+                    .addLocationRequest(locationRequest)
+                    .setAlwaysShow(true)
+                    .build()
+
+                val client = com.google.android.gms.location.LocationServices.getSettingsClient(context)
+                val task = client.checkLocationSettings(settingsRequest)
+
+                // Guard against double-resume — the continuation may otherwise
+                // be resumed by both the success listener and the activity
+                // result listener in rare race conditions.
+                val resumed = AtomicBoolean(false)
+                fun safeResume(value: Boolean) {
+                    if (resumed.compareAndSet(false, true)) {
+                        cont.resume(value)
+                    }
+                }
+
+                task.addOnSuccessListener {
+                    // Location settings are already satisfied — GPS is on.
+                    safeResume(true)
+                }
+
+                task.addOnFailureListener { exception ->
+                    if (exception is com.google.android.gms.common.api.ResolvableApiException) {
+                        // Register the activity result listener BEFORE showing
+                        // the dialog so we cannot miss the result.
+                        val listener = object : BaseActivityEventListener() {
+                            override fun onActivityResult(
+                                activity: Activity?,
+                                requestCode: Int,
+                                resultCode: Int,
+                                data: Intent?
+                            ) {
+                                if (requestCode != GPS_RESOLUTION_REQUEST_CODE) return
+                                reactContext.removeActivityEventListener(this)
+                                // RESULT_OK = user tapped "OK" in the dialog and GPS is now on.
+                                // RESULT_CANCELED = user tapped "No thanks" or dismissed.
+                                val enabled = resultCode == Activity.RESULT_OK
+                                safeResume(enabled)
+                            }
+                        }
+                        reactContext.addActivityEventListener(listener)
+
+                        try {
+                            exception.startResolutionForResult(
+                                activity, GPS_RESOLUTION_REQUEST_CODE
+                            )
+                        } catch (e: Exception) {
+                            Log.w(TAG, "Failed to show resolution dialog: ${e.message}")
+                            reactContext.removeActivityEventListener(listener)
+                            openLocationSettingsFallback(context)
+                            safeResume(isLocationServicesEnabled())
+                        }
+                    } else {
+                        // Not resolvable (e.g. SETTINGS_CHANGE_UNAVAILABLE on an
+                        // airplane-mode-locked device) — fall back to the system
+                        // settings screen.
+                        Log.w(TAG, "Location settings not resolvable: ${exception.message}")
+                        openLocationSettingsFallback(context)
+                        safeResume(isLocationServicesEnabled())
+                    }
+                }
+            }
+        }
+    }
+
+    private fun openLocationSettingsFallback(context: android.content.Context) {
+        val intent = android.content.Intent(android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS)
+        intent.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)
+        try {
+            context.startActivity(intent)
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to open location settings: ${e.message}")
+        }
+    }
+
+    // === Device State Monitoring ===
+    
+    override fun isAirplaneModeEnabled(): Boolean {
+        ensureInitialized()
+        return airplaneModeMonitor?.isAirplaneModeEnabled() ?: false
+    }
+
+    override fun onAirplaneModeChange(callback: (isEnabled: Boolean) -> Unit) {
+        airplaneModeCallback = callback
+        ensureInitialized()
+        airplaneModeMonitor?.setCallback(callback)
+    }
+
     // === Distance Utilities ===
 
     override fun getDistanceBetween(lat1: Double, lon1: Double, lat2: Double, lon2: Double): Double {
@@ -399,5 +570,6 @@ class NitroLocationTracking : HybridNitroLocationTrackingSpec() {
         providerStatusMonitor?.destroy()
         permissionStatusMonitor?.destroy()
         mockLocationMonitor?.destroy()
+        airplaneModeMonitor?.destroy()
     }
 }

package/android/src/main/java/com/margelo/nitro/nitrolocationtracking/PermissionStatusMonitor.kt

@@ -25,7 +25,9 @@ class PermissionStatusMonitor(private val context: Context) {
     }
 
     private var callback: ((PermissionStatus) -> Unit)? = null
+    private var internalCallback: ((PermissionStatus) -> Unit)? = null
     private var lastStatus: PermissionStatus? = null
+    private var observerRegistered = false
     private val mainHandler = Handler(Looper.getMainLooper())
 
     private val lifecycleObserver = object : DefaultLifecycleObserver {
@@ -36,8 +38,25 @@ class PermissionStatusMonitor(private val context: Context) {
 
     fun setCallback(callback: (PermissionStatus) -> Unit) {
         this.callback = callback
+        ensureObserverRegistered()
+    }
+
+    /**
+     * Internal callback used by the native module to react to permission loss
+     * (e.g. auto-stop tracking) independently of any JS listener. Registering
+     * this also starts the lifecycle observer, so native cleanup works even
+     * when the user has not called onPermissionStatusChange() from JS.
+     */
+    fun setInternalCallback(callback: (PermissionStatus) -> Unit) {
+        this.internalCallback = callback
+        ensureObserverRegistered()
+    }
+
+    private fun ensureObserverRegistered() {
+        if (observerRegistered) return
         // Capture the current status so we only fire on actual changes
         lastStatus = getCurrentPermissionStatus()
+        observerRegistered = true
 
         // addObserver MUST be called on the main thread
         mainHandler.post {
@@ -46,6 +65,7 @@ class PermissionStatusMonitor(private val context: Context) {
                 Log.d(TAG, "Registered lifecycle observer for permission changes")
             } catch (e: Exception) {
                 Log.e(TAG, "Failed to register lifecycle observer: ${e.message}")
+                observerRegistered = false
             }
         }
     }
@@ -55,6 +75,10 @@ class PermissionStatusMonitor(private val context: Context) {
         if (current != lastStatus) {
             Log.d(TAG, "Permission status changed: $lastStatus -> $current")
             lastStatus = current
+            // Native cleanup first, JS notification second — so by the time JS
+            // hears about the denial, the native side has already released
+            // resources (tracking session, foreground service).
+            internalCallback?.invoke(current)
             callback?.invoke(current)
         }
     }
@@ -86,7 +110,9 @@ class PermissionStatusMonitor(private val context: Context) {
                 ProcessLifecycleOwner.get().lifecycle.removeObserver(lifecycleObserver)
             } catch (_: Exception) {}
         }
+        observerRegistered = false
         callback = null
+        internalCallback = null
         lastStatus = null
     }
 }