expo-background-tracking 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farhati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# expo-background-tracking
+
+Tracking GPS & geofencing pour **Expo** (Android + iOS),100 % Expo, **sans Firebase**, sans code natif custom, **compatible Expo Go**.
+
+Détection de mouvement économe en batterie (accéléromètre + vitesse GPS), persistance SQLite, synchronisation HTTP avec file offline, geofencing illimité (cercles + polygones), odomètre, planning hebdomadaire.
+
+## Installation
+
+```bash
+npm install expo-background-tracking
+npx expo install expo-location expo-task-manager expo-sqlite expo-sensors expo-battery expo-network expo-device expo-constants
+```
+
+## Compatibilité Expo Go
+
+| | Expo Go | Dev build / production |
+|---|---|---|
+| Tracking app ouverte (foreground) | ✅ | ✅ |
+| Tracking app minimisée (background) | ❌* | ✅ |
+| Geofencing | ✅ (logiciel, foreground) | ✅ (natif + logiciel) |
+| SQLite, HTTP sync, odomètre, scheduler, motion-detection | ✅ | ✅ |
+
+\* Limitation officielle d'Expo : le background location exige un development build ([docs Expo](https://docs.expo.dev/versions/latest/sdk/location/)). La lib détecte l'environnement automatiquement — **même code partout**, zéro crash dans Expo Go.
+
+Pour le background complet (dev build), ajoutez dans `app.json` :
+
+```json
+{
+  "expo": {
+    "ios": { "infoPlist": { "UIBackgroundModes": ["location", "fetch"] } },
+    "android": { "permissions": ["ACCESS_BACKGROUND_LOCATION", "FOREGROUND_SERVICE", "FOREGROUND_SERVICE_LOCATION"] },
+    "plugins": [["expo-location", {
+      "isAndroidBackgroundLocationEnabled": true,
+      "isAndroidForegroundServiceEnabled": true
+    }]]
+  }
+}
+```
+
+## Usage
+
+```ts
+import BackgroundGeolocation from 'expo-background-tracking';
+
+// 1. Écouter les événements
+const sub = BackgroundGeolocation.onLocation((location) => {
+  console.log('[location]', location.coords);
+});
+
+BackgroundGeolocation.onMotionChange(({ isMoving, location }) => {
+  console.log('[motionchange]', isMoving);
+});
+
+BackgroundGeolocation.onGeofence(({ identifier, action }) => {
+  console.log('[geofence]', identifier, action);
+});
+
+// 2. Configurer (ready, une seule fois)
+const state = await BackgroundGeolocation.ready({
+  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
+  distanceFilter: 10,
+  stopTimeout: 5,
+  url: 'https://your-server.com/locations', // HTTP sync — fetch natif, pas de Firebase
+  autoSync: true,
+  batchSync: false,
+  headers: { 'X-API-KEY': 'xyz' },
+  debug: true,
+});
+
+// 3. Démarrer
+if (!state.enabled) {
+  await BackgroundGeolocation.start();
+}
+```
+
+### Geofencing (illimité, cercles + polygones)
+
+```ts
+await BackgroundGeolocation.addGeofence({
+  identifier: 'HOME',
+  latitude: 48.8566,
+  longitude: 2.3522,
+  radius: 200,
+  notifyOnEntry: true,
+  notifyOnExit: true,
+  notifyOnDwell: true,
+  loiteringDelay: 60000,
+});
+
+// Polygone (évalué en logiciel)
+await BackgroundGeolocation.addGeofence({
+  identifier: 'ZONE',
+  vertices: [[48.85, 2.34], [48.86, 2.34], [48.86, 2.36], [48.85, 2.36]],
+});
+
+await BackgroundGeolocation.startGeofences(); // mode geofences-only
+```
+
+## Envoi HTTP des positions vers votre serveur
+
+La lib embarque un service HTTP complet (basé sur `fetch`, **sans Firebase**) : chaque position est persistée en SQLite puis envoyée à votre `url`. En cas d'échec (hors-ligne, erreur serveur), les positions restent en file et repartent automatiquement à la reconnexion.
+
+### Configuration de base
+
+```ts
+await BackgroundGeolocation.ready({
+  url: 'https://votre-serveur.com/locations', // destination des positions
+  method: 'POST',                              // 'POST' (défaut) | 'PUT' | 'OPTIONS'
+  headers: {                                   // headers HTTP personnalisés
+    'X-API-KEY': 'abc123',
+    'Authorization': 'Bearer ...',
+  },
+  params: {                                    // champs ajoutés à la racine du corps JSON
+    device_id: 'phone-01',
+    company_id: 7,
+  },
+  extras: {                                    // attachés à CHAQUE position envoyée
+    user_id: 42,
+    mission: 'livraison',
+  },
+  autoSync: true,                              // envoi automatique à chaque position
+  httpTimeout: 60000,                          // timeout requête en ms
+});
+```
+
+### Contrôler le nombre et la fréquence des envois
+
+| Option | Effet |
+|---|---|
+| `autoSync: true` | Envoie automatiquement chaque nouvelle position |
+| `autoSyncThreshold: 10` | N'envoie qu'à partir de **10 positions** accumulées en file |
+| `batchSync: true` | Envoie les positions **en lot** (1 requête HTTP = N positions) |
+| `maxBatchSize: 50` | Maximum **50 positions par requête** (les lots s'enchaînent) |
+| `autoSync: false` + `sync()` | Envoi **100 % manuel**, quand vous le décidez |
+
+```ts
+// Exemple : économiser la batterie/réseau — 1 requête tous les 25 points, par lots
+await BackgroundGeolocation.ready({
+  url: 'https://votre-serveur.com/locations',
+  autoSync: true,
+  autoSyncThreshold: 25,
+  batchSync: true,
+  maxBatchSize: 100,
+});
+
+// Envoi manuel (par ex. sur bouton ou à la fin d'une mission)
+const uploaded = await BackgroundGeolocation.sync();
+console.log(`${uploaded.length} positions envoyées`);
+```
+
+### Format du payload reçu par votre serveur
+
+Par défaut (`httpRootProperty: 'location'`) :
+
+```json
+{
+  "location": {
+    "uuid": "f3f57a91-…",
+    "timestamp": "2026-06-12T14:32:11.000Z",
+    "odometer": 1842.5,
+    "is_moving": true,
+    "coords": {
+      "latitude": 48.856614, "longitude": 2.352222,
+      "accuracy": 5, "speed": 1.4, "heading": 270, "altitude": 35
+    },
+    "activity": { "activity": "walking", "confidence": 75 },
+    "battery": { "level": 0.82, "is_charging": false },
+    "extras": { "user_id": 42, "mission": "livraison" }
+  },
+  "device_id": "phone-01",
+  "company_id": 7
+}
+```
+
+Avec `batchSync: true`, `"location"` devient un **tableau** de positions.
+
+### Personnaliser le format
+
+```ts
+await BackgroundGeolocation.ready({
+  url: '…',
+  httpRootProperty: 'data',          // { "data": {...} } — ou '.' pour aucun wrapper
+  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>,"ts":<%= timestamp %>,"batt":<%= battery.level %>}',
+});
+```
+
+Variables de template : `latitude`, `longitude`, `accuracy`, `speed`, `heading`, `altitude`, `timestamp`, `uuid`, `odometer`, `is_moving`, `activity.type`, `activity.confidence`, `battery.level`, `battery.is_charging`.
+
+### Suivre les envois
+
+```ts
+BackgroundGeolocation.onHttp((response) => {
+  console.log('[http]', response.status, response.success, response.responseText);
+});
+```
+
+### Persistance & sync manuel
+
+```ts
+const count = await BackgroundGeolocation.getCount();        // positions en file
+const locations = await BackgroundGeolocation.getLocations(); // lire la file
+const uploaded = await BackgroundGeolocation.sync();          // envoyer maintenant
+await BackgroundGeolocation.destroyLocations();               // vider la file
+```
+
+Options de rétention : `maxDaysToPersist` (défaut 1 jour), `maxRecordsToPersist`, `persistMode` (`ALL` | `LOCATION` | `GEOFENCE` | `NONE`).
+
+### Planning
+
+```ts
+await BackgroundGeolocation.ready({
+  schedule: ['1-5 09:00-17:00', '6 10:00-14:00'], // lun-ven 9h-17h, sam 10h-14h
+});
+await BackgroundGeolocation.startSchedule();
+```
+
+### Odomètre, capteurs, état
+
+```ts
+const km = (await BackgroundGeolocation.getOdometer()) / 1000;
+await BackgroundGeolocation.resetOdometer();
+const sensors = await BackgroundGeolocation.getSensors();
+const providerState = await BackgroundGeolocation.getProviderState();
+const powerSave = await BackgroundGeolocation.isPowerSaveMode();
+```
+
+### Auth JWT avec refresh automatique (sur 401)
+
+```ts
+await BackgroundGeolocation.ready({
+  url: 'https://api.example.com/locations',
+  authorization: {
+    strategy: 'JWT',
+    accessToken: 'eyJ...',
+    refreshToken: 'def...',
+    refreshUrl: 'https://api.example.com/auth/refresh',
+  },
+});
+BackgroundGeolocation.onAuthorization((event) => console.log(event));
+```
+
+## API complète
+
+Événements : `onLocation`, `onMotionChange`, `onActivityChange`, `onGeofence`, `onGeofencesChange`, `onHeartbeat`, `onHttp`, `onProviderChange`, `onConnectivityChange`, `onPowerSaveChange`, `onEnabledChange`, `onSchedule`, `onAuthorization`.
+
+Méthodes : `ready`, `start`, `stop`, `startGeofences`, `startSchedule`, `stopSchedule`, `changePace`, `getCurrentPosition`, `watchPosition`, `stopWatchPosition`, `getState`, `setConfig`, `reset`, `getLocations`, `getCount`, `insertLocation`, `destroyLocations`, `destroyLocation`, `sync`, `getOdometer`, `setOdometer`, `resetOdometer`, `addGeofence`, `addGeofences`, `removeGeofence`, `removeGeofences`, `getGeofences`, `getGeofence`, `geofenceExists`, `getSensors`, `getDeviceInfo`, `isPowerSaveMode`, `getProviderState`, `requestPermission`, `requestTemporaryFullAccuracy`, `registerHeadlessTask`, `startBackgroundTask`, `stopBackgroundTask`, `getLog`, `destroyLog`, `emailLog`, `removeListeners`.
+
+
+
+## App de test
+
+```bash
+cd testapp
+npm install
+npx expo start --clear
+```
+
+## Licence
+
+MIT

package/build/BackgroundGeolocation.d.ts

@@ -0,0 +1,122 @@
+import { AccuracyAuthorization, AuthorizationStatus, DesiredAccuracy, LogLevel, PersistMode, type ActivityChangeEvent, type Config, type ConnectivityChangeEvent, type CurrentPositionRequest, type DeviceInfo, type GeofencesChangeEvent, type Geofence, type GeofenceEvent, type HeadlessTask, type HeartbeatEvent, type HttpEvent, type Location, type MotionChangeEvent, type ProviderChangeEvent, type ScheduleEvent, type Sensors, type SQLQuery, type State, type Subscription, type WatchPositionRequest, type AuthorizationEvent } from './types';
+export declare const LOCATION_TASK = "expo-background-tracking.location";
+declare class BackgroundGeolocationImpl {
+    readonly DESIRED_ACCURACY_NAVIGATION = DesiredAccuracy.NAVIGATION;
+    readonly DESIRED_ACCURACY_HIGH = DesiredAccuracy.HIGH;
+    readonly DESIRED_ACCURACY_MEDIUM = DesiredAccuracy.MEDIUM;
+    readonly DESIRED_ACCURACY_LOW = DesiredAccuracy.LOW;
+    readonly DESIRED_ACCURACY_VERY_LOW = DesiredAccuracy.VERY_LOW;
+    readonly LOG_LEVEL_OFF = LogLevel.OFF;
+    readonly LOG_LEVEL_ERROR = LogLevel.ERROR;
+    readonly LOG_LEVEL_WARNING = LogLevel.WARNING;
+    readonly LOG_LEVEL_INFO = LogLevel.INFO;
+    readonly LOG_LEVEL_DEBUG = LogLevel.DEBUG;
+    readonly LOG_LEVEL_VERBOSE = LogLevel.VERBOSE;
+    readonly PERSIST_MODE_ALL = PersistMode.ALL;
+    readonly PERSIST_MODE_LOCATION = PersistMode.LOCATION;
+    readonly PERSIST_MODE_GEOFENCE = PersistMode.GEOFENCE;
+    readonly PERSIST_MODE_NONE = PersistMode.NONE;
+    readonly AUTHORIZATION_STATUS_ALWAYS = AuthorizationStatus.ALWAYS;
+    readonly AUTHORIZATION_STATUS_WHEN_IN_USE = AuthorizationStatus.WHEN_IN_USE;
+    readonly AUTHORIZATION_STATUS_DENIED = AuthorizationStatus.DENIED;
+    readonly logger: import("./Logger").Logger;
+    private bus;
+    private http;
+    private geofenceManager;
+    private motion;
+    private scheduler;
+    private config;
+    private enabled;
+    private trackingMode;
+    private odometer;
+    private lastLocation;
+    private lastPersistedCoords;
+    private isReady;
+    private foregroundSub;
+    private watchSub;
+    private heartbeatTimer;
+    private providerTimer;
+    private powerSaveSub;
+    private lastProviderState;
+    private headlessTask;
+    private bgTaskCounter;
+    constructor();
+    private defineTasks;
+    private dispatchHeadless;
+    ready(config?: Config): Promise<State>;
+    start(): Promise<State>;
+    stop(): Promise<State>;
+    /** Geofences-only mode: no continuous location tracking. */
+    startGeofences(): Promise<State>;
+    startSchedule(): Promise<State>;
+    stopSchedule(): Promise<State>;
+    changePace(isMoving: boolean): Promise<void>;
+    private setEnabled;
+    private assertReady;
+    private mapAccuracy;
+    private startForegroundWatch;
+    private startBackgroundUpdates;
+    private effectiveDistanceFilter;
+    private buildLocation;
+    private shouldPersist;
+    private processLocation;
+    private handleMotionChange;
+    private fetchCurrentLocation;
+    getCurrentPosition(options?: CurrentPositionRequest): Promise<Location>;
+    watchPosition(success: (location: Location) => void, failure?: (error: unknown) => void, options?: WatchPositionRequest): Promise<void>;
+    stopWatchPosition(): Promise<void>;
+    getState(): Promise<State>;
+    setConfig(config: Config): Promise<State>;
+    reset(config?: Config): Promise<State>;
+    getLocations(query?: SQLQuery): Promise<Location[]>;
+    getCount(): Promise<number>;
+    insertLocation(location: Partial<Location>): Promise<string>;
+    destroyLocations(): Promise<void>;
+    destroyLocation(uuid: string): Promise<void>;
+    sync(): Promise<Location[]>;
+    getOdometer(): Promise<number>;
+    setOdometer(value: number): Promise<Location>;
+    resetOdometer(): Promise<Location>;
+    addGeofence(geofence: Geofence): Promise<boolean>;
+    addGeofences(geofences: Geofence[]): Promise<boolean>;
+    removeGeofence(identifier: string): Promise<boolean>;
+    removeGeofences(identifiers?: string[]): Promise<boolean>;
+    getGeofences(): Promise<Geofence[]>;
+    getGeofence(identifier: string): Promise<Geofence | null>;
+    geofenceExists(identifier: string): Promise<boolean>;
+    getSensors(): Promise<Sensors>;
+    getDeviceInfo(): Promise<DeviceInfo>;
+    isPowerSaveMode(): Promise<boolean>;
+    private startPowerSaveMonitoring;
+    requestPermission(): Promise<AuthorizationStatus>;
+    requestTemporaryFullAccuracy(_purpose: string): Promise<AccuracyAuthorization>;
+    getProviderState(): Promise<ProviderChangeEvent>;
+    private startProviderMonitoring;
+    private startHeartbeat;
+    private stopHeartbeat;
+    startBackgroundTask(): Promise<number>;
+    stopBackgroundTask(_taskId: number): Promise<void>;
+    registerHeadlessTask(task: HeadlessTask): void;
+    getLog(): Promise<string>;
+    destroyLog(): Promise<void>;
+    emailLog(_email: string): Promise<string>;
+    playSound(_soundId: number | string): Promise<void>;
+    onLocation(success: (location: Location) => void, failure?: (error: unknown) => void): Subscription;
+    onMotionChange(fn: (event: MotionChangeEvent) => void): Subscription;
+    onActivityChange(fn: (event: ActivityChangeEvent) => void): Subscription;
+    onGeofence(fn: (event: GeofenceEvent) => void): Subscription;
+    onGeofencesChange(fn: (event: GeofencesChangeEvent) => void): Subscription;
+    onHeartbeat(fn: (event: HeartbeatEvent) => void): Subscription;
+    onHttp(fn: (event: HttpEvent) => void): Subscription;
+    onProviderChange(fn: (event: ProviderChangeEvent) => void): Subscription;
+    onConnectivityChange(fn: (event: ConnectivityChangeEvent) => void): Subscription;
+    onPowerSaveChange(fn: (isPowerSaveMode: boolean) => void): Subscription;
+    onEnabledChange(fn: (enabled: boolean) => void): Subscription;
+    onSchedule(fn: (event: ScheduleEvent) => void): Subscription;
+    onAuthorization(fn: (event: AuthorizationEvent) => void): Subscription;
+    onNotificationAction(fn: (buttonId: string) => void): Subscription;
+    removeListeners(): void;
+    removeAllListeners(): void;
+}
+export declare const BackgroundGeolocation: BackgroundGeolocationImpl;
+export {};