feat: add core location types, config, and EventBus event

Add foundational location types and wiring needed by subsequent location
features:

- LocationModuleConfig: enableLocationTracking flag with Builder
- LocationData / TrackLocationEvent in core Event sealed class
- LocationSnapshot, AuthorizationStatus, LocationProviderError,
  LocationGranularity types in location module
- LocationProviding interface abstracting platform location services
- LocationRequestException for structured error propagation
- DataPipeline subscription for TrackLocationEvent -> "Location Update"
- LOCATION_UPDATE event name constant

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

Author: Shahroz16

core/api/core.api

@@ -27,6 +27,19 @@ public final class io/customer/sdk/communication/Event$DeleteDeviceTokenEvent :
 	public fun <init> ()V
 }
 
+public final class io/customer/sdk/communication/Event$LocationData {
+	public fun <init> (DD)V
+	public final fun component1 ()D
+	public final fun component2 ()D
+	public final fun copy (DD)Lio/customer/sdk/communication/Event$LocationData;
+	public static synthetic fun copy$default (Lio/customer/sdk/communication/Event$LocationData;DDILjava/lang/Object;)Lio/customer/sdk/communication/Event$LocationData;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLatitude ()D
+	public final fun getLongitude ()D
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class io/customer/sdk/communication/Event$ProfileIdentifiedEvent : io/customer/sdk/communication/Event {
 	public fun <init> (Ljava/lang/String;)V
 	public final fun component1 ()Ljava/lang/String;
@@ -80,6 +93,17 @@ public final class io/customer/sdk/communication/Event$TrackInAppMetricEvent : i
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class io/customer/sdk/communication/Event$TrackLocationEvent : io/customer/sdk/communication/Event {
+	public fun <init> (Lio/customer/sdk/communication/Event$LocationData;)V
+	public final fun component1 ()Lio/customer/sdk/communication/Event$LocationData;
+	public final fun copy (Lio/customer/sdk/communication/Event$LocationData;)Lio/customer/sdk/communication/Event$TrackLocationEvent;
+	public static synthetic fun copy$default (Lio/customer/sdk/communication/Event$TrackLocationEvent;Lio/customer/sdk/communication/Event$LocationData;ILjava/lang/Object;)Lio/customer/sdk/communication/Event$TrackLocationEvent;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getLocation ()Lio/customer/sdk/communication/Event$LocationData;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class io/customer/sdk/communication/Event$TrackPushMetricEvent : io/customer/sdk/communication/Event {
 	public fun <init> (Ljava/lang/String;Lio/customer/sdk/events/Metric;Ljava/lang/String;)V
 	public final fun component1 ()Ljava/lang/String;

core/src/main/kotlin/io/customer/sdk/communication/Event.kt

@@ -48,4 +48,23 @@ sealed class Event {
     ) : Event()
 
     class DeleteDeviceTokenEvent : Event()
+
+    /**
+     * Event emitted when a location update should be tracked.
+     * Published by the Location module and consumed by DataPipeline
+     * to send location data to Customer.io servers.
+     */
+    data class TrackLocationEvent(
+        val location: LocationData
+    ) : Event()
+
+    /**
+     * Location data in a framework-agnostic format.
+     * Used to pass location information between modules without
+     * requiring Android location framework imports.
+     */
+    data class LocationData(
+        val latitude: Double,
+        val longitude: Double
+    )
 }

core/src/main/kotlin/io/customer/sdk/util/EventNames.kt

@@ -11,4 +11,7 @@ object EventNames {
 
     // Event name fired by AndroidLifecyclePlugin when app enters background
     const val APPLICATION_BACKGROUNDED = "Application Backgrounded"
+
+    // Event name for location updates tracked by the Location module
+    const val LOCATION_UPDATE = "Location Update"
 }

datapipelines/src/main/kotlin/io/customer/sdk/CustomerIO.kt

@@ -157,6 +157,21 @@ class CustomerIO private constructor(
         eventBus.subscribe<Event.RegisterDeviceTokenEvent> {
             registerDeviceToken(deviceToken = it.token)
         }
+        eventBus.subscribe<Event.TrackLocationEvent> {
+            trackLocation(it)
+        }
+    }
+
+    private fun trackLocation(event: Event.TrackLocationEvent) {
+        val location = event.location
+        logger.debug("tracking location update: lat=${location.latitude}, lng=${location.longitude}")
+        track(
+            name = EventNames.LOCATION_UPDATE,
+            properties = mapOf(
+                "lat" to location.latitude,
+                "lng" to location.longitude
+            )
+        )
     }
 
     private fun migrateTrackingEvents() {

location/api/location.api

@@ -1,16 +1,21 @@
 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 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 class io/customer/location/ModuleLocation : io/customer/sdk/core/module/CustomerIOModule {
 	public static final field Companion Lio/customer/location/ModuleLocation$Companion;
 	public static final field MODULE_NAME Ljava/lang/String;
+	public fun <init> ()V
 	public fun <init> (Lio/customer/location/LocationModuleConfig;)V
+	public synthetic fun <init> (Lio/customer/location/LocationModuleConfig;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun getModuleConfig ()Lio/customer/location/LocationModuleConfig;
 	public synthetic fun getModuleConfig ()Lio/customer/sdk/core/module/CustomerIOModuleConfig;
 	public fun getModuleName ()Ljava/lang/String;

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

@@ -6,11 +6,33 @@ import io.customer.sdk.core.module.CustomerIOModuleConfig
  * Location module configurations that can be used to customize
  * location tracking behavior based on the provided configurations.
  */
-class LocationModuleConfig private constructor() : CustomerIOModuleConfig {
+class LocationModuleConfig private constructor(
+    /**
+     * Whether location tracking is enabled.
+     *
+     * When false, the location module is effectively disabled and all location
+     * tracking operations will no-op silently.
+     */
+    val enableLocationTracking: Boolean
+) : CustomerIOModuleConfig {
 
     class Builder : CustomerIOModuleConfig.Builder<LocationModuleConfig> {
+        private var enableLocationTracking: Boolean = true
+
+        /**
+         * Sets whether location tracking is enabled.
+         * When disabled, all location operations will no-op silently.
+         * Default is true.
+         */
+        fun setEnableLocationTracking(enable: Boolean): Builder {
+            this.enableLocationTracking = enable
+            return this
+        }
+
         override fun build(): LocationModuleConfig {
-            return LocationModuleConfig()
+            return LocationModuleConfig(
+                enableLocationTracking = enableLocationTracking
+            )
         }
     }
 }

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

@@ -7,15 +7,28 @@ import io.customer.sdk.core.module.CustomerIOModule
  * Location module for Customer.io SDK.
  *
  * This module provides location tracking capabilities including:
- * - Permission and consent management
- * - One-shot location capture
- * - Continuous location tracking
+ * - Manual location setting from host app's existing location system
+ * - One-shot SDK-managed location capture
+ *
+ * Usage:
+ * ```
+ * val config = CustomerIOConfigBuilder(appContext, "your-api-key")
+ *     .addCustomerIOModule(
+ *         ModuleLocation(
+ *             LocationModuleConfig.Builder()
+ *                 .setEnableLocationTracking(true)
+ *                 .build()
+ *         )
+ *     )
+ *     .build()
+ *
+ * CustomerIO.initialize(config)
+ * ```
  */
-class ModuleLocation(
-    config: LocationModuleConfig
+class ModuleLocation @JvmOverloads constructor(
+    override val moduleConfig: LocationModuleConfig = LocationModuleConfig.Builder().build()
 ) : CustomerIOModule<LocationModuleConfig> {
     override val moduleName: String = MODULE_NAME
-    override val moduleConfig: LocationModuleConfig = config
 
     override fun initialize() {
         // Module initialization will be implemented in future PRs

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

@@ -0,0 +1,35 @@
+package io.customer.location.provider
+
+import io.customer.location.type.AuthorizationStatus
+import io.customer.location.type.LocationGranularity
+import io.customer.location.type.LocationSnapshot
+
+/**
+ * Abstracts system location services. Implementations wrap platform-specific
+ * location providers (e.g. FusedLocationProviderClient).
+ *
+ * This component does not request location permission. The host app must handle
+ * runtime permission requests and only call location APIs once authorized.
+ */
+internal interface LocationProvider {
+    /**
+     * One-shot location request. Returns the location result directly.
+     *
+     * @param granularity desired accuracy level for the request
+     * @return the captured location snapshot
+     * @throws LocationRequestException if location could not be obtained
+     */
+    suspend fun requestLocation(granularity: LocationGranularity): LocationSnapshot
+
+    /**
+     * Cancels any in-flight location request. Idempotent - safe to call
+     * even when no request is in progress.
+     */
+    suspend fun cancelRequestLocation()
+
+    /**
+     * Current authorization state for location access.
+     * Used for pre-checks before requesting location.
+     */
+    suspend fun currentAuthorizationStatus(): AuthorizationStatus
+}

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

@@ -0,0 +1,13 @@
+package io.customer.location.provider
+
+import io.customer.location.type.LocationProviderError
+
+/**
+ * Exception thrown when a location request fails.
+ * Wraps [LocationProviderError] to provide structured error information.
+ */
+internal class LocationRequestException(
+    val error: LocationProviderError,
+    message: String = "Location request failed: $error",
+    cause: Throwable? = null
+) : Exception(message, cause)

location/src/main/kotlin/io/customer/location/type/AuthorizationStatus.kt

@@ -0,0 +1,25 @@
+package io.customer.location.type
+
+/**
+ * Authorization status for location access.
+ * Maps Android runtime permission states to SDK-level values
+ * without depending on Android framework classes.
+ *
+ * Note: On Android, [DENIED] covers both "never asked" and "explicitly denied"
+ * because [android.content.pm.PackageManager.checkPermission] cannot distinguish
+ * between the two without an Activity context.
+ */
+internal enum class AuthorizationStatus {
+    /** Permission not granted (either never asked or explicitly denied). */
+    DENIED,
+
+    /** Foreground-only location access granted. */
+    AUTHORIZED_FOREGROUND,
+
+    /** Background + foreground location access granted. */
+    AUTHORIZED_BACKGROUND;
+
+    /** Whether the app is authorized to use location (foreground or background). */
+    val isAuthorized: Boolean
+        get() = this == AUTHORIZED_FOREGROUND || this == AUTHORIZED_BACKGROUND
+}