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

package/README.md

@@ -1864,6 +1864,19 @@ const history = await roomTemperatures.getRoomTemperatureHistory({
 
 Requires the `RoomTemperatures` permission.
 
+#### `useVacations(): EnergyAppVacations`
+
+Read the customer's absences (vacation mode), as planned in the enyo app — every absence that is not over yet, planned or running; they never overlap. Each `EnyoVacation` carries `startIso` / `endIso` and the customer's choices per appliance category: `heatpump.heating` — `mode` while away (`EnyoVacationHeatingModeEnum`: `FrostProtection` = `VACATION_FROST_PROTECTION_C` 7 °C, `Lowered` to `loweredTemperatureC` between `VACATION_LOWERED_MIN_C` and `VACATION_LOWERED_MAX_C` (10–20 °C), or `Normal`) and `preheatBeforeReturn` —, `heatpump.domesticHotWater.pause`, and `battery.gridServing` / `battery.minSocAtReturnPercent`. An early return moves `endIso` to that moment and fires the listener. Read-only. The energy manager turns an absence into [VacationStartedV1 / VacationStoppedV1](#vacationstartedv1--vacationstoppedv1).
+
+```typescript
+const vacations = energyApp.useVacations();
+
+applyVacations(await vacations.getVacations());
+vacations.listenForVacationsChanged((all) => applyVacations(all));
+```
+
+Requires the `EnergyManager` permission.
+
 #### `useGridConnectionPoint(): EnergyAppGridConnectionPoint`
 
 Read the site's grid connection details — main fuse rating, number of phases, the maximum allowed grid power, and the total power that load balancing may allocate to EV chargers. Use this to size dispatch envelopes and avoid violating the contractual cap.
@@ -3891,13 +3904,14 @@ Drives a heatpump. Manages building / DHW overheating commands and grid-power-av
 
 > **Preferred: control heatpumps with the V3 messages.** `HeatpumpControlV3` (power, power sources, which zones to heat now, until when), `HeatpumpControlCancelV3` (cancel a session) and `HeatpumpControlStatusV3` (progress) are the preferred way to control a heatpump — for energy managers sending commands and for integrations receiving them. Use them for all new work. `HeatpumpOverheatingV1`, `SetHeatpumpAvailablePowerV2` and `HeatpumpAvailablePowerAnnouncementV1` are deprecated and only remain for heatpumps that do not declare `ControlV3`. See [HeatpumpControlV3](#heatpumpcontrolv3). Likewise, a heatpump offers its flexibility with `HeatpumpFlexibilityAnnouncementV3` rather than the generic `ApplianceFlexibilityAnnouncementV1` / `V2` — see [HeatpumpFlexibilityAnnouncementV3](#heatpumpflexibilityannouncementv3).
 
-- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `SetHeatpumpHeatingCurveOffsetV1`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `SetHeatpumpHeatingCurveOffsetV1`, `VacationStartedV1`, `VacationStoppedV1`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
 - **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
 - **Optional overrides:**
   - `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
   - `handleHeatpumpControl` — support `HeatpumpControlV3` (see below). Answers `NotSupported` by default; override it and declare `ControlV3`.
   - `handleHeatpumpProgramSwitch(request)` — switch a zone to comfort or eco, or back to its time program (see [HeatpumpProgramSwitchV3](#heatpumpprogramswitchv3)). Answers `NotSupported` by default; override it and declare `ProgramSwitch`.
   - `handleHeatpumpHeatingCurveOffset(message)` — shift a heating circuit's curve permanently, relative to its initial curve (see [SetHeatpumpHeatingCurveOffsetV1](#setheatpumpheatingcurveoffsetv1)). Answers `NotSupported` by default; override it and declare `HeatingCurveOffset`.
+  - `handleVacationStarted(message)` / `handleVacationStopped(message)` — the customer is away: heat with frost protection or lowered and / or pause hot water, then restore everything (see [VacationStartedV1 / VacationStoppedV1](#vacationstartedv1--vacationstoppedv1)). Answer `NotSupported` by default; override both and declare `VacationFrostProtection`, `VacationLowered` and / or `VacationHotWaterPause`.
   - `handleHeatpumpControlCancel` — withdraw a cancelled session on the device. By default `Accepted` for heatpumps declaring `ControlV3`, `NotSupported` otherwise.
   - `onHeatpumpControlEnded(applianceId, cause)` — return the heatpump to its own behaviour when a session ends; `cause` is `HeatpumpControlEndCauseEnum.Expired`, `Ended` or `Cancelled`. Does nothing by default.
   - `resolveHeatpumpMetadata(applianceId)` — the metadata actions are validated against. Defaults to the stored appliance's `heatpump` metadata.
@@ -3906,7 +3920,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
 
@@ -3996,6 +4010,33 @@ protected async handleHeatpumpHeatingCurveOffset(message: EnyoDataBusSetHeatpump
 }
 ```
 
+#### VacationStartedV1 / VacationStoppedV1
+
+The customer is away (`useVacations()`): `VacationStartedV1` carries the customer's preferences, nested by appliance type — `heatpump` (heating while away, whether hot water is paused) and `battery` — and the integration decides how to realise them, ideally with the device's own holiday / absence mode. `VacationStoppedV1` ends the vacation (return, early return or removed): restore everything so the zones follow their own time program again. Both are answered with the usual `CommandAcknowledgeV1`.
+
+```typescript
+// VacationStartedV1
+{
+    vacationId: 'vacation-1',
+    returnIso: '2026-12-14T18:00:00.000Z',  // planned return; safety net: end everything by then on your own
+    heatpump: {
+        heating: { mode: EnyoVacationHeatingEnum.FrostProtection, targetTemperatureC: 7 },  // absent = heat as usual
+        domesticHotWater: { pause: true },  // absent or pause: false = hot water as usual; legionella protection keeps running
+    },
+    // battery: { gridServing: true, minSocAtReturnPercent: 50 },  // for batteries with their own vacation handling; not sent by the enyo energy manager today
+    reason: { type: EnyoDataBusCommandReasonTypeEnum.UserRequest },
+}
+// VacationStoppedV1
+{ vacationId: 'vacation-1' }
+```
+
+- **Only to heatpumps declaring a vacation feature.** `heatpump.heating.mode` `FrostProtection` (`EnyoVacationHeatingEnum`, the device's own frost protection ≈ `VACATION_FROST_PROTECTION_C` 7 °C) needs `VacationFrostProtection`; `Lowered` needs `VacationLowered` and a `targetTemperatureC` inside the appliance-level `vacationLoweredRangeC` (the setpoint the device can hold for all its circuits); `heatpump.domesticHotWater.pause: true` needs `VacationHotWaterPause`. A heatpump without any vacation feature gets the eco fallback via `HeatpumpProgramSwitchV3`.
+- **Idempotent, the complete wanted state.** The energy manager re-sends `VacationStartedV1` whenever the wanted state changes and at least hourly. Pre-heating for the return stays with the energy manager: when heating resumes it re-sends the message without `heatpump.heating`, when hot water resumes with `domesticHotWater.pause: false`, and when nothing is left it sends `VacationStoppedV1`.
+- **Ends by itself.** Write `returnIso` to the device as the end of its holiday mode, or end everything yourself at `returnIso` if no `VacationStoppedV1` arrives.
+- **Stop is always accepted.** Answer `VacationStoppedV1` `Accepted` even when nothing runs.
+- **Precedence.** While a vacation heating state is active the energy manager sends no `HeatpumpProgramSwitchV3` and no `HeatpumpControlV3` room action for the heatpump; while `heatpump.domesticHotWater.pause` is set, no hot water boosts.
+- **Validation** (run by the base class before the handlers, or `validateVacationStarted(data, metadata)` / `validateVacationStopped(data)` directly): malformed data is `Rejected`; a `heatpump.heating` mode whose feature is missing, a lowered target outside `vacationLoweredRangeC` or `heatpump.domesticHotWater.pause: true` without `VacationHotWaterPause` is `NotSupported`. A stop is only rejected when malformed.
+
 #### HeatpumpFlexibilityAnnouncementV3
 
 The heatpump's offer, in the vocabulary of `HeatpumpControlV3`: per zone (`target` + `index`), how far it can be raised right now (`maxDeltaK` above `setpointC`, room in Kelvin of room temperature) and the smallest raise that actually starts it (`minDeltaK`, e.g. the remaining hysteresis), with which heat source at what power (`heatSources`: compressor and heating rod as separate entries, each with a `power` band and an optional `estimatedElectricalKwh` for the full raise), and when (`earliestStartIso` / `latestStartIso`, `minDurationMinutes`). An optional `required: {deltaK, byIso}` turns a "may" into a "must, by then" — e.g. hot water dropping below comfort at 18:00. Declare `FlexibilityAnnouncementV3` on the heatpump; for such heatpumps it supersedes the generic `ApplianceFlexibilityAnnouncementV1` / `V2`.
@@ -4032,6 +4073,9 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `RoomTemperature` | `heatingCircuits[].roomTemperatureC` in `HeatpumpTemperaturesUpdateV1`; where it is measured goes in `heatingCircuits[].roomTemperatureSource` (`None` / `Internal` / `External`) and, for an enyo sensor, `roomTemperatureSensor` |
 | `RoomTemperatureInput` | The heatpump accepts measured room temperatures via `SetHeatpumpRoomTemperatureV1` |
 | `HeatingCurveOffset` | The heatpump's app shifts a circuit's curve via `SetHeatpumpHeatingCurveOffsetV1`. `heatingCircuits[].heatingCurveOffsetRangeK` (allowed range, must contain 0), `activeHeatingCurveOffsetK` (effective shift read back) and `initialHeatingCurve` (the curve before the first shift) |
+| `VacationFrostProtection` | The heatpump's app handles `VacationStartedV1` with `heatpump.heating.mode` `FrostProtection` — the device's own frost protection while the customer is away |
+| `VacationLowered` | The heatpump's app handles `VacationStartedV1` with `heatpump.heating.mode` `Lowered`. `vacationLoweredRangeC` (required) — the setpoints (°C) the device can hold for all its circuits |
+| `VacationHotWaterPause` | The heatpump's app handles `VacationStartedV1` with `heatpump.domesticHotWater.pause: true`. Declare it only if legionella protection keeps running |
 | — | `heatingCircuits[].curveOptimization` — the customer's choice for the room-temperature based curve optimisation: `enabled` (off by default) and `roomIds` (the rooms the circuit heats, see `useRoom()`). Customer-owned; integrations only read it |
 | — | `building.recommendedHeatingCurve` — the curve the building actually needs, learned from the days the room held its target |
 | `PvSurplusSignal` | The heatpump takes `availablePowerW` of `HeatpumpControlV3` as a PV surplus signal (e.g. Lambda register 102). Supersedes the deprecated `AvailablePowerAnnouncement` |

package/dist/cjs/energy-app.cjs

@@ -578,6 +578,19 @@ class EnergyApp {
     useRoomTemperatures() {
         return this.energyAppSdk.useRoomTemperatures();
     }
+    /**
+     * Gets the Vacations API for reading the customer's absences (vacation
+     * mode): departure and return, what the heatpump heats to meanwhile,
+     * whether hot water pauses, whether to pre-heat for the return and how the
+     * battery is used. Read them with `getVacations()` and react to changes
+     * with `listenForVacationsChanged()`.
+     * @returns The Vacations API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `EnergyManager`
+     *         permission is not granted.
+     */
+    useVacations() {
+        return this.energyAppSdk.useVacations();
+    }
     /**
      * Gets the Timeseries Store API for storing the app's own timeseries —
      * numbers and text — and querying them back raw or aggregated by the host.

package/dist/cjs/energy-app.d.cts

@@ -55,6 +55,7 @@ import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
 import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { EnergyAppRoom } from "./packages/energy-app-room.cjs";
 import { EnergyAppRoomTemperatures } from "./packages/energy-app-room-temperatures.cjs";
+import { EnergyAppVacations } from "./packages/energy-app-vacations.cjs";
 import { EnergyAppTimeseriesStore } from "./packages/energy-app-timeseries-store.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
@@ -494,6 +495,17 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useRoomTemperatures(): EnergyAppRoomTemperatures;
+    /**
+     * Gets the Vacations API for reading the customer's absences (vacation
+     * mode): departure and return, what the heatpump heats to meanwhile,
+     * whether hot water pauses, whether to pre-heat for the return and how the
+     * battery is used. Read them with `getVacations()` and react to changes
+     * with `listenForVacationsChanged()`.
+     * @returns The Vacations API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `EnergyManager`
+     *         permission is not granted.
+     */
+    useVacations(): EnergyAppVacations;
     /**
      * Gets the Timeseries Store API for storing the app's own timeseries —
      * numbers and text — and querying them back raw or aggregated by the host.

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -54,6 +54,7 @@ import { EnergyAppWebhook } from "./packages/energy-app-webhook.cjs";
 import { EnergyAppSubscriptions } from "./packages/energy-app-subscriptions.cjs";
 import { EnergyAppRoom } from "./packages/energy-app-room.cjs";
 import { EnergyAppRoomTemperatures } from "./packages/energy-app-room-temperatures.cjs";
+import { EnergyAppVacations } from "./packages/energy-app-vacations.cjs";
 import { EnergyAppTimeseriesStore } from "./packages/energy-app-timeseries-store.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
@@ -205,6 +206,8 @@ export interface EnyoEnergyAppSdk {
     useRoom: () => EnergyAppRoom;
     /** Get the Room Temperatures API for reading the current and past temperatures measured in the rooms of the home */
     useRoomTemperatures: () => EnergyAppRoomTemperatures;
+    /** Get the Vacations API for reading the absences (vacation mode) the customer planned in the enyo app */
+    useVacations: () => EnergyAppVacations;
     /** Get the Timeseries Store API for storing the app's own number and text timeseries and querying them raw or aggregated */
     useTimeseriesStore: () => EnergyAppTimeseriesStore;
 }

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

@@ -6,6 +6,8 @@ exports.validateHeatpumpControlAction = validateHeatpumpControlAction;
 exports.computeHeatpumpSetpointRaise = computeHeatpumpSetpointRaise;
 exports.validateHeatpumpProgramSwitch = validateHeatpumpProgramSwitch;
 exports.validateHeatpumpHeatingCurveOffset = validateHeatpumpHeatingCurveOffset;
+exports.validateVacationStarted = validateVacationStarted;
+exports.validateVacationStopped = validateVacationStopped;
 const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
 const enyo_heatpump_appliance_js_1 = require("../../types/enyo-heatpump-appliance.cjs");
 /**
@@ -345,3 +347,127 @@ function validateHeatpumpHeatingCurveOffset(data, metadata) {
     }
     return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
 }
+/**
+ * Whether a value is a parsable ISO 8601 timestamp.
+ *
+ * @param value - The value to check.
+ * @returns `true` for a string `Date.parse` understands.
+ */
+function isIsoTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+/**
+ * Validates a `VacationStartedV1` against the heatpump's metadata and returns
+ * the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleVacationStarted`; an integration handling the message itself can call
+ * it too, and the energy manager can use it to decide between the vacation
+ * message and the eco fallback.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. Malformed data (**Rejected**): `vacationId` is not a non-empty string,
+ *    `returnIso` is not an ISO 8601 timestamp, `heatpump.heating` has an
+ *    unknown `mode` or a non-finite `targetTemperatureC`,
+ *    `heatpump.domesticHotWater.pause` is not a boolean, or `battery` has a
+ *    non-boolean `gridServing` or a `minSocAtReturnPercent` outside 0…100.
+ * 2. `heatpump.heating` asks for a mode whose feature is missing —
+ *    `VacationFrostProtection` or `VacationLowered` (**NotSupported**).
+ * 3. A lowered `targetTemperatureC` outside `vacationLoweredRangeC`, or no
+ *    range declared (**NotSupported**).
+ * 4. `heatpump.domesticHotWater.pause: true` without `VacationHotWaterPause`
+ *    (**NotSupported**).
+ *
+ * The `battery` part is only checked for its shape — heatpumps ignore it.
+ *
+ * Without metadata only rule 1 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateVacationStarted(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+function validateVacationStarted(data, metadata) {
+    const rejected = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, rejectionReason });
+    const notSupported = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported, rejectionReason });
+    if (typeof data.vacationId !== 'string' || data.vacationId.length === 0) {
+        return rejected(`vacationId must be a non-empty string; got ${data.vacationId}.`);
+    }
+    if (!isIsoTimestamp(data.returnIso))
+        return rejected(`returnIso must be an ISO 8601 timestamp; got ${data.returnIso}.`);
+    const heating = data.heatpump?.heating;
+    if (heating) {
+        if (!Object.values(enyo_data_bus_value_js_1.EnyoVacationHeatingEnum).includes(heating.mode)) {
+            return rejected(`heatpump.heating.mode must be one of ${Object.values(enyo_data_bus_value_js_1.EnyoVacationHeatingEnum).join(', ')}; got ${heating.mode}.`);
+        }
+        if (typeof heating.targetTemperatureC !== 'number' || !Number.isFinite(heating.targetTemperatureC)) {
+            return rejected(`heatpump.heating.targetTemperatureC must be a finite number; got ${heating.targetTemperatureC}.`);
+        }
+    }
+    const hotWater = data.heatpump?.domesticHotWater;
+    if (hotWater && typeof hotWater.pause !== 'boolean') {
+        return rejected(`heatpump.domesticHotWater.pause must be a boolean; got ${hotWater.pause}.`);
+    }
+    const battery = data.battery;
+    if (battery) {
+        if (typeof battery.gridServing !== 'boolean') {
+            return rejected(`battery.gridServing must be a boolean; got ${battery.gridServing}.`);
+        }
+        const soc = battery.minSocAtReturnPercent;
+        if (typeof soc !== 'number' || !Number.isFinite(soc) || soc < 0 || soc > 100) {
+            return rejected(`battery.minSocAtReturnPercent must be a number between 0 and 100; got ${soc}.`);
+        }
+    }
+    if (!metadata)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    const features = metadata.availableFeatures ?? [];
+    if (heating?.mode === enyo_data_bus_value_js_1.EnyoVacationHeatingEnum.FrostProtection
+        && !features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationFrostProtection)) {
+        return notSupported('The heatpump does not support vacation frost protection (no VacationFrostProtection).');
+    }
+    if (heating?.mode === enyo_data_bus_value_js_1.EnyoVacationHeatingEnum.Lowered) {
+        if (!features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationLowered)) {
+            return notSupported('The heatpump does not support a lowered vacation temperature (no VacationLowered).');
+        }
+        const range = metadata.vacationLoweredRangeC;
+        if (!range)
+            return notSupported('The heatpump declares no vacationLoweredRangeC.');
+        if (heating.targetTemperatureC < range.minC || heating.targetTemperatureC > range.maxC) {
+            return notSupported(`heatpump.heating.targetTemperatureC ${heating.targetTemperatureC} °C is outside vacationLoweredRangeC ${range.minC}…${range.maxC} °C.`);
+        }
+    }
+    if (hotWater?.pause && !features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationHotWaterPause)) {
+        return notSupported('The heatpump does not support pausing hot water while away (no VacationHotWaterPause).');
+    }
+    return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+}
+/**
+ * Validates a `VacationStoppedV1` and returns the answer it deserves. It is
+ * only `Rejected` when malformed (`vacationId` not a non-empty string) — a
+ * stop must be accepted even when nothing runs, so it needs no metadata.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleVacationStopped`.
+ *
+ * @param data - The message's data.
+ * @returns The answer: `Accepted` unless the data is malformed.
+ *
+ * @example
+ * ```typescript
+ * const result = validateVacationStopped(message.data);
+ * ```
+ */
+function validateVacationStopped(data) {
+    if (typeof data.vacationId !== 'string' || data.vacationId.length === 0) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected,
+            rejectionReason: `vacationId must be a non-empty string; got ${data.vacationId}.`,
+        };
+    }
+    return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+}

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

@@ -1,4 +1,4 @@
-import { EnyoCommandAcknowledgeActionResult, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoDataBusSetHeatpumpHeatingCurveOffsetV1, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
+import { EnyoCommandAcknowledgeActionResult, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoDataBusSetHeatpumpHeatingCurveOffsetV1, EnyoDataBusVacationStartedV1, EnyoDataBusVacationStoppedV1, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
 import { EnyoHeatpumpApplianceAvailableFeaturesEnum, EnyoHeatpumpApplianceMetadata } from '../../types/enyo-heatpump-appliance.cjs';
 /**
  * The overheating feature each `HeatpumpControlV3` target needs — and that a
@@ -212,3 +212,64 @@ export interface HeatpumpHeatingCurveOffsetValidationResult {
  * ```
  */
 export declare function validateHeatpumpHeatingCurveOffset(data: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined): HeatpumpHeatingCurveOffsetValidationResult;
+/** The answer {@link validateVacationStarted} or {@link validateVacationStopped} gives. */
+export interface HeatpumpVacationValidationResult {
+    /** `Accepted` when every rule holds. */
+    answer: EnyoCommandAcknowledgeAnswerEnum;
+    /** Why the command was rejected or is not supported. */
+    rejectionReason?: string;
+}
+/**
+ * Validates a `VacationStartedV1` against the heatpump's metadata and returns
+ * the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleVacationStarted`; an integration handling the message itself can call
+ * it too, and the energy manager can use it to decide between the vacation
+ * message and the eco fallback.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. Malformed data (**Rejected**): `vacationId` is not a non-empty string,
+ *    `returnIso` is not an ISO 8601 timestamp, `heatpump.heating` has an
+ *    unknown `mode` or a non-finite `targetTemperatureC`,
+ *    `heatpump.domesticHotWater.pause` is not a boolean, or `battery` has a
+ *    non-boolean `gridServing` or a `minSocAtReturnPercent` outside 0…100.
+ * 2. `heatpump.heating` asks for a mode whose feature is missing —
+ *    `VacationFrostProtection` or `VacationLowered` (**NotSupported**).
+ * 3. A lowered `targetTemperatureC` outside `vacationLoweredRangeC`, or no
+ *    range declared (**NotSupported**).
+ * 4. `heatpump.domesticHotWater.pause: true` without `VacationHotWaterPause`
+ *    (**NotSupported**).
+ *
+ * The `battery` part is only checked for its shape — heatpumps ignore it.
+ *
+ * Without metadata only rule 1 can be checked.
+ *
+ * @param data - The message's data.
+ * @param metadata - The heatpump's metadata, if known.
+ * @returns The answer: `Accepted` when every rule holds.
+ *
+ * @example
+ * ```typescript
+ * const result = validateVacationStarted(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+export declare function validateVacationStarted(data: EnyoDataBusVacationStartedV1['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined): HeatpumpVacationValidationResult;
+/**
+ * Validates a `VacationStoppedV1` and returns the answer it deserves. It is
+ * only `Rejected` when malformed (`vacationId` not a non-empty string) — a
+ * stop must be accepted even when nothing runs, so it needs no metadata.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleVacationStopped`.
+ *
+ * @param data - The message's data.
+ * @returns The answer: `Accepted` unless the data is malformed.
+ *
+ * @example
+ * ```typescript
+ * const result = validateVacationStopped(message.data);
+ * ```
+ */
+export declare function validateVacationStopped(data: EnyoDataBusVacationStoppedV1['data']): HeatpumpVacationValidationResult;

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

@@ -450,6 +450,9 @@ function assertValidHeatpumpTimeProgram(program) {
  *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
  *    Warning: `HeatingCurveOffset` is declared but no circuit has a
  *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
+ *  - Error: `VacationLowered` is declared without a `vacationLoweredRangeC`,
+ *    a `vacationLoweredRangeC` is set without `VacationLowered`, or the range
+ *    is not finite or has `minC` above `maxC`.
  *  - SG Ready relays: errors and warnings from {@link checkSgReadyRelays}.
  *
  * @param metadata - The heatpump metadata to validate.
@@ -505,6 +508,22 @@ function validateHeatpumpAdvancedMetadata(metadata) {
         && !circuits.some((c) => c.heatingCurveOffsetRangeK)) {
         warnings.push('HeatingCurveOffset is declared but no heating circuit has a heatingCurveOffsetRangeK — only offset 0 could be accepted');
     }
+    const declaresVacationLowered = features.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationLowered);
+    const vacationRange = metadata.vacationLoweredRangeC;
+    if (declaresVacationLowered && !vacationRange) {
+        errors.push('VacationLowered is declared but vacationLoweredRangeC is missing');
+    }
+    if (vacationRange) {
+        if (!declaresVacationLowered) {
+            errors.push('vacationLoweredRangeC is set but the heatpump does not declare VacationLowered');
+        }
+        if (!isFiniteNumber(vacationRange.minC) || !isFiniteNumber(vacationRange.maxC)) {
+            errors.push('vacationLoweredRangeC.minC and maxC must be finite numbers');
+        }
+        else if (vacationRange.minC > vacationRange.maxC) {
+            errors.push(`vacationLoweredRangeC ${vacationRange.minC}…${vacationRange.maxC} °C has minC above maxC`);
+        }
+    }
     for (const circuit of circuits) {
         const prefix = `heatingCircuits[index=${circuit.index}]`;
         if (circuit.heatingCurve)

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

@@ -117,9 +117,12 @@ export declare function assertValidHeatpumpTimeProgram(program: EnyoHeatpumpTime
  *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
  *    Warning: `HeatingCurveOffset` is declared but no circuit has a
  *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
+ *  - Error: `VacationLowered` is declared without a `vacationLoweredRangeC`,
+ *    a `vacationLoweredRangeC` is set without `VacationLowered`, or the range
+ *    is not finite or has `minC` above `maxC`.
  *  - SG Ready relays: errors and warnings from {@link checkSgReadyRelays}.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.
  */
-export declare function validateHeatpumpAdvancedMetadata(metadata: Pick<EnyoHeatpumpApplianceMetadata, 'availableFeatures' | 'heatingCircuits' | 'domesticHotWater' | 'building'> & Partial<Pick<EnyoHeatpumpApplianceMetadata, 'sgReadyRelays' | 'additionalDevices'>>): HeatpumpMetadataValidationResult;
+export declare function validateHeatpumpAdvancedMetadata(metadata: Pick<EnyoHeatpumpApplianceMetadata, 'availableFeatures' | 'heatingCircuits' | 'domesticHotWater' | 'building'> & Partial<Pick<EnyoHeatpumpApplianceMetadata, 'sgReadyRelays' | 'additionalDevices' | 'vacationLoweredRangeC'>>): HeatpumpMetadataValidationResult;

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);
@@ -204,6 +205,8 @@ __exportStar(require("./types/enyo-room.cjs"), exports);
 __exportStar(require("./packages/energy-app-room.cjs"), exports);
 __exportStar(require("./types/enyo-room-temperature.cjs"), exports);
 __exportStar(require("./packages/energy-app-room-temperatures.cjs"), exports);
+__exportStar(require("./types/enyo-vacation.cjs"), exports);
+__exportStar(require("./packages/energy-app-vacations.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/define-subscription-plan.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/subscription-plan-validators.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/subscription-offer-validators.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';
@@ -188,6 +189,8 @@ export * from './types/enyo-room.cjs';
 export * from './packages/energy-app-room.cjs';
 export * from './types/enyo-room-temperature.cjs';
 export * from './packages/energy-app-room-temperatures.cjs';
+export * from './types/enyo-vacation.cjs';
+export * from './packages/energy-app-vacations.cjs';
 export * from './implementations/subscriptions/define-subscription-plan.cjs';
 export * from './implementations/subscriptions/subscription-plan-validators.cjs';
 export * from './implementations/subscriptions/subscription-offer-validators.cjs';