@drkostas/expo-ntfy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+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,101 @@
+# @drkostas/expo-ntfy
+
+This package gets messages from a self-hosted [ntfy](https://ntfy.sh) server to an Android phone running an Expo app, without Firebase. I wrote it because the JavaScript socket in my app stopped receiving the moment the phone locked, so notifications only reached a phone that someone was already looking at.
+
+It has three parts.
+
+- A config plugin that adds a native Android foreground service. The service holds the ntfy WebSocket while the app is closed and posts every message to the tray itself.
+- The wire logic (`proto` and `poll`), with no Expo or React Native imports, so it runs in Node and is tested there.
+- The Expo glue (`notify` and `background`) for permissions, local notifications, the socket while the app is open, taps, and a background poll.
+
+## Install
+
+```bash
+npm install @drkostas/expo-ntfy
+```
+
+It expects `expo`, `expo-notifications`, `react` and `react-native` in the app, and `expo-background-task` and `expo-task-manager` if you use the background poll.
+
+## The config plugin
+
+```json
+{
+  "expo": {
+    "scheme": "myapp",
+    "android": { "package": "org.example.myapp" },
+    "plugins": [
+      ["@drkostas/expo-ntfy", { "alertChannelName": "My app" }]
+    ]
+  }
+}
+```
+
+The topic URL comes from `EXPO_PUBLIC_NTFY_URL` at prebuild time, or from the `url` option. There is no default address. The Android prebuild stops with an error when the URL is missing, is not http(s), or is a loopback address (localhost, 127.0.0.1, ::1), because a phone given that address connects to itself and never receives anything. Reading the app config (`expo start`, a web build) does not need the URL.
+
+| option | default |
+|---|---|
+| `url` | the value of `urlEnv` |
+| `urlEnv` | `EXPO_PUBLIC_NTFY_URL` |
+| `package` | `expo.android.package` |
+| `buildConfigField` | `NTFY_TOPIC_URL` |
+| `defaultTitle` | `expo.name` |
+| `linkPrefix` | `<expo.scheme>://`, or no links when there is no scheme |
+| `alertChannelId`, `alertChannelName`, `alertChannelDescription` | `ntfy_messages`, `expo.name`, a short text |
+| `ongoingChannelId`, `ongoingChannelName`, `ongoingChannelDescription` | `ntfy_connection`, `Connection`, a short text |
+| `ongoingTitle`, `ongoingText` | `<expo.name> is connected`, `waiting for messages` |
+| `logTag` | `NtfyService` |
+
+What it writes at prebuild.
+
+- `NtfyService.kt` and `BootReceiver` next to `MainActivity`, in the app's package.
+- The URL as a BuildConfig field. It is replaced on every build, so building again with a different URL corrects a wrong one.
+- A call in `MainActivity.onCreate` that starts the service.
+- The manifest entries for the service (type `dataSync`), the receiver, and the permissions `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_DATA_SYNC`, `RECEIVE_BOOT_COMPLETED` and `WAKE_LOCK`.
+
+A message's click URL opens the app only when it starts with `linkPrefix`. A notification is data from the network, so any other link is shown in the text but never followed.
+
+## The glue
+
+```ts
+import { installForegroundHandler, raiseLocalNotification, useNtfy } from "@drkostas/expo-ntfy/notify";
+import { defineTopicPollTask, registerTopicPoll } from "@drkostas/expo-ntfy/background";
+import { pollTopicOnce } from "@drkostas/expo-ntfy";
+
+const TOPIC = process.env.EXPO_PUBLIC_NTFY_URL;
+const text = { appName: "My app", linkPrefix: "myapp://" };
+
+installForegroundHandler();
+
+// while a screen is open
+const { connected } = useNtfy(TOPIC, () => refetch(), { text });
+
+// while the app is closed, on a schedule the OS decides
+defineTopicPollTask("topic-poll", () =>
+  pollTopicOnce({ topicUrl: TOPIC!, readMark, commitMark, text,
+    announce: (n) => raiseLocalNotification(n.title, n.body, n.url) }));
+await registerTopicPoll("topic-poll", 15);
+```
+
+## Things I learned on real phones
+
+- Only one part of the app may post to the tray. With the native service posting and JavaScript posting too, every message arrived twice. On Android the glue stays out of the tray by default (`TRAY_IS_NATIVE`), and keeps the in-app updates.
+- Android 14 and later need the foreground service type in the `startForeground` call as well as in the manifest, or the service crashes when it starts.
+- Installing an update stops the service, and nothing starts it again until someone opens the app. The receiver listens for `MY_PACKAGE_REPLACED` for that reason.
+- Some Android skins (ColorOS on OPPO, for example) stop even a foreground service unless the app's battery setting allows background activity. The app cannot change that setting itself. The person has to choose "Allow background activity" in the app's battery settings.
+- A device that has never watched the topic has not missed anything. On the first read the watermark takes the newest position instead of announcing the whole backlog.
+- ntfy stamps whole seconds, so the watermark keeps the ids seen at its second, and no message from the same second is skipped or shown twice.
+- ntfy parses `since` as a Go duration, which has no day unit. `7d` gets a 400, `24h` and `all` work.
+- The background poll interval is a request. Android decides when it runs, so the poll is a floor under the socket and the service, not a replacement.
+
+## Tests
+
+```bash
+npm ci
+npm test
+```
+
+The plugin test copies a fixture Android project to a temporary folder, runs the plugin through `@expo/config-plugins`, and reads the Kotlin, Gradle and manifest files it wrote.
+
+## License
+
+MIT

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require("./plugin/withNtfyForegroundService");

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@drkostas/expo-ntfy",
+  "version": "0.1.0",
+  "description": "Phone notifications from a self-hosted ntfy server in an Expo app, without Firebase: a config plugin that adds a native Android foreground service, plus the wire logic and the notification glue",
+  "license": "MIT",
+  "author": "Konstantinos Georgiou",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drkostas/claude-human.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/drkostas/claude-human/tree/main/js#readme",
+  "keywords": [
+    "expo",
+    "expo-config-plugin",
+    "ntfy",
+    "notifications",
+    "android",
+    "foreground-service",
+    "react-native"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./proto": "./src/proto.ts",
+    "./poll": "./src/poll.ts",
+    "./notify": "./src/notify.ts",
+    "./background": "./src/background.ts",
+    "./plugin": "./app.plugin.js",
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "plugin",
+    "app.plugin.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-background-task": "*",
+    "expo-notifications": "*",
+    "expo-task-manager": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "expo-background-task": {
+      "optional": true
+    },
+    "expo-notifications": {
+      "optional": true
+    },
+    "expo-task-manager": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "^57.0.9",
+    "@types/node": "^22.20.5",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/plugin/withNtfyForegroundService.js

@@ -0,0 +1,413 @@
+/**
+ * Expo config plugin that adds a native Android foreground service holding an ntfy WebSocket.
+ *
+ * Without Firebase, a socket opened from JavaScript lives only while the app is in the foreground:
+ * Android suspends it seconds after the screen locks. A foreground service can keep it open, which
+ * is what ntfy's own Android app does for self-hosted servers. This plugin writes a small Kotlin
+ * service that owns the socket and posts each message to the tray itself, a receiver that starts
+ * it again after a reboot or an app update, and the manifest entries they need.
+ *
+ * The source and the manifest changes are written at prebuild time, because `expo prebuild
+ * --clean` regenerates android/ and anything edited there by hand is lost.
+ *
+ * Options (all optional):
+ *   url               the topic URL (default: the environment variable named by urlEnv)
+ *   urlEnv            default "EXPO_PUBLIC_NTFY_URL"
+ *   package           Kotlin package and manifest namespace (default: expo.android.package)
+ *   buildConfigField  name of the BuildConfig field that carries the URL (default "NTFY_TOPIC_URL")
+ *   defaultTitle      title for a message without one (default: expo.name)
+ *   linkPrefix        a message's click URL opens the app only when it starts with this
+ *                     (default: "<expo.scheme>://", or no links when the app has no scheme)
+ *   ongoingChannelId, ongoingChannelName, ongoingChannelDescription, ongoingTitle, ongoingText
+ *                     the low-importance channel and notification a foreground service must show
+ *   alertChannelId, alertChannelName, alertChannelDescription
+ *                     the channel messages are posted on
+ *   logTag            Android log tag (default "NtfyService")
+ *
+ * The Android prebuild fails when the URL is missing or points at the build machine itself (localhost,
+ * 127.0.0.1, ::1): a phone given that address connects to itself and never receives anything.
+ */
+const fs = require("fs");
+const path = require("path");
+
+function loadConfigPlugins(config) {
+  const roots = [config && config._internal && config._internal.projectRoot, process.cwd(), __dirname]
+    .filter(Boolean);
+  for (const name of ["expo/config-plugins", "@expo/config-plugins"]) {
+    try {
+      return require(require.resolve(name, { paths: roots }));
+    } catch (e) {
+      // try the next one
+    }
+  }
+  throw new Error("expo-ntfy: cannot find expo/config-plugins. Install expo in the app.");
+}
+
+function isLoopbackHost(host) {
+  const h = String(host || "").replace(/^\[|\]$/g, "").toLowerCase();
+  return h === "" || h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "0.0.0.0"
+    || /^127\.\d+\.\d+\.\d+$/.test(h);
+}
+
+/** The topic URL, checked. Throws when it is missing, invalid or loopback. */
+function checkTopicUrl(url, source) {
+  let parsed = null;
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    parsed = null;
+  }
+  if (!url) {
+    throw new Error(`expo-ntfy: no ntfy topic URL. Set ${source} or pass the "url" option.`);
+  }
+  if (!parsed || !/^https?:$/.test(parsed.protocol)) {
+    throw new Error(`expo-ntfy: ${JSON.stringify(url)} is not an http(s) URL.`);
+  }
+  if (isLoopbackHost(parsed.hostname)) {
+    throw new Error(`expo-ntfy: refusing to build with ntfy at ${url}. A phone cannot reach the ` +
+      "build machine as localhost. Use an address of the ntfy server that the phone can reach.");
+  }
+  if (/["\\$\s]/.test(url)) {
+    throw new Error(`expo-ntfy: the topic URL contains a character that cannot go into BuildConfig: ${url}`);
+  }
+  return url;
+}
+
+function resolveOptions(config, options = {}, env = process.env) {
+  const name = config.name || "App";
+  const urlEnv = options.urlEnv || "EXPO_PUBLIC_NTFY_URL";
+  const pkg = options.package || (config.android && config.android.package);
+  if (!pkg || !/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$/.test(pkg)) {
+    throw new Error(`expo-ntfy: set expo.android.package or the "package" option (got ${JSON.stringify(pkg)})`);
+  }
+  const scheme = Array.isArray(config.scheme) ? config.scheme[0] : config.scheme;
+  const o = {
+    url: checkTopicUrl(options.url || env[urlEnv], options.url ? 'the "url" option' : urlEnv),
+    package: pkg,
+    buildConfigField: options.buildConfigField || "NTFY_TOPIC_URL",
+    defaultTitle: options.defaultTitle || name,
+    linkPrefix: options.linkPrefix !== undefined ? options.linkPrefix : (scheme ? `${scheme}://` : ""),
+    ongoingChannelId: options.ongoingChannelId || "ntfy_connection",
+    ongoingChannelName: options.ongoingChannelName || "Connection",
+    ongoingChannelDescription: options.ongoingChannelDescription ||
+      "Keeps the app connected so messages arrive while it is closed",
+    ongoingTitle: options.ongoingTitle || `${name} is connected`,
+    ongoingText: options.ongoingText || "waiting for messages",
+    alertChannelId: options.alertChannelId || "ntfy_messages",
+    alertChannelName: options.alertChannelName || name,
+    alertChannelDescription: options.alertChannelDescription || "Messages from the server",
+    logTag: options.logTag || "NtfyService",
+  };
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(o.buildConfigField)) {
+    throw new Error(`expo-ntfy: buildConfigField must be an upper case identifier (got ${o.buildConfigField})`);
+  }
+  for (const k of ["ongoingChannelId", "alertChannelId"]) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(o[k])) throw new Error(`expo-ntfy: invalid ${k} ${JSON.stringify(o[k])}`);
+  }
+  return o;
+}
+
+/** A Kotlin string literal. */
+function kt(s) {
+  return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$")
+    .replace(/\n/g, "\\n") + '"';
+}
+
+function renderKotlin(o) {
+  const linkCheck = o.linkPrefix
+    ? `click.startsWith(${kt(o.linkPrefix)})`
+    : "false";
+  return `package ${o.package}
+
+import android.app.*
+import android.content.*
+import android.os.Build
+import android.os.IBinder
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import okhttp3.*
+import org.json.JSONObject
+import java.util.concurrent.TimeUnit
+
+/**
+ * Holds the ntfy topic's WebSocket open natively, so messages arrive while the phone is locked and
+ * the JavaScript side is suspended. It posts what it receives to the tray itself and does not talk
+ * to JavaScript. Written by the expo-ntfy config plugin; regenerated on every prebuild.
+ */
+class NtfyService : Service() {
+    companion object {
+        const val ONGOING_CHANNEL = ${kt(o.ongoingChannelId)}
+        const val ALERT_CHANNEL = ${kt(o.alertChannelId)}
+        const val ONGOING_ID = 4711
+        private const val TAG = ${kt(o.logTag)}
+        var topicUrl: String = BuildConfig.${o.buildConfigField}
+    }
+
+    private var client: OkHttpClient? = null
+    private var ws: WebSocket? = null
+    private var stopping = false
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        createChannels()
+        // Android 14 and later throw unless the service type is also given here, not only in the
+        // manifest.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            startForeground(
+                ONGOING_ID, ongoingNotification(),
+                android.content.pm.ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+            )
+        } else {
+            startForeground(ONGOING_ID, ongoingNotification())
+        }
+        connect()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int = START_STICKY
+
+    override fun onDestroy() {
+        stopping = true
+        ws?.close(1000, "service stopping")
+        super.onDestroy()
+    }
+
+    private fun createChannels() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val mgr = getSystemService(NotificationManager::class.java)
+        // The connection notice is required for a foreground service. It is not a message, so its
+        // channel has the lowest importance.
+        mgr.createNotificationChannel(
+            NotificationChannel(ONGOING_CHANNEL, ${kt(o.ongoingChannelName)}, NotificationManager.IMPORTANCE_MIN)
+                .apply { description = ${kt(o.ongoingChannelDescription)} }
+        )
+        mgr.createNotificationChannel(
+            NotificationChannel(ALERT_CHANNEL, ${kt(o.alertChannelName)}, NotificationManager.IMPORTANCE_HIGH)
+                .apply { description = ${kt(o.alertChannelDescription)} }
+        )
+    }
+
+    private fun ongoingNotification(): Notification =
+        NotificationCompat.Builder(this, ONGOING_CHANNEL)
+            .setContentTitle(${kt(o.ongoingTitle)})
+            .setContentText(${kt(o.ongoingText)})
+            .setSmallIcon(applicationInfo.icon)
+            .setOngoing(true)
+            .setPriority(NotificationCompat.PRIORITY_MIN)
+            .setContentIntent(
+                PendingIntent.getActivity(
+                    this, 0,
+                    packageManager.getLaunchIntentForPackage(packageName),
+                    PendingIntent.FLAG_IMMUTABLE
+                )
+            )
+            .build()
+
+    private fun wsUrl(): String {
+        var base = topicUrl.trimEnd('/')
+        base = base.replaceFirst("https://", "wss://").replaceFirst("http://", "ws://")
+        return base + "/ws"
+    }
+
+    private fun connect() {
+        if (stopping) return
+        val c = OkHttpClient.Builder()
+            .readTimeout(0, TimeUnit.MILLISECONDS)
+            .pingInterval(45, TimeUnit.SECONDS)   // keeps NAT mappings and tunnels open
+            .build()
+        client = c
+        ws = c.newWebSocket(Request.Builder().url(wsUrl()).build(), object : WebSocketListener() {
+            override fun onMessage(webSocket: WebSocket, text: String) = handle(text)
+            override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                Log.w(TAG, "socket failed: " + t.message)
+                reconnectSoon()
+            }
+            override fun onClosed(webSocket: WebSocket, code: Int, reason: String) = reconnectSoon()
+        })
+    }
+
+    private fun reconnectSoon() {
+        if (stopping) return
+        Thread {
+            Thread.sleep(5000)
+            if (!stopping) connect()
+        }.start()
+    }
+
+    /** Only message frames are shown. Open and keepalive frames are not for a person. */
+    private fun handle(text: String) {
+        try {
+            val f = JSONObject(text)
+            if (f.optString("event") != "message") return
+            val title = f.optString("title").ifBlank { ${kt(o.defaultTitle)} }
+            val body = f.optString("message").ifBlank { title }
+            val click = f.optString("click")
+            val open = packageManager.getLaunchIntentForPackage(packageName)?.apply {
+                // only links into this app are followed; a link from the network is data
+                if (${linkCheck}) {
+                    action = Intent.ACTION_VIEW
+                    data = android.net.Uri.parse(click)
+                }
+            }
+            val n = NotificationCompat.Builder(this, ALERT_CHANNEL)
+                .setContentTitle(title)
+                .setContentText(body)
+                .setStyle(NotificationCompat.BigTextStyle().bigText(body))
+                .setSmallIcon(applicationInfo.icon)
+                .setAutoCancel(true)
+                .setPriority(NotificationCompat.PRIORITY_HIGH)
+                .apply {
+                    if (open != null) setContentIntent(
+                        PendingIntent.getActivity(
+                            this@NtfyService, click.hashCode(), open,
+                            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
+                        )
+                    )
+                }
+                .build()
+            getSystemService(NotificationManager::class.java)
+                .notify(f.optString("id").hashCode(), n)
+        } catch (e: Exception) {
+            Log.w(TAG, "bad frame: " + e.message)
+        }
+    }
+}
+
+/**
+ * Starts the service after a reboot and after the app is updated. Installing a new version stops
+ * the app and its services, and without MY_PACKAGE_REPLACED nothing would start the service again
+ * until someone opened the app, so messages would stop arriving after every update.
+ */
+class BootReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action == Intent.ACTION_BOOT_COMPLETED ||
+            intent.action == Intent.ACTION_MY_PACKAGE_REPLACED) {
+            val i = Intent(context, NtfyService::class.java)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) context.startForegroundService(i)
+            else context.startService(i)
+        }
+    }
+}
+`;
+}
+
+const DEPS_MARKER = "expo-ntfy-deps";
+
+/** app/build.gradle with the dependencies and the BuildConfig field. The field is replaced on every
+ *  build, so building again with a different URL corrects it. */
+function patchAppGradle(src, o) {
+  let g = src;
+  if (!g.includes(DEPS_MARKER)) {
+    g = g.replace(/dependencies\s*\{/, `dependencies {
+    // ${DEPS_MARKER}
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+    implementation("androidx.core:core-ktx:1.13.1")`);
+  }
+  const field = `buildConfigField("String", "${o.buildConfigField}", "\\"${o.url}\\"")`;
+  const existing = new RegExp(`buildConfigField\\("String", "${o.buildConfigField}", "\\\\"[^"\\\\]*\\\\""\\)`);
+  if (existing.test(g)) {
+    g = g.replace(existing, field);
+  } else {
+    g = g.replace(/defaultConfig\s*\{/, `defaultConfig {\n        ${field}`);
+    if (/buildFeatures\s*\{/.test(g)) {
+      if (!/buildConfig\s+true/.test(g)) g = g.replace(/buildFeatures\s*\{/, "buildFeatures {\n        buildConfig true");
+    } else {
+      g = g.replace(/android\s*\{/, "android {\n    buildFeatures { buildConfig true }");
+    }
+  }
+  return g;
+}
+
+/** MainActivity.kt starting the service in onCreate, or the service would only run after a reboot. */
+function patchMainActivity(src) {
+  if (src.includes("NtfyService::class.java")) return src;
+  return src.replace(/(super\.onCreate\([^)]*\))/, `$1
+    // hold the ntfy socket natively (expo-ntfy): the JavaScript socket stops when the screen locks
+    try {
+      val svc = android.content.Intent(this, NtfyService::class.java)
+      if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O)
+        startForegroundService(svc) else startService(svc)
+    } catch (e: Exception) { android.util.Log.w("NtfyService", "start: " + e.message) }`);
+}
+
+const PERMISSIONS = [
+  "android.permission.FOREGROUND_SERVICE",
+  "android.permission.FOREGROUND_SERVICE_DATA_SYNC",
+  "android.permission.RECEIVE_BOOT_COMPLETED",
+  "android.permission.WAKE_LOCK",
+];
+
+/** The manifest (as Expo's parsed XML object) with the permissions, the service and the receiver. */
+function addManifestEntries(manifest, app) {
+  manifest["uses-permission"] = manifest["uses-permission"] || [];
+  for (const name of PERMISSIONS) {
+    if (!manifest["uses-permission"].some((p) => p.$["android:name"] === name)) {
+      manifest["uses-permission"].push({ $: { "android:name": name } });
+    }
+  }
+  app.service = app.service || [];
+  if (!app.service.some((s) => s.$["android:name"] === ".NtfyService")) {
+    app.service.push({
+      $: {
+        "android:name": ".NtfyService",
+        "android:exported": "false",
+        "android:foregroundServiceType": "dataSync",
+      },
+    });
+  }
+  app.receiver = app.receiver || [];
+  if (!app.receiver.some((r) => r.$["android:name"] === ".BootReceiver")) {
+    app.receiver.push({
+      $: { "android:name": ".BootReceiver", "android:exported": "true" },
+      "intent-filter": [
+        { action: [{ $: { "android:name": "android.intent.action.BOOT_COMPLETED" } }] },
+        { action: [{ $: { "android:name": "android.intent.action.MY_PACKAGE_REPLACED" } }] },
+      ],
+    });
+  }
+  return manifest;
+}
+
+function withNtfyForegroundService(config, options = {}) {
+  const { withDangerousMod, withAndroidManifest, AndroidConfig } = loadConfigPlugins(config);
+
+  config = withDangerousMod(config, [
+    "android",
+    (cfg) => {
+      // Resolved here and not when the plugin is loaded, so that reading the app config (expo
+      // start, the web build) never needs the phone's ntfy address.
+      const o = resolveOptions(cfg, options);
+      const root = cfg.modRequest.platformProjectRoot;
+      const dir = path.join(root, "app/src/main/java", ...o.package.split("."));
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, "NtfyService.kt"), renderKotlin(o));
+
+      const gradle = path.join(root, "app/build.gradle");
+      fs.writeFileSync(gradle, patchAppGradle(fs.readFileSync(gradle, "utf8"), o));
+
+      const mainActivity = path.join(dir, "MainActivity.kt");
+      if (fs.existsSync(mainActivity)) {
+        fs.writeFileSync(mainActivity, patchMainActivity(fs.readFileSync(mainActivity, "utf8")));
+      }
+      return cfg;
+    },
+  ]);
+
+  config = withAndroidManifest(config, (cfg) => {
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(cfg.modResults);
+    addManifestEntries(cfg.modResults.manifest, app);
+    return cfg;
+  });
+  return config;
+}
+
+module.exports = withNtfyForegroundService;
+module.exports.withNtfyForegroundService = withNtfyForegroundService;
+module.exports.resolveOptions = resolveOptions;
+module.exports.checkTopicUrl = checkTopicUrl;
+module.exports.isLoopbackHost = isLoopbackHost;
+module.exports.renderKotlin = renderKotlin;
+module.exports.patchAppGradle = patchAppGradle;
+module.exports.patchMainActivity = patchMainActivity;
+module.exports.addManifestEntries = addManifestEntries;

package/src/background.ts

@@ -0,0 +1,37 @@
+/** Read the topic while the app is not open, on a schedule the OS controls.
+ *
+ *  The foreground socket in notify.ts stops when the app is backgrounded. This registers a
+ *  background task that runs `pollTopicOnce` (poll.ts) on each wake. The interval is a request to
+ *  the OS, not a promise: Android decides, and aggressive battery managers can defer it for a long
+ *  time. It is a floor under the live socket and the native service, not a replacement for them.
+ *
+ *  `defineTopicPollTask` must run at module top level (Expo's TaskManager requires tasks to be
+ *  defined in the global scope), so call it from a module the app imports at startup. */
+import * as BackgroundTask from "expo-background-task";
+import * as TaskManager from "expo-task-manager";
+import { Platform } from "react-native";
+
+/** Define the task `name` to run `pass` on every OS wake. */
+export function defineTopicPollTask(name: string, pass: () => Promise<unknown>): void {
+  TaskManager.defineTask(name, async () => {
+    try {
+      await pass();
+      return BackgroundTask.BackgroundTaskResult.Success;
+    } catch {
+      return BackgroundTask.BackgroundTaskResult.Failed;
+    }
+  });
+}
+
+/** Ask the OS to wake the task about every `minutes`. False on web, or when registration fails. */
+export async function registerTopicPoll(name: string, minutes = 15): Promise<boolean> {
+  if (Platform.OS === "web") return false;
+  try {
+    if (!(await TaskManager.isTaskRegisteredAsync(name))) {
+      await BackgroundTask.registerTaskAsync(name, { minimumInterval: minutes });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/** The parts that run anywhere (Node included). The Expo glue is imported from
+ *  "@drkostas/expo-ntfy/notify" and "@drkostas/expo-ntfy/background", and the config plugin is
+ *  listed in app.json as "@drkostas/expo-ntfy". */
+export * from "./proto";
+export * from "./poll";

package/src/notify.ts

@@ -0,0 +1,176 @@
+/** Expo and React Native glue that turns an ntfy topic into notifications on this device, without
+ *  Firebase. The app holds its own WebSocket to the topic while it is open and raises a local
+ *  notification per message. The wire logic is in proto.ts.
+ *
+ *  On Android the config plugin adds a native foreground service that holds the socket while the
+ *  app is closed and posts to the tray itself. Only one part of the app may own the tray, or every
+ *  message appears twice, so on Android this module stays out of the tray by default (see
+ *  TRAY_IS_NATIVE). */
+import { useEffect, useRef, useState } from "react";
+import { Linking, Platform } from "react-native";
+import * as Notifications from "expo-notifications";
+
+import { frameToNotification, parseFrame, wsUrlFrom, type NotificationText, type NtfyFrame } from "./proto";
+
+/** True on Android, where the plugin's native service posts every message. Set the `trayIsNative`
+ *  option to false if the app does not use the config plugin. */
+export const TRAY_IS_NATIVE = Platform.OS === "android";
+
+/** Show notifications that arrive while the app is in the foreground. Call once at startup. */
+export function installForegroundHandler(): void {
+  if (Platform.OS === "web") return;
+  Notifications.setNotificationHandler({
+    handleNotification: async () => ({
+      shouldShowBanner: true,
+      shouldShowList: true,
+      shouldPlaySound: true,
+      shouldSetBadge: false,
+    }),
+  });
+}
+
+/** Ask for notification permission once. Always false on web, which has no OS tray here. */
+export async function ensureNotificationPermission(): Promise<boolean> {
+  if (Platform.OS === "web") return false;
+  const cur = await Notifications.getPermissionsAsync();
+  if (cur.granted) return true;
+  const req = await Notifications.requestPermissionsAsync();
+  return req.granted;
+}
+
+/** Raise a local notification now. `url` rides in its data, so a tap can open it. Does nothing on
+ *  web, and nothing on Android while the native service owns the tray. */
+export async function raiseLocalNotification(
+  title: string,
+  body: string,
+  url?: string,
+  opts: { trayIsNative?: boolean } = {},
+): Promise<void> {
+  if (Platform.OS === "web") return;
+  if (opts.trayIsNative ?? TRAY_IS_NATIVE) return;
+  await Notifications.scheduleNotificationAsync({
+    content: { title, body, data: url ? { url } : {} },
+    trigger: null,
+  });
+}
+
+export interface ResponseHandlers {
+  /** a notification raised by this module was tapped. `url` is its click URL, if it had one. */
+  onTap?: (url: string | undefined) => void;
+  /** the app was opened by a link (the native service opens the app with the click URL as a deep
+   *  link), including the link that launched it from cold */
+  onLink?: (url: string) => void;
+}
+
+/** Listen for taps on notifications and for incoming links, including the ones that launched the
+ *  app from cold, which are read once at startup. */
+export function useNotificationResponses(handlers: ResponseHandlers): void {
+  const ref = useRef(handlers);
+  useEffect(() => {
+    ref.current = handlers;
+  }, [handlers]);
+  useEffect(() => {
+    if (Platform.OS === "web") return;
+    let alive = true;
+    const handle = (resp: Notifications.NotificationResponse | null) => {
+      if (!alive || !resp) return;
+      ref.current.onTap?.(resp.notification.request.content.data?.url as string | undefined);
+    };
+    void Notifications.getLastNotificationResponseAsync().then(handle);
+    const sub = Notifications.addNotificationResponseReceivedListener(handle);
+    void Linking.getInitialURL().then((u) => {
+      if (alive && u) ref.current.onLink?.(u);
+    });
+    const link = Linking.addEventListener("url", (e) => {
+      if (alive) ref.current.onLink?.(e.url);
+    });
+    return () => {
+      alive = false;
+      sub.remove();
+      link.remove();
+    };
+  }, []);
+}
+
+export interface NtfyState {
+  connected: boolean;
+  last: NtfyFrame | null;
+}
+
+export interface UseNtfyOptions {
+  /** how a frame reads as a notification */
+  text?: NotificationText;
+  /** see raiseLocalNotification */
+  trayIsNative?: boolean;
+  /** delay before reconnecting a dropped socket, in ms (default 3000) */
+  retryMs?: number;
+}
+
+/** Hold the topic's WebSocket open while the component is mounted, reconnecting when it drops.
+ *  Each message raises a local notification and calls `onMessage`. With no `topicUrl` nothing
+ *  connects.
+ *
+ *  This socket lives only while the app is in the foreground. Android suspends it seconds after
+ *  the app is backgrounded, which is why the native service and the background poll exist. */
+export function useNtfy(
+  topicUrl: string | undefined,
+  onMessage?: (f: NtfyFrame) => void,
+  opts: UseNtfyOptions = {},
+): NtfyState {
+  const [connected, setConnected] = useState(false);
+  const [last, setLast] = useState<NtfyFrame | null>(null);
+  const cb = useRef(onMessage);
+  const options = useRef(opts);
+  useEffect(() => {
+    cb.current = onMessage;
+    options.current = opts;
+  });
+
+  useEffect(() => {
+    if (!topicUrl) return;
+    let closed = false;
+    let ws: WebSocket | null = null;
+    let retry: ReturnType<typeof setTimeout> | undefined;
+
+    void ensureNotificationPermission();
+
+    const connect = () => {
+      if (closed) return;
+      ws = new WebSocket(wsUrlFrom(topicUrl));
+      ws.onopen = () => setConnected(true);
+      ws.onclose = () => {
+        setConnected(false);
+        if (!closed) retry = setTimeout(connect, options.current.retryMs ?? 3000);
+      };
+      ws.onerror = () => {
+        try {
+          ws?.close();
+        } catch {
+          // onclose reconnects
+        }
+      };
+      ws.onmessage = (ev) => {
+        const raw = (ev as { data?: unknown }).data;
+        const frame = parseFrame(typeof raw === "string" ? raw : "");
+        if (!frame) return;
+        setLast(frame);
+        const n = frameToNotification(frame, options.current.text);
+        void raiseLocalNotification(n.title, n.body, n.url, { trayIsNative: options.current.trayIsNative });
+        cb.current?.(frame);
+      };
+    };
+
+    connect();
+    return () => {
+      closed = true;
+      if (retry) clearTimeout(retry);
+      try {
+        ws?.close();
+      } catch {
+        // unmounting
+      }
+    };
+  }, [topicUrl]);
+
+  return { connected, last };
+}

package/src/poll.ts

@@ -0,0 +1,52 @@
+/** One read of the topic's backlog, announcing what is new since a watermark.
+ *
+ *  This has no Expo or React Native imports. background.ts runs it from an OS-scheduled task, and
+ *  an app can run the same pass when it returns to the foreground. */
+import {
+  frameToNotification,
+  newSince,
+  parseBacklog,
+  pollUrlFrom,
+  ZERO_WATERMARK,
+  type NotificationText,
+  type NtfyFrame,
+  type Watermark,
+} from "./proto";
+
+export interface PollOptions {
+  /** the topic URL, for example https://ntfy.example.org/alerts */
+  topicUrl: string;
+  /** the stored position. A number is a time in seconds; null means "never watched". */
+  readMark: () => Promise<Watermark | number | null>;
+  /** store the new position. Called once per pass, after every message was announced. */
+  commitMark?: (mark: Watermark) => Promise<void>;
+  /** show one message, for example with raiseLocalNotification */
+  announce: (n: { title: string; body: string; url?: string }, frame: NtfyFrame) => Promise<void>;
+  /** how a frame reads as a notification */
+  text?: NotificationText;
+  /** backlog window, a Go duration or "all" (default "all") */
+  since?: string;
+  fetch?: typeof fetch;
+}
+
+/** Read the backlog once, announce the new messages oldest first, then commit the watermark.
+ *  Returns how many were announced.
+ *
+ *  The mark is committed after the read, never before. Either order leaves a gap of a few
+ *  milliseconds around the read. Committing after can miss a message published inside it, while
+ *  committing before would show it twice, and the live socket covers the gap anyway. */
+export async function pollTopicOnce(o: PollOptions): Promise<number> {
+  const stored = await o.readMark();
+  const mark: Watermark =
+    stored == null ? ZERO_WATERMARK : typeof stored === "number" ? { time: stored, idsAtTime: [] } : stored;
+  const get = o.fetch ?? fetch;
+  const r = await get(pollUrlFrom(o.topicUrl, o.since));
+  if (!r.ok) throw new Error(`HTTP ${r.status}`);
+  const frames = parseBacklog(await r.text());
+  const next = newSince(frames, mark);
+  for (const f of next.fresh.slice().reverse()) {
+    await o.announce(frameToNotification(f, o.text), f);
+  }
+  await o.commitMark?.(next.mark);
+  return next.fresh.length;
+}

package/src/proto.ts

@@ -0,0 +1,158 @@
+/** The wire logic of subscribing to a self-hosted ntfy topic.
+ *
+ *  Nothing here imports React, Expo or React Native, so it runs and is tested in plain Node. The
+ *  device glue (permissions, local notifications, the socket lifecycle) is in notify.ts. */
+
+/** One frame from ntfy's WebSocket or JSON stream. ntfy sends open, keepalive and message frames.
+ *  Only message frames carry something a person should see. */
+export interface NtfyFrame {
+  id: string;
+  time?: number;
+  event: "open" | "keepalive" | "message" | "poll_request" | string;
+  topic?: string;
+  message?: string;
+  title?: string;
+  priority?: number;
+  tags?: string[];
+  /** ntfy's Click: where the message is about, often a deep link into the app */
+  click?: string;
+  /** ntfy's Attach (a URL) or an uploaded attachment */
+  attach?: string;
+  /** file name of the attachment, when ntfy sent one */
+  filename?: string;
+  /** ntfy's Actions: view (open a URL), http (call an endpoint), broadcast */
+  actions?: NtfyAction[];
+}
+
+export interface NtfyAction {
+  action: "view" | "http" | "broadcast" | string;
+  label: string;
+  url?: string;
+  method?: string;
+  body?: string;
+  headers?: Record<string, string>;
+  clear?: boolean;
+}
+
+/** The topic's backlog URL. `since` is parsed as a Go duration, which has no day unit: "7d" makes
+ *  the server answer 400, while "24h", "all" or a Unix time work. */
+export function pollUrlFrom(topicUrl: string, since = "all"): string {
+  return `${topicUrl.replace(/\/+$/, "")}/json?poll=1&since=${since}`;
+}
+
+/** https://host/topic -> wss://host/topic/ws (and http -> ws). */
+export function wsUrlFrom(topicUrl: string): string {
+  const base = topicUrl.replace(/\/+$/, "");
+  return base.replace(/^http(s?):/, "ws$1:") + "/ws";
+}
+
+/** One raw frame, or null. Only `message` frames are returned (never open or keepalive), and
+ *  invalid JSON gives null, so one bad frame cannot stop a socket loop. */
+export function parseFrame(raw: string): NtfyFrame | null {
+  let f: NtfyFrame;
+  try {
+    f = JSON.parse(raw) as NtfyFrame;
+  } catch {
+    return null;
+  }
+  if (!f || f.event !== "message") return null;
+  return f;
+}
+
+/** ndjson (one frame per line) -> the message frames, newest first. */
+export function parseBacklog(body: string): NtfyFrame[] {
+  return body
+    .split("\n")
+    .map((l) => parseFrame(l))
+    .filter((f): f is NtfyFrame => f !== null)
+    .reverse();
+}
+
+export interface NotificationText {
+  /** title used when the frame has none (default "Notification") */
+  appName?: string;
+  /** body used when the frame has neither a message nor a title */
+  emptyBody?: string;
+  /** a click URL is kept only when it starts with this prefix (for example "myapp://").
+   *  Without a prefix no click URL is kept. A notification is data from the network, and a link
+   *  in it should not be followed unless it points into the app. */
+  linkPrefix?: string;
+}
+
+/** How a message frame should read in the notification tray. */
+export function frameToNotification(
+  f: NtfyFrame,
+  opts: NotificationText = {},
+): { title: string; body: string; url?: string } {
+  const appName = opts.appName ?? "Notification";
+  const title = (f.title && f.title.trim()) || appName;
+  const body = (f.message && f.message.trim()) || f.title || opts.emptyBody || appName;
+  const url = opts.linkPrefix && f.click && f.click.startsWith(opts.linkPrefix) ? f.click : undefined;
+  return url ? { title, body, url } : { title, body };
+}
+
+/** How far through the topic a device has already announced.
+ *
+ *  A timestamp alone is not enough, because ntfy stamps whole seconds and several messages can
+ *  share one. The ids seen at that second are kept too, so none is skipped or shown twice. */
+export interface Watermark {
+  time: number;
+  idsAtTime: string[];
+}
+
+export const ZERO_WATERMARK: Watermark = { time: 0, idsAtTime: [] };
+
+/** The frames not announced yet, and the watermark after them.
+ *
+ *  On a zero watermark nothing is announced and the position is adopted instead. A device that
+ *  never watched has not missed anything, and announcing the topic's whole history on first launch
+ *  would bury the person in old messages. */
+export function newSince(
+  frames: NtfyFrame[],
+  mark: Watermark,
+): { fresh: NtfyFrame[]; mark: Watermark } {
+  const at = (f: NtfyFrame) => f.time ?? 0;
+  if (mark.time === 0 && mark.idsAtTime.length === 0) {
+    const maxTime = frames.reduce((m, f) => Math.max(m, at(f)), 0);
+    return {
+      fresh: [],
+      mark: { time: maxTime, idsAtTime: frames.filter((f) => at(f) === maxTime).map((f) => f.id) },
+    };
+  }
+  const fresh = frames.filter(
+    (f) => at(f) > mark.time || (at(f) === mark.time && !mark.idsAtTime.includes(f.id)),
+  );
+  const maxTime = frames.reduce((m, f) => Math.max(m, at(f)), mark.time);
+  const idsAtMax = frames.filter((f) => at(f) === maxTime).map((f) => f.id);
+  return {
+    fresh,
+    mark: {
+      time: maxTime,
+      idsAtTime: maxTime === mark.time ? [...new Set([...mark.idsAtTime, ...idsAtMax])] : idsAtMax,
+    },
+  };
+}
+
+/** Throws when a topic URL is one a phone cannot reach (empty, invalid, or loopback). A phone
+ *  that is given "localhost" connects to itself and never receives anything. */
+export function assertReachableFromPhone(url: string | undefined): string {
+  let host = "";
+  try {
+    host = new URL(url ?? "").hostname;
+  } catch {
+    host = "";
+  }
+  if (isLoopbackHost(host)) {
+    throw new Error(
+      `ntfy topic URL ${JSON.stringify(url ?? "")} cannot be reached from a phone. ` +
+        "Use an address of the server that the phone can reach (not localhost).",
+    );
+  }
+  return url as string;
+}
+
+export function isLoopbackHost(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+  return h === "" || h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "0.0.0.0"
+    || /^127\.\d+\.\d+\.\d+$/.test(h);
+}