react-native-push-signal 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Anton Seagull
+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/PushSignal.podspec

@@ -0,0 +1,31 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "PushSignal"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://antonseagull.com.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{h,m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+  s.public_header_files = "ios/**/*.h"
+  s.frameworks = "UIKit", "UserNotifications"
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/PushSignal+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,125 @@
+# react-native-push-signal
+
+English | [Русский](README.ru.md)
+
+Get push permission, device credentials for your server, and listen for incoming notifications or taps. The library does not send pushes — your backend talks to APNs and FCM.
+
+## Installation
+
+```sh
+npm install react-native-push-signal react-native-nitro-modules
+```
+
+`react-native-nitro-modules` is required because this library uses [Nitro Modules](https://nitro.margelo.com/).
+
+## Usage
+
+```ts
+import {
+  getCredentials,
+  getPermissionStatus,
+  initialize,
+  onMessage,
+  onNotificationPress,
+  requestPermission,
+} from 'react-native-push-signal';
+
+initialize({
+  projectId: 'my-project',
+  applicationId: '1:123456789:android:abcd',
+  apiKey: 'AIza...',
+  gcmSenderId: '123456789',
+});
+
+const status = await getPermissionStatus();
+const afterRequest = await requestPermission();
+const credentials = await getCredentials();
+// POST credentials to your server: { platform, token, environment? }
+
+const stopMessages = onMessage((message) => {
+  console.log('incoming', message);
+});
+
+const stopPress = onNotificationPress((message) => {
+  console.log('opened from notification', message);
+});
+```
+
+`onNotificationPress` also delivers the tap that launched the app if you subscribe after startup.
+
+### What to send to your server
+
+| Platform | `credentials.token` | Server sends through |
+| --- | --- | --- |
+| iOS | APNs device token (hex) | Apple APNs HTTP/2 |
+| Android | FCM registration token | Firebase Cloud Messaging HTTP v1 |
+
+Keep Apple `.p8` keys and the Firebase service account on the server. The app never sees them.
+
+`environment` is iOS-only: `sandbox` for development builds, `production` for TestFlight / App Store.
+
+## iOS setup
+
+1. Enable **Push Notifications** on the app target.
+2. Enable **Background Modes → Remote notifications**.
+3. Use a physical device. The simulator cannot register with APNs.
+
+The library hooks `UNUserNotificationCenter` and APNs token callbacks, so the host `AppDelegate` does not need extra code.
+
+## Android setup
+
+Remote Android pushes go through FCM. You can either pass the client Firebase fields at runtime or use `google-services.json`.
+
+### Runtime config (no file in the APK)
+
+Call `initialize` with values from `google-services.json` (not a service account):
+
+```ts
+initialize({
+  projectId: '...',       // project_id
+  applicationId: '...',   // mobilesdk_app_id
+  apiKey: '...',          // current_key
+  gcmSenderId: '...',     // project_number
+});
+```
+
+All four fields are required for Firebase to start. If any is missing, `initialize` does nothing and does not throw. iOS ignores this call.
+
+Keep the Firebase service account on your server. Do not put it in the app.
+
+### google-services.json
+
+Alternatively, add Firebase to the host app:
+
+1. Place `google-services.json` in `android/app`.
+2. Apply the Google Services plugin in `android/app/build.gradle`:
+
+```gradle
+apply plugin: "com.google.gms.google-services"
+```
+
+3. Add the plugin classpath in `android/build.gradle` / `settings.gradle` as in the [Firebase Android setup](https://firebase.google.com/docs/android/setup).
+
+Without `initialize(...)` or that file, `getCredentials()` throws. Notification permission (`POST_NOTIFICATIONS`) is requested on API 33+.
+
+If the host app already declares its own `FirebaseMessagingService`, only one service can handle `com.google.firebase.MESSAGING_EVENT`. Prefer this library’s service or forward events into it.
+
+## Incoming messages vs taps
+
+- `onMessage` — the push arrived while the app is in the foreground (and Android data messages while the process is alive). The library does not draw a banner.
+- `onNotificationPress` — the user opened the notification, including a cold start.
+- On iOS, a visible push received in the background or when the app is killed is delivered on tap, not through `onMessage`. That is an OS limit.
+
+## Web
+
+Permission helpers resolve to `denied`. `getCredentials()` throws. Listeners are no-ops.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT

package/README.ru.md

@@ -0,0 +1,125 @@
+# react-native-push-signal
+
+[English](README.md) | Русский
+
+Библиотека запрашивает разрешение на пуши, отдаёт токен устройства для вашего сервера и сообщает о входящем уведомлении или нажатии на него. Сами пуши она не отправляет — в APNs и FCM ходит бэкенд.
+
+## Установка
+
+```sh
+npm install react-native-push-signal react-native-nitro-modules
+```
+
+`react-native-nitro-modules` обязателен: библиотека собрана на [Nitro Modules](https://nitro.margelo.com/).
+
+## Использование
+
+```ts
+import {
+  getCredentials,
+  getPermissionStatus,
+  initialize,
+  onMessage,
+  onNotificationPress,
+  requestPermission,
+} from 'react-native-push-signal';
+
+initialize({
+  projectId: 'my-project',
+  applicationId: '1:123456789:android:abcd',
+  apiKey: 'AIza...',
+  gcmSenderId: '123456789',
+});
+
+const status = await getPermissionStatus();
+const afterRequest = await requestPermission();
+const credentials = await getCredentials();
+// POST credentials на сервер: { platform, token, environment? }
+
+const stopMessages = onMessage((message) => {
+  console.log('incoming', message);
+});
+
+const stopPress = onNotificationPress((message) => {
+  console.log('opened from notification', message);
+});
+```
+
+Если приложение открыли из уведомления до подписки, `onNotificationPress` всё равно отдаст этот тап сразу после `onNotificationPress(...)`.
+
+### Что отправлять на сервер
+
+| Платформа | `credentials.token`     | Куда сервер шлёт пуш             |
+| --------- | ----------------------- | -------------------------------- |
+| iOS       | APNs device token (hex) | Apple APNs HTTP/2                |
+| Android   | FCM registration token  | Firebase Cloud Messaging HTTP v1 |
+
+Ключи Apple `.p8` и service account Firebase остаются на сервере. Приложение их не видит.
+
+`environment` есть только на iOS: `sandbox` для dev-сборок, `production` для TestFlight и App Store.
+
+## Настройка iOS
+
+1. Включите **Push Notifications** у app target.
+2. Включите **Background Modes → Remote notifications**.
+3. Проверяйте на физическом устройстве. Симулятор не умеет регистрироваться в APNs.
+
+Библиотека сама подписывается на `UNUserNotificationCenter` и колбеки APNs-токена. В `AppDelegate` хоста ничего дописывать не нужно.
+
+## Настройка Android
+
+Удалённые пуши на Android идут через FCM. Можно передать клиентские поля Firebase в рантайме или положить `google-services.json`.
+
+### Конфиг в рантайме (без файла в APK)
+
+Вызовите `initialize` со значениями из `google-services.json` (не из service account):
+
+```ts
+initialize({
+  projectId: '...', // project_id
+  applicationId: '...', // mobilesdk_app_id
+  apiKey: '...', // current_key
+  gcmSenderId: '...', // project_number
+});
+```
+
+Нужны все четыре поля. Если чего-то нет, `initialize` тихо ничего не делает и не бросает ошибку. На iOS вызов игнорируется.
+
+Service account Firebase оставляйте на сервере. В приложение его класть нельзя.
+
+### google-services.json
+
+Либо подключите Firebase в хост-приложение:
+
+1. Положите `google-services.json` в `android/app`.
+2. Подключите плагин Google Services в `android/app/build.gradle`:
+
+```gradle
+apply plugin: "com.google.gms.google-services"
+```
+
+3. Добавьте classpath плагина в `android/build.gradle` / `settings.gradle` по [инструкции Firebase для Android](https://firebase.google.com/docs/android/setup).
+
+Без `initialize(...)` или этого файла `getCredentials()` бросит ошибку. Разрешение на уведомления (`POST_NOTIFICATIONS`) запрашивается на API 33+.
+
+Если в хост-приложении уже есть свой `FirebaseMessagingService`, обработать `com.google.firebase.MESSAGING_EVENT` может только один сервис. Оставьте сервис этой библиотеки или пробрасывайте события в него.
+
+## Входящее сообщение и тап
+
+- `onMessage` — пуш пришёл, пока приложение на переднем плане (и Android data-message, пока процесс жив). Баннер библиотека не рисует.
+- `onNotificationPress` — пользователь открыл уведомление, в том числе при холодном старте.
+- На iOS видимый пуш в фоне или при убитом приложении приходит только в тап, не в `onMessage`. Это ограничение ОС.
+
+## Web
+
+Методы разрешения возвращают `denied`. `getCredentials()` бросает ошибку. Слушатели ничего не делают.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(pushsignal)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME pushsignal)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/pushsignal+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,115 @@
+buildscript {
+  ext.PushSignal = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return PushSignal[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/pushsignal+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.pushsignal"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packaging {
+    resources {
+      excludes += [
+        "META-INF",
+        "META-INF/**"
+      ]
+    }
+
+    jniLibs {
+      excludes += [
+        "**/libc++_shared.so",
+        "**/libfbjni.so",
+        "**/libjsi.so",
+        "**/libfolly_json.so",
+        "**/libfolly_runtime.so",
+        "**/libglog.so",
+        "**/libhermes.so",
+        "**/libhermes-executor-debug.so",
+        "**/libhermes_executor.so",
+        "**/libreactnative.so",
+        "**/libreactnativejni.so",
+        "**/libturbomodulejsijni.so",
+        "**/libreact_nativemodule_core.so",
+        "**/libjscexecutor.so"
+      ]
+    }
+  }
+
+  buildFeatures {
+    prefab true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+  implementation "androidx.activity:activity-ktx:1.10.1"
+  implementation "androidx.core:core-ktx:1.16.0"
+  implementation "com.google.firebase:firebase-messaging:24.1.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+  <application>
+    <provider
+      android:name="com.margelo.nitro.pushsignal.PushSignalInitProvider"
+      android:authorities="${applicationId}.pushsignal.init"
+      android:exported="false" />
+
+    <service
+      android:name="com.margelo.nitro.pushsignal.PushSignalMessagingService"
+      android:exported="false">
+      <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+      </intent-filter>
+    </service>
+  </application>
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,11 @@
+#include <jni.h>
+#include "pushsignalOnLoad.hpp"
+
+#include <fbjni/fbjni.h>
+
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::pushsignal::registerAllNatives();
+  });
+}

package/android/src/main/java/com/margelo/nitro/pushsignal/PushSignal.kt

@@ -0,0 +1,44 @@
+package com.margelo.nitro.pushsignal
+
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+
+@DoNotStrip
+class PushSignal : HybridPushSignalSpec() {
+  override fun initialize(config: AndroidFirebaseConfig) {
+    PushSignalCenter.initialize(config)
+  }
+
+  override fun getPermissionStatus(): Promise<PermissionStatus> {
+    return Promise.async {
+      PushSignalCenter.getPermissionStatus()
+    }
+  }
+
+  override fun requestPermission(): Promise<PermissionStatus> {
+    val promise = Promise<PermissionStatus>()
+    PushSignalCenter.requestPermission { status ->
+      promise.resolve(status)
+    }
+    return promise
+  }
+
+  override fun getCredentials(): Promise<PushCredentials> {
+    return Promise.async {
+      val token = PushSignalCenter.fetchToken()
+      PushCredentials(
+        PushPlatform.ANDROID,
+        token,
+        null
+      )
+    }
+  }
+
+  override fun setOnMessage(callback: (message: PushMessage) -> Unit) {
+    PushSignalCenter.setOnMessage(callback)
+  }
+
+  override fun setOnNotificationPress(callback: (message: PushMessage) -> Unit) {
+    PushSignalCenter.setOnNotificationPress(callback)
+  }
+}