kard-network-ble-mesh 1.0.0

package/README.md

@@ -0,0 +1,216 @@
+# kard-network-ble-mesh
+
+A React Native library for BLE (Bluetooth Low Energy) mesh networking. Build decentralized, peer-to-peer messaging apps that work without internet connectivity.
+
+## Features
+
+- **Cross-platform**: Works on both iOS and Android
+- **Mesh networking**: Messages automatically relay through peers
+- **End-to-end encryption**: Noise protocol for secure private messages
+- **Seamless permissions**: Handles permission requests automatically
+- **Message deduplication**: Built-in deduplication prevents duplicate messages
+- **Peer discovery**: Automatic discovery of nearby devices
+
+## Installation
+
+```bash
+npm install kard-network-ble-mesh
+# or
+yarn add kard-network-ble-mesh
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+Add the following to your `Info.plist`:
+
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>This app uses Bluetooth to communicate with nearby devices</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>This app uses Bluetooth to communicate with nearby devices</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>bluetooth-central</string>
+  <string>bluetooth-peripheral</string>
+</array>
+```
+
+### Android
+
+Add the following permissions to your `AndroidManifest.xml` (they are already included in the library manifest):
+
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+```
+
+## Usage
+
+```typescript
+import { BleMesh } from 'kard-network-ble-mesh';
+
+// Start the mesh service (automatically requests permissions)
+await BleMesh.start({ nickname: 'Alice' });
+
+// Listen for events
+BleMesh.onPeerListUpdated(({ peers }) => {
+  console.log('Connected peers:', peers);
+});
+
+BleMesh.onMessageReceived(({ message }) => {
+  console.log('Received message:', message);
+});
+
+// Send a public broadcast message
+await BleMesh.sendMessage('Hello everyone!');
+
+// Send a private encrypted message
+await BleMesh.sendPrivateMessage('Secret message', recipientPeerId);
+
+// Get current peers
+const peers = await BleMesh.getPeers();
+
+// Stop the service
+await BleMesh.stop();
+```
+
+## API Reference
+
+### BleMesh
+
+The main singleton instance for interacting with the BLE mesh.
+
+#### Methods
+
+##### `start(config?: MeshServiceConfig): Promise<void>`
+
+Starts the mesh service. Automatically requests required permissions.
+
+```typescript
+interface MeshServiceConfig {
+  nickname?: string;              // Default: 'anon'
+  autoRequestPermissions?: boolean; // Default: true
+}
+```
+
+##### `stop(): Promise<void>`
+
+Stops the mesh service and disconnects from all peers.
+
+##### `setNickname(nickname: string): Promise<void>`
+
+Updates your nickname and broadcasts the change to peers.
+
+##### `getMyPeerId(): Promise<string>`
+
+Returns your unique peer ID (derived from your public key fingerprint).
+
+##### `getMyNickname(): Promise<string>`
+
+Returns your current nickname.
+
+##### `getPeers(): Promise<Peer[]>`
+
+Returns an array of all discovered peers.
+
+```typescript
+interface Peer {
+  peerId: string;
+  nickname: string;
+  isConnected: boolean;
+  rssi?: number;
+  lastSeen: number;
+  isVerified: boolean;
+}
+```
+
+##### `sendMessage(content: string, channel?: string): Promise<string>`
+
+Sends a public broadcast message. Returns the message ID.
+
+##### `sendPrivateMessage(content: string, recipientPeerId: string): Promise<string>`
+
+Sends an encrypted private message to a specific peer. Returns the message ID.
+
+##### `sendReadReceipt(messageId: string, recipientPeerId: string): Promise<void>`
+
+Sends a read receipt for a received message.
+
+##### `hasEncryptedSession(peerId: string): Promise<boolean>`
+
+Checks if an encrypted session exists with the specified peer.
+
+##### `initiateHandshake(peerId: string): Promise<void>`
+
+Initiates a Noise handshake with a peer for encrypted communication.
+
+##### `getIdentityFingerprint(): Promise<string>`
+
+Returns your identity fingerprint for verification.
+
+##### `getPeerFingerprint(peerId: string): Promise<string | null>`
+
+Returns a peer's identity fingerprint for verification.
+
+##### `broadcastAnnounce(): Promise<void>`
+
+Forces a broadcast announce to refresh your presence on the mesh.
+
+#### Events
+
+##### `onPeerListUpdated(callback): () => void`
+
+Called when the peer list changes.
+
+```typescript
+BleMesh.onPeerListUpdated(({ peers }) => {
+  console.log('Peers updated:', peers);
+});
+```
+
+##### `onMessageReceived(callback): () => void`
+
+Called when a message is received.
+
+```typescript
+BleMesh.onMessageReceived(({ message }) => {
+  console.log('Message from', message.senderNickname, ':', message.content);
+});
+```
+
+##### `onConnectionStateChanged(callback): () => void`
+
+Called when the connection state changes.
+
+##### `onReadReceipt(callback): () => void`
+
+Called when a read receipt is received.
+
+##### `onDeliveryAck(callback): () => void`
+
+Called when a delivery acknowledgment is received.
+
+##### `onError(callback): () => void`
+
+Called when an error occurs.
+
+## Protocol Compatibility
+
+This library uses the same binary protocol as:
+- [bitchat (iOS)](https://github.com/permissionlesstech/bitchat)
+- [bitchat-android](https://github.com/permissionlesstech/bitchat-android)
+
+Messages can be exchanged between all three platforms.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,94 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.1.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0"
+  }
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["BleMesh_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["BleMesh_" + name]).toInteger()
+}
+
+def supportsNamespace() {
+  def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+  def major = parsed[0].toInteger()
+  def minor = parsed[1].toInteger()
+  return (major == 7 && minor >= 3) || major >= 8
+}
+
+android {
+  if (supportsNamespace()) {
+    namespace "com.blemesh"
+
+    sourceSets {
+      main {
+        manifest.srcFile "src/main/AndroidManifestNew.xml"
+      }
+    }
+  }
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  kotlinOptions {
+    jvmTarget = "1.8"
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs = ['src/main/java']
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
+  implementation "androidx.core:core-ktx:1.12.0"
+}

package/android/gradle.properties

@@ -0,0 +1,4 @@
+BleMesh_kotlinVersion=1.9.0
+BleMesh_minSdkVersion=24
+BleMesh_targetSdkVersion=34
+BleMesh_compileSdkVersion=34

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.blemesh">
+
+    <!-- BLE Permissions -->
+    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+
+    <!-- Location Permissions (required for BLE scanning) -->
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+    <!-- Declare BLE feature -->
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+
+</manifest>

package/android/src/main/AndroidManifestNew.xml

@@ -0,0 +1,17 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- BLE Permissions -->
+    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+
+    <!-- Location Permissions (required for BLE scanning) -->
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+    <!-- Declare BLE feature -->
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
+
+</manifest>