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

package/README.md

@@ -3522,33 +3522,58 @@ Both are for marking on the same power scale a consumer already draws from `maxC
 
 ### BatteryCommandForecast
 
-Relative `{seconds, mode, powerW}` schedule where `mode` is one of `'charge'`, `'discharge'`, or `'auto'`. `auto` returns control to the appliance and must always carry `powerW = 0`.
+A discriminated union on `mode`:
+
+- `mode: 'auto'` — hand the battery back to its own logic over the horizon; no schedule. May carry an optional `reason` (`EnyoDataBusCommandReason`) saying **why** nothing is prescribed — e.g. `PriceSpreadTooSmall` when trading would not pay. Set it only when every Auto slot of the horizon shares the same reason; when they differ, leave it out rather than guess. Without it, an empty Auto forecast tends to read as "no forecast".
+- `mode: 'schedule'` — follow `relativeSchedule`, a list of `{seconds, direction, powerW}` setpoints, where `direction` is `charge`, `discharge` or `idle`.
 
 The type is named `BatteryCommandForecast` to make the distinction with the existing [`BatteryForecast`](#batteryforecast) class (which forecasts state-of-charge from history) explicit.
 
 ```typescript
 import {
+    ApplianceForecastResolutionEnum,
     BatteryCommandForecast,
+    BatteryCommandForecastDirectionEnum,
     BatteryCommandForecastModeEnum,
+    EnyoCurrencyEnum,
+    EnyoDataBusCommandReasonCategoryEnum,
+    EnyoDataBusCommandReasonTypeEnum,
 } from '@enyo-energy/energy-app-sdk';
 
-const forecast: BatteryCommandForecast = {
+// A planned cadence:
+const scheduled: BatteryCommandForecast = {
+    resolution: ApplianceForecastResolutionEnum.FifteenMinutes,
+    mode: BatteryCommandForecastModeEnum.Schedule,
     relativeSchedule: [
-        { seconds: 0,    mode: BatteryCommandForecastModeEnum.Charge,    powerW: 3000 },
-        { seconds: 1800, mode: BatteryCommandForecastModeEnum.Discharge, powerW: 2500 },
-        { seconds: 3600, mode: BatteryCommandForecastModeEnum.Auto,      powerW: 0    },
+        { seconds: 0,    direction: BatteryCommandForecastDirectionEnum.Charge,    powerW: 3000 },
+        { seconds: 1800, direction: BatteryCommandForecastDirectionEnum.Discharge, powerW: 2500 },
+        { seconds: 3600, direction: BatteryCommandForecastDirectionEnum.Idle,      powerW: 0    },
     ],
     estimatedSavings: { costSavings: 0.18, currency: 'EUR' },
 };
+await forecasts.publishBatteryForecast('battery-1', scheduled);
 
-await forecasts.publishBatteryForecast('battery-1', forecast);
+// Nothing planned, and why:
+const auto: BatteryCommandForecast = {
+    resolution: ApplianceForecastResolutionEnum.FifteenMinutes,
+    mode: BatteryCommandForecastModeEnum.Auto,
+    reason: {
+        type: EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall,
+        category: EnyoDataBusCommandReasonCategoryEnum.EnergyPrice,
+        electricityPricePerKwh: 0.352,
+        currency: EnyoCurrencyEnum.EUR,
+        context: { arbitrage: { buyPricePerKwh: 0.352, breakEvenPricePerKwh: 0.527, sellPricePerKwh: 0.429, roundTripEfficiency: 0.757 } },
+    },
+};
+await forecasts.publishBatteryForecast('battery-1', auto);
 ```
 
-Per-entry invariants:
+Invariants:
 
-- `seconds`: finite, non-negative; first entry `= 0`; subsequent entries strictly increasing.
-- `mode`: one of `charge` / `discharge` / `auto`.
-- `powerW`: finite, non-negative. **MUST be `0` when `mode === 'auto'`.**
+- `mode: 'auto'` must not carry a `relativeSchedule`. A `reason` must have a valid `type`; its `context.arbitrage` prices must be EUR/kWh within a plausible band (a ct value such as `35.2` is rejected), `roundTripEfficiency` must lie in (0, 1], and each window's start must lie before its end.
+- `seconds`: finite, non-negative; first entry `= 0`; strictly increasing; a multiple of the `resolution` step.
+- `direction`: one of `charge` / `discharge` / `idle`. `idle` hands the slot to the battery's own logic — to block charging or discharging, use that direction with `powerW = 0` instead.
+- `powerW`: finite, non-negative. **MUST be `0` when `direction === 'idle'`.**
 
 ### HeatpumpForecast
 
@@ -4190,6 +4215,14 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 **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 %)."
 
+**Battery trading: why or why not.** The `arbitrage` context (`EnyoDataBusCommandReasonArbitrageContext`) carries the trough-against-peak arithmetic behind a battery buy: `buyPricePerKwh` / `buyStartIso` / `buyEndIso`, `sellPricePerKwh` / `sellStartIso` / `sellEndIso`, `breakEvenPricePerKwh` (losses, wear and margin included) and `roundTripEfficiency` (a fraction, `0.757`). Prices are **EUR/kWh like every machine-readable price in the SDK** — `0.336`, not `33.6`. Three uses:
+
+- `PriceSpreadTooSmall` (category `EnergyPrice`) — the battery stays on Auto because buying in the trough and using the energy at the peak would not pay back: "Charging at 35.2 ct/kWh only pays off from 52.7 ct/kWh, but the peak averages 42.9 ct/kWh." Set `electricityPricePerKwh` to the buy price and all the figures; on a flat horizon send it without `arbitrage`. The trough is not "too expensive" — the gap is too small — so this is not `ElectricityPriceAboveThreshold`. Where PV makes Auto mean self-consumption, `SelfConsumptionOptimization` stays the right type.
+- `ElectricityPriceBelowThreshold` on a grid charge — the buy and the peak it is for: "Charging at 33.6 ct for the 17:00 peak at 43.7 ct."
+- `ScheduledOptimization` on a price hold (`Discharge 0`) — `sellStartIso` / `sellPricePerKwh`: "Stored energy kept for 17:00 (43.7 ct)." Not `ElectricityPriceBelowThreshold`, which would say power is cheap for a command that stops the battery.
+
+**Installation limits.** Power capped by a limit the owner or installer set — not the grid operator — carries `InstallationLimit` (category `Contention`) with `powerW` set to the ceiling and `context.installationLimit` = `{source, limitW}`, where `source` is `EnyoInstallationLimitSourceEnum.DesiredGridLimit` (`desiredKwLimit`) or `ChargerLimit` (`chargerLimitW`). `limitW` is in **W** even for the desired limit, which is configured in kW. `GridOperatorPowerLimitationActive` stays reserved for limits the grid operator imposed.
+
 **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."

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApplianceCommandForecastValidationError = void 0;
 exports.validateChargerForecast = validateChargerForecast;
 exports.validateBatteryCommandForecast = validateBatteryCommandForecast;
+exports.validateBatteryForecastReason = validateBatteryForecastReason;
 exports.validateHeatpumpForecast = validateHeatpumpForecast;
 exports.validateChargerSchedule = validateChargerSchedule;
 exports.validateBatterySchedule = validateBatterySchedule;
@@ -69,7 +70,9 @@ function validateChargerForecast(forecast) {
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 function validateBatteryCommandForecast(forecast) {
     if (!forecast || typeof forecast !== 'object') {
@@ -84,10 +87,75 @@ function validateBatteryCommandForecast(forecast) {
         if (forecast.relativeSchedule !== undefined) {
             throw new ApplianceCommandForecastValidationError("BatteryCommandForecast with mode='auto' must not carry a relativeSchedule.");
         }
+        if (forecast.reason !== undefined) {
+            validateBatteryForecastReason(forecast.reason, 'BatteryCommandForecast.reason');
+        }
         return;
     }
     validateBatterySchedule(forecast.relativeSchedule, forecast.resolution);
 }
+/**
+ * Lowest and highest plausible price per kWh in a reason's `arbitrage`
+ * context, in EUR/kWh. Wide enough for negative and spiking dynamic prices,
+ * narrow enough to catch a ct value (`33.6`) in a EUR field.
+ */
+const ARBITRAGE_PRICE_MIN_PER_KWH = -1;
+const ARBITRAGE_PRICE_MAX_PER_KWH = 5;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+function validateBatteryForecastReason(reason, fieldName) {
+    if (!reason || typeof reason !== 'object') {
+        throw new ApplianceCommandForecastValidationError(`${fieldName} must be an object.`);
+    }
+    validateEnumField(reason.type, Object.values(enyo_data_bus_value_js_1.EnyoDataBusCommandReasonTypeEnum), `${fieldName}.type`, true);
+    const arbitrage = reason.context?.arbitrage;
+    if (arbitrage === undefined)
+        return;
+    for (const key of ['buyPricePerKwh', 'sellPricePerKwh', 'breakEvenPricePerKwh']) {
+        const price = arbitrage[key];
+        if (price === undefined)
+            continue;
+        if (!Number.isFinite(price)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} must be a finite number; got ${price}.`);
+        }
+        if (price < ARBITRAGE_PRICE_MIN_PER_KWH || price > ARBITRAGE_PRICE_MAX_PER_KWH) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is ${price}, outside ` +
+                `${ARBITRAGE_PRICE_MIN_PER_KWH}…${ARBITRAGE_PRICE_MAX_PER_KWH} — prices are per kWh in ` +
+                'the reason\'s currency (EUR/kWh), not ct/kWh.');
+        }
+    }
+    const efficiency = arbitrage.roundTripEfficiency;
+    if (efficiency !== undefined && (!Number.isFinite(efficiency) || efficiency <= 0 || efficiency > 1)) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.roundTripEfficiency is ${efficiency}; it is a fraction in (0, 1], ` +
+            'e.g. 0.757 rather than 75.7.');
+    }
+    for (const [start, end] of [['buyStartIso', 'buyEndIso'], ['sellStartIso', 'sellEndIso']]) {
+        const startIso = arbitrage[start];
+        const endIso = arbitrage[end];
+        for (const [key, iso] of [[start, startIso], [end, endIso]]) {
+            if (iso !== undefined && Number.isNaN(Date.parse(iso))) {
+                throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is not an ISO 8601 timestamp: ${iso}.`);
+            }
+        }
+        if (startIso !== undefined && endIso !== undefined && Date.parse(startIso) >= Date.parse(endIso)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${start} must lie before ${end}.`);
+        }
+    }
+}
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.d.cts

