@josuelmm/cordova-background-geolocation 4.2.3 → 4.5.2

package/www/BackgroundGeolocation.d.ts

@@ -153,7 +153,7 @@ export interface ConfigureOptions {
    * Platform: Android
    * Provider: all
    *
-   * @default 60000
+   * @default 600000
    * @see {@link https://bit.ly/1x00RUu|Android docs}
    */
   interval?: number;
@@ -510,6 +510,81 @@ export interface ConfigureOptions {
    */
   mockLocationPolicy?: 'allow' | 'flag' | 'drop';
 
+  /**
+   * v4.4 — Stamp device battery percentage (0-100) and charging state on every location
+   * sent to the backend. Default `true`. Set `false` to opt out.
+   *
+   * - With `bodyTemplate`/`postTemplate`, use placeholders `'@battery'` and `'@isCharging'`.
+   * - Default JSON includes `battery` and `isCharging` keys automatically.
+   *
+   * Android: read via `BatteryManager` sticky broadcast (no permission required).
+   * iOS: read via `UIDevice.batteryLevel` (free).
+   *
+   * Platform: Android, iOS
+   * @since 4.4.0
+   */
+  includeBattery?: boolean;
+
+  /**
+   * v4.5.1 — WakeLock policy (Android only). Controls whether the service holds a
+   * `PARTIAL_WAKE_LOCK` while tracking. Default `'posting'`.
+   *
+   * - `'none'`     — never acquire a wake lock. Best battery, but the device may
+   *                  sleep mid-POST. Recommended only with `httpMode: 'batch'`.
+   * - `'posting'`  — acquire a 30 s wake lock on every fix while writing to SQLite
+   *                  and posting. Default. Good battery / reliability trade-off.
+   * - `'always'`   — keep CPU awake the whole time the service is running. Most
+   *                  reliable, worst battery. Use only for fleet/emergency apps.
+   *
+   * @platform Android
+   * @since 4.5.1
+   */
+  wakeLockMode?: 'none' | 'posting' | 'always';
+
+  /**
+   * v4.5.1 — Stationary detection knobs (Android `DISTANCE_FILTER_PROVIDER`).
+   * Override the previously hard-coded constants. All values in milliseconds.
+   *
+   * - `stationaryTimeout` (default 300_000) — time of no movement before declaring stationary.
+   * - `stationaryPollInterval` (default 180_000) — lazy poll while stationary.
+   * - `stationaryPollFast` (default 60_000) — aggressive poll near boundary.
+   *
+   * @platform Android
+   * @since 4.5.1
+   */
+  stationaryTimeout?: number;
+  stationaryPollInterval?: number;
+  stationaryPollFast?: number;
+
+  /**
+   * v4.5.2 — Activity-recognition confidence threshold (0-100). Transitions below this
+   * confidence are ignored, preventing jittery STILL/ACTIVE flips that cause spurious
+   * GPS start/stop bursts. Only used by `ACTIVITY_PROVIDER`.
+   *
+   * iOS confidence is normalized from CMMotionActivityConfidence (Low/Medium/High →
+   * 20/40/80) so the threshold means the same thing on both platforms.
+   *
+   * Platform: Android, iOS
+   * Provider: ACTIVITY
+   * @default 50
+   * @since 4.5.2
+   */
+  activityConfidenceThreshold?: number;
+
+  /**
+   * v4.5.2 — Maximum accepted horizontal accuracy in meters. Fixes whose reported
+   * accuracy is worse than this value are dropped before reaching the JS layer
+   * (and before being persisted / posted / synced).
+   *
+   * Use to filter out indoor GPS noise on Android (`accuracy > 100 m`) or initial
+   * coarse network fixes on iOS. `null` / unset disables the filter.
+   *
+   * Platform: Android, iOS
+   * Provider: all
+   * @since 4.5.2
+   */
+  maxAcceptedAccuracy?: number;
+
   /**
    * v4.0 Phase 6 — Driver insights configuration. Enables a GPS-based state machine
    * that emits `moving`, `stopped`, `tripStart`, `tripEnd`, `speeding` and
@@ -643,6 +718,31 @@ export interface Location {
    * True if location was simulated by software (e.g. Simulator). (iOS 15+)
    */
   simulated?: boolean;
+
+  /**
+   * v4.3 — Driving events anexados a este fix por el detector interno.
+   *
+   * Solo presente cuando un evento se disparó al mismo tiempo que esta location y
+   * `drivingEvents.enabled` está activo. Cada elemento es `{ type, time, ...payload }`,
+   * donde `payload` depende del tipo:
+   *   - hardBrake / rapidAcceleration / sharpTurn → `value: number`
+   *   - speeding → `speedKmh: number, limitKmh: number`
+   *   - tripEnd → `distance: number, durationMs: number`
+   *   - possibleCrash → `value: number, source: 'gps' | 'sensor'`
+   *   - providerChange → `provider: string`
+   *   - moving / stopped / tripStart / phoneUsageWhileDriving → solo type+time.
+   *
+   * Desde v4.5.0, `events` se persiste en la cola de sync y sobrevive a POST fallidos.
+   *
+   * @since 4.3.0
+   */
+  events?: Array<{ type: string; time: number; [key: string]: any }>;
+
+  /** v4.4 — Device battery percentage (0-100) at the time of the fix. Disabled with
+   *  `includeBattery: false` in ConfigureOptions. @since 4.4.0 */
+  battery?: number;
+  /** v4.4 — Whether the device is charging at the time of the fix. @since 4.4.0 */
+  isCharging?: boolean;
 }
 
 export interface StationaryLocation extends Location {
@@ -972,6 +1072,39 @@ export interface BackgroundGeolocationPlugin {
     fail?: (error: BackgroundGeolocationError) => void
   ): Promise<void>;
 
+  /**
+   * v4.5 — Request `ACCESS_BACKGROUND_LOCATION` runtime permission (Android 10+).
+   * On Android < 10 resolves immediately as `{ granted: true, notRequired: true }`.
+   * On iOS resolves as `{ granted: true, notRequired: true }` (Apple does not surface
+   * a separate background permission — the standard "Always" authorization covers it).
+   * @since 4.5.0
+   */
+  requestBackgroundLocationPermission(
+    success?: (result: { granted: boolean; denied?: string[]; notRequired?: boolean }) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<{ granted: boolean; denied?: string[]; notRequired?: boolean }>;
+
+  /**
+   * v4.5 — Request `ACTIVITY_RECOGNITION` runtime permission (Android 10+).
+   * Required by `ActivityLocationProvider`. iOS / Android < 10 resolve `granted: true, notRequired`.
+   * @since 4.5.0
+   */
+  requestActivityRecognitionPermission(
+    success?: (result: { granted: boolean; denied?: string[]; notRequired?: boolean }) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<{ granted: boolean; denied?: string[]; notRequired?: boolean }>;
+
+  /**
+   * v4.5 — Request `POST_NOTIFICATIONS` runtime permission (Android 13+).
+   * Without it the foreground-service notification is invisible. iOS / Android < 13
+   * resolve `granted: true, notRequired`.
+   * @since 4.5.0
+   */
+  requestNotificationPermission(
+    success?: (result: { granted: boolean; denied?: string[]; notRequired?: boolean }) => void,
+    fail?: (error: BackgroundGeolocationError) => void
+  ): Promise<{ granted: boolean; denied?: string[]; notRequired?: boolean }>;
+
   /**
    * Show app settings to allow change of app location permissions.
    *
@@ -1245,13 +1378,20 @@ export interface BackgroundGeolocationPlugin {
   ): Promise<void>;
 
   /**
-   * A special task that gets executed when the app is terminated, but
-   * the plugin was configured to continue running in the background
+   * **Android only.** A special task that gets executed when the app is terminated,
+   * but the plugin was configured to continue running in the background
    * (option <code>stopOnTerminate: false</code>).
    *
    * In this scenario the Activity was killed by the system and all registered
    * event listeners will not be triggered until the app is relaunched.
    *
+   * **iOS:** Apple does not support running JS in a killed-app scenario the same
+   * way; on iOS this method is a no-op. Use `significantLocationChanges` and the
+   * normal `BackgroundGeolocation.on(...)` listeners with the standard background
+   * location mode instead.
+   *
+   * Platform: Android
+   *
    * @example
    *  BackgroundGeolocation.headlessTask(function(event) {
    *

package/www/BackgroundGeolocation.js

@@ -3,10 +3,6 @@
 
  This is fork of christocracy cordova-plugin-background-geolocation plugin
  https://github.com/christocracy/cordova-plugin-background-geolocation
-
- Differences to original version:
-
- 1. new method isLocationEnabled
  */
 
 var exec = require('cordova/exec');
@@ -250,6 +246,17 @@ var BackgroundGeolocation = {
     return execWithPromise(success, failure, 'triggerSOS', [payload || {}]);
   },
 
+  // v4.5 — runtime permission helpers (Android). Resolve with { granted: bool, denied?: string[] }.
+  requestBackgroundLocationPermission: function (success, failure) {
+    return execWithPromise(success, failure, 'requestBackgroundLocationPermission');
+  },
+  requestActivityRecognitionPermission: function (success, failure) {
+    return execWithPromise(success, failure, 'requestActivityRecognitionPermission');
+  },
+  requestNotificationPermission: function (success, failure) {
+    return execWithPromise(success, failure, 'requestNotificationPermission');
+  },
+
   startTask: function (success, failure) {
     return execWithPromise(success,
       failure,

package/CLAUDE.md

@@ -1,56 +0,0 @@
-# Global Instructions
-
-## Ejecución
-Pensar antes de actuar.
-Ejecutar herramienta primero.
-Leer archivos existentes antes de escribir código.
-Abrir solo archivos relevantes.
-Usar rg antes de abrir muchos archivos.
-No releer archivos ya leídos, salvo cambio posible.
-Leer por rangos, no completo.
-Omitir archivos mayores de 100 KB, salvo necesidad explícita.
-Ignorar vendor, node_modules, dist, build, storage/logs y binarios.
-Preferir editar antes que reescribir completo.
-Hacer diffs mínimos.
-No tocar código no relacionado.
-No refactorizar sin pedirlo.
-No cambiar arquitectura sin permiso.
-Preguntar antes de instalar paquetes.
-Preguntar antes de borrar archivos.
-Preguntar antes de migraciones destructivas.
-
-## Validación
-Probar código antes de darlo por terminado.
-Validar con comando específico.
-No ejecutar tests pesados sin pedirlo.
-Reportar solo errores reales.
-Ejecutar /cost en sesiones largas.
-Iniciar nueva sesión si tarea cambia.
-
-## Respuesta
-Mostrar resultado y parar.
-Salida concisa.
-Razonamiento exhaustivo interno.
-Cero relleno.
-Sin introducciones aduladoras.
-Sin cierres superfluos.
-Frases de 3 a 6 palabras.
-Sin artículos innecesarios.
-Solo bugs y cambios.
-Sin explicación extra.
-No repetir input.
-Respetar formato definido.
-No asumir datos.
-Preguntar solo si hay bloqueo real.
-Reportar solo archivos modificados.
-
-## Formato por defecto
-Cambios:
-- archivo: resumen corto
-
-Validación:
-- comando ejecutado
-- resultado
-
-Pendiente:
-- solo si falta dato