@enyo-energy/energy-app-sdk 1.26.0 → 1.27.0

package/README.md

@@ -191,6 +191,7 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Read EPEX SPOT wholesale prices (incl. negative-price windows) | [`useEpexSpotPrices()`](#useepexspotprices-energyappepexspotprice) |
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
 | Publish or resolve time-variable grid fees (§14a HT/NT) | [`useGridFee()`](#usegridfee-energyappgridfee) |
+| Price appliances behind a cascade meter (own tariff, prices and grid fee) | [`useCascade()`](#usecascade-energyappcascade) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
 | Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
@@ -1715,6 +1716,18 @@ const prices = await tariffs.getPrices(EnyoTariffDirectionEnum.Consumption, { fr
 const needsGridFee = !prices?.includes.includes(EnyoPriceComponentEnum.GridFee);
 ```
 
+To price one device, ask for the prices that actually bill it. This works for every appliance: the
+site's consumption prices, or — for an appliance behind an active [meter cascade](#usecascade-energyappcascade)
+— the cascade's, filled per 15-minute slot. The prices are effective prices (grid fee and taxes
+included, see `includes`), so never add a grid fee on top:
+
+```typescript
+const billed = await tariffs.getPricesForAppliance('heatpump-1', { fromIso, untilIso });
+// billed.billingMeter: 'primary' | 'cascade'
+// entry.fallback: cascade had no price for this slot, the site's was used
+// billed.inheritedFromSite: cascade has no tariff of its own yet
+```
+
 The app that integrates a provider owns the other side. It answers when the user picks it, sets the
 tariff once it is actually usable, and pushes prices as they arrive:
 
@@ -1785,6 +1798,115 @@ const fees = await gridFee.getGridFeeValues({ fromIso, untilIso });
 
 Publishers need `GridFeeRegister`; consumers need `GridFeeUse`.
 
+#### `useCascade(): EnergyAppCascade`
+
+A **meter cascade** (Kaskadenschaltung) is a second billing meter (Z2) installed *behind* the primary
+meter (Z1) — typically for a heatpump or wallbox on a dedicated tariff with a reduced (§14a EnWG) grid
+fee. Appliances behind an **active** Z2 are billed on the cascade's tariff and grid fee; everything else
+on `useElectricityTariff()` and `useGridFee()`. The site has at most one cascade, and Z2 has a
+**consumption tariff only** — all feed-in leaves through Z1.
+
+**Split rule.** PV and battery cover Z2 first; Z2 only pays the cascade tariff for what Z1 imports at the
+same moment. Z1 importing 2 kW, battery 1 kW, Z2 drawing 2 kW → Z2 grid share 1 kW, Z2 self-consumed
+1 kW, household grid share 1 kW.
+
+Topology — is there a cascade, is it working, who is behind it:
+
+```typescript
+const cascade = energyApp.useCascade();
+
+const details = await cascade.getCascade();   // active, status, estimated, meterApplianceId?, applianceIds
+if (details?.active && details.status !== EnyoCascadeStatusEnum.Live) {
+    // 'noCascadeSource' (nothing assigned yet) or 'noGridReading' (no Z1 reading)
+}
+cascade.onCascadeChanged(event => reassignPrices(event.cascade));
+```
+
+With `estimated: true`, Z2 is the sum of its appliances and has no meter (`meterApplianceId` absent).
+A physical Z2 meter carries the topology feature `CascadeSubMeter` — skip it when looking for the grid
+meter.
+
+Prices — to price a device, use `useElectricityTariff().getPricesForAppliance(applianceId, range)`. It
+works for every appliance and picks Z2 or Z1 itself, returning the **effective** price per 15-minute slot,
+grid fee and taxes included. `cascade.getPrices(range)` returns Z2's effective prices directly. Never add
+a grid fee on top:
+
+```typescript
+const prices = await energyApp.useElectricityTariff().getPricesForAppliance('heatpump-1', { fromIso, untilIso });
+// prices.billingMeter: 'cascade' | 'primary'
+// entry.fallback: Z2 had no price for that slot, the site's was used
+// prices.inheritedFromSite: Z2 has no tariff of its own yet
+```
+
+Until Z2 has its own tariff or grid fee, the hub prices it with the site's — and so do `getTariff`,
+`getPrices`, `getGridFee` and `getGridFeeValues`: they return the site's values with
+`inheritedFromSite: true` rather than `null`. The grid fee methods are informational (to show the fee
+separately).
+
+What Z2 is actually drawing and costing — live via the `CascadeSplitUpdateV1` data bus message
+(`householdGridW`, `cascadeGridW`, `cascadeSelfConsumedW`, `subMeterPowerW`, `status`, `estimated` — the
+same values the cockpit shows), and as history:
+
+```typescript
+energyApp.useDataBus().listenForMessages([EnyoDataBusMessageEnum.CascadeSplitUpdateV1], msg => {
+    const { cascadeGridW, status } = (msg as EnyoDataBusCascadeSplitUpdateV1).data;
+});
+
+const history = await cascade.getCascadeTimeseries({ fromIso, untilIso, resolution: '1d' });
+// resolution: '1m' (kept 31 days) | '15m' | '1d' | '1mo'
+// per bucket: householdGridKwh, cascadeGridKwh, cascadeSelfConsumedKwh,
+//             householdCostCt, cascadeCostCt, cascadePriceCt, estimated
+```
+
+History costs are in **ct**, priced when read with the tariffs then in force.
+
+**The core owns the cascade tariff by default** — the user enters it in the hub. The cascade **grid fee
+comes with the tariff**: it is provided by the core, or by the app that owns the cascade tariff, and goes
+away with that app's ownership. An app that provides a
+**dynamic** tariff can offer itself for Z2 and take it over once the user selects it, then publish its
+prices:
+
+```typescript
+// Registering the handler is what lists this app in the hub's cascade tariff selection.
+cascade.onTariffSelected(async () => {
+    if (!await isAuthenticated()) {
+        return {
+            status: EnyoTariffActivationStatusEnum.AuthenticationRequired,
+            authenticationUrl: buildOAuthUrl('cascade'),
+        };
+    }
+    await cascade.setTariff({                                 // takes over the slot from the core
+        name: 'Tibber Wärmepumpe',
+        vendorName: 'Tibber',
+        currency: EnyoCurrencyEnum.EUR,
+        pricing: { type: EnyoTariffPricingTypeEnum.Dynamic }, // only dynamic tariffs can be app-provided
+        externalTariffId: contract.id,
+    });
+    return { status: EnyoTariffActivationStatusEnum.Success };
+});
+
+await cascade.publishPrices({ includes: [], entries });      // only while this app owns Z2's tariff
+await cascade.registerGridFee(reducedGridFee);              // optional: the Z2 grid fee comes with the tariff
+
+cascade.onTariffChanged(event => {
+    if (event.tariff?.externalTariffId !== contract.id) stopPublishing(); // lost ownership
+});
+```
+
+| Group | Methods | Permission |
+|---|---|---|
+| Topology | `isActive`, `getCascade`, `getApplianceIds`, `isApplianceBehindCascade`, `onCascadeChanged` | none |
+| Prices & tariff (read) | `getTariff`, `getPrices`, `onTariffChanged` | none |
+| History | `getCascadeTimeseries` | `Timeseries` |
+| Grid fee | `getGridFee`, `getGridFeeValues`, `onGridFeeChanged` / `registerGridFee`, `removeGridFee` (cascade tariff owner only) | `GridFeeUse` / `GridFeeRegister` |
+| Dynamic tariff provider | `onTariffSelected`, `setTariff`, `publishPrices` | `ElectricityTariff` |
+| Data bus | `CascadeSplitUpdateV1`, `AggregatedStateUpdateV1.data.cascade` | `SubscribeDataBus` |
+
+Without a cascade, topology getters resolve to `null` / `false` / `[]`, cascade price and grid fee
+getters to `null`, and writes reject; `useElectricityTariff().getPricesForAppliance` returns the site's
+prices. Z1 also counts
+everything that passes Z2, so never add the two meter readings together.
+
 #### `useWeatherForecasting(): EnergyAppWeatherForecasting`
 
 Register a weather-forecast provider (e.g. wraps an external API) and / or consume forecasts by zip code or coordinates.
@@ -2971,11 +3093,48 @@ class MyHeatpumpApp extends HeatpumpIntegrationEnergyApp {
 
 Drives a heatpump. Manages building / DHW overheating commands and grid-power-availability announcements.
 
-- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `GridOperatorPowerLimitationV1` (broadcast)
-- **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleGridOperatorPowerLimitation`
+- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `SetHeatpumpAvailablePowerV2`, `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+- **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
+- **Optional override:** `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
 - **Publish helpers:**
   - `publishHeatpumpValuesUpdate(applianceId, values)` — operation mode, electrical and thermal power, energies.
-  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow, return, DHW tanks, heating circuits, buffer tank.
+  - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank.
+
+#### Advanced heatpump metadata
+
+Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata`) can carry what the device is configured to do. Declare each part with its feature flag in `availableFeatures` so consumers know to expect it:
+
+| Feature flag | Where the data lives |
+|---|---|
+| `HeatingCurve` | `heatingCircuits[].heatingCurve` — outdoor → flow temperature `points` (vendor-neutral, linearly interpolated), plus raw `slope` / `parallelShiftK`, min / max flow and an optional cooling curve |
+| `TimeProgram` | `heatingCircuits[].timeProgram` and `domesticHotWater[].timeProgram` — weekly periods (`daysOfWeek` 0 = Sunday, local `HH:mm` times, may wrap past midnight) switching between `Comfort` / `Reduced` / `Off` / `Boost` |
+| `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` |
+| `FlowTemperature` / `ReturnTemperature` | `heatpumpFlowTemperatureC`, `heatpumpTargetFlowTemperatureC`, `heatpumpReturnTemperatureC` and per-circuit `flowTemperatureC`, `targetFlowTemperatureC`, `returnTemperatureC` in `HeatpumpTemperaturesUpdateV1` |
+
+`updateAppliance` replaces the whole `heatingCircuits` / `domesticHotWater` array, so use the `ApplianceManager` helpers to change a single entry:
+
+```typescript
+await applianceManager.updateHeatpumpHeatingCircuit(applianceId, 0, {
+    heatingCurve: {
+        points: [
+            { outdoorTemperatureC: -15, flowTemperatureC: 48 },
+            { outdoorTemperatureC: 0, flowTemperatureC: 38 },
+            { outdoorTemperatureC: 15, flowTemperatureC: 27 },
+        ],
+        slope: 0.8,
+        parallelShiftK: 0,
+    },
+    timeProgram: {
+        defaultLevel: EnyoHeatpumpTimeProgramLevelEnum.Reduced,
+        levelTemperaturesC: { Comfort: 21, Reduced: 18 },
+        periods: [{ daysOfWeek: [1, 2, 3, 4, 5], startTimeOfDay: '06:00', endTimeOfDay: '22:00', level: EnyoHeatpumpTimeProgramLevelEnum.Comfort }],
+    },
+});
+await applianceManager.updateHeatpumpDomesticHotWater(applianceId, 0, { timeProgram: dhwProgram });
+```
+
+Validate before publishing with `validateHeatpumpHeatingCurve`, `validateHeatpumpTimeProgram` or `validateHeatpumpAdvancedMetadata` (or their `assertValid*` counterparts). Each returns `{ ok, errors, warnings }`.
 
 ### WallboxIntegrationEnergyApp
 

package/dist/cjs/energy-app-model-feature.enum.cjs

@@ -41,6 +41,8 @@ var EnergyAppModelFeatureEnum;
     EnergyAppModelFeatureEnum["HeatpumpPowerModulation"] = "heatpump-power-modulation";
     /** The model supports the SG Ready interface for smart-grid signalling */
     EnergyAppModelFeatureEnum["HeatpumpSgReady"] = "heatpump-sg-ready";
+    /** The heat pump accepts measured room temperatures from an external sensor as control input */
+    EnergyAppModelFeatureEnum["HeatpumpRoomTemperatureInput"] = "heatpump-room-temperature-input";
     // Climate Control / Air Conditioning
     /** The target temperature setpoint can be controlled */
     EnergyAppModelFeatureEnum["ClimateTemperatureSetpoint"] = "climate-temperature-setpoint";

package/dist/cjs/energy-app-model-feature.enum.d.cts

@@ -33,6 +33,8 @@ export declare enum EnergyAppModelFeatureEnum {
     HeatpumpPowerModulation = "heatpump-power-modulation",
     /** The model supports the SG Ready interface for smart-grid signalling */
     HeatpumpSgReady = "heatpump-sg-ready",
+    /** The heat pump accepts measured room temperatures from an external sensor as control input */
+    HeatpumpRoomTemperatureInput = "heatpump-room-temperature-input",
     /** The target temperature setpoint can be controlled */
     ClimateTemperatureSetpoint = "climate-temperature-setpoint",
     /** The operating mode (heat / cool / fan / off) can be controlled */

package/dist/cjs/energy-app.cjs

@@ -506,6 +506,23 @@ class EnergyApp {
     useCommandLog() {
         return this.energyAppSdk.useCommandLog();
     }
+    /**
+     * Gets the Cascade API for the site's meter cascade: a second meter behind
+     * the primary meter (e.g. for a heatpump on a dedicated tariff) with its
+     * own electricity tariff, prices and grid fee.
+     *
+     * Use it to find out whether a cascade is active and which appliances are
+     * behind it, and to read or supply the cascade's tariff, prices and grid
+     * fee — appliances behind an active cascade are billed on those instead of
+     * on {@link useElectricityTariff} and {@link useGridFee}.
+     * @returns The Cascade API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ElectricityTariff`,
+     *         `GridFeeRegister` or `GridFeeUse` permission required by the
+     *         called method is not granted.
+     */
+    useCascade() {
+        return this.energyAppSdk.useCascade();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -50,6 +50,7 @@ import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
+import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -426,6 +427,21 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useCommandLog(): EnergyAppCommandLog;
+    /**
+     * Gets the Cascade API for the site's meter cascade: a second meter behind
+     * the primary meter (e.g. for a heatpump on a dedicated tariff) with its
+     * own electricity tariff, prices and grid fee.
+     *
+     * Use it to find out whether a cascade is active and which appliances are
+     * behind it, and to read or supply the cascade's tariff, prices and grid
+     * fee — appliances behind an active cascade are billed on those instead of
+     * on {@link useElectricityTariff} and {@link useGridFee}.
+     * @returns The Cascade API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `ElectricityTariff`,
+     *         `GridFeeRegister` or `GridFeeUse` permission required by the
+     *         called method is not granted.
+     */
+    useCascade(): EnergyAppCascade;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -49,6 +49,7 @@ import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
 import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { EnergyAppCommandLog } from "./packages/energy-app-command-log.cjs";
+import { EnergyAppCascade } from "./packages/energy-app-cascade.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -181,4 +182,6 @@ export interface EnyoEnergyAppSdk {
     useGridFee: () => EnergyAppGridFee;
     /** Get the Command Log API for recording which register, configuration key or message this app wrote to an appliance, and reading those commands back */
     useCommandLog: () => EnergyAppCommandLog;
+    /** Get the Cascade API for the meter behind the primary meter: whether it is active, which appliances are behind it, and its own electricity tariff, prices and grid fee */
+    useCascade: () => EnergyAppCascade;
 }

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

@@ -531,6 +531,78 @@ class ApplianceManager {
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
     }
+    /**
+     * Patches a single heating circuit of a heatpump — e.g. to publish a changed
+     * heating curve or time program — without resending the whole
+     * `heatingCircuits` array.
+     *
+     * {@link updateAppliance} merges `heatpump` metadata only one level deep,
+     * so passing `heatingCircuits` there replaces every circuit. This helper
+     * reads the stored array, shallow-merges `patch` into the circuit with the
+     * given `index` (appending a new circuit when none exists), keeps the
+     * array sorted by index, and saves. Other circuits are left untouched.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit to patch
+     * @param patch The circuit fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async updateHeatpumpHeatingCircuit(applianceId, index, patch) {
+        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) {
+            circuits[position] = { ...circuits[position], ...patch, index };
+        }
+        else {
+            circuits.push({ ...patch, index });
+            circuits.sort((a, b) => a.index - b.index);
+        }
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { heatingCircuits: circuits } }), applianceId);
+        await this.primeCacheFromSdk(applianceId);
+    }
+    /**
+     * Patches a single domestic-hot-water zone of a heatpump — e.g. to publish
+     * a changed time program — without resending the whole `domesticHotWater`
+     * array. Works like {@link updateHeatpumpHeatingCircuit}.
+     *
+     * Appending a zone that does not exist yet requires `targetTemperatureC`
+     * in `patch`, because a DHW zone cannot be stored without it.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the DHW zone to patch
+     * @param patch The zone fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
+     */
+    async updateHeatpumpDomesticHotWater(applianceId, index, patch) {
+        this.throwIfDisposed();
+        const appliance = await this.energyApp.useAppliances().getById(applianceId);
+        if (!appliance)
+            return;
+        const zones = [...(appliance.heatpump?.domesticHotWater ?? [])];
+        const position = zones.findIndex(z => z.index === index);
+        if (position >= 0) {
+            zones[position] = { ...zones[position], ...patch, index };
+        }
+        else {
+            const { targetTemperatureC } = patch;
+            if (targetTemperatureC === undefined) {
+                throw new Error(`Cannot add domestic hot water zone ${index} to appliance ${applianceId} without targetTemperatureC`);
+            }
+            zones.push({ ...patch, index, targetTemperatureC });
+            zones.sort((a, b) => a.index - b.index);
+        }
+        await this.energyApp.useAppliances().save(this.mergeApplianceData(appliance, { heatpump: { domesticHotWater: zones } }), 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, 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 { EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
+import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, 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";
@@ -329,6 +329,42 @@ export declare class ApplianceManager {
      * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
      */
     updateAppliance(applianceId: string, attributes: Partial<PartialEnyoAppliance>): Promise<void>;
+    /**
+     * Patches a single heating circuit of a heatpump — e.g. to publish a changed
+     * heating curve or time program — without resending the whole
+     * `heatingCircuits` array.
+     *
+     * {@link updateAppliance} merges `heatpump` metadata only one level deep,
+     * so passing `heatingCircuits` there replaces every circuit. This helper
+     * reads the stored array, shallow-merges `patch` into the circuit with the
+     * given `index` (appending a new circuit when none exists), keeps the
+     * array sorted by index, and saves. Other circuits are left untouched.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the heating circuit to patch
+     * @param patch The circuit fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    updateHeatpumpHeatingCircuit(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceHeatingCircuit, 'index'>>): Promise<void>;
+    /**
+     * Patches a single domestic-hot-water zone of a heatpump — e.g. to publish
+     * a changed time program — without resending the whole `domesticHotWater`
+     * array. Works like {@link updateHeatpumpHeatingCircuit}.
+     *
+     * Appending a zone that does not exist yet requires `targetTemperatureC`
+     * in `patch`, because a DHW zone cannot be stored without it.
+     *
+     * Does nothing when the appliance does not exist.
+     *
+     * @param applianceId The ID of the heatpump appliance
+     * @param index The `index` of the DHW zone to patch
+     * @param patch The zone fields to set; fields not given keep their stored value
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     * @throws {Error} when the zone does not exist and `patch` lacks `targetTemperatureC`
+     */
+    updateHeatpumpDomesticHotWater(applianceId: string, index: number, patch: Partial<Omit<EnyoHeatpumpApplianceDomesticHotWater, 'index'>>): 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