@enyo-energy/energy-app-sdk 1.42.0 → 1.44.0

package/README.md

@@ -409,6 +409,8 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`GridFeeRegister`** / **`GridFeeUse`**: Publish / resolve dynamic grid fees (time-variable network charges)
 - **`CommandLog`**: Record and read back the commands apps issued to appliances
 - **`Subscriptions`**: Read the subscriptions bought for the app on this device
+- **`Room`**: Read the rooms of the home the customer set up in the enyo app
+- **`RoomTemperatures`**: Read the current and past temperatures measured in those rooms
 
 #### Site & Identity Permissions
 
@@ -1768,6 +1770,37 @@ const full = await location.getLocation();                 // requires LocationC
 if (full) console.log(`lat=${full.latitude} lon=${full.longitude}`);
 ```
 
+#### `useRoom(): EnergyAppRoom`
+
+Read the rooms of the home, as the customer set them up in the enyo app: name, the appliances in each, the temperature the customer wants there (`targetTemperatureC`, optional — use `HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C` = 21 °C until set) and, for the heating curve optimisation, the room's `warmth` (`EnyoRoomWarmthEnum`) and `thermostat` (`EnyoRoomThermostatEnum`). Read-only.
+
+```typescript
+const rooms = energyApp.useRoom();
+
+applyRooms(await rooms.getRooms());
+const circuitRooms = await rooms.getRoomsById(circuit.curveOptimization?.roomIds ?? []);
+rooms.listenForRoomsChanged((all) => applyRooms(all));
+```
+
+Requires the `Room` permission.
+
+#### `useRoomTemperatures(): EnergyAppRoomTemperatures`
+
+Read the temperatures measured in the rooms, per sensor — a room can have several. `getCurrentRoomTemperatures(roomIds)` returns the latest reading of each sensor, `getRoomTemperatureHistory({roomIds, startDateIso, endDateIso, resolution})` the past ones in `'1m'` or `'15m'` buckets (average, min, max). There is no listener: follow the sensors named in the current values (`applianceId`, `sensorId`) via `TemperatureSensorValuesUpdateV1` on the data bus.
+
+```typescript
+const roomTemperatures = energyApp.useRoomTemperatures();
+
+const current = await roomTemperatures.getCurrentRoomTemperatures(['living', 'bath']);
+const history = await roomTemperatures.getRoomTemperatureHistory({
+    roomIds: ['living', 'bath'],
+    startDateIso: '2026-10-27T00:00:00Z',
+    endDateIso: '2026-10-28T00:00:00Z',
+});
+```
+
+Requires the `RoomTemperatures` 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.
@@ -3666,12 +3699,13 @@ 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`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpProgramSwitchV3`, `SetHeatpumpHeatingCurveOffsetV1`, `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`.
   - `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.
@@ -3732,6 +3766,44 @@ Switches one heating circuit or DHW zone to its **comfort** or **eco** setpoint
 - **Owner's consent for price-driven eco.** An energy manager switches zones to eco for price reasons only while the general setting `heatpumpEcoModeInExpensiveTimes` (and `heatpumpControl`) is `true` — see [General settings](#general-settings).
 - **Validation** (run by the base class before the handler, or `validateHeatpumpProgramSwitch(data, metadata)` directly): target `Room` / `Dhw`, a known mode, a valid `untilIso` for comfort / eco (`Rejected`); `ProgramSwitch` declared and the mode listed for the zone (`NotSupported`); a known zone index (`Rejected`).
 
+#### SetHeatpumpHeatingCurveOffsetV1
+
+Shifts the heating curve of one heating circuit in parallel — **permanently**, until the next message. The energy manager uses it to lower the curve as far as the measured room temperature allows (less flow temperature, roughly 2.5 % less heating electricity per K).
+
+```typescript
+{
+    heatingCircuitIndex: 0,
+    offsetK: -1.5,   // K of flow temperature, relative to the initial curve; 0 restores it
+}
+```
+
+- **Relative to the initial curve, never to the current one.** Before the first offset other than `0`, the integration stores the curve set on the device as `heatingCircuits[].initialHeatingCurve` (`ApplianceManager.rememberHeatpumpInitialHeatingCurve` keeps an already stored one). The same message may therefore arrive twice.
+- **`offsetK: 0` restores** the initial curve exactly, including vendor parameters, then clears it (`ApplianceManager.clearHeatpumpInitialHeatingCurve`, which also sets `activeHeatingCurveOffsetK` to `0`).
+- **No expiry.** If the hub is offline nobody could reset it anyway; the stored initial curve is the safety net.
+- **Vendor units.** Convert to whatever the device shifts in (K of room temperature, steps, …) and report the effective shift in K of flow temperature as `heatingCircuits[].activeHeatingCurveOffsetK`, read back from the device. The energy manager waits for it before the next change.
+- **Changed by hand.** If the curve read from the device differs from `initialHeatingCurve` shifted by `activeHeatingCurveOffsetK` by more than 0.5 K at any point (`isHeatingCurveManuallyChanged(initial, offsetK, read)`), store the read curve as the new `initialHeatingCurve`, set `activeHeatingCurveOffsetK` to `0` and log it in a plain sentence.
+- **Alongside `HeatpumpControlV3` and `HeatpumpProgramSwitchV3`.** Boost and eco act on top; the offset is the new base.
+- **Validation** (run by the base class before the handler via `checkHeatingCurveOffset`, or `validateHeatpumpHeatingCurveOffset(data, metadata)` directly): a valid index and finite `offsetK` (`Rejected`); `HeatingCurveOffset` declared (`NotSupported`); a known circuit and — unless `offsetK` is `0` — within `heatingCurveOffsetRangeK` (`Rejected`).
+- **Customer settings.** Whether to optimise at all, and which rooms of the home the circuit heats (`roomIds`, whether or not a room has a sensor), live in `heatingCircuits[].curveOptimization`. The rooms themselves come from `useRoom().getRoomsById(roomIds)`, their measured temperatures from `useRoomTemperatures()`; `curveOptimizationRooms(curveOptimization, rooms)` picks the ones the curve is judged by (the warmest rooms behind a manual thermostat, and every room with a self-regulating thermostat or none). A room at its target means the curve is just right when its thermostat is open, but only a room falling below its target shows the curve went too far behind a self-regulating one. Rooms without a sensor are left out; the room furthest below its target counts, and the curve is lowered by at most `HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K` (3 K). Integrations only read them.
+
+```typescript
+protected async handleHeatpumpHeatingCurveOffset(message: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1) {
+    const {heatingCircuitIndex: index, offsetK} = message.data;
+    if (offsetK !== 0) {
+        await this.appliances.rememberHeatpumpInitialHeatingCurve(message.applianceId, index, await this.readCurve(index));
+    }
+    await this.device.writeCurveShift(index, offsetK);
+    if (offsetK === 0) {
+        await this.appliances.clearHeatpumpInitialHeatingCurve(message.applianceId, index);
+    } else {
+        await this.appliances.updateHeatpumpHeatingCircuit(message.applianceId, index, {
+            activeHeatingCurveOffsetK: await this.readEffectiveShiftK(index),
+        });
+    }
+    return {answer: EnyoCommandAcknowledgeAnswerEnum.Accepted};
+}
+```
+
 #### 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`.
@@ -3767,6 +3839,9 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `ProgramSwitch` | `heatingCircuits[].supportedProgramModes` / `programModeTemperaturesC` / `activeProgramMode` and the same on `domesticHotWater[]` — which zones can be switched to comfort / eco with `HeatpumpProgramSwitchV3`, at which setpoints, and the mode they run in now |
 | `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) |
+| — | `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` |
 | `ControlV3` | The heatpump's app handles `HeatpumpControlV3` / `HeatpumpControlCancelV3` and reports `HeatpumpControlStatusV3`. The energy manager sends V3 only to heatpumps declaring it. Needs at least one overheating feature to be actionable |
 | `FlexibilityAnnouncementV3` | The heatpump publishes `HeatpumpFlexibilityAnnouncementV3` offers; the energy manager plans from them instead of deriving the headroom from metadata. Needs at least one overheating feature to be actionable |

package/dist/cjs/energy-app-permission.type.cjs

@@ -69,4 +69,6 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["VehicleIntegration"] = "VehicleIntegration";
     EnergyAppPermissionTypeEnum["Webhook"] = "Webhook";
     EnergyAppPermissionTypeEnum["Subscriptions"] = "Subscriptions";
+    EnergyAppPermissionTypeEnum["Room"] = "Room";
+    EnergyAppPermissionTypeEnum["RoomTemperatures"] = "RoomTemperatures";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

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

@@ -64,7 +64,9 @@ export declare enum EnergyAppPermissionTypeEnum {
     Calibration = "Calibration",
     VehicleIntegration = "VehicleIntegration",
     Webhook = "Webhook",
-    Subscriptions = "Subscriptions"
+    Subscriptions = "Subscriptions",
+    Room = "Room",
+    RoomTemperatures = "RoomTemperatures"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -552,6 +552,32 @@ class EnergyApp {
     useSubscriptions() {
         return this.energyAppSdk.useSubscriptions();
     }
+    /**
+     * Gets the Room API for reading the rooms of the home: their name, the
+     * appliances in them, the temperature the customer wants there and, for
+     * the heating curve optimisation, their warmth and thermostat. Read the
+     * rooms with `getRooms()` or `getRoomsById()` and react to changes with
+     * `listenForRoomsChanged()`.
+     * @returns The Room API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Room` permission is
+     *         not granted.
+     */
+    useRoom() {
+        return this.energyAppSdk.useRoom();
+    }
+    /**
+     * Gets the Room Temperatures API for reading the temperatures measured in
+     * the rooms of the home, per sensor: the current values with
+     * `getCurrentRoomTemperatures()` and the past ones with
+     * `getRoomTemperatureHistory()`. Follow changes via the
+     * `TemperatureSensorValuesUpdateV1` messages on the data bus.
+     * @returns The Room Temperatures API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `RoomTemperatures`
+     *         permission is not granted.
+     */
+    useRoomTemperatures() {
+        return this.energyAppSdk.useRoomTemperatures();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -53,6 +53,8 @@ import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 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 { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -469,6 +471,28 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useSubscriptions(): EnergyAppSubscriptions;
+    /**
+     * Gets the Room API for reading the rooms of the home: their name, the
+     * appliances in them, the temperature the customer wants there and, for
+     * the heating curve optimisation, their warmth and thermostat. Read the
+     * rooms with `getRooms()` or `getRoomsById()` and react to changes with
+     * `listenForRoomsChanged()`.
+     * @returns The Room API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Room` permission is
+     *         not granted.
+     */
+    useRoom(): EnergyAppRoom;
+    /**
+     * Gets the Room Temperatures API for reading the temperatures measured in
+     * the rooms of the home, per sensor: the current values with
+     * `getCurrentRoomTemperatures()` and the past ones with
+     * `getRoomTemperatureHistory()`. Follow changes via the
+     * `TemperatureSensorValuesUpdateV1` messages on the data bus.
+     * @returns The Room Temperatures API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `RoomTemperatures`
+     *         permission is not granted.
+     */
+    useRoomTemperatures(): EnergyAppRoomTemperatures;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -52,6 +52,8 @@ import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
 import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 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 { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -198,4 +200,8 @@ export interface EnyoEnergyAppSdk {
     useWebhook: () => EnergyAppWebhook;
     /** Get the Subscriptions API for reading the subscriptions bought for this app on this device and listening for new or changed subscriptions */
     useSubscriptions: () => EnergyAppSubscriptions;
+    /** Get the Room API for reading the rooms of the home the customer set up in the enyo app */
+    useRoom: () => EnergyAppRoom;
+    /** Get the Room Temperatures API for reading the current and past temperatures measured in the rooms of the home */
+    useRoomTemperatures: () => EnergyAppRoomTemperatures;
 }

package/dist/cjs/implementations/appliances/appliance-manager.cjs

@@ -618,6 +618,62 @@ class ApplianceManager {
         await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { domesticHotWater: zones } }), applianceId);
         await this.primeCacheFromSdk(applianceId);
     }
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async rememberHeatpumpInitialHeatingCurve(applianceId, index, curve) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return false;
+        const circuit = appliance.heatpump?.heatingCircuits?.find(c => c.index === index);
+        if (circuit?.initialHeatingCurve)
+            return false;
+        await this.updateHeatpumpHeatingCircuit(applianceId, index, { initialHeatingCurve: curve });
+        return true;
+    }
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async clearHeatpumpInitialHeatingCurve(applianceId, index) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return;
+        const circuits = [...(appliance.heatpump?.heatingCircuits ?? [])];
+        const position = circuits.findIndex(c => c.index === index);
+        if (position < 0)
+            return;
+        const { initialHeatingCurve: _removed, ...rest } = circuits[position];
+        circuits[position] = { ...rest, activeHeatingCurveOffsetK: 0 };
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { heatingCircuits: circuits } }), applianceId);
+        await this.primeCacheFromSdk(applianceId);
+    }
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with

