node-red-contrib-ntrip 0.2.2 → 0.2.7

package/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+    - package-ecosystem: 'npm'
+      directory: '/'
+      schedule:
+          interval: 'weekly'
+      open-pull-requests-limit: 5
+      # The following packages are transitive devDependencies pulled in by
+      # `node-red` / `node-red-node-test-helper`. They have known advisories
+      # but no patched version is currently resolvable, so Dependabot's
+      # security-update PRs fail noisily on every retry. Since these packages
+      # are dev-only (not reachable from the published runtime tree of
+      # @gnss/nmea, @gnss/rtcm, ntrip-client), the advisories don't affect
+      # end users. Remove the ignore once upstream ships a fixed version.
+      ignore:
+          - dependency-name: 'picomatch'
+          - dependency-name: 'ip-address'
+          - dependency-name: 'serialize-javascript'
+
+    - package-ecosystem: 'github-actions'
+      directory: '/'
+      schedule:
+          interval: 'monthly'

package/.github/workflows/node.js.yml

@@ -4,28 +4,29 @@
 name: Node.js CI
 
 on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
+    push:
+        branches: ['main']
+    pull_request:
+        branches: ['main']
 
 jobs:
-  build:
+    build:
+        runs-on: ubuntu-latest
 
-    runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                node-version: [18.x, 20.x, 22.x]
+                # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x, 22.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npm ci
-    - run: npm run build --if-present
-    #- run: npm test
+        steps:
+            - uses: actions/checkout@v4
+            - name: Use Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: 'npm'
+            - run: npm ci
+            - run: npm run build --if-present
+            - run: npm run lint
+            - run: npm run format:check
+            - run: npm test

package/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+# Release pipeline.
+#
+# Trigger: push of a version tag matching v* or V* (e.g. v0.2.7, V1.0.0).
+# Stages:
+#   1. test — runs the full lint/format/test matrix on the tagged commit.
+#   2. publish-npm — publishes the package to the npm registry.
+#   3. github-release — creates a GitHub Release with auto-generated notes.
+#
+# Requires the `NPM_TOKEN` secret to be configured in the repository.
+
+name: Release
+
+on:
+    push:
+        tags:
+            - 'v*'
+            - 'V*'
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                node-version: [18.x, 20.x, 22.x]
+        steps:
+            - uses: actions/checkout@v4
+            - name: Use Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: 'npm'
+            - run: npm ci
+            - run: npm run lint
+            - run: npm run format:check
+            - run: npm test
+
+    publish-npm:
+        needs: test
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  registry-url: 'https://registry.npmjs.org/'
+            - run: npm ci
+            - run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+    github-release:
+        needs: publish-npm
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                  tag_name: ${{ github.ref_name }}
+                  name: ${{ github.ref_name }}
+                  generate_release_notes: true

package/.prettierignore

@@ -0,0 +1,20 @@
+# Generated / vendored
+node_modules/
+package-lock.json
+
+# Node-RED flow files — re-formatting would change diff noise without value
+examples/
+
+# Editor UI HTML has Node-RED-specific structural conventions
+# (data-template-name script blocks, x-red script blocks) that Prettier
+# can mangle. Touch only with care.
+ntrip/99-ntrip.html
+
+# Markdown is kept hand-formatted (line-wrapped prose, ASCII diagrams).
+# Re-flowing it would produce a large noisy diff.
+*.md
+doc/
+
+# Editor / agent local state — not checked in
+.claude/
+.vscode/

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+    "trailingComma": "es5",
+    "tabWidth": 4,
+    "semi": true,
+    "singleQuote": true,
+    "bracketSpacing": true,
+    "endOfLine": "auto",
+    "printWidth": 160
+}

package/CHANGELOG.md

