node-red-contrib-i3x 0.0.1

package/lib/i3x-client.js

@@ -0,0 +1,425 @@
+/**
+ * I3XClient – Shared HTTP client for the i3X (CESMII) API.
+ *
+ * Wraps all REST endpoints described in the i3X OpenAPI v0.0.1 spec.
+ * Used by every node-red-contrib-i3x node via the i3x-server config node.
+ *
+ * @see https://i3x.cesmii.net/docs
+ */
+"use strict";
+
+const axios = require("axios");
+const { EventEmitter } = require("events");
+
+const RETRY_STATUS_CODES = new Set([429, 502, 503, 504]);
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+
+class I3XClient extends EventEmitter {
+    /**
+     * @param {object} config
+     * @param {string} config.baseUrl       – e.g. "https://i3x.cesmii.net"
+     * @param {string} [config.apiVersion]  – path prefix, default ""
+     * @param {string} [config.authType]    – "none"|"basic"|"bearer"|"apikey"
+     * @param {string} [config.username]
+     * @param {string} [config.password]
+     * @param {string} [config.token]
+     * @param {string} [config.apiKey]
+     * @param {object} [config.tlsOptions]  – { rejectUnauthorized, ca, cert, key }
+     * @param {number} [config.timeout]     – ms, default 10000
+     */
+    constructor(config) {
+        super();
+        this.baseUrl = (config.baseUrl || "").replace(/\/+$/, "");
+        this.apiVersion = config.apiVersion || "";
+        this.authType = config.authType || "none";
+        this.timeout = config.timeout || 10000;
+
+        const axiosConfig = {
+            baseURL: this._prefix(),
+            timeout: this.timeout,
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+        };
+
+        if (this.authType === "basic" && config.username) {
+            axiosConfig.auth = { username: config.username, password: config.password || "" };
+        } else if (this.authType === "bearer" && config.token) {
+            axiosConfig.headers["Authorization"] = `Bearer ${config.token}`;
+        } else if (this.authType === "apikey" && config.apiKey) {
+            axiosConfig.headers["X-API-Key"] = config.apiKey;
+        }
+
+        if (config.tlsOptions) {
+            const https = require("https");
+            axiosConfig.httpsAgent = new https.Agent(config.tlsOptions);
+        }
+
+        this.http = axios.create(axiosConfig);
+        this._activeSubscriptions = new Map();
+    }
+
+    // ── Explore ────────────────────────────────────────────────────────
+
+    /** @returns {Promise<Array<{uri:string, displayName:string}>>} */
+    async getNamespaces() {
+        return this._get("/namespaces");
+    }
+
+    /**
+     * @param {object} [options]
+     * @param {string} [options.namespaceUri]
+     */
+    async getObjectTypes(options = {}) {
+        const params = {};
+        if (options.namespaceUri) params.namespaceUri = options.namespaceUri;
+        return this._get("/objecttypes", params);
+    }
+
+    /** @param {string[]} elementIds */
+    async queryObjectTypes(elementIds) {
+        return this._post("/objecttypes/query", { elementIds });
+    }
+
+    /**
+     * @param {object} [options]
+     * @param {string} [options.namespaceUri]
+     */
+    async getRelationshipTypes(options = {}) {
+        const params = {};
+        if (options.namespaceUri) params.namespaceUri = options.namespaceUri;
+        return this._get("/relationshiptypes", params);
+    }
+
+    /** @param {string[]} elementIds */
+    async queryRelationshipTypes(elementIds) {
+        return this._post("/relationshiptypes/query", { elementIds });
+    }
+
+    /**
+     * @param {object} [options]
+     * @param {string}  [options.typeId]
+     * @param {boolean} [options.includeMetadata]
+     */
+    async getObjects(options = {}) {
+        const params = {};
+        if (options.typeId) params.typeId = options.typeId;
+        if (options.includeMetadata) params.includeMetadata = true;
+        return this._get("/objects", params);
+    }
+
+    /**
+     * @param {string[]} elementIds
+     * @param {object}   [options]
+     * @param {boolean}  [options.includeMetadata]
+     */
+    async listObjects(elementIds, options = {}) {
+        const body = { elementIds };
+        if (options.includeMetadata) body.includeMetadata = true;
+        return this._post("/objects/list", body);
+    }
+
+    /**
+     * @param {string[]} elementIds
+     * @param {object}   [options]
+     * @param {string}   [options.relationshipType]
+     * @param {boolean}  [options.includeMetadata]
+     */
+    async getRelatedObjects(elementIds, options = {}) {
+        const body = { elementIds };
+        if (options.relationshipType) body.relationshiptype = options.relationshipType;
+        if (options.includeMetadata) body.includeMetadata = true;
+        return this._post("/objects/related", body);
+    }
+
+    // ── Query ──────────────────────────────────────────────────────────
+
+    /**
+     * @param {string[]} elementIds
+     * @param {object}   [options]
+     * @param {number}   [options.maxDepth] – 0 = infinite, 1 = no recursion
+     */
+    async readValues(elementIds, options = {}) {
+        const body = { elementIds };
+        if (options.maxDepth !== undefined) body.maxDepth = options.maxDepth;
+        return this._post("/objects/value", body);
+    }
+
+    /**
+     * @param {string[]} elementIds
+     * @param {object}   [options]
+     * @param {string}   [options.startTime] – ISO 8601
+     * @param {string}   [options.endTime]   – ISO 8601
+     * @param {number}   [options.maxDepth]
+     */
+    async readHistory(elementIds, options = {}) {
+        const body = { elementIds };
+        if (options.startTime) body.startTime = options.startTime;
+        if (options.endTime) body.endTime = options.endTime;
+        if (options.maxDepth !== undefined) body.maxDepth = options.maxDepth;
+        return this._post("/objects/history", body);
+    }
+
+    // ── Update ─────────────────────────────────────────────────────────
+
+    /**
+     * @param {string} elementId
+     * @param {*}      value
+     */
+    async writeValue(elementId, value) {
+        return this._put(`/objects/${encodeURIComponent(elementId)}/value`, value);
+    }
+
+    /**
+     * @param {string} elementId
+     * @param {*}      data – historical data payload
+     */
+    async writeHistory(elementId, data) {
+        return this._put(`/objects/${encodeURIComponent(elementId)}/history`, data);
+    }
+
+    // ── Subscribe ──────────────────────────────────────────────────────
+
+    async listSubscriptions() {
+        return this._get("/subscriptions");
+    }
+
+    /** @returns {Promise<{subscriptionId:string, message:string}>} */
+    async createSubscription() {
+        return this._post("/subscriptions", {});
+    }
+
+    /** @param {string} subscriptionId */
+    async getSubscription(subscriptionId) {
+        return this._get(`/subscriptions/${encodeURIComponent(subscriptionId)}`);
+    }
+
+    /** @param {string} subscriptionId */
+    async deleteSubscription(subscriptionId) {
+        return this._delete(`/subscriptions/${encodeURIComponent(subscriptionId)}`);
+    }
+
+    /**
+     * @param {string}   subscriptionId
+     * @param {string[]} elementIds
+     * @param {number}   [maxDepth]
+     */
+    async registerMonitoredItems(subscriptionId, elementIds, maxDepth = 1) {
+        const body = { elementIds, maxDepth };
+        return this._post(
+            `/subscriptions/${encodeURIComponent(subscriptionId)}/register`,
+            body
+        );
+    }
+
+    /**
+     * @param {string}   subscriptionId
+     * @param {string[]} elementIds
+     */
+    async unregisterMonitoredItems(subscriptionId, elementIds) {
+        const body = { elementIds };
+        return this._post(
+            `/subscriptions/${encodeURIComponent(subscriptionId)}/unregister`,
+            body
+        );
+    }
+
+    /**
+     * Open an SSE stream for the given subscription.
+     * Supports automatic reconnection on stream errors.
+     *
+     * @param {string}   subscriptionId
+     * @param {object}   callbacks
+     * @param {function} callbacks.onData  – called with each parsed SSE event
+     * @param {function} [callbacks.onError] – called on stream errors (instead of EventEmitter)
+     * @param {function} [callbacks.onReconnect] – called when a reconnection attempt starts
+     * @param {number}   [maxReconnects=5] – max consecutive reconnection attempts
+     * @returns {{ close: function }} handle to close the stream
+     */
+    streamSubscription(subscriptionId, callbacks, maxReconnects = 5) {
+        if (typeof callbacks === "function") {
+            callbacks = { onData: callbacks };
+        }
+        const { onData, onError, onReconnect } = callbacks;
+
+        const url = `${this._prefix()}/subscriptions/${encodeURIComponent(subscriptionId)}/stream`;
+        let controller = new AbortController();
+        let closed = false;
+        let reconnectCount = 0;
+
+        const headers = { ...this.http.defaults.headers.common, Accept: "text/event-stream" };
+        if (this.http.defaults.auth) {
+            const b64 = Buffer.from(
+                `${this.http.defaults.auth.username}:${this.http.defaults.auth.password}`
+            ).toString("base64");
+            headers["Authorization"] = `Basic ${b64}`;
+        }
+
+        const connect = async () => {
+            if (closed) return;
+            try {
+                controller = new AbortController();
+                const response = await axios({
+                    method: "get",
+                    url,
+                    headers,
+                    responseType: "stream",
+                    signal: controller.signal,
+                    timeout: 0,
+                    httpsAgent: this.http.defaults.httpsAgent,
+                });
+                reconnectCount = 0;
+                let buffer = "";
+                response.data.on("data", (chunk) => {
+                    buffer += chunk.toString();
+                    const parts = buffer.split("\n\n");
+                    buffer = parts.pop();
+                    for (const part of parts) {
+                        const dataLine = part
+                            .split("\n")
+                            .find((l) => l.startsWith("data:"));
+                        if (dataLine) {
+                            try {
+                                onData(JSON.parse(dataLine.slice(5).trim()));
+                            } catch (_) {
+                                onData(dataLine.slice(5).trim());
+                            }
+                        }
+                    }
+                });
+                response.data.on("end", () => {
+                    if (!closed) reconnect();
+                });
+                response.data.on("error", (err) => {
+                    if (!closed) reconnect(err);
+                });
+            } catch (err) {
+                if (!closed) reconnect(err);
+            }
+        };
+
+        const reconnect = (err) => {
+            if (closed) return;
+            reconnectCount++;
+            if (reconnectCount > maxReconnects) {
+                if (onError) onError(err || new Error("Max reconnection attempts reached"));
+                return;
+            }
+            if (onReconnect) onReconnect(reconnectCount);
+            const delay = Math.min(1000 * Math.pow(2, reconnectCount - 1), 30000);
+            setTimeout(connect, delay);
+        };
+
+        connect();
+
+        const handle = {
+            close: () => {
+                closed = true;
+                controller.abort();
+            },
+        };
+        this._activeSubscriptions.set(subscriptionId, handle);
+        return handle;
+    }
+
+    /**
+     * Poll-based sync: returns and clears queued updates.
+     * @param {string} subscriptionId
+     */
+    async syncSubscription(subscriptionId) {
+        return this._post(
+            `/subscriptions/${encodeURIComponent(subscriptionId)}/sync`,
+            {}
+        );
+    }
+
+    // ── Utility ────────────────────────────────────────────────────────
+
+    /**
+     * Lightweight connectivity test.
+     * Uses GET /namespaces as health indicator.
+     */
+    async testConnection() {
+        await this._get("/namespaces");
+        return true;
+    }
+
+    /** Close all active SSE streams and clean up. */
+    destroy() {
+        for (const [, handle] of this._activeSubscriptions) {
+            handle.close();
+        }
+        this._activeSubscriptions.clear();
+    }
+
+    // ── Internal helpers ───────────────────────────────────────────────
+
+    /** @private */
+    _prefix() {
+        const ver = this.apiVersion ? `/${this.apiVersion.replace(/^\//, "")}` : "";
+        return `${this.baseUrl}${ver}`;
+    }
+
+    /** @private */
+    async _get(path, params) {
+        return this._request("get", path, { params });
+    }
+
+    /** @private */
+    async _post(path, data) {
+        return this._request("post", path, { data });
+    }
+
+    /** @private */
+    async _put(path, data) {
+        return this._request("put", path, { data });
+    }
+
+    /** @private */
+    async _delete(path) {
+        return this._request("delete", path);
+    }
+
+    /**
+     * Central request dispatcher with retry logic.
+     * @private
+     */
+    async _request(method, path, opts = {}) {
+        let lastErr;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const res = await this.http.request({ method, url: path, ...opts });
+                return res.data;
+            } catch (err) {
+                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);
+                    await new Promise((r) => setTimeout(r, delay));
+                    continue;
+                }
+                throw this._wrapError(err);
+            }
+        }
+        throw this._wrapError(lastErr);
+    }
+
+    /**
+     * Produce a normalised error object.
+     * @private
+     */
+    _wrapError(err) {
+        if (err._i3x) return err;
+        const wrapped = new Error(err.message);
+        wrapped._i3x = true;
+        if (err.response) {
+            wrapped.statusCode = err.response.status;
+            wrapped.statusText = err.response.statusText;
+            wrapped.body = err.response.data;
+        } else if (err.code) {
+            wrapped.code = err.code;
+        }
+        return wrapped;
+    }
+}
+
+module.exports = I3XClient;

