@enyo-energy/energy-app-sdk 0.0.197 → 0.0.198

package/README.md

@@ -1137,7 +1137,7 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `BatteryChargingMode` | `paced` \| `immediate` |
 | `BatteryChargeFromGrid` | boolean |
 | `BatteryDischargeWhileChargingWh` | number \| `null` (Wh allowance; `null`/unset = disabled) |
-| `BlockBatteryDischargeWhileEvDischarging` | boolean |
+| `BlockBatteryDischargeWhileEvCharging` | boolean |
 | `HeatpumpControl` | boolean |
 | `HeatingRodControl` | boolean |
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |

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

@@ -118,6 +118,9 @@ function gateValue(values, setting) {
  * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
  *   (**error**), and is not a negligible positive figure (**warning** — catches
  *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take
@@ -160,7 +163,7 @@ function validateEnergyManagerSettingsState(state) {
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
     for (const key of ['batteryControl', 'batteryChargeFromGrid',
-        'blockBatteryDischargeWhileEvDischarging', 'heatpumpControl',
+        'blockBatteryDischargeWhileEvCharging', 'heatpumpControl',
         'heatingRodControl', 'chargerControl']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
@@ -203,6 +206,13 @@ function validateEnergyManagerSettingsState(state) {
                 'any house battery — this field is in watt-hours, not kilowatt-hours.');
         }
     }
+    if (values.blockBatteryDischargeWhileEvCharging === true
+        && typeof values.batteryDischargeWhileChargingWh === 'number'
+        && values.batteryDischargeWhileChargingWh > 0) {
+        warnings.push('`blockBatteryDischargeWhileEvCharging` is true, which closes the tap entirely, so the ' +
+            `\`batteryDischargeWhileChargingWh\` budget of ${values.batteryDischargeWhileChargingWh} Wh ` +
+            'can never be spent. Clear one of the two.');
+    }
     if (values.costOptimizedTargetTime !== undefined) {
         if (typeof values.costOptimizedTargetTime !== 'string'
             || !TIME_RE.test(values.costOptimizedTargetTime)) {

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

@@ -59,6 +59,9 @@ export interface EnergyManagerSettingsValidationResult {
  * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
  *   (**error**), and is not a negligible positive figure (**warning** — catches
  *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take

package/dist/cjs/types/enyo-energy-manager-settings.cjs

@@ -46,8 +46,8 @@ var EnergyManagerSettingEnum;
     EnergyManagerSettingEnum["BatteryChargeFromGrid"] = "battery-charge-from-grid";
     /** How much energy the battery may discharge into a charging vehicle, in Wh. Unset/`null` disables it. */
     EnergyManagerSettingEnum["BatteryDischargeWhileChargingWh"] = "battery-discharge-while-charging-wh";
-    /** Whether the battery is held back while the vehicle discharges into the house (V2H/V2G). */
-    EnergyManagerSettingEnum["BlockBatteryDischargeWhileEvDischarging"] = "block-battery-discharge-while-ev-discharging";
+    /** Hard block on battery discharge into a charging vehicle. Overrides any Wh allowance. */
+    EnergyManagerSettingEnum["BlockBatteryDischargeWhileEvCharging"] = "block-battery-discharge-while-ev-charging";
     // ── Heat pump ──────────────────────────────────────────────────────────
     /** Whether the energy manager may steer the heat pump. */
     EnergyManagerSettingEnum["HeatpumpControl"] = "heatpump-control";
@@ -135,7 +135,7 @@ exports.ENERGY_MANAGER_SETTING_DEPENDENCIES = {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvDischarging]: {
+    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
@@ -168,7 +168,7 @@ exports.ENERGY_MANAGER_SETTING_VALUE_KEYS = {
     [EnergyManagerSettingEnum.BatteryChargingMode]: ['batteryChargingMode'],
     [EnergyManagerSettingEnum.BatteryChargeFromGrid]: ['batteryChargeFromGrid'],
     [EnergyManagerSettingEnum.BatteryDischargeWhileChargingWh]: ['batteryDischargeWhileChargingWh'],
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvDischarging]: ['blockBatteryDischargeWhileEvDischarging'],
+    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: ['blockBatteryDischargeWhileEvCharging'],
     [EnergyManagerSettingEnum.HeatpumpControl]: ['heatpumpControl'],
     [EnergyManagerSettingEnum.HeatingRodControl]: ['heatingRodControl'],
     [EnergyManagerSettingEnum.HeatingRodMode]: ['heatingRodMode'],

package/dist/cjs/types/enyo-energy-manager-settings.d.cts

@@ -42,8 +42,8 @@ export declare enum EnergyManagerSettingEnum {
     BatteryChargeFromGrid = "battery-charge-from-grid",
     /** How much energy the battery may discharge into a charging vehicle, in Wh. Unset/`null` disables it. */
     BatteryDischargeWhileChargingWh = "battery-discharge-while-charging-wh",
-    /** Whether the battery is held back while the vehicle discharges into the house (V2H/V2G). */
-    BlockBatteryDischargeWhileEvDischarging = "block-battery-discharge-while-ev-discharging",
+    /** Hard block on battery discharge into a charging vehicle. Overrides any Wh allowance. */
+    BlockBatteryDischargeWhileEvCharging = "block-battery-discharge-while-ev-charging",
     /** Whether the energy manager may steer the heat pump. */
     HeatpumpControl = "heatpump-control",
     /** Whether the energy manager may steer the heating rod. Gates {@link HeatingRodMode}. */
@@ -144,27 +144,28 @@ export interface EnergyManagerSettingValues {
      */
     batteryDischargeWhileChargingWh?: number | null;
     /**
-     * Whether the house battery is held back while the **vehicle** is
-     * discharging into the house (V2H / V2G).
+     * Whether the house battery is forbidden from discharging into a vehicle
+     * while it charges — a hard block, regardless of any budget.
      *
-     * The mirror image of {@link batteryDischargeWhileChargingWh}, and a
-     * different question: that one governs energy flowing battery → car while
-     * the car charges, this one governs what the battery does while the car is
-     * the one supplying the house.
+     * **This overrides {@link batteryDischargeWhileChargingWh}.** The two govern
+     * the same flow at different strengths: the Wh field is a budget the energy
+     * manager may spend, this one closes the tap. When it is `true`, any
+     * allowance is ignored rather than merged, so a stored budget can never take
+     * effect. `validateEnergyManagerSettingsState()` warns when both are set
+     * that way.
      *
-     * `true` means the car alone covers the load and the battery is preserved
-     * for later — which is usually the point of discharging the car in the first
-     * place. `false` lets both sources serve the house together, draining them
-     * in parallel.
+     * Why both exist: the budget answers "how much", this answers "at all". A
+     * user who wants the battery kept for the house says so once here, and it
+     * keeps holding no matter what number is left over in the allowance field.
      *
-     * Only meaningful while {@link batteryControl} is `true`, and only ever
-     * observable on an installation whose vehicle can discharge at all — on
-     * everything else it simply never applies.
+     * Only meaningful while {@link batteryControl} is `true` — an energy manager
+     * that may not steer the battery cannot hold it back either.
      *
      * As with every field here, `undefined` is not `false`: it means unsupported
-     * or never chosen.
+     * or never chosen, while `false` is the user deciding the battery *may*
+     * contribute.
      */
-    blockBatteryDischargeWhileEvDischarging?: boolean;
+    blockBatteryDischargeWhileEvCharging?: boolean;
     /**
      * Whether the energy manager may steer the heat pump.
      *

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.197';
+exports.SDK_VERSION = '0.0.198';
 /**
  * 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 = "0.0.197";
+export declare const SDK_VERSION = "0.0.198";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/implementations/energy-manager-settings/energy-manager-settings-validators.d.ts

@@ -59,6 +59,9 @@ export interface EnergyManagerSettingsValidationResult {
  * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
  *   (**error**), and is not a negligible positive figure (**warning** — catches
  *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take

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

@@ -112,6 +112,9 @@ function gateValue(values, setting) {
  * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
  *   (**error**), and is not a negligible positive figure (**warning** — catches
  *   a kWh value in a Wh field).
+ * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
+ *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
+ *   the budget, so it could never be spent).
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take
@@ -154,7 +157,7 @@ export function validateEnergyManagerSettingsState(state) {
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
     for (const key of ['batteryControl', 'batteryChargeFromGrid',
-        'blockBatteryDischargeWhileEvDischarging', 'heatpumpControl',
+        'blockBatteryDischargeWhileEvCharging', 'heatpumpControl',
         'heatingRodControl', 'chargerControl']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
@@ -197,6 +200,13 @@ export function validateEnergyManagerSettingsState(state) {
                 'any house battery — this field is in watt-hours, not kilowatt-hours.');
         }
     }
+    if (values.blockBatteryDischargeWhileEvCharging === true
+        && typeof values.batteryDischargeWhileChargingWh === 'number'
+        && values.batteryDischargeWhileChargingWh > 0) {
+        warnings.push('`blockBatteryDischargeWhileEvCharging` is true, which closes the tap entirely, so the ' +
+            `\`batteryDischargeWhileChargingWh\` budget of ${values.batteryDischargeWhileChargingWh} Wh ` +
+            'can never be spent. Clear one of the two.');
+    }
     if (values.costOptimizedTargetTime !== undefined) {
         if (typeof values.costOptimizedTargetTime !== 'string'
             || !TIME_RE.test(values.costOptimizedTargetTime)) {

package/dist/types/enyo-energy-manager-settings.d.ts

@@ -42,8 +42,8 @@ export declare enum EnergyManagerSettingEnum {
     BatteryChargeFromGrid = "battery-charge-from-grid",
     /** How much energy the battery may discharge into a charging vehicle, in Wh. Unset/`null` disables it. */
     BatteryDischargeWhileChargingWh = "battery-discharge-while-charging-wh",
-    /** Whether the battery is held back while the vehicle discharges into the house (V2H/V2G). */
-    BlockBatteryDischargeWhileEvDischarging = "block-battery-discharge-while-ev-discharging",
+    /** Hard block on battery discharge into a charging vehicle. Overrides any Wh allowance. */
+    BlockBatteryDischargeWhileEvCharging = "block-battery-discharge-while-ev-charging",
     /** Whether the energy manager may steer the heat pump. */
     HeatpumpControl = "heatpump-control",
     /** Whether the energy manager may steer the heating rod. Gates {@link HeatingRodMode}. */
@@ -144,27 +144,28 @@ export interface EnergyManagerSettingValues {
      */
     batteryDischargeWhileChargingWh?: number | null;
     /**
-     * Whether the house battery is held back while the **vehicle** is
-     * discharging into the house (V2H / V2G).
+     * Whether the house battery is forbidden from discharging into a vehicle
+     * while it charges — a hard block, regardless of any budget.
      *
-     * The mirror image of {@link batteryDischargeWhileChargingWh}, and a
-     * different question: that one governs energy flowing battery → car while
-     * the car charges, this one governs what the battery does while the car is
-     * the one supplying the house.
+     * **This overrides {@link batteryDischargeWhileChargingWh}.** The two govern
+     * the same flow at different strengths: the Wh field is a budget the energy
+     * manager may spend, this one closes the tap. When it is `true`, any
+     * allowance is ignored rather than merged, so a stored budget can never take
+     * effect. `validateEnergyManagerSettingsState()` warns when both are set
+     * that way.
      *
-     * `true` means the car alone covers the load and the battery is preserved
-     * for later — which is usually the point of discharging the car in the first
-     * place. `false` lets both sources serve the house together, draining them
-     * in parallel.
+     * Why both exist: the budget answers "how much", this answers "at all". A
+     * user who wants the battery kept for the house says so once here, and it
+     * keeps holding no matter what number is left over in the allowance field.
      *
-     * Only meaningful while {@link batteryControl} is `true`, and only ever
-     * observable on an installation whose vehicle can discharge at all — on
-     * everything else it simply never applies.
+     * Only meaningful while {@link batteryControl} is `true` — an energy manager
+     * that may not steer the battery cannot hold it back either.
      *
      * As with every field here, `undefined` is not `false`: it means unsupported
-     * or never chosen.
+     * or never chosen, while `false` is the user deciding the battery *may*
+     * contribute.
      */
-    blockBatteryDischargeWhileEvDischarging?: boolean;
+    blockBatteryDischargeWhileEvCharging?: boolean;
     /**
      * Whether the energy manager may steer the heat pump.
      *

package/dist/types/enyo-energy-manager-settings.js

@@ -43,8 +43,8 @@ export var EnergyManagerSettingEnum;
     EnergyManagerSettingEnum["BatteryChargeFromGrid"] = "battery-charge-from-grid";
     /** How much energy the battery may discharge into a charging vehicle, in Wh. Unset/`null` disables it. */
     EnergyManagerSettingEnum["BatteryDischargeWhileChargingWh"] = "battery-discharge-while-charging-wh";
-    /** Whether the battery is held back while the vehicle discharges into the house (V2H/V2G). */
-    EnergyManagerSettingEnum["BlockBatteryDischargeWhileEvDischarging"] = "block-battery-discharge-while-ev-discharging";
+    /** Hard block on battery discharge into a charging vehicle. Overrides any Wh allowance. */
+    EnergyManagerSettingEnum["BlockBatteryDischargeWhileEvCharging"] = "block-battery-discharge-while-ev-charging";
     // ── Heat pump ──────────────────────────────────────────────────────────
     /** Whether the energy manager may steer the heat pump. */
     EnergyManagerSettingEnum["HeatpumpControl"] = "heatpump-control";
@@ -132,7 +132,7 @@ export const ENERGY_MANAGER_SETTING_DEPENDENCIES = {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvDischarging]: {
+    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
@@ -165,7 +165,7 @@ export const ENERGY_MANAGER_SETTING_VALUE_KEYS = {
     [EnergyManagerSettingEnum.BatteryChargingMode]: ['batteryChargingMode'],
     [EnergyManagerSettingEnum.BatteryChargeFromGrid]: ['batteryChargeFromGrid'],
     [EnergyManagerSettingEnum.BatteryDischargeWhileChargingWh]: ['batteryDischargeWhileChargingWh'],
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvDischarging]: ['blockBatteryDischargeWhileEvDischarging'],
+    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: ['blockBatteryDischargeWhileEvCharging'],
     [EnergyManagerSettingEnum.HeatpumpControl]: ['heatpumpControl'],
     [EnergyManagerSettingEnum.HeatingRodControl]: ['heatingRodControl'],
     [EnergyManagerSettingEnum.HeatingRodMode]: ['heatingRodMode'],

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.197";
+export declare const SDK_VERSION = "0.0.198";
 /**
  * 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 = '0.0.197';
+export const SDK_VERSION = '0.0.198';
 /**
  * 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": "0.0.197",
+  "version": "0.0.198",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",