@enyo-energy/energy-app-sdk 1.43.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.
@@ -3751,7 +3784,7 @@ Shifts the heating curve of one heating circuit in parallel — **permanently**,
 - **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 host resolves them into `rooms`: per room its target temperature (set in the enyo app, `HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C` = 21 °C until then) and the temperature sensors assigned to it. 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.
+- **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) {
@@ -3807,7 +3840,7 @@ 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) |
-| — | `heatingCircuits[].curveOptimization` — the customer's choice for the room-temperature based curve optimisation: `enabled` (off by default), `roomIds` (the rooms the circuit heats) and, resolved by the host, `rooms` — per room `roomId`, `name`, its `targetRoomTemperatureC` (16–26 °C) and the `sensors` assigned to it. Customer-owned; integrations only read it |
+| — | `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 |

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/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[];

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

@@ -80,17 +80,13 @@ function checkProgramModes(zone, prefix, errors, warnings) {
         errors.push(`${prefix}: activeProgramMode "${zone.activeProgramMode}" is not a valid value`);
     }
 }
-/** Range the customer may choose for a room's `targetRoomTemperatureC`, in °C. */
-const CURVE_OPTIMIZATION_TARGET_RANGE_C = { min: 16, max: 26 };
 /**
  * Validates the heating-curve-offset fields of one heating circuit
  * (`heatingCurveOffsetRangeK`, `activeHeatingCurveOffsetK`,
  * `curveOptimization`) and appends the problems to `errors`.
  *
  * Errors: the range is not finite or does not contain `0`; the active offset
- * is not finite or lies outside the range; a room id is empty; a resolved room
- * lacks its `roomId`, a sensor lacks its `applianceId` / `sensorId`, or its
- * target lies outside 16…26 °C.
+ * is not finite or lies outside the range; a room id is empty.
  *
  * @param circuit - The heating circuit.
  * @param prefix - Path prefix for the messages, e.g. `heatingCircuits[index=0]`.
@@ -124,22 +120,6 @@ function checkHeatingCurveOffset(circuit, prefix, errors) {
             errors.push(`${prefix}: curveOptimization.roomIds[${i}] must be a non-empty string`);
         }
     });
-    (settings.rooms ?? []).forEach((room, i) => {
-        if (!room?.roomId) {
-            errors.push(`${prefix}: curveOptimization.rooms[${i}] needs a roomId`);
-        }
-        (room?.sensors ?? []).forEach((sensor, j) => {
-            if (!sensor?.applianceId || !sensor?.sensorId) {
-                errors.push(`${prefix}: curveOptimization.rooms[${i}].sensors[${j}] needs applianceId and sensorId`);
-            }
-        });
-        const target = room?.targetRoomTemperatureC;
-        if (!(isFiniteNumber(target)
-            && target >= CURVE_OPTIMIZATION_TARGET_RANGE_C.min && target <= CURVE_OPTIMIZATION_TARGET_RANGE_C.max)) {
-            errors.push(`${prefix}: curveOptimization.rooms[${i}].targetRoomTemperatureC must lie within ` +
-                `${CURVE_OPTIMIZATION_TARGET_RANGE_C.min}…${CURVE_OPTIMIZATION_TARGET_RANGE_C.max} °C; got ${target}`);
-        }
-    });
 }
 /**
  * Parses an `HH:mm` time of day into minutes since midnight.

package/dist/cjs/index.cjs

@@ -110,6 +110,7 @@ __exportStar(require("./implementations/heatpump/heatpump-control-validators.cjs
 __exportStar(require("./implementations/heatpump/heatpump-control-session.cjs"), exports);
 __exportStar(require("./implementations/heatpump/heatpump-flexibility-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);
 __exportStar(require("./types/enyo-onboarding.cjs"), exports);
 __exportStar(require("./packages/energy-app-onboarding.cjs"), exports);
@@ -193,6 +194,10 @@ __exportStar(require("./types/enyo-webhook.cjs"), exports);
 __exportStar(require("./packages/energy-app-webhook.cjs"), exports);
 __exportStar(require("./types/enyo-subscription.cjs"), exports);
 __exportStar(require("./packages/energy-app-subscriptions.cjs"), exports);
+__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("./implementations/subscriptions/define-subscription-plan.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/subscription-plan-validators.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/in-memory-subscriptions.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -94,6 +94,7 @@ 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-heating-curve-offset.cjs';
+export * from './implementations/heatpump/heatpump-curve-optimization-rooms.cjs';
 export * from './types/enyo-inverter-appliance.cjs';
 export * from './types/enyo-onboarding.cjs';
 export * from './packages/energy-app-onboarding.cjs';
@@ -177,6 +178,10 @@ export * from './types/enyo-webhook.cjs';
 export * from './packages/energy-app-webhook.cjs';
 export * from './types/enyo-subscription.cjs';
 export * from './packages/energy-app-subscriptions.cjs';
+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 './implementations/subscriptions/define-subscription-plan.cjs';
 export * from './implementations/subscriptions/subscription-plan-validators.cjs';
 export * from './implementations/subscriptions/in-memory-subscriptions.cjs';

package/dist/cjs/packages/energy-app-room-temperatures.cjs

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

package/dist/cjs/packages/energy-app-room-temperatures.d.cts

@@ -0,0 +1,51 @@
+import { EnyoRoomCurrentTemperatures, EnyoRoomTemperatureHistoryRequest, EnyoRoomTemperatureHistoryResponse } from "../types/enyo-room-temperature.cjs";
+/**
+ * Interface for reading the temperatures measured in the rooms of the home
+ * ({@link EnergyAppRoom}), current and past. A room can have several
+ * temperature sensors; each one is reported on its own.
+ *
+ * There is no listener: to follow a room's temperatures, read the current
+ * values once and then subscribe to the
+ * {@link EnyoDataBusMessageEnum.TemperatureSensorValuesUpdateV1} messages of
+ * the sensors they name ({@link EnyoRoomTemperatureSensorReading.applianceId},
+ * {@link EnyoRoomTemperatureSensorReading.sensorId}) on the data bus.
+ *
+ * Access to this API requires the `RoomTemperatures` permission
+ * ({@link EnergyAppPermissionType}).
+ *
+ * @example
+ * ```typescript
+ * const roomTemperatures = energyApp.useRoomTemperatures();
+ *
+ * // Current values of the rooms a heating circuit heats.
+ * const current = await roomTemperatures.getCurrentRoomTemperatures(['living', 'bath']);
+ *
+ * // The last 24 hours in 15-minute buckets.
+ * const history = await roomTemperatures.getRoomTemperatureHistory({
+ *     roomIds: ['living', 'bath'],
+ *     startDateIso: '2026-10-27T00:00:00Z',
+ *     endDateIso: '2026-10-28T00:00:00Z',
+ * });
+ * ```
+ */
+export interface EnergyAppRoomTemperatures {
+    /**
+     * Returns the latest reading of every temperature sensor in the given
+     * rooms. An ID without a room is left out.
+     *
+     * @param roomIds - IDs of the rooms ({@link EnyoRoom.id}) to read
+     * @returns Promise that resolves to one entry per room found, in the order of `roomIds`
+     * @throws {EnergyAppPermissionNotGrantedError} If the `RoomTemperatures` permission is not granted.
+     */
+    getCurrentRoomTemperatures(roomIds: string[]): Promise<EnyoRoomCurrentTemperatures[]>;
+    /**
+     * Returns the measured temperatures of the given rooms over a time
+     * interval, per sensor and bucket. The sensors are those in the room now:
+     * a sensor moved to another room brings its earlier readings along.
+     *
+     * @param request - The rooms, the interval and the bucket size
+     * @returns Promise that resolves to the history of every room found
+     * @throws {EnergyAppPermissionNotGrantedError} If the `RoomTemperatures` permission is not granted.
+     */
+    getRoomTemperatureHistory(request: EnyoRoomTemperatureHistoryRequest): Promise<EnyoRoomTemperatureHistoryResponse>;
+}

package/dist/cjs/packages/energy-app-room.cjs

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

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

@@ -0,0 +1,59 @@
+import { EnyoRoom, EnyoRoomsChangedListener } from "../types/enyo-room.cjs";
+/**
+ * Interface for reading the rooms of the home.
+ *
+ * Rooms are set up by the customer in the enyo app: a name, the appliances in
+ * it, the temperature the customer wants there and — for the heating curve
+ * optimisation — how warm it should be compared with the other rooms of its
+ * heating circuit and which thermostat it has. Apps only read them. The
+ * temperatures measured in a room come from {@link EnergyAppRoomTemperatures}.
+ *
+ * Access to this API requires the `Room` permission
+ * ({@link EnergyAppPermissionType}).
+ *
+ * @example
+ * ```typescript
+ * const rooms = energyApp.useRoom();
+ *
+ * // On boot: read the rooms.
+ * applyRooms(await rooms.getRooms());
+ *
+ * // Afterwards: react to the customer changing a room.
+ * rooms.listenForRoomsChanged((all) => applyRooms(all));
+ * ```
+ */
+export interface EnergyAppRoom {
+    /**
+     * Returns every room of the home.
+     *
+     * @returns Promise that resolves to the rooms, in no particular order
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Room` permission is not granted.
+     */
+    getRooms(): Promise<EnyoRoom[]>;
+    /**
+     * Returns the rooms with the given IDs, e.g. the
+     * {@link EnyoHeatpumpHeatingCurveOptimizationSettings.roomIds} of a
+     * heating circuit. An ID without a room — the customer removed it — is
+     * left out.
+     *
+     * @param roomIds - IDs of the rooms to return
+     * @returns Promise that resolves to the rooms found, in the order of `roomIds`
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Room` permission is not granted.
+     */
+    getRoomsById(roomIds: string[]): Promise<EnyoRoom[]>;
+    /**
+     * Registers a listener called with every room of the home whenever the
+     * customer creates, changes or removes one.
+     *
+     * @param listener - Callback invoked with all rooms after the change
+     * @returns A listener ID that can be passed to {@link removeListener}
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Room` permission is not granted.
+     */
+    listenForRoomsChanged(listener: EnyoRoomsChangedListener): string;
+    /**
+     * Removes a listener registered with {@link listenForRoomsChanged}.
+     *
+     * @param listenerId - The ID returned when the listener was registered
+     */
+    removeListener(listenerId: string): void;
+}

package/dist/cjs/types/enyo-heatpump-appliance.cjs

@@ -301,6 +301,7 @@ var EnyoHeatpumpHeatingControlReferenceEnum;
  */
 exports.HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K = 3;
 /**
- * The target temperature of a room whose customer has not set one, in °C.
+ * The target temperature of a room whose customer has not set one, in °C
+ * ({@link EnyoRoom.targetTemperatureC}).
  */
 exports.HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C = 21;

package/dist/cjs/types/enyo-heatpump-appliance.d.cts

@@ -442,36 +442,10 @@ export interface EnyoHeatpumpRoomTemperatureSensorReference {
  */
 export declare const HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K = 3;
 /**
- * The target temperature of a room whose customer has not set one, in °C.
+ * The target temperature of a room whose customer has not set one, in °C
+ * ({@link EnyoRoom.targetTemperatureC}).
  */
 export declare const HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C = 21;
-/**
- * One room a heating circuit heats, as the host resolves it for the heating
- * curve optimisation: the room's target temperature and the temperature
- * sensors assigned to that room. Read-only for apps — the host fills it from
- * {@link EnyoHeatpumpHeatingCurveOptimizationSettings.roomIds} and the rooms
- * the customer set up in the enyo app.
- */
-export interface EnyoHeatpumpCurveOptimizationRoom {
-    /** ID of the room in the enyo app. */
-    roomId: string;
-    /** The room's name, as the customer called it — for logs and diagnostics. */
-    name?: string;
-    /**
-     * The room temperature in °C the customer wants in this room — a setpoint
-     * of the energy manager's controller, **not** written to the heatpump.
-     * {@link HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C} until the customer
-     * sets one. Raising it means the customer is too cold there, and the
-     * energy manager reacts at once.
-     */
-    targetRoomTemperatureC: number;
-    /**
-     * The temperature sensors assigned to this room. Empty when the room has
-     * none: such a room is part of the circuit but cannot be judged, and the
-     * energy manager leaves it out. With several, the coldest counts.
-     */
-    sensors: EnyoHeatpumpRoomTemperatureSensorReference[];
-}
 /**
  * The range of {@link EnyoDataBusSetHeatpumpHeatingCurveOffsetV1.data}
  * `offsetK` a heating circuit accepts, in Kelvin of flow temperature relative
@@ -487,7 +461,7 @@ export interface EnyoHeatpumpHeatingCurveOffsetRange {
 /**
  * What the customer chose for the room-temperature based optimisation of one
  * heating circuit's heating curve: the energy manager lowers the curve as far
- * as possible without any of the {@link rooms} falling below its own target,
+ * as possible without any of the circuit's rooms falling below its own target,
  * using {@link EnyoDataBusSetHeatpumpHeatingCurveOffsetV1}.
  *
  * **Customer-owned.** Set in the enyo app, never by an integration: the host
@@ -503,18 +477,17 @@ export interface EnyoHeatpumpHeatingCurveOptimizationSettings {
      */
     enabled: boolean;
     /**
-     * IDs of the rooms (as set up in the enyo app) this circuit heats — chosen
-     * by the customer, whether or not a room has a temperature sensor.
+     * IDs of the rooms ({@link EnyoRoom.id}) this circuit heats — chosen by the
+     * customer, whether or not a room has a temperature sensor. Read the rooms
+     * with {@link EnergyAppRoom.getRoomsById}; {@link curveOptimizationRooms}
+     * picks the ones the curve is judged by, and
+     * {@link EnergyAppRoomTemperatures} gives their measured temperatures. The
+     * room furthest below its target decides how low the curve may go; rooms
+     * without a sensor are left out, and without any room that has one the
+     * optimisation cannot run. The
+     * curve is lowered by at most {@link HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K}.
      */
     roomIds?: string[];
-    /**
-     * Those rooms resolved by the host: each with its target and its sensors.
-     * The room furthest below its target decides how low the curve may go;
-     * rooms without a sensor are left out. Without any room that has a sensor
-     * the optimisation cannot run. The curve is lowered by at most
-     * {@link HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K}. Read-only for apps.
-     */
-    rooms?: EnyoHeatpumpCurveOptimizationRoom[];
 }
 /**
  * A domestic-hot-water zone of the installation.

package/dist/cjs/types/enyo-room-temperature.cjs

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