@@ -1,4 +1,5 @@
 import { AirConditioningForecast, AirConditioningForecastScheduleEntry, ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatingRodForecast, HeatingRodForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry, SmartPlugForecast, SmartPlugForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.cjs';
+import { type EnyoDataBusCommandReason } from '../../types/enyo-data-bus-value.cjs';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
  * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
@@ -23,9 +24,28 @@ export declare function validateChargerForecast(forecast: ChargerForecast): void
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 export declare function validateBatteryCommandForecast(forecast: BatteryCommandForecast): void;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+export declare function validateBatteryForecastReason(reason: EnyoDataBusCommandReason, fieldName: string): void;
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/cjs/types/enyo-appliance-command-forecast.d.cts

@@ -47,6 +47,7 @@
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum } from './enyo-air-conditioning-appliance.cjs';
 import { EnyoAutomationTriggerTypeEnum } from './enyo-automation.cjs';
 import { EnyoChargeModeEnum } from './enyo-data-bus-value.cjs';
+import type { EnyoDataBusCommandReason } from './enyo-data-bus-value.cjs';
 import { EnyoSmartPlugApplianceStateEnum } from './enyo-smart-plug-appliance.cjs';
 /**
  * Optional metadata describing the estimated savings of a forecasted
@@ -262,6 +263,17 @@ export interface BatteryCommandForecastScheduleEntry {
 export interface BatteryCommandForecastAuto extends ApplianceForecastMetadata {
     /** Discriminator — set to {@link BatteryCommandForecastModeEnum.Auto}. */
     mode: BatteryCommandForecastModeEnum.Auto;