package/dist/cjs/implementations/appliances/appliance-manager.d.cts

@@ -3,7 +3,7 @@ import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
 import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceGroup, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
 import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.cjs";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.cjs";
-import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
+import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceHeatingCurve, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
 import type { EnyoBatteryApplianceMetadata } from "../../types/enyo-battery-appliance.cjs";
 import type { EnyoInverterApplianceMetadata } from "../../types/enyo-inverter-appliance.cjs";
 import type { EnyoMeterAppliance } from "../../types/enyo-meter-appliance.cjs";
@@ -401,6 +401,39 @@ export declare class ApplianceManager {
      * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
      */
     updateHeatpumpDomesticHotWater(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceDomesticHotWater, 'index'>>): Promise<void>;
+    /**
+     * Remembers the heating curve a circuit had before the first
+     * `SetHeatpumpHeatingCurveOffsetV1` changed it, as the circuit's
+     * `initialHeatingCurve` — the curve `offsetK: 0` restores. Call it before
+     * writing the first offset other than `0`.
+     *
+     * Keeps an already stored initial curve: every later offset is relative to
+     * the curve before the *first* change, so it must not be overwritten with
+     * an already shifted one. Works like {@link updateHeatpumpHeatingCircuit}
+     * otherwise.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @param curve The curve currently set on the device
+     * @returns `true` when the curve was stored, `false` when an initial curve
+     *   was already stored or the appliance does not exist
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    rememberHeatpumpInitialHeatingCurve(applianceId: string, index: number, curve: EnyoHeatpumpApplianceHeatingCurve): Promise<boolean>;
+    /**
+     * Forgets a circuit's `initialHeatingCurve` after the integration restored
+     * it on the device (`offsetK: 0`), and sets `activeHeatingCurveOffsetK` to
+     * `0`. Other circuits and fields are left untouched.
+     *
+     * Does nothing when the appliance or the circuit does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    clearHeatpumpInitialHeatingCurve(applianceId: string, index: number): Promise<void>;
     /**
      * Refetches an appliance from the SDK and reflects the result in the
      * cache. Used by mutating methods to keep cache reads consistent with

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

@@ -5,6 +5,7 @@ exports.isPvOnlyPowerSources = isPvOnlyPowerSources;
 exports.validateHeatpumpControlAction = validateHeatpumpControlAction;
 exports.computeHeatpumpSetpointRaise = computeHeatpumpSetpointRaise;
 exports.validateHeatpumpProgramSwitch = validateHeatpumpProgramSwitch;
+exports.validateHeatpumpHeatingCurveOffset = validateHeatpumpHeatingCurveOffset;
 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");
 /**
@@ -284,3 +285,63 @@ function validateHeatpumpProgramSwitch(data, metadata, nowMs = Date.now()) {
     }
     return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
 }
+/**
+ * Validates a `SetHeatpumpHeatingCurveOffsetV1` against the heatpump's
+ * metadata and returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpHeatingCurveOffset`; an integration handling the message
+ * itself can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `heatingCircuitIndex` is an integer ≥ 0 and `offsetK` a finite number
+ *    (**Rejected**).
+ * 2. The heatpump does not declare `HeatingCurveOffset` (**NotSupported**).
+ * 3. No heating circuit has the message's index (**Rejected**).
+ * 4. `offsetK` is not `0` and the circuit has no `heatingCurveOffsetRangeK`
+ *    or `offsetK` lies outside it (**Rejected**). `0` — restoring the initial
+ *    curve — is always allowed.
+ *
+ * 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 = validateHeatpumpHeatingCurveOffset(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+function validateHeatpumpHeatingCurveOffset(data, metadata) {
+    const rejected = (rejectionReason) => ({ answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Rejected, rejectionReason });
+    if (!Number.isInteger(data.heatingCircuitIndex) || data.heatingCircuitIndex < 0) {
+        return rejected(`heatingCircuitIndex must be an integer ≥ 0; got ${data.heatingCircuitIndex}.`);
+    }
+    if (typeof data.offsetK !== 'number' || !Number.isFinite(data.offsetK)) {
+        return rejected(`offsetK must be a finite number; got ${data.offsetK}.`);
+    }
+    if (!metadata)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    if (!(metadata.availableFeatures ?? []).includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingCurveOffset)) {
+        return {
+            answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.NotSupported,
+            rejectionReason: 'The heatpump does not support heating curve offsets (no HeatingCurveOffset).',
+        };
+    }
+    const circuit = (metadata.heatingCircuits ?? []).find((c) => c.index === data.heatingCircuitIndex);
+    if (!circuit) {
+        return rejected(`No heating circuit with index ${data.heatingCircuitIndex}.`);
+    }
+    if (data.offsetK === 0)
+        return { answer: enyo_data_bus_value_js_1.EnyoCommandAcknowledgeAnswerEnum.Accepted };
+    const range = circuit.heatingCurveOffsetRangeK;
+    if (!range) {
+        return rejected(`Heating circuit ${circuit.index} declares no heatingCurveOffsetRangeK; only offsetK 0 is accepted.`);
+    }
+    if (data.offsetK < range.minK || data.offsetK > range.maxK) {
+        return rejected(`offsetK ${data.offsetK} K is outside the range ${range.minK}…${range.maxK} K of heating circuit ${circuit.index}.`);
+    }
+    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, EnyoHeatpumpControlAction, EnyoHeatpumpControlTargetEnum, EnyoPowerSourceShare } from '../../types/enyo-data-bus-value.cjs';
+import { EnyoCommandAcknowledgeActionResult, EnyoCommandAcknowledgeAnswerEnum, EnyoDataBusHeatpumpFlexibilityAnnouncementV3, EnyoDataBusHeatpumpProgramSwitchV3, EnyoDataBusSetHeatpumpHeatingCurveOffsetV1, 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
@@ -175,3 +175,40 @@ export interface HeatpumpProgramSwitchValidationResult {
  * ```
  */
 export declare function validateHeatpumpProgramSwitch(data: EnyoDataBusHeatpumpProgramSwitchV3['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined, nowMs?: number): HeatpumpProgramSwitchValidationResult;
+/** The answer {@link validateHeatpumpHeatingCurveOffset} gives a `SetHeatpumpHeatingCurveOffsetV1`. */
+export interface HeatpumpHeatingCurveOffsetValidationResult {
+    /** `Accepted` when every rule holds. */
+    answer: EnyoCommandAcknowledgeAnswerEnum;
+    /** Why the offset was rejected or is not supported. */
+    rejectionReason?: string;
+}
+/**
+ * Validates a `SetHeatpumpHeatingCurveOffsetV1` against the heatpump's
+ * metadata and returns the answer it deserves.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp` before it calls
+ * `handleHeatpumpHeatingCurveOffset`; an integration handling the message
+ * itself can call it too.
+ *
+ * Rules, in order — the first that fails decides:
+ * 1. `heatingCircuitIndex` is an integer ≥ 0 and `offsetK` a finite number
+ *    (**Rejected**).
+ * 2. The heatpump does not declare `HeatingCurveOffset` (**NotSupported**).
+ * 3. No heating circuit has the message's index (**Rejected**).
+ * 4. `offsetK` is not `0` and the circuit has no `heatingCurveOffsetRangeK`
+ *    or `offsetK` lies outside it (**Rejected**). `0` — restoring the initial
+ *    curve — is always allowed.
+ *
+ * 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 = validateHeatpumpHeatingCurveOffset(message.data, appliance.heatpump);
+ * if (result.answer !== EnyoCommandAcknowledgeAnswerEnum.Accepted) console.warn(result.rejectionReason);
+ * ```
+ */
+export declare function validateHeatpumpHeatingCurveOffset(data: EnyoDataBusSetHeatpumpHeatingCurveOffsetV1['data'], metadata: EnyoHeatpumpApplianceMetadata | undefined): HeatpumpHeatingCurveOffsetValidationResult;

package/dist/cjs/implementations/heatpump/heatpump-curve-optimization-rooms.cjs

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Which rooms of a heating circuit the room-temperature based heating curve
+ * optimisation is judged by. Shared by the energy manager, which lowers the
+ * curve, and the host's app, which tells the customer how to set each room's
+ * thermostat — both must agree on it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.curveWarmthRank = curveWarmthRank;
+exports.isManualRoomThermostat = isManualRoomThermostat;
+exports.curveTopManualRank = curveTopManualRank;
+exports.curveJudgedRoomIds = curveJudgedRoomIds;
+exports.curveOptimizationRooms = curveOptimizationRooms;
+const enyo_room_js_1 = require("../../types/enyo-room.cjs");
+const WARMTH_RANK = {
+    [enyo_room_js_1.EnyoRoomWarmthEnum.Cool]: 0,
+    [enyo_room_js_1.EnyoRoomWarmthEnum.Normal]: 1,
+    [enyo_room_js_1.EnyoRoomWarmthEnum.Warm]: 2,
+};
+const MANUAL_THERMOSTATS = new Set([
+    enyo_room_js_1.EnyoRoomThermostatEnum.Steps5,
+    enyo_room_js_1.EnyoRoomThermostatEnum.Steps6,
+    enyo_room_js_1.EnyoRoomThermostatEnum.CelsiusDial,
+]);
+/**
+ * How much warmth a room asks for compared with the other rooms of its
+ * circuit: 0 for `cool`, 1 for `normal` (also when absent), 2 for `warm`.
+ *
+ * @param traits - The room's warmth, if known.
+ * @returns The rank.
+ */
+function curveWarmthRank(traits) {
+    return WARMTH_RANK[traits?.warmth ?? enyo_room_js_1.EnyoRoomWarmthEnum.Normal];
+}
+/**
+ * Whether a thermostat is set by hand: a dial with steps or a dial in °C.
+ * Absent counts as the common dial with steps 1–5.
+ *
+ * @param thermostat - The room's thermostat.
+ * @returns `true` for a manual thermostat.
+ */
+function isManualRoomThermostat(thermostat) {
+    return thermostat === undefined || MANUAL_THERMOSTATS.has(thermostat);
+}
+/**
+ * How much warmth the most demanding room behind a manual thermostat asks for.
+ *
+ * @param roomIds - The rooms of the circuit.
+ * @param traitsOf - A room's warmth and thermostat.
+ * @returns The highest rank, or `undefined` when no room has a manual thermostat.
+ */
+function curveTopManualRank(roomIds, traitsOf) {
+    const ranks = roomIds
+        .filter((roomId) => isManualRoomThermostat(traitsOf(roomId)?.thermostat))
+        .map((roomId) => curveWarmthRank(traitsOf(roomId)));
+    return ranks.length > 0 ? Math.max(...ranks) : undefined;
+}
+/**
+ * The rooms of a heating circuit the curve is judged by. One flow temperature
+ * heats every room of the circuit, so the curve has to serve the warmest wish:
+ * of the rooms with a manual thermostat, those asking for the most warmth keep
+ * it fully open and show what the curve does. Every other one is held back by
+ * its thermostat, reads the thermostat rather than the curve, and would mislead
+ * the controller. A room with no thermostat follows the curve, and one with a
+ * self-regulating thermostat holds its own target — both are always judged.
+ *
+ * @param roomIds - The rooms of the circuit.
+ * @param traitsOf - A room's warmth and thermostat.
+ * @returns The judged room IDs, in the order given.
+ */
+function curveJudgedRoomIds(roomIds, traitsOf) {
+    const top = curveTopManualRank(roomIds, traitsOf);
+    return roomIds.filter((roomId) => {
+        const traits = traitsOf(roomId);
+        return !isManualRoomThermostat(traits?.thermostat) || curveWarmthRank(traits) === top;
+    });
+}
+/**
+ * The rooms a heating circuit's curve optimisation is judged by, resolved
+ * against the rooms of the home ({@link EnergyAppRoom.getRooms} or
+ * {@link EnergyAppRoom.getRoomsById}). A room that no longer exists is
+ * dropped. Whether a judged room can be measured is up to
+ * {@link EnergyAppRoomTemperatures}.
+ *
+ * @param settings - The circuit's {@link EnyoHeatpumpApplianceHeatingCircuit.curveOptimization}.
+ * @param rooms - Every room of the home.
+ * @returns The judged rooms, in the order of `settings.roomIds`.
+ */
+function curveOptimizationRooms(settings, rooms) {
+    const live = (settings?.roomIds ?? []).flatMap((roomId) => {
+        const room = rooms.find((candidate) => candidate.id === roomId);
+        return room ? [room] : [];
+    });
+    const judged = curveJudgedRoomIds(live.map((room) => room.id), (roomId) => live.find((room) => room.id === roomId));
+    return live.filter((room) => judged.includes(room.id));
+}

package/dist/cjs/implementations/heatpump/heatpump-curve-optimization-rooms.d.cts

@@ -0,0 +1,65 @@
+/**
+ * Which rooms of a heating circuit the room-temperature based heating curve
+ * optimisation is judged by. Shared by the energy manager, which lowers the
+ * curve, and the host's app, which tells the customer how to set each room's
+ * thermostat — both must agree on it.
+ */
+import type { EnyoHeatpumpHeatingCurveOptimizationSettings } from '../../types/enyo-heatpump-appliance.cjs';
+import { type EnyoRoom, EnyoRoomThermostatEnum, EnyoRoomWarmthEnum } from '../../types/enyo-room.cjs';
+/** What the curve rules need to know about a room. */
+export interface CurveRoomTraits {
+    /** Absent: {@link EnyoRoomWarmthEnum.Normal}. */
+    warmth?: EnyoRoomWarmthEnum;
+    /** Absent: {@link EnyoRoomThermostatEnum.Steps5}. */
+    thermostat?: EnyoRoomThermostatEnum;
+}
+/**
+ * How much warmth a room asks for compared with the other rooms of its
+ * circuit: 0 for `cool`, 1 for `normal` (also when absent), 2 for `warm`.
+ *
+ * @param traits - The room's warmth, if known.
+ * @returns The rank.
+ */
+export declare function curveWarmthRank(traits: CurveRoomTraits | undefined): number;
+/**
+ * Whether a thermostat is set by hand: a dial with steps or a dial in °C.
+ * Absent counts as the common dial with steps 1–5.
+ *
+ * @param thermostat - The room's thermostat.
+ * @returns `true` for a manual thermostat.
+ */
+export declare function isManualRoomThermostat(thermostat: EnyoRoomThermostatEnum | undefined): boolean;
+/**
+ * How much warmth the most demanding room behind a manual thermostat asks for.
+ *
+ * @param roomIds - The rooms of the circuit.
+ * @param traitsOf - A room's warmth and thermostat.
+ * @returns The highest rank, or `undefined` when no room has a manual thermostat.
+ */
+export declare function curveTopManualRank(roomIds: readonly string[], traitsOf: (roomId: string) => CurveRoomTraits | undefined): number | undefined;
+/**
+ * The rooms of a heating circuit the curve is judged by. One flow temperature
+ * heats every room of the circuit, so the curve has to serve the warmest wish:
+ * of the rooms with a manual thermostat, those asking for the most warmth keep
+ * it fully open and show what the curve does. Every other one is held back by
+ * its thermostat, reads the thermostat rather than the curve, and would mislead
+ * the controller. A room with no thermostat follows the curve, and one with a
+ * self-regulating thermostat holds its own target — both are always judged.
+ *
+ * @param roomIds - The rooms of the circuit.
+ * @param traitsOf - A room's warmth and thermostat.
+ * @returns The judged room IDs, in the order given.
+ */
+export declare function curveJudgedRoomIds(roomIds: readonly string[], traitsOf: (roomId: string) => CurveRoomTraits | undefined): string[];
+/**
+ * The rooms a heating circuit's curve optimisation is judged by, resolved
+ * against the rooms of the home ({@link EnergyAppRoom.getRooms} or
+ * {@link EnergyAppRoom.getRoomsById}). A room that no longer exists is
+ * dropped. Whether a judged room can be measured is up to
+ * {@link EnergyAppRoomTemperatures}.
+ *
+ * @param settings - The circuit's {@link EnyoHeatpumpApplianceHeatingCircuit.curveOptimization}.
+ * @param rooms - Every room of the home.
+ * @returns The judged rooms, in the order of `settings.roomIds`.
+ */
+export declare function curveOptimizationRooms(settings: EnyoHeatpumpHeatingCurveOptimizationSettings | undefined, rooms: readonly EnyoRoom[]): EnyoRoom[];