@sigx/lynx-notifications 0.4.1 → 0.4.2

package/ios/PushAppDelegateHook.swift

@@ -0,0 +1,155 @@
+import Foundation
+import UIKit
+import UserNotifications
+
+/// AppDelegate hook for remote push.
+///
+/// Discovered by the auto-linker via `signalx-module.json`'s
+/// `ios.appDelegateHook` field; the generated `GeneratedAppDelegateHooks` calls
+/// these static methods at the matching `UIApplicationDelegate` callbacks.
+///
+/// Responsibilities:
+///   - `didFinishLaunching` — install the singleton `UNUserNotificationCenter`
+///     delegate so foreground banners and tap callbacks reach JS. Also captures
+///     a cold-start notification payload (`launchOptions[.remoteNotification]`)
+///     for `Notifications.getInitialNotification()`.
+///   - `didRegisterForRemoteNotificationsWithDeviceToken` — converts the APNs
+///     `Data` token to its canonical hex form and publishes via `PushEventBus`.
+///   - `didFailToRegisterForRemoteNotificationsWithError` — surfaces the error
+///     to JS so apps can show a "push unavailable" state instead of hanging.
+@objc public class PushAppDelegateHook: NSObject {
+
+    @objc public static func didFinishLaunching(
+        _ application: UIApplication,
+        launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) {
+        // Take ownership of the notification-center delegate. Apps that need
+        // to interpose their own delegate should set it AFTER our hook runs
+        // and forward to PushNotificationDelegate.shared from their
+        // implementation. (Standard pattern for Firebase / OneSignal / etc.)
+        UNUserNotificationCenter.current().delegate = PushNotificationDelegate.shared
+
+        // Open the cold-start capture window. The first `didReceive` tap
+        // after launch (which is how local notifications launched from a
+        // terminated state arrive — they never appear in launchOptions) will
+        // be stashed as the initial payload instead of fired on the response
+        // channel. JS drains it via `getInitialNotification()`.
+        PushEventBus.shared.beginColdStartWindow()
+
+        // Cold-start REMOTE push: iOS also pre-populates
+        // `launchOptions[.remoteNotification]` for these. Capture the payload
+        // here too — same destination, just a different source.
+        if let userInfo = launchOptions?[.remoteNotification] as? [AnyHashable: Any] {
+            let (notificationId, data) = extractData(from: userInfo)
+            PushEventBus.shared.captureInitialResponse(
+                notificationId: notificationId,
+                data: data,
+                actionIdentifier: UNNotificationDefaultActionIdentifier
+            )
+        }
+    }
+
+    @objc public static func didRegisterForRemoteNotificationsWithDeviceToken(
+        _ application: UIApplication,
+        deviceToken: Data
+    ) {
+        let hex = deviceToken.map { String(format: "%02x", $0) }.joined()
+        PushEventBus.shared.publishToken(hex, platform: "apns")
+    }
+
+    @objc public static func didFailToRegisterForRemoteNotificationsWithError(
+        _ application: UIApplication,
+        error: Error
+    ) {
+        PushEventBus.shared.publishTokenError(error.localizedDescription)
+    }
+
+    /// Pull a notification id and string-coerced data dict out of an APNs
+    /// userInfo payload. Notification id falls back to a generated UUID when
+    /// the payload doesn't carry one (APNs doesn't require it; some servers
+    /// set it as `apns-collapse-id` or in a custom field).
+    static func extractData(from userInfo: [AnyHashable: Any]) -> (String, [String: String]) {
+        var data: [String: String] = [:]
+        var notificationId = UUID().uuidString
+        for (k, v) in userInfo {
+            guard let key = k as? String else { continue }
+            // `aps` carries title/body/sound — strip it from the JS-visible
+            // data dict; the relevant fields are surfaced as title/body
+            // already by the foreground / response handlers.
+            if key == "aps" { continue }
+            if key == "notification_id" || key == "notificationId" {
+                if let s = v as? String { notificationId = s }
+                continue
+            }
+            data[key] = "\(v)"
+        }
+        return (notificationId, data)
+    }
+}
+
+/// Singleton `UNUserNotificationCenterDelegate`. Forwards foreground deliveries
+/// (`willPresent`) and tap responses (`didReceive`) to `PushEventBus`. Owned by
+/// `PushAppDelegateHook.didFinishLaunching`; the app keeps it as
+/// `UNUserNotificationCenter.current().delegate`.
+final class PushNotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
+
+    static let shared = PushNotificationDelegate()
+
+    /// Foreground delivery. Pass `[.banner, .list, .sound, .badge]` so the OS
+    /// shows the banner even when the app is open — without this, iOS suppresses
+    /// foreground notifications entirely (the historical complaint in the
+    /// previous local-only README).
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+    ) {
+        let content = notification.request.content
+        let (_, data) = PushAppDelegateHook.extractData(from: content.userInfo)
+        PushEventBus.shared.publishMessage(
+            title: content.title.isEmpty ? nil : content.title,
+            body: content.body.isEmpty ? nil : content.body,
+            data: data,
+            foreground: true
+        )
+        if #available(iOS 14.0, *) {
+            completionHandler([.banner, .list, .sound, .badge])
+        } else {
+            completionHandler([.alert, .sound, .badge])
+        }
+    }
+
+    /// User tapped a notification (remote OR local). This is the path the
+    /// previous README flagged as "Tap callbacks aren't surfaced in JS yet" —
+    /// now they are.
+    ///
+    /// If we're still in the cold-start window opened by
+    /// `didFinishLaunching`, the first tap is stashed as the initial payload
+    /// (drained later by `getInitialNotification()`) instead of fired on the
+    /// response channel — this covers local notifications launched from a
+    /// terminated state, where `launchOptions[.remoteNotification]` is empty.
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void
+    ) {
+        let content = response.notification.request.content
+        let (idFromPayload, data) = PushAppDelegateHook.extractData(from: content.userInfo)
+        let notificationId = response.notification.request.identifier.isEmpty
+            ? idFromPayload
+            : response.notification.request.identifier
+        let captured = PushEventBus.shared.captureInitialResponseIfColdStart(
+            notificationId: notificationId,
+            data: data,
+            actionIdentifier: response.actionIdentifier
+        )
+        if !captured {
+            PushEventBus.shared.publishResponse(
+                notificationId: notificationId,
+                data: data,
+                actionIdentifier: response.actionIdentifier
+            )
+        }
+        completionHandler()
+    }
+}

