chore: split LocationTracker into enrichment and sync concerns, add NOT_DETERMINED auth status

Split the monolithic LocationTracker into LocationEnrichmentProvider (identify
context enrichment) and LocationSyncCoordinator (persistence + sync filter +
track events) to match iOS SDK architecture. Both register as IdentifyHook
with their own reset responsibilities.

Add NOT_DETERMINED to AuthorizationStatus and PERMISSION_NOT_DETERMINED to
LocationProviderError for API completeness with iOS.

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

Author: Shahroz16

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

@@ -0,0 +1,9 @@
+package io.customer.location
+
+/**
+ * Internal location coordinate holder.
+ */
+internal data class LocationCoordinates(
+    val latitude: Double,
+    val longitude: Double
+)

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

@@ -0,0 +1,58 @@
+package io.customer.location
+
+import io.customer.location.store.LocationPreferenceStore
+import io.customer.sdk.core.pipeline.IdentifyHook
+import io.customer.sdk.core.util.Logger
+
+/**
+ * Provides location data for identify event context enrichment.
+ *
+ * Every identify() call enriches the event context with the latest
+ * location coordinates. This is unfiltered — a new user always gets
+ * the device's current location on their profile immediately.
+ *
+ * On clearIdentify(), [resetContext] clears the in-memory cache and
+ * persisted coordinates synchronously during analytics.reset().
+ */
+internal class LocationEnrichmentProvider(
+    private val locationPreferenceStore: LocationPreferenceStore,
+    private val logger: Logger
+) : IdentifyHook {
+
+    @Volatile
+    private var lastLocation: LocationCoordinates? = null
+
+    override fun getIdentifyContext(): Map<String, Any> {
+        val location = lastLocation ?: return emptyMap()
+        return mapOf(
+            "location_latitude" to location.latitude,
+            "location_longitude" to location.longitude
+        )
+    }
+
+    override fun resetContext() {
+        lastLocation = null
+        locationPreferenceStore.clearCachedLocation()
+        logger.debug("Location enrichment state reset")
+    }
+
+    /**
+     * Updates the in-memory location cache used for identify context.
+     * Called by [LocationSyncCoordinator] when a new location is received.
+     */
+    fun updateLocation(coordinates: LocationCoordinates) {
+        lastLocation = coordinates
+    }
+
+    /**
+     * Reads persisted cached location from the preference store and sets the
+     * in-memory cache so that identify events have location context
+     * immediately after SDK restart.
+     */
+    fun restorePersistedLocation() {
+        val lat = locationPreferenceStore.getCachedLatitude() ?: return
+        val lng = locationPreferenceStore.getCachedLongitude() ?: return
+        lastLocation = LocationCoordinates(latitude = lat, longitude = lng)
+        logger.debug("Restored persisted location: lat=$lat, lng=$lng")
+    }
+}

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

