unified-ble-manager 4.0.0-alpha.0

package/package.json

@@ -0,0 +1,488 @@
+{
+  "name": "unified-ble-manager",
+  "version": "4.0.0-alpha.0",
+  "description": "Unified Bluetooth Low Energy manager for React Native, Electron, Web, and desktop (4.0 train; successor lineage of @sfourdrinier/react-native-ble-plx)",
+  "packageManager": "pnpm@10.14.0",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/commonjs/src/index.d.ts",
+  "source": "src/index",
+  "files": [
+    "lib",
+    "bin",
+    "android",
+    "ios",
+    "native",
+    "docs",
+    "ROADMAP.md",
+    "ROADMAP.4.0.md",
+    "plugin/build",
+    "app.plugin.js",
+    "*.podspec",
+    "!docs/superpowers",
+    "!docs/audits",
+    "!docs/review",
+    "!docs/evidence/g0/**",
+    "!docs/index.html",
+    "!docs/assets",
+    "!lib/typescript/example",
+    "!lib/typescript/example-expo",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!native/**/build",
+    "!native/**/*.node",
+    "!native/**/obj.target",
+    "!native/protocol/tests/**",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*",
+    "MIGRATION_4.0.md"
+  ],
+  "scripts": {
+    "build": "pnpm prepack",
+    "test": "pnpm test:package",
+    "test:package": "jest --config jest.config.js",
+    "native-protocol:generate": "node scripts/native-protocol/generate-native-protocol.js",
+    "native-protocol:check": "node scripts/native-protocol/generate-native-protocol.js --check",
+    "test:native-protocol": "node scripts/native-protocol/test-native-protocol.js",
+    "validate:evidence": "node scripts/evidence/validate-current-evidence.js",
+    "docs:backend-sdk": "node scripts/docs/generate-backend-sdk-reference.js",
+    "docs:check": "node scripts/docs/generate-backend-sdk-reference.js --check",
+    "cli": "node bin/ubm.js",
+    "pack:shim": "node scripts/prepare-shim-pack.js --pack --output-dir ./.artifacts/shim",
+    "docs": "pnpm prepack && documentation build lib/module/index.js -o docs --config documentation.yml -f html",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "lint": "eslint \"src/**/*.{ts,tsx}\" \"plugin/src/**/*.{ts,tsx}\" --max-warnings 0 && pnpm typecheck",
+    "prepack": "node scripts/ci/build-package.js",
+    "verify:release": "bash scripts/verify-release.sh",
+    "release": "release-it",
+    "example": "pnpm --dir example",
+    "build:android": "cd example/android && ./gradlew assembleDebug --no-daemon --console=plain -PreactNativeArchitectures=arm64-v8a",
+    "test:android": "cd example/android && ./gradlew assembleDebug --no-daemon --console=plain -PreactNativeArchitectures=arm64-v8a",
+    "build:ios": "cd example/ios && xcodebuild -workspace BlePlxExample.xcworkspace -scheme BlePlxExample -configuration Debug -sdk iphonesimulator CC=clang CPLUSPLUS=clang++ LD=clang LDPLUSPLUS=clang++ GCC_OPTIMIZATION_LEVEL=0 GCC_PRECOMPILE_PREFIX_HEADER=YES ASSETCATALOG_COMPILER_OPTIMIZATION=time DEBUG_INFORMATION_FORMAT=dwarf COMPILER_INDEX_STORE_ENABLE=NO",
+    "test:ios": "cd example/ios && xcodebuild -workspace BlePlxExample.xcworkspace -scheme BlePlxExample -configuration Debug -sdk iphonesimulator ASSETCATALOG_COMPILER_OPTIMIZATION=time DEBUG_INFORMATION_FORMAT=dwarf COMPILER_INDEX_STORE_ENABLE=NO",
+    "test:tvos:library": "bash scripts/ci/check-tvos-library.sh",
+    "test:expo": "pnpm --dir example-expo install --no-frozen-lockfile && pnpm --dir example-expo exec expo install --fix && pnpm --dir example-expo exec tsc --noEmit -p tsconfig.json && cd example-expo && npx expo-doctor && npx expo prebuild --clean --no-install",
+    "build:expo:android": "pnpm --dir example-expo install --no-frozen-lockfile && cd example-expo && npx expo prebuild --clean --no-install && cd android && ./gradlew :app:assembleDebug --no-daemon --console=plain",
+    "bootstrap": "pnpm --dir example install && pnpm install && pnpm --dir example pods",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build plugin/build lib",
+    "build:plugin": "tsc --build plugin",
+    "clean:plugin": "del-cli plugin/build",
+    "test:plugin": "jest --config plugin/jest.config.js",
+    "test:codemod": "node scripts/codemod/transform-bytes-path.js --check scripts/codemod/fixtures/before-read.js && node scripts/codemod/transform-bytes-path.js --check scripts/codemod/fixtures/before-read-safe.js && node scripts/codemod/transform-bytes-path.js --check scripts/codemod/fixtures/before-read-mixed.js",
+    "build:electron:macos": "cd native/electron/corebluetooth && node-gyp rebuild --release",
+    "build:electron:winrt": "cd native/electron/winrt && node-gyp rebuild --release",
+    "example:web": "pnpm prepack && npx --yes vite --config example-web/vite.config.js",
+    "example:electron": "pnpm prepack && electron example-electron/main.js",
+    "example:electron:live": "pnpm run build:electron:macos && pnpm prepack && node example-electron/live-polar.js",
+    "example:electron:ui:live": "pnpm run build:electron:macos && pnpm prepack && npx --yes @electron/rebuild -f -w native/electron/corebluetooth && ELECTRON_BLE_REQUIRE_NATIVE=1 electron example-electron/main.js",
+    "example:electron:smoke": "pnpm prepack && node example-electron/smoke.js",
+    "prepare": "pnpm clean:plugin && pnpm build:plugin",
+    "lint:plugin": "eslint plugin/src/*"
+  },
+  "keywords": [
+    "bluetooth",
+    "ble",
+    "unified-ble-manager",
+    "react-native",
+    "electron",
+    "web",
+    "corebluetooth",
+    "gatt",
+    "central"
+  ],
+  "bin": {
+    "ubm": "bin/ubm.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sfourdrinier/react-native-ble-plx.git"
+  },
+  "author": "sfourdrinier",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/sfourdrinier/react-native-ble-plx/issues"
+  },
+  "homepage": "https://github.com/sfourdrinier/react-native-ble-plx#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.25.9",
+    "@babel/core": "^7.25.2",
+    "@babel/preset-typescript": "^7.25.2",
+    "@commitlint/config-conventional": "^17.0.2",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^9.39.4",
+    "@evilmartians/lefthook": "^1.5.0",
+    "@expo/config-plugins": "^57.0.0",
+    "@react-native/eslint-config": "~0.86.0",
+    "@react-native/jest-preset": "~0.86.0",
+    "@react-native/metro-config": "~0.86.0",
+    "@react-native/typescript-config": "~0.86.0",
+    "@react-navigation/native": "^7.0.0",
+    "@react-navigation/native-stack": "^7.0.0",
+    "@release-it/conventional-changelog": "^11.0.1",
+    "@types/jest": "^29.5.5",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.2",
+    "@types/react-native-base64": "^0.2.2",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "babel-plugin-syntax-hermes-parser": "^0.15.1",
+    "commitlint": "^17.0.2",
+    "del-cli": "^5.1.0",
+    "documentation": "12.3.0",
+    "electron": "43.2.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-jsx-a11y": "^6.7.1",
+    "eslint-plugin-prettier": "^5.0.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-native": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.3",
+    "expo": "^57.0.0",
+    "expo-module-scripts": "^5.0.0",
+    "globals": "^17.7.0",
+    "hermes-eslint": "^0.15.1",
+    "jest": "^29.7.0",
+    "node-addon-api": "^8.9.0",
+    "node-gyp": "^13.0.1",
+    "prettier": "^3.0.3",
+    "react": "~19.2.0",
+    "react-native": "~0.86.0",
+    "react-native-base64": "^0.2.1",
+    "react-native-builder-bob": "^0.43.0",
+    "react-native-safe-area-context": "^5.0.0",
+    "react-native-toast-message": "^2.1.6",
+    "release-it": "^20.2.1",
+    "styled-components": "^6.1.11",
+    "turbo": "^1.10.7",
+    "typescript": "^5.2.2"
+  },
+  "resolutions": {
+    "@types/react": "^19.0.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.86.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^20.19.4 || ^22.13.0 || ^24.3.0 || >=25.0.0"
+  },
+  "codegenConfig": {
+    "name": "BlePlxSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.sfourdrinier.unifiedblemanager"
+    },
+    "ios": {
+      "modulesProvider": {
+        "BlePlx": "BlePlx",
+        "UnifiedBleProtocolControl": "UnifiedBleProtocolControl"
+      }
+    }
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/integration-tests",
+      "<rootDir>/example/node_modules",
+      "<rootDir>/example-expo/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": "angular"
+      }
+    }
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "{BleError.ts,BleManager.ts,BleModule.ts,Characteristic.ts,ConnectionManager.ts,Descriptor.ts,Device.ts,DeviceOperationQueue.ts,NativeBlePlx.ts,NativeUnifiedBleProtocolControl.ts,Service.ts,TypeDefinition.ts,Utils.ts,encoding.ts,longWrite.ts,permissions.ts,stringUtils.ts,supports.ts,unsupported.ts,**/{__tests__,__fixtures__,__mocks__,discovery,helpers,hosts,port}/**,profiles/{battery.ts,bloodPressure.ts,deviceInformation.ts,healthThermometer.ts,heartRate.ts,ieee11073.ts,index.ts,serviceHelpers.ts,types.ts}}",
+    "targets": [
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json",
+          "tsc": "./node_modules/.bin/tsc"
+        }
+      ]
+    ]
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/typescript/module/src/index.d.ts",
+        "default": "./lib/module/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      },
+      "default": "./lib/commonjs/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json",
+    "./backend-sdk": {
+      "import": {
+        "types": "./lib/typescript/module/src/backend-sdk.d.ts",
+        "default": "./lib/module/backend-sdk.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/backend-sdk.d.ts",
+        "default": "./lib/commonjs/backend-sdk.js"
+      },
+      "default": "./lib/commonjs/backend-sdk.js"
+    },
+    "./cli": {
+      "import": {
+        "types": "./lib/typescript/module/src/cli.d.ts",
+        "default": "./lib/module/cli.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/cli.d.ts",
+        "default": "./lib/commonjs/cli.js"
+      },
+      "default": "./lib/commonjs/cli.js"
+    },
+    "./testing": {
+      "import": {
+        "types": "./lib/typescript/module/src/testing.d.ts",
+        "default": "./lib/module/testing.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/testing.d.ts",
+        "default": "./lib/commonjs/testing.js"
+      },
+      "default": "./lib/commonjs/testing.js"
+    },
+    "./codecs": {
+      "import": {
+        "types": "./lib/typescript/module/src/codecs.d.ts",
+        "default": "./lib/module/codecs.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/codecs.d.ts",
+        "default": "./lib/commonjs/codecs.js"
+      },
+      "default": "./lib/commonjs/codecs.js"
+    },
+    "./profiles/commands": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/commands.d.ts",
+        "default": "./lib/module/profiles/commands.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/commands.d.ts",
+        "default": "./lib/commonjs/profiles/commands.js"
+      },
+      "default": "./lib/commonjs/profiles/commands.js"
+    },
+    "./profiles/standard-commands": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/standard-commands.d.ts",
+        "default": "./lib/module/profiles/standard-commands.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/standard-commands.d.ts",
+        "default": "./lib/commonjs/profiles/standard-commands.js"
+      },
+      "default": "./lib/commonjs/profiles/standard-commands.js"
+    },
+    "./profiles/heart-rate": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/heart-rate.d.ts",
+        "default": "./lib/module/profiles/heart-rate.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/heart-rate.d.ts",
+        "default": "./lib/commonjs/profiles/heart-rate.js"
+      },
+      "default": "./lib/commonjs/profiles/heart-rate.js"
+    },
+    "./profiles/battery-service": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/battery-service.d.ts",
+        "default": "./lib/module/profiles/battery-service.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/battery-service.d.ts",
+        "default": "./lib/commonjs/profiles/battery-service.js"
+      },
+      "default": "./lib/commonjs/profiles/battery-service.js"
+    },
+    "./profiles/device-information": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/device-information.d.ts",
+        "default": "./lib/module/profiles/device-information.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/device-information.d.ts",
+        "default": "./lib/commonjs/profiles/device-information.js"
+      },
+      "default": "./lib/commonjs/profiles/device-information.js"
+    },
+    "./profiles/health-thermometer": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/health-thermometer.d.ts",
+        "default": "./lib/module/profiles/health-thermometer.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/health-thermometer.d.ts",
+        "default": "./lib/commonjs/profiles/health-thermometer.js"
+      },
+      "default": "./lib/commonjs/profiles/health-thermometer.js"
+    },
+    "./profiles/blood-pressure": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/blood-pressure.d.ts",
+        "default": "./lib/module/profiles/blood-pressure.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/blood-pressure.d.ts",
+        "default": "./lib/commonjs/profiles/blood-pressure.js"
+      },
+      "default": "./lib/commonjs/profiles/blood-pressure.js"
+    },
+    "./profiles/ieee-11073": {
+      "import": {
+        "types": "./lib/typescript/module/src/profiles/ieee-11073.d.ts",
+        "default": "./lib/module/profiles/ieee-11073.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/profiles/ieee-11073.d.ts",
+        "default": "./lib/commonjs/profiles/ieee-11073.js"
+      },
+      "default": "./lib/commonjs/profiles/ieee-11073.js"
+    },
+    "./web": {
+      "import": {
+        "types": "./lib/typescript/module/src/web.d.ts",
+        "default": "./lib/module/web.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/web.d.ts",
+        "default": "./lib/commonjs/web.js"
+      },
+      "default": "./lib/commonjs/web.js"
+    },
+    "./react-native": {
+      "import": {
+        "types": "./lib/typescript/module/src/react-native.d.ts",
+        "default": "./lib/module/react-native.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/react-native.d.ts",
+        "default": "./lib/commonjs/react-native.js"
+      },
+      "default": "./lib/commonjs/react-native.js"
+    },
+    "./node/bluez": {
+      "import": {
+        "types": "./lib/typescript/module/src/node-bluez.d.ts",
+        "default": "./lib/module/node-bluez.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/node-bluez.d.ts",
+        "default": "./lib/commonjs/node-bluez.js"
+      },
+      "default": "./lib/commonjs/node-bluez.js"
+    },
+    "./node/corebluetooth": {
+      "import": {
+        "types": "./lib/typescript/module/src/node-corebluetooth.d.ts",
+        "default": "./lib/module/node-corebluetooth.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/node-corebluetooth.d.ts",
+        "default": "./lib/commonjs/node-corebluetooth.js"
+      },
+      "default": "./lib/commonjs/node-corebluetooth.js"
+    },
+    "./node/winrt": {
+      "import": {
+        "types": "./lib/typescript/module/src/node-winrt.d.ts",
+        "default": "./lib/module/node-winrt.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/node-winrt.d.ts",
+        "default": "./lib/commonjs/node-winrt.js"
+      },
+      "default": "./lib/commonjs/node-winrt.js"
+    },
+    "./electron/main": {
+      "import": {
+        "types": "./lib/typescript/module/src/electron-main.d.ts",
+        "default": "./lib/module/electron-main.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/electron-main.d.ts",
+        "default": "./lib/commonjs/electron-main.js"
+      },
+      "default": "./lib/commonjs/electron-main.js"
+    },
+    "./electron/renderer": {
+      "import": {
+        "types": "./lib/typescript/module/src/electron-renderer.d.ts",
+        "default": "./lib/module/electron-renderer.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/electron-renderer.d.ts",
+        "default": "./lib/commonjs/electron-renderer.js"
+      },
+      "default": "./lib/commonjs/electron-renderer.js"
+    }
+  },
+  "optionalDependencies": {
+    "dbus-next": "^0.10.2"
+  }
+}

