@mxtommy/kip 4.8.0-beta.1 → 4.8.1

package/plugin/index.js

@@ -65,7 +65,7 @@ const start = (server) => {
     const CONFIG_SCHEMA = {
         type: 'object',
         title: 'Remote Control and Data Series',
-        description: 'NOTE: All plugin settings are also managed from within KIP\'s Display Options panel. Changes made here will be overridden when KIP applies settings from the Display Options.',
+        description: 'NOTE: All plugin settings are also managed from within KIP\'s Display Options panel. Changes made here will be overridden when KIP applies settings from the Display Options. See the KIP Time-Series help documentation for details.',
         properties: {
             nodeSqliteAvailable: {
                 type: 'boolean',
@@ -155,37 +155,105 @@ const start = (server) => {
             .replace(/[^a-z0-9]+/g, '-')
             .replace(/^-+|-+$/g, '');
     }
-    function resolveBmsBatteryIdsFromSelfPath() {
-        const batteriesPath = server.getSelfPath('electrical.batteries');
-        const readCandidate = (node) => {
-            if (!node || typeof node !== 'object' || Array.isArray(node)) {
-                return null;
-            }
-            const root = node;
-            if (Object.prototype.hasOwnProperty.call(root, 'value')) {
-                const value = root.value;
-                if (value && typeof value === 'object' && !Array.isArray(value)) {
-                    return value;
-                }
+    const ELECTRICAL_SERIES_PREFIX_BY_FAMILY = {
+        batteries: 'bms',
+        solar: 'solar',
+        chargers: 'charger',
+        inverters: 'inverter',
+        alternators: 'alternator',
+        ac: 'ac'
+    };
+    const ELECTRICAL_SELF_ROOT_BY_FAMILY = {
+        batteries: 'electrical.batteries',
+        solar: 'electrical.solar',
+        chargers: 'electrical.chargers',
+        inverters: 'electrical.inverters',
+        alternators: 'electrical.alternators',
+        ac: 'electrical.ac'
+    };
+    const ELECTRICAL_METRICS_BY_FAMILY = {
+        batteries: ['capacity.stateOfCharge', 'current'],
+        solar: ['current', 'panelPower'],
+        chargers: ['voltage', 'current'],
+        inverters: ['voltage', 'current'],
+        alternators: ['voltage', 'current'],
+        ac: [
+            'line1.voltage',
+            'line1.current',
+            'line1.frequency',
+            'line2.voltage',
+            'line2.current',
+            'line2.frequency',
+            'line3.voltage',
+            'line3.current',
+            'line3.frequency'
+        ]
+    };
+    function resolveFamilyKeyFromTemplateSeries(series) {
+        if (!(0, history_series_service_1.isKipElectricalTemplateSeriesDefinition)(series)) {
+            return null;
+        }
+        if (series.familyKey) {
+            return series.familyKey;
+        }
+        switch (series.expansionMode) {
+            case 'bms-battery-tree':
+                return 'batteries';
+            case 'solar-tree':
+                return 'solar';
+            case 'charger-tree':
+                return 'chargers';
+            case 'inverter-tree':
+                return 'inverters';
+            case 'alternator-tree':
+                return 'alternators';
+            case 'ac-tree':
+                return 'ac';
+            default:
                 return null;
-            }
-            return root;
-        };
-        const candidates = readCandidate(batteriesPath);
-        if (!candidates) {
+        }
+    }
+    function normalizeAllowedIds(series) {
+        const rawAllowedIds = Array.isArray(series.allowedIds)
+            ? series.allowedIds
+            : null;
+        if (!Array.isArray(rawAllowedIds)) {
             return [];
         }
-        return Object.keys(candidates)
-            .filter(id => /^[a-z0-9_-]+$/i.test(id))
-            .sort((left, right) => left.localeCompare(right));
+        return rawAllowedIds
+            .filter((id) => typeof id === 'string')
+            .map(id => id.trim())
+            .filter(id => id.length > 0);
+    }
+    function normalizeTrackedDevices(series) {
+        if (!Array.isArray(series.trackedDevices)) {
+            return [];
+        }
+        const trackedByKey = new Map();
+        series.trackedDevices.forEach(item => {
+            if (!item || typeof item !== 'object') {
+                return;
+            }
+            const id = typeof item.id === 'string' ? item.id.trim() : '';
+            const normalizedSource = typeof item.source === 'string' ? item.source.trim() : '';
+            const source = normalizedSource.length > 0 ? normalizedSource : 'default';
+            if (!id) {
+                return;
+            }
+            trackedByKey.set(`${id}||${source}`, { id, source });
+        });
+        return Array.from(trackedByKey.values()).sort((left, right) => {
+            const idCompare = left.id.localeCompare(right.id);
+            return idCompare !== 0 ? idCompare : left.source.localeCompare(right.source);
+        });
     }
-    function resolveSolarIdsFromSelfPath() {
-        const solarPath = server.getSelfPath('electrical.solar');
-        const readCandidate = (node) => {
-            if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    function resolveElectricalIdsFromSelfPath(rootPath) {
+        const node = server.getSelfPath(rootPath);
+        const readCandidate = (entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
                 return null;
             }
-            const root = node;
+            const root = entry;
             if (Object.prototype.hasOwnProperty.call(root, 'value')) {
                 const value = root.value;
                 if (value && typeof value === 'object' && !Array.isArray(value)) {
@@ -195,7 +263,7 @@ const start = (server) => {
             }
             return root;
         };
-        const candidates = readCandidate(solarPath);
+        const candidates = readCandidate(node);
         if (!candidates) {
             return [];
         }
@@ -203,19 +271,13 @@ const start = (server) => {
             .filter(id => /^[a-z0-9_-]+$/i.test(id))
             .sort((left, right) => left.localeCompare(right));
     }
-    function getExistingConcreteBmsSeries(templateSeries, existingSeries) {
+    function getExistingConcreteElectricalSeries(templateSeries, familyKey, existingSeries) {
+        const rootPrefix = `${ELECTRICAL_SELF_ROOT_BY_FAMILY[familyKey]}.`;
         return existingSeries
             .filter(series => series.ownerWidgetUuid === templateSeries.ownerWidgetUuid)
             .filter(history_series_service_1.isKipConcreteSeriesDefinition)
             .filter(series => series.seriesId !== templateSeries.seriesId)
-            .map(series => ({ ...series }));
-    }
-    function getExistingConcreteSolarSeries(templateSeries, existingSeries) {
-        return existingSeries
-            .filter(series => series.ownerWidgetUuid === templateSeries.ownerWidgetUuid)
-            .filter(history_series_service_1.isKipConcreteSeriesDefinition)
-            .filter(series => series.seriesId !== templateSeries.seriesId)
-            .filter(series => series.path.startsWith('electrical.solar.'))
+            .filter(series => series.path.startsWith(rootPrefix))
             .map(series => ({ ...series }));
     }
     function mergeSeriesDefinitions(series) {
@@ -226,91 +288,69 @@ const start = (server) => {
         return Array.from(mergedById.values());
     }
     function expandTemplateSeriesDefinitions(payload, existingSeries = []) {
-        const bmsMetrics = ['capacity.stateOfCharge', 'current'];
-        const solarMetrics = ['current', 'panelPower'];
         const expandedById = new Map();
-        const discoveredBatteryIds = resolveBmsBatteryIdsFromSelfPath();
-        const discoveredSolarIds = resolveSolarIdsFromSelfPath();
+        const discoveredIdsByFamily = new Map();
+        const ensureDiscoveredIds = (familyKey) => {
+            if (!discoveredIdsByFamily.has(familyKey)) {
+                const discovered = resolveElectricalIdsFromSelfPath(ELECTRICAL_SELF_ROOT_BY_FAMILY[familyKey]);
+                discoveredIdsByFamily.set(familyKey, discovered);
+            }
+            return discoveredIdsByFamily.get(familyKey) ?? [];
+        };
         payload.forEach(series => {
             if (!(0, history_series_service_1.isKipTemplateSeriesDefinition)(series)) {
                 expandedById.set(series.seriesId, series);
                 return;
             }
-            if ((0, history_series_service_1.isKipBmsTemplateSeriesDefinition)(series)) {
-                if (discoveredBatteryIds.length === 0) {
-                    getExistingConcreteBmsSeries(series, existingSeries).forEach(existing => {
-                        expandedById.set(existing.seriesId, existing);
-                    });
-                    return;
-                }
-                const allowedBatteryIds = Array.isArray(series.allowedBatteryIds)
-                    ? series.allowedBatteryIds
-                        .filter((id) => typeof id === 'string')
-                        .map(id => id.trim())
-                        .filter(id => id.length > 0)
-                    : [];
-                const allowedSet = allowedBatteryIds.length > 0 ? new Set(allowedBatteryIds) : null;
-                const batteryIds = discoveredBatteryIds.filter(id => !allowedSet || allowedSet.has(id));
-                if (batteryIds.length === 0) {
-                    return;
-                }
-                const source = series.source ?? 'default';
-                const sourceKey = slugify(source || 'default') || 'default';
-                batteryIds.forEach(batteryId => {
-                    bmsMetrics.forEach(metric => {
-                        const path = `self.electrical.batteries.${batteryId}.${metric}`;
-                        const seriesId = `${series.ownerWidgetUuid}:bms:${batteryId}:${metric}:${sourceKey}`;
-                        expandedById.set(seriesId, {
-                            ...series,
-                            seriesId,
-                            datasetUuid: `${series.ownerWidgetUuid}:bms:${batteryId}:${metric}:${sourceKey}`,
-                            path,
-                            retentionDurationMs: Number.isFinite(series.retentionDurationMs) ? series.retentionDurationMs : 24 * 60 * 60 * 1000,
-                            expansionMode: null,
-                            allowedBatteryIds: null,
-                            allowedSolarIds: null
-                        });
-                    });
-                });
+            const familyKey = resolveFamilyKeyFromTemplateSeries(series);
+            if (!familyKey) {
+                expandedById.set(series.seriesId, series);
                 return;
             }
-            if ((0, history_series_service_1.isKipSolarTemplateSeriesDefinition)(series)) {
-                if (discoveredSolarIds.length === 0) {
-                    getExistingConcreteSolarSeries(series, existingSeries).forEach(existing => {
+            const seriesPrefix = ELECTRICAL_SERIES_PREFIX_BY_FAMILY[familyKey];
+            const metricList = ELECTRICAL_METRICS_BY_FAMILY[familyKey];
+            const selfRoot = `self.${ELECTRICAL_SELF_ROOT_BY_FAMILY[familyKey]}`;
+            const trackedDevices = normalizeTrackedDevices(series);
+            let concreteDevices = trackedDevices;
+            if (concreteDevices.length === 0) {
+                const discoveredIds = ensureDiscoveredIds(familyKey);
+                if (discoveredIds.length === 0) {
+                    getExistingConcreteElectricalSeries(series, familyKey, existingSeries).forEach(existing => {
                         expandedById.set(existing.seriesId, existing);
                     });
                     return;
                 }
-                const allowedSolarIds = Array.isArray(series.allowedSolarIds)
-                    ? series.allowedSolarIds
-                        .filter((id) => typeof id === 'string')
-                        .map(id => id.trim())
-                        .filter(id => id.length > 0)
-                    : [];
-                const allowedSet = allowedSolarIds.length > 0 ? new Set(allowedSolarIds) : null;
-                const chargerIds = discoveredSolarIds.filter(id => !allowedSet || allowedSet.has(id));
-                if (chargerIds.length === 0) {
+                const allowedIds = normalizeAllowedIds(series);
+                const allowedSet = allowedIds.length > 0 ? new Set(allowedIds) : null;
+                const filteredIds = discoveredIds.filter(id => !allowedSet || allowedSet.has(id));
+                if (filteredIds.length === 0) {
                     return;
                 }
-                const source = series.source ?? 'default';
-                const sourceKey = slugify(source || 'default') || 'default';
-                chargerIds.forEach(chargerId => {
-                    solarMetrics.forEach(metric => {
-                        const path = `self.electrical.solar.${chargerId}.${metric}`;
-                        const seriesId = `${series.ownerWidgetUuid}:solar:${chargerId}:${metric}:${sourceKey}`;
-                        expandedById.set(seriesId, {
-                            ...series,
-                            seriesId,
-                            datasetUuid: `${series.ownerWidgetUuid}:solar:${chargerId}:${metric}:${sourceKey}`,
-                            path,
-                            retentionDurationMs: Number.isFinite(series.retentionDurationMs) ? series.retentionDurationMs : 24 * 60 * 60 * 1000,
-                            expansionMode: null,
-                            allowedBatteryIds: null,
-                            allowedSolarIds: null
-                        });
+                const fallbackSource = series.source ?? 'default';
+                concreteDevices = filteredIds.map(deviceId => ({
+                    id: deviceId,
+                    source: fallbackSource
+                }));
+            }
+            concreteDevices.forEach(device => {
+                const sourceKey = slugify(device.source || 'default') || 'default';
+                metricList.forEach(metric => {
+                    const path = `${selfRoot}.${device.id}.${metric}`;
+                    const seriesId = `${series.ownerWidgetUuid}:${seriesPrefix}:${device.id}:${metric}:${sourceKey}`;
+                    expandedById.set(seriesId, {
+                        ...series,
+                        seriesId,
+                        datasetUuid: `${series.ownerWidgetUuid}:${seriesPrefix}:${device.id}:${metric}:${sourceKey}`,
+                        path,
+                        source: device.source,
+                        retentionDurationMs: Number.isFinite(series.retentionDurationMs) ? series.retentionDurationMs : 24 * 60 * 60 * 1000,
+                        expansionMode: null,
+                        familyKey: null,
+                        allowedIds: null,
+                        trackedDevices: null
                     });
                 });
-            }
+            });
         });
         return Array.from(expandedById.values());
     }
@@ -358,16 +398,15 @@ const start = (server) => {
         }
     }
     function getRouteError(error, fallbackMessage) {
-        const message = String(error?.message || fallbackMessage);
+        const message = error?.message?.trim() || fallbackMessage;
         const normalized = message.toLowerCase();
         if (normalized.includes('invalid ')
             || normalized.includes('missing ')
-            || normalized.includes('body must')
-            || normalized.includes('required')
-            || normalized.includes('expected an iso')) {
+            || normalized.includes('required')) {
             return { statusCode: 400, message };
         }
         if (normalized.includes('sqlite')
+            || normalized.includes('database')
             || normalized.includes('storage unavailable')
             || normalized.includes('not initialized')
             || isSqliteUnavailable()) {
@@ -1228,16 +1267,19 @@ const start = (server) => {
                     const scopedPayload = payload.map(series => ({
                         ...series
                     }));
-                    const isBatteryDiscoveryUnavailable = resolveBmsBatteryIdsFromSelfPath().length === 0;
-                    const isSolarDiscoveryUnavailable = resolveSolarIdsFromSelfPath().length === 0;
                     const preservedTemplateConcreteSeries = scopedPayload
                         .filter(history_series_service_1.isKipTemplateSeriesDefinition)
                         .flatMap(series => {
-                        if ((0, history_series_service_1.isKipBmsTemplateSeriesDefinition)(series) && isBatteryDiscoveryUnavailable) {
-                            return getExistingConcreteBmsSeries(series, currentSeries);
+                        const familyKey = resolveFamilyKeyFromTemplateSeries(series);
+                        if (!familyKey) {
+                            return [];
+                        }
+                        if (normalizeTrackedDevices(series).length > 0) {
+                            return [];
                         }
-                        if ((0, history_series_service_1.isKipSolarTemplateSeriesDefinition)(series) && isSolarDiscoveryUnavailable) {
-                            return getExistingConcreteSolarSeries(series, currentSeries);
+                        const isDiscoveryUnavailable = resolveElectricalIdsFromSelfPath(ELECTRICAL_SELF_ROOT_BY_FAMILY[familyKey]).length === 0;
+                        if (isDiscoveryUnavailable) {
+                            return getExistingConcreteElectricalSeries(series, familyKey, currentSeries);
                         }
                         return [];
                     });

package/plugin/kip-series-contract.js

@@ -1,18 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isKipTemplateSeriesDefinition = isKipTemplateSeriesDefinition;
+exports.isKipElectricalTemplateSeriesDefinition = isKipElectricalTemplateSeriesDefinition;
 exports.isKipBmsTemplateSeriesDefinition = isKipBmsTemplateSeriesDefinition;
 exports.isKipSolarTemplateSeriesDefinition = isKipSolarTemplateSeriesDefinition;
 exports.isKipConcreteSeriesDefinition = isKipConcreteSeriesDefinition;
 exports.isKipSeriesEnabled = isKipSeriesEnabled;
 function isKipTemplateSeriesDefinition(series) {
-    return series.expansionMode === 'bms-battery-tree' || series.expansionMode === 'solar-tree';
+    return series.expansionMode === 'bms-battery-tree'
+        || series.expansionMode === 'solar-tree'
+        || series.expansionMode === 'charger-tree'
+        || series.expansionMode === 'inverter-tree'
+        || series.expansionMode === 'alternator-tree'
+        || series.expansionMode === 'ac-tree';
+}
+function isKipElectricalTemplateSeriesDefinition(series) {
+    return isKipTemplateSeriesDefinition(series);
 }
 function isKipBmsTemplateSeriesDefinition(series) {
-    return series.expansionMode === 'bms-battery-tree';
+    return series.expansionMode === 'bms-battery-tree' && (series.familyKey == null || series.familyKey === 'batteries');
 }
 function isKipSolarTemplateSeriesDefinition(series) {
-    return series.expansionMode === 'solar-tree';
+    return series.expansionMode === 'solar-tree' && (series.familyKey == null || series.familyKey === 'solar');
 }
 function isKipConcreteSeriesDefinition(series) {
     return series.expansionMode == null;

package/plugin/openApi.json

@@ -217,21 +217,38 @@
                                 "nullable": true,
                                 "description": "Null for concrete series definitions."
                             },
-                            "allowedBatteryIds": {
+                            "familyKey": {
+                                "type": "string",
+                                "nullable": true,
+                                "description": "Concrete series do not use family key and should leave this null."
+                            },
+                            "allowedIds": {
                                 "type": "array",
                                 "nullable": true,
                                 "items": {
                                     "type": "string"
                                 },
-                                "description": "Concrete series do not use battery filters and should leave this null."
+                                "description": "Concrete series do not use template filters and should leave this null."
                             },
-                            "allowedSolarIds": {
+                            "trackedDevices": {
                                 "type": "array",
                                 "nullable": true,
                                 "items": {
-                                    "type": "string"
+                                    "type": "object",
+                                    "properties": {
+                                        "id": {
+                                            "type": "string"
+                                        },
+                                        "source": {
+                                            "type": "string"
+                                        }
+                                    },
+                                    "required": [
+                                        "id",
+                                        "source"
+                                    ]
                                 },
-                                "description": "Concrete series do not use solar charger filters and should leave this null."
+                                "description": "Concrete series do not use tracked device template filters and should leave this null."
                             }
                         }
                     }
@@ -249,34 +266,68 @@
                                 "type": "string",
                                 "enum": [
                                     "widget-bms",
-                                    "widget-solar-charger"
+                                    "widget-solar-charger",
+                                    "widget-charger",
+                                    "widget-inverter",
+                                    "widget-alternator",
+                                    "widget-ac"
                                 ]
                             },
                             "expansionMode": {
                                 "type": "string",
                                 "enum": [
                                     "bms-battery-tree",
-                                    "solar-tree"
+                                    "solar-tree",
+                                    "charger-tree",
+                                    "inverter-tree",
+                                    "alternator-tree",
+                                    "ac-tree"
                                 ]
                             },
-                            "allowedBatteryIds": {
+                            "familyKey": {
+                                "type": "string",
+                                "enum": [
+                                    "batteries",
+                                    "solar",
+                                    "chargers",
+                                    "inverters",
+                                    "alternators",
+                                    "ac"
+                                ]
+                            },
+                            "allowedIds": {
                                 "type": "array",
                                 "nullable": true,
                                 "items": {
                                     "type": "string"
-                                }
+                                },
+                                "description": "Template device IDs to include. Null or empty includes all discovered devices."
                             },
-                            "allowedSolarIds": {
+                            "trackedDevices": {
                                 "type": "array",
                                 "nullable": true,
                                 "items": {
-                                    "type": "string"
-                                }
+                                    "type": "object",
+                                    "properties": {
+                                        "id": {
+                                            "type": "string"
+                                        },
+                                        "source": {
+                                            "type": "string"
+                                        }
+                                    },
+                                    "required": [
+                                        "id",
+                                        "source"
+                                    ]
+                                },
+                                "description": "Explicit tracked device id/source pairs to expand. When provided, template expansion skips self-tree discovery and emits one concrete series per pair and metric."
                             }
                         },
                         "required": [
                             "ownerWidgetSelector",
-                            "expansionMode"
+                            "expansionMode",
+                            "familyKey"
                         ]
                     }
                 ]

package/plugin/sqlite-history-storage.service.js

@@ -709,7 +709,8 @@ class SqliteHistoryStorageService {
                 });
             }
             catch (err) {
-                this.logger.error(`[SERIES STORAGE] Prune failed: ${err?.message ?? err}`);
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger.error(`[SERIES STORAGE] Prune failed: ${message}`);
             }
         }, SqliteHistoryStorageService.FOUR_HOURS_INTERVAL);
         this.pruneJob.unref?.();
@@ -739,7 +740,8 @@ class SqliteHistoryStorageService {
                 });
             }
             catch (err) {
-                this.logger.error(`[SERIES STORAGE] Stale series cleanup failed: ${err?.message ?? err}`);
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger.error(`[SERIES STORAGE] Stale series cleanup failed: ${message}`);
             }
         }, SqliteHistoryStorageService.EIGHT_HOURS_INTERVAL);
         this.staleSeriesCleanupJob.unref?.();