node-red-contrib-operx 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# node-red-contrib-operx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Un nodo «OperX» para Node-RED: envía a OperX Connect los valores de tus máquinas
+(lo que leas de Modbus, OPC UA, un PLC o un broker MQTT) y guarda en ese
+computador lo que no pueda enviar, hasta que vuelva internet.
+
+Necesita Node-RED 4 o más nuevo (Node.js 18 o más). No instala nada más.
+
+## Instalar
+
+- En Node-RED: menú › Manage palette › Install, busca «operx» e instala
+  `node-red-contrib-operx`.
+- O en una terminal, en la carpeta de Node-RED (normalmente `~/.node-red`):
+  `npm install node-red-contrib-operx`, y reinicia Node-RED.
+
+## Usar
+
+1. En OperX: Connect › Agregar dispositivo › «Node-RED u otro sistema». Copia
+   la clave que te muestra al final.
+2. En Node-RED: arrastra el nodo «OperX» (en la sección network), ábrelo y crea
+   su dispositivo con esa clave. La clave queda en el archivo de credenciales de
+   Node-RED, no en el flujo: exportar el flujo no la comparte.
+3. Únelo a lo que lea tus máquinas. Hay un ejemplo en menú › Import › Examples ›
+   node-red-contrib-operx.
+
+## Qué le llega
+
+- Un valor (`80.5`, `true`, `on`) con `msg.topic` como nombre del canal, como lo
+  trae un nodo «mqtt in»: `planta/comp2/temp`.
+- Un objeto con un nombre por canal: `{"temperatura": 80.5, "horas": 1200}`.
+  Con `msg.topic`, cada nombre va bajo el tema; sin él, los nombres son los
+  canales.
+- El JSON de OperX: `{"ts": …, "values": {…}}` o
+  `{"readings": [{"channel", "value", "time"}]}`.
+
+Una lista de números (como la de un nodo Modbus) no dice qué es cada uno:
+ponles nombre en un nodo «function». Lo que no puede leer lo dice una vez en la
+barra de depuración y debajo del nodo.
+
+## Cuánto envía
+
+- De cada canal, el primer valor de cada minuto.
+- Un dispositivo recibe hasta 100.000 valores al día: unos 69 canales a un valor
+  por minuto. Para más, otro dispositivo con su propio nodo.
+- Lo que esperó durante un corte de internet cuenta el día en que sale: un corte
+  largo puede llenar el día siguiente.
+- Guarda hasta 100.000 valores en la carpeta `operx` de Node-RED; si se llena,
+  se van los más viejos.
+- No pasa por un proxy: necesita salida directa por el puerto 443.
+
+## Para desarrollar
+
+`npm test` corre las pruebas (sin dependencias, con `node --test`).

package/examples/Enviar a OperX.json

@@ -0,0 +1,51 @@
+[
+  {
+    "id": "opx_example_tab",
+    "type": "tab",
+    "label": "Enviar a OperX",
+    "info": "Cada minuto arma los valores de tu máquina y los envía a OperX. Abre «Dispositivo de OperX» y pega la clave del dispositivo; luego cambia los valores del nodo «Tus valores» por lo que leas de Modbus u OPC UA."
+  },
+  {
+    "id": "opx_example_device",
+    "type": "operx-device",
+    "name": "Dispositivo de OperX",
+    "address": "https://api.operx.pro"
+  },
+  {
+    "id": "opx_example_tick",
+    "type": "inject",
+    "z": "opx_example_tab",
+    "name": "Cada minuto",
+    "props": [{ "p": "payload" }],
+    "repeat": "60",
+    "once": true,
+    "onceDelay": "5",
+    "topic": "",
+    "payload": "",
+    "payloadType": "date",
+    "x": 130,
+    "y": 80,
+    "wires": [["opx_example_values"]]
+  },
+  {
+    "id": "opx_example_values",
+    "type": "function",
+    "z": "opx_example_tab",
+    "name": "Tus valores",
+    "func": "// Cada nombre será un canal en OperX. Cambia estos valores por los de tu máquina.\nmsg.payload = {\n    temperatura: 80.5,\n    horas: 1200.5\n};\nreturn msg;",
+    "outputs": 1,
+    "x": 320,
+    "y": 80,
+    "wires": [["opx_example_send"]]
+  },
+  {
+    "id": "opx_example_send",
+    "type": "operx",
+    "z": "opx_example_tab",
+    "name": "OperX",
+    "device": "opx_example_device",
+    "x": 500,
+    "y": 80,
+    "wires": []
+  }
+]