package/plugin/build/debugLog.d.ts

@@ -0,0 +1,2 @@
+export declare function isBlePlxPluginDebugEnabled(propDebug?: boolean): boolean;
+export declare function blePlxPluginDebugLog(enabled: boolean, ...args: unknown[]): void;

package/plugin/build/debugLog.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlePlxPluginDebugEnabled = isBlePlxPluginDebugEnabled;
+exports.blePlxPluginDebugLog = blePlxPluginDebugLog;
+function isBlePlxPluginDebugEnabled(propDebug) {
+    if (propDebug === true)
+        return true;
+    const env = process.env.BLEPLX_PLUGIN_DEBUG;
+    if (!env)
+        return false;
+    return env === '1' || env.toLowerCase() === 'true' || env.toLowerCase() === 'yes';
+}
+function blePlxPluginDebugLog(enabled, ...args) {
+    if (!enabled)
+        return;
+    // eslint-disable-next-line no-console
+    console.log('[BLEPLX_PLUGIN]', ...args);
+}

package/plugin/build/withBLE.d.ts

@@ -0,0 +1,18 @@
+import { type ConfigPlugin } from '@expo/config-plugins';
+import { BackgroundMode } from './withBLEBackgroundModes';
+export { BackgroundMode };
+declare const _default: ConfigPlugin<void | {
+    /** Enable debug logging for this config plugin (also controllable via BLEPLX_PLUGIN_DEBUG=1). */
+    debug?: boolean;
+    isBackgroundEnabled?: boolean;
+    neverForLocation?: boolean;
+    modes?: BackgroundMode[];
+    bluetoothAlwaysPermission?: string | false;
+    /** Enable iOS BLE state restoration support (Restoration subspec) */
+    iosEnableRestoration?: boolean;
+    /** Optional custom restoration identifier passed to iOS central manager */
+    iosRestorationIdentifier?: string;
+    /** Enable Android foreground service for background BLE operations */
+    androidEnableForegroundService?: boolean;
+}>;
+export default _default;

