@enyo-energy/energy-app-sdk 1.43.0 → 1.45.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
 
@@ -1253,6 +1255,33 @@ settings.listenForSettingsChanges((settingName, newValue) => {
 const allSettings = await settings.getSettingsConfig();
 ```
 
+##### Action settings (buttons)
+
+A setting of type `'action'` renders as a button for a one-off command (restart a device, start a self-test, …). Every tap writes the current time as an ISO 8601 string to the setting, so each tap arrives as a change event — react to the event, not to the stored value.
+
+Use an action only for something that *happens*. Anything that has a state the user turns on or off (e.g. "charging cable locked") is a `checkbox`, not an action.
+
+```typescript
+await settings.addSettingConfig({
+    name: `restart-${applianceId}`,
+    applianceId,
+    type: 'action',
+    required: false,
+    fieldName: [{ language: 'en', value: 'Restart wallbox' }, { language: 'de', value: 'Wallbox neu starten' }],
+    actionOptions: {
+        buttonCaption: [{ language: 'en', value: 'Restart now' }, { language: 'de', value: 'Jetzt neu starten' }],
+        // optional: ask before triggering
+        confirmationText: [{ language: 'en', value: 'Restart the wallbox?' }, { language: 'de', value: 'Wallbox neu starten?' }],
+    },
+});
+
+settings.listenForSettingsChanges((event) => {
+    if (event.settingName === `restart-${applianceId}`) {
+        void restartWallbox();
+    }
+});
+```
+
 #### `useConfigurationManager(): EnergyAppConfigurationManager`
 
 Register **internal**, non user-facing configurations for your package and react to value changes. Unlike `useSettings()`, configurations registered here are NOT rendered in the Energy App UI — they are intended for values the package itself reads and writes at runtime (e.g. internal feature toggles, tuning parameters, calibration values) and need to be persisted across restarts.
@@ -1768,6 +1797,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.
@@ -3147,7 +3207,9 @@ const packageDef = defineEnergyAppPackage({
 | `pricingModel` | `per-package` (default): one price for the package on the device. `per-unit`: the price is charged per unit — see [Per-unit plans](#per-unit-plans). |
 | `prices` | One net price per currency. `amountWithoutTax` is always the **total for one interval** — per month, per year, or the single one-time amount; per unit for `per-unit` plans — in the currency (not cent), at most two decimals; enyo adds VAT. |
 | `trialDays` | Optional free trial in days. Not allowed for `one-time` plans. |
-| `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. |
+| `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. Prefer `includedFeatures` over `benefits`. |
+| `includedFeatures` | Optional feature keys from `subscriptionFeatures`, or `{ featureKey, value }` with a translated value — see [Offer screen](#offer-screen). |
+| `highlight` | Optional badge: `recommended`, `best-value` or `most-popular`. At most one plan per package. |
 | `internalComment` | Optional note, never shown to users. |
 
 What a plan unlocks is decided by the app: check `isPlanActive(subscriptions, planKey)` at runtime (see
@@ -3176,6 +3238,97 @@ In tests, `InMemorySubscriptions` takes the mode as its third constructor argume
 throws when an `optional` package reports `SubscriptionRequired`. The same check is available as
 `assertEnergyAppStateMatchesSubscriptionMode(mode, state)`.
 
+### Offer screen
+
+Promote the plans on the screen where enyo sells them: declare a **feature catalog** once, say which features the
+**free tier** and each plan include, and build the screen from **blocks**. All three are optional. Without an offer
+screen, enyo shows only the plan cards.
+
+```typescript
+import {
+    defineSubscriptionFeature,
+    defineSubscriptionOfferScreen,
+    EnyoSubscriptionOfferHintKindEnum,
+    EnyoSubscriptionOfferIconEnum,
+    EnyoSubscriptionPlanHighlightEnum
+} from '@enyo-energy/energy-app-sdk';
+
+defineEnergyAppPackage({
+    // ...
+    subscriptionMode: EnyoSubscriptionModeEnum.Optional,
+    subscriptionFeatures: [
+        defineSubscriptionFeature({
+            featureKey: 'pv-charging',
+            icon: EnyoSubscriptionOfferIconEnum.Sun,
+            storeEntry: [
+                { language: 'en', title: 'PV surplus charging' },
+                { language: 'de', title: 'PV-Überschussladen' }
+            ]
+        }),
+        defineSubscriptionFeature({
+            featureKey: 'price-optimisation',
+            icon: EnyoSubscriptionOfferIconEnum.PiggyBank,
+            storeEntry: [
+                { language: 'en', title: 'Dynamic price optimisation', description: 'Charges when electricity is cheapest.' },
+                { language: 'de', title: 'Optimierung nach dynamischen Preisen', description: 'Lädt, wenn Strom am günstigsten ist.' }
+            ]
+        }),
+        defineSubscriptionFeature({
+            featureKey: 'vehicles',
+            icon: EnyoSubscriptionOfferIconEnum.Car,
+            storeEntry: [{ language: 'en', title: 'Connected vehicles' }, { language: 'de', title: 'Verbundene Fahrzeuge' }]
+        })
+    ],
+    subscriptionFreeTier: {
+        storeEntry: [{ language: 'en', title: 'Basic' }, { language: 'de', title: 'Basis' }],
+        includedFeatures: ['pv-charging']
+    },
+    subscriptionPlans: [
+        defineSubscriptionPlan({
+            planKey: 'premium',
+            highlight: EnyoSubscriptionPlanHighlightEnum.Recommended,
+            includedFeatures: [
+                'pv-charging',
+                'price-optimisation',
+                { featureKey: 'vehicles', value: [{ language: 'en', value: 'up to 5' }, { language: 'de', value: 'bis zu 5' }] }
+            ],
+            // paymentInterval, prices, storeEntry ...
+        })
+    ],
+    subscriptionOfferScreen: defineSubscriptionOfferScreen({
+        blocks: [
+            { type: 'hero', icon: 'piggy-bank', storeEntry: [
+                { language: 'en', title: 'Charge for less', text: 'Smart charging with dynamic prices.' },
+                { language: 'de', title: 'Günstiger laden', text: 'Intelligentes Laden mit dynamischen Preisen.' }
+            ] },
+            { type: 'comparison' },                     // Basic vs. Premium, one row per feature
+            { type: 'hint', kind: EnyoSubscriptionOfferHintKindEnum.PricingReason, icon: 'handshake', storeEntry: [
+                { language: 'en', title: 'Why does this cost money?', text: 'The car vendors charge us for every connected vehicle.' },
+                { language: 'de', title: 'Warum kostet das Geld?', text: 'Die Fahrzeughersteller berechnen uns jedes verbundene Fahrzeug.' }
+            ] },
+            { type: 'plans' }
+        ]
+    })
+});
+```
+
+| Block | Shows | Notes |
+|---|---|---|
+| `hero` | A large headline with optional text and icon | `title` is required. |
+| `features` | Features with icon and description | `featureKeys` picks and orders them; omit it to list all. |
+| `comparison` | A table: one row per feature, one column per tier | The free column is shown when a free tier is declared (`includeFreeTier` overrides this). `planKeys` and `featureKeys` pick the columns and rows. A cell shows a check mark, the feature's `value`, or nothing. Needs at least two columns. |
+| `hint` | A highlighted note | `kind`: `pricing-reason` (why it costs money), `requirement`, `info`, `legal`. `text` is required. |
+| `plans` | The plan cards and checkout | At most one. Without it, the plans follow the last block. |
+
+- **Icons** come from a fixed set, `EnyoSubscriptionOfferIconEnum` (`piggy-bank`, `sun`, `car`, `wallbox`, `heat-pump`,
+  `handshake`, …), so every app's offer screen looks the same.
+- **A plan's `includedFeatures` should list everything the customer gets with it**, including the free tier's
+  features. The comparison table takes each column straight from the tier's list.
+- **`subscriptionFreeTier` is only allowed with `subscriptionMode: 'optional'`**.
+- Every text needs `de` and `en`. `validatePackageSubscriptionPlans()` checks all of this as well (it calls
+  `validatePackageSubscriptionOffer()`). It also warns about features that no tier includes and comparison rows
+  that stay empty.
+
 ### Per-unit plans
 
 For a `per-unit` plan the price is charged once per unit — 3 units on a yearly plan for 10 € cost 30 € per year
@@ -3751,7 +3904,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 +3960,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 |
@@ -3840,6 +3993,26 @@ await applianceManager.updateHeatpumpDomesticHotWater(applianceId, 0, { timeProg
 
 Validate before publishing with `validateHeatpumpHeatingCurve`, `validateHeatpumpTimeProgram` or `validateHeatpumpAdvancedMetadata` (or their `assertValid*` counterparts). Each returns `{ ok, errors, warnings }`.
 
+**SG Ready relays.** You can declare 0–n SG Ready inputs in `metadata.heatpump.sgReadyRelays`. Each one has a
+`function` that says what it acts on: `heating` (a heating circuit), `dhw-heatpump` (DHW heated by the compressor)
+or `dhw-heating-rod` (DHW heated by the heating rod). `zoneIndex` names the heating circuit or DHW zone; omit it for
+the first one. If only some of the four states (`blocked`, `normal`, `recommended`, `forced`) are wired, list them
+in `supportedStates`. `activeState` reports the current state. This works independently of `connectionType`.
+
+```typescript
+sgReadyRelays: [
+    { index: 0, function: EnyoHeatpumpSgReadyFunctionEnum.Heating, zoneIndex: 0, name: 'K1/K2' },
+    { index: 1, function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatpump, name: 'K3/K4' },
+    { index: 2, function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatingRod,
+      supportedStates: [EnyoHeatpumpSgReadyStateEnum.Normal, EnyoHeatpumpSgReadyStateEnum.Forced] },
+]
+```
+
+`validateHeatpumpAdvancedMetadata` checks the relays too. It rejects duplicate indexes, unknown functions or
+states, and an `activeState` that is not in `supportedStates`. It warns about unknown zones, two relays with the
+same function on one zone, a relay without `normal`, and a `dhw-heating-rod` relay when `additionalDevices` has
+no `HeatingRod`.
+
 ### WallboxIntegrationEnergyApp
 
 Drives an EV wallbox / charger. Has the richest command surface of all integrations.

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

@@ -4,6 +4,7 @@ import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
 import type { EnyoOnboardingV2Guide } from "./types/enyo-onboarding-v2.cjs";
 import type { EnyoOnboardingTranslatedContent } from "./types/enyo-onboarding.cjs";
 import type { EnyoSubscriptionMode, EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
+import type { EnyoSubscriptionFeature, EnyoSubscriptionFreeTier, EnyoSubscriptionIncludedFeature, EnyoSubscriptionOfferScreen, EnyoSubscriptionPlanHighlight } from "./types/enyo-subscription-offer.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -294,7 +295,13 @@ export interface EnergyAppPackageSubscriptionPlanStoreEntry {
     title: string;
     /** One sentence describing what the plan unlocks */
     shortDescription: string;
-    /** Optional list of benefits, shown as bullet points on the offer screen */
+    /**
+     * Optional list of benefits, shown as bullet points on the plan card.
+     *
+     * Prefer {@link EnergyAppPackageSubscriptionPlan.includedFeatures}: features
+     * carry icons and descriptions and feed the comparison table. The host
+     * shows `benefits` only for plans without `includedFeatures`.
+     */
     benefits?: string[];
 }
 /**
@@ -358,6 +365,21 @@ export interface EnergyAppPackageSubscriptionPlan {
     trialDays?: number;
     /** Localized store information. Entries for `de` and `en` are required. */
     storeEntry: EnergyAppPackageSubscriptionPlanStoreEntry[];
+    /**
+     * The features this plan includes, as keys of
+     * {@link EnergyAppPackageDefinition.subscriptionFeatures} — or with a
+     * translated value such as "up to 5 vehicles" — in display order. Shown on
+     * the plan card and in the comparison table.
+     *
+     * List every feature the customer gets with the plan, including those of
+     * the free tier, so the comparison table reads correctly.
+     */
+    includedFeatures?: EnyoSubscriptionIncludedFeature[];
+    /**
+     * Optional badge that makes this plan stand out on the offer screen, e.g.
+     * `recommended`. At most one plan of a package may be highlighted.
+     */
+    highlight?: EnyoSubscriptionPlanHighlight;
     /** Optional internal note explaining this plan; never shown to users. */
     internalComment?: string;
 }
@@ -1064,6 +1086,29 @@ export interface EnergyAppPackageDefinition {
      * Omit for packages that are free.
      */
     subscriptionPlans?: EnergyAppPackageSubscriptionPlan[];
+    /**
+     * The package's feature catalog: every feature that the plans and the free
+     * tier refer to, declared once with its icon and translations. enyo builds
+     * the feature lists and the comparison table of the offer screen from it.
+     *
+     * Only used together with {@link subscriptionPlans}. Validate it with
+     * `validatePackageSubscriptionPlans()`.
+     */
+    subscriptionFeatures?: EnyoSubscriptionFeature[];
+    /**
+     * What the app offers without a plan, shown as the free column of the
+     * comparison table. Only allowed with `subscriptionMode: 'optional'`.
+     */
+    subscriptionFreeTier?: EnyoSubscriptionFreeTier;
+    /**
+     * The blocks of the screen on which enyo offers the plans — a headline,
+     * feature lists, a comparison table, hints such as why the app costs
+     * money, and the plan cards — in display order.
+     *
+     * Omit to show only the plan cards. Validate it with
+     * `validatePackageSubscriptionPlans()`.
+     */
+    subscriptionOfferScreen?: EnyoSubscriptionOfferScreen;
     /**
      * Whether the app needs one of its plans to work at all.
      *

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