hoffmation-base 3.8.0 → 4.1.0

package/lib/services/energy/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./energy-history-service"), exports);

package/lib/services/energy/plant-energy-dials.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The part of an energy manager's settings the energy history service needs, read structurally to stay off a
+ * concrete manager.
+ *
+ * All of these describe the **plant**: how much its battery holds, and how good its own recorded data has to
+ * be before a statement is built from it. They are read off the manager rather than handed in, because a
+ * caller could only fill them by reading this same global place - an option filled that way is a pass-through,
+ * and it would let two callers disagree about what counts as a covered day of one and the same plant.
+ *
+ * Not part of the published surface: it describes how the service reads a manager, not something a consumer of
+ * the library implements.
+ */
+export interface iPlantEnergyDials {
+    /** The capacity of the battery in watt hours */
+    batteryCapacityWattage?: number;
+    /** Share of the expected consumption readings a historical day has to carry to be counted, 0 to 1 */
+    historyMinimumDayCoverage?: number;
+    /** The quantile of the historical consumption windows the model free bound is calculated with, 0 to 1 */
+    historyConsumptionQuantile?: number;
+    /** How many usable consumption window sums are needed before that quantile means anything */
+    historyMinimumConsumptionDays?: number;
+}

package/lib/services/energy/plant-energy-dials.js

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

package/lib/services/https-service.d.ts

