@josuelmm/capacitor-background-geolocation 1.0.0

package/android/src/main/java/com/marianhello/bgloc/driving/DrivingEventsDetector.java

@@ -0,0 +1,265 @@
+package com.marianhello.bgloc.driving;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+/**
+ * v4.0 Phase 6 — Driver insights state machine (GPS-only).
+ *
+ * Pure-Java helper, no Android imports. Hosted by {@code LocationServiceImpl}, which
+ * feeds it every received location and surfaces emitted events via the plugin
+ * {@code MSG_ON_*} broadcast pipeline.
+ *
+ * Heuristics:
+ *   moving   = speed > minMovingSpeed
+ *   stopped  = !moving for stoppedDuration ms
+ *   tripStart = stopped → moving with speed >= minTripSpeed sustained for minTripDuration ms
+ *   tripEnd  = moving → stopped (after a tripStart)
+ *   speeding = first crossing above speedLimit (km/h); rearms on drop below
+ *
+ * Sensor-fusion events (hardBrake / sharpTurn / possibleCrash) are intentionally NOT
+ * implemented in this class. They require linear acceleration + gyroscope sampling and
+ * are planned for v4.1 in a separate {@code SensorFusionDetector}.
+ */
+public class DrivingEventsDetector {
+
+    public interface Listener {
+        void onMoving(BackgroundLocation location);
+        void onStopped(BackgroundLocation location);
+        void onTripStart(BackgroundLocation location);
+        /** distance in meters, durationMs in milliseconds. */
+        void onTripEnd(BackgroundLocation location, double distance, long durationMs);
+        void onSpeeding(BackgroundLocation location, double speedKmh, double limitKmh);
+        void onProviderChange(String provider);
+        // v4.1 GPS-derived driving events
+        /** GPS-derived deceleration (m/s²). Negative number, more negative = harder brake. */
+        void onHardBrake(BackgroundLocation location, double decelMps2);
+        /** GPS-derived acceleration (m/s²). */
+        void onRapidAcceleration(BackgroundLocation location, double accelMps2);
+        /** Bearing change rate (deg/s). */
+        void onSharpTurn(BackgroundLocation location, double degPerSec);
+        /** Velocity drop in km/h within {@code crashWindowMs} while tripActive. */
+        void onPossibleCrash(BackgroundLocation location, double velocityDropKmh);
+    }
+
+    public static class Config {
+        public boolean enabled = false;
+        public double speedLimitKmh = 0;        // 0 disables speeding
+        public double minMovingSpeedMps = 1.0;  // ~3.6 km/h
+        public long stoppedDurationMs = 60_000;
+        public double minTripSpeedMps = 3.0;    // ~10.8 km/h
+        public long minTripDurationMs = 30_000;
+        // v4.1 GPS-derived driving events. 0 disables each one.
+        public double hardBrakeMps2 = 3.5;      // -m/s² threshold (positive value)
+        public double rapidAccelMps2 = 3.5;     // m/s² threshold
+        public double sharpTurnDegPerSec = 30;  // deg/sec, requires speed > 5 m/s
+        public double crashImpactKmh = 25;      // velocity drop within crashWindow
+        public long   crashWindowMs = 2_000;    // window to evaluate the velocity drop
+    }
+
+    private final Listener listener;
+    private Config cfg = new Config();
+
+    // State
+    private boolean isMoving = false;
+    private boolean tripActive = false;
+    private long tripStartedAt = 0;
+    private double tripDistanceMeters = 0;
+    private double tripStartLat, tripStartLon;
+    private boolean hasTripStartCoord = false;
+
+    private long aboveTripSpeedSince = 0;   // first sample with speed >= minTripSpeed
+    private long belowMovingSinceMs = 0;    // first sample with speed < minMovingSpeed
+
+    private boolean wasSpeeding = false;
+    private String lastProvider;
+
+    private double prevLat, prevLon;
+    private boolean hasPrev = false;
+
+    // v4.1 GPS-derived deltas
+    private double prevSpeedMps = 0.0;
+    private long   prevSpeedAt = 0L;
+    private double prevBearingDeg = 0.0;
+    private boolean hasPrevBearing = false;
+    private long   prevBearingAt = 0L;
+    /** Cooldown so we don't refire the same event on every fix in a sustained brake. */
+    private long lastHardBrakeAt = 0L, lastRapidAccelAt = 0L, lastSharpTurnAt = 0L, lastCrashAt = 0L;
+    private static final long DRIVING_EVENT_COOLDOWN_MS = 4_000L;
+
+    public DrivingEventsDetector(Listener listener) {
+        this.listener = listener;
+    }
+
+    public synchronized void setConfig(Config c) {
+        if (c != null) this.cfg = c;
+    }
+
+    /** Reset internal state. Called when service stops. */
+    public synchronized void reset() {
+        prevSpeedMps = 0.0;
+        prevSpeedAt = 0L;
+        prevBearingDeg = 0.0;
+        hasPrevBearing = false;
+        prevBearingAt = 0L;
+        lastHardBrakeAt = lastRapidAccelAt = lastSharpTurnAt = lastCrashAt = 0L;
+        isMoving = false;
+        tripActive = false;
+        tripStartedAt = 0;
+        tripDistanceMeters = 0;
+        hasTripStartCoord = false;
+        aboveTripSpeedSince = 0;
+        belowMovingSinceMs = 0;
+        wasSpeeding = false;
+        lastProvider = null;
+        hasPrev = false;
+    }
+
+    public synchronized void onLocation(BackgroundLocation loc) {
+        if (!cfg.enabled || loc == null) return;
+        long now = System.currentTimeMillis();
+        double speed = loc.hasSpeed() ? loc.getSpeed() : 0.0;
+
+        // Provider change
+        String provider = loc.getProvider();
+        if (provider != null && !provider.equals(lastProvider)) {
+            lastProvider = provider;
+            if (listener != null) listener.onProviderChange(provider);
+        }
+
+        // Distance accumulator (very simple: planar haversine approximation via
+        // Location.distanceBetween is not used here to keep this class platform-free;
+        // consumer can swap to BackgroundLocation.distanceTo in onTripEnd if desired).
+        double curLat = loc.getLatitude();
+        double curLon = loc.getLongitude();
+        if (hasPrev && tripActive) {
+            tripDistanceMeters += haversineMeters(prevLat, prevLon, curLat, curLon);
+        }
+        prevLat = curLat;
+        prevLon = curLon;
+        hasPrev = true;
+
+        // Moving / stopped state
+        boolean nowMoving = speed >= cfg.minMovingSpeedMps;
+        if (nowMoving) {
+            belowMovingSinceMs = 0;
+            if (!isMoving) {
+                isMoving = true;
+                if (listener != null) listener.onMoving(loc);
+            }
+            // Trip start arming
+            if (!tripActive) {
+                if (speed >= cfg.minTripSpeedMps) {
+                    if (aboveTripSpeedSince == 0) aboveTripSpeedSince = now;
+                    if (now - aboveTripSpeedSince >= cfg.minTripDurationMs) {
+                        tripActive = true;
+                        tripStartedAt = now;
+                        tripDistanceMeters = 0;
+                        tripStartLat = curLat;
+                        tripStartLon = curLon;
+                        hasTripStartCoord = true;
+                        if (listener != null) listener.onTripStart(loc);
+                    }
+                } else {
+                    aboveTripSpeedSince = 0;
+                }
+            }
+        } else {
+            aboveTripSpeedSince = 0;
+            if (belowMovingSinceMs == 0) belowMovingSinceMs = now;
+            if (isMoving && (now - belowMovingSinceMs) >= cfg.stoppedDurationMs) {
+                isMoving = false;
+                if (listener != null) listener.onStopped(loc);
+                if (tripActive) {
+                    long durMs = now - tripStartedAt;
+                    double dist = tripDistanceMeters;
+                    tripActive = false;
+                    if (listener != null) listener.onTripEnd(loc, dist, durMs);
+                }
+            }
+        }
+
+        // Speeding (km/h)
+        if (cfg.speedLimitKmh > 0) {
+            double kmh = speed * 3.6;
+            if (kmh > cfg.speedLimitKmh) {
+                if (!wasSpeeding) {
+                    wasSpeeding = true;
+                    if (listener != null) listener.onSpeeding(loc, kmh, cfg.speedLimitKmh);
+                }
+            } else {
+                // Rearm: emit again on next crossing.
+                wasSpeeding = false;
+            }
+        }
+
+        // v4.1 GPS-derived driving events (only meaningful during an active trip)
+        if (tripActive && prevSpeedAt > 0) {
+            long dtMs = now - prevSpeedAt;
+            if (dtMs > 0 && dtMs <= 5_000) {
+                double dt = dtMs / 1000.0;
+                double dv = speed - prevSpeedMps; // m/s
+                double accel = dv / dt;            // m/s²
+
+                if (cfg.hardBrakeMps2 > 0
+                        && accel <= -cfg.hardBrakeMps2
+                        && (now - lastHardBrakeAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastHardBrakeAt = now;
+                    if (listener != null) listener.onHardBrake(loc, accel);
+                }
+                if (cfg.rapidAccelMps2 > 0
+                        && accel >= cfg.rapidAccelMps2
+                        && (now - lastRapidAccelAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastRapidAccelAt = now;
+                    if (listener != null) listener.onRapidAcceleration(loc, accel);
+                }
+
+                // Possible crash: sustained velocity drop greater than crashImpactKmh in <= crashWindow.
+                if (cfg.crashImpactKmh > 0 && dtMs <= cfg.crashWindowMs) {
+                    double dropKmh = (prevSpeedMps - speed) * 3.6; // positive when slowing down
+                    if (dropKmh >= cfg.crashImpactKmh
+                            && speed < 1.5 // ended near stop
+                            && prevSpeedMps * 3.6 >= cfg.crashImpactKmh
+                            && (now - lastCrashAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                        lastCrashAt = now;
+                        if (listener != null) listener.onPossibleCrash(loc, dropKmh);
+                    }
+                }
+            }
+        }
+
+        // Sharp turn (bearing change rate) — requires meaningful speed to avoid GPS jitter.
+        if (cfg.sharpTurnDegPerSec > 0 && loc.hasBearing() && speed >= 5.0 && hasPrevBearing) {
+            long dtMs = now - prevBearingAt;
+            if (dtMs > 0 && dtMs <= 5_000) {
+                double bearing = loc.getBearing();
+                double diff = Math.abs(bearing - prevBearingDeg);
+                if (diff > 180) diff = 360 - diff;
+                double rate = diff * 1000.0 / dtMs;
+                if (rate >= cfg.sharpTurnDegPerSec
+                        && (now - lastSharpTurnAt) >= DRIVING_EVENT_COOLDOWN_MS) {
+                    lastSharpTurnAt = now;
+                    if (listener != null) listener.onSharpTurn(loc, rate);
+                }
+            }
+            prevBearingDeg = loc.getBearing();
+            prevBearingAt = now;
+        } else if (loc.hasBearing()) {
+            prevBearingDeg = loc.getBearing();
+            prevBearingAt = now;
+            hasPrevBearing = true;
+        }
+
+        prevSpeedMps = speed;
+        prevSpeedAt = now;
+    }
+
+    private static double haversineMeters(double lat1, double lon1, double lat2, double lon2) {
+        double R = 6371000.0;
+        double dLat = Math.toRadians(lat2 - lat1);
+        double dLon = Math.toRadians(lon2 - lon1);
+        double a = Math.sin(dLat/2) * Math.sin(dLat/2)
+                + Math.cos(Math.toRadians(lat1)) * Math.cos(Math.toRadians(lat2))
+                * Math.sin(dLon/2) * Math.sin(dLon/2);
+        return 2 * R * Math.asin(Math.sqrt(a));
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/headless/AbstractTaskRunner.java

@@ -0,0 +1,15 @@
+package com.marianhello.bgloc.headless;
+
+import android.content.Context;
+
+public abstract class AbstractTaskRunner implements TaskRunner {
+    protected Context mContext;
+
+    public AbstractTaskRunner() {}
+
+    public abstract void runTask(Task task);
+
+    public void setContext(Context context) {
+        mContext = context;
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/headless/ActivityTask.java

@@ -0,0 +1,48 @@
+package com.marianhello.bgloc.headless;
+
+import android.os.Bundle;
+
+import com.marianhello.bgloc.data.BackgroundActivity;
+
+import org.json.JSONException;
+
+public abstract class ActivityTask extends Task {
+    private BackgroundActivity mActivity;
+
+    public ActivityTask(BackgroundActivity activity) {
+        mActivity = activity;
+    }
+
+    @Override
+    public String getName() {
+        return "activity";
+    }
+
+    @Override
+    public Bundle getBundle() {
+        Bundle bundle = new Bundle();
+        Bundle params = new Bundle();
+
+        params.putInt("confidence", mActivity.getConfidence());
+        params.putString("type", BackgroundActivity.getActivityString(mActivity.getType()));
+
+        bundle.putString("name", getName());
+        bundle.putBundle("params", params);
+        return bundle;
+    }
+
+    @Override
+    public String toString() {
+        if (mActivity == null) {
+            return null;
+        }
+
+        try {
+            return mActivity.toJSONObject().toString();
+        } catch (JSONException e) {
+            onError("Error processing params: " + e.getMessage());
+        }
+
+        return null;
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/headless/JsCallback.java

@@ -0,0 +1,10 @@
+package com.marianhello.bgloc.headless;
+
+/**
+ * Interface for passing code that will be executed after the JS has finished
+ */
+
+public interface JsCallback {
+	void onResult(String value);
+	void onError(String errorMessage);
+}

package/android/src/main/java/com/marianhello/bgloc/headless/LocationTask.java

@@ -0,0 +1,60 @@
+package com.marianhello.bgloc.headless;
+
+import android.os.Bundle;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+import org.json.JSONException;
+
+public abstract class LocationTask extends Task {
+    protected BackgroundLocation mLocation;
+
+    public LocationTask(BackgroundLocation location) {
+        mLocation = location;
+    }
+
+    @Override
+    public String getName() {
+        return "location";
+    }
+
+    @Override
+    public Bundle getBundle() {
+        Bundle bundle = new Bundle();
+        Bundle params = new Bundle();
+
+        params.putString("provider", mLocation.getProvider());
+        params.putInt("locationProvider", mLocation.getLocationProvider());
+        params.putLong("time", mLocation.getTime());
+        params.putDouble("latitude", mLocation.getLatitude());
+        params.putDouble("longitude", mLocation.getLongitude());
+        if (mLocation.hasAccuracy()) params.putFloat("accuracy", mLocation.getAccuracy());
+        if (mLocation.hasVerticalAccuracy()) params.putFloat("accuracy", mLocation.getVerticalAccuracy());
+        if (mLocation.hasSpeed()) params.putFloat("speed", mLocation.getSpeed());
+        if (mLocation.hasAltitude()) params.putDouble("altitude", mLocation.getAltitude());
+        if (mLocation.hasBearing()) params.putFloat("bearing", mLocation.getBearing());
+        if (mLocation.hasRadius()) params.putFloat("radius", mLocation.getRadius());
+        if (mLocation.hasIsFromMockProvider()) params.putBoolean("isFromMockProvider", mLocation.isFromMockProvider());
+        if (mLocation.hasMockLocationsEnabled()) params.putBoolean("mockLocationsEnabled", mLocation.areMockLocationsEnabled());
+
+        bundle.putString("name", getName());
+        bundle.putBundle("params", params);
+
+        return bundle;
+    }
+
+    @Override
+    public String toString() {
+        if (mLocation == null) {
+            return null;
+        }
+
+        try {
+            return mLocation.toJSONObject().toString();
+        } catch (JSONException e) {
+            onError("Error processing params: " + e.getMessage());
+        }
+
+        return null;
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/headless/StationaryTask.java

@@ -0,0 +1,25 @@
+package com.marianhello.bgloc.headless;
+
+import android.os.Bundle;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+import org.json.JSONException;
+
+public abstract class StationaryTask extends LocationTask {
+    public StationaryTask(BackgroundLocation location) {
+        super(location);
+    }
+
+    @Override
+    public String getName() {
+        return "stationary";
+    }
+
+    @Override
+    public Bundle getBundle() {
+        Bundle bundle = super.getBundle();
+
+        return bundle;
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/headless/Task.java

@@ -0,0 +1,8 @@
+package com.marianhello.bgloc.headless;
+
+import android.os.Bundle;
+
+public abstract class Task implements JsCallback {
+    public abstract String getName();
+    public abstract Bundle getBundle();
+}

package/android/src/main/java/com/marianhello/bgloc/headless/TaskRunner.java

@@ -0,0 +1,5 @@
+package com.marianhello.bgloc.headless;
+
+public interface TaskRunner {
+    void runTask(Task task);
+}

package/android/src/main/java/com/marianhello/bgloc/headless/TaskRunnerFactory.java

@@ -0,0 +1,8 @@
+package com.marianhello.bgloc.headless;
+
+public class TaskRunnerFactory {
+
+    public TaskRunner getTaskRunner(String className) throws ClassNotFoundException, IllegalAccessException, InstantiationException {
+        return (TaskRunner) Class.forName(className).newInstance();
+    }
+}

package/android/src/main/java/com/marianhello/bgloc/http/UrlTemplateResolver.java

@@ -0,0 +1,115 @@
+package com.marianhello.bgloc.http;
+
+import com.marianhello.bgloc.data.BackgroundLocation;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+import java.util.TimeZone;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Resolves placeholders like {lat}, {lon}, {timestamp_iso}, {device_id}, ...
+ * in a URL template using a single BackgroundLocation and an optional queryParams map.
+ *
+ * Placeholders not found in the location/queryParams are left as-is so that
+ * partial templates (e.g. only static keys for batch mode) keep working.
+ *
+ * Usage:
+ *   String url = UrlTemplateResolver.resolve(template, location, queryParams);
+ *   // location may be null for batch mode (only queryParams keys are resolved).
+ */
+public final class UrlTemplateResolver {
+
+    private static final Pattern PLACEHOLDER = Pattern.compile("\\{([a-zA-Z0-9_]+)\\}");
+
+    private UrlTemplateResolver() { /* no instances */ }
+
+    public static String resolve(String template, BackgroundLocation location, Map<String, ?> queryParams) {
+        if (template == null || template.isEmpty()) return template;
+        Map<String, String> ctx = buildContext(location, queryParams);
+        Matcher m = PLACEHOLDER.matcher(template);
+        StringBuffer sb = new StringBuffer(template.length());
+        while (m.find()) {
+            String key = m.group(1);
+            String value = ctx.get(key);
+            if (value != null) {
+                m.appendReplacement(sb, Matcher.quoteReplacement(urlEncode(value)));
+            } else {
+                // Leave placeholder as-is if no value available.
+                m.appendReplacement(sb, Matcher.quoteReplacement(m.group(0)));
+            }
+        }
+        m.appendTail(sb);
+        return sb.toString();
+    }
+
+    public static boolean hasPlaceholders(String template) {
+        if (template == null) return false;
+        return PLACEHOLDER.matcher(template).find();
+    }
+
+    private static Map<String, String> buildContext(BackgroundLocation loc, Map<String, ?> queryParams) {
+        Map<String, String> ctx = new HashMap<String, String>();
+
+        // queryParams first so location-derived values can override if user wants
+        if (queryParams != null) {
+            for (Map.Entry<String, ?> e : queryParams.entrySet()) {
+                if (e.getValue() != null) {
+                    ctx.put(e.getKey(), String.valueOf(e.getValue()));
+                }
+            }
+        }
+
+        if (loc != null) {
+            ctx.put("latitude", String.valueOf(loc.getLatitude()));
+            ctx.put("longitude", String.valueOf(loc.getLongitude()));
+            ctx.put("lat", String.valueOf(loc.getLatitude()));
+            ctx.put("lon", String.valueOf(loc.getLongitude()));
+
+            long timeMs = loc.getTime();
+            ctx.put("time", String.valueOf(timeMs));
+            ctx.put("timestamp", String.valueOf(timeMs));
+            ctx.put("timestamp_iso", isoUtc(timeMs));
+
+            if (loc.hasSpeed()) ctx.put("speed", String.valueOf(loc.getSpeed()));
+            if (loc.hasAltitude()) ctx.put("altitude", String.valueOf(loc.getAltitude()));
+            if (loc.hasBearing()) ctx.put("bearing", String.valueOf(loc.getBearing()));
+            if (loc.hasAccuracy()) ctx.put("accuracy", String.valueOf(loc.getAccuracy()));
+
+            if (loc.getProvider() != null) ctx.put("provider", loc.getProvider());
+            // is_moving derived from speed when available (>0.5 m/s ~ walking pace).
+            if (loc.hasSpeed()) {
+                ctx.put("is_moving", loc.getSpeed() > 0.5f ? "true" : "false");
+            }
+            // {activity} is not produced by BackgroundLocation by default; the user can supply
+            // a value via queryParams (already populated above).
+        }
+
+        return ctx;
+    }
+
+    /**
+     * URL-encode a placeholder value for use in URL paths and query strings.
+     * Spaces become %20, not + (which is form-encoding).
+     */
+    private static String urlEncode(String s) {
+        if (s == null) return "";
+        try {
+            String enc = java.net.URLEncoder.encode(s, "UTF-8");
+            // URLEncoder uses application/x-www-form-urlencoded; convert "+" back to "%20" for URL safety.
+            return enc.replace("+", "%20");
+        } catch (Exception e) {
+            return s;
+        }
+    }
+
+    private static String isoUtc(long ms) {
+        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US);
+        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
+        return sdf.format(new Date(ms));
+    }
+}