node-red-contrib-tdn-eventsub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen
+
+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,114 @@
+# node-red-contrib-tdn-eventsub
+
+Node-RED nodes for an access-control **REST Server API**.
+
+| Node | What it does | Mode |
+|---|---|---|
+| `get access groups` | Downloads all access groups, stores to global context | request/reply |
+| `get cardholders` | Downloads all cardholders, stores to global context | request/reply |
+| `get items` | Downloads all items (optionally filtered by type/division), stores to global context | request/reply |
+| `item status` | Subscribes to status of one or more item (source) ids and keeps waiting for updates indefinitely | continuous |
+
+All share one **REST server** config node: URL/host, port (default 8904), API key, optional auth scheme, optional server certificate fingerprint, optional client certificate.
+
+Every node has a trigger input and **three outputs**:
+
+1. **Response** – full server response in `msg`
+2. **Status** – state changes (`msg.payload.state`, `text`, `time`, node id/name/type) for wiring to a shared log/dashboard
+3. **Error** – `msg.payload.message`, `statusCode`, `body`, `url`, `code`
+
+No runtime dependencies. Node 16+, Node-RED 3+.
+
+## Install
+
+```sh
+cd ~/.node-red
+npm install /path/to/node-red-contrib-tdn-eventsub      # or the .tgz
+```
+
+Restart Node-RED. Nodes appear under **TDN REST**. Import the example via *Import → Examples → node-red-contrib-tdn-eventsub*.
+
+## Server config
+
+| Field | Notes |
+|---|---|
+| URL / host | `rest-server`, `192.168.1.10` or `https://rest-server`. `/api` path assumed. |
+| Port | Default `8904`. |
+| API key | Stored as a Node-RED credential; treated as opaque. |
+| Auth scheme | Blank (default): `Authorization: Basic base64(":" + key)`, accepted by server v9.0+. For older servers enter the API-key scheme token from your server's REST API docs; the key is then sent as `Authorization: <scheme> <key>`. |
+| Cert fingerprint | Optional. SHA-256 (64 hex) or SHA-1 (40 hex) of the **server** certificate, colons optional. When set, the server's self-signed cert is accepted only if it matches; the check runs before any request is written, so the key is never sent to an impostor. A mismatch error prints the actual fingerprint. |
+| Verify server certificate | Normal CA check when no fingerprint is set. |
+| Force links onto this host:port | The server builds `href`s from its own machine name. With this on, followed links keep path + query but use your configured host/port. With it off, a link that would downgrade `https` to `http` is refused. |
+| Client cert / key / PFX | Only if the REST Client item on the server has a thumbprint (pinned client certificate). |
+
+Get the server fingerprint with:
+
+```sh
+openssl s_client -connect rest-server:8904 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256
+```
+
+## List nodes (access groups / cardholders / items)
+
+Discovers the URL from `GET /api` (`features.accessGroups.accessGroups`, `features.cardholders.cardholders`, `features.items.items`), requests with `sort=id&top=1000`, and follows `next.href` until done.
+
+**Output 1**
+
+```js
+msg.payload  = { results: [...all pages merged], count, pageCount }
+msg.pages    = [ raw page 1, raw page 2, ... ]   // unmodified server bodies (toggle)
+msg.request  = { href, params }
+msg.contextKey
+```
+
+**Global context**: `global.<key>` = results array, `global.<key>_updated` = ISO time. Defaults: `rest_accessGroups`, `rest_cardholders`, `rest_items`. Any context store can be picked.
+
+**Per-message overrides**: `msg.query` (object or `"a=1&b=2"`), `msg.fields`, `msg.top`, `msg.maxPages`, `msg.contextKey`.
+
+Useful settings: cardholders `fields=defaults,cards,accessGroups`; items `query=type=11` (use the item types list to find ids). A trigger while a download is running is ignored and reported as `busy` on the status output.
+
+## Item status node
+
+Implements the REST Server status-subscription loop:
+
+1. `POST features.items.updates.href` with `{"itemIds":[...]}` → current status of every item (output, `phase:"subscribe"`)
+2. `GET next.href` – update-wait (long poll, server returns after ~50 s if nothing changes)
+3. Updates arrive → output (`phase:"update"`), then a new update-wait
+4. Update-wait times out (empty `updates`) → another update-wait (optionally output with `phase:"timeout"`; the status output is not used, only the node badge)
+5. `404` → the server dropped the subscription (>30 s gap or server restart) → re-POST immediately
+6. Any other error → error output, exponential back-off (5 s → 60 s), re-subscribe. Runs until stopped.
+
+**Input** – one trigger starts it:
+
+- `msg.payload = "508"` / `"508,526"` / `["508","526"]` / `{itemIds:[...]}` / array of item objects with `id` (so you can wire straight from a filtered `get items` result)
+- `msg.itemIds` takes precedence over `payload`
+- a new trigger with ids replaces the running subscription
+- `msg.payload = "stop"` or `msg.stop = true` stops it
+
+**Output 1**
+
+```js
+msg.payload  = { updates: [{ id, status, statusText, statusFlags }], next: { href } }  // full server response
+msg.updates  = msg.payload.updates
+msg.phase    = "subscribe" | "update" | "timeout"
+msg.itemIds, msg.seq, msg.statusCode, msg.url
+```
+
+Optional global key keeps a map `id → latest status` (+ `updated` time).
+
+Delay between waits defaults to 1 s and is capped at 20 s so the next GET always lands inside the server's 30 s window.
+
+Requires REST Server v8.30+ and the **RESTStatus** licence. Before 9.50 the first update-wait repeats the POST results; that is passed through as the server sends it.
+
+## Status output states
+
+`requesting`, `done`, `busy` (lists) · `subscribing`, `subscribed`, `update`, `resubscribing`, `retrying`, `stopped` (item status) · `error`.
+
+The "waiting" and "timed out" states of each long poll are shown on the node badge only, not sent on output 2, so the status log isn't flooded every 50 s.
+
+## Test
+
+```sh
+npm test
+```
+
+Spins up a self-signed HTTPS mock REST Server and a minimal Node-RED harness; covers fingerprint pin/mismatch, Basic and custom auth schemes, link-downgrade refusal, paging, href rewrite, global context, the update-wait loop, 404 re-subscribe, stop/replace, and recovery after the server drops.

package/examples/rest-basic.json

@@ -0,0 +1,290 @@
+[
+  {
+    "id": "rest_tab",
+    "type": "tab",
+    "label": "REST Server"
+  },
+  {
+    "z": "rest_tab",
+    "id": "dbg_resp",
+    "type": "debug",
+    "name": "responses",
+    "active": true,
+    "tosidebar": true,
+    "complete": "true",
+    "targetType": "msg",
+    "x": 760,
+    "y": 100,
+    "wires": []
+  },
+  {
+    "z": "rest_tab",
+    "id": "dbg_status",
+    "type": "debug",
+    "name": "status (all nodes)",
+    "active": true,
+    "tosidebar": true,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 780,
+    "y": 300,
+    "wires": []
+  },
+  {
+    "z": "rest_tab",
+    "id": "dbg_err",
+    "type": "debug",
+    "name": "errors (all nodes)",
+    "active": true,
+    "tosidebar": true,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 780,
+    "y": 360,
+    "wires": []
+  },
+  {
+    "z": "rest_tab",
+    "id": "inj_ag",
+    "type": "inject",
+    "name": "refresh ag",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "once": false,
+    "payload": "",
+    "payloadType": "date",
+    "x": 140,
+    "y": 60,
+    "wires": [
+      [
+        "n_ag"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "n_ag",
+    "type": "tdn-rest-access-groups",
+    "name": "get access groups",
+    "server": "rest_srv",
+    "contextKey": "rest_accessGroups",
+    "contextStore": "",
+    "top": 1000,
+    "sort": "id",
+    "fields": "",
+    "query": "",
+    "maxPages": 0,
+    "includePages": true,
+    "x": 400,
+    "y": 60,
+    "wires": [
+      [
+        "dbg_resp"
+      ],
+      [
+        "dbg_status"
+      ],
+      [
+        "dbg_err"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "inj_ch",
+    "type": "inject",
+    "name": "refresh ch",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "once": false,
+    "payload": "",
+    "payloadType": "date",
+    "x": 140,
+    "y": 120,
+    "wires": [
+      [
+        "n_ch"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "n_ch",
+    "type": "tdn-rest-cardholders",
+    "name": "get cardholders",
+    "server": "rest_srv",
+    "contextKey": "rest_cardholders",
+    "contextStore": "",
+    "top": 1000,
+    "sort": "id",
+    "fields": "",
+    "query": "",
+    "maxPages": 0,
+    "includePages": true,
+    "x": 400,
+    "y": 120,
+    "wires": [
+      [
+        "dbg_resp"
+      ],
+      [
+        "dbg_status"
+      ],
+      [
+        "dbg_err"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "inj_it",
+    "type": "inject",
+    "name": "refresh it",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "repeat": "",
+    "once": false,
+    "payload": "",
+    "payloadType": "date",
+    "x": 140,
+    "y": 180,
+    "wires": [
+      [
+        "n_it"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "n_it",
+    "type": "tdn-rest-items",
+    "name": "get items",
+    "server": "rest_srv",
+    "contextKey": "rest_items",
+    "contextStore": "",
+    "top": 1000,
+    "sort": "id",
+    "fields": "",
+    "query": "",
+    "maxPages": 0,
+    "includePages": true,
+    "x": 400,
+    "y": 180,
+    "wires": [
+      [
+        "dbg_resp"
+      ],
+      [
+        "dbg_status"
+      ],
+      [
+        "dbg_err"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "inj_sub",
+    "type": "inject",
+    "name": "watch 508,526",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "payload": "508,526",
+    "payloadType": "str",
+    "x": 150,
+    "y": 260,
+    "wires": [
+      [
+        "n_st"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "inj_stop",
+    "type": "inject",
+    "name": "stop",
+    "props": [
+      {
+        "p": "payload"
+      }
+    ],
+    "payload": "stop",
+    "payloadType": "str",
+    "x": 130,
+    "y": 300,
+    "wires": [
+      [
+        "n_st"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "n_st",
+    "type": "tdn-rest-item-status",
+    "name": "door status",
+    "server": "rest_srv",
+    "pollDelay": 1000,
+    "retryDelay": 5000,
+    "maxRetryDelay": 60000,
+    "emitTimeouts": false,
+    "contextKey": "rest_itemStatus",
+    "contextStore": "",
+    "x": 400,
+    "y": 280,
+    "wires": [
+      [
+        "dbg_upd"
+      ],
+      [
+        "dbg_status"
+      ],
+      [
+        "dbg_err"
+      ]
+    ]
+  },
+  {
+    "z": "rest_tab",
+    "id": "dbg_upd",
+    "type": "debug",
+    "name": "status updates",
+    "active": true,
+    "tosidebar": true,
+    "complete": "updates",
+    "targetType": "msg",
+    "x": 760,
+    "y": 240,
+    "wires": []
+  },
+  {
+    "id": "rest_srv",
+    "type": "tdn-rest-server",
+    "name": "REST Server",
+    "url": "192.168.1.10",
+    "port": 8904,
+    "authScheme": "",
+    "fingerprint": "",
+    "rejectUnauthorized": true,
+    "rewriteHrefs": true,
+    "timeout": 30000,
+    "certPath": "",
+    "keyPath": "",
+    "pfxPath": ""
+  }
+]