node-red-contrib-i3x 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.0.4 (2026-04-12)
+
+Migration to i3X API 1.0-Beta specification with enhanced query capabilities and improved API alignment.
+
+### Added
+
+- **Server Info Endpoint** – New `getInfo()` method retrieves server metadata (spec version, server version, capabilities) from `GET /info` endpoint with TTL caching
+- **Single-Object History Query** – New `getHistory(elementId, options)` method for `GET /objects/{elementId}/history` endpoint
+- **Partial Response Handling** – History queries now detect HTTP 206 status and set `_partial: true` flag on results when server returns incomplete data
+- **Root Objects Filter** – `getObjects()` now supports `root: true` parameter to retrieve only root-level objects
+- **Enhanced Subscribe Options** – Subscribe node now supports `maxDepth`, `includeMetadata`, and `returnMode` parameters for fine-grained control
+
+### Changed
+
+- **API Version Update** – Updated from i3X v0.0.1 to 1.0-Beta specification
+- **API Documentation URL** – Changed from `https://i3x.cesmii.net/docs` to `https://api.i3x.dev/v1/docs`
+- **Parameter Naming** – `typeId` parameter renamed to `typeElementId` in `getObjects()` (legacy `typeId` still supported as alias)
+- **Relationship Type Parameter** – Fixed casing from `relationshiptype` to `relationshipType` in `getRelatedObjects()`
+- **History Query Implementation** – `getHistoryBulk()` now uses `_requestRaw()` to access HTTP status codes for partial response detection
+
+### Tests
+
+- Updated all test cases to reflect 1.0-Beta API changes
+- Added tests for new `getInfo()` endpoint
+- Added tests for single-object history query
+- Added tests for partial response handling (HTTP 206)
+- Updated integration tests for new parameter names
+
 ## 0.0.3 (2026-03-10)
 
 Hardening, security improvements, and new browser widget features.

package/README.md

