node-red-contrib-tdn-eventsub 0.2.2 → 0.2.3

package/README.md

@@ -2,20 +2,21 @@
 
 Node-RED nodes for an access-control **REST Server API**.
 
-| Node | What it does | Mode |
+| Node | Endpoint (under the base path) | 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: can come from a credentials object instead), how to send it (Authorization or API key header), optional server certificate fingerprint, optional client certificate.
+| `get cardholders` | `/cardholders`, `/cardholders/{id}` | request/reply |
+| `get access groups` | `/access_groups`, `/access_groups/{id}/cardholders` | request/reply |
+| `get items` | `/items`, `/items/{id}` | request/reply |
+| `get personal data fields` | `/personal_data_fields`, `/personal_data_fields/{id}` | request/reply |
+| `get event groups` | `/events/groups`, `/events/groups/{id}` (event types) | request/reply |
+| `item status` | `POST /items/updates`, then long-poll | continuous |
+| `event updates` | `/events/updates`, long-poll | continuous |
 
 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`
+1. **Response**: the full server response in `msg`.
+2. **Status**: one message per **successful** server response, for wiring to a shared log or dashboard.
+3. **Error**: **every** non-success, whether an HTTP error, a network failure, a certificate problem or bad input. Errors never appear on the status output.
 
 No runtime dependencies. Node 16+, Node-RED 3+.
 
@@ -23,41 +24,49 @@ No runtime dependencies. Node 16+, Node-RED 3+.
 
 ```sh
 cd ~/.node-red
-npm install /path/to/node-red-contrib-tdn-eventsub      # or the .tgz
+npm install node-red-contrib-tdn-eventsub@latest
 ```
 
 Restart Node-RED. Nodes appear under **TDN REST**. Import the example via *Import → Examples → node-red-contrib-tdn-eventsub*.
 
-## Server config
+## Server address
 
-| Field | Notes |
-|---|---|
-| URL / host | `rest-server`, `192.168.1.10` or `https://rest-server`. `/api` path assumed. |
-| Port | Default `8904`. |
-| API key | Optional. Stored as a Node-RED credential; treated as opaque. When set it is always used. When blank, each node reads a [credentials object](#credentials-object). |
-| Send key as | **Authorization header** (default) or **API key header**. |
-| Auth scheme | Authorization header only. 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>`. |
-| Header name | API key header only. Sent as `<header name>: <key>`; default `X-API-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. |
-| Plain HTTP (insecure) | Unencrypted `http://` whatever the URL says; certificate settings are ignored and the key travels in clear text. For bench testing against a non-TLS endpoint only. A TLS error like `unexpected message` or `wrong version number` usually means the endpoint needs this; the error text says so. |
-| 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). |
+Every request goes to `<protocol>://<host>:<port><basePath><endpoint>`, for example:
 
-## Credentials object
+```
+http://localhost:80/api/cardholders
+https://192.168.0.20:8904/api/access_groups
+https://testserver:8911/api/items
+```
 
-If the server config has **no API key stored** in Node-RED, every node takes the key from its **Credentials** property: a typedInput pointing at `msg`, `flow`, `global` or `env`, default `msg.credentials`. The value is either a bare key string or:
+The address is read from **global context** at every request, key `rest_server` (configurable in the server config node):
 
 ```js
-{
-  apiKey: "XXXX-...",                          // required
-  authType: "authorization" | "header",        // default: server config
-  authScheme: "",                              // authorization only; blank = Basic
-  headerName: "X-API-Key"                      // header only
+global.rest_server = {
+  host: "192.168.0.20",   // hostname or IP (a full URL like "https://testserver:8911/api" also works)
+  port: 8904,
+  basePath: "/api",
+  protocol: "https"       // or "http"
 }
 ```
 
