@bglocation/capacitor 1.1.0

package/android/src/main/kotlin/dev/bglocation/core/geofence/BGLGeofenceManager.kt

@@ -0,0 +1,310 @@
+package dev.bglocation.core.geofence
+
+import android.Manifest
+import android.app.PendingIntent
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.ActivityCompat
+import com.google.android.gms.location.Geofence
+import com.google.android.gms.location.GeofencingClient
+import com.google.android.gms.location.GeofencingRequest
+import com.google.android.gms.location.LocationServices
+import dev.bglocation.core.BGLLocationData
+import dev.bglocation.core.location.BGLLocationHelpers
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Manages Android geofencing via [GeofencingClient] with SharedPreferences persistence.
+ *
+ * - Persistence is the source of truth for getGeofences() (GeofencingClient does not
+ *   expose registered geofences with full config).
+ * - PendingIntent uses FLAG_MUTABLE (required for Android 12+ BroadcastReceiver).
+ * - Limit of [MAX_GEOFENCES] enforced.
+ */
+class BGLGeofenceManager(
+    private val context: Context,
+    private val prefs: SharedPreferences = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+) {
+
+    companion object {
+        private const val TAG = "BGLocation"
+        const val MAX_GEOFENCES = 20
+        private const val PREFS_NAME = "bgl_geofences"
+        private const val KEY_GEOFENCES = "geofences_json"
+        const val ACTION_GEOFENCE_EVENT = "dev.bglocation.ACTION_GEOFENCE_EVENT"
+    }
+
+    private val geofencingClient: GeofencingClient = LocationServices.getGeofencingClient(context)
+
+    /**
+     * Callback fired on geofence transitions (called from [BGLGeofenceBroadcastReceiver]).
+     */
+    var onGeofenceEvent: ((BGLGeofenceEventData) -> Unit)? = null
+
+    /** In-memory cache — invalidated on every save. Avoids repeated JSON deserialization. */
+    private var cachedGeofences: List<BGLGeofenceConfig>? = null
+
+    // MARK: - Public API
+
+    /**
+     * Add a single geofence. Replaces existing geofence with the same identifier.
+     * @throws GeofenceLimitExceededException if adding would exceed [MAX_GEOFENCES].
+     */
+    fun addGeofence(geofence: BGLGeofenceConfig, onSuccess: () -> Unit, onError: (String) -> Unit) {
+        val current = getGeofences().toMutableList()
+
+        // Replace existing with same identifier
+        current.removeAll { it.identifier == geofence.identifier }
+
+        if (current.size >= MAX_GEOFENCES) {
+            onError("Cannot add geofence — limit of $MAX_GEOFENCES reached.")
+            return
+        }
+
+        current.add(geofence)
+        saveGeofences(current)
+
+        registerNativeGeofence(geofence, onSuccess, onError)
+    }
+
+    /**
+     * Add multiple geofences atomically. If the total would exceed the limit, none are added.
+     */
+    fun addGeofences(geofences: List<BGLGeofenceConfig>, onSuccess: () -> Unit, onError: (String) -> Unit) {
+        val current = getGeofences().toMutableList()
+
+        // Remove duplicates by identifier
+        val newIdentifiers = geofences.map { it.identifier }.toSet()
+        current.removeAll { it.identifier in newIdentifiers }
+
+        if (current.size + geofences.size > MAX_GEOFENCES) {
+            onError("Cannot add geofences — would exceed limit of $MAX_GEOFENCES.")
+            return
+        }
+
+        current.addAll(geofences)
+        saveGeofences(current)
+
+        registerNativeGeofences(geofences, onSuccess, onError)
+    }
+
+    /**
+     * Remove a geofence by identifier. No-op if not found.
+     */
+    fun removeGeofence(identifier: String) {
+        val current = getGeofences().toMutableList()
+        current.removeAll { it.identifier == identifier }
+        saveGeofences(current)
+
+        geofencingClient.removeGeofences(listOf(identifier))
+            .addOnSuccessListener { Log.d(TAG, "Geofence removed: $identifier") }
+            .addOnFailureListener { e -> Log.w(TAG, "Failed to remove geofence $identifier: ${e.message}") }
+    }
+
+    /**
+     * Remove all registered geofences.
+     */
+    fun removeAllGeofences() {
+        val current = getGeofences()
+        saveGeofences(emptyList())
+
+        if (current.isNotEmpty()) {
+            geofencingClient.removeGeofences(getPendingIntent())
+                .addOnSuccessListener { Log.d(TAG, "All geofences removed") }
+                .addOnFailureListener { e -> Log.w(TAG, "Failed to remove all geofences: ${e.message}") }
+        }
+    }
+
+    /**
+     * Get all registered geofences from the cache (backed by persistence).
+     */
+    fun getGeofences(): List<BGLGeofenceConfig> {
+        cachedGeofences?.let { return it }
+        val loaded = loadGeofences()
+        cachedGeofences = loaded
+        return loaded
+    }
+
+    /**
+     * Whether any geofences are currently registered.
+     */
+    val hasGeofences: Boolean
+        get() = getGeofences().isNotEmpty()
+
+    /**
+     * Re-register all persisted geofences with the system.
+     * Called on boot and after configure() to restore geofences.
+     */
+    fun reRegisterAllGeofences() {
+        val geofences = loadGeofences()
+        if (geofences.isEmpty()) return
+
+        registerNativeGeofences(geofences,
+            onSuccess = { Log.d(TAG, "Re-registered ${geofences.size} geofences") },
+            onError = { e -> Log.w(TAG, "Failed to re-register geofences: $e") }
+        )
+    }
+
+    // MARK: - Native Geofence Registration
+
+    private fun registerNativeGeofence(geofence: BGLGeofenceConfig, onSuccess: () -> Unit, onError: (String) -> Unit) {
+        registerNativeGeofences(listOf(geofence), onSuccess, onError)
+    }
+
+    private fun registerNativeGeofences(geofences: List<BGLGeofenceConfig>, onSuccess: () -> Unit, onError: (String) -> Unit) {
+        if (ActivityCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            onError("Location permission not granted")
+            return
+        }
+
+        val nativeGeofences = geofences.map { config ->
+            var transitionTypes = 0
+            if (config.notifyOnEntry) transitionTypes = transitionTypes or Geofence.GEOFENCE_TRANSITION_ENTER
+            if (config.notifyOnExit) transitionTypes = transitionTypes or Geofence.GEOFENCE_TRANSITION_EXIT
+            if (config.notifyOnDwell) transitionTypes = transitionTypes or Geofence.GEOFENCE_TRANSITION_DWELL
+
+            Geofence.Builder()
+                .setRequestId(config.identifier)
+                .setCircularRegion(config.latitude, config.longitude, config.radius.toFloat())
+                .setExpirationDuration(Geofence.NEVER_EXPIRE)
+                .setTransitionTypes(transitionTypes)
+                .apply {
+                    if (config.notifyOnDwell) {
+                        setLoiteringDelay(config.dwellDelay * 1000) // seconds to millis
+                    }
+                }
+                .build()
+        }
+
+        val request = GeofencingRequest.Builder()
+            .setInitialTrigger(GeofencingRequest.INITIAL_TRIGGER_ENTER)
+            .addGeofences(nativeGeofences)
+            .build()
+
+        geofencingClient.addGeofences(request, getPendingIntent())
+            .addOnSuccessListener {
+                Log.d(TAG, "Registered ${geofences.size} geofences")
+                onSuccess()
+            }
+            .addOnFailureListener { e ->
+                Log.e(TAG, "Failed to register geofences: ${e.message}")
+                onError(e.message ?: "Unknown error registering geofences")
+            }
+    }
+
+    /**
+     * Build the PendingIntent for [BGLGeofenceBroadcastReceiver].
+     * Uses FLAG_MUTABLE (required for Android 12+ BroadcastReceiver with geofencing).
+     */
+    private fun getPendingIntent(): PendingIntent {
+        val intent = android.content.Intent(context, BGLGeofenceBroadcastReceiver::class.java).apply {
+            action = ACTION_GEOFENCE_EVENT
+        }
+        val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
+        } else {
+            PendingIntent.FLAG_UPDATE_CURRENT
+        }
+        return PendingIntent.getBroadcast(context, 0, intent, flags)
+    }
+
+    // MARK: - Persistence (SharedPreferences JSON)
+
+    private fun loadGeofences(): List<BGLGeofenceConfig> {
+        val json = prefs.getString(KEY_GEOFENCES, null) ?: return emptyList()
+        return try {
+            val array = JSONArray(json)
+            (0 until array.length()).map { i ->
+                val obj = array.getJSONObject(i)
+                BGLGeofenceConfig(
+                    identifier = obj.getString("identifier"),
+                    latitude = obj.getDouble("latitude"),
+                    longitude = obj.getDouble("longitude"),
+                    radius = obj.getDouble("radius"),
+                    notifyOnEntry = obj.optBoolean("notifyOnEntry", true),
+                    notifyOnExit = obj.optBoolean("notifyOnExit", true),
+                    notifyOnDwell = obj.optBoolean("notifyOnDwell", false),
+                    dwellDelay = obj.optInt("dwellDelay", 300),
+                    extras = obj.optJSONObject("extras")?.let { extrasObj ->
+                        extrasObj.keys().asSequence().associateWith { key -> extrasObj.getString(key) }
+                    }
+                )
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to parse geofences: ${e.message}")
+            emptyList()
+        }
+    }
+
+    private fun saveGeofences(geofences: List<BGLGeofenceConfig>) {
+        cachedGeofences = geofences
+        val array = JSONArray()
+        for (geofence in geofences) {
+            val obj = JSONObject().apply {
+                put("identifier", geofence.identifier)
+                put("latitude", geofence.latitude)
+                put("longitude", geofence.longitude)
+                put("radius", geofence.radius)
+                put("notifyOnEntry", geofence.notifyOnEntry)
+                put("notifyOnExit", geofence.notifyOnExit)
+                put("notifyOnDwell", geofence.notifyOnDwell)
+                put("dwellDelay", geofence.dwellDelay)
+                geofence.extras?.let { extras ->
+                    put("extras", JSONObject(extras))
+                }
+            }
+            array.put(obj)
+        }
+        prefs.edit().putString(KEY_GEOFENCES, array.toString()).apply()
+    }
+
+    internal fun findGeofence(identifier: String): BGLGeofenceConfig? {
+        return getGeofences().firstOrNull { it.identifier == identifier }
+    }
+}
+
+/**
+ * Geofence configuration stored in persistence.
+ */
+data class BGLGeofenceConfig(
+    val identifier: String,
+    val latitude: Double,
+    val longitude: Double,
+    val radius: Double,
+    val notifyOnEntry: Boolean = true,
+    val notifyOnExit: Boolean = true,
+    val notifyOnDwell: Boolean = false,
+    val dwellDelay: Int = 300,
+    val extras: Map<String, String>? = null
+)
+
+/**
+ * Geofence event emitted to JS layer.
+ */
+data class BGLGeofenceEventData(
+    val identifier: String,
+    val action: String, // "enter", "exit", "dwell"
+    val location: BGLLocationData?,
+    val extras: Map<String, String>?,
+    val timestamp: Long
+) {
+    fun toJSONObject(): JSONObject {
+        return JSONObject().apply {
+            put("identifier", identifier)
+            put("action", action)
+            put("timestamp", timestamp)
+            if (location != null) {
+                put("location", BGLLocationHelpers.toJSONObject(location))
+            } else {
+                put("location", JSONObject.NULL)
+            }
+            extras?.let { put("extras", JSONObject(it)) }
+        }
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/http/BGLHttpSender.kt

@@ -0,0 +1,187 @@
+package dev.bglocation.core.http
+
+import dev.bglocation.core.BGLHttpConfig
+import dev.bglocation.core.BGLLocationData
+import dev.bglocation.core.location.BGLLocationHelpers
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import org.json.JSONObject
+import java.io.BufferedReader
+import java.io.InputStreamReader
+import java.io.OutputStreamWriter
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+data class BGLHttpResult(
+    val statusCode: Int,
+    val success: Boolean,
+    val responseText: String,
+    val error: String? = null,
+    val bufferedCount: Int = 0
+)
+
+class BGLHttpSender {
+
+    companion object {
+        private const val TAG = "BGLocation"
+        private const val CONNECT_TIMEOUT = 10_000
+        private const val READ_TIMEOUT = 10_000
+        private const val FLUSH_BATCH_SIZE = 50
+    }
+
+    private val executor: ExecutorService = Executors.newSingleThreadExecutor()
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private var config: BGLHttpConfig? = null
+    private var buffer: BGLLocationBuffer? = null
+    @Volatile
+    private var isFlushing = false
+
+    /** Called for each HTTP result during buffer flush. Set this to receive onHttp events for flushed items. */
+    @Volatile
+    var onFlushProgress: ((BGLHttpResult) -> Unit)? = null
+
+    fun configure(httpConfig: BGLHttpConfig?) {
+        config = httpConfig
+    }
+
+    fun setBuffer(locationBuffer: BGLLocationBuffer?) {
+        buffer = locationBuffer
+    }
+
+    fun sendLocation(location: BGLLocationData, callback: (BGLHttpResult) -> Unit) {
+        val httpConfig = config ?: return
+
+        executor.execute {
+            val result = executePost(httpConfig, location)
+            if (!result.success && buffer != null) {
+                buffer?.add(location)
+                val count = buffer?.count() ?: 0
+                Log.d(TAG, "HTTP failed, location buffered (buffer=$count)")
+                mainHandler.post { callback(result.copy(bufferedCount = count)) }
+            } else {
+                val count = buffer?.count() ?: 0
+                mainHandler.post { callback(result.copy(bufferedCount = count)) }
+                // After a successful send, try to flush buffered items
+                if (result.success && count > 0) {
+                    flushBuffer(httpConfig, onFlushProgress)
+                }
+            }
+        }
+    }
+
+    /**
+     * Flush buffered locations to the server.
+     * Called after a successful send or on network reconnect.
+     */
+    fun flushBuffer(onProgress: ((BGLHttpResult) -> Unit)?) {
+        val httpConfig = config ?: return
+        flushBuffer(httpConfig, onProgress)
+    }
+
+    private fun flushBuffer(httpConfig: BGLHttpConfig, onProgress: ((BGLHttpResult) -> Unit)?) {
+        val locationBuffer = buffer ?: return
+        if (isFlushing) return
+        isFlushing = true
+
+        executor.execute {
+            try {
+                while (true) {
+                    val batch = locationBuffer.peek(FLUSH_BATCH_SIZE)
+                    if (batch.isEmpty()) break
+
+                    val successIds = mutableListOf<Long>()
+                    for ((id, location) in batch) {
+                        val result = executePost(httpConfig, location)
+                        if (result.success) {
+                            successIds.add(id)
+                        } else {
+                            // Stop flushing on first failure — server is likely unavailable
+                            if (successIds.isNotEmpty()) {
+                                locationBuffer.remove(successIds)
+                            }
+                            val count = locationBuffer.count()
+                            mainHandler.post {
+                                onProgress?.invoke(result.copy(bufferedCount = count))
+                            }
+                            return@execute
+                        }
+                    }
+                    if (successIds.isNotEmpty()) {
+                        locationBuffer.remove(successIds)
+                    }
+                }
+                val count = locationBuffer.count()
+                if (count == 0) {
+                    Log.d(TAG, "Buffer flush complete — all locations sent")
+                }
+                mainHandler.post {
+                    onProgress?.invoke(BGLHttpResult(
+                        statusCode = 200,
+                        success = true,
+                        responseText = "",
+                        bufferedCount = count
+                    ))
+                }
+            } finally {
+                isFlushing = false
+            }
+        }
+    }
+
+    fun shutdown() {
+        executor.shutdown()
+    }
+
+    private fun executePost(httpConfig: BGLHttpConfig, location: BGLLocationData): BGLHttpResult {
+        return try {
+            val url = URL(httpConfig.url)
+            val conn = url.openConnection() as HttpURLConnection
+            conn.requestMethod = "POST"
+            conn.setRequestProperty("Content-Type", "application/json")
+
+            for ((key, value) in httpConfig.headers) {
+                conn.setRequestProperty(key, value)
+            }
+
+            conn.doOutput = true
+            conn.connectTimeout = CONNECT_TIMEOUT
+            conn.readTimeout = READ_TIMEOUT
+
+            val body = BGLLocationHelpers.buildLocationBody(location)
+
+            OutputStreamWriter(conn.outputStream).use { writer ->
+                writer.write(body.toString())
+                writer.flush()
+            }
+
+            val statusCode = conn.responseCode
+            val responseText = try {
+                val stream = if (statusCode < 400) conn.inputStream else conn.errorStream
+                BufferedReader(InputStreamReader(stream)).use { it.readText() }
+            } catch (_: Exception) {
+                ""
+            }
+
+            conn.disconnect()
+
+            Log.d(TAG, "HTTP POST → ${httpConfig.url} → $statusCode")
+
+            BGLHttpResult(
+                statusCode = statusCode,
+                success = statusCode in 200..299,
+                responseText = responseText
+            )
+        } catch (e: Exception) {
+            Log.e(TAG, "HTTP POST failed: ${e.message}")
+            BGLHttpResult(
+                statusCode = 0,
+                success = false,
+                responseText = "",
+                error = e.message
+            )
+        }
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/http/BGLLocationBuffer.kt

@@ -0,0 +1,152 @@
+package dev.bglocation.core.http
+
+import dev.bglocation.core.BGLLocationBufferConfig
+import dev.bglocation.core.BGLLocationData
+import android.content.ContentValues
+import android.content.Context
+import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteOpenHelper
+import android.util.Log
+
+/**
+ * SQLite-backed offline buffer for location data.
+ *
+ * When HTTP upload fails, locations are stored locally and retried later.
+ * The buffer enforces a configurable maximum size — oldest entries are dropped
+ * when the limit is exceeded.
+ */
+class BGLLocationBuffer(context: Context) : SQLiteOpenHelper(context, DB_NAME, null, DB_VERSION) {
+
+    companion object {
+        private const val TAG = "BGLocation"
+        internal const val DB_NAME = "bgl_location_buffer.db"
+        internal const val DB_VERSION = 2
+        internal const val TABLE = "buffered_locations"
+    }
+
+    private var maxSize: Int = 1000
+
+    /** Called when buffer overflow triggers auto-trim. Parameter is the number of dropped entries. */
+    var onOverflow: ((Int) -> Unit)? = null
+
+    fun configure(bufferConfig: BGLLocationBufferConfig?) {
+        maxSize = bufferConfig?.maxSize ?: 1000
+    }
+
+    override fun onCreate(db: SQLiteDatabase) {
+        db.execSQL("""
+            CREATE TABLE $TABLE (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                latitude REAL NOT NULL,
+                longitude REAL NOT NULL,
+                accuracy REAL NOT NULL,
+                speed REAL NOT NULL,
+                heading REAL NOT NULL,
+                altitude REAL NOT NULL,
+                timestamp INTEGER NOT NULL,
+                is_moving INTEGER NOT NULL,
+                is_mock INTEGER NOT NULL DEFAULT 0,
+                created_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)
+            )
+        """.trimIndent())
+    }
+
+    override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
+        // Additive migrations — preserve buffered locations across schema upgrades.
+        // Each version block adds only the delta.
+        if (oldVersion < 2) {
+            db.execSQL("ALTER TABLE $TABLE ADD COLUMN is_mock INTEGER NOT NULL DEFAULT 0")
+        }
+    }
+
+    /**
+     * Store a failed location in the buffer.
+     * If the buffer exceeds [maxSize], the oldest entries are removed.
+     */
+    fun add(location: BGLLocationData) {
+        val db = writableDatabase
+        val values = ContentValues().apply {
+            put("latitude", location.latitude)
+            put("longitude", location.longitude)
+            put("accuracy", location.accuracy.toDouble())
+            put("speed", location.speed.toDouble())
+            put("heading", location.heading.toDouble())
+            put("altitude", location.altitude)
+            put("timestamp", location.timestamp)
+            put("is_moving", if (location.isMoving) 1 else 0)
+            put("is_mock", if (location.isMock) 1 else 0)
+        }
+        db.insert(TABLE, null, values)
+        trimBuffer(db)
+    }
+
+    /**
+     * Retrieve the oldest [limit] buffered locations (FIFO order).
+     * Returns pairs of (rowId, BGLLocationData) for deletion after successful send.
+     */
+    fun peek(limit: Int = 50): List<Pair<Long, BGLLocationData>> {
+        val db = readableDatabase
+        val cursor = db.query(
+            TABLE, null, null, null, null, null,
+            "id ASC", limit.toString()
+        )
+        val results = mutableListOf<Pair<Long, BGLLocationData>>()
+        cursor.use {
+            while (it.moveToNext()) {
+                val id = it.getLong(it.getColumnIndexOrThrow("id"))
+                val data = BGLLocationData(
+                    latitude = it.getDouble(it.getColumnIndexOrThrow("latitude")),
+                    longitude = it.getDouble(it.getColumnIndexOrThrow("longitude")),
+                    accuracy = it.getFloat(it.getColumnIndexOrThrow("accuracy")),
+                    speed = it.getFloat(it.getColumnIndexOrThrow("speed")),
+                    heading = it.getFloat(it.getColumnIndexOrThrow("heading")),
+                    altitude = it.getDouble(it.getColumnIndexOrThrow("altitude")),
+                    timestamp = it.getLong(it.getColumnIndexOrThrow("timestamp")),
+                    isMoving = it.getInt(it.getColumnIndexOrThrow("is_moving")) == 1,
+                    isMock = it.getInt(it.getColumnIndexOrThrow("is_mock")) == 1
+                )
+                results.add(id to data)
+            }
+        }
+        return results
+    }
+
+    /**
+     * Remove specific entries by their row IDs after successful send.
+     */
+    fun remove(ids: List<Long>) {
+        if (ids.isEmpty()) return
+        val db = writableDatabase
+        val placeholders = ids.joinToString(",") { "?" }
+        val args = ids.map { it.toString() }.toTypedArray()
+        db.delete(TABLE, "id IN ($placeholders)", args)
+    }
+
+    /** Current number of buffered locations. */
+    fun count(): Int {
+        val db = readableDatabase
+        val cursor = db.rawQuery("SELECT COUNT(*) FROM $TABLE", null)
+        cursor.use {
+            return if (it.moveToFirst()) it.getInt(0) else 0
+        }
+    }
+
+    /** Remove all buffered locations. */
+    fun clear() {
+        writableDatabase.delete(TABLE, null, null)
+    }
+
+    /**
+     * Trim the buffer to [maxSize] by removing oldest entries.
+     */
+    private fun trimBuffer(db: SQLiteDatabase) {
+        val overflow = count() - maxSize
+        if (overflow <= 0) return
+        db.execSQL(
+            "DELETE FROM $TABLE WHERE id IN (SELECT id FROM $TABLE ORDER BY id ASC LIMIT ?)",
+            arrayOf(overflow)
+        )
+        Log.d(TAG, "BGLLocationBuffer trimmed $overflow oldest entries (maxSize=$maxSize)")
+        onOverflow?.invoke(overflow)
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/license/BGLBuildConfig.kt

@@ -0,0 +1,16 @@
+package dev.bglocation.core.license
+
+/**
+ * Build-time configuration injected by the consuming plugin bridge.
+ * The bridge sets [buildEpoch] during plugin initialization.
+ * Used for update gating: licenses with `exp < buildEpoch` degrade to trial mode.
+ */
+object BGLBuildConfig {
+    /**
+     * Unix epoch seconds when the consuming plugin was built.
+     * Set by the bridge during initialization (e.g. from Gradle BuildConfig).
+     * Default 0 means update gating is disabled.
+     */
+    @JvmStatic
+    var buildEpoch: Long = 0L
+}