data-solectrus 0.2.10

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,32 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm-publish
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm run lint
+
+      - name: Publish to NPM
+        run: npm publish --provenance --access public

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+## 0.2.9 - 2026-01-31
+
+### Changed
+
+- **BREAKING:** Package renamed from `iobroker.data-solectrus` to `data-solectrus` for NPM namespace compatibility
+- Enabled GitHub Actions automated publishing via Trusted Publishing (OIDC)
+
+## 0.2.8 - 2026-01-31
+
+### Changed
+
+- Official NPM release with automated publishing via GitHub Actions
+- Added NPM version and download badges to README
+- Configured trusted publisher for secure automated releases
+- Restructured info states: 6 core + hierarchical diagnostics (diagnostics.*, diagnostics.timing.*)
+
+## 0.2.7 - 2026-01-30
+
+### Added
+
+- New sync diagnostics under `info.*`: input timestamp gap telemetry (`info.inputTsGapMs`, `info.inputTsGapOk`, `info.inputTsGapThresholdMs`, `info.inputTsSources`, `info.inputTsMissing`).
+- Expanded sync diagnostics: active-only gap and culprit helpers (`info.inputTsGapActiveMs`, `info.inputTsSleepingSources`, `info.inputTsOldestId`, `info.inputTsOldestAgeMs`).
+- Runtime setting to enable/disable the input timestamp gap diagnostics (`enableInputTsGapDiagnostics`).
+- New deterministic regression check script: `npm run check:simulate` (30s / 6 ticks) to validate PV + signed grid meter scenarios.
+
+### Changed
+
+- Admin UI: clearer wording + tooltip for “Ergebnis negativ → 0” (mode-aware hint: source vs formula).
+- Docs: README + Wiki updated to clarify output clamp vs per-input clamp.
+
+### Fixed
+
+- Formula evaluation: item-level `noNegative` no longer clamps negative *inputs* (important for signed meters where export is negative). Only per-input `noNegative` clamps that input; item-level `noNegative` clamps the final result.
+- Source mode: output datatype handling corrected (string/boolean/mixed items no longer force numeric parsing; primitives are mirrored correctly).
+- Sync diagnostics robustness: initial reads now populate the timestamp cache so `info.inputTsGap*` works immediately after startup.
+
+## 0.2.6 - 2026-01-29
+- **Info states structure**: Reorganized `info.*` states for better readability and logical grouping (Variante D):
+  - Core states: `info.status`, `info.itemsActive`, `info.lastError`, `info.lastRun`, `info.lastRunMs`
+  - Diagnostics moved to: `info.diagnostics.*` (eval stats) and `info.diagnostics.timing.*` (timestamp skew)
+  - Old info states are automatically cleaned up on adapter restart
+  - Renamed: `evalTimeMs` → `lastRunMs`, `itemsEnabled` → `itemsActive`, `itemsConfigured` → `diagnostics.itemsTotal`
+
+### Added
+
+- Admin UI: Formula Builder popup for building formulas with a palette (operators/functions/state pickers).
+- Admin UI: Live input values inside the builder (polling while popup is open).
+- Admin UI: Local in-browser formula preview pill (updates automatically while popup is open).
+
+### Fixed
+
+- Admin UI: Builder crash on open (runtime error in custom UI script).
+- Admin UI: Formula Builder live values now respect JSONPath and input clamping (neg→0) in the preview.
+
+## 0.2.5 - 2026-01-29
+
+### Changed
+
+- Internal refactor: extracted formula parsing/evaluation and JSONPath helpers into separate modules under `lib/` to keep `main.js` smaller and easier to maintain.
+- No functional changes intended.
+
+## 0.2.4 - 2026-01-29
+
+### Added
+
+- Subscription management hardening: subscriptions are now derived from enabled items and kept in sync (unsubscribe removed ids). A global cap prevents runaway subscription counts.
+- Tick time budget to avoid long ticks piling up; new telemetry states: `info.timeBudgetMs` and `info.skippedItems`.
+
+### Fixed
+
+- Output type consistency: formula results are no longer forced numeric for `string`/`boolean`/`mixed` outputs.
+- Fallback after repeated errors is now type-appropriate (e.g. `''` for string outputs instead of `'0'`).
+
+## 0.2.3 - 2026-01-29
+
+### Fixed
+
+- Formula inputs with JSONPath can now yield strings/booleans (not only numbers). This enables conditions like `IF(opMode == 'Heating', ..., 0)` when `opMode` is an input extracted from a JSON payload.
+	- Numeric-like strings (e.g. `"12.2"`) are still treated as numbers to keep strict comparisons (`===`) working as expected.
+
+## 0.2.2 - 2026-01-29
+
+### Added
+
+- New formula helper `jp("state.id", "jsonPath")` to read primitive values (string/number/boolean) from JSON payload states via the built-in minimal JSONPath.
+	- This enables conditions like `IF(jp("...", "$['Operation Mode']") == 'Heating', ..., 0)` without requiring separate input states.
+- Per-item diagnostics states under `data-solectrus.0.items.<outputId>.*`:
+	- `compiledOk`, `compileError`, `lastError`, `lastOkTs`, `lastEvalMs`, `consecutiveErrors`.
+
+### Changed
+
+- Robust tick behavior: formula/compile/snapshot failures no longer stop the adapter; errors are handled per item.
+- Fallback behavior on errors: keep the last good value for a few retries, then set the output to `0` (config key `errorRetriesBeforeZero`, default: 3).
+- Performance: formulas are compiled once per item (normalized expression + AST) and reused during ticks; snapshot/subscriptions use compiled source ids.
+- Config change detection: when items change without restart, the adapter rebuilds compiled caches on the next tick.
+
+## 0.2.1 - 2026-01-29
+
+### Added
+
+- Formula function `IF(condition, valueIfTrue, valueIfFalse)` (alias: `if(...)`).
+- Helper `v("state.id")` to read raw foreign state values (string/boolean/number) from cache/snapshot.
+- Compatibility normalization in formulas (outside strings): `AND`/`OR`/`NOT` and single `=`.
+
+### Changed
+
+- Expression engine: re-introduced `==` and `!=` for compatibility with existing formula styles (use `===`/`!==` when you want strict matching).
+- `s("...")` / `v("...")` state ids are now discovered from formulas and included in snapshot/subscriptions.
+
+## 0.2.0 - 2026-01-29
+
+### Added
+
+- Formula function `pow(a, b)` (use this instead of an exponent operator).
+- One-time debug logs for blocked dangerous input keys and for skipped JSONPath when the source value is already numeric.
+
+### Changed
+
+- Security hardening: formula input variables use a null-prototype map and block dangerous keys (`__proto__`, `prototype`, `constructor`).
+- Expression engine: removed support for `**` and for loose equality operators `==` / `!=` (use `===` / `!==`).
+- Bounded internal "log once" caches to avoid unbounded growth.
+
+## 0.1.22 - 2026-01-28
+
+### Added
+
+- Optional JSON extraction for `source` items and formula inputs via **JSONPath (optional)** (e.g. `$.apower`, `$.aenergy.by_minute[2]`).
+
+### Changed
+
+- Wiki/README updated: JSON payloads no longer require a separate alias/script when JSONPath is configured.
+- When `Datatype` is set to `boolean` or `string`, the adapter now writes real booleans/strings to the output state (not 0/1).
+
+### Notes
+
+- JSONPath support is intentionally limited (dot access, bracket keys, array indexes). Unsupported expressions fall back to `0` and log a warning once.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sven Griese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# ioBroker.Data-SOLECTRUS
+
+![Version](https://img.shields.io/github/package-json/v/Felliglanz/data-solectrus?label=version)
+![NPM Version](https://img.shields.io/npm/v/data-solectrus?label=npm)
+![NPM Downloads](https://img.shields.io/npm/dt/data-solectrus)
+
+<img src="admin/data-solectrus.png" alt="SOLECTRUS" width="120" />
+
+Ein kleiner ioBroker-Adapter, der eigene States unter `data-solectrus.0.*` anlegt und im festen Intervall (Standard: 5s, **wall-clock aligned**) mit berechneten oder gespiegelten Werten befüllt.
+
+Kurz gesagt: 🧮 **Formeln** + 🔌 **beliebige ioBroker-States** → 📦 **saubere, adapter-eigene Ziel-States** (z.B. für SOLECTRUS-Dashboards).
+
+## 📑 Inhaltsverzeichnis
+
+- [✨ Highlights](#-highlights)
+- [📦 Installation](#-installation)
+- [🚀 Quickstart](#-quickstart)
+- [⚡ Wichtige Semantik (Vorzeichen & Clamps)](#-wichtige-semantik-vorzeichen--clamps)
+- [📚 Wiki & Anwendungsbeispiele](#-wiki--anwendungsbeispiele)
+- [📊 Diagnose-States](#-diagnose-states)
+- [🔧 Entwicklung & Tests](#-entwicklung--tests)
+- [⚙️ Konfiguration](#-konfiguration)
+- [🧮 Formeln](#-formeln)
+
+## ✨ Highlights
+
+- 🔗 **Quell-Items**: 1:1 spiegeln (optional mit JSONPath)
+- 🧮 **Formel-Items**: Werte aus vielen Quellen zusammenrechnen
+- 📸 **Snapshot-Modus**: Reduziert Timing-Effekte bei zeitversetzten Quell-Updates
+- 🎚️ **Ergebnis-Regeln**: Clamps am Ergebnis (z.B. negativ → 0, Min/Max)
+- 📊 **Diagnose-States**: Laufzeit, Fehler und Sync-Statistiken
+
+## 📦 Installation
+
+Der Adapter kann lokal als `.tgz` gebaut und in ioBroker installiert werden (oder via GitHub-Release, falls vorhanden).
+
+- Paket bauen: `npm pack`
+- Installation in ioBroker: Admin → Adapter → „Benutzerdefiniert" / URL/Datei → `data-solectrus-<version>.tgz` (z.B. `data-solectrus-0.2.9.tgz`)
+- Oder direkt von NPM: `npm install data-solectrus`
+
+Hinweis: Adaptername in ioBroker ist `data-solectrus` (Instanz: `data-solectrus.0`).
+
+## 🚀 Quickstart
+
+Der Adapter ist absichtlich „leer" – du legst nur die Werte an, die du brauchst.
+
+### 1️⃣ Werte anlegen
+**Admin → Adapter → data-solectrus → Werte**
+
+- **Modus „Quelle"**: Genau einen State 1:1 spiegeln
+- **Modus „Formel"**: Mehrere Inputs zusammenrechnen
+
+### 2️⃣ Snapshot aktivieren (optional)
+**Globale Einstellungen**
+
+Wenn deine Quellen zeitversetzt updaten und du kurzzeitig unplausible Kombinationen siehst, aktiviere den Snapshot-Modus.
+
+## ⚡ Wichtige Semantik (Vorzeichen & Clamps)
+
+### Ergebnis negativ → 0
+
+Die Option **„Ergebnis negativ → 0“** wirkt nur auf das **Ergebnis** des Items (Output).
+
+- Wenn du nur einzelne Inputs bereinigen willst (z.B. PV darf nie negativ sein, aber Netzleistung ist signed), nutze dafür pro Input **„neg→0“** oder `max(0, …)` in der Formel.
+
+### Beispiel: Hausverbrauch aus PV + signed Netzleistung
+
+- `gridSigned`: Import positiv, Export negativ
+- Hausverbrauch: `pvTotal + gridSigned`
+
+Wenn PV=4639W und Export=-2514W, ergibt sich Hausverbrauch ≈ 2125W.
+
+## 📚 Wiki & Anwendungsbeispiele
+
+Ausführliche Beispiele und Erklärungen findest du im Wiki:  
+👉 https://github.com/Felliglanz/data-solectrus/wiki
+
+**Direktlinks:**
+
+- 🏠 [Hausverbrauch berechnen](https://github.com/Felliglanz/data-solectrus/wiki/Hausverbrauch)
+- 🎚️ [Werte begrenzen](https://github.com/Felliglanz/data-solectrus/wiki/Werte-begrenzen)
+- 🔧 [Formel-Builder nutzen](https://github.com/Felliglanz/data-solectrus/wiki/Formel-Builder)
+- 📖 [Alle Anwendungsfälle](https://github.com/Felliglanz/data-solectrus/wiki/Use-Cases)
+
+## 📊 Diagnose-States
+
+Der Adapter legt strukturierte States unter `data-solectrus.0.info.*` an:
+
+### 🎯 Kern-Infos (immer sichtbar)
+
+- `info.connection` – Standard ioBroker Verbindungsstatus
+- `info.itemsActive` – Anzahl aktivierter Werte
+- `info.lastError` – Letzter Fehler (leer wenn alles OK)
+- `info.lastRun` – Zeitstempel letzter Durchlauf (ISO 8601)
+- `info.lastRunMs` – Dauer letzter Durchlauf (ms)
+- `info.status` – Adapter-Status (`starting`, `ok`, `no_items_enabled`)
+
+### 🔍 Diagnose (eingeklappt im Objektbaum)
+
+**`info.diagnostics.*`**
+
+- `evalBudgetMs` – Verfügbare Zeit pro Durchlauf (ms)
+- `evalSkipped` – Übersprungene Werte im letzten Durchlauf
+- `itemsTotal` – Gesamtzahl konfigurierter Werte (aktiv + inaktiv)
+
+**`info.diagnostics.timing.*`** *(Timestamp-Analyse für zeitversetzte Quellen)*
+
+- `gapMs` – Differenz zwischen ältestem und neuestem Eingabe-Zeitstempel (ms)
+- `gapOk` – ✅ wenn Differenz unter Schwellwert
+- `gapActiveMs` – Differenz nur für aktive Quellen (ms)
+- `gapActiveOk` – ✅ wenn aktive Differenz unter Schwellwert
+- `sources` – Anzahl Eingaben mit Zeitstempel
+- `sourcesActive` – Anzahl aktiver Eingaben (kürzlich aktualisiert)
+- `sourcesSleeping` – Anzahl schlafender Eingaben (alte Zeitstempel)
+- `oldestId` – State-ID mit ältestem Zeitstempel
+- `oldestAgeMs` – Alter der ältesten Eingabe (ms)
+- `newestId` – State-ID mit neuestem Zeitstempel
+- `newestAgeMs` – Alter der neuesten Eingabe (ms)
+
+### 📈 Pro-Wert Diagnose
+
+Unter `data-solectrus.0.items.<outputId>.*`:
+
+- `compiledOk` – ✅ Kompilierung erfolgreich
+- `compileError` – Kompilierungs-Fehler (leer bei OK)
+- `lastError` – Letzter Laufzeit-Fehler
+- `lastOkTs` – Zeitstempel letzte erfolgreiche Berechnung
+- `lastEvalMs` – Dauer letzte Berechnung (ms)
+- `consecutiveErrors` – Anzahl aufeinanderfolgender Fehler
+
+## 🔧 Entwicklung & Tests
+
+Für schnelle Checks (z.B. nach Refactorings) gibt es einen Runtime-Smoke-Test, der **ohne** ioBroker-Controller läuft.
+Er mockt die minimal benötigte Adapter-API und führt einmalig diese Phasen aus:
+
+- `cleanupOldInfoStates()` (räumt alte Struktur auf)
+- `createInfoStates()` (legt neue Struktur an)
+- `prepareItems()` (inkl. Formel-Compile, Source-Discovery, Subscriptions)
+- `runTick()` (ein Tick mit Snapshot + Berechnung + Output-States)
+
+Ausführen:
+
+- `npm run smoke`
+
+## ⚙️ Konfiguration
+
+Die Konfiguration ist absichtlich **leer** – du fügst nur die Werte hinzu, die du brauchst.
+
+### 🌍 Globale Einstellungen
+
+**⏱️ Aktualisierungs-Intervall**
+- Intervall in Sekunden (min. 1 Sekunde)
+- Läuft synchron zur Uhr: Bei 5s → `...:00, ...:05, ...:10, ...`
+
+**📸 Snapshot-Modus (optional)**
+- **Eingaben synchron einlesen**: Liest alle benötigten States einmal pro Durchlauf aktiv ein
+- Reduziert Abweichungen, wenn Quellen zeitversetzt aktualisieren
+- **Snapshot-Verzögerung**: Optionaler Delay in ms (z.B. 100–300ms) nach dem Durchlauf-Start
+
+**🛡️ Fehlerbehandlung**
+- `errorRetriesBeforeZero` – Anzahl Fehlversuche, bevor Output auf `0` gesetzt wird (Standard: 3)
+
+### 📝 Werte konfigurieren
+
+Jeder Eintrag erzeugt genau **einen Output-State**.
+
+Felder:
+
+- **Enabled**: aktiviert/deaktiviert.
+- **Name**: Anzeigename (optional).
+- **Folder/Group**: optionaler Ordner/Channel-Prefix.
+	- Beispiel: `pv` + Target ID `leistung` → Output wird `data-solectrus.0.pv.leistung`.
+- **Target ID**: Ziel-State innerhalb des Adapters (relativ). Beispiel: `leistung`, `pv.gesamt`.
+	- Erlaubt sind nur Segmente mit `A-Z`, `a-z`, `0-9`, `_`, `-` und `.` (keine absoluten IDs, kein `..`).
+- **Mode**:
+	- `source`: 1:1 Spiegelung eines ioBroker-States (mit optionaler Nachbearbeitung).
+	- `formula`: Berechnung aus mehreren Inputs.
+- **ioBroker Source State**:
+	- bei `mode=source`: der Quell-State (vollqualifiziert, z.B. `some.adapter.0.channel.state`).
+	- bei `mode=formula`: pro Input ein Source-State.
+- **JSONPath (optional)**:
+	- Wenn der Source-State (oder ein Input) statt einer Zahl ein JSON als Text enthält, kann hier ein JSONPath angegeben werden, um daraus einen numerischen Wert zu extrahieren.
+	- Beispiele: `$.apower`, `$.aenergy.by_minute[2]`
+- **Inputs** (nur `mode=formula`): Liste aus (Key, Source State).
+	- Optional pro Input: **Input negativ auf 0** (klemmt nur diesen Input vor der Rechnung).
+	- Optional pro Input: **JSONPath**
+		- Wenn JSONPath auf einen String/Boolean zeigt, wird dieser Wert als Variable bereitgestellt (z.B. für `IF(opMode == 'Heating', ...)`).
+		- Wenn JSONPath auf eine Zahl zeigt (oder einen numerischen String wie `"12.2"`), wird der Wert als Zahl bereitgestellt.
+	- **Wichtig zu Keys**: In Formeln sind `-` und Leerzeichen Operatoren/Trenner.
+		- Verwende daher am besten nur `a-z`, `0-9`, `_` (z.B. `bkw_garage`, `enpal`, `zendure`).
+		- Intern werden ungültige Zeichen im Key zu `_` umgewandelt.
+- **Formula expression**: Formel-String.
+- **Datatype**: optional (Standard: number).
+- **Role**, **Unit**: optional (für Metadaten).
+
+Nachbearbeitung:
+
+- **Clamp negative to 0**: negative Werte werden auf `0` gesetzt.
+	- wirkt auf das **Ergebnis** des Items (Output).
+	- wenn du nur einzelne Quellen/Inputs „bereinigen“ willst (z.B. PV darf nie negativ sein, aber Netzleistung ist signed), nutze dafür **Input negativ auf 0** direkt am jeweiligen Input oder `max(0, …)` in der Formel.
+- **Clamp result**: Ergebnis begrenzen (Min/Max). Leere Felder bedeuten „nicht begrenzen“.
+
+## 🧮 Formeln
+
+### Variablen
+
+Variablen kommen aus den **Eingaben** (Schlüssel → Quell-State).
+
+**Beispiel:**
+
+```javascript
+// Eingaben definiert:
+pv1 = 1000
+pv2 = 1500
+pv3 = 800
+
+// Formel:
+pv1 + pv2 + pv3  // = 3300
+```
+
+**🔧 Verfügbare Funktionen:**
+
+Siehe [Formel-Builder Wiki](https://github.com/Felliglanz/data-solectrus/wiki/Formel-Builder) für alle mathematischen Funktionen, Operatoren und Beispiele.
+
+**✅ Tests ausführen:**
+
+- `npm run lint` – Syntax-Prüfung
+- `npm run smoke` – Runtime-Test (mockt ioBroker)
+- `npm run check:simulate` – 30s Regressions-Test (PV + signed Meter)