@josuelmm/cordova-background-geolocation 4.2.2 → 4.5.1

package/ios/common/BackgroundGeolocation/MAURLocationContract.m

@@ -26,7 +26,11 @@
         @{ @"name": @LC_COLUMN_NAME_PROVIDER, @"type": [SQLColumnType sqlColumnWithType: kText]},
         @{ @"name": @LC_COLUMN_NAME_LOCATION_PROVIDER, @"type": [SQLColumnType sqlColumnWithType: kText]},
         @{ @"name": @LC_COLUMN_NAME_STATUS, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
-        @{ @"name": @LC_COLUMN_NAME_RECORDED_AT, @"type": [SQLColumnType sqlColumnWithType: kInteger]}
+        @{ @"name": @LC_COLUMN_NAME_RECORDED_AT, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
+        // v4.5 — survive sync queue
+        @{ @"name": @LC_COLUMN_NAME_EVENTS_JSON, @"type": [SQLColumnType sqlColumnWithType: kText]},
+        @{ @"name": @LC_COLUMN_NAME_BATTERY_LEVEL, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
+        @{ @"name": @LC_COLUMN_NAME_IS_CHARGING, @"type": [SQLColumnType sqlColumnWithType: kInteger]}
     ];
     
     return [MAURSQLiteHelper createTableSqlStatement:@LC_TABLE_NAME columns:columns];

package/ios/common/BackgroundGeolocation/MAURPostLocationTask.h

@@ -30,6 +30,15 @@
 
 @property (nonatomic, weak) MAURConfig * _Nullable config;
 @property (nonatomic, weak) id<MAURPostLocationTaskDelegate> _Nullable delegate;
+/** v4.5.1 — pending driving events buffer owned by the facade; the task drains it onto the
+ *  post-transform location so events fired without a simultaneous fix (provider change,
+ *  sensor crash, phone usage) survive even if `locationTransform` returns a new instance.
+ *  Weak ref: if the facade is gone, no flush — by design. */
+@property (nonatomic, weak) NSMutableArray * _Nullable pendingDrivingEventsBuffer;
+/** v4.5.1 — same idea for the battery snapshot block. The facade installs a block that the
+ *  task invokes AFTER a successful transform, so even when `locationTransform` returns a
+ *  fresh instance, battery/charging fields land on what actually gets POSTed. */
+@property (nonatomic, copy) void (^ _Nullable attachBatterySnapshot)(MAURLocation * _Nonnull);
 
 - (void) add:(MAURLocation * _Nonnull)location;
 - (void) start;

package/ios/common/BackgroundGeolocation/MAURPostLocationTask.m

@@ -83,11 +83,63 @@ static MAURLocationTransform s_locationTransform = nil;
         MAURLocation *location = inLocation;
 
         if (locationTransform != nil) {
+            // v4.5.1 — snapshot v4.3+ fields BEFORE transform so they survive a transform
+            // that returns a brand new MAURLocation instance (otherwise events/battery would
+            // be lost en route to SQLite / backend).
+            NSMutableArray *rawEvents = inLocation.drivingEvents;
+            NSNumber *rawBattery = inLocation.batteryLevel;
+            NSNumber *rawCharging = inLocation.isCharging;
+
             location = locationTransform(location);
 
             if (location == nil) {
                 return;
             }
+
+            // v4.5.1 — re-attach fields the transform may have dropped. When the transform
+            // produced a NEW instance (`location != inLocation`), MERGE rawEvents into the new
+            // instance's array instead of overwriting — same semantics as Android
+            // `LocationServiceImpl.onLocation` re-attach. If the transform returned the same
+            // instance (mutated in place) the rawEvents are already there.
+            if (location != inLocation) {
+                if (rawEvents != nil && [rawEvents count] > 0) {
+                    if (location.drivingEvents == nil) {
+                        location.drivingEvents = [rawEvents mutableCopy];
+                    } else {
+                        [location.drivingEvents addObjectsFromArray:rawEvents];
+                    }
+                }
+                if (location.batteryLevel == nil) location.batteryLevel = rawBattery;
+                if (location.isCharging == nil)   location.isCharging   = rawCharging;
+            }
+        }
+
+        // v4.5.1 — drain pending driving events ONTO the post-transform location. Previously
+        // the facade drained them BEFORE [postLocationTask add:], so a transform that returned
+        // nil silently lost every buffered event. Now: if transform succeeded we're guaranteed
+        // `location != nil` here and the buffer is drained safely.
+        NSMutableArray *pendingBuffer = self.pendingDrivingEventsBuffer;
+        if (pendingBuffer != nil) {
+            @synchronized (pendingBuffer) {
+                if ([pendingBuffer count] > 0) {
+                    NSTimeInterval nowMs = [[NSDate date] timeIntervalSince1970] * 1000.0;
+                    if (location.drivingEvents == nil) location.drivingEvents = [NSMutableArray array];
+                    for (NSDictionary *ev in pendingBuffer) {
+                        NSNumber *t = ev[@"time"];
+                        NSTimeInterval evMs = t != nil ? [t doubleValue] : nowMs;
+                        if (nowMs - evMs <= 60000.0) {
+                            [location.drivingEvents addObject:ev];
+                        }
+                    }
+                    [pendingBuffer removeAllObjects];
+                }
+            }
+        }
+        // v4.5.1 — stamp battery snapshot AFTER transform so it lands on the POSTed instance
+        // even if the transform created a new one.
+        void (^attachBattery)(MAURLocation *) = self.attachBatterySnapshot;
+        if (attachBattery != nil) {
+            attachBattery(location);
         }
 
         // v3.5 Phase 4: mock location policy. Detection already exists in MAURLocation.simulated.
@@ -255,7 +307,8 @@ static MAURLocationTransform s_locationTransform = nil;
         return YES;
     }
     
-    if (*outError == nil) {
+    // v4.4.1: guard against outError == NULL (defensive — current callers pass &error).
+    if (outError == NULL || *outError == nil) {
         DDLogDebug(@"%@ Server error while posting locations responseCode: %ld", TAG, (long)statusCode);
     } else {
         DDLogError(@"%@ Error while posting locations %@", TAG, [*outError localizedDescription]);
@@ -269,6 +322,11 @@ static MAURLocationTransform s_locationTransform = nil;
     if (![self.config syncEnabled] || ![self.config hasValidSyncUrl]) {
         return;
     }
+    // v4.5.1 — rescue rows stuck in SyncPending from a previous upload that never completed
+    // (app/process killed mid-flight). Anything older than 15 min is safe to revert to
+    // PostPending; rows younger than that may still be uploading on a background NSURLSession.
+    NSTimeInterval staleCutoff = [[NSDate date] timeIntervalSince1970] - (15 * 60);
+    [[MAURSQLiteLocationDAO sharedInstance] restoreStaleSyncLocationsOlderThan:staleCutoff error:nil];
     // For sync (batch) only static queryParams placeholders apply; per-location templating
     // belongs in real-time post (httpMode="single" + httpMethod=GET) instead.
     NSString *resolvedSyncUrl = [MAURUrlTemplateResolver resolve:self.config.syncUrl location:nil queryParams:self.config.queryParams];

package/ios/common/BackgroundGeolocation/MAURSQLiteConfigurationDAO.m

@@ -88,7 +88,8 @@
         @COMMA_SEP @CC_COLUMN_NAME_PAUSE_LOCATION_UPDATES
         @COMMA_SEP @CC_COLUMN_NAME_TEMPLATE
         @COMMA_SEP @CC_COLUMN_NAME_LAST_UPDATED_AT
-        @") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,DateTime('now'))";
+        @COMMA_SEP @CC_COLUMN_NAME_CONFIG_JSON
+        @") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,DateTime('now'),?)";
 
     [queue inDatabase:^(FMDatabase *database) {
         success = [database executeUpdate:sql,
@@ -119,7 +120,9 @@
                     [config hasSaveBatteryOnBackground] ? config._saveBatteryOnBackground : @CC_COLUMN_NAME_NULLABLE,
                     [config hasMaxLocations] ? config.maxLocations : @CC_COLUMN_NAME_NULLABLE,
                     [config hasPauseLocationUpdates] ? config._pauseLocationUpdates : @CC_COLUMN_NAME_NULLABLE,
-                    (templateString != nil) ? templateString : @CC_COLUMN_NAME_NULLABLE
+                    (templateString != nil) ? templateString : @CC_COLUMN_NAME_NULLABLE,
+                    // v4.5: full Config as JSON for paridad con Android
+                    [self serializeConfigToJson:config]
                 ];
 
         if (success) {
@@ -165,6 +168,7 @@
     @COMMA_SEP @CC_COLUMN_NAME_MAX_LOCATIONS
     @COMMA_SEP @CC_COLUMN_NAME_PAUSE_LOCATION_UPDATES
     @COMMA_SEP @CC_COLUMN_NAME_TEMPLATE
+    @COMMA_SEP @CC_COLUMN_NAME_CONFIG_JSON
     @" FROM " @CC_TABLE_NAME @" WHERE " @CC_COLUMN_NAME_ID @" = 1";
     
     [queue inDatabase:^(FMDatabase *database) {
@@ -231,14 +235,60 @@
                     config._template = [NSJSONSerialization JSONObjectWithData:jsonTemplate options:0 error:nil];
                 }
             }
+            // v4.5: rehydrate post-3.2 keys from config_json blob (paridad Android).
+            // Index 28 is the new column. Strict NULL check (no NULLHACK sentinel for JSON column).
+            if (![rs columnIndexIsNull:28]) {
+                NSString *jsonString = [rs stringForColumnIndex:28];
+                if (jsonString != nil && jsonString.length > 0) {
+                    [self applyConfigJson:jsonString to:config];
+                }
+            }
         }
-        
+
         [rs close];
     }];
-    
+
     return config;
 }
 
+// v4.5: serialize all post-3.2 keys to JSON for storage. Mirrors Android ConfigJsonMapper.
+- (NSString*) serializeConfigToJson:(MAURConfig*)config
+{
+    NSMutableDictionary *j = [NSMutableDictionary dictionary];
+    if (config.httpMethod != nil)       j[@"httpMethod"]       = config.httpMethod;
+    if (config.syncHttpMethod != nil)   j[@"syncHttpMethod"]   = config.syncHttpMethod;
+    if (config.httpMode != nil)         j[@"httpMode"]         = config.httpMode;
+    if (config.syncMode != nil)         j[@"syncMode"]         = config.syncMode;
+    if (config.queryParams != nil)      j[@"queryParams"]      = config.queryParams;
+    if (config.heartbeatInterval != nil) j[@"heartbeatInterval"] = config.heartbeatInterval;
+    if (config.mockLocationPolicy != nil) j[@"mockLocationPolicy"] = config.mockLocationPolicy;
+    if (config.drivingEvents != nil)    j[@"drivingEvents"]    = config.drivingEvents;
+    if (config.includeBattery != nil)   j[@"includeBattery"]   = config.includeBattery;
+    if (config._showsBackgroundLocationIndicator != nil) j[@"showsBackgroundLocationIndicator"] = config._showsBackgroundLocationIndicator;
+    NSError *err = nil;
+    NSData *data = [NSJSONSerialization dataWithJSONObject:j options:0 error:&err];
+    if (err != nil || data == nil) return @"";
+    return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+}
+
+- (void) applyConfigJson:(NSString*)jsonString to:(MAURConfig*)config
+{
+    NSData *data = [jsonString dataUsingEncoding:NSUTF8StringEncoding];
+    NSError *err = nil;
+    NSDictionary *j = [NSJSONSerialization JSONObjectWithData:data options:0 error:&err];
+    if (err != nil || ![j isKindOfClass:[NSDictionary class]]) return;
+    if (j[@"httpMethod"])         config.httpMethod         = j[@"httpMethod"];
+    if (j[@"syncHttpMethod"])     config.syncHttpMethod     = j[@"syncHttpMethod"];
+    if (j[@"httpMode"])           config.httpMode           = j[@"httpMode"];
+    if (j[@"syncMode"])           config.syncMode           = j[@"syncMode"];
+    if ([j[@"queryParams"] isKindOfClass:[NSDictionary class]]) config.queryParams = [j[@"queryParams"] mutableCopy];
+    if (j[@"heartbeatInterval"]) config.heartbeatInterval   = j[@"heartbeatInterval"];
+    if (j[@"mockLocationPolicy"]) config.mockLocationPolicy = j[@"mockLocationPolicy"];
+    if ([j[@"drivingEvents"] isKindOfClass:[NSDictionary class]]) config.drivingEvents = j[@"drivingEvents"];
+    if (j[@"includeBattery"] != nil) config.includeBattery = j[@"includeBattery"];
+    if (j[@"showsBackgroundLocationIndicator"] != nil) config._showsBackgroundLocationIndicator = j[@"showsBackgroundLocationIndicator"];
+}
+
 - (BOOL) clearDatabase
 {
     __block BOOL success;

package/ios/common/BackgroundGeolocation/MAURSQLiteLocationDAO.h

@@ -28,6 +28,18 @@
 - (BOOL) deleteAllLocations:(NSError * __autoreleasing *)outError;
 /** Mark all locations pending sync (PostPending) as deleted. Clears the sync queue without sending. */
 - (BOOL) deletePendingSyncLocations:(NSError * __autoreleasing *)outError;
+/** v4.5.1 — soft-delete only sync-pending rows whose `recorded_at` is <= cutoff (UNIX seconds).
+ *  Used after a successful background-sync POST so locations persisted DURING the upload (race
+ *  window) are NOT incorrectly marked deleted. */
+- (BOOL) deleteSyncedLocationsBefore:(NSTimeInterval)cutoff error:(NSError * __autoreleasing *)outError;
+/** v4.5.1 — undo the in-flight SyncPending state when the upload failed. SyncPending → PostPending
+ *  so the next sync window re-tries them. Without this, a network failure during background-sync
+ *  would silently drop every pending location. */
+- (BOOL) restoreFailedSyncLocations:(NSError * __autoreleasing *)outError;
+/** v4.5.1 — recover SyncPending rows that got stuck (app/process killed between getLocationsForSync
+ *  and the upload's success/failure callback). Rows whose `recorded_at` is older than `cutoff`
+ *  (UNIX seconds) are restored to PostPending so they get retried. Call before each sync window. */
+- (BOOL) restoreStaleSyncLocationsOlderThan:(NSTimeInterval)cutoff error:(NSError * __autoreleasing *)outError;
 - (BOOL) clearDatabase;
 - (NSString*) getDatabaseName;
 - (NSString*) getDatabasePath;

package/ios/common/BackgroundGeolocation/MAURSQLiteLocationDAO.m

@@ -94,9 +94,17 @@
         }
         [rs close];
 
-        sql = @"UPDATE " @LC_TABLE_NAME @" SET " @LC_COLUMN_NAME_STATUS @" = ?";
-        if (![database executeUpdate:sql, [NSString stringWithFormat:@"%ld", MAURLocationDeleted]]) {
-            NSLog(@"Deleting all location failed code: %d: message: %@", [database lastErrorCode], [database lastErrorMessage]);
+        // v4.5.1 FIX (CRITICAL): mark the rows we just selected as SyncPending — NOT Deleted.
+        // The previous code UPDATEd the WHOLE table to Deleted before the upload had even started,
+        // losing every fix on HTTP failure / network drop. Now:
+        //   PostPending → SyncPending  (in-flight, do not re-include)
+        //   on success in the network task: SyncPending → Deleted (deleteSyncedLocationsBefore:)
+        //   on failure in the network task: SyncPending → PostPending (restoreFailedSyncLocations)
+        NSString *upd = @"UPDATE " @LC_TABLE_NAME @" SET " @LC_COLUMN_NAME_STATUS @" = ? WHERE " @LC_COLUMN_NAME_STATUS @" = ?";
+        if (![database executeUpdate:upd,
+                [NSString stringWithFormat:@"%ld", MAURLocationSyncPending],
+                [NSString stringWithFormat:@"%ld", MAURLocationPostPending]]) {
+            NSLog(@"Marking PostPending → SyncPending failed code: %d: message: %@", [database lastErrorCode], [database lastErrorMessage]);
         }
     }];
 
@@ -139,7 +147,18 @@
     @COMMA_SEP @LC_COLUMN_NAME_LOCATION_PROVIDER
     @COMMA_SEP @LC_COLUMN_NAME_STATUS
     @COMMA_SEP @LC_COLUMN_NAME_RECORDED_AT
-    @") VALUES (?,?,?,?,?,?,?,?,?,?,?)";
+    @COMMA_SEP @LC_COLUMN_NAME_EVENTS_JSON
+    @COMMA_SEP @LC_COLUMN_NAME_BATTERY_LEVEL
+    @COMMA_SEP @LC_COLUMN_NAME_IS_CHARGING
+    @") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)";
+
+    // v4.5: serialize driving events array to JSON for SQLite storage.
+    NSString *eventsJson = nil;
+    if (location.drivingEvents != nil && [location.drivingEvents count] > 0) {
+        NSError *jerr = nil;
+        NSData *jd = [NSJSONSerialization dataWithJSONObject:location.drivingEvents options:0 error:&jerr];
+        if (jd != nil) eventsJson = [[NSString alloc] initWithData:jd encoding:NSUTF8StringEncoding];
+    }
 
     BOOL success = [database executeUpdate:sql,
         [NSNumber numberWithDouble:[location.time timeIntervalSince1970]],
@@ -152,7 +171,10 @@
         location.provider ?: [NSNull null],
         location.locationProvider ?: [NSNull null],
         location.isValid == YES ? @(1) : @(0),
-        recordedAt
+        recordedAt,
+        eventsJson ?: [NSNull null],
+        location.batteryLevel ?: [NSNull null],
+        location.isCharging ?: [NSNull null]
     ];
 
     if (success) {
@@ -223,8 +245,19 @@
         @COMMA_SEP @LC_COLUMN_NAME_LOCATION_PROVIDER @EQ_BIND
         @COMMA_SEP @LC_COLUMN_NAME_STATUS @EQ_BIND
         @COMMA_SEP @LC_COLUMN_NAME_RECORDED_AT @EQ_BIND
+        @COMMA_SEP @LC_COLUMN_NAME_EVENTS_JSON @EQ_BIND
+        @COMMA_SEP @LC_COLUMN_NAME_BATTERY_LEVEL @EQ_BIND
+        @COMMA_SEP @LC_COLUMN_NAME_IS_CHARGING @EQ_BIND
         @" WHERE " @LC_COLUMN_NAME_ID @EQ_BIND;
 
+        // v4.5.1: serialize events for UPDATE path so old values don't bleed onto new locations
+        NSString *eventsJsonForUpdate = nil;
+        if (location.drivingEvents != nil && [location.drivingEvents count] > 0) {
+            NSError *jerr = nil;
+            NSData *jd = [NSJSONSerialization dataWithJSONObject:location.drivingEvents options:0 error:&jerr];
+            if (jd != nil) eventsJsonForUpdate = [[NSString alloc] initWithData:jd encoding:NSUTF8StringEncoding];
+        }
+
         BOOL success = [database executeUpdate:sql,
             [NSNumber numberWithDouble:[location.time timeIntervalSince1970]],
             location.accuracy,
@@ -237,6 +270,9 @@
             location.locationProvider ?: [NSNull null],
             location.isValid == YES ? @(1) : @(0),
             recordedAt,
+            eventsJsonForUpdate ?: [NSNull null],
+            location.batteryLevel ?: [NSNull null],
+            location.isCharging ?: [NSNull null],
             locationId
         ];
 
@@ -304,6 +340,77 @@
     return success;
 }
 
+- (BOOL) deleteSyncedLocationsBefore:(NSTimeInterval)cutoff error:(NSError * __autoreleasing *)outError
+{
+    __block BOOL success = YES;
+    // v4.5.1 — operate on SyncPending (the rows the network task is/was uploading), not on
+    // PostPending (those are still queued for real-time POST and must NOT be touched).
+    NSString *sql = @"UPDATE " @LC_TABLE_NAME
+        @" SET " @LC_COLUMN_NAME_STATUS @" = ? "
+        @" WHERE " @LC_COLUMN_NAME_STATUS @" = ? AND " @LC_COLUMN_NAME_RECORDED_AT @" <= ?";
+    [queue inDatabase:^(FMDatabase *database) {
+        if (![database executeUpdate:sql,
+                @(MAURLocationDeleted),
+                @(MAURLocationSyncPending),
+                @(cutoff)]) {
+            int errorCode = [database lastErrorCode];
+            NSString *errorMessage = [database lastErrorMessage];
+            NSLog(@"deleteSyncedLocationsBefore failed code: %d: message: %@", errorCode, errorMessage);
+            if (outError != NULL) {
+                *outError = [NSError errorWithDomain:Domain code:errorCode userInfo:@{ NSLocalizedDescriptionKey: errorMessage ?: @"" }];
+            }
+            success = NO;
+        }
+    }];
+    return success;
+}
+
+- (BOOL) restoreStaleSyncLocationsOlderThan:(NSTimeInterval)cutoff error:(NSError * __autoreleasing *)outError
+{
+    // v4.5.1 — rows left as SyncPending because the previous sync's task was killed
+    // (app suspended mid-upload, OS process death, manual kill) never reach their
+    // success/failure callback. Call at the start of each sync window to rescue them.
+    __block BOOL success = YES;
+    NSString *sql = @"UPDATE " @LC_TABLE_NAME
+        @" SET " @LC_COLUMN_NAME_STATUS @" = ? "
+        @" WHERE " @LC_COLUMN_NAME_STATUS @" = ? AND " @LC_COLUMN_NAME_RECORDED_AT @" < ?";
+    [queue inDatabase:^(FMDatabase *database) {
+        if (![database executeUpdate:sql,
+                @(MAURLocationPostPending),
+                @(MAURLocationSyncPending),
+                @(cutoff)]) {
+            int errorCode = [database lastErrorCode];
+            NSString *errorMessage = [database lastErrorMessage];
+            NSLog(@"restoreStaleSyncLocations failed code: %d: message: %@", errorCode, errorMessage);
+            if (outError != NULL) {
+                *outError = [NSError errorWithDomain:Domain code:errorCode userInfo:@{ NSLocalizedDescriptionKey: errorMessage ?: @"" }];
+            }
+            success = NO;
+        }
+    }];
+    return success;
+}
+
+- (BOOL) restoreFailedSyncLocations:(NSError * __autoreleasing *)outError
+{
+    // v4.5.1 — undo the in-flight transition: SyncPending → PostPending so the next sync window
+    // (or real-time post) re-tries them.
+    __block BOOL success = YES;
+    NSString *sql = @"UPDATE " @LC_TABLE_NAME @" SET " @LC_COLUMN_NAME_STATUS @" = ? WHERE " @LC_COLUMN_NAME_STATUS @" = ?";
+    [queue inDatabase:^(FMDatabase *database) {
+        if (![database executeUpdate:sql, @(MAURLocationPostPending), @(MAURLocationSyncPending)]) {
+            int errorCode = [database lastErrorCode];
+            NSString *errorMessage = [database lastErrorMessage];
+            NSLog(@"restoreFailedSyncLocations failed code: %d: message: %@", errorCode, errorMessage);
+            if (outError != NULL) {
+                *outError = [NSError errorWithDomain:Domain code:errorCode userInfo:@{ NSLocalizedDescriptionKey: errorMessage ?: @"" }];
+            }
+            success = NO;
+        }
+    }];
+    return success;
+}
+
 - (BOOL) deletePendingSyncLocations:(NSError * __autoreleasing *)outError
 {
     __block BOOL success = YES;
@@ -368,6 +475,9 @@
     @COMMA_SEP @LC_COLUMN_NAME_LOCATION_PROVIDER
     @COMMA_SEP @LC_COLUMN_NAME_STATUS
     @COMMA_SEP @LC_COLUMN_NAME_RECORDED_AT
+    @COMMA_SEP @LC_COLUMN_NAME_EVENTS_JSON
+    @COMMA_SEP @LC_COLUMN_NAME_BATTERY_LEVEL
+    @COMMA_SEP @LC_COLUMN_NAME_IS_CHARGING
     @" FROM " @LC_TABLE_NAME;
 }
 
@@ -387,6 +497,16 @@
     location.isValid = [rs intForColumnIndex:10] == 1 ? YES : NO;
     NSTimeInterval recordedAt = [rs longForColumnIndex:11];
     location.recordedAt = [NSDate dateWithTimeIntervalSince1970:recordedAt];
+    // v4.5: events / battery / charging
+    NSString *eventsJson = [rs stringForColumnIndex:12];
+    if (eventsJson != nil && eventsJson.length > 0) {
+        NSError *jerr = nil;
+        id parsed = [NSJSONSerialization JSONObjectWithData:[eventsJson dataUsingEncoding:NSUTF8StringEncoding] options:NSJSONReadingMutableContainers error:&jerr];
+        if ([parsed isKindOfClass:[NSMutableArray class]]) location.drivingEvents = parsed;
+        else if ([parsed isKindOfClass:[NSArray class]]) location.drivingEvents = [parsed mutableCopy];
+    }
+    if (![rs columnIndexIsNull:13]) location.batteryLevel = @([rs intForColumnIndex:13]);
+    if (![rs columnIndexIsNull:14]) location.isCharging = @([rs intForColumnIndex:14] == 1);
     return location;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josuelmm/cordova-background-geolocation",
-  "version": "4.2.2",
+  "version": "4.5.1",
   "description": "Cordova Background Geolocation (fork actualizado)",
   "main": "./www/BackgroundGeolocation.js",
   "types": "./www/BackgroundGeolocation.d.ts",
@@ -104,6 +104,41 @@
         "cordova": ">=10.0.0",
         "cordova-android": ">=12.0.0",
         "cordova-ios": ">=6.2.0"
+      },
+      "4.2.3": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.2.4": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.3.0": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.4.0": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.4.1": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.5.0": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
+      },
+      "4.5.1": {
+        "cordova": ">=10.0.0",
+        "cordova-android": ">=12.0.0",
+        "cordova-ios": ">=6.2.0"
       }
     }
   },

