node-red-contrib-i3x 0.0.1 → 0.0.3

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:www.i3x.dev)",
+      "WebFetch(domain:api.i3x.dev)",
+      "Bash(npx mocha:*)",
+      "Bash(npm test:*)",
+      "Bash(node-red:*)",
+      "Bash(npx node-red:*)",
+      "Bash(docker compose:*)",
+      "Bash(ls /home/la/private/node-red-contrib-i3x/docker-compose* /home/la/private/node-red-contrib-i3x/Dockerfile* 2>/dev/null)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,8 +1,57 @@
 # Changelog
 
+## 0.0.3 (2026-03-10)
+
+Hardening, security improvements, and new browser widget features.
+
+### Added
+
+- **Live Values in Browser Widget** – The tree view now displays the current value, quality, and timestamp next to each element. Values are fetched automatically when expanding types or children, and on search results. Hover to see full value with quality and timestamp.
+- **Test Connection Button** – Server config panel now includes a "Test Connection" button to verify connectivity without deploying
+- **New admin endpoint** `POST /i3x-server/:id/browse/values` – Batch-reads live values for up to 50 elements (used by browser widget)
+- **`statusError()` utility** – Smarter error message truncation (48 chars with `...`) replacing the hard `substring(0, 32)` cut across all nodes
+- **`clampMaxDepth()` utility** – Validates and clamps `maxDepth` to 0–100 range, preventing negative or excessively large values
+
+### Security
+
+- **HTTPS warning** – Nodes now warn at startup when credentials are sent over plain HTTP to non-localhost servers
+- **Error response sanitization** – `_wrapError()` strips sensitive fields (`token`, `password`, `apiKey`, `secret`) from API error response bodies to prevent accidental credential leakage in logs
+
+### Fixed
+
+- **SSE auth header duplication** – `streamSubscription()` now copies all configured headers cleanly via spread instead of manually duplicating individual auth headers
+- **Poll interval minimum** – Increased from 500ms to 1000ms to prevent accidental API overload
+
+### Changed
+
+- Error status messages across all nodes now show up to 48 characters (was 32)
+- `maxDepth` is validated on all nodes that accept it (read, history, subscribe)
+
+## 0.0.2 (2026-03-05)
+
+Compliance improvements based on [i3X Client Developer Guidelines](https://www.i3x.dev/sdk/category/client-developers).
+
+### Added
+
+- **TTL Caching** – Namespace and object type responses are cached for 60 seconds to reduce API load
+- **Rate Limiting** – Client-side sliding-window throttle (100 requests per 60-second window) to proactively stay within API limits
+- **Retry-After Header Support** – Respects server-provided `Retry-After` headers (both seconds and HTTP-date formats) instead of only using fixed exponential backoff
+- **Input Sanitization** – Allowlist validation on write payloads (`writeValue`, `writeHistory`) to prevent injection of unexpected fields
+- **New tests** – 12 additional unit tests covering caching, Retry-After, input sanitization, and rate limiting (75 tests total)
+
+### Fixed
+
+- **`testConnection()` bypassed cache** – Health check now performs a real HTTP round-trip instead of returning stale cached data
+- **SSE stream missing auth headers** – Bearer tokens and API keys are now explicitly propagated to SSE stream requests (previously only `headers.common` was copied, which could miss auth headers)
+- **TLS `rejectUnauthorized` default** – Now defaults to `true` per i3X security guidelines; can still be overridden via TLS config node
+
+### Changed
+
+- Updated API docs URL from `https://i3x.cesmii.net/docs` to `https://api.i3x.dev/v0/docs`
+
 ## 0.0.1 (2026-03-03)
 
-Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://i3x.cesmii.net/docs).
+Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs).
 
 ### Nodes
 
