react-native-nitro-geolocation 1.1.4 → 1.2.0

package/nitrogen/generated/shared/c++/ReverseGeocodedAddress.hpp

@@ -0,0 +1,108 @@
+///
+/// ReverseGeocodedAddress.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+#include <optional>
+
+namespace margelo::nitro::nitrogeolocation {
+
+  /**
+   * A struct which can be represented as a JavaScript object (ReverseGeocodedAddress).
+   */
+  struct ReverseGeocodedAddress final {
+  public:
+    std::optional<std::string> country     SWIFT_PRIVATE;
+    std::optional<std::string> region     SWIFT_PRIVATE;
+    std::optional<std::string> city     SWIFT_PRIVATE;
+    std::optional<std::string> district     SWIFT_PRIVATE;
+    std::optional<std::string> street     SWIFT_PRIVATE;
+    std::optional<std::string> postalCode     SWIFT_PRIVATE;
+    std::optional<std::string> formattedAddress     SWIFT_PRIVATE;
+
+  public:
+    ReverseGeocodedAddress() = default;
+    explicit ReverseGeocodedAddress(std::optional<std::string> country, std::optional<std::string> region, std::optional<std::string> city, std::optional<std::string> district, std::optional<std::string> street, std::optional<std::string> postalCode, std::optional<std::string> formattedAddress): country(country), region(region), city(city), district(district), street(street), postalCode(postalCode), formattedAddress(formattedAddress) {}
+
+  public:
+    friend bool operator==(const ReverseGeocodedAddress& lhs, const ReverseGeocodedAddress& rhs) = default;
+  };
+
+} // namespace margelo::nitro::nitrogeolocation
+
+namespace margelo::nitro {
+
+  // C++ ReverseGeocodedAddress <> JS ReverseGeocodedAddress (object)
+  template <>
+  struct JSIConverter<margelo::nitro::nitrogeolocation::ReverseGeocodedAddress> final {
+    static inline margelo::nitro::nitrogeolocation::ReverseGeocodedAddress fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::nitrogeolocation::ReverseGeocodedAddress(
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "country"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "region"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "city"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "district"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "street"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "postalCode"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "formattedAddress")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitrogeolocation::ReverseGeocodedAddress& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "country"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.country));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "region"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.region));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "city"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.city));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "district"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.district));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "street"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.street));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "postalCode"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.postalCode));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "formattedAddress"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.formattedAddress));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "country")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "region")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "city")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "district")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "street")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "postalCode")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "formattedAddress")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "⚡🚀Blazing-fast geolocation for React Native powered by Nitro Modules",
   "main": "src/index",
   "source": "src/index",

package/src/NitroGeolocation.nitro.ts

@@ -1,5 +1,18 @@
 import type { HybridObject } from "react-native-nitro-modules";
-import type { GeolocationResponse } from "./types";
+import type {
+  AccuracyAuthorization,
+  AndroidGranularity,
+  GeocodedLocation,
+  GeocodingCoordinates,
+  GeolocationResponse,
+  Heading,
+  HeadingOptions,
+  IOSActivityType,
+  LocationAccuracyOptions,
+  LocationAvailability,
+  LocationProviderStatus,
+  ReverseGeocodedAddress
+} from "./types";
 
 /**
  * Permission status for location services.
@@ -24,13 +37,14 @@ export type LocationProvider = "playServices" | "android_platform" | "auto";
 
 /**
  * Global configuration for geolocation services.
- * Set once via GeolocationProvider.
+ * Apply once at app startup with `setConfiguration()`.
  */
