react-native-ble-nitro 1.0.0-beta.0 → 1.0.0-beta.2

package/android/src/main/kotlin/co/zyke/ble/BleNitroBleManager.kt

@@ -57,6 +57,11 @@ class BleNitroBleManager(private val context: ReactApplicationContext) : HybridB
     private var logLevel: LogLevel = LogLevel.None
     private var isScanning = false
     private var scanCallback: ScanCallback? = null
+    
+    // State restoration
+    private var restoreIdentifier: String? = null
+    private var isInitialized = false
+    private var restoredState: BleRestoredState? = null
     private var scanListener: ((NativeBleError?, NativeDevice?) -> Unit)? = null
     private var stateChangeListener: ((State) -> Unit)? = null
     
@@ -100,6 +105,104 @@ class BleNitroBleManager(private val context: ReactApplicationContext) : HybridB
         }
     }
     
+    override fun initialize(options: BleManagerNitroOptions): Promise<Unit> = Promise.resolve {
+        options.restoreStateIdentifier?.let { restoreId ->
+            this.restoreIdentifier = restoreId
+            
+            // Attempt to restore previous state from SharedPreferences
+            restoreConnectionState(restoreId)
+            
+            Log.d(TAG, "BleNitro: Initialized with restore state identifier: $restoreId")
+        }
+        
+        this.isInitialized = true
+        Log.d(TAG, "BleNitro: BLE Manager initialized")
+        Unit
+    }
+    
+    override fun getRestoredState(): Promise<BleRestoredState?> = Promise.resolve {
+        restoredState
+    }
+    
+    private fun restoreConnectionState(restoreId: String) {
+        try {
+            val sharedPrefs = context.getSharedPreferences("BleNitro_$restoreId", Context.MODE_PRIVATE)
+            val connectedDevicesJson = sharedPrefs.getString("connected_devices", null)
+            
+            connectedDevicesJson?.let { json ->
+                // Parse stored device IDs and attempt to reconnect
+                val deviceIds = json.split(",").filter { it.isNotEmpty() }
+                
+                if (deviceIds.isNotEmpty()) {
+                    Log.d(TAG, "BleNitro: Restoring ${deviceIds.size} devices")
+                    
+                    deviceIds.forEach { deviceId ->
+                        // Attempt to reconnect to previously connected devices
+                        restoreDeviceConnection(deviceId)
+                    }
+                    
+                    // Store restored state (initially empty, will be populated as devices reconnect)
+                    val initialDevices = deviceIds.mapNotNull { deviceId ->
+                        bluetoothAdapter?.getRemoteDevice(deviceId)?.let { device ->
+                            createNativeDevice(device, null, -1) // Initial state without GATT
+                        }
+                    }
+                    
+                    if (initialDevices.isNotEmpty()) {
+                        this.restoredState = BleRestoredState(initialDevices)
+                        Log.d(TAG, "BleNitro: Stored restored state with ${initialDevices.size} devices")
+                    }
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "BleNitro: Error restoring connection state", e)
+        }
+    }
+    
+    private fun restoreDeviceConnection(deviceId: String) {
+        try {
+            val bluetoothDevice = bluetoothAdapter?.getRemoteDevice(deviceId)
+            bluetoothDevice?.let { device ->
+                Log.d(TAG, "BleNitro: Attempting to restore connection to $deviceId")
+                
+                val gatt = device.connectGatt(context, true, object : BluetoothGattCallback() {
+                    override fun onConnectionStateChange(gatt: BluetoothGatt?, status: Int, newState: Int) {
+                        if (newState == BluetoothProfile.STATE_CONNECTED) {
+                            connectedDevices[deviceId] = gatt!!
+                            Log.d(TAG, "BleNitro: Successfully restored connection to $deviceId")
+                        } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
+                            Log.d(TAG, "BleNitro: Failed to restore connection to $deviceId")
+                            gatt?.close()
+                        }
+                    }
+                })
+                
+                if (gatt != null) {
+                    deviceCallbacks[deviceId] = gatt
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "BleNitro: Error restoring device connection for $deviceId", e)
+        }
+    }
+    
+    private fun saveConnectionState() {
+        restoreIdentifier?.let { restoreId ->
+            try {
+                val sharedPrefs = context.getSharedPreferences("BleNitro_$restoreId", Context.MODE_PRIVATE)
+                val deviceIds = connectedDevices.keys.joinToString(",")
+                
+                sharedPrefs.edit()
+                    .putString("connected_devices", deviceIds)
+                    .apply()
+                
+                Log.d(TAG, "BleNitro: Saved connection state for ${connectedDevices.size} devices")
+            } catch (e: Exception) {
+                Log.e(TAG, "BleNitro: Error saving connection state", e)
+            }
+        }
+    }
+    
     override fun setLogLevel(logLevel: LogLevel): Promise<LogLevel> = Promise.resolve {
         this.logLevel = logLevel
         logLevel

package/ios/BleNitroBleManager.swift

@@ -26,12 +26,28 @@ public class BleNitroBleManager: HybridBleManagerSpec, CBCentralManagerDelegate
     private var characteristicMonitors: [String: ((_ error: NativeBleError?, _ characteristic: NativeCharacteristic?) -> Void)] = [:]
     private var pendingOperations: [String: Any] = [:]
     
+    // State restoration
+    private var restoreIdentifier: String?
+    private var isInitialized = false
+    private var restoredState: BleRestoredState?
+    
     // MARK: - Initialization
     public override init() {
         super.init()
+        // Initialize with default options - will be reconfigured in initialize() method
         self.centralManager = CBCentralManager(delegate: self, queue: nil)
     }
     
+    private func reinitializeCentralManager() {
+        // Create CBCentralManager with state restoration if identifier is provided
+        var options: [String: Any] = [:]
+        if let restoreId = restoreIdentifier {
+            options[CBCentralManagerOptionRestoreIdentifierKey] = restoreId
+        }
+        
+        self.centralManager = CBCentralManager(delegate: self, queue: nil, options: options.isEmpty ? nil : options)
+    }
+    
     public override var memorySize: Int {
         return MemorySize.MemorySize_estimate(self)
     }
@@ -51,6 +67,29 @@ public class BleNitroBleManager: HybridBleManagerSpec, CBCentralManagerDelegate
         }
     }
     
