@tsachit/react-native-geo-service 1.0.0

package/ios/RNGeoService.m

@@ -0,0 +1,311 @@
+#import "RNGeoService.h"
+#import <React/RCTLog.h>
+
+// ---------------------------------------------------------------------------
+// CLActivityType helper
+// ---------------------------------------------------------------------------
+static CLActivityType activityTypeFromString(NSString *type) {
+    if ([type isEqualToString:@"automotiveNavigation"]) return CLActivityTypeAutomotiveNavigation;
+    if ([type isEqualToString:@"fitness"])              return CLActivityTypeFitness;
+    if ([type isEqualToString:@"otherNavigation"])      return CLActivityTypeOtherNavigation;
+    if (@available(iOS 12.0, *)) {
+        if ([type isEqualToString:@"airborne"])         return CLActivityTypeAirborne;
+    }
+    return CLActivityTypeOther;
+}
+
+// ---------------------------------------------------------------------------
+// CLLocationAccuracy helper
+// ---------------------------------------------------------------------------
+static CLLocationAccuracy accuracyFromString(NSString *accuracy) {
+    if ([accuracy isEqualToString:@"navigation"])  return kCLLocationAccuracyBestForNavigation;
+    if ([accuracy isEqualToString:@"high"])        return kCLLocationAccuracyBest;
+    if ([accuracy isEqualToString:@"low"])         return kCLLocationAccuracyKilometer;
+    // "balanced" → nearest 100 metres — good trade-off between precision and battery
+    return kCLLocationAccuracyHundredMeters;
+}
+
+// ---------------------------------------------------------------------------
+// RNGeoService implementation
+// ---------------------------------------------------------------------------
+@interface RNGeoService ()
+
+@property (nonatomic, strong) CLLocationManager *locationManager;
+@property (nonatomic, strong) NSDictionary *config;
+
+@property (nonatomic, assign) BOOL isTracking;
+@property (nonatomic, assign) BOOL hasListeners;
+@property (nonatomic, assign) BOOL coarseTracking;
+@property (nonatomic, assign) BOOL debugMode;
+
+// Adaptive accuracy state
+@property (nonatomic, assign) BOOL adaptiveAccuracy;
+@property (nonatomic, assign) float idleSpeedThreshold;
+@property (nonatomic, assign) NSInteger idleSampleCount;
+@property (nonatomic, assign) NSInteger slowReadingCount;
+@property (nonatomic, assign) BOOL isIdle;
+
+@end
+
+@implementation RNGeoService
+
+RCT_EXPORT_MODULE();
+
++ (BOOL)requiresMainQueueSetup {
+    return YES;
+}
+
+- (dispatch_queue_t)methodQueue {
+    return dispatch_get_main_queue();
+}
+
+// ---------------------------------------------------------------------------
+// Supported events
+// ---------------------------------------------------------------------------
+- (NSArray<NSString *> *)supportedEvents {
+    return @[@"onLocation", @"onError"];
+}
+
+- (void)startObserving { self.hasListeners = YES; }
+- (void)stopObserving  { self.hasListeners = NO;  }
+
+// ---------------------------------------------------------------------------
+// Lazy CLLocationManager
+// ---------------------------------------------------------------------------
+- (CLLocationManager *)locationManager {
+    if (!_locationManager) {
+        _locationManager = [[CLLocationManager alloc] init];
+        _locationManager.delegate = self;
+    }
+    return _locationManager;
+}
+
+// ---------------------------------------------------------------------------
+// configure()
+// ---------------------------------------------------------------------------
+RCT_EXPORT_METHOD(configure:(NSDictionary *)options
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    self.config = options;
+    self.coarseTracking   = [options[@"coarseTracking"] boolValue];
+    self.debugMode        = [options[@"debug"] boolValue];
+    self.adaptiveAccuracy = options[@"adaptiveAccuracy"] ? [options[@"adaptiveAccuracy"] boolValue] : YES;
+    self.idleSpeedThreshold = options[@"idleSpeedThreshold"] ? [options[@"idleSpeedThreshold"] floatValue] : 0.5f;
+    self.idleSampleCount  = options[@"idleSampleCount"] ? [options[@"idleSampleCount"] integerValue] : 3;
+    self.slowReadingCount = 0;
+    self.isIdle           = NO;
+
+    [self applyConfigToLocationManager];
+
+    if (self.debugMode) RCTLogInfo(@"[RNGeoService] Config applied: %@", options);
+    resolve(nil);
+}
+
+- (void)applyConfigToLocationManager {
+    NSDictionary *cfg = self.config ?: @{};
+
+    NSString *accuracy = cfg[@"accuracy"] ?: @"balanced";
+    self.locationManager.desiredAccuracy = accuracyFromString(accuracy);
+
+    double minDist = [cfg[@"minDistanceMeters"] doubleValue];
+    self.locationManager.distanceFilter = (minDist > 0) ? minDist : kCLDistanceFilterNone;
+
+    NSString *motionActivity = cfg[@"motionActivity"] ?: @"other";
+    self.locationManager.activityType = activityTypeFromString(motionActivity);
+
+    BOOL autoPause = [cfg[@"autoPauseUpdates"] boolValue];
+    self.locationManager.pausesLocationUpdatesAutomatically = autoPause;
+
+    if (@available(iOS 11.0, *)) {
+        BOOL bgIndicator = [cfg[@"showBackgroundIndicator"] boolValue];
+        self.locationManager.showsBackgroundLocationIndicator = bgIndicator;
+    }
+
+    self.locationManager.allowsBackgroundLocationUpdates = YES;
+}
+
+// ---------------------------------------------------------------------------
+// start()
+// ---------------------------------------------------------------------------
+RCT_EXPORT_METHOD(start:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    CLAuthorizationStatus status = [CLLocationManager authorizationStatus];
+
+    if (status == kCLAuthorizationStatusDenied ||
+        status == kCLAuthorizationStatusRestricted) {
+        reject(@"PERMISSION_DENIED", @"Location permission denied. Request 'Always' permission before calling start().", nil);
+        return;
+    }
+
+    if (status == kCLAuthorizationStatusNotDetermined) {
+        [self.locationManager requestAlwaysAuthorization];
+    }
+
+    [self applyConfigToLocationManager];
+
+    if (self.coarseTracking) {
+        [self.locationManager startMonitoringSignificantLocationChanges];
+        if (self.debugMode) RCTLogInfo(@"[RNGeoService] Coarse (significant-change) tracking started");
+    } else {
+        [self.locationManager startUpdatingLocation];
+        if (self.debugMode) RCTLogInfo(@"[RNGeoService] Standard tracking started");
+    }
+
+    self.isTracking = YES;
+    [[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"GeoServiceIsTracking"];
+    [[NSUserDefaults standardUserDefaults] synchronize];
+
+    resolve(nil);
+}
+
+// ---------------------------------------------------------------------------
+// stop()
+// ---------------------------------------------------------------------------
+RCT_EXPORT_METHOD(stop:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    if (self.coarseTracking) {
+        [self.locationManager stopMonitoringSignificantLocationChanges];
+    } else {
+        [self.locationManager stopUpdatingLocation];
+    }
+
+    self.isTracking = NO;
+    [[NSUserDefaults standardUserDefaults] setBool:NO forKey:@"GeoServiceIsTracking"];
+    [[NSUserDefaults standardUserDefaults] synchronize];
+
+    if (self.debugMode) RCTLogInfo(@"[RNGeoService] Tracking stopped");
+    resolve(nil);
+}
+
+// ---------------------------------------------------------------------------
+// isTracking() / getCurrentLocation()
+// ---------------------------------------------------------------------------
+RCT_EXPORT_METHOD(isTracking:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    resolve(@(self.isTracking));
+}
+
+RCT_EXPORT_METHOD(getCurrentLocation:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    CLLocation *last = self.locationManager.location;
+    if (last) {
+        resolve([self locationToDictionary:last]);
+    } else {
+        reject(@"NO_LOCATION", @"No cached location available. Call start() first.", nil);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CLLocationManagerDelegate
+// ---------------------------------------------------------------------------
+- (void)locationManager:(CLLocationManager *)manager
+     didUpdateLocations:(NSArray<CLLocation *> *)locations {
+    CLLocation *location = [locations lastObject];
+    if (!location) return;
+
+    if (self.debugMode) {
+        RCTLogInfo(@"[RNGeoService] Location: %f, %f (±%.0fm) speed=%.1fm/s",
+                   location.coordinate.latitude,
+                   location.coordinate.longitude,
+                   location.horizontalAccuracy,
+                   location.speed);
+    }
+
+    if (self.adaptiveAccuracy && !self.coarseTracking) {
+        [self evaluateMotionState:location];
+    }
+
+    if (self.hasListeners) {
+        [self sendEventWithName:@"onLocation" body:[self locationToDictionary:location]];
+    }
+}
+
+- (void)evaluateMotionState:(CLLocation *)location {
+    // speed is -1 when unavailable (e.g. first fix from cache) — treat as moving
+    float speed = (location.speed >= 0) ? (float)location.speed : 1.0f;
+
+    if (speed < self.idleSpeedThreshold) {
+        self.slowReadingCount++;
+        if (!self.isIdle && self.slowReadingCount >= self.idleSampleCount) {
+            self.isIdle = YES;
+            self.slowReadingCount = 0;
+            // Reduce accuracy — CoreLocation stops requesting GPS
+            self.locationManager.desiredAccuracy = kCLLocationAccuracyKilometer;
+            self.locationManager.distanceFilter = 50.0;
+            if (self.debugMode) RCTLogInfo(@"[RNGeoService] Device idle — GPS off");
+        }
+    } else {
+        if (self.isIdle) {
+            self.isIdle = NO;
+            self.slowReadingCount = 0;
+            [self applyConfigToLocationManager];
+            if (self.debugMode) RCTLogInfo(@"[RNGeoService] Movement detected — accuracy restored");
+        } else {
+            self.slowReadingCount = 0;
+        }
+    }
+}
+
+- (void)locationManager:(CLLocationManager *)manager
+       didFailWithError:(NSError *)error {
+    // kCLErrorLocationUnknown (code 0) is transient — CoreLocation couldn't get a
+    // fix yet but will keep trying automatically. Silently ignore it so we don't
+    // surface a noisy error to the app before the GPS has warmed up.
+    if ([error.domain isEqualToString:kCLErrorDomain] && error.code == kCLErrorLocationUnknown) {
+        if (self.debugMode) RCTLogInfo(@"[RNGeoService] Location unknown (transient) — waiting for GPS fix");
+        return;
+    }
+
+    // kCLErrorDenied means the user revoked location permission — this is a real
+    // error worth surfacing, and we should stop tracking to avoid repeated failures.
+    if ([error.domain isEqualToString:kCLErrorDomain] && error.code == kCLErrorDenied) {
+        RCTLogWarn(@"[RNGeoService] Location permission denied — stopping tracking");
+        [self.locationManager stopUpdatingLocation];
+        [self.locationManager stopMonitoringSignificantLocationChanges];
+    } else {
+        RCTLogError(@"[RNGeoService] Location error: %@", error.localizedDescription);
+    }
+
+    if (self.hasListeners) {
+        [self sendEventWithName:@"onError" body:@{
+            @"code":    @(error.code),
+            @"message": error.localizedDescription ?: @"Unknown location error"
+        }];
+    }
+}
+
+- (void)locationManager:(CLLocationManager *)manager
+    didChangeAuthorizationStatus:(CLAuthorizationStatus)status {
+    if (self.debugMode) RCTLogInfo(@"[RNGeoService] Auth status: %d", status);
+
+    // Resume tracking after background relaunch (e.g. significant location change)
+    if (status == kCLAuthorizationStatusAuthorizedAlways &&
+        [[NSUserDefaults standardUserDefaults] boolForKey:@"GeoServiceIsTracking"]) {
+        [self applyConfigToLocationManager];
+        if (self.coarseTracking) {
+            [self.locationManager startMonitoringSignificantLocationChanges];
+        } else {
+            [self.locationManager startUpdatingLocation];
+        }
+        self.isTracking = YES;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+- (NSDictionary *)locationToDictionary:(CLLocation *)location {
+    return @{
+        @"latitude":         @(location.coordinate.latitude),
+        @"longitude":        @(location.coordinate.longitude),
+        @"accuracy":         @(location.horizontalAccuracy),
+        @"altitude":         @(location.altitude),
+        @"altitudeAccuracy": @(location.verticalAccuracy),
+        @"speed":            @(location.speed),
+        @"bearing":          @(location.course),
+        @"timestamp":        @((long long)(location.timestamp.timeIntervalSince1970 * 1000)),
+        @"isStationary":     @(self.isIdle)
+    };
+}
+
+@end

package/lib/index.d.ts

@@ -0,0 +1,73 @@
+import { GeoServiceConfig, GeoSubscription, Location, LocationCallback, ErrorCallback } from './types';
+export * from './types';
+/**
+ * Configure the geo service. Call this before start().
+ * Safe to call multiple times; subsequent calls update the config.
+ */
+declare function configure(config: GeoServiceConfig): Promise<void>;
+/**
+ * Start background location tracking.
+ * On Android, this starts a foreground service with a persistent notification.
+ * On iOS, this starts standard or significant-change location monitoring.
+ */
+declare function start(): Promise<void>;
+/**
+ * Stop background location tracking.
+ */
+declare function stop(): Promise<void>;
+/**
+ * Fetch the current device location as a one-time request.
+ */
+declare function getCurrentLocation(): Promise<Location>;
+/**
+ * Returns whether the geo service is currently tracking.
+ */
+declare function isTracking(): Promise<boolean>;
+/**
+ * Subscribe to location updates.
+ * Returns a GeoSubscription — call .remove() to unsubscribe.
+ *
+ * @example
+ * const sub = RNGeoService.onLocation((location) => {
+ *   console.log(location.latitude, location.longitude);
+ * });
+ * // Later:
+ * sub.remove();
+ */
+declare function onLocation(callback: LocationCallback): GeoSubscription;
+/**
+ * Subscribe to location errors.
+ */
+declare function onError(callback: ErrorCallback): GeoSubscription;
+/**
+ * Register a headless task handler for Android background processing.
+ *
+ * When the app is not in the foreground, location updates are delivered via
+ * HeadlessJS. Register your handler here OR in your app's index.js using
+ * AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', ...).
+ *
+ * The handler receives a Location object and should return a Promise.
+ *
+ * @example
+ * // In index.js (outside the App component, at the top level):
+ * import { AppRegistry } from 'react-native';
+ * AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', () => async (location) => {
+ *   console.log('[Headless] Location:', location);
+ *   // Send to your server using a pre-stored auth token (e.g. SecureStore/Keychain).
+ *   // Do not rely on in-memory app state — this context is headless and isolated.
+ * });
+ *
+ * @platform android
+ */
+declare function registerHeadlessTask(handler: (location: Location) => Promise<void>): void;
+declare const RNGeoService: {
+    configure: typeof configure;
+    start: typeof start;
+    stop: typeof stop;
+    getCurrentLocation: typeof getCurrentLocation;
+    isTracking: typeof isTracking;
+    onLocation: typeof onLocation;
+    onError: typeof onError;
+    registerHeadlessTask: typeof registerHeadlessTask;
+};
+export default RNGeoService;

package/lib/index.js

@@ -0,0 +1,155 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_native_1 = require("react-native");
+__exportStar(require("./types"), exports);
+// The native bridge module registered as "RNGeoService" on both platforms
+const nativeModule = react_native_1.NativeModules.RNGeoService;
+if (!nativeModule) {
+    throw new Error('[react-native-geo-service] Native module not found. ' +
+        'Make sure you have linked the native module correctly. ' +
+        'For iOS run `pod install`, for Android rebuild the project.');
+}
+const eventEmitter = new react_native_1.NativeEventEmitter(nativeModule);
+const DEFAULT_CONFIG = {
+    minDistanceMeters: 10,
+    accuracy: 'balanced',
+    stopOnAppClose: false,
+    restartOnBoot: false,
+    updateIntervalMs: 5000,
+    minUpdateIntervalMs: 2000,
+    serviceTitle: 'Location Tracking',
+    serviceBody: 'Your location is being tracked in the background.',
+    backgroundTaskName: 'GeoServiceHeadlessTask',
+    motionActivity: 'other',
+    autoPauseUpdates: false,
+    showBackgroundIndicator: false,
+    coarseTracking: false,
+    adaptiveAccuracy: true,
+    idleSpeedThreshold: 0.5,
+    idleSampleCount: 3,
+    debug: false,
+};
+/**
+ * Configure the geo service. Call this before start().
+ * Safe to call multiple times; subsequent calls update the config.
+ */
+function configure(config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const merged = Object.assign(Object.assign({}, DEFAULT_CONFIG), config);
+        return nativeModule.configure(merged);
+    });
+}
+/**
+ * Start background location tracking.
+ * On Android, this starts a foreground service with a persistent notification.
+ * On iOS, this starts standard or significant-change location monitoring.
+ */
+function start() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return nativeModule.start();
+    });
+}
+/**
+ * Stop background location tracking.
+ */
+function stop() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return nativeModule.stop();
+    });
+}
+/**
+ * Fetch the current device location as a one-time request.
+ */
+function getCurrentLocation() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return nativeModule.getCurrentLocation();
+    });
+}
+/**
+ * Returns whether the geo service is currently tracking.
+ */
+function isTracking() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return nativeModule.isTracking();
+    });
+}
+/**
+ * Subscribe to location updates.
+ * Returns a GeoSubscription — call .remove() to unsubscribe.
+ *
+ * @example
+ * const sub = RNGeoService.onLocation((location) => {
+ *   console.log(location.latitude, location.longitude);
+ * });
+ * // Later:
+ * sub.remove();
+ */
+function onLocation(callback) {
+    return eventEmitter.addListener('onLocation', callback);
+}
+/**
+ * Subscribe to location errors.
+ */
+function onError(callback) {
+    return eventEmitter.addListener('onError', callback);
+}
+/**
+ * Register a headless task handler for Android background processing.
+ *
+ * When the app is not in the foreground, location updates are delivered via
+ * HeadlessJS. Register your handler here OR in your app's index.js using
+ * AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', ...).
+ *
+ * The handler receives a Location object and should return a Promise.
+ *
+ * @example
+ * // In index.js (outside the App component, at the top level):
+ * import { AppRegistry } from 'react-native';
+ * AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', () => async (location) => {
+ *   console.log('[Headless] Location:', location);
+ *   // Send to your server using a pre-stored auth token (e.g. SecureStore/Keychain).
+ *   // Do not rely on in-memory app state — this context is headless and isolated.
+ * });
+ *
+ * @platform android
+ */
+function registerHeadlessTask(handler) {
+    if (react_native_1.Platform.OS !== 'android')
+        return;
+    const taskName = DEFAULT_CONFIG.backgroundTaskName;
+    react_native_1.AppRegistry.registerHeadlessTask(taskName, () => handler);
+}
+const RNGeoService = {
+    configure,
+    start,
+    stop,
+    getCurrentLocation,
+    isTracking,
+    onLocation,
+    onError,
+    registerHeadlessTask,
+};
+exports.default = RNGeoService;

