@enyo-energy/energy-app-sdk 1.50.0 → 1.52.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.
@@ -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/index.cjs

@@ -205,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

@@ -189,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';

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

@@ -78,6 +78,15 @@ function combineHeatpumpControlAnswers(answers) {
  *    {@link handleHeatpumpHeatingCurveOffset} and declare
  *    {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingCurveOffset}).
  *    The base class validates it with {@link checkHeatingCurveOffset} first.
+ *  - `VacationStartedV1` / `VacationStoppedV1` — the customer is away: heat
+ *    with frost protection or lowered and / or pause hot water, then restore
+ *    everything (optional: override {@link handleVacationStarted} /
+ *    {@link handleVacationStopped} and declare
+ *    {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationFrostProtection},
+ *    {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationLowered} and / or
+ *    {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationHotWaterPause}).
+ *    The base class validates them with {@link validateVacationStarted} /
+ *    {@link validateVacationStopped} first.
  *  - `GridOperatorPowerLimitationV1` — §14a EnWG broadcast (handled in base).
  *
  * Publishes `HeatpumpFlexibilityAnnouncementV3` offers via
@@ -138,6 +147,8 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpControlCancelV3, (msg) => this.dispatchHeatpumpControlCancel(msg));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpProgramSwitchV3, (msg) => this.dispatchHeatpumpProgramSwitch(msg));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetHeatpumpHeatingCurveOffsetV1, (msg) => this.dispatchHeatpumpHeatingCurveOffset(msg));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.VacationStartedV1, (msg) => this.dispatchVacationStarted(msg));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.VacationStoppedV1, (msg) => this.dispatchVacationStopped(msg));
     }
     /**
      * Stops the integration, drops every running `HeatpumpControlV3` session
@@ -558,6 +569,99 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         const metadata = await this.resolveHeatpumpMetadata(message.applianceId);
         return (0, heatpump_control_validators_js_1.validateHeatpumpHeatingCurveOffset)(message.data, metadata);
     }
+    /**
+     * Handles a `VacationStartedV1` command: the customer is away, so bring the
+     * heatpump into the wanted state — heat with frost protection or at a
+     * lowered room temperature (`message.data.heatpump.heating`; absent = heat
+     * as usual) and pause hot water
+     * (`message.data.heatpump.domesticHotWater.pause`). How to realise it is up
+     * to the integration; the `battery` part is not meant for heatpumps. Answers `NotSupported` by default. Override
+     * it together with {@link handleVacationStopped} and declare the vacation
+     * features the device supports
+     * ({@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationFrostProtection},
+     * {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationLowered} with
+     * `vacationLoweredRangeC`,
+     * {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.VacationHotWaterPause}).
+     *
+     * What an implementation must do:
+     * - Prefer the device's own holiday / absence mode and write
+     *   `message.data.returnIso` as its end, so everything ends even when the
+     *   app or the energy manager is not running. Without one, write the
+     *   setpoints and restore them yourself at `returnIso` if no
+     *   `VacationStoppedV1` arrives.
+     * - Treat the message as idempotent and as the complete wanted state: the
+     *   energy manager re-sends it whenever the wanted state changes and at
+     *   least hourly. A message without `heatpump.heating` means heating runs
+     *   as usual again (e.g. pre-heating for the return); without
+     *   `heatpump.domesticHotWater` or with `pause: false`, hot water is
+     *   reheated again.
+     * - Keep legionella protection running while hot water is paused.
+     * - Answer `Rejected` (with `rejectionReason`) when the state cannot be
+     *   written right now, e.g. the device is in a manual mode.
+     *
+     * The base class has already validated the message with
+     * {@link validateVacationStarted}: the data is well-formed, the features
+     * for the requested heating mode and hot water pause are declared and a
+     * lowered target lies inside `vacationLoweredRangeC`.
+     *
+     * @param _message - The vacation started command.
+     * @returns `Accepted` once the state is written, `Rejected` (with
+     *   `rejectionReason`) when it cannot be written right now,
+     *   `NotSupported` when the integration does not support vacations.
+     *
+     * @example
+     * ```ts
+     * protected async handleVacationStarted(message: EnyoDataBusVacationStartedV1) {
+     *     const {heatpump, returnIso} = message.data;
+     *     await this.device.writeHolidayMode({
+     *         roomSetpointC: heatpump?.heating?.targetTemperatureC,
+     *         pauseHotWater: heatpump?.domesticHotWater?.pause ?? false,
+     *         endIso: returnIso,
+     *     });
+     *     return {answer: EnyoCommandAcknowledgeAnswerEnum.Accepted};
+     * }
+     * ```
+     */
+    async handleVacationStarted(_message) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported,
+            rejectionReason: 'Heatpump integration does not support VacationStartedV1',
+        };
+    }
+    /**
+     * Handles a `VacationStoppedV1` command: the vacation is over (return,
+     * early return or removed), so restore everything
+     * {@link handleVacationStarted} changed and let the heatpump follow its
+     * own time program again. Answers `NotSupported` by default; override it
+     * together with {@link handleVacationStarted}.
+     *
+     * An implementation must answer `Accepted` even when nothing runs (e.g.
+     * the device already ended its holiday mode at `returnIso`), and
+     * `Rejected` (with `rejectionReason`) only when the device cannot be
+     * restored right now.
+     *
+     * The base class has already validated the message with
+     * {@link validateVacationStopped}.
+     *
+     * @param _message - The vacation stopped command.
+     * @returns `Accepted` once everything is restored (or nothing ran),
+     *   `Rejected` (with `rejectionReason`) when it cannot be restored right
+     *   now, `NotSupported` when the integration does not support vacations.
+     *
+     * @example
+     * ```ts
+     * protected async handleVacationStopped(_message: EnyoDataBusVacationStoppedV1) {
+     *     await this.device.endHolidayMode();
+     *     return {answer: EnyoCommandAcknowledgeAnswerEnum.Accepted};
+     * }
+     * ```
+     */
+    async handleVacationStopped(_message) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported,
+            rejectionReason: 'Heatpump integration does not support VacationStoppedV1',
+        };
+    }
     /**
      * Publishes a `HeatpumpValuesUpdateV1` message reporting the heatpump's
      * current operation mode and energy values to the data bus.
@@ -721,6 +825,23 @@ class HeatpumpIntegrationEnergyApp extends integration_energy_app_js_1.Integrati
         }
         return this.handleHeatpumpHeatingCurveOffset(message);
     }
+    /** Validates a `VacationStartedV1` against the metadata, then calls {@link handleVacationStarted}. */
+    async dispatchVacationStarted(message) {
+        const metadata = await this.resolveHeatpumpMetadata(message.applianceId);
+        const validation = (0, heatpump_control_validators_js_1.validateVacationStarted)(message.data, metadata);
+        if (validation.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted) {
+            return validation;
+        }
+        return this.handleVacationStarted(message);
+    }
+    /** Validates a `VacationStoppedV1`, then calls {@link handleVacationStopped}. */
+    async dispatchVacationStopped(message) {
+        const validation = (0, heatpump_control_validators_js_1.validateVacationStopped)(message.data);
+        if (validation.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted) {
+            return validation;
+        }
+        return this.handleVacationStopped(message);
+    }
     async dispatchHeatpumpControlCancel(message) {
         const response = await this.handleHeatpumpControlCancel(message);
         if (response.answer !== enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported