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

package/README.md

@@ -1646,10 +1646,14 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `BatteryEvDischargeMode` | `fixed-wh` \| `soc-limit` \| `intelligent` \| `block-discharge` \| `unmanaged` |
 | `BatteryEvDischargeFixedWh` | number, **Wh** (only under `fixed-wh`) |
 | `BatteryEvDischargeSocLimitPercent` | number, **%** floor (only under `soc-limit`) |
+| `BatteryPvPriorityTargetSocPercent` | number \| `null`, **%** target the battery is charged to from PV before other surplus consumers (absent / `null` = disabled) |
+| `BatteryDischargeBlockAboveHomeConsumptionW` | number \| `null`, **W** home consumption above which the battery may not discharge (absent / `null` = disabled) |
 | `HeatpumpControl` | boolean |
 | `HeatingRodControl` | boolean |
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |
+| `HeatingRodBatteryDischargeSocLimitPercent` | number \| `null`, **%** floor the battery may feed the heating rod down to (absent / `null` = disabled) |
 | `ChargerControl` | boolean |
+| `GridOptimizedEvCharging` | boolean, off by default — cost-optimised charging on a static / time-of-use tariff avoids high grid load (by EPEX spot) |
 | `DefaultChargeMode` | `EnyoChargeModeEnum` |
 | `PriceLimitMode` | `ct-per-kwh` \| `cheapest-share` (absent = no ceiling) |
 | `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh; only under `ct-per-kwh`) |
@@ -1694,7 +1698,11 @@ Three things to get right:
 
 - **Absent is not `false`.** `undefined` means unsupported or never chosen; `false` means the user switched it off. Check `supported` first, then the value — collapsing the two steers hardware someone deliberately disabled.
 - **How the battery may feed a charging EV is one mode plus its parameter.** `BatteryEvDischargeMode` picks the strategy; `BatteryEvDischargeFixedWh` and `BatteryEvDischargeSocLimitPercent` are read only under their own mode. `block-discharge` (actively hold the battery back) and `unmanaged` (do not intervene either way) are **not** synonyms.
-- **Ten settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
+- **Battery-first PV surplus is a charging target, not a floor.** `BatteryPvPriorityTargetSocPercent` (`40` = charge the battery to 40 % first) only holds back consumers that run *on surplus* — an EV on PV, a `pv-surplus-only` heating rod, heat pump surplus boosts, surplus automations. Grid-backed modes and explicit user requests are unaffected. It is independent of `BatteryEvDischargeSocLimitPercent`, which is a floor for discharging into the car. Disabled while absent or `null`; write `null` to switch it off again.
+- **The heating rod may draw from the battery only down to a floor, and only when asked.** `HeatingRodBatteryDischargeSocLimitPercent` (`80` = the rod may use the battery while it holds more than 80 %) is disabled while absent or `null`. It applies under both heating rod modes — under `pv-surplus-only` the battery above the floor counts as supply alongside PV, still never a grid import. It needs `batteryControl` to be enforced, and should not lie below `BatteryPvPriorityTargetSocPercent`; the validator warns on both. A consumer held back by it carries the command reason `BatteryPvPriority` (category `PvSurplus`) with `context.batteryPvPriority.targetSocPercent` and `socPercent`.
+- **The battery can be blocked from discharging under a heavy load.** `BatteryDischargeBlockAboveHomeConsumptionW` (`11000` = no discharge while the house draws more than 11 kW) keeps a sauna or an oven from emptying the battery in minutes. It is in **watts** — the validator warns below 100 W, which catches a kW value. Home consumption means the household plus every appliance the energy manager does **not** track — the same quantity as `homeConsumptionW` in the home consumption timeseries. Tracked appliances (wallbox, heat pump, heating rod, …) and the battery's own charging are excluded, so a charging car alone never trips the block. The block wins over the EV and heating rod discharge permissions; charging is unaffected. Disabled while absent or `null`. A battery held by it carries `HomeConsumptionHigh` with `context.batteryDischargeBlock.thresholdW` and `powerW` set to the current consumption.
+- **Grid-optimised EV charging is about the grid, not the bill.** `GridOptimizedEvCharging` adds no charge mode. It only affects `cost-optimized` sessions while the tariff is static or time-of-use (no effect under a dynamic one): the grid energy PV does not cover is placed in the hours with the lowest EPEX spot price before the deadline — the spot price as a proxy for grid load — instead of as late as possible or in the tariff's cheap windows. PV still comes first, the deadline still holds, and a session's price ceiling still applies against the customer's own tariff. On a time-of-use tariff a low-load hour can be a more expensive one; that is the trade the owner opts into.
+- **Fifteen settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
 - **`priceLimitCtPerKwh` is in cents**, unlike the SDK's machine-readable price fields (`electricityPricePerKwh`, EUR/kWh). Divide by 100 when comparing. `validateEnergyManagerSettingsState()` warns on values outside a plausible ct band, which catches the mix-up.
 - **A price ceiling is one mode plus its parameter**, the same shape as the battery-to-EV one. `PriceLimitMode` picks how the ceiling is expressed — an absolute `ct-per-kwh` or a relative `cheapest-share` — and each value is read only under its own mode; the mode being absent means no ceiling at all. A relative ceiling ranks the price intervals *known* for the day and treats the cheapest `n` % as importable (the same rule as the `cheapest-share-of-day` automation trigger), so its effective threshold moves when tomorrow's prices publish — re-evaluate it rather than resolving it once.
 
@@ -1759,8 +1767,17 @@ An entry may carry an optional `gridFeeGrossPerKwh`: the gross grid fee **contai
 `pricePerKwh`, in currency units per kWh. It is a breakdown only — `pricePerKwh` is always the
 total, so never compute `pricePerKwh + gridFeeGrossPerKwh`.
 
+It may also carry an optional `spotPricePerKwh`: the net wholesale (e.g. EPEX day-ahead) price the
+interval's price is based on, as the provider reports it — in currency units per kWh, possibly negative.
+Informational too: never add it to `pricePerKwh`.
+
 ```typescript