package/lib/types.d.ts

@@ -0,0 +1,139 @@
+export interface GeoServiceConfig {
+    /**
+     * Minimum distance in meters the device must move before a location update is fired.
+     * Higher values = fewer updates = better battery life.
+     * Default: 10
+     */
+    minDistanceMeters?: number;
+    /**
+     * Location accuracy mode.
+     * - 'navigation': GPS-level accuracy (most battery)
+     * - 'high': High accuracy
+     * - 'balanced': City-block accuracy, uses cell/WiFi (recommended for most apps)
+     * - 'low': Approximate location, very low battery usage
+     * Default: 'balanced'
+     */
+    accuracy?: 'navigation' | 'high' | 'balanced' | 'low';
+    /**
+     * Stop location tracking when the app is closed by the user.
+     * Set to false for always-on headless tracking.
+     * Default: false
+     */
+    stopOnAppClose?: boolean;
+    /**
+     * Automatically restart tracking on device reboot (Android only).
+     * Default: false
+     */
+    restartOnBoot?: boolean;
+    /**
+     * Target time interval between location updates in milliseconds (Android only).
+     * Default: 5000
+     */
+    updateIntervalMs?: number;
+    /**
+     * Minimum time between location updates in milliseconds (Android only).
+     * Updates will never arrive faster than this value.
+     * Default: 2000
+     */
+    minUpdateIntervalMs?: number;
+    /**
+     * Title of the persistent foreground service notification (Android only).
+     * Default: 'Location Tracking'
+     */
+    serviceTitle?: string;
+    /**
+     * Body text of the persistent foreground service notification (Android only).
+     * Default: 'Your location is being tracked in the background.'
+     */
+    serviceBody?: string;
+    /**
+     * Name of the HeadlessJS task to invoke when the app is not in the foreground (Android only).
+     * Register this task in your app's index.js using AppRegistry.registerHeadlessTask().
+     * Default: 'GeoServiceHeadlessTask'
+     */
+    backgroundTaskName?: string;
+    /**
+     * Hint to the OS about what kind of motion this location data is used for (iOS only).
+     * Allows CoreLocation to apply activity-specific power optimisations.
+     * Default: 'other'
+     */
+    motionActivity?: 'other' | 'automotiveNavigation' | 'fitness' | 'otherNavigation' | 'airborne';
+    /**
+     * Allow iOS to automatically pause location updates when no movement is detected.
+     * Set to false to always receive updates.
+     * Default: false
+     */
+    autoPauseUpdates?: boolean;
+    /**
+     * Show the blue location indicator in the iOS status bar when tracking in background.
+     * Default: false
+     */
+    showBackgroundIndicator?: boolean;
+    /**
+     * Use Significant Location Changes instead of standard location updates (iOS only).
+     * Much more battery efficient — only fires when the device moves ~500m.
+     * Wakes the app even if it was terminated.
+     * Default: false
+     */
+    coarseTracking?: boolean;
+    /**
+     * Automatically drop to low-power mode when the device appears stationary,
+     * and restore the configured accuracy the moment movement is detected again.
+     *
+     * On Android this turns the GPS chip completely off while parked.
+     * On iOS this reduces accuracy to kCLLocationAccuracyKilometer while still.
+     *
+     * This is the single biggest battery saving for apps that track driving/walking —
+     * GPS stays off while the user is parked or sitting still.
+     * Default: true
+     */
+    adaptiveAccuracy?: boolean;
+    /**
+     * Speed in m/s below which a reading is counted as "idle/stationary".
+     * Default: 0.5 (~1.8 km/h)
+     */
+    idleSpeedThreshold?: number;
+    /**
+     * Number of consecutive idle readings required before entering low-power mode.
+     * Higher = fewer false positives but slower to power down.
+     * Default: 3
+     */
+    idleSampleCount?: number;
+    /**
+     * Enable verbose native logging.
+     * Default: false
+     */
+    debug?: boolean;
+}
+export interface Location {
+    latitude: number;
+    longitude: number;
+    /** Horizontal accuracy in meters */
+    accuracy: number;
+    altitude: number;
+    /** Vertical accuracy in meters (iOS only, -1 on Android) */
+    altitudeAccuracy: number;
+    /** Speed in meters per second, -1 if unavailable */
+    speed: number;
+    /** Bearing/heading in degrees (0–360), -1 if unavailable */
+    bearing: number;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Whether this location came from a mock provider (Android only) */
+    isFromMockProvider?: boolean;
+    /** True when adaptive accuracy has detected the device is idle and GPS is off */
+    isStationary?: boolean;
+}
+export interface LocationError {
+    code: number;
+    message: string;
+}
+export type LocationCallback = (location: Location) => void;
+export type ErrorCallback = (error: LocationError) => void;
+/**
+ * Returned by onLocation() and onError().
+ * Call .remove() to stop receiving updates and clean up the listener.
+ */
+export interface GeoSubscription {
+    remove(): void;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });