@josuelmm/cordova-background-geolocation 4.2.3 → 4.5.2

package/android/CDVBackgroundGeolocation/src/main/java/com/tenforwardconsulting/bgloc/cordova/BackgroundGeolocationPlugin.java

@@ -14,6 +14,7 @@ package com.tenforwardconsulting.bgloc.cordova;
 import android.app.Activity;
 import android.app.Application;
 import android.content.Context;
+import android.os.Build;
 
 import com.marianhello.bgloc.BackgroundGeolocationFacade;
 import com.marianhello.bgloc.Config;
@@ -87,9 +88,15 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
     public static final String ACTION_OPEN_AUTOSTART_SETTINGS       = "openAutoStartSettings";
     public static final String ACTION_GET_MANUFACTURER_HELP         = "getManufacturerHelp";
     public static final String ACTION_TRIGGER_SOS                   = "triggerSOS";
+    // v4.5: runtime permission helpers — opt-in. The app drives the flow; the plugin
+    // simply asks the OS dialog (or returns the current state on iOS where Apple does
+    // not surface separate runtime gates for background location / activity recognition).
+    public static final String ACTION_REQUEST_BACKGROUND_PERMISSION   = "requestBackgroundLocationPermission";
+    public static final String ACTION_REQUEST_ACTIVITY_PERMISSION     = "requestActivityRecognitionPermission";
+    public static final String ACTION_REQUEST_NOTIFICATION_PERMISSION = "requestNotificationPermission";
 
     /** Plugin version; keep in sync with plugin.xml. */
-    public static final String PLUGIN_VERSION = "4.2.3";
+    public static final String PLUGIN_VERSION = "4.5.2";
 
     private BackgroundGeolocationFacade facade;
 
@@ -507,11 +514,64 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
                 callbackContext.sendPluginResult(ErrorPluginResult.from("triggerSOS failed", e, PluginException.SERVICE_ERROR));
             }
             return true;
+        } else if (ACTION_REQUEST_BACKGROUND_PERMISSION.equals(action)) {
+            // Android 10+ (API 29+). Returns {granted: bool}.
+            return requestPermissionAction(callbackContext,
+                    Build.VERSION.SDK_INT >= 29 ? android.Manifest.permission.ACCESS_BACKGROUND_LOCATION : android.Manifest.permission.ACCESS_FINE_LOCATION);
+        } else if (ACTION_REQUEST_ACTIVITY_PERMISSION.equals(action)) {
+            // Android 10+ (API 29+) needs runtime grant for activity recognition.
+            return requestPermissionAction(callbackContext,
+                    Build.VERSION.SDK_INT >= 29 ? "android.permission.ACTIVITY_RECOGNITION" : null);
+        } else if (ACTION_REQUEST_NOTIFICATION_PERMISSION.equals(action)) {
+            // Android 13+ (API 33+) requires POST_NOTIFICATIONS at runtime.
+            return requestPermissionAction(callbackContext,
+                    Build.VERSION.SDK_INT >= 33 ? "android.permission.POST_NOTIFICATIONS" : null);
         }
 
         return false;
     }
 
+    /** v4.5: shared helper — request a single runtime permission via PermissionManager.
+     *  Returns {granted: true} if already granted (or unsupported on this OS version).
+     *  Returns {granted: false, denied: [name]} if user denies.
+     */
+    private boolean requestPermissionAction(final CallbackContext cb, final String permission) {
+        if (permission == null) {
+            // OS version where this permission does not exist: act as already granted.
+            try {
+                JSONObject r = new JSONObject();
+                r.put("granted", true);
+                r.put("notRequired", true);
+                cb.success(r);
+            } catch (JSONException e) { cb.success(); }
+            return true;
+        }
+        Context ctx = cordova.getActivity().getApplicationContext();
+        if (hasPermission(ctx, permission)) {
+            try { JSONObject r = new JSONObject(); r.put("granted", true); cb.success(r); }
+            catch (JSONException e) { cb.success(); }
+            return true;
+        }
+        com.intentfilter.androidpermissions.PermissionManager pm =
+                com.intentfilter.androidpermissions.PermissionManager.getInstance(ctx);
+        pm.checkPermissions(java.util.Arrays.asList(permission),
+                new com.intentfilter.androidpermissions.PermissionManager.PermissionRequestListener() {
+            @Override public void onPermissionGranted() {
+                try { JSONObject r = new JSONObject(); r.put("granted", true); cb.success(r); }
+                catch (JSONException e) { cb.success(); }
+            }
+            @Override public void onPermissionDenied(com.intentfilter.androidpermissions.models.DeniedPermissions deniedPermissions) {
+                try {
+                    JSONObject r = new JSONObject();
+                    r.put("granted", false);
+                    r.put("denied", new org.json.JSONArray().put(permission));
+                    cb.success(r);
+                } catch (JSONException e) { cb.success(); }
+            }
+        });
+        return true;
+    }
+
     /** v3.5 Phase 4: extended diagnostics. */
     private JSONObject buildDiagnostics() throws JSONException {
         JSONObject d = new JSONObject();

package/android/common/src/main/AndroidManifest.xml

@@ -58,7 +58,7 @@
         <uses-library android:name="org.apache.http.legacy" android:required="true" />
     </application>
 
-    <uses-permission android:name="android.hardware.location" />
+    <uses-feature android:name="android.hardware.location" android:required="false" />
     <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

package/android/common/src/main/java/com/marianhello/bgloc/BootCompletedReceiver.java

@@ -17,6 +17,8 @@ import android.content.pm.PackageManager;
 import android.os.Build;
 import android.util.Log;
 
+import androidx.core.content.ContextCompat;
+
 import com.marianhello.bgloc.data.ConfigurationDAO;
 import com.marianhello.bgloc.data.DAOFactory;
 import com.marianhello.bgloc.service.LocationServiceImpl;
@@ -32,6 +34,20 @@ public class BootCompletedReceiver extends BroadcastReceiver {
     @Override
      public void onReceive(Context context, Intent intent) {
         String action = intent != null ? intent.getAction() : null;
+
+        // v4.5.2 — hardening: ignore arbitrary broadcasts directed at this
+        // receiver. Without this, any explicit intent (e.g. a malicious app
+        // targeting our package) could trigger the service auto-start path.
+        // Accept only the canonical boot/package-replaced actions plus the
+        // OEM-specific quick-boot variants used by HTC and Samsung.
+        if (!Intent.ACTION_BOOT_COMPLETED.equals(action)
+                && !"android.intent.action.QUICKBOOT_POWERON".equals(action)
+                && !"com.htc.intent.action.QUICKBOOT_POWERON".equals(action)
+                && !Intent.ACTION_MY_PACKAGE_REPLACED.equals(action)) {
+            Log.w(TAG, "Ignoring unsupported broadcast: " + action);
+            return;
+        }
+
         Log.d(TAG, "Received boot/replace broadcast: " + action);
         ConfigurationDAO dao = DAOFactory.createConfigurationDAO(context);
         Config config = null;
@@ -76,11 +92,12 @@ public class BootCompletedReceiver extends BroadcastReceiver {
      }
 
     private static boolean hasLocationPermission(Context context) {
-        return context.checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
-                || context.checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
+        // v4.5.1 — ContextCompat handles API < 23 (always granted at install time).
+        return ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
+                || ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
     }
 
     private static boolean hasBackgroundLocationPermission(Context context) {
-        return context.checkSelfPermission(Manifest.permission.ACCESS_BACKGROUND_LOCATION) == PackageManager.PERMISSION_GRANTED;
+        return ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_BACKGROUND_LOCATION) == PackageManager.PERMISSION_GRANTED;
     }
 }

package/android/common/src/main/java/com/marianhello/bgloc/Config.java

@@ -83,6 +83,22 @@ public class Config implements Parcelable
     private String mockLocationPolicy;    // allow | flag | drop (default allow)
     // v4.0 (Phase 6): driver insights
     private DrivingEventsOptions drivingEvents;
+    // v4.4: include device battery in every location payload (default true).
+    private Boolean includeBattery;
+    // v4.5.1: battery-saving knobs.
+    /** WakeLock policy: 'none' | 'posting' | 'always'. Default 'posting'. */
+    private String wakeLockMode;
+    /** ms before declaring stationary. DistanceFilterLocationProvider default 5*60_000. */
+    private Integer stationaryTimeout;
+    /** Lazy poll interval while stationary (ms). Default 3*60_000. */
+    private Integer stationaryPollInterval;
+    /** Aggressive poll interval while stationary (ms). Default 60_000. */
+    private Integer stationaryPollFast;
+    // v4.5.2 — provider hardening
+    /** 0-100. Activity-recognition transitions below this confidence are ignored. Default 50. */
+    private Integer activityConfidenceThreshold;
+    /** Discard fixes whose `accuracy` (m) is worse than this. `null` (default) disables the filter. */
+    private Float maxAcceptedAccuracy;
 
     /** v4.0 Phase 6 + v4.1: driver-insights configuration. Plain holder; no Parcelable to keep this class diff small. */
     public static class DrivingEventsOptions {
@@ -149,6 +165,13 @@ public class Config implements Parcelable
         this.queryParams = CloneHelper.deepCopy(config.queryParams);
         this.heartbeatInterval = config.heartbeatInterval;
         this.mockLocationPolicy = config.mockLocationPolicy;
+        this.includeBattery = config.includeBattery;
+        this.wakeLockMode = config.wakeLockMode;
+        this.stationaryTimeout = config.stationaryTimeout;
+        this.stationaryPollInterval = config.stationaryPollInterval;
+        this.stationaryPollFast = config.stationaryPollFast;
+        this.activityConfidenceThreshold = config.activityConfidenceThreshold;
+        this.maxAcceptedAccuracy = config.maxAcceptedAccuracy;
         if (config.drivingEvents != null) {
             DrivingEventsOptions de = new DrivingEventsOptions();
             de.enabled            = config.drivingEvents.enabled;
@@ -251,7 +274,19 @@ public class Config implements Parcelable
             de.phoneUsageCooldownMs = dePhoneUsageCooldown;
             this.drivingEvents = de;
         }
-        Bundle bundle = in.readBundle();
+        // v4.4: includeBattery
+        setIncludeBattery((Boolean) in.readValue(null));
+        // v4.5.1: battery-saving knobs
+        setWakeLockMode(in.readString());
+        setStationaryTimeout((Integer) in.readValue(null));
+        setStationaryPollInterval((Integer) in.readValue(null));
+        setStationaryPollFast((Integer) in.readValue(null));
+        // v4.5.2 provider hardening
+        setActivityConfidenceThreshold((Integer) in.readValue(null));
+        setMaxAcceptedAccuracy((Float) in.readValue(null));
+        // v4.5.1 — pass the plugin's classloader so getSerializable() can deserialize
+        // LocationTemplate / HashMap subclasses across IPC boundaries (e.g. SyncService :sync process).
+        Bundle bundle = in.readBundle(Config.class.getClassLoader());
         setHttpHeaders((HashMap<String, String>) bundle.getSerializable("httpHeaders"));
         setQueryParams((HashMap<String, String>) bundle.getSerializable("queryParams"));
         setTemplate((LocationTemplate) bundle.getSerializable(AbstractLocationTemplate.BUNDLE_KEY));
@@ -298,6 +333,13 @@ public class Config implements Parcelable
         config.queryParams = null;
         config.heartbeatInterval = 0;
         config.mockLocationPolicy = "allow";
+        config.includeBattery = true; // v4.4: on by default
+        config.wakeLockMode = "posting";  // v4.5.1: hold wake lock only while posting/syncing
+        config.stationaryTimeout = 5 * 60 * 1000;
+        config.stationaryPollInterval = 3 * 60 * 1000;
+        config.stationaryPollFast = 60 * 1000;
+        config.activityConfidenceThreshold = 50; // v4.5.2: ignore <50% confidence transitions
+        config.maxAcceptedAccuracy = null;       // v4.5.2: off by default (no JS regression)
 
         return config;
     }
@@ -365,6 +407,16 @@ public class Config implements Parcelable
         out.writeLong  (de != null ? de.phoneUsageWindowMs    : 4_000L);
         out.writeLong  (de != null ? de.phoneUsageCooldownMs  : 60_000L);
         out.writeInt   (de != null ? 1 : 0);
+        // v4.4: includeBattery
+        out.writeValue(getIncludeBattery());
+        // v4.5.1
+        out.writeString(getWakeLockMode());
+        out.writeValue(getStationaryTimeout());
+        out.writeValue(getStationaryPollInterval());
+        out.writeValue(getStationaryPollFast());
+        // v4.5.2
+        out.writeValue(getActivityConfidenceThreshold());
+        out.writeValue(getMaxAcceptedAccuracy());
         Bundle bundle = new Bundle();
         bundle.putSerializable("httpHeaders", getHttpHeaders());
         bundle.putSerializable("queryParams", getQueryParams());
@@ -762,6 +814,28 @@ public class Config implements Parcelable
         this.enableWatchdog = enableWatchdog;
     }
 