package/lib/node-utils.js

@@ -0,0 +1,61 @@
+/**
+ * Shared utilities for i3x Node-RED nodes.
+ * Eliminates boilerplate for server binding and status management.
+ */
+"use strict";
+
+/**
+ * Bind an operation node to its i3x-server config node.
+ * Sets up connection status indicators and returns false if no server is configured.
+ *
+ * @param {object} node  – the Node-RED node instance
+ * @param {object} RED   – the Node-RED runtime
+ * @param {string} serverId – config.server
+ * @returns {boolean} true if server is available, false otherwise
+ */
+function bindServer(node, RED, serverId) {
+    node.server = RED.nodes.getNode(serverId);
+
+    if (!node.server) {
+        node.status({ fill: "red", shape: "ring", text: "no server configured" });
+        return false;
+    }
+
+    node.server.on("connected", () => {
+        node.status({ fill: "green", shape: "dot", text: "connected" });
+    });
+    node.server.on("disconnected", () => {
+        node.status({ fill: "red", shape: "ring", text: "disconnected" });
+    });
+
+    if (node.server.connected) {
+        node.status({ fill: "green", shape: "dot", text: "connected" });
+    }
+
+    return true;
+}
+
+/**
+ * Parse a value that may be a comma-separated string or an array into an array of strings.
+ * @param {string|string[]} input
+ * @returns {string[]}
+ */
+function parseIds(input) {
+    if (Array.isArray(input)) return input;
+    if (typeof input === "string") {
+        return input.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    return [];
+}
+
+/**
+ * Backwards-compatible send helper for Node-RED < 1.0.
+ * @param {object} node
+ * @param {function|undefined} send
+ * @returns {function}
+ */
+function safeSend(node, send) {
+    return send || function () { node.send.apply(node, arguments); };
+}
+
+module.exports = { bindServer, parseIds, safeSend };

package/nodes/i3x-browse.html

@@ -0,0 +1,106 @@
+<script type="text/html" data-template-name="i3x-browse">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+        <input type="text" id="node-input-server">
+    </div>
+    <div class="form-row">
+        <label for="node-input-browseTarget"><i class="fa fa-sitemap"></i> Target</label>
+        <select id="node-input-browseTarget">
+            <option value="namespaces">Namespaces</option>
+            <option value="objecttypes">Object Types</option>
+            <option value="relationshiptypes">Relationship Types</option>
+            <option value="objects">Objects</option>
+            <option value="related">Related Objects</option>
+        </select>
+    </div>
+    <div class="form-row i3x-browse-elementId">
+        <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-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">
+    </div>
+    <div class="form-row i3x-browse-ns">
+        <label for="node-input-namespaceUri"><i class="fa fa-folder-o"></i> Namespace</label>
+        <input type="text" id="node-input-namespaceUri" placeholder="optional – filter by namespace URI">
+    </div>
+    <div class="form-row i3x-browse-rel">
+        <label for="node-input-relationshipType"><i class="fa fa-link"></i> Rel. Type</label>
+        <input type="text" id="node-input-relationshipType" placeholder="optional – filter by relationship type">
+    </div>
+    <div class="form-row i3x-browse-meta">
+        <label for="node-input-includeMetadata"><i class="fa fa-info-circle"></i> Metadata</label>
+        <input type="checkbox" id="node-input-includeMetadata" style="width:auto;">
+        <span> Include full metadata</span>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="i3x-browse">
+    <p>Explores the i3X information model – namespaces, object types, relationship types, objects, and related objects.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt class="optional">browseTarget <span class="property-type">string</span></dt>
+        <dd>What to browse: <code>namespaces</code>, <code>objecttypes</code>, <code>relationshiptypes</code>, <code>objects</code>, or <code>related</code>.</dd>
+        <dt class="optional">elementId <span class="property-type">string | string[]</span></dt>
+        <dd>One or more element IDs to query directly.</dd>
+        <dt class="optional">typeId <span class="property-type">string</span></dt>
+        <dd>Filter objects by type ID (only for <code>objects</code> target).</dd>
+        <dt class="optional">namespaceUri <span class="property-type">string</span></dt>
+        <dd>Filter by namespace URI (for <code>objecttypes</code> / <code>relationshiptypes</code>).</dd>
+        <dt class="optional">relationshipType <span class="property-type">string</span></dt>
+        <dd>Filter related objects by relationship type.</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">array</span></dt>
+        <dd>Array of discovered objects matching the browse criteria.</dd>
+    </dl>
+
+    <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>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("i3x-browse", {
+        category: "i3x",
+        color: "#5DB87C",
+        defaults: {
+            name: { value: "" },
+            server: { value: "", type: "i3x-server", required: true },
+            browseTarget: { value: "objects" },
+            elementId: { value: "" },
+            typeId: { value: "" },
+            namespaceUri: { value: "" },
+            includeMetadata: { value: false },
+            relationshipType: { value: "" },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "i3x-icon.svg",
+        paletteLabel: "i3x browse",
+        label: function () {
+            return this.name || this.browseTarget || "i3x browse";
+        },
+        oneditprepare: function () {
+            var target = $("#node-input-browseTarget");
+            function toggle() {
+                var v = target.val();
+                $(".i3x-browse-elementId").toggle(v !== "namespaces");
+                $(".i3x-browse-typeId").toggle(v === "objects");
+                $(".i3x-browse-ns").toggle(v === "objecttypes" || v === "relationshiptypes");
+                $(".i3x-browse-rel").toggle(v === "related");
+                $(".i3x-browse-meta").toggle(v === "objects" || v === "related");
+            }
+            target.on("change", toggle);
+            toggle();
+        },
+    });
+</script>

package/nodes/i3x-browse.js

@@ -0,0 +1,93 @@
+/**
+ * i3x-browse – Explore namespaces, object types, objects, and relationships.
+ */
+"use strict";
+
+const { bindServer, safeSend } = require("../lib/node-utils");
+
+module.exports = function (RED) {
+    function I3XBrowseNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        node.browseTarget = config.browseTarget || "objects";
+        node.elementId = config.elementId || "";
+        node.typeId = config.typeId || "";
+        node.namespaceUri = config.namespaceUri || "";
+        node.includeMetadata = config.includeMetadata || false;
+        node.relationshipType = config.relationshipType || "";
+
+        if (!bindServer(node, RED, config.server)) return;
+
+        node.on("input", async function (msg, send, done) {
+            send = safeSend(node, send);
+            const client = node.server.client;
+
+            const target = msg.browseTarget || node.browseTarget;
+            const elementId = 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..." });
+
+            try {
+                let result;
+                switch (target) {
+                    case "namespaces":
+                        result = await client.getNamespaces();
+                        break;
+                    case "objecttypes":
+                        if (elementId) {
+                            const ids = Array.isArray(elementId) ? elementId : [elementId];
+                            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];
+                            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];
+                            result = await client.listObjects(ids, { includeMetadata: inclMeta });
+                        } else {
+                            result = await client.getObjects({ typeId: typeId || undefined, includeMetadata: inclMeta });
+                        }
+                        break;
+                    case "related":
+                        if (!elementId) {
+                            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,
+                            });
+                        }
+                        break;
+                    default:
+                        throw new Error("Unknown browse target: " + target);
+                }
+
+                msg.payload = result;
+                node.status({ fill: "green", shape: "dot", text: "ok" });
+                send(msg);
+                if (done) done();
+            } catch (err) {
+                node.status({ fill: "red", shape: "ring", text: err.message.substring(0, 32) });
+                if (done) done(err); else node.error(err, msg);
+            }
+        });
+    }
+
+    RED.nodes.registerType("i3x-browse", I3XBrowseNode);
+};