+    /**
+     * Why no schedule is prescribed over the horizon — e.g.
+     * {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall} when
+     * trading would not pay.
+     *
+     * Set it only when every Auto slot of the horizon shares the same reason;
+     * when they differ, leave it out rather than pick one. Optional, so a
+     * consumer that does not read it is unaffected — but without it an empty
+     * Auto forecast tends to read as "no forecast".
+     */
+    reason?: EnyoDataBusCommandReason;
 }
 /**
  * Forecast variant that declares an explicit relative schedule the

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoPriceLimitModeEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = exports.EnyoSwitchingProtectionHoldEnum = exports.EnyoBatteryToEvHoldTriggerEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
+exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoPriceLimitModeEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = exports.EnyoSwitchingProtectionHoldEnum = exports.EnyoBatteryToEvHoldTriggerEnum = exports.EnyoInstallationLimitSourceEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -14,6 +14,12 @@ var EnyoDataBusCommandReasonTypeEnum;
      * cost per kWh of delivered heat rather than by price alone, add
      * {@link EnyoDataBusCommandReasonContext.efficiency} so the arithmetic is
      * visible — a warm hour at a higher price can still be the cheaper heat.
+     *
+     * When a battery buys from the grid to cover a later peak, add
+     * {@link EnyoDataBusCommandReasonContext.arbitrage} with the buy price and
+     * the peak it is for (`sellStartIso`, `sellPricePerKwh`), so the text can
+     * say what the buy is for: "Charging at 33.6 ct for the 17:00 peak at
+     * 43.7 ct."
      */
     EnyoDataBusCommandReasonTypeEnum["ElectricityPriceBelowThreshold"] = "electricity-price-below-threshold";
     /** Command issued because the electricity price is above a configured threshold */
@@ -55,7 +61,13 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityUnavailable"] = "battery-capacity-unavailable";
-    /** Command issued because a grid operator power limitation is active */
+    /**
+     * Command issued because a grid operator power limitation is active.
+     *
+     * Only for a limit the grid operator imposed. A cap set by the owner or
+     * installer — the desired grid limit, the charger limit — is
+     * {@link InstallationLimit}.
+     */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
@@ -79,7 +91,14 @@ var EnyoDataBusCommandReasonTypeEnum;
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}) with
      * {@link EnyoDataBusCommandReason.context} — `forecast` for what was seen
      * coming, `efficiency` for why this slot won, `thermalStorage` for what
-     * ends the block, `placement` for when it runs.
+     * ends the block, `placement` for when it runs, `arbitrage` for the price
+     * spread a battery block was placed for.
+     *
+     * Also the type for a battery held back (`Discharge 0`) so that stored
+     * energy is kept for a later, dearer peak: set `arbitrage.sellStartIso`
+     * and `arbitrage.sellPricePerKwh` so the text reads "Stored energy kept for
+     * 17:00 (43.7 ct)." Not {@link ElectricityPriceBelowThreshold} — that
+     * would say power is cheap for a command that stops the battery.
      */
     EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
     /** Command issued because the user explicitly requested it */
@@ -109,7 +128,15 @@ var EnyoDataBusCommandReasonTypeEnum;
      * limit."
      */
     EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
-    /** Command issued to optimize self-consumption */
+    /**
+     * Command issued to optimize self-consumption — e.g. a battery handed back
+     * to its own logic so it stores PV surplus and covers the house load.
+     *
+     * Only true where there is something to self-consume. A battery on a site
+     * without PV that is left on Auto because trading does not pay is
+     * {@link PriceSpreadTooSmall}; do not use this type as the default for
+     * every Auto hand-back.
+     */
     EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
     /**
      * Nothing left to deliver — the run's energy (or temperature, or state of
@@ -318,6 +345,37 @@ var EnyoDataBusCommandReasonTypeEnum;
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
      */
     EnyoDataBusCommandReasonTypeEnum["GridLoadOptimized"] = "grid-load-optimized";
+    /**
+     * The battery is left to its own logic because buying in the cheap hours
+     * and using the energy in the dear ones would not pay back after storage
+     * losses and wear. The trough is not "expensive" — the gap between trough
+     * and peak is too small.
+     *
+     * Set {@link EnyoDataBusCommandReason.electricityPricePerKwh} to the buy
+     * price and {@link EnyoDataBusCommandReasonContext.arbitrage} to the
+     * figures behind the verdict. On a flat horizon — prices barely move, so
+     * there is no cycle to weigh at all — send the type without `arbitrage`;
+     * the text then says so without figures.
+     *
+     * Told apart from {@link ElectricityPriceAboveThreshold}, which claims the
+     * price is over a level, and from {@link SelfConsumptionOptimization},
+     * which stays the right type where PV makes Auto mean self-consumption.
+     * Not {@link ScheduledOptimization}: nothing is placed, this is a refusal
+     * to trade. Category {@link EnyoDataBusCommandReasonCategoryEnum.EnergyPrice}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["PriceSpreadTooSmall"] = "price-spread-too-small";
+    /**
+     * Power is capped by a limit the owner or installer set for the
+     * installation — not by the grid operator.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the ceiling and
+     * {@link EnyoDataBusCommandReasonContext.installationLimit} to say which
+     * limit it is, so the text can tell "your desired grid limit of 8 kW" from
+     * "the charger limit of 11 kW set by your installer". Told apart from
+     * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
+     * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["InstallationLimit"] = "installation-limit";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -360,6 +418,23 @@ var EnyoDataBusCommandReasonCategoryEnum;
     /** Any reason not covered by the categories above. */
     EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
 })(EnyoDataBusCommandReasonCategoryEnum || (exports.EnyoDataBusCommandReasonCategoryEnum = EnyoDataBusCommandReasonCategoryEnum = {}));
+/**
+ * Which owner- or installer-set limit capped the power behind an
+ * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ */
+var EnyoInstallationLimitSourceEnum;
+(function (EnyoInstallationLimitSourceEnum) {
+    /**
+     * The soft grid limit the user or installer would like import and export
+     * to stay within — {@link EnyoGridConnectionPoint.desiredKwLimit}.
+     */
+    EnyoInstallationLimitSourceEnum["DesiredGridLimit"] = "desired-grid-limit";
+    /**
+     * The installer's cap on the total power all wallboxes may draw —
+     * {@link EnyoGridConnectionPoint.chargerLimitW}.
+     */
+    EnyoInstallationLimitSourceEnum["ChargerLimit"] = "charger-limit";
+})(EnyoInstallationLimitSourceEnum || (exports.EnyoInstallationLimitSourceEnum = EnyoInstallationLimitSourceEnum = {}));
 /**
  * Which part of the owner's battery-to-EV setting
  * (`batteryEvDischargeMode`) caused a

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

@@ -30,6 +30,12 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * cost per kWh of delivered heat rather than by price alone, add
      * {@link EnyoDataBusCommandReasonContext.efficiency} so the arithmetic is
      * visible — a warm hour at a higher price can still be the cheaper heat.
+     *
+     * When a battery buys from the grid to cover a later peak, add
+     * {@link EnyoDataBusCommandReasonContext.arbitrage} with the buy price and
+     * the peak it is for (`sellStartIso`, `sellPricePerKwh`), so the text can
+     * say what the buy is for: "Charging at 33.6 ct for the 17:00 peak at
+     * 43.7 ct."
      */
     ElectricityPriceBelowThreshold = "electricity-price-below-threshold",
     /** Command issued because the electricity price is above a configured threshold */