+    public func initialize(options: BleManagerNitroOptions) throws -> Promise<Void> {
+        return Promise.resolve(withBlock: {
+            if let restoreId = options.restoreStateIdentifier {
+                // Store the restore identifier
+                self.restoreIdentifier = restoreId
+                
+                // Reinitialize the central manager with state restoration
+                self.reinitializeCentralManager()
+                
+                print("BleNitro: Initialized with restore state identifier: \(restoreId)")
+            }
+            
+            self.isInitialized = true
+            print("BleNitro: BLE Manager initialized")
+        })
+    }
+    
+    public func getRestoredState() throws -> Promise<BleRestoredState?> {
+        return Promise.resolve(withBlock: {
+            return self.restoredState
+        })
+    }
+    
     public func setLogLevel(logLevel: LogLevel) throws -> Promise<LogLevel> {
         return Promise.resolve(withBlock: {
             self.logLevel = logLevel
@@ -491,6 +530,40 @@ extension BleNitroBleManager: CBPeripheralDelegate {
             }
         }
     }
+    
+    // MARK: - CBCentralManagerDelegate State Restoration
+    
+    public func centralManager(_ central: CBCentralManager, willRestoreState dict: [String : Any]) {
+        // Handle state restoration
+        if let peripherals = dict[CBCentralManagerRestoredStatePeripheralsKey] as? [CBPeripheral] {
+            print("BleNitro: Restoring \(peripherals.count) peripherals")
+            
+            // Add restored peripherals to our connected devices
+            for peripheral in peripherals {
+                let deviceId = peripheral.identifier.uuidString
+                connectedDevices[deviceId] = peripheral
+                peripheral.delegate = self
+                
+                print("BleNitro: Restored peripheral: \(deviceId)")
+            }
+            
+            // Store restored state for later retrieval
+            if !peripherals.isEmpty {
+                let restoredDevices = peripherals.map(createNativeDevice)
+                self.restoredState = BleRestoredState(connectedPeripherals: restoredDevices)
+                print("BleNitro: Stored restored state with \(restoredDevices.count) devices")
+            }
+        }
+    }
+    
+    public func centralManagerDidUpdateState(_ central: CBCentralManager) {
+        let newState = convertCBManagerStateToState(central.state)
+        
+        // Notify state change listener if available
+        stateChangeListener?(newState)
+        
+        print("BleNitro: Central manager state changed to: \(central.state.rawValue)")
+    }
 }
 
 /**

package/lib/BleManagerCompatFactory.d.ts

@@ -38,7 +38,8 @@ export declare class BleManagerCompat {
     readCharacteristicForDevice(deviceIdentifier: DeviceId, serviceUUID: UUID, characteristicUUID: UUID, transactionId?: TransactionId): Promise<NativeCharacteristic>;
     writeCharacteristicWithResponseForDevice(deviceIdentifier: DeviceId, serviceUUID: UUID, characteristicUUID: UUID, base64Value: string, transactionId?: TransactionId): Promise<NativeCharacteristic>;
     writeCharacteristicWithoutResponseForDevice(deviceIdentifier: DeviceId, serviceUUID: UUID, characteristicUUID: UUID, base64Value: string, transactionId?: TransactionId): Promise<NativeCharacteristic>;
-    monitorCharacteristicForDevice(deviceIdentifier: DeviceId, serviceUUID: UUID, characteristicUUID: UUID, listener: (error: any | null, characteristic: NativeCharacteristic | null) => void, transactionId?: TransactionId, subscriptionType?: 'notification' | 'indication'): Subscription;
+    monitorCharacteristicForDevice(deviceIdentifier: DeviceId, serviceUUID: UUID, characteristicUUID: UUID, listener: (error: any | null, characteristic: NativeCharacteristic | null) => void, // TODO: COMPAT! use proper error type like in react-native-ble-plx
+    transactionId?: TransactionId, subscriptionType?: 'notification' | 'indication'): Subscription;
     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: string, transactionId?: TransactionId): Promise<NativeDescriptor>;

package/lib/BleManagerCompatFactory.js

@@ -50,7 +50,8 @@ export class BleManagerCompat {
         }, emitCurrentState);
     }
     // Device scanning with compatibility wrappers
-    async startDeviceScan(uuids, options, listener) {
+    async startDeviceScan(uuids, options, listener // TODO: COMPAT! remove any and move to BleError as react-native-ble-plx uses this type as well!
+    ) {
         return await this.bleManager.startDeviceScan(uuids, options, (error, device) => {
             listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
         });
@@ -76,7 +77,8 @@ export class BleManagerCompat {
     async isDeviceConnected(deviceIdentifier) {
         return await this.bleManager.isDeviceConnected(deviceIdentifier);
     }
-    onDeviceDisconnected(deviceIdentifier, listener) {
+    onDeviceDisconnected(deviceIdentifier, listener // TODO: COMPAT! use propper error type like in react-native-ble-plx!!!
+    ) {
         return this.bleManager.onDeviceDisconnected(deviceIdentifier, (error, device) => {
             listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
         });
@@ -125,7 +127,8 @@ export class BleManagerCompat {
     async writeCharacteristicWithoutResponseForDevice(deviceIdentifier, serviceUUID, characteristicUUID, base64Value, transactionId) {
         return await this.bleManager.writeCharacteristicWithoutResponseForDevice(deviceIdentifier, serviceUUID, characteristicUUID, base64Value, transactionId);
     }
-    monitorCharacteristicForDevice(deviceIdentifier, serviceUUID, characteristicUUID, listener, transactionId, subscriptionType) {
+    monitorCharacteristicForDevice(deviceIdentifier, serviceUUID, characteristicUUID, listener, // TODO: COMPAT! use proper error type like in react-native-ble-plx
+    transactionId, subscriptionType) {
         const nitroSubscriptionType = subscriptionType
             ? normalizeCharacteristicSubscriptionType(subscriptionType)
             : undefined;

package/lib/BleManagerFactory.d.ts

@@ -5,8 +5,26 @@ import type { BleManagerOptions } from './specs/types.js';
  * This function maintains compatibility with react-native-ble-plx's BleManager constructor
  */
 export declare function createBleManager(options?: BleManagerOptions): BleManagerInterface;
