@sigx/lynx-notifications 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andreas Ekdahl
+
+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/README.md

@@ -0,0 +1,77 @@
+# @sigx/lynx-notifications
+
+Local push notifications for sigx-lynx. `UNUserNotificationCenter` on iOS, `NotificationManager` + `AlarmManager` on Android. **Local-only** — push notifications via APNs/FCM are not in this module.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-notifications
+```
+
+```ts
+// sigx.lynx.config.ts
+export default defineLynxConfig({
+    modules: ['@sigx/lynx-notifications'],
+});
+```
+
+`sigx prebuild` auto-links the native module and adds `android.permission.POST_NOTIFICATIONS` (Android 13+). iOS notification permission is requested at runtime via `requestPermission()`.
+
+> **Android pairs with `@sigx/lynx-permissions`** — needed for the runtime permission prompt on Android 13+.
+
+## Usage
+
+```ts
+import { Notifications } from '@sigx/lynx-notifications';
+
+const { status } = await Notifications.requestPermission();
+if (status === 'granted') {
+    const id = await Notifications.schedule(
+        { title: 'Reminder', body: 'Check your tasks', data: { taskId: '42' } },
+        { delay: 60 },     // seconds
+    );
+    // Cancel later by id:
+    // await Notifications.cancel(id);
+}
+
+// Daily reminder
+await Notifications.schedule(
+    { title: 'Daily check-in', body: 'How are you feeling today?' },
+    { delay: 60 * 60 * 24, repeat: 'day' },
+);
+
+await Notifications.cancelAll();
+```
+
+## API
+
+| Method                                                                  | Notes                                                                                              |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `schedule(content: NotificationContent, options?: ScheduleOptions): Promise<string>` | Returns the notification id (use it for `cancel()`).                                  |
+| `cancel(notificationId: string): Promise<void>`                         | Cancels a scheduled notification. No-op if not scheduled.                                          |
+| `cancelAll(): Promise<void>`                                            | Cancels all pending notifications scheduled by this app.                                           |
+| `requestPermission(): Promise<PermissionResponse>`                      | Shows the OS permission dialog if needed.                                                          |
+| `getPermissionStatus(): Promise<PermissionResponse>`                    | Read-only check — no prompt.                                                                       |
+| `isAvailable(): boolean`                                                | Whether the native module is registered in the current build.                                      |
+
+```ts
+interface NotificationContent {
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+}
+
+interface ScheduleOptions {
+    delay?: number;                                   // seconds from now; default = immediate
+    repeat?: 'minute' | 'hour' | 'day' | 'week';      // periodic re-fire
+}
+```
+
+## Gotchas
+
+- **Foreground delivery on iOS.** When the app is in the foreground, iOS suppresses the banner by default. Hook into `UNUserNotificationCenterDelegate` natively if you need in-app banners.
+- **Tap callbacks aren't surfaced in JS yet.** The notification fires, but if the user taps it the routing/payload-handling has to happen on the native side (or via deep links). A future revision could expose an `onResponse` event.
+
+## Reference app
+
+`examples/lynx-one/my-sigx-app/src/cards/NotificationsCard.tsx` covers permission + schedule-with-delay + cancel.

package/android/com/sigx/notifications/NotificationsModule.kt

@@ -0,0 +1,104 @@
+package com.sigx.notifications
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyMap
+import com.sigx.permissions.PermissionHelper
+import com.lynx.react.bridge.ReadableMap
+import java.util.UUID
+
+/**
+ * Local notifications module.
+ * JS usage: NativeModules.Notifications.schedule({ title, body }, { delay }, callback)
+ */
+class NotificationsModule(context: Context) : LynxModule(context) {
+
+    companion object {
+        private const val TAG = "NotificationsModule"
+        private const val CHANNEL_ID = "sigx_lynxgo_default"
+        private const val CHANNEL_NAME = "sigx-lynx-go"
+    }
+
+    init {
+        createNotificationChannel()
+    }
+
+    @LynxMethod
+    fun schedule(content: ReadableMap?, options: ReadableMap?, callback: Callback?) {
+        try {
+            val title = content?.getString("title") ?: "Notification"
+            val body = content?.getString("body") ?: ""
+            val notificationId = UUID.randomUUID().toString()
+
+            val manager = mContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+
+            val notification = NotificationCompat.Builder(mContext, CHANNEL_ID)
+                .setContentTitle(title)
+                .setContentText(body)
+                .setSmallIcon(android.R.drawable.ic_dialog_info)
+                .setAutoCancel(true)
+                .build()
+
+            manager.notify(notificationId.hashCode(), notification)
+            callback?.invoke(notificationId)
+            Log.d(TAG, "Notification scheduled: $notificationId")
+        } catch (e: Exception) {
+            val error = JavaOnlyMap()
+            error.putString("error", e.message ?: "Unknown error")
+            callback?.invoke(error)
+        }
+    }
+
+    @LynxMethod
+    fun cancel(notificationId: String?, callback: Callback?) {
+        try {
+            val manager = mContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            manager.cancel((notificationId ?: "").hashCode())
+            callback?.invoke(true)
+        } catch (e: Exception) {
+            callback?.invoke(false)
+        }
+    }
+
+    @LynxMethod
+    fun cancelAll(callback: Callback?) {
+        try {
+            val manager = mContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            manager.cancelAll()
+            callback?.invoke(true)
+        } catch (e: Exception) {
+            callback?.invoke(false)
+        }
+    }
+
+    @LynxMethod
+    fun requestPermission(callback: Callback?) {
+        PermissionHelper.requestPermission(mContext, "notifications") { result ->
+            callback?.invoke(result)
+        }
+    }
+
+    @LynxMethod
+    fun getPermissionStatus(callback: Callback?) {
+        val result = PermissionHelper.checkPermission(mContext, "notifications")
+        callback?.invoke(result)
+    }
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID, CHANNEL_NAME, NotificationManager.IMPORTANCE_DEFAULT
+            )
+            val manager = mContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            manager.createNotificationChannel(channel)
+        }
+    }
+}
+

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Notifications } from './notifications.js';
+export type { NotificationContent, ScheduleOptions } from './notifications.js';
+export type { PermissionResponse } from '@sigx/lynx-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Notifications } from './notifications.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/notifications.d.ts

@@ -0,0 +1,37 @@
+import type { PermissionResponse } from '@sigx/lynx-core';
+export interface NotificationContent {
+    title: string;
+    body: string;
+    /** Optional data payload */
+    data?: Record<string, string>;
+}
+export interface ScheduleOptions {
+    /** Delay in seconds from now */
+    delay?: number;
+    /** Repeat interval: 'minute', 'hour', 'day', 'week' */
+    repeat?: 'minute' | 'hour' | 'day' | 'week';
+}
+/**
+ * Local notification APIs.
+ *
+ * @example
+ * ```ts
+ * import { Notifications } from '@sigx/lynx-notifications';
+ *
+ * const { status } = await Notifications.requestPermission();
+ * if (status === 'granted') {
+ *     await Notifications.schedule({ title: 'Reminder', body: 'Check your tasks' }, { delay: 60 });
+ * }
+ * ```
+ */
+export declare const Notifications: {
+    readonly schedule: (content: NotificationContent, options?: ScheduleOptions) => Promise<string>;
+    readonly cancel: (notificationId: string) => Promise<void>;
+    readonly cancelAll: () => Promise<void>;
+    /** Request notification permission, showing the OS dialog if needed. */
+    readonly requestPermission: () => Promise<PermissionResponse>;
+    /** Check current notification permission status without prompting. */
+    readonly getPermissionStatus: () => Promise<PermissionResponse>;
+    readonly isAvailable: () => boolean;
+};
+//# sourceMappingURL=notifications.d.ts.map

package/dist/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAI1D,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC5B,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa;iCACJ,mBAAmB,YAAW,eAAe,KAAQ,OAAO,CAAC,MAAM,CAAC;sCAI/D,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;8BAIhC,OAAO,CAAC,IAAI,CAAC;IAI1B,wEAAwE;sCACnD,OAAO,CAAC,kBAAkB,CAAC;IAIhD,sEAAsE;wCAC/C,OAAO,CAAC,kBAAkB,CAAC;gCAInC,OAAO;CAGhB,CAAC"}

package/dist/notifications.js

@@ -0,0 +1,38 @@
+import { callAsync, isModuleAvailable } from '@sigx/lynx-core';
+const MODULE = 'Notifications';
+/**
+ * Local notification APIs.
+ *
+ * @example
+ * ```ts
+ * import { Notifications } from '@sigx/lynx-notifications';
+ *
+ * const { status } = await Notifications.requestPermission();
+ * if (status === 'granted') {
+ *     await Notifications.schedule({ title: 'Reminder', body: 'Check your tasks' }, { delay: 60 });
+ * }
+ * ```
+ */
+export const Notifications = {
+    schedule(content, options = {}) {
+        return callAsync(MODULE, 'schedule', content, options);
+    },
+    cancel(notificationId) {
+        return callAsync(MODULE, 'cancel', notificationId);
+    },
+    cancelAll() {
+        return callAsync(MODULE, 'cancelAll');
+    },
+    /** Request notification permission, showing the OS dialog if needed. */
+    requestPermission() {
+        return callAsync(MODULE, 'requestPermission');
+    },
+    /** Check current notification permission status without prompting. */
+    getPermissionStatus() {
+        return callAsync(MODULE, 'getPermissionStatus');
+    },
+    isAvailable() {
+        return isModuleAvailable(MODULE);
+    },
+};
+//# sourceMappingURL=notifications.js.map

package/dist/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,MAAM,MAAM,GAAG,eAAe,CAAC;AAgB/B;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,QAAQ,CAAC,OAA4B,EAAE,UAA2B,EAAE;QAChE,OAAO,SAAS,CAAS,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,CAAC,cAAsB;QACzB,OAAO,SAAS,CAAO,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC7D,CAAC;IAED,SAAS;QACL,OAAO,SAAS,CAAO,MAAM,EAAE,WAAW,CAAC,CAAC;IAChD,CAAC;IAED,wEAAwE;IACxE,iBAAiB;QACb,OAAO,SAAS,CAAqB,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACtE,CAAC;IAED,sEAAsE;IACtE,mBAAmB;QACf,OAAO,SAAS,CAAqB,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACxE,CAAC;IAED,WAAW;QACP,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;CACK,CAAC"}

package/ios/NotificationsModule.swift

@@ -0,0 +1,94 @@
+import Foundation
+import UserNotifications
+import Lynx
+
+/// Local notifications module.
+/// JS usage: NativeModules.Notifications.schedule({ title, body }, { delay }, callback)
+class NotificationsModule: NSObject, LynxModule {
+
+    @objc static var name: String { "Notifications" }
+
+    @objc static var methodLookup: [String: String] {
+        [
+            "schedule": NSStringFromSelector(#selector(schedule(_:options:callback:))),
+            "cancel": NSStringFromSelector(#selector(cancel(_:callback:))),
+            "cancelAll": NSStringFromSelector(#selector(cancelAll(_:))),
+            "requestPermission": NSStringFromSelector(#selector(requestPermission(_:))),
+            "getPermissionStatus": NSStringFromSelector(#selector(getPermissionStatus(_:))),
+        ]
+    }
+
+    required override init() { super.init() }
+    required init(param: Any) { super.init() }
+
+    @objc func schedule(_ content: [String: Any]?, options: [String: Any]?, callback: LynxCallbackBlock?) {
+        let title = content?["title"] as? String ?? "Notification"
+        let body = content?["body"] as? String ?? ""
+        let delay = options?["delay"] as? TimeInterval ?? 0
+
+        let notificationId = UUID().uuidString
+
+        let notificationContent = UNMutableNotificationContent()
+        notificationContent.title = title
+        notificationContent.body = body
+        notificationContent.sound = .default
+
+        let trigger: UNNotificationTrigger
+        if delay > 0 {
+            trigger = UNTimeIntervalNotificationTrigger(timeInterval: delay, repeats: false)
+        } else {
+            trigger = UNTimeIntervalNotificationTrigger(timeInterval: 0.1, repeats: false)
+        }
+
+        let request = UNNotificationRequest(identifier: notificationId, content: notificationContent, trigger: trigger)
+
+        UNUserNotificationCenter.current().add(request) { error in
+            if let error = error {
+                callback?(["error": error.localizedDescription])
+            } else {
+                callback?(notificationId)
+            }
+        }
+    }
+
+    @objc func cancel(_ notificationId: String?, callback: LynxCallbackBlock?) {
+        guard let notificationId = notificationId else {
+            callback?(false)
+            return
+        }
+        UNUserNotificationCenter.current().removePendingNotificationRequests(withIdentifiers: [notificationId])
+        UNUserNotificationCenter.current().removeDeliveredNotifications(withIdentifiers: [notificationId])
+        callback?(true)
+    }
+
+    @objc func cancelAll(_ callback: LynxCallbackBlock?) {
+        UNUserNotificationCenter.current().removeAllPendingNotificationRequests()
+        UNUserNotificationCenter.current().removeAllDeliveredNotifications()
+        callback?(true)
+    }
+
+    @objc func requestPermission(_ callback: LynxCallbackBlock?) {
+        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
+            if let error = error {
+                callback?(["status": "denied", "error": error.localizedDescription])
+            } else {
+                callback?(["status": granted ? "granted" : "denied"])
+            }
+        }
+    }
+
+    @objc func getPermissionStatus(_ callback: LynxCallbackBlock?) {
+        UNUserNotificationCenter.current().getNotificationSettings { settings in
+            let status: String
+            switch settings.authorizationStatus {
+            case .notDetermined: status = "undetermined"
+            case .denied:        status = "denied"
+            case .authorized:    status = "granted"
+            case .provisional:   status = "granted"
+            case .ephemeral:     status = "granted"
+            @unknown default:    status = "unknown"
+            }
+            callback?(["status": status])
+        }
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@sigx/lynx-notifications",
+  "version": "0.1.0",
+  "description": "Local push notifications for sigx-lynx",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sigx-module.json": "./sigx-module.json"
+  },
+  "files": [
+    "dist",
+    "ios",
+    "android",
+    "sigx-module.json"
+  ],
+  "dependencies": {
+    "@sigx/lynx-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/sigx-module.json

@@ -0,0 +1,16 @@
+{
+    "name": "Notifications",
+    "package": "@sigx/lynx-notifications",
+    "description": "Local push notifications",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "moduleClass": "NotificationsModule",
+        "sourceDir": "ios",
+        "methods": ["schedule","cancel","cancelAll","requestPermission","getPermissionStatus"]
+    },
+    "android": {
+        "moduleClass": "com.sigx.notifications.NotificationsModule",
+        "sourceDir": "android",
+        "permissions": ["android.permission.POST_NOTIFICATIONS"]
+    }
+}