-Missing fields fall back to the server config. A stored key always takes precedence, and the credentials object is then ignored. A msg-borne credentials property is deleted from the msg before it is passed on, so the key doesn't reach debug nodes or downstream flows. The item status node reads the credentials once per trigger and keeps them for that subscription.
+Any field that's missing falls back to the server config node. A plain string value is treated as the host or URL. You can change the value with a change node to switch servers without redeploying. The protocol is decided in this order: `protocol`, then the scheme in `host`, then the config node's *Plain HTTP* checkbox, then https.
+
+## Server config
+
+| Field | Notes |
+|---|---|
+| Global key | Default `rest_server`. Leave blank to ignore global context. |
+| Host / IP, Port, Base path | Fallbacks when global context doesn't set them. Defaults: port `8904`, base path `/api`. |
+| API key | Optional. Stored as a Node-RED credential and treated as opaque. When it's set, it is always used. When it's blank, each node reads a [credentials object](#credentials-object). |
+| Send key as | **Authorization header** (default) or **API key header**. |
+| Auth scheme | Authorization header only. Blank (the default) sends `Authorization: Basic base64(":" + key)`, which server v9.0+ accepts. 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>`. |
+| Header name | API key header only. Sent as `<header name>: <key>`; default `X-API-Key`. |
+| Plain HTTP (insecure) | Uses unencrypted `http://` when nothing else sets the protocol. Certificate settings are ignored and the key travels in clear text, so use it for bench testing only. |
+| Cert fingerprint | Optional. The SHA-256 (64 hex) or SHA-1 (40 hex) fingerprint of the **server** certificate; colons are optional. When set, a self-signed certificate is accepted only if it matches. The check runs before any request is written, so the key is never sent to an impostor. |
+| Verify server certificate | Normal CA check when no fingerprint is set. |
+| Force links onto this host:port | Paging and subscription links (`next.href`) are built from the server's own machine name. With this option on, they keep their path and query but use your host and port. With it off, a link that would downgrade `https` to `http` is refused. |
+| Client cert / key / PFX | Only needed if the REST Client item on the server has a thumbprint (pinned client certificate). |
 
 Get the server fingerprint with:
 
@@ -65,63 +74,98 @@ Get the server fingerprint with:
 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.
+## Credentials object
 
-**Output 1**
+If the server config has **no API key stored** in Node-RED, every node takes the key from its **Credentials** property. This is a typedInput pointing at `msg`, `flow`, `global` or `env`; the default is `msg.credentials`. The value is either a bare key string or:
 
 ```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
+{ apiKey: "XXXX-...", authType: "authorization" | "header", authScheme: "", headerName: "X-API-Key" }
 ```
 
-**Global context**: `global.<key>` = results array, `global.<key>_updated` = ISO time. Defaults: `rest_accessGroups`, `rest_cardholders`, `rest_items`. Any context store can be picked.
+- Missing fields fall back to the server config.
+- A stored key always takes precedence.
+- A credentials property on the msg is deleted before the msg is passed on.
+- Subscriptions read the credentials once per trigger.
 
-**Per-message overrides**: `msg.query` (object or `"a=1&b=2"`), `msg.fields`, `msg.top`, `msg.maxPages`, `msg.contextKey`.
+## List nodes
 
-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.
+### Input
 
-## Item status node
+| msg | Request |
+|---|---|
+| no id, or an inject timestamp or boolean | **list**: `GET <endpoint>` with `top`, `sort` and `fields`; every page is followed and merged |
+| an id: `msg.id`, a string or number `msg.payload`, or `msg.payload.id` | **details**: `GET <endpoint>/{id}`. For **access groups** this is the group's members instead: `GET /access_groups/{id}/cardholders` |
+| `msg.action` set | takes precedence over the defaults above |
 
-Implements the REST Server status-subscription loop:
+| `msg.action` | Request | Stored in global context |
+|---|---|---|
+| `list` | `GET <endpoint>` (all pages) | `<key>` (array) and `<key>_updated` |
+| `get` | `GET <endpoint>/{id}` | `<key>_byId[id]` |
+| `members` (access groups) | `GET /access_groups/{id}/cardholders` (all pages) | `<key>_members[id]` |
+| `groups` (cardholders) | `GET /cardholders/{id}?fields=accessGroups` | `<key>_groups[id]` |
+| `create` | `POST <endpoint>`, body `msg.payload` | none (`msg.location` = new resource) |
+| `update` | `PATCH <endpoint>/{id}`, body `msg.payload` | none |
+| `delete` | `DELETE <endpoint>/{id}` (only with an explicit action) | removes `<key>_byId[id]` |
 
-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.
+Default keys are `rest_cardholders`, `rest_accessGroups`, `rest_items`, `rest_pdfs` and `rest_eventGroups`. Any context store can be picked. Id responses go into maps, so they never overwrite the full list.
 
-**Input** – one trigger starts it:
+Per-message overrides: `msg.query` (an object or `"a=1&b=2"`), `msg.fields`, `msg.top`, `msg.maxPages` and `msg.contextKey`.
 
-- `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
+Requests are **queued** and run one at a time, up to the *Queue limit* (default 100).
 
-**Output 1**
+### 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
+msg.payload    // list/members: { results: [...all pages], count, pageCount }; details/writes: the server's body
+msg.pages      // raw page bodies (toggle)
+msg.action, msg.id, msg.statusCode, msg.location, msg.request, msg.contextKey
 ```
 
-Optional global key keeps a map `id → latest status` (+ `updated` time).
+## Item status node
+
+1. `POST /items/updates` with `{"itemIds":[...]}` returns the current status of every item. It is sent on output 1 with `phase:"subscribe"`.
+2. `GET next.href` is the update-wait: a long poll that the server answers on a change, or after about 50 s.
+3. When updates arrive they're output with `phase:"update"`, and the next update-wait goes out immediately. Empty update-waits only update the node badge (or use the *Also output empty responses* option).
+
+**Input** is `"508"`, `"508,526"`, an array, `{itemIds:[...]}`, or item objects with `id`. `msg.itemIds` and then `msg.id` take precedence. A new trigger replaces the running subscription. `payload:"stop"`, `action:"stop"` or `msg.stop=true` stops it.
+
+There's an optional global map of item id → latest status. The delay between waits is capped at 20 s, so each request stays inside the server's 30 s window.
 
-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.
+This needs REST Server v8.30+ and the **RESTStatus** licence.
 
-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.
+## Event updates node
 
-## Status output states
+`GET /events/updates?<filter>` long-polls for new events. Each response's `updates.href` (or `next.href`) is followed immediately, indefinitely.
 
-`requesting`, `done`, `busy` (lists) · `subscribing`, `subscribed`, `update`, `resubscribing`, `retrying`, `stopped` (item status) · `error`.
+- **Filter**: set it in the node (`group=23&type=20001&source=508`) or in `msg.query` at start. Use *get event groups* to find group and type ids.
+- **Output 1**: `msg.payload` (the full response), `msg.events`, `msg.phase`, `msg.seq` and `msg.query`.
+- **Global context** (optional): keeps the last N events.
+- **Start on deploy**: an option that takes credentials from flow, global or env.
+- **Stopping**: same as item status.
 
-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.
+## Failures and back-off
+
+| Failure | List nodes | Item status / event updates |
+|---|---|---|
+| **401** wrong API key | error, no retry; the rest of the queue is dropped (one `EDROPPED` error) so a bad key can't trigger the server's failed-login alarms | error, **polling stops** |
+| **Certificate / TLS** (pin mismatch, CA, client cert, not TLS) | error, no retry; queue dropped | error, **polling stops** |
+| **403** licence or privilege | error, no retry | error, **polling stops** |
+| **404** | error, no retry | on the start endpoint: error, **polling stops**. On a followed link (expired subscription): error, then an immediate re-subscribe |
+| other 4xx | error, no retry | error, polling stops |
+| **5xx, 408, 429, timeout, network** | GET/DELETE retried *Retries* times (default 3) at delay × 2ⁿ (5 s, 10 s, 20 s…, capped); each attempt is an error with `attempt` and `retryInMs`. POST/PATCH are never retried, to avoid duplicates | error, back-off 5 s → 60 s, re-subscribe, indefinitely |
+
+A stopped subscription restarts on the next trigger or on redeploy. Error payloads carry `category` (`fatal`, `transient` or `expired`) and, for subscriptions, `stopped: true` when polling has ended.
+
+## Status output
+
+Status messages are `{ topic: "status", payload: { state, text, node, name, type, time, ... } }`:
+
+- **lists**: `response` (one per successful HTTP response, with `statusCode`, `method`, `url` and `page`), then `done`;
+- **item status**: `subscribed` and `update`;
+- **event updates**: `update`;
+- **subscriptions**: `stopped` on a stop input.
+
+Empty long-poll returns (about every 50 s) show on the node badge only.
 
 ## Test
 
@@ -129,4 +173,11 @@ The "waiting" and "timed out" states of each long poll are shown on the node bad
 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.
+This spins up a mock REST Server (self-signed HTTPS, plain HTTP, and a TLS echo endpoint) and a minimal Node-RED harness. It covers:
+- addressing and the global-context override;
+- every list node and action, paging, the queue, back-off, and the hard-stop rules;
+- the credentials object and both auth header modes;
+- certificate pinning;
+- the item-status and events long-poll loops, including expiry, stop/replace and recovery.
+
+After changing a list-node definition, regenerate the editor HTML with `node tools/gen-lists-html.js`.