react-native-nitro-geolocation 1.2.5 → 1.3.0

package/src/background/types.ts

@@ -0,0 +1,328 @@
+import type {
+  LocationError,
+  PermissionStatus
+} from "../NitroGeolocation.nitro";
+import type {
+  AccuracyAuthorization,
+  AndroidGranularity,
+  GeolocationResponse,
+  LocationAccuracyOptions,
+  LocationProviderStatus,
+  LocationProviderUsed
+} from "../publicTypes";
+
+export type BackgroundPermissionStatus =
+  | "granted"
+  | "denied"
+  | "restricted"
+  | "undetermined";
+
+export interface BackgroundPermissionResult {
+  foreground: PermissionStatus;
+  background: BackgroundPermissionStatus;
+  accuracyAuthorization?: AccuracyAuthorization;
+  canRequestBackgroundInline?: boolean;
+  needsSettingsRedirect?: boolean;
+}
+
+export type BackgroundLocationState =
+  | "idle"
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "error";
+
+export interface AndroidBackgroundLocationStatus {
+  isForegroundServiceRunning: boolean;
+  isIgnoringBatteryOptimizations?: boolean;
+  notificationPermission?: PermissionStatus;
+}
+
+export interface IOSBackgroundLocationStatus {
+  allowsBackgroundLocationUpdates: boolean;
+  significantChangesEnabled: boolean;
+}
+
+export interface BackgroundLocationStatus {
+  state: BackgroundLocationState;
+  isRunning: boolean;
+  isConfigured: boolean;
+  foregroundPermission: PermissionStatus;
+  backgroundPermission: BackgroundPermissionStatus;
+  accuracyAuthorization?: AccuracyAuthorization;
+  locationServicesEnabled: boolean;
+  providerStatus?: LocationProviderStatus;
+  storedLocationCount: number;
+  storedEventCount: number;
+  geofenceCount: number;
+  android?: AndroidBackgroundLocationStatus;
+  ios?: IOSBackgroundLocationStatus;
+  lastError?: LocationError;
+}
+
+export type BackgroundTrackingMode =
+  | "continuous"
+  | "significantChanges"
+  | "activityAware";
+
+export interface BackgroundLocationOptions {
+  trackingMode?: BackgroundTrackingMode;
+  accuracy?: LocationAccuracyOptions;
+  granularity?: AndroidGranularity;
+  interval?: number;
+  fastestInterval?: number;
+  distanceFilter?: number;
+  maxUpdateDelay?: number;
+  waitForAccurateLocation?: boolean;
+  persist?: boolean;
+  maxStoredLocations?: number;
+  maxStoredEvents?: number;
+  stopOnTerminate?: boolean;
+  startOnBoot?: boolean;
+  android?: AndroidBackgroundLocationOptions;
+  ios?: IOSBackgroundLocationOptions;
+  geofencing?: GeofencingOptions;
+  activityRecognition?: ActivityRecognitionOptions;
+  sync?: BackgroundHttpSyncOptions;
+}
+
+export type AndroidBackgroundProvider =
+  | "auto"
+  | "playServices"
+  | "android_platform";
+
+export interface AndroidBackgroundLocationOptions {
+  locationProvider?: AndroidBackgroundProvider;
+  foregroundService: AndroidForegroundServiceOptions;
+  requestNotificationPermission?: boolean;
+  requestIgnoreBatteryOptimizations?: boolean;
+}
+
+export interface AndroidForegroundServiceOptions {
+  notificationId?: number;
+  notificationTitle: string;
+  notificationText: string;
+  notificationChannelId?: string;
+  notificationChannelName?: string;
+  notificationChannelDescription?: string;
+  notificationIcon?: string;
+  notificationColor?: string;
+  stopActionTitle?: string;
+}
+
+export type IOSBackgroundActivityType =
+  | "other"
+  | "automotiveNavigation"
+  | "fitness"
+  | "otherNavigation"
+  | "airborne";
+
+export interface IOSBackgroundLocationOptions {
+  activityType?: IOSBackgroundActivityType;
+  pausesLocationUpdatesAutomatically?: boolean;
+  showsBackgroundLocationIndicator?: boolean;
+  useSignificantChanges?: boolean;
+  deferredUpdatesDistance?: number;
+  deferredUpdatesInterval?: number;
+}
+
+export type BackgroundLocationSource =
+  | "foregroundService"
+  | "background"
+  | "significantChange"
+  | "geofence"
+  | "deferred"
+  | "manual"
+  | "unknown";
+
+export interface BatterySnapshot {
+  level?: number;
+  isCharging?: boolean;
+}
+
+export interface BackgroundLocation extends GeolocationResponse {
+  id?: string;
+  source: BackgroundLocationSource;
+  isFromBackground: boolean;
+  provider?: LocationProviderUsed;
+  mocked?: boolean;
+  recordedAt: number;
+  activity?: DetectedActivity;
+  battery?: BatterySnapshot;
+}
+
+export interface StoredBackgroundLocation extends BackgroundLocation {
+  id: string;
+  deliveredToJS: boolean;
+  synced: boolean;
+  createdAt: number;
+}
+
+export type BackgroundEventType =
+  | "location"
+  | "geofence"
+  | "activity"
+  | "providerChange"
+  | "httpSync"
+  | "error";
+
+export interface BackgroundEventBase {
+  id: string;
+  type: BackgroundEventType;
+  timestamp: number;
+  deliveredToJS: boolean;
+}
+
+export interface BackgroundLocationEvent extends BackgroundEventBase {
+  type: "location";
+  location: BackgroundLocation;
+}
+
+export interface BackgroundGeofenceEventEnvelope extends BackgroundEventBase {
+  type: "geofence";
+  geofence: GeofenceEvent;
+}
+
+export interface BackgroundActivityEventEnvelope extends BackgroundEventBase {
+  type: "activity";
+  activity: DetectedActivity;
+}
+
+export interface BackgroundProviderChangeEvent extends BackgroundEventBase {
+  type: "providerChange";
+  providerStatus: LocationProviderStatus;
+}
+
+export interface BackgroundHttpSyncEvent extends BackgroundEventBase {
+  type: "httpSync";
+  result: BackgroundHttpSyncResult;
+}
+
+export interface BackgroundErrorEvent extends BackgroundEventBase {
+  type: "error";
+  error: LocationError;
+}
+
+export interface BackgroundEventEnvelope extends BackgroundEventBase {
+  location?: BackgroundLocation;
+  geofence?: GeofenceEvent;
+  activity?: DetectedActivity;
+  providerStatus?: LocationProviderStatus;
+  result?: BackgroundHttpSyncResult;
+  error?: LocationError;
+}
+
+export type BackgroundEvent =
+  | BackgroundLocationEvent
+  | BackgroundGeofenceEventEnvelope
+  | BackgroundActivityEventEnvelope
+  | BackgroundProviderChangeEvent
+  | BackgroundHttpSyncEvent
+  | BackgroundErrorEvent;
+
+export type GeofenceTransition = "enter" | "exit" | "dwell";
+
+export interface GeofenceRegion {
+  identifier: string;
+  latitude: number;
+  longitude: number;
+  radius: number;
+  notifyOnEntry?: boolean;
+  notifyOnExit?: boolean;
+  notifyOnDwell?: boolean;
+  loiteringDelay?: number;
+  expirationDuration?: number;
+  metadata?: Record<string, string | number | boolean | null>;
+}
+
+export interface GeofencingOptions {
+  initialTrigger?: GeofenceTransition[];
+  notificationResponsiveness?: number;
+}
+
+export interface GeofenceEvent {
+  region: GeofenceRegion;
+  transition: GeofenceTransition;
+  location?: BackgroundLocation;
+  timestamp: number;
+}
+
+export type DetectedActivityType =
+  | "still"
+  | "walking"
+  | "running"
+  | "onFoot"
+  | "onBicycle"
+  | "inVehicle"
+  | "tilting"
+  | "unknown";
+
+export interface DetectedActivity {
+  type: DetectedActivityType;
+  confidence: number;
+  timestamp: number;
+}
+
+export interface ActivityRecognitionOptions {
+  enabled?: boolean;
+  interval?: number;
+  stopOnStill?: boolean;
+  minimumConfidence?: number;
+}
+
+export type BackgroundHttpMethod = "POST" | "PUT" | "PATCH";
+
+export interface BackgroundHttpSyncOptions {
+  url: string;
+  method?: BackgroundHttpMethod;
+  headers?: Record<string, string>;
+  batch?: boolean;
+  batchSize?: number;
+  syncThreshold?: number;
+  syncInterval?: number;
+  retry?: boolean;
+  maxRetries?: number;
+  bodyTemplate?: Record<string, string | number | boolean | null>;
+  autoClear?: boolean;
+}
+
+export interface BackgroundHttpSyncResult {
+  success: boolean;
+  statusCode?: number;
+  syncedLocationIds: string[];
+  failedLocationIds: string[];
+  error?: string;
+}
+
+export interface StoredBackgroundEvent extends BackgroundEventBase {
+  event: BackgroundEvent;
+  createdAt: number;
+}
+
+export interface StoredBackgroundEventEnvelope extends BackgroundEventBase {
+  event: BackgroundEventEnvelope;
+  createdAt: number;
+}
+
+export interface GetStoredBackgroundLocationsOptions {
+  limit?: number;
+  since?: number;
+  includeDelivered?: boolean;
+  includeSynced?: boolean;
+}
+
+export interface GetStoredBackgroundEventsOptions {
+  types?: BackgroundEventType[];
+  limit?: number;
+  since?: number;
+  includeDelivered?: boolean;
+}
+
+export interface BackgroundSubscription {
+  remove(): void;
+}
+
+export type BackgroundTaskHandler = (
+  event: BackgroundEvent
+) => void | Promise<void>;

