chore: replace enableLocationTracking boolean with LocationTrackingMode enum

Introduce a 3-state LocationTrackingMode enum (OFF, MANUAL, ON_APP_START)
replacing the boolean enableLocationTracking config. OFF disables all
location machinery including identify enrichment and track events.
MANUAL preserves existing behavior. ON_APP_START auto-captures location
on cold start with cacheOnly mode for identify context enrichment.

- Add LocationTrackingMode enum with OFF, MANUAL, ON_APP_START
- Update LocationModuleConfig to use trackingMode with isEnabled guard
- Add cacheOnly parameter to LocationTracker.onLocationReceived()
- Guard restore/enrich/subscribe setup behind isEnabled in ModuleLocation
- Remove stopLocationUpdates() (only relevant for continuous tracking)
- Add request deduplication via job cancellation in LocationServicesImpl
- Update public API surface, tests, and sample app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Shahroz16

location/api/location.api

@@ -1,20 +1,28 @@
 public final class io/customer/location/LocationModuleConfig : io/customer/sdk/core/module/CustomerIOModuleConfig {
-	public synthetic fun <init> (ZLkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun getEnableLocationTracking ()Z
+	public synthetic fun <init> (Lio/customer/location/LocationTrackingMode;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun getTrackingMode ()Lio/customer/location/LocationTrackingMode;
 }
 
 public final class io/customer/location/LocationModuleConfig$Builder : io/customer/sdk/core/module/CustomerIOModuleConfig$Builder {
 	public fun <init> ()V
 	public fun build ()Lio/customer/location/LocationModuleConfig;
 	public synthetic fun build ()Lio/customer/sdk/core/module/CustomerIOModuleConfig;
-	public final fun setEnableLocationTracking (Z)Lio/customer/location/LocationModuleConfig$Builder;
+	public final fun setLocationTrackingMode (Lio/customer/location/LocationTrackingMode;)Lio/customer/location/LocationModuleConfig$Builder;
 }
 
 public abstract interface class io/customer/location/LocationServices {
 	public abstract fun requestLocationUpdate ()V
 	public abstract fun setLastKnownLocation (DD)V
 	public abstract fun setLastKnownLocation (Landroid/location/Location;)V
-	public abstract fun stopLocationUpdates ()V
+}
+
+public final class io/customer/location/LocationTrackingMode : java/lang/Enum {
+	public static final field MANUAL Lio/customer/location/LocationTrackingMode;
+	public static final field OFF Lio/customer/location/LocationTrackingMode;
+	public static final field ON_APP_START Lio/customer/location/LocationTrackingMode;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lio/customer/location/LocationTrackingMode;
+	public static fun values ()[Lio/customer/location/LocationTrackingMode;
 }
 
 public final class io/customer/location/ModuleLocation : io/customer/sdk/core/module/CustomerIOModule {

location/src/main/kotlin/io/customer/location/LocationModuleConfig.kt

@@ -8,30 +8,37 @@ import io.customer.sdk.core.module.CustomerIOModuleConfig
  */
 class LocationModuleConfig private constructor(
     /**
-     * Whether location tracking is enabled.
+     * The tracking mode for the location module.
      *
-     * When false, the location module is effectively disabled and all location
-     * tracking operations will no-op silently.
+     * - [LocationTrackingMode.OFF]: Location tracking is disabled; all operations no-op.
+     * - [LocationTrackingMode.MANUAL]: Host app controls when location is captured (default).
+     * - [LocationTrackingMode.ON_APP_START]: SDK auto-captures location on cold start,
+     *   caching it for identify context enrichment.
      */
-    val enableLocationTracking: Boolean
+    val trackingMode: LocationTrackingMode
 ) : CustomerIOModuleConfig {
 
+    /**
+     * Whether location tracking is enabled (any mode other than [LocationTrackingMode.OFF]).
+     */
+    internal val isEnabled: Boolean
+        get() = trackingMode != LocationTrackingMode.OFF
+
     class Builder : CustomerIOModuleConfig.Builder<LocationModuleConfig> {
-        private var enableLocationTracking: Boolean = true
+        private var trackingMode: LocationTrackingMode = LocationTrackingMode.MANUAL
 
         /**
-         * Sets whether location tracking is enabled.
-         * When disabled, all location operations will no-op silently.
-         * Default is true.
+         * Sets the location tracking mode.
+         * Default is [LocationTrackingMode.MANUAL].
          */
-        fun setEnableLocationTracking(enable: Boolean): Builder {
-            this.enableLocationTracking = enable
+        fun setLocationTrackingMode(mode: LocationTrackingMode): Builder {
+            this.trackingMode = mode
             return this
         }
 
         override fun build(): LocationModuleConfig {
             return LocationModuleConfig(
-                enableLocationTracking = enableLocationTracking
+                trackingMode = trackingMode
             )
         }
     }

location/src/main/kotlin/io/customer/location/LocationOrchestrator.kt

@@ -17,8 +17,8 @@ internal class LocationOrchestrator(
     private val locationProvider: LocationProvider
 ) {
 
-    suspend fun requestLocationUpdate() {
-        if (!config.enableLocationTracking) {
+    suspend fun requestLocationUpdate(cacheOnly: Boolean = false) {
+        if (!config.isEnabled) {
             logger.debug("Location tracking is disabled, ignoring requestLocationUpdate.")
             return
         }
@@ -34,7 +34,7 @@ internal class LocationOrchestrator(
                 granularity = LocationGranularity.DEFAULT
             )
             logger.debug("Tracking location: lat=${snapshot.latitude}, lng=${snapshot.longitude}")
-            locationTracker.onLocationReceived(snapshot.latitude, snapshot.longitude)
+            locationTracker.onLocationReceived(snapshot.latitude, snapshot.longitude, cacheOnly)
         } catch (e: CancellationException) {
             logger.debug("Location request was cancelled.")
             throw e

location/src/main/kotlin/io/customer/location/LocationServices.kt

@@ -41,20 +41,12 @@ interface LocationServices {
     fun setLastKnownLocation(location: Location)
 
     /**
-     * Starts a single location update and sends the result to Customer.io.
+     * Requests a single location update and sends the result to Customer.io.
      *
      * No-ops if location tracking is disabled or permission is not granted.
-     * Only one request at a time; calling again cancels any in-flight request
-     * and starts a new one.
      *
      * The SDK does not request location permission. The host app must request
      * runtime permissions and only call this when permission is granted.
      */
     fun requestLocationUpdate()
-
-    /**
-     * Cancels any in-flight location request.
-     * No-op if nothing is in progress.
-     */
-    fun stopLocationUpdates()
 }

location/src/main/kotlin/io/customer/location/LocationServicesImpl.kt

@@ -2,8 +2,6 @@ package io.customer.location
 
 import android.location.Location
 import io.customer.sdk.core.util.Logger
-import java.util.concurrent.locks.ReentrantLock
-import kotlin.concurrent.withLock
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.launch
@@ -21,11 +19,10 @@ internal class LocationServicesImpl(
     private val scope: CoroutineScope
 ) : LocationServices {
 
-    private val lock = ReentrantLock()
     private var currentLocationJob: Job? = null
 
     override fun setLastKnownLocation(latitude: Double, longitude: Double) {
-        if (!config.enableLocationTracking) {
+        if (!config.isEnabled) {
             logger.debug("Location tracking is disabled, ignoring setLastKnownLocation.")
             return
         }
@@ -45,36 +42,17 @@ internal class LocationServicesImpl(
     }
 
     override fun requestLocationUpdate() {
-        lock.withLock {
-            // Cancel any previous in-flight request
-            currentLocationJob?.cancel()
-
-            currentLocationJob = scope.launch {
-                val thisJob = coroutineContext[Job]
-                try {
-                    orchestrator.requestLocationUpdate()
-                } finally {
-                    lock.withLock {
-                        if (currentLocationJob === thisJob) {
-                            currentLocationJob = null
-                        }
-                    }
-                }
+        // Cancel any previous in-flight request to avoid concurrent GPS calls
+        currentLocationJob?.cancel()
+        currentLocationJob = scope.launch {
+            try {
+                orchestrator.requestLocationUpdate()
+            } finally {
+                currentLocationJob = null
             }
         }
     }
 
-    override fun stopLocationUpdates() {
-        val job: Job?
-        lock.withLock {
-            job = currentLocationJob
-            currentLocationJob = null
-        }
-        // Cancelling the job triggers invokeOnCancellation in FusedLocationProvider's
-        // suspendCancellableCoroutine, which cancels the CancellationTokenSource.
-        job?.cancel()
-    }
-
     companion object {
         /**
          * Validates that latitude is within [-90, 90] and longitude is within [-180, 180].

location/src/main/kotlin/io/customer/location/LocationTracker.kt

@@ -74,16 +74,23 @@ internal class LocationTracker(
     }
 
     /**
-     * Processes an incoming location: caches in memory, persists
-     * coordinates, and attempts to send a location track event.
+     * Processes an incoming location: caches in memory, persists coordinates,
+     * and optionally attempts to send a location track event.
+     *
+     * @param cacheOnly when true, updates the in-memory cache and persists
+     *   coordinates but does NOT send a "Location Update" track event.
+     *   Used by ON_APP_START auto-requests to refresh cached location for
+     *   identify context enrichment without generating a discrete event.
      */
-    fun onLocationReceived(latitude: Double, longitude: Double) {
-        logger.debug("Location update received: lat=$latitude, lng=$longitude")
+    fun onLocationReceived(latitude: Double, longitude: Double, cacheOnly: Boolean = false) {
+        logger.debug("Location update received: lat=$latitude, lng=$longitude, cacheOnly=$cacheOnly")
 
         lastLocation = LocationCoordinates(latitude = latitude, longitude = longitude)
         locationPreferenceStore.saveCachedLocation(latitude, longitude)
 
-        trySendLocationTrack(latitude, longitude)
+        if (!cacheOnly) {
+            trySendLocationTrack(latitude, longitude)
+        }
     }
 
     /**

location/src/main/kotlin/io/customer/location/LocationTrackingMode.kt

@@ -0,0 +1,29 @@
+package io.customer.location
+
+/**
+ * Defines the tracking mode for the location module.
+ */
+enum class LocationTrackingMode {
+    /**
+     * Location tracking is disabled.
+     * All location operations will no-op silently.
+     */
+    OFF,
+
+    /**
+     * Host app controls when location is captured.
+     * Use [LocationServices.setLastKnownLocation] or [LocationServices.requestLocationUpdate]
+     * to manually trigger location capture. This is the default mode.
+     */
+    MANUAL,
+
+    /**
+     * SDK automatically captures location on cold start.
+     *
+     * The auto-captured location is cached for identify context enrichment
+     * without immediately sending a track event. Manual location APIs
+     * ([LocationServices.setLastKnownLocation], [LocationServices.requestLocationUpdate])
+     * remain fully functional and will send track events as usual.
+     */
+    ON_APP_START
+}

location/src/main/kotlin/io/customer/location/ModuleLocation.kt

@@ -12,21 +12,23 @@ import io.customer.sdk.core.module.CustomerIOModule
 import io.customer.sdk.core.pipeline.DataPipeline
 import io.customer.sdk.core.pipeline.identifyHookRegistry
 import io.customer.sdk.core.util.Logger
+import kotlinx.coroutines.launch
 
 /**
  * Location module for Customer.io SDK.
  *
  * This module provides location tracking capabilities including:
  * - Manual location setting from host app's existing location system
  * - One-shot SDK-managed location capture
+ * - Automatic location capture on app start (ON_APP_START mode)
  *
  * Usage:
  * ```
  * val config = CustomerIOConfigBuilder(appContext, "your-api-key")
  *     .addCustomerIOModule(
  *         ModuleLocation(
  *             LocationModuleConfig.Builder()
- *                 .setEnableLocationTracking(true)
+ *                 .setLocationTrackingMode(LocationTrackingMode.MANUAL)
  *                 .build()
  *         )
  *     )
@@ -67,6 +69,7 @@ class ModuleLocation @JvmOverloads constructor(
         val logger = SDKComponent.logger
         val eventBus = SDKComponent.eventBus
         val context = SDKComponent.android().applicationContext
+        val locationScope = SDKComponent.scopeProvider.locationScope
 
         val dataPipeline = SDKComponent.getOrNull<DataPipeline>()
         val store = LocationPreferenceStoreImpl(context, logger)
@@ -75,6 +78,27 @@ class ModuleLocation @JvmOverloads constructor(
         )
         val locationTracker = LocationTracker(dataPipeline, store, locationSyncFilter, logger)
 
+        val locationProvider = FusedLocationProvider(context)
+        val orchestrator = LocationOrchestrator(
+            config = moduleConfig,
+            logger = logger,
+            locationTracker = locationTracker,
+            locationProvider = locationProvider
+        )
+
+        _locationServices = LocationServicesImpl(
+            config = moduleConfig,
+            logger = logger,
+            locationTracker = locationTracker,
+            orchestrator = orchestrator,
+            scope = locationScope
+        )
+
+        // When OFF, skip all background machinery — no restoration, no enrichment,
+        // no event subscriptions. LocationServicesImpl has its own isEnabled guards
+        // for the public API, so callers get silent no-ops with helpful log messages.
+        if (!moduleConfig.isEnabled) return
+
         locationTracker.restorePersistedLocation()
 
         // Register as IdentifyHook so location is added to identify event context
@@ -92,21 +116,15 @@ class ModuleLocation @JvmOverloads constructor(
             }
         }
 
-        val locationProvider = FusedLocationProvider(context)
-        val orchestrator = LocationOrchestrator(
-            config = moduleConfig,
-            logger = logger,
-            locationTracker = locationTracker,
-            locationProvider = locationProvider
-        )
-
-        _locationServices = LocationServicesImpl(
-            config = moduleConfig,
-            logger = logger,
-            locationTracker = locationTracker,
-            orchestrator = orchestrator,
-            scope = SDKComponent.scopeProvider.locationScope
-        )
+        // ON_APP_START: auto-capture location on cold start.
+        // Fire-and-forget — refreshes cached location so subsequent identify() calls
+        // carry fresh data. If permissions are denied or services disabled, orchestrator
+        // silently no-ops.
+        if (moduleConfig.trackingMode == LocationTrackingMode.ON_APP_START) {
+            locationScope.launch {
+                orchestrator.requestLocationUpdate(cacheOnly = true)
+            }
+        }
     }
 
     companion object {
@@ -143,6 +161,4 @@ private class UninitializedLocationServices(
     override fun setLastKnownLocation(location: Location) = logNotInitialized()
 
     override fun requestLocationUpdate() = logNotInitialized()
-
-    override fun stopLocationUpdates() = logNotInitialized()
 }