+/**
+ * Helper function to retrieve stored callbacks for a BleManager instance
+ * This is used internally when callbacks need to be invoked
+ */
+export declare function getStoredCallbacks(manager: BleManagerInterface): {
+    restoreStateFunction?: (restoredState: any) => void;
+    errorCodesToMessagesMapping?: {
+        [key: number]: string;
+    };
+} | undefined;
+/**
+ * Helper function to get custom error message if available
+ * @param manager The BleManager instance
+ * @param errorCode The BLE error code
+ * @param defaultMessage Default error message
+ * @returns Custom message if available, otherwise default message
+ */
+export declare function getCustomErrorMessage(manager: BleManagerInterface, errorCode: number, defaultMessage: string): string;
 /**
  * Legacy compatibility: Export a BleManager constructor function
  * This maintains compatibility with code that imports { BleManager } from 'react-native-ble-plx'
  */
-export declare const BleManager: any;
+export declare const BleManager: (options?: BleManagerOptions) => BleManagerInterface;

package/lib/BleManagerFactory.js

@@ -1,4 +1,6 @@
 import { NitroModules } from 'react-native-nitro-modules';
+// Store callbacks that can't be passed to Nitro
+const storedCallbacks = new WeakMap();
 /**
  * Creates a BleManager instance using Nitro Modules
  * This function maintains compatibility with react-native-ble-plx's BleManager constructor
@@ -9,10 +11,59 @@ export function createBleManager(options) {
         throw new Error('Failed to create BleManager: Nitro module not found. ' +
             'Make sure react-native-ble-nitro is properly installed and linked.');
     }
-    // If options are provided, we could initialize with them
-    // For now, we return the module directly as Nitro handles the native initialization
+    // Initialize with options if provided
+    if (options) {
+        // Extract Nitro-compatible options
+        const nitroOptions = {
+            restoreStateIdentifier: options.restoreStateIdentifier,
+        };
+        // Store callbacks and mappings that can't be passed to Nitro
+        if (options.restoreStateFunction || options.errorCodesToMessagesMapping) {
+            storedCallbacks.set(BleManagerModule, {
+                restoreStateFunction: options.restoreStateFunction,
+                errorCodesToMessagesMapping: options.errorCodesToMessagesMapping,
+            });
+        }
+        // Note: initialize() is async but we need to maintain sync compatibility with react-native-ble-plx
+        // The initialization will happen asynchronously in the background
+        BleManagerModule.initialize(nitroOptions).then(async () => {
+            // Check for restored state and call the callback if available
+            if (options.restoreStateFunction) {
+                try {
+                    const restoredState = await BleManagerModule.getRestoredState();
+                    if (restoredState) {
+                        options.restoreStateFunction(restoredState);
+                    }
+                }
+                catch (error) {
+                    console.warn('BleManager restore state callback failed:', error);
+                }
+            }
+        }).catch(error => {
+            console.warn('BleManager initialization failed:', error);
+        });
+    }
     return BleManagerModule;
 }
+/**
+ * Helper function to retrieve stored callbacks for a BleManager instance
+ * This is used internally when callbacks need to be invoked
+ */
+export function getStoredCallbacks(manager) {
+    return storedCallbacks.get(manager);
+}
+/**
+ * Helper function to get custom error message if available
+ * @param manager The BleManager instance
+ * @param errorCode The BLE error code
+ * @param defaultMessage Default error message
+ * @returns Custom message if available, otherwise default message
+ */
+export function getCustomErrorMessage(manager, errorCode, defaultMessage) {
+    const callbacks = storedCallbacks.get(manager);
+    const customMessage = callbacks?.errorCodesToMessagesMapping?.[errorCode];
+    return customMessage || defaultMessage;
+}
 /**
  * Legacy compatibility: Export a BleManager constructor function
  * This maintains compatibility with code that imports { BleManager } from 'react-native-ble-plx'

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './compatibility/constants.js';
 export * from './utils/index.js';
 export { BleManagerCompat as BleManager, createBleManagerCompat as createBleManager } from './BleManagerCompatFactory.js';
+export { getCustomErrorMessage, getStoredCallbacks } from './BleManagerFactory.js';
 export * from './errors/BleError.js';
 export { DeviceWrapper as Device } from './compatibility/deviceWrapper.js';
 export type { BleManagerOptions, ScanOptions, ConnectionOptions, NativeBleError, NativeDevice, NativeService, NativeCharacteristic, NativeDescriptor, Subscription } from './specs/types.js';

package/lib/index.js

@@ -4,6 +4,8 @@ export * from './compatibility/constants.js';
 export * from './utils/index.js';
 // Export the main BleManager instance with compatibility wrapper
 export { BleManagerCompat as BleManager, createBleManagerCompat as createBleManager } from './BleManagerCompatFactory.js';
+// Export BleManager factory utilities (for internal use by error handling)
+export { getCustomErrorMessage, getStoredCallbacks } from './BleManagerFactory.js';
 // Export error handling utilities
 export * from './errors/BleError.js';
 // Export device wrapper for compatibility

package/lib/specs/BleManager.nitro.d.ts

@@ -1,10 +1,18 @@
 import type { HybridObject } from 'react-native-nitro-modules';
 import type { State, LogLevel, UUID, DeviceId, TransactionId, ConnectionPriority, ScanOptions, ConnectionOptions, StateListener, DeviceScanListener, DeviceDisconnectedListener, CharacteristicMonitorListener, CharacteristicSubscriptionType, NativeDevice, NativeService, NativeCharacteristic, NativeDescriptor, Base64, Subscription } from './types.js';
+export interface BleManagerNitroOptions {
+    restoreStateIdentifier?: string;
+}
+export interface BleRestoredState {
+    connectedPeripherals: NativeDevice[];
+}
 export interface BleManager extends HybridObject<{
     ios: 'swift';
     android: 'kotlin';
 }> {
     destroy(): Promise<void>;
+    initialize(options: BleManagerNitroOptions): Promise<void>;
+    getRestoredState(): Promise<BleRestoredState | null>;
     setLogLevel(logLevel: LogLevel): Promise<LogLevel>;
     logLevel(): Promise<LogLevel>;
     cancelTransaction(transactionId: TransactionId): Promise<void>;

package/lib/utils/base64.d.ts

@@ -1,4 +1,4 @@
-import type { Base64 } from '../specs/types';
+import type { Base64 } from '../specs/types.js';
 /**
  * Utility functions for Base64 encoding/decoding
  * Maintains compatibility with react-native-ble-plx Base64 operations

package/lib/utils/index.d.ts

@@ -1,2 +1,2 @@
-export * from './uuid';
-export * from './base64';
+export * from './uuid.js';
+export * from './base64.js';

package/lib/utils/index.js

@@ -1,2 +1,2 @@
-export * from './uuid';
-export * from './base64';
+export * from './uuid.js';
+export * from './base64.js';

package/lib/utils/uuid.d.ts

@@ -1,4 +1,4 @@
-import type { UUID } from '../specs/types';
+import type { UUID } from '../specs/types.js';
 /**
  * Converts UUID to full 128bit, lowercase format which should be used to compare UUID values.
  * This function maintains 100% compatibility with react-native-ble-plx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-ble-nitro",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "description": "High-performance React Native BLE library built on Nitro Modules - drop-in replacement for react-native-ble-plx",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -76,7 +76,7 @@
     "nitro-codegen": "^0.26.4",
     "react-native": "^0.76.0",
     "ts-jest": "^29.4.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.8.3"
   },
   "files": [
     "lib/",

package/src/BleManagerCompatFactory.ts

@@ -93,7 +93,7 @@ export class BleManagerCompat {
   async startDeviceScan(
     uuids: UUID[] | null,
     options: ScanOptions | null,
-    listener: (error: any | null, scannedDevice: DeviceWrapper | null) => void
+    listener: (error: any | null, scannedDevice: DeviceWrapper | null) => void // TODO: COMPAT! remove any and move to BleError as react-native-ble-plx uses this type as well!
   ): Promise<void> {
     return await this.bleManager.startDeviceScan(uuids, options, (error, device) => {
       listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
@@ -131,7 +131,7 @@ export class BleManagerCompat {
 
   onDeviceDisconnected(
     deviceIdentifier: DeviceId,
-    listener: (error: any | null, device: DeviceWrapper | null) => void
+    listener: (error: any | null, device: DeviceWrapper | null) => void // TODO: COMPAT! use propper error type like in react-native-ble-plx!!!
   ): Subscription {
     return this.bleManager.onDeviceDisconnected(deviceIdentifier, (error, device) => {
       listener(error, device ? new DeviceWrapper(this.createDeviceFromNative(device)) : null);
@@ -255,7 +255,7 @@ export class BleManagerCompat {
     deviceIdentifier: DeviceId,
     serviceUUID: UUID,
     characteristicUUID: UUID,
-    listener: (error: any | null, characteristic: NativeCharacteristic | null) => void,
+    listener: (error: any | null, characteristic: NativeCharacteristic | null) => void, // TODO: COMPAT! use proper error type like in react-native-ble-plx
     transactionId?: TransactionId,
     subscriptionType?: 'notification' | 'indication'
   ): Subscription {
@@ -324,7 +324,7 @@ export class BleManagerCompat {
    * Helper method to create a Device wrapper from NativeDevice data
    * This is a temporary method until we have proper Device Nitro objects
    */