-entries.push({ timestampIso: '2026-05-23T10:00:00Z', pricePerKwh: 0.31, gridFeeGrossPerKwh: 0.09 });
+entries.push({
+    timestampIso: '2026-05-23T10:00:00Z',
+    pricePerKwh: 0.31,
+    gridFeeGrossPerKwh: 0.09,
+    spotPricePerKwh: 0.084,
+});
 ```
 
 **Calling `setTariff` is the activation signal.** Return `AuthenticationRequired` or
@@ -4171,10 +4188,18 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 **Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history.
 
+**Battery first on PV surplus.** When a surplus consumer (EV on PV, heating rod, heat pump boost, surplus automation) is held back or reduced because the battery is charged first up to the owner's `batteryPvPriorityTargetSocPercent`, the energy manager states `BatteryPvPriority` (category `PvSurplus`) on that consumer: `context.batteryPvPriority.targetSocPercent` for the target, `socPercent` for the pack's current SoC and `powerW` for the surplus the battery is taking — e.g. "The battery charges to 40 % first (now 28 %)."
+
+**Grid-optimised charging.** A cost-optimised session placed in, or waiting for, a low-load hour because of `gridOptimizedEvCharging` carries `GridLoadOptimized` (category `Schedule`) with `context.placement` (chosen window and deadline) and `context.gridLoad` (`epexPricePerKwh`, `currency`). The EPEX price is a grid-load proxy, not what the customer pays, so the text must not promise a saving — e.g. "Charging from 02:00, when the grid is less busy — ready by 07:00."
+
+**Battery vs. heating rod.** When the owner set `heatingRodBatteryDischargeSocLimitPercent`, two reason types (category `BatteryState`) say whether the battery feeds the rod: `BatterySupportsHeatingRod` while it may (with `powerW` for its contribution), `BatteryReservedFromHeatingRod` once it reaches the floor. Both carry `context.batteryToHeatingRod.socLimitPercent` and `socPercent` — e.g. "Heating rod no longer runs from the battery — it is at your 80 % limit."
+
 **Short-cycling protection.** When an appliance is kept running (or kept off) to honour its minimum on/off time, state `DeviceProtection` with `context.switching` (`EnyoDataBusCommandReasonSwitchingContext`): `hold` (`EnyoSwitchingProtectionHoldEnum.KeptOn` / `KeptOff`), `minOnSeconds`, `minOffSeconds` and `untilIso`. The text can then say "Kept running for another 4 minutes to protect the compressor" instead of a generic "Protecting the device".
 
 A hold that keeps an appliance **off** after a stop has its own type, `RestartDelay` (category `DeviceProtection`): set `context.switching` with `hold: KeptOff`, `minOffSeconds` and `untilIso` (when it may restart), and `powerW` to the power waiting for it — e.g. "Short pause after switching off — charging resumes at 13:15 so the car isn't switched on and off too often."
 
+**Fluctuating PV surplus.** When the surplus jumps around (clouds passing) and the energy manager holds an appliance's power steady instead of following every dip, state `PvSurplusFluctuating` (category `PvSurplus`) with `powerW` set to the power being held — e.g. "Charging power held steady while clouds pass." / "Ladeleistung wird gehalten, solange Wolken durchziehen." It is a smoothing decision, told apart from `PvSurplusAvailable` / `PvSurplusUnavailable`.
+
 ## Dynamic Grid Fees & Tariff Bonuses
 
 An electricity price is rarely one number. It is the energy price, plus the grid operator's network

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.cjs

@@ -67,6 +67,15 @@ const PRICE_LIMIT_MAX_CT = 200;
  * warned about for duplicating mode `block-discharge` rather than for being a unit slip.
  */
 const DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH = 100;
+/**
+ * Below this, a
+ * {@link EnergyManagerSettingValues.batteryDischargeBlockAboveHomeConsumptionW}
+ * threshold is almost certainly kW entered into a W field.
+ *
+ * `11` would block the battery above 11 W — that is, whenever the house draws
+ * anything — where 11 kW was plainly meant. `0` is caught by the same check.
+ */
+const HOME_CONSUMPTION_BLOCK_MIN_PLAUSIBLE_W = 100;
 /** Every {@link EnergyManagerBatteryEvDischargeModeEnum} value. */
 const EV_DISCHARGE_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerBatteryEvDischargeModeEnum));
 /** Value enums checked per field, for the enum-valued settings. */
@@ -139,6 +148,21 @@ function gateValue(values, setting) {
  *   duplicates mode `block-discharge`, the second catches a kWh value in a Wh field).
  * - `batteryEvDischargeSocLimitPercent` is a finite number in 0…100 (**error**),
  *   and not `100` (**warning** — a floor nothing can discharge past).
+ * - `batteryPvPriorityTargetSocPercent`, unless `null` (disabled), is a finite
+ *   number in 0…100 (**error**), and neither `0` (**warning** — no priority at
+ *   all, write `null`) nor `100` (**warning** — charging tapers near full, so
+ *   surplus consumers can be held back for hours).
+ * - `heatingRodBatteryDischargeSocLimitPercent`, unless `null` (disabled), is a
+ *   finite number in 0…100 (**error**), and not `100` (**warning** — a floor
+ *   nothing can discharge past). Set while `batteryControl` is not `true`
+ *   (**warning** — the floor cannot be enforced), or below
+ *   `batteryPvPriorityTargetSocPercent` (**warning** — the rod drains what the
+ *   PV priority refills).
+ * - `batteryDischargeBlockAboveHomeConsumptionW`, unless `null` (disabled), is
+ *   a finite non-negative number (**error**), and not below 100 W (**warning**
+ *   — catches a kW value in a W field; the battery would be blocked almost
+ *   always).
+ * - `null` counts as unset for the "stored" checks below.
  * - A parameter belonging to a mode other than the selected one is flagged by
  *   the gate check below, since {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}
  *   gates each on its own mode.
@@ -184,7 +208,7 @@ function validateEnergyManagerSettingsState(state) {
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
     for (const key of ['batteryControl', 'batteryChargeFromGrid', 'heatpumpControl',
-        'heatingRodControl', 'chargerControl']) {
+        'heatingRodControl', 'chargerControl', 'gridOptimizedEvCharging']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
         }
@@ -271,6 +295,67 @@ function validateEnergyManagerSettingsState(state) {
                 'states that intent directly.');
         }
     }
+    if (values.batteryPvPriorityTargetSocPercent !== undefined
+        && values.batteryPvPriorityTargetSocPercent !== null) {
+        const target = values.batteryPvPriorityTargetSocPercent;
+        if (typeof target !== 'number' || !Number.isFinite(target)) {
+            errors.push('`batteryPvPriorityTargetSocPercent` must be a finite number when set.');
+        }
+        else if (target < 0 || target > 100) {
+            errors.push(`\`batteryPvPriorityTargetSocPercent\` is ${target}; it is a percentage and must lie ` +
+                'between 0 and 100.');
+        }
+        else if (target === 0) {
+            warnings.push('`batteryPvPriorityTargetSocPercent` is 0, which gives the battery no priority at all — ' +
+                'write `null` to say that outright.');
+        }
+        else if (target === 100) {
+            warnings.push('`batteryPvPriorityTargetSocPercent` is 100. Charging tapers as the battery nears full, ' +
+                'so PV-surplus consumers may be held back for hours waiting for the last percent.');
+        }
+    }
+    if (values.batteryDischargeBlockAboveHomeConsumptionW !== undefined
+        && values.batteryDischargeBlockAboveHomeConsumptionW !== null) {
+        const threshold = values.batteryDischargeBlockAboveHomeConsumptionW;
+        if (typeof threshold !== 'number' || !Number.isFinite(threshold)) {
+            errors.push('`batteryDischargeBlockAboveHomeConsumptionW` must be a finite number or null when set.');
+        }
+        else if (threshold < 0) {
+            errors.push(`\`batteryDischargeBlockAboveHomeConsumptionW\` is ${threshold}; a consumption threshold ` +
+                'cannot be negative.');
+        }
+        else if (threshold < HOME_CONSUMPTION_BLOCK_MIN_PLAUSIBLE_W) {
+            warnings.push(`\`batteryDischargeBlockAboveHomeConsumptionW\` is ${threshold} W, so the battery would be ` +
+                'blocked almost always — this field is in watts, not kilowatts.');
+        }
+    }
+    if (values.heatingRodBatteryDischargeSocLimitPercent !== undefined
+        && values.heatingRodBatteryDischargeSocLimitPercent !== null) {
+        const floor = values.heatingRodBatteryDischargeSocLimitPercent;
+        if (typeof floor !== 'number' || !Number.isFinite(floor)) {
+            errors.push('`heatingRodBatteryDischargeSocLimitPercent` must be a finite number or null when set.');
+        }
+        else if (floor < 0 || floor > 100) {
+            errors.push(`\`heatingRodBatteryDischargeSocLimitPercent\` is ${floor}; it is a percentage and must lie ` +
+                'between 0 and 100.');
+        }
+        else {
+            if (floor === 100) {
+                warnings.push('`heatingRodBatteryDischargeSocLimitPercent` is 100, a floor the battery is already at, ' +
+                    'so the rod can never draw from it — write `null` to disable it outright.');
+            }
+            if (values.batteryControl !== true) {
+                warnings.push('`heatingRodBatteryDischargeSocLimitPercent` is set, but `batteryControl` is not true — ' +
+                    'the energy manager cannot hold the battery at the floor.');
+            }
+            const priority = values.batteryPvPriorityTargetSocPercent;
+            if (typeof priority === 'number' && Number.isFinite(priority) && floor < priority) {
+                warnings.push(`\`heatingRodBatteryDischargeSocLimitPercent\` (${floor} %) is below ` +
+                    `\`batteryPvPriorityTargetSocPercent\` (${priority} %) — the rod drains the battery ` +
+                    'into a range the PV priority then refills.');
+            }
+        }
+    }
     if (values.costOptimizedTargetTime !== undefined) {
         if (typeof values.costOptimizedTargetTime !== 'string'
             || !TIME_RE.test(values.costOptimizedTargetTime)) {
@@ -290,7 +375,7 @@ function validateEnergyManagerSettingsState(state) {
     // ── stored but unsupported ─────────────────────────────────────────────
     for (const setting of Object.values(enyo_energy_manager_settings_js_1.EnergyManagerSettingEnum)) {
         const keys = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[setting];
-        const held = keys.filter((key) => values[key] !== undefined);
+        const held = keys.filter((key) => values[key] !== undefined && values[key] !== null);
         if (held.length && !supported.has(setting)) {
             warnings.push(`"${setting}" holds a value (${held.join(', ')}) but is not in \`supported\` — ` +
                 'the energy manager will ignore it.');
@@ -301,7 +386,8 @@ function validateEnergyManagerSettingsState(state) {
         if (!dependency)
             continue;
         const key = setting;
-        const held = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[key].some((k) => values[k] !== undefined);
+        const held = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[key]
+            .some((k) => values[k] !== undefined && values[k] !== null);
         if (held && gateValue(values, dependency.requires) !== dependency.equals) {
             warnings.push(`"${key}" holds a value, but it only takes effect while "${dependency.requires}" ` +
                 `is ${JSON.stringify(dependency.equals)} — it currently cannot.`);

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.d.cts

@@ -65,6 +65,21 @@ export interface EnergyManagerSettingsValidationResult {
  *   duplicates mode `block-discharge`, the second catches a kWh value in a Wh field).
  * - `batteryEvDischargeSocLimitPercent` is a finite number in 0…100 (**error**),
  *   and not `100` (**warning** — a floor nothing can discharge past).
+ * - `batteryPvPriorityTargetSocPercent`, unless `null` (disabled), is a finite
+ *   number in 0…100 (**error**), and neither `0` (**warning** — no priority at
+ *   all, write `null`) nor `100` (**warning** — charging tapers near full, so
+ *   surplus consumers can be held back for hours).
+ * - `heatingRodBatteryDischargeSocLimitPercent`, unless `null` (disabled), is a
+ *   finite number in 0…100 (**error**), and not `100` (**warning** — a floor
+ *   nothing can discharge past). Set while `batteryControl` is not `true`
+ *   (**warning** — the floor cannot be enforced), or below
+ *   `batteryPvPriorityTargetSocPercent` (**warning** — the rod drains what the
+ *   PV priority refills).
+ * - `batteryDischargeBlockAboveHomeConsumptionW`, unless `null` (disabled), is
+ *   a finite non-negative number (**error**), and not below 100 W (**warning**
+ *   — catches a kW value in a W field; the battery would be blocked almost
+ *   always).
+ * - `null` counts as unset for the "stored" checks below.
  * - A parameter belonging to a mode other than the selected one is flagged by
  *   the gate check below, since {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}
  *   gates each on its own mode.

package/dist/cjs/types/enyo-data-bus-value.cjs

@@ -38,6 +38,19 @@ var EnyoDataBusCommandReasonTypeEnum;
      * saying "elsewhere".
      */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusFluctuating"] = "pv-surplus-fluctuating";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */
@@ -82,7 +95,19 @@ var EnyoDataBusCommandReasonTypeEnum;
      * {@link RestartDelay}.
      */
     EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
-    /** Command issued because home consumption is high */
+    /**
+     * Command issued because home consumption is high.
+     *
+     * When the energy manager holds the battery because home consumption — the
+     * household plus untracked appliances, tracked appliances excluded — is
+     * above the owner's `batteryDischargeBlockAboveHomeConsumptionW`, set
+     * {@link EnyoDataBusCommandReasonContext.batteryDischargeBlock} with the
+     * threshold, {@link EnyoDataBusCommandReason.powerW} to the current home
+     * consumption and category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState} — so the text
+     * can say "Battery paused: home consumption is 13.2 kW, above your 11 kW
+     * limit."
+     */
     EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
     /** Command issued to optimize self-consumption */
     EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
@@ -229,6 +254,70 @@ var EnyoDataBusCommandReasonTypeEnum;
      * the appliance from short-cycling and is not about price, sun or contention.
      */
     EnyoDataBusCommandReasonTypeEnum["RestartDelay"] = "restart-delay";
+    /**
+     * A PV-surplus consumer (EV on PV, heating rod, heat pump surplus boost,
+     * surplus automation) is held back or reduced because the house battery is
+     * charged first, up to the owner's `batteryPvPriorityTargetSocPercent`.
+     *
+     * Stated by the energy manager's surplus allocation on the consumer that
+     * lost out, never on the battery itself. Set
+     * {@link EnyoDataBusCommandReasonContext.batteryPvPriority} with the
+     * target, {@link EnyoDataBusCommandReason.socPercent} to the pack's current
+     * SoC, and {@link EnyoDataBusCommandReason.powerW} to the surplus the
+     * battery is taking — so the text can say "The battery charges to 40 %
+     * first (now 28 %)."
+     *
+     * Told apart from {@link PvSurplusAllocatedElsewhere}: the surplus did not
+     * go to another appliance by the planner's choice, it went to the battery
+     * because the owner asked for it. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} — it is about who
+     * got the sun.
+     */
+    EnyoDataBusCommandReasonTypeEnum["BatteryPvPriority"] = "battery-pv-priority";
+    /**
+     * The house battery is allowed to feed the heating rod, down to the
+     * owner's `heatingRodBatteryDischargeSocLimitPercent`.
+     *
+     * Set {@link EnyoDataBusCommandReasonContext.batteryToHeatingRod} with the
+     * floor, {@link EnyoDataBusCommandReason.socPercent} to the pack's current
+     * SoC and {@link EnyoDataBusCommandReason.powerW} to the power the battery
+     * contributes. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["BatterySupportsHeatingRod"] = "battery-supports-heating-rod";
+    /**
+     * The house battery is held back from the heating rod because it has
+     * reached the owner's floor (`heatingRodBatteryDischargeSocLimitPercent`).
+     * The rod runs on PV surplus only — or, under boost, from the grid.
+     *
+     * The counterpart of {@link BatterySupportsHeatingRod}. Set
+     * {@link EnyoDataBusCommandReasonContext.batteryToHeatingRod} and
+     * {@link EnyoDataBusCommandReason.socPercent}. Told apart from
+     * {@link BatterySoCLow}: the pack is not low, it is at the floor the owner
+     * chose for the rod. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["BatteryReservedFromHeatingRod"] = "battery-reserved-from-heating-rod";
+    /**
+     * A cost-optimised charging session was placed in — or is waiting for — a
+     * low-load hour on the grid, because the owner switched on
+     * `gridOptimizedEvCharging`. Covers both the "charging now" and the
+     * "waiting" side of the decision.
+     *
+     * About relieving the grid, not about the customer's price: on a static or
+     * time-of-use tariff the EPEX spot price that ranked the slot is not what
+     * the customer pays, so the text must not promise a saving — which is why
+     * this is its own type rather than
+     * {@link ElectricityPriceBelowThreshold} or {@link WaitingForCheaperSlot}.
+     *
+     * Set {@link EnyoDataBusCommandReasonContext.placement} with the chosen
+     * window and the session's deadline, and
+     * {@link EnyoDataBusCommandReasonContext.gridLoad} with the spot price
+     * behind it — so the text can say "Charging from 02:00, when the grid is
+     * less busy — ready by 07:00." Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["GridLoadOptimized"] = "grid-load-optimized";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -54,6 +54,19 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * saying "elsewhere".
      */
     PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    PvSurplusFluctuating = "pv-surplus-fluctuating",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
@@ -98,7 +111,19 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link RestartDelay}.
      */
     DeviceProtection = "device-protection",
-    /** Command issued because home consumption is high */
+    /**
+     * Command issued because home consumption is high.
+     *
+     * When the energy manager holds the battery because home consumption — the
+     * household plus untracked appliances, tracked appliances excluded — is
+     * above the owner's `batteryDischargeBlockAboveHomeConsumptionW`, set
+     * {@link EnyoDataBusCommandReasonContext.batteryDischargeBlock} with the
+     * threshold, {@link EnyoDataBusCommandReason.powerW} to the current home
+     * consumption and category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState} — so the text
+     * can say "Battery paused: home consumption is 13.2 kW, above your 11 kW
+     * limit."
+     */
     HomeConsumptionHigh = "home-consumption-high",
     /** Command issued to optimize self-consumption */
     SelfConsumptionOptimization = "self-consumption-optimization",
@@ -244,7 +269,71 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link EnyoDataBusCommandReasonCategoryEnum.DeviceProtection} — it protects
      * the appliance from short-cycling and is not about price, sun or contention.
      */
-    RestartDelay = "restart-delay"
+    RestartDelay = "restart-delay",
+    /**
+     * A PV-surplus consumer (EV on PV, heating rod, heat pump surplus boost,
+     * surplus automation) is held back or reduced because the house battery is
+     * charged first, up to the owner's `batteryPvPriorityTargetSocPercent`.
+     *
+     * Stated by the energy manager's surplus allocation on the consumer that
+     * lost out, never on the battery itself. Set
+     * {@link EnyoDataBusCommandReasonContext.batteryPvPriority} with the
+     * target, {@link EnyoDataBusCommandReason.socPercent} to the pack's current
+     * SoC, and {@link EnyoDataBusCommandReason.powerW} to the surplus the
+     * battery is taking — so the text can say "The battery charges to 40 %
+     * first (now 28 %)."
+     *
+     * Told apart from {@link PvSurplusAllocatedElsewhere}: the surplus did not
+     * go to another appliance by the planner's choice, it went to the battery
+     * because the owner asked for it. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} — it is about who
+     * got the sun.
+     */
+    BatteryPvPriority = "battery-pv-priority",
+    /**
+     * The house battery is allowed to feed the heating rod, down to the
+     * owner's `heatingRodBatteryDischargeSocLimitPercent`.
+     *
+     * Set {@link EnyoDataBusCommandReasonContext.batteryToHeatingRod} with the
+     * floor, {@link EnyoDataBusCommandReason.socPercent} to the pack's current
+     * SoC and {@link EnyoDataBusCommandReason.powerW} to the power the battery
+     * contributes. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    BatterySupportsHeatingRod = "battery-supports-heating-rod",
+    /**
+     * The house battery is held back from the heating rod because it has
+     * reached the owner's floor (`heatingRodBatteryDischargeSocLimitPercent`).
+     * The rod runs on PV surplus only — or, under boost, from the grid.
+     *
+     * The counterpart of {@link BatterySupportsHeatingRod}. Set
+     * {@link EnyoDataBusCommandReasonContext.batteryToHeatingRod} and
+     * {@link EnyoDataBusCommandReason.socPercent}. Told apart from
+     * {@link BatterySoCLow}: the pack is not low, it is at the floor the owner
+     * chose for the rod. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    BatteryReservedFromHeatingRod = "battery-reserved-from-heating-rod",
+    /**
+     * A cost-optimised charging session was placed in — or is waiting for — a
+     * low-load hour on the grid, because the owner switched on
+     * `gridOptimizedEvCharging`. Covers both the "charging now" and the
+     * "waiting" side of the decision.
+     *
+     * About relieving the grid, not about the customer's price: on a static or
+     * time-of-use tariff the EPEX spot price that ranked the slot is not what
+     * the customer pays, so the text must not promise a saving — which is why
+     * this is its own type rather than
+     * {@link ElectricityPriceBelowThreshold} or {@link WaitingForCheaperSlot}.
+     *
+     * Set {@link EnyoDataBusCommandReasonContext.placement} with the chosen
+     * window and the session's deadline, and
+     * {@link EnyoDataBusCommandReasonContext.gridLoad} with the spot price
+     * behind it — so the text can say "Charging from 02:00, when the grid is
+     * less busy — ready by 07:00." Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
+     */
+    GridLoadOptimized = "grid-load-optimized"
 }
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -538,6 +627,131 @@ export interface EnyoDataBusCommandReasonContext {
      * protection is against short-cycling (kept on).
      */
     switching?: EnyoDataBusCommandReasonSwitchingContext;
+    /**
+     * The owner's battery-first target (`batteryPvPriorityTargetSocPercent`).
+     * Set on {@link EnyoDataBusCommandReasonTypeEnum.BatteryPvPriority}.
+     */
+    batteryPvPriority?: EnyoDataBusCommandReasonBatteryPvPriorityContext;
+    /**
+     * The owner's battery-to-heating-rod floor
+     * (`heatingRodBatteryDischargeSocLimitPercent`). Set on
+     * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsHeatingRod} and
+     * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromHeatingRod}.
+     */
+    batteryToHeatingRod?: EnyoDataBusCommandReasonBatteryToHeatingRodContext;
+    /**
+     * The owner's home-consumption threshold above which the battery may not
+     * discharge (`batteryDischargeBlockAboveHomeConsumptionW`). Set on
+     * {@link EnyoDataBusCommandReasonTypeEnum.HomeConsumptionHigh} when that
+     * threshold is why the battery is held.
+     */
+    batteryDischargeBlock?: EnyoDataBusCommandReasonBatteryDischargeBlockContext;
+    /**
+     * The EPEX spot price that stood in for grid load. Set on
+     * {@link EnyoDataBusCommandReasonTypeEnum.GridLoadOptimized}.
+     */
+    gridLoad?: EnyoDataBusCommandReasonGridLoadContext;
+}
+/**
+ * The market signal behind a
+ * {@link EnyoDataBusCommandReasonTypeEnum.GridLoadOptimized} decision.
+ *
+ * The EPEX spot price is used as a proxy for how heavily the grid is loaded —
+ * it is **not** what the customer pays, which is why it lives here and not in
+ * {@link EnyoDataBusCommandReason.electricityPricePerKwh}.
+ *
+ * @example
+ * ```typescript
+ * // Waiting for the low-load hours from 02:00 to finish by 07:00:
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.GridLoadOptimized,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.Schedule,
+ *     context: {
+ *         placement: {
+ *             startIso: '2026-10-13T02:00:00+02:00',
+ *             endIso: '2026-10-13T04:30:00+02:00',
+ *             deadlineIso: '2026-10-13T07:00:00+02:00',
+ *         },
+ *         gridLoad: {epexPricePerKwh: 0.042, currency: EnyoCurrencyEnum.EUR},
+ *     },
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonGridLoadContext {
+    /** EPEX spot price per kWh of the chosen slot, in {@link currency} — a grid-load proxy. */
+    epexPricePerKwh: number;
+    /** Currency of {@link epexPricePerKwh}. */
+    currency: EnyoCurrencyEnum;
+}
+/**
+ * The owner's home-consumption threshold
+ * (`batteryDischargeBlockAboveHomeConsumptionW`) the battery is held under —
+ * the structured backing of
+ * {@link EnyoDataBusCommandReasonTypeEnum.HomeConsumptionHigh} when it blocks
+ * the battery. The current home consumption travels in
+ * {@link EnyoDataBusCommandReason.powerW}, measured like
+ * {@link HomeConsumptionTimeseriesEntry.homeConsumptionW}: household plus
+ * untracked appliances, tracked appliances excluded.
+ *
+ * @example
+ * ```typescript
+ * // Home consumption is 13.2 kW, above the owner's 11 kW threshold — hold the battery:
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.HomeConsumptionHigh,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.BatteryState,
+ *     powerW: 13200,
+ *     context: {batteryDischargeBlock: {thresholdW: 11000}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonBatteryDischargeBlockContext {
+    /** The home consumption, in W, above which the battery may not discharge. */
+    thresholdW: number;
+}
+/**
+ * The owner's battery-to-heating-rod floor
+ * (`heatingRodBatteryDischargeSocLimitPercent`) a decision was taken under —
+ * the structured backing of
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatterySupportsHeatingRod} and
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromHeatingRod}. The
+ * pack's current SoC travels in {@link EnyoDataBusCommandReason.socPercent}.
+ *
+ * @example
+ * ```typescript
+ * // The battery reaches the owner's 80 % floor — the rod stops drawing from it:
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromHeatingRod,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.BatteryState,
+ *     socPercent: 80,
+ *     context: {batteryToHeatingRod: {socLimitPercent: 80}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonBatteryToHeatingRodContext {
+    /** The SoC floor, in percent, the battery may feed the rod down to. */
+    socLimitPercent: number;
+}
+/**
+ * The owner's battery-first setting (`batteryPvPriorityTargetSocPercent`) a
+ * PV-surplus consumer was held back under — the structured backing of
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatteryPvPriority}. The pack's
+ * current SoC travels in {@link EnyoDataBusCommandReason.socPercent}.
+ *
+ * @example
+ * ```typescript
+ * // The wallbox gets no PV surplus while the battery charges to 40 %:
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.BatteryPvPriority,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.PvSurplus,
+ *     socPercent: 28,
+ *     powerW: 3200,
+ *     context: {batteryPvPriority: {targetSocPercent: 40}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonBatteryPvPriorityContext {
+    /** The SoC, in percent, the battery is charged to before surplus is shared. */
+    targetSocPercent: number;
 }
 /**
  * Which part of the owner's battery-to-EV setting

package/dist/cjs/types/enyo-electricity-tariff.d.cts

@@ -189,6 +189,19 @@ export interface EnyoTariffPriceEntry {
      * series declares {@link EnyoPriceComponentEnum.GridFee} in its `includes`.
      */
     gridFeeGrossPerKwh?: number;
+    /**
+     * Optional wholesale spot price per kWh this interval's price is based on,
+     * as the provider reports it — typically the EPEX day-ahead price for a
+     * dynamic tariff. In the tariff's currency (not cent), net: without grid
+     * fee, taxes, levies or supplier margin. May be negative.
+     *
+     * Informational only, like {@link gridFeeGrossPerKwh}: it shows what the
+     * price was derived from and is **never added** to {@link pricePerKwh},
+     * which is always the total price. Set it when the provider hands it out;
+     * omit it otherwise — consumers needing a spot price without it can read
+     * `useEpexSpotPrices()`.
+     */
+    spotPricePerKwh?: number;
 }
 /**
  * Prices for one direction over a requested range.