@@ -71,7 +77,13 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
     BatteryCapacityUnavailable = "battery-capacity-unavailable",
-    /** Command issued because a grid operator power limitation is active */
+    /**
+     * Command issued because a grid operator power limitation is active.
+     *
+     * Only for a limit the grid operator imposed. A cap set by the owner or
+     * installer — the desired grid limit, the charger limit — is
+     * {@link InstallationLimit}.
+     */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
     GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
@@ -95,7 +107,14 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}) with
      * {@link EnyoDataBusCommandReason.context} — `forecast` for what was seen
      * coming, `efficiency` for why this slot won, `thermalStorage` for what
-     * ends the block, `placement` for when it runs.
+     * ends the block, `placement` for when it runs, `arbitrage` for the price
+     * spread a battery block was placed for.
+     *
+     * Also the type for a battery held back (`Discharge 0`) so that stored
+     * energy is kept for a later, dearer peak: set `arbitrage.sellStartIso`
+     * and `arbitrage.sellPricePerKwh` so the text reads "Stored energy kept for
+     * 17:00 (43.7 ct)." Not {@link ElectricityPriceBelowThreshold} — that
+     * would say power is cheap for a command that stops the battery.
      */
     ScheduledOptimization = "scheduled-optimization",
     /** Command issued because the user explicitly requested it */
@@ -125,7 +144,15 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * limit."
      */
     HomeConsumptionHigh = "home-consumption-high",
-    /** Command issued to optimize self-consumption */
+    /**
+     * Command issued to optimize self-consumption — e.g. a battery handed back
+     * to its own logic so it stores PV surplus and covers the house load.
+     *
+     * Only true where there is something to self-consume. A battery on a site
+     * without PV that is left on Auto because trading does not pay is
+     * {@link PriceSpreadTooSmall}; do not use this type as the default for
+     * every Auto hand-back.
+     */
     SelfConsumptionOptimization = "self-consumption-optimization",
     /**
      * Nothing left to deliver — the run's energy (or temperature, or state of
@@ -333,7 +360,38 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * less busy — ready by 07:00." Category
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
      */
