@bota-dev/react-native-sdk 0.0.6 → 0.0.8

package/src/ble/parsers.ts

@@ -11,6 +11,10 @@ import type {
   DeviceStatus,
   DeviceFlags,
   StorageInfo,
+  DeviceCapabilities,
+  WiFiStatus,
+  WiFiStatusInfo,
+  WiFiConfigResult,
 } from '../models/Device';
 import type { DeviceRecording, AudioCodec, TransferPacket } from '../models/Recording';
 import {
@@ -48,6 +52,20 @@ import {
   PACKET_TYPE_DATA,
   PACKET_TYPE_EOF,
   PACKET_TYPE_ERROR,
+  CAP_BLE_SYNC,
+  CAP_WIFI_UPLOAD,
+  CAP_LTE_UPLOAD,
+  CAP_REMOTE_RECORD,
+  WIFI_STATUS_IDLE,
+  WIFI_STATUS_CONNECTING,
+  WIFI_STATUS_CONNECTED,
+  WIFI_STATUS_FAILED,
+  WIFI_STATUS_DISCONNECTED,
+  WIFI_CONFIG_SUCCESS,
+  WIFI_CONFIG_INVALID_GRANT,
+  WIFI_CONFIG_GRANT_EXPIRED,
+  WIFI_CONFIG_DECRYPTION_ERROR,
+  WIFI_CONFIG_STORAGE_ERROR,
 } from './constants';
 
 /**
@@ -393,3 +411,116 @@ export function createTransferCommand(
 
   return Buffer.from([cmdByte]);
 }
+
+// ============================================================================
+// WiFi Upload Configuration Parsers
+// ============================================================================
+
+/**
+ * Parse device capabilities from byte value
+ */
+export function parseDeviceCapabilities(byte: number): DeviceCapabilities {
+  return {
+    bleSync: (byte & CAP_BLE_SYNC) !== 0,
+    wifiUpload: (byte & CAP_WIFI_UPLOAD) !== 0,
+    lteUpload: (byte & CAP_LTE_UPLOAD) !== 0,
+    remoteRecord: (byte & CAP_REMOTE_RECORD) !== 0,
+  };
+}
+
+/**
+ * Parse WiFi status from byte value
+ */
+export function parseWiFiStatus(byte: number): WiFiStatus {
+  switch (byte) {
+    case WIFI_STATUS_IDLE:
+      return 'idle';
+    case WIFI_STATUS_CONNECTING:
+      return 'connecting';
+    case WIFI_STATUS_CONNECTED:
+      return 'connected';
+    case WIFI_STATUS_FAILED:
+      return 'failed';
+    case WIFI_STATUS_DISCONNECTED:
+      return 'disconnected';
+    default:
+      return 'idle';
+  }
+}
+
+/**
+ * Parse WiFi status information from characteristic value
+ *
+ * Format:
+ * Byte 0:      Status (0x00=idle, 0x01=connecting, 0x02=connected, 0x03=failed, 0x04=disconnected)
+ * Byte 1:      Signal strength (0-100)
+ * Byte 2:      SSID length
+ * Bytes 3-34:  SSID (max 32 bytes)
+ * Bytes 35+:   Error message (if status=failed)
+ */
+export function parseWiFiStatusInfo(data: Buffer): WiFiStatusInfo {
+  if (data.length < 3) {
+    throw new Error(`Invalid WiFi status data length: ${data.length}`);
+  }
+
+  const status = parseWiFiStatus(data.readUInt8(0));
+  const signalStrength = data.readUInt8(1);
+  const ssidLength = data.readUInt8(2);
+
+  let ssid: string | undefined;
+  let lastError: string | undefined;
+
+  if (ssidLength > 0 && data.length >= 3 + ssidLength) {
+    ssid = data.slice(3, 3 + ssidLength).toString('utf-8');
+  }
+
+  if (status === 'failed' && data.length > 3 + ssidLength) {
+    lastError = data.slice(3 + ssidLength).toString('utf-8');
+  }
+
+  return {
+    status,
+    signalStrength: signalStrength > 0 ? signalStrength : undefined,
+    ssid,
+    lastError,
+  };
+}
+
+/**
+ * Parse WiFi configuration result from characteristic value
+ *
+ * Format:
+ * Byte 0: Result code (0x00=success, 0x01=invalid_grant, 0x02=grant_expired, 0x03=decryption_error, 0x04=storage_error)
+ */
+export function parseWiFiConfigResult(data: Buffer): WiFiConfigResult {
+  if (data.length < 1) {
+    throw new Error(`Invalid WiFi config result length: ${data.length}`);
+  }
+
+  const code = data.readUInt8(0);
+
+  switch (code) {
+    case WIFI_CONFIG_SUCCESS:
+      return { success: true };
+    case WIFI_CONFIG_INVALID_GRANT:
+      return { success: false, error: 'invalid_grant' };
+    case WIFI_CONFIG_GRANT_EXPIRED:
+      return { success: false, error: 'grant_expired' };
+    case WIFI_CONFIG_DECRYPTION_ERROR:
+      return { success: false, error: 'decryption_error' };
+    case WIFI_CONFIG_STORAGE_ERROR:
+      return { success: false, error: 'storage_error' };
+    default:
+      return { success: false, error: 'unknown' };
+  }
+}
+
+/**
+ * Create WiFi grant submission packet
+ *
+ * Format:
+ * Bytes 0-N: Grant blob (JWT token as UTF-8 string)
+ */
+export function createWiFiGrantPacket(grantBlob: string): Buffer {
+  return Buffer.from(grantBlob, 'utf-8');
+}

package/src/managers/DeviceManager.ts

@@ -11,6 +11,7 @@ import {
   SERVICE_DEVICE_INFO,
   SERVICE_BOTA_PROVISIONING,
   SERVICE_BOTA_CONTROL,
+  SERVICE_BOTA_WIFI_CONFIG,
   CHAR_SERIAL_NUMBER,
   CHAR_FIRMWARE_REVISION,
   CHAR_HARDWARE_REVISION,
@@ -22,6 +23,9 @@ import {
   CHAR_RECORDING_CONTROL,
   CHAR_RECORDING_STATUS,
   CHAR_TIME_SYNC,
+  CHAR_WIFI_GRANT,
+  CHAR_WIFI_CREDENTIAL,
+  CHAR_WIFI_STATUS,
   API_ENDPOINT_PRODUCTION,
   API_ENDPOINT_SANDBOX,
   PROVISIONING_SUCCESS,
@@ -41,6 +45,9 @@ import {
   parsePairingState,
   parseDeviceStatus,
   createTimeSyncData,
+  parseWiFiStatusInfo,
+  parseWiFiConfigResult,
+  createWiFiGrantPacket,
 } from '../ble/parsers';
 import type {
   DiscoveredDevice,
@@ -53,6 +60,10 @@ import type {
   // RecordingCommand, // TODO: Re-enable when used
   StartRecordingOptions,
   StopRecordingOptions,
+  WiFiConfigGrant,
+  WiFiCredentials,
+  WiFiConfigResult,
+  WiFiStatusInfo,
 } from '../models/Device';
 import type { DeviceManagerEvents } from '../models/Status';
 import {
@@ -60,6 +71,11 @@ import {
   ProvisioningError,
 } from '../utils/errors';
 import { logger } from '../utils/logger';
+import {
+  deriveSessionKey,
+  encryptWiFiCredentials,
+  formatWiFiCredentialPacket,
+} from '../utils/crypto';
 
 const log = logger.tag('DeviceManager');
 
@@ -776,6 +792,234 @@ export class DeviceManager extends EventEmitter<DeviceManagerEvents> {
     };
   }
 
+  // ============================================================================
+  // WiFi Upload Configuration
+  // ============================================================================
+
+  /**
+   * Configure WiFi credentials on device via BLE.
+   * Requires a WiFi configuration grant from backend.
+   *
+   * @param deviceId - Connected device ID
+   * @param credentials - WiFi network credentials
+   * @param grant - WiFi config grant from backend
+   * @returns Configuration result
+   *
+   * @example
+   * ```typescript
+   * // 1. Get grant from backend
+   * const grant = await api.createWiFiConfigGrant(deviceId);
+   *
+   * // 2. Configure device via BLE
+   * const result = await deviceManager.configureWiFi(
+   *   deviceId,
+   *   { ssid: 'MyNetwork', password: 'password123', securityType: 'WPA2' },
+   *   grant
+   * );
+   *
+   * if (result.success) {
+   *   console.log('WiFi configured successfully');
+   * }
+   * ```
+   */
+  async configureWiFi(
+    deviceId: string,
+    credentials: WiFiCredentials,
+    grant: WiFiConfigGrant
+  ): Promise<WiFiConfigResult> {
+    log.info('Configuring WiFi on device', { deviceId, ssid: credentials.ssid });
+
+    try {
+      // Step 1: Submit WiFi config grant to device
+      const grantPacket = createWiFiGrantPacket(grant.grantBlob);
+      await this.bleManager.writeCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_GRANT,
+        grantPacket
+      );
+
+      log.debug('WiFi grant submitted');
+
+      // Step 2: Derive K_session from grant
+      const sessionKey = deriveSessionKey(grant.grantBlob);
+
+      // Step 3: Encrypt WiFi credentials with K_session
+      const encrypted = encryptWiFiCredentials(
+        credentials.ssid,
+        credentials.password,
+        sessionKey
+      );
+
+      // Step 4: Format credential packet for BLE transmission
+      const credentialPacket = formatWiFiCredentialPacket(encrypted);
+
+      log.debug('Sending encrypted WiFi credentials', {
+        packetSize: credentialPacket.length,
+      });
+
+      // Step 5: Write encrypted credentials to device
+      await this.bleManager.writeCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_CREDENTIAL,
+        credentialPacket
+      );
+
+      // Step 6: Wait for configuration result
+      const result = await this.waitForWiFiConfigResult(deviceId);
+
+      if (result.success) {
+        log.info('WiFi configuration successful', { deviceId });
+      } else {
+        log.warn('WiFi configuration failed', { deviceId, error: result.error });
+      }
+
+      return result;
+    } catch (error) {
+      log.error('WiFi configuration error', error instanceof Error ? error : undefined);
+      throw new DeviceError(
+        `Failed to configure WiFi: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'WIFI_CONFIG_ERROR',
+        deviceId,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Get WiFi connection status from device.
+   *
+   * @param deviceId - Connected device ID
+   * @returns WiFi status information
+   *
+   * @example
+   * ```typescript
+   * const status = await deviceManager.getWiFiStatus(deviceId);
+   * console.log('WiFi status:', status.status);
+   * if (status.status === 'connected') {
+   *   console.log('Connected to:', status.ssid);
+   *   console.log('Signal strength:', status.signalStrength);
+   * }
+   * ```
+   */
+  async getWiFiStatus(deviceId: string): Promise<WiFiStatusInfo> {
+    log.debug('Reading WiFi status', { deviceId });
+
+    try {
+      const data = await this.bleManager.readCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_STATUS
+      );
+
+      const status = parseWiFiStatusInfo(data);
+
+      log.debug('WiFi status', { deviceId, status: status.status, ssid: status.ssid });
+
+      return status;
+    } catch (error) {
+      log.error('Failed to read WiFi status', error instanceof Error ? error : undefined);
+      throw new DeviceError(
+        `Failed to read WiFi status: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'WIFI_STATUS_ERROR',
+        deviceId,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Subscribe to WiFi status updates from device.
+   *
+   * @param deviceId - Connected device ID
+   * @param callback - Callback function for status updates
+   * @returns Subscription object (call .remove() to unsubscribe)
+   *
+   * @example
+   * ```typescript
+   * const subscription = deviceManager.subscribeToWiFiStatus(deviceId, (status) => {
+   *   console.log('WiFi status update:', status.status);
+   *   if (status.status === 'connected') {
+   *     console.log('Connected to:', status.ssid);
+   *   } else if (status.status === 'failed') {
+   *     console.error('Connection failed:', status.lastError);
+   *   }
+   * });
+   *
+   * // Later: unsubscribe
+   * subscription.remove();
+   * ```
+   */
+  subscribeToWiFiStatus(
+    deviceId: string,
+    callback: (status: WiFiStatusInfo) => void
+  ): Subscription {
+    log.debug('Subscribing to WiFi status', { deviceId });
+
+    return this.bleManager.subscribeToCharacteristic(
+      deviceId,
+      SERVICE_BOTA_WIFI_CONFIG,
+      CHAR_WIFI_STATUS,
+      (data) => {
+        try {
+          const status = parseWiFiStatusInfo(data);
+          callback(status);
+        } catch (error) {
+          log.error('Failed to parse WiFi status', error instanceof Error ? error : undefined);
+        }
+      },
+      (error) => {
+        log.error('WiFi status subscription error', error);
+      }
+    );
+  }
+
+  /**
+   * Wait for WiFi configuration result from device.
+   */
+  private waitForWiFiConfigResult(deviceId: string): Promise<WiFiConfigResult> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        subscription.remove();
+        reject(new DeviceError(
+          'WiFi configuration timeout',
+          'WIFI_CONFIG_TIMEOUT',
+          deviceId
+        ));
+      }, OPERATION_TIMEOUT);
+
+      const subscription = this.bleManager.subscribeToCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_STATUS,
+        (data) => {
+          try {
+            // Configuration result comes via status updates
+            const result = parseWiFiConfigResult(data);
+
+            clearTimeout(timeout);
+            subscription.remove();
+            resolve(result);
+          } catch (error) {
+            // Ignore parse errors, wait for valid result
+            log.debug('Ignoring invalid WiFi config result', { error: error instanceof Error ? error.message : String(error) });
+          }
+        },
+        (error) => {
+          clearTimeout(timeout);
+          subscription.remove();
+          reject(new DeviceError(
+            `WiFi config result error: ${error.message}`,
+            'WIFI_CONFIG_RESULT_ERROR',
+            deviceId,
+            error
+          ));
+        }
+      );
+    });
+  }
+
   /**
    * Clean up resources
    */

