@bota.dev/react-native-app-sdk 2.0.0-beta.0

package/src/sync/syncStatus.ts

@@ -0,0 +1,243 @@
+/**
+ * Centralized sync-status derivation.
+ *
+ * Apps display "what's happening with the recordings on the device right now"
+ * in multiple places — sync banners, pending-recordings rows, recording detail
+ * pages, list-item subtitles. Without a shared rule set every screen tends to
+ * compute its own label from raw inputs, leading to screens that disagree
+ * (one shows "Bluetooth syncing", another shows "4G uploading").
+ *
+ * This module owns the *rules* (pure function over a typed input shape). Apps
+ * own the *subscription* (a thin hook that reads from whatever stores/queries
+ * they use and calls `deriveSyncStatus`). The label text returned here is the
+ * canonical surface — every consumer should read `label` / `shortLabel`
+ * verbatim rather than re-deriving from `kind`/`channel`.
+ *
+ * Precedence policy (when multiple signals are true simultaneously):
+ *   1. Live recording — if the device is actively recording AND streaming is
+ *      enabled, show "Streaming via <channel>" regardless of pending uploads.
+ *   2. Actual device transport — if `device.syncActive` is set and a radio
+ *      (WiFi / 4G) is up, the label reflects *that* transport, even if the
+ *      app initiated the sync via BLE. This matches what bytes are actually
+ *      moving and avoids the smart-sync handoff flicker where the app's
+ *      "BLE pull" state lags the device's "4G upload" reality.
+ *   3. App-driven BLE pull — `appDriving.active` (e.g. the consumer's
+ *      `useSyncAllRecordings` global) shows as "Bluetooth syncing N/M".
+ *   4. Device claims sync but no radio is up — `'waiting_channel'`, best-guess
+ *      channel from `wifiAttempting` / `lteAttempting`.
+ *   5. Otherwise — `'idle'`.
+ */
+
+export type SyncKind =
+  | 'idle'
+  | 'ble_pull'
+  | 'wifi_upload'
+  | 'lte_upload'
+  | 'streaming'
+  | 'waiting_channel';
+
+export type SyncChannel = 'Bluetooth' | 'WiFi' | '4G';
+
+/**
+ * Inputs to `deriveSyncStatus`. Every field is what the *consumer app* already
+ * has on hand — the SDK does not subscribe to any state itself.
+ *
+ * `appDriving` — populated from the consumer's app-level sync state (e.g. the
+ *   global `isSyncing` + `syncAllProgress` exposed by their `useSyncAll*`
+ *   hook). Set `active: false` if the app isn't currently pulling.
+ *
+ * `device` — flags reported by the device. For BLE-connected devices these
+ *   come from `BotaClient.devices.on('statusUpdate', ...)`. For backend-only
+ *   visibility (no BLE) they come from the heartbeat-derived state on the
+ *   server, merged at the app layer.
+ *
+ * `bleConnected` — whether the app currently has a live BLE link to this
+ *   device. Used to disambiguate `'ble_pull'` from `'4g/wifi_upload'`.
+ */
+export interface SyncStatusInputs {
+  appDriving: {
+    /** True while the consumer's sync flow is actively pulling via BLE. */
+    active: boolean;
+    /** 1-indexed current item. Undefined if not tracking per-item progress. */
+    currentIndex?: number;
+    /** Total items being synced. Undefined if unknown. */
+    total?: number;
+  };
+  device: {
+    /** Device's own sync-active flag (bit 5 of the firmware status flags). */
+    syncActive: boolean;
+    /** Device is currently recording. */
+    isRecording: boolean;
+    /** Device has a usable WiFi connection. */
+    wifiConnected: boolean;
+    /** Device has a usable LTE/4G connection. */
+    lteConnected: boolean;
+    /** Device's WiFi radio is powered up and trying (connecting / scanning). */
+    wifiAttempting: boolean;
+    /** Device's LTE radio is powered up and trying (registered / searching). */
+    lteAttempting: boolean;
+    /** Streaming upload mode is enabled on the device. */
+    streamingEnabled: boolean;
+    /**
+     * Device's upload-channel preference order (highest priority first), e.g.
+     * `['wifi', 'ble', 'cellular']`. When provided, the streaming channel is
+     * resolved by walking this list and picking the first channel that is both
+     * enabled (`enabledConnections`) and currently up — so a device whose LTE
+     * radio is connected but whose preference ranks BLE higher (or has cellular
+     * disabled) is correctly shown as streaming via Bluetooth, not 4G.
+     * Omit to fall back to the legacy "first connected radio wins" heuristic.
+     */
+    uploadPreference?: Array<'wifi' | 'ble' | 'cellular'>;
+    /** Which upload channels are enabled on the device. */
+    enabledConnections?: { wifi: boolean; cellular: boolean };
+  };
+  /** BLE link to the device is currently up. */
+  bleConnected: boolean;
+}
+
+/**
+ * Resolve the channel a live stream is actually using. When the device's upload
+ * preference + enabled-connection flags are known, walk the preference order and
+ * pick the first channel that is enabled AND up (BLE is always available while
+ * the link is live) — this matches the firmware/app channel-selection rule. When
+ * those inputs are absent, fall back to "first connected radio wins".
+ */
+function resolveStreamingChannel(device: SyncStatusInputs['device']): SyncChannel {
+  const { wifiConnected, lteConnected, uploadPreference, enabledConnections } = device;
+
+  if (uploadPreference && enabledConnections) {
+    for (const channel of uploadPreference) {
+      if (channel === 'ble') return 'Bluetooth';
+      if (channel === 'wifi' && enabledConnections.wifi && wifiConnected) return 'WiFi';
+      if (channel === 'cellular' && enabledConnections.cellular && lteConnected) return '4G';
+    }
+    return 'Bluetooth';
+  }
+
+  return wifiConnected ? 'WiFi' : lteConnected ? '4G' : 'Bluetooth';
+}
+
+export interface SyncStatus {
+  kind: SyncKind;
+  /** Resolved channel ('Bluetooth' / 'WiFi' / '4G'), absent for idle. */
+  channel?: SyncChannel;
+  /** 1-indexed current item, if known. */
+  currentIndex?: number;
+  /** Total items, if known. */
+  total?: number;
+  /**
+   * Full label suitable for banners. Examples:
+   *   "Syncing 2/5 via Bluetooth..."
+   *   "Uploading 1/3 via 4G..."
+   *   "Streaming via WiFi"
+   *   "Waiting for upload channel..."
+   *   "" (when kind === 'idle')
+   */
+  label: string;
+  /**
+   * Compact label for tight UI (table rows, badges). Examples:
+   *   "Bluetooth syncing 2/5"
+   *   "4G uploading 1/3"
+   *   "Streaming"
+   *   "" (when kind === 'idle')
+   */
+  shortLabel: string;
+}
+
+const IDLE: SyncStatus = { kind: 'idle', label: '', shortLabel: '' };
+
+function progressFraction(currentIndex?: number, total?: number): string {
+  if (currentIndex == null || total == null || total <= 0) return '';
+  return ` ${Math.min(currentIndex, total)}/${total}`;
+}
+
+/**
+ * Pure derivation: given a snapshot of app + device + link state, return the
+ * single canonical `SyncStatus`. Safe to call on every render (no I/O, no
+ * allocations beyond the return value and label strings).
+ */
+export function deriveSyncStatus(inputs: SyncStatusInputs): SyncStatus {
+  const { appDriving, device, bleConnected } = inputs;
+
+  // 1. Live streaming wins — the user is recording right now and bytes are
+  //    flowing as they're captured, not from queued files.
+  if (device.isRecording && device.streamingEnabled) {
+    const channel = resolveStreamingChannel(device);
+    return {
+      kind: 'streaming',
+      channel,
+      label: `Streaming via ${channel}`,
+      shortLabel: `Streaming (${channel})`,
+    };
+  }
+
+  // 2. Device says it's syncing AND a radio is up — trust the device's own
+  //    transport. This wins over `appDriving` so smart-sync handoff (BLE
+  //    trigger → device 4G upload) doesn't flicker on the label.
+  if (device.syncActive && device.wifiConnected) {
+    const frac = progressFraction(appDriving.currentIndex, appDriving.total);
+    return {
+      kind: 'wifi_upload',
+      channel: 'WiFi',
+      currentIndex: appDriving.currentIndex,
+      total: appDriving.total,
+      label: `Uploading${frac} via WiFi...`,
+      shortLabel: `WiFi uploading${frac}`,
+    };
+  }
+  if (device.syncActive && device.lteConnected && !bleConnected) {
+    // When BLE is up the app is in control — see rule 3 — so we let
+    // `appDriving` take over if it's active even though LTE is also flagged.
+    const frac = progressFraction(appDriving.currentIndex, appDriving.total);
+    return {
+      kind: 'lte_upload',
+      channel: '4G',
+      currentIndex: appDriving.currentIndex,
+      total: appDriving.total,
+      label: `Uploading${frac} via 4G...`,
+      shortLabel: `4G uploading${frac}`,
+    };
+  }
+
+  // 3. App-driven BLE pull.
+  if (appDriving.active) {
+    const frac = progressFraction(appDriving.currentIndex, appDriving.total);
+    return {
+      kind: 'ble_pull',
+      channel: 'Bluetooth',
+      currentIndex: appDriving.currentIndex,
+      total: appDriving.total,
+      label: `Syncing${frac} via Bluetooth...`,
+      shortLabel: `Bluetooth syncing${frac}`,
+    };
+  }
+
+  // 4. Device says it's syncing but no radio is up yet — typically a 4G
+  //    cold-start (PDP attach in progress) or WiFi reconnect.
+  if (device.syncActive) {
+    const guess: SyncChannel | undefined = device.wifiAttempting
+      ? 'WiFi'
+      : device.lteAttempting
+      ? '4G'
+      : undefined;
+    if (guess) {
+      const frac = progressFraction(appDriving.currentIndex, appDriving.total);
+      return {
+        kind: 'waiting_channel',
+        channel: guess,
+        currentIndex: appDriving.currentIndex,
+        total: appDriving.total,
+        label: `Uploading${frac} via ${guess}...`,
+        shortLabel: `${guess} uploading${frac}`,
+      };
+    }
+    return {
+      kind: 'waiting_channel',
+      label: 'Waiting for upload channel...',
+      shortLabel: 'Waiting for channel',
+    };
+  }
+
+  // 5. Idle.
+  return IDLE;
+}