package/lib/queue.js

@@ -0,0 +1,120 @@
+// What waits to go to OperX, in files under Node-RED's folder, so it survives a restart, a
+// redeploy and a day without internet. Gateways often run on an SD card, so new values are
+// appended, never the whole file rewritten each time: <name>.jsonl holds one reading a line, and
+// <name>.done how many of its first lines already left. Once enough has left, the file is written
+// again with what still waits. Refused values go to <name>.aparte.jsonl, never sent again.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// A day of a «Node-RED u otro sistema» device's limit (100,000 values a day).
+const MOST_VALUES = 100_000;
+const COMPACT_AFTER = 10_000;
+
+function linesOf(file) {
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, "utf8").split("\n").filter((line) => line.trim() !== "");
+}
+
+/** The readings of a file's lines. A line cut by a power loss reads as nothing. */
+function readingsIn(lines) {
+  const readings = [];
+  for (const line of lines) {
+    try {
+      readings.push(JSON.parse(line));
+    } catch {
+      // Cut halfway: it never reached the queue.
+    }
+  }
+  return readings;
+}
+
+function asLines(readings) {
+  return readings.map((reading) => JSON.stringify(reading) + "\n").join("");
+}
+
+class Queue {
+  constructor(folder, name, most = MOST_VALUES, compactAfter = COMPACT_AFTER) {
+    fs.mkdirSync(folder, { recursive: true });
+    this.file = path.join(folder, `${name}.jsonl`);
+    this.doneFile = path.join(folder, `${name}.done`);
+    this.asideFile = path.join(folder, `${name}.aparte.jsonl`);
+    this.most = most;
+    this.compactAfter = compactAfter;
+    this.dropped = 0;
+    this.endCutLine();
+    const lines = linesOf(this.file);
+    this.done = fs.existsSync(this.doneFile) ? Number(fs.readFileSync(this.doneFile, "utf8")) || 0 : 0;
+    this.lines = lines.length;
+    this.rows = readingsIn(lines.slice(this.done));
+    this.asideCount = linesOf(this.asideFile).length;
+  }
+
+  /** A line cut by a power loss gets its end, so the next one starts on its own line. */
+  endCutLine() {
+    if (!fs.existsSync(this.file)) return;
+    const text = fs.readFileSync(this.file, "utf8");
+    if (text && !text.endsWith("\n")) fs.appendFileSync(this.file, "\n");
+  }
+
+  add(readings) {
+    if (!readings.length) return;
+    fs.appendFileSync(this.file, asLines(readings));
+    this.rows.push(...readings);
+    this.lines += readings.length;
+    const over = this.rows.length - this.most;
+    if (over > 0) {
+      this.dropped += over;
+      this.forget(over);
+    }
+  }
+
+  oldest(count) {
+    return this.rows.slice(0, count);
+  }
+
+  /** The oldest `count` reached OperX. */
+  taken(count) {
+    this.forget(count);
+  }
+
+  /** OperX read the oldest `count` and won't take them: kept apart, never sent again. */
+  setAside(count) {
+    const refused = this.rows.slice(0, count);
+    fs.appendFileSync(this.asideFile, asLines(refused));
+    this.asideCount += refused.length;
+    this.forget(count);
+  }
+
+  forget(count) {
+    const gone = Math.min(count, this.rows.length);
+    this.rows.splice(0, gone);
+    this.done = this.lines - this.rows.length;
+    if (this.done >= this.compactAfter && this.done >= this.rows.length) {
+      this.compact();
+      return;
+    }
+    fs.writeFileSync(this.doneFile, String(this.done));
+  }
+
+  /** The file again with what still waits. The count goes back to 0 first: stopped halfway, some
+   * values are sent twice, which OperX skips (a channel's repeated time), and none is lost. */
+  compact() {
+    const temporary = `${this.file}.tmp`;
+    fs.writeFileSync(temporary, asLines(this.rows));
+    fs.writeFileSync(this.doneFile, "0");
+    fs.renameSync(temporary, this.file);
+    this.done = 0;
+    this.lines = this.rows.length;
+  }
+
+  waiting() {
+    return this.rows.length;
+  }
+
+  aside() {
+    return this.asideCount;
+  }
+}
+
+module.exports = { MOST_VALUES, Queue };