package/ios/PushEventBus.swift

@@ -0,0 +1,164 @@
+import Foundation
+
+/// Process-wide pub/sub bus that converts APNs + UNUserNotificationCenter
+/// callbacks into JS-side event payloads. The AppDelegate hook and the
+/// notification-center delegate write here; per-LynxView `PushPublisher`
+/// instances read.
+///
+/// Mirrors the `WebSocketEventBus` pattern. Native lifecycle is decoupled from
+/// any specific LynxView so events that arrive before a LynxView is built
+/// (cold-start payloads, token registrations) can be replayed to subscribers
+/// when they attach.
+final class PushEventBus {
+
+    static let shared = PushEventBus()
+
+    /// JSON-encodable payload. Wire shape matches the JS-side types in
+    /// `src/push.ts` (channel name carried as `__channel`).
+    typealias Payload = [String: Any]
+    typealias Listener = (String, Payload) -> Void
+
+    private let queue = DispatchQueue(label: "com.sigx.notifications.bus")
+    private var listeners: [(token: UUID, fn: Listener)] = []
+
+    /// Cached cold-start tap. Cleared after the JS shim retrieves it via
+    /// `Notifications.getInitialNotification()`. Stored regardless of whether
+    /// a LynxView has attached yet — the JS shim polls on first call.
+    private(set) var initialResponse: Payload?
+
+    /// Cached most-recent device token so a JS subscriber that attaches after
+    /// registration completes still receives it on subscribe. APNs returns
+    /// the same token across registrations, so caching is safe.
+    private(set) var lastToken: Payload?
+
+    /// `true` between `application(_:didFinishLaunchingWithOptions:)` and the
+    /// first time JS asks for the initial notification. While set, the FIRST
+    /// `didReceive` tap is also captured as the cold-start payload — covers
+    /// the local-notification cold-start path where there's no
+    /// `launchOptions[.remoteNotification]` to read.
+    private(set) var inColdStartWindow = false
+
+    @discardableResult
+    func addListener(_ fn: @escaping Listener) -> UUID {
+        let token = UUID()
+        // Snapshot the cached token in the same critical section as the
+        // listener append so we either replay-then-deliver or skip-then-deliver
+        // — no torn-state where a concurrent publishToken slips between the
+        // two and the listener sees the token twice. The replay itself runs
+        // OUTSIDE the queue so a listener that re-enters the bus (e.g.
+        // immediately subscribes a second listener, or calls publishToken
+        // recursively) doesn't deadlock on the serial queue.
+        let cached: Payload? = queue.sync {
+            listeners.append((token, fn))
+            return lastToken
+        }
+        if let cached = cached {
+            fn(PushEventChannel.token, cached)
+        }
+        return token
+    }
+
+    func removeListener(_ token: UUID) {
+        queue.sync { listeners.removeAll { $0.token == token } }
+    }
+
+    // MARK: - Publish
+
+    func publishToken(_ token: String, platform: String = "apns") {
+        let payload: Payload = ["token": token, "platform": platform]
+        queue.sync { lastToken = payload }
+        emit(channel: PushEventChannel.token, payload: payload)
+    }
+
+    func publishTokenError(_ message: String) {
+        emit(channel: PushEventChannel.tokenError, payload: ["error": message])
+    }
+
+    func publishMessage(title: String?, body: String?, data: [String: String], foreground: Bool) {
+        var payload: Payload = [
+            "data": data,
+            "foreground": foreground,
+        ]
+        if let title = title { payload["title"] = title }
+        if let body = body { payload["body"] = body }
+        emit(channel: PushEventChannel.message, payload: payload)
+    }
+
+    func publishResponse(notificationId: String, data: [String: String], actionIdentifier: String) {
+        let payload: Payload = [
+            "notificationId": notificationId,
+            "data": data,
+            "actionIdentifier": actionIdentifier,
+        ]
+        emit(channel: PushEventChannel.response, payload: payload)
+    }
+
+    /// Open the cold-start capture window. Called from
+    /// `application(_:didFinishLaunchingWithOptions:)`. The window stays
+    /// open until either the first `consumeInitialResponse()` call or a
+    /// successful capture — whichever comes first.
+    func beginColdStartWindow() {
+        queue.sync { inColdStartWindow = true }
+    }
+
+    /// Stash a cold-start tap. `application(_:didFinishLaunchingWithOptions:)`
+    /// runs before any LynxView exists; the payload is held until JS asks for
+    /// it via `getInitialNotification()`.
+    func captureInitialResponse(notificationId: String, data: [String: String], actionIdentifier: String) {
+        queue.sync {
+            initialResponse = [
+                "notificationId": notificationId,
+                "data": data,
+                "actionIdentifier": actionIdentifier,
+            ]
+            inColdStartWindow = false
+        }
+    }
+
+    /// Capture a tap as the cold-start payload IF we're still in the
+    /// cold-start window AND nothing's been captured yet. Returns `true` if
+    /// the call stashed the payload — the caller should NOT also publish the
+    /// same tap on the response channel (the JS shim drains it via
+    /// `getInitialNotification`).
+    func captureInitialResponseIfColdStart(
+        notificationId: String,
+        data: [String: String],
+        actionIdentifier: String,
+    ) -> Bool {
+        return queue.sync {
+            guard inColdStartWindow, initialResponse == nil else { return false }
+            initialResponse = [
+                "notificationId": notificationId,
+                "data": data,
+                "actionIdentifier": actionIdentifier,
+            ]
+            inColdStartWindow = false
+            return true
+        }
+    }
+
+    /// Drain and return the cold-start payload (one-shot — subsequent calls
+    /// return nil). Also closes the cold-start window so any subsequent tap
+    /// goes through the regular response channel.
+    func consumeInitialResponse() -> Payload? {
+        return queue.sync {
+            let p = initialResponse
+            initialResponse = nil
+            inColdStartWindow = false
+            return p
+        }
+    }
+
+    private func emit(channel: String, payload: Payload) {
+        let snapshot = queue.sync { listeners }
+        for (_, fn) in snapshot { fn(channel, payload) }
+    }
+}
+
+/// Stable event-channel names. These also appear in the JS shim — keep in sync.
+enum PushEventChannel {
+    static let token = "__sigxPushToken"
+    static let tokenError = "__sigxPushTokenError"
+    static let message = "__sigxPushMessage"
+    static let response = "__sigxNotificationResponse"
+}