package/src/utils/errors.ts

@@ -0,0 +1,327 @@
+/**
+ * Custom error types for the Bota SDK
+ */
+
+import { BLE_ERROR_STORAGE_KEY_UNAVAILABLE } from '../ble/constants';
+
+/**
+ * Base error class for all Bota SDK errors
+ */
+export class BotaError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'BotaError';
+    Object.setPrototypeOf(this, BotaError.prototype);
+  }
+}
+
+/**
+ * Bluetooth-related errors
+ */
+export class BluetoothError extends BotaError {
+  constructor(message: string, code: string, cause?: Error) {
+    super(message, code, cause);
+    this.name = 'BluetoothError';
+    Object.setPrototypeOf(this, BluetoothError.prototype);
+  }
+
+  static unavailable(): BluetoothError {
+    return new BluetoothError(
+      'Bluetooth is not available on this device',
+      'BLUETOOTH_UNAVAILABLE'
+    );
+  }
+
+  static unauthorized(): BluetoothError {
+    return new BluetoothError(
+      'Bluetooth permission not granted',
+      'BLUETOOTH_UNAUTHORIZED'
+    );
+  }
+
+  static poweredOff(): BluetoothError {
+    return new BluetoothError('Bluetooth is powered off', 'BLUETOOTH_OFF');
+  }
+}
+
+/**
+ * Device-related errors
+ */
+export class DeviceError extends BotaError {
+  constructor(
+    message: string,
+    code: string,
+    public readonly deviceId?: string,
+    cause?: Error
+  ) {
+    super(message, code, cause);
+    this.name = 'DeviceError';
+    Object.setPrototypeOf(this, DeviceError.prototype);
+  }
+
+  static notFound(deviceId: string): DeviceError {
+    return new DeviceError(
+      `Device ${deviceId} not found`,
+      'DEVICE_NOT_FOUND',
+      deviceId
+    );
+  }
+
+  static connectionFailed(deviceId: string, cause?: Error): DeviceError {
+    return new DeviceError(
+      `Failed to connect to device ${deviceId}`,
+      'CONNECTION_FAILED',
+      deviceId,
+      cause
+    );
+  }
+
+  static connectionLost(deviceId: string, during?: string): DeviceError {
+    const message = during
+      ? `Connection to device ${deviceId} lost during ${during}`
+      : `Connection to device ${deviceId} lost`;
+    return new DeviceError(message, 'CONNECTION_LOST', deviceId);
+  }
+
+  static bondingFailed(deviceId: string, cause?: Error): DeviceError {
+    return new DeviceError(
+      `Bonding failed for device ${deviceId}`,
+      'BONDING_FAILED',
+      deviceId,
+      cause
+    );
+  }
+
+  static notConnected(deviceId: string): DeviceError {
+    return new DeviceError(
+      `Device ${deviceId} is not connected`,
+      'NOT_CONNECTED',
+      deviceId
+    );
+  }
+
+  static alreadyConnected(deviceId: string): DeviceError {
+    return new DeviceError(
+      `Device ${deviceId} is already connected`,
+      'ALREADY_CONNECTED',
+      deviceId
+    );
+  }
+}
+
+/**
+ * Provisioning-related errors
+ */
+export class ProvisioningError extends BotaError {
+  constructor(
+    message: string,
+    code: string,
+    public readonly deviceId?: string,
+    cause?: Error
+  ) {
+    super(message, code, cause);
+    this.name = 'ProvisioningError';
+    Object.setPrototypeOf(this, ProvisioningError.prototype);
+  }
+
+  static invalidToken(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Device rejected the token as invalid',
+      'INVALID_TOKEN',
+      deviceId
+    );
+  }
+
+  static storageError(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Device failed to store the token',
+      'STORAGE_ERROR',
+      deviceId
+    );
+  }
+
+  static chunkError(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Token chunk transfer failed',
+      'CHUNK_ERROR',
+      deviceId
+    );
+  }
+
+  static alreadyProvisioned(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Device is already provisioned',
+      'ALREADY_PROVISIONED',
+      deviceId
+    );
+  }
+
+  static alreadyPaired(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Device is already paired with another credential. Factory reset the device before re-provisioning.',
+      'ALREADY_PAIRED',
+      deviceId
+    );
+  }
+
+  static timeout(deviceId: string): ProvisioningError {
+    return new ProvisioningError(
+      'Provisioning timed out waiting for device response',
+      'PROVISIONING_TIMEOUT',
+      deviceId
+    );
+  }
+}
+
+/**
+ * Transfer-related errors
+ */
+export class TransferError extends BotaError {
+  constructor(
+    message: string,
+    code: string,
+    public readonly recordingUuid?: string,
+    cause?: Error
+  ) {
+    super(message, code, cause);
+    this.name = 'TransferError';
+    Object.setPrototypeOf(this, TransferError.prototype);
+  }
+
+  static recordingNotFound(uuid: string): TransferError {
+    return new TransferError(
+      `Recording ${uuid} not found on device`,
+      'RECORDING_NOT_FOUND',
+      uuid
+    );
+  }
+
+  static checksumMismatch(uuid: string): TransferError {
+    return new TransferError(
+      `Checksum mismatch for recording ${uuid}`,
+      'CHECKSUM_MISMATCH',
+      uuid
+    );
+  }
+
+  static interrupted(uuid: string, cause?: Error): TransferError {
+    return new TransferError(
+      `Transfer interrupted for recording ${uuid}`,
+      'TRANSFER_INTERRUPTED',
+      uuid,
+      cause
+    );
+  }
+
+  static timeout(uuid: string): TransferError {
+    return new TransferError(
+      `Transfer timed out for recording ${uuid}`,
+      'TRANSFER_TIMEOUT',
+      uuid
+    );
+  }
+
+  static deviceError(uuid: string, errorCode: number): TransferError {
+    if (errorCode === BLE_ERROR_STORAGE_KEY_UNAVAILABLE) {
+      return new TransferError(
+        `Recording ${uuid} exists, but its device storage key is unavailable`,
+        'STORAGE_KEY_UNAVAILABLE',
+        uuid
+      );
+    }
+    return new TransferError(
+      `Device error (code: ${errorCode}) during transfer of ${uuid}`,
+      'DEVICE_ERROR',
+      uuid
+    );
+  }
+}
+
+/**
+ * Upload-related errors
+ */
+export class UploadError extends BotaError {
+  constructor(
+    message: string,
+    code: string,
+    public readonly taskId?: string,
+    cause?: Error
+  ) {
+    super(message, code, cause);
+    this.name = 'UploadError';
+    Object.setPrototypeOf(this, UploadError.prototype);
+  }
+
+  static urlExpired(taskId: string): UploadError {
+    return new UploadError(
+      'Upload URL has expired',
+      'URL_EXPIRED',
+      taskId
+    );
+  }
+
+  static networkUnavailable(): UploadError {
+    return new UploadError(
+      'Network is not available',
+      'NETWORK_UNAVAILABLE'
+    );
+  }
+
+  static uploadFailed(taskId: string, cause?: Error): UploadError {
+    return new UploadError(
+      `Upload failed for task ${taskId}`,
+      'UPLOAD_FAILED',
+      taskId,
+      cause
+    );
+  }
+
+  static completionFailed(taskId: string, cause?: Error): UploadError {
+    return new UploadError(
+      `Failed to notify completion for task ${taskId}`,
+      'COMPLETION_FAILED',
+      taskId,
+      cause
+    );
+  }
+}
+
+/**
+ * SDK state errors
+ */
+export class SdkError extends BotaError {
+  constructor(message: string, code: string, cause?: Error) {
+    super(message, code, cause);
+    this.name = 'SdkError';
+    Object.setPrototypeOf(this, SdkError.prototype);
+  }
+
+  static notInitialized(): SdkError {
+    return new SdkError(
+      'SDK has not been initialized. Call BotaClient.configure() first.',
+      'NOT_INITIALIZED'
+    );
+  }
+
+  static invalidState(expected: string, actual: string): SdkError {
+    return new SdkError(
+      `Invalid state: expected ${expected}, got ${actual}`,
+      'INVALID_STATE'
+    );
+  }
+
+  static timeout(operation: string): SdkError {
+    return new SdkError(`Operation timed out: ${operation}`, 'TIMEOUT');
+  }
+}
+
+/**
+ * Type guard to check if an error is a BotaError
+ */
+export function isBotaError(error: unknown): error is BotaError {
+  return error instanceof BotaError;
+}