-    GridLoadOptimized = "grid-load-optimized"
+    GridLoadOptimized = "grid-load-optimized",
+    /**
+     * The battery is left to its own logic because buying in the cheap hours
+     * and using the energy in the dear ones would not pay back after storage
+     * losses and wear. The trough is not "expensive" — the gap between trough
+     * and peak is too small.
+     *
+     * Set {@link EnyoDataBusCommandReason.electricityPricePerKwh} to the buy
+     * price and {@link EnyoDataBusCommandReasonContext.arbitrage} to the
+     * figures behind the verdict. On a flat horizon — prices barely move, so
+     * there is no cycle to weigh at all — send the type without `arbitrage`;
+     * the text then says so without figures.
+     *
+     * Told apart from {@link ElectricityPriceAboveThreshold}, which claims the
+     * price is over a level, and from {@link SelfConsumptionOptimization},
+     * which stays the right type where PV makes Auto mean self-consumption.
+     * Not {@link ScheduledOptimization}: nothing is placed, this is a refusal
+     * to trade. Category {@link EnyoDataBusCommandReasonCategoryEnum.EnergyPrice}.
+     */
+    PriceSpreadTooSmall = "price-spread-too-small",
+    /**
+     * Power is capped by a limit the owner or installer set for the
+     * installation — not by the grid operator.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the ceiling and
+     * {@link EnyoDataBusCommandReasonContext.installationLimit} to say which
+     * limit it is, so the text can tell "your desired grid limit of 8 kW" from
+     * "the charger limit of 11 kW set by your installer". Told apart from
+     * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
+     * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
+     */
+    InstallationLimit = "installation-limit"
 }
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -651,6 +709,124 @@ export interface EnyoDataBusCommandReasonContext {
      * {@link EnyoDataBusCommandReasonTypeEnum.GridLoadOptimized}.
      */
     gridLoad?: EnyoDataBusCommandReasonGridLoadContext;
+    /**
+     * The trough-against-peak arithmetic behind a battery buy that was or was
+     * not made. Set on {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall},
+     * and alongside {@link EnyoDataBusCommandReasonTypeEnum.ElectricityPriceBelowThreshold}
+     * (a buy for a peak) or {@link EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization}
+     * (energy kept for a peak).
+     */
+    arbitrage?: EnyoDataBusCommandReasonArbitrageContext;
+    /**
+     * Which owner- or installer-set limit capped the power. Set on
+     * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+     */
+    installationLimit?: EnyoDataBusCommandReasonInstallationLimitContext;
+}
+/**
+ * The trough-against-peak arithmetic behind a battery buy that was or was not
+ * made.
+ *
+ * Prices are per kWh of electricity in
+ * {@link EnyoDataBusCommandReason.currency} — **EUR/kWh, not ct**, like
+ * {@link EnyoDataBusCommandReason.electricityPricePerKwh}: `0.336`, not
+ * `33.6`. Every field is optional so each use sets only what it states:
+ *
+ * - {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall} — all of them.
+ * - {@link EnyoDataBusCommandReasonTypeEnum.ElectricityPriceBelowThreshold} on
+ *   a grid charge — the buy, and the peak it is for.
+ * - {@link EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization} on a hold —
+ *   the peak the energy is kept for.
+ *
+ * @example
+ * ```typescript
+ * // No cycle charge: buying at 35.2 ct needs 52.7 ct to pay back, the peak averages 42.9 ct.
+ * const refused: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.EnergyPrice,
+ *     electricityPricePerKwh: 0.352,
+ *     currency: EnyoCurrencyEnum.EUR,
+ *     context: {arbitrage: {
+ *         buyPricePerKwh: 0.352,
+ *         buyStartIso: '2026-10-13T11:00:00Z',
+ *         buyEndIso: '2026-10-13T13:00:00Z',
+ *         sellPricePerKwh: 0.429,
+ *         sellStartIso: '2026-10-13T16:00:00Z',
+ *         sellEndIso: '2026-10-13T19:00:00Z',
+ *         breakEvenPricePerKwh: 0.527,
+ *         roundTripEfficiency: 0.757,
+ *     }},
+ * };
+ *
+ * // Stored energy kept for the 17:00 peak:
+ * const hold: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.Schedule,
+ *     powerW: 0,
+ *     currency: EnyoCurrencyEnum.EUR,
+ *     context: {arbitrage: {sellStartIso: '2026-10-13T17:00:00Z', sellPricePerKwh: 0.437}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonArbitrageContext {
+    /** Average price, EUR/kWh, over the cheapest window the energy would be bought in. */
+    buyPricePerKwh?: number;
+    /** ISO 8601 start of the buy window. */
+    buyStartIso?: string;
+    /** ISO 8601 end of the buy window. */
+    buyEndIso?: string;
+    /** Average price, EUR/kWh, over the peak window the energy would be used in. */
+    sellPricePerKwh?: number;
+    /** ISO 8601 start of the peak window. */
+    sellStartIso?: string;
+    /** ISO 8601 end of the peak window. */
+    sellEndIso?: string;
+    /**
+     * Price, EUR/kWh, the peak must reach for the buy to pay back — losses,
+     * wear and margin included.
+     */
+    breakEvenPricePerKwh?: number;
+    /** Round-trip efficiency the verdict assumed, as a fraction (0–1): `0.757`, not `75.7`. */
+    roundTripEfficiency?: number;
+}
+/**
+ * Which owner- or installer-set limit capped the power behind an
+ * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ */
+export declare enum EnyoInstallationLimitSourceEnum {
+    /**
+     * The soft grid limit the user or installer would like import and export
+     * to stay within — {@link EnyoGridConnectionPoint.desiredKwLimit}.
+     */
+    DesiredGridLimit = "desired-grid-limit",
+    /**
+     * The installer's cap on the total power all wallboxes may draw —
+     * {@link EnyoGridConnectionPoint.chargerLimitW}.
+     */
+    ChargerLimit = "charger-limit"
+}
+/**
+ * The limit behind an {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ *
+ * @example
+ * ```typescript
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.InstallationLimit,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.Contention,
+ *     powerW: 11000,
+ *     context: {installationLimit: {source: EnyoInstallationLimitSourceEnum.ChargerLimit, limitW: 11000}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonInstallationLimitContext {
+    /** Which limit applied. */
+    source: EnyoInstallationLimitSourceEnum;
+    /**
+     * The limit, in **watts** — also for
+     * {@link EnyoInstallationLimitSourceEnum.DesiredGridLimit}, whose
+     * configured value `desiredKwLimit` is in kW: convert before setting it.
+     */
+    limitW: number;
 }
 /**
  * The market signal behind a

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.29.0';
+exports.SDK_VERSION = '1.30.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.29.0";
+export declare const SDK_VERSION = "1.30.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/implementations/appliance-command-forecast/appliance-command-forecast-validators.d.ts

@@ -1,4 +1,5 @@
 import { AirConditioningForecast, AirConditioningForecastScheduleEntry, ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatingRodForecast, HeatingRodForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry, SmartPlugForecast, SmartPlugForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.js';
+import { type EnyoDataBusCommandReason } from '../../types/enyo-data-bus-value.js';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
  * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
@@ -23,9 +24,28 @@ export declare function validateChargerForecast(forecast: ChargerForecast): void
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 export declare function validateBatteryCommandForecast(forecast: BatteryCommandForecast): void;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+export declare function validateBatteryForecastReason(reason: EnyoDataBusCommandReason, fieldName: string): void;
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/implementations/appliance-command-forecast/appliance-command-forecast-validators.js

@@ -1,7 +1,7 @@
 import { ApplianceForecastResolutionEnum, BatteryCommandForecastDirectionEnum, BatteryCommandForecastModeEnum, } from '../../types/enyo-appliance-command-forecast.js';
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum, } from '../../types/enyo-air-conditioning-appliance.js';
 import { EnyoAutomationTriggerTypeEnum } from '../../types/enyo-automation.js';
-import { EnyoChargeModeEnum } from '../../types/enyo-data-bus-value.js';
+import { EnyoChargeModeEnum, EnyoDataBusCommandReasonTypeEnum, } from '../../types/enyo-data-bus-value.js';
 import { EnyoSmartPlugApplianceStateEnum } from '../../types/enyo-smart-plug-appliance.js';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
@@ -49,7 +49,9 @@ export function validateChargerForecast(forecast) {
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 export function validateBatteryCommandForecast(forecast) {
     if (!forecast || typeof forecast !== 'object') {
@@ -64,10 +66,75 @@ export function validateBatteryCommandForecast(forecast) {
         if (forecast.relativeSchedule !== undefined) {
             throw new ApplianceCommandForecastValidationError("BatteryCommandForecast with mode='auto' must not carry a relativeSchedule.");
         }
+        if (forecast.reason !== undefined) {
+            validateBatteryForecastReason(forecast.reason, 'BatteryCommandForecast.reason');
+        }
         return;
     }
     validateBatterySchedule(forecast.relativeSchedule, forecast.resolution);
 }
+/**
+ * Lowest and highest plausible price per kWh in a reason's `arbitrage`
+ * context, in EUR/kWh. Wide enough for negative and spiking dynamic prices,
+ * narrow enough to catch a ct value (`33.6`) in a EUR field.
+ */
+const ARBITRAGE_PRICE_MIN_PER_KWH = -1;
+const ARBITRAGE_PRICE_MAX_PER_KWH = 5;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+export function validateBatteryForecastReason(reason, fieldName) {
+    if (!reason || typeof reason !== 'object') {
+        throw new ApplianceCommandForecastValidationError(`${fieldName} must be an object.`);
+    }
+    validateEnumField(reason.type, Object.values(EnyoDataBusCommandReasonTypeEnum), `${fieldName}.type`, true);
+    const arbitrage = reason.context?.arbitrage;
+    if (arbitrage === undefined)
+        return;
+    for (const key of ['buyPricePerKwh', 'sellPricePerKwh', 'breakEvenPricePerKwh']) {
+        const price = arbitrage[key];
+        if (price === undefined)
+            continue;
+        if (!Number.isFinite(price)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} must be a finite number; got ${price}.`);
+        }
+        if (price < ARBITRAGE_PRICE_MIN_PER_KWH || price > ARBITRAGE_PRICE_MAX_PER_KWH) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is ${price}, outside ` +
+                `${ARBITRAGE_PRICE_MIN_PER_KWH}…${ARBITRAGE_PRICE_MAX_PER_KWH} — prices are per kWh in ` +
+                'the reason\'s currency (EUR/kWh), not ct/kWh.');
+        }
+    }
+    const efficiency = arbitrage.roundTripEfficiency;
+    if (efficiency !== undefined && (!Number.isFinite(efficiency) || efficiency <= 0 || efficiency > 1)) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.roundTripEfficiency is ${efficiency}; it is a fraction in (0, 1], ` +
+            'e.g. 0.757 rather than 75.7.');
+    }
+    for (const [start, end] of [['buyStartIso', 'buyEndIso'], ['sellStartIso', 'sellEndIso']]) {
+        const startIso = arbitrage[start];
+        const endIso = arbitrage[end];
+        for (const [key, iso] of [[start, startIso], [end, endIso]]) {
+            if (iso !== undefined && Number.isNaN(Date.parse(iso))) {
+                throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is not an ISO 8601 timestamp: ${iso}.`);
+            }
+        }
+        if (startIso !== undefined && endIso !== undefined && Date.parse(startIso) >= Date.parse(endIso)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${start} must lie before ${end}.`);
+        }
+    }
+}
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/types/enyo-appliance-command-forecast.d.ts

@@ -47,6 +47,7 @@
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum } from './enyo-air-conditioning-appliance.js';
 import { EnyoAutomationTriggerTypeEnum } from './enyo-automation.js';
 import { EnyoChargeModeEnum } from './enyo-data-bus-value.js';
+import type { EnyoDataBusCommandReason } from './enyo-data-bus-value.js';
 import { EnyoSmartPlugApplianceStateEnum } from './enyo-smart-plug-appliance.js';
 /**
  * Optional metadata describing the estimated savings of a forecasted
@@ -262,6 +263,17 @@ export interface BatteryCommandForecastScheduleEntry {
 export interface BatteryCommandForecastAuto extends ApplianceForecastMetadata {
     /** Discriminator — set to {@link BatteryCommandForecastModeEnum.Auto}. */
     mode: BatteryCommandForecastModeEnum.Auto;
+    /**
+     * Why no schedule is prescribed over the horizon — e.g.
+     * {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall} when
+     * trading would not pay.
+     *
+     * Set it only when every Auto slot of the horizon shares the same reason;
+     * when they differ, leave it out rather than pick one. Optional, so a
+     * consumer that does not read it is unaffected — but without it an empty
+     * Auto forecast tends to read as "no forecast".
+     */
+    reason?: EnyoDataBusCommandReason;
 }
 /**
  * Forecast variant that declares an explicit relative schedule the

package/dist/types/enyo-data-bus-value.d.ts

@@ -30,6 +30,12 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * cost per kWh of delivered heat rather than by price alone, add
      * {@link EnyoDataBusCommandReasonContext.efficiency} so the arithmetic is
      * visible — a warm hour at a higher price can still be the cheaper heat.
+     *
+     * When a battery buys from the grid to cover a later peak, add
+     * {@link EnyoDataBusCommandReasonContext.arbitrage} with the buy price and
+     * the peak it is for (`sellStartIso`, `sellPricePerKwh`), so the text can
+     * say what the buy is for: "Charging at 33.6 ct for the 17:00 peak at
+     * 43.7 ct."
      */
     ElectricityPriceBelowThreshold = "electricity-price-below-threshold",
     /** Command issued because the electricity price is above a configured threshold */
@@ -71,7 +77,13 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
     BatteryCapacityUnavailable = "battery-capacity-unavailable",
-    /** Command issued because a grid operator power limitation is active */
+    /**
+     * Command issued because a grid operator power limitation is active.
+     *
+     * Only for a limit the grid operator imposed. A cap set by the owner or
+     * installer — the desired grid limit, the charger limit — is
+     * {@link InstallationLimit}.
+     */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
     GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
@@ -95,7 +107,14 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}) with
      * {@link EnyoDataBusCommandReason.context} — `forecast` for what was seen
      * coming, `efficiency` for why this slot won, `thermalStorage` for what
-     * ends the block, `placement` for when it runs.
+     * ends the block, `placement` for when it runs, `arbitrage` for the price
+     * spread a battery block was placed for.
+     *
+     * Also the type for a battery held back (`Discharge 0`) so that stored
+     * energy is kept for a later, dearer peak: set `arbitrage.sellStartIso`
+     * and `arbitrage.sellPricePerKwh` so the text reads "Stored energy kept for
+     * 17:00 (43.7 ct)." Not {@link ElectricityPriceBelowThreshold} — that
+     * would say power is cheap for a command that stops the battery.
      */
     ScheduledOptimization = "scheduled-optimization",
     /** Command issued because the user explicitly requested it */
@@ -125,7 +144,15 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * limit."
      */
     HomeConsumptionHigh = "home-consumption-high",
-    /** Command issued to optimize self-consumption */
+    /**
+     * Command issued to optimize self-consumption — e.g. a battery handed back
+     * to its own logic so it stores PV surplus and covers the house load.
+     *
+     * Only true where there is something to self-consume. A battery on a site
+     * without PV that is left on Auto because trading does not pay is
+     * {@link PriceSpreadTooSmall}; do not use this type as the default for
+     * every Auto hand-back.
+     */
     SelfConsumptionOptimization = "self-consumption-optimization",
     /**
      * Nothing left to deliver — the run's energy (or temperature, or state of
@@ -333,7 +360,38 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * less busy — ready by 07:00." Category
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
      */
-    GridLoadOptimized = "grid-load-optimized"
+    GridLoadOptimized = "grid-load-optimized",
+    /**
+     * The battery is left to its own logic because buying in the cheap hours
+     * and using the energy in the dear ones would not pay back after storage
+     * losses and wear. The trough is not "expensive" — the gap between trough
+     * and peak is too small.
+     *
+     * Set {@link EnyoDataBusCommandReason.electricityPricePerKwh} to the buy
+     * price and {@link EnyoDataBusCommandReasonContext.arbitrage} to the
+     * figures behind the verdict. On a flat horizon — prices barely move, so
+     * there is no cycle to weigh at all — send the type without `arbitrage`;
+     * the text then says so without figures.
+     *
+     * Told apart from {@link ElectricityPriceAboveThreshold}, which claims the
+     * price is over a level, and from {@link SelfConsumptionOptimization},
+     * which stays the right type where PV makes Auto mean self-consumption.
+     * Not {@link ScheduledOptimization}: nothing is placed, this is a refusal
+     * to trade. Category {@link EnyoDataBusCommandReasonCategoryEnum.EnergyPrice}.
+     */
+    PriceSpreadTooSmall = "price-spread-too-small",
+    /**
+     * Power is capped by a limit the owner or installer set for the
+     * installation — not by the grid operator.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the ceiling and
+     * {@link EnyoDataBusCommandReasonContext.installationLimit} to say which
+     * limit it is, so the text can tell "your desired grid limit of 8 kW" from
+     * "the charger limit of 11 kW set by your installer". Told apart from
+     * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
+     * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
+     */
+    InstallationLimit = "installation-limit"
 }
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -651,6 +709,124 @@ export interface EnyoDataBusCommandReasonContext {
      * {@link EnyoDataBusCommandReasonTypeEnum.GridLoadOptimized}.
      */
     gridLoad?: EnyoDataBusCommandReasonGridLoadContext;
+    /**
+     * The trough-against-peak arithmetic behind a battery buy that was or was
+     * not made. Set on {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall},
+     * and alongside {@link EnyoDataBusCommandReasonTypeEnum.ElectricityPriceBelowThreshold}
+     * (a buy for a peak) or {@link EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization}
+     * (energy kept for a peak).
+     */
+    arbitrage?: EnyoDataBusCommandReasonArbitrageContext;
+    /**
+     * Which owner- or installer-set limit capped the power. Set on
+     * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+     */
+    installationLimit?: EnyoDataBusCommandReasonInstallationLimitContext;
+}
+/**
+ * The trough-against-peak arithmetic behind a battery buy that was or was not
+ * made.
+ *
+ * Prices are per kWh of electricity in
+ * {@link EnyoDataBusCommandReason.currency} — **EUR/kWh, not ct**, like
+ * {@link EnyoDataBusCommandReason.electricityPricePerKwh}: `0.336`, not
+ * `33.6`. Every field is optional so each use sets only what it states:
+ *
+ * - {@link EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall} — all of them.
+ * - {@link EnyoDataBusCommandReasonTypeEnum.ElectricityPriceBelowThreshold} on
+ *   a grid charge — the buy, and the peak it is for.
+ * - {@link EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization} on a hold —
+ *   the peak the energy is kept for.
+ *
+ * @example
+ * ```typescript
+ * // No cycle charge: buying at 35.2 ct needs 52.7 ct to pay back, the peak averages 42.9 ct.
+ * const refused: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.EnergyPrice,
+ *     electricityPricePerKwh: 0.352,
+ *     currency: EnyoCurrencyEnum.EUR,
+ *     context: {arbitrage: {
+ *         buyPricePerKwh: 0.352,
+ *         buyStartIso: '2026-10-13T11:00:00Z',
+ *         buyEndIso: '2026-10-13T13:00:00Z',
+ *         sellPricePerKwh: 0.429,
+ *         sellStartIso: '2026-10-13T16:00:00Z',
+ *         sellEndIso: '2026-10-13T19:00:00Z',
+ *         breakEvenPricePerKwh: 0.527,
+ *         roundTripEfficiency: 0.757,
+ *     }},
+ * };
+ *
+ * // Stored energy kept for the 17:00 peak:
+ * const hold: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.Schedule,
+ *     powerW: 0,
+ *     currency: EnyoCurrencyEnum.EUR,
+ *     context: {arbitrage: {sellStartIso: '2026-10-13T17:00:00Z', sellPricePerKwh: 0.437}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonArbitrageContext {
+    /** Average price, EUR/kWh, over the cheapest window the energy would be bought in. */
+    buyPricePerKwh?: number;
+    /** ISO 8601 start of the buy window. */
+    buyStartIso?: string;
+    /** ISO 8601 end of the buy window. */
+    buyEndIso?: string;
+    /** Average price, EUR/kWh, over the peak window the energy would be used in. */
+    sellPricePerKwh?: number;
+    /** ISO 8601 start of the peak window. */
+    sellStartIso?: string;
+    /** ISO 8601 end of the peak window. */
+    sellEndIso?: string;
+    /**
+     * Price, EUR/kWh, the peak must reach for the buy to pay back — losses,
+     * wear and margin included.
+     */
+    breakEvenPricePerKwh?: number;
+    /** Round-trip efficiency the verdict assumed, as a fraction (0–1): `0.757`, not `75.7`. */
+    roundTripEfficiency?: number;
+}
+/**
+ * Which owner- or installer-set limit capped the power behind an
+ * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ */
+export declare enum EnyoInstallationLimitSourceEnum {
+    /**
+     * The soft grid limit the user or installer would like import and export
+     * to stay within — {@link EnyoGridConnectionPoint.desiredKwLimit}.
+     */
+    DesiredGridLimit = "desired-grid-limit",
+    /**
+     * The installer's cap on the total power all wallboxes may draw —
+     * {@link EnyoGridConnectionPoint.chargerLimitW}.
+     */
+    ChargerLimit = "charger-limit"
+}
+/**
+ * The limit behind an {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ *
+ * @example
+ * ```typescript
+ * const reason: EnyoDataBusCommandReason = {
+ *     type: EnyoDataBusCommandReasonTypeEnum.InstallationLimit,
+ *     category: EnyoDataBusCommandReasonCategoryEnum.Contention,
+ *     powerW: 11000,
+ *     context: {installationLimit: {source: EnyoInstallationLimitSourceEnum.ChargerLimit, limitW: 11000}},
+ * };
+ * ```
+ */
+export interface EnyoDataBusCommandReasonInstallationLimitContext {
+    /** Which limit applied. */
+    source: EnyoInstallationLimitSourceEnum;
+    /**
+     * The limit, in **watts** — also for
+     * {@link EnyoInstallationLimitSourceEnum.DesiredGridLimit}, whose
+     * configured value `desiredKwLimit` is in kW: convert before setting it.
+     */
+    limitW: number;
 }
 /**
  * The market signal behind a

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

@@ -11,6 +11,12 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * cost per kWh of delivered heat rather than by price alone, add
      * {@link EnyoDataBusCommandReasonContext.efficiency} so the arithmetic is
      * visible — a warm hour at a higher price can still be the cheaper heat.
+     *
+     * When a battery buys from the grid to cover a later peak, add
+     * {@link EnyoDataBusCommandReasonContext.arbitrage} with the buy price and
+     * the peak it is for (`sellStartIso`, `sellPricePerKwh`), so the text can
+     * say what the buy is for: "Charging at 33.6 ct for the 17:00 peak at
+     * 43.7 ct."
      */
     EnyoDataBusCommandReasonTypeEnum["ElectricityPriceBelowThreshold"] = "electricity-price-below-threshold";
     /** Command issued because the electricity price is above a configured threshold */
@@ -52,7 +58,13 @@ export var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityUnavailable"] = "battery-capacity-unavailable";
-    /** Command issued because a grid operator power limitation is active */
+    /**
+     * Command issued because a grid operator power limitation is active.
+     *
+     * Only for a limit the grid operator imposed. A cap set by the owner or
+     * installer — the desired grid limit, the charger limit — is
+     * {@link InstallationLimit}.
+     */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
@@ -76,7 +88,14 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}) with
      * {@link EnyoDataBusCommandReason.context} — `forecast` for what was seen
      * coming, `efficiency` for why this slot won, `thermalStorage` for what