+    @Nullable
+    public Boolean getIncludeBattery() {
+        return includeBattery;
+    }
+
+    public void setIncludeBattery(Boolean includeBattery) {
+        this.includeBattery = includeBattery;
+    }
+
+    @Nullable public String getWakeLockMode() { return wakeLockMode; }
+    public void setWakeLockMode(String mode) { this.wakeLockMode = mode; }
+    @Nullable public Integer getStationaryTimeout() { return stationaryTimeout; }
+    public void setStationaryTimeout(Integer ms) { this.stationaryTimeout = ms; }
+    @Nullable public Integer getStationaryPollInterval() { return stationaryPollInterval; }
+    public void setStationaryPollInterval(Integer ms) { this.stationaryPollInterval = ms; }
+    @Nullable public Integer getStationaryPollFast() { return stationaryPollFast; }
+    public void setStationaryPollFast(Integer ms) { this.stationaryPollFast = ms; }
+    @Nullable public Integer getActivityConfidenceThreshold() { return activityConfidenceThreshold; }
+    public void setActivityConfidenceThreshold(Integer v) { this.activityConfidenceThreshold = v; }
+    @Nullable public Float getMaxAcceptedAccuracy() { return maxAcceptedAccuracy; }
+    public void setMaxAcceptedAccuracy(Float v) { this.maxAcceptedAccuracy = v; }
+
     public boolean hasShowTime() {
         return showTime != null;
     }