package/src/compat/index.web.ts

@@ -0,0 +1,141 @@
+import type {
+  CompatGeolocationConfiguration,
+  CompatGeolocationError,
+  CompatGeolocationOptions,
+  CompatGeolocationResponse
+} from "../publicTypes";
+import type { BrowserPosition, BrowserPositionError } from "../web/browser";
+import { getGeolocation } from "../web/browser";
+
+export type {
+  CompatGeolocationConfiguration as GeolocationConfiguration,
+  CompatGeolocationResponse as GeolocationResponse,
+  CompatGeolocationError as GeolocationError,
+  CompatGeolocationOptions as GeolocationOptions
+} from "../publicTypes";
+
+function mapPosition(pos: BrowserPosition): CompatGeolocationResponse {
+  return {
+    coords: {
+      latitude: pos.coords.latitude,
+      longitude: pos.coords.longitude,
+      altitude: pos.coords.altitude,
+      accuracy: pos.coords.accuracy,
+      altitudeAccuracy: pos.coords.altitudeAccuracy,
+      heading: pos.coords.heading,
+      speed: pos.coords.speed
+    },
+    timestamp: pos.timestamp
+  };
+}
+
+function mapError(err: BrowserPositionError): CompatGeolocationError {
+  return {
+    code: err.code,
+    message: err.message,
+    PERMISSION_DENIED: 1,
+    POSITION_UNAVAILABLE: 2,
+    TIMEOUT: 3
+  };
+}
+
+export function setRNConfiguration(
+  _config: CompatGeolocationConfiguration
+): void {}
+
+export function requestAuthorization(
+  success?: () => void,
+  _error?: (error: CompatGeolocationError) => void
+): void {
+  success?.();
+}
+
+export function getCurrentPosition(
+  success: (position: CompatGeolocationResponse) => void,
+  error?: (error: CompatGeolocationError) => void,
+  options?: CompatGeolocationOptions
+): void {
+  const geo = getGeolocation();
+  if (!geo) {
+    error?.({
+      code: 2,
+      message: "Browser geolocation is unavailable.",
+      PERMISSION_DENIED: 1,
+      POSITION_UNAVAILABLE: 2,
+      TIMEOUT: 3
+    });
+    return;
+  }
+  geo.getCurrentPosition(
+    (pos) => success(mapPosition(pos)),
+    error ? (err) => error(mapError(err)) : undefined,
+    options
+      ? {
+          timeout: options.timeout,
+          maximumAge: options.maximumAge,
+          enableHighAccuracy: options.enableHighAccuracy
+        }
+      : undefined
+  );
+}
+
+const activeWatches = new Set<number>();
+
+export function watchPosition(
+  success: (position: CompatGeolocationResponse) => void,
+  error?: (error: CompatGeolocationError) => void,
+  options?: CompatGeolocationOptions
+): number {
+  const geo = getGeolocation();
+  if (!geo) {
+    error?.({
+      code: 2,
+      message: "Browser geolocation is unavailable.",
+      PERMISSION_DENIED: 1,
+      POSITION_UNAVAILABLE: 2,
+      TIMEOUT: 3
+    });
+    return -1;
+  }
+  const watchId = geo.watchPosition(
+    (pos) => success(mapPosition(pos)),
+    error ? (err) => error(mapError(err)) : undefined,
+    options
+      ? {
+          timeout: options.timeout,
+          maximumAge: options.maximumAge,
+          enableHighAccuracy: options.enableHighAccuracy
+        }
+      : undefined
+  );
+  activeWatches.add(watchId);
+  return watchId;
+}
+
+export function clearWatch(watchId: number): void {
+  getGeolocation()?.clearWatch(watchId);
+  activeWatches.delete(watchId);
+}
+
+export function stopObserving(): void {
+  const geo = getGeolocation();
+  if (!geo) {
+    activeWatches.clear();
+    return;
+  }
+  for (const watchId of activeWatches) {
+    geo.clearWatch(watchId);
+  }
+  activeWatches.clear();
+}
+
+const Geolocation = {
+  setRNConfiguration,
+  requestAuthorization,
+  getCurrentPosition,
+  watchPosition,
+  clearWatch,
+  stopObserving
+};
+
+export default Geolocation;