package/lib/read.js

@@ -0,0 +1,120 @@
+// What one Node-RED message says, as OperX readings. The same rules as `operx connect forward`
+// (cli/operx_cli/forwarding/read.py) and a plant broker's bridge (backend/connect/forward.py), so a
+// channel keeps its name whichever way the plant sends: msg.topic names it, and an object's keys
+// go under the topic. With no topic the keys are the names, as the Node-RED guide's flow has
+// always named them.
+
+const MAX_KEY = 100;
+const TIME_KEYS = ["taken_at", "ts", "time", "timestamp", "TS", "Time", "Timestamp"];
+const NUMBER_TEXT = /^-?\d+(\.\d+)?$/;
+const NOT_READABLE = "No es un número, true/false, on/off ni JSON.";
+const NOT_A_NUMBER = "«NaN» e «Infinity» no son números.";
+const NEEDS_TOPIC = "Un valor solo necesita msg.topic: es el nombre del canal.";
+const NAME_THE_LIST = "Una lista de números no dice qué es cada uno: ponles nombre en un nodo function, como {temperatura: msg.payload[0]}.";
+
+/** The message can't be read; its message says why, in Spanish. */
+class NotReadable extends Error {}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !Buffer.isBuffer(value);
+}
+
+/** Nested objects as dot names: {motor: {temp: 1}} gives "motor.temp". Lists inside are skipped. */
+function flatten(body, prefix = "") {
+  const pairs = [];
+  for (const [key, value] of Object.entries(body)) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    if (isObject(value)) {
+      pairs.push(...flatten(value, name));
+    } else if (!Array.isArray(value)) {
+      pairs.push([name, value]);
+    }
+  }
+  return pairs;
+}
+
+function timeOf(body) {
+  for (const key of TIME_KEYS) {
+    if (body[key] !== undefined && body[key] !== null && body[key] !== "") return body[key];
+  }
+  return undefined;
+}
+
+/** [name, value, time] of a list: {channel, value} entries, or objects of names. */
+function fromList(entries, time) {
+  const values = [];
+  for (const entry of entries) {
+    if (!isObject(entry)) throw new NotReadable(NAME_THE_LIST);
+    if ("channel" in entry) {
+      const ownTime = timeOf(entry);
+      values.push([String(entry.channel), entry.value, ownTime !== undefined ? ownTime : time]);
+    } else {
+      values.push(...fromObject(entry));
+    }
+  }
+  return values;
+}
+
+/** [name, value, time] of an object: OperX's {readings}, {ts, values}, {ts, data}, or plain names. */
+function fromObject(body) {
+  const time = timeOf(body);
+  if (Array.isArray(body.readings)) return fromList(body.readings, time);
+  if (isObject(body.values)) return flatten(body.values).map(([key, raw]) => [key, raw, time]);
+  if (time !== undefined && isObject(body.data)) return flatten(body.data).map(([key, raw]) => [key, raw, time]);
+  const rest = Object.fromEntries(Object.entries(body).filter(([key]) => !TIME_KEYS.includes(key)));
+  return flatten(rest).map(([key, raw]) => [key, raw, time]);
+}
+
+/** A message that is one value, not JSON: 80.5, true, off. undefined for anything else. */
+function bare(text) {
+  const lowered = text.toLowerCase();
+  if (lowered === "true" || lowered === "false") return lowered === "true";
+  if (lowered === "on" || lowered === "off") return text;
+  return NUMBER_TEXT.test(text) ? text : undefined;
+}
+
+function add(result, channel, raw, time) {
+  if (typeof raw === "number" && !Number.isFinite(raw)) throw new NotReadable(NOT_A_NUMBER);
+  if (channel.length > MAX_KEY) {
+    result.tooLong.push(channel);
+    return;
+  }
+  const reading = { channel, value: raw };
+  if (time !== undefined) reading.time = time;
+  result.readings.push(reading);
+}
+
+function single(result, name, value) {
+  if (!name) throw new NotReadable(NEEDS_TOPIC);
+  add(result, name, value);
+  return result;
+}
+
+function named(result, name, values) {
+  for (const [key, raw, time] of values) add(result, name ? `${name}/${key}` : key, raw, time);
+  return result;
+}
+
+/** {readings, tooLong} of a message. Throws NotReadable. */
+function readingsOf(topic, payload) {
+  const name = typeof topic === "string" ? topic.trim() : "";
+  const result = { readings: [], tooLong: [] };
+  let body = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
+  if (typeof body === "string") {
+    const text = body.trim();
+    if (!text) return result;
+    const value = bare(text);
+    if (value !== undefined) return single(result, name, value);
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new NotReadable(NOT_READABLE);
+    }
+  }
+  if (body === null || body === undefined) return result;
+  if (Array.isArray(body)) return named(result, name, fromList(body));
+  if (isObject(body)) return named(result, name, fromObject(body));
+  return single(result, name, body);
+}
+
+module.exports = { MAX_KEY, NotReadable, readingsOf };