-     * ends the block, `placement` for when it runs.
+     * ends the block, `placement` for when it runs, `arbitrage` for the price
+     * spread a battery block was placed for.
+     *
+     * Also the type for a battery held back (`Discharge 0`) so that stored
+     * energy is kept for a later, dearer peak: set `arbitrage.sellStartIso`
+     * and `arbitrage.sellPricePerKwh` so the text reads "Stored energy kept for
+     * 17:00 (43.7 ct)." Not {@link ElectricityPriceBelowThreshold} — that
+     * would say power is cheap for a command that stops the battery.
      */
     EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
     /** Command issued because the user explicitly requested it */
@@ -106,7 +125,15 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * limit."
      */
     EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
-    /** Command issued to optimize self-consumption */
+    /**
+     * Command issued to optimize self-consumption — e.g. a battery handed back
+     * to its own logic so it stores PV surplus and covers the house load.
+     *
+     * Only true where there is something to self-consume. A battery on a site
+     * without PV that is left on Auto because trading does not pay is
+     * {@link PriceSpreadTooSmall}; do not use this type as the default for
+     * every Auto hand-back.
+     */
     EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
     /**
      * Nothing left to deliver — the run's energy (or temperature, or state of
@@ -315,6 +342,37 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * {@link EnyoDataBusCommandReasonCategoryEnum.Schedule}.
      */
     EnyoDataBusCommandReasonTypeEnum["GridLoadOptimized"] = "grid-load-optimized";
