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

package/src/ble/deviceDiagnostics.ts

@@ -0,0 +1,238 @@
+import { Buffer } from 'buffer';
+
+import {
+  DEVICE_DIAGNOSTICS_EVT_END,
+  DEVICE_DIAGNOSTICS_EVT_DETAIL,
+  DEVICE_DIAGNOSTICS_EVT_META,
+  DEVICE_DIAGNOSTICS_EVT_SIGNATURE,
+} from './constants';
+import type {
+  DeviceDiagnosticEvent,
+  DeviceDiagnosticEventType,
+  DeviceDiagnosticReasonCode,
+  DeviceDiagnosticsBatch,
+} from '../models/Device';
+
+const EVENT_TYPES: Record<number, DeviceDiagnosticEventType> = {
+  1: 'reset', 2: 'watchdog', 3: 'hard_fault', 4: 'storage',
+  5: 'power', 6: 'radio', 7: 'security',
+};
+const REASONS: Record<number, DeviceDiagnosticReasonCode> = {
+  1: 'watchdog_timeout', 2: 'cpu_illegal_instruction',
+  3: 'cpu_misaligned_access', 4: 'cpu_stack_overflow',
+  5: 'cpu_usage_fault', 6: 'memory_protection_fault',
+  7: 'invalid_register_read', 8: 'invalid_register_write',
+  9: 'audio_subsystem_fault', 10: 'wireless_subsystem_fault',
+  11: 'flash_mmu_fault', 12: 'low_voltage_reset',
+  255: 'unknown_cpu_exception',
+};
+const SUBSYSTEMS: Record<number, string> = {
+  0: 'system', 1: 'audio', 2: 'wireless', 3: 'storage',
+  4: 'power', 5: 'security',
+};
+const STATES: Record<number, string> = {
+  0: 'boot', 1: 'deep_standby', 2: 'recording', 3: 'upload_preparing',
+  4: 'uploading', 5: 'error_recovery', 6: 'full_sleep',
+};
+const BREADCRUMBS: Record<number, string> = {
+  1: 'boot', 2: 'standby_entered', 3: 'recording_started',
+  4: 'upload_preparing', 5: 'upload_started', 6: 'error_recovery',
+  7: 'full_sleep',
+};
+const DETAIL_WIRE_SIZE = 176;
+
+function u64LeHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).reverse().toString('hex').padStart(16, '0');
+}
+
+export function diagnosticEventIdCommand(eventId: string): Buffer {
+  if (!/^[0-9a-f]{16}$/.test(eventId)) {
+    throw new Error('Diagnostic event_id must be 16 lowercase hex characters');
+  }
+  return Buffer.concat([
+    Buffer.from([0x11]),
+    Buffer.from(eventId, 'hex').reverse(),
+  ]);
+}
+
+type PartialEvent = Omit<DeviceDiagnosticEvent, 'signature' | 'firmware_build_id' |
+  'subsystem' | 'state_before_event'> & {
+    signature?: string;
+    firmware_build_id?: string;
+    subsystem?: string;
+    state_before_event?: string;
+  };
+
+interface DetailAssembly {
+  buffer: Buffer;
+  received: number;
+}
+
+function normalizedAddress(value: number): string | undefined {
+  if (value === 0) return undefined;
+  const region = (value & 0x80000000) !== 0
+    ? 'sdram'
+    : (value & 0x40000000) !== 0 ? 'ram' : 'rom';
+  const offset = (value & 0x3fffffff).toString(16).padStart(8, '0');
+  return `${region}:${offset}`;
+}
+
+function fixedHex32(value: number): string {
+  return value.toString(16).padStart(8, '0');
+}
+
+function decodeDetail(bytes: Buffer): Pick<DeviceDiagnosticEvent,
+  'firmware_build_id' | 'subsystem' | 'state_before_event' | 'report'> {
+  if (bytes.length !== DETAIL_WIRE_SIZE || bytes[0] !== 1) {
+    throw new Error('Unsupported diagnostic detail payload');
+  }
+  const hasReport = (bytes[1] & 1) !== 0;
+  const firmwareBuildId = Buffer.from(bytes.subarray(2, 14)).toString('ascii');
+  if (!/^[0-9a-f]{12}$/.test(firmwareBuildId)) {
+    throw new Error('Invalid diagnostic firmware build id');
+  }
+  const common = {
+    firmware_build_id: firmwareBuildId,
+    subsystem: SUBSYSTEMS[bytes[14]] ?? 'system',
+    state_before_event: STATES[bytes[15]] ?? 'unknown',
+  };
+  if (!hasReport) return common;
+
+  const pcCount = Math.min(bytes[17], 6);
+  const breadcrumbCount = Math.min(bytes[18], 8);
+  const runtimeMask = bytes[19];
+  const pcTrace: string[] = [];
+  for (let index = 0; index < pcCount; index++) {
+    const address = normalizedAddress(bytes.readUInt32LE(48 + index * 4));
+    if (address) pcTrace.push(address);
+  }
+  const task = Buffer.from(bytes.subarray(80, 96)).toString('ascii').replace(/\0.*$/, '');
+  const breadcrumbs = [];
+  for (let index = 0; index < breadcrumbCount; index++) {
+    const offset = 96 + index * 10;
+    breadcrumbs.push({
+      delta_ms: bytes.readInt32LE(offset),
+      code: BREADCRUMBS[bytes.readUInt16LE(offset + 4)] ?? 'state_changed',
+      arg0: bytes.readInt32LE(offset + 6),
+    });
+  }
+  const reti = normalizedAddress(bytes.readUInt32LE(40));
+  const rets = normalizedAddress(bytes.readUInt32LE(44));
+  return {
+    ...common,
+    report: {
+      fault: {
+        cpu_id: bytes[16],
+        cpu_emu: fixedHex32(bytes.readUInt32LE(20)),
+        core_emu: fixedHex32(bytes.readUInt32LE(24)),
+        hsb_emu: fixedHex32(bytes.readUInt32LE(28)),
+        audio_emu: fixedHex32(bytes.readUInt32LE(32)),
+        wireless_emu: fixedHex32(bytes.readUInt32LE(36)),
+      },
+      execution: {
+        ...(task ? { task } : {}),
+        ...(reti ? { reti } : {}),
+        ...(rets ? { rets } : {}),
+        pc_trace: pcTrace,
+      },
+      ...((runtimeMask & 3) !== 0 ? {
+        runtime: {
+          ...((runtimeMask & 1) !== 0
+            ? { heap_free_bytes: bytes.readUInt32LE(72) } : {}),
+          ...((runtimeMask & 2) !== 0
+            ? { task_stack_remaining_bytes: bytes.readUInt32LE(76) } : {}),
+        },
+      } : {}),
+      ...(breadcrumbs.length ? { breadcrumbs } : {}),
+    },
+  };
+}
+
+export class DeviceDiagnosticsDecoder {
+  private events = new Map<number, PartialEvent>();
+  private details = new Map<number, DetailAssembly>();
+
+  push(packet: Buffer): DeviceDiagnosticsBatch | null {
+    if (packet.length === 17 && packet[0] === DEVICE_DIAGNOSTICS_EVT_META) {
+      const type = EVENT_TYPES[packet[2]];
+      if (!type) return null;
+      this.events.set(packet[1], {
+        event_id: u64LeHex(packet.subarray(9, 17)),
+        event_type: type,
+        reason_code: REASONS[packet.readUInt16LE(3)] ?? 'unknown_cpu_exception',
+        uptime_ms: packet.readUInt32LE(5),
+      });
+      return null;
+    }
+    if (packet.length === 10 && packet[0] === DEVICE_DIAGNOSTICS_EVT_SIGNATURE) {
+      const event = this.events.get(packet[1]);
+      if (event) event.signature = u64LeHex(packet.subarray(2, 10));
+      return null;
+    }
+    if (packet.length >= 6 && packet.length <= 20 &&
+        packet[0] === DEVICE_DIAGNOSTICS_EVT_DETAIL) {
+      const index = packet[1];
+      const offset = packet.readUInt16LE(2);
+      const total = packet.readUInt16LE(4);
+      if (total !== DETAIL_WIRE_SIZE || offset + packet.length - 6 > total) {
+        this.reset();
+        throw new Error('Invalid diagnostic detail chunk');
+      }
+      let detail = this.details.get(index);
+      if (offset === 0) {
+        if (detail) {
+          this.reset();
+          throw new Error(`Duplicate diagnostic detail at index ${index}`);
+        }
+        detail = { buffer: Buffer.alloc(total), received: 0 };
+        this.details.set(index, detail);
+      }
+      if (!detail || detail.received !== offset) {
+        this.reset();
+        throw new Error(`Out-of-order diagnostic detail at index ${index}`);
+      }
+      packet.copy(detail.buffer, offset, 6);
+      detail.received += packet.length - 6;
+      if (detail.received === total) {
+        const event = this.events.get(index);
+        if (!event) {
+          this.reset();
+          throw new Error(`Diagnostic detail without metadata at index ${index}`);
+        }
+        try {
+          Object.assign(event, decodeDetail(detail.buffer));
+        } catch (error) {
+          this.reset();
+          throw error;
+        }
+      }
+      return null;
+    }
+    if (packet.length === 2 && packet[0] === DEVICE_DIAGNOSTICS_EVT_END) {
+      const expected = packet[1];
+      const events: DeviceDiagnosticEvent[] = [];
+      for (let index = 0; index < expected; index++) {
+        const event = this.events.get(index);
+        if (!event?.signature || !event.firmware_build_id ||
+            !event.subsystem || !event.state_before_event ||
+            this.details.get(index)?.received !== DETAIL_WIRE_SIZE) {
+          this.reset();
+          throw new Error(`Incomplete diagnostic event at index ${index}`);
+        }
+        events.push(event as DeviceDiagnosticEvent);
+      }
+      const batch: DeviceDiagnosticsBatch = {
+        schema_version: 1,
+        events,
+      };
+      this.reset();
+      return batch;
+    }
+    return null;
+  }
+
+  reset(): void {
+    this.events.clear();
+    this.details.clear();
+  }
+}

package/src/client.ts

@@ -1,4 +1,5 @@
 import type {
+  NativeClientContext,
   NativeCapabilities,
   NativeConnectedDevice,
   NativeConfiguration,
@@ -10,6 +11,7 @@ import type {
   NativeEncryptedUploadV2Checkpoint,
   NativeEncryptedUploadV2Progress,
   NativeEncryptedUploadV2Recording,
+  NativePendingRecording,
   NativeFactoryResetCompletion,
   NativeFactoryResetGrantRequest,
   NativeFirmwareUpdateProgress,
@@ -28,6 +30,12 @@ import type {
   NativeDeviceWiFiScanResult,
   Spec,
 } from './specs/NativeBotaDeviceSDK';
+import { SDK_PACKAGE, SDK_VERSION } from './sdkIdentity';
+
+export type BotaClientPresenceContext = NativeClientContext;
+export type BotaClientPresence = {
+  nextReport(deviceId: string): Promise<BotaClientPresenceContext | null>;
+};
 import type {
   ConnectedDevice,
   ConnectionType,
@@ -37,6 +45,9 @@ import type {
   DeviceStatus,
   DeviceType,
   DeviceLogEvent,
+  DeviceDiagnosticEventType,
+  DeviceDiagnosticReasonCode,
+  DeviceDiagnosticsBatch,
   DiscoveredDevice,
   PairingState,
   ReconnectOptions,
@@ -195,11 +206,24 @@ export type BotaRecordingTransferProgress = {
 
 export type BotaEncryptedUploadV2Recording = NativeEncryptedUploadV2Recording;
 
+export type BotaEncryptedUploadV2PendingRecording = Omit<BotaEncryptedUploadV2Recording, 'durationMs'> & {
+  storageFormat: 3;
+  startedAt: Date;
+  durationMs: number;
+  plaintextLength: string;
+};
+
+export type BotaEncryptedUploadV2SyncOptions = {
+  signal?: AbortSignal;
+  operationId?: string;
+};
+
 export type BotaEncryptedUploadV2Capability = NativeEncryptedUploadV2Capability;
 
 export type BotaEncryptedUploadV2Checkpoint = NativeEncryptedUploadV2Checkpoint;
 
 export type BotaEncryptedUploadV2ProviderContext = {
+  operationId: string;
   recording: BotaEncryptedUploadV2Recording;
   capability: BotaEncryptedUploadV2Capability;
   checkpoint?: BotaEncryptedUploadV2Checkpoint;
@@ -287,6 +311,8 @@ export type BotaDeviceSDKOTAClient = {
 };
 
 export type BotaDeviceSDKLogClient = {
+  readDiagnosticEvents(device: ConnectedDevice): Promise<DeviceDiagnosticsBatch>;
+  acknowledgeDiagnosticEvents(device: ConnectedDevice, acceptedEventIds: string[]): Promise<void>;
   subscribe(
     device: ConnectedDevice,
     onLine: (line: DeviceLogEvent) => void
@@ -310,6 +336,7 @@ export type BotaDeviceSDKWiFiClient = {
 
 export type BotaDeviceSDKRecordingClient = {
   listRecordings(device: ConnectedDevice): Promise<DeviceRecording[]>;
+  listPendingRecordings(device: ConnectedDevice): Promise<Array<DeviceRecording | BotaEncryptedUploadV2PendingRecording>>;
   syncRecording(
     device: ConnectedDevice,
     recording: DeviceRecording,
@@ -319,12 +346,14 @@ export type BotaDeviceSDKRecordingClient = {
     localPath: string;
     e2eEncrypted: boolean;
     contentSha256?: string;
+    fileSizeBytes: number;
   }>;
   syncEncryptedRecordingV2(
     device: ConnectedDevice,
     recording: BotaEncryptedUploadV2Recording,
     provider: BotaEncryptedUploadV2ProfileProvider,
-    onProgress?: (progress: BotaEncryptedUploadV2Progress) => void
+    onProgress?: (progress: BotaEncryptedUploadV2Progress) => void,
+    options?: BotaEncryptedUploadV2SyncOptions
   ): Promise<void>;
   confirmRecording(
     device: ConnectedDevice,
@@ -335,6 +364,7 @@ export type BotaDeviceSDKRecordingClient = {
     onProgress?: (progress: BotaRecordingTransferProgress) => void
   ): Promise<void>;
   cancelRecordingUpload(taskId: string): Promise<void>;
+  releaseRecordingFile(taskId: string, localPath: string): Promise<void>;
   loadUploadQueue(): Promise<UploadTask[]>;
   saveUploadQueue(tasks: UploadTask[]): Promise<void>;
   destroyCompatibilityOperations(): Promise<void>;
@@ -410,6 +440,7 @@ export class BotaNativeModuleError extends Error {
 }
 
 export type BotaDeviceSDKClient = {
+  readonly clientPresence: BotaClientPresence;
   readonly controls: BotaDeviceSDKControlClient;
   readonly devices: BotaDeviceSDKDeviceClient;
   readonly factoryReset: BotaDeviceSDKFactoryResetClient;
@@ -425,6 +456,13 @@ export type BotaDeviceSDKClient = {
   getState(): Promise<BotaDeviceSDKState>;
 };
 
+const formatAdvertisedMac = (value: string | undefined): string | null => {
+  if (!value || !/^(?:[0-9a-f]{12}|(?:[0-9a-f]{2}:){5}[0-9a-f]{2})$/i.test(value)) {
+    return null;
+  }
+  return value.replace(/:/g, '').toUpperCase().match(/.{2}/g)!.join(':');
+};
+
 const mapDiscoveredDevice = (
   device: NativeDiscoveredDevice
 ): DiscoveredDevice => ({
@@ -432,7 +470,7 @@ const mapDiscoveredDevice = (
   name: device.name ?? '',
   deviceType: (device.deviceType ?? 'bota_pin') as DeviceType,
   firmwareVersion: device.firmwareVersion ?? '',
-  macAddress: device.macAddress ?? null,
+  macAddress: formatAdvertisedMac(device.macAddress),
   pairingState: (device.pairingState ?? 'unpaired') as PairingState,
   rssi: device.rssi,
   discoveredAt: new Date(device.discoveredAtMs),
@@ -484,6 +522,48 @@ const createOpaqueId = (): string =>
     return nibble.toString(16);
   });
 
+const catalogInteger = (value: string | undefined, maximum = BigInt(Number.MAX_SAFE_INTEGER)): number => {
+  if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,19})$/.test(value) || BigInt(value) > maximum) {
+    throw new Error('invalid native recording catalog metadata');
+  }
+  return Number(value);
+};
+
+const mapPendingRecording = (value: NativePendingRecording): DeviceRecording | BotaEncryptedUploadV2PendingRecording => {
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+  if (value.profile === 'legacy' && value.legacy && !value.encrypted) {
+    const recording = value.legacy;
+    if (typeof recording.uuid !== 'string' || !uuidPattern.test(recording.uuid) ||
+        !Number.isSafeInteger(recording.startedAtMs) || recording.startedAtMs < 0 || recording.startedAtMs > 8640000000000000 ||
+        !Number.isSafeInteger(recording.durationMs) || recording.durationMs < 0 ||
+        !Number.isSafeInteger(recording.fileSize) || recording.fileSize < 0 ||
+        typeof recording.codec !== 'string' || typeof recording.isEncrypted !== 'boolean') {
+      throw new Error('invalid native recording catalog metadata');
+    }
+    return mapRecording(recording);
+  }
+  if (value.profile !== 'encrypted_upload_v2' || !value.encrypted || value.legacy) {
+    throw new Error('invalid native recording catalog profile');
+  }
+  const recording = value.encrypted;
+  const plaintextLength = recording.plaintextLength;
+  if (typeof recording.uuid !== 'string' || !uuidPattern.test(recording.uuid) ||
+      recording.storageFormat !== 3 || typeof plaintextLength !== 'string' ||
+      !/^(0|[1-9][0-9]{0,19})$/.test(plaintextLength) || BigInt(plaintextLength) > 0xffffffffffffffffn ||
+      typeof recording.ciphertextLength !== 'string' || !/^[1-9][0-9]{0,19}$/.test(recording.ciphertextLength) || BigInt(recording.ciphertextLength) > 0xffffffffffffffffn ||
+      typeof recording.ciphertextSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(recording.ciphertextSha256) ||
+      !Number.isInteger(recording.generation) || recording.generation < 0 || recording.generation > 0xffffffff) {
+    throw new Error('invalid native recording catalog identity');
+  }
+  return {
+    uuid: recording.uuid, generation: recording.generation,
+    ciphertextLength: recording.ciphertextLength, ciphertextSha256: recording.ciphertextSha256,
+    storageFormat: 3, plaintextLength, startedAtMs: recording.startedAtMs,
+    startedAt: new Date(catalogInteger(recording.startedAtMs, 8640000000000000n)),
+    durationMs: catalogInteger(recording.durationMs),
+  };
+};
+
 const bytesToHex = (value: Uint8Array): string =>
   Array.from(value, (byte) => byte.toString(16).padStart(2, '0')).join('');
 
@@ -710,6 +790,7 @@ const toNativeRecordingUploadRequest = (
   recordingId: task.recordingId,
   deviceId: task.deviceId,
   localPath: task.localPath,
+  ...(task.fileSizeBytes === undefined ? {} : { fileSizeBytes: task.fileSizeBytes }),
   uploadUrl: task.uploadUrl,
   ...(task.uploadToken ? { uploadToken: task.uploadToken } : {}),
   ...(task.completeUrl ? { completeUrl: task.completeUrl } : {}),
@@ -724,9 +805,13 @@ const toNativeRecordingUploadRequest = (
 });
 
 const parseUploadQueue = (serialized: string): UploadTask[] => {
-  const value: unknown = JSON.parse(serialized || '[]');
-  if (!Array.isArray(value)) return [];
+  const value: unknown = JSON.parse(serialized);
+  if (!Array.isArray(value)) throw new Error('Invalid upload recovery journal');
   return value.map((task) => {
+    if (!task || typeof task !== 'object' || Array.isArray(task) ||
+        typeof task.createdAt !== 'string' || typeof task.updatedAt !== 'string') {
+      throw new Error('Invalid upload recovery journal');
+    }
     const candidate = task as UploadTask & {
       createdAt: string | Date;
       updatedAt: string | Date;
@@ -740,6 +825,8 @@ const parseUploadQueue = (serialized: string): UploadTask[] => {
 };
 
 export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKClient => {
+  let presenceStopped = false;
+  let presenceGeneration = 0;
   const requireNativeModule = (): Spec => {
     if (!nativeModule) throw new BotaNativeModuleError();
     return nativeModule;
@@ -1056,6 +1143,11 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
       return values.map(mapRecording);
     },
 
+    async listPendingRecordings(device) {
+      const values = await requireNativeModule().listPendingRecordings(toNativeConnectedDevice(device));
+      return values.map(mapPendingRecording);
+    },
+
     async syncRecording(device, recording, onProgress, sinkId) {
       const module = requireNativeModule();
       const subscription = module.onRecordingTransferProgress((progress) => {
@@ -1072,21 +1164,48 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
       }
     },
 
-    async syncEncryptedRecordingV2(device, recording, provider, onProgress) {
+    async syncEncryptedRecordingV2(device, recording, provider, onProgress, options = {}) {
+      if (options.signal?.aborted) throw new Error('encrypted upload v2 cancelled');
       const module = requireNativeModule();
-      const operationId = createOpaqueId();
-      const profileSubscription = module.onEncryptedUploadV2ProfileRequested(
+      const operationId = options.operationId ?? createOpaqueId();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(operationId)) {
+        throw new Error('invalid encrypted upload v2 operation ID');
+      }
+      let active = true;
+      let nativeStarted = false;
+      let cancellation: Promise<void> | undefined;
+      let cancellationFailed = false;
+      const cancel = () => {
+        if (nativeStarted && !cancellation) {
+          try {
+            cancellation = module.cancelEncryptedRecordingV2(operationId).catch(() => { cancellationFailed = true; });
+          } catch {
+            cancellationFailed = true;
+          }
+        }
+      };
+      let profileSubscription: BotaEventSubscription | undefined;
+      let progressSubscription: BotaEventSubscription | undefined;
+      try {
+        options.signal?.addEventListener('abort', cancel, { once: true });
+        profileSubscription = module.onEncryptedUploadV2ProfileRequested(
         (request) => {
-          if (request.operationId !== operationId) return;
+          if (!active || options.signal?.aborted || request.operationId !== operationId) return;
           void (async () => {
+            let decision: BotaEncryptedUploadV2ProfileDecision | undefined;
             try {
-              const decision = await provider({
+              decision = await provider({
+                operationId,
                 recording: request.recording,
                 capability: request.capability,
                 ...(request.checkpoint === undefined
                   ? {}
                   : { checkpoint: request.checkpoint }),
               });
+              if (!active || options.signal?.aborted) {
+                await module.releaseEncryptedUploadV2Material(decision.materialRegistrationId);
+                return;
+              }
               if (decision.profile !== 'encrypted_upload_v2') {
                 throw new Error('encrypted upload v2 requires an explicit v2 profile');
               }
@@ -1095,29 +1214,40 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
                 decision
               );
             } catch (error) {
-              await module.rejectEncryptedUploadV2Profile(
-                request.requestId,
-                'application_material_rejected'
-              );
+              if (decision) await module.releaseEncryptedUploadV2Material(decision.materialRegistrationId).catch(() => {});
+              if (active && !options.signal?.aborted) {
+                await module.rejectEncryptedUploadV2Profile(request.requestId, 'application_material_rejected');
+              }
             }
           })().catch(() => {});
         }
       );
-      const progressSubscription = module.onEncryptedUploadV2Progress(
+      progressSubscription = module.onEncryptedUploadV2Progress(
         (progress) => {
-          if (progress.operationId !== operationId) return;
+          if (!active || options.signal?.aborted || progress.operationId !== operationId) return;
           onProgress?.(mapEncryptedUploadV2Progress(progress));
         }
       );
-      try {
+        if (options.signal?.aborted) throw new Error('encrypted upload v2 cancelled');
+        nativeStarted = true;
         await module.syncEncryptedRecordingV2(
           toNativeConnectedDevice(device),
           recording,
           operationId
         );
       } finally {
-        profileSubscription.remove();
-        progressSubscription.remove();
+        active = false;
+        let cleanupFailed = false;
+        for (const remove of [
+          () => options.signal?.removeEventListener('abort', cancel),
+          () => profileSubscription?.remove(),
+          () => progressSubscription?.remove(),
+        ]) {
+          try { remove(); } catch { cleanupFailed = true; }
+        }
+        await cancellation;
+        if (cancellationFailed) throw new Error('encrypted upload v2 cancellation failed');
+        if (cleanupFailed) throw new Error('encrypted upload v2 listener cleanup failed');
       }
     },
 
@@ -1148,6 +1278,10 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
       await requireNativeModule().cancelRecordingUpload(taskId);
     },
 
+    async releaseRecordingFile(taskId, localPath) {
+      await requireNativeModule().releaseRecordingFile(taskId, localPath);
+    },
+
     async loadUploadQueue() {
       return parseUploadQueue(
         await requireNativeModule().loadCompatibilityUploadQueue()
@@ -1278,6 +1412,30 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
   };
 
   const logs: BotaDeviceSDKLogClient = {
+    async readDiagnosticEvents(device) {
+      const batch = await requireNativeModule().readDiagnosticEvents(toNativeConnectedDevice(device));
+      if (batch.schema_version !== 1) throw new Error('Unsupported diagnostic batch schema');
+      return {
+        schema_version: 1,
+        events: batch.events.map(({ report, ...event }) => ({
+          ...event,
+          event_type: event.event_type as DeviceDiagnosticEventType,
+          reason_code: event.reason_code as DeviceDiagnosticReasonCode,
+          ...(report ? { report: {
+            fault: report.fault,
+            execution: { ...report.execution, pc_trace: [...report.execution.pc_trace] },
+            ...(report.runtime ? { runtime: report.runtime } : {}),
+            ...(report.breadcrumbs ? { breadcrumbs: [...report.breadcrumbs] } : {}),
+          } } : {}),
+        })),
+      };
+    },
+    async acknowledgeDiagnosticEvents(device, acceptedEventIds) {
+      if (acceptedEventIds.some((id) => !/^[0-9a-f]{16}$/.test(id))) {
+        throw new Error('Diagnostic event_id must be 16 lowercase hex characters');
+      }
+      await requireNativeModule().acknowledgeDiagnosticEvents(toNativeConnectedDevice(device), [...acceptedEventIds]);
+    },
     async subscribe(device, onLine) {
       const module = requireNativeModule();
       const eventSubscription = module.onDeviceLog((line) => {
@@ -1365,6 +1523,15 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
   };
 
   const client: BotaDeviceSDKClient = {
+    clientPresence: {
+      async nextReport(deviceId) {
+        if (presenceStopped) return null;
+        const generation = presenceGeneration;
+        const report = await requireNativeModule().nextClientPresence(deviceId);
+        if (presenceStopped || generation !== presenceGeneration) return null;
+        return report === null ? null : { ...report, sdkPackage: SDK_PACKAGE, sdkVersion: SDK_VERSION };
+      },
+    },
     controls,
     devices,
     factoryReset,
@@ -1376,6 +1543,7 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
     wifi,
 
     async configure(configuration = {}) {
+      const generation = presenceGeneration;
       const nativeConfiguration: NativeConfiguration = {
         logLevel: configuration.logLevel ?? 'warn',
         ...(configuration.applicationSupportDirectory
@@ -1386,9 +1554,12 @@ export const createBotaDeviceSDK = (nativeModule: Spec | null): BotaDeviceSDKCli
           : {}),
       };
       await requireNativeModule().configure(nativeConfiguration);
+      if (generation === presenceGeneration) presenceStopped = false;
     },
 
     async destroy() {
+      presenceStopped = true;
+      presenceGeneration++;
       await requireNativeModule().destroy();
     },
 

package/src/clientPresence.ts

@@ -0,0 +1,33 @@
+/** Optional diagnostics, not device attestation or command authority. */
+export interface SdkClientContext {
+  schema_version: 1;
+  session_id: string;
+  sequence: number;
+  platform: 'ios' | 'android';
+  sdk_package: string;
+  sdk_version: string;
+}
+
+export interface ClientPresence {
+  nextReport(deviceId: string): Promise<SdkClientContext | null>;
+}
+
+/** Read fresh BLE status only while the same verified connection and host scope survive.
+ * The caller owns authentication, binding generation, scheduling and HTTP.
+ * Unavailable presence or a changed scope/session skips reporting without BLE writes.
+ */
+export async function readClientPresenceObservation<T>(options: {
+  presence: ClientPresence;
+  deviceId: string;
+  isCurrent(): boolean;
+  readStatus(): Promise<T>;
+}): Promise<{ status: T; clientContext: SdkClientContext } | null> {
+  if (!options.isCurrent()) return null;
+  const before = await options.presence.nextReport(options.deviceId);
+  if (!before || !options.isCurrent()) return null;
+  const status = await options.readStatus();
+  if (!options.isCurrent()) return null;
+  const after = await options.presence.nextReport(options.deviceId);
+  if (!after || !options.isCurrent() || before.session_id !== after.session_id) return null;
+  return { status, clientContext: after };
+}