package/lib/send.js

@@ -0,0 +1,117 @@
+// Sends what waits to the device's address, oldest first, in batches the address takes: the same
+// rules as `operx connect forward` (cli/operx_cli/forwarding/send.py). A batch leaves the queue
+// only once OperX answered: sending one again after a lost answer is safe, because the address
+// skips a channel's repeated times.
+
+const MOST_VALUES = 500;
+// The address takes up to 256 KB.
+const MOST_BYTES = 200 * 1024;
+// The address takes 60 messages a minute per key.
+const PACE_SECONDS = 1.1;
+const IDLE_SECONDS = 2;
+const FIRST_WAIT = 5;
+const LONGEST_WAIT = 300;
+const KEY_WAIT = 60;
+const LONGEST_LIMIT_WAIT = 3600;
+const TIMEOUT_MS = 30_000;
+
+/** The POST to the device's address, as a function of the body: {status, retryAfter, detail}.
+ * status null: no answer at all (no internet, a timeout, or the node stopping). */
+function httpPost(address, key, stopping) {
+  const url = `${address.replace(/\/+$/, "")}/api/v1/connect/ingest`;
+  return async function post(body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const stop = () => controller.abort();
+    stopping.addEventListener("abort", stop, { once: true });
+    try {
+      const response = await fetch(url, {
+        method: "POST", body, signal: controller.signal,
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      });
+      const retryAfter = Number.parseInt(response.headers.get("retry-after") || "", 10);
+      const answer = await response.json().catch(() => ({}));
+      const detail = answer && typeof answer.detail === "string" ? answer.detail.slice(0, 200) : "";
+      return { status: response.status, retryAfter: Number.isNaN(retryAfter) ? null : retryAfter, detail };
+    } catch {
+      return { status: null };
+    } finally {
+      clearTimeout(timer);
+      stopping.removeEventListener("abort", stop);
+    }
+  };
+}
+
+/** One batch at a time. `state` is what the node's status shows: sending, away, limit or key. */
+class Sender {
+  constructor(post, queue, say) {
+    this.post = post;
+    this.queue = queue;
+    this.say = say;
+    this.wait = FIRST_WAIT;
+    this.state = "sending";
+    this.sent = 0;
+  }
+
+  /** The oldest readings, as many as fit in one message. */
+  batch() {
+    const readings = [];
+    let size = 20;
+    for (const reading of this.queue.oldest(MOST_VALUES)) {
+      const length = Buffer.byteLength(JSON.stringify(reading)) + 1;
+      if (readings.length && size + length > MOST_BYTES) break;
+      readings.push(reading);
+      size += length;
+    }
+    return readings;
+  }
+
+  noAnswer(status) {
+    if (this.state !== "away") {
+      this.state = "away";
+      const cause = status === null ? "no responde" : `respondió ${status}`;
+      this.say(`Sin conexión: OperX ${cause}. Lo que llega se queda aquí, en orden, y sigo intentando.`);
+    }
+    const wait = this.wait;
+    this.wait = Math.min(this.wait * 2, LONGEST_WAIT);
+    return wait;
+  }
+
+  delivered(count) {
+    this.queue.taken(count);
+    this.sent += count;
+    this.wait = FIRST_WAIT;
+    if (this.state === "away") this.say("Volvió la conexión con OperX: enviando lo que esperaba, en orden.");
+    this.state = "sending";
+    return PACE_SECONDS;
+  }
+
+  /** One batch. Resolves to how many seconds to wait before the next. */
+  async sendOneBatch() {
+    const readings = this.batch();
+    if (!readings.length) return IDLE_SECONDS;
+    const answer = await this.post(JSON.stringify({ readings }));
+    const status = answer.status;
+    if (status === null || status >= 500) return this.noAnswer(status);
+    if (status >= 200 && status < 300) return this.delivered(readings.length);
+    if (status === 429) {
+      this.state = "limit";
+      const wait = Math.min(answer.retryAfter || KEY_WAIT, LONGEST_LIMIT_WAIT);
+      this.say(`OperX dice que este dispositivo pasó su límite: espero ${wait} s. ${answer.detail || ""}`.trim());
+      return wait;
+    }
+    if (status === 401 || status === 403) {
+      if (this.state !== "key") {
+        this.state = "key";
+        this.say("OperX no acepta esta clave: revísala en el dispositivo, pestaña Clave. Lo que llega se queda aquí.");
+      }
+      return KEY_WAIT;
+    }
+    // OperX read it and won't take it: sending it again would stop everything behind it.
+    this.queue.setAside(readings.length);
+    this.say(`OperX rechazó ${readings.length} valores (${status}): quedan aparte, en este computador. ${answer.detail || ""}`.trim());
+    return PACE_SECONDS;
+  }
+}
+
+module.exports = { Sender, httpPost };

package/lib/thin.js

@@ -0,0 +1,50 @@
+// One value per channel per minute is kept, before anything is saved (decision 20, as in
+// `operx connect forward`): a flow that reads every second would otherwise use a day's limit in
+// hours, and fill this computer during an outage.
+
+const KEPT_MINUTES = 120;
+
+/** "2026-11-05T14:00" of seconds or milliseconds since 1970, or undefined. */
+function epoch(number) {
+  if (typeof number !== "number" || number < 1e9) return undefined;
+  const seconds = number > 1e11 ? number / 1000 : number;
+  const date = new Date(seconds * 1000);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 16);
+}
+
+/** The minute a value belongs to: its own time's, else when it arrived (an ISO time). A time in
+ * text keeps its own clock: comparing a channel's minutes only needs them to agree. */
+function minuteOf(raw, arrival) {
+  let minute;
+  if (typeof raw === "number") {
+    minute = epoch(raw);
+  } else if (typeof raw === "string") {
+    const text = raw.trim();
+    minute = /^\d+$/.test(text) ? epoch(Number(text)) : undefined;
+    if (minute === undefined && /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}/.test(text)) minute = text.slice(0, 16).replace(" ", "T");
+  }
+  return minute || arrival.slice(0, 16);
+}
+
+/** Keeps the first value of each channel in each minute, remembering each channel's latest
+ * minutes only: a backlog comes in order, and its oldest minutes won't come again. */
+class Thinner {
+  constructor() {
+    this.kept = new Map();
+  }
+
+  keep(channel, rawTime, arrival) {
+    const minute = minuteOf(rawTime, arrival);
+    if (!this.kept.has(channel)) this.kept.set(channel, new Set());
+    const seen = this.kept.get(channel);
+    if (seen.has(minute)) return false;
+    seen.add(minute);
+    if (seen.size > KEPT_MINUTES) {
+      const oldest = [...seen].sort()[0];
+      seen.delete(oldest);
+    }
+    return true;
+  }
+}
+
+module.exports = { Thinner, minuteOf };

package/nodes/operx-device.html