-export interface ModernGeolocationConfiguration {
+export interface GeolocationConfiguration {
   /**
-   * Automatically request location permission when GeolocationProvider mounts.
-   * When true, permission is requested immediately on app start.
-   * When false, you must manually call useRequestPermission().
+   * @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;
@@ -68,9 +82,26 @@ export interface LocationRequestOptions {
   /** Maximum age of cached location in milliseconds (default: 0) */
   maximumAge?: number;
 
-  /** Enable high accuracy mode (GPS) */
+  /**
+   * Enable high accuracy mode (GPS).
+   *
+   * @deprecated Since v1.2, use `accuracy` for explicit platform-native
+   * presets. This remains available for v1 compatibility and is planned for
+   * removal from the Modern API in v2.
+   */
   enableHighAccuracy?: boolean;
 
+  /**
+   * Platform-specific accuracy preset.
+   *
+   * Available since v1.2.
+   *
+   * When provided, this takes precedence over `enableHighAccuracy` on the
+   * matching platform while keeping `enableHighAccuracy` available for the
+   * legacy true/false contract.
+   */
+  accuracy?: LocationAccuracyOptions;
+
   /** Minimum time interval between updates in milliseconds (watch only) */
   interval?: number;
 
@@ -80,23 +111,134 @@ export interface LocationRequestOptions {
   /** Minimum distance change in meters for updates (watch only) */
   distanceFilter?: number;
 
+  /**
+   * Android-only location granularity.
+   *
+   * Available since v1.2.
+   *
+   * `permission` follows the granted permission level, `coarse` prevents fine
+   * GPS-only requests from being used, and `fine` requires fine location
+   * permission.
+   */
+  granularity?: AndroidGranularity;
+
+  /**
+   * Android-only option for high-accuracy initial updates.
+   *
+   * Available since v1.2.
+   */
+  waitForAccurateLocation?: boolean;
+
+  /**
+   * Android-only maximum age for an initial update in milliseconds.
+   *
+   * Available since v1.2.
+   */
+  maxUpdateAge?: number;
+
+  /**
+   * Android-only maximum batching delay in milliseconds.
+   *
+   * Available since v1.2.
+   */
+  maxUpdateDelay?: number;
+
+  /**
+   * Android-only maximum number of updates before a watch stops itself.
+   *
+   * Available since v1.2.
+   */
+  maxUpdates?: number;
+
   /** Use significant location changes mode (iOS watch only) */
   useSignificantChanges?: boolean;
+
+  /**
+   * iOS-only activity type used to tune Core Location behavior.
+   *
+   * Available since v1.2.
+   */
+  activityType?: IOSActivityType;
+
+  /**
+   * iOS-only setting for automatic pausing of location updates.
+   *
+   * Available since v1.2.
+   */
+  pausesLocationUpdatesAutomatically?: boolean;
+
+  /**
+   * iOS-only setting for the background location indicator.
+   *
+   * Requires background location capability and is ignored by Android.
+   *
+   * Available since v1.2.
+   */
+  showsBackgroundLocationIndicator?: boolean;
+}
+
+/**
+ * Android-only location settings request options.
+ *
+ * Used by `requestLocationSettings()` on Android to build the native
+ * `LocationSettingsRequest`. On iOS these options are ignored because iOS does
+ * not provide an equivalent system settings resolution dialog.
+ */
+export interface LocationSettingsOptions {
+  /**
+   * Request high accuracy Android location settings.
+   * Defaults to true because this API is primarily used before user-facing
+   * precise location flows.
+   *
+   * @deprecated Since v1.2, use `accuracy.android` for explicit Android
+   * settings priorities. This remains available for v1 compatibility and is
+   * planned for removal from the Modern API in v2.
+   */
+  enableHighAccuracy?: boolean;
+
+  /**
+   * Platform-specific accuracy preset for settings checks.
+   *
+   * Available since v1.2.
+   *
+   * Android uses `accuracy.android` to map to the native location request
+   * priority. iOS ignores this option because iOS has no equivalent settings
+   * resolution dialog.
+   */
+  accuracy?: LocationAccuracyOptions;
+
+  /** Desired update interval in milliseconds. */
+  interval?: number;
+
+  /** Fastest acceptable update interval in milliseconds. */
+  fastestInterval?: number;
+
+  /** Minimum distance change in meters. */
+  distanceFilter?: number;
+
+  /** Ask Android to always show the resolution dialog when possible. */
+  alwaysShow?: boolean;
+
+  /** Require BLE availability for the location settings request. */
+  needBle?: boolean;
 }
 
 /**
  * Location error structure.
  */
 export interface LocationError {
-  code: number; // 1: PERMISSION_DENIED, 2: POSITION_UNAVAILABLE, 3: TIMEOUT
+  // -1: INTERNAL_ERROR, 1: PERMISSION_DENIED, 2: POSITION_UNAVAILABLE,
+  // 3: TIMEOUT, 4: PLAY_SERVICE_NOT_AVAILABLE, 5: SETTINGS_NOT_SATISFIED
+  code: number;
   message: string;
 }
 
 /**
- * Modern Geolocation Nitro Module.
+ * Geolocation Nitro Module.
  *
  * Key Features:
- * - Promise-based for async operations
+ * - Public async APIs are wrapped in JS Promises
+ * - Native sends structured LocationError callbacks
  * - First-class function callbacks for continuous updates
  * - Token-based subscriptions (internal use only)
  * - Type-safe across JS ↔ Native boundary
@@ -105,11 +247,11 @@ export interface NitroGeolocation
   extends HybridObject<{ ios: "swift"; android: "kotlin" }> {
   /**
    * Set global geolocation configuration.
-   * Should be called once at app startup via GeolocationProvider.
+   * Should be called once at app startup before location requests.
    *
    * @param config - Platform-specific configuration
    */
-  setConfiguration(config: ModernGeolocationConfiguration): void;
+  setConfiguration(config: GeolocationConfiguration): void;
 
   /**
    * Check current location permission status.
@@ -123,9 +265,82 @@ export interface NitroGeolocation
    * Request location permission from the user.
    * Shows system permission dialog if not yet determined.
    *
-   * @returns Promise resolving to new permission status
+   * Internal native contract. The public JS API wraps this in a Promise so
+   * native remains the source of truth for structured LocationError objects.
+   */
+  requestPermission(
+    success: (status: PermissionStatus) => void,
+    error?: (error: LocationError) => void
+  ): void;
+
+  /**
+   * Check whether device-level location services are enabled.
+   *
+   * Android: checks Android system location/provider state.
+   * iOS: maps to `CLLocationManager.locationServicesEnabled()`.
+   */
+  hasServicesEnabled(): Promise<boolean>;
+
+  /**
+   * Get native provider/settings state.
+   *
+   * Android: returns Android provider availability and Google Location Accuracy
+   * state when available.
+   *
+   * iOS: returns Core Location service availability and app background location
+   * mode only. Android-specific provider fields are `undefined`.
+   */
+  getProviderStatus(): Promise<LocationProviderStatus>;
+
+  /**
+   * Get whether the current platform is likely to deliver location updates.
+   *
+   * Android: uses Fused Location availability when the configured provider is
+   * Play Services, otherwise falls back to platform provider/service checks.
+   *
+   * iOS: maps Core Location service and authorization state.
    */
-  requestPermission(): Promise<PermissionStatus>;
+  getLocationAvailability(): Promise<LocationAvailability>;
+
+  /**
+   * Android-only settings resolution API.
+   *
+   * Android: checks whether current device settings satisfy the requested
+   * location requirements and shows the native settings resolution dialog when
+   * Android can resolve the mismatch.
+   *
+   * iOS: does not show a settings dialog and ignores `options`. It resolves
+   * with `locationServicesEnabled`, `backgroundModeEnabled`, and `undefined`
+   * Android-specific provider fields.
+   */
+  requestLocationSettings(
+    success: (status: LocationProviderStatus) => void,
+    error?: (error: LocationError) => void,
+    options?: LocationSettingsOptions
+  ): void;
+
+  /**
+   * Get current platform location accuracy authorization.
+   *
+   * iOS: maps Core Location full/reduced accuracy authorization.
+   * Android: maps fine permission to `full` and coarse-only permission to
+   * `reduced`.
+   */
+  getAccuracyAuthorization(): Promise<AccuracyAuthorization>;
+
+  /**
+   * iOS-only temporary full accuracy request.
+   *
+   * iOS: calls Core Location temporary full accuracy authorization with the
+   * provided Info.plist purpose key.
+   * Android: resolves with the current accuracy authorization without showing
+   * a prompt.
+   */
+  requestTemporaryFullAccuracy(
+    purposeKey: string,
+    success: (authorization: AccuracyAuthorization) => void,
+    error?: (error: LocationError) => void
+  ): void;
 
   /**
    * Get current location (one-time request).
@@ -135,13 +350,72 @@ export interface NitroGeolocation
    * 2. Request fresh location from GPS/Network
    * 3. Timeout after specified duration
    *
+   * Internal native contract. The public JS API wraps this in a Promise so
+   * native remains the source of truth for structured LocationError objects.
+   *
+   * @param success - Called with the current position
+   * @param error - Called with native-classified LocationError
    * @param options - Location request options
-   * @returns Promise resolving to current position
-   * @throws LocationError if permission denied, timeout, or unavailable
    */
   getCurrentPosition(
+    success: (position: GeolocationResponse) => void,
+    error?: (error: LocationError) => void,
     options?: LocationRequestOptions
-  ): Promise<GeolocationResponse>;
+  ): void;
+
+  /**
+   * Get the best cached location without starting a fresh location request.
+   *
+   * Returns `POSITION_UNAVAILABLE` when no cached location satisfies `options`.
+   */
+  getLastKnownPosition(
+    success: (position: GeolocationResponse) => void,
+    error?: (error: LocationError) => void,
+    options?: LocationRequestOptions
+  ): void;
+
+  /**
+   * Convert a human-readable address into candidate coordinates.
+   *
+   * Uses the platform geocoder: Android `Geocoder` and iOS `CLGeocoder`.
+   * Results and availability depend on platform networking/geocoder services.
+   */
+  geocode(
+    address: string,
+    success: (locations: GeocodedLocation[]) => void,
+    error?: (error: LocationError) => void
+  ): void;
+
+  /**
+   * 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.
+   */
+  reverseGeocode(
+    coords: GeocodingCoordinates,
+    success: (addresses: ReverseGeocodedAddress[]) => void,
+    error?: (error: LocationError) => void
+  ): void;
+
+  /**
+   * Get one heading reading from the platform heading sensor.
+   */
+  getHeading(
+    success: (heading: Heading) => void,
+    error?: (error: LocationError) => void
+  ): void;
+
+  /**
+   * Start watching heading updates.
+   *
+   * Use `unwatch(token)` to stop a heading watch.
+   */
+  watchHeading(
+    success: (heading: Heading) => void,
+    error?: (error: LocationError) => void,
+    options?: HeadingOptions
+  ): string;
 
   /**
    * Start watching for continuous location updates.

package/src/NitroGeolocationCompat.nitro.ts

@@ -1,8 +1,8 @@
 import type { HybridObject } from "react-native-nitro-modules";
 import type {
-  GeolocationError,
-  GeolocationOptions,
-  GeolocationResponse
+  CompatGeolocationError,
+  CompatGeolocationOptions,
+  CompatGeolocationResponse
 } from "./types";
 
 // Configuration - Internal (for C++ codegen, avoiding ANDROID macro conflict)
@@ -12,7 +12,7 @@ export type LocationProviderInternal =
   | "android_platform"
   | "auto";
 
-export interface RNConfigurationInternal {
+export interface CompatGeolocationConfigurationInternal {
   skipPermissionRequests: boolean;
   authorizationLevel?: AuthorizationLevelInternal;
   enableBackgroundLocationUpdates?: boolean;
@@ -21,20 +21,20 @@ export interface RNConfigurationInternal {
 
 export interface NitroGeolocationCompat
   extends HybridObject<{ ios: "swift"; android: "kotlin" }> {
-  setRNConfiguration(config: RNConfigurationInternal): void;
+  setRNConfiguration(config: CompatGeolocationConfigurationInternal): void;
   requestAuthorization(
     success?: () => void,
-    error?: (error: GeolocationError) => void
+    error?: (error: CompatGeolocationError) => void
   ): void;
   getCurrentPosition(
-    success: (position: GeolocationResponse) => void,
-    error?: (error: GeolocationError) => void,
-    options?: GeolocationOptions
+    success: (position: CompatGeolocationResponse) => void,
+    error?: (error: CompatGeolocationError) => void,
+    options?: CompatGeolocationOptions
   ): void;
   watchPosition(
-    success: (position: GeolocationResponse) => void,
-    error?: (error: GeolocationError) => void,
-    options?: GeolocationOptions
+    success: (position: CompatGeolocationResponse) => void,
+    error?: (error: CompatGeolocationError) => void,
+    options?: CompatGeolocationOptions
   ): number;
   clearWatch(watchId: number): void;
   stopObserving(): void;

package/src/api/geocode.ts

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

package/src/api/getAccuracyAuthorization.ts

@@ -0,0 +1,12 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { AccuracyAuthorization } from "../publicTypes";
+
+/**
+ * Get current platform location accuracy authorization.
+ *
+ * iOS maps Core Location full/reduced accuracy authorization. Android maps
+ * fine permission to `full` and coarse-only permission to `reduced`.
+ */
+export function getAccuracyAuthorization(): Promise<AccuracyAuthorization> {
+  return NitroGeolocationHybridObject.getAccuracyAuthorization();
+}

package/src/api/getCurrentPosition.ts

@@ -2,7 +2,7 @@ import type { LocationRequestOptions } from "../NitroGeolocation.nitro";
 import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
 import { isDevtoolsEnabled } from "../devtools";
 import { getDevtoolsCurrentPosition } from "../devtools/getCurrentPosition";
-import type { GeolocationResponse } from "../types";
+import type { GeolocationResponse } from "../publicTypes";
 
 /**
  * Get current location (one-time request).
@@ -21,7 +21,7 @@ import type { GeolocationResponse } from "../types";
  *
  * try {
  *   const position = await getCurrentPosition({
- *     enableHighAccuracy: true,
+ *     accuracy: { android: "high", ios: "best" },
  *     timeout: 15000
  *   });
  *   console.log(position.coords.latitude, position.coords.longitude);
@@ -39,5 +39,7 @@ export function getCurrentPosition(
       return devtoolsResult;
     }
   }
-  return NitroGeolocationHybridObject.getCurrentPosition(options);
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.getCurrentPosition(resolve, reject, options);
+  });
 }

package/src/api/getHeading.ts

@@ -0,0 +1,13 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { Heading } from "../publicTypes";
+
+/**
+ * Get one platform heading reading.
+ *
+ * @returns Promise resolving to magnetic/true heading data.
+ */
+export function getHeading(): Promise<Heading> {
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.getHeading(resolve, reject);
+  });
+}

