react-native-nitro-geolocation 1.3.3 → 1.4.1

package/README.md

@@ -112,12 +112,15 @@ for the full compatibility matrix and option notes.
 ### 3. Background API
 
 Native background tracking, geofencing, activity events, Android Headless JS,
-HTTP sync, and stored event recovery should use the explicit background subpath.
+HTTP sync, stored event recovery, and silent-delivery diagnosis should use the
+explicit background subpath.
 
 Background location is native-only. Browser builds expose unsupported stubs so
 web bundles can still import shared code safely. Start with the
 [Background Location guide](https://react-native-nitro-geolocation.pages.dev/background/overview)
 for permissions, start/stop, geofencing, storage recovery, and native sync.
+Use `diagnoseBackgroundLocation()` from the same subpath to turn the raw
+background status into actionable issues when delivery is silent.
 
 ---
 
@@ -218,7 +221,7 @@ Use the docs site for the detailed flows:
 - [Quick Start](https://react-native-nitro-geolocation.pages.dev/guide/quick-start) - install, set native permissions, and read your first location.
 - [Modern API](https://react-native-nitro-geolocation.pages.dev/guide/modern-api) - accuracy presets, watches, Android settings, cached reads, geocoding, heading, and iOS accuracy authorization.
 - [Compat API](https://react-native-nitro-geolocation.pages.dev/guide/compat-api) - callback compatibility and web behavior.
-- [Background Location](https://react-native-nitro-geolocation.pages.dev/background/overview) - native background tracking, geofencing, storage recovery, Headless JS, and HTTP sync.
+- [Background Location](https://react-native-nitro-geolocation.pages.dev/background/overview) - native background tracking, geofencing, storage recovery, Headless JS, HTTP sync, and delivery diagnosis.
 - [Migration Assistance](https://react-native-nitro-geolocation.pages.dev/guide/migration-assistance) - choose the community or service migration path.
 - [Expo Development Builds](https://react-native-nitro-geolocation.pages.dev/guide/expo-development-build) - use the package in Expo custom native builds.
 - [DevTools Plugin](https://react-native-nitro-geolocation.pages.dev/guide/devtools) - mock locations during development.

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/BackgroundDecisions.kt

@@ -50,3 +50,12 @@ internal fun resolveMaxStored(configured: Int?, default: Int): Int {
         else -> configured
     }
 }
+
+/**
+ * Headless JS is the fallback path when no in-process JS listener received the native event. If a
+ * live listener already handled the event, starting Headless JS duplicates delivery and React
+ * Native warns when the app did not register NitroBackgroundLocationTask.
+ */
+internal fun shouldDispatchHeadlessTask(deliveredToInProcessListener: Boolean): Boolean {
+    return !deliveredToInProcessListener
+}

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundEventHub.kt

@@ -45,22 +45,27 @@ class NitroBackgroundEventHub {
         errorListeners.remove(token)
     }
 
-    fun emit(event: BackgroundEventEnvelope) {
+    fun emit(event: BackgroundEventEnvelope): Boolean {
+        var delivered = eventListeners.isNotEmpty()
         eventListeners.values.forEach { listener -> dispatch { listener(event) } }
 
         when (event.type) {
             BackgroundEventType.LOCATION -> {
                 event.location?.let { location ->
+                    delivered = delivered || locationListeners.isNotEmpty()
                     locationListeners.values.forEach { listener -> dispatch { listener(location) } }
                 }
             }
             BackgroundEventType.ERROR -> {
                 event.error?.let { error ->
+                    delivered = delivered || errorListeners.isNotEmpty()
                     errorListeners.values.forEach { listener -> dispatch { listener(error) } }
                 }
             }
             else -> Unit
         }
+
+        return delivered
     }
 
     // Listeners run inline on the caller's thread (often the broadcast receiver thread). Isolate

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundLocationController.kt

@@ -604,7 +604,8 @@ class NitroBackgroundLocationController private constructor(
     }
 
     private fun dispatchEvent(event: BackgroundEventEnvelope) {
-        eventHub.emit(event)
+        val deliveredToInProcessListener = eventHub.emit(event)
+        if (!shouldDispatchHeadlessTask(deliveredToInProcessListener)) return
         // The in-process eventHub already delivered to any live JS listeners; the headless task is
         // the fallback for when JS is dead. Guard its start: startService from the background can be
         // rejected (ForegroundServiceStartNotAllowed / IllegalState), which must not crash the

package/android/src/test/java/com/margelo/nitro/nitrogeolocation/background/BackgroundDecisionsTest.kt

@@ -64,4 +64,14 @@ class BackgroundDecisionsTest {
         assertEquals(0, resolveMaxStored(0, 10_000))
         assertEquals(0, resolveMaxStored(-5, 10_000))
     }
+
+    @Test
+    fun headlessTaskIsSkippedWhenInProcessListenerReceivedEvent() {
+        assertFalse(shouldDispatchHeadlessTask(true))
+    }
+
+    @Test
+    fun headlessTaskRunsWhenNoInProcessListenerReceivedEvent() {
+        assertTrue(shouldDispatchHeadlessTask(false))
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Nitro-powered native geolocation for modern React Native apps",
   "main": "src/index",
   "source": "src/index",

package/src/background/index.ts

@@ -8,6 +8,7 @@ import type {
   BackgroundGeofenceEventEnvelope,
   BackgroundHttpSyncEvent,
   BackgroundLocation,
+  BackgroundLocationStatus,
   BackgroundSubscription,
   StoredBackgroundEvent,
   StoredBackgroundEventEnvelope
@@ -65,10 +66,7 @@ export const getBackgroundConfiguration =
     NativeBackgroundLocation
   );
 export const startBackgroundLocation: NitroBackgroundLocation["startBackgroundLocation"] =
-  (options) =>
-    NativeBackgroundLocation.startBackgroundLocation(
-      options ?? (undefined as any)
-    );
+  (options) => NativeBackgroundLocation.startBackgroundLocation(options);
 export const stopBackgroundLocation =
   NativeBackgroundLocation.stopBackgroundLocation.bind(
     NativeBackgroundLocation
@@ -82,15 +80,9 @@ export const getBackgroundLocationStatus =
     NativeBackgroundLocation
   );
 export const getStoredBackgroundLocations: NitroBackgroundLocation["getStoredBackgroundLocations"] =
-  (options) =>
-    NativeBackgroundLocation.getStoredBackgroundLocations(
-      options ?? (undefined as any)
-    );
+  (options) => NativeBackgroundLocation.getStoredBackgroundLocations(options);
 export const clearStoredBackgroundLocations: NitroBackgroundLocation["clearStoredBackgroundLocations"] =
-  (ids) =>
-    NativeBackgroundLocation.clearStoredBackgroundLocations(
-      ids ?? (undefined as any)
-    );
+  (ids) => NativeBackgroundLocation.clearStoredBackgroundLocations(ids);
 export const markStoredBackgroundLocationsDelivered =
   NativeBackgroundLocation.markStoredBackgroundLocationsDelivered.bind(
     NativeBackgroundLocation
@@ -98,19 +90,15 @@ export const markStoredBackgroundLocationsDelivered =
 export async function getStoredBackgroundEvents(
   options?: Parameters<NitroBackgroundLocation["getStoredBackgroundEvents"]>[0]
 ): Promise<StoredBackgroundEvent[]> {
-  const events = await NativeBackgroundLocation.getStoredBackgroundEvents(
-    options ?? (undefined as any)
-  );
+  const events =
+    await NativeBackgroundLocation.getStoredBackgroundEvents(options);
   return events.map((event: StoredBackgroundEventEnvelope) => ({
     ...event,
     event: narrowBackgroundEvent(event.event)
   }));
 }
 export const clearStoredBackgroundEvents: NitroBackgroundLocation["clearStoredBackgroundEvents"] =
-  (ids) =>
-    NativeBackgroundLocation.clearStoredBackgroundEvents(
-      ids ?? (undefined as any)
-    );
+  (ids) => NativeBackgroundLocation.clearStoredBackgroundEvents(ids);
 export const markStoredBackgroundEventsDelivered =
   NativeBackgroundLocation.markStoredBackgroundEventsDelivered.bind(
     NativeBackgroundLocation
@@ -120,17 +108,13 @@ export const addGeofences = NativeBackgroundLocation.addGeofences.bind(
 );
 export const removeGeofences: NitroBackgroundLocation["removeGeofences"] = (
   identifiers
-) =>
-  NativeBackgroundLocation.removeGeofences(identifiers ?? (undefined as any));
+) => NativeBackgroundLocation.removeGeofences(identifiers);
 export const getRegisteredGeofences =
   NativeBackgroundLocation.getRegisteredGeofences.bind(
     NativeBackgroundLocation
   );
 export const startActivityRecognition: NitroBackgroundLocation["startActivityRecognition"] =
-  (options) =>
-    NativeBackgroundLocation.startActivityRecognition(
-      options ?? (undefined as any)
-    );
+  (options) => NativeBackgroundLocation.startActivityRecognition(options);
 export const stopActivityRecognition =
   NativeBackgroundLocation.stopActivityRecognition.bind(
     NativeBackgroundLocation
@@ -138,6 +122,79 @@ export const stopActivityRecognition =
 export const syncStoredLocations =
   NativeBackgroundLocation.syncStoredLocations.bind(NativeBackgroundLocation);
 
+export interface BackgroundLocationDiagnosis {
+  /** True when no blocking issues were found. */
+  healthy: boolean;
+  /** The raw status the diagnosis was derived from. */
+  status: BackgroundLocationStatus;
+  /** Human-readable, actionable reasons delivery may not be working. Empty when healthy. */
+  issues: string[];
+}
+
+/**
+ * Inspects the current background-location status and returns actionable reasons why location
+ * delivery may not be working. Useful when the pipeline is silent: it surfaces the common causes
+ * (a recorded native error, missing permissions, disabled location services, or a service that is
+ * configured but not yet delivering) without the caller having to interpret the raw status object.
+ */
+export async function diagnoseBackgroundLocation(): Promise<BackgroundLocationDiagnosis> {
+  const status = await getBackgroundLocationStatus();
+  const issues: string[] = [];
+
+  if (status.lastError) {
+    issues.push(
+      `Last native error: ${status.lastError.message} (code ${status.lastError.code}).`
+    );
+  }
+  if (status.foregroundPermission !== "granted") {
+    issues.push(
+      `Foreground location permission is "${status.foregroundPermission}", not "granted".`
+    );
+  }
+  if (status.backgroundPermission !== "granted") {
+    issues.push(
+      `Background location permission is "${status.backgroundPermission}", not "granted".`
+    );
+  }
+  if (!status.locationServicesEnabled) {
+    issues.push("Device location services are turned off.");
+  }
+  if (status.isConfigured && !status.isRunning) {
+    issues.push(
+      "Tracking is configured but not running — call startBackgroundLocation()."
+    );
+  }
+  if (status.isRunning && status.state !== "running") {
+    issues.push(
+      `Service is started but not yet delivering (state: "${status.state}").`
+    );
+  }
+  if (
+    status.isRunning &&
+    status.state === "running" &&
+    status.storedLocationCount === 0
+  ) {
+    issues.push(
+      "Running with no stored locations yet — the provider may have no fix, or distanceFilter/interval is filtering updates."
+    );
+  }
+  if (status.android) {
+    if (status.isRunning && !status.android.isForegroundServiceRunning) {
+      issues.push("Android foreground service is not running.");
+    }
+    if (
+      status.android.notificationPermission &&
+      status.android.notificationPermission !== "granted"
+    ) {
+      issues.push(
+        `Android notification permission is "${status.android.notificationPermission}" — the foreground-service notification may be suppressed.`
+      );
+    }
+  }
+
+  return { healthy: issues.length === 0, status, issues };
+}
+
 export function onBackgroundEvent(
   listener: (event: BackgroundEvent) => void
 ): BackgroundSubscription {