@mentra/bluetooth-sdk 0.1.9 → 0.1.11

package/android/src/main/java/com/mentra/bluetoothsdk/audio/AudioModels.kt

@@ -21,7 +21,9 @@ data class MicPcmEvent(
         bitsPerSample = numberValue(values, "bitsPerSample") ?: BITS_PER_SAMPLE,
         channels = numberValue(values, "channels") ?: CHANNELS,
         encoding = stringValue(values, "encoding") ?: ENCODING,
-        voiceActivityDetectionEnabled = boolValue(values, "voiceActivityDetectionEnabled") ?: true,
+        voiceActivityDetectionEnabled =
+            boolValue(values, "voiceActivityDetectionEnabled")
+                ?: BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED,
     )
 
     fun toMap(): Map<String, Any> =
@@ -63,7 +65,9 @@ data class MicLc3Event(
         frameSizeBytes = numberValue(values, "frameSizeBytes") ?: DEFAULT_FRAME_SIZE_BYTES,
         bitrate = numberValue(values, "bitrate") ?: DEFAULT_BITRATE,
         packetizedFromGlasses = boolValue(values, "packetizedFromGlasses") ?: false,
-        voiceActivityDetectionEnabled = boolValue(values, "voiceActivityDetectionEnabled") ?: true,
+        voiceActivityDetectionEnabled =
+            boolValue(values, "voiceActivityDetectionEnabled")
+                ?: BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED,
     )
 
     fun toMap(): Map<String, Any> =

package/android/src/main/java/com/mentra/bluetoothsdk/camera/CameraModels.kt

@@ -16,7 +16,8 @@ enum class PhotoSize(val value: String) {
 enum class ButtonPhotoSize(val value: String) {
     SMALL("small"),
     MEDIUM("medium"),
-    LARGE("large");
+    LARGE("large"),
+    MAX("max");
 
     companion object {
         @JvmStatic
@@ -47,20 +48,86 @@ data class ButtonVideoRecordingSettings(
     val fps: Int,
 )
 
+enum class CameraRoiPosition(val value: Int, val label: String) {
+    CENTER(0, "center"),
+    BOTTOM(1, "bottom"),
+    TOP(2, "top");
+
+    companion object {
+        @JvmStatic
+        fun fromValue(value: Int?): CameraRoiPosition =
+            values().firstOrNull { it.value == value } ?: CENTER
+
+        @JvmStatic
+        fun fromName(value: String?): CameraRoiPosition =
+            values().firstOrNull { it.label == value } ?: CENTER
+    }
+}
+
 class CameraFov @JvmOverloads constructor(
     fov: Int = DEFAULT_FOV,
-    roiPosition: Int = DEFAULT_ROI_POSITION,
+    roiPosition: CameraRoiPosition = DEFAULT_ROI_POSITION,
 ) {
     val fov: Int = fov.coerceIn(MIN_FOV, MAX_FOV)
-    val roiPosition: Int = roiPosition.coerceIn(MIN_ROI_POSITION, MAX_ROI_POSITION)
+    val roiPosition: CameraRoiPosition = roiPosition
 
     companion object {
-        const val MIN_FOV = 82
+        const val MIN_FOV = 62
         const val MAX_FOV = 118
         const val DEFAULT_FOV = 102
-        const val MIN_ROI_POSITION = 0
-        const val MAX_ROI_POSITION = 2
-        const val DEFAULT_ROI_POSITION = 0
+        const val NARROW_FOV = 82
+        @JvmField
+        val DEFAULT_ROI_POSITION = CameraRoiPosition.CENTER
+        @JvmField
+        val NARROW = CameraFov(NARROW_FOV, DEFAULT_ROI_POSITION)
+        @JvmField
+        val STANDARD = CameraFov(DEFAULT_FOV, DEFAULT_ROI_POSITION)
+        @JvmField
+        val WIDE = CameraFov(MAX_FOV, DEFAULT_ROI_POSITION)
+    }
+}
+
+data class CameraFovResult(
+    val requestId: String,
+    val fov: Int,
+    val roiPosition: CameraRoiPosition,
+    val timestamp: Long,
+) {
+    val values: Map<String, Any>
+        get() =
+            mapOf(
+                "requestId" to requestId,
+                "fov" to fov,
+                "roiPosition" to roiPosition.label,
+                "timestamp" to timestamp,
+            )
+
+    companion object {
+        @JvmStatic
+        fun fromAck(
+            ack: SettingsAckEvent,
+            fallback: CameraFov,
+        ): CameraFovResult {
+            if (ack.status == "error") {
+                throw BluetoothException(
+                    ack.errorCode ?: "camera_fov_failed",
+                    ack.errorMessage ?: "Camera FOV request failed.",
+                )
+            }
+            if (!ack.hardwareApplied) {
+                throw BluetoothException(
+                    "camera_fov_not_applied",
+                    "Camera FOV was saved but not applied to hardware.",
+                )
+            }
+
+            return CameraFovResult(
+                requestId = ack.requestId,
+                fov = ack.fov ?: fallback.fov,
+                roiPosition = CameraRoiPosition.fromValue(ack.roiPosition ?: fallback.roiPosition.value),
+                timestamp = ack.timestamp,
+            )
+        }
     }
 }
 
@@ -72,6 +139,7 @@ data class PhotoRequest @JvmOverloads constructor(
     val authToken: String? = null,
     val compress: PhotoCompression = PhotoCompression.MEDIUM,
     val flash: Boolean = true,
+    val save: Boolean = false,
     val sound: Boolean = true,
     /** Sensor exposure time for this capture only (ns), or null for auto exposure */
     val exposureTimeNs: Double? = null,
@@ -107,6 +175,7 @@ data class PhotoRequest @JvmOverloads constructor(
                 authToken = stringValue(values, "authToken", "auth_token")?.takeIf { it.isNotBlank() },
                 compress = PhotoCompression.fromValue(stringValue(values, "compress") ?: "none"),
                 flash = boolValue(values, "flash") ?: true,
+                save = boolValue(values, "save", "saveToGallery") ?: false,
                 sound = boolValue(values, "sound") ?: true,
                 exposureTimeNs = exposureTimeNs,
                 iso = iso,
@@ -154,8 +223,23 @@ data class VideoRecordingRequest(
     val requestId: String,
     val save: Boolean,
     val sound: Boolean,
+    // Optional per-recording overrides; 0 means "use the saved button-video default".
+    val width: Int = 0,
+    val height: Int = 0,
+    val fps: Int = 0,
 )
 
+data class VideoRecordingStatusEvent(
+    val values: Map<String, Any>,
+) {
+    val requestId: String get() = stringValue(values, "requestId").orEmpty()
+    val success: Boolean get() = boolValue(values, "success") ?: false
+    val status: String get() = stringValue(values, "status").orEmpty()
+    val details: String? get() = stringValue(values, "details")
+    val timestamp: Long get() = longValue(values, "timestamp") ?: System.currentTimeMillis()
+    val data: Map<String, Any>? get() = stringMapValue(values["data"])
+}
+
 data class GalleryStatusEvent(
     val values: Map<String, Any>,
 )
@@ -172,7 +256,7 @@ sealed interface PhotoResponse {
                 "requestId" to requestId,
                 "uploadUrl" to uploadUrl,
                 "timestamp" to timestamp,
-            )
+            ).withOptionalPhotoMetadata(this)
 
             is Error -> mutableMapOf<String, Any>(
                 "state" to state,
@@ -191,6 +275,10 @@ sealed interface PhotoResponse {
     data class Success(
         override val requestId: String,
         val uploadUrl: String,
+        val photoUrl: String?,
+        val statusUrl: String?,
+        val contentType: String?,
+        val fileSizeBytes: Long?,
         override val timestamp: Long,
     ) : PhotoResponse {
         override val state: String = "success"
@@ -210,14 +298,27 @@ sealed interface PhotoResponse {
             val requestId = stringValue(values, "requestId").orEmpty()
             val timestamp = longValue(values, "timestamp") ?: System.currentTimeMillis()
             val state = stringValue(values, "state")?.lowercase()
-            return if (state == "success") {
+            val success = state == "success" || boolValue(values, "success") == true
+            return if (success) {
                 val uploadUrl = stringValue(values, "uploadUrl").orEmpty()
-                Success(requestId = requestId, uploadUrl = uploadUrl, timestamp = timestamp)
+                Success(
+                    requestId = requestId,
+                    uploadUrl = uploadUrl,
+                    photoUrl = stringValue(values, "photoUrl"),
+                    statusUrl = stringValue(values, "statusUrl"),
+                    contentType = stringValue(values, "contentType", "mimeType"),
+                    fileSizeBytes =
+                        longValue(values, "fileSizeBytes")
+                            ?: longValue(values, "bytes")
+                            ?: longValue(values, "size"),
+                    timestamp = timestamp,
+                )
             } else {
                 Error(
                     requestId = requestId,
                     errorCode = stringValue(values, "errorCode"),
-                    errorMessage = stringValue(values, "errorMessage") ?: "Unknown photo error",
+                    errorMessage =
+                        stringValue(values, "errorMessage", "error") ?: "Unknown photo error",
                     timestamp = timestamp,
                 )
             }
@@ -225,6 +326,16 @@ sealed interface PhotoResponse {
     }
 }
 
+private fun Map<String, Any>.withOptionalPhotoMetadata(
+    success: PhotoResponse.Success,
+): Map<String, Any> =
+    toMutableMap().apply {
+        success.photoUrl?.takeIf { it.isNotBlank() }?.let { this["photoUrl"] = it }
+        success.statusUrl?.takeIf { it.isNotBlank() }?.let { this["statusUrl"] = it }
+        success.contentType?.takeIf { it.isNotBlank() }?.let { this["contentType"] = it }
+        success.fileSizeBytes?.let { this["fileSizeBytes"] = it }
+    }
+
 data class PhotoResponseEvent(
     val response: PhotoResponse,
 ) {
@@ -241,6 +352,9 @@ data class PhotoStatusEvent(
     val status: String get() = stringValue(values, "status").orEmpty()
     val timestamp: Long get() = longValue(values, "timestamp") ?: System.currentTimeMillis()
     val resolvedConfig: Map<String, Any>? get() = stringMapValue(values["resolvedConfig"])
+    val requestedCaptureConfig: Map<String, Any>? get() = stringMapValue(values["requestedCaptureConfig"])
+    val meteredPreview: Map<String, Any>? get() = stringMapValue(values["meteredPreview"])
+    val captureMetadata: Map<String, Any>? get() = stringMapValue(values["captureMetadata"])
     val errorCode: String? get() = stringValue(values, "errorCode")
     val errorMessage: String? get() = stringValue(values, "errorMessage")
 }

package/android/src/main/java/com/mentra/bluetoothsdk/controllers/ControllerManager.kt

@@ -1,5 +1,6 @@
 package com.mentra.bluetoothsdk.controllers
 
+import com.mentra.bluetoothsdk.BluetoothSdkDefaults
 import com.mentra.bluetoothsdk.DeviceStore
 
 abstract class ControllerManager {
@@ -22,6 +23,7 @@ abstract class ControllerManager {
         authToken: String?,
         compress: String?,
         flash: Boolean,
+        save: Boolean,
         sound: Boolean,
         exposureTimeNs: Long?,
         iso: Int?,
@@ -43,7 +45,13 @@ abstract class ControllerManager {
     abstract fun clearDisplay()
     abstract fun sendTextWall(text: String)
     abstract fun sendDoubleTextWall(top: String, bottom: String)
-    abstract fun displayBitmap(base64ImageData: String): Boolean
+    abstract fun displayBitmap(
+            base64ImageData: String,
+            x: Int? = null,
+            y: Int? = null,
+            width: Int? = null,
+            height: Int? = null
+    ): Boolean
     abstract fun showDashboard()
     abstract fun setDashboardPosition(height: Int, depth: Int)
 
@@ -135,7 +143,9 @@ abstract class ControllerManager {
         get() = DeviceStore.get("glasses", "micEnabled") as? Boolean ?: false
 
     val voiceActivityDetectionEnabled: Boolean
-        get() = DeviceStore.get("glasses", "voiceActivityDetectionEnabled") as? Boolean ?: true
+        get() =
+            DeviceStore.get("glasses", "voiceActivityDetectionEnabled") as? Boolean
+                ?: BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED
 
     val batteryLevel: Int
         get() = DeviceStore.get("glasses", "batteryLevel") as? Int ?: -1

package/android/src/main/java/com/mentra/bluetoothsdk/controllers/R1.kt

@@ -863,7 +863,7 @@ class R1 : ControllerManager() {
     override fun sendJson(jsonOriginal: Map<String, Any>, wakeUp: Boolean, requireAck: Boolean) {}
     override fun requestPhoto(
         requestId: String, appId: String, size: String?, webhookUrl: String?,
-        authToken: String?, compress: String?, flash: Boolean, sound: Boolean,
+        authToken: String?, compress: String?, flash: Boolean, save: Boolean, sound: Boolean,
         exposureTimeNs: Long?, iso: Int?,
     ) {}
     override fun startVideoRecording(requestId: String, save: Boolean, flash: Boolean, sound: Boolean) {}
@@ -879,7 +879,13 @@ class R1 : ControllerManager() {
     override fun clearDisplay() {}
     override fun sendTextWall(text: String) {}
     override fun sendDoubleTextWall(top: String, bottom: String) {}
-    override fun displayBitmap(base64ImageData: String): Boolean = false
+    override fun displayBitmap(
+            base64ImageData: String,
+            x: Int?,
+            y: Int?,
+            width: Int?,
+            height: Int?
+    ): Boolean = false
     override fun showDashboard() {}
     override fun setDashboardPosition(height: Int, depth: Int) {}
     override fun setHeadUpAngle(angle: Int) {}

package/android/src/main/java/com/mentra/bluetoothsdk/debug/BleTraceLogger.kt

@@ -10,6 +10,7 @@ import org.json.JSONObject
 object BleTraceLogger {
     private const val TAG = "MentraBleTrace"
     private const val MAX_PAYLOAD_CHARS = 3000
+    private const val K900_TYPE = "k900"
     private val sensitiveKeyParts =
         listOf("password", "pass", "token", "secret", "authorization", "auth", "email")
 
@@ -26,8 +27,12 @@ object BleTraceLogger {
 
     @JvmStatic
     fun logMap(direction: String, layer: String, type: String?, payload: Map<String, Any>) {
-        val sanitized = sanitize(JSONObject(payload))
-        Log.i(TAG, format(direction, layer, caller(), type ?: extractType(sanitized), null, sanitized.toString()))
+        try {
+            val sanitized = sanitize(JSONObject(payload))
+            Log.i(TAG, format(direction, layer, caller(), type ?: extractType(sanitized), null, sanitized.toString()))
+        } catch (e: Exception) {
+            Log.d(TAG, "BLE trace map logging failed", e)
+        }
     }
 
     @JvmStatic
@@ -37,20 +42,24 @@ object BleTraceLogger {
         event: String,
         extra: Map<String, Any?> = emptyMap(),
     ) {
-        val payload = JSONObject()
-        payload.put("event", event)
-        payload.put("component", component)
-        payload.put("pid", Process.myPid())
-        payload.put("model", Build.MODEL)
-        payload.put("sdkInt", Build.VERSION.SDK_INT)
-
-        context?.let {
-            payload.put("package", it.packageName)
-            packageVersion(it)?.let { version -> payload.put("version", version) }
-        }
+        try {
+            val payload = JSONObject()
+            payload.put("event", event)
+            payload.put("component", component)
+            payload.put("pid", Process.myPid())
+            payload.put("model", Build.MODEL)
+            payload.put("sdkInt", Build.VERSION.SDK_INT)
+
+            context?.let {
+                payload.put("package", it.packageName)
+                packageVersion(it)?.let { version -> payload.put("version", version) }
+            }
 
-        extra.forEach { (key, value) -> payload.put(key, value ?: JSONObject.NULL) }
-        Log.i(TAG, format("phone_app", "app_lifecycle", caller(), event, null, sanitize(payload).toString()))
+            extra.forEach { (key, value) -> payload.put(key, value ?: JSONObject.NULL) }
+            Log.i(TAG, format("phone_app", "app_lifecycle", caller(), event, null, sanitize(payload).toString()))
+        } catch (e: Exception) {
+            Log.d(TAG, "BLE trace lifecycle logging failed", e)
+        }
     }
 
     private fun format(
@@ -72,12 +81,16 @@ object BleTraceLogger {
                 val inner = JSONObject(cValue)
                 inner.optString("type").takeIf { it.isNotBlank() }?.let { return it }
             } catch (_: Exception) {
-                return "k900:${cValue.take(40)}"
+                return extractK900Type(cValue)
             }
+            return extractK900Type(cValue)
         }
         return "unknown"
     }
 
+    private fun extractK900Type(cValue: String): String =
+        if (cValue == "sr_log") "$K900_TYPE:sr_log" else K900_TYPE
+
     private fun sanitize(value: JSONObject): JSONObject {
         val output = JSONObject()
         value.keys().forEach { key ->
@@ -102,7 +115,7 @@ object BleTraceLogger {
             try {
                 return sanitize(JSONObject(value)).toString()
             } catch (_: Exception) {
-                return truncate(value)
+                return sanitizeK900Command(value)
             }
         }
         return when (value) {
@@ -113,6 +126,9 @@ object BleTraceLogger {
         }
     }
 
+    private fun sanitizeK900Command(value: String): String =
+        if (value == "sr_log") value else "<non-json C payload>"
+
     private fun caller(): String {
         val frame =
             Throwable().stackTrace.firstOrNull {

package/android/src/main/java/com/mentra/bluetoothsdk/events/BluetoothEvents.kt

@@ -39,6 +39,100 @@ data class SpeakingStatusEvent(
     val values: Map<String, Any>,
 )
 
+data class OtaUpdateAvailableEvent(
+    val versionCode: Long?,
+    val versionName: String?,
+    val updates: List<String>,
+    val totalSize: Long?,
+    val cacheReady: Boolean?,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        internal fun fromMap(values: Map<String, Any>): OtaUpdateAvailableEvent =
+            OtaUpdateAvailableEvent(
+                versionCode = longValue(values, "version_code"),
+                versionName = stringValue(values, "version_name"),
+                updates = (values["updates"] as? List<*>)?.filterIsInstance<String>() ?: emptyList(),
+                totalSize = longValue(values, "total_size"),
+                cacheReady = boolValue(values, "cache_ready"),
+                values = values,
+            )
+    }
+}
+
+data class OtaStartAckEvent(
+    val timestamp: Long?,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        internal fun fromMap(values: Map<String, Any>): OtaStartAckEvent =
+            OtaStartAckEvent(
+                timestamp = longValue(values, "timestamp"),
+                values = values,
+            )
+    }
+}
+
+data class OtaStatusEvent(
+    val sessionId: String,
+    val totalSteps: Int,
+    val currentStep: Int,
+    val stepType: String,
+    val phase: String,
+    val stepPercent: Int,
+    val overallPercent: Int,
+    val status: String,
+    val errorMessage: String?,
+    val glassesTimeMs: Long?,
+    val values: Map<String, Any>,
+) {
+    companion object {
+        internal fun fromMap(values: Map<String, Any>): OtaStatusEvent =
+            OtaStatusEvent(
+                sessionId = stringValue(values, "session_id") ?: "",
+                totalSteps = numberValue(values, "total_steps") ?: 0,
+                currentStep = numberValue(values, "current_step") ?: 0,
+                stepType = stringValue(values, "step_type") ?: "",
+                phase = stringValue(values, "phase") ?: "",
+                stepPercent = numberValue(values, "step_percent") ?: 0,
+                overallPercent = numberValue(values, "overall_percent") ?: 0,
+                status = stringValue(values, "status") ?: "",
+                errorMessage = stringValue(values, "error_message"),
+                glassesTimeMs = longValue(values, "glasses_time_ms"),
+                values = values,
+            )
+    }
+}
+
+data class OtaQueryResult(
+    val values: Map<String, Any>,
+) {
+    val type: String get() = stringValue(values, "type").orEmpty()
+    val status: String? get() = stringValue(values, "status")
+}
+
+data class SettingsAckEvent(
+    val values: Map<String, Any>,
+) {
+    val requestId: String get() = stringValue(values, "requestId").orEmpty()
+    val setting: String get() = stringValue(values, "setting").orEmpty()
+    val status: String get() = stringValue(values, "status") ?: "applied"
+    val timestamp: Long get() = longValue(values, "timestamp") ?: System.currentTimeMillis()
+    val fov: Int? get() = numberValue(values, "fov")
+    val roiPosition: Int? get() = numberValue(values, "roiPosition", "roi_position")
+    val hardwareApplied: Boolean get() = boolValue(values, "hardwareApplied", "hardware_applied") ?: false
+    val errorCode: String? get() = stringValue(values, "errorCode")
+    val errorMessage: String? get() = stringValue(values, "errorMessage")
+}
+
+data class RgbLedControlResponseEvent(
+    val values: Map<String, Any>,
+) {
+    val requestId: String get() = stringValue(values, "requestId").orEmpty()
+    val state: String get() = stringValue(values, "state") ?: "error"
+    val errorCode: String? get() = stringValue(values, "errorCode")
+}
+
 interface MentraBluetoothSdkListener {
     fun onStateChanged(state: MentraBluetoothState) {}
     fun onGlassesChanged(glasses: GlassesRuntimeState) {}
@@ -59,8 +153,15 @@ interface MentraBluetoothSdkListener {
     fun onGalleryStatus(event: GalleryStatusEvent) {}
     fun onPhotoResponse(event: PhotoResponseEvent) {}
     fun onPhotoStatus(event: PhotoStatusEvent) {}
+    fun onVideoRecordingStatus(event: VideoRecordingStatusEvent) {}
+    fun onRgbLedControlResponse(event: RgbLedControlResponseEvent) {}
     fun onStreamStatus(event: StreamStatusEvent) {}
     fun onKeepAliveAck(event: KeepAliveAckEvent) {}
+    fun onOtaUpdateAvailable(event: OtaUpdateAvailableEvent) {}
+    fun onOtaStartAck(event: OtaStartAckEvent) {}
+    fun onOtaStatus(event: OtaStatusEvent) {}
+    fun onSettingsAck(event: SettingsAckEvent) {}
+    fun onVersionInfo(event: VersionInfoResult) {}
     fun onMicPcm(event: MicPcmEvent) {}
     fun onMicLc3(event: MicLc3Event) {}
     fun onLocalTranscription(event: LocalTranscriptionEvent) {}

package/android/src/main/java/com/mentra/bluetoothsdk/internal/MapParsing.kt

@@ -8,6 +8,14 @@ internal fun numberValue(
         (values[key] as? Number)?.toInt()
     }
 
+internal fun doubleValue(
+    values: Map<String, Any>,
+    vararg keys: String,
+): Double? =
+    keys.firstNotNullOfOrNull { key ->
+        (values[key] as? Number)?.toDouble()
+    }
+
 internal fun stringValue(
     values: Map<String, Any>,
     vararg keys: String,

package/android/src/main/java/com/mentra/bluetoothsdk/photoreceiver/LocalPhotoReceiverRegistry.java

@@ -0,0 +1,108 @@
+package com.mentra.bluetoothsdk.photoreceiver;
+
+import androidx.annotation.Nullable;
+
+import java.net.URI;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * Tracks the SDK photo receiver that is hosted inside the phone app process.
+ *
+ * <p>The glasses need a LAN-reachable URL, but the phone-side BLE fallback relay
+ * can upload to the same receiver over loopback. Keeping this tiny registry lets
+ * the relay avoid stale Wi-Fi interface addresses after network changes.
+ */
+public final class LocalPhotoReceiverRegistry {
+    private static volatile Set<URI> activeUploadUris = Collections.emptySet();
+
+    private LocalPhotoReceiverRegistry() {}
+
+    public static void register(String uploadUrl) {
+        try {
+            URI uri = URI.create(uploadUrl);
+            if (isSupportedUploadUri(uri)) {
+                Set<URI> nextUploadUris = new HashSet<>(activeUploadUris);
+                nextUploadUris.add(uri);
+                activeUploadUris = Collections.unmodifiableSet(nextUploadUris);
+            }
+        } catch (Exception ignored) {
+        }
+    }
+
+    public static void unregister() {
+        activeUploadUris = Collections.emptySet();
+    }
+
+    public static boolean isActive() {
+        return !activeUploadUris.isEmpty();
+    }
+
+    @Nullable
+    public static String loopbackUploadUrlFor(@Nullable String webhookUrl) {
+        Set<URI> registeredUris = activeUploadUris;
+        if (registeredUris.isEmpty() || webhookUrl == null || webhookUrl.isEmpty()) {
+            return null;
+        }
+
+        try {
+            URI uri = URI.create(webhookUrl);
+            for (URI registeredUri : registeredUris) {
+                if (matchesRegisteredUploadUri(uri, registeredUri)) {
+                    return new URI(
+                            uri.getScheme(),
+                            null,
+                            "127.0.0.1",
+                            effectivePort(uri),
+                            normalizedPath(uri),
+                            uri.getRawQuery(),
+                            uri.getRawFragment()
+                    ).toString();
+                }
+            }
+            return null;
+        } catch (Exception ignored) {
+            return null;
+        }
+    }
+
+    private static boolean matchesRegisteredUploadUri(URI candidate, URI registered) {
+        return isSupportedUploadUri(candidate)
+                && equalsIgnoreCase(candidate.getScheme(), registered.getScheme())
+                && equalsIgnoreCase(candidate.getHost(), registered.getHost())
+                && effectivePort(candidate) == effectivePort(registered)
+                && Objects.equals(normalizedPath(candidate), normalizedPath(registered))
+                && Objects.equals(candidate.getRawQuery(), registered.getRawQuery())
+                && Objects.equals(candidate.getRawFragment(), registered.getRawFragment());
+    }
+
+    private static boolean isSupportedUploadUri(URI uri) {
+        String scheme = uri.getScheme();
+        if (!"http".equalsIgnoreCase(scheme) && !"https".equalsIgnoreCase(scheme)) {
+            return false;
+        }
+        return uri.getHost() != null && effectivePort(uri) > 0 && "/upload".equals(normalizedPath(uri));
+    }
+
+    private static int effectivePort(URI uri) {
+        int port = uri.getPort();
+        if (port != -1) {
+            return port;
+        }
+        return "https".equalsIgnoreCase(uri.getScheme()) ? 443 : 80;
+    }
+
+    private static String normalizedPath(URI uri) {
+        String path = uri.getRawPath();
+        return (path == null || path.isEmpty()) ? "/" : path;
+    }
+
+    private static boolean equalsIgnoreCase(@Nullable String first, @Nullable String second) {
+        if (first == null || second == null) {
+            return first == second;
+        }
+        return first.equalsIgnoreCase(second);
+    }
+}