package/plugin/build/withBLE.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundMode = void 0;
+const config_plugins_1 = require("@expo/config-plugins");
+// Path is ../../package.json because this file is compiled to plugin/build/withBLE.js
+const pkg = require('../../package.json');
+const withBLEAndroidManifest_1 = require("./withBLEAndroidManifest");
+const withBLEAndroidForegroundService_1 = require("./withBLEAndroidForegroundService");
+const withBLEBackgroundModes_1 = require("./withBLEBackgroundModes");
+Object.defineProperty(exports, "BackgroundMode", { enumerable: true, get: function () { return withBLEBackgroundModes_1.BackgroundMode; } });
+const withBluetoothPermissions_1 = require("./withBluetoothPermissions");
+const withBLEDebugLogging_1 = require("./withBLEDebugLogging");
+const withBLERestorationPodfile_1 = require("./withBLERestorationPodfile");
+const debugLog_1 = require("./debugLog");
+/**
+ * Apply BLE native configuration.
+ */
+const withBLE = (config, props = {}) => {
+    const _props = props || {};
+    const debugEnabled = (0, debugLog_1.isBlePlxPluginDebugEnabled)(_props.debug);
+    (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'Plugin running with props:', JSON.stringify(props));
+    (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'Package name from pkg.json:', pkg.name);
+    config = (0, withBLEDebugLogging_1.withBLEDebugLogging)(config, { debugEnabled });
+    const isBackgroundEnabled = _props.isBackgroundEnabled ?? false;
+    const neverForLocation = _props.neverForLocation ?? false;
+    const iosEnableRestoration = _props.iosEnableRestoration ?? false;
+    const iosRestorationIdentifier = _props.iosRestorationIdentifier ?? 'com.reactnativebleplx.restore';
+    const androidEnableForegroundService = _props.androidEnableForegroundService ?? false;
+    (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'iosEnableRestoration:', iosEnableRestoration);
+    (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'androidEnableForegroundService:', androidEnableForegroundService);
+    // iOS
+    config = (0, withBluetoothPermissions_1.withBluetoothPermissions)(config, _props);
+    config = (0, withBLEBackgroundModes_1.withBLEBackgroundModes)(config, _props.modes || []);
+    // Always run so true→false flips strip sticky Podfile/plist artifacts (#32).
+    if (iosEnableRestoration) {
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, '✓ iosEnableRestoration is TRUE - adding Restoration subspec');
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'Setting BlePlxRestoreIdentifier in Info.plist:', iosRestorationIdentifier);
+        config = (0, config_plugins_1.withInfoPlist)(config, conf => {
+            conf.modResults = (0, withBLERestorationPodfile_1.setBlePlxRestoreIdentifier)(conf.modResults, iosRestorationIdentifier);
+            return conf;
+        });
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, 'Calling withBLERestorationPodfile (enable) with pkgName:', pkg.name);
+        config = (0, withBLERestorationPodfile_1.withBLERestorationPodfile)(config, { pkgName: pkg.name, enable: true });
+    }
+    else {
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, '✗ iosEnableRestoration is FALSE - removing Restoration subspec / BlePlxRestoreIdentifier if present');
+        config = (0, config_plugins_1.withInfoPlist)(config, conf => {
+            conf.modResults = (0, withBLERestorationPodfile_1.clearBlePlxRestoreIdentifier)(conf.modResults);
+            return conf;
+        });
+        config = (0, withBLERestorationPodfile_1.withBLERestorationPodfile)(config, { pkgName: pkg.name, enable: false });
+    }
+    // Android
+    config = config_plugins_1.AndroidConfig.Permissions.withPermissions(config, [
+        'android.permission.BLUETOOTH',
+        'android.permission.BLUETOOTH_ADMIN',
+        'android.permission.BLUETOOTH_CONNECT' // since Android SDK 31
+    ]);
+    config = (0, withBLEAndroidManifest_1.withBLEAndroidManifest)(config, {
+        isBackgroundEnabled,
+        neverForLocation
+    });
+    // Always run so an enabled-to-disabled config transition removes the plugin's sticky FGS entries.
+    if (androidEnableForegroundService) {
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, '✓ androidEnableForegroundService is TRUE - adding foreground service config');
+    }
+    else {
+        (0, debugLog_1.blePlxPluginDebugLog)(debugEnabled, '✗ androidEnableForegroundService is FALSE - removing foreground service config');
+    }
+    config = (0, withBLEAndroidForegroundService_1.withBLEAndroidForegroundService)(config, {
+        enableAndroidForegroundService: androidEnableForegroundService
+    });
+    return config;
+};
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withBLE, pkg.name, pkg.version);