package/src/index.tsx

@@ -70,6 +70,9 @@ export {
   stopObserving
 } from "./api";
 
+// Background API
+export * from "./background";
+
 // Hooks
 export * from "./hooks";
 

package/src/index.web.tsx

@@ -0,0 +1,41 @@
+/**
+ * Browser implementation for the Modern API.
+ *
+ * This entry intentionally avoids Nitro native imports so web bundlers can use
+ * the package root without loading native bindings.
+ */
+
+export * from "./web";
+export * from "./background/index.web";
+
+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 "./publicTypes";
+
+export * from "./utils";

package/src/publicTypes.ts

@@ -73,8 +73,9 @@ export type GeolocationConfiguration = Omit<
   /**
    * Android location provider.
    *
-   * `auto` currently uses Android's platform `LocationManager` by default.
-   * Set `playServices` explicitly to use Google Play Services fused location.
+   * `auto` and `playServices` prefer Google Play Services fused location when
+   * available and fall back to Android's platform provider. Use `android` to
+   * force Android's platform `LocationManager` path.
    */
   locationProvider?: LocationProvider;
 };
@@ -90,10 +91,10 @@ export type CompatGeolocationConfiguration = Omit<
   "locationProvider"
 > & {
   /**
-   * Android location provider.
+   * Android location provider compatibility option.
    *
-   * `auto` currently uses Android's platform `LocationManager` by default.
-   * Set `playServices` explicitly to use Google Play Services fused location.
+   * Preserved for the legacy `/compat` configuration surface. Use the Modern
+   * API root import when you need Android fused/provider selection.
    */
   locationProvider?: LocationProvider;
 };

package/src/types.ts

@@ -112,6 +112,9 @@ export interface LocationProviderStatus {
   /** Android-only passive provider availability. Undefined on iOS. */
   passiveAvailable?: boolean;
 
+  /** Android-only Google Play Services availability. Undefined on iOS. */
+  googlePlayServicesAvailable?: boolean;
+
   /**
    * Android-only Google Location Accuracy state when Google Play Services
    * exposes it. Undefined on iOS or when unavailable.