@@ -1056,6 +1130,18 @@ public class Config implements Parcelable
         if (config2.drivingEvents != null) {
             merger.setDrivingEvents(config2.drivingEvents);
         }
+        // v4.4.1 — was missing: configure({includeBattery: false}) was being ignored.
+        if (config2.includeBattery != null) {
+            merger.setIncludeBattery(config2.getIncludeBattery());
+        }
+        // v4.5.1 — battery-saving knobs.
+        if (config2.wakeLockMode != null) merger.setWakeLockMode(config2.wakeLockMode);
+        if (config2.stationaryTimeout != null) merger.setStationaryTimeout(config2.stationaryTimeout);
+        if (config2.stationaryPollInterval != null) merger.setStationaryPollInterval(config2.stationaryPollInterval);
+        if (config2.stationaryPollFast != null) merger.setStationaryPollFast(config2.stationaryPollFast);
+        // v4.5.2
+        if (config2.activityConfidenceThreshold != null) merger.setActivityConfidenceThreshold(config2.activityConfidenceThreshold);
+        if (config2.maxAcceptedAccuracy != null) merger.setMaxAcceptedAccuracy(config2.maxAcceptedAccuracy);
 
         return merger;
     }

package/android/common/src/main/java/com/marianhello/bgloc/data/BackgroundLocation.java

@@ -11,6 +11,7 @@ import androidx.core.util.TimeUtils;
 
 import com.marianhello.bgloc.data.sqlite.SQLiteLocationContract.LocationEntry;
 