package/plugin/build/withBLEAndroidForegroundService.d.ts

@@ -0,0 +1,40 @@
+import { type ConfigPlugin } from '@expo/config-plugins';
+import type { AndroidManifestWithExtraTools } from './withBLEAndroidManifest';
+/**
+ * Add foreground service permissions and service declaration to AndroidManifest.xml
+ *
+ * This enables background BLE operations on Android by:
+ * 1. Adding FOREGROUND_SERVICE permission
+ * 2. Adding FOREGROUND_SERVICE_CONNECTED_DEVICE permission (Android 14+)
+ * 3. Declaring the BlePlxForegroundService in the manifest
+ */
+export declare const withBLEAndroidForegroundService: ConfigPlugin<{
+    enableAndroidForegroundService: boolean;
+}>;
+/**
+ * Add FOREGROUND_SERVICE, FOREGROUND_SERVICE_CONNECTED_DEVICE, and POST_NOTIFICATIONS permissions.
+ * POST_NOTIFICATIONS (API 33+) is required for the FGS persistent notification to be user-visible;
+ * the host app must still request it at runtime (R2-F031).
+ */
+export declare const FOREGROUND_SERVICE_PERMISSIONS: string[];
+/** Manifest meta-data marker recording exactly what this plugin inserted on a prior enabled prebuild. */
+export declare const FOREGROUND_SERVICE_OWNERSHIP_METADATA_NAME = "com.sfourdrinier.unifiedblemanager.foreground-service-ownership";
+/**
+ * FQCN of the library foreground service — must match Android `namespace`
+ * (`com.sfourdrinier.unifiedblemanager`) + `BlePlxForegroundService` class.
+ */
+export declare const BLE_PLX_FOREGROUND_SERVICE_NAME = "com.sfourdrinier.unifiedblemanager.BlePlxForegroundService";
+/** @deprecated 3.9 FQCN; still recognized so re-prebuild does not double-declare */
+export declare const BLE_PLX_FOREGROUND_SERVICE_NAME_LEGACY = "com.bleplx.BlePlxForegroundService";
+/**
+ * Add BlePlxForegroundService declaration to the application.
+ * Exported for unit tests (Phase 0 identity / FGS FQCN contract).
+ */
+export declare function addForegroundServiceDeclaration(androidManifest: AndroidManifestWithExtraTools): boolean;
+/**
+ * Remove only entries that the ownership marker proves this plugin added on an
+ * earlier enabled prebuild. Generic Android permissions may belong to another
+ * foreground service in the host application and must never be inferred owned.
+ */
+export declare function removeForegroundServiceConfiguration(androidManifest: AndroidManifestWithExtraTools): void;
+export default withBLEAndroidForegroundService;