react-native-ble-nitro 1.0.0-alpha.1

package/src/errors/BleError.ts

@@ -0,0 +1,193 @@
+import {
+  BleErrorCode,
+  BleATTErrorCode,
+  BleIOSErrorCode,
+  BleAndroidErrorCode
+} from '../specs/types';
+import type {
+  NativeBleError,
+  BleErrorCodeMessageMapping
+} from '../specs/types';
+
+/**
+ * Default error messages for BLE error codes
+ * Maintains compatibility with react-native-ble-plx error messages
+ */
+const BleErrorCodeMessage: BleErrorCodeMessageMapping = {
+  [BleErrorCode.UnknownError]: 'Unknown error occurred',
+  [BleErrorCode.BluetoothManagerDestroyed]: 'BLE Manager was destroyed',
+  [BleErrorCode.OperationCancelled]: 'Operation was cancelled',
+  [BleErrorCode.OperationTimedOut]: 'Operation timed out',
+  [BleErrorCode.OperationStartFailed]: 'Operation could not be started',
+  [BleErrorCode.InvalidIdentifiers]: 'Invalid identifiers provided',
+  [BleErrorCode.BluetoothUnsupported]: 'Bluetooth is not supported on this device',
+  [BleErrorCode.BluetoothUnauthorized]: 'App is not authorized to use Bluetooth',
+  [BleErrorCode.BluetoothPoweredOff]: 'Bluetooth is powered off',
+  [BleErrorCode.BluetoothInUnknownState]: 'Bluetooth is in unknown state',
+  [BleErrorCode.BluetoothResetting]: 'Bluetooth is resetting',
+  [BleErrorCode.BluetoothStateChangeFailed]: 'Bluetooth state change failed',
+  [BleErrorCode.DeviceConnectionFailed]: 'Device connection failed',
+  [BleErrorCode.DeviceDisconnected]: 'Device was disconnected',
+  [BleErrorCode.DeviceRSSIReadFailed]: 'Failed to read RSSI',
+  [BleErrorCode.DeviceAlreadyConnected]: 'Device is already connected',
+  [BleErrorCode.DeviceNotFound]: 'Device not found',
+  [BleErrorCode.DeviceNotConnected]: 'Device is not connected',
+  [BleErrorCode.DeviceMTUChangeFailed]: 'Failed to change MTU',
+  [BleErrorCode.ServicesDiscoveryFailed]: 'Services discovery failed',
+  [BleErrorCode.IncludedServicesDiscoveryFailed]: 'Included services discovery failed',
+  [BleErrorCode.ServiceNotFound]: 'Service not found',
+  [BleErrorCode.ServicesNotDiscovered]: 'Services not discovered',
+  [BleErrorCode.CharacteristicsDiscoveryFailed]: 'Characteristics discovery failed',
+  [BleErrorCode.CharacteristicWriteFailed]: 'Characteristic write failed',
+  [BleErrorCode.CharacteristicReadFailed]: 'Characteristic read failed',
+  [BleErrorCode.CharacteristicNotifyChangeFailed]: 'Failed to change characteristic notification state',
+  [BleErrorCode.CharacteristicNotFound]: 'Characteristic not found',
+  [BleErrorCode.CharacteristicsNotDiscovered]: 'Characteristics not discovered',
+  [BleErrorCode.CharacteristicInvalidDataFormat]: 'Invalid characteristic data format',
+  [BleErrorCode.DescriptorsDiscoveryFailed]: 'Descriptors discovery failed',
+  [BleErrorCode.DescriptorWriteFailed]: 'Descriptor write failed',
+  [BleErrorCode.DescriptorReadFailed]: 'Descriptor read failed',
+  [BleErrorCode.DescriptorNotFound]: 'Descriptor not found',
+  [BleErrorCode.DescriptorsNotDiscovered]: 'Descriptors not discovered',
+  [BleErrorCode.DescriptorInvalidDataFormat]: 'Invalid descriptor data format',
+  [BleErrorCode.DescriptorWriteNotAllowed]: 'Descriptor write not allowed',
+  [BleErrorCode.ScanStartFailed]: 'Failed to start scan',
+  [BleErrorCode.LocationServicesDisabled]: 'Location services are disabled'
+};
+
+/**
+ * BleError class that maintains 100% compatibility with react-native-ble-plx
+ * Contains additional properties for platform-independent error handling
+ */
+export class BleError extends Error {
+  /**
+   * Platform independent error code
+   */
+  public readonly errorCode: BleErrorCode;
+
+  /**
+   * Platform independent error code related to ATT errors
+   */
+  public readonly attErrorCode: BleATTErrorCode | null;
+
+  /**
+   * iOS specific error code (if not an ATT error)
+   */
+  public readonly iosErrorCode: BleIOSErrorCode | null;
+
+  /**
+   * Android specific error code (if not an ATT error)
+   */
+  public readonly androidErrorCode: BleAndroidErrorCode | null;
+
+  /**
+   * Platform specific error message
+   */
+  public readonly reason: string | null;
+
+  /**
+   * Device ID associated with error (if applicable)
+   */
+  public readonly deviceID?: string;
+
+  /**
+   * Service UUID associated with error (if applicable)
+   */
+  public readonly serviceUUID?: string;
+
+  /**
+   * Characteristic UUID associated with error (if applicable)
+   */
+  public readonly characteristicUUID?: string;
+
+  /**
+   * Descriptor UUID associated with error (if applicable)
+   */
+  public readonly descriptorUUID?: string;
+
+  /**
+   * Internal error message for debugging
+   */
+  public readonly internalMessage?: string;
+
+  constructor(
+    nativeBleError: NativeBleError | string,
+    errorMessageMapping: BleErrorCodeMessageMapping = BleErrorCodeMessage
+  ) {
+    if (typeof nativeBleError === 'string') {
+      // Simple string error case
+      super(nativeBleError);
+      this.errorCode = BleErrorCode.UnknownError;
+      this.attErrorCode = null;
+      this.iosErrorCode = null;
+      this.androidErrorCode = null;
+      this.reason = nativeBleError;
+      return;
+    }
+
+    // Native BLE error case
+    const errorMessage = errorMessageMapping[nativeBleError.errorCode] || 'Unknown BLE error';
+    super(errorMessage);
+
+    this.errorCode = nativeBleError.errorCode;
+    this.attErrorCode = nativeBleError.attErrorCode;
+    this.iosErrorCode = nativeBleError.iosErrorCode;
+    this.androidErrorCode = nativeBleError.androidErrorCode;
+    this.reason = nativeBleError.reason;
+    if (nativeBleError.deviceID !== undefined) this.deviceID = nativeBleError.deviceID;
+    if (nativeBleError.serviceUUID !== undefined) this.serviceUUID = nativeBleError.serviceUUID;
+    if (nativeBleError.characteristicUUID !== undefined) this.characteristicUUID = nativeBleError.characteristicUUID;
+    if (nativeBleError.descriptorUUID !== undefined) this.descriptorUUID = nativeBleError.descriptorUUID;
+    if (nativeBleError.internalMessage !== undefined) this.internalMessage = nativeBleError.internalMessage;
+
+    // Set proper prototype chain
+    Object.setPrototypeOf(this, BleError.prototype);
+    this.name = 'BleError';
+  }
+
+  /**
+   * Returns a string representation of the error with all relevant information
+   */
+  public toString(): string {
+    const parts = [
+      `BleError: ${this.message}`,
+      `Error code: ${this.errorCode}`
+    ];
+
+    if (this.attErrorCode !== null) {
+      parts.push(`ATT error code: ${this.attErrorCode}`);
+    }
+
+    if (this.iosErrorCode !== null) {
+      parts.push(`iOS error code: ${this.iosErrorCode}`);
+    }
+
+    if (this.androidErrorCode !== null) {
+      parts.push(`Android error code: ${this.androidErrorCode}`);
+    }
+
+    if (this.reason) {
+      parts.push(`Reason: ${this.reason}`);
+    }
+
+    if (this.deviceID) {
+      parts.push(`Device ID: ${this.deviceID}`);
+    }
+
+    if (this.serviceUUID) {
+      parts.push(`Service UUID: ${this.serviceUUID}`);
+    }
+
+    if (this.characteristicUUID) {
+      parts.push(`Characteristic UUID: ${this.characteristicUUID}`);
+    }
+
+    if (this.descriptorUUID) {
+      parts.push(`Descriptor UUID: ${this.descriptorUUID}`);
+    }
+
+    return parts.join(', ');
+  }
+}
+
+export { BleErrorCodeMessage };