package/src/models/Device.ts

@@ -76,6 +76,20 @@ export interface DiscoveredDevice {
   discoveredAt: Date;
 }
 
+/**
+ * Device capabilities (bitmask)
+ */
+export interface DeviceCapabilities {
+  /** Supports Bluetooth Sync (BLE transfer) */
+  bleSync: boolean;
+  /** Supports WiFi Upload */
+  wifiUpload: boolean;
+  /** Supports Cellular Upload (4G/LTE) */
+  lteUpload: boolean;
+  /** Supports Remote Recording Control */
+  remoteRecord: boolean;
+}
+
 /**
  * Device after successful BLE connection
  */
@@ -96,6 +110,8 @@ export interface ConnectedDevice {
   connectionState: ConnectionState;
   /** Negotiated MTU size */
   mtu: number;
+  /** Device capabilities */
+  capabilities?: DeviceCapabilities;
 }
 
 /**
@@ -255,3 +271,63 @@ export interface RecordingState {
   /** Who initiated the recording */
   initiatedBy?: 'local' | 'remote';
 }
+
+// ============================================================================
+// WiFi Upload Configuration Types
+// ============================================================================
+
+/**
+ * WiFi security type
+ */
+export type WiFiSecurityType = 'WPA2' | 'WPA3' | 'WEP' | 'OPEN';
+
+/**
+ * WiFi connection status
+ */
+export type WiFiStatus = 'idle' | 'connecting' | 'connected' | 'failed' | 'disconnected';
+
+/**
+ * WiFi configuration grant from backend
+ */
+export interface WiFiConfigGrant {
+  /** Grant blob (JWT token) */
+  grantBlob: string;
+  /** Expiration timestamp */
+  expiresAt: Date;
+}
+
+/**
+ * WiFi credentials to configure
+ */
+export interface WiFiCredentials {
+  /** WiFi network SSID */
+  ssid: string;
+  /** WiFi password */
+  password: string;
+  /** Security type (default: WPA2) */
+  securityType?: WiFiSecurityType;
+}
+
+/**
+ * WiFi configuration result from device
+ */
+export interface WiFiConfigResult {
+  /** Whether configuration was successful */
+  success: boolean;
+  /** Error code if failed */
+  error?: 'invalid_grant' | 'grant_expired' | 'decryption_error' | 'storage_error' | 'unknown';
+}
+
+/**
+ * WiFi status information from device
+ */
+export interface WiFiStatusInfo {
+  /** Current WiFi connection status */
+  status: WiFiStatus;
+  /** Connected SSID (if connected) */
+  ssid?: string;
+  /** Signal strength (0-100) */
+  signalStrength?: number;
+  /** Last connection error (if failed) */
+  lastError?: string;
+}