@@ -19,5 +68,5 @@ Initial pre-alpha release targeting the [i3X API Prototype v0.0.1](https://i3x.c
 - Shared HTTP client (`lib/i3x-client.js`) with retry logic, error wrapping, and SSE reconnection
 - Dynamic configuration via `msg` properties (all node settings can be overridden at runtime)
 - Example flow demonstrating all features against the public CESMII demo server
-- Unit tests (63 tests) and integration tests against the live API
+- Unit tests and integration tests against the live API
 - Docker Compose setup for testing and local Node-RED development

package/README.md

@@ -90,9 +90,25 @@ Subscribe to value changes via SSE streaming or polling.
 - **Fallback:** If SSE fails, the node automatically falls back to polling
 - **Lifecycle:** Subscriptions are created on deploy and deleted on stop/re-deploy
 
+## Built-in Resilience & Best Practices
+
+The shared HTTP client (`lib/i3x-client.js`) implements all [i3X Client Developer Best Practices](https://www.i3x.dev/sdk/category/client-developers):
+
+| Feature | Description |
+| ------- | ----------- |
+| **Retry with Exponential Backoff** | Automatic retries on 429, 502, 503, 504 with exponential delay |
+| **Retry-After Header** | Respects server-provided `Retry-After` headers (seconds and HTTP-date formats) |
+| **TTL Caching** | Namespaces and object types are cached for 60 seconds to reduce API load |
+| **Rate Limiting** | Client-side sliding-window throttle (100 requests per 60-second window) |
+| **Input Sanitization** | Allowlist validation on write payloads to prevent injection of unexpected fields |
+| **TLS Certificate Validation** | `rejectUnauthorized: true` by default; overridable via TLS config node |
+| **SSE Reconnection** | Automatic reconnection with exponential backoff (up to 5 attempts, max 30s delay) |
+| **SSE → Polling Fallback** | Automatic fallback to polling if SSE stream setup fails |
+| **Subscription Cleanup** | Subscriptions are deleted server-side on node stop/re-deploy |
+
 ## API Endpoints Used
 
-This package targets the [i3X API Prototype v0.0.1](https://i3x.cesmii.net/docs):
+This package targets the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs):
 
 | Category  | Method | Endpoint                                     |
 | --------- | ------ | -------------------------------------------- |
@@ -208,7 +224,8 @@ node-red
 
 ## References
 
-- [i3X API Documentation](https://i3x.cesmii.net/docs)
+- [i3X API Documentation](https://api.i3x.dev/v0/docs)
+- [i3X Client Developer Guide](https://www.i3x.dev/sdk/category/client-developers)
 - [i3X Specification & RFC](https://github.com/cesmii/i3X)
 - [i3X SDK Documentation](https://www.i3x.dev/sdk)
 - [CESMII](https://www.cesmii.org)

package/lib/i3x-client.js

@@ -15,6 +15,55 @@ const RETRY_STATUS_CODES = new Set([429, 502, 503, 504]);
 const MAX_RETRIES = 3;
 const RETRY_DELAY_MS = 1000;
 
+const DEFAULT_CACHE_TTL_MS = 60000; // 1 minute
+const RATE_LIMIT_WINDOW_MS = 60000; // 60 seconds
+const RATE_LIMIT_MAX_REQUESTS = 100;
+
+class TTLCache {
+    constructor(ttl = DEFAULT_CACHE_TTL_MS) {
+        this._ttl = ttl;
+        this._store = new Map();
+    }
+
+    get(key) {
+        const entry = this._store.get(key);
+        if (!entry) return undefined;
+        if (Date.now() > entry.expires) {
+            this._store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+
+    set(key, value) {
+        this._store.set(key, { value, expires: Date.now() + this._ttl });
+    }
+
+    clear() {
+        this._store.clear();
+    }
+}
+
+class RateLimiter {
+    constructor(maxRequests = RATE_LIMIT_MAX_REQUESTS, windowMs = RATE_LIMIT_WINDOW_MS) {
+        this._maxRequests = maxRequests;
+        this._windowMs = windowMs;
+        this._timestamps = [];
+    }
+
+    async acquire() {
+        const now = Date.now();
+        this._timestamps = this._timestamps.filter((t) => now - t < this._windowMs);
+        if (this._timestamps.length >= this._maxRequests) {
+            const oldest = this._timestamps[0];
+            const waitMs = this._windowMs - (now - oldest);
+            await new Promise((r) => setTimeout(r, waitMs));
+            return this.acquire();
+        }
+        this._timestamps.push(Date.now());
+    }
+}
+
 class I3XClient extends EventEmitter {
     /**
      * @param {object} config
@@ -35,6 +84,14 @@ class I3XClient extends EventEmitter {
         this.authType = config.authType || "none";
         this.timeout = config.timeout || 10000;
 
+        // Warn if credentials are sent over plain HTTP (not localhost)
+        if (this.authType !== "none" && this.baseUrl && !this.baseUrl.startsWith("https://")) {
+            const isLocal = /^https?:\/\/(localhost|127\.0\.0\.1|::1)(:|\/|$)/.test(this.baseUrl);
+            if (!isLocal) {
+                this._httpsWarning = "Credentials sent over plain HTTP – use HTTPS in production";
+            }
+        }
+
         const axiosConfig = {
             baseURL: this._prefix(),
             timeout: this.timeout,
@@ -51,18 +108,26 @@ class I3XClient extends EventEmitter {
 
         if (config.tlsOptions) {
             const https = require("https");
-            axiosConfig.httpsAgent = new https.Agent(config.tlsOptions);
+            const tlsOpts = { rejectUnauthorized: true, ...config.tlsOptions };
+            axiosConfig.httpsAgent = new https.Agent(tlsOpts);
         }
 
         this.http = axios.create(axiosConfig);
         this._activeSubscriptions = new Map();
+        this._cache = new TTLCache();
+        this._rateLimiter = new RateLimiter();
     }
 
     // ── Explore ────────────────────────────────────────────────────────
 
     /** @returns {Promise<Array<{uri:string, displayName:string}>>} */
     async getNamespaces() {
-        return this._get("/namespaces");
+        const cacheKey = "namespaces";
+        const cached = this._cache.get(cacheKey);
+        if (cached) return cached;
+        const result = await this._get("/namespaces");
+        this._cache.set(cacheKey, result);
+        return result;
     }
 
     /**
@@ -72,7 +137,12 @@ class I3XClient extends EventEmitter {
     async getObjectTypes(options = {}) {
         const params = {};
         if (options.namespaceUri) params.namespaceUri = options.namespaceUri;
-        return this._get("/objecttypes", params);
+        const cacheKey = "objecttypes:" + (options.namespaceUri || "");
+        const cached = this._cache.get(cacheKey);
+        if (cached) return cached;
+        const result = await this._get("/objecttypes", params);
+        this._cache.set(cacheKey, result);
+        return result;
     }
 
     /** @param {string[]} elementIds */
@@ -166,6 +236,7 @@ class I3XClient extends EventEmitter {
      * @param {*}      value
      */
     async writeValue(elementId, value) {
+        I3XClient._validateWritePayload(value);
         return this._put(`/objects/${encodeURIComponent(elementId)}/value`, value);
     }
 
@@ -174,9 +245,28 @@ class I3XClient extends EventEmitter {
      * @param {*}      data – historical data payload
      */
     async writeHistory(elementId, data) {
+        I3XClient._validateWritePayload(data);
         return this._put(`/objects/${encodeURIComponent(elementId)}/history`, data);
     }
 
+    static _WRITE_ALLOWED_FIELDS = new Set([
+        "value", "timestamp", "quality", "displayName", "attributes", "metadata",
+        "startTime", "endTime", "values", "elementId", "status",
+    ]);
+
+    static _validateWritePayload(payload) {
+        if (payload === null || payload === undefined) {
+            throw new Error("Write payload must not be null or undefined");
+        }
+        if (typeof payload === "object" && !Array.isArray(payload)) {
+            const keys = Object.keys(payload);
+            const disallowed = keys.filter((k) => !I3XClient._WRITE_ALLOWED_FIELDS.has(k));
+            if (disallowed.length > 0) {
+                throw new Error("Disallowed fields in write payload: " + disallowed.join(", "));
+            }
+        }
+    }
+
     // ── Subscribe ──────────────────────────────────────────────────────
 
     async listSubscriptions() {
@@ -246,7 +336,19 @@ class I3XClient extends EventEmitter {
         let closed = false;
         let reconnectCount = 0;
 
-        const headers = { ...this.http.defaults.headers.common, Accept: "text/event-stream" };
+        const headers = {
+            ...this.http.defaults.headers.common,
+            ...this.http.defaults.headers,
+            Accept: "text/event-stream",
+        };
+        // Remove non-header axios defaults that got spread in
+        delete headers.common;
+        delete headers.get;
+        delete headers.post;
+        delete headers.put;
+        delete headers.delete;
+        delete headers.patch;
+        delete headers.head;
         if (this.http.defaults.auth) {
             const b64 = Buffer.from(
                 `${this.http.defaults.auth.username}:${this.http.defaults.auth.password}`
@@ -336,10 +438,10 @@ class I3XClient extends EventEmitter {
 
     /**
      * Lightweight connectivity test.
-     * Uses GET /namespaces as health indicator.
+     * Bypasses cache to ensure a real round-trip to the server.
      */
     async testConnection() {
-        await this._get("/namespaces");
+        await this._request("get", "/namespaces", {});
         return true;
     }
 
@@ -349,6 +451,7 @@ class I3XClient extends EventEmitter {
             handle.close();
         }
         this._activeSubscriptions.clear();
+        this._cache.clear();
     }
 
     // ── Internal helpers ───────────────────────────────────────────────
@@ -380,10 +483,11 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Central request dispatcher with retry logic.
+     * Central request dispatcher with retry logic, Retry-After support, and rate limiting.
      * @private
      */
     async _request(method, path, opts = {}) {
+        await this._rateLimiter.acquire();
         let lastErr;
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
@@ -393,7 +497,16 @@ class I3XClient extends EventEmitter {
                 lastErr = err;
                 const status = err.response && err.response.status;
                 if (status && RETRY_STATUS_CODES.has(status) && attempt < MAX_RETRIES) {
-                    const delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+                    const retryAfter = err.response.headers && err.response.headers["retry-after"];
+                    let delay;
+                    if (retryAfter) {
+                        const seconds = parseInt(retryAfter, 10);
+                        delay = isNaN(seconds)
+                            ? Math.max(0, new Date(retryAfter).getTime() - Date.now())
+                            : seconds * 1000;
+                    } else {
+                        delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+                    }
                     await new Promise((r) => setTimeout(r, delay));
                     continue;
                 }
@@ -414,7 +527,17 @@ class I3XClient extends EventEmitter {
         if (err.response) {
             wrapped.statusCode = err.response.status;
             wrapped.statusText = err.response.statusText;
-            wrapped.body = err.response.data;
+            // Sanitize response body to avoid leaking auth details
+            const body = err.response.data;
+            if (body && typeof body === "object") {
+                const sanitized = { ...body };
+                for (const key of ["authorization", "token", "apiKey", "api_key", "password", "secret"]) {
+                    delete sanitized[key];
+                }
+                wrapped.body = sanitized;
+            } else {
+                wrapped.body = body;
+            }
         } else if (err.code) {
             wrapped.code = err.code;
         }

package/lib/node-utils.js

@@ -58,4 +58,30 @@ function safeSend(node, send) {
     return send || function () { node.send.apply(node, arguments); };
 }
 
-module.exports = { bindServer, parseIds, safeSend };
+/**
+ * Truncate an error message for node status display.
+ * Keeps up to 48 characters and appends "..." if truncated.
+ * @param {string} msg
+ * @returns {string}
+ */
+function statusError(msg) {
+    if (!msg) return "error";
+    if (msg.length <= 48) return msg;
+    return msg.substring(0, 45) + "...";
+}
+
+/**
+ * Clamp maxDepth to a valid range (0–100).
+ * @param {number} val
+ * @param {number} [fallback=1]
+ * @returns {number}
+ */
+function clampMaxDepth(val, fallback) {
+    if (fallback === undefined) fallback = 1;
+    var n = parseInt(val, 10);
+    if (isNaN(n) || n < 0) return fallback;
+    if (n > 100) return 100;
+    return n;
+}
+
+module.exports = { bindServer, parseIds, safeSend, statusError, clampMaxDepth };

package/nodes/i3x-browse.html

@@ -21,6 +21,9 @@
         <label for="node-input-elementId"><i class="fa fa-crosshairs"></i> Element ID</label>
         <input type="text" id="node-input-elementId" placeholder="optional – filter by element ID">
     </div>
+    <div class="form-row i3x-browse-elementId">
+        <div id="i3x-browse-browser"></div>
+    </div>
     <div class="form-row i3x-browse-typeId">
         <label for="node-input-typeId"><i class="fa fa-filter"></i> Type ID</label>
         <input type="text" id="node-input-typeId" placeholder="optional – filter objects by type">
@@ -66,6 +69,7 @@
     <h3>Details</h3>
     <p>This node talks to the <b>Explore</b> endpoints of the i3X API.
     <code>msg</code> properties override the values configured in the node editor.</p>
+    <p>Use the <b>Browse</b> button to visually select an element from the server.</p>
 </script>
 
 <script type="text/javascript">
@@ -101,6 +105,15 @@
             }
             target.on("change", toggle);
             toggle();
+
+            if (window.I3XBrowser) {
+                this._browser = I3XBrowser.create({
+                    container: "#i3x-browse-browser",
+                    serverField: "#node-input-server",
+                    targetField: "#node-input-elementId",
+                    mode: "single",
+                });
+            }
         },
     });
 </script>

package/nodes/i3x-browse.js

@@ -3,7 +3,7 @@
  */
 "use strict";
 
-const { bindServer, safeSend } = require("../lib/node-utils");
+const { bindServer, parseIds, safeSend, statusError } = require("../lib/node-utils");
 
 module.exports = function (RED) {
     function I3XBrowseNode(config) {
@@ -24,13 +24,13 @@ module.exports = function (RED) {
             const client = node.server.client;
 
             const target = msg.browseTarget || node.browseTarget;
-            const elementId = msg.elementId || node.elementId;
+            const ids = parseIds(msg.elementId || node.elementId);
             const typeId = msg.typeId || node.typeId;
             const nsUri = msg.namespaceUri || node.namespaceUri;
             const inclMeta = msg.includeMetadata !== undefined ? msg.includeMetadata : node.includeMetadata;
             const relType = msg.relationshipType || node.relationshipType;
 
-            node.status({ fill: "blue", shape: "dot", text: "requesting..." });
+            node.status({ fill: "blue", shape: "dot", text: "browsing " + target + "..." });
 
             try {
                 let result;
@@ -39,51 +39,46 @@ module.exports = function (RED) {
                         result = await client.getNamespaces();
                         break;
                     case "objecttypes":
-                        if (elementId) {
-                            const ids = Array.isArray(elementId) ? elementId : [elementId];
+                        if (ids.length) {
                             result = await client.queryObjectTypes(ids);
                         } else {
                             result = await client.getObjectTypes({ namespaceUri: nsUri || undefined });
                         }
                         break;
                     case "relationshiptypes":
-                        if (elementId) {
-                            const ids = Array.isArray(elementId) ? elementId : [elementId];
+                        if (ids.length) {
                             result = await client.queryRelationshipTypes(ids);
                         } else {
                             result = await client.getRelationshipTypes({ namespaceUri: nsUri || undefined });
                         }
                         break;
                     case "objects":
-                        if (elementId) {
-                            const ids = Array.isArray(elementId) ? elementId : [elementId];
+                        if (ids.length) {
                             result = await client.listObjects(ids, { includeMetadata: inclMeta });
                         } else {
                             result = await client.getObjects({ typeId: typeId || undefined, includeMetadata: inclMeta });
                         }
                         break;
                     case "related":
-                        if (!elementId) {
+                        if (!ids.length) {
                             throw new Error("elementId is required for related objects query");
                         }
-                        {
-                            const ids = Array.isArray(elementId) ? elementId : [elementId];
-                            result = await client.getRelatedObjects(ids, {
-                                relationshipType: relType || undefined,
-                                includeMetadata: inclMeta,
-                            });
-                        }
+                        result = await client.getRelatedObjects(ids, {
+                            relationshipType: relType || undefined,
+                            includeMetadata: inclMeta,
+                        });
                         break;
                     default:
                         throw new Error("Unknown browse target: " + target);
                 }
 
+                const count = Array.isArray(result) ? result.length : 1;
                 msg.payload = result;
-                node.status({ fill: "green", shape: "dot", text: "ok" });
+                node.status({ fill: "green", shape: "dot", text: count + " " + target });
                 send(msg);
                 if (done) done();
             } catch (err) {
-                node.status({ fill: "red", shape: "ring", text: err.message.substring(0, 32) });
+                node.status({ fill: "red", shape: "ring", text: statusError(err.message) });
                 if (done) done(err); else node.error(err, msg);
             }
         });

package/nodes/i3x-history.html

@@ -11,6 +11,9 @@
         <label for="node-input-elementIds"><i class="fa fa-list"></i> Element IDs</label>
         <input type="text" id="node-input-elementIds" placeholder="comma-separated element IDs">
     </div>
+    <div class="form-row">
+        <div id="i3x-history-browser"></div>
+    </div>
     <div class="form-row">
         <label for="node-input-startTime"><i class="fa fa-clock-o"></i> Start Time</label>
         <input type="text" id="node-input-startTime" placeholder="ISO 8601 or relative (e.g. -1h, -7d)">
@@ -50,6 +53,7 @@
     <p>Uses <code>POST /objects/history</code>. Time values support both ISO 8601 and
     relative notation: <code>-30s</code> (seconds), <code>-5m</code> (minutes), <code>-1h</code> (hours),
     <code>-7d</code> (days), <code>-1w</code> (weeks).</p>
+    <p>Use the <b>Browse</b> button to visually select elements from the server.</p>
 </script>
 
 <script type="text/javascript">
@@ -71,5 +75,15 @@
         label: function () {
             return this.name || this.elementIds || "i3x history";
         },
+        oneditprepare: function () {
+            if (window.I3XBrowser) {
+                this._browser = I3XBrowser.create({
+                    container: "#i3x-history-browser",
+                    serverField: "#node-input-server",
+                    targetField: "#node-input-elementIds",
+                    mode: "multi",
+                });
+            }
+        },
     });
 </script>

package/nodes/i3x-history.js

@@ -3,7 +3,7 @@
  */
 "use strict";
 
-const { bindServer, parseIds, safeSend } = require("../lib/node-utils");
+const { bindServer, parseIds, safeSend, statusError, clampMaxDepth } = require("../lib/node-utils");
 
 /**
  * Resolve relative time strings like "-1h", "-7d", "-30m" to ISO 8601.
@@ -28,8 +28,7 @@ module.exports = function (RED) {
         node.elementIds = config.elementIds || "";
         node.startTime = config.startTime || "";
         node.endTime = config.endTime || "";
-        node.maxDepth = parseInt(config.maxDepth, 10);
-        if (isNaN(node.maxDepth)) node.maxDepth = 1;
+        node.maxDepth = clampMaxDepth(config.maxDepth);
 
         if (!bindServer(node, RED, config.server)) return;
 
@@ -46,18 +45,19 @@ module.exports = function (RED) {
 
             const startTime = resolveTime(msg.startTime || node.startTime);
             const endTime = resolveTime(msg.endTime || node.endTime);
-            const maxDepth = msg.maxDepth !== undefined ? parseInt(msg.maxDepth, 10) : node.maxDepth;
+            const maxDepth = msg.maxDepth !== undefined ? clampMaxDepth(msg.maxDepth) : node.maxDepth;
 
             node.status({ fill: "blue", shape: "dot", text: "querying..." });
 
             try {
                 const result = await client.readHistory(ids, { startTime, endTime, maxDepth });
                 msg.payload = result;
-                node.status({ fill: "green", shape: "dot", text: "ok" });
+                const count = Array.isArray(result) ? result.length : 1;
+                node.status({ fill: "green", shape: "dot", text: count + " record" + (count !== 1 ? "s" : "") });
                 send(msg);
                 if (done) done();
             } catch (err) {
-                node.status({ fill: "red", shape: "ring", text: err.message.substring(0, 32) });
+                node.status({ fill: "red", shape: "ring", text: statusError(err.message) });
                 if (done) done(err); else node.error(err, msg);
             }
         });

package/nodes/i3x-read.html

@@ -11,6 +11,9 @@
         <label for="node-input-elementIds"><i class="fa fa-list"></i> Element IDs</label>
         <input type="text" id="node-input-elementIds" placeholder="comma-separated element IDs">
     </div>
+    <div class="form-row">
+        <div id="i3x-read-browser"></div>
+    </div>
     <div class="form-row">
         <label for="node-input-maxDepth"><i class="fa fa-level-down"></i> Max Depth</label>
         <input type="number" id="node-input-maxDepth" placeholder="1" min="0" step="1">
@@ -37,6 +40,8 @@
     <h3>Details</h3>
     <p>Uses <code>POST /objects/value</code>. The <code>maxDepth</code> parameter controls whether
     child component values are included recursively.</p>
+    <p>Use the <b>Browse</b> button to visually select elements from the server,
+    or provide element IDs via <code>msg.elementIds</code> at runtime.</p>
 </script>
 
 <script type="text/javascript">
@@ -56,5 +61,15 @@
         label: function () {
             return this.name || this.elementIds || "i3x read";
         },
+        oneditprepare: function () {
+            if (window.I3XBrowser) {
+                this._browser = I3XBrowser.create({
+                    container: "#i3x-read-browser",
+                    serverField: "#node-input-server",
+                    targetField: "#node-input-elementIds",
+                    mode: "multi",
+                });
+            }
+        },
     });
 </script>

package/nodes/i3x-read.js

@@ -3,7 +3,7 @@
  */
 "use strict";
 
-const { bindServer, parseIds, safeSend } = require("../lib/node-utils");
+const { bindServer, parseIds, safeSend, statusError, clampMaxDepth } = require("../lib/node-utils");
 
 module.exports = function (RED) {
     function I3XReadNode(config) {
@@ -11,8 +11,7 @@ module.exports = function (RED) {
         const node = this;
 
         node.elementIds = config.elementIds || "";
-        node.maxDepth = parseInt(config.maxDepth, 10);
-        if (isNaN(node.maxDepth)) node.maxDepth = 1;
+        node.maxDepth = clampMaxDepth(config.maxDepth);
 
         if (!bindServer(node, RED, config.server)) return;
 
@@ -27,18 +26,19 @@ module.exports = function (RED) {
                 return;
             }
 
-            const maxDepth = msg.maxDepth !== undefined ? parseInt(msg.maxDepth, 10) : node.maxDepth;
+            const maxDepth = msg.maxDepth !== undefined ? clampMaxDepth(msg.maxDepth) : node.maxDepth;
 
             node.status({ fill: "blue", shape: "dot", text: "requesting..." });
 
             try {
                 const result = await client.readValues(ids, { maxDepth });
                 msg.payload = result;
-                node.status({ fill: "green", shape: "dot", text: "ok" });
+                const count = Array.isArray(result) ? result.length : 1;
+                node.status({ fill: "green", shape: "dot", text: count + " value" + (count !== 1 ? "s" : "") });
                 send(msg);
                 if (done) done();
             } catch (err) {
-                node.status({ fill: "red", shape: "ring", text: err.message.substring(0, 32) });
+                node.status({ fill: "red", shape: "ring", text: statusError(err.message) });
                 if (done) done(err); else node.error(err, msg);
             }
         });