+    /**
+     * The battery is left to its own logic because buying in the cheap hours
+     * and using the energy in the dear ones would not pay back after storage
+     * losses and wear. The trough is not "expensive" — the gap between trough
+     * and peak is too small.
+     *
+     * Set {@link EnyoDataBusCommandReason.electricityPricePerKwh} to the buy
+     * price and {@link EnyoDataBusCommandReasonContext.arbitrage} to the
+     * figures behind the verdict. On a flat horizon — prices barely move, so
+     * there is no cycle to weigh at all — send the type without `arbitrage`;
+     * the text then says so without figures.
+     *
+     * Told apart from {@link ElectricityPriceAboveThreshold}, which claims the
+     * price is over a level, and from {@link SelfConsumptionOptimization},
+     * which stays the right type where PV makes Auto mean self-consumption.
+     * Not {@link ScheduledOptimization}: nothing is placed, this is a refusal
+     * to trade. Category {@link EnyoDataBusCommandReasonCategoryEnum.EnergyPrice}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["PriceSpreadTooSmall"] = "price-spread-too-small";
+    /**
+     * Power is capped by a limit the owner or installer set for the
+     * installation — not by the grid operator.
+     *
+     * Set {@link EnyoDataBusCommandReason.powerW} to the ceiling and
+     * {@link EnyoDataBusCommandReasonContext.installationLimit} to say which
+     * limit it is, so the text can tell "your desired grid limit of 8 kW" from
+     * "the charger limit of 11 kW set by your installer". Told apart from
+     * {@link GridOperatorPowerLimitationActive}, which would be untrue here.
+     * Category {@link EnyoDataBusCommandReasonCategoryEnum.Contention}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["InstallationLimit"] = "installation-limit";
 })(EnyoDataBusCommandReasonTypeEnum || (EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -357,6 +415,23 @@ export var EnyoDataBusCommandReasonCategoryEnum;
     /** Any reason not covered by the categories above. */
     EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
 })(EnyoDataBusCommandReasonCategoryEnum || (EnyoDataBusCommandReasonCategoryEnum = {}));
+/**
+ * Which owner- or installer-set limit capped the power behind an
+ * {@link EnyoDataBusCommandReasonTypeEnum.InstallationLimit}.
+ */
+export var EnyoInstallationLimitSourceEnum;
+(function (EnyoInstallationLimitSourceEnum) {
+    /**
+     * The soft grid limit the user or installer would like import and export
+     * to stay within — {@link EnyoGridConnectionPoint.desiredKwLimit}.
+     */
+    EnyoInstallationLimitSourceEnum["DesiredGridLimit"] = "desired-grid-limit";
+    /**
+     * The installer's cap on the total power all wallboxes may draw —
+     * {@link EnyoGridConnectionPoint.chargerLimitW}.
+     */
+    EnyoInstallationLimitSourceEnum["ChargerLimit"] = "charger-limit";
+})(EnyoInstallationLimitSourceEnum || (EnyoInstallationLimitSourceEnum = {}));
 /**
  * Which part of the owner's battery-to-EV setting
  * (`batteryEvDischargeMode`) caused a

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.29.0";
+export declare const SDK_VERSION = "1.30.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.29.0';
+export const SDK_VERSION = '1.30.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",