@@ -13,7 +13,7 @@ import kotlinx.coroutines.CancellationException
 internal class LocationOrchestrator(
     private val config: LocationModuleConfig,
     private val logger: Logger,
-    private val locationTracker: LocationTracker,
+    private val syncCoordinator: LocationSyncCoordinator,
     private val locationProvider: LocationProvider
 ) {
 
@@ -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)
+            syncCoordinator.onLocationReceived(snapshot.latitude, snapshot.longitude)
         } catch (e: CancellationException) {
             logger.debug("Location request was cancelled.")
             throw e

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

@@ -14,7 +14,7 @@ import kotlinx.coroutines.launch
 internal class LocationServicesImpl(
     private val config: LocationModuleConfig,
     private val logger: Logger,
-    private val locationTracker: LocationTracker,
+    private val syncCoordinator: LocationSyncCoordinator,
     private val orchestrator: LocationOrchestrator,
     private val scope: CoroutineScope
 ) : LocationServices {
@@ -34,7 +34,7 @@ internal class LocationServicesImpl(
 
         logger.debug("Tracking location: lat=$latitude, lng=$longitude")
 
-        locationTracker.onLocationReceived(latitude, longitude)
+        syncCoordinator.onLocationReceived(latitude, longitude)
     }
 
     override fun setLastKnownLocation(location: Location) {

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

@@ -0,0 +1,94 @@
+package io.customer.location
+
+import io.customer.location.store.LocationPreferenceStore
+import io.customer.location.sync.LocationSyncFilter
+import io.customer.sdk.core.pipeline.DataPipeline
+import io.customer.sdk.core.pipeline.IdentifyHook
+import io.customer.sdk.core.util.Logger
+import io.customer.sdk.util.EventNames
+
+/**
+ * Coordinates location persistence and "Location Update" track events.
+ *
+ * When a location is received, it is persisted, the enrichment provider's
+ * in-memory cache is updated, and the sync filter is evaluated to decide
+ * whether a track event should be sent. The track event is gated by a
+ * userId check and the 24h / 1km sync filter to avoid redundant events.
+ *
+ * Implements [IdentifyHook] solely for [resetContext] — clears sync filter
+ * state on clearIdentify() so the next user starts with a fresh baseline.
+ */
+internal class LocationSyncCoordinator(
+    private val dataPipeline: DataPipeline?,
+    private val locationPreferenceStore: LocationPreferenceStore,
+    private val locationSyncFilter: LocationSyncFilter,
+    private val enrichmentProvider: LocationEnrichmentProvider,
+    private val logger: Logger
+) : IdentifyHook {
+
+    override fun getIdentifyContext(): Map<String, Any> = emptyMap()
+
+    override fun resetContext() {
+        locationSyncFilter.clearSyncedData()
+        logger.debug("Location sync state reset")
+    }
+
+    /**
+     * Processes an incoming location: updates the enrichment provider's
+     * in-memory cache, persists coordinates, and attempts to send a
+     * location track event.
+     */
+    fun onLocationReceived(latitude: Double, longitude: Double) {
+        logger.debug("Location update received: lat=$latitude, lng=$longitude")
+
+        enrichmentProvider.updateLocation(LocationCoordinates(latitude = latitude, longitude = longitude))
+        locationPreferenceStore.saveCachedLocation(latitude, longitude)
+
+        trySendLocationTrack(latitude, longitude)
+    }
+
+    /**
+     * Called when a user is identified. Attempts to sync the cached
+     * location as a track event for the newly identified user.
+     *
+     * The identify event itself already carries location via
+     * [LocationEnrichmentProvider.getIdentifyContext] — this method handles
+     * the supplementary "Location Update" track event, subject to the sync filter.
+     */
+    fun onUserIdentified() {
+        syncCachedLocationIfNeeded()
+    }
+
+    /**
+     * Re-evaluates the cached location for sending.
+     * Called on identify (via [onUserIdentified]) and on cold start
+     * (via replayed UserChangedEvent) to handle cases where a location
+     * was cached but not yet sent for the current user.
+     */
+    internal fun syncCachedLocationIfNeeded() {
+        val lat = locationPreferenceStore.getCachedLatitude() ?: return
+        val lng = locationPreferenceStore.getCachedLongitude() ?: return
+
+        logger.debug("Re-evaluating cached location: lat=$lat, lng=$lng")
+        trySendLocationTrack(lat, lng)
+    }
+
+    /**
+     * Applies the userId gate and sync filter, then sends a location
+     * track event via [DataPipeline] if both pass.
+     */
+    private fun trySendLocationTrack(latitude: Double, longitude: Double) {
+        val pipeline = dataPipeline ?: return
+        if (!pipeline.isUserIdentified) return
+        if (!locationSyncFilter.filterAndRecord(latitude, longitude)) return
+
+        logger.debug("Sending location track: lat=$latitude, lng=$longitude")
+        pipeline.track(
+            name = EventNames.LOCATION_UPDATE,
+            properties = mapOf(
+                "latitude" to latitude,
+                "longitude" to longitude
+            )
+        )
+    }
+}

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

@@ -76,20 +76,27 @@ class ModuleLocation @JvmOverloads constructor(
         val locationSyncFilter = LocationSyncFilter(
             LocationSyncStoreImpl(context, logger)
         )
-        val locationTracker = LocationTracker(dataPipeline, store, locationSyncFilter, logger)
+        val enrichmentProvider = LocationEnrichmentProvider(store, logger)
+        val syncCoordinator = LocationSyncCoordinator(
+            dataPipeline,
+            store,
+            locationSyncFilter,
+            enrichmentProvider,
+            logger
+        )
 
         val locationProvider = FusedLocationProvider(context)
         val orchestrator = LocationOrchestrator(
             config = moduleConfig,
             logger = logger,
-            locationTracker = locationTracker,
+            syncCoordinator = syncCoordinator,
             locationProvider = locationProvider
         )
 
         _locationServices = LocationServicesImpl(
             config = moduleConfig,
             logger = logger,
-            locationTracker = locationTracker,
+            syncCoordinator = syncCoordinator,
             orchestrator = orchestrator,
             scope = locationScope
         )
@@ -99,20 +106,19 @@ class ModuleLocation @JvmOverloads constructor(
         // for the public API, so callers get silent no-ops with helpful log messages.
         if (!moduleConfig.isEnabled) return
 
-        locationTracker.restorePersistedLocation()
+        enrichmentProvider.restorePersistedLocation()
 
-        // Register as IdentifyHook so location is added to identify event context
-        // and cleared synchronously during analytics.reset(). This ensures every
-        // identify() call carries the device's current location in the event context —
-        // the primary way location reaches a user's profile.
-        SDKComponent.identifyHookRegistry.register(locationTracker)
+        // Register both as IdentifyHooks — enrichment provider adds location to
+        // identify context, sync coordinator clears sync filter state on reset.
+        SDKComponent.identifyHookRegistry.register(enrichmentProvider)
+        SDKComponent.identifyHookRegistry.register(syncCoordinator)
 
         // On identify, attempt to send a supplementary "Location Update" track event.
         // The identify event itself already carries location via context enrichment —
         // this track event is for journey/segment triggers in the user's timeline.
         eventBus.subscribe<Event.UserChangedEvent> {
             if (!it.userId.isNullOrEmpty()) {
-                locationTracker.onUserIdentified()
+                syncCoordinator.onUserIdentified()
             }
         }