@@ -1,6 +1,70 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.2.7]
+### Internal — tooling, tests, docs (no runtime changes)
+- Added a mocha test suite (14 specs across `NmeaDecoder`, `NmeaEncoder`, `RtcmDecoder`) using `node-red-node-test-helper`. Regression specs are tagged so they can be re-run with `mocha -g regression`.
+- Added ESLint (flat config, `@eslint/js` recommended + `eslint-config-prettier`) and Prettier (4-space indent, single quotes, `printWidth 160`).
+- CI now runs `lint` + `format:check` + `test` across Node 18/20/22.
+- New `.github/workflows/release.yml` — push a `v*` or `V*` tag to trigger npm publish + GitHub Release with auto-generated notes.
+- New `.github/dependabot.yml` — weekly npm, monthly github-actions. Ignores `picomatch`, `ip-address`, `serialize-javascript` (transitive devDeps with no resolvable patched version yet) to stop noisy red security-update runs.
+- New architecture documentation tree under `doc/architecture/` (8 chapters + 8 ADRs).
+
+## [0.2.6]
+### Fixed regressions introduced in 0.2.5
+- RTCM and NMEA decoders no longer call `node.error()` on decode failures. Decode failures still go to the second (error) output, but they no longer flood the Node-RED `[error]` log when a binary stream is intentionally piped through the "wrong" decoder (e.g. RTCM bytes through the NMEA decoder — the demo flow ships with this wiring).
+- NMEA decoder error output now preserves the original payload on `input` (a `Buffer` if a `Buffer` was supplied) and exposes the utf8 string form as `inputString`, matching pre-0.2.5 behavior.
+
+### Documentation
+- Completed the per-node help text in the Node-RED info sidebar for all four nodes (`NtripClient`, `RtcmDecoder`, `NmeaDecoder`, `NmeaEncoder`) — configuration parameters, input/output shapes, status legend.
+- README updated: Requirements section (Node.js >= 18), corrected NMEA decoder output schema (`nmeaMessage`, not `message`), new NMEA Encoder section with the full list of supported `messageType` values, a "Notes on usage" section covering the common gotchas (two-output design, coordinate gating, dynamic `setXYZ` injection, pass-through interleaving, plaintext transport), and a number of typo fixes.
+
+## [0.2.5]
+### Fixed NTRIP client node
+- Unsupported `mode` no longer crashes the node with `client is undefined`; it now logs an error and stops cleanly.
+- Handshake detection (`ICY 200 OK`, `ICY 406`, `SOURCETABLE 200 OK`) is now only checked while the connection is not yet established, and any RTCM bytes that arrive in the same TCP segment as the `ICY 200 OK` reply are now forwarded instead of dropped.
+- Coordinate guard changed from `x && y && z` to `not all zero`, so coordinates on an axis (e.g. equator) are no longer silently dropped. Non-finite values are rejected.
+- Separate Rx/Tx counters; handshake replies no longer inflate the inbound message count.
+- `host` is validated as a non-empty trimmed string; `interval` is coerced to an integer.
+- `AggregateError` reference is now guarded by a `typeof` check.
+- `client.removeAllListeners()` is called on node close to prevent listener leaks across reconnects.
+- Status badge no longer passes raw Error objects where a string is expected.
+- Removed pointless `async` on the input handler.
+
+### Fixed RTCM decoder node
+- Frames that straddle TCP packet boundaries are now buffered across input events instead of being dropped on a decode error.
+- Added a zero-length / non-positive-length guard to prevent a potential infinite loop.
+- Decode failures now propagate to `node.error` so Catch nodes can react.
+
+### Fixed NMEA decoder node
+- A single chunk containing multiple `\r\n`-delimited NMEA sentences is now decoded sentence by sentence (previously only the first sentence was parsed).
+- Non-string / non-Buffer payloads are routed to the error output instead of crashing.
+- Decode failures now propagate to `node.error` so Catch nodes can react.
+
+### Fixed NTRIP client library wrapper
+- Rejects CR/LF in `mountpoint`, `username`, and `password` to prevent handshake header injection.
+- Fixed `'socket timeouted'` typo in timeout error message.
+
+### Fixed editor UI
+- Password field is now rendered with `type="password"` instead of `type="text"`.
+- `host` and `mountpoint` are validated as non-empty strings in the configuration dialog.
+
+### Other
+- Bumped `engines.node` from `>=7.6.0` to `>=18.0.0` to match the CI matrix and the actual runtime requirements (`AggregateError`, optional chaining, etc.).
+
+## [0.2.4]
+### Fixed NMEA encoder node
+- Restored `NmeaMessage` instance passthrough (the `instanceof` check was previously inspecting `input.prototype` and always evaluated to false).
+- Replaced unguarded property access with a payload validation guard so missing `nmeaMessage`/`messageType` is routed to the error output instead of throwing.
+- Fixed `ReferenceError` in the catch and invalid-input branches that referenced an out-of-scope `input` variable.
+- Unknown `messageType` values are now routed to the error output instead of silently emitting `nmeaMessage: undefined` on the success output.
+- `case 'Object'` renamed to `case 'OBJECT'` (the preceding `toUpperCase()` made the original case unreachable).
+- Status badge now turns red when a message fails to encode.
+- `messageType` is coerced to a string before `toUpperCase()` to tolerate non-string inputs.
+
+## [0.2.3]
+### Added NMEA encoder node - [#13](https://github.com/windkh/node-red-contrib-ntrip/issues/13)
+
 ## [0.2.2]
 ### Added documentation - [#3](https://github.com/windkh/node-red-contrib-ntrip/issues/3)
 

package/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+`node-red-contrib-ntrip` is a Node-RED contribution package providing four GNSS-related nodes: an NTRIP client (download/upload), an RTCM decoder, an NMEA decoder, and an NMEA encoder. It is published to npm and consumed by users via Node-RED's palette manager — there is no application entry point of its own. Runtime target is Node.js >= 7.6 (CI matrix: 18.x, 20.x, 22.x).
+
+## Commands
+
+This package has no build step. Linting (ESLint flat config) and formatting (Prettier) are wired in:
+
+```bash
+npm test                                  # run all specs (mocha + node-red-node-test-helper)
+npm run lint                              # eslint, treats warnings as warnings
+npm run lint:fix                          # eslint --fix
+npm run format                            # prettier --write .
+npm run format:check                      # prettier --check . (used in CI)
+
+npx mocha test/nmea-decoder.spec.js       # run one spec file
+npx mocha test/**/*.spec.js -g 'regression'  # run only regression specs
+```
+
+CI runs `npm ci`, `npm run build --if-present`, `npm run lint`, `npm run format:check`, then `npm test` across Node 18/20/22 (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)).
+
+Prettier settings live in [.prettierrc.json](.prettierrc.json) (4-space indent, single quotes, trailing-commas-es5, printWidth 160). [.prettierignore](.prettierignore) skips `examples/` (Node-RED flow files), `ntrip/99-ntrip.html` (Node-RED-specific structural conventions), markdown, and `doc/`. ESLint config is [eslint.config.js](eslint.config.js) (flat config, `@eslint/js` recommended + `eslint-config-prettier`).
+
+To exercise changes manually, install this directory into a local Node-RED:
+
+```bash
+cd <node-red userDir, e.g. ~/.node-red>
+npm install <path-to-this-repo>
+```
+
+Then start Node-RED and import a flow from [examples/](examples/) (e.g. `ntripclient.json`, `sapos.json`, `upload.json`, `tcp.json`, `nmea-decode.json`, `nmea-encode.json`) to drive the nodes against a real NTRIP caster.
+
+## Architecture
+
+Node-RED contribution packages follow a strict structure that this repo conforms to:
+
+- [package.json](package.json) `node-red.nodes` points at a single registration file [ntrip/99-ntrip.js](ntrip/99-ntrip.js).
+- That registration file is the only entry Node-RED loads. It `require`s each node implementation from [ntrip/nodes/](ntrip/nodes/) and calls `RED.nodes.registerType(...)` for each.
+- Each Node-RED node is a pair: a `.js` runtime file in [ntrip/nodes/](ntrip/nodes/), plus the editor UI (HTML + inline `<script>`/`<template>`) co-located in [ntrip/99-ntrip.html](ntrip/99-ntrip.html). All four nodes' editor definitions share this single HTML file.
+- Credentials (NTRIP username/password) are declared in both the registration call ([ntrip/99-ntrip.js:13-16](ntrip/99-ntrip.js#L13-L16)) and the HTML `credentials` block — they must stay in sync, otherwise Node-RED will not persist them.
+
+Node responsibilities:
+
+- **NtripClient** ([ntrip/nodes/ntrip-client-node.js](ntrip/nodes/ntrip-client-node.js)) — wraps [ntrip/lib/ntrip-client.js](ntrip/lib/ntrip-client.js), which extends the upstream `ntrip-client` package to add an *uploader* variant. The uploader's `_connect()` switches the handshake string by `authmode` (`legacy`, `hybrid`, `ntripv1`, `ntripv2`) — see [ntrip/lib/ntrip-client.js:45-66](ntrip/lib/ntrip-client.js#L45-L66). Special inbound bytes are intercepted and turned into status/error rather than forwarded: `ICY 200 OK` (connected), `ICY 406` (rejected), `SOURCETABLE 200 OK` (mountpoint missing). When `msg.payload` is an `Array`, it is treated as an `[x, y, z]` coordinate triple and forwarded via `client.setXYZ(...)` (used by the Sapos flow to seed a GGA sentence); any other payload is written to the caster. `passthrough` controls whether written data is also re-emitted on the output.
+- **RtcmDecoder** ([ntrip/nodes/rtcm-decoder-node.js](ntrip/nodes/rtcm-decoder-node.js)) — loops `RtcmTransport.decode(buffer)` (from `@gnss/rtcm`), slicing the buffer by the returned `length` until empty, emitting one message per decoded RTCM frame. Two outputs: `[ok, error]`.
+- **NmeaDecoder** ([ntrip/nodes/nmea-decoder-node.js](ntrip/nodes/nmea-decoder-node.js)) — decodes via `NmeaTransport.decode` from `@gnss/nmea`. Accepts either a Buffer or a string, and either `msg.payload` directly or `msg.payload.nmeaMessage`. Two outputs: `[ok, error]`.
+- **NmeaEncoder** ([ntrip/nodes/nmea-encoder-node.js](ntrip/nodes/nmea-encoder-node.js)) — symmetric inverse, with a large `switch (messageType)` that maps NMEA sentence types (`GGA`, `RMC`, `GSV`, ...) to the corresponding `NmeaMessage*.construct(...)` factory before calling `NmeaTransport.encode`. When adding support for a new NMEA sentence type, add both the import at the top and the matching `case` in the switch.
+
+## Tests
+
+Specs live in [test/](test/) — one file per node. Each uses `node-red-node-test-helper` to load the registration file [ntrip/99-ntrip.js](ntrip/99-ntrip.js), wires the node under test to two `helper` sink nodes (one per output port), and asserts on `msg.payload` shape.
+
+Two patterns to reuse when adding tests:
+
+- **`regression:` tag in the test name** — for any spec that locks in a previously-shipped bug. Future maintainers can run `mocha -g regression` to verify the fix is still in place.
+- **`node.error` spy** — replace `n1.error` with a wrapper that flips a boolean, then assert the boolean stayed false. Used to prevent regressing the "decoder floods the Node-RED error log when fed mismatched binary" bug.
+
+Known-good test fixtures embedded in the specs:
+
+- NMEA: `$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47`, `$GPGLL,4916.45,N,12311.12,W,225444,A,*1D`
+- RTCM: a real 25-byte type 1005 frame as hex `D300133ED7D30202980EDEEF34B4BD62AC0941986F33360B98`
+
+NTRIP client integration tests are not yet written; the recommended approach is a fake TCP server via `net.createServer` that returns `"ICY 200 OK\r\n\r\n" + rtcmBytes` to exercise the handshake-state machine.
+
+## Conventions worth knowing
+
+- All four nodes follow the same pattern: increment a `messagesReceived`/`invalidMessagesReceived` counter and call `node.status({...})` after each input, set `node.status({})` on `close`. Keep this consistent when adding nodes.
+- The package version printed at load time is read from `package.json` at [ntrip/99-ntrip.js:8-9](ntrip/99-ntrip.js#L8-L9) — bumping `version` in package.json is the only source of truth.
+- Releases are tracked in [CHANGELOG.md](CHANGELOG.md) using "Keep a Changelog" headings; each entry typically references the GitHub issue number that motivated it.

package/README.md

@@ -30,6 +30,10 @@ Or run the following command in the root directory of your Node-RED installation
 
     npm install node-red-contrib-ntrip --save
 
+# Requirements
+- Node.js **>= 18.0.0** (uses `AggregateError` and other recent runtime features).
+- Node-RED **>= 0.1.0**.
+
 # Dependencies
 This package depends on the following libraries
 - [@gnss/nmea](https://github.com/node-ntrip/nmea)
@@ -93,58 +97,181 @@ You need to provide these additional properties:
 
 ### Authentication Modes
 #### Legacy
-This mode initiates the uploading to a mountpoint using plan text.
+This mode initiates the upload to a mountpoint using plain text.
 ```javascript
 SOURCE ${mountpoint}\r\n\r\n
 ```
-or with password and unsername
+or with password and username
 ```javascript
 SOURCE ${password} /${mountpoint}\r\nSource-Agent: NTRIP ${username}\r\n\r\n
 ```
 
 #### Legacy (Basic Auth)
-This hybrid mode initiates the uploading to a mountpoint using plan text and Basic Auth.
+This hybrid mode initiates the upload to a mountpoint using plain text and Basic Auth.
 ```javascript
 SOURCE ${mountpoint}\r\nAuthorization: Basic ${authorization}\r\n\r\n
 ```
 
 #### NTRIP V1
-This mode initiates the uploading to a mountpoint using HTTP with Basic Auth.
+This mode initiates the upload to a mountpoint using HTTP with Basic Auth.
 ```javascript
 POST /${mountpoint} HTTP/1.0\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nContent-Type: gnss/data\r\n\r\n
 ```
 
 #### NTRIP V2
-THis mode is equal to NTRIP V1 with some more data.
+This mode is equal to NTRIP V1 with some more data.
 ```javascript
 POST /${mountpoint} HTTP/1.1\r\nHost: ${host}:${port}\r\nUser-Agent: NTRIP ${userAgent}\r\nAuthorization: Basic ${authorization}\r\nNtrip-Version: Ntrip/2.0\r\nContent-Type: gnss/data\r\nConnection: keep-alive\r\n\r\n
 ```
 
 # RTCM Decoder Node
-This node accepts binary RTCM data. The node accepts either a single or multiple RTCN messages.
-The converted messages are sent one by one to the output in the following format.
+This node accepts binary RTCM data. A single input message may contain a single
+RTCM frame or several concatenated frames; each decoded frame is emitted as its
+own output message. Bytes left over from a partial frame at the end of an input
+chunk are buffered internally and joined with the next chunk, so frames that
+straddle TCP packet boundaries are reassembled correctly.
+
+The node has **two outputs**: decoded frames go to the first output, decode
+failures to the second.
+
+Successful output:
+```javascript
+msg.payload =
+{
+    rtcm,         // RTCM message number (e.g. 1005, 1077)
+    messageType,  // a readable name (e.g. "Stationary", "Msm7Gps")
+    message,      // the decoded message object with all fields
+    input,        // the raw bytes of this frame
+};
+```
+
+Error output:
 ```javascript
-msg.payload = 
+msg.payload =
 {
-    rtcm, // RTCm message number
-    messageType, // a string indicating a readyble RTCM message name
-    message, // a structure containing all decoded data
-    input, // the raw input message
+    error,        // the Error thrown by the decoder
+    input,        // the buffer at the point of failure
+    inputString,  // String(input) for logging
 };
 ```
 
 # NMEA Decoder Node
-This node accepts binary NMEA data. The node accepts either a single or multiple NMEA messages.
-The converted messages are sent one by one to the output in the following format.
+This node accepts NMEA 0183 sentences as a string or `Buffer`. Multiple
+sentences in a single input (delimited by `\r\n`) are split and decoded
+individually; each decoded sentence is emitted as its own output message.
+
+The node has **two outputs**: decoded sentences go to the first, failures to
+the second.
+
+Successful output:
+```javascript
+msg.payload =
+{
+    messageType,  // sentence type in upper case (e.g. "GGA", "RMC", "GSV")
+    nmeaMessage,  // the decoded sentence object with all fields
+    input,        // the raw sentence as it was parsed
+};
+```
+
+Error output:
 ```javascript
-msg.payload = 
+msg.payload =
 {
-    messageType, // a string indicating a readyble RTCM message name
-    message, // a structure containing all decoded data
-    input, // the raw input message
+    error,        // the Error thrown by the decoder
+    input,        // the original payload as supplied (Buffer if a Buffer was given)
+    inputString,  // the utf8 string form of input
 };
 ```
 
+Errors are routed to the second output only — the node does not call
+`node.error()` for per-sentence decode failures, so wiring binary RTCM through
+the NMEA decoder (as the demo flow does) will not flood the Node-RED log.
+
+# NMEA Encoder Node
+This node is the inverse of the NMEA Decoder. It encodes a NMEA sentence object
+back to its textual form using `@gnss/nmea`. Useful for round-tripping or for
+synthesising sentences (e.g. building a `GGA` fix to feed into an NTRIP
+uploader).
+
+The node has **two outputs**: encoded sentences go to the first, failures to
+the second.
+
+Input shape:
+```javascript
+msg.payload =
+{
+    messageType, // "GGA", "RMC", "VTG", ... (case-insensitive)
+    nmeaMessage, // either a plain field object matching the sentence schema,
+                 // or an already-constructed NmeaMessage instance
+};
+```
+
+Supported `messageType` values: `DTM`, `GBS`, `GGA`, `GLL`, `GNS`, `GRS`,
+`GSA`, `GST`, `GSV`, `RMC`, `THS`, `TXT`, `VHW`, `VLW`, `VPW`, `VTG`, `ZDA`,
+plus `OBJECT` for the generic `NmeaMessageUnknown` form.
+
+Successful output:
+```javascript
+msg.payload =
+{
+    nmeaMessage,  // the encoded NMEA sentence string (with $ prefix and checksum)
+    messageType,  // echoed back as supplied
+    input,        // the original input object
+};
+```
+
+Unknown `messageType` values, missing input fields, and encoder exceptions all
+surface on the error output.
+
+See also example flow [**NMEA encode flow**](examples/nmea-encode.json).
+
+# Notes on usage
+
+A few things that are easy to get wrong:
+
+- **Two outputs on the decoders and the encoder.** The first output carries
+  successful messages, the second carries decode/encode failures. If you only
+  wire the first output you will silently drop errors.
+- **NTRIP Client: handshake handling.** On the first reply from a caster the
+  node intercepts the `ICY 200 OK`, `ICY 406`, or `SOURCETABLE 200 OK` line and
+  uses it to set its status badge (`connecting…` → connected / rejected /
+  missing mountpoint). RTCM bytes that happen to share the same TCP segment as
+  the `ICY 200 OK` reply are forwarded; later packets are forwarded verbatim.
+- **NTRIP Client: coordinates.** The `X`/`Y`/`Z` form fields are an ECEF
+  coordinate triple used to synthesise a `GGA` sentence for the caster. The
+  node only sends a `GGA` if the triple is finite **and not all zero** — so
+  `(0, 0, 0)` is the sentinel for "no location, do not send GGA". Coordinates
+  on a single axis (e.g. `(x, 0, 0)`) are still sent.
+- **NTRIP Client: dynamic location updates.** To stream a moving position into
+  the caster, inject `msg.payload = [x, y, z]` (an Array, not a Buffer) into
+  the NTRIP Client. Arrays are routed to `client.setXYZ()` and update the
+  position used by the periodic `GGA`; non-array payloads are written verbatim
+  to the caster.
+- **NTRIP Client: upload pass-through.** With *Pass through data* enabled the
+  bytes written to the caster are *also* re-emitted on the node output,
+  interleaved with bytes received from the caster. Downstream nodes will see
+  both streams on the same wire — distinguish them with a tag in a function
+  node if you need to.
+- **NTRIP Client: status badge.** `Rx N Tx M` counts inbound and outbound
+  messages separately. Handshake replies do not bump the inbound count.
+- **NTRIP Client: CR/LF in credentials.** `mountpoint`, `username`, and
+  `password` are interpolated into the handshake string. CR/LF in these fields
+  is rejected at startup to prevent header injection.
+- **NMEA Encoder input shape.** The encoder expects `msg.payload` to be an
+  object with `messageType` and `nmeaMessage` properties — not a NMEA string.
+  To re-encode the output of the NMEA Decoder you can pipe it straight in;
+  to build a sentence from scratch use a function node:
+  ```javascript
+  msg.payload = {
+      messageType: "GGA",
+      nmeaMessage: { /* GGA field object */ }
+  };
+  return msg;
+  ```
+- **Plaintext transport.** NTRIP traffic is unencrypted TCP. Credentials in
+  upload mode use Basic Auth and are observable on the wire. NTRIP-over-TLS
+  is not supported by this package.
+
 # Examples 
 Examples are stored in the examples folder an can be imported from within node-red's sidebar via import.
 

package/doc/architecture/README.md

@@ -0,0 +1,19 @@
+# Architecture documentation
+
+Architectural analysis of `node-red-contrib-ntrip`. Start with
+[overview.md](overview.md) for a high-level orientation.
+
+| Chapter | Read when |
+|---------|-----------|
+| [Overview](overview.md) | First contact — what this package is and how the pieces fit. |
+| [Structural Design](structural-design.md) | You need to find or change a specific file / module. |
+| [Behavioural Design](behavioural-design.md) | You're changing runtime behaviour — state machines, error paths, lifecycle hooks. |
+| [Architecture Decisions](architecture-decisions.md) | You're about to revisit a load-bearing decision. Individual ADRs live in [adr/](adr/). |
+| [Errors and Weaknesses](errors-and-weaknesses.md) | You're triaging a bug report — check whether it's already known. |
+| [Refactoring Recommendations](refactoring-recommendations.md) | You have spare cycles and want to invest them in code health. |
+| [Future Improvements](future-improvements.md) | You're planning the next minor release. |
+| [Statistics](statistics.md) | You want a quantitative read on size, test coverage, and quality. |
+
+This documentation lives alongside the code and is versioned with it. When
+you change behaviour that contradicts a statement here, update the doc in the
+same commit.

package/doc/architecture/adr/0001-single-registration-file.md

@@ -0,0 +1,64 @@
+# ADR-0001: Single registration file for all nodes
+
+## Status
+
+Accepted (original design).
+
+## Context
+
+Node-RED loads a contribution package via the `node-red.nodes` map in
+`package.json`. That map can point at one or many entry files: each entry file
+is run once at startup and is expected to call `RED.nodes.registerType(...)`
+for the node types it owns.
+
+Two viable patterns exist:
+
+- **One entry per node.** `package.json` lists four entries; each file
+  registers exactly one type. Pro: a node's entire definition is in one place.
+  Con: four entries to keep in sync, four loader invocations.
+- **One entry for the whole package.** `package.json` lists one entry; that
+  file `require`s each node implementation and registers them all. Pro:
+  centralised; package version logging happens once.
+
+## Decision
+
+Use a single registration entry file: [ntrip/99-ntrip.js](../../../ntrip/99-ntrip.js).
+The `99-` prefix is a convention seen across published `node-red-contrib-*`
+packages — it sorts late alphabetically, making the file easy to find.
+
+Each node implementation lives under [ntrip/nodes/](../../../ntrip/nodes/) and
+exports a factory function that the registration file imports.
+
+The four node types' editor UIs share one HTML file
+([ntrip/99-ntrip.html](../../../ntrip/99-ntrip.html)) — Node-RED's loader picks
+up the `.html` next to the registered `.js`.
+
+## Consequences
+
+**Positive**
+
+- One place to read the full inventory of nodes.
+- Package version logging happens exactly once at load time (read from
+  `package.json`).
+- New nodes are added by a one-line `require` + one-line `registerType` in the
+  entry file, plus a new file under `nodes/` and a new `<script>` block in the
+  HTML.
+
+**Negative**
+
+- The HTML file is large (~470 lines) because it must hold form templates and
+  help text for all four nodes. Adding a fifth node means appending another
+  ~100 lines to the same file.
+- A typo in `registerType` names (e.g. `NtripClinet` instead of `NtripClient`)
+  is silently fatal — the JS side and HTML side must agree exactly.
+
+**Trade-offs**
+
+- Choosing the single-entry pattern prioritises *package coherence* over
+  *per-node isolation*. If the package ever grows to a dozen+ nodes, splitting
+  would become attractive.
+
+## Related
+
+- Code: [ntrip/99-ntrip.js](../../../ntrip/99-ntrip.js), [ntrip/99-ntrip.html](../../../ntrip/99-ntrip.html)
+- Configured via: [package.json](../../../package.json) `node-red.nodes`