@bota.dev/react-native-app-sdk 2.0.0-beta.1 → 2.0.0-beta.3

package/README.md

@@ -14,19 +14,25 @@ into the native Apple and Android SDKs.
 
 ## Install
 
-This source prepares synchronized `2.0.0-beta.1`; use the exact pin below after
-publication. Version `2.0.0-beta.0` remains the previous published release.
+This source prepares synchronized `2.0.0-beta.3`; use the exact pin below after
+publication. Version `2.0.0-beta.1` remains the previous published release.
 Remove `@bota.dev/react-native-sdk` before adding the replacement; do not
 co-install both. Production maintenance 0.0.x consumers need not migrate.
 
 ```bash
-npm install --save-exact @bota.dev/react-native-app-sdk@2.0.0-beta.1
+npm install --save-exact @bota.dev/react-native-app-sdk@2.0.0-beta.3
 npx pod-install
 ```
 
 Rebuild the native iOS and Android applications after installation. An Expo Go
 runtime cannot load this native module; use a development or production build.
 
+An application-native upload pod may depend on `BotaDeviceSDK`. With static
+SwiftPM linkage, the SDK's CocoaPods workaround normalizes the module-map path
+in both aggregate and dependent-pod cached build settings. This preserves the
+path when Expo later writes macro flags. Do not work around missing module maps
+by adding another copy of the Apple SDK.
+
 Expo prebuild and EAS projects must set the Android minimum SDK explicitly. Add
 the Expo-compatible `expo-build-properties` package and configure it in the app
 config:
@@ -59,6 +65,12 @@ await BotaClient.waitForBluetooth();
 The `BotaClient.devices`, `BotaClient.recordings`, and `BotaClient.ota`
 managers become available after configuration completes.
 
+Discovery exposes the manufacturer-advertised `macAddress` as uppercase,
+colon-separated bytes (`AA:BB:CC:DD:EE:FF`), preserving the legacy React Native
+registration contract. Compact native addresses are formatted at the RN
+boundary; missing or malformed advertised values become `null`. The peripheral
+`id` is unchanged and is never substituted for an absent advertised MAC.
+
 ## Encrypted upload v2
 
 The target encrypted-upload-v2 runtime is an additive `BotaDeviceSDK` API; it
@@ -92,6 +104,57 @@ Its target-facade tests and the maintenance SDK `0.0.67` runtime tests are
 cross-referenced by the same canonical v2 workflow evidence in CI and tagged
 release verification. The frozen public compatibility surface remains `0.0.65`.
 
+### Unpublished Native App Integration
+
+Current source adds `BotaDeviceSDK.recordings.listPendingRecordings(device)`.
+It returns legacy recordings and v2 entries tagged by `storageFormat: 3`, with
+the full UUID/generation, ciphertext length/hash and catalog metadata. Catalog
+errors do not silently downgrade to legacy listing. These changes require
+matching native source and a newly built application; beta.1 is insufficient.
+
+The v2 sync method accepts a fifth argument `{ signal, operationId }`. The
+optional operation ID is a fresh UUID shared with an application-native
+adapter; cancellation stops and awaits that exact operation. Native provider
+contexts expose an operation-scoped `readAuthNonce` callback. An RN application's
+Swift/Kotlin adapter can call
+`BotaDeviceSDKEncryptedUploadV2Materials.readAuthNonce(operationId)` while the
+profile request is pending; it must not make a competing public BLE read.
+
+Native material must supply `uploadContext`, which relays opaque challenge/proof
+documents through the application backend. The SDK owns the bounded device
+handshake before authorization and the first completion receipt. Ordinary v2
+requires capability mask `0x17f`; expired-session replacement requires `0x37f`.
+Neither the app nor SDK verifies backend signatures or trusts the phone clock
+as a substitute for device verification. Cancellation discards late native
+material via `cancelPreparation`; it does not delete recoverable recordings.
+Historical checkpoints without ciphertext identity may resume the same owner
+but cannot authorize replacement. See `docs/parity/v2-demo-*.md` for evidence
+and limitations. Hardware and publication gates remain unchanged.
+
+## Unpublished Maintenance Additions
+
+Current source follows the diagnostic and upload-recovery additions from
+maintenance SDK commit `318974f925a573cf04b0d624978bee04784af09b`. These additions
+are not part of the published `2.0.0-beta.1` package.
+
+- `BotaClient.devices.readDiagnosticEvents(device)` returns a bounded batch.
+  Reading does not delete it. After the application durably accepts events,
+  call `acknowledgeDiagnosticEvents(device, acceptedEventIds)` with their exact
+  16-character lowercase hexadecimal IDs. The native `BotaDeviceSDK.logs` API
+  exposes the same methods. Firmware must support the diagnostics service.
+- Configure `uploadRecoveryProvider` to refresh upload credentials for the
+  original recording and account/project scope after restart. Only non-secret
+  queue metadata persists; recording bytes stay in native files. Completion
+  acknowledgement is required before releasing recoverable files.
+- Legacy `RecordingDataStore` JavaScript byte callbacks are not supported.
+  Supplying one fails configuration explicitly. Use the native file store and
+  credential/completion callbacks instead; this is a migration adaptation,
+  not byte-store API equivalence.
+
+See the repository's `docs/parity/` notes for recovery contracts and test
+coverage. This does not enable encrypted-v2 device support or complete the
+separate physical-device and application rollout gates.
+
 ## Documentation
 
 See [docs.bota.dev](https://docs.bota.dev) for pairing, provisioning,

package/android/build.gradle

@@ -72,5 +72,6 @@ dependencies {
   implementation "${androidMetadata.mavenCoordinate}:${packageVersion}"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:${androidMetadata.coroutinesVersion}"
   testImplementation "junit:junit:4.13.2"
+  testImplementation "org.json:json:20240303"
   testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:${androidMetadata.coroutinesVersion}"
 }

package/android/src/main/java/dev/bota/sdk/reactnative/BotaDeviceSDKAndroidDiagnostics.kt

@@ -0,0 +1,53 @@
+package dev.bota.sdk.reactnative
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import dev.bota.sdk.model.DeviceDiagnosticsBatch
+import dev.bota.sdk.model.DeviceDiagnosticEvent
+
+internal fun DeviceDiagnosticsBatch.toWritableMap(): WritableMap = Arguments.createMap().apply {
+    putInt("schema_version", schemaVersion)
+    putArray("events", Arguments.createArray().apply { events.forEach { pushMap(it.toWritableMap()) } })
+}
+
+private fun DeviceDiagnosticEvent.toWritableMap(): WritableMap = Arguments.createMap().apply {
+    putString("event_id", eventId)
+    putString("event_type", eventType)
+    putString("reason_code", reasonCode)
+    putDouble("uptime_ms", uptimeMs.toDouble())
+    putString("signature", signature)
+    putString("firmware_build_id", firmwareBuildId)
+    putString("subsystem", subsystem)
+    putString("state_before_event", stateBeforeEvent)
+    report?.let { detail ->
+        putMap("report", Arguments.createMap().apply {
+            putMap("fault", Arguments.createMap().apply {
+                putInt("cpu_id", detail.fault.cpuId)
+                putString("cpu_emu", detail.fault.cpuEmu)
+                putString("core_emu", detail.fault.coreEmu)
+                putString("hsb_emu", detail.fault.hsbEmu)
+                putString("audio_emu", detail.fault.audioEmu)
+                putString("wireless_emu", detail.fault.wirelessEmu)
+            })
+            putMap("execution", Arguments.createMap().apply {
+                detail.execution.task?.let { putString("task", it) }
+                detail.execution.reti?.let { putString("reti", it) }
+                detail.execution.rets?.let { putString("rets", it) }
+                putArray("pc_trace", Arguments.createArray().apply { detail.execution.pcTrace.forEach { pushString(it) } })
+            })
+            detail.runtime?.let { runtime ->
+                putMap("runtime", Arguments.createMap().apply {
+                    runtime.heapFreeBytes?.let { putDouble("heap_free_bytes", it.toDouble()) }
+                    runtime.taskStackRemainingBytes?.let { putDouble("task_stack_remaining_bytes", it.toDouble()) }
+                })
+            }
+            detail.breadcrumbs?.let { breadcrumbs ->
+                putArray("breadcrumbs", Arguments.createArray().apply {
+                    breadcrumbs.forEach { pushMap(Arguments.createMap().apply {
+                        putInt("delta_ms", it.deltaMs); putString("code", it.code); putInt("arg0", it.arg0)
+                    }) }
+                })
+            }
+        })
+    }
+}

package/android/src/main/java/dev/bota/sdk/reactnative/BotaDeviceSDKAndroidLogs.kt

@@ -3,6 +3,7 @@ package dev.bota.sdk.reactnative
 import dev.bota.sdk.BotaDeviceClient
 import dev.bota.sdk.model.ConnectedDevice
 import dev.bota.sdk.model.DeviceLogLine
+import dev.bota.sdk.model.DeviceDiagnosticsBatch
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.CoroutineStart
@@ -15,6 +16,8 @@ import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 
 internal interface BotaDeviceSDKAndroidLogClient {
+    suspend fun readDiagnosticEvents(device: ConnectedDevice): DeviceDiagnosticsBatch
+    suspend fun acknowledgeDiagnosticEvents(device: ConnectedDevice, acceptedEventIds: List<String>)
     fun streamLogs(device: ConnectedDevice): Flow<DeviceLogLine>
 
     suspend fun stop()
@@ -29,12 +32,25 @@ internal class BotaDeviceSDKSharedAndroidLogClient(
     override suspend fun stop() {
         client.logs.stop()
     }
+
+    override suspend fun readDiagnosticEvents(device: ConnectedDevice): DeviceDiagnosticsBatch =
+        client.logs.readDiagnosticEvents(device)
+
+    override suspend fun acknowledgeDiagnosticEvents(device: ConnectedDevice, acceptedEventIds: List<String>) {
+        client.logs.acknowledgeDiagnosticEvents(device, acceptedEventIds)
+    }
 }
 
 internal class BotaDeviceSDKAndroidLogs(
     private val client: BotaDeviceSDKAndroidLogClient,
     private val scope: CoroutineScope,
 ) {
+    suspend fun readDiagnosticEvents(device: ConnectedDevice): DeviceDiagnosticsBatch =
+        client.readDiagnosticEvents(device)
+
+    suspend fun acknowledgeDiagnosticEvents(device: ConnectedDevice, acceptedEventIds: List<String>) {
+        client.acknowledgeDiagnosticEvents(device, acceptedEventIds)
+    }
     private val operations = Mutex()
     private val streamLock = Any()
     private var activeStream: Job? = null

package/android/src/main/java/dev/bota/sdk/reactnative/BotaDeviceSDKAndroidRecordingUploads.kt

@@ -5,11 +5,18 @@ import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableMap
 import java.io.File
+import java.io.FileOutputStream
 import java.nio.file.AtomicMoveNotSupportedException
 import java.nio.file.Files
 import java.nio.file.StandardCopyOption
+import java.nio.channels.FileChannel
+import java.nio.file.StandardOpenOption
 import java.util.concurrent.ConcurrentHashMap
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
 import okhttp3.Call
 import okhttp3.MediaType.Companion.toMediaTypeOrNull
@@ -17,6 +24,8 @@ import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.RequestBody.Companion.asRequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
+import org.json.JSONArray
+import org.json.JSONObject
 
 internal data class BotaRecordingUploadRequest(
     val taskId: String,
@@ -29,6 +38,7 @@ internal data class BotaRecordingUploadRequest(
     val contentSha256: String?,
     val relayUrl: String?,
     val relayBearerToken: String?,
+    val fileSizeBytes: Long? = null,
 )
 
 internal data class BotaRecordingUploadProgress(
@@ -40,21 +50,51 @@ internal data class BotaRecordingUploadProgress(
 internal class BotaDeviceSDKAndroidRecordingUploads(
     private val queueFile: File,
     private val httpClient: OkHttpClient = OkHttpClient(),
+    private val defaultRecordingDirectory: File = File(queueFile.parentFile, "recordings"),
+    private val syncDirectory: (File) -> Unit = { directory ->
+        FileChannel.open(directory.toPath(), StandardOpenOption.READ).use { it.force(true) }
+    },
 ) {
     constructor(
         context: Context,
         httpClient: OkHttpClient = OkHttpClient(),
-    ) : this(File(context.filesDir, "bota-sdk/compat-upload-queue.json"), httpClient)
+    ) : this(File(context.filesDir, "bota-sdk/compat-upload-queue.json"), httpClient,
+        File(context.noBackupFilesDir, "bota-app-sdk/recordings"))
 
-    private val calls = ConcurrentHashMap<String, Call>()
+    @Volatile private var recordingDirectory = defaultRecordingDirectory
+
+    fun configure(storageDirectory: File?) {
+        recordingDirectory = storageDirectory?.let { File(it, "recordings") } ?: defaultRecordingDirectory
+    }
+
+    private class Operation {
+        private var cancelled = false
+        private var call: Call? = null
+
+        @Synchronized fun execute(next: Call) {
+            check(!cancelled) { "recording upload cancelled" }
+            call = next
+        }
+
+        @Synchronized fun cancel() { cancelled = true; call?.cancel() }
+        @Synchronized fun checkActive() { check(!cancelled) { "recording upload cancelled" } }
+    }
+
+    private val operations = ConcurrentHashMap<String, Operation>()
+    private val cancelledAttempts = mutableSetOf<String>()
+    private val journalMutex = Mutex()
+    private var journalWriteUncertain = false
 
     suspend fun upload(
         upload: BotaRecordingUploadRequest,
         onProgress: (BotaRecordingUploadProgress) -> Unit,
     ): Unit = withContext(Dispatchers.IO) {
         val file = File(upload.localPath)
+        requireOwnedFile(upload.localPath)
         require(file.isFile) { "recording file does not exist: ${upload.localPath}" }
         val total = file.length()
+        require(upload.fileSizeBytes == null || upload.fileSizeBytes == total) { "stored recording length changed" }
+        currentCoroutineContext().ensureActive()
         onProgress(BotaRecordingUploadProgress(upload.taskId, 0, total))
         val relay = upload.relayUrl != null
         val request = Request.Builder()
@@ -69,15 +109,22 @@ internal class BotaDeviceSDKAndroidRecordingUploads(
             }
             .build()
         val call = httpClient.newCall(request)
-        check(calls.putIfAbsent(upload.taskId, call) == null) {
-            "recording upload is already active: ${upload.taskId}"
+        val operation = Operation()
+        synchronized(operations) {
+            check(upload.taskId !in cancelledAttempts) { "recording upload cancelled" }
+            check(operations.putIfAbsent(upload.taskId, operation) == null) {
+                "recording upload is already active: ${upload.taskId}"
+            }
         }
         try {
+            operation.execute(call)
             call.execute().use { response ->
                 check(response.isSuccessful) {
                     "recording upload failed with HTTP ${response.code}"
                 }
             }
+            currentCoroutineContext().ensureActive()
+            operation.checkActive()
             if (!relay && upload.completeUrl != null && upload.uploadToken != null) {
                 val checksum = upload.contentSha256?.let {
                     ",\"content_sha256\":\"${it.jsonEscaped()}\""
@@ -89,39 +136,86 @@ internal class BotaDeviceSDKAndroidRecordingUploads(
                     .post(body.toRequestBody("application/json".toMediaTypeOrNull()))
                     .build()
                 val completionCall = httpClient.newCall(complete)
-                calls[upload.taskId] = completionCall
+                operation.execute(completionCall)
                 completionCall.execute().use { response ->
                     check(response.isSuccessful) {
                         "recording completion failed with HTTP ${response.code}"
                     }
                 }
             }
+            currentCoroutineContext().ensureActive()
+            operation.checkActive()
             onProgress(BotaRecordingUploadProgress(upload.taskId, total, total))
-            check(file.delete() || !file.exists()) {
-                "uploaded recording file could not be removed"
-            }
         } finally {
-            calls.remove(upload.taskId)
+            operations.remove(upload.taskId, operation)
         }
     }
 
     suspend fun cancel(taskId: String) = withContext(Dispatchers.IO) {
-        calls.remove(taskId)?.cancel()
+        synchronized(operations) {
+            cancelledAttempts.add(taskId)
+            operations[taskId]?.cancel()
+        }
     }
 
     suspend fun cancelAll() = withContext(Dispatchers.IO) {
-        calls.values.forEach(Call::cancel)
-        calls.clear()
+        synchronized(operations) {
+            cancelledAttempts.addAll(operations.keys)
+            operations.values.forEach(Operation::cancel)
+        }
     }
 
     suspend fun loadQueue(): String = withContext(Dispatchers.IO) {
-        if (queueFile.isFile) queueFile.readText() else "[]"
+        journalMutex.withLock {
+            if (!queueFile.isFile) return@withLock "[]"
+            queueFile.readText()
+        }
     }
 
     suspend fun saveQueue(serializedTasks: String): Unit = withContext(Dispatchers.IO) {
+        journalMutex.withLock { writeQueue(metadata(serializedTasks).toString()) }
+    }
+
+    suspend fun release(taskId: String, localPath: String): Unit = withContext(Dispatchers.IO) {
+        journalMutex.withLock {
+            check(!journalWriteUncertain) { "recording release requires durable journal completion" }
+            val tasks = metadata(queueFile.readText())
+            check((0 until tasks.length()).any { index ->
+                val task = tasks.getJSONObject(index)
+                task.optString("id") == taskId && task.optString("localPath") == localPath &&
+                    task.optString("status") == "completed"
+            }) { "recording release requires exact durable completion" }
+            removeCompletedFile(localPath)
+        }
+    }
+
+    private fun removeCompletedFile(path: String) {
+        requireOwnedFile(path)
+        val file = File(path)
+        require(!file.exists() || (file.isFile && !Files.isSymbolicLink(file.toPath()))) { "recording release requires a regular file" }
+        check(file.delete() || !file.exists()) { "completed recording cleanup deferred" }
+        // A missing file may be an earlier unlink whose directory sync failed.
+        syncDirectory(requireNotNull(file.parentFile))
+    }
+
+    private fun requireOwnedFile(path: String) {
+        val file = File(path)
+        require(file.isAbsolute && file.extension == "recording" &&
+            runCatching { java.util.UUID.fromString(file.nameWithoutExtension) }.isSuccess &&
+            file.canonicalFile.parentFile == recordingDirectory.canonicalFile &&
+            !Files.isSymbolicLink(file.toPath()) && (!file.exists() || file.isFile)
+        ) { "recording file is not owned by the native recording store" }
+    }
+
+    private fun writeQueue(serializedTasks: String) {
+        journalWriteUncertain = true
         queueFile.parentFile?.mkdirs()
+        queueFile.parentFile?.parentFile?.let(syncDirectory)
         val temporary = File(queueFile.parentFile, "${queueFile.name}.tmp")
-        temporary.writeText(serializedTasks)
+        FileOutputStream(temporary).use { stream ->
+            stream.write(serializedTasks.toByteArray(Charsets.UTF_8))
+            stream.fd.sync()
+        }
         try {
             Files.move(
                 temporary.toPath(),
@@ -136,6 +230,41 @@ internal class BotaDeviceSDKAndroidRecordingUploads(
                 StandardCopyOption.REPLACE_EXISTING,
             )
         }
+        queueFile.parentFile?.let(syncDirectory)
+        journalWriteUncertain = false
+    }
+
+    private fun metadata(serialized: String): JSONArray {
+        val tasks = JSONArray(serialized)
+        val fields = setOf("id", "recordingId", "deviceId", "recordingUuid", "localPath", "status", "retryCount", "createdAt", "updatedAt", "recoveryScope", "fileSizeBytes", "nextAttemptAt", "contentType", "contentSha256", "relayUpload")
+        val ids = mutableSetOf<String>()
+        return JSONArray().apply {
+            for (index in 0 until tasks.length()) {
+                val task = tasks.getJSONObject(index)
+                require(task.get("id") is String && task.getString("id").isNotEmpty() && ids.add(task.getString("id"))) { "invalid upload recovery journal" }
+                for (key in listOf("recordingId", "deviceId", "localPath", "createdAt", "updatedAt")) require(task.get(key) is String) { "invalid upload recovery journal" }
+                require(task.getString("recordingId").isNotEmpty() && task.getString("deviceId").isNotEmpty()) { "invalid upload recovery journal" }
+                require(validInteger(task.get("retryCount")) && task.getString("status") in setOf("pending", "uploading", "completed", "failed")) { "invalid upload recovery journal" }
+                for (key in listOf("recordingUuid", "recoveryScope", "contentType", "contentSha256")) if (task.has(key)) require(task.get(key) is String) { "invalid upload recovery journal" }
+                for (key in listOf("fileSizeBytes", "nextAttemptAt")) if (task.has(key)) require(validInteger(task.get(key))) { "invalid upload recovery journal" }
+                if (task.has("relayUpload")) require(task.get("relayUpload") is Boolean) { "invalid upload recovery journal" }
+                for (key in listOf("createdAt", "updatedAt")) require(runCatching { java.time.Instant.parse(task.getString(key)) }.isSuccess) { "invalid upload recovery journal" }
+                put(JSONObject().apply {
+                    for (key in fields) if (task.has(key)) {
+                        val value = task.get(key)
+                        require(value is String || value is Number || value is Boolean) { "invalid upload recovery journal" }
+                        put(key, value)
+                    }
+                    put("relayUpload", if (task.has("relayUpload")) task.getBoolean("relayUpload") else task.optJSONObject("relay") != null)
+                })
+            }
+        }
+    }
+
+    private fun validInteger(value: Any): Boolean {
+        if (value !is Number) return false
+        val number = value.toDouble()
+        return number.isFinite() && number >= 0 && number <= 9_007_199_254_740_991.0 && number % 1.0 == 0.0
     }
 }
 
@@ -151,6 +280,7 @@ internal fun ReadableMap.toRecordingUploadRequest(): BotaRecordingUploadRequest
         contentSha256 = optionalString("contentSha256"),
         relayUrl = optionalString("relayUrl"),
         relayBearerToken = optionalString("relayBearerToken"),
+        fileSizeBytes = if (hasKey("fileSizeBytes") && !isNull("fileSizeBytes")) getDouble("fileSizeBytes").toLong() else null,
     )
 
 internal fun BotaRecordingUploadProgress.toWritableMap(): WritableMap =