@@ -1,12 +1,58 @@
 import { HTTPSOptions } from './HTTPSOptions';
 export declare class HTTPSService {
+    /**
+     * The status code the callback is handed for a request that produced no answer: no answer of the endpoint,
+     * an exhausted retry chain, a failing socket or a failing response.
+     *
+     * Negative on purpose. It is outside the range HTTP status codes occupy, so no comparison a caller writes
+     * against a real code - `=== 200`, a check for the successful range, a switch over the classes - can match
+     * it by accident; a failure that a caller reads as success is worse than one it never hears about. Zero was
+     * not an option: the successful path already yields it for an answer that ended without a status code, so
+     * the two cases would be indistinguishable.
+     */
+    static readonly failureStatusCode: number;
+    /**
+     * The body the callback is handed alongside `failureStatusCode`.
+     *
+     * Not the empty string, which a caller looking only at the body would take for an answer that happened to
+     * carry nothing. It names neither host nor path, because a caller is free to log what it receives and the
+     * path of a request carries its query.
+     */
+    static readonly failureResponse: string;
+    /**
+     * How long one attempt may go without any traffic on its socket before it is given up on and handed to the
+     * retry chain.
+     *
+     * A limit is needed at all because silence is not an error: an endpoint that accepts the connection and
+     * then says nothing produces neither `error` nor `response`, so without one the attempt - and every caller
+     * waiting on its callback - stays open until the process ends.
+     *
+     * Thirty seconds, because the whole chain has to stay inside the cadence of the callers that repeat: the
+     * weather service asks every ten minutes, and the default of five retries makes six attempts, so a fully
+     * silent endpoint costs about three minutes. That leaves a request no way to still be running when the next
+     * one starts, while staying far above the seconds a loaded endpoint may legitimately need to answer.
+     */
+    static readonly requestTimeoutMs: number;
+    /**
+     * Sends one HTTPS request and reports its outcome to `responseCallback` **exactly once**, on every way the
+     * request can end: an answer, an exhausted retry chain, a failing socket or a failing response. A caller
+     * may therefore wrap this in a promise and rely on it settling.
+     * @param options - Host, path, headers, method and port of the request
+     * @param postData - The body to send; nothing is written when it is empty
+     * @param retryOnError - How many further attempts a failing socket may cost before the request is given up
+     * @param responseCallback - Receives body and status code; a failure arrives as `failureResponse` and
+     * `failureStatusCode`
+     */
     static request(options: HTTPSOptions, postData?: string, retryOnError?: number, responseCallback?: (data: string, statuscode: number) => void): void;
     /**
-     * Downloads a file from a given url to the given location.
+     * Downloads a file from a given url to the given location, and **settles either way**: on every way the
+     * download can end - the file written, the endpoint refusing, the request failing, the answer breaking off
+     * or the disk failing - the promise is resolved or rejected exactly once.
      * If the location doesn't exist, it will be created quietly.
      * @param url - URL to download file from
      * @param filePath - Path to save file to
-     * @returns A promise that resolves to true if the file was downloaded successfully, false otherwise
+     * @returns A promise that resolves to true once the file is written and to false when the transfer failed;
+     * it is rejected when the endpoint refused the download or when the file could not be written
      */
     static downloadFile(url: string, filePath: string): Promise<boolean>;
     private static defaultCallback;

package/lib/services/https-service.js

@@ -44,31 +44,79 @@ const logging_1 = require("../logging");
 const enums_1 = require("../enums");
 const utils_1 = require("../utils");
 class HTTPSService {
+    /**
+     * Sends one HTTPS request and reports its outcome to `responseCallback` **exactly once**, on every way the
+     * request can end: an answer, an exhausted retry chain, a failing socket or a failing response. A caller
+     * may therefore wrap this in a promise and rely on it settling.
+     * @param options - Host, path, headers, method and port of the request
+     * @param postData - The body to send; nothing is written when it is empty
+     * @param retryOnError - How many further attempts a failing socket may cost before the request is given up
+     * @param responseCallback - Receives body and status code; a failure arrives as `failureResponse` and
+     * `failureStatusCode`
+     */
     static request(options, postData = '', retryOnError = 5, responseCallback = HTTPSService.defaultCallback) {
         const responseData = [];
-        const req = https_1.default.request(options, (res) => {
+        // True as soon as this attempt has done with the callback: either it has delivered the outcome, or it has
+        // handed the attempt to a retry that delivers for it. Both ways out of a request can fire for the same
+        // one - a socket error may still arrive after the response has ended, and an `end` may follow an error on
+        // the response - and every one of them is guarded by this flag. Two calls would be a new fault class in
+        // place of the old one, and an unguarded late error would open a second retry chain that calls the
+        // callback again from its own end.
+        let settled = false;
+        const settle = (data, statuscode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            responseCallback(data, statuscode);
+        };
+        // A copy rather than the options themselves: the limit belongs to this service, not to the request the
+        // caller described, and a caller may hand the same options to a second request.
+        const req = https_1.default.request({ ...options, timeout: HTTPSService.requestTimeoutMs }, (res) => {
             res.on('data', (data) => {
                 responseData.push(data.toString());
             });
             res.on('end', () => {
                 var _a;
-                responseCallback(responseData.join(''), (_a = res.statusCode) !== null && _a !== void 0 ? _a : 0);
+                settle(responseData.join(''), (_a = res.statusCode) !== null && _a !== void 0 ? _a : 0);
             });
             res.on('error', (e) => {
                 logging_1.ServerLogService.writeLog(enums_1.LogLevel.Error, `HTTPS Error: ${e}`);
+                // No retry from here: part of the answer may already have been handed out, and repeating a request
+                // whose body was sent is not free. The response ends here, so the caller hears about it here.
+                settle(HTTPSService.failureResponse, HTTPSService.failureStatusCode);
             });
         });
+        req.on('timeout', () => {
+            if (settled) {
+                // The socket of a request whose outcome is already delivered may idle as long as it likes; tearing
+                // that one down would be about a request nobody is waiting for any more.
+                return;
+            }
+            // `timeout` only reports the idle socket, it does not end anything - node leaves that to this listener.
+            // Destroying with an error routes the silence into the handler below, so it costs a retry and ends in
+            // the callback exactly like an endpoint that was never reachable. The message names neither host nor
+            // path: that handler logs what it is given, and the path of a request carries its query.
+            req.destroy(new Error(`HTTPS request timed out after ${HTTPSService.requestTimeoutMs} ms`));
+        });
         req.on('error', (e) => {
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `HTTPS Error: ${e}`);
+            if (settled) {
+                return;
+            }
             if (retryOnError > 0) {
                 logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `HTTPS request failed --> ${retryOnError} retries left`);
+                // The retry inherits the callback, so this attempt is done with it from here on.
+                settled = true;
                 utils_1.Utils.guardedTimeout(() => {
                     HTTPSService.request(options, postData, retryOnError - 1, responseCallback);
                 }, 100);
+                return;
             }
-            else {
-                logging_1.ServerLogService.writeLog(enums_1.LogLevel.Error, 'HTTPS request failed after retries');
-            }
+            // Neither the request nor the error is quoted here: the path of a request carries its query, and this
+            // repository is public.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Error, 'HTTPS request failed after retries');
+            settle(HTTPSService.failureResponse, HTTPSService.failureStatusCode);
         });
         if (postData !== '') {
             req.write(postData);
@@ -76,11 +124,14 @@ class HTTPSService {
         req.end();
     }
     /**
-     * Downloads a file from a given url to the given location.
+     * Downloads a file from a given url to the given location, and **settles either way**: on every way the
+     * download can end - the file written, the endpoint refusing, the request failing, the answer breaking off
+     * or the disk failing - the promise is resolved or rejected exactly once.
      * If the location doesn't exist, it will be created quietly.
      * @param url - URL to download file from
      * @param filePath - Path to save file to
-     * @returns A promise that resolves to true if the file was downloaded successfully, false otherwise
+     * @returns A promise that resolves to true once the file is written and to false when the transfer failed;
+     * it is rejected when the endpoint refused the download or when the file could not be written
      */
     static async downloadFile(url, filePath) {
         return new Promise((resolve, reject) => {
@@ -91,10 +142,34 @@ class HTTPSService {
             }
             const file = fs.createWriteStream(filePath);
             let fileInfo = null;
+            // True as soon as the download is over, whichever way it went. Several of the ways below fire for the
+            // same download - a socket error still turns up once the file has been written - and without this the
+            // clean up of a failed one would take a finished file with it.
+            let settled = false;
+            const succeed = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                resolve(true);
+            };
+            /**
+             * Ends a failed download: closes the write stream and removes what was written of the file before the
+             * caller hears about it. A torso that stays behind is taken for a finished download the next time.
+             * @param reason - What to reject with, or nothing to report the failure as `false`
+             */
+            const discard = (reason) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                file.destroy();
+                fs.unlink(filePath, () => (reason !== undefined ? reject(reason) : resolve(false)));
+            };
             const request = https_1.default.get(url, (response) => {
                 var _a, _b;
                 if (response.statusCode !== 200) {
-                    reject(new Error(`Failed to get '${url}' (${response.statusCode})`));
+                    discard(new Error(`Failed to get '${url}' (${response.statusCode})`));
                     return;
                 }
                 fileInfo = {
@@ -102,13 +177,31 @@ class HTTPSService {
                     size: parseInt((_b = response.headers['content-length']) !== null && _b !== void 0 ? _b : '0', 10),
                 };
                 logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `Downloaded File\tType: "${fileInfo.mime}"\tSize:${fileInfo.size}`);
+                // An answer that breaks off once it is being piped ends the download without the request failing and
+                // without the file ever finishing, so it is heard here or nowhere. Same class of failure as a failing
+                // socket, so it is reported the same way.
+                response.on('error', (err) => {
+                    logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `Error Downloading File: ${err}`);
+                    discard();
+                });
                 response.pipe(file);
             });
             // The destination stream is ended by the time it's called
-            file.on('finish', () => resolve(true));
+            file.on('finish', () => succeed());
+            // A failing disk - no space, no permission - fails the write stream and nothing else: request and
+            // answer are both fine. Without this the event goes unhandled and the caller waits for a download that
+            // is already over.
+            file.on('error', (err) => {
+                var _a;
+                // Only the code of the failure travels on: the message of a real one quotes the file it was writing,
+                // and the caller is free to log what it is handed.
+                const code = (_a = err.code) !== null && _a !== void 0 ? _a : err.name;
+                logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `Error writing downloaded file: ${code}`);
+                discard(new Error(`Writing the downloaded file failed (${code})`));
+            });
             request.on('error', (err) => {
                 logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `Error Downloading File: ${err}`);
-                fs.unlink(filePath, () => resolve(false));
+                discard();
             });
         });
     }