-  private createDeviceFromNative(nativeDevice: NativeDevice): any {
+  private createDeviceFromNative(nativeDevice: NativeDevice) {
     // This is a placeholder - in the actual implementation, we'd need to create
     // proper Nitro Device objects, but for now we'll work with the native data
     return {

package/src/BleManagerFactory.ts

@@ -1,7 +1,13 @@
 import { NitroModules } from 'react-native-nitro-modules';
-import type { BleManager as BleManagerInterface } from './specs/BleManager.nitro.js';
+import type { BleManager as BleManagerInterface, BleManagerNitroOptions } from './specs/BleManager.nitro.js';
 import type { BleManagerOptions } from './specs/types.js';
 
+// Store callbacks that can't be passed to Nitro
+const storedCallbacks = new WeakMap<BleManagerInterface, {
+  restoreStateFunction?: (restoredState: any) => void;
+  errorCodesToMessagesMapping?: { [key: number]: string };
+}>();
+
 /**
  * Creates a BleManager instance using Nitro Modules
  * This function maintains compatibility with react-native-ble-plx's BleManager constructor
@@ -16,15 +22,72 @@ export function createBleManager(options?: BleManagerOptions): BleManagerInterfa
     );
   }
 
-  // If options are provided, we could initialize with them
-  // For now, we return the module directly as Nitro handles the native initialization
+  // Initialize with options if provided
+  if (options) {
+    // Extract Nitro-compatible options
+    const nitroOptions: BleManagerNitroOptions = {
+      restoreStateIdentifier: options.restoreStateIdentifier,
+    };
+
+    // Store callbacks and mappings that can't be passed to Nitro
+    if (options.restoreStateFunction || options.errorCodesToMessagesMapping) {
+      storedCallbacks.set(BleManagerModule, {
+        restoreStateFunction: options.restoreStateFunction,
+        errorCodesToMessagesMapping: options.errorCodesToMessagesMapping,
+      });
+    }
+
+    // Note: initialize() is async but we need to maintain sync compatibility with react-native-ble-plx
+    // The initialization will happen asynchronously in the background
+    BleManagerModule.initialize(nitroOptions).then(async () => {
+      // Check for restored state and call the callback if available
+      if (options.restoreStateFunction) {
+        try {
+          const restoredState = await BleManagerModule.getRestoredState();
+          if (restoredState) {
+            options.restoreStateFunction(restoredState);
+          }
+        } catch (error) {
+          console.warn('BleManager restore state callback failed:', error);
+        }
+      }
+    }).catch(error => {
+      console.warn('BleManager initialization failed:', error);
+    });
+  }
+
   return BleManagerModule;
 }
 
+/**
+ * Helper function to retrieve stored callbacks for a BleManager instance
+ * This is used internally when callbacks need to be invoked
+ */
+export function getStoredCallbacks(manager: BleManagerInterface) {
+  return storedCallbacks.get(manager);
+}
+
+/**
+ * Helper function to get custom error message if available
+ * @param manager The BleManager instance
+ * @param errorCode The BLE error code
+ * @param defaultMessage Default error message
+ * @returns Custom message if available, otherwise default message
+ */
+export function getCustomErrorMessage(
+  manager: BleManagerInterface,
+  errorCode: number,
+  defaultMessage: string
+): string {
+  const callbacks = storedCallbacks.get(manager);
+  const customMessage = callbacks?.errorCodesToMessagesMapping?.[errorCode];
+  return customMessage || defaultMessage;
+}
+
 /**
  * Legacy compatibility: Export a BleManager constructor function
  * This maintains compatibility with code that imports { BleManager } from 'react-native-ble-plx'
  */
 export const BleManager = function(options?: BleManagerOptions): BleManagerInterface {
   return createBleManager(options);
-} as any;
+} as (options?: BleManagerOptions) => BleManagerInterface;

package/src/__tests__/compatibility/enums.test.ts

@@ -16,7 +16,6 @@ import {
   normalizeCharacteristicSubscriptionType,
   State,
   LogLevel,
-  type CharacteristicSubscriptionType
 } from '../../compatibility/enums';
 import { 
   State as NitroState, 

package/src/index.ts

@@ -7,6 +7,9 @@ export * from './utils/index.js';
 // Export the main BleManager instance with compatibility wrapper
 export { BleManagerCompat as BleManager, createBleManagerCompat as createBleManager } from './BleManagerCompatFactory.js';
 
+// Export BleManager factory utilities (for internal use by error handling)
+export { getCustomErrorMessage, getStoredCallbacks } from './BleManagerFactory.js';
+
 // Export error handling utilities
 export * from './errors/BleError.js';
 

package/src/specs/BleManager.nitro.ts

@@ -8,7 +8,6 @@ import type {
   ConnectionPriority,
   ScanOptions,
   ConnectionOptions,
-  BleManagerOptions,
   StateListener,
   DeviceScanListener,
   DeviceDisconnectedListener,
@@ -18,16 +17,30 @@ import type {
   NativeService,
   NativeCharacteristic,
   NativeDescriptor,
-  NativeBleError,
-  BleRestoredState,
   Base64,
   Subscription
 } from './types.js';
 
+// Nitro-compatible options interface (simplified without functions)
+export interface BleManagerNitroOptions {
+  restoreStateIdentifier?: string;
+}
+
+// Interface for restored state data
+export interface BleRestoredState {
+  connectedPeripherals: NativeDevice[];
+}
+
 export interface BleManager extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
   // Lifecycle
   destroy(): Promise<void>;
 
+  // Initialization - Configure the BLE manager with options
+  initialize(options: BleManagerNitroOptions): Promise<void>;
+
+  // Get restored state if available (called after initialization)
+  getRestoredState(): Promise<BleRestoredState | null>;
+
   // Common operations
   setLogLevel(logLevel: LogLevel): Promise<LogLevel>;
   logLevel(): Promise<LogLevel>;

package/src/utils/base64.ts

@@ -1,4 +1,4 @@
-import type { Base64 } from '../specs/types';
+import type { Base64 } from '../specs/types.js';
 
 /**
  * Utility functions for Base64 encoding/decoding

package/src/utils/index.ts

@@ -1,2 +1,2 @@
-export * from './uuid';
-export * from './base64';
+export * from './uuid.js';
+export * from './base64.js';

package/src/utils/uuid.ts

@@ -1,4 +1,4 @@
-import type { UUID } from '../specs/types';
+import type { UUID } from '../specs/types.js';
 
 /**
  * Converts UUID to full 128bit, lowercase format which should be used to compare UUID values.