capacitor-messenger-notifications 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeCraft Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MessengerNotifications.podspec

@@ -0,0 +1,18 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'MessengerNotifications'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_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.swift_version = '5.1'
+end

package/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "MessengerNotifications",
+    platforms: [.iOS(.v13)],
+    products: [
+        .library(
+            name: "MessengerNotifications",
+            targets: ["MessengerNotificationsPlugin"])
+    ],
+    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")
+    ],
+    targets: [
+        .target(
+            name: "MessengerNotificationsPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "SocketIO", package: "socket.io-client-swift")
+            ],
+            path: "ios/Sources/MessengerNotificationsPlugin")
+    ]
+)

package/README.md

@@ -0,0 +1,152 @@
+# capacitor-messenger-notifications
+
+[![license](https://img.shields.io/npm/l/capacitor-messenger-notifications.svg)](https://github.com/imuhammadnadeem/capacitor-messenger-notifications/blob/main/LICENSE)
+
+Capacitor plugin for managing messenger-style notifications with WebSocket support on Android and iOS. Built for end-to-end encrypted chat applications.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Usage](#usage)
+  - [JavaScript Examples](#javascript-examples)
+  - [Native Integration (Android/iOS)](#native-integration-androidios)
+- [Configuration](#configuration)
+- [Platform Implementation](#platform-implementation)
+- [Setup by Platform](#setup-by-platform)
+- [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.
+
+## Requirements
+
+- **Capacitor**: ^6.0.0 || ^7.0.0 || ^8.0.0
+- **Node.js**: 18.x or higher
+- **iOS**: 13.0 or higher
+- **Android**: API level 22 (Android 5.1) or higher
+
+## Install
+
+```bash
+npm install capacitor-messenger-notifications
+npx cap sync
+```
+
+## Usage
+
+### JavaScript Examples
+
+#### Start Persistent Socket (Android)
+
+```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'
+});
+```
+
+#### Show a Manual Notification
+
+```typescript
+await MessengerNotifications.showNotification({
+  title: 'John Doe',
+  body: 'Hey, how are you?',
+  roomId: 101,
+  roomName: 'General Chat',
+  messageId: 'uuid-12345',
+  timestamp: Date.now()
+});
+```
+
+### Native Integration (Android/iOS)
+
+This plugin is often triggered from native background tasks (FCM / Silent Push).
+
+- **Android**: Use `EncryptedMessageNotifier.notifyFromSocketPayload(context, data)` from your background services.
+- **iOS**: Use `TemporarySocketSessionManager.shared.fetchAndNotify(...)` inside `didReceiveRemoteNotification`.
+
+## Configuration
+
+Most configurations are handled dynamically via the API, but you can define defaults in **`capacitor.config.json`**:
+
+```json
+{
+  "plugins": {
+    "MessengerNotifications": {
+      "defaultSocketUrl": "wss://your-default-server.com",
+      "notificationChannelId": "chat_messages",
+      "notificationChannelName": "Messenger Notifications"
+    }
+  }
+}
+```
+
+## Platform Implementation
+
+| Platform | Implementation |
+| --- | --- |
+| Android | Foreground Service + NotificationManager with `MessagingStyle`. |
+| iOS | `UNNotificationContent` with `threadIdentifier` + SocketIO Task. |
+
+## Setup by Platform
+
+> For full host‑app steps (Android & iOS), see `HOST_APP_SETUP.md`.
+
+### Android
+
+- **AndroidManifest.xml**: Add `FOREGROUND_SERVICE` and `POST_NOTIFICATIONS` permissions.
+- **ProGuard**: Add `-keep` rules for the plugin and Socket.IO.
+
+### iOS
+
+- **Capabilities**: Enable **Push Notifications** and **Background Modes** (Background fetch, Remote notifications).
+
+## API
+
+| Method | 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. |
+
+---
+
+## Troubleshooting
+
+### Android: Service is killed
+
+Ensure you have added `android:foregroundServiceType="dataSync"` to the service declaration in `AndroidManifest.xml` as required by Android 14+.
+
+### iOS: Notifications aren't grouping
+
+Ensure `threadIdentifier` is correctly set in the push payload or that you are passing the same `roomId` to `showNotification`.
+
+## Development
+
+- **Build**: `npm run build`
+- **Lint**: `npm run lint`
+- **Format**: `npm run fmt`
+- **Verify**: `npm run verify`
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,62 @@
+ext {
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.12.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.1'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "com.codecraft_studio.messenger.notifications"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    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'
+    }
+    
+    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

@@ -0,0 +1,19 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <service
+            android:name="com.codecraft_studio.messenger.notifications.PersistentSocketService"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+
+        <receiver
+            android:name="com.codecraft_studio.messenger.notifications.NotificationDismissReceiver"
+            android:enabled="true"
+            android:exported="false" />
+    </application>
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <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" />
+</manifest>

package/android/src/main/java/com/codecraft_studio/messenger/notifications/EncryptedMessageNotifier.java

@@ -0,0 +1,68 @@
+package com.codecraft_studio.messenger.notifications;
+
+import android.content.Context;
+import android.util.Log;
+import java.util.Map;
+import org.json.JSONObject;
+
+/**
+ * Handles incoming push/socket payloads, decrypts them, and triggers notifications.
+ */
+public class EncryptedMessageNotifier {
+
+    private static final String TAG = "MessageNotifier";
+
+    public static boolean notifyFromPushData(Context context, Map<String, String> data) {
+        if (data == null || data.isEmpty()) return false;
+        try {
+            int roomId = Integer.parseInt(data.get("roomId") != null ? data.get("roomId") : data.get("room_id"));
+            String senderName = data.get("senderName") != null ? data.get("senderName") : data.get("title");
+            String body = data.get("body") != null ? data.get("body") : data.get("message");
+            String messageId = data.get("messageId") != null ? data.get("messageId") : data.get("id");
+            long timestamp = System.currentTimeMillis();
+
+            NotificationHelper.showRoomNotification(context, senderName, body, roomId, messageId, timestamp);
+            return true;
+        } catch (Exception e) {
+            Log.e(TAG, "Error processing push data", e);
+        }
+        return false;
+    }
+
+    public static boolean notifyFromSocketPayload(Context context, Object payload) {
+        if (!(payload instanceof JSONObject)) return false;
+        JSONObject obj = (JSONObject) payload;
+        try {
+            int roomId = obj.optInt("room_id", obj.optInt("roomId"));
+            if (roomId <= 0) return false;
+
+            String encryptedMsg = obj.optString("encrypted_message", obj.optString("encryptedMessage"));
+            String encryptedUser = obj.optString("encrypted_username", obj.optString("encryptedUsername"));
+            String encryptedRoom = obj.optString("encrypted_room_name", obj.optString("encryptedRoomName"));
+
+            String senderName = encryptedUser.isEmpty()
+                ? "New Message"
+                : NativeCrypto.decryptUserData(obj.optInt("sender_id"), encryptedUser).text;
+            String messageBody = encryptedMsg.isEmpty() ? "New encrypted message" : NativeCrypto.decryptRoomData(roomId, encryptedMsg).text;
+            String roomName = encryptedRoom.isEmpty() ? null : NativeCrypto.decryptRoomData(roomId, encryptedRoom).text;
+
+            String messageId = obj.optString("id", obj.optString("messageId"));
+            long timestamp = obj.optLong("timestamp", System.currentTimeMillis());
+
+            NotificationHelper.showRoomNotification(context, senderName, messageBody, roomId, roomName, messageId, timestamp, false);
+            return true;
+        } catch (Exception e) {
+            Log.e(TAG, "Error processing socket payload", e);
+        }
+        return false;
+    }
+
+    public static boolean notifyFromSyncMessagesResponse(Context context, Object arg) {
+        // For sync response, we just treat each message as a socket payload.
+        return notifyFromSocketPayload(context, arg);
+    }
+
+    public static void notifyFromUnreadApiRecord(Context context, JSONObject item) {
+        notifyFromSocketPayload(context, item);
+    }
+}

package/android/src/main/java/com/codecraft_studio/messenger/notifications/FcmFetchManager.java

@@ -0,0 +1,37 @@
+package com.codecraft_studio.messenger.notifications;
+
+import android.util.Log;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Tracks when a notification was last shown per room ID.
+ * Used to avoid duplicate notifications.
+ */
+public final class FcmFetchManager {
+
+    private static final String TAG = "FcmFetchManager";
+    private static final Map<Integer, Long> lastRoomNotificationMs = new ConcurrentHashMap<>();
+    private static final long NOTIFICATION_GRACE_MS = 10_000L;
+    private static volatile long lastAnyNotificationMs = 0L;
+
+    private FcmFetchManager() {}
+
+    public static void markNotificationShown(int roomId) {
+        long now = System.currentTimeMillis();
+        lastRoomNotificationMs.put(roomId, now);
+        lastAnyNotificationMs = now;
+    }
+
+    public static boolean wasNotificationShownRecently(int roomId) {
+        Long last = lastRoomNotificationMs.get(roomId);
+        if (last == null) return false;
+        return (System.currentTimeMillis() - last) < NOTIFICATION_GRACE_MS;
+    }
+
+    public static boolean wasAnyNotificationShownRecently(long windowMs) {
+        long last = lastAnyNotificationMs;
+        if (last <= 0L) return false;
+        return (System.currentTimeMillis() - last) < Math.max(0L, windowMs);
+    }
+}

package/android/src/main/java/com/codecraft_studio/messenger/notifications/MessengerNotificationsPlugin.java

@@ -0,0 +1,92 @@
+package com.codecraft_studio.messenger.notifications;
+
+import android.os.Bundle;
+import android.util.Log;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+@CapacitorPlugin(name = "MessengerNotifications")
+public class MessengerNotificationsPlugin extends Plugin {
+
+    private static final String TAG = "MessengerNotifications";
+
+    @Override
+    public void load() {
+        Log.i(TAG, "Plugin loaded");
+    }
+
+    @PluginMethod
+    public void showNotification(PluginCall call) {
+        String title = call.getString("title", "New Message");
+        String body = call.getString("body", "You have a new message");
+        int roomId = call.getInt("roomId", 0);
+        String messageId = call.getString("messageId");
+        long timestamp = call.getLong("timestamp", 0L);
+        String roomName = call.getString("roomName");
+
+        Log.i(TAG, "showNotification() title=" + title + " roomId=" + roomId + " messageId=" + messageId);
+
+        NotificationHelper.showRoomNotification(getContext(), title, body, roomId, roomName, messageId, timestamp, false);
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void clearRoomNotification(PluginCall call) {
+        int roomId = call.getInt("roomId", 0);
+        if (roomId <= 0) {
+            call.resolve();
+            return;
+        }
+
+        Log.i(TAG, "clearRoomNotification() roomId=" + roomId);
+        NotificationHelper.clearRoomHistory(getContext(), roomId, true);
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void getPendingRoomId(PluginCall call) {
+        JSObject result = new JSObject();
+        // Since we don't have MainActivity.pendingRoomId in a plugin,
+        // we might want to store it in SharedPreferences or through a static field in the plugin.
+        // For now, let's assume we store it in a static field here.
+        Integer roomId = NotificationHelper.getPendingRoomId();
+        if (roomId != null) {
+            result.put("roomId", roomId);
+            NotificationHelper.consumePendingRoomId();
+        } else {
+            result.put("roomId", JSObject.NULL);
+        }
+        call.resolve(result);
+    }
+
+    @PluginMethod
+    public void startPersistentSocket(PluginCall call) {
+        String url = call.getString("url");
+        String token = call.getString("token");
+
+        if (url == null || token == null) {
+            call.reject("Missing url or token");
+            return;
+        }
+
+        // Store these for the service to use (e.g. in SharedPreferences)
+        getContext()
+            .getSharedPreferences("messenger_plugin_prefs", android.content.Context.MODE_PRIVATE)
+            .edit()
+            .putString("socket_url", url)
+            .putString("auth_token", token)
+            .apply();
+
+        PersistentSocketService.start(getContext());
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void stopPersistentSocket(PluginCall call) {
+        PersistentSocketService.stop(getContext());
+        call.resolve();
+    }
+}

package/android/src/main/java/com/codecraft_studio/messenger/notifications/NativeCrypto.java

@@ -0,0 +1,43 @@
+package com.codecraft_studio.messenger.notifications;
+
+import android.util.Base64;
+import android.util.Log;
+import androidx.annotation.NonNull;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Native crypto logic picked from ChatE2EE.
+ * In a real plugin, this would interface with a security library or the app's keys.
+ */
+public class NativeCrypto {
+
+    private static final String TAG = "NativeCrypto";
+
+    public static class DecryptResult {
+
+        public final String text;
+
+        public DecryptResult(String text) {
+            this.text = text;
+        }
+    }
+
+    /**
+     * Placeholder decryption logic.
+     * In the real app, this uses Lipsum or similar.
+     * For the plugin, we assume the host app might provide keys or we just return the ciphertext
+     * if we can't decrypt it yet.
+     */
+    public static DecryptResult decryptRoomData(int roomId, @NonNull String encryptedJSON) {
+        // This is a placeholder.
+        // In the original app, it calls a native method or a complex JS bridge.
+        // For the plugin, we'll try to decrypt if we have the keys, otherwise return as-is.
+        Log.d(TAG, "decryptRoomData() roomId=" + roomId);
+        return new DecryptResult(encryptedJSON); // Placeholder
+    }
+
+    public static DecryptResult decryptUserData(int userId, @NonNull String encryptedJSON) {
+        Log.d(TAG, "decryptUserData() userId=" + userId);
+        return new DecryptResult(encryptedJSON); // Placeholder
+    }
+}

package/android/src/main/java/com/codecraft_studio/messenger/notifications/NotificationDismissReceiver.java

@@ -0,0 +1,20 @@
+package com.codecraft_studio.messenger.notifications;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.util.Log;
+
+public class NotificationDismissReceiver extends BroadcastReceiver {
+
+    private static final String TAG = "NotificationDismiss";
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        int roomId = intent.getIntExtra(NotificationHelper.EXTRA_ROOM_ID, 0);
+        Log.d(TAG, "Notification dismissed for roomId: " + roomId);
+        if (roomId > 0) {
+            NotificationHelper.onNotificationDismissed(context, roomId);
+        }
+    }
+}