use-geo-sync 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+interface GeoPoint {
+    id: string;
+    latitude: number;
+    longitude: number;
+    timestamp: number;
+    accuracy: number | null;
+    speed: number | null;
+}
+interface SyncConfig {
+    batchSize?: number;
+    syncEndpoint?: string;
+    syncIntervalMs?: number;
+    retryLimit?: number;
+}
+type PermissionState = 'idle' | 'requesting' | 'granted_foreground' | 'granted_background' | 'denied';
+interface UseGeoSyncResult {
+    permissionState: PermissionState;
+    requestPermissions: () => Promise<void>;
+    startTracking: () => Promise<void>;
+    stopTracking: () => Promise<void>;
+    isTracking: boolean;
+    queueLength: number;
+}
+
+declare function useGeoPermissions(): {
+    permissionState: PermissionState;
+    requestPermissions: () => Promise<void>;
+    checkPermissions: () => Promise<void>;
+};
+
+declare function useGeoSync(config?: SyncConfig): UseGeoSyncResult;
+
+declare const BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+
+export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, useGeoPermissions, useGeoSync };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+interface GeoPoint {
+    id: string;
+    latitude: number;
+    longitude: number;
+    timestamp: number;
+    accuracy: number | null;
+    speed: number | null;
+}
+interface SyncConfig {
+    batchSize?: number;
+    syncEndpoint?: string;
+    syncIntervalMs?: number;
+    retryLimit?: number;
+}
+type PermissionState = 'idle' | 'requesting' | 'granted_foreground' | 'granted_background' | 'denied';
+interface UseGeoSyncResult {
+    permissionState: PermissionState;
+    requestPermissions: () => Promise<void>;
+    startTracking: () => Promise<void>;
+    stopTracking: () => Promise<void>;
+    isTracking: boolean;
+    queueLength: number;
+}
+
+declare function useGeoPermissions(): {
+    permissionState: PermissionState;
+    requestPermissions: () => Promise<void>;
+    checkPermissions: () => Promise<void>;
+};
+
+declare function useGeoSync(config?: SyncConfig): UseGeoSyncResult;
+
+declare const BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+
+export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, useGeoPermissions, useGeoSync };

package/dist/index.js

