@josuelmm/cordova-background-geolocation 3.2.0 → 4.2.2

package/.npmignore

@@ -4,6 +4,10 @@
 # only include project files
 !/.npmignore
 !/*.md
+# exclude internal/development markdown (audit, release notes, internal docs)
+/REVIEW_*.md
+/RELEASE.MD
+/NPM_PUBLISH.md
 !/plugin.xml
 !/package.json
 !/www

package/CHANGELOG.md

@@ -1,5 +1,295 @@
 # Changelog
 
+## [4.2.2](https://github.com/josuelmm/cordova-background-geolocation/tree/4.2.2) (2026-05-09)
+
+### Fixed
+- `PostLocationTask.postLocation`: cast del retorno de `LocationTemplate.locationToJson` (que es `Object` — `JSONObject` para `HashMapLocationTemplate`, `JSONArray` para `ArrayListLocationTemplate`) a la sobrecarga correcta de `HttpPostService.postJSON`. Bug latente que rompía la compilación con consumidores Capacitor (Gradle 8.x).
+- `BackgroundGeolocationPlugin.buildDiagnostics`: envolver `facade.locationServicesEnabled()` en `try/catch (PluginException)`. El método declara `throws JSONException` pero no `PluginException`, lo que rompía el build cuando se invoca desde `getDiagnostics`.
+
+## [4.2.0](https://github.com/josuelmm/cordova-background-geolocation/tree/4.2.0) (2026-05-08)
+
+### Phase 8 — Real sensor fusion (accelerometer + gyroscope)
+
+#### Added
+- Android `SensorFusionDetector` (`Sensor.TYPE_LINEAR_ACCELERATION` + `Sensor.TYPE_GYROSCOPE`, `SENSOR_DELAY_GAME`).
+- iOS `MAURSensorFusionDetector` (`CMMotionManager.startDeviceMotionUpdatesToQueue`, 50 Hz).
+- `drivingEvents.sensorFusion` flag (off by default) plus `crashImpactG`, `sensorCrashCooldownMs`, `phoneUsageWindowMs`, `phoneUsageCooldownMs` thresholds.
+- `possibleCrash` event payload now carries `source: "gps" | "sensor"` so consumers can distinguish the GPS heuristic from the accelerometer impact.
+- New event `phoneUsageWhileDriving`: detects sustained device interaction (gyro/accel jitter) while a trip is active and the screen is on.
+- Hot-reload: `configure()` reevaluates and (re)starts sensor pipeline on both platforms.
+
+#### Notes
+- Sensor pipeline only samples while `tripActive` is true → modest battery cost.
+- Android requires `TYPE_LINEAR_ACCELERATION` (gravity-removed); fallback path skips silently if unavailable.
+- iOS uses foreground-active heuristic for screen-on (background = passenger usage assumed).
+
+## [4.1.0](https://github.com/josuelmm/cordova-background-geolocation/tree/4.1.0) (2026-05-09)
+
+### Phase 6.1 — GPS-derived sensor-like driving events
+
+#### Added
+
+- **`hardBrake`** — emitted when GPS-derived deceleration `Δspeed/Δt` ≤ `-drivingEvents.hardBrakeMps2` during an active trip. Payload `{ location, value }` where `value` is the negative m/s².
+- **`rapidAcceleration`** — emitted when GPS-derived acceleration ≥ `drivingEvents.rapidAccelMps2` during an active trip.
+- **`sharpTurn`** — emitted when |Δbearing|/Δt ≥ `drivingEvents.sharpTurnDegPerSec` and speed ≥ 5 m/s (filters GPS jitter at low speeds).
+- **`possibleCrash`** — heuristic. Fires when speed drops by ≥ `drivingEvents.crashImpactKmh` within `crashWindowMs` and ends near 0 during an active trip. Payload `{ location, value }` where `value` is the velocity drop in km/h. **Apps must always confirm with the user before notifying contacts** — false positives are expected (sudden tunnel exit, GPS glitches).
+- All 4 events have a 4-second cooldown to avoid refiring during sustained events.
+
+#### Added — Config
+
+- Extended `drivingEvents` with: `hardBrakeMps2` (default 3.5), `rapidAccelMps2` (default 3.5), `sharpTurnDegPerSec` (default 30), `crashImpactKmh` (default 25), `crashWindowMs` (default 2000). Set any to `0` to disable that specific event.
+
+#### Implementation
+
+- Android `DrivingEventsDetector`: state machine extended with `prevSpeed`/`prevBearing` deltas, per-event cooldown, and the 4 new listener callbacks.
+- Android `Config.DrivingEventsOptions`: 5 new fields parceled with the existing primitives pattern.
+- Android `LocationServiceImpl`: 4 new MSG codes (120-123) routed through `BackgroundGeolocationFacade` to the new default-no-op methods on `PluginDelegate`.
+- iOS `MAURBackgroundGeolocationFacade.drivingDetectorFeed:`: same state machine in Objective-C, posting 4 new `NSNotification` names.
+- iOS `CDVBackgroundGeolocation`: 4 new observers + `sendDrivingEventN:note:` helper.
+- TypeScript: 4 new event names in `Event` union and `BackgroundGeolocationEvents` enum; 4 new typed `on()` overloads.
+- Plugin version bumped to `4.1.0` in all 4 sync points.
+
+#### Sensor-fusion (deferred)
+
+- Real accelerometer + gyroscope sampling (`Sensor.TYPE_LINEAR_ACCELERATION`, `CMMotionManager.deviceMotion`) deferred. The current heuristics work surprisingly well for `hardBrake` and `rapidAcceleration` because GPS already reports speed; `sharpTurn` works above 5 m/s; `possibleCrash` is intentionally conservative. v4.2 will add a separate `SensorFusionDetector` for finer-grained event detection during slow driving and parking-lot crashes.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/4.0.0...4.1.0)
+
+---
+
+## [4.0.0](https://github.com/josuelmm/cordova-background-geolocation/tree/4.0.0) (2026-05-08)
+
+### Phase 6 — Driver insights (Roadmap v4.0)
+
+#### Added — GPS-based driver-insight events (no extra sensors required)
+
+- **`tripStart`** — emitted when the user moves continuously above `drivingEvents.minTripSpeed` for `minTripDuration`. Payload: latest location.
+- **`tripEnd`** — emitted when the user becomes "stopped" while a trip was active. Payload: `{ location, distance, durationMs }`.
+- **`moving`** — speed crossed above `minMovingSpeed`.
+- **`stopped`** — speed below the threshold for `stoppedDuration`.
+- **`speeding`** — speed crossed above `drivingEvents.speedLimit` (km/h). Rearms when speed drops below.
+- **`providerChange`** — native location provider changed (GPS / network / fused). Payload: `{ provider }`.
+- **`sos`** — emitted by `BackgroundGeolocation.triggerSOS(payload?)`. Payload: user dictionary plus `location` (the latest known fix; absent if no fix yet).
+
+#### Added — Methods
+
+- **`triggerSOS(payload?)`** — JS API + Angular service + Android `BackgroundGeolocationFacade.triggerSOS(JSONObject)` + iOS `MAURBackgroundGeolocationFacade triggerSOS:`.
+
+#### Added — Config
+
+- **`drivingEvents`** option:
+  ```ts
+  drivingEvents?: {
+    enabled?: boolean;
+    speedLimit?: number;       // km/h, 0 disables
+    minMovingSpeed?: number;   // m/s, default 1.0
+    stoppedDuration?: number;  // ms, default 60000
+    minTripSpeed?: number;     // m/s, default 3.0
+    minTripDuration?: number;  // ms, default 30000
+  };
+  ```
+
+#### Implementation
+
+- New shared GPS state machine: Android `com.marianhello.bgloc.driving.DrivingEventsDetector` (pure-Java, hosted by `LocationServiceImpl.onLocation` and broadcasting via the `MSG_ON_*` pipeline); iOS inline detector inside `MAURBackgroundGeolocationFacade` posting `NSNotification`s.
+- New Android MSG codes: `MSG_ON_TRIP_START` (113), `MSG_ON_TRIP_END` (114), `MSG_ON_MOVING` (115), `MSG_ON_STOPPED` (116), `MSG_ON_SPEEDING` (117), `MSG_ON_PROVIDER_CHANGE` (118), `MSG_ON_SOS` (119). Routed by `BackgroundGeolocationFacade` to the new default-no-op methods on `PluginDelegate`.
+- iOS notification names: `MAURTripStartNotification`, `MAURTripEndNotification`, `MAURMovingNotification`, `MAURStoppedNotification`, `MAURSpeedingNotification`, `MAURProviderChangeNotification`, `MAURSOSNotification`. Observed by `CDVBackgroundGeolocation.pluginInitialize`.
+- TypeScript: 7 new event names in the `Event` union and `BackgroundGeolocationEvents` enum; 7 new typed `on()` overloads with full payload typings; new `triggerSOS()` method declaration.
+- Plugin version bumped to `4.0.0` in `package.json`, `plugin.xml`, Android `PLUGIN_VERSION` and iOS `getPluginVersion`.
+
+#### Sensor-fusion events deferred to v4.1
+
+- `hardBrake`, `rapidAcceleration`, `sharpTurn`, `possibleCrash` require accelerometer + gyroscope sampling and a separate detector class. They are intentionally not part of v4.0.0 to keep this release focused on GPS-only signals that work reliably on every device. The API surface for `drivingEvents` is intentionally extensible so v4.1 can add `hardBrakeMps2`, `sharpTurnDegPerSec`, `crashImpactKmh` thresholds without breaking changes.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.6.0...4.0.0)
+
+---
+
+## [3.6.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.6.0) (2026-05-08)
+
+### Phase 5 — Battery / OEM helpers (Roadmap v3.6)
+
+#### Added
+
+- **`isIgnoringBatteryOptimizations()`** — Android: returns `true` if the app is on the system battery-optimisation whitelist (Settings → Battery → "Don't optimise"). iOS: resolves `true` (concept does not apply).
+- **`requestIgnoreBatteryOptimizations()`** — Android: opens the system dialog to add the app to the whitelist; the user must accept. Falls back to the battery settings screen if the system dialog is unavailable. iOS: no-op resolves `true`.
+- **`openBatterySettings()`** — Android: opens the per-app battery-optimisation settings screen (with fallback to app-info). iOS: opens the app's Settings entry via `UIApplicationOpenSettingsURLString`.
+- **`openAutoStartSettings()`** — Android: opens the OEM-specific "auto-start" / "background activity" screen on Xiaomi MIUI, Huawei EMUI, Oppo ColorOS, Vivo FunTouch, OnePlus, Asus and Samsung (Samsung falls back to app-info because there is no stable component). Resolves `{ opened, manufacturer, screen }`. iOS: opens the app's Settings entry and reports `manufacturer: 'apple'`.
+- **`getManufacturerHelp()`** — returns OEM-specific guidance steps (`{ manufacturer, steps: string[] }`) so the app can render an actionable help screen when the FGS is being killed by the OEM. Coverage: Xiaomi (MIUI/Redmi/Poco), Huawei/Honor (EMUI), Oppo (ColorOS), Vivo (FunTouch), Samsung (One UI), OnePlus, Asus, generic Android, iOS.
+
+#### Implementation
+
+- New helper class `com.marianhello.bgloc.oem.BatteryOemHelper` (Android) wraps the `PowerManager.isIgnoringBatteryOptimizations(...)` call, the `Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` dialog, and a per-OEM `ComponentName` table for the auto-start screens. Components verified against AOSP / OEM forks.
+- iOS: 5 best-effort selectors in `CDVBackgroundGeolocation.m` that use `UIApplicationOpenSettingsURLString` and report `manufacturer: 'apple'` so the JS layer can branch with `getManufacturerHelp()`.
+- TypeScript surface: 5 new methods on the `BackgroundGeolocationPlugin` interface with strong types for the result objects (`isIgnoringBatteryOptimizations`, `requestIgnoreBatteryOptimizations`, `openBatterySettings`, `openAutoStartSettings`, `getManufacturerHelp`).
+- Angular service re-exports all 5 methods.
+- `plugin.xml`: registers `android/common/.../oem/BatteryOemHelper.java` as a `<source-file>`.
+- Plugin version bumped to `3.6.0` in `package.json`, `plugin.xml`, Android `PLUGIN_VERSION`, and iOS `getPluginVersion`.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.5.0...3.6.0)
+
+---
+
+## [3.5.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.5.0) (2026-05-08)
+
+### Phase 4 — Diagnostics (Roadmap v3.5)
+
+#### Added
+
+- **`getDiagnostics()`** — extended diagnostics method that explains *why* tracking may not be running in production. Returns a typed `Diagnostics` object covering, where applicable to the platform: `isRunning`, `locationServicesEnabled`, `startOnBoot`, `pendingSyncCount`, `lastLocationAt`, plus permissions (`fineLocationGranted`, `coarseLocationGranted`, `backgroundLocationGranted`, `notificationPermissionGranted`, `activityRecognitionGranted`), `batteryOptimizationIgnored`, `manufacturer`, `foregroundServiceType` (Android), and `preciseLocationEnabled`, `backgroundRefreshStatus`, `lowPowerModeEnabled`, `motionPermissionStatus`, `authorizationStatusText` (iOS).
+- **`Diagnostics` TypeScript interface** in `www/BackgroundGeolocation.d.ts`.
+- **Angular service:** `BackgroundGeolocationService.getDiagnostics(success?, fail?)`.
+
+#### Implementation
+
+- Android `BackgroundGeolocationPlugin`: new action `getDiagnostics` + helpers `hasPermission`, `isIgnoringBatteryOptimizations`, `readForegroundServiceTypeFromManifest`. Plugin version bumped to `3.5.0`.
+- iOS `CDVBackgroundGeolocation`: new selector `getDiagnostics:` reads `CLLocationManager.authorizationStatus`, `accuracyAuthorization` (iOS 14+), `UIBackgroundRefreshStatus`, `NSProcessInfo.lowPowerModeEnabled` (iOS 9+), `CMMotionActivityManager.authorizationStatus` (iOS 11+), and `MAURSQLiteLocationDAO.getLocationsForSyncCount`.
+- New imports added to iOS plugin: `CoreMotion/CoreMotion.h`, `UIKit/UIKit.h`, `MAURSQLiteLocationDAO.h`.
+
+### Phase 4 — extra (still in 3.5.0)
+
+- **`mockLocationPolicy: 'allow' | 'flag' | 'drop'`** — applied in Android `PostLocationTask` and iOS `MAURPostLocationTask`. With `'drop'`, a mocked location is discarded before persisting/posting; with `'flag'` it is delivered but the existing `isFromMockProvider` (Android) / `simulated` (iOS) field marks it; `'allow'` (default) preserves current behaviour.
+- **`heartbeatInterval`** config option added to `Config` / `MAURConfig` and `.d.ts`. Native timer-based emission of `heartbeat` is **still deferred** to 3.5.1+ (the surface — config + event name — is registered).
+- **Sync events emission (real, native).**
+  - Android: `MSG_ON_SYNC_START`, `MSG_ON_SYNC_SUCCESS`, `MSG_ON_SYNC_ERROR` codes added to `LocationServiceImpl`. `PluginDelegate` extended with default-no-op `onSyncStart()`, `onSyncSuccess(int)`, `onSyncError(int, String)`. `BackgroundGeolocationFacade.serviceBroadcastReceiver` routes them to the delegate. `SyncAdapter.uploadLocations` broadcasts `MSG_ON_SYNC_START` before the upload, then `MSG_ON_SYNC_SUCCESS` (with `sent` count) on 2xx or `MSG_ON_SYNC_ERROR` (with `httpStatus` + message) on non-2xx / IOException. `BackgroundGeolocationPlugin` overrides the new delegate methods and emits the events to JS.
+  - iOS: new notification names `MAURBackgroundSyncDidStartNotification`, `MAURBackgroundSyncDidSucceedNotification`, `MAURBackgroundSyncDidFailNotification` posted from `MAURBackgroundSync`. `CDVBackgroundGeolocation` registers observers in `pluginInitialize` and forwards them as `syncStart` / `syncSuccess` / `syncError` JS events. Payload includes `sent` (success) and `httpStatus` + `message` (error). `MAURBackgroundSyncDelegate` also exposes the new optional methods for in-process listeners.
+  - TypeScript: `Event` union extended with `'heartbeat' | 'syncStart' | 'syncProgress' | 'syncSuccess' | 'syncError'` so `removeAllListeners('syncSuccess')` etc. type-check.
+
+### Bug fixes
+
+- **iOS `getPluginVersion`:** returned the hardcoded string `"3.2.0"`; now returns `"3.5.0"` matching `plugin.xml` and the Android `PLUGIN_VERSION`. Production traceability restored.
+
+### Phase 4 — additional fixes (still in 3.5.0)
+
+- **`syncProgress` now emits natively.** Android: `MSG_ON_SYNC_PROGRESS = 111` added to `LocationServiceImpl`; `SyncAdapter.onProgress(int)` broadcasts the percentage; `BackgroundGeolocationFacade` routes it to the new `PluginDelegate.onSyncProgress(int)` (default no-op); `BackgroundGeolocationPlugin` emits the JS event with the integer payload. iOS: `NSURLSessionTaskDelegate didSendBodyData:totalBytesSent:totalBytesExpectedToSend:` computes 0..100 and posts `MAURBackgroundSyncDidProgressNotification`; `CDVBackgroundGeolocation` forwards it as `syncProgress` JS event with numeric payload.
+- **TypeScript `on()` overloads** for the new events: `'heartbeat'`, `'syncStart'`, `'syncProgress'`, `'syncSuccess'`, `'syncError'`. Apps can now write `BackgroundGeolocation.on('syncSuccess', ({ sent }) => ...)` with full type safety. The catch-all `BackgroundGeolocationEvents` enum overload was widened to cover the new payload shapes.
+- **Bug: `MAURBackgroundSync` `tasks` was never allocated** — `addObject:`, `removeObject:`, `cancel` and `status` silently no-op'd on a `nil` array (Objective-C messages-to-nil semantics), so background uploads couldn't be tracked or cancelled. `tasks` is now `[[NSMutableArray alloc] init]` in `init`.
+
+### Phase 4 — heartbeat native emission (still in 3.5.0)
+
+- **Heartbeat now emits natively.**
+  - Android: `LocationServiceImpl` adds `MSG_ON_HEARTBEAT = 112`, a `mLastReceivedLocation` field updated on every `onLocation()`, and a `ScheduledExecutorService`-based scheduler started after `MSG_ON_SERVICE_STARTED` and cancelled on stop. Each tick broadcasts the latest `BackgroundLocation` as the `payload` parcelable. `BackgroundGeolocationFacade` routes `MSG_ON_HEARTBEAT` to the new `PluginDelegate.onHeartbeat(BackgroundLocation)` (default no-op). `BackgroundGeolocationPlugin` forwards it to JS as `sendEvent("heartbeat", location.toJSONObjectWithId())`.
+  - iOS: `MAURBackgroundGeolocationFacade` declares `MAURHeartbeatNotification`, caches `lastReceivedLocation` on every `onLocationChanged:`, schedules an `NSTimer` (main run loop) when `start:` succeeds and invalidates it in `stop:`. Each tick posts `MAURHeartbeatNotification` with `userInfo[@"location"]`. `CDVBackgroundGeolocation` observes and emits a `heartbeat` JS event with the location dictionary (or empty when no fix yet).
+
+### Status
+
+- All Phase 4 deliverables for 3.5.0 are now native and end-to-end:
+  - `getDiagnostics()` ✅
+  - `mockLocationPolicy` ✅
+  - `syncStart` / `syncProgress` / `syncSuccess` / `syncError` ✅
+  - `heartbeat` ✅
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.4.0...3.5.0)
+
+---
+
+## [3.4.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.4.0) (2026-05-08)
+
+### Phase 3 — Location API modernization (Roadmap v3.4)
+
+#### Android
+
+- **`ActivityRecognitionLocationProvider.java`:** migrated to `new LocationRequest.Builder(priority, intervalMillis)` + `Priority.PRIORITY_*` (from `com.google.android.gms.location.Priority`). Replaces `LocationRequest.create()`, `setPriority()`, `setInterval()`, `setFastestInterval()` and `LocationRequest.PRIORITY_*` — all deprecated since `play-services-location 21.0.0`. Adds `setMinUpdateIntervalMillis` (replaces `fastestInterval`) and `setWaitForAccurateLocation(false)`.
+- **`RawLocationProvider.java`:** removed `Criteria` API and `LocationManager.getBestProvider(criteria, true)`. Provider selection is now explicit GPS-first / Network-fallback. Drops the historical "boost stationary" Criteria block; behaviour matches GPS-enabled path on modern Android.
+- **`plugin.xml`:** bumped `GOOGLE_PLAY_SERVICES_VERSION` default from `17+` to `21.0.1`. Apps overriding the variable continue to work.
+
+#### iOS
+
+- **`MAURPostLocationTask.m`:** migrated `[NSURLConnection sendSynchronousRequest:returningResponse:error:]` (deprecated since iOS 9) to `NSURLSession dataTaskWithRequest:completionHandler:` synchronised via `dispatch_semaphore`. Caller still receives `error` and `statusCode` with the same semantics; the call is safe because it runs on a background queue.
+- **`MAURDistanceFilterLocationProvider.m`:** added `locationManagerDidChangeAuthorization:` (iOS 14+) which is the canonical replacement for the deprecated `locationManager:didChangeAuthorizationStatus:`. Both callbacks share a private helper `handleAuthorizationStatusChange:`. The legacy callback is short-circuited on iOS 14+ to avoid double-notifying delegates.
+- **`MAURDistanceFilterLocationProvider.m` + `MAURConfig`:** new `showsBackgroundLocationIndicator` config option (iOS 11+). When `true`, iOS shows the blue status indicator while the app uses location in the background.
+
+#### TypeScript
+
+- `www/BackgroundGeolocation.d.ts`: added `showsBackgroundLocationIndicator?: boolean` (iOS) with documentation.
+
+#### Versions
+
+- `cordovaDependencies."3.4.0"`: requires `cordova-ios >= 6.2.0`. The new APIs use runtime availability checks (`@available(iOS 11.0, *)` for `showsBackgroundLocationIndicator`, `API_AVAILABLE(ios(14.0))` for `locationManagerDidChangeAuthorization:`), so older iOS versions still link and run.
+
+### Bug fixes
+
+- **iOS `MAURConfig.fromDictionary`:** corrected `isNull(config[@"activitiesInterval"])` → `isNotNull(...)`. The inverted check meant a value sent by the app was assigned only when the dictionary entry was missing/null, effectively dropping user input. Pre-existing bug.
+- **Android `HttpPostService.postJSONString`:** `Content-Length` now uses UTF-8 byte length instead of `String.length()`. Multi-byte characters (`ñ`, `é`, emoji, ...) now match the body sent. Pre-existing bug.
+
+### Phase 3 also closed
+
+- **Android `DistanceFilterLocationProvider`:** the legacy `Criteria` API is fully removed. The `criteria` field, its init in `onCreate()`, and the `translateDesiredAccuracy(...)` helper are gone. `LocationManager.getBestProvider(criteria, true)` is replaced by an explicit `pickProvider()` (GPS-first, Network-fallback). `requestSingleUpdate(criteria, ...)` in `StationaryLocationMonitorReceiver` is replaced by the provider-string overload plus a wider `try/catch` that also handles `IllegalArgumentException`.
+
+### Notes (still legacy but functional)
+
+- `LocationManager.getLastKnownLocation(provider)` is **not** deprecated; only `getBestProvider(Criteria, ...)` is. Kept as-is in `getLastBestLocation()`.
+- `LocationManager.requestSingleUpdate(String, PendingIntent)` is deprecated since API 30 but is the only PendingIntent-based path; the modern `getCurrentLocation` does not accept a `PendingIntent` and would require redesigning the receiver pattern that wakes the app from background.
+- `AlarmManager.setInexactRepeating` retained for stationary polling. Doze defers it to ≥9-15 min windows; an FGS-driven `LocationCallback` interval is the planned replacement.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.3.0...3.4.0)
+
+---
+
+## [3.3.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.3.0) (2026-05-07)
+
+### Phase 2 — Backend-agnostic HTTP transport (Roadmap v3.3)
+
+#### Added
+
+- **`httpMethod`** and **`syncHttpMethod`** config options. Values: `POST` (default), `GET`, `PUT`, `PATCH`. Removes the previously hardcoded `POST` in Android (`HttpPostService.java`) and iOS (`MAURPostLocationTask.m`, `MAURBackgroundSync.m`).
+- **`httpMode`** and **`syncMode`** config options. Values: `batch` (default) or `single` (one HTTP request per location). `single` is required when `httpMethod === 'GET'`.
+- **URL templating.** The plugin now substitutes placeholders in `url`, `syncUrl` (and string values inside `bodyTemplate`/`postTemplate`) using the current location plus any `queryParams`. Built-in placeholders: `{latitude}`, `{longitude}`, `{lat}`, `{lon}`, `{time}`, `{timestamp}`, `{timestamp_iso}`, `{speed}`, `{altitude}`, `{bearing}`, `{accuracy}`, `{provider}`. Any extra `queryParams` keys are also available (e.g. `{device_id}`, `{token}`).
+- **`queryParams`** config option. Static dictionary used to fill placeholders not derived from a location.
+- **`headers`** config option as alias of `httpHeaders` (if both are present, `headers` wins).
+- **`bodyTemplate`** config option as alias of `postTemplate`.
+- New helpers: Android `com.marianhello.bgloc.http.UrlTemplateResolver` and iOS `MAURUrlTemplateResolver`.
+
+#### Changed
+
+- **`Config` / `MAURConfig`** extended with the new transport options. Parcelable read/write, copy constructor, defaults, `merge`, `toString`, `toDictionary` and `ConfigMapper` updated accordingly. All existing apps using only `url` + `httpHeaders` + `postTemplate` continue to work unchanged.
+- **`HttpPostService`** Android: `setRequestMethod` is now driven by the configured method. GET requests skip the body entirely. New static helpers `postJSON(url, json, headers, method)` and `postJSONFile(url, file, headers, listener, method)`.
+- **`MAURPostLocationTask` / `MAURBackgroundSync`** iOS: `setHTTPMethod` is parameterised. URL templates are resolved before each request. `single` mode posts one location per request.
+
+### Phase 1 — Auto-start Android (Roadmap v3.3)
+
+#### Added
+
+- **Android `ACCESS_BACKGROUND_LOCATION` permission** declared in `plugin.xml`. Required for Android 10+ when starting the foreground location service from background (boot, app update). Apps must request it at runtime with the proper flow (foreground → explanation → "Allow all the time").
+- **Boot/replace receiver expanded.** `BootCompletedReceiver` now also handles:
+  - `android.intent.action.QUICKBOOT_POWERON` (HTC, MIUI / Xiaomi).
+  - `com.htc.intent.action.QUICKBOOT_POWERON`.
+  - `android.intent.action.MY_PACKAGE_REPLACED` — service is restarted after the app is updated via Play Store, with no need for the user to re-open the app.
+- **Background location permission validated** in `BootCompletedReceiver` (Android 10+ only) and in `LocationServiceProxy.startForegroundService()`.
+- **`ForegroundServiceStartNotAllowedException` handled** (Android 12+). Both `BootCompletedReceiver` and `LocationServiceProxy.startForegroundService()` now wrap `startForegroundService()` in try/catch with clear logging. WorkManager is **not** used as a fallback for tracking — it is only suitable for deferred sync, not for continuous GPS.
+
+#### Changed
+
+- **`foregroundServiceType` simplified to `"location"`** (was `"location|dataSync"`). The service does not perform `dataSync`; declaring it added unnecessary scrutiny in Play Console.
+- **`LocationServiceImpl.startForeground()`** now reads `foregroundServiceType` dynamically from the merged manifest via `getManifestForegroundServiceType()` instead of using a hardcoded `0x8`. If the manifest type cannot be read (returns 0), the service refuses to start in foreground and logs an error rather than calling `startForeground` with an invalid type.
+- **`LocationServiceProxy.startForegroundService()`** no longer falls back to a non-foreground `startService()` when the location permission is missing. It now logs and exits, avoiding zombie services.
+- **`engines`** raised in both `package.json` and `plugin.xml`: `cordova >= 10.0.0`, `cordova-android >= 12.0.0`. Required for `targetSdk 34+` and modern foreground service handling.
+
+#### Removed
+
+- **`FOREGROUND_SERVICE_DATA_SYNC` permission** removed from `plugin.xml`. Pair of the `dataSync` foreground type cleanup above.
+- **`<uses-library android:name="org.apache.http.legacy" />`** removed from `plugin.xml`. The plugin's HTTP client uses `HttpURLConnection`; no `org.apache.http.*` imports exist in the codebase.
+- **`useLibrary 'org.apache.http.legacy'`** removed from `android/dependencies.gradle`. Same reason.
+- **Dead constant `FOREGROUND_SERVICE_TYPE_LOCATION = 4`** removed from `LocationServiceImpl.java`. Its value was incorrect (real value is `0x00000008 = 8`; `4` is `PHONE_CALL`) and the constant was never referenced.
+
+#### Build
+
+- **`jcenter()` replaced with `mavenCentral()`** in `android/build.gradle` (both `buildscript` and `allprojects` blocks). JCenter has been deprecated since 2022.
+
+#### Documentation
+
+- **`docs/auto-start.md`** — full guide for boot/restart behavior (Android current state, gaps, v3.3 plan with concrete diffs; iOS limitations).
+- **`docs/http-transport.md`** — backend-agnostic HTTP transport (Phase 2, v3.3.0).
+- **`docs/traccar.md`** — Traccar as an optional backend example (geofences, events, history); plugin remains backend-agnostic.
+- **`docs/driving-events.md`** — driving events plan (Phase 6, v4.0).
+- **`docs/location-modernization.md`** — location API modernization plan (Phase 3, v3.4).
+- **`docs/ROADMAP.md`** — phases 1→6.
+- **`REVIEW_3.2.0.md`** — full audit and rationale for the roadmap.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.2.0...3.3.0)
+
+---
+
 ## [3.2.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.2.0) (2026-02-28)
 
 ### Added

package/CLAUDE.md

@@ -0,0 +1,56 @@
+# 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

package/HISTORY.md

@@ -2,6 +2,131 @@
 
 **for cordova-plugin-background-geolocation**
 
+## [4.2.2] - 2026-05-09
+
+### Fixed
+- `PostLocationTask`: handle `LocationTemplate.locationToJson` returning `Object` (JSONObject vs JSONArray) — fixed compile failure under Capacitor / Gradle 8.x.
+- `BackgroundGeolocationPlugin.buildDiagnostics`: wrap `facade.locationServicesEnabled()` in `try/catch (PluginException)` — fixed unreported-checked-exception build error.
+- Plugin version: `4.2.2`.
+
+## [4.2.0] - 2026-05-08
+
+### Phase 8 — Real sensor fusion (accelerometer + gyroscope)
+
+- New Android `com.marianhello.bgloc.sensor.SensorFusionDetector` using `Sensor.TYPE_LINEAR_ACCELERATION` + `Sensor.TYPE_GYROSCOPE` at `SENSOR_DELAY_GAME`.
+- New iOS `MAURSensorFusionDetector` using `CMMotionManager.startDeviceMotionUpdatesToQueue` (50 Hz).
+- New `drivingEvents.sensorFusion` toggle (off by default) plus thresholds: `crashImpactG` (default 3.0), `sensorCrashCooldownMs`, `phoneUsageWindowMs`, `phoneUsageCooldownMs`.
+- `possibleCrash` event payload extended with `source: "gps" | "sensor"`.
+- New `phoneUsageWhileDriving` event (jitter + screen-on during active trip).
+- Hot-reload of sensor pipeline on `configure()`.
+- Plugin version: `4.2.0`.
+
+## [4.1.0] - 2026-05-09
+
+### Phase 6.1 — GPS-derived sensor-like driving events
+
+- New events: `hardBrake`, `rapidAcceleration`, `sharpTurn`, `possibleCrash` (all GPS-derived, no accelerometer/gyroscope yet).
+- New config thresholds: `hardBrakeMps2`, `rapidAccelMps2`, `sharpTurnDegPerSec`, `crashImpactKmh`, `crashWindowMs`. Set any to 0 to disable.
+- 4-second cooldown per event to avoid refiring on sustained conditions.
+- Android `DrivingEventsDetector` extended; iOS detector inline in `MAURBackgroundGeolocationFacade`. Same heuristics on both platforms.
+- 4 new MSG codes (120-123) and 4 new NSNotifications wired end-to-end to JS.
+- Plugin version: `4.1.0`.
+
+Sensor fusion (real accelerometer + gyroscope) deferred to v4.2 as a separate `SensorFusionDetector` class.
+
+## [4.0.0] - 2026-05-08
+
+### Phase 6 — Driver insights (GPS-only)
+
+- New events: `tripStart`, `tripEnd` (with `distance` + `durationMs`), `moving`, `stopped`, `speeding`, `providerChange`, `sos`.
+- New method: `triggerSOS(payload?)`. New config: `drivingEvents` with thresholds for moving / trip / speed limit.
+- Shared state machine: Android `DrivingEventsDetector.java` (pure-Java); iOS inline in `MAURBackgroundGeolocationFacade`. Android uses MSG codes 113-119 routed via the existing `PluginDelegate`; iOS uses 7 new `NSNotification`s observed in `CDVBackgroundGeolocation`.
+- TypeScript: 7 new event overloads, new method declaration, new config option.
+- Plugin version: `4.0.0`.
+
+### Sensor-fusion events deferred to v4.1
+- `hardBrake`, `rapidAcceleration`, `sharpTurn`, `possibleCrash` require accelerometer + gyroscope. Excluded on purpose to keep v4.0.0 GPS-only and reliable.
+
+## [3.6.0] - 2026-05-08
+
+### Phase 5 — Battery / OEM helpers
+
+- Added `isIgnoringBatteryOptimizations()`, `requestIgnoreBatteryOptimizations()`, `openBatterySettings()`, `openAutoStartSettings()`, `getManufacturerHelp()` (Android + iOS).
+- Android helper class `com.marianhello.bgloc.oem.BatteryOemHelper` with per-OEM `ComponentName` table for auto-start screens (Xiaomi MIUI, Huawei EMUI, Oppo ColorOS, Vivo FunTouch, OnePlus, Asus; Samsung falls back to app-info).
+- iOS uses `UIApplicationOpenSettingsURLString` as best-effort destination and reports `manufacturer: 'apple'`.
+- Angular service re-exports the 5 new helpers with strong types.
+
+## [3.5.0] - 2026-05-08
+
+### Phase 4 — Diagnostics
+
+- Added `getDiagnostics()` (Android + iOS) returning permissions, battery whitelist state, OEM manufacturer, last fix age, pending sync count, foreground service type (Android) and precise location / background refresh / low power / motion permission (iOS).
+- Added `Diagnostics` TypeScript interface in `www/BackgroundGeolocation.d.ts`.
+- Angular service exposes `getDiagnostics()`.
+- Android plugin version bumped to `3.5.0`.
+
+- Added `mockLocationPolicy: 'allow' | 'flag' | 'drop'` config (Android `Config` + iOS `MAURConfig`). Applied in `PostLocationTask` (Android) and `MAURPostLocationTask` (iOS): mocked samples are dropped before persistence when policy is `'drop'`.
+- Added `heartbeatInterval` config option (typed in `.d.ts`, persisted in `Config` / `MAURConfig`).
+- Registered events `heartbeat`, `syncStart`, `syncProgress`, `syncSuccess`, `syncError` in `www/BackgroundGeolocation.js` and both `Event` union and `BackgroundGeolocationEvents` enum in `.d.ts`.
+- **Sync events emit natively now**: Android via `MSG_ON_SYNC_*` broadcasts from `SyncAdapter` → `BackgroundGeolocationFacade` → `PluginDelegate` → `BackgroundGeolocationPlugin.sendEvent`; iOS via `NSNotificationCenter` from `MAURBackgroundSync` → `CDVBackgroundGeolocation` observers. `syncSuccess` payload includes `sent`; `syncError` payload includes `httpStatus` + `message`.
+- Bug: iOS `getPluginVersion` returned hardcoded `"3.2.0"`; now `"3.5.0"`.
+
+- `syncProgress` emits natively now: Android via `MSG_ON_SYNC_PROGRESS` from `SyncAdapter.onProgress`; iOS via `URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:` posting `MAURBackgroundSyncDidProgressNotification`. Both are forwarded as `syncProgress` JS events.
+- TypeScript `on()` overloads added for `'heartbeat'`, `'syncStart'`, `'syncProgress'`, `'syncSuccess'`, `'syncError'` so string-literal subscriptions type-check.
+- Bug: iOS `MAURBackgroundSync.tasks` was never allocated. Fixed in `init`.
+
+- `heartbeat` emits natively now: Android `LocationServiceImpl` schedules a `ScheduledExecutorService` task on service start using `Config.heartbeatInterval`, broadcasts `MSG_ON_HEARTBEAT` with the latest `BackgroundLocation`, and `BackgroundGeolocationPlugin` forwards it to JS. iOS `MAURBackgroundGeolocationFacade` schedules an `NSTimer` (main run loop), posts `MAURHeartbeatNotification`, and `CDVBackgroundGeolocation` forwards it as a `heartbeat` JS event with the latest location.
+
+Phase 4 status: all four deliverables (`getDiagnostics`, `mockLocationPolicy`, sync events, heartbeat) are now native and end-to-end.
+
+## [3.4.0] - 2026-05-08
+
+### Phase 3 — Location API modernization
+
+- Android `ActivityRecognitionLocationProvider`: `LocationRequest.Builder` + `Priority.PRIORITY_*` (replaces deprecated `LocationRequest.create()`, `setPriority/setInterval/setFastestInterval`, `LocationRequest.PRIORITY_*`).
+- Android `RawLocationProvider`: removed `Criteria` and `getBestProvider`; explicit GPS-first / Network-fallback selection.
+- `plugin.xml`: `GOOGLE_PLAY_SERVICES_VERSION` default raised to `21.0.1`.
+- iOS `MAURPostLocationTask`: `NSURLConnection` (deprecated iOS 9) replaced with `NSURLSession dataTaskWithRequest:` + `dispatch_semaphore` for the synchronous post path.
+- iOS `MAURDistanceFilterLocationProvider`: added `locationManagerDidChangeAuthorization:` (iOS 14+) alongside the legacy callback; short-circuit legacy on iOS 14+ to avoid double notifications.
+- iOS `MAURConfig` + `MAURDistanceFilterLocationProvider`: new `showsBackgroundLocationIndicator` config (iOS 11+).
+- TypeScript: `showsBackgroundLocationIndicator?: boolean` added to `ConfigureOptions`.
+- `cordova-ios >= 6.2.0` required for `3.4.0` (runtime `@available` checks gate iOS 11/14 APIs).
+
+- Android `DistanceFilterLocationProvider`: `Criteria` API fully removed; `getBestProvider(criteria, true)` replaced by explicit `pickProvider()`; `requestSingleUpdate(criteria, ...)` replaced by the provider-string overload.
+- Bug: iOS `activitiesInterval` parsing in `MAURConfig.fromDictionary` had inverted `isNull` check; fixed.
+- Bug: Android `Content-Length` used `String.length()` (chars) instead of UTF-8 byte length; fixed in `HttpPostService.postJSONString`.
+
+Notes (still legacy but functional):
+- `LocationManager.getLastKnownLocation` kept (not deprecated).
+- `LocationManager.requestSingleUpdate(String, PendingIntent)` kept (modern `getCurrentLocation` does not accept `PendingIntent`).
+- `AlarmManager.setInexactRepeating` kept for stationary polling; planned FGS-driven replacement.
+
+## [3.3.0] - 2026-05-07
+
+### Phase 2 — Backend-agnostic HTTP transport
+
+- Added: `httpMethod`, `syncHttpMethod` (`POST` default, also `GET`, `PUT`, `PATCH`).
+- Added: `httpMode`, `syncMode` (`batch` default, `single` for one request per location). `single` is required with `GET`.
+- Added: URL templating with placeholders `{latitude}`, `{longitude}`, `{lat}`, `{lon}`, `{time}`, `{timestamp}`, `{timestamp_iso}`, `{speed}`, `{altitude}`, `{bearing}`, `{accuracy}`, `{provider}` plus any keys from `queryParams`.
+- Added: `queryParams`, `headers` (alias of `httpHeaders`), `bodyTemplate` (alias of `postTemplate`).
+- Added: helpers `com.marianhello.bgloc.http.UrlTemplateResolver` (Android) and `MAURUrlTemplateResolver` (iOS).
+- Changed: `HttpPostService` (Android), `MAURPostLocationTask` and `MAURBackgroundSync` (iOS) no longer hardcode POST.
+- Compatibility: existing apps using only `url` + `httpHeaders` + `postTemplate` keep working.
+
+### Phase 1 — Auto-start Android
+
+- Added: `ACCESS_BACKGROUND_LOCATION` permission, validated at runtime on Android 10+ before starting the foreground service.
+- Added: boot receiver also handles `QUICKBOOT_POWERON` (HTC, MIUI), `com.htc.intent.action.QUICKBOOT_POWERON`, and `MY_PACKAGE_REPLACED` (service is relaunched after app updates).
+- Added: `ForegroundServiceStartNotAllowedException` (Android 12+) is now caught with clear logging in `BootCompletedReceiver` and `LocationServiceProxy`. WorkManager is not used as a tracking fallback (only for deferred sync).
+- Changed: `foregroundServiceType` simplified to `"location"`; `LocationServiceImpl.startForeground()` reads the type dynamically from the manifest instead of hardcoding `0x8`.
+- Changed: `LocationServiceProxy.startForegroundService()` no longer falls back to `startService()` when location permission is missing — it logs and exits.
+- Changed: `engines` raised to `cordova >= 10.0.0` and `cordova-android >= 12.0.0`.
+- Removed: `FOREGROUND_SERVICE_DATA_SYNC` permission and `dataSync` from `foregroundServiceType`.
+- Removed: `<uses-library org.apache.http.legacy>` and `useLibrary 'org.apache.http.legacy'` (no longer used; the plugin uses `HttpURLConnection`).
+- Removed: dead constant `FOREGROUND_SERVICE_TYPE_LOCATION = 4` in `LocationServiceImpl.java` (incorrect value; never referenced).
+- Build: `jcenter()` → `mavenCentral()` in `android/build.gradle`.
+- Docs: planning docs `docs/auto-start.md`, `docs/http-transport.md`, `docs/traccar.md`, `docs/driving-events.md`, `docs/ROADMAP.md`, `docs/location-modernization.md` (Fase 3 / v3.4). Audit in `REVIEW_3.2.0.md` (§8–§9 alineados al roadmap vigente).
+
 ## [3.2.0] - 2026-02-28
 
 ### Added