node-red-contrib-i3x 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.0.5 (2026-06-12)
+
+Migration to the **i3X API 1.0 Release** specification (finalized 2026-06-09). See the
+[official i3X changelog](https://github.com/cesmii/i3X/blob/1.0/CHANGELOG.md) for the
+spec-side deltas this release adopts.
+
+### Breaking (spec-mandated)
+
+- **Bulk write endpoints** – `PUT /objects/{elementId}/value` and `PUT /objects/{elementId}/history`
+  were removed from the spec. `writeValue()` / `writeHistory()` now use the bulk endpoints
+  `PUT /objects/value` and `PUT /objects/history` with `{"updates": [{"elementId", "value"}]}`
+  bodies. Values are normalised to VQT objects (`{value, quality, timestamp}`); history writes
+  default missing `quality` to `"Good"` and missing `timestamp` to the current UTC time.
+- **`clientId` required on all subscription endpoints** – create, list, delete, register,
+  unregister, stream, and sync now always send a `clientId` (1.0 servers reject requests
+  without one with 400). The i3x-server config node derives a stable `clientId` from its
+  node id; it can be overridden per call or via the `I3XClient` constructor.
+- **`GET /objects/{elementId}/history` removed** – `getHistory()` is deprecated and now
+  delegates to the bulk `POST /objects/history` endpoint, returning its bulk result array.
+
+### Added
+
+- `writeValues(updates)` – bulk-write current values of multiple objects in one request
+- Sync acknowledgement – the subscribe node tracks batch `sequenceNumber`s and acknowledges
+  received updates via `lastSequenceNumber` on the next poll; `lastSequenceNumber = -1`
+  (acknowledge all) is supported by the client
+- Poll-only server support – servers may answer `/subscriptions/stream` with HTTP 501;
+  the subscribe node now detects this and falls back to sync polling automatically
+
+### Changed
+
+- Sync responses are handled in the new batched format `[{sequenceNumber, updates: [...]}]`
+  (flat pre-1.0 responses are still tolerated); the subscribe node emits the flattened updates
+- Error details are read from the new `responseDetail` envelope field (with fallback to
+  the older `problemDetail` and `error` shapes) and appended to error messages
+- Write payload sanitization now validates against the VQT fields (`value`, `quality`,
+  `timestamp`); unknown fields are rejected to avoid silent data loss
+- README and node help texts updated to the 1.0 Release endpoint set
+
+## 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:** This package targets the **i3X API 1.0 Release** (finalized 2026-06-09). The specification is stable; the next revision is not expected before the vNext working group convenes in late 2026.
 
 ## Installation
 
@@ -68,10 +68,12 @@ Write a current value or historical data to an i3X object.
 - **Target:** `value` (default) or `history` – selectable via dropdown or `msg.writeTarget`
 - **Output:** `msg.payload` – write confirmation from the API
 
-| Target    | API Endpoint                          | Payload format                        |
-| --------- | ------------------------------------- | ------------------------------------- |
-| `value`   | `PUT /objects/{elementId}/value`      | Depends on type schema (number, object, …) |
-| `history` | `PUT /objects/{elementId}/history`    | Array of VQT records `[{value, quality, timestamp}, …]` |
+| Target    | API Endpoint          | Payload format                        |
+| --------- | --------------------- | ------------------------------------- |
+| `value`   | `PUT /objects/value`  | A value or VQT object `{value, quality?, timestamp?}` |
+| `history` | `PUT /objects/history`| A VQT or array of VQT records `[{value, quality, timestamp}, …]` |
+
+Both use the i3X 1.0 bulk update format (`{updates: [{elementId, value}]}`); the node builds it for you. For history writes a missing `quality` defaults to `"Good"` and a missing `timestamp` to the current UTC time.
 
 ### i3x-history
 
@@ -85,10 +87,10 @@ Query historical time-series data.
 
 Subscribe to value changes via SSE streaming or polling.
 
-- **SSE mode:** Opens a persistent Server-Sent Events stream (`GET /subscriptions/{id}/stream`)
-- **Polling mode:** Periodically calls `POST /subscriptions/{id}/sync`
-- **Fallback:** If SSE fails, the node automatically falls back to polling
-- **Lifecycle:** Subscriptions are created on deploy and deleted on stop/re-deploy
+- **SSE mode:** Opens a persistent Server-Sent Events stream (`POST /subscriptions/stream`)
+- **Polling mode:** Periodically calls `POST /subscriptions/sync`, acknowledging received batches by sequence number
+- **Fallback:** If SSE fails — or the server returns HTTP 501 (streaming not supported) — the node automatically falls back to polling
+- **Lifecycle:** Subscriptions are created on deploy and deleted on stop/re-deploy; all calls are scoped by a `clientId` derived from the server config node (required by i3X 1.0)
 
 ## Built-in Resilience & Best Practices
 
@@ -108,30 +110,33 @@ 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):
-
-| Category  | Method | Endpoint                                     |
-| --------- | ------ | -------------------------------------------- |
-| Explore   | GET    | `/namespaces`                                |
-| Explore   | GET    | `/objecttypes`                               |
-| Explore   | POST   | `/objecttypes/query`                         |
-| Explore   | GET    | `/relationshiptypes`                         |
-| Explore   | POST   | `/relationshiptypes/query`                   |
-| Explore   | GET    | `/objects`                                   |
-| Explore   | POST   | `/objects/list`                              |
-| Explore   | POST   | `/objects/related`                           |
-| Query     | POST   | `/objects/value`                             |
-| Query     | POST   | `/objects/history`                           |
-| Update    | PUT    | `/objects/{elementId}/value`                 |
-| Update    | PUT    | `/objects/{elementId}/history`               |
-| Subscribe | GET    | `/subscriptions`                             |
-| Subscribe | POST   | `/subscriptions`                             |
-| Subscribe | GET    | `/subscriptions/{subscriptionId}`            |
-| Subscribe | DELETE | `/subscriptions/{subscriptionId}`            |
-| Subscribe | POST   | `/subscriptions/{subscriptionId}/register`   |
-| Subscribe | POST   | `/subscriptions/{subscriptionId}/unregister` |
-| Subscribe | GET    | `/subscriptions/{subscriptionId}/stream`     |
-| Subscribe | POST   | `/subscriptions/{subscriptionId}/sync`       |
+This package targets the [i3X API 1.0 Release](https://api.i3x.dev/v1/docs):
+
+| Category  | Method | Endpoint                     |
+| --------- | ------ | ---------------------------- |
+| Info      | GET    | `/info`                      |
+| Explore   | GET    | `/namespaces`                |
+| Explore   | GET    | `/objecttypes`               |
+| Explore   | POST   | `/objecttypes/query`         |
+| Explore   | GET    | `/relationshiptypes`         |
+| Explore   | POST   | `/relationshiptypes/query`   |
+| Explore   | GET    | `/objects`                   |
+| Explore   | POST   | `/objects/list`              |
+| Explore   | POST   | `/objects/related`           |
+| Query     | POST   | `/objects/value`             |
+| Query     | POST   | `/objects/history`           |
+| Update    | PUT    | `/objects/value`             |
+| Update    | PUT    | `/objects/history`           |
+| Subscribe | POST   | `/subscriptions`             |
+| Subscribe | POST   | `/subscriptions/list`        |
+| Subscribe | POST   | `/subscriptions/delete`      |
+| Subscribe | POST   | `/subscriptions/register`    |
+| Subscribe | POST   | `/subscriptions/unregister`  |
+| Subscribe | POST   | `/subscriptions/stream`      |
+| Subscribe | POST   | `/subscriptions/sync`        |
+
+All subscription requests carry the spec-required `clientId` (derived from the
+server config node), which scopes subscriptions per client.
 
 ## Example Flows
 

package/examples/i3x-complete-demo.json

@@ -601,7 +601,7 @@
         "type": "comment",
         "z": "i3x-demo-tab",
         "name": "=== 3. WRITE - Write values ===",
-        "info": "The **i3x-write** node writes a value to an i3X object.\n\n**API endpoint:** `PUT /objects/{elementId}/value`\n\n**Input:**\n- `msg.payload` - The value to write (must match the element's type schema)\n- `msg.elementId` or node property - Target element\n\n**Output:**\n- `msg.payload` - Server confirmation (`{ success, message }`)\n- `msg.elementId` - The element ID that was written to\n\n**Payload format depends on the element type:**\n- `state-type` → object: `{ description, color, type: { id, name, description }, metadata: { ... } }`\n- `measurement-value-type` / `sensor-type` → plain number (e.g. `72.5`)\n- `measurement-health-type` → integer (e.g. `95`)\n\n**Analogy:** Comparable to OPC UA Write or S7 OUT.",
+        "info": "The **i3x-write** node writes a value to an i3X object.\n\n**API endpoint:** `PUT /objects/value` (bulk update format)\n\n**Input:**\n- `msg.payload` - The value to write (must match the element's type schema)\n- `msg.elementId` or node property - Target element\n\n**Output:**\n- `msg.payload` - Server confirmation (`{ success, message }`)\n- `msg.elementId` - The element ID that was written to\n\n**Payload format depends on the element type:**\n- `state-type` → object: `{ description, color, type: { id, name, description }, metadata: { ... } }`\n- `measurement-value-type` / `sensor-type` → plain number (e.g. `72.5`)\n- `measurement-health-type` → integer (e.g. `95`)\n\n**Analogy:** Comparable to OPC UA Write or S7 OUT.",
         "x": 270,
         "y": 800,
         "wires": []
@@ -974,7 +974,7 @@
         "type": "comment",
         "z": "i3x-demo-tab",
         "name": "=== 5. SUBSCRIBE - Monitor value changes ===",
-        "info": "The **i3x-subscribe** node monitors value changes and outputs a message on each update.\n\n**Modes:**\n- **SSE** (Server-Sent Events) – Real-time stream via `GET /subscriptions/{id}/stream`\n- **Polling** – Periodic sync via `POST /subscriptions/{id}/sync`\n\n**Behaviour:**\n- Automatically creates a subscription on deploy\n- Registers the specified element IDs as monitored items\n- Automatically deletes the subscription on stop/re-deploy\n- If SSE fails, automatically falls back to polling\n\n**Analogy:** Comparable to MQTT IN or OPC UA Subscription.\n\n**Note:** This node has no input – it starts automatically on deploy.",
+        "info": "The **i3x-subscribe** node monitors value changes and outputs a message on each update.\n\n**Modes:**\n- **SSE** (Server-Sent Events) – Real-time stream via `POST /subscriptions/stream`\n- **Polling** – Periodic sync via `POST /subscriptions/sync`\n\n**Behaviour:**\n- Automatically creates a subscription on deploy\n- Registers the specified element IDs as monitored items\n- Automatically deletes the subscription on stop/re-deploy\n- If SSE fails, automatically falls back to polling\n\n**Analogy:** Comparable to MQTT IN or OPC UA Subscription.\n\n**Note:** This node has no input – it starts automatically on deploy.",
         "x": 310,
         "y": 1320,
         "wires": []

package/lib/i3x-client.js

@@ -1,10 +1,12 @@
 /**
  * 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.
+ * Wraps all REST endpoints described in the i3X OpenAPI 1.0 Release spec
+ * (released 2026-06-09). 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
+ * @see https://github.com/cesmii/i3X/blob/1.0/CHANGELOG.md
  */
 "use strict";
 
@@ -76,6 +78,8 @@ class I3XClient extends EventEmitter {
      * @param {string} [config.apiKey]
      * @param {object} [config.tlsOptions]  – { rejectUnauthorized, ca, cert, key }
      * @param {number} [config.timeout]     – ms, default 10000
+     * @param {string} [config.clientId]    – client identifier; required by the
+     *        1.0 spec on all subscription endpoints (scopes subscriptions per client)
      */
     constructor(config) {
         super();
@@ -83,6 +87,7 @@ class I3XClient extends EventEmitter {
         this.apiVersion = config.apiVersion || "";
         this.authType = config.authType || "none";
         this.timeout = config.timeout || 10000;
+        this.clientId = config.clientId || "node-red-contrib-i3x";
 
         // Warn if credentials are sent over plain HTTP (not localhost)
         if (this.authType !== "none" && this.baseUrl && !this.baseUrl.startsWith("https://")) {
@@ -118,6 +123,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 +186,18 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * @param {object} [options]
-     * @param {string}  [options.typeId]
+     * @param {object}  [options]
+     * @param {string}  [options.typeElementId] – filter by type
+     * @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 +220,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 +239,7 @@ class I3XClient extends EventEmitter {
     }
 
     /**
+     * Bulk historical values query (POST).
      * @param {string[]} elementIds
      * @param {object}   [options]
      * @param {string}   [options.startTime] – ISO 8601
@@ -226,112 +251,227 @@ 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.
+     * @deprecated The per-element `GET /objects/{elementId}/history` endpoint was
+     * removed in the 1.0 Release – this now delegates to the bulk
+     * `POST /objects/history` endpoint and returns its bulk result array.
+     * @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 = {}) {
+        return this.readHistory([elementId], options);
     }
 
-    // ── Update ─────────────────────────────────────────────────────────
+    // ── Update (1.0 Release: bulk-only endpoints) ──────────────────────
 
     /**
+     * Write the current value of a single object.
+     * Convenience wrapper around {@link writeValues}.
      * @param {string} elementId
-     * @param {*}      value
+     * @param {*}      value – primitive, or VQT object {value, quality?, timestamp?}
      */
     async writeValue(elementId, value) {
-        I3XClient._validateWritePayload(value);
-        return this._put(`/objects/${encodeURIComponent(elementId)}/value`, value);
+        return this.writeValues([{ elementId, value }]);
     }
 
     /**
+     * Bulk-write current values (PUT /objects/value).
+     * @param {Array<{elementId:string, value:*}>} updates
+     */
+    async writeValues(updates) {
+        if (!Array.isArray(updates) || updates.length === 0) {
+            throw new Error("updates must be a non-empty array of {elementId, value}");
+        }
+        const body = {
+            updates: updates.map((u) => {
+                if (!u || !u.elementId) {
+                    throw new Error("Each update requires an elementId");
+                }
+                return { elementId: u.elementId, value: I3XClient._toVQT(u.value) };
+            }),
+        };
+        return this._put("/objects/value", body);
+    }
+
+    /**
+     * Write historical values of a single object (PUT /objects/history).
+     * For history writes the spec requires full VQTs – missing quality defaults
+     * to "Good", a missing timestamp defaults to the current time (UTC).
      * @param {string} elementId
-     * @param {*}      data – historical data payload
+     * @param {*}      data – VQT object, array of VQTs, or primitive value
      */
     async writeHistory(elementId, data) {
-        I3XClient._validateWritePayload(data);
-        return this._put(`/objects/${encodeURIComponent(elementId)}/history`, data);
+        const values = Array.isArray(data)
+            ? data
+            : data && typeof data === "object" && Array.isArray(data.values)
+                ? data.values
+                : [data];
+        if (values.length === 0) {
+            throw new Error("writeHistory requires at least one value");
+        }
+        const body = {
+            updates: values.map((v) => ({
+                elementId,
+                value: I3XClient._toHistoryVQT(v),
+            })),
+        };
+        return this._put("/objects/history", body);
     }
 
-    static _WRITE_ALLOWED_FIELDS = new Set([
-        "value", "timestamp", "quality", "displayName", "attributes", "metadata",
-        "startTime", "endTime", "values", "elementId", "status",
-    ]);
+    static _VQT_FIELDS = new Set(["value", "quality", "timestamp"]);
 
-    static _validateWritePayload(payload) {
-        if (payload === null || payload === undefined) {
+    /**
+     * Normalise a raw payload into a VQTInput {value, quality?, timestamp?}.
+     * Primitives and arrays are wrapped as {value}. Objects must use only
+     * the VQT fields – anything else is rejected to avoid silent data loss.
+     * @private
+     */
+    static _toVQT(raw) {
+        if (raw === null || raw === 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 (typeof raw === "object" && !Array.isArray(raw) && "value" in raw) {
+            const disallowed = Object.keys(raw).filter((k) => !I3XClient._VQT_FIELDS.has(k));
             if (disallowed.length > 0) {
                 throw new Error("Disallowed fields in write payload: " + disallowed.join(", "));
             }
+            const vqt = { value: raw.value };
+            if (raw.quality !== undefined) vqt.quality = raw.quality;
+            if (raw.timestamp !== undefined) vqt.timestamp = raw.timestamp;
+            return vqt;
         }
+        return { value: raw };
     }
 
-    // ── Subscribe ──────────────────────────────────────────────────────
-
-    async listSubscriptions() {
-        return this._get("/subscriptions");
+    /**
+     * Like _toVQT, but fills the fields the spec requires for history writes.
+     * @private
+     */
+    static _toHistoryVQT(raw) {
+        const vqt = I3XClient._toVQT(raw);
+        if (vqt.quality === undefined) vqt.quality = "Good";
+        if (vqt.timestamp === undefined) vqt.timestamp = new Date().toISOString();
+        return vqt;
     }
 
-    /** @returns {Promise<{subscriptionId:string, message:string}>} */
-    async createSubscription() {
-        return this._post("/subscriptions", {});
+    // ── Subscribe (1.0 Release: clientId required on all endpoints) ──
+
+    /**
+     * Create a new subscription.
+     * @param {object} [options]
+     * @param {string} [options.clientId]     – overrides the client-level clientId
+     * @param {string} [options.displayName]  – optional human-readable name
+     * @returns {Promise<{subscriptionId:string, clientId?:string, displayName?:string}>}
+     */
+    async createSubscription(options = {}) {
+        const body = { clientId: options.clientId || this.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] – overrides the client-level clientId
+     */
+    async listSubscriptions(subscriptionIds, options = {}) {
+        const body = { clientId: options.clientId || this.clientId, subscriptionIds };
+        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] – overrides the client-level clientId
+     */
+    async deleteSubscriptions(subscriptionIds, options = {}) {
+        const body = { clientId: options.clientId || this.clientId, subscriptionIds };
+        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]  – overrides the client-level 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 = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+            elementIds,
+            maxDepth: options.maxDepth !== undefined ? options.maxDepth : 1,
+        };
+        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] – overrides the client-level clientId
      */
-    async unregisterMonitoredItems(subscriptionId, elementIds) {
-        const body = { elementIds };
-        return this._post(
-            `/subscriptions/${encodeURIComponent(subscriptionId)}/unregister`,
-            body
-        );
+    async unregisterMonitoredItems(subscriptionId, elementIds, options = {}) {
+        const body = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+            elementIds,
+        };
+        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 = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+        };
 
-        const url = `${this._prefix()}/subscriptions/${encodeURIComponent(subscriptionId)}/stream`;
         let controller = new AbortController();
         let closed = false;
         let reconnectCount = 0;
@@ -340,6 +480,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 +502,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,
@@ -395,6 +537,13 @@ class I3XClient extends EventEmitter {
                     if (!closed) reconnect(err);
                 });
             } catch (err) {
+                // 1.0 Release: poll-only servers SHOULD return 501 for /stream –
+                // surface it immediately so callers can fall back to /sync polling.
+                if (err.response && err.response.status === 501) {
+                    closed = true;
+                    if (onError) onError(this._wrapError(err));
+                    return;
+                }
                 if (!closed) reconnect(err);
             }
         };
@@ -424,14 +573,24 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Poll-based sync: returns and clears queued updates.
+     * Poll-based sync: acknowledge previously received updates and return pending ones.
+     * The 1.0 Release returns updates grouped into batches:
+     * [{sequenceNumber, updates: [...]}, ...]. Pass lastSequenceNumber = -1 to
+     * acknowledge and clear all pending updates in one round trip.
      * @param {string} subscriptionId
+     * @param {object} [options]
+     * @param {number} [options.lastSequenceNumber] – acknowledge events up to this sequence number
+     * @param {string} [options.clientId] – overrides the client-level clientId
      */
-    async syncSubscription(subscriptionId) {
-        return this._post(
-            `/subscriptions/${encodeURIComponent(subscriptionId)}/sync`,
-            {}
-        );
+    async syncSubscription(subscriptionId, options = {}) {
+        const body = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+        };
+        if (options.lastSequenceNumber !== undefined) {
+            body.lastSequenceNumber = options.lastSequenceNumber;
+        }
+        return this._post("/subscriptions/sync", body);
     }
 
     // ── Utility ────────────────────────────────────────────────────────
@@ -484,15 +643,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 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;
@@ -535,6 +717,13 @@ class I3XClient extends EventEmitter {
                     delete sanitized[key];
                 }
                 wrapped.body = sanitized;
+                // 1.0 Release: error details live in `responseDetail`
+                // (Beta used `problemDetail`, earlier drafts `error`)
+                const detail = body.responseDetail || body.problemDetail || body.error;
+                if (detail && typeof detail === "object") {
+                    const text = detail.detail || detail.message || detail.title;
+                    if (text) wrapped.message = `${err.message}: ${text}`;
+                }
             } else {
                 wrapped.body = body;
             }

package/nodes/i3x-server.js

@@ -22,6 +22,10 @@ module.exports = function (RED) {
             apiVersion: node.apiVersion,
             authType: node.authType,
             timeout: node.timeout,
+            // 1.0 spec: clientId is required on all subscription endpoints and
+            // scopes subscriptions per client. The config-node id is stable
+            // across restarts, so subscriptions survive a redeploy cleanly.
+            clientId: "node-red-" + node.id.replace(/\./g, "-"),
         };
 
         if (node.credentials) {

package/nodes/i3x-subscribe.html

@@ -43,11 +43,13 @@
     </dl>
 
     <h3>Details</h3>
-    <p>Creates a server-side subscription via the i3X Subscribe API and monitors the specified elements.</p>
-    <p><b>SSE mode</b> opens a persistent Server-Sent Events stream (<code>GET /subscriptions/{id}/stream</code>)
+    <p>Creates a server-side subscription via the i3X Subscribe API and monitors the specified elements.
+    Subscriptions are scoped by a <code>clientId</code> derived from the server config node (required by i3X 1.0).</p>
+    <p><b>SSE mode</b> opens a persistent Server-Sent Events stream (<code>POST /subscriptions/stream</code>)
     and emits messages in real-time as values change.</p>
-    <p><b>Polling mode</b> periodically calls <code>POST /subscriptions/{id}/sync</code> to retrieve and
-    clear queued updates. If SSE setup fails, the node automatically falls back to polling.</p>
+    <p><b>Polling mode</b> periodically calls <code>POST /subscriptions/sync</code> to retrieve queued
+    update batches; previously received batches are acknowledged via their sequence number. If SSE setup
+    fails — or the server does not support streaming (HTTP 501) — the node automatically falls back to polling.</p>
     <p>The subscription is automatically cleaned up (deleted from the server) when the node is stopped or re-deployed.</p>
     <p>Use the <b>Browse</b> button to visually select elements from the server.</p>
 </script>

package/nodes/i3x-subscribe.js

@@ -19,6 +19,7 @@ module.exports = function (RED) {
         node._sseHandle = null;
         node._pollTimer = null;
         node._closing = false;
+        node._lastSequenceNumber = undefined;
 
         if (!bindServer(node, RED, config.server)) return;
 
@@ -77,6 +78,13 @@ module.exports = function (RED) {
                 },
                 onError: (err) => {
                     if (node._closing) return;
+                    // 1.0 spec: poll-only servers return 501 for /stream
+                    if (err.statusCode === 501) {
+                        node.warn("Server does not support SSE streaming (501) – falling back to polling");
+                        node._sseHandle = null;
+                        startPolling(client);
+                        return;
+                    }
                     node.status({ fill: "red", shape: "ring", text: "stream error" });
                     node.error("SSE stream error: " + err.message);
                 },
@@ -94,9 +102,29 @@ module.exports = function (RED) {
             async function poll() {
                 if (node._closing) return;
                 try {
-                    const data = await client.syncSubscription(node._subscriptionId);
-                    if (data && (Array.isArray(data) ? data.length > 0 : Object.keys(data).length > 0)) {
-                        node.send({ payload: data, topic: "i3x/subscription" });
+                    // Acknowledge everything received so far, then fetch pending batches
+                    const opts = {};
+                    if (node._lastSequenceNumber !== undefined) {
+                        opts.lastSequenceNumber = node._lastSequenceNumber;
+                    }
+                    const batches = await client.syncSubscription(node._subscriptionId, opts);
+                    // 1.0 spec: [{sequenceNumber, updates: [...]}, ...]
+                    const updates = [];
+                    for (const batch of Array.isArray(batches) ? batches : []) {
+                        if (batch && typeof batch === "object" && Array.isArray(batch.updates)) {
+                            updates.push(...batch.updates);
+                            if (typeof batch.sequenceNumber === "number") {
+                                node._lastSequenceNumber = node._lastSequenceNumber === undefined
+                                    ? batch.sequenceNumber
+                                    : Math.max(node._lastSequenceNumber, batch.sequenceNumber);
+                            }
+                        } else if (batch !== null && batch !== undefined) {
+                            // tolerate pre-1.0 servers returning a flat update list
+                            updates.push(batch);
+                        }
+                    }
+                    if (updates.length > 0) {
+                        node.send({ payload: updates, topic: "i3x/subscription" });
                     }
                 } catch (err) {
                     if (!node._closing) {
@@ -125,7 +153,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
                 }
@@ -144,6 +172,7 @@ module.exports = function (RED) {
                 if (node._pollTimer) { clearInterval(node._pollTimer); node._pollTimer = null; }
                 if (node._sseHandle) { node._sseHandle.close(); node._sseHandle = null; }
                 node._subscriptionId = null;
+                node._lastSequenceNumber = undefined;
                 setup();
             }
         });

package/nodes/i3x-write.html

@@ -29,7 +29,10 @@
     <h3>Inputs</h3>
     <dl class="message-properties">
         <dt>payload <span class="property-type">any</span></dt>
-        <dd>The value to write. Format depends on the element type schema.</dd>
+        <dd>The value to write. Either a plain value (wrapped automatically) or a
+        VQT object <code>{value, quality, timestamp}</code>. For history writes an
+        array of VQTs writes multiple records at once; missing <code>quality</code>
+        defaults to <code>"Good"</code>, missing <code>timestamp</code> to now.</dd>
         <dt class="optional">elementId <span class="property-type">string</span></dt>
         <dd>Target element ID. Overrides the configured value. Also accepts <code>msg.nodeId</code>.</dd>
         <dt class="optional">writeTarget <span class="property-type">string</span></dt>
@@ -45,10 +48,10 @@
     </dl>
 
     <h3>Details</h3>
-    <p>When <b>Target</b> is set to <i>Current Value</i>, uses <code>PUT /objects/{elementId}/value</code>
+    <p>When <b>Target</b> is set to <i>Current Value</i>, uses <code>PUT /objects/value</code>
     to update the current value of the object.</p>
-    <p>When <b>Target</b> is set to <i>Historical Data</i>, uses <code>PUT /objects/{elementId}/history</code>
-    to write historical time-series records.</p>
+    <p>When <b>Target</b> is set to <i>Historical Data</i>, uses <code>PUT /objects/history</code>
+    to write historical time-series records (i3X 1.0 bulk update format).</p>
     <p>Use the <b>Browse</b> button to visually select the target element from the server,
     or provide the element ID via <code>msg.elementId</code> at runtime.</p>
 </script>

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.5",
   "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"
   },

package/.claude/settings.local.json

@@ -1,14 +0,0 @@
-{
-  "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)"
-    ]
-  }
-}