@@ -117,3 +210,36 @@ class HTTPSService {
     }
 }
 exports.HTTPSService = HTTPSService;
+/**
+ * The status code the callback is handed for a request that produced no answer: no answer of the endpoint,
+ * an exhausted retry chain, a failing socket or a failing response.
+ *
+ * Negative on purpose. It is outside the range HTTP status codes occupy, so no comparison a caller writes
+ * against a real code - `=== 200`, a check for the successful range, a switch over the classes - can match
+ * it by accident; a failure that a caller reads as success is worse than one it never hears about. Zero was
+ * not an option: the successful path already yields it for an answer that ended without a status code, so
+ * the two cases would be indistinguishable.
+ */
+HTTPSService.failureStatusCode = -1;
+/**
+ * The body the callback is handed alongside `failureStatusCode`.
+ *
+ * Not the empty string, which a caller looking only at the body would take for an answer that happened to
+ * carry nothing. It names neither host nor path, because a caller is free to log what it receives and the
+ * path of a request carries its query.
+ */
+HTTPSService.failureResponse = 'HTTPS request failed';
+/**
+ * How long one attempt may go without any traffic on its socket before it is given up on and handed to the
+ * retry chain.
+ *
+ * A limit is needed at all because silence is not an error: an endpoint that accepts the connection and
+ * then says nothing produces neither `error` nor `response`, so without one the attempt - and every caller
+ * waiting on its callback - stays open until the process ends.
+ *
+ * Thirty seconds, because the whole chain has to stay inside the cadence of the callers that repeat: the
+ * weather service asks every ten minutes, and the default of five retries makes six attempts, so a fully
+ * silent endpoint costs about three minutes. That leaves a request no way to still be running when the next
+ * one starts, while staying far above the seconds a loaded endpoint may legitimately need to answer.
+ */
+HTTPSService.requestTimeoutMs = 30000;

