hoffmation-base 3.8.0 → 4.1.0

package/lib/services/dbo/postgreSqlPersist.js

@@ -16,40 +16,52 @@ class PostgreSqlPersist {
     }
     /** @inheritDoc */
     addRoom(room) {
+        // The name is bound rather than pasted in: it is a text a person gave, and an apostrophe in one - a room
+        // called `Anna's Zimmer` - closes the literal it would sit in. The statement would then be unparseable,
+        // the insert would fail with a logged warning, and the room would silently not be recorded. The floor is
+        // a number and stays this file's own text.
         this.query(`
       insert into hoffmation_schema."BasicRooms" (name, etage)
-      values ('${room.roomName}', ${room.etage}) ON CONFLICT (name)
+      values ($1, ${room.etage}) ON CONFLICT (name)
     DO
       UPDATE SET
         etage = ${room.etage}
       ;
-    `);
+    `, [room.roomName]);
     }
     /** @inheritDoc */
     addDevice(device) {
+        // Room, key and custom name are texts a person gave, and the id is a text as well - each of them can
+        // close the literal it would be pasted into. This row is the one the device data tables reference, so a
+        // failed insert here is not one lost record but a whole device missing its anchor. The update half binds
+        // the same placeholders: it is the one an interpolation is most easily left behind in. The device type is
+        // a number and stays this file's own text.
         this.query(`
       insert into hoffmation_schema."DeviceInfo" ("deviceid", "roomname", "alldeviceskey", "customname", "devtype")
-      values ('${device.id}', '${device.info.room}', '${device.info.allDevicesKey}', '${device.info.customName}',
+      values ($1, $2, $3, $4,
               ${device.deviceType}) ON CONFLICT ("deviceid")
     DO
       UPDATE SET
-        "roomname" = '${device.info.room}',
-        "alldeviceskey" = '${device.info.allDevicesKey}',
-        "customname" = '${device.info.customName}',
+        "roomname" = $2,
+        "alldeviceskey" = $3,
+        "customname" = $4,
         "devtype" = ${device.deviceType}
       ;
-    `);
+    `, [device.id, device.info.room, device.info.allDevicesKey, device.info.customName]);
     }
     /** @inheritDoc */
     async getLastDesiredPosition(device) {
+        // The device id is bound rather than pasted in: it is a string, and a string inside quotes can close
+        // them. The rest of the filter is this file's own text and stays in the statement - a bound id compares
+        // against the column exactly as the literal did, so the reader answers what it always answered.
         const dbResult = await this.query(`SELECT position
        from hoffmation_schema."ShutterDeviceData"
-       WHERE "deviceID" = '${device.id}'
+       WHERE "deviceID" = $1
          and date >= CURRENT_DATE
          AND date
            < CURRENT_DATE + INTERVAL '1 DAY'
        ORDER BY date desc
-         Limit 1`);
+         Limit 1`, [device.id]);
         if (dbResult !== null && dbResult.length > 0) {
             return dbResult[0];
         }
@@ -58,13 +70,15 @@ class PostgreSqlPersist {
     }
     /** @inheritDoc */
     async motionSensorTodayCount(device) {
+        // Bound for the same reason as the reader above, and with the same result: the count is taken over the
+        // rows whose id equals this string, whatever the string spells.
         const dbResult = await this.query(`SELECT Count(*)
        from hoffmation_schema."MotionSensorDeviceData"
-       WHERE "deviceID" = '${device.id}'
+       WHERE "deviceID" = $1
          and "movementDetected"
          and date >= CURRENT_DATE
          AND date
-           < CURRENT_DATE + INTERVAL '1 DAY'`);
+           < CURRENT_DATE + INTERVAL '1 DAY'`, [device.id]);
         if (dbResult !== null && dbResult.length > 0) {
             const result = dbResult[0];
             result.count = Number(result.count);
@@ -87,25 +101,220 @@ class PostgreSqlPersist {
     async getTemperatureHistory(deviceId, startDate, endDate) {
         const end = endDate !== null && endDate !== void 0 ? endDate : new Date();
         const start = startDate !== null && startDate !== void 0 ? startDate : new Date(end.getTime() - 24 * 60 * 60 * 1000);
+        // The device id is bound rather than pasted in: it is a string this reader is handed, and a string inside
+        // quotes can close them. The dates travel the same way for consistency - bound as ISO text, which is what
+        // the naive column stores and hence the same comparison the statement makes with a literal.
         const dbResult = await this.query(`SELECT temperature, date
        from hoffmation_schema."TemperatureSensorDeviceData"
-       WHERE "deviceID" = '${deviceId}'
-         and date >= '${start.toISOString()}'
-         AND date <= '${end.toISOString()}'
+       WHERE "deviceID" = $1
+         and date >= $2
+         AND date <= $3
+       ORDER BY DATE DESC`, [deviceId, start.toISOString(), end.toISOString()]);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getTemperatureHistory', dbResult, start, end);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // The column is nullable and the write path stores a null whenever the sensor has nothing to say.
+            // Converted directly an absent value becomes 0, and 0 °C is not an impossible reading but an ordinary
+            // winter one - so it never looks wrong downstream, it only pulls every average it enters towards
+            // freezing. A genuine zero survives: it is a temperature this installation really sees, and only an
+            // absent or unreadable value is dropped.
+            const temperature = PostgreSqlPersist.toFiniteNumber(entry.temperature);
+            // A measurement without a timestamp cannot be placed: read as a Date an absent one lands on
+            // 1970-01-01, which looks like a reading at the far edge of the window rather than like a missing one.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.date);
+            if (temperature === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            result.push({
+                temperature: temperature,
+                date: date,
+            });
+        }
+        PostgreSqlPersist.logDroppedRows('getTemperatureHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
+    async getBatteryLevelHistory(startDate, endDate) {
+        const dbResult = await this.query(`SELECT "batteryLevel", "endDate"
+       from hoffmation_schema."EnergyCalculation"
+       WHERE "endDate" >= '${startDate.toISOString()}'
+         AND "endDate" <= '${endDate.toISOString()}'
+       ORDER BY "endDate" DESC`);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getBatteryLevelHistory', dbResult, startDate, endDate);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // "batteryLevel" was added to an existing table (see initialize()), so early rows carry no level.
+            // Reading such a row as 0 % would invent a nightly low that never happened. The level is read at the
+            // end of the interval (victron-device.ts:279-283 sets it right before persisting), so the reading is
+            // dated with "endDate" - the same time base the consumption readings use.
+            const stored = PostgreSqlPersist.toFiniteNumber(entry.batteryLevel);
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.endDate);
+            if (stored === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            // The column holds a fraction, not a percentage: victron-device.ts:279 divides the device's percentage
+            // by 100 before persisting. Everything downstream of here - the reserve, the corrected sample, the
+            // thresholds of the unit itself - is in percent, so the conversion happens here. Do not "tidy" this
+            // multiplication away without changing that line.
+            const level = utils_1.Utils.round(stored * 100, 1);
+            // Outside 0..100 this is not a state of charge: victron-device.ts:89-95 reports -1 when the battery
+            // says nothing, which lands in the column as -0.01. An invented trough is worse than a missing one.
+            // A plain 0 counts as "not reported" as well, and the trade-off behind that is deliberate: the column
+            // cannot tell "not reported" from "really empty", because iEnergyCalculation.batteryLevel starts at 0
+            // and an energy manager that never sets it (JsObjectEnergyManager) persists that 0 on every row. The
+            // price is that a genuine zero reading is discarded - which beats fitting the model on an invented one,
+            // and a battery that reports 0 % does not occur in practice: its management cuts off well before, and
+            // an unknown level arrives as -1, never as 0.
+            if (level <= 0 || level > 100) {
+                dropped++;
+                continue;
+            }
+            result.push({ level: level, date: date });
+        }
+        PostgreSqlPersist.logDroppedRows('getBatteryLevelHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
+    async getEnergyConsumptionHistory(startDate, endDate) {
+        const dbResult = await this.query(`SELECT "selfConsumedKwH", "drawnKwH", "endDate"
+       from hoffmation_schema."EnergyCalculation"
+       WHERE "endDate" >= '${startDate.toISOString()}'
+         AND "endDate" <= '${endDate.toISOString()}'
+       ORDER BY "endDate" DESC`);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getEnergyConsumptionHistory', dbResult, startDate, endDate);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // What the house used out of its own generation plus what it pulled from the grid. "injectedKwH" is
+            // export and deliberately absent - both energy managers build the three so that
+            // selfConsuming + drawing == total house consumption (phaseState.ts:11-14, victron-device.ts:126).
+            const selfConsumed = PostgreSqlPersist.toFiniteNumber(entry.selfConsumedKwH);
+            const drawn = PostgreSqlPersist.toFiniteNumber(entry.drawnKwH);
+            // The row's energy belongs to the interval it closes, so it is timestamped with its end - a reading
+            // dated at its start would be counted into the following window instead of its own.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.endDate);
+            if (selfConsumed === undefined || drawn === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            result.push({ consumedKwh: selfConsumed + drawn, date: date });
+        }
+        PostgreSqlPersist.logDroppedRows('getEnergyConsumptionHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
+    async getActuatorHistory(deviceId, startDate, endDate) {
+        // The device id is bound rather than pasted in: it is a string this reader is handed, and a string
+        // inside quotes can close them. The dates travel the same way for consistency - bound as ISO text, which
+        // is what the naive column stores and hence the same comparison the statement makes with a literal.
+        const dbResult = await this.query(`SELECT "on", date
+       from hoffmation_schema."ActuatorDeviceData"
+       WHERE "deviceID" = $1
+         and date >= $2
+         AND date <= $3
+       ORDER BY DATE DESC`, [deviceId, startDate.toISOString(), endDate.toISOString()]);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getActuatorHistory', dbResult, startDate, endDate);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // A row without a state says nothing; counting it as off would understate the run time.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.date);
+            if (entry.on === null || entry.on === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            result.push({ on: entry.on === true || entry.on === 'true' || entry.on === 't', date: date });
+        }
+        PostgreSqlPersist.logDroppedRows('getActuatorHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
+    async getWeatherDaySummaries(startDate, endDate) {
+        const dbResult = await this.query(`SELECT date, "cloudCover", "tempMin", "tempMax", "precipitation"
+       from hoffmation_schema."WeatherDaySummary"
+       WHERE date >= '${startDate.toISOString()}'
+         AND date <= '${endDate.toISOString()}'
        ORDER BY DATE DESC`);
         if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getWeatherDaySummaries', dbResult, startDate, endDate);
             return [];
         }
         const result = [];
+        let dropped = 0;
         for (const entry of dbResult) {
+            const cloudCover = PostgreSqlPersist.toFiniteNumber(entry.cloudCover);
+            const tempMin = PostgreSqlPersist.toFiniteNumber(entry.tempMin);
+            const tempMax = PostgreSqlPersist.toFiniteNumber(entry.tempMax);
+            // A half filled aggregate is dropped rather than completed: a substitute cloud cover would be fitted
+            // as if it had been measured.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.date);
+            if (cloudCover === undefined || tempMin === undefined || tempMax === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            // Read after the completeness check and deliberately outside it, mirroring the write path: every row
+            // stored before this column existed carries a null here, and none of them may be dropped for it. An
+            // absent value stays absent rather than becoming a 0, which would read as a dry day.
+            const precipitation = PostgreSqlPersist.toFiniteNumber(entry.precipitation);
             result.push({
-                temperature: Number(entry.temperature),
-                date: new Date(entry.date),
+                date: date,
+                cloudCover: cloudCover,
+                tempMin: tempMin,
+                tempMax: tempMax,
+                precipitation: precipitation,
             });
         }
+        PostgreSqlPersist.logDroppedRows('getWeatherDaySummaries', dropped);
         return result;
     }
     /** @inheritDoc */
+    persistWeatherDaySummary(summary) {
+        var _a;
+        // The values are bound, not written into the statement. Every other write in this file carries figures
+        // this process produced itself; these come from the weather service, and they are read back out of this
+        // table by a decision that switches an appliance. The fetcher already refuses what is not a number, but
+        // that check sits one caller away from being bypassed - so the statement itself is fixed text and the
+        // aggregate is data. The update half binds the same three placeholders: it is the one an interpolation
+        // is most easily left behind in.
+        this.query(`
+      insert into hoffmation_schema."WeatherDaySummary" ("date", "cloudCover", "tempMin", "tempMax", "precipitation")
+      values ($1, $2, $3, $4, $5) ON CONFLICT ("date")
+    DO
+      UPDATE SET
+        "cloudCover" = $2,
+        "tempMin" = $3,
+        "tempMax" = $4,
+        "precipitation" = COALESCE($5, hoffmation_schema."WeatherDaySummary"."precipitation")
+      ;
+    `, [
+            summary.date.toISOString(),
+            summary.cloudCover,
+            summary.tempMin,
+            summary.tempMax,
+            // Undefined is bound as null on purpose - the column has to be able to say "not recorded", and a 0
+            // would say "it did not rain". The three columns above are overwritten unconditionally because the
+            // running day's forecast moves; this one keeps what is already stored when nothing new arrived, so a
+            // refetch that comes back without the field cannot erase a figure an earlier one delivered.
+            (_a = summary.precipitation) !== null && _a !== void 0 ? _a : null,
+        ]);
+    }
+    /** @inheritDoc */
     async initialize() {
         await this.psql.connect();
         // Execute BasicRoomsDDL
@@ -319,6 +528,21 @@ BEGIN
 
   END IF;
 
+  IF (SELECT to_regclass('hoffmation_schema."SoilSensorDeviceData"') IS NULL) Then
+    -- Deliberately without a foreign key on "DeviceInfo", for the same reason as the air quality table above:
+    -- creating one needs the REFERENCES privilege on that table, which an existing installation whose tables
+    -- were created by another role may not grant.
+    create table if not exists hoffmation_schema."SoilSensorDeviceData"
+    (
+        "deviceID"        varchar(60) not null,
+        "soilMoisture"    double precision,
+        date              timestamp   not null,
+        constraint soilsensordevicedata_pk
+            primary key ("deviceID", date)
+    );
+
+  END IF;
+
   IF (SELECT to_regclass('hoffmation_schema."BatteryDeviceData"') IS NULL) Then  
     create table if not exists hoffmation_schema."BatteryDeviceData"
     (
@@ -382,7 +606,31 @@ BEGIN
     );
     
   END IF;
-  
+
+  IF (SELECT to_regclass('hoffmation_schema."WeatherDaySummary"') IS NULL) Then
+    create table hoffmation_schema."WeatherDaySummary"
+    (
+        date         timestamp not null
+            constraint weatherdaysummary_pk
+                primary key,
+        "cloudCover" double precision,
+        "tempMin"    double precision,
+        "tempMax"    double precision,
+        "precipitation" double precision
+    );
+
+  END IF;
+
+  IF (SELECT COUNT(column_name) = 0
+    FROM information_schema.columns
+    WHERE table_name = 'WeatherDaySummary'
+      and column_name = 'precipitation') Then
+    -- The table predates this column, so an existing installation gets it added rather than created. Existing
+    -- rows keep a null, which is the honest answer: nothing was recorded for those days.
+    alter table hoffmation_schema."WeatherDaySummary"
+      add "precipitation" double precision;
+  END IF;
+
   IF (SELECT COUNT(column_name) = 0
     FROM information_schema.columns
     WHERE table_name = 'EnergyCalculation'
@@ -462,10 +710,14 @@ $$;`);
     }
     /** @inheritDoc */
     persistSwitchInput(device, pressType, buttonName) {
+        // The button name is a text a person gave and the id is a text as well, so both are bound - an apostrophe
+        // in either closes the literal it would be pasted into. The press type is a number and stays this file's
+        // own text, and so does the timestamp: the column is `timestamp without time zone` and every recorded row
+        // was written as an interpolated `toISOString()`.
         this.query(`
       insert into hoffmation_schema."ButtonSwitchPresses" ("deviceID", "pressType", "buttonName", "date")
-      values ('${device.id}', ${pressType}, '${buttonName}', '${new Date().toISOString()}');
-    `);
+      values ($1, ${pressType}, $2, '${new Date().toISOString()}');
+    `, [device.id, buttonName]);
     }
     /** @inheritDoc */
     persistMotionSensor(device) {
@@ -511,6 +763,53 @@ $$;`);
     `);
     }
     /** @inheritDoc */
+    persistSoilSensor(device) {
+        this.query(`
+      insert into hoffmation_schema."SoilSensorDeviceData" ("deviceID", "soilMoisture", "date")
+      values ('${device.id}', ${device.soilMoisture}, '${new Date().toISOString()}');
+    `);
+    }
+    /** @inheritDoc */
+    async getSoilMoistureHistory(deviceId, startDate, endDate) {
+        // The device id is bound rather than pasted in: it is a string this reader is handed, and a string inside
+        // quotes can close them. The dates travel the same way for consistency - bound as ISO text, which is what
+        // the naive column stores and hence the same comparison the statement makes with a literal.
+        const dbResult = await this.query(`SELECT "soilMoisture", date
+       from hoffmation_schema."SoilSensorDeviceData"
+       WHERE "deviceID" = $1
+         and date >= $2
+         AND date <= $3
+       ORDER BY DATE DESC`, [deviceId, startDate.toISOString(), endDate.toISOString()]);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getSoilMoistureHistory', dbResult, startDate, endDate);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // An absent value read as 0 would read as bone dry soil - the one reading that makes a watering
+            // decision act. A genuine 0 % survives; only an absent or unreadable one is dropped.
+            const soilMoisture = PostgreSqlPersist.toFiniteNumber(entry.soilMoisture);
+            // A reading without a timestamp cannot be placed: read as a Date an absent one lands on 1970-01-01,
+            // which looks like a reading at the far edge of the window rather than like a missing one.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.date);
+            if (soilMoisture === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            // Outside 0..100 this is not a soil moisture. The sentinel the sensor carries before its first reading
+            // is -1, and the write path already refuses to store it - this is the second line of defence, for rows
+            // an older version may have written.
+            if (soilMoisture < 0 || soilMoisture > 100) {
+                dropped++;
+                continue;
+            }
+            result.push({ soilMoisture: soilMoisture, date: date });
+        }
+        PostgreSqlPersist.logDroppedRows('getSoilMoistureHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
     persistBatteryDevice(device) {
         this.query(`
       insert into hoffmation_schema."BatteryDeviceData" ("deviceID", "battery", "date")
@@ -548,36 +847,57 @@ $$;`);
     }
     /** @inheritDoc */
     persistSettings(id, settings, customName) {
+        // Of the four write paths that carry a text this is the widest: `settings` is a `JSON.stringify` of a
+        // whole settings object, so every value a person ever typed into any device setting arrives here. One
+        // apostrophe anywhere inside it closes the literal it would be pasted into - the statement fails, the
+        // failure is only a logged warning, and the setting is silently not stored until someone notices it gone
+        // after a restart. All three texts are bound, in both halves of the upsert; the blob keeps its own
+        // placeholder in the update half. The timestamp stays this file's own text: the column is `timestamp
+        // without time zone` and every recorded row was written as an interpolated `toISOString()`.
         this.query(`
       insert into hoffmation_schema."Settings" (id, settings, customname, date)
-      values ('${id}', '${settings}', '${customName}', '${new Date().toISOString()}') ON CONFLICT (id, date)
+      values ($1, $2, $3, '${new Date().toISOString()}') ON CONFLICT (id, date)
     DO
       UPDATE SET
-        settings = '${settings}',
-        customname = '${customName}'
+        settings = $2,
+        customname = $3
       ;
-    `);
+    `, [id, settings, customName]);
     }
     /** @inheritDoc */
     async loadSettings(id) {
+        // The id is bound rather than pasted in. Of the readers in this file it is the one whose argument does
+        // not come out of the device list: besides ObjectSettings.initializeFromDb, which passes a holder's id,
+        // ApiService.loadConfig hands through whatever its caller asks for - so this is a string from beyond
+        // this process, and a string inside quotes can close them.
         const dbResult = await this.query(`SELECT settings::text, id, date
        from hoffmation_schema."Settings"
-       WHERE "id" = '${id}'
+       WHERE "id" = $1
        ORDER BY "date" DESC
-         LIMIT 1`);
+         LIMIT 1`, [id]);
         if (dbResult !== null && dbResult.length > 0) {
             return dbResult[0].settings;
         }
         logging_1.ServerLogService.writeLog(enums_1.LogLevel.Info, `No persisted settings for ${id} found`);
         return undefined;
     }
-    async query(query) {
+    /**
+     * Runs a statement, optionally with bind values.
+     *
+     * `values` is what makes a statement able to carry data that did not come from this process: the driver
+     * sends text and values apart, so a value is never parsed as SQL, whatever it spells. Anything that is not
+     * a literal fixed by this file belongs in there rather than in the string.
+     * @param query - The statement, with `$1..$n` where values are bound
+     * @param values - The values to bind, in the order of their placeholders
+     * @returns - The rows, or null when the statement did not come back
+     */
+    async query(query, values) {
         if (!this.isPsqlReady()) {
             return null;
         }
         return new Promise((resolve) => {
             this.psql
-                .query(query)
+                .query(query, values)
                 .then((result) => {
                 resolve(result.rows);
             })
@@ -588,6 +908,51 @@ $$;`);
             });
         });
     }
+    /**
+     * A missing or unreadable history is a defined state of the history based decisions, not a failure - but it
+     * has to be visible once, otherwise "no answer" and "nothing recorded" look the same from the outside.
+     * @param reader - The reader that came up empty
+     * @param dbResult - null when the query itself did not come back, an empty set otherwise
+     * @param startDate - Start of the requested window
+     * @param endDate - End of the requested window
+     */
+    static logEmptyAnswer(reader, dbResult, startDate, endDate) {
+        logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, `${reader}: ${dbResult === null ? 'no answer' : 'no rows'} for ${startDate.toISOString()} - ${endDate.toISOString()}`);
+    }
+    static logDroppedRows(reader, dropped) {
+        if (dropped === 0) {
+            return;
+        }
+        logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, `${reader}: dropped ${dropped} unusable row(s)`);
+    }
+    /**
+     * Turns what the driver made of a `timestamp without time zone` back into the instant it was stored for.
+     *
+     * The write path stores `new Date(...).toISOString()`. For a naive column PostgreSQL silently drops the
+     * zone suffix of the literal and keeps the UTC wall clock. Reading it back, the driver rebuilds those
+     * components with the **local** multi argument Date constructor (`postgres-date/index.js:49-50`, registered
+     * for OID 1114 in `pg-types/lib/textParsers.js:175`), so the Date is off by the machine's zone offset - one
+     * hour or two in Berlin, and the offset changes inside a single 90 day window at the daylight saving
+     * switch. Reading the local components back out as UTC undoes exactly that.
+     *
+     * Only the read side compensates: `toISOString()` already stores the UTC wall clock and three years of
+     * recorded history are written that way, so changing the write path would put old and new rows at odds.
+     * @param value - The Date the driver produced, or null for an absent timestamp
+     * @returns - The instant, or undefined when there is none to be had
+     */
+    static fromNaiveTimestamp(value) {
+        if (value === null || isNaN(value.getTime())) {
+            return undefined;
+        }
+        return new Date(Date.UTC(value.getFullYear(), value.getMonth(), value.getDate(), value.getHours(), value.getMinutes(), value.getSeconds(), value.getMilliseconds()));
+    }
+    static toFiniteNumber(value) {
+        if (value === null || value === undefined || value === '') {
+            return undefined;
+        }
+        const parsed = Number(value);
+        return isFinite(parsed) ? parsed : undefined;
+    }
     isPsqlReady() {
         if (!this.initialized) {
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, 'Db is not yet initialized');

package/lib/services/dbo/soil-moisture-row.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The raw shape the driver hands back for one stored soil moisture reading.
+ *
+ * Same conversion rules as {@link BatteryLevelRow}: the numeric column may arrive as a string, and the date is
+ * a Date built from naive components because the column carries no zone.
+ *
+ * Not part of the published surface - a database row shape is not an interface anyone implements.
+ */
+export type SoilMoistureRow = {
+    /** The stored soil moisture in percent, as the driver hands it back */
+    soilMoisture: string | number | null;
+    /** When the reading was taken, built from naive components */
+    date: Date | null;
+};

package/lib/services/dbo/soil-moisture-row.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/dbo/weather-day-summary-row.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The raw shape the driver hands back for one stored daily weather aggregate.
+ *
+ * Same conversion rules as {@link BatteryLevelRow}: numeric columns may arrive as a string, and the date is a
+ * Date built from naive components because the column carries no zone.
+ *
+ * Not part of the published surface - a database row shape is not an interface anyone implements.
+ */
+export type WeatherDaySummaryRow = {
+    /** The day the aggregate belongs to, built from naive components */
+    date: Date | null;
+    /** Cloud cover of that day in percent, as the driver hands it back */
+    cloudCover: string | number | null;
+    /** Lowest air temperature of that day in degrees celsius */
+    tempMin: string | number | null;
+    /** Highest air temperature of that day in degrees celsius */
+    tempMax: string | number | null;
+    /** Total precipitation of that day in millimetres. Null for every row written before the column existed */
+    precipitation: string | number | null;
+};

package/lib/services/dbo/weather-day-summary-row.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });