react-native-nitro-geolocation 1.1.3 → 1.2.0

package/src/types.ts

@@ -1,40 +1,33 @@
-// Public API types (compatible with @react-native-community/geolocation)
-export type AuthorizationLevel = "always" | "whenInUse" | "auto";
-export type LocationProvider = "playServices" | "android" | "auto";
+// Shared Nitro schema structs. Public entry points re-export inferred aliases
+// from the Nitro/Compat specs in publicTypes.ts.
+export type LocationProviderUsed =
+  | "fused"
+  | "gps"
+  | "network"
+  | "passive"
+  | "unknown";
 export type NullableDouble = number | null;
+export type AndroidAccuracyPreset = "high" | "balanced" | "low" | "passive";
+export type AndroidGranularity = "permission" | "coarse" | "fine";
+export type IOSAccuracyPreset =
+  | "bestForNavigation"
+  | "best"
+  | "nearestTenMeters"
+  | "hundredMeters"
+  | "kilometer"
+  | "threeKilometers"
+  | "reduced";
+export type AccuracyAuthorization = "full" | "reduced" | "unknown";
+export type IOSActivityType =
+  | "other"
+  | "automotiveNavigation"
+  | "fitness"
+  | "otherNavigation"
+  | "airborne";
 
-/**
- * User-facing geolocation configuration.
- * This uses "android" instead of "android_platform" for better DX.
- */
-export interface ModernGeolocationConfiguration {
-  /**
-   * Automatically request location permission when GeolocationProvider mounts.
-   * @default false
-   */
-  autoRequestPermission?: boolean;
-
-  /**
-   * iOS: Authorization level
-   */
-  authorizationLevel?: AuthorizationLevel;
-
-  /**
-   * iOS: Enable background location updates.
-   */
-  enableBackgroundLocationUpdates?: boolean;
-
-  /**
-   * Android: Location provider
-   */
-  locationProvider?: LocationProvider;
-}
-
-export interface GeolocationConfiguration {
-  skipPermissionRequests: boolean;
-  authorizationLevel?: AuthorizationLevel;
-  enableBackgroundLocationUpdates?: boolean;
-  locationProvider?: LocationProvider;
+export interface LocationAccuracyOptions {
+  android?: AndroidAccuracyPreset;
+  ios?: IOSAccuracyPreset;
 }
 
 export interface GeolocationCoordinates {
@@ -50,9 +43,88 @@ export interface GeolocationCoordinates {
 export interface GeolocationResponse {
   coords: GeolocationCoordinates;
   timestamp: number;
+  mocked?: boolean;
+  provider?: LocationProviderUsed;
+}
+
+export interface LocationAvailability {
+  available: boolean;
+  reason?: string;
+}
+
+export interface Heading {
+  magneticHeading: number;
+  trueHeading?: number;
+  accuracy?: number;
+  timestamp: number;
+}
+
+export interface HeadingOptions {
+  headingFilter?: number;
+}
+
+export interface GeocodingCoordinates {
+  latitude: number;
+  longitude: number;
+}
+
+export interface GeocodedLocation {
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+}
+
+export interface ReverseGeocodedAddress {
+  country?: string;
+  region?: string;
+  city?: string;
+  district?: string;
+  street?: string;
+  postalCode?: string;
+  formattedAddress?: string;
+}
+
+/**
+ * Native provider/settings status.
+ *
+ * Android includes device-level location services, provider availability, and
+ * Google Location Accuracy when Google Play Services exposes it.
+ *
+ * iOS includes only Core Location service availability and app background
+ * location mode. Android-specific provider fields are `undefined` on iOS.
+ */
+export interface LocationProviderStatus {
+  /** Android system location switch, or iOS Core Location services state. */
+  locationServicesEnabled: boolean;
+
+  /**
+   * iOS: whether `UIBackgroundModes` contains `location`.
+   * Android: whether background location permission is granted.
+   */
+  backgroundModeEnabled: boolean;
+
+  /** Android-only GPS provider availability. Undefined on iOS. */
+  gpsAvailable?: boolean;
+
+  /** Android-only network provider availability. Undefined on iOS. */
+  networkAvailable?: boolean;
+
+  /** Android-only passive provider availability. Undefined on iOS. */
+  passiveAvailable?: boolean;
+
+  /**
+   * Android-only Google Location Accuracy state when Google Play Services
+   * exposes it. Undefined on iOS or when unavailable.
+   */
+  googleLocationAccuracyEnabled?: boolean;
+}
+
+export interface CompatGeolocationResponse {
+  coords: GeolocationCoordinates;
+  timestamp: number;
 }
 
-export interface GeolocationError {
+export interface CompatGeolocationError {
   code: number;
   message: string;
   PERMISSION_DENIED: number;
@@ -60,12 +132,16 @@ export interface GeolocationError {
   TIMEOUT: number;
 }
 
-export interface GeolocationOptions {
+export interface CompatGeolocationOptions {
   timeout?: number;
   maximumAge?: number;
   enableHighAccuracy?: boolean;
+  accuracy?: LocationAccuracyOptions;
   interval?: number;
   fastestInterval?: number;
   distanceFilter?: number;
   useSignificantChanges?: boolean;
+  activityType?: IOSActivityType;
+  pausesLocationUpdatesAutomatically?: boolean;
+  showsBackgroundLocationIndicator?: boolean;
 }

package/src/utils/errors.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import {
+  LocationErrorCode,
+  createLocationError,
+  getLocationErrorCodeName,
+  mapAndroidException,
+  mapCLErrorCode
+} from "./errors";
+
+describe("LocationErrorCode", () => {
+  it("keeps legacy-compatible codes and adds modern-only error codes", () => {
+    expect(LocationErrorCode.INTERNAL_ERROR).toBe(-1);
+    expect(LocationErrorCode.PERMISSION_DENIED).toBe(1);
+    expect(LocationErrorCode.POSITION_UNAVAILABLE).toBe(2);
+    expect(LocationErrorCode.TIMEOUT).toBe(3);
+    expect(LocationErrorCode.PLAY_SERVICE_NOT_AVAILABLE).toBe(4);
+    expect(LocationErrorCode.SETTINGS_NOT_SATISFIED).toBe(5);
+  });
+
+  it("creates the same plain LocationError shape native sends to JS", () => {
+    const error = createLocationError(
+      LocationErrorCode.SETTINGS_NOT_SATISFIED,
+      "Location settings are disabled"
+    );
+
+    expect(error).toEqual({
+      code: LocationErrorCode.SETTINGS_NOT_SATISFIED,
+      message: "Location settings are disabled"
+    });
+  });
+
+  it("maps platform-specific error sources", () => {
+    expect(mapCLErrorCode(0)).toBe(LocationErrorCode.POSITION_UNAVAILABLE);
+    expect(mapCLErrorCode(1)).toBe(LocationErrorCode.PERMISSION_DENIED);
+    expect(mapAndroidException("SecurityException")).toBe(
+      LocationErrorCode.PERMISSION_DENIED
+    );
+    expect(mapAndroidException("ResolvableApiException")).toBe(
+      LocationErrorCode.SETTINGS_NOT_SATISFIED
+    );
+    expect(mapAndroidException("GooglePlayServicesNotAvailableException")).toBe(
+      LocationErrorCode.PLAY_SERVICE_NOT_AVAILABLE
+    );
+  });
+
+  it("returns stable names for code display", () => {
+    expect(getLocationErrorCodeName(LocationErrorCode.INTERNAL_ERROR)).toBe(
+      "INTERNAL_ERROR"
+    );
+    expect(getLocationErrorCodeName(LocationErrorCode.PERMISSION_DENIED)).toBe(
+      "PERMISSION_DENIED"
+    );
+    expect(
+      getLocationErrorCodeName(LocationErrorCode.POSITION_UNAVAILABLE)
+    ).toBe("POSITION_UNAVAILABLE");
+    expect(getLocationErrorCodeName(LocationErrorCode.TIMEOUT)).toBe("TIMEOUT");
+    expect(
+      getLocationErrorCodeName(LocationErrorCode.PLAY_SERVICE_NOT_AVAILABLE)
+    ).toBe("PLAY_SERVICE_NOT_AVAILABLE");
+    expect(
+      getLocationErrorCodeName(LocationErrorCode.SETTINGS_NOT_SATISFIED)
+    ).toBe("SETTINGS_NOT_SATISFIED");
+    expect(getLocationErrorCodeName(999)).toBe("UNKNOWN_LOCATION_ERROR");
+  });
+});

package/src/utils/errors.ts

@@ -1,26 +1,39 @@
+import type { LocationError as NativeLocationError } from "../NitroGeolocation.nitro";
+
 /**
  * Error codes for geolocation errors.
- * These codes match the W3C Geolocation API specification.
+ * Codes 1-3 match the W3C Geolocation API specification. Modern API also
+ * exposes native location-provider/setup failures that cannot be represented
+ * by the legacy browser contract.
  */
 export enum LocationErrorCode {
+  /** Unexpected module/native failure */
+  INTERNAL_ERROR = -1,
   /** User denied the request for Geolocation */
   PERMISSION_DENIED = 1,
   /** Location provider is unavailable */
   POSITION_UNAVAILABLE = 2,
   /** The request to get location timed out */
-  TIMEOUT = 3
+  TIMEOUT = 3,
+  /** Android Google Play Services provider is unavailable */
+  PLAY_SERVICE_NOT_AVAILABLE = 4,
+  /** Device/provider settings do not satisfy the request */
+  SETTINGS_NOT_SATISFIED = 5
 }
 
 /**
  * Geolocation error object.
  */
-export interface LocationError extends Error {
-  code: LocationErrorCode;
-  message: string;
-  PERMISSION_DENIED: LocationErrorCode.PERMISSION_DENIED;
-  POSITION_UNAVAILABLE: LocationErrorCode.POSITION_UNAVAILABLE;
-  TIMEOUT: LocationErrorCode.TIMEOUT;
-}
+export type LocationError = NativeLocationError;
+
+const locationErrorCodeNames: Record<LocationErrorCode, string> = {
+  [LocationErrorCode.INTERNAL_ERROR]: "INTERNAL_ERROR",
+  [LocationErrorCode.PERMISSION_DENIED]: "PERMISSION_DENIED",
+  [LocationErrorCode.POSITION_UNAVAILABLE]: "POSITION_UNAVAILABLE",
+  [LocationErrorCode.TIMEOUT]: "TIMEOUT",
+  [LocationErrorCode.PLAY_SERVICE_NOT_AVAILABLE]: "PLAY_SERVICE_NOT_AVAILABLE",
+  [LocationErrorCode.SETTINGS_NOT_SATISFIED]: "SETTINGS_NOT_SATISFIED"
+};
 
 /**
  * Creates a standardized LocationError object.
@@ -41,12 +54,14 @@ export function createLocationError(
   code: LocationErrorCode,
   message: string
 ): LocationError {
-  const error = new Error(message) as LocationError;
-  error.code = code;
-  error.PERMISSION_DENIED = LocationErrorCode.PERMISSION_DENIED;
-  error.POSITION_UNAVAILABLE = LocationErrorCode.POSITION_UNAVAILABLE;
-  error.TIMEOUT = LocationErrorCode.TIMEOUT;
-  return error;
+  return { code, message };
+}
+
+export function getLocationErrorCodeName(code: number): string {
+  return (
+    locationErrorCodeNames[code as LocationErrorCode] ??
+    "UNKNOWN_LOCATION_ERROR"
+  );
 }
 
 /**
@@ -59,10 +74,10 @@ export function createLocationError(
  */
 export function mapCLErrorCode(clErrorCode: number): LocationErrorCode {
   switch (clErrorCode) {
-    case 0: // kCLErrorDenied
-      return LocationErrorCode.PERMISSION_DENIED;
-    case 1: // kCLErrorLocationUnknown
+    case 0: // kCLErrorLocationUnknown
       return LocationErrorCode.POSITION_UNAVAILABLE;
+    case 1: // kCLErrorDenied
+      return LocationErrorCode.PERMISSION_DENIED;
     default:
       return LocationErrorCode.POSITION_UNAVAILABLE;
   }
@@ -78,5 +93,17 @@ export function mapAndroidException(exceptionType: string): LocationErrorCode {
   if (exceptionType === "SecurityException") {
     return LocationErrorCode.PERMISSION_DENIED;
   }
+  if (
+    exceptionType === "GooglePlayServicesNotAvailableException" ||
+    exceptionType === "GooglePlayServicesRepairableException"
+  ) {
+    return LocationErrorCode.PLAY_SERVICE_NOT_AVAILABLE;
+  }
+  if (
+    exceptionType === "ResolvableApiException" ||
+    exceptionType === "LocationSettingsException"
+  ) {
+    return LocationErrorCode.SETTINGS_NOT_SATISFIED;
+  }
   return LocationErrorCode.POSITION_UNAVAILABLE;
 }

package/src/utils/index.ts

@@ -7,9 +7,9 @@ export { isCachedLocationValid } from "./cache";
 export {
   LocationErrorCode,
   createLocationError,
+  getLocationErrorCodeName,
   mapCLErrorCode,
-  mapAndroidException,
-  type LocationError
+  mapAndroidException
 } from "./errors";
 export {
   isBetterLocation,

package/src/utils/provider.test.ts

@@ -1,5 +1,78 @@
 import { describe, expect, it } from "vitest";
-import { selectProviderForAndroidPermissions } from "./provider";
+import {
+  getAndroidProviderOrder,
+  resolveAndroidAccuracy,
+  selectProviderForAndroidPermissions
+} from "./provider";
+
+describe("resolveAndroidAccuracy", () => {
+  it("keeps enableHighAccuracy as the legacy default", () => {
+    expect(resolveAndroidAccuracy(undefined, true)).toEqual({
+      mode: "high",
+      explicitPreset: undefined
+    });
+
+    expect(resolveAndroidAccuracy(undefined, false)).toEqual({
+      mode: "balanced",
+      explicitPreset: undefined
+    });
+  });
+
+  it("lets explicit Android accuracy override enableHighAccuracy", () => {
+    expect(resolveAndroidAccuracy({ android: "high" }, false)).toEqual({
+      mode: "high",
+      explicitPreset: "high"
+    });
+
+    expect(resolveAndroidAccuracy({ android: "low" }, true)).toEqual({
+      mode: "low",
+      explicitPreset: "low"
+    });
+  });
+
+  it("ignores iOS-only accuracy presets on Android", () => {
+    expect(resolveAndroidAccuracy({ ios: "bestForNavigation" }, false)).toEqual(
+      {
+        mode: "balanced",
+        explicitPreset: undefined
+      }
+    );
+  });
+});
+
+describe("getAndroidProviderOrder", () => {
+  it("keeps GPS fallback only for legacy balanced mode", () => {
+    expect(
+      getAndroidProviderOrder({
+        mode: "balanced",
+        explicitPreset: undefined
+      })
+    ).toEqual(["network", "gps"]);
+
+    expect(
+      getAndroidProviderOrder({
+        mode: "balanced",
+        explicitPreset: "balanced"
+      })
+    ).toEqual(["network"]);
+  });
+
+  it("keeps low accuracy network-first and passive accuracy passive-only", () => {
+    expect(
+      getAndroidProviderOrder({
+        mode: "low",
+        explicitPreset: "low"
+      })
+    ).toEqual(["network", "passive"]);
+
+    expect(
+      getAndroidProviderOrder({
+        mode: "passive",
+        explicitPreset: "passive"
+      })
+    ).toEqual(["passive"]);
+  });
+});
 
 describe("selectProviderForAndroidPermissions", () => {
   it("prefers the network provider for low-accuracy coarse-only requests", () => {
@@ -98,6 +171,104 @@ describe("selectProviderForAndroidPermissions", () => {
     ).toBe("gps");
   });
 
+  it("lets explicit high accuracy override enableHighAccuracy=false", () => {
+    expect(
+      selectProviderForAndroidPermissions({
+        enableHighAccuracy: false,
+        accuracy: {
+          android: "high"
+        },
+        providers: {
+          gps: true,
+          network: true
+        },
+        permissions: {
+          fine: true,
+          coarse: true
+        }
+      })
+    ).toBe("gps");
+  });
+
+  it("does not fall back to GPS for explicit balanced accuracy", () => {
+    expect(
+      selectProviderForAndroidPermissions({
+        enableHighAccuracy: true,
+        accuracy: {
+          android: "balanced"
+        },
+        providers: {
+          gps: true,
+          network: false
+        },
+        permissions: {
+          fine: true,
+          coarse: true
+        }
+      })
+    ).toBeNull();
+  });
+
+  it("does not fall back to GPS for explicit low accuracy", () => {
+    expect(
+      selectProviderForAndroidPermissions({
+        enableHighAccuracy: true,
+        accuracy: {
+          android: "low"
+        },
+        providers: {
+          gps: true,
+          network: false,
+          passive: false
+        },
+        permissions: {
+          fine: true,
+          coarse: true
+        }
+      })
+    ).toBeNull();
+  });
+
+  it("uses passive provider only for explicit passive accuracy", () => {
+    expect(
+      selectProviderForAndroidPermissions({
+        enableHighAccuracy: true,
+        accuracy: {
+          android: "passive"
+        },
+        providers: {
+          gps: true,
+          network: true,
+          passive: true
+        },
+        permissions: {
+          fine: true,
+          coarse: true
+        }
+      })
+    ).toBe("passive");
+  });
+
+  it("rejects passive accuracy when the passive provider is disabled", () => {
+    expect(
+      selectProviderForAndroidPermissions({
+        enableHighAccuracy: false,
+        accuracy: {
+          android: "passive"
+        },
+        providers: {
+          gps: true,
+          network: true,
+          passive: false
+        },
+        permissions: {
+          fine: true,
+          coarse: true
+        }
+      })
+    ).toBeNull();
+  });
+
   it("rejects provider selection when no Android location permission is granted", () => {
     expect(
       selectProviderForAndroidPermissions({

package/src/utils/provider.ts

@@ -1,13 +1,23 @@
+import type { AndroidAccuracyPreset, LocationAccuracyOptions } from "../types";
+
 /**
  * Location provider types supported on Android.
  */
-export type Provider = "gps" | "network" | null;
+export type Provider = "gps" | "network" | "passive" | null;
+export type AndroidAccuracyMode = AndroidAccuracyPreset;
+
+export interface AndroidAccuracyResolution {
+  mode: AndroidAccuracyMode;
+  explicitPreset?: AndroidAccuracyPreset;
+}
 
 export interface AndroidProviderSelectionInput {
   enableHighAccuracy: boolean;
+  accuracy?: LocationAccuracyOptions;
   providers: {
     gps: boolean;
     network: boolean;
+    passive?: boolean;
   };
   permissions: {
     fine: boolean;
@@ -72,14 +82,49 @@ export function selectProvider(
   return null;
 }
 
+export function resolveAndroidAccuracy(
+  accuracy: LocationAccuracyOptions | undefined,
+  enableHighAccuracy: boolean
+): AndroidAccuracyResolution {
+  const preset = accuracy?.android;
+
+  return {
+    mode: preset ?? (enableHighAccuracy ? "high" : "balanced"),
+    explicitPreset: preset
+  };
+}
+
+export function getAndroidProviderOrder({
+  mode,
+  explicitPreset
+}: AndroidAccuracyResolution): Exclude<Provider, null>[] {
+  switch (mode) {
+    case "high":
+      return ["gps", "network"];
+    case "balanced":
+      return explicitPreset ? ["network"] : ["network", "gps"];
+    case "low":
+      return ["network", "passive"];
+    case "passive":
+      return ["passive"];
+  }
+}
+
 export function selectProviderForAndroidPermissions({
   enableHighAccuracy,
+  accuracy,
   providers,
   permissions
 }: AndroidProviderSelectionInput): Provider {
-  const gpsAvailable = providers.gps && permissions.fine;
-  const networkAvailable =
-    providers.network && (permissions.coarse || permissions.fine);
+  const providerOrder = getAndroidProviderOrder(
+    resolveAndroidAccuracy(accuracy, enableHighAccuracy)
+  );
 
-  return selectProvider(enableHighAccuracy, gpsAvailable, networkAvailable);
+  return (
+    providerOrder.find((provider) => {
+      if (!providers[provider]) return false;
+      if (provider === "gps") return permissions.fine;
+      return permissions.coarse || permissions.fine;
+    }) ?? null
+  );
 }

package/nitrogen/generated/android/c++/JFunc_void_GeolocationError.hpp

@@ -1,78 +0,0 @@
-///
-/// JFunc_void_GeolocationError.hpp
-/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
-/// https://github.com/mrousavy/nitro
-/// Copyright © Marc Rousavy @ Margelo
-///
-
-#pragma once
-
-#include <fbjni/fbjni.h>
-#include <functional>
-
-#include "GeolocationError.hpp"
-#include <functional>
-#include <NitroModules/JNICallable.hpp>
-#include "JGeolocationError.hpp"
-#include <string>
-
-namespace margelo::nitro::nitrogeolocation {
-
-  using namespace facebook;
-
-  /**
-   * Represents the Java/Kotlin callback `(error: GeolocationError) -> Unit`.
-   * This can be passed around between C++ and Java/Kotlin.
-   */
-  struct JFunc_void_GeolocationError: public jni::JavaClass<JFunc_void_GeolocationError> {
-  public:
-    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitrogeolocation/Func_void_GeolocationError;";
-
-  public:
-    /**
-     * Invokes the function this `JFunc_void_GeolocationError` instance holds through JNI.
-     */
-    void invoke(const GeolocationError& error) const {
-      static const auto method = javaClassStatic()->getMethod<void(jni::alias_ref<JGeolocationError> /* error */)>("invoke");
-      method(self(), JGeolocationError::fromCpp(error));
-    }
-  };
-
-  /**
-   * An implementation of Func_void_GeolocationError that is backed by a C++ implementation (using `std::function<...>`)
-   */
-  class JFunc_void_GeolocationError_cxx final: public jni::HybridClass<JFunc_void_GeolocationError_cxx, JFunc_void_GeolocationError> {
-  public:
-    static jni::local_ref<JFunc_void_GeolocationError::javaobject> fromCpp(const std::function<void(const GeolocationError& /* error */)>& func) {
-      return JFunc_void_GeolocationError_cxx::newObjectCxxArgs(func);
-    }
-
-  public:
-    /**
-     * Invokes the C++ `std::function<...>` this `JFunc_void_GeolocationError_cxx` instance holds.
-     */
-    void invoke_cxx(jni::alias_ref<JGeolocationError> error) {
-      _func(error->toCpp());
-    }
-
-  public:
-    [[nodiscard]]
-    inline const std::function<void(const GeolocationError& /* error */)>& getFunction() const {
-      return _func;
-    }
-
-  public:
-    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/nitrogeolocation/Func_void_GeolocationError_cxx;";
-    static void registerNatives() {
-      registerHybrid({makeNativeMethod("invoke_cxx", JFunc_void_GeolocationError_cxx::invoke_cxx)});
-    }
-
-  private:
-    explicit JFunc_void_GeolocationError_cxx(const std::function<void(const GeolocationError& /* error */)>& func): _func(func) { }
-
-  private:
-    friend HybridBase;
-    std::function<void(const GeolocationError& /* error */)> _func;
-  };
-
-} // namespace margelo::nitro::nitrogeolocation