package/lib/services/index.d.ts

@@ -7,6 +7,7 @@ export * from './time-callback-service';
 export * from './network';
 export * from './ac';
 export * from './calendar';
+export * from './energy';
 export * from './blockAutomaticHandler';
 export * from './file-info';
 export * from './https-service';

package/lib/services/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./time-callback-service"), exports);
 __exportStar(require("./network"), exports);
 __exportStar(require("./ac"), exports);
 __exportStar(require("./calendar"), exports);
+__exportStar(require("./energy"), exports);
 __exportStar(require("./blockAutomaticHandler"), exports);
 __exportStar(require("./file-info"), exports);
 __exportStar(require("./https-service"), exports);

package/lib/services/time-callback-service.d.ts

@@ -22,6 +22,18 @@ export declare class TimeCallbackService {
     static recalcSunTimes(calculationDate?: Date): void;
     static removeCallback(pCallback: ITimeCallback): void;
     static updateSunRise(pDay?: Date, lat?: number, long?: number): void;
+    /**
+     * The sunrise of a given day, as this service defines it.
+     *
+     * The counterpart of {@link getSunsetForDate}, and it exists so that a caller which needs both ends of one
+     * day gets them from one definition of the sun: two libraries put sunrise and sunset minutes apart, and a
+     * window bounded by one at each end is bounded by two different mornings.
+     * @param pDay - The day to calculate for; defaults to today.
+     * @param lat - The latitude to calculate for; defaults to the configured one.
+     * @param long - The longitude to calculate for; defaults to the configured one.
+     * @returns The moment of sunrise on that day.
+     */
+    static getSunriseForDate(pDay?: Date, lat?: number, long?: number): Date;
     static updateSunSet(pDay?: Date, lat?: number, long?: number): void;
     static getSunsetForDate(pDay?: Date, lat?: number, long?: number): Date;
     static hoursTilSunset(): number;

package/lib/services/time-callback-service.js

@@ -143,7 +143,21 @@ Next Sunset: ${TimeCallbackService._nextSunSet.toLocaleString('de-DE')}`);
         }
     }
     static updateSunRise(pDay = new Date(), lat, long) {
-        TimeCallbackService._nextSunRise = (0, sunrise_sunset_js_1.getSunrise)(lat !== null && lat !== void 0 ? lat : settings_service_1.SettingsService.latitude, long !== null && long !== void 0 ? long : settings_service_1.SettingsService.longitude, pDay);
+        TimeCallbackService._nextSunRise = this.getSunriseForDate(pDay, lat !== null && lat !== void 0 ? lat : settings_service_1.SettingsService.latitude, long !== null && long !== void 0 ? long : settings_service_1.SettingsService.longitude);
+    }
+    /**
+     * The sunrise of a given day, as this service defines it.
+     *
+     * The counterpart of {@link getSunsetForDate}, and it exists so that a caller which needs both ends of one
+     * day gets them from one definition of the sun: two libraries put sunrise and sunset minutes apart, and a
+     * window bounded by one at each end is bounded by two different mornings.
+     * @param pDay - The day to calculate for; defaults to today.
+     * @param lat - The latitude to calculate for; defaults to the configured one.
+     * @param long - The longitude to calculate for; defaults to the configured one.
+     * @returns The moment of sunrise on that day.
+     */
+    static getSunriseForDate(pDay = new Date(), lat, long) {
+        return (0, sunrise_sunset_js_1.getSunrise)(lat !== null && lat !== void 0 ? lat : settings_service_1.SettingsService.latitude, long !== null && long !== void 0 ? long : settings_service_1.SettingsService.longitude, pDay);
     }
     static updateSunSet(pDay = new Date(), lat, long) {
         TimeCallbackService._nextSunSet = this.getSunsetForDate(pDay, lat !== null && lat !== void 0 ? lat : settings_service_1.SettingsService.latitude, long !== null && long !== void 0 ? long : settings_service_1.SettingsService.longitude);
@@ -152,7 +166,7 @@ Next Sunset: ${TimeCallbackService._nextSunSet.toLocaleString('de-DE')}`);
         return (0, sunrise_sunset_js_1.getSunset)(lat !== null && lat !== void 0 ? lat : settings_service_1.SettingsService.latitude, long !== null && long !== void 0 ? long : settings_service_1.SettingsService.longitude, pDay);
     }
     static hoursTilSunset() {
-        return (this.nextSunSet.getTime() - utils_1.Utils.nowMS()) / 1000 / 60;
+        return (this.nextSunSet.getTime() - utils_1.Utils.nowMS()) / (1000 * 60 * 60);
     }
 }
 exports.TimeCallbackService = TimeCallbackService;