package/src/index.ts

@@ -0,0 +1,30 @@
+// Export compatibility layer types and constants
+export * from './compatibility/constants';
+
+// Export utility functions
+export * from './utils';
+
+// Export the main BleManager instance with compatibility wrapper
+export { BleManagerCompat as BleManager, createBleManagerCompat as createBleManager } from './BleManagerCompatFactory';
+
+// Export error handling utilities
+export * from './errors/BleError';
+
+// Export device wrapper for compatibility
+export { DeviceWrapper as Device } from './compatibility/deviceWrapper';
+
+// Export interfaces for TypeScript (but not runtime values)
+export type { 
+  BleManagerOptions,
+  ScanOptions,
+  ConnectionOptions,
+  NativeBleError,
+  NativeDevice,
+  NativeService,
+  NativeCharacteristic,
+  NativeDescriptor,
+  Subscription
+} from './specs/types';
+
+// Re-export react-native-ble-plx compatible API
+export { fullUUID } from './utils/uuid';

package/src/specs/BleManager.nitro.ts

@@ -0,0 +1,152 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  State,
+  LogLevel,
+  UUID,
+  DeviceId,
+  TransactionId,
+  ConnectionPriority,
+  ScanOptions,
+  ConnectionOptions,
+  BleManagerOptions,
+  StateListener,
+  DeviceScanListener,
+  DeviceDisconnectedListener,
+  CharacteristicMonitorListener,
+  CharacteristicSubscriptionType,
+  NativeDevice,
+  NativeService,
+  NativeCharacteristic,
+  NativeDescriptor,
+  NativeBleError,
+  BleRestoredState,
+  Base64,
+  Subscription
+} from './types';
+
+export interface BleManager extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  // Lifecycle
+  destroy(): Promise<void>;
+
+  // Common operations
+  setLogLevel(logLevel: LogLevel): Promise<LogLevel>;
+  logLevel(): Promise<LogLevel>;
+  cancelTransaction(transactionId: TransactionId): Promise<void>;
+
+  // State management
+  enable(transactionId?: TransactionId): Promise<void>;
+  disable(transactionId?: TransactionId): Promise<void>;
+  state(): Promise<State>;
+  onStateChange(listener: StateListener, emitCurrentState?: boolean): Subscription;
+
+  // Device scanning
+  startDeviceScan(
+    uuids: UUID[] | null,
+    options: ScanOptions | null,
+    listener: DeviceScanListener
+  ): Promise<void>;
+  stopDeviceScan(): Promise<void>;
+
+  // Connection priority and RSSI/MTU requests
+  requestConnectionPriorityForDevice(
+    deviceIdentifier: DeviceId,
+    connectionPriority: ConnectionPriority,
+    transactionId?: TransactionId
+  ): Promise<NativeDevice>;
+
+  readRSSIForDevice(
+    deviceIdentifier: DeviceId,
+    transactionId?: TransactionId
+  ): Promise<NativeDevice>;
+
+  requestMTUForDevice(
+    deviceIdentifier: DeviceId,
+    mtu: number,
+    transactionId?: TransactionId
+  ): Promise<NativeDevice>;
+
+  // Connection management
+  devices(deviceIdentifiers: DeviceId[]): Promise<NativeDevice[]>;
+  connectedDevices(serviceUUIDs: UUID[]): Promise<NativeDevice[]>;
+  connectToDevice(
+    deviceIdentifier: DeviceId,
+    options?: ConnectionOptions
+  ): Promise<NativeDevice>;
+  cancelDeviceConnection(deviceIdentifier: DeviceId): Promise<NativeDevice>;
+  onDeviceDisconnected(
+    deviceIdentifier: DeviceId,
+    listener: DeviceDisconnectedListener
+  ): Subscription;
+  isDeviceConnected(deviceIdentifier: DeviceId): Promise<boolean>;
+
+  // Service and characteristic discovery
+  discoverAllServicesAndCharacteristicsForDevice(
+    deviceIdentifier: DeviceId,
+    transactionId?: TransactionId
+  ): Promise<NativeDevice>;
+
+  // Service operations
+  servicesForDevice(deviceIdentifier: DeviceId): Promise<NativeService[]>;
+
+  // Characteristic operations
+  characteristicsForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID
+  ): Promise<NativeCharacteristic[]>;
+
+  readCharacteristicForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithResponseForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    base64Value: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithoutResponseForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    base64Value: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  monitorCharacteristicForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    listener: CharacteristicMonitorListener,
+    transactionId?: TransactionId,
+    subscriptionType?: CharacteristicSubscriptionType
+  ): Subscription;
+
+  // Descriptor operations
+  descriptorsForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID
+  ): Promise<NativeDescriptor[]>;
+
+  readDescriptorForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+
+  writeDescriptorForDevice(
+    deviceIdentifier: DeviceId,
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+}