@@ -4,7 +4,7 @@ Node-RED nodes for the **i3X** (Industrial Information Interoperability eXchange
 
 i3X is an open, vendor-agnostic REST API specification for standardised access to contextualised manufacturing information platforms (Historians, MES, MOM, etc.).
 
-> **Note:** The i3X API is currently in **pre-alpha (v0)**. Response structures may change as the specification evolves.
+> **Note:** The i3X API is currently in **beta (v1.0-Beta)**. Response structures may change as the specification evolves.
 
 ## Installation
 
@@ -108,10 +108,11 @@ The shared HTTP client (`lib/i3x-client.js`) implements all [i3X Client Develope
 
 ## API Endpoints Used
 
-This package targets the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs):
+This package targets the [i3X API 1.0-Beta](https://api.i3x.dev/v1/docs):
 
 | Category  | Method | Endpoint                                     |
 | --------- | ------ | -------------------------------------------- |
+| Info      | GET    | `/info`                                      |
 | Explore   | GET    | `/namespaces`                                |
 | Explore   | GET    | `/objecttypes`                               |
 | Explore   | POST   | `/objecttypes/query`                         |
@@ -121,6 +122,7 @@ This package targets the [i3X API Prototype v0.0.1](https://api.i3x.dev/v0/docs)
 | Explore   | POST   | `/objects/list`                              |
 | Explore   | POST   | `/objects/related`                           |
 | Query     | POST   | `/objects/value`                             |
+| Query     | GET    | `/objects/{elementId}/history`               |
 | Query     | POST   | `/objects/history`                           |
 | Update    | PUT    | `/objects/{elementId}/value`                 |
 | Update    | PUT    | `/objects/{elementId}/history`               |

package/lib/i3x-client.js

@@ -1,10 +1,10 @@
 /**
  * I3XClient – Shared HTTP client for the i3X (CESMII) API.
  *
- * Wraps all REST endpoints described in the i3X OpenAPI v0.0.1 spec.
+ * Wraps all REST endpoints described in the i3X OpenAPI 1.0-Beta spec.
  * Used by every node-red-contrib-i3x node via the i3x-server config node.
  *
- * @see https://i3x.cesmii.net/docs
+ * @see https://api.i3x.dev/v1/docs
  */
 "use strict";
 
@@ -118,6 +118,21 @@ class I3XClient extends EventEmitter {
         this._rateLimiter = new RateLimiter();
     }
 
+    // ── Server Info ──────────────────────────────────────────────────────
+
+    /**
+     * Retrieve server information (no authentication required).
+     * @returns {Promise<{specVersion:string, serverVersion:string, serverName:string, capabilities:object}>}
+     */
+    async getInfo() {
+        const cacheKey = "info";
+        const cached = this._cache.get(cacheKey);
+        if (cached) return cached;
+        const result = await this._get("/info");
+        this._cache.set(cacheKey, result);
+        return result;
+    }
+
     // ── Explore ────────────────────────────────────────────────────────
 
     /** @returns {Promise<Array<{uri:string, displayName:string}>>} */
@@ -166,14 +181,18 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * @param {object} [options]
-     * @param {string}  [options.typeId]
+     * @param {object}  [options]
+     * @param {string}  [options.typeElementId] – filter by type (Beta spec name)
+     * @param {string}  [options.typeId]        – legacy alias for typeElementId
      * @param {boolean} [options.includeMetadata]
+     * @param {boolean} [options.root]          – return only root objects
      */
     async getObjects(options = {}) {
         const params = {};
-        if (options.typeId) params.typeId = options.typeId;
+        const typeFilter = options.typeElementId || options.typeId;
+        if (typeFilter) params.typeElementId = typeFilter;
         if (options.includeMetadata) params.includeMetadata = true;
+        if (options.root) params.root = true;
         return this._get("/objects", params);
     }
 
@@ -196,7 +215,7 @@ class I3XClient extends EventEmitter {
      */
     async getRelatedObjects(elementIds, options = {}) {
         const body = { elementIds };
-        if (options.relationshipType) body.relationshiptype = options.relationshipType;
+        if (options.relationshipType) body.relationshipType = options.relationshipType;
         if (options.includeMetadata) body.includeMetadata = true;
         return this._post("/objects/related", body);
     }
@@ -215,6 +234,7 @@ class I3XClient extends EventEmitter {
     }
 
     /**
+     * Bulk historical values query (POST).
      * @param {string[]} elementIds
      * @param {object}   [options]
      * @param {string}   [options.startTime] – ISO 8601
@@ -226,7 +246,37 @@ class I3XClient extends EventEmitter {
         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);
+        const res = await this._requestRaw("post", "/objects/history", { data: body });
+        const result = I3XClient._unwrapEnvelope(res.data);
+        if (res.status === 206) {
+            result._partial = true;
+        }
+        return result;
+    }
+
+    /**
+     * Single-object historical values query (GET).
+     * @param {string} elementId
+     * @param {object} [options]
+     * @param {string} [options.startTime] – ISO 8601
+     * @param {string} [options.endTime]   – ISO 8601
+     * @param {number} [options.maxDepth]
+     */
+    async getHistory(elementId, options = {}) {
+        const params = {};
+        if (options.startTime) params.startTime = options.startTime;
+        if (options.endTime) params.endTime = options.endTime;
+        if (options.maxDepth !== undefined) params.maxDepth = options.maxDepth;
+        const res = await this._requestRaw(
+            "get",
+            `/objects/${encodeURIComponent(elementId)}/history`,
+            { params }
+        );
+        const result = I3XClient._unwrapEnvelope(res.data);
+        if (res.status === 206) {
+            result._partial = true;
+        }
+        return result;
     }
 
     // ── Update ─────────────────────────────────────────────────────────
@@ -267,71 +317,106 @@ class I3XClient extends EventEmitter {
         }
     }
 
-    // ── Subscribe ──────────────────────────────────────────────────────
-
-    async listSubscriptions() {
-        return this._get("/subscriptions");
-    }
+    // ── Subscribe (Beta-Spec: body-based endpoints) ──────────────────
 
-    /** @returns {Promise<{subscriptionId:string, message:string}>} */
-    async createSubscription() {
-        return this._post("/subscriptions", {});
+    /**
+     * Create a new subscription.
+     * @param {object} [options]
+     * @param {string} [options.clientId]     – optional client identifier
+     * @param {string} [options.displayName]  – optional human-readable name
+     * @returns {Promise<{subscriptionId:string, clientId?:string, displayName?:string}>}
+     */
+    async createSubscription(options = {}) {
+        const body = {};
+        if (options.clientId) body.clientId = options.clientId;
+        if (options.displayName) body.displayName = options.displayName;
+        return this._post("/subscriptions", body);
     }
 
-    /** @param {string} subscriptionId */
-    async getSubscription(subscriptionId) {
-        return this._get(`/subscriptions/${encodeURIComponent(subscriptionId)}`);
+    /**
+     * List subscriptions by IDs.
+     * @param {string[]} subscriptionIds
+     * @param {object}   [options]
+     * @param {string}   [options.clientId]
+     */
+    async listSubscriptions(subscriptionIds, options = {}) {
+        const body = { subscriptionIds };
+        if (options.clientId) body.clientId = options.clientId;
+        return this._post("/subscriptions/list", body);
     }
 
-    /** @param {string} subscriptionId */
-    async deleteSubscription(subscriptionId) {
-        return this._delete(`/subscriptions/${encodeURIComponent(subscriptionId)}`);
+    /**
+     * Delete one or more subscriptions.
+     * @param {string[]} subscriptionIds
+     * @param {object}   [options]
+     * @param {string}   [options.clientId]
+     */
+    async deleteSubscriptions(subscriptionIds, options = {}) {
+        const body = { subscriptionIds };
+        if (options.clientId) body.clientId = options.clientId;
+        return this._post("/subscriptions/delete", body);
     }
 
     /**
+     * Register monitored items on a subscription.
      * @param {string}   subscriptionId
      * @param {string[]} elementIds
-     * @param {number}   [maxDepth]
+     * @param {object}   [options]
+     * @param {number}   [options.maxDepth]  – default 1
+     * @param {string}   [options.clientId]
      */
-    async registerMonitoredItems(subscriptionId, elementIds, maxDepth = 1) {
-        const body = { elementIds, maxDepth };
-        return this._post(
-            `/subscriptions/${encodeURIComponent(subscriptionId)}/register`,
-            body
-        );
+    async registerMonitoredItems(subscriptionId, elementIds, options = {}) {
+        // Support legacy positional maxDepth: registerMonitoredItems(id, ids, 2)
+        if (typeof options === "number") {
+            options = { maxDepth: options };
+        }
+        const body = { subscriptionId, elementIds, maxDepth: options.maxDepth !== undefined ? options.maxDepth : 1 };
+        if (options.clientId) body.clientId = options.clientId;
+        return this._post("/subscriptions/register", body);
     }
 
     /**
+     * Unregister monitored items from a subscription.
      * @param {string}   subscriptionId
      * @param {string[]} elementIds
+     * @param {object}   [options]
+     * @param {string}   [options.clientId]
      */
-    async unregisterMonitoredItems(subscriptionId, elementIds) {
-        const body = { elementIds };
-        return this._post(
-            `/subscriptions/${encodeURIComponent(subscriptionId)}/unregister`,
-            body
-        );
+    async unregisterMonitoredItems(subscriptionId, elementIds, options = {}) {
+        const body = { subscriptionId, elementIds };
+        if (options.clientId) body.clientId = options.clientId;
+        return this._post("/subscriptions/unregister", body);
     }
 
     /**
-     * Open an SSE stream for the given subscription.
+     * Open an SSE stream for the given subscription (POST).
      * 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.onError] – called on stream errors
      * @param {function} [callbacks.onReconnect] – called when a reconnection attempt starts
-     * @param {number}   [maxReconnects=5] – max consecutive reconnection attempts
+     * @param {object}   [options]
+     * @param {string}   [options.clientId]
+     * @param {number}   [options.maxReconnects=5]
      * @returns {{ close: function }} handle to close the stream
      */
-    streamSubscription(subscriptionId, callbacks, maxReconnects = 5) {
+    streamSubscription(subscriptionId, callbacks, options = {}) {
         if (typeof callbacks === "function") {
             callbacks = { onData: callbacks };
         }
+        // Support legacy positional maxReconnects number
+        if (typeof options === "number") {
+            options = { maxReconnects: options };
+        }
         const { onData, onError, onReconnect } = callbacks;
+        const maxReconnects = options.maxReconnects !== undefined ? options.maxReconnects : 5;
+
+        const url = `${this._prefix()}/subscriptions/stream`;
+        const postBody = { subscriptionId };
+        if (options.clientId) postBody.clientId = options.clientId;
 
-        const url = `${this._prefix()}/subscriptions/${encodeURIComponent(subscriptionId)}/stream`;
         let controller = new AbortController();
         let closed = false;
         let reconnectCount = 0;
@@ -340,6 +425,7 @@ class I3XClient extends EventEmitter {
             ...this.http.defaults.headers.common,
             ...this.http.defaults.headers,
             Accept: "text/event-stream",
+            "Content-Type": "application/json",
         };
         // Remove non-header axios defaults that got spread in
         delete headers.common;
@@ -361,8 +447,9 @@ class I3XClient extends EventEmitter {
             try {
                 controller = new AbortController();
                 const response = await axios({
-                    method: "get",
+                    method: "post",
                     url,
+                    data: postBody,
                     headers,
                     responseType: "stream",
                     signal: controller.signal,
@@ -424,14 +511,19 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Poll-based sync: returns and clears queued updates.
+     * Poll-based sync: acknowledge previously received updates and return pending ones.
      * @param {string} subscriptionId
+     * @param {object} [options]
+     * @param {number} [options.lastSequenceNumber] – acknowledge events up to this sequence number
+     * @param {string} [options.clientId]
      */
-    async syncSubscription(subscriptionId) {
-        return this._post(
-            `/subscriptions/${encodeURIComponent(subscriptionId)}/sync`,
-            {}
-        );
+    async syncSubscription(subscriptionId, options = {}) {
+        const body = { subscriptionId };
+        if (options.lastSequenceNumber !== undefined) {
+            body.lastSequenceNumber = options.lastSequenceNumber;
+        }
+        if (options.clientId) body.clientId = options.clientId;
+        return this._post("/subscriptions/sync", body);
     }
 
     // ── Utility ────────────────────────────────────────────────────────
@@ -484,15 +576,38 @@ class I3XClient extends EventEmitter {
 
     /**
      * Central request dispatcher with retry logic, Retry-After support, and rate limiting.
+     * Returns unwrapped result data. Use _requestRaw for full response access.
      * @private
      */
     async _request(method, path, opts = {}) {
+        const res = await this._requestRaw(method, path, opts);
+        return I3XClient._unwrapEnvelope(res.data);
+    }
+
+    /**
+     * Unwrap the Beta-Spec response envelope if present.
+     * SuccessResponse: {success, result} → result
+     * BulkResponse:    {success, results} → results
+     * @private
+     */
+    static _unwrapEnvelope(data) {
+        if (data && typeof data === "object" && data.success === true) {
+            if ("result" in data) return data.result;
+            if ("results" in data) return data.results;
+        }
+        return data;
+    }
+
+    /**
+     * Central request dispatcher returning the full axios response.
+     * @private
+     */
+    async _requestRaw(method, path, opts = {}) {
         await this._rateLimiter.acquire();
         let lastErr;
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             try {
-                const res = await this.http.request({ method, url: path, ...opts });
-                return res.data;
+                return await this.http.request({ method, url: path, ...opts });
             } catch (err) {
                 lastErr = err;
                 const status = err.response && err.response.status;

package/nodes/i3x-subscribe.js

@@ -125,7 +125,7 @@ module.exports = function (RED) {
 
             if (node._subscriptionId && node.server && node.server.client) {
                 try {
-                    await node.server.client.deleteSubscription(node._subscriptionId);
+                    await node.server.client.deleteSubscriptions([node._subscriptionId]);
                 } catch (_) {
                     // best-effort cleanup
                 }

package/nodes/icons/i3x-icon.svg

@@ -1,11 +1,4 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40" width="40" height="40">
   <rect width="40" height="40" rx="4" fill="#2E8B57"/>
-  <text x="20" y="16" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" font-weight="bold" fill="white">i3X</text>
-  <line x1="8" y1="22" x2="32" y2="22" stroke="white" stroke-width="1.5" stroke-linecap="round"/>
-  <circle cx="12" cy="30" r="3" fill="none" stroke="white" stroke-width="1.5"/>
-  <circle cx="20" cy="30" r="3" fill="none" stroke="white" stroke-width="1.5"/>
-  <circle cx="28" cy="30" r="3" fill="none" stroke="white" stroke-width="1.5"/>
-  <line x1="12" y1="27" x2="12" y2="22" stroke="white" stroke-width="1.5"/>
-  <line x1="20" y1="27" x2="20" y2="22" stroke="white" stroke-width="1.5"/>
-  <line x1="28" y1="27" x2="28" y2="22" stroke="white" stroke-width="1.5"/>
+  <text x="20" y="26" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="white">i3X</text>
 </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-i3x",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Node-RED nodes for the i3X (Industrial Information Interoperability eXchange) API by CESMII",
   "keywords": [
     "node-red",
@@ -27,13 +27,13 @@
     "test:docker": "docker compose run --rm test"
   },
   "dependencies": {
-    "axios": "^1.7.0"
+    "axios": "^1.15.0"
   },
   "devDependencies": {
-    "mocha": "^10.0.0",
+    "mocha": "^11.0.0",
     "chai": "^4.0.0",
-    "sinon": "^17.0.0",
-    "nock": "^13.0.0",
+    "sinon": "^21.0.0",
+    "nock": "^14.0.0",
     "node-red": "^3.0.0",
     "node-red-node-test-helper": "^0.3.0"
   },