package/plugin.xml

@@ -2,7 +2,7 @@
 <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
     xmlns:android="http://schemas.android.com/apk/res/android"
     id="cordova-background-geolocation"
-    version="4.2.2">
+    version="4.5.1">
     <name>cordova-background-geolocation</name>
     <description>Cordova Background Geolocation Plugin</description>
     <license>Apache-2.0</license>
@@ -59,6 +59,7 @@
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/BackgroundActivity.java" target-dir="src/com/marianhello/bgloc/data" />
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/BackgroundLocation.java" target-dir="src/com/marianhello/bgloc/data" />
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/ConfigurationDAO.java" target-dir="src/com/marianhello/bgloc/data" />
+        <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/ConfigJsonMapper.java" target-dir="src/com/marianhello/bgloc/data" />
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/DAOFactory.java" target-dir="src/com/marianhello/bgloc/data" />
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/HashMapLocationTemplate.java" target-dir="src/com/marianhello/bgloc/data" />
         <source-file src="android/common/src/main/java/com/marianhello/bgloc/data/LocationDAO.java" target-dir="src/com/marianhello/bgloc/data" />
@@ -196,7 +197,7 @@
             <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
             <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
             <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
-            <uses-permission android:name="android.hardware.location" />
+            <uses-feature android:name="android.hardware.location" android:required="false" />
         </config-file>
         <config-file target="res/xml/config.xml" parent="/*">
             <feature name="BackgroundGeolocation">

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,52 @@ 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.0 Phase 6 — Driver insights configuration. Enables a GPS-based state machine
    * that emits `moving`, `stopped`, `tripStart`, `tripEnd`, `speeding` and
@@ -643,6 +689,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 +1043,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 +1349,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) {
    *