@sailingnaturali/signalk-ntfy-relay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Clark
+
+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,56 @@
+# @sailingnaturali/signalk-ntfy-relay
+
+Relay [Signal K](https://signalk.org) notifications (alarms) to an
+[ntfy](https://ntfy.sh) topic — so a man-overboard, depth/wind/battery alarm, or
+any other notification reaches your phone, independent of any chartplotter or
+shoreside server.
+
+**Zero runtime dependencies.** Notifications are read in-process via the Signal K
+subscription manager; ntfy is reached with Node's built-in `https`.
+
+## How it works
+
+- Subscribes to `notifications.*` and **edge-triggers**: it pushes once when an
+  alarm becomes active, not repeatedly while it persists.
+- Forwards notifications at or above a configurable severity (`warn` by default).
+- Maps Signal K severity to ntfy **priority** and **tags**:
+
+  | Signal K state | ntfy priority | tag |
+  |----------------|---------------|-----|
+  | `emergency` | 5 (max) | 🆘 `sos` |
+  | `alarm` | 4 (high) | 🚨 `rotating_light` |
+  | `warn` | 3 (default) | ⚠️ `warning` |
+  | `alert` | 2 (low) | ℹ️ `information_source` |
+  | cleared (`normal`) | 1 (min) | ✅ `white_check_mark` |
+
+- Appends the vessel position to the message when known.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| `server` | `https://ntfy.sh` | Set to your self-hosted ntfy server |
+| `topic` | *(required)* | The ntfy topic to publish to |
+| `token` | *(empty)* | `Authorization: Bearer` token (self-hosted/ACL) |
+| `minState` | `warn` | Minimum severity to forward |
+| `notifyOnClear` | `true` | Also send a message when an alarm resolves |
+| `includePosition` | `true` | Append `lat, lon` to the message |
+
+## Setup
+
+1. Install from the Signal K app store (category: Notifications), or drop this
+   folder into the server's `node_modules`.
+2. Pick a hard-to-guess topic (anyone who knows a public-server topic can read it),
+   e.g. `naturali-alarms-7f3a`.
+3. Install the ntfy app on your phone and subscribe to that topic.
+4. Configure the plugin with the topic and enable it.
+
+Test it by raising a notification, e.g. a man-overboard via the Signal K v2 API:
+
+```bash
+curl -X POST http://localhost:3000/signalk/v2/api/notifications/mob
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,204 @@
+/*
+ * signalk-ntfy-relay — relay SignalK notifications to ntfy.
+ *
+ * Watches notifications.* in-process, edge-triggers on state change, and POSTs
+ * active alarms (>= a configurable severity) to an ntfy topic via Node's
+ * built-in https/http. Zero runtime dependencies, so it mounts read-only.
+ *
+ * The factory takes an optional second arg `deps` so tests can inject a fake
+ * `send`; SignalK calls it with just (app), using the real network sender.
+ */
+const SEVERITY = { nominal: 0, normal: 1, alert: 2, warn: 3, alarm: 4, emergency: 5 };
+const INACTIVE = new Set(['nominal', 'normal']);
+
+function rank(state) {
+  return state in SEVERITY ? SEVERITY[state] : -1;
+}
+function isActive(state) {
+  return state != null && !INACTIVE.has(state);
+}
+function shouldForward(state, minState) {
+  return isActive(state) && rank(state) >= rank(minState);
+}
+
+const PRIORITY = { emergency: '5', alarm: '4', warn: '3', alert: '2' };
+const TAGS = {
+  emergency: 'sos',
+  alarm: 'rotating_light',
+  warn: 'warning',
+  alert: 'information_source',
+};
+
+// Inactive (cleared) states get the min-priority "resolved" treatment.
+function priorityFor(state) {
+  return isActive(state) ? (PRIORITY[state] || '3') : '1';
+}
+function tagsFor(state) {
+  return isActive(state) ? (TAGS[state] || 'warning') : 'white_check_mark';
+}
+
+// Compose the ntfy HTTP request (pure — no I/O). Returns {url, headers, body}.
+function buildRequest(n, position, options) {
+  const base = (options.server || 'https://ntfy.sh').replace(/\/+$/, '');
+  // Encode the topic so a stray space/slash can't break the path or smuggle in
+  // extra path segments (ntfy topics are [A-Za-z0-9_-], but be defensive).
+  const url = `${base}/${encodeURIComponent(options.topic)}`;
+  const headers = {
+    'Content-Type': 'text/plain; charset=utf-8',
+    Title: `${String(n.state).toUpperCase()}: ${n.path}`,
+    Priority: priorityFor(n.state),
+    Tags: tagsFor(n.state),
+  };
+  if (options.token) headers.Authorization = `Bearer ${options.token}`;
+  let body = n.message || n.path;
+  if (
+    options.includePosition !== false &&
+    position &&
+    typeof position.latitude === 'number' &&
+    typeof position.longitude === 'number'
+  ) {
+    body += `\n@ ${position.latitude.toFixed(5)}, ${position.longitude.toFixed(5)}`;
+  }
+  return { url, headers, body };
+}
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+// The only I/O boundary. Fire-and-forget POST to ntfy; never throws — any
+// failure is logged via app.error so one bad push can't stall other alarms.
+function defaultSend({ url, headers, body }, app) {
+  try {
+    const u = new URL(url);
+    const lib = u.protocol === 'http:' ? http : https;
+    const req = lib.request(u, { method: 'POST', headers }, (res) => {
+      res.resume(); // drain
+      if (res.statusCode >= 300) app.error(`ntfy responded ${res.statusCode}`);
+    });
+    req.on('error', (e) => app.error(`ntfy post failed: ${e.message}`));
+    req.setTimeout(5000, () => req.destroy(new Error('ntfy timeout')));
+    req.write(body);
+    req.end();
+  } catch (e) {
+    app.error(`ntfy send error: ${e.message}`);
+  }
+}
+
+module.exports = function (app, deps) {
+  const send = (deps && deps.send) || defaultSend;
+  const plugin = {
+    id: 'signalk-ntfy-relay',
+    name: 'ntfy notification relay',
+    description: 'Relay SignalK notifications (alarms) to an ntfy topic.',
+  };
+
+  plugin.schema = {
+    type: 'object',
+    required: ['topic'],
+    properties: {
+      server: {
+        type: 'string',
+        title: 'ntfy server base URL',
+        default: 'https://ntfy.sh',
+      },
+      topic: {
+        type: 'string',
+        title: 'ntfy topic to publish alarms to',
+      },
+      token: {
+        type: 'string',
+        title: 'Access token (optional, for self-hosted/ACL servers)',
+        default: '',
+      },
+      minState: {
+        type: 'string',
+        title: 'Minimum severity to forward',
+        enum: ['alert', 'warn', 'alarm', 'emergency'],
+        default: 'warn',
+      },
+      notifyOnClear: {
+        type: 'boolean',
+        title: 'Send a message when an alarm clears',
+        default: true,
+      },
+      includePosition: {
+        type: 'boolean',
+        title: 'Append vessel position to the message',
+        default: true,
+      },
+    },
+  };
+
+  let unsubscribes = [];
+  let lastState = new Map();
+
+  function position() {
+    const node = app.getSelfPath('navigation.position');
+    if (node == null) return undefined;
+    const v = typeof node === 'object' && 'value' in node ? node.value : node;
+    return v && typeof v.latitude === 'number' ? v : undefined;
+  }
+
+  function onDelta(delta, options) {
+    (delta.updates || []).forEach((u) =>
+      (u.values || []).forEach((v) => {
+        if (!v.path || !v.path.startsWith('notifications.')) return;
+        const state = v.value && v.value.state;
+        const path = v.path.slice('notifications.'.length);
+        const prev = lastState.get(path);
+        if (state === prev) return; // edge-trigger: only act on change
+        lastState.set(path, state);
+        const min = options.minState || 'warn';
+        const message = (v.value && v.value.message) || undefined;
+        if (shouldForward(state, min)) {
+          send(buildRequest({ path, state, message }, position(), options), app);
+        } else if (
+          !isActive(state) &&
+          isActive(prev) &&
+          options.notifyOnClear !== false
+        ) {
+          send(
+            buildRequest({ path, state: state || 'normal', message }, position(), options),
+            app
+          );
+        }
+      })
+    );
+  }
+
+  plugin.start = function (options) {
+    options = options || {};
+    lastState = new Map();
+    if (!options.topic) {
+      app.error('signalk-ntfy-relay: no ntfy topic configured — idling');
+      return;
+    }
+    app.subscriptionmanager.subscribe(
+      {
+        context: 'vessels.self',
+        subscribe: [{ path: 'notifications.*', policy: 'instant' }],
+      },
+      unsubscribes,
+      (err) => app.error(err),
+      (delta) => {
+        try {
+          onDelta(delta, options);
+        } catch (e) {
+          app.error(`signalk-ntfy-relay: ${e.message}`);
+        }
+      }
+    );
+  };
+
+  plugin.stop = function () {
+    unsubscribes.forEach((f) => f());
+    unsubscribes = [];
+    lastState = new Map();
+  };
+
+  return plugin;
+};
+
+// Pure helpers, hung off the factory for unit tests.
+module.exports._internal = { rank, isActive, shouldForward, priorityFor, tagsFor, buildRequest };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sailingnaturali/signalk-ntfy-relay",
+  "version": "0.1.0",
+  "description": "Relay SignalK notifications (alarms) to an ntfy topic — zero dependencies, edge-triggered, severity-aware.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-category-notifications",
+    "ntfy",
+    "notifications",
+    "alarm",
+    "marine"
+  ],
+  "author": "Bryan Clark",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailingnaturali/signalk-ntfy-relay.git"
+  },
+  "homepage": "https://github.com/sailingnaturali/signalk-ntfy-relay#readme",
+  "bugs": {
+    "url": "https://github.com/sailingnaturali/signalk-ntfy-relay/issues"
+  },
+  "files": [
+    "index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}