react-native-nitro-geolocation 1.1.4 → 1.2.1

package/src/api/getProviderStatus.ts

@@ -0,0 +1,16 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { LocationProviderStatus } from "../publicTypes";
+
+/**
+ * Get native provider/settings status for the current device.
+ *
+ * Android: returns device-level service state plus provider availability
+ * (`gpsAvailable`, `networkAvailable`, `passiveAvailable`) and Google Location
+ * Accuracy state when Google Play Services exposes it.
+ *
+ * iOS: returns Core Location service availability and whether the app declares
+ * background location mode. Android-specific provider fields are `undefined`.
+ */
+export function getProviderStatus(): Promise<LocationProviderStatus> {
+  return NitroGeolocationHybridObject.getProviderStatus();
+}

package/src/api/hasServicesEnabled.ts

@@ -0,0 +1,13 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+
+/**
+ * Check whether device-level location services are enabled.
+ *
+ * Android: checks the system location service/provider state used by native
+ * Android location requests.
+ *
+ * iOS: maps to `CLLocationManager.locationServicesEnabled()`.
+ */
+export function hasServicesEnabled(): Promise<boolean> {
+  return NitroGeolocationHybridObject.hasServicesEnabled();
+}

package/src/api/index.ts

@@ -1,7 +1,18 @@
 export { setConfiguration } from "./setConfiguration";
 export { checkPermission } from "./checkPermission";
 export { requestPermission } from "./requestPermission";
+export { hasServicesEnabled } from "./hasServicesEnabled";
+export { getProviderStatus } from "./getProviderStatus";
+export { getLocationAvailability } from "./getLocationAvailability";
+export { requestLocationSettings } from "./requestLocationSettings";
+export { getAccuracyAuthorization } from "./getAccuracyAuthorization";
+export { requestTemporaryFullAccuracy } from "./requestTemporaryFullAccuracy";
 export { getCurrentPosition } from "./getCurrentPosition";
+export { getLastKnownPosition } from "./getLastKnownPosition";
+export { geocode } from "./geocode";
+export { reverseGeocode } from "./reverseGeocode";
+export { getHeading } from "./getHeading";
+export { watchHeading } from "./watchHeading";
 export { watchPosition } from "./watchPosition";
 export { unwatch } from "./unwatch";
 export { stopObserving } from "./stopObserving";

package/src/api/requestLocationSettings.ts

@@ -0,0 +1,29 @@
+import type { LocationSettingsOptions } from "../NitroGeolocation.nitro";
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { LocationProviderStatus } from "../publicTypes";
+
+/**
+ * Android-only settings resolution API.
+ *
+ * Android: checks whether current device settings satisfy the requested
+ * location requirements and shows Android's native settings resolution dialog
+ * when available.
+ *
+ * iOS: does not show a settings dialog and ignores `options`. It resolves with
+ * the current Core Location status:
+ * - `locationServicesEnabled`: `CLLocationManager.locationServicesEnabled()`
+ * - `backgroundModeEnabled`: whether `UIBackgroundModes` contains `location`
+ * - `gpsAvailable`, `networkAvailable`, `passiveAvailable`, and
+ *   `googleLocationAccuracyEnabled`: `undefined`
+ */
+export function requestLocationSettings(
+  options?: LocationSettingsOptions
+): Promise<LocationProviderStatus> {
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.requestLocationSettings(
+      resolve,
+      reject,
+      options
+    );
+  });
+}

package/src/api/requestPermission.ts

@@ -17,5 +17,7 @@ import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
  * ```
  */
 export function requestPermission(): Promise<PermissionStatus> {
-  return NitroGeolocationHybridObject.requestPermission();
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.requestPermission(resolve, reject);
+  });
 }

package/src/api/requestTemporaryFullAccuracy.ts

@@ -0,0 +1,21 @@
+import type { LocationError } from "../NitroGeolocation.nitro";
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { AccuracyAuthorization } from "../publicTypes";
+
+/**
+ * Request temporary full location accuracy on iOS.
+ *
+ * Android resolves with the current accuracy authorization without showing a
+ * prompt.
+ */
+export function requestTemporaryFullAccuracy(
+  purposeKey: string
+): Promise<AccuracyAuthorization> {
+  return new Promise((resolve, reject: (error: LocationError) => void) => {
+    NitroGeolocationHybridObject.requestTemporaryFullAccuracy(
+      purposeKey,
+      resolve,
+      reject
+    );
+  });
+}

package/src/api/reverseGeocode.ts

@@ -0,0 +1,23 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type {
+  GeocodingCoordinates,
+  ReverseGeocodedAddress
+} from "../publicTypes";
+
+/**
+ * Convert coordinates into candidate human-readable addresses.
+ *
+ * Uses the platform geocoder: Android `Geocoder` and iOS `CLGeocoder`.
+ * Results and availability depend on platform networking/geocoder services.
+ *
+ * @param coords - Latitude and longitude to reverse geocode
+ * @returns Promise resolving to matching address candidates
+ * @throws LocationError if input is invalid or the platform geocoder fails
+ */
+export function reverseGeocode(
+  coords: GeocodingCoordinates
+): Promise<ReverseGeocodedAddress[]> {
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.reverseGeocode(coords, resolve, reject);
+  });
+}

package/src/api/setConfiguration.ts

@@ -1,6 +1,10 @@
-import type { ModernGeolocationConfiguration as NitroModernGeolocationConfiguration } from "../NitroGeolocation.nitro";
+import type { NitroGeolocation } from "../NitroGeolocation.nitro";
 import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
-import type { ModernGeolocationConfiguration } from "../types";
+import type { GeolocationConfiguration } from "../publicTypes";
+
+type NitroGeolocationConfiguration = Parameters<
+  NitroGeolocation["setConfiguration"]
+>[0];
 
 /**
  * Set global geolocation configuration.
@@ -18,8 +22,8 @@ import type { ModernGeolocationConfiguration } from "../types";
  * });
  * ```
  */
