node-red-contrib-i3x 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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.

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 **beta (v1.0-Beta)**. 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,32 +110,33 @@ The shared HTTP client (`lib/i3x-client.js`) implements all [i3X Client Develope
 
 ## API Endpoints Used
 
-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`                         |
-| Explore   | GET    | `/relationshiptypes`                         |
-| Explore   | POST   | `/relationshiptypes/query`                   |
-| Explore   | GET    | `/objects`                                   |
-| 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`               |
-| 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 1.0-Beta 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://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://")) {
@@ -182,7 +187,7 @@ class I3XClient extends EventEmitter {
 
     /**
      * @param {object}  [options]
-     * @param {string}  [options.typeElementId] – filter by type (Beta spec name)
+     * @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
@@ -255,7 +260,10 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Single-object historical values query (GET).
+     * 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
@@ -263,72 +271,112 @@ class I3XClient extends EventEmitter {
      * @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;
+        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 };
+    }
+
+    /**
+     * 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;
     }
 
-    // ── Subscribe (Beta-Spec: body-based endpoints) ──────────────────
+    // ── Subscribe (1.0 Release: clientId required on all endpoints) ──
 
     /**
      * Create a new subscription.
      * @param {object} [options]
-     * @param {string} [options.clientId]     – optional client identifier
+     * @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 = {};
-        if (options.clientId) body.clientId = options.clientId;
+        const body = { clientId: options.clientId || this.clientId };
         if (options.displayName) body.displayName = options.displayName;
         return this._post("/subscriptions", body);
     }
@@ -337,11 +385,10 @@ class I3XClient extends EventEmitter {
      * List subscriptions by IDs.
      * @param {string[]} subscriptionIds
      * @param {object}   [options]
-     * @param {string}   [options.clientId]
+     * @param {string}   [options.clientId] – overrides the client-level clientId
      */
     async listSubscriptions(subscriptionIds, options = {}) {
-        const body = { subscriptionIds };
-        if (options.clientId) body.clientId = options.clientId;
+        const body = { clientId: options.clientId || this.clientId, subscriptionIds };
         return this._post("/subscriptions/list", body);
     }
 
@@ -349,11 +396,10 @@ class I3XClient extends EventEmitter {
      * Delete one or more subscriptions.
      * @param {string[]} subscriptionIds
      * @param {object}   [options]
-     * @param {string}   [options.clientId]
+     * @param {string}   [options.clientId] – overrides the client-level clientId
      */
     async deleteSubscriptions(subscriptionIds, options = {}) {
-        const body = { subscriptionIds };
-        if (options.clientId) body.clientId = options.clientId;
+        const body = { clientId: options.clientId || this.clientId, subscriptionIds };
         return this._post("/subscriptions/delete", body);
     }
 
@@ -363,15 +409,19 @@ class I3XClient extends EventEmitter {
      * @param {string[]} elementIds
      * @param {object}   [options]
      * @param {number}   [options.maxDepth]  – default 1
-     * @param {string}   [options.clientId]
+     * @param {string}   [options.clientId]  – overrides the client-level clientId
      */
     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;
+        const body = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+            elementIds,
+            maxDepth: options.maxDepth !== undefined ? options.maxDepth : 1,
+        };
         return this._post("/subscriptions/register", body);
     }
 
@@ -380,11 +430,14 @@ class I3XClient extends EventEmitter {
      * @param {string}   subscriptionId
      * @param {string[]} elementIds
      * @param {object}   [options]
-     * @param {string}   [options.clientId]
+     * @param {string}   [options.clientId] – overrides the client-level clientId
      */
     async unregisterMonitoredItems(subscriptionId, elementIds, options = {}) {
-        const body = { subscriptionId, elementIds };
-        if (options.clientId) body.clientId = options.clientId;
+        const body = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+            elementIds,
+        };
         return this._post("/subscriptions/unregister", body);
     }
 
@@ -414,8 +467,10 @@ class I3XClient extends EventEmitter {
         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 postBody = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+        };
 
         let controller = new AbortController();
         let closed = false;
@@ -482,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);
             }
         };
@@ -512,17 +574,22 @@ class I3XClient extends EventEmitter {
 
     /**
      * 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]
+     * @param {string} [options.clientId] – overrides the client-level clientId
      */
     async syncSubscription(subscriptionId, options = {}) {
-        const body = { subscriptionId };
+        const body = {
+            clientId: options.clientId || this.clientId,
+            subscriptionId,
+        };
         if (options.lastSequenceNumber !== undefined) {
             body.lastSequenceNumber = options.lastSequenceNumber;
         }
-        if (options.clientId) body.clientId = options.clientId;
         return this._post("/subscriptions/sync", body);
     }
 
@@ -585,7 +652,7 @@ class I3XClient extends EventEmitter {
     }
 
     /**
-     * Unwrap the Beta-Spec response envelope if present.
+     * Unwrap the spec response envelope if present.
      * SuccessResponse: {success, result} → result
      * BulkResponse:    {success, results} → results
      * @private
@@ -650,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) {
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-i3x",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Node-RED nodes for the i3X (Industrial Information Interoperability eXchange) API by CESMII",
   "keywords": [
     "node-red",

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)"
-    ]
-  }
-}