@@ -0,0 +1,199 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BACKGROUND_LOCATION_TASK: () => BACKGROUND_LOCATION_TASK,
+  useGeoPermissions: () => useGeoPermissions,
+  useGeoSync: () => useGeoSync
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useGeoPermissions.ts
+var import_react = require("react");
+var Location = __toESM(require("expo-location"));
+function useGeoPermissions() {
+  const [permissionState, setPermissionState] = (0, import_react.useState)("idle");
+  const checkPermissions = (0, import_react.useCallback)(async () => {
+    try {
+      const { status: fgStatus } = await Location.getForegroundPermissionsAsync();
+      if (fgStatus === "granted") {
+        const { status: bgStatus } = await Location.getBackgroundPermissionsAsync();
+        setPermissionState(bgStatus === "granted" ? "granted_background" : "granted_foreground");
+      } else if (fgStatus === "denied") {
+        setPermissionState("denied");
+      } else {
+        setPermissionState("idle");
+      }
+    } catch (error) {
+      console.error("[use-geo-sync] Error checking permissions:", error);
+      setPermissionState("denied");
+    }
+  }, []);
+  (0, import_react.useEffect)(() => {
+    checkPermissions();
+  }, [checkPermissions]);
+  const requestPermissions = (0, import_react.useCallback)(async () => {
+    setPermissionState("requesting");
+    try {
+      const { status: fgStatus } = await Location.requestForegroundPermissionsAsync();
+      if (fgStatus !== "granted") {
+        setPermissionState("denied");
+        return;
+      }
+      const { status: bgStatus } = await Location.requestBackgroundPermissionsAsync();
+      if (bgStatus === "granted") {
+        setPermissionState("granted_background");
+      } else {
+        setPermissionState("granted_foreground");
+      }
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to request location permissions:", error);
+      setPermissionState("denied");
+    }
+  }, []);
+  return {
+    permissionState,
+    requestPermissions,
+    checkPermissions
+  };
+}
+
+// src/useGeoSync.ts
+var import_react2 = require("react");
+var Location2 = __toESM(require("expo-location"));
+
+// src/backgroundTask.ts
+var TaskManager = __toESM(require("expo-task-manager"));
+var BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+var locationQueue = [];
+var activeConfig = { batchSize: 20 };
+var setTaskConfig = (config) => {
+  activeConfig = { ...activeConfig, ...config };
+};
+TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
+  if (error) {
+    console.error("[use-geo-sync] Background task error:", error.message);
+    return;
+  }
+  if (data) {
+    const { locations } = data;
+    const newPoints = locations.map((loc) => ({
+      id: `${loc.timestamp}-${Math.random().toString(36).substr(2, 9)}`,
+      latitude: loc.coords.latitude,
+      longitude: loc.coords.longitude,
+      timestamp: loc.timestamp,
+      accuracy: loc.coords.accuracy,
+      speed: loc.coords.speed
+    }));
+    locationQueue.push(...newPoints);
+    console.log(`[use-geo-sync] \u{1F4CD} Caught ${newPoints.length} points. Queue size: ${locationQueue.length}`);
+    const batchLimit = activeConfig.batchSize || 20;
+    if (activeConfig.syncEndpoint && locationQueue.length >= batchLimit) {
+      console.log(`[use-geo-sync] \u{1F680} Queue hit limit (${batchLimit}). Syncing to backend...`);
+      try {
+        const response = await fetch(activeConfig.syncEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ locations: locationQueue })
+        });
+        if (response.ok) {
+          console.log("[use-geo-sync] \u2705 Sync successful! Clearing queue.");
+          locationQueue = [];
+        } else {
+          console.warn(`[use-geo-sync] \u26A0\uFE0F Sync failed with status: ${response.status}. Keeping data in queue.`);
+        }
+      } catch (networkError) {
+        console.warn("[use-geo-sync] \u{1F50C} Network offline. Points saved in queue for next sync.");
+      }
+    }
+  }
+});
+
+// src/useGeoSync.ts
+function useGeoSync(config) {
+  const { permissionState, requestPermissions } = useGeoPermissions();
+  const [isTracking, setIsTracking] = (0, import_react2.useState)(false);
+  const [queueLength, setQueueLength] = (0, import_react2.useState)(locationQueue.length);
+  (0, import_react2.useEffect)(() => {
+    if (config) {
+      setTaskConfig(config);
+    }
+  }, [config]);
+  const startTracking = (0, import_react2.useCallback)(async () => {
+    if (permissionState !== "granted_background" && permissionState !== "granted_foreground") {
+      console.warn("[use-geo-sync] Cannot start tracking. Permissions not granted.");
+      return;
+    }
+    try {
+      await Location2.startLocationUpdatesAsync(BACKGROUND_LOCATION_TASK, {
+        // Balanced accuracy saves battery compared to Highest
+        accuracy: Location2.Accuracy.Balanced,
+        timeInterval: config?.syncIntervalMs || 1e4,
+        // Ping every 10 seconds
+        distanceInterval: 10,
+        // Or ping every 10 meters
+        showsBackgroundLocationIndicator: true,
+        foregroundService: {
+          notificationTitle: "Location Sync Active",
+          notificationBody: "Tracking your route in the background."
+        }
+      });
+      setIsTracking(true);
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to start background tracking:", error);
+    }
+  }, [permissionState, config]);
+  const stopTracking = (0, import_react2.useCallback)(async () => {
+    try {
+      const hasTask = await Location2.hasStartedLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      if (hasTask) {
+        await Location2.stopLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      }
+      setIsTracking(false);
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to stop tracking:", error);
+    }
+  }, []);
+  return {
+    permissionState,
+    requestPermissions,
+    startTracking,
+    stopTracking,
+    isTracking,
+    queueLength
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BACKGROUND_LOCATION_TASK,
+  useGeoPermissions,
+  useGeoSync
+});

package/dist/index.mjs

