iobroker.victoriametrics 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeaSpotter <seatowage@gmail.com>
+
+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,428 @@
+![Logo](admin/victoriametrics.png)
+# iobroker.victoriametrics
+
+<!-- Diese Badges brauchen eine npm-Veröffentlichung bzw. Aufnahme ins offizielle
+     ioBroker-Repository/Weblate und funktionieren daher noch nicht - sobald einer dieser
+     Schritte passiert, hier einkommentieren:
+![Number of Installations](https://iobroker.live/badges/victoriametrics-installed.svg)
+![Number of Installations](https://iobroker.live/badges/victoriametrics-stable.svg)
+[![NPM version](https://img.shields.io/npm/v/iobroker.victoriametrics.svg)](https://www.npmjs.com/package/iobroker.victoriametrics)
+[![Downloads](https://img.shields.io/npm/dm/iobroker.victoriametrics.svg)](https://www.npmjs.com/package/iobroker.victoriametrics)
+[![Translation status](https://weblate.iobroker.net/widgets/adapters/-/victoriametrics/svg-badge.svg)](https://weblate.iobroker.net/engage/adapters/?utm_source=widget)
+-->
+![Test and Release](https://github.com/seaspotter/iobroker.victoriametrics/workflows/Test%20and%20Release/badge.svg)
+
+Schreibt ioBroker-Datenpunkt-Historie nativ in [VictoriaMetrics](https://victoriametrics.com/) – über
+dessen [JSON-Lines-Import-API](https://docs.victoriametrics.com/#how-to-import-data-in-json-line-format),
+mit echten Prometheus-Labels statt Feld-Namens-Suffixen (wie sie z.B. beim Schreiben über den
+InfluxDB-Kompatibilitätslayer entstehen, etwa `Wohnzimmer_Temperatur_value`).
+
+Schreibt Datenpunkt-Änderungen gepuffert an VictoriaMetrics und beantwortet `getHistory()`-Anfragen
+(damit vis-Chart-Widgets direkt gegen diesen Adapter abfragen können) – siehe [Lesepfad](#lesepfad)
+unten für Details und bekannte Einschränkungen. Für Visualisierung ohne vis (z.B. Grafana)
+weiterhin direkt gegen VictoriaMetrics per PromQL abfragen. Der Adapter ist privat und (noch)
+nicht im offiziellen ioBroker-Repository gelistet.
+
+## Voraussetzungen
+
+- Eine laufende VictoriaMetrics-Instanz (Single-Node), erreichbar per HTTP(S) – siehe
+  [Installation von VictoriaMetrics](#installation-von-victoriametrics) unten
+- ioBroker js-controller >= 6.0.11, Admin >= 7.0.23
+
+## Installation von VictoriaMetrics
+
+VictoriaMetrics läuft als einzelne, eigenständige Binary/Docker-Image – kein separater
+Datenbank-Server-Setup wie bei InfluxDB nötig. Offizielle Installationsanleitungen für alle
+Plattformen (Linux-Binary, Docker, Kubernetes-Helm-Chart, …): siehe
+[VictoriaMetrics-Dokumentation](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/).
+
+### Per Docker
+
+```bash
+docker run -d --name victoriametrics \
+  -p 8428:8428 \
+  -v victoria-metrics-data:/victoria-metrics-data \
+  victoriametrics/victoria-metrics:latest \
+  --storageDataPath=/victoria-metrics-data \
+  --retentionPeriod=100y
+```
+
+Danach ist VictoriaMetrics unter `http://<Docker-Host>:8428` erreichbar (Health-Check:
+`http://<Docker-Host>:8428/health`, VMUI: `http://<Docker-Host>:8428/vmui/`). Offizielles
+Docker-Image: [victoriametrics/victoria-metrics auf Docker Hub](https://hub.docker.com/r/victoriametrics/victoria-metrics/).
+Für dauerhaften Betrieb empfiehlt sich ein Volume/Bind-Mount für `-storageDataPath` (siehe
+oben) sowie – je nach Umgebung – ein `docker-compose.yml` mit `restart: unless-stopped`.
+
+### Ohne Docker
+
+Statisch gelinktes Binary für die jeweilige Plattform von der
+[GitHub-Releases-Seite](https://github.com/VictoriaMetrics/VictoriaMetrics/releases) laden,
+entpacken und starten:
+
+```bash
+./victoria-metrics-prod --storageDataPath=/path/to/data --retentionPeriod=100y
+```
+
+Ausführliche Installationsanleitungen (inkl. systemd-Service, Kubernetes, Cluster-Setup) in der
+[offiziellen Dokumentation](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#how-to-start-victoriametrics).
+
+## Installation des Adapters
+
+Da der Adapter privat ist (nicht im offiziellen Repository), erfolgt die Installation über die
+GitHub-URL, entweder in der Admin-Oberfläche unter "Adapter" → "Custom von URL installieren..."
+oder per CLI:
+
+```bash
+iobroker url https://github.com/seaspotter/iobroker.victoriametrics
+```
+
+## Konfiguration
+
+### Tab "Verbindung"
+
+| Feld | Beschreibung |
+|------|--------------|
+| Protokoll | `http` oder `https` |
+| Host / IP-Adresse | Hostname/IP der VictoriaMetrics-Instanz, ohne Protokoll |
+| Port | Standard: `8428` |
+| Basic-Auth verwenden | Aktiviert Benutzername/Passwort (VictoriaMetrics `-httpAuth.*`) |
+| Timeout (ms) | HTTP-Request-Timeout |
+
+Über den Button **"Verbindung testen"** wird der `/health`-Endpunkt von VictoriaMetrics mit den
+aktuell eingegebenen (noch nicht gespeicherten) Werten geprüft; bei Erfolg zeigt die Meldung
+zusätzlich die aktuell konfigurierte Retention an.
+
+Beim Start des Adapters wird zusätzlich die aktuell auf dem VM-Server konfigurierte Retention
+geloggt (`VictoriaMetrics unter ... erreichbar (Retention: 100y)`) – reines Anzeigen, siehe
+[Retention](#retention) unten, warum sich das nicht über den Adapter ändern lässt.
+
+In der linken Seitenleiste von ioBroker.admin erscheint außerdem ein **"VictoriaMetrics"**-Menüpunkt
+(analog zu Node-RED/Zigbee2MQTT), der die VMUI (VictoriaMetrics' eigene Web-Oberfläche zum
+Ausführen von PromQL-Abfragen, Graphen etc.) direkt unter `http://<Host>:<Port>/vmui/` einbettet.
+**Achtung:** Läuft ioBroker.admin über HTTPS, aber VictoriaMetrics nur über HTTP, blockiert der
+Browser das Einbetten (Mixed-Content-Schutz) – dann öffnet sich eine leere Seite. Abhilfe nur durch
+VictoriaMetrics ebenfalls über HTTPS erreichbar zu machen, ein Workaround im Adapter ist nicht möglich.
+
+### Tab "Schreibverhalten"
+
+| Feld | Beschreibung |
+|------|--------------|
+| Schreibintervall (Sekunden) | Wie oft gepufferte Werte gesammelt geschrieben werden |
+| Max. Puffergröße (Punkte) | Löst bei Erreichen einen sofortigen Schreibvorgang aus |
+
+### Datenpunkte historisieren
+
+Im Objektbaum bei jedem gewünschten Datenpunkt den Tab **"Historie"** öffnen, diesen Adapter
+auswählen und über den Schalter **"Aktiviert"** einschalten.
+
+| Feld | Beschreibung |
+|------|--------------|
+| Entprellzeit (ms, optional) | Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt (wartet auf einen "ruhigen" Zustand vor dem Schreiben) |
+| Blockzeit (ms, optional) | Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert (Rate-Limit) |
+| Ignoriere Werte kleiner/größer als (optional) | Schwellenwert-Filter, z. B. um offensichtliche Sensor-Ausreißer zu verwerfen |
+| Ignoriere Nullwerte (0) | Überspringt Werte, die exakt 0 sind |
+| Metrik-Name (optional) | Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (`__name__`), siehe unten |
+| Runden auf Nachkommastellen (optional) | Rundet den Wert vor dem Schreiben; leer lassen für keine Rundung |
+| Minimale Änderung (optional) | Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben; leer lassen für keine Filterung |
+| Nur Änderungen aufzeichnen | Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet |
+| Relog-Intervall (ms, optional) | Nur bei aktiviertem "Nur Änderungen aufzeichnen": schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen |
+
+Entprellzeit und Blockzeit sind kombinierbar mit den übrigen Filtern: Entprellzeit
+verzögert das Schreiben, bis der Wert eine Zeit lang stabil war; Blockzeit begrenzt,
+wie oft ein Datenpunkt maximal geschrieben wird, unabhängig davon, ob er sich ändert.
+"Nur Änderungen aufzeichnen" ist unabhängig von "Minimale Änderung" nutzbar: Erstere schreibt
+nur bei einer *exakten* Wertänderung (mit optionalem periodischem Relog), Letztere filtert
+Änderungen unterhalb eines *Schwellenwerts*.
+
+### Tab "Standardwerte"
+
+Dieselben Felder (außer Metrik-Name) lassen sich auch **instanzweit** setzen, im Instanz-Konfig-Tab
+"Standardwerte". Sie gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt
+haben – so muss nicht jeder einzelne Datenpunkt konfiguriert werden. Ein Datenpunkt-eigener Wert
+überschreibt immer den instanzweiten Standard.
+
+## Metrik-Namensbildung
+
+Der Prometheus-Metrikname (`__name__`) wird wie folgt ermittelt:
+
+1. Ist im Historie-Tab ein **Metrik-Name** (`aliasId`) gesetzt, wird dieser verwendet.
+2. Andernfalls wird die **ioBroker-Objekt-ID** verwendet (nicht der Objektname, da dieser sich
+   unbemerkt ändern und die Zeitreihe stillschweigend spalten könnte).
+
+Der gewählte Name wird anschließend normalisiert: kleingeschrieben, `.` wird zu `_`, jede Folge
+ungültiger Zeichen wird zu einem einzelnen `_` zusammengefasst, führende/trailing `_` entfernt,
+und falls das Ergebnis mit einer Ziffer beginnt, wird ein `_` vorangestellt.
+
+Beispiel: `javascript.0.Room Temperature` → `javascript_0_room_temperature`. Für einen
+kurzen, sprechenden Namen wie `room_temperature` das Feld **Metrik-Name** verwenden.
+
+## Datentyp-Behandlung
+
+VictoriaMetrics-Metriken sind grundsätzlich numerisch:
+
+- **Zahlen** werden unverändert geschrieben.
+- **Booleans** werden zu `0.0`/`1.0` konvertiert.
+- **Strings** werden als Zahl geparst (z.B. `"21.5"` → `21.5`); nicht parsbare Strings werden mit
+  einer Warnung im Log übersprungen (kein Schreiben eines String-Labels, um eine
+  Kardinalitätsexplosion zu vermeiden).
+
+Zusätzlich wird automatisch ein Label `unit` gesetzt, sofern das ioBroker-Objekt eine Einheit
+(`common.unit`) definiert hat.
+
+## Verbindungsabbruch & Datenverlustschutz
+
+Werte werden zunächst in einem Puffer gesammelt und im konfigurierten Schreibintervall (bzw. bei
+Erreichen der maximalen Puffergröße) gesammelt an VictoriaMetrics geschrieben.
+
+Schlägt ein Schreibvorgang fehl (z.B. VM nicht erreichbar), wird für jeden betroffenen
+Datenpunkt ein Fehlerzähler erhöht:
+- Bei einem Zählerstand `< 10` wird der Punkt erneut gepuffert und beim nächsten Intervall erneut
+  versucht.
+- Bei Erreichen von `10` wird der Punkt verworfen und der Zähler zurückgesetzt (verhindert
+  unbegrenztes Anwachsen des Puffers bei dauerhaft nicht erreichbarem VM).
+
+Zusätzlich wird der Puffer beim sauberen Beenden des Adapters sowie (gedrosselt auf max. einmal
+pro Minute) nach fehlgeschlagenen Schreibversuchen persistiert, sodass auch ein harter Absturz
+(z.B. Container-Neustart) im normalen Rahmen keine Daten verliert.
+
+## Lesepfad
+
+Der Adapter beantwortet `getHistory()`-Anfragen (das, was vis-Chart-Widgets aufrufen), indem
+er Datenpunkte der angefragten Metrik aus VictoriaMetrics liest und sie an die geteilte
+[`@iobroker/aggregate`](https://github.com/ioBroker/aggregate)-Bibliothek übergibt – dieselbe
+Bibliothek, die `iobroker.influxdb`, `iobroker.sql` und `iobroker.history` für
+Bucket-Aggregation (Durchschnitt/Min/Max/Summe/Anzahl/Perzentil/...), Lücken-Behandlung und
+Rand-Interpolation verwenden. Dadurch funktionieren grundsätzlich alle Standard-Aggregationstypen,
+ohne dass dieser Adapter die Bucket-Logik selbst nachbauen musste.
+
+**Serverseitiges Pushdown:** für die Aggregationsmethoden `average`, `min`, `max`, `total` und
+`count` mit bekanntem Zeit-`step` rechnet VictoriaMetrics selbst per PromQL (`avg_over_time`,
+`min_over_time`, `max_over_time`, `sum_over_time`, `count_over_time`) – der Adapter überträgt
+dann nur die fertigen Bucket-Werte statt aller Rohpunkte. Für `onchange`/`none`/`minmax` sowie
+`percentile`/`quantile`/`integral` (kein direktes PromQL-Äquivalent) und immer dann, wenn das
+Pushdown fehlschlägt, wird transparent auf den Rohdaten-Pfad (`/api/v1/export` + JS-seitige
+Aggregation) zurückgefallen.
+
+**`id: '*'`:** liefert die letzten Rohwerte über alle *aktuell in Admin aktivierten*
+Datenpunkte hinweg (nicht verwaiste Metriken zwischenzeitlich deaktivierter Datenpunkte),
+jeweils mit `id`-Feld pro Punkt. Aggregation wird hierfür nicht unterstützt (ergibt über
+verschiedene Metriken hinweg keinen Sinn) – es werden immer Rohwerte zurückgegeben.
+
+**Weitere bekannte Einschränkungen:**
+- Antworten enthalten kein `ack`/`q`/`from` – der Adapter speichert diese Felder gar nicht erst
+  in VictoriaMetrics
+- Kein Vorab-Flush noch nicht geschriebener, gepufferter Werte vor einer Abfrage (anders als
+  `iobroker.influxdb`) – ein `getHistory()`-Aufruf direkt nach einer Zustandsänderung sieht den
+  neuesten Wert ggf. erst nach dem nächsten Schreibintervall
+
+### Zugriff aus dem JavaScript-Adapter
+
+```javascript
+// Letzte 50 Rohwerte
+sendTo('victoriametrics.0', 'getHistory', {
+    id: 'javascript.0.exampleValue',
+    options: {
+        end: Date.now(),
+        count: 50,
+        aggregate: 'onchange',
+    }
+}, function (result) {
+    for (var i = 0; i < result.result.length; i++) {
+        console.log(result.result[i].ts + ' ' + result.result[i].val);
+    }
+});
+
+// Stundenmittelwert der letzten 24h
+var end = Date.now();
+sendTo('victoriametrics.0', 'getHistory', {
+    id: 'javascript.0.exampleValue',
+    options: {
+        start: end - 24 * 3600000,
+        end: end,
+        aggregate: 'average',
+        step: 3600000,
+    }
+}, function (result) {
+    console.log(JSON.stringify(result.result));
+});
+
+// Letzte 20 Rohwerte über alle aktivierten Datenpunkte hinweg
+sendTo('victoriametrics.0', 'getHistory', {
+    id: '*',
+    options: {
+        end: Date.now(),
+        count: 20,
+        addId: true,
+    }
+}, function (result) {
+    for (var i = 0; i < result.result.length; i++) {
+        console.log(result.result[i].id + ' ' + result.result[i].val);
+    }
+});
+```
+
+Unterstützte `options`-Felder und `aggregate`-Werte entsprechen dem ioBroker-Standard (siehe
+[`iobroker.history`-Dokumentation](https://github.com/ioBroker/ioBroker.history#access-values-from-javascript-adapter)
+für die vollständige Referenz) – mit den oben genannten Einschränkungen.
+
+## Datenmanagement / Skript-Schnittstellen
+
+Der Adapter beantwortet zusätzlich drei weitere ioBroker-Message-Kommandos (`sendTo`), z.B. für
+Skripte oder Migrationswerkzeuge:
+
+### features
+
+Capability-Discovery:
+
+```javascript
+sendTo('victoriametrics.0', 'features', {}, function (result) {
+    console.log(JSON.stringify(result.supportedFeatures)); // ['storeState', 'deleteAll']
+});
+```
+
+### storeState
+
+Schreibt einen oder mehrere historische Punkte, z.B. um alte Historie aus einer anderen Quelle
+(z.B. InfluxDB) nachträglich zu importieren:
+
+```javascript
+sendTo('victoriametrics.0', 'storeState', {
+    id: 'javascript.0.exampleValue',
+    state: { ts: 1690000000000, val: 512.3 },
+    rules: true, // Rundung + Schwellenwert-/Nullwert-Filter anwenden (siehe unten)
+}, result => console.log(JSON.stringify(result)));
+
+// auch als Batch für dieselbe id:
+sendTo('victoriametrics.0', 'storeState', {
+    id: 'javascript.0.exampleValue',
+    state: [
+        { ts: 1690000000000, val: 512.3 },
+        { ts: 1690000060000, val: 498.1 },
+    ],
+}, result => console.log(JSON.stringify(result)));
+
+// oder als Array mehrerer ids:
+sendTo('victoriametrics.0', 'storeState', [
+    { id: 'javascript.0.a', state: { ts: 1690000000000, val: 1 } },
+    { id: 'javascript.0.b', state: { ts: 1690000000000, val: 2 } },
+], result => console.log(JSON.stringify(result)));
+```
+
+`rules: true` wendet Rundung und Schwellenwert-/Nullwert-Filter an (Werte-Validität, sinnvoll
+auch für Importe); Entprellzeit/Blockzeit/Minimale Änderung werden **immer** ignoriert, da diese
+auf Live-Zustandsänderungen ausgelegt sind und für rückdatierte Bulk-Importe keinen Sinn ergeben.
+Erfordert nicht, dass der Datenpunkt aktuell für Live-Historisierung aktiviert ist. Bei
+Teilfehlern liefert die Antwort `{error, errors: [...], successCount}`, bei vollem Erfolg
+`{success: true, successCount}`.
+
+### deleteAll
+
+Löscht die komplette in VictoriaMetrics gespeicherte Historie eines Datenpunkts:
+
+```javascript
+sendTo('victoriametrics.0', 'deleteAll', { id: 'javascript.0.exampleValue' },
+    result => console.log(JSON.stringify(result)));
+
+// auch als Array mehrerer ids:
+sendTo('victoriametrics.0', 'deleteAll', [
+    { id: 'javascript.0.a' },
+    { id: 'javascript.0.b' },
+], result => console.log(JSON.stringify(result)));
+```
+
+**Bewusst nicht implementiert:** `delete`/`deleteRange`/`update` (Einzelpunkt-Löschung/-Bearbeitung,
+wie es das influxdb-Admin-UI per Klick auf einen Chart-Punkt anbietet). VictoriaMetrics kann
+technisch keine einzelnen Datenpunkte löschen oder bearbeiten – nur ganze Zeitreihen per
+Label-Match, da die Speicherung auf unveränderlichen, zeitsortierten Blöcken beruht (wie bei
+Prometheus). Ein Löschen "einzelner Punkte" würde in Wirklichkeit die komplette Zeitreihe löschen –
+das wäre überraschend und gefährlich, deshalb absichtlich weggelassen.
+
+## Retention
+
+VictoriaMetrics' Retention ist ein **serverseitiges Start-Flag** (`-retentionPeriod`) des
+VM-Prozesses selbst, nicht per HTTP-API zur Laufzeit änderbar (anders als z.B. InfluxDB, wo der
+Adapter per `ALTER RETENTION POLICY` aktiv einen Wert setzen kann). Dieser Adapter zeigt die
+aktuell konfigurierte Retention deshalb nur lesend an – zum Ändern muss VM mit einem anderen
+`-retentionPeriod`-Wert neu gestartet werden (bei Docker: den `--retentionPeriod=...`-Parameter
+im `docker run`/`docker-compose.yml` ändern und den Container neu erstellen).
+
+Sichtbar ist die aktuelle Retention an drei Stellen (alle read-only, beim Adapterstart einmalig
+vom `/flags`-Endpunkt gelesen):
+- Datenpunkt **`<instance>.info.retention`** (String, z.B. `"100y"`) – für Skripte/VIS
+- Log-Eintrag beim Start (`VictoriaMetrics unter ... erreichbar (Retention: 100y)`)
+- Erfolgs-Meldung des Buttons **"Verbindung testen"** im Tab "Verbindung"
+
+**Details:**
+- **Standard-Retention**, falls `-retentionPeriod` nicht gesetzt ist: **1 Monat (31 Tage)**.
+- **Minimum**: 24h/1 Tag. VictoriaMetrics unterstützt keine "unbegrenzte" Retention im engeren
+  Sinne, aber beliebig hohe Werte sind möglich, z.B. `-retentionPeriod=100y`.
+- Daten werden **pro Monats-Partition** gelöscht, jeweils am ersten Tag des neuen Monats – nicht
+  sofort beim Erreichen der Grenze. Der maximale Plattenplatzverbrauch liegt daher bei
+  `retentionPeriod + 1 Monat`.
+- Eine bestehende Retention kann jederzeit **verlängert** werden, ohne Daten zu verlieren. Wird
+  sie **verkürzt**, werden Daten außerhalb der neuen Grenze beim nächsten Monatswechsel gelöscht.
+- Ausführliche Details: [VictoriaMetrics-Dokumentation, Abschnitt "Retention"](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#retention).
+
+## Sonstige bekannte Einschränkungen
+
+- Kein Multi-Cluster-Support (vminsert/vmselect) – nur ein Single-Node-Ziel.
+- Freie, pro Datenpunkt konfigurierbare Zusatz-Labels (über `unit` hinaus) sind nicht
+  implementiert.
+
+## Entwicklung
+
+| Script | Beschreibung |
+|--------|--------------|
+| `npm run lint` | ESLint |
+| `npm run check` | Type-Check (`tsc --noEmit`) |
+| `npm run test:js` | Unit-Tests |
+| `npm run test:package` | Prüft `package.json`/`io-package.json` |
+| `npm run dev-server` | Startet [`dev-server`](https://github.com/ioBroker/dev-server) für einen lokalen Testlauf inkl. Admin-UI |
+
+## Changelog
+
+### **WORK IN PROGRESS**
+
+### 0.4.0 (2026-08-28)
+* (SeaSpotter) Fix: VMUI-Sidebar-Link warf einen `URIError` beim Anklicken (`%native_protocol%` wurde nicht ersetzt) – korrekte Platzhalter-Syntax laut Admin-Quellcode ist `%protocol%`/`%host%`/`%port%` ohne `native_`-Präfix
+* (SeaSpotter) Serverseitiges PromQL-Pushdown für `getHistory` bei den Aggregationsmethoden average/min/max/total/count (`avg_over_time` etc.) statt Rohdaten-Export + JS-Aggregation
+* (SeaSpotter) `getHistory` mit `id: '*'`: letzte Rohwerte über alle aktuell aktivierten Datenpunkte hinweg
+* (SeaSpotter) Neue Pro-Datenpunkt-/Standardwert-Filter `changesOnly` (nur Änderungen aufzeichnen) und `changesRelogInterval` (periodisches Relog unveränderter Werte)
+* (SeaSpotter) Retention jetzt auch als eigener Datenpunkt `info.retention` und im Erfolgs-Alert von "Verbindung testen" sichtbar, nicht nur im Log
+* (SeaSpotter) Eigenes Adapter-Icon
+
+### 0.3.0 (2026-08-28)
+* (SeaSpotter) VMUI-Sidebar-Link in der Admin-Seitenleiste (`common.adminTab`, analog Node-RED/Zigbee2MQTT)
+* (SeaSpotter) Instanzweite Standardwerte für alle Historie-Filter (round/changesMinDelta/debounceTime/blockTime/ignoreBelow-/AboveNumber/ignoreZero) – Datenpunkt-eigene Werte überschreiben weiterhin den Standard
+* (SeaSpotter) Retention wird beim Start read-only geloggt (`/flags`-Endpunkt)
+* (SeaSpotter) Neue Message-Kommandos `storeState` (Bulk-Import/Migration), `deleteAll` (Historie eines Datenpunkts löschen) und `features` (Capability-Discovery)
+* (SeaSpotter) `round`, `changesMinDelta`, `debounceTime`, `blockTime`, `ignoreBelowNumber`/`ignoreAboveNumber`, `ignoreZero` als Pro-Datenpunkt-Filter ergänzt
+
+### 0.2.0 (2026-08-28)
+* (SeaSpotter) `getHistory()`-Lesepfad über die geteilte `@iobroker/aggregate`-Bibliothek
+
+### 0.1.0 (2026-08-28)
+* (SeaSpotter) Schreibpfad nach VictoriaMetrics (native JSON-Lines-Import-API), Verbindungstest, Puffer/Retry, Historie-Tab-Integration
+
+## License
+MIT License
+
+Copyright (c) 2026 SeaSpotter <seatowage@gmail.com>
+
+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/admin/i18n/de.json

@@ -0,0 +1,38 @@
+{
+    "Basic-Auth verwenden": "Basic-Auth verwenden",
+    "Benutzername": "Benutzername",
+    "Blockzeit (ms, optional)": "Blockzeit (ms, optional)",
+    "Entprellzeit (ms, optional)": "Entprellzeit (ms, optional)",
+    "Gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt haben.": "Gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt haben.",
+    "Host / IP-Adresse": "Host / IP-Adresse",
+    "Hostname oder IP-Adresse der VictoriaMetrics-Instanz, ohne Protokoll": "Hostname oder IP-Adresse der VictoriaMetrics-Instanz, ohne Protokoll",
+    "Ignoriere Nullwerte (0)": "Ignoriere Nullwerte (0)",
+    "Ignoriere Werte größer als (optional)": "Ignoriere Werte größer als (optional)",
+    "Ignoriere Werte kleiner als (optional)": "Ignoriere Werte kleiner als (optional)",
+    "Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert.": "Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert.",
+    "Löst bei Erreichen einen sofortigen Schreibvorgang aus, unabhängig vom Schreibintervall": "Löst bei Erreichen einen sofortigen Schreibvorgang aus, unabhängig vom Schreibintervall",
+    "Max. Puffergröße (Punkte)": "Max. Puffergröße (Punkte)",
+    "Metrik-Name (optional)": "Metrik-Name (optional)",
+    "Minimale Änderung (optional)": "Minimale Änderung (optional)",
+    "Nur Änderungen aufzeichnen": "Nur Änderungen aufzeichnen",
+    "Passwort": "Passwort",
+    "Port": "Port",
+    "Protokoll": "Protokoll",
+    "Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt. Leer lassen für sofortiges Schreiben.": "Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt. Leer lassen für sofortiges Schreiben.",
+    "Relog-Intervall (ms, optional)": "Relog-Intervall (ms, optional)",
+    "Runden auf Nachkommastellen (optional)": "Runden auf Nachkommastellen (optional)",
+    "Rundet den Wert vor dem Schreiben auf die angegebene Anzahl Nachkommastellen. Leer lassen für keine Rundung.": "Rundet den Wert vor dem Schreiben auf die angegebene Anzahl Nachkommastellen. Leer lassen für keine Rundung.",
+    "Schreibintervall (Sekunden)": "Schreibintervall (Sekunden)",
+    "Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet.": "Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet.",
+    "Schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen. Nur wirksam bei aktiviertem 'Nur Änderungen aufzeichnen'.": "Schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen. Nur wirksam bei aktiviertem 'Nur Änderungen aufzeichnen'.",
+    "Schreibverhalten": "Schreibverhalten",
+    "Standardwerte": "Standardwerte",
+    "Timeout (ms)": "Timeout (ms)",
+    "Verbindung": "Verbindung",
+    "Verbindung erfolgreich (Retention: %s)": "Verbindung erfolgreich (Retention: %s)",
+    "Verbindung testen": "Verbindung testen",
+    "Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben. Leer lassen für keine Filterung.": "Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben. Leer lassen für keine Filterung.",
+    "Wie oft gepufferte Werte gesammelt an VictoriaMetrics gesendet werden": "Wie oft gepufferte Werte gesammelt an VictoriaMetrics gesendet werden",
+    "Zeitüberschreitung bei der Verbindung": "Zeitüberschreitung bei der Verbindung",
+    "Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (__name__). Leer lassen für Standardableitung.": "Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (__name__). Leer lassen für Standardableitung."
+}

package/admin/i18n/en.json

@@ -0,0 +1,38 @@
+{
+    "Verbindung": "Connection",
+    "Schreibverhalten": "Write behavior",
+    "Protokoll": "Protocol",
+    "Host / IP-Adresse": "Host / IP address",
+    "Hostname oder IP-Adresse der VictoriaMetrics-Instanz, ohne Protokoll": "Hostname or IP address of the VictoriaMetrics instance, without protocol",
+    "Port": "Port",
+    "Basic-Auth verwenden": "Use basic auth",
+    "Benutzername": "Username",
+    "Passwort": "Password",
+    "Timeout (ms)": "Timeout (ms)",
+    "Verbindung testen": "Test connection",
+    "Zeitüberschreitung bei der Verbindung": "Connection timeout",
+    "Verbindung erfolgreich (Retention: %s)": "Connection successful (retention: %s)",
+    "Schreibintervall (Sekunden)": "Write interval (seconds)",
+    "Wie oft gepufferte Werte gesammelt an VictoriaMetrics gesendet werden": "How often buffered values are sent to VictoriaMetrics in a batch",
+    "Max. Puffergröße (Punkte)": "Max. buffer size (points)",
+    "Löst bei Erreichen einen sofortigen Schreibvorgang aus, unabhängig vom Schreibintervall": "Triggers an immediate write when reached, independent of the write interval",
+    "Metrik-Name (optional)": "Metric name (optional)",
+    "Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (__name__). Leer lassen für Standardableitung.": "Overrides the metric name (__name__) automatically derived from the object ID. Leave empty for the default derivation.",
+    "Runden auf Nachkommastellen (optional)": "Round to decimal places (optional)",
+    "Rundet den Wert vor dem Schreiben auf die angegebene Anzahl Nachkommastellen. Leer lassen für keine Rundung.": "Rounds the value to the given number of decimal places before writing. Leave empty for no rounding.",
+    "Minimale Änderung (optional)": "Minimum change (optional)",
+    "Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben. Leer lassen für keine Filterung.": "Values that differ from the last written value by less than this amount are not written. Leave empty for no filtering.",
+    "Entprellzeit (ms, optional)": "Debounce time (ms, optional)",
+    "Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt. Leer lassen für sofortiges Schreiben.": "Only logs the value once it has stayed unchanged for the given time. Leave empty to write immediately.",
+    "Blockzeit (ms, optional)": "Block time (ms, optional)",
+    "Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert.": "Ignores new values for the given time after the last written value.",
+    "Ignoriere Werte kleiner als (optional)": "Ignore values below (optional)",
+    "Ignoriere Werte größer als (optional)": "Ignore values above (optional)",
+    "Ignoriere Nullwerte (0)": "Ignore zero values (0)",
+    "Standardwerte": "Defaults",
+    "Gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt haben.": "Apply to all datapoints that don't set their own value in the Historie tab.",
+    "Nur Änderungen aufzeichnen": "Log changes only",
+    "Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet.": "Only writes a value if it differs from the last written value.",
+    "Relog-Intervall (ms, optional)": "Relog interval (ms, optional)",
+    "Schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen. Nur wirksam bei aktiviertem 'Nur Änderungen aufzeichnen'.": "Writes an unchanged value again at the latest after this time, so charts don't show gaps. Only effective when 'Log changes only' is enabled."
+}

package/admin/i18n/es.json

@@ -0,0 +1,38 @@
+{
+    "Basic-Auth verwenden": "Usar autenticación básica",
+    "Benutzername": "Nombre de usuario",
+    "Blockzeit (ms, optional)": "Tiempo de bloqueo (ms, opcional)",
+    "Entprellzeit (ms, optional)": "Tiempo de rebote (ms, opcional)",
+    "Gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt haben.": "Aplicar a todos los puntos de datos que no establecen su propio valor en la pestaña Historial.",
+    "Host / IP-Adresse": "Anfitrión/dirección IP",
+    "Hostname oder IP-Adresse der VictoriaMetrics-Instanz, ohne Protokoll": "Nombre de host o dirección IP de la instancia de VictoriaMetrics, sin protocolo",
+    "Ignoriere Nullwerte (0)": "Ignorar valores cero (0)",
+    "Ignoriere Werte größer als (optional)": "Ignorar los valores anteriores (opcional)",
+    "Ignoriere Werte kleiner als (optional)": "Ignorar los valores siguientes (opcional)",
+    "Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert.": "Ignora los valores nuevos durante el tiempo dado después del último valor escrito.",
+    "Löst bei Erreichen einen sofortigen Schreibvorgang aus, unabhängig vom Schreibintervall": "Activa una escritura inmediata cuando se alcanza, independientemente del intervalo de escritura.",
+    "Max. Puffergröße (Punkte)": "Máx. tamaño del buffer (puntos)",
+    "Metrik-Name (optional)": "Nombre de la métrica (opcional)",
+    "Minimale Änderung (optional)": "Cambio mínimo (opcional)",
+    "Nur Änderungen aufzeichnen": "Registrar solo cambios",
+    "Passwort": "Contraseña",
+    "Port": "Puerto",
+    "Protokoll": "Protocolo",
+    "Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt. Leer lassen für sofortiges Schreiben.": "Solo registra el valor una vez que ha permanecido sin cambios durante el tiempo determinado. Déjelo vacío para escribir inmediatamente.",
+    "Relog-Intervall (ms, optional)": "Intervalo de registro (ms, opcional)",
+    "Runden auf Nachkommastellen (optional)": "Redondear a decimales (opcional)",
+    "Rundet den Wert vor dem Schreiben auf die angegebene Anzahl Nachkommastellen. Leer lassen für keine Rundung.": "Redondea el valor al número de decimales indicado antes de escribir. Déjelo vacío para que no se redondee.",
+    "Schreibintervall (Sekunden)": "Intervalo de escritura (segundos)",
+    "Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet.": "Sólo escribe un valor si difiere del último valor escrito.",
+    "Schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen. Nur wirksam bei aktiviertem 'Nur Änderungen aufzeichnen'.": "Vuelve a escribir un valor sin cambios a más tardar después de este tiempo, para que los gráficos no muestren espacios en blanco. Solo es efectivo cuando está habilitado \"Registrar solo cambios\".",
+    "Schreibverhalten": "Comportamiento de escritura",
+    "Standardwerte": "Valores predeterminados",
+    "Timeout (ms)": "Tiempo de espera (ms)",
+    "Verbindung": "Conexión",
+    "Verbindung erfolgreich (Retention: %s)": "Conexión exitosa (retención: %s)",
+    "Verbindung testen": "Conexión de prueba",
+    "Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben. Leer lassen für keine Filterung.": "Los valores que difieran del último valor escrito por menos de esta cantidad no se escriben. Déjelo vacío para no filtrar.",
+    "Wie oft gepufferte Werte gesammelt an VictoriaMetrics gesendet werden": "Con qué frecuencia se envían los valores almacenados en el búfer a VictoriaMetrics en un lote",
+    "Zeitüberschreitung bei der Verbindung": "Tiempo de espera de conexión",
+    "Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (__name__). Leer lassen für Standardableitung.": "Anula el nombre de la métrica (__name__) derivado automáticamente del ID del objeto. Déjelo vacío para la derivación predeterminada."
+}

package/admin/i18n/fr.json

@@ -0,0 +1,38 @@
+{
+    "Basic-Auth verwenden": "Utiliser l'authentification de base",
+    "Benutzername": "Nom d'utilisateur",
+    "Blockzeit (ms, optional)": "Temps de blocage (ms, facultatif)",
+    "Entprellzeit (ms, optional)": "Temps anti-rebond (ms, facultatif)",
+    "Gelten für alle Datenpunkte, die im Historie-Tab kein eigenes Feld gesetzt haben.": "Appliquer à tous les points de données qui ne définissent pas leur propre valeur dans l'onglet Historique.",
+    "Host / IP-Adresse": "Hôte/adresse IP",
+    "Hostname oder IP-Adresse der VictoriaMetrics-Instanz, ohne Protokoll": "Nom d'hôte ou adresse IP de l'instance VictoriaMetrics, sans protocole",
+    "Ignoriere Nullwerte (0)": "Ignorer les valeurs nulles (0)",
+    "Ignoriere Werte größer als (optional)": "Ignorer les valeurs ci-dessus (facultatif)",
+    "Ignoriere Werte kleiner als (optional)": "Ignorer les valeurs ci-dessous (facultatif)",
+    "Ignoriert neue Werte für die angegebene Zeit nach dem zuletzt geschriebenen Wert.": "Ignore les nouvelles valeurs pendant le temps donné après la dernière valeur écrite.",
+    "Löst bei Erreichen einen sofortigen Schreibvorgang aus, unabhängig vom Schreibintervall": "Déclenche une écriture immédiate une fois atteint, indépendamment de l'intervalle d'écriture",
+    "Max. Puffergröße (Punkte)": "Max. taille du tampon (points)",
+    "Metrik-Name (optional)": "Nom de la métrique (facultatif)",
+    "Minimale Änderung (optional)": "Changement minimum (facultatif)",
+    "Nur Änderungen aufzeichnen": "Consigner les modifications uniquement",
+    "Passwort": "Mot de passe",
+    "Port": "Port",
+    "Protokoll": "Protocole",
+    "Protokolliert den Wert erst, wenn er für die angegebene Zeit unverändert bleibt. Leer lassen für sofortiges Schreiben.": "N'enregistre la valeur qu'une fois qu'elle est restée inchangée pendant la durée donnée. Laissez vide pour écrire immédiatement.",
+    "Relog-Intervall (ms, optional)": "Intervalle de reconnexion (ms, facultatif)",
+    "Runden auf Nachkommastellen (optional)": "Arrondir à la décimale (facultatif)",
+    "Rundet den Wert vor dem Schreiben auf die angegebene Anzahl Nachkommastellen. Leer lassen für keine Rundung.": "Arrondit la valeur au nombre de décimales donné avant d'écrire. Laissez vide pour ne pas arrondir.",
+    "Schreibintervall (Sekunden)": "Intervalle d'écriture (secondes)",
+    "Schreibt einen Wert nur, wenn er sich vom zuletzt geschriebenen Wert unterscheidet.": "N'écrit une valeur que si elle diffère de la dernière valeur écrite.",
+    "Schreibt einen unveränderten Wert spätestens nach dieser Zeit erneut, damit im Chart keine Lücken entstehen. Nur wirksam bei aktiviertem 'Nur Änderungen aufzeichnen'.": "Écrit à nouveau une valeur inchangée au plus tard après cette heure, afin que les graphiques n'affichent pas d'écarts. Efficace uniquement lorsque « Enregistrer les modifications uniquement » est activé.",
+    "Schreibverhalten": "Comportement d'écriture",
+    "Standardwerte": "Valeurs par défaut",
+    "Timeout (ms)": "Délai d'expiration (ms)",
+    "Verbindung": "Connexion",
+    "Verbindung erfolgreich (Retention: %s)": "Connexion réussie (rétention : %s)",
+    "Verbindung testen": "Tester la connexion",
+    "Werte, die sich vom zuletzt geschriebenen Wert um weniger als diesen Betrag unterscheiden, werden nicht geschrieben. Leer lassen für keine Filterung.": "Les valeurs qui diffèrent de la dernière valeur écrite de moins de ce montant ne sont pas écrites. Laissez vide pour aucun filtrage.",
+    "Wie oft gepufferte Werte gesammelt an VictoriaMetrics gesendet werden": "À quelle fréquence les valeurs mises en mémoire tampon sont envoyées à VictoriaMetrics dans un lot",
+    "Zeitüberschreitung bei der Verbindung": "Délai de connexion",
+    "Überschreibt die automatisch aus der Objekt-ID abgeleitete Metrik (__name__). Leer lassen für Standardableitung.": "Remplace le nom de la métrique (__name__) automatiquement dérivé de l'ID de l'objet. Laissez vide pour la dérivation par défaut."
+}