capacitor-push-signal 0.0.1

package/CapacitorPushSignal.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapacitorPushSignal'
+  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.public_header_files = 'ios/Sources/PushSignalCore/include/*.h'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.frameworks = 'UIKit', 'UserNotifications'
+  s.swift_version = '5.1'
+end

package/Package.swift

@@ -0,0 +1,36 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorPushSignal",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapacitorPushSignal",
+            targets: ["PushSignalPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "PushSignalCore",
+            path: "ios/Sources/PushSignalCore",
+            publicHeadersPath: "include",
+            cSettings: [
+                .headerSearchPath("include")
+            ]),
+        .target(
+            name: "PushSignalPlugin",
+            dependencies: [
+                "PushSignalCore",
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/PushSignalPlugin"),
+        .testTarget(
+            name: "PushSignalPluginTests",
+            dependencies: ["PushSignalPlugin", "PushSignalCore"],
+            path: "ios/Tests/PushSignalPluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,271 @@
+# capacitor-push-signal
+
+Get device credentials for your server and listen for incoming notifications or taps. The plugin does not send pushes — your backend talks to APNs and FCM. Request notification permission yourself (for example with [`@capacitor/push-notifications`](https://capacitorjs.com/docs/apis/push-notifications) permission APIs or platform APIs).
+
+The public JS API matches [`react-native-push-signal`](https://github.com/AntonSeagull/react-native-push-signal): `initialize`, `getCredentials`, `onMessage`, `onNotificationPress`.
+
+## Install
+
+```bash
+npm install capacitor-push-signal
+npx cap sync
+```
+
+## Usage
+
+```ts
+import {
+  getCredentials,
+  initialize,
+  onMessage,
+  onNotificationPress,
+} from 'capacitor-push-signal';
+
+await initialize({
+  project_id: 'my-project',
+  mobilesdk_app_id: '1:123456789:android:abcd',
+  current_key: 'AIza...',
+  project_number: '123456789',
+});
+
+// Request notification permission with your preferred API before getCredentials().
+
+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.
+
+`platform` is `'ios'` or `'android'`.
+
+## 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 plugin hooks `UNUserNotificationCenter` at launch (before JS starts) and APNs token callbacks, so the host `AppDelegate` does not need extra code. Foreground pushes only reach JS if this delegate is installed before launch finishes.
+
+## 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
+await initialize({
+  project_id: '...',
+  mobilesdk_app_id: '...',
+  current_key: '...',
+  project_number: '...',
+});
+```
+
+All four fields are required for Firebase to start. If any is missing, `initialize` resolves and does nothing. iOS ignores the config and still resolves the promise.
+
+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.
+
+If the host app already declares its own `FirebaseMessagingService`, only one service can handle `com.google.firebase.MESSAGING_EVENT`. Prefer this plugin’s service or forward events into it.
+
+## Incoming messages vs taps
+
+| App state | iOS | Android (notification payload) | Android (data-only) |
+| --- | --- | --- | --- |
+| Foreground | `onMessage` + system banner | `onMessage` + tray (if title/body) | `onMessage` + tray (if title/body) |
+| Background / killed | System banner. Tap → `onNotificationPress` | System banner. Tap → `onNotificationPress` | No banner. `onMessage` if the process is alive |
+
+- `onMessage` — the push arrived while the app is in the foreground (and Android data messages while the process is alive). Listeners only receive the payload; they do not control the 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
+
+`initialize()` resolves. `getCredentials()` throws. Listeners (`onMessage`, `onNotificationPress`) are no-ops.
+
+## API
+
+<docgen-index>
+
+* [`initialize(...)`](#initialize)
+* [`getCredentials()`](#getcredentials)
+* [`startListening()`](#startlistening)
+* [`addListener('onMessage', ...)`](#addlisteneronmessage-)
+* [`addListener('onNotificationPress', ...)`](#addlisteneronnotificationpress-)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### initialize(...)
+
+```typescript
+initialize(config?: AndroidFirebaseConfig | undefined) => Promise<void>
+```
+
+Bootstrap Android Firebase from client fields (no-op on iOS / incomplete config).
+
+| Param        | Type                                                                    |
+| ------------ | ----------------------------------------------------------------------- |
+| **`config`** | <code><a href="#androidfirebaseconfig">AndroidFirebaseConfig</a></code> |
+
+--------------------
+
+
+### getCredentials()
+
+```typescript
+getCredentials() => Promise<PushCredentials>
+```
+
+Returns APNs (iOS) or FCM (Android) credentials for your server.
+
+**Returns:** <code>Promise&lt;<a href="#pushcredentials">PushCredentials</a>&gt;</code>
+
+--------------------
+
+
+### startListening()
+
+```typescript
+startListening() => Promise<void>
+```
+
+Start delivering native message / press events to JS listeners.
+
+--------------------
+
+
+### addListener('onMessage', ...)
+
+```typescript
+addListener(eventName: 'onMessage', listenerFunc: (message: PushMessage) => void) => Promise<PluginListenerHandle>
+```
+
+| Param              | Type                                                                      |
+| ------------------ | ------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'onMessage'</code>                                                  |
+| **`listenerFunc`** | <code>(message: <a href="#pushmessage">PushMessage</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('onNotificationPress', ...)
+
+```typescript
+addListener(eventName: 'onNotificationPress', listenerFunc: (message: PushMessage) => void) => Promise<PluginListenerHandle>
+```
+
+| Param              | Type                                                                      |
+| ------------------ | ------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'onNotificationPress'</code>                                        |
+| **`listenerFunc`** | <code>(message: <a href="#pushmessage">PushMessage</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### Interfaces
+
+
+#### AndroidFirebaseConfig
+
+| Prop                   | Type                |
+| ---------------------- | ------------------- |
+| **`project_id`**       | <code>string</code> |
+| **`mobilesdk_app_id`** | <code>string</code> |
+| **`current_key`**      | <code>string</code> |
+| **`project_number`**   | <code>string</code> |
+
+
+#### PushCredentials
+
+| Prop              | Type                                                        |
+| ----------------- | ----------------------------------------------------------- |
+| **`platform`**    | <code><a href="#pushplatform">PushPlatform</a></code>       |
+| **`token`**       | <code>string</code>                                         |
+| **`environment`** | <code><a href="#pushenvironment">PushEnvironment</a></code> |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### PushMessage
+
+| Prop        | Type                                                            |
+| ----------- | --------------------------------------------------------------- |
+| **`id`**    | <code>string</code>                                             |
+| **`title`** | <code>string</code>                                             |
+| **`body`**  | <code>string</code>                                             |
+| **`data`**  | <code><a href="#record">Record</a>&lt;string, string&gt;</code> |
+
+
+### Type Aliases
+
+
+#### PushPlatform
+
+<code>'ios' | 'android'</code>
+
+
+#### PushEnvironment
+
+<code>'sandbox' | 'production'</code>
+
+
+#### Record
+
+Construct a type with a set of properties K of type T
+
+<code>{
 [P in K]: T;
 }</code>
+
+</docgen-api>
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,66 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty('kotlin_version') ? rootProject.ext.kotlin_version : '2.0.21'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace = "com.antonseagull.cap.push.signal"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        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_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    kotlinOptions {
+        jvmTarget = '21'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    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"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <provider
+            android:name="com.antonseagull.cap.push.signal.PushSignalInitProvider"
+            android:authorities="${applicationId}.pushsignal.init"
+            android:exported="false" />
+
+        <service
+            android:name="com.antonseagull.cap.push.signal.PushSignalMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+    </application>
+</manifest>

package/android/src/main/java/com/antonseagull/cap/push/signal/PushModels.kt

@@ -0,0 +1,15 @@
+package com.antonseagull.cap.push.signal
+
+data class PushMessage(
+  val id: String?,
+  val title: String?,
+  val body: String?,
+  val data: Map<String, String>,
+)
+
+data class AndroidFirebaseConfig(
+  val project_id: String?,
+  val mobilesdk_app_id: String?,
+  val current_key: String?,
+  val project_number: String?,
+)