@@ -0,0 +1,160 @@
+// src/useGeoPermissions.ts
+import { useState, useCallback, useEffect } from "react";
+import * as Location from "expo-location";
+function useGeoPermissions() {
+  const [permissionState, setPermissionState] = useState("idle");
+  const checkPermissions = useCallback(async () => {
+    try {
+      const { status: fgStatus } = await Location.getForegroundPermissionsAsync();
+      if (fgStatus === "granted") {
+        const { status: bgStatus } = await Location.getBackgroundPermissionsAsync();
+        setPermissionState(bgStatus === "granted" ? "granted_background" : "granted_foreground");
+      } else if (fgStatus === "denied") {
+        setPermissionState("denied");
+      } else {
+        setPermissionState("idle");
+      }
+    } catch (error) {
+      console.error("[use-geo-sync] Error checking permissions:", error);
+      setPermissionState("denied");
+    }
+  }, []);
+  useEffect(() => {
+    checkPermissions();
+  }, [checkPermissions]);
+  const requestPermissions = useCallback(async () => {
+    setPermissionState("requesting");
+    try {
+      const { status: fgStatus } = await Location.requestForegroundPermissionsAsync();
+      if (fgStatus !== "granted") {
+        setPermissionState("denied");
+        return;
+      }
+      const { status: bgStatus } = await Location.requestBackgroundPermissionsAsync();
+      if (bgStatus === "granted") {
+        setPermissionState("granted_background");
+      } else {
+        setPermissionState("granted_foreground");
+      }
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to request location permissions:", error);
+      setPermissionState("denied");
+    }
+  }, []);
+  return {
+    permissionState,
+    requestPermissions,
+    checkPermissions
+  };
+}
+
+// src/useGeoSync.ts
+import { useState as useState2, useCallback as useCallback2, useEffect as useEffect2 } from "react";
+import * as Location2 from "expo-location";
+
+// src/backgroundTask.ts
+import * as TaskManager from "expo-task-manager";
+var BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+var locationQueue = [];
+var activeConfig = { batchSize: 20 };
+var setTaskConfig = (config) => {
+  activeConfig = { ...activeConfig, ...config };
+};
+TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
+  if (error) {
+    console.error("[use-geo-sync] Background task error:", error.message);
+    return;
+  }
+  if (data) {
+    const { locations } = data;
+    const newPoints = locations.map((loc) => ({
+      id: `${loc.timestamp}-${Math.random().toString(36).substr(2, 9)}`,
+      latitude: loc.coords.latitude,
+      longitude: loc.coords.longitude,
+      timestamp: loc.timestamp,
+      accuracy: loc.coords.accuracy,
+      speed: loc.coords.speed
+    }));
+    locationQueue.push(...newPoints);
+    console.log(`[use-geo-sync] \u{1F4CD} Caught ${newPoints.length} points. Queue size: ${locationQueue.length}`);
+    const batchLimit = activeConfig.batchSize || 20;
+    if (activeConfig.syncEndpoint && locationQueue.length >= batchLimit) {
+      console.log(`[use-geo-sync] \u{1F680} Queue hit limit (${batchLimit}). Syncing to backend...`);
+      try {
+        const response = await fetch(activeConfig.syncEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ locations: locationQueue })
+        });
+        if (response.ok) {
+          console.log("[use-geo-sync] \u2705 Sync successful! Clearing queue.");
+          locationQueue = [];
+        } else {
+          console.warn(`[use-geo-sync] \u26A0\uFE0F Sync failed with status: ${response.status}. Keeping data in queue.`);
+        }
+      } catch (networkError) {
+        console.warn("[use-geo-sync] \u{1F50C} Network offline. Points saved in queue for next sync.");
+      }
+    }
+  }
+});
+
+// src/useGeoSync.ts
+function useGeoSync(config) {
+  const { permissionState, requestPermissions } = useGeoPermissions();
+  const [isTracking, setIsTracking] = useState2(false);
+  const [queueLength, setQueueLength] = useState2(locationQueue.length);
+  useEffect2(() => {
+    if (config) {
+      setTaskConfig(config);
+    }
+  }, [config]);
+  const startTracking = useCallback2(async () => {
+    if (permissionState !== "granted_background" && permissionState !== "granted_foreground") {
+      console.warn("[use-geo-sync] Cannot start tracking. Permissions not granted.");
+      return;
+    }
+    try {
+      await Location2.startLocationUpdatesAsync(BACKGROUND_LOCATION_TASK, {
+        // Balanced accuracy saves battery compared to Highest
+        accuracy: Location2.Accuracy.Balanced,
+        timeInterval: config?.syncIntervalMs || 1e4,
+        // Ping every 10 seconds
+        distanceInterval: 10,
+        // Or ping every 10 meters
+        showsBackgroundLocationIndicator: true,
+        foregroundService: {
+          notificationTitle: "Location Sync Active",
+          notificationBody: "Tracking your route in the background."
+        }
+      });
+      setIsTracking(true);
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to start background tracking:", error);
+    }
+  }, [permissionState, config]);
+  const stopTracking = useCallback2(async () => {
+    try {
+      const hasTask = await Location2.hasStartedLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      if (hasTask) {
+        await Location2.stopLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      }
+      setIsTracking(false);
+    } catch (error) {
+      console.error("[use-geo-sync] Failed to stop tracking:", error);
+    }
+  }, []);
+  return {
+    permissionState,
+    requestPermissions,
+    startTracking,
+    stopTracking,
+    isTracking,
+    queueLength
+  };
+}
+export {
+  BACKGROUND_LOCATION_TASK,
+  useGeoPermissions,
+  useGeoSync
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "use-geo-sync",
+  "version": "1.0.0",
+  "description": "A React Native/Expo headless toolkit for background location sync and queuing.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "location",
+    "background-sync",
+    "geolocation"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "peerDependencies": {
+    "expo-location": "^16.0.0",
+    "expo-task-manager": "^11.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "expo-location": "^55.1.6",
+    "expo-task-manager": "^55.0.12",
+    "react": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
+  }
+}