package/src/models/Recording.ts

@@ -30,14 +30,14 @@ export interface DeviceRecording {
 export interface UploadInfo {
   /** Pre-signed S3 URL for upload */
   uploadUrl: string;
-  /** Upload token (up_*) for verification */
-  uploadToken: string;
   /** Recording ID assigned by Bota API (rec_*) */
   recordingId: string;
-  /** URL to call when upload is complete */
-  completeUrl: string;
+  /** Upload token (up_*) for verification - optional if using custom completion flow */
+  uploadToken?: string;
+  /** URL to call when upload is complete - optional if using custom completion flow */
+  completeUrl?: string;
   /** Expiration time of the upload URL */
-  expiresAt: Date;
+  expiresAt?: Date;
   /** Content type for S3 upload (e.g., 'audio/opus', 'audio/wav') */
   contentType?: string;
 }
@@ -92,10 +92,10 @@ export interface UploadTask {
   localPath: string;
   /** Pre-signed S3 upload URL */
   uploadUrl: string;
-  /** Upload token */
-  uploadToken: string;
-  /** Complete URL to call after upload */
-  completeUrl: string;
+  /** Upload token - optional if using custom completion flow */
+  uploadToken?: string;
+  /** Complete URL to call after upload - optional if using custom completion flow */
+  completeUrl?: string;
   /** Content type for S3 upload (e.g., 'audio/opus', 'audio/wav') */
   contentType?: string;
   /** Current status */

package/src/upload/UploadQueue.ts

@@ -69,8 +69,8 @@ export class UploadQueue extends EventEmitter<UploadQueueEvents> {
     deviceId: string;
     localPath: string;
     uploadUrl: string;
-    uploadToken: string;
-    completeUrl: string;
+    uploadToken?: string;
+    completeUrl?: string;
     contentType?: string;
   }): Promise<UploadTask> {
     const task: UploadTask = {
@@ -251,12 +251,19 @@ export class UploadQueue extends EventEmitter<UploadQueueEvents> {
         abortSignal: abortController.signal,
       });
 
-      // Notify completion
-      await this.uploader.notifyCompletion(
-        task.completeUrl,
-        task.recordingId,
-        task.uploadToken
-      );
+      // Notify completion (only if completeUrl and uploadToken are provided)
+      if (task.completeUrl && task.uploadToken) {
+        await this.uploader.notifyCompletion(
+          task.completeUrl,
+          task.recordingId,
+          task.uploadToken
+        );
+      } else {
+        log.debug('Skipping completion notification (custom completion flow)', {
+          taskId: task.id,
+          recordingId: task.recordingId,
+        });
+      }
 
       // Mark as completed
       await this.storage.updateTaskStatus(task.id, 'completed');