package/src/api/getLastKnownPosition.ts

@@ -0,0 +1,28 @@
+import type { LocationRequestOptions } from "../NitroGeolocation.nitro";
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import { isDevtoolsEnabled } from "../devtools";
+import { getDevtoolsCurrentPosition } from "../devtools/getCurrentPosition";
+import type { GeolocationResponse } from "../publicTypes";
+
+/**
+ * Get the best cached location without starting a fresh native location
+ * request.
+ *
+ * @param options - Cache filtering and provider selection options
+ * @returns Promise resolving to a cached position
+ * @throws LocationError if permission is denied or no cached location exists
+ */
+export function getLastKnownPosition(
+  options?: LocationRequestOptions
+): Promise<GeolocationResponse> {
+  if (isDevtoolsEnabled()) {
+    const devtoolsResult = getDevtoolsCurrentPosition();
+    if (devtoolsResult) {
+      return devtoolsResult;
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    NitroGeolocationHybridObject.getLastKnownPosition(resolve, reject, options);
+  });
+}

package/src/api/getLocationAvailability.ts

@@ -0,0 +1,11 @@
+import { NitroGeolocationHybridObject } from "../NitroGeolocationModule";
+import type { LocationAvailability } from "../publicTypes";
+
+/**
+ * Check whether the current platform is likely to deliver location updates.
+ *
+ * @returns Promise resolving to availability state plus an optional reason.
+ */
+export function getLocationAvailability(): Promise<LocationAvailability> {
+  return NitroGeolocationHybridObject.getLocationAvailability();
+}

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();
+}