package/ios/PushPublisher.swift

@@ -0,0 +1,30 @@
+import Foundation
+import Lynx
+
+/// Per-`LynxView` publisher that pumps `PushEventBus` payloads into JS via
+/// `LynxView.sendGlobalEvent(name, withParams:)`.
+///
+/// One instance per LynxView; instantiated by the generated
+/// `GeneratedLifecyclePublishers.attachAll(to:)` and retained for the
+/// LynxView's lifetime. The bus is global so a remote push or tap that fires
+/// before the LynxView's JS heap is ready will be replayed (for `__sigxPushToken`)
+/// or delivered on the next message via cold-start retrieval.
+final class PushPublisher {
+
+    private weak var lynxView: LynxView?
+    private var token: UUID?
+
+    init(lynxView: LynxView) {
+        self.lynxView = lynxView
+        self.token = PushEventBus.shared.addListener { [weak self] channel, payload in
+            guard let view = self?.lynxView else { return }
+            view.sendGlobalEvent(channel, withParams: [payload])
+        }
+    }
+
+    deinit {
+        if let token = token {
+            PushEventBus.shared.removeListener(token)
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-notifications",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Local push notifications for sigx-lynx",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,11 +19,12 @@
     "signalx-module.json"
   ],
   "dependencies": {
-    "@sigx/lynx-core": "^0.4.1"
+    "@sigx/lynx-core": "^0.4.2"
   },
   "devDependencies": {
-    "@typescript/native-preview": "7.0.0-dev.20260511.1",
-    "typescript": "^6.0.3"
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "author": "Andreas Ekdahl",
   "license": "MIT",
@@ -51,6 +52,7 @@
   "scripts": {
     "build": "node ../../scripts/clean.mjs dist && tsgo",
     "dev": "tsgo --watch",
+    "test": "vitest run",
     "clean": "node ../../scripts/clean.mjs dist .turbo"
   }
 }

package/signalx-module.json

@@ -1,16 +1,54 @@
 {
     "name": "Notifications",
     "package": "@sigx/lynx-notifications",
-    "description": "Local push notifications",
+    "description": "Local + remote push notifications (APNs / FCM)",
     "platforms": ["android", "ios"],
     "ios": {
         "moduleClass": "NotificationsModule",
+        "publisherClass": "PushPublisher",
+        "appDelegateHook": {
+            "class": "PushAppDelegateHook",
+            "methods": [
+                "didFinishLaunching",
+                "didRegisterForRemoteNotificationsWithDeviceToken",
+                "didFailToRegisterForRemoteNotificationsWithError"
+            ]
+        },
         "sourceDir": "ios",
-        "methods": ["schedule","cancel","cancelAll","requestPermission","getPermissionStatus"]
+        "methods": [
+            "schedule",
+            "cancel",
+            "cancelAll",
+            "requestPermission",
+            "getPermissionStatus",
+            "registerForPushNotifications",
+            "unregisterForPushNotifications",
+            "setBadgeCount",
+            "getBadgeCount",
+            "getInitialNotification"
+        ],
+        "backgroundModes": ["remote-notification"]
     },
     "android": {
         "moduleClass": "com.sigx.notifications.NotificationsModule",
+        "publisherClass": "com.sigx.notifications.PushPublisher",
+        "activityHook": {
+            "class": "com.sigx.notifications.PushActivityHook",
+            "methods": ["onCreate", "onNewIntent"]
+        },
         "sourceDir": "android",
-        "permissions": ["android.permission.POST_NOTIFICATIONS"]
+        "permissions": ["android.permission.POST_NOTIFICATIONS"],
+        "dependencies": [
+            "com.google.firebase:firebase-messaging:24.0.0",
+            "com.google.firebase:firebase-common-ktx:21.0.0",
+            "com.google.android.gms:play-services-base:18.5.0"
+        ],
+        "services": [
+            {
+                "name": "com.sigx.notifications.SigxFirebaseMessagingService",
+                "exported": false,
+                "actions": ["com.google.firebase.MESSAGING_EVENT"]
+            }
+        ]
     }
 }