package/src/specs/Characteristic.nitro.ts

@@ -0,0 +1,61 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  Identifier,
+  UUID,
+  DeviceId,
+  Base64,
+  TransactionId,
+  CharacteristicSubscriptionType,
+  NativeDescriptor,
+  CharacteristicMonitorListener,
+  Subscription
+} from './types';
+
+export interface Characteristic extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  // Characteristic properties
+  readonly id: Identifier;
+  readonly uuid: UUID;
+  readonly serviceID: Identifier;
+  readonly serviceUUID: UUID;
+  readonly deviceID: DeviceId;
+  readonly isReadable: boolean;
+  readonly isWritableWithResponse: boolean;
+  readonly isWritableWithoutResponse: boolean;
+  readonly isNotifiable: boolean;
+  readonly isNotifying: boolean;
+  readonly isIndicatable: boolean;
+  readonly value: Base64 | null;
+
+  // Characteristic operations
+  read(transactionId?: TransactionId): Promise<Characteristic>;
+
+  writeWithResponse(
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<Characteristic>;
+
+  writeWithoutResponse(
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<Characteristic>;
+
+  monitor(
+    listener: CharacteristicMonitorListener,
+    transactionId?: TransactionId,
+    subscriptionType?: CharacteristicSubscriptionType
+  ): Subscription;
+
+  // Descriptor operations
+  descriptors(): Promise<NativeDescriptor[]>;
+
+  readDescriptor(
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+
+  writeDescriptor(
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+}

package/src/specs/Descriptor.nitro.ts

@@ -0,0 +1,28 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  Identifier,
+  UUID,
+  DeviceId,
+  Base64,
+  TransactionId
+} from './types';
+
+export interface Descriptor extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  // Descriptor properties
+  readonly id: Identifier;
+  readonly uuid: UUID;
+  readonly characteristicID: Identifier;
+  readonly characteristicUUID: UUID;
+  readonly serviceID: Identifier;
+  readonly serviceUUID: UUID;
+  readonly deviceID: DeviceId;
+  readonly value: Base64 | null;
+
+  // Descriptor operations
+  read(transactionId?: TransactionId): Promise<Descriptor>;
+
+  write(
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<Descriptor>;
+}

package/src/specs/Device.nitro.ts

@@ -0,0 +1,104 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  DeviceId,
+  UUID,
+  Base64,
+  TransactionId,
+  ConnectionPriority,
+  ConnectionOptions,
+  CharacteristicSubscriptionType,
+  ServiceDataEntry,
+  NativeDevice,
+  NativeService,
+  NativeCharacteristic,
+  NativeDescriptor,
+  DeviceDisconnectedListener,
+  CharacteristicMonitorListener,
+  Subscription
+} from './types';
+
+export interface Device extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  // Device properties
+  readonly id: DeviceId;
+  readonly deviceName?: string | null;
+  readonly rssi?: number | null;
+  readonly mtu: number;
+  readonly manufacturerData?: Base64 | null;
+  readonly rawScanRecord: Base64;
+  readonly serviceData?: ServiceDataEntry[] | null;
+  readonly serviceUUIDs?: UUID[] | null;
+  readonly localName?: string | null;
+  readonly txPowerLevel?: number | null;
+  readonly solicitedServiceUUIDs?: UUID[] | null;
+  readonly isConnectable?: boolean | null;
+  readonly overflowServiceUUIDs?: UUID[] | null;
+
+  // Connection management
+  requestConnectionPriority(
+    connectionPriority: ConnectionPriority,
+    transactionId?: TransactionId
+  ): Promise<NativeDevice>;
+
+  readRSSI(transactionId?: TransactionId): Promise<NativeDevice>;
+  requestMTU(mtu: number, transactionId?: TransactionId): Promise<NativeDevice>;
+  connect(options?: ConnectionOptions): Promise<NativeDevice>;
+  cancelConnection(): Promise<NativeDevice>;
+  isConnected(): Promise<boolean>;
+  onDisconnected(listener: DeviceDisconnectedListener): Subscription;
+
+  // Service discovery
+  discoverAllServicesAndCharacteristics(transactionId?: TransactionId): Promise<NativeDevice>;
+  services(): Promise<NativeService[]>;
+
+  // Characteristic operations
+  characteristicsForService(serviceUUID: UUID): Promise<NativeCharacteristic[]>;
+
+  readCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithoutResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  monitorCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    listener: CharacteristicMonitorListener,
+    transactionId?: TransactionId,
+    subscriptionType?: CharacteristicSubscriptionType
+  ): Subscription;
+
+  // Descriptor operations
+  descriptorsForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID
+  ): Promise<NativeDescriptor[]>;
+
+  readDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+
+  writeDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+}