package/readme.md

@@ -0,0 +1,86 @@
+Markdown# use-geo-sync 🌍
+
+A plug-and-play, offline-first background location tracking and syncing toolkit for React Native and Expo. 
+
+Handling iOS/Android background permissions, app state, and network drops is a massive headache. `use-geo-sync` abstracts all that boilerplate into a single, strictly-typed React Hook with a built-in offline queue.
+
+## ✨ Features
+- **📱 Bulletproof Permissions:** Automatically handles the strict Foreground -> Background permission cascade on both iOS and Android.
+- **🔋 Battery Optimized:** Uses balanced accuracy and headless task management to save battery life.
+- **📡 Offline-First Queuing:** If the network drops, coordinates are safely queued locally. When the connection returns, the queue is automatically batched and synced to your backend.
+- **🛠 Zero-Config Architecture:** No complex Redux/Zustand setups required. It just works.
+
+## 📦 Installation
+
+Install the package via npm or yarn:
+
+```bash
+npm install use-geo-sync
+```
+Important: This package relies on Expo modules under the hood. You must install the peer dependencies:
+
+```
+npx expo install expo-location expo-task-manager
+```
+
+# 🚀 Quick Start
+Here is a complete example of how to implement background tracking in your app:
+```
+import { useEffect } from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import { useGeoSync } from 'use-geo-sync';
+
+export default function TrackingScreen() {
+  const { 
+    permissionState, 
+    requestPermissions, 
+    startTracking, 
+    stopTracking, 
+    isTracking, 
+    queueLength 
+  } = useGeoSync({
+    syncEndpoint: '[https://your-api.com/api/location-sync](https://your-api.com/api/location-sync)', // Your backend URL
+    batchSize: 20, // Auto-syncs to your backend after collecting 20 points
+    syncIntervalMs: 10000 // Pings GPS every 10 seconds
+  });
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>📍 Fleet Tracker</Text>
+      
+      <Text>Status: {isTracking ? 'Active 🟢' : 'Stopped 🔴'}</Text>
+      <Text>Permissions: {permissionState}</Text>
+      <Text>Unsynced Points in Queue: {queueLength}</Text>
+
+      {permissionState !== 'granted_background' && (
+        <Button title="Grant Background Permissions" onPress={requestPermissions} />
+      )}
+
+      <Button 
+        title={isTracking ? "Stop Tracking" : "Start Tracking"} 
+        onPress={isTracking ? stopTracking : startTracking} 
+        color={isTracking ? "red" : "green"}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, justifyContent: 'center', alignItems: 'center', gap: 10 },
+  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 }
+});
+```
+
+## ⚙️ Configuration Options (SyncConfig)
+
+When calling `useGeoSync(config)`, you can pass the following options:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `syncEndpoint` | `string` | `undefined` | The backend API URL where the queued location batch will be sent via POST request. |
+| `batchSize` | `number` | `20` | How many location points to collect before triggering a sync to the backend. |
+| `syncIntervalMs` | `number` | `10000` | Time in milliseconds between GPS pings. |
+
+## 📜 License
+
+MIT

package/src/backgroundTask.ts