@@ -0,0 +1,48 @@
+<script type="text/javascript">
+  RED.nodes.registerType("operx-device", {
+    category: "config",
+    defaults: {
+      name: { value: "" },
+      address: { value: "https://api.operx.pro", required: true },
+    },
+    credentials: {
+      key: { type: "password" },
+    },
+    label: function () {
+      return this.name || "Dispositivo de OperX";
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="operx-device">
+  <div class="form-row">
+    <label for="node-config-input-name"><i class="fa fa-tag"></i> Nombre</label>
+    <input type="text" id="node-config-input-name" placeholder="PC sala de control">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-key"><i class="fa fa-key"></i> Clave</label>
+    <input type="password" id="node-config-input-key" placeholder="opxd_…">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-address"><i class="fa fa-globe"></i> Dirección</label>
+    <input type="text" id="node-config-input-address">
+  </div>
+  <div class="form-tips">
+    La clave del dispositivo, la que OperX muestra al crearlo en Connect › Agregar dispositivo ›
+    «Node-RED u otro sistema». Queda guardada aparte del flujo: no sale cuando lo exportas.
+  </div>
+</script>
+
+<script type="text/html" data-help-name="operx-device">
+  <p>El dispositivo de OperX Connect con el que envía un nodo «OperX».</p>
+  <h3>Datos</h3>
+  <dl class="message-properties">
+    <dt>Clave <span class="property-type">texto</span></dt>
+    <dd>La del dispositivo, que empieza por <code>opxd_</code>. Sirve igual con o sin «Bearer ».
+      Node-RED la guarda en su archivo de credenciales, no en el flujo.</dd>
+    <dt>Dirección <span class="property-type">texto</span></dt>
+    <dd>La de OperX: <code>https://api.operx.pro</code>. No la cambies.</dd>
+  </dl>
+  <p>Un dispositivo por nodo «OperX»: dos nodos con la misma clave comparten su límite de 60 envíos
+    por minuto y sus valores del día.</p>
+</script>

package/nodes/operx-device.js

@@ -0,0 +1,14 @@
+// The device a flow sends as: OperX's address and the device's key. The key is a Node-RED
+// credential, kept in flows_cred.json and never in the flow, so exporting a flow never shares it.
+
+const DEFAULT_ADDRESS = "https://api.operx.pro";
+
+module.exports = function register(RED) {
+  function OperxDevice(config) {
+    RED.nodes.createNode(this, config);
+    this.name = config.name;
+    this.address = (config.address || DEFAULT_ADDRESS).trim();
+  }
+
+  RED.nodes.registerType("operx-device", OperxDevice, { credentials: { key: { type: "password" } } });
+};

package/nodes/operx.html

@@ -0,0 +1,85 @@
+<script type="text/javascript">
+  RED.nodes.registerType("operx", {
+    category: "network",
+    color: "#FCD34D",
+    defaults: {
+      name: { value: "" },
+      device: { value: "", type: "operx-device", required: true },
+    },
+    inputs: 1,
+    outputs: 0,
+    icon: "font-awesome/fa-cloud-upload",
+    align: "right",
+    paletteLabel: "OperX",
+    label: function () {
+      return this.name || "OperX";
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="operx">
+  <div class="form-row">
+    <label for="node-input-device"><i class="fa fa-key"></i> Dispositivo</label>
+    <input type="text" id="node-input-device">
+  </div>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Nombre</label>
+    <input type="text" id="node-input-name" placeholder="OperX">
+  </div>
+  <div class="form-tips">
+    Envía a OperX lo que le llega y guarda aquí lo que no pueda enviar hasta que vuelva internet.
+    Un dispositivo recibe hasta 100.000 valores al día.
+  </div>
+</script>
+
+<script type="text/html" data-help-name="operx">
+  <p>Envía a OperX Connect los valores que le llegan. Lo que no puede enviar se queda en este
+    computador, en orden, y sale cuando vuelve internet.</p>
+
+  <h3>Entradas</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">número | texto | objeto</span></dt>
+    <dd>
+      Un valor (<code>80.5</code>, <code>true</code>, <code>on</code>), o un objeto con un nombre por
+      canal (<code>{"temperatura": 80.5, "horas": 1200}</code>). También lee el JSON de OperX:
+      <code>{"ts": …, "values": {…}}</code> o <code>{"readings": [{"channel", "value", "time"}]}</code>.
+    </dd>
+    <dt class="optional">topic <span class="property-type">texto</span></dt>
+    <dd>
+      El nombre del canal para un valor solo, como lo trae un nodo «mqtt in»:
+      <code>planta/comp2/temp</code>. Con un objeto, cada nombre va bajo el tema:
+      <code>planta/comp2/temperatura</code>. Sin tema, los nombres del objeto son los canales.
+    </dd>
+  </dl>
+
+  <h3>Qué envía</h3>
+  <ul>
+    <li>De cada canal, el primer valor de cada minuto. Si el objeto trae <code>ts</code>,
+      <code>time</code> o <code>timestamp</code>, esa es su hora; si no, la de llegada.</li>
+    <li>Un dispositivo recibe hasta <b>100.000 valores al día</b>: unos 69 canales a un valor por
+      minuto. Para más, otro dispositivo con su propio nodo.</li>
+    <li>Lo que esperó durante un corte de internet cuenta el día en que sale: un corte largo puede
+      llenar el día siguiente.</li>
+  </ul>
+
+  <h3>Lo que no lee</h3>
+  <ul>
+    <li>Una lista de números, como la de un nodo Modbus: no dice qué es cada uno. Ponles nombre en
+      un nodo «function»: <code>msg.payload = {temperatura: msg.payload[0]}</code>.</li>
+    <li>Un valor solo sin <code>msg.topic</code>, y texto con unidades (<code>80,5 °C</code>).</li>
+  </ul>
+  <p>Cada caso se dice una vez en la barra de depuración y debajo del nodo.</p>
+
+  <h3>Si se cae internet</h3>
+  <p>Guarda hasta 100.000 valores en la carpeta <code>operx</code> de Node-RED (un día del límite del
+    dispositivo); si se llena, se van los más viejos. Sobrevive a un Deploy y a reiniciar Node-RED.
+    No pasa por un proxy: necesita salida directa a internet por el puerto 443.</p>
+
+  <h3>Debajo del nodo</h3>
+  <ul>
+    <li><b>enviados N · en espera N</b>: todo bien.</li>
+    <li><b>sin conexión</b>: OperX no responde; sigue intentando, cada vez más espaciado.</li>
+    <li><b>OperX no acepta la clave</b>: fue revocada o no es de este dispositivo.</li>
+    <li><b>pasó su límite del día</b>: espera y sigue después.</li>
+  </ul>
+</script>

package/nodes/operx.js

@@ -0,0 +1,129 @@
+// «OperX»: sends what reaches it to OperX Connect, keeping one value per channel per minute, and
+// keeps what can't go yet in a file until the internet comes back (CONNECT_SPEC.md › OperX Agent,
+// step 2). Reading never waits for the internet: a message is saved at once, and a loop sends.
+
+const path = require("node:path");
+const { MAX_KEY, NotReadable, readingsOf } = require("../lib/read");
+const { Thinner } = require("../lib/thin");
+const { Queue } = require("../lib/queue");
+const { Sender, httpPost } = require("../lib/send");
+
+// A problem with a message shows under the node this long, then the counts come back.
+const PROBLEM_SHOWN_MS = 60_000;
+// Each topic's problem is said once; a flow that publishes thousands must not flood the log.
+const MOST_TOLD = 1000;
+
+/** The device's key as pasted, with or without «Bearer ». "" when it isn't one. */
+function cleanKey(text) {
+  const key = String(text || "").trim().replace(/^Bearer\s+/i, "").trim();
+  return key.startsWith("opxd_") ? key : "";
+}
+
+function thousands(count) {
+  return String(count).replace(/\B(?=(\d{3})+(?!\d))/g, ".");
+}
+
+/** Waits `seconds`, or less if the node stops meanwhile. */
+function pause(seconds, stopping) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, seconds * 1000);
+    stopping.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+module.exports = function register(RED) {
+  function Operx(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const device = RED.nodes.getNode(config.device);
+    const key = cleanKey(device && device.credentials && device.credentials.key);
+    if (!device || !key) {
+      node.status({ fill: "red", shape: "ring", text: "falta la clave del dispositivo" });
+      node.on("input", (_msg, _send, done) => done());
+      return;
+    }
+
+    const stopping = new AbortController();
+    const queue = new Queue(path.join(RED.settings.userDir || ".", "operx"), node.id);
+    const thin = new Thinner();
+    const told = new Set();
+    let problem = null;
+    // Shutting down aborts the request in flight: that isn't a lost connection to tell about.
+    const say = (line) => {
+      if (!stopping.signal.aborted) node.warn(line);
+    };
+    const sender = new Sender(httpPost(device.address, key, stopping.signal), queue, say);
+
+    function showStatus() {
+      const waiting = thousands(queue.waiting());
+      if (sender.state === "key") return node.status({ fill: "red", shape: "ring", text: "OperX no acepta la clave" });
+      if (sender.state === "away") return node.status({ fill: "yellow", shape: "ring", text: `sin conexión · ${waiting} en espera` });
+      if (sender.state === "limit") return node.status({ fill: "yellow", shape: "ring", text: `pasó su límite del día · ${waiting} en espera` });
+      if (problem && Date.now() - problem.at < PROBLEM_SHOWN_MS) return node.status({ fill: "yellow", shape: "dot", text: problem.text });
+      return node.status({ fill: "green", shape: "dot", text: `enviados ${thousands(sender.sent)} · en espera ${waiting}` });
+    }
+
+    function tellOnce(topic, text) {
+      problem = { text: text.slice(0, 80), at: Date.now() };
+      if (!told.has(topic) && told.size < MOST_TOLD) {
+        told.add(topic);
+        node.warn(text);
+      }
+    }
+
+    node.on("input", (msg, _send, done) => {
+      const arrival = new Date().toISOString();
+      const topic = typeof msg.topic === "string" ? msg.topic : "";
+      let result;
+      try {
+        result = readingsOf(topic, msg.payload);
+      } catch (error) {
+        if (!(error instanceof NotReadable)) return done(error);
+        tellOnce(topic, topic ? `«${topic.slice(0, 200)}»: ${error.message}` : error.message);
+        showStatus();
+        return done();
+      }
+      for (const name of result.tooLong) tellOnce(name, `«${name.slice(0, 200)}» pasa los ${MAX_KEY} caracteres que puede tener el nombre de un canal.`);
+      // Every value goes with a time: what waits through an outage keeps its minute.
+      const stamped = result.readings.map((reading) => ("time" in reading ? reading : { ...reading, time: arrival }));
+      const kept = stamped.filter((reading) => thin.keep(reading.channel, reading.time, arrival));
+      try {
+        queue.add(kept);
+      } catch (error) {
+        return done(error);
+      }
+      showStatus();
+      return done();
+    });
+
+    async function sendForever() {
+      while (!stopping.signal.aborted) {
+        let seconds;
+        try {
+          seconds = await sender.sendOneBatch();
+        } catch (error) {
+          node.error(`No pude enviar ni guardar: ${error.message}`);
+          seconds = 5;
+        }
+        showStatus();
+        await pause(seconds, stopping.signal);
+      }
+    }
+
+    showStatus();
+    if (queue.waiting()) node.log(`Hay ${thousands(queue.waiting())} valores de antes: salen primero.`);
+    const sending = sendForever();
+
+    // Each Deploy closes this node and starts a new one on the same files: stop sending, end the
+    // request in flight, and only then let the new one start. The queue is already on disk.
+    node.on("close", (_removed, done) => {
+      stopping.abort();
+      sending.then(() => done(), () => done());
+    });
+  }
+
+  RED.nodes.registerType("operx", Operx);
+};

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "node-red-contrib-operx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Envía a OperX Connect los valores de tus máquinas, y guarda lo que no salga hasta que vuelva internet.",
+  "author": "OperX",
+  "homepage": "https://operx.pro",
+  "license": "UNLICENSED",
+  "keywords": ["node-red", "operx", "iot", "mantenimiento", "connect"],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["nodes", "lib", "examples", "README.md"],
+  "scripts": {
+    "test": "node --test"
+  },
+  "node-red": {
+    "version": ">=4.0.0",
+    "nodes": {
+      "operx-device": "nodes/operx-device.js",
+      "operx": "nodes/operx.js"
+    }
+  }
+}