-export function setConfiguration(config: ModernGeolocationConfiguration): void {
-  const nativeConfig: NitroModernGeolocationConfiguration = {
+export function setConfiguration(config: GeolocationConfiguration): void {
+  const nativeConfig: NitroGeolocationConfiguration = {
     ...config,
     locationProvider:
       config.locationProvider === "android"

package/src/api/watchHeading.ts

@@ -0,0 +1,19 @@
+import type { LocationError } from "../NitroGeolocation.nitro";
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { Heading, HeadingOptions } from "../publicTypes";
+
+/**
+ * Start watching platform heading updates.
+ *
+ * @param success - Called on each heading update
+ * @param error - Called when heading is unavailable or options are invalid
+ * @param options - Heading watch options
+ * @returns Subscription token for cleanup with `unwatch(token)`
+ */
+export function watchHeading(
+  success: (heading: Heading) => void,
+  error?: (error: LocationError) => void,
+  options?: HeadingOptions
+): string {
+  return NitroGeolocationHybridObject.watchHeading(success, error, options);
+}

package/src/api/watchPosition.ts

@@ -5,7 +5,7 @@ import type {
 import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
 import { isDevtoolsEnabled } from "../devtools";
 import { devtoolsWatchPosition } from "../devtools/watchPosition";
-import type { GeolocationResponse } from "../types";
+import type { GeolocationResponse } from "../publicTypes";
 
 /**
  * Start watching for continuous location updates.
@@ -24,7 +24,7 @@ import type { GeolocationResponse } from "../types";
  * const token = watchPosition(
  *   (position) => console.log(position.coords),
  *   (error) => console.error(error.message),
- *   { enableHighAccuracy: true, distanceFilter: 10 }
+ *   { accuracy: { android: "high", ios: "best" }, distanceFilter: 10 }
  * );
  *
  * // Later: cleanup

package/src/compat/getCurrentPosition.ts

@@ -1,14 +1,14 @@
 import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
 import type {
-  GeolocationError,
-  GeolocationOptions,
-  GeolocationResponse
-} from "../types";
+  CompatGeolocationError,
+  CompatGeolocationOptions,
+  CompatGeolocationResponse
+} from "../publicTypes";
 
 export function getCurrentPosition(
-  success: (position: GeolocationResponse) => void,
-  error?: (error: GeolocationError) => void,
-  options?: GeolocationOptions
+  success: (position: CompatGeolocationResponse) => void,
+  error?: (error: CompatGeolocationError) => void,
+  options?: CompatGeolocationOptions
 ): void {
   NitroGeolocationHybridCompatObject.getCurrentPosition(
     success,

package/src/compat/index.tsx

@@ -25,10 +25,10 @@ const Geolocation = {
 
 // Export types
 export type {
-  GeolocationConfiguration,
-  GeolocationResponse,
-  GeolocationError,
-  GeolocationOptions
-} from "../types";
+  CompatGeolocationConfiguration as GeolocationConfiguration,
+  CompatGeolocationResponse as GeolocationResponse,
+  CompatGeolocationError as GeolocationError,
+  CompatGeolocationOptions as GeolocationOptions
+} from "../publicTypes";
 
 export default Geolocation;

package/src/compat/requestAuthorization.ts

@@ -1,9 +1,9 @@
 import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
-import type { GeolocationError } from "../types";
+import type { CompatGeolocationError } from "../publicTypes";
 
 export function requestAuthorization(
   success?: () => void,
-  error?: (error: GeolocationError) => void
+  error?: (error: CompatGeolocationError) => void
 ): void {
   NitroGeolocationHybridCompatObject.requestAuthorization(success, error);
 }

package/src/compat/setRNConfiguration.ts

@@ -1,11 +1,11 @@
-import type { RNConfigurationInternal } from "../NitroGeolocationCompat.nitro";
+import type { CompatGeolocationConfigurationInternal } from "../NitroGeolocationCompat.nitro";
 import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
-import type { GeolocationConfiguration } from "../types";
+import type { CompatGeolocationConfiguration } from "../publicTypes";
 
 // Mapping layer: convert "android" to "android_platform" for C++
 function mapConfigToInternal(
-  config: GeolocationConfiguration
-): RNConfigurationInternal {
+  config: CompatGeolocationConfiguration
+): CompatGeolocationConfigurationInternal {
   return {
     skipPermissionRequests: config.skipPermissionRequests,
     authorizationLevel: config.authorizationLevel,
@@ -17,7 +17,9 @@ function mapConfigToInternal(
   };
 }
 
-export function setRNConfiguration(config: GeolocationConfiguration): void {
+export function setRNConfiguration(
+  config: CompatGeolocationConfiguration
+): void {
   NitroGeolocationHybridCompatObject.setRNConfiguration(
     mapConfigToInternal(config)
   );

package/src/compat/watchPosition.ts

@@ -1,9 +1,9 @@
 import { NitroGeolocationHybridCompatObject } from "../NitroGeolocationModule";
 import type {
-  GeolocationError,
-  GeolocationOptions,
-  GeolocationResponse
-} from "../types";
+  CompatGeolocationError,
+  CompatGeolocationOptions,
+  CompatGeolocationResponse
+} from "../publicTypes";
 
 /**
  * Invokes the success callback whenever the location changes.
@@ -15,9 +15,9 @@ import type {
  * @returns watchId - A number that identifies this watch session
  */
 export function watchPosition(
-  success: (position: GeolocationResponse) => void,
-  error?: (error: GeolocationError) => void,
-  options?: GeolocationOptions
+  success: (position: CompatGeolocationResponse) => void,
+  error?: (error: CompatGeolocationError) => void,
+  options?: CompatGeolocationOptions
 ): number {
   return NitroGeolocationHybridCompatObject.watchPosition(
     success,

package/src/devtools/getCurrentPosition.ts

@@ -1,4 +1,5 @@
-import type { GeolocationResponse } from "../types";
+import type { GeolocationResponse } from "../publicTypes";
+import { LocationErrorCode, createLocationError } from "../utils/errors";
 import { getDevtoolsState } from "./index";
 
 export function getDevtoolsCurrentPosition(): Promise<GeolocationResponse> | null {
@@ -6,9 +7,10 @@ export function getDevtoolsCurrentPosition(): Promise<GeolocationResponse> | nul
   if (devtools.position) {
     return Promise.resolve(devtools.position);
   }
-  // Devtools not connected - throw error
+  // Devtools is JS-only, but keep the public rejection shape aligned.
   return Promise.reject(
-    new Error(
+    createLocationError(
+      LocationErrorCode.INTERNAL_ERROR,
       "Geolocation devtools not connected. Press 'j' in Metro to open devtools and enable the geolocation plugin."
     )
   );

package/src/devtools/index.ts

@@ -1,4 +1,4 @@
-import type { GeolocationResponse } from "../types";
+import type { GeolocationResponse } from "../publicTypes";
 
 declare const __DEV__: boolean;
 

package/src/devtools/watchPosition.ts

@@ -1,9 +1,11 @@
-import type { GeolocationError, GeolocationResponse } from "../types";
+import type { LocationError } from "../NitroGeolocation.nitro";
+import type { GeolocationResponse } from "../publicTypes";
+import { LocationErrorCode } from "../utils/errors";
 import { getDevtoolsState } from "./index";
 
 export function devtoolsWatchPosition(
   success: (position: GeolocationResponse) => void,
-  error?: (error: GeolocationError) => void
+  error?: (error: LocationError) => void
 ): string {
   const devtools = getDevtoolsState();
 
@@ -12,12 +14,9 @@ export function devtoolsWatchPosition(
     // Call error callback immediately if provided
     if (error) {
       error({
-        code: 2, // POSITION_UNAVAILABLE
+        code: LocationErrorCode.POSITION_UNAVAILABLE,
         message:
-          "Geolocation devtools not connected. Press 'j' in Metro to open devtools and enable the geolocation plugin.",
-        PERMISSION_DENIED: 1,
-        POSITION_UNAVAILABLE: 2,
-        TIMEOUT: 3
+          "Geolocation devtools not connected. Press 'j' in Metro to open devtools and enable the geolocation plugin."
       });
     }
     // Return a dummy token that does nothing

package/src/hooks/useWatchPosition.ts

@@ -4,7 +4,7 @@ import type {
   LocationRequestOptions
 } from "../NitroGeolocation.nitro";
 import { unwatch, watchPosition } from "../api";
-import type { GeolocationResponse } from "../types";
+import type { GeolocationResponse } from "../publicTypes";
 
 /**
  * Options for useWatchPosition hook.
@@ -33,7 +33,7 @@ export interface UseWatchPositionOptions extends LocationRequestOptions {
  * function LiveTracking() {
  *   const { position, error, isWatching } = useWatchPosition({
  *     enabled: true,
- *     enableHighAccuracy: true,
+ *     accuracy: { android: "high", ios: "best" },
  *     distanceFilter: 10  // Update every 10 meters
  *   });
  *

package/src/index.tsx

@@ -1,8 +1,8 @@
 /**
- * Modern Geolocation API for React Native.
+ * Geolocation API for React Native.
  *
- * This is the main entry point for the modern, functional API.
- * For legacy compatibility, use: import Geolocation from 'react-native-nitro-geolocation/compat'
+ * This is the main entry point for the functional API.
+ * For compat usage, use: import Geolocation from 'react-native-nitro-geolocation/compat'
  *
  * @example
  * ```tsx
@@ -24,7 +24,9 @@
  * async function setup() {
  *   const status = await requestPermission();
  *   if (status === 'granted') {
- *     const position = await getCurrentPosition({ enableHighAccuracy: true });
+ *     const position = await getCurrentPosition({
+ *       accuracy: { android: 'high', ios: 'best' }
+ *     });
  *     console.log('Position:', position);
  *   }
  * }
@@ -33,7 +35,7 @@
  * function LiveTracking() {
  *   const { position, error, isWatching } = useWatchPosition({
  *     enabled: true,
- *     enableHighAccuracy: true,
+ *     accuracy: { android: 'high', ios: 'best' },
  *     distanceFilter: 10
  *   });
  *
@@ -51,7 +53,18 @@ export {
   setConfiguration,
   checkPermission,
   requestPermission,
+  hasServicesEnabled,
+  getProviderStatus,
+  getLocationAvailability,
+  requestLocationSettings,
+  getAccuracyAuthorization,
+  requestTemporaryFullAccuracy,
   getCurrentPosition,
+  getLastKnownPosition,
+  geocode,
+  reverseGeocode,
+  getHeading,
+  watchHeading,
   watchPosition,
   unwatch,
   stopObserving
@@ -64,16 +77,32 @@ export * from "./hooks";
 export type {
   PermissionStatus,
   LocationRequestOptions,
+  LocationSettingsOptions,
   LocationError
 } from "./NitroGeolocation.nitro";
 
 export type {
   GeolocationResponse,
   GeolocationCoordinates,
+  LocationProviderStatus,
+  LocationAvailability,
+  GeocodingCoordinates,
+  GeocodedLocation,
+  ReverseGeocodedAddress,
+  AndroidAccuracyPreset,
+  AndroidGranularity,
+  IOSAccuracyPreset,
+  AccuracyAuthorization,
+  IOSActivityType,
+  LocationAccuracyOptions,
+  Heading,
+  HeadingOptions,
   AuthorizationLevel,
   LocationProvider,
+  LocationProviderUsed,
+  GeolocationConfiguration,
   ModernGeolocationConfiguration
-} from "./types";
+} from "./publicTypes";
 
 // Pure utility functions (advanced users only)
 export * from "./utils";

package/src/publicTypes.ts

@@ -0,0 +1,108 @@
+import type { NitroGeolocation } from "./NitroGeolocation.nitro";
+import type {
+  CompatGeolocationConfigurationInternal,
+  NitroGeolocationCompat
+} from "./NitroGeolocationCompat.nitro";
+import type {
+  AccuracyAuthorization as SchemaAccuracyAuthorization,
+  AndroidAccuracyPreset as SchemaAndroidAccuracyPreset,
+  AndroidGranularity as SchemaAndroidGranularity,
+  GeocodedLocation as SchemaGeocodedLocation,
+  GeocodingCoordinates as SchemaGeocodingCoordinates,
+  GeolocationResponse as SchemaGeolocationResponse,
+  Heading as SchemaHeading,
+  HeadingOptions as SchemaHeadingOptions,
+  IOSAccuracyPreset as SchemaIOSAccuracyPreset,
+  IOSActivityType as SchemaIOSActivityType,
+  LocationAccuracyOptions as SchemaLocationAccuracyOptions,
+  LocationAvailability as SchemaLocationAvailability,
+  LocationProviderStatus as SchemaLocationProviderStatus,
+  LocationProviderUsed as SchemaLocationProviderUsed,
+  ReverseGeocodedAddress as SchemaReverseGeocodedAddress
+} from "./types";
+
+type CallbackValue<TCallback> = TCallback extends (value: infer Value) => void
+  ? Value
+  : never;
+
+type CompatGetCurrentPosition = NitroGeolocationCompat["getCurrentPosition"];
+type CompatSuccessCallback = Parameters<CompatGetCurrentPosition>[0];
+type CompatErrorCallback = NonNullable<Parameters<CompatGetCurrentPosition>[1]>;
+type NativeGeolocationConfiguration = Parameters<
+  NitroGeolocation["setConfiguration"]
+>[0];
+type NativeLocationProvider = NonNullable<
+  NativeGeolocationConfiguration["locationProvider"]
+>;
+
+export type GeolocationResponse = SchemaGeolocationResponse;
+export type LocationProviderStatus = SchemaLocationProviderStatus;
+export type LocationAvailability = SchemaLocationAvailability;
+export type GeocodingCoordinates = SchemaGeocodingCoordinates;
+export type GeocodedLocation = SchemaGeocodedLocation;
+export type ReverseGeocodedAddress = SchemaReverseGeocodedAddress;
+export type AndroidAccuracyPreset = SchemaAndroidAccuracyPreset;
+export type AndroidGranularity = SchemaAndroidGranularity;
+export type IOSAccuracyPreset = SchemaIOSAccuracyPreset;
+export type AccuracyAuthorization = SchemaAccuracyAuthorization;
+export type IOSActivityType = SchemaIOSActivityType;
+export type LocationAccuracyOptions = SchemaLocationAccuracyOptions;
+export type Heading = SchemaHeading;
+export type HeadingOptions = SchemaHeadingOptions;
+
+export type CompatGeolocationResponse = CallbackValue<CompatSuccessCallback>;
+
+export type GeolocationCoordinates = GeolocationResponse["coords"];
+export type LocationProviderUsed = SchemaLocationProviderUsed;
+export type CompatGeolocationError = CallbackValue<CompatErrorCallback>;
+export type CompatGeolocationOptions = NonNullable<
+  Parameters<CompatGetCurrentPosition>[2]
+>;
+
+export type AuthorizationLevel = NonNullable<
+  NativeGeolocationConfiguration["authorizationLevel"]
+>;
+export type LocationProvider =
+  | Exclude<NativeLocationProvider, "android_platform">
+  | "android";
+
+export type GeolocationConfiguration = Omit<
+  NativeGeolocationConfiguration,
+  "autoRequestPermission" | "locationProvider"
+> & {
+  /**
+   * @deprecated This option is accepted for backward compatibility only.
+   * `setConfiguration()` does not request permission. Call
+   * `requestPermission()` explicitly when your app is ready to show the native
+   * permission prompt.
+   * @default false
+   */
+  autoRequestPermission?: boolean;
+
+  /**
+   * Android location provider.
+   *
+   * `auto` currently uses Android's platform `LocationManager` by default.
+   * Set `playServices` explicitly to use Google Play Services fused location.
+   */
+  locationProvider?: LocationProvider;
+};
+
+/**
+ * @deprecated Use `GeolocationConfiguration` instead.
+ * This alias is kept only for backward compatibility.
+ */
+export type ModernGeolocationConfiguration = GeolocationConfiguration;
+
+export type CompatGeolocationConfiguration = Omit<
+  CompatGeolocationConfigurationInternal,
+  "locationProvider"
+> & {
+  /**
+   * Android location provider.
+   *
+   * `auto` currently uses Android's platform `LocationManager` by default.
+   * Set `playServices` explicitly to use Google Play Services fused location.
+   */
+  locationProvider?: LocationProvider;
+};