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

package/src/managers/uploadRecoveryMetadata.ts

@@ -0,0 +1,59 @@
+import type { UploadTask } from '../models/Recording';
+
+const invalid = (): never => { throw new Error('Invalid upload recovery journal'); };
+
+/** Whitelist, never spread a runtime object into persistent storage. */
+export function persistedUploadQueue(tasks: UploadTask[]): UploadTask[] {
+  return tasks.map((task) => ({
+    id: task.id,
+    recordingId: task.recordingId,
+    deviceId: task.deviceId,
+    localPath: task.localPath,
+    uploadUrl: '',
+    status: task.status,
+    retryCount: task.retryCount,
+    createdAt: new Date(task.createdAt),
+    updatedAt: new Date(task.updatedAt),
+    ...(task.recordingUuid === undefined ? {} : { recordingUuid: task.recordingUuid }),
+    ...(task.recoveryScope === undefined ? {} : { recoveryScope: task.recoveryScope }),
+    ...(task.fileSizeBytes === undefined ? {} : { fileSizeBytes: task.fileSizeBytes }),
+    ...(task.nextAttemptAt === undefined ? {} : { nextAttemptAt: task.nextAttemptAt }),
+    ...(task.contentType === undefined ? {} : { contentType: task.contentType }),
+    ...(task.contentSha256 === undefined ? {} : { contentSha256: task.contentSha256 }),
+    relayUpload: task.relayUpload ?? !!task.relay,
+  }));
+}
+
+export function restoreUploadQueue(value: unknown): UploadTask[] {
+  if (!Array.isArray(value)) return invalid();
+  const ids = new Set<string>();
+  const validated = value.map((entry): UploadTask => {
+    if (!entry || typeof entry !== 'object') return invalid();
+    const task = entry as UploadTask;
+    for (const field of ['id', 'recordingId', 'deviceId'] as const) {
+      if (typeof task[field] !== 'string' || !task[field]) return invalid();
+    }
+    if (typeof task.localPath !== 'string' || ids.has(task.id)) return invalid();
+    ids.add(task.id);
+    if (!['pending', 'uploading', 'failed', 'completed'].includes(task.status)) return invalid();
+    if (!Number.isSafeInteger(task.retryCount) || task.retryCount < 0) return invalid();
+    for (const field of ['recordingUuid', 'recoveryScope', 'contentType', 'contentSha256'] as const) {
+      if (task[field] !== undefined && typeof task[field] !== 'string') return invalid();
+    }
+    for (const field of ['fileSizeBytes', 'nextAttemptAt'] as const) {
+      if (task[field] !== undefined && (!Number.isSafeInteger(task[field]) || task[field]! < 0)) return invalid();
+    }
+    if (task.relayUpload !== undefined && typeof task.relayUpload !== 'boolean') return invalid();
+    const createdAt = new Date(task.createdAt);
+    const updatedAt = new Date(task.updatedAt);
+    if (!Number.isFinite(createdAt.getTime()) || !Number.isFinite(updatedAt.getTime())) return invalid();
+    return { ...task, createdAt, updatedAt, status: task.status === 'uploading' ? 'pending' : task.status };
+  });
+  return persistedUploadQueue(validated);
+}
+
+export function rejectRecordingDataStore(value: unknown): void {
+  if (value !== undefined) {
+    throw new Error('RecordingDataStore byte callbacks are unsupported; recording files are native-owned');
+  }
+}

package/src/models/Device.ts

@@ -199,6 +199,49 @@ export interface DeviceLogEvent {
   isBacklog: boolean;
 }
 
+export type DeviceDiagnosticEventType =
+  | 'reset' | 'watchdog' | 'hard_fault' | 'storage'
+  | 'power' | 'radio' | 'security';
+
+export type DeviceDiagnosticReasonCode =
+  | 'watchdog_timeout' | 'cpu_illegal_instruction'
+  | 'cpu_misaligned_access' | 'cpu_stack_overflow'
+  | 'cpu_usage_fault' | 'memory_protection_fault'
+  | 'invalid_register_read' | 'invalid_register_write'
+  | 'audio_subsystem_fault' | 'wireless_subsystem_fault'
+  | 'flash_mmu_fault' | 'low_voltage_reset'
+  | 'unknown_cpu_exception';
+
+/** A retained device fault. Reading does not acknowledge or delete it. */
+export interface DeviceDiagnosticEvent {
+  event_id: string;
+  event_type: DeviceDiagnosticEventType;
+  reason_code: DeviceDiagnosticReasonCode;
+  uptime_ms: number;
+  signature: string;
+  firmware_build_id: string;
+  subsystem: string;
+  state_before_event: string;
+  report?: {
+    fault: {
+      cpu_id: number;
+      cpu_emu: string;
+      core_emu: string;
+      hsb_emu: string;
+      audio_emu: string;
+      wireless_emu: string;
+    };
+    execution: { task?: string; reti?: string; rets?: string; pc_trace: string[] };
+    runtime?: { heap_free_bytes?: number; task_stack_remaining_bytes?: number };
+    breadcrumbs?: Array<{ delta_ms: number; code: string; arg0: number }>;
+  };
+}
+
+export interface DeviceDiagnosticsBatch {
+  schema_version: 1;
+  events: DeviceDiagnosticEvent[];
+}
+
 /**
  * Storage information from device
  */

