feat: add SDK-managed one-shot location (requestLocationUpdateOnce)

Implement SDK-managed location tracking using FusedLocationProviderClient:

- FusedLocationProvider: wraps Google's FusedLocationProviderClient with
  getCurrentLocation for one-shot requests, cancellation token support,
  permission pre-checks, and location services availability detection
- LocationOrchestrator: coordinates request lifecycle with config checks,
  authorization verification, and EventBus posting on success
- LocationServicesImpl: coroutine-based job management for one-shot
  requests with cancellation (cancel previous before starting new)
- ModuleLocation: wires FusedLocationProvider, orchestrator, and scope
- AndroidManifest: declares ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION
  permissions (merged into host app manifest)

Uses PRIORITY_LOW_POWER (~10km accuracy) for privacy-conscious city/timezone
level tracking. SDK never requests permissions - host app is responsible.

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

Author: Shahroz16

location/api/location.api

@@ -11,7 +11,7 @@ public final class io/customer/location/LocationModuleConfig$Builder : io/custom
 }
 
 public abstract interface class io/customer/location/LocationServices {
-	public abstract fun requestLocationUpdateOnce ()V
+	public abstract fun requestLocationUpdate ()V
 	public abstract fun setLastKnownLocation (DD)V
 	public abstract fun setLastKnownLocation (Landroid/location/Location;)V
 	public abstract fun stopLocationUpdates ()V

location/src/main/AndroidManifest.xml

@@ -1,4 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
+    <!-- Coarse location is sufficient for city/timezone level tracking -->
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+
 </manifest>

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

@@ -0,0 +1,57 @@
+package io.customer.location
+
+import io.customer.location.provider.LocationProvider
+import io.customer.location.provider.LocationRequestException
+import io.customer.location.type.LocationGranularity
+import io.customer.sdk.communication.Event
+import io.customer.sdk.communication.EventBus
+import io.customer.sdk.core.util.Logger
+import kotlinx.coroutines.CancellationException
+
+/**
+ * Coordinates location requests: one-shot only.
+ * Uses an injected [LocationProvider] for platform location access.
+ */
+internal class LocationOrchestrator(
+    private val config: LocationModuleConfig,
+    private val logger: Logger,
+    private val eventBus: EventBus,
+    private val locationProvider: LocationProvider
+) {
+
+    suspend fun requestLocationUpdate() {
+        if (!config.enableLocationTracking) {
+            logger.debug("Location tracking is disabled, ignoring requestLocationUpdate.")
+            return
+        }
+
+        val authStatus = locationProvider.currentAuthorizationStatus()
+        if (!authStatus.isAuthorized) {
+            logger.debug("Location permission not granted ($authStatus), ignoring request.")
+            return
+        }
+
+        try {
+            val snapshot = locationProvider.requestLocation(
+                granularity = LocationGranularity.DEFAULT
+            )
+            postLocation(snapshot.latitude, snapshot.longitude)
+        } catch (e: CancellationException) {
+            logger.debug("Location request was cancelled.")
+            throw e
+        } catch (e: LocationRequestException) {
+            logger.debug("Location request failed: ${e.error}")
+        } catch (e: Exception) {
+            logger.debug("Location request failed with unexpected error: ${e.message}")
+        }
+    }
+
+    private fun postLocation(latitude: Double, longitude: Double) {
+        logger.debug("Tracking location: lat=$latitude, lng=$longitude")
+        val locationData = Event.LocationData(
+            latitude = latitude,
+            longitude = longitude
+        )
+        eventBus.publish(Event.TrackLocationEvent(location = locationData))
+    }
+}

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

@@ -50,7 +50,7 @@ interface LocationServices {
      * The SDK does not request location permission. The host app must request
      * runtime permissions and only call this when permission is granted.
      */
-    fun requestLocationUpdateOnce()
+    fun requestLocationUpdate()
 
     /**
      * Cancels any in-flight location request.

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

@@ -4,19 +4,28 @@ import android.location.Location
 import io.customer.sdk.communication.Event
 import io.customer.sdk.communication.EventBus
 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
 
 /**
  * Real implementation of [LocationServices].
- * Handles manual location setting with validation and config checks.
- *
- * SDK-managed location (requestLocationUpdateOnce) will be implemented in a future PR.
+ * Handles manual location setting with validation and config checks,
+ * and SDK-managed one-shot location via [LocationOrchestrator].
  */
 internal class LocationServicesImpl(
     private val config: LocationModuleConfig,
     private val logger: Logger,
-    private val eventBus: EventBus
+    private val eventBus: EventBus,
+    private val orchestrator: LocationOrchestrator,
+    private val scope: CoroutineScope
 ) : LocationServices {
 
+    private val lock = ReentrantLock()
+    private var currentLocationJob: Job? = null
+
     override fun setLastKnownLocation(latitude: Double, longitude: Double) {
         if (!config.enableLocationTracking) {
             logger.debug("Location tracking is disabled, ignoring setLastKnownLocation.")
@@ -41,14 +50,35 @@ internal class LocationServicesImpl(
         setLastKnownLocation(location.latitude, location.longitude)
     }
 
-    override fun requestLocationUpdateOnce() {
-        // Will be implemented in the SDK-managed location PR
-        logger.debug("requestLocationUpdateOnce is not yet implemented.")
+    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
+                        }
+                    }
+                }
+            }
+        }
     }
 
     override fun stopLocationUpdates() {
-        // Will be implemented in the SDK-managed location PR
-        logger.debug("stopLocationUpdates is not yet implemented.")
+        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 {

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

@@ -1,9 +1,12 @@
 package io.customer.location
 
 import android.location.Location
+import io.customer.location.provider.FusedLocationProvider
 import io.customer.sdk.core.di.SDKComponent
 import io.customer.sdk.core.module.CustomerIOModule
 import io.customer.sdk.core.util.Logger
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.SupervisorJob
 
 /**
  * Location module for Customer.io SDK.
@@ -26,8 +29,11 @@ import io.customer.sdk.core.util.Logger
  *
  * CustomerIO.initialize(config)
  *
- * // Then use the location services
+ * // Manual location from host app
  * ModuleLocation.instance().locationServices.setLastKnownLocation(37.7749, -122.4194)
+ *
+ * // SDK-managed one-shot location
+ * ModuleLocation.instance().locationServices.requestLocationUpdate()
  * ```
  */
 class ModuleLocation @JvmOverloads constructor(
@@ -52,10 +58,27 @@ class ModuleLocation @JvmOverloads constructor(
         get() = _locationServices ?: UninitializedLocationServices(SDKComponent.logger)
 
     override fun initialize() {
+        val logger = SDKComponent.logger
+        val eventBus = SDKComponent.eventBus
+        val context = SDKComponent.android().applicationContext
+        val dispatchers = SDKComponent.dispatchersProvider
+
+        val locationProvider = FusedLocationProvider(context)
+        val orchestrator = LocationOrchestrator(
+            config = moduleConfig,
+            logger = logger,
+            eventBus = eventBus,
+            locationProvider = locationProvider
+        )
+
+        val locationScope = CoroutineScope(dispatchers.default + SupervisorJob())
+
         _locationServices = LocationServicesImpl(
             config = moduleConfig,
-            logger = SDKComponent.logger,
-            eventBus = SDKComponent.eventBus
+            logger = logger,
+            eventBus = eventBus,
+            orchestrator = orchestrator,
+            scope = locationScope
         )
     }
 
@@ -92,7 +115,7 @@ private class UninitializedLocationServices(
 
     override fun setLastKnownLocation(location: Location) = logNotInitialized()
 
-    override fun requestLocationUpdateOnce() = logNotInitialized()
+    override fun requestLocationUpdate() = logNotInitialized()
 
     override fun stopLocationUpdates() = logNotInitialized()
 }

location/src/main/kotlin/io/customer/location/provider/FusedLocationProvider.kt

@@ -0,0 +1,130 @@
+package io.customer.location.provider
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.location.LocationManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.Priority
+import com.google.android.gms.tasks.CancellationTokenSource
+import io.customer.location.type.AuthorizationStatus
+import io.customer.location.type.LocationGranularity
+import io.customer.location.type.LocationProviderError
+import io.customer.location.type.LocationSnapshot
+import java.util.Date
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+/**
+ * [LocationProvider] implementation wrapping Google's [FusedLocationProviderClient].
+ *
+ * Uses [FusedLocationProviderClient.getCurrentLocation] for one-shot location requests
+ * with cancellation support. Does not request permissions - the host app is responsible.
+ */
+internal class FusedLocationProvider(
+    private val context: Context
+) : LocationProvider {
+
+    private val fusedClient: FusedLocationProviderClient =
+        LocationServices.getFusedLocationProviderClient(context)
+
+    @Suppress("MissingPermission")
+    override suspend fun requestLocation(granularity: LocationGranularity): LocationSnapshot {
+        val authStatus = currentAuthorizationStatus()
+        if (!authStatus.isAuthorized) {
+            throw LocationRequestException(error = LocationProviderError.PERMISSION_DENIED)
+        }
+
+        if (!isLocationServicesEnabled()) {
+            throw LocationRequestException(error = LocationProviderError.SERVICES_DISABLED)
+        }
+
+        val priority = mapGranularityToPriority(granularity)
+        val tokenSource = CancellationTokenSource()
+
+        return suspendCancellableCoroutine { continuation ->
+            continuation.invokeOnCancellation {
+                tokenSource.cancel()
+            }
+
+            fusedClient.getCurrentLocation(priority, tokenSource.token)
+                .addOnSuccessListener { location ->
+                    if (!continuation.isActive) return@addOnSuccessListener
+                    if (location != null) {
+                        continuation.resume(
+                            LocationSnapshot(
+                                latitude = location.latitude,
+                                longitude = location.longitude,
+                                timestamp = Date(location.time),
+                                horizontalAccuracy = location.accuracy.toDouble(),
+                                altitude = if (location.hasAltitude()) location.altitude else null
+                            )
+                        )
+                    } else {
+                        continuation.resumeWithException(
+                            LocationRequestException(error = LocationProviderError.TIMEOUT)
+                        )
+                    }
+                }
+                .addOnFailureListener { exception ->
+                    if (!continuation.isActive) return@addOnFailureListener
+                    continuation.resumeWithException(
+                        LocationRequestException(
+                            error = LocationProviderError.TIMEOUT,
+                            cause = exception
+                        )
+                    )
+                }
+                .addOnCanceledListener {
+                    if (!continuation.isActive) return@addOnCanceledListener
+                    continuation.cancel()
+                }
+        }
+    }
+
+    override suspend fun currentAuthorizationStatus(): AuthorizationStatus {
+        val hasFine = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_FINE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        val hasCoarse = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_COARSE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        if (!hasFine && !hasCoarse) {
+            return AuthorizationStatus.DENIED
+        }
+
+        // Check for background location on Android 10+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            val hasBackground = ContextCompat.checkSelfPermission(
+                context,
+                Manifest.permission.ACCESS_BACKGROUND_LOCATION
+            ) == PackageManager.PERMISSION_GRANTED
+            if (hasBackground) {
+                return AuthorizationStatus.AUTHORIZED_BACKGROUND
+            }
+        }
+
+        return AuthorizationStatus.AUTHORIZED_FOREGROUND
+    }
+
+    private fun isLocationServicesEnabled(): Boolean {
+        val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as? LocationManager
+            ?: return false
+        return locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER) ||
+            locationManager.isProviderEnabled(LocationManager.NETWORK_PROVIDER)
+    }
+
+    private fun mapGranularityToPriority(granularity: LocationGranularity): Int {
+        return when (granularity) {
+            LocationGranularity.COARSE_CITY_OR_TIMEZONE -> Priority.PRIORITY_LOW_POWER
+        }
+    }
+}