package/lib/services/weather/index.d.ts

@@ -1,2 +1,3 @@
 export * from './weather-service';
+export * from './weather-history-backfill';
 export { RainNextMinutesInfo } from './rain-next-minutes-info';

package/lib/services/weather/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RainNextMinutesInfo = void 0;
 __exportStar(require("./weather-service"), exports);
+__exportStar(require("./weather-history-backfill"), exports);
 var rain_next_minutes_info_1 = require("./rain-next-minutes-info");
 Object.defineProperty(exports, "RainNextMinutesInfo", { enumerable: true, get: function () { return rain_next_minutes_info_1.RainNextMinutesInfo; } });

package/lib/services/weather/open-weather-day-summary.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The part of the One Call 3.0 day summary answer the backfill uses.
+ *
+ * The leaves are `unknown` on purpose. This shape describes an answer from beyond the trust boundary, and
+ * declaring them `number` would be a promise nothing on this side can keep - `JSON.parse` returns whatever
+ * arrived, and a cast does not check it. `unknown` forces every leaf through a plausibility check before it is
+ * used, which is the only place the values are actually established as numbers.
+ *
+ * Not part of the published surface: it describes a foreign answer, not something anyone implements.
+ */
+export type OpenWeatherDaySummary = {
+    /** Cloud cover of the day, as the endpoint reports it */
+    cloud_cover?: {
+        afternoon?: unknown;
+    };
+    /** Air temperatures of the day, as the endpoint reports them */
+    temperature?: {
+        min?: unknown;
+        max?: unknown;
+    };
+    /** Precipitation of the day, as the endpoint reports it. Absent on an endpoint that does not send it */
+    precipitation?: {
+        total?: unknown;
+    };
+};

package/lib/services/weather/open-weather-day-summary.js

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

package/lib/services/weather/weather-day-summary-fetcher.d.ts

@@ -0,0 +1,6 @@
+import { iWeatherDaySummary } from '../../interfaces/iWeatherDaySummary';
+/**
+ * Fetches the daily weather aggregate of one past day, or `undefined` when that day cannot be obtained.
+ * Handed in so the backfill can be exercised without talking to the weather service.
+ */
+export type WeatherDaySummaryFetcher = (date: Date) => Promise<iWeatherDaySummary | undefined>;

package/lib/services/weather/weather-day-summary-fetcher.js

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

package/lib/services/weather/weather-history-backfill.d.ts