package/src/specs/Service.nitro.ts

@@ -0,0 +1,64 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  Identifier,
+  UUID,
+  DeviceId,
+  Base64,
+  TransactionId,
+  CharacteristicSubscriptionType,
+  NativeCharacteristic,
+  NativeDescriptor,
+  CharacteristicMonitorListener,
+  Subscription
+} from './types';
+
+export interface Service extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  // Service properties
+  readonly id: Identifier;
+  readonly uuid: UUID;
+  readonly deviceID: DeviceId;
+  readonly isPrimary: boolean;
+
+  // Characteristic operations
+  characteristics(): Promise<NativeCharacteristic[]>;
+
+  readCharacteristic(
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithResponse(
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  writeCharacteristicWithoutResponse(
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeCharacteristic>;
+
+  monitorCharacteristic(
+    characteristicUUID: UUID,
+    listener: CharacteristicMonitorListener,
+    transactionId?: TransactionId,
+    subscriptionType?: CharacteristicSubscriptionType
+  ): Subscription;
+
+  // Descriptor operations
+  descriptorsForCharacteristic(characteristicUUID: UUID): Promise<NativeDescriptor[]>;
+
+  readDescriptorForCharacteristic(
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+
+  writeDescriptorForCharacteristic(
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<NativeDescriptor>;
+}