@enyo-energy/energy-app-sdk 1.49.0 → 1.50.0

package/README.md

@@ -3906,7 +3906,7 @@ Drives a heatpump. Manages building / DHW overheating commands and grid-power-av
   - `publishHeatpumpControlStatus(applianceId, {sessionId, actions})` — how a session's actions progress (`HeatpumpControlStatusV3`).
   - `publishHeatpumpFlexibility(applianceId, options, {validForSeconds?, repeatEverySeconds?})` — offer per zone how far the heatpump can be raised right now (`HeatpumpFlexibilityAnnouncementV3`); repeated automatically until replaced (see below).
   - `publishHeatpumpValuesUpdate(applianceId, values)` — operation mode, electrical and thermal power, energies.
-  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank.
+  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank. Each heating circuit must set at least one current temperature (`temperatureC`, `roomTemperatureC`, `flowTemperatureC` or `returnTemperatureC`) — `temperatureC` itself is optional; the payload is checked with the exported `validateHeatpumpTemperatures(data)` and an invalid one throws.
 
 #### HeatpumpControlV3
 

package/dist/cjs/implementations/heatpump/heatpump-temperatures-validators.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateHeatpumpTemperatures = validateHeatpumpTemperatures;
+/** The current-temperature fields of a heating circuit, at least one of which must be set. */
+const HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS = [
+    'temperatureC',
+    'roomTemperatureC',
+    'flowTemperatureC',
+    'returnTemperatureC',
+];
+/**
+ * Validates the data of a `HeatpumpTemperaturesUpdateV1`.
+ *
+ * Errors:
+ * - A heating circuit carries no current temperature — none of
+ *   `temperatureC`, `roomTemperatureC`, `flowTemperatureC` or
+ *   `returnTemperatureC` is a finite number. Since `temperatureC` is optional,
+ *   such a circuit would report nothing but its target.
+ *
+ * @param data - The message's `data`.
+ * @returns The validation result; `ok` is `false` when there are errors.
+ */
+function validateHeatpumpTemperatures(data) {
+    const errors = [];
+    for (const circuit of data.heatingCircuits ?? []) {
+        const hasCurrentTemperature = HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS.some((field) => Number.isFinite(circuit[field]));
+        if (!hasCurrentTemperature) {
+            errors.push(`heatingCircuits[index=${circuit.index}] must set at least one of ` +
+                `${HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS.join(', ')}`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}

package/dist/cjs/implementations/heatpump/heatpump-temperatures-validators.d.cts

@@ -0,0 +1,24 @@
+import { EnyoDataBusHeatpumpTemperaturesV1 } from '../../types/enyo-data-bus-value.cjs';
+/**
+ * Result of {@link validateHeatpumpTemperatures}: `ok` is `false` when there
+ * are errors.
+ */
+export interface HeatpumpTemperaturesValidationResult {
+    /** `true` when there are no errors. */
+    ok: boolean;
+    /** Problems that make the temperature update wrong. */
+    errors: string[];
+}
+/**
+ * Validates the data of a `HeatpumpTemperaturesUpdateV1`.
+ *
+ * Errors:
+ * - A heating circuit carries no current temperature — none of
+ *   `temperatureC`, `roomTemperatureC`, `flowTemperatureC` or
+ *   `returnTemperatureC` is a finite number. Since `temperatureC` is optional,
+ *   such a circuit would report nothing but its target.
+ *
+ * @param data - The message's `data`.
+ * @returns The validation result; `ok` is `false` when there are errors.
+ */
+export declare function validateHeatpumpTemperatures(data: EnyoDataBusHeatpumpTemperaturesV1['data']): HeatpumpTemperaturesValidationResult;

package/dist/cjs/index.cjs

@@ -110,6 +110,7 @@ __exportStar(require("./implementations/heatpump/heatpump-metadata-validators.cj
 __exportStar(require("./implementations/heatpump/heatpump-control-validators.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-control-session.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-flexibility-validators.cjs"), exports);
+__exportStar(require("./implementations/heatpump/heatpump-temperatures-validators.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-heating-curve-offset.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-curve-optimization-rooms.cjs"), exports);
 __exportStar(require("./types/enyo-inverter-appliance.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -94,6 +94,7 @@ export * from './implementations/heatpump/heatpump-metadata-validators.cjs';
 export * from './implementations/heatpump/heatpump-control-validators.cjs';
 export * from './implementations/heatpump/heatpump-control-session.cjs';
 export * from './implementations/heatpump/heatpump-flexibility-validators.cjs';
+export * from './implementations/heatpump/heatpump-temperatures-validators.cjs';
 export * from './implementations/heatpump/heatpump-heating-curve-offset.cjs';
 export * from './implementations/heatpump/heatpump-curve-optimization-rooms.cjs';
 export * from './types/enyo-inverter-appliance.cjs';

package/dist/cjs/integrations/heatpump-integration-energy-app.cjs

@@ -6,6 +6,7 @@ const integration_energy_app_js_1 = require("./integration-energy-app.cjs");
 const enyo_appliance_js_1 = require("../types/enyo-appliance.cjs");
 const enyo_data_bus_value_js_1 = require("../types/enyo-data-bus-value.cjs");
 const heatpump_flexibility_validators_js_1 = require("../implementations/heatpump/heatpump-flexibility-validators.cjs");
+const heatpump_temperatures_validators_js_1 = require("../implementations/heatpump/heatpump-temperatures-validators.cjs");
 const enyo_heatpump_appliance_js_1 = require("../types/enyo-heatpump-appliance.cjs");
 const heatpump_control_validators_js_1 = require("../implementations/heatpump/heatpump-control-validators.cjs");
 const heatpump_control_session_js_1 = require("../implementations/heatpump/heatpump-control-session.cjs");
@@ -584,8 +585,14 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
      * @param applianceId - The heatpump appliance ID this update is for.
      * @param temperatures - Temperature payload — see
      *   {@link EnyoDataBusHeatpumpTemperaturesV1.data}.
+     * @throws Error when the payload fails {@link validateHeatpumpTemperatures},
+     *   e.g. a heating circuit without any current temperature.
      */
     publishHeatpumpTemperatures(applianceId, temperatures) {
+        const { ok, errors } = (0, heatpump_temperatures_validators_js_1.validateHeatpumpTemperatures)(temperatures);
+        if (!ok) {
+            throw new Error(`Invalid heatpump temperatures: ${errors.join('; ')}`);
+        }
         const message = {
             id: this.generateMessageId(),
             type: 'message',

package/dist/cjs/integrations/heatpump-integration-energy-app.d.cts

@@ -512,6 +512,8 @@ export declare abstract class HeatpumpIntegrationEnergyApp extends IntegrationEn
      * @param applianceId - The heatpump appliance ID this update is for.
      * @param temperatures - Temperature payload — see
      *   {@link EnyoDataBusHeatpumpTemperaturesV1.data}.
+     * @throws Error when the payload fails {@link validateHeatpumpTemperatures},
+     *   e.g. a heating circuit without any current temperature.
      */
     publishHeatpumpTemperatures(applianceId: string, temperatures: EnyoDataBusHeatpumpTemperaturesV1['data']): void;
     private sendHeatpumpFlexibility;

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -4098,8 +4098,13 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
              * reports it. Prefer the explicit {@link flowTemperatureC} and
              * {@link roomTemperatureC} where available — this field does not
              * say which of the two it is.
+             *
+             * Optional, but every circuit must carry at least one current
+             * temperature: this field, {@link roomTemperatureC},
+             * {@link flowTemperatureC} or {@link returnTemperatureC}. See
+             * {@link validateHeatpumpTemperatures}.
              */
-            temperatureC: number;
+            temperatureC?: number;
             /** Target room temperature in Celsius */
             targetRoomTemperatureC?: number;
             /**

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.49.0';
+exports.SDK_VERSION = '1.50.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.49.0";
+export declare const SDK_VERSION = "1.50.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/implementations/heatpump/heatpump-temperatures-validators.d.ts

@@ -0,0 +1,24 @@
+import { EnyoDataBusHeatpumpTemperaturesV1 } from '../../types/enyo-data-bus-value.js';
+/**
+ * Result of {@link validateHeatpumpTemperatures}: `ok` is `false` when there
+ * are errors.
+ */
+export interface HeatpumpTemperaturesValidationResult {
+    /** `true` when there are no errors. */
+    ok: boolean;
+    /** Problems that make the temperature update wrong. */
+    errors: string[];
+}
+/**
+ * Validates the data of a `HeatpumpTemperaturesUpdateV1`.
+ *
+ * Errors:
+ * - A heating circuit carries no current temperature — none of
+ *   `temperatureC`, `roomTemperatureC`, `flowTemperatureC` or
+ *   `returnTemperatureC` is a finite number. Since `temperatureC` is optional,
+ *   such a circuit would report nothing but its target.
+ *
+ * @param data - The message's `data`.
+ * @returns The validation result; `ok` is `false` when there are errors.
+ */
+export declare function validateHeatpumpTemperatures(data: EnyoDataBusHeatpumpTemperaturesV1['data']): HeatpumpTemperaturesValidationResult;

package/dist/implementations/heatpump/heatpump-temperatures-validators.js

@@ -0,0 +1,30 @@
+/** The current-temperature fields of a heating circuit, at least one of which must be set. */
+const HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS = [
+    'temperatureC',
+    'roomTemperatureC',
+    'flowTemperatureC',
+    'returnTemperatureC',
+];
+/**
+ * Validates the data of a `HeatpumpTemperaturesUpdateV1`.
+ *
+ * Errors:
+ * - A heating circuit carries no current temperature — none of
+ *   `temperatureC`, `roomTemperatureC`, `flowTemperatureC` or
+ *   `returnTemperatureC` is a finite number. Since `temperatureC` is optional,
+ *   such a circuit would report nothing but its target.
+ *
+ * @param data - The message's `data`.
+ * @returns The validation result; `ok` is `false` when there are errors.
+ */
+export function validateHeatpumpTemperatures(data) {
+    const errors = [];
+    for (const circuit of data.heatingCircuits ?? []) {
+        const hasCurrentTemperature = HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS.some((field) => Number.isFinite(circuit[field]));
+        if (!hasCurrentTemperature) {
+            errors.push(`heatingCircuits[index=${circuit.index}] must set at least one of ` +
+                `${HEATING_CIRCUIT_CURRENT_TEMPERATURE_FIELDS.join(', ')}`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}

package/dist/index.d.ts

@@ -94,6 +94,7 @@ export * from './implementations/heatpump/heatpump-metadata-validators.js';
 export * from './implementations/heatpump/heatpump-control-validators.js';
 export * from './implementations/heatpump/heatpump-control-session.js';
 export * from './implementations/heatpump/heatpump-flexibility-validators.js';
+export * from './implementations/heatpump/heatpump-temperatures-validators.js';
 export * from './implementations/heatpump/heatpump-heating-curve-offset.js';
 export * from './implementations/heatpump/heatpump-curve-optimization-rooms.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/index.js

@@ -94,6 +94,7 @@ export * from './implementations/heatpump/heatpump-metadata-validators.js';
 export * from './implementations/heatpump/heatpump-control-validators.js';
 export * from './implementations/heatpump/heatpump-control-session.js';
 export * from './implementations/heatpump/heatpump-flexibility-validators.js';
+export * from './implementations/heatpump/heatpump-temperatures-validators.js';
 export * from './implementations/heatpump/heatpump-heating-curve-offset.js';
 export * from './implementations/heatpump/heatpump-curve-optimization-rooms.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/integrations/heatpump-integration-energy-app.d.ts

@@ -512,6 +512,8 @@ export declare abstract class HeatpumpIntegrationEnergyApp extends IntegrationEn
      * @param applianceId - The heatpump appliance ID this update is for.
      * @param temperatures - Temperature payload — see
      *   {@link EnyoDataBusHeatpumpTemperaturesV1.data}.
+     * @throws Error when the payload fails {@link validateHeatpumpTemperatures},
+     *   e.g. a heating circuit without any current temperature.
      */
     publishHeatpumpTemperatures(applianceId: string, temperatures: EnyoDataBusHeatpumpTemperaturesV1['data']): void;
     private sendHeatpumpFlexibility;

package/dist/integrations/heatpump-integration-energy-app.js

@@ -2,6 +2,7 @@ import { IntegrationEnergyApp } from "./integration-energy-app.js";
 import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.js";
 import { EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.js";
 import { heatpumpFlexibilityOfferId, validateHeatpumpFlexibilityAnnouncement } from "../implementations/heatpump/heatpump-flexibility-validators.js";
+import { validateHeatpumpTemperatures } from "../implementations/heatpump/heatpump-temperatures-validators.js";
 import { EnyoHeatpumpApplianceAvailableFeaturesEnum, EnyoHeatpumpProgramModeEnum } from "../types/enyo-heatpump-appliance.js";
 import { validateHeatpumpControlAction, validateHeatpumpHeatingCurveOffset, validateHeatpumpProgramSwitch } from "../implementations/heatpump/heatpump-control-validators.js";
 import { HeatpumpControlEndCauseEnum, heatpumpControlActionsKey, HeatpumpControlSessionTracker } from "../implementations/heatpump/heatpump-control-session.js";
@@ -580,8 +581,14 @@ export class HeatpumpIntegrationEnergyApp extends IntegrationEnergyApp {
      * @param applianceId - The heatpump appliance ID this update is for.
      * @param temperatures - Temperature payload — see
      *   {@link EnyoDataBusHeatpumpTemperaturesV1.data}.
+     * @throws Error when the payload fails {@link validateHeatpumpTemperatures},
+     *   e.g. a heating circuit without any current temperature.
      */
     publishHeatpumpTemperatures(applianceId, temperatures) {
+        const { ok, errors } = validateHeatpumpTemperatures(temperatures);
+        if (!ok) {
+            throw new Error(`Invalid heatpump temperatures: ${errors.join('; ')}`);
+        }
         const message = {
             id: this.generateMessageId(),
             type: 'message',

package/dist/types/enyo-data-bus-value.d.ts

@@ -4098,8 +4098,13 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
              * reports it. Prefer the explicit {@link flowTemperatureC} and
              * {@link roomTemperatureC} where available — this field does not
              * say which of the two it is.
+             *
+             * Optional, but every circuit must carry at least one current
+             * temperature: this field, {@link roomTemperatureC},
+             * {@link flowTemperatureC} or {@link returnTemperatureC}. See
+             * {@link validateHeatpumpTemperatures}.
              */
-            temperatureC: number;
+            temperatureC?: number;
             /** Target room temperature in Celsius */
             targetRoomTemperatureC?: number;
             /**

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.49.0";
+export declare const SDK_VERSION = "1.50.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.49.0';
+export const SDK_VERSION = '1.50.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",