@@ -0,0 +1,94 @@
+import { iPersist, iWeatherSettings } from '../../interfaces';
+import { WeatherDaySummaryFetcher } from './weather-day-summary-fetcher';
+/**
+ * Fills the gaps in the stored daily weather aggregates from the One Call 3.0 day summary endpoint.
+ *
+ * Its own service instead of a method on the weather service: that one serves the live forecast, while this
+ * one walks a window of past days and must stay bounded and throttled. The full recorded history is far larger
+ * than a day's request quota, so the fitting window is the hard limit and the throttle keeps an accidentally
+ * widened window from draining the quota in one burst.
+ */
+export declare class WeatherHistoryBackfill {
+    /** Milliseconds between two calls to the weather service. */
+    static readonly defaultThrottleMs: number;
+    /**
+     * The band a daily air temperature in degrees Celsius can occupy. Wide on purpose - it is there to reject
+     * what cannot be a temperature at all, not to second guess the weather service on a hot afternoon. The
+     * bounds sit outside the coldest and the hottest reading ever recorded on the planet.
+     */
+    private static readonly minTemperature;
+    private static readonly maxTemperature;
+    /**
+     * The most millimetres of precipitation a single day can carry. Wide on purpose, like the temperature band:
+     * it rejects what cannot be a daily rainfall at all, it does not second guess the weather service on a
+     * thunderstorm. The bound sits above the highest daily total ever recorded on the planet.
+     */
+    private static readonly maxPrecipitation;
+    private static readonly host;
+    /**
+     * The past days of the window that were already fetched on the running day, and the running day that was
+     * recorded on.
+     *
+     * The attempt is remembered, not its outcome: a past day is archive, so a second fetch on the same calendar
+     * day cannot yield anything the first one did not, whatever became of the first. That also covers the fetch
+     * that succeeded while the write did not land - `persistWeatherDaySummary` reports nothing back, so a
+     * failing write is invisible from here and would otherwise cost the full window once per run, and the
+     * backfill runs far more often than once a day. The running day is remembered alongside, so a passing outage
+     * heals on the next calendar day instead of staying suppressed until a restart.
+     */
+    private static attemptedPastDays;
+    private static attemptedPastDaysRecordedOn;
+    /**
+     * Fetches the daily weather aggregates that are missing within the fitting window and stores them, plus the
+     * running day's aggregate on every run. Past days that are already stored are not fetched again, so a
+     * service restart does not cost quota; the running day always is, because it is a forecast that moves. A past
+     * day that was already fetched on the running day is not fetched again until the next calendar day.
+     * @param persist - The persistence to read the present days from and to write the fetched ones to
+     * @param referenceDate - The running day; the window ends on it, inclusive
+     * @param historyWindowDays - Length of the history window in days; calls are bounded by it plus one
+     * @param fetcher - The fetcher to use, defaults to the configured One Call 3.0 day summary endpoint
+     * @param throttleMs - Milliseconds to wait between two calls
+     * @returns - The number of days that were fetched and handed to the persistence. Not the number that
+     * arrived: `persistWeatherDaySummary` reports nothing back, so whether a row landed cannot be seen from
+     * here. Do not read this as a count of stored rows - look in the table for that.
+     */
+    static run(persist: iPersist | undefined, referenceDate: Date, historyWindowDays: number, fetcher?: WeatherDaySummaryFetcher, throttleMs?: number): Promise<number>;
+    /**
+     * Forgets which past days were already fetched, so the next run offers the whole window again. Called by
+     * `run` itself on a change of the running day; separate so a test can start from a known state.
+     */
+    static resetAttemptedPastDays(): void;
+    /**
+     * Builds the fetcher against the One Call 3.0 day summary endpoint.
+     * @param settings - The weather settings to use, defaults to the configured ones
+     * @returns - The fetcher, or `undefined` when there is no location or no key to work with
+     */
+    static createOpenWeatherFetcher(settings?: iWeatherSettings | undefined): WeatherDaySummaryFetcher | undefined;
+    /**
+     * The days of the fitting window, oldest first, **including the running day**. The running day is in there
+     * on purpose: the gate reads today's cloud cover and maximum temperature out of the same table and through
+     * the same reader as the history, so that both sides of the fit are the same quantity from the same field.
+     * That is one extra call per run - the alternative was the gate deriving today's figures from a different
+     * product, which measurably is not the same number.
+     * @param referenceDate - The running day
+     * @param historyWindowDays - Length of the history window in days
+     * @returns - `historyWindowDays + 1` day starts, the last of which is the running day
+     */
+    private static windowDays;
+    private static fetchDaySummary;
+    private static parseDaySummary;
+    /**
+     * Establishes one field of the answer as a reading: a real number within the band its quantity can occupy.
+     *
+     * `typeof` rather than `Number(...)`: a value that has to be converted first is not a reading of the
+     * quantity, and converting would turn `null` into 0 and `""` into 0 - both of which pass every band. The
+     * band itself catches what is numeric but cannot be the quantity, `NaN` and the infinities included, since
+     * neither compares inside it.
+     * @param value - The field as it arrived
+     * @param min - Lowest value the quantity can take
+     * @param max - Highest value the quantity can take
+     * @returns - The reading, or undefined when the field is not one
+     */
+    private static plausibleReading;
+    private static dayKey;
+}