package/src/utils/logger.ts

@@ -0,0 +1,122 @@
+import type { LogLevel } from '../models/Status';
+
+export type SdkLogLevel = Exclude<LogLevel, 'none'>;
+
+export interface SdkLogEntry {
+  level: SdkLogLevel;
+  message: string;
+  context?: Record<string, unknown>;
+  timestamp: Date;
+}
+
+export type LogHandler = (entry: SdkLogEntry) => void;
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4,
+};
+
+class Logger {
+  private level: LogLevel = 'warn';
+  private readonly prefix = '[Bota SDK]';
+  private handler: LogHandler | null = null;
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  getLevel(): LogLevel {
+    return this.level;
+  }
+
+  setHandler(handler: LogHandler | null): void {
+    this.handler = handler;
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    this.write('debug', message, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    this.write('info', message, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    this.write('warn', message, context);
+  }
+
+  error(
+    message: string,
+    error?: Error,
+    context?: Record<string, unknown>
+  ): void {
+    this.write(
+      'error',
+      message,
+      error
+        ? { ...context, error: error.message, stack: error.stack }
+        : context
+    );
+  }
+
+  tag(tag: string): TaggedLogger {
+    return new TaggedLogger(this, tag);
+  }
+
+  private write(
+    level: SdkLogLevel,
+    message: string,
+    context?: Record<string, unknown>
+  ): void {
+    if (LOG_LEVELS[level] < LOG_LEVELS[this.level]) return;
+    if (this.handler) {
+      this.handler({ level, message, context, timestamp: new Date() });
+      return;
+    }
+    const output = this.format(level, message, context);
+    console[level](output);
+  }
+
+  private format(
+    level: SdkLogLevel,
+    message: string,
+    context?: Record<string, unknown>
+  ): string {
+    const contextValue = context ? ` ${JSON.stringify(context)}` : '';
+    return `${new Date().toISOString()} ${this.prefix} [${level.toUpperCase()}] ${message}${contextValue}`;
+  }
+}
+
+class TaggedLogger {
+  constructor(
+    private readonly parent: Logger,
+    private readonly tagValue: string
+  ) {}
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    this.parent.debug(`[${this.tagValue}] ${message}`, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    this.parent.info(`[${this.tagValue}] ${message}`, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    this.parent.warn(`[${this.tagValue}] ${message}`, context);
+  }
+
+  error(
+    message: string,
+    error?: Error,
+    context?: Record<string, unknown>
+  ): void {
+    this.parent.error(`[${this.tagValue}] ${message}`, error, context);
+  }
+}
+
+export const logger = new Logger();
+
+export type { TaggedLogger };