capacitor-messenger-notifications 1.0.0 → 1.0.1

package/MessengerNotifications.podspec

@@ -13,6 +13,7 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.ios.deployment_target  = '13.0'
   s.dependency 'Capacitor'
-  s.dependency 'Socket.io-client-swift', '~> 15.0'
+  s.dependency 'Socket.io-client-swift', '~> 16.0'
+  s.dependency 'Sodium', '~> 0.9'
   s.swift_version = '5.1'
 end

package/Package.swift

@@ -11,7 +11,8 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.1.0"),
-        .package(url: "https://github.com/socketio/socket.io-client-swift.git", from: "16.1.0")
+        .package(url: "https://github.com/socketio/socket.io-client-swift.git", from: "16.1.0"),
+        .package(url: "https://github.com/jedisct1/swift-sodium.git", from: "0.9.1")
     ],
     targets: [
         .target(
@@ -19,7 +20,8 @@ let package = Package(
             dependencies: [
                 .product(name: "Capacitor", package: "capacitor-swift-pm"),
                 .product(name: "Cordova", package: "capacitor-swift-pm"),
-                .product(name: "SocketIO", package: "socket.io-client-swift")
+                .product(name: "SocketIO", package: "socket.io-client-swift"),
+                .product(name: "Sodium", package: "swift-sodium")
             ],
             path: "ios/Sources/MessengerNotificationsPlugin")
     ]

package/README.md

@@ -10,23 +10,41 @@ Capacitor plugin for managing messenger-style notifications with WebSocket suppo
 - [Requirements](#requirements)
 - [Install](#install)
 - [Usage](#usage)
-  - [JavaScript Examples](#javascript-examples)
-  - [Native Integration (Android/iOS)](#native-integration-androidios)
-- [Configuration](#configuration)
-- [Platform Implementation](#platform-implementation)
+  - [Permissions](#permissions)
+  - [Show a Notification](#show-a-notification)
+  - [Clear a Room's Notifications](#clear-a-rooms-notifications)
+  - [Cold-Start Navigation](#cold-start-navigation)
+  - [Persistent Socket (Android)](#persistent-socket-android)
+  - [FCM Token Registration](#fcm-token-registration)
+  - [Native Integration](#native-integration)
 - [Setup by Platform](#setup-by-platform)
+  - [Android](#android)
+  - [iOS](#ios)
+- [How It Works](#how-it-works)
 - [API](#api)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 
+---
+
 ## Features
 
-- **Native Notification Grouping**: Automatically groups messages by room ID using `MessagingStyle` (Android) and `threadIdentifier` (iOS).
-- **Persistent WebSocket (Android)**: Foreground service that stays alive to receive messages even when the app is killed.
-- **Background Fetch (iOS)**: Automatically wakes up to fetch unread messages when a silent push is received.
-- **End-to-End Encryption Ready**: Designed to handle encrypted payloads and decrypt them on-device before showing notifications.
+- **Native Notification Grouping**: Groups messages per room using `MessagingStyle` (Android) and `threadIdentifier` (iOS), keyed dynamically off the host app's package/bundle ID.
+- **End-to-End Decryption**: Decrypts room names, usernames, and message bodies on-device using Libsodium (Android) and swift-sodium (iOS) before showing any notification.
+- **Persistent WebSocket (Android)**: A foreground service maintains a live Socket.IO connection for devices without Google Play Services (GMS), auto-reconnecting on token or network changes.
+- **FCM Background Fetch (Android)**: On GMS devices, `FcmFetchForegroundService` + `FcmFetchBackgroundService` spin up a short-lived socket session triggered by each FCM push and tear it down cleanly.
+- **Job Scheduler Retry (Android)**: `FcmJobService` schedules a retry via `JobScheduler` if the primary fetch fails, ensuring no message is dropped.
+- **Background Fetch (iOS)**: `TemporarySocketSessionManager` opens a short-lived Socket.IO session inside `didReceiveRemoteNotification` with idle and max-session timeouts.
+- **HTTP Unread Fallback**: Both platforms fall back to fetching from the `/api/rooms/messages/unread` endpoint when a socket session cannot decrypt a message.
+- **Rich Notifications**: Custom SVG avatar rendering (Android via AndroidSVG), conversation shortcuts, and dismissal tracking.
+- **Notification Deduplication**: In-memory + persisted message ID tracking prevents showing the same message twice across socket and FCM paths.
+- **Dynamic Resources**: All icon, app name, and notification group key lookups are resolved from the host app at runtime — no hardcoded app-specific values.
+- **`window.Notification` Polyfill (Android)**: Injects a polyfill into the WebView so the JS app's `new Notification(...)` calls route through the native plugin.
+- **FCM Token Registration**: Registers the device's FCM push token with your backend API automatically after login.
+
+---
 
 ## Requirements
 
@@ -35,6 +53,8 @@ Capacitor plugin for managing messenger-style notifications with WebSocket suppo
 - **iOS**: 13.0 or higher
 - **Android**: API level 22 (Android 5.1) or higher
 
+---
+
 ## Install
 
 ```bash
@@ -42,111 +62,356 @@ npm install capacitor-messenger-notifications
 npx cap sync
 ```
 
+---
+
 ## Usage
 
-### JavaScript Examples
+### Permissions
 
-#### Start Persistent Socket (Android)
+Before showing notifications, check and request permission:
 
 ```typescript
 import { MessengerNotifications } from 'capacitor-messenger-notifications';
 
-// Starts a foreground service on Android to maintain a heartbeat connection
-await MessengerNotifications.startPersistentSocket({
-  url: 'wss://your-chat-server.com',
-  token: 'YOUR_AUTH_TOKEN'
-});
+const status = await MessengerNotifications.checkPermissions();
+
+if (status.notifications !== 'granted') {
+  const result = await MessengerNotifications.requestPermissions();
+  if (result.notifications !== 'granted') {
+    console.warn('Notification permission denied');
+  }
+}
 ```
 
-#### Show a Manual Notification
+### Show a Notification
 
 ```typescript
 await MessengerNotifications.showNotification({
-  title: 'John Doe',
+  title: 'Alice',
   body: 'Hey, how are you?',
   roomId: 101,
   roomName: 'General Chat',
   messageId: 'uuid-12345',
-  timestamp: Date.now()
+  timestamp: Date.now(),
+  senderId: 42,
+  avatarSvg: '<svg>...</svg>', // optional SVG string for sender avatar
 });
 ```
 
-### Native Integration (Android/iOS)
-
-This plugin is often triggered from native background tasks (FCM / Silent Push).
+### Clear a Room's Notifications
 
-- **Android**: Use `EncryptedMessageNotifier.notifyFromSocketPayload(context, data)` from your background services.
-- **iOS**: Use `TemporarySocketSessionManager.shared.fetchAndNotify(...)` inside `didReceiveRemoteNotification`.
+```typescript
+await MessengerNotifications.clearRoomNotification({ roomId: 101 });
+```
 
-## Configuration
+### Cold-Start Navigation
 
-Most configurations are handled dynamically via the API, but you can define defaults in **`capacitor.config.json`**:
+When the user taps a notification to open the app, retrieve the room to navigate to:
 
-```json
-{
-  "plugins": {
-    "MessengerNotifications": {
-      "defaultSocketUrl": "wss://your-default-server.com",
-      "notificationChannelId": "chat_messages",
-      "notificationChannelName": "Messenger Notifications"
-    }
-  }
+```typescript
+const { roomId } = await MessengerNotifications.getPendingRoomId();
+if (roomId !== null) {
+  router.push(`/room/${roomId}`);
 }
 ```
 
-## Platform Implementation
+### Persistent Socket (Android)
 
-| Platform | Implementation |
-| --- | --- |
-| Android | Foreground Service + NotificationManager with `MessagingStyle`. |
-| iOS | `UNNotificationContent` with `threadIdentifier` + SocketIO Task. |
+On non-GMS Android devices the plugin starts a foreground service that keeps a Socket.IO connection alive. Call this after the user logs in:
 
-## Setup by Platform
+```typescript
+await MessengerNotifications.startPersistentSocket({
+  url: 'wss://your-chat-server.com',
+  token: 'YOUR_AUTH_JWT',
+});
+
+// Call when the user logs out
+await MessengerNotifications.stopPersistentSocket();
+```
+
+> On GMS devices the socket is only opened for the duration of each incoming FCM push. `startPersistentSocket` stores the credentials but does not start the service.
+
+### FCM Token Registration
+
+After the user logs in, trigger FCM token registration with your backend:
+
+```typescript
+await MessengerNotifications.registerFcmToken();
+```
 
-> For full host‑app steps (Android & iOS), see `HOST_APP_SETUP.md`.
+The plugin reads the FCM token and JWT from `safe_storage` (SharedPreferences / UserDefaults) and POSTs to `{backendBaseUrl}/api/users/fcm-token`. Registration is skipped automatically if it has already succeeded.
+
+### Native Integration
+
+The plugin is typically triggered from native background handlers:
+
+**Android** — Inside your `FirebaseMessagingService.onMessageReceived`:
+
+```java
+// Kicks off the full fetch → decrypt → notify pipeline
+FcmFetchManager.retrieveMessages(context, remoteMessage.getData());
+```
+
+**iOS** — Inside `application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`:
+
+```swift
+EncryptedMessageNotifier.notifyFromPushData(userInfo as? [String: Any] ?? [:])
+```
+
+---
+
+## Setup by Platform
 
 ### Android
 
-- **AndroidManifest.xml**: Add `FOREGROUND_SERVICE` and `POST_NOTIFICATIONS` permissions.
-- **ProGuard**: Add `-keep` rules for the plugin and Socket.IO.
+#### 1. Safe Storage Keys
+
+The plugin reads credentials from `SharedPreferences` file `"safe_storage"`. Your JS app should write the following keys (e.g. via a SafeStorage plugin):
+
+| Key | Description |
+| --- | --- |
+| `token` / `authToken` | User's JWT for socket auth and API calls |
+| `socketUrl` | WebSocket server URL |
+| `backendBaseUrl` / `serverUrl` / ... | HTTP base URL for the unread messages API |
+| `fcmToken` | FCM registration token (written by Firebase) |
+| `roomDecryptedKeys` | JSON map of room E2EE private keys |
+| `memberDecryptedKeys` | JSON map of member E2EE private keys |
+
+#### 2. Required Resources
+
+Add the following drawables to your host app's `res/drawable/` so the plugin can find them at runtime (fallback to system icons if absent):
+
+| Resource | Purpose |
+| --- | --- |
+| `ic_notification.png` | Small notification icon (monochrome, white on transparent) |
+| `ic_transparent.png` | Transparent icon for the persistent service notification |
+
+#### 3. AndroidManifest.xml
+
+The plugin's manifest already declares all necessary services and permissions. If you need to override, merge the following into your app's manifest:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+```
+
+#### 4. ProGuard
+
+Add to your `proguard-rules.pro`:
+
+```proguard
+-keep class com.codecraft_studio.messenger.notifications.** { *; }
+-keep class io.socket.** { *; }
+-keep class org.java_websocket.** { *; }
+```
+
+---
 
 ### iOS
 
-- **Capabilities**: Enable **Push Notifications** and **Background Modes** (Background fetch, Remote notifications).
+#### 1. Capabilities
 
-## API
+In Xcode, enable the following for your app target:
+
+- **Push Notifications**
+- **Background Modes** → check *Remote notifications* and *Background fetch*
+
+#### 2. AppDelegate
+
+Forward remote notifications to the plugin:
 
-| Method | Description |
+```swift
+import UIKit
+import Capacitor
+
+@UIApplicationMain
+class AppDelegate: UIResponder, UIApplicationDelegate {
+
+    func application(
+        _ application: UIApplication,
+        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
+    ) {
+        let data = userInfo as? [String: Any] ?? [:]
+        let handled = EncryptedMessageNotifier.notifyFromPushData(data)
+        completionHandler(handled ? .newData : .noData)
+    }
+}
+```
+
+#### 3. Safe Storage Keys
+
+The plugin reads from `UserDefaults` suite `"safe_storage"`. Write the following keys from your JS app:
+
+| Key | Description |
 | --- | --- |
-| `startPersistentSocket(options)` | Starts the background socket service (Android only). |
-| `stopPersistentSocket()` | Stops the background socket service. |
-| `showNotification(options)` | Manually triggers a native grouped notification. |
-| `clearRoomNotification(options)` | Clears all notifications for a specific room. |
-| `getPendingRoomId()` | Returns the roomId if the app was launched from a notification. |
+| `token` / `authToken` | User's JWT |
+| `socketUrl` | WebSocket server URL |
+| `backendBaseUrl` / `serverUrl` / ... | HTTP base URL |
+| `fcmToken` | APNs/FCM token |
+| `roomDecryptedKeys` | JSON map of room E2EE private keys |
+| `memberDecryptedKeys` | JSON map of member E2EE private keys |
+
+---
+
+## How It Works
+
+### Message Flow (Android)
+
+```text
+FCM push received
+       │
+       ▼
+FcmFetchManager.retrieveMessages()
+       │
+       ├─► FcmFetchForegroundService  (keep process alive + wake lock)
+       │
+       ├─► TemporarySocketSessionManager.runSession()
+       │         └─► socket.emit("sync_messages")
+       │              └─► EncryptedMessageNotifier.notifyFromSyncMessagesResponse()
+       │                       └─► NativeCrypto.decrypt*()
+       │                              └─► NotificationHelper.showRoomNotification()
+       │
+       └─► [fallback] UnreadMessagesFetcher.fetchAndNotify()  (HTTP API)
+```
+
+### Message Flow (iOS)
+
+```text
+Silent push received
+       │
+       ▼
+EncryptedMessageNotifier.notifyFromPushData()
+       │
+       ├─► Direct decrypt from push payload
+       │
+       └─► [fallback] TemporarySocketSessionManager.runSession()
+                  └─► UnreadMessagesFetcher.fetchAndNotify()  (HTTP API)
+```
+
+---
+
+## API
+
+### `showNotification(options)`
+
+Shows a native grouped chat notification.
+
+| Option      | Type     | Required | Description                                                |
+| ----------- | -------- | -------- | ---------------------------------------------------------- |
+| `title`     | `string` | ✓        | Sender name displayed in the notification                  |
+| `body`      | `string` | ✓        | Message body                                               |
+| `roomId`    | `number` | ✓        | Room identifier used for grouping                          |
+| `messageId` | `string` |          | Unique message ID for deduplication                        |
+| `timestamp` | `number` |          | Unix timestamp (ms) for message ordering                   |
+| `roomName`  | `string` |          | Room display name shown in notification subtitle           |
+| `senderId`  | `number` |          | Sender's user ID (used for avatar/Person identity)         |
+| `avatarSvg` | `string` |          | SVG string for the sender's avatar                         |
+
+---
+
+### `clearRoomNotification(options)`
+
+Cancels all active notifications for a room and clears its in-memory history.
+
+| Option   | Type     | Required | Description                                  |
+| -------- | -------- | -------- | -------------------------------------------- |
+| `roomId` | `number` | ✓        | Room whose notifications should be cleared   |
+
+---
+
+### `getPendingRoomId()`
+
+Returns the `roomId` from the notification that launched the app (cold start), then clears it. Returns `{ roomId: null }` if the app was not opened via a notification.
+
+---
+
+### `startPersistentSocket(options)`
+
+Stores socket credentials and starts the persistent foreground service on non-GMS Android devices.
+
+| Option  | Type     | Required | Description          |
+| ------- | -------- | -------- | -------------------- |
+| `url`   | `string` | ✓        | WebSocket server URL |
+| `token` | `string` | ✓        | JWT auth token       |
+
+---
+
+### `stopPersistentSocket()`
+
+Stops the persistent socket foreground service.
+
+---
+
+### `checkPermissions()`
+
+Returns the current notification permission state.
+
+**Returns**: `Promise<{ notifications: 'granted' | 'denied' | 'prompt' }>`
+
+---
+
+### `requestPermissions()`
+
+Prompts the user for notification permission.
+
+**Returns**: `Promise<{ notifications: 'granted' | 'denied' | 'prompt' }>`
+
+---
+
+### `registerFcmToken()`
+
+Triggers registration of the device's FCM/APNs token with the backend server. Reads `fcmToken`, JWT, and backend URL from `safe_storage`. No-ops if already registered or if prerequisites are missing.
 
 ---
 
 ## Troubleshooting
 
-### Android: Service is killed
+### Android: Notifications not appearing after FCM push
+
+1. Confirm `roomDecryptedKeys` and `memberDecryptedKeys` are written to `safe_storage` before the push arrives.
+2. Check Logcat for `EncryptedMessageNotifier`, `NativeCrypto`, and `NotificationHelper` tags.
+3. Ensure `ic_notification` drawable exists in the host app (required for the notification icon).
+
+### Android: Persistent service is killed
+
+Ensure `android:foregroundServiceType="dataSync"` is declared on `PersistentSocketService` (already set in the plugin manifest). On Android 14+ the system enforces this.
+
+### Android: Duplicate notifications
+
+The plugin deduplicates by `messageId`. Ensure each message has a unique, stable `messageId` in the FCM payload.
+
+### iOS: Notifications not grouping
 
-Ensure you have added `android:foregroundServiceType="dataSync"` to the service declaration in `AndroidManifest.xml` as required by Android 14+.
+Confirm the same `roomId` is passed to `showNotification` and that Background Modes are enabled for the app target in Xcode.
 
-### iOS: Notifications aren't grouping
+### iOS: Decryption failing
 
-Ensure `threadIdentifier` is correctly set in the push payload or that you are passing the same `roomId` to `showNotification`.
+Ensure `roomDecryptedKeys` and `memberDecryptedKeys` are present in `UserDefaults` suite `"safe_storage"` before the silent push arrives.
+
+---
 
 ## Development
 
-- **Build**: `npm run build`
-- **Lint**: `npm run lint`
-- **Format**: `npm run fmt`
-- **Verify**: `npm run verify`
+```bash
+npm run build    # compile TypeScript
+npm run lint     # run ESLint
+npm run fmt      # run Prettier
+npm run verify   # build + lint + native checks
+```
+
+---
 
 ## Contributing
 
 Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+---
+
 ## License
 
 MIT

package/android/build.gradle

@@ -43,6 +43,7 @@ android {
 repositories {
     google()
     mavenCentral()
+    maven { url 'https://jitpack.io' }
 }
 
 dependencies {
@@ -50,12 +51,21 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation "androidx.core:core:$androidxCoreVersion"
-    
+
     // Socket.IO client for Android
     implementation ('io.socket:socket.io-client:2.1.0') {
         exclude group: 'org.json', module: 'json'
     }
-    
+
+    // Libsodium JNI for E2EE decryption
+    implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:2.0.2'
+
+    // Google Play Services for GMS availability check
+    implementation 'com.google.android.gms:play-services-base:18.2.0'
+
+    // AndroidSVG for rendering avatar SVGs in notifications
+    implementation 'com.caverock:androidsvg:1.4'
+
     testImplementation 'junit:junit:4.13.2'
     androidTestImplementation 'androidx.test.ext:junit:1.1.5'
     androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'

package/android/src/main/AndroidManifest.xml

@@ -6,6 +6,23 @@
             android:exported="false"
             android:foregroundServiceType="dataSync" />
 
+        <service
+            android:name="com.codecraft_studio.messenger.notifications.FcmFetchForegroundService"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+
+        <service
+            android:name="com.codecraft_studio.messenger.notifications.FcmFetchBackgroundService"
+            android:enabled="true"
+            android:exported="false" />
+
+        <service
+            android:name="com.codecraft_studio.messenger.notifications.FcmJobService"
+            android:enabled="true"
+            android:exported="false"
+            android:permission="android.permission.BIND_JOB_SERVICE" />
+
         <receiver
             android:name="com.codecraft_studio.messenger.notifications.NotificationDismissReceiver"
             android:enabled="true"
@@ -13,7 +30,9 @@
     </application>
 
     <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
 </manifest>