+import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
@@ -43,6 +44,20 @@ public class BackgroundLocation implements Parcelable {
     private int status = POST_PENDING;
     private Bundle extras = null;
 
+    /**
+     * v4.3 — Driving events anexados al fix actual.
+     * v4.5: ahora se persiste en SQLite (events_json TEXT) y se propaga vía Parcel para
+     * sobrevivir a la cola de sync. Si el POST en real-time falla, los eventos llegan al
+     * backend cuando la location se sincroniza más tarde.
+     */
+    private JSONArray drivingEvents;
+
+    /** v4.4 — Device battery percentage (0-100) at the time of this fix, or null if unknown
+     *  or {@code includeBattery} is disabled. v4.5: persisted in SQLite + Parcel. */
+    private Integer batteryLevel;
+    /** v4.4 — Whether the device is charging at the time of this fix. v4.5: persisted. */
+    private Boolean isCharging;
+
     private static final long TWO_MINUTES_IN_NANOS = 1000000000L * 60 * 2;
 
     public BackgroundLocation() {}
@@ -106,6 +121,12 @@ public class BackgroundLocation implements Parcelable {
         mockFlags = l.mockFlags;
         status = l.status;
         extras = (l.extras == null) ? null : new Bundle(l.extras);
+        // v4.5: copy v4.3+ persisted fields
+        if (l.drivingEvents != null) {
+            try { drivingEvents = new JSONArray(l.drivingEvents.toString()); } catch (JSONException ignored) {}
+        }
+        batteryLevel = l.batteryLevel;
+        isCharging = l.isCharging;
     }
 
     private static BackgroundLocation fromParcel(Parcel in) {
@@ -134,6 +155,13 @@ public class BackgroundLocation implements Parcelable {
         l.mockFlags = in.readInt();
         l.status = in.readInt();
         l.extras = in.readBundle();
+        // v4.5: read driving events / battery / charging
+        String evJson = in.readString();
+        if (evJson != null) {
+            try { l.drivingEvents = new JSONArray(evJson); } catch (JSONException ignored) {}
+        }
+        l.batteryLevel = (Integer) in.readValue(null);
+        l.isCharging = (Boolean) in.readValue(null);
 
         return l;
     }
@@ -205,6 +233,18 @@ public class BackgroundLocation implements Parcelable {
         l.setStatus(c.getInt(c.getColumnIndex(LocationEntry.COLUMN_NAME_STATUS)));
         l.setLocationId(c.getLong(c.getColumnIndex(LocationEntry._ID)));
         l.setMockFlags(c.getInt((c.getColumnIndex(LocationEntry.COLUMN_NAME_MOCK_FLAGS))));
+        // v4.5: events / battery / charging — guarded for DBs that may have NULL after migration.
+        int idxEv = c.getColumnIndex(LocationEntry.COLUMN_NAME_EVENTS_JSON);
+        if (idxEv >= 0 && !c.isNull(idxEv)) {
+            String s = c.getString(idxEv);
+            if (s != null && !s.isEmpty()) {
+                try { l.drivingEvents = new JSONArray(s); } catch (JSONException ignored) {}
+            }
+        }
+        int idxBat = c.getColumnIndex(LocationEntry.COLUMN_NAME_BATTERY_LEVEL);
+        if (idxBat >= 0 && !c.isNull(idxBat)) l.batteryLevel = c.getInt(idxBat);
+        int idxChg = c.getColumnIndex(LocationEntry.COLUMN_NAME_IS_CHARGING);
+        if (idxChg >= 0 && !c.isNull(idxChg)) l.isCharging = (c.getInt(idxChg) == 1);
 
         return l;
     }
@@ -239,6 +279,10 @@ public class BackgroundLocation implements Parcelable {
         dest.writeInt(mockFlags);
         dest.writeInt(status);
         dest.writeBundle(extras);
+        // v4.5: persist driving events / battery / charging through Parcel.
+        dest.writeString(drivingEvents != null ? drivingEvents.toString() : null);
+        dest.writeValue(batteryLevel);
+        dest.writeValue(isCharging);
     }
 
     public static final Parcelable.Creator<BackgroundLocation> CREATOR
@@ -899,10 +943,37 @@ public class BackgroundLocation implements Parcelable {
         if (hasRadius) json.put("radius", radius);
         if (hasIsFromMockProvider()) json.put("isFromMockProvider", isFromMockProvider());
         if (hasMockLocationsEnabled()) json.put("mockLocationsEnabled", areMockLocationsEnabled());
+        // v4.3: driving events anexados a este fix (si los hay).
+        if (drivingEvents != null && drivingEvents.length() > 0) {
+            json.put("events", drivingEvents);
+        }
+        // v4.4: device battery snapshot.
+        if (batteryLevel != null) json.put("battery", batteryLevel);
+        if (isCharging != null) json.put("isCharging", isCharging);
 
         return json;
   	}
 
+    // v4.3 — driving event helpers
+    /** Append a driving event to this location. The event survives only until the next
+     *  serialization in real-time POST. NOT persisted in SQLite. */
+    public void addDrivingEvent(JSONObject event) {
+        if (event == null) return;
+        if (drivingEvents == null) drivingEvents = new JSONArray();
+        drivingEvents.put(event);
+    }
+    public JSONArray getDrivingEvents() { return drivingEvents; }
+    public boolean hasDrivingEvents() { return drivingEvents != null && drivingEvents.length() > 0; }
+    public void clearDrivingEvents() { drivingEvents = null; }
+    /** v4.5: bulk setter used by SQLite hydration to restore the persisted events array. */
+    public void setDrivingEvents(JSONArray events) { this.drivingEvents = events; }
+
+    // v4.4 — battery helpers
+    public void setBatteryLevel(Integer level) { this.batteryLevel = level; }
+    public Integer getBatteryLevel() { return batteryLevel; }
+    public void setCharging(Boolean charging) { this.isCharging = charging; }
+    public Boolean isCharging() { return isCharging; }
+
     /**
      * Returns location as JSON object containing location id
      * Note: Location id is not unique and is usually being recycled when
@@ -942,6 +1013,18 @@ public class BackgroundLocation implements Parcelable {
         values.put(LocationEntry.COLUMN_NAME_STATUS, status);
         values.put(LocationEntry.COLUMN_NAME_BATCH_START_MILLIS, batchStartMillis);
         values.put(LocationEntry.COLUMN_NAME_MOCK_FLAGS, mockFlags);
+        // v4.5.1 — always write these columns (with NULL when absent) so that recycled rows
+        // in ContentProviderLocationDAO's max-rows UPDATE path do not inherit stale events,
+        // battery or charging state from the location previously stored at that _id.
+        if (drivingEvents != null && drivingEvents.length() > 0) {
+            values.put(LocationEntry.COLUMN_NAME_EVENTS_JSON, drivingEvents.toString());
+        } else {
+            values.putNull(LocationEntry.COLUMN_NAME_EVENTS_JSON);
+        }
+        if (batteryLevel != null) values.put(LocationEntry.COLUMN_NAME_BATTERY_LEVEL, batteryLevel);
+        else values.putNull(LocationEntry.COLUMN_NAME_BATTERY_LEVEL);
+        if (isCharging != null) values.put(LocationEntry.COLUMN_NAME_IS_CHARGING, isCharging ? 1 : 0);
+        else values.putNull(LocationEntry.COLUMN_NAME_IS_CHARGING);
         return values;
     }
 
@@ -988,6 +1071,17 @@ public class BackgroundLocation implements Parcelable {
         if ("@mockLocationsEnabled".equals(key)) {
             return hasMockLocationsEnabled() ? areMockLocationsEnabled() : JSONObject.NULL;
         }
+        // v4.3 — driving events array (only present if events were attached during this fix).
+        if ("@events".equals(key)) {
+            return drivingEvents != null ? drivingEvents : JSONObject.NULL;
+        }
+        // v4.4 — battery snapshot
+        if ("@battery".equals(key)) {
+            return batteryLevel != null ? batteryLevel : JSONObject.NULL;
+        }
+        if ("@isCharging".equals(key)) {
+            return isCharging != null ? isCharging : JSONObject.NULL;
+        }
 
         return null;
     }

package/android/common/src/main/java/com/marianhello/bgloc/data/ConfigJsonMapper.java

@@ -0,0 +1,211 @@
+package com.marianhello.bgloc.data;
+
+import com.marianhello.bgloc.Config;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.util.HashMap;
+import java.util.Iterator;
+
+/**
+ * v4.4.1 — JSON serializer/deserializer for the full {@link Config} state.
+ *
+ * Lives in {@code common} so both the SQLite DAO (also common) and the Cordova
+ * {@code ConfigMapper} (cordova) can reuse it without creating a common→cordova
+ * dependency. Used to persist a single {@code config_json} TEXT column instead of
+ * adding one schema column per new field on every release.
+ *
+ * Round-trip: every JS-configurable key the plugin understands is preserved.
+ * Anything not present in the input JSON keeps the {@link Config} default.
+ */
+public final class ConfigJsonMapper {
+
+    private ConfigJsonMapper() {}
+
+    /** Serialize the current Config state to a JSONObject suitable for storage.
+     *  String fields use {@link JSONObject#NULL} when the user explicitly cleared them
+     *  (i.e. equals {@link Config#NullString}) so the sentinel survives the round-trip. */
+    public static JSONObject toJSONObject(Config c) throws JSONException {
+        JSONObject j = new JSONObject();
+        if (c == null) return j;
+        j.put("stationaryRadius", c.getStationaryRadius());
+        j.put("distanceFilter", c.getDistanceFilter());
+        j.put("desiredAccuracy", c.getDesiredAccuracy());
+        j.put("debug", c.isDebugging());
+        j.put("notificationTitle", nullable(c.getNotificationTitle()));
+        j.put("notificationText", nullable(c.getNotificationText()));
+        j.put("notificationSyncTitle", nullable(c.getNotificationSyncTitle()));
+        j.put("notificationSyncText", nullable(c.getNotificationSyncText()));
+        j.put("notificationSyncCompletedText", nullable(c.getNotificationSyncCompletedText()));
+        j.put("notificationSyncFailedText", nullable(c.getNotificationSyncFailedText()));
+        j.put("notificationIconLarge", nullable(c.getLargeNotificationIcon()));
+        j.put("notificationIconSmall", nullable(c.getSmallNotificationIcon()));
+        j.put("notificationIconColor", nullable(c.getNotificationIconColor()));
+        j.put("locationProvider", c.getLocationProvider());
+        j.put("interval", c.getInterval());
+        j.put("fastestInterval", c.getFastestInterval());
+        j.put("activitiesInterval", c.getActivitiesInterval());
+        j.put("stopOnTerminate", c.getStopOnTerminate());
+        j.put("startOnBoot", c.getStartOnBoot());
+        j.put("startForeground", c.getStartForeground());
+        j.put("notificationsEnabled", c.getNotificationsEnabled());
+        j.put("stopOnStillActivity", c.getStopOnStillActivity());
+        j.put("url", nullable(c.getUrl()));
+        j.put("syncUrl", nullable(c.getSyncUrl()));
+        j.put("syncThreshold", c.getSyncThreshold());
+        j.put("syncEnabled", c.getSyncEnabled());
+        j.put("maxLocations", c.getMaxLocations());
+        j.put("enableWatchdog", c.getEnableWatchdog());
+        j.put("showTime", c.getShowTime());
+        j.put("showDistance", c.getShowDistance());
+        j.put("httpMethod", c.getHttpMethod());
+        j.put("syncHttpMethod", c.getSyncHttpMethod());
+        j.put("httpMode", c.getHttpMode());
+        j.put("syncMode", c.getSyncMode());
+        j.put("heartbeatInterval", c.getHeartbeatInterval());
+        j.put("mockLocationPolicy", c.getMockLocationPolicy());
+        j.put("includeBattery", c.getIncludeBattery());
+        // v4.5.1: battery knobs
+        j.put("wakeLockMode", c.getWakeLockMode());
+        j.put("stationaryTimeout", c.getStationaryTimeout());
+        j.put("stationaryPollInterval", c.getStationaryPollInterval());
+        j.put("stationaryPollFast", c.getStationaryPollFast());
+        // v4.5.2: provider hardening knobs
+        j.put("activityConfidenceThreshold", c.getActivityConfidenceThreshold());
+        j.put("maxAcceptedAccuracy", c.getMaxAcceptedAccuracy());
+
+        if (c.getHttpHeaders() != null) {
+            j.put("httpHeaders", new JSONObject(c.getHttpHeaders()));
+        }
+        if (c.getQueryParams() != null) {
+            j.put("queryParams", new JSONObject(c.getQueryParams()));
+        }
+
+        Config.DrivingEventsOptions de = c.getDrivingEvents();
+        if (de != null) {
+            JSONObject deJson = new JSONObject();
+            deJson.put("enabled", de.enabled);
+            deJson.put("speedLimit", de.speedLimitKmh);
+            deJson.put("minMovingSpeed", de.minMovingSpeedMps);
+            deJson.put("stoppedDuration", de.stoppedDurationMs);
+            deJson.put("minTripSpeed", de.minTripSpeedMps);
+            deJson.put("minTripDuration", de.minTripDurationMs);
+            deJson.put("hardBrakeMps2", de.hardBrakeMps2);
+            deJson.put("rapidAccelMps2", de.rapidAccelMps2);
+            deJson.put("sharpTurnDegPerSec", de.sharpTurnDegPerSec);
+            deJson.put("crashImpactKmh", de.crashImpactKmh);
+            deJson.put("crashWindowMs", de.crashWindowMs);
+            deJson.put("sensorFusion", de.sensorFusion);
+            deJson.put("crashImpactG", de.crashImpactG);
+            deJson.put("sensorCrashCooldownMs", de.sensorCrashCooldownMs);
+            deJson.put("phoneUsageWindowMs", de.phoneUsageWindowMs);
+            deJson.put("phoneUsageCooldownMs", de.phoneUsageCooldownMs);
+            j.put("drivingEvents", deJson);
+        }
+        return j;
+    }
+
+    /** Deserialize a previously serialized config JSON. Missing keys are skipped (defaults preserved). */
+    public static Config fromJSONObject(JSONObject j) throws JSONException {
+        Config c = Config.getDefault();
+        if (j == null) return c;
+        if (j.has("stationaryRadius")) c.setStationaryRadius((float) j.getDouble("stationaryRadius"));
+        if (j.has("distanceFilter")) c.setDistanceFilter(j.getInt("distanceFilter"));
+        if (j.has("desiredAccuracy")) c.setDesiredAccuracy(j.getInt("desiredAccuracy"));
+        if (j.has("debug")) c.setDebugging(j.getBoolean("debug"));
+        if (j.has("notificationTitle")) c.setNotificationTitle(readNullable(j, "notificationTitle"));
+        if (j.has("notificationText")) c.setNotificationText(readNullable(j, "notificationText"));
+        if (j.has("notificationSyncTitle")) c.setNotificationSyncTitle(readNullable(j, "notificationSyncTitle"));
+        if (j.has("notificationSyncText")) c.setNotificationSyncText(readNullable(j, "notificationSyncText"));
+        if (j.has("notificationSyncCompletedText")) c.setNotificationSyncCompletedText(readNullable(j, "notificationSyncCompletedText"));
+        if (j.has("notificationSyncFailedText")) c.setNotificationSyncFailedText(readNullable(j, "notificationSyncFailedText"));
+        if (j.has("notificationIconLarge")) c.setLargeNotificationIcon(readNullable(j, "notificationIconLarge"));
+        if (j.has("notificationIconSmall")) c.setSmallNotificationIcon(readNullable(j, "notificationIconSmall"));
+        if (j.has("notificationIconColor")) c.setNotificationIconColor(readNullable(j, "notificationIconColor"));
+        if (j.has("locationProvider")) c.setLocationProvider(j.getInt("locationProvider"));
+        if (j.has("interval")) c.setInterval(j.getInt("interval"));
+        if (j.has("fastestInterval")) c.setFastestInterval(j.getInt("fastestInterval"));
+        if (j.has("activitiesInterval")) c.setActivitiesInterval(j.getInt("activitiesInterval"));
+        if (j.has("stopOnTerminate")) c.setStopOnTerminate(j.getBoolean("stopOnTerminate"));
+        if (j.has("startOnBoot")) c.setStartOnBoot(j.getBoolean("startOnBoot"));
+        if (j.has("startForeground")) c.setStartForeground(j.getBoolean("startForeground"));
+        if (j.has("notificationsEnabled")) c.setNotificationsEnabled(j.getBoolean("notificationsEnabled"));
+        if (j.has("stopOnStillActivity")) c.setStopOnStillActivity(j.getBoolean("stopOnStillActivity"));
+        if (j.has("url")) c.setUrl(readNullable(j, "url"));
+        if (j.has("syncUrl")) c.setSyncUrl(readNullable(j, "syncUrl"));
+        if (j.has("syncThreshold")) c.setSyncThreshold(j.getInt("syncThreshold"));
+        if (j.has("syncEnabled")) c.setSyncEnabled(j.getBoolean("syncEnabled"));
+        if (j.has("maxLocations")) c.setMaxLocations(j.getInt("maxLocations"));
+        if (j.has("enableWatchdog")) c.setEnableWatchdog(j.getBoolean("enableWatchdog"));
+        if (j.has("showTime")) c.setShowTime(j.getBoolean("showTime"));
+        if (j.has("showDistance")) c.setShowDistance(j.getBoolean("showDistance"));
+        if (has(j, "httpMethod")) c.setHttpMethod(j.getString("httpMethod"));
+        if (has(j, "syncHttpMethod")) c.setSyncHttpMethod(j.getString("syncHttpMethod"));
+        if (has(j, "httpMode")) c.setHttpMode(j.getString("httpMode"));
+        if (has(j, "syncMode")) c.setSyncMode(j.getString("syncMode"));
+        if (j.has("heartbeatInterval")) c.setHeartbeatInterval(j.getInt("heartbeatInterval"));
+        if (has(j, "mockLocationPolicy")) c.setMockLocationPolicy(j.getString("mockLocationPolicy"));
+        if (j.has("includeBattery")) c.setIncludeBattery(j.getBoolean("includeBattery"));
+        // v4.5.1: battery knobs
+        if (has(j, "wakeLockMode"))  c.setWakeLockMode(j.getString("wakeLockMode"));
+        if (j.has("stationaryTimeout") && !j.isNull("stationaryTimeout")) c.setStationaryTimeout(j.getInt("stationaryTimeout"));
+        if (j.has("stationaryPollInterval") && !j.isNull("stationaryPollInterval")) c.setStationaryPollInterval(j.getInt("stationaryPollInterval"));
+        if (j.has("stationaryPollFast") && !j.isNull("stationaryPollFast")) c.setStationaryPollFast(j.getInt("stationaryPollFast"));
+        // v4.5.2
+        if (j.has("activityConfidenceThreshold") && !j.isNull("activityConfidenceThreshold")) c.setActivityConfidenceThreshold(j.getInt("activityConfidenceThreshold"));
+        if (j.has("maxAcceptedAccuracy") && !j.isNull("maxAcceptedAccuracy")) c.setMaxAcceptedAccuracy((float) j.getDouble("maxAcceptedAccuracy"));
+
+        if (has(j, "httpHeaders")) c.setHttpHeaders(jsonToHashMap(j.getJSONObject("httpHeaders")));
+        if (has(j, "queryParams")) c.setQueryParams(jsonToHashMap(j.getJSONObject("queryParams")));
+
+        if (has(j, "drivingEvents")) {
+            JSONObject de = j.getJSONObject("drivingEvents");
+            Config.DrivingEventsOptions o = new Config.DrivingEventsOptions();
+            if (de.has("enabled"))               o.enabled               = de.getBoolean("enabled");
+            if (de.has("speedLimit"))            o.speedLimitKmh         = de.getDouble("speedLimit");
+            if (de.has("minMovingSpeed"))        o.minMovingSpeedMps     = de.getDouble("minMovingSpeed");
+            if (de.has("stoppedDuration"))       o.stoppedDurationMs     = de.getLong("stoppedDuration");
+            if (de.has("minTripSpeed"))          o.minTripSpeedMps       = de.getDouble("minTripSpeed");
+            if (de.has("minTripDuration"))       o.minTripDurationMs     = de.getLong("minTripDuration");
+            if (de.has("hardBrakeMps2"))         o.hardBrakeMps2         = de.getDouble("hardBrakeMps2");
+            if (de.has("rapidAccelMps2"))        o.rapidAccelMps2        = de.getDouble("rapidAccelMps2");
+            if (de.has("sharpTurnDegPerSec"))    o.sharpTurnDegPerSec    = de.getDouble("sharpTurnDegPerSec");
+            if (de.has("crashImpactKmh"))        o.crashImpactKmh        = de.getDouble("crashImpactKmh");
+            if (de.has("crashWindowMs"))         o.crashWindowMs         = de.getLong("crashWindowMs");
+            if (de.has("sensorFusion"))          o.sensorFusion          = de.getBoolean("sensorFusion");
+            if (de.has("crashImpactG"))          o.crashImpactG          = de.getDouble("crashImpactG");
+            if (de.has("sensorCrashCooldownMs")) o.sensorCrashCooldownMs = de.getLong("sensorCrashCooldownMs");
+            if (de.has("phoneUsageWindowMs"))    o.phoneUsageWindowMs    = de.getLong("phoneUsageWindowMs");
+            if (de.has("phoneUsageCooldownMs")) o.phoneUsageCooldownMs   = de.getLong("phoneUsageCooldownMs");
+            c.setDrivingEvents(o);
+        }
+        return c;
+    }
+
+    private static HashMap<String, String> jsonToHashMap(JSONObject obj) throws JSONException {
+        HashMap<String, String> map = new HashMap<>();
+        Iterator<String> keys = obj.keys();
+        while (keys.hasNext()) {
+            String k = keys.next();
+            map.put(k, String.valueOf(obj.get(k)));
+        }
+        return map;
+    }
+
+    private static boolean has(JSONObject j, String key) {
+        return j.has(key) && !j.isNull(key);
+    }
+
+    /** Map {@link Config#NullString} or null to JSONObject.NULL so the sentinel survives. */
+    private static Object nullable(String s) {
+        if (s == null || s == Config.NullString) return JSONObject.NULL;
+        return s;
+    }
+
+    /** Inverse of {@link #nullable(String)}. JSON null → {@link Config#NullString}. */
+    private static String readNullable(JSONObject j, String key) throws JSONException {
+        if (j.isNull(key)) return Config.NullString;
+        return j.getString(key);
+    }
+}