@@ -0,0 +1,71 @@
+// src/backgroundTask.ts
+
+import * as TaskManager from 'expo-task-manager';
+import * as Location from 'expo-location';
+import { GeoPoint, SyncConfig } from './types';
+
+export const BACKGROUND_LOCATION_TASK = 'BACKGROUND_LOCATION_TASK';
+
+// In-memory queue
+export let locationQueue: GeoPoint[] = [];
+
+// We need a way to store the developer's config globally so the background task can read it
+let activeConfig: SyncConfig = { batchSize: 20 }; 
+
+// Function to update the config from the React Hook
+export const setTaskConfig = (config: SyncConfig) => {
+  activeConfig = { ...activeConfig, ...config };
+};
+
+TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
+  if (error) {
+    console.error('[use-geo-sync] Background task error:', error.message);
+    return;
+  }
+  
+  if (data) {
+    const { locations } = data as { locations: Location.LocationObject[] };
+    
+    // 1. Transform Expo's object
+    const newPoints: GeoPoint[] = locations.map(loc => ({
+      id: `${loc.timestamp}-${Math.random().toString(36).substr(2, 9)}`,
+      latitude: loc.coords.latitude,
+      longitude: loc.coords.longitude,
+      timestamp: loc.timestamp,
+      accuracy: loc.coords.accuracy,
+      speed: loc.coords.speed
+    }));
+
+    // 2. Add to Queue
+    locationQueue.push(...newPoints);
+    console.log(`[use-geo-sync] 📍 Caught ${newPoints.length} points. Queue size: ${locationQueue.length}`);
+
+    // 3. THE MAGIC: Check if we need to sync!
+    const batchLimit = activeConfig.batchSize || 20;
+    
+    if (activeConfig.syncEndpoint && locationQueue.length >= batchLimit) {
+      console.log(`[use-geo-sync] 🚀 Queue hit limit (${batchLimit}). Syncing to backend...`);
+      
+      try {
+        // Send the data to the developer's backend
+        const response = await fetch(activeConfig.syncEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ locations: locationQueue }),
+        });
+
+        if (response.ok) {
+          console.log('[use-geo-sync] ✅ Sync successful! Clearing queue.');
+          // 4. Clear the queue ONLY if the network request succeeds
+          locationQueue = []; 
+        } else {
+          console.warn(`[use-geo-sync] ⚠️ Sync failed with status: ${response.status}. Keeping data in queue.`);
+        }
+      } catch (networkError) {
+        // If they are driving through a tunnel and lose 5G, the fetch will fail.
+        // We catch the error and do NOT clear the queue. It will try again next time.
+        console.warn('[use-geo-sync] 🔌 Network offline. Points saved in queue for next sync.');
+      }
+    }
+  }
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+// src/index.ts
+
+export * from './types';
+export { useGeoPermissions } from './useGeoPermissions';
+export { useGeoSync } from './useGeoSync';
+export { BACKGROUND_LOCATION_TASK } from './backgroundTask';

package/src/types.ts

@@ -0,0 +1,35 @@
+// src/types.ts
+
+import * as Location from 'expo-location';
+
+export interface GeoPoint {
+  id: string; // Unique ID for the queue
+  latitude: number;
+  longitude: number;
+  timestamp: number;
+  accuracy: number | null;
+  speed: number | null;
+}
+
+export interface SyncConfig {
+  batchSize?: number; // How many points to hold before syncing (default: 20)
+  syncEndpoint?: string; // The backend URL to POST data to
+  syncIntervalMs?: number; // Time-based sync fallback
+  retryLimit?: number; // How many times to retry a failed sync
+}
+
+export type PermissionState = 
+  | 'idle' 
+  | 'requesting' 
+  | 'granted_foreground' 
+  | 'granted_background' 
+  | 'denied';
+
+export interface UseGeoSyncResult {
+  permissionState: PermissionState;
+  requestPermissions: () => Promise<void>;
+  startTracking: () => Promise<void>;
+  stopTracking: () => Promise<void>;
+  isTracking: boolean;
+  queueLength: number; // Number of unsynced points
+}

package/src/useGeoPermissions.ts