package/src/models/Recording.ts

@@ -30,6 +30,20 @@ export interface DeviceRecording {
  * (obtained by calling customer's API, not Bota API directly)
  */
 export interface UploadInfo {
+  /** Non-secret account/project/environment identity. Must match during recovery. */
+  recoveryScope?: string;
+  /** Skip sending the object; complete must still acknowledge host durability. */
+  alreadyUploaded?: boolean;
+  /** Resolve only after the backend durably acknowledges this exact recording. */
+  complete?: (context: {
+    fileSizeBytes: number;
+    contentSha256?: string;
+    signal: AbortSignal;
+  }) => Promise<void>;
+  /** Aborted by the host when this authorization context becomes invalid. */
+  signal?: AbortSignal;
+  /** Releases host listeners/leases after the attempt, including cancellation. */
+  dispose?: () => void;
   /** Pre-signed S3 URL for upload */
   uploadUrl: string;
   /** Recording ID assigned by Bota API (rec_*) */
@@ -55,6 +69,37 @@ export interface UploadInfo {
   };
 }
 
+/** Maintenance compatibility shape only. JS byte stores are unsupported by the
+ * native-owned facade; supplying one throws before native configuration. */
+export interface RecordingDataStore {
+  saveRecordingData(input: {
+    deviceId: string;
+    recordingUuid: string;
+    data: Uint8Array;
+  }): Promise<string>;
+  loadRecordingData(localPath: string): Promise<Uint8Array>;
+  deleteRecordingData(localPath: string): Promise<void>;
+}
+
+/** Metadata only. The host must refresh credentials for this exact identity. */
+export interface UploadRecoveryContext {
+  taskId: string;
+  recordingId: string;
+  deviceId: string;
+  recordingUuid: string;
+  recoveryScope?: string;
+  fileSizeBytes?: number;
+  relayUpload: boolean;
+  contentType?: string;
+  contentSha256?: string;
+  signal: AbortSignal;
+}
+
+/** Null parks an unavailable account without consuming the retry budget. */
+export type UploadRecoveryProvider = (
+  context: UploadRecoveryContext
+) => Promise<UploadInfo | null>;
+
 /**
  * Sync progress stages
  */
@@ -102,6 +147,13 @@ export type UploadTaskStatus = 'pending' | 'uploading' | 'completed' | 'failed';
  * Upload task in the queue
  */
 export interface UploadTask {
+  recordingUuid?: string;
+  recoveryScope?: string;
+  fileSizeBytes?: number;
+  relayUpload?: boolean;
+  nextAttemptAt?: number;
+  /** Volatile compatibility field; never included in queue persistence. */
+  complete?: UploadInfo['complete'];
   /** Unique task identifier */
   id: string;
   /** Recording ID from Bota API */

package/src/models/Status.ts

@@ -3,7 +3,7 @@
  */
 
 import type { DeviceStatus, StorageInfo } from './Device';
-import type { SyncProgress, UploadTask } from './Recording';
+import type { RecordingDataStore, SyncProgress, UploadRecoveryProvider, UploadTask } from './Recording';
 
 /**
  * SDK log level
@@ -14,6 +14,10 @@ export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
  * SDK configuration options
  */
 export interface BotaConfig {
+  /** Refreshes credentials for retained native recordings after restart. */
+  uploadRecoveryProvider?: UploadRecoveryProvider;
+  /** Unsupported compatibility option: byte callbacks cannot cross the bridge. */
+  recordingDataStore?: RecordingDataStore;
   /** Environment for API endpoint (development, gamma, or production) */
   environment?: 'development' | 'gamma' | 'production';
   /** Enable background sync (default: true) */

package/src/specs/NativeBotaDeviceSDK.ts

@@ -156,6 +156,16 @@ export type NativeEncryptedUploadV2Recording = {
   generation: number;
   ciphertextLength: string;
   ciphertextSha256: string;
+  startedAtMs?: string;
+  durationMs?: string;
+  plaintextLength?: string;
+  storageFormat?: number;
+};
+
+export type NativePendingRecording = {
+  profile: string;
+  legacy?: NativeDeviceRecording;
+  encrypted?: NativeEncryptedUploadV2Recording;
 };
 
 export type NativeEncryptedUploadV2Capability = {
@@ -223,6 +233,7 @@ export type NativeRecordingTransferResult = {
   localPath: string;
   e2eEncrypted: boolean;
   contentSha256?: string;
+  fileSizeBytes: number;
 };
 
 export type NativeRecordingUploadProgress = {
@@ -236,6 +247,7 @@ export type NativeRecordingUploadRequest = {
   recordingId: string;
   deviceId: string;
   localPath: string;
+  fileSizeBytes?: number;
   uploadUrl: string;
   uploadToken?: string;
   completeUrl?: string;
@@ -329,6 +341,44 @@ export type NativeDeviceLogLine = {
   isBacklog: boolean;
 };
 
+export type NativeDiagnosticFault = {
+  cpu_id: number;
+  cpu_emu: string;
+  core_emu: string;
+  hsb_emu: string;
+  audio_emu: string;
+  wireless_emu: string;
+};
+export type NativeDiagnosticExecution = {
+  task?: string;
+  reti?: string;
+  rets?: string;
+  pc_trace: ReadonlyArray<string>;
+};
+export type NativeDiagnosticRuntime = {
+  heap_free_bytes?: number;
+  task_stack_remaining_bytes?: number;
+};
+export type NativeDiagnosticBreadcrumb = { delta_ms: number; code: string; arg0: number };
+export type NativeDiagnosticReport = {
+  fault: NativeDiagnosticFault;
+  execution: NativeDiagnosticExecution;
+  runtime?: NativeDiagnosticRuntime;
+  breadcrumbs?: ReadonlyArray<NativeDiagnosticBreadcrumb>;
+};
+export type NativeDiagnosticEvent = {
+  event_id: string;
+  event_type: string;
+  reason_code: string;
+  uptime_ms: number;
+  signature: string;
+  firmware_build_id: string;
+  subsystem: string;
+  state_before_event: string;
+  report?: NativeDiagnosticReport;
+};
+export type NativeDiagnosticsBatch = { schema_version: number; events: ReadonlyArray<NativeDiagnosticEvent> };
+
 export type NativeWiFiConfigResult = {
   success: boolean;
   error?: string;
@@ -480,6 +530,8 @@ export interface Spec extends TurboModule {
   startWiFiStatusUpdates: (device: NativeConnectedDevice) => Promise<void>;
   startDeviceLogs: (device: NativeConnectedDevice) => Promise<void>;
   stopDeviceLogs: () => Promise<void>;
+  readDiagnosticEvents: (device: NativeConnectedDevice) => Promise<NativeDiagnosticsBatch>;
+  acknowledgeDiagnosticEvents: (device: NativeConnectedDevice, acceptedEventIds: ReadonlyArray<string>) => Promise<void>;
   stopStatusUpdates: () => Promise<void>;
   stopWiFiStatusUpdates: () => Promise<void>;
   stopScan: () => Promise<void>;
@@ -493,6 +545,9 @@ export interface Spec extends TurboModule {
     recording: NativeEncryptedUploadV2Recording,
     operationId: string
   ) => Promise<void>;
+  listPendingRecordings: (device: NativeConnectedDevice) => Promise<ReadonlyArray<NativePendingRecording>>;
+  cancelEncryptedRecordingV2: (operationId: string) => Promise<void>;
+  releaseEncryptedUploadV2Material: (materialRegistrationId: string) => Promise<void>;
   resolveEncryptedUploadV2Profile: (
     requestId: string,
     decision: NativeEncryptedUploadV2ProfileDecision
@@ -507,6 +562,7 @@ export interface Spec extends TurboModule {
   ) => Promise<void>;
   uploadRecordingFile: (request: NativeRecordingUploadRequest) => Promise<void>;
   cancelRecordingUpload: (taskId: string) => Promise<void>;
+  releaseRecordingFile: (taskId: string, localPath: string) => Promise<void>;
   loadCompatibilityUploadQueue: () => Promise<string>;
   saveCompatibilityUploadQueue: (serializedTasks: string) => Promise<void>;
   stopAllRecordingOperations: () => Promise<void>;