@@ -0,0 +1,67 @@
+// src/useGeoPermissions.ts
+
+import { useState, useCallback, useEffect } from 'react';
+import * as Location from 'expo-location';
+import { PermissionState } from './types';
+
+export function useGeoPermissions() {
+  const [permissionState, setPermissionState] = useState<PermissionState>('idle');
+
+  // Check the current status silently without triggering a system popup
+  const checkPermissions = useCallback(async () => {
+    try {
+      const { status: fgStatus } = await Location.getForegroundPermissionsAsync();
+      
+      if (fgStatus === 'granted') {
+        const { status: bgStatus } = await Location.getBackgroundPermissionsAsync();
+        setPermissionState(bgStatus === 'granted' ? 'granted_background' : 'granted_foreground');
+      } else if (fgStatus === 'denied') {
+        setPermissionState('denied');
+      } else {
+        setPermissionState('idle');
+      }
+    } catch (error) {
+      console.error("[use-geo-sync] Error checking permissions:", error);
+      setPermissionState('denied');
+    }
+  }, []);
+
+  // Run the silent check on mount
+  useEffect(() => {
+    checkPermissions();
+  }, [checkPermissions]);
+
+  // The actual request function the developer will call
+  const requestPermissions = useCallback(async () => {
+    setPermissionState('requesting');
+    
+    try {
+      // 1. MUST request foreground first
+      const { status: fgStatus } = await Location.requestForegroundPermissionsAsync();
+
+      if (fgStatus !== 'granted') {
+        setPermissionState('denied');
+        return; // Stop here if they say no
+      }
+
+      // 2. Now safe to request background
+      const { status: bgStatus } = await Location.requestBackgroundPermissionsAsync();
+
+      if (bgStatus === 'granted') {
+        setPermissionState('granted_background');
+      } else {
+        // They allowed app to use location while open, but not in background
+        setPermissionState('granted_foreground');
+      }
+    } catch (error) {
+      console.error('[use-geo-sync] Failed to request location permissions:', error);
+      setPermissionState('denied');
+    }
+  }, []);
+
+  return { 
+    permissionState, 
+    requestPermissions, 
+    checkPermissions 
+  };
+}

package/src/useGeoSync.ts

@@ -0,0 +1,66 @@
+// src/useGeoSync.ts
+
+import { useState, useCallback, useEffect } from 'react';
+import * as Location from 'expo-location';
+import { BACKGROUND_LOCATION_TASK, locationQueue } from './backgroundTask';
+import { SyncConfig, UseGeoSyncResult } from './types';
+import { useGeoPermissions } from './useGeoPermissions';
+import { setTaskConfig } from './backgroundTask'; // <-- add this to your imports
+export function useGeoSync(config?: SyncConfig): UseGeoSyncResult {
+  // Bring in our custom permission hook
+  const { permissionState, requestPermissions } = useGeoPermissions();
+  
+  const [isTracking, setIsTracking] = useState(false);
+  const [queueLength, setQueueLength] = useState(locationQueue.length);
+
+  useEffect(() => {
+    if (config) {
+      setTaskConfig(config);
+    }
+  }, [config]);
+
+  const startTracking = useCallback(async () => {
+    if (permissionState !== 'granted_background' && permissionState !== 'granted_foreground') {
+      console.warn('[use-geo-sync] Cannot start tracking. Permissions not granted.');
+      return;
+    }
+
+    try {
+      await Location.startLocationUpdatesAsync(BACKGROUND_LOCATION_TASK, {
+        // Balanced accuracy saves battery compared to Highest
+        accuracy: Location.Accuracy.Balanced, 
+        timeInterval: config?.syncIntervalMs || 10000, // Ping every 10 seconds
+        distanceInterval: 10, // Or ping every 10 meters
+        showsBackgroundLocationIndicator: true,
+        foregroundService: {
+          notificationTitle: "Location Sync Active",
+          notificationBody: "Tracking your route in the background.",
+        }
+      });
+      setIsTracking(true);
+    } catch (error) {
+      console.error('[use-geo-sync] Failed to start background tracking:', error);
+    }
+  }, [permissionState, config]);
+
+  const stopTracking = useCallback(async () => {
+    try {
+      const hasTask = await Location.hasStartedLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      if (hasTask) {
+        await Location.stopLocationUpdatesAsync(BACKGROUND_LOCATION_TASK);
+      }
+      setIsTracking(false);
+    } catch (error) {
+      console.error('[use-geo-sync] Failed to stop tracking:', error);
+    }
+  }, []);
+
+  return {
+    permissionState,
+    requestPermissions,
+    startTracking,
+    stopTracking,
+    isTracking,
+    queueLength
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "isolatedModules": true,
+    "ignoreDeprecations": "6.0" 
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true, // Generates types
+  clean: true, // Cleans dist folder before build
+  external: ['react', 'expo-location', 'expo-task-manager'], // Don't bundle these!
+});