@enyo-energy/energy-app-sdk 0.0.100 → 0.0.102

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

@@ -12,7 +12,7 @@ export interface EnergyAppDiagnostics {
      *   system-level power values, per-appliance snapshots, and derived energy values
      * @param forecast - The forecast containing time-bucketed predictions for consumption,
      *   production, pricing, and appliance-specific data
-     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     * @param controlPlan - The time-slotted control plan with actions for each appliance
      *   and estimated costs
      *
      * @example

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

@@ -26,23 +26,29 @@ export interface EnergyAppEnergyManager {
     registerFeatures(features: EnergyManagerFeatureEnum[]): void;
     /**
      * Only for Energy Manager Energy Apps: Publishes the energy manager's control plan forecast.
-     * The control plan contains time-slotted commands for each appliance along with
+     * The control plan contains time-slotted actions for each appliance along with
      * estimated costs and grid power values.
      *
-     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     * @param controlPlan - The time-slotted control plan with actions for each appliance
      *   and estimated costs
      *
      * @example
      * ```typescript
      * const energyManager = energyApp.useEnergyManager();
      * energyManager.publishForecast({
-     *     commands: [
+     *     actions: [
      *         {
+     *             action: EnyoDiagnosticsControlActionEnum.BatteryChargeFromGrid,
      *             type: EnyoApplianceTypeEnum.Storage,
      *             applianceId: 'battery-1',
-     *             decision: BatteryDecision.Charge,
+     *             timestampIso: new Date().toISOString(),
+     *             isCommand: true,
      *             powerW: 3000,
-     *             durationInMinutes: 60
+     *             durationInMinutes: 60,
+     *             reason: {
+     *                 type: EnyoDiagnosticsActionReasonTypeEnum.ElectricityPriceBelowThreshold,
+     *                 electricityPricePerKwh: 0.15,
+     *             }
      *         }
      *     ],
      *     generatedAtIso: new Date().toISOString(),

package/dist/cjs/types/enyo-diagnostics.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoDiagnosticsPriceTableSourceEnum = void 0;
+exports.EnyoDiagnosticsActionReasonTypeEnum = exports.EnyoDiagnosticsControlActionEnum = exports.EnyoDiagnosticsPriceTableSourceEnum = void 0;
 // ─── Price table types ────────────────────────────────────
 /** Energy source type for price table entries. */
 var EnyoDiagnosticsPriceTableSourceEnum;
@@ -9,3 +9,66 @@ var EnyoDiagnosticsPriceTableSourceEnum;
     EnyoDiagnosticsPriceTableSourceEnum["Battery"] = "battery";
     EnyoDiagnosticsPriceTableSourceEnum["Grid"] = "grid";
 })(EnyoDiagnosticsPriceTableSourceEnum || (exports.EnyoDiagnosticsPriceTableSourceEnum = EnyoDiagnosticsPriceTableSourceEnum = {}));
+// ─── Action-based control plan ──────────────────────────────
+/**
+ * Enum of all control plan action types.
+ * Each value represents a specific action the energy manager can plan for an appliance.
+ */
+var EnyoDiagnosticsControlActionEnum;
+(function (EnyoDiagnosticsControlActionEnum) {
+    /** Block the battery from discharging. */
+    EnyoDiagnosticsControlActionEnum["BatteryBlockDischarge"] = "battery_block_discharge";
+    /** Charge the battery from the grid. */
+    EnyoDiagnosticsControlActionEnum["BatteryChargeFromGrid"] = "battery_charge_from_grid";
+    /** Force the battery to discharge. */
+    EnyoDiagnosticsControlActionEnum["BatteryForceDischarge"] = "battery_force_discharge";
+    /** Battery is charging from PV surplus (observational, not a command). */
+    EnyoDiagnosticsControlActionEnum["BatteryChargingFromPv"] = "battery_charging_from_pv";
+    /** Battery is discharging into the home (observational, not a command). */
+    EnyoDiagnosticsControlActionEnum["BatteryDischargingIntoHome"] = "battery_discharging_into_home";
+    /** Start charging the EV. */
+    EnyoDiagnosticsControlActionEnum["EvStartCharge"] = "ev_start_charge";
+    /** Pause charging the EV. */
+    EnyoDiagnosticsControlActionEnum["EvPauseCharge"] = "ev_pause_charge";
+    /** Boost domestic hot water production via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpDhwBoost"] = "heatpump_dhw_boost";
+    /** Address room overheating via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpRoomOverheating"] = "heatpump_room_overheating";
+    /** Boost buffer tank temperature via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpBufferTankBoost"] = "heatpump_buffer_tank_boost";
+})(EnyoDiagnosticsControlActionEnum || (exports.EnyoDiagnosticsControlActionEnum = EnyoDiagnosticsControlActionEnum = {}));
+/**
+ * Enum of reason types explaining why an action was planned.
+ * Used to attach context to actions for logging, debugging, and UI display.
+ */
+var EnyoDiagnosticsActionReasonTypeEnum;
+(function (EnyoDiagnosticsActionReasonTypeEnum) {
+    /** Action planned because the electricity price is below a configured threshold. */
+    EnyoDiagnosticsActionReasonTypeEnum["ElectricityPriceBelowThreshold"] = "electricity-price-below-threshold";
+    /** Action planned because the electricity price is above a configured threshold. */
+    EnyoDiagnosticsActionReasonTypeEnum["ElectricityPriceAboveThreshold"] = "electricity-price-above-threshold";
+    /** Action planned because PV surplus is available. */
+    EnyoDiagnosticsActionReasonTypeEnum["PvSurplusAvailable"] = "pv-surplus-available";
+    /** Action planned because PV surplus is unavailable. */
+    EnyoDiagnosticsActionReasonTypeEnum["PvSurplusUnavailable"] = "pv-surplus-unavailable";
+    /** Action planned because battery capacity is available. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
+    /** Action planned because battery capacity is unavailable. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatteryCapacityUnavailable"] = "battery-capacity-unavailable";
+    /** Action planned because the battery state of charge is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Action planned because the battery state of charge is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Action planned based on the EV charging schedule. */
+    EnyoDiagnosticsActionReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Action planned because of a grid operator power limitation. */
+    EnyoDiagnosticsActionReasonTypeEnum["GridOperatorPowerLimitation"] = "grid-operator-power-limitation";
+    /** Action planned because the DHW temperature is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["DhwTemperatureLow"] = "dhw-temperature-low";
+    /** Action planned because the room temperature is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["RoomTemperatureHigh"] = "room-temperature-high";
+    /** Action planned because the buffer tank temperature is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["BufferTankTemperatureLow"] = "buffer-tank-temperature-low";
+    /** Action planned because the home consumption is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+})(EnyoDiagnosticsActionReasonTypeEnum || (exports.EnyoDiagnosticsActionReasonTypeEnum = EnyoDiagnosticsActionReasonTypeEnum = {}));

package/dist/cjs/types/enyo-diagnostics.d.cts

@@ -1,4 +1,5 @@
 import { EnyoApplianceTypeEnum } from "./enyo-appliance.cjs";
+import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoChargeModeEnum } from "./enyo-data-bus-value.cjs";
 /** Energy source type for price table entries. */
 export declare enum EnyoDiagnosticsPriceTableSourceEnum {
@@ -19,12 +20,6 @@ export interface EnyoDiagnosticsPriceTableEntry {
 export type DhwState = "charging" | "discharging" | "idle";
 /** Heating circuit state. */
 export type HeatingState = "active" | "idle";
-/** Battery control decision issued by the energy manager. */
-export type BatteryDecision = "block_discharge" | "charge_from_grid" | "force_discharge";
-/** EV charging control decision issued by the energy manager. */
-export type EvDecision = "charging_pv" | "charging_grid" | "charging_mixed";
-/** Heat pump control decision issued by the energy manager. */
-export type HeatpumpDecision = "dhw_boost" | "room_overheating" | "buffer_tank_boost";
 export interface EnyoDiagnosticsForecastInverterAppliance {
     type: EnyoApplianceTypeEnum.Inverter;
     applianceId: string;
@@ -154,60 +149,220 @@ export interface EnyoDiagnosticsForecast {
     /** Total estimated grid export in kWh. */
     totalGridExportKwh: number;
 }
-/** Battery control command for a specific appliance. */
-export interface EnyoDiagnosticsStorageControlCommand {
-    type: EnyoApplianceTypeEnum.Storage;
+/**
+ * Enum of all control plan action types.
+ * Each value represents a specific action the energy manager can plan for an appliance.
+ */
+export declare enum EnyoDiagnosticsControlActionEnum {
+    /** Block the battery from discharging. */
+    BatteryBlockDischarge = "battery_block_discharge",
+    /** Charge the battery from the grid. */
+    BatteryChargeFromGrid = "battery_charge_from_grid",
+    /** Force the battery to discharge. */
+    BatteryForceDischarge = "battery_force_discharge",
+    /** Battery is charging from PV surplus (observational, not a command). */
+    BatteryChargingFromPv = "battery_charging_from_pv",
+    /** Battery is discharging into the home (observational, not a command). */
+    BatteryDischargingIntoHome = "battery_discharging_into_home",
+    /** Start charging the EV. */
+    EvStartCharge = "ev_start_charge",
+    /** Pause charging the EV. */
+    EvPauseCharge = "ev_pause_charge",
+    /** Boost domestic hot water production via heat pump. */
+    HeatpumpDhwBoost = "heatpump_dhw_boost",
+    /** Address room overheating via heat pump. */
+    HeatpumpRoomOverheating = "heatpump_room_overheating",
+    /** Boost buffer tank temperature via heat pump. */
+    HeatpumpBufferTankBoost = "heatpump_buffer_tank_boost"
+}
+/**
+ * Enum of reason types explaining why an action was planned.
+ * Used to attach context to actions for logging, debugging, and UI display.
+ */
+export declare enum EnyoDiagnosticsActionReasonTypeEnum {
+    /** Action planned because the electricity price is below a configured threshold. */
+    ElectricityPriceBelowThreshold = "electricity-price-below-threshold",
+    /** Action planned because the electricity price is above a configured threshold. */
+    ElectricityPriceAboveThreshold = "electricity-price-above-threshold",
+    /** Action planned because PV surplus is available. */
+    PvSurplusAvailable = "pv-surplus-available",
+    /** Action planned because PV surplus is unavailable. */
+    PvSurplusUnavailable = "pv-surplus-unavailable",
+    /** Action planned because battery capacity is available. */
+    BatteryCapacityAvailable = "battery-capacity-available",
+    /** Action planned because battery capacity is unavailable. */
+    BatteryCapacityUnavailable = "battery-capacity-unavailable",
+    /** Action planned because the battery state of charge is low. */
+    BatterySoCLow = "battery-soc-low",
+    /** Action planned because the battery state of charge is high. */
+    BatterySoCHigh = "battery-soc-high",
+    /** Action planned based on the EV charging schedule. */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Action planned because of a grid operator power limitation. */
+    GridOperatorPowerLimitation = "grid-operator-power-limitation",
+    /** Action planned because the DHW temperature is low. */
+    DhwTemperatureLow = "dhw-temperature-low",
+    /** Action planned because the room temperature is high. */
+    RoomTemperatureHigh = "room-temperature-high",
+    /** Action planned because the buffer tank temperature is low. */
+    BufferTankTemperatureLow = "buffer-tank-temperature-low",
+    /** Action planned because the home consumption is high. */
+    HomeConsumptionHigh = "home-consumption-high"
+}
+/**
+ * Structured reason explaining why an action was planned.
+ * Provides context such as pricing information, capacity, power, or temperature values.
+ */
+export interface EnyoDiagnosticsActionReason {
+    /** The reason type indicating why this action was planned. */
+    type: EnyoDiagnosticsActionReasonTypeEnum;
+    /** Electricity price per kWh that influenced this action. */
+    electricityPricePerKwh?: number;
+    /** Currency of the electricity price. */
+    currency?: EnyoCurrencyEnum;
+    /** Relevant capacity in kWh. */
+    capacityKwh?: number;
+    /** Relevant power in Watts. */
+    powerW?: number;
+    /** Relevant temperature in Celsius. */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage. */
+    socPercent?: number;
+}
+/**
+ * Base interface for all control plan actions.
+ * Each specific action interface extends this with narrowed discriminant fields.
+ */
+export interface EnyoDiagnosticsControlActionBase {
+    /** Discriminant identifying the specific action type. */
+    action: EnyoDiagnosticsControlActionEnum;
+    /** Appliance type this action applies to. */
+    type: EnyoApplianceTypeEnum;
     /** Target appliance ID. */
     applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
+    /** ISO 8601 timestamp when this action starts. */
     timestampIso: string;
-    /** Control decision for the battery. */
-    decision: BatteryDecision;
+    /** Duration of this action in minutes. */
+    durationInMinutes: number;
+    /** Whether this action sends a command to hardware ({@code true}) or is observational ({@code false}). */
+    isCommand: boolean;
+    /** Reason why this action was planned. */
+    reason: EnyoDiagnosticsActionReason;
+}
+/** Battery action: block the battery from discharging. */
+export interface EnyoDiagnosticsStorageBlockDischargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryBlockDischarge;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target state of charge as a percentage. */
+    targetSoCPercent?: number;
+}
+/** Battery action: charge the battery from the grid. */
+export interface EnyoDiagnosticsStorageChargeFromGridAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryChargeFromGrid;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target state of charge as a percentage. */
+    targetSoCPercent?: number;
+}
+/** Battery action: force the battery to discharge. */
+export interface EnyoDiagnosticsStorageForceDischargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryForceDischarge;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
     /** Target power in Watts. */
     powerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional target state of charge as a percentage. */
     targetSoCPercent?: number;
 }
-/** EV charger control command for a specific appliance. */
-export interface EnyoDiagnosticsChargerControlCommand {
+/** Battery action: battery is charging from PV surplus (observational, not a command). */
+export interface EnyoDiagnosticsStorageChargingFromPvAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryChargingFromPv;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: false;
+    /** Power in Watts being charged from PV. */
+    powerW: number;
+    /** Current state of charge as a percentage. */
+    socPercent?: number;
+}
+/** Battery action: battery is discharging into the home (observational, not a command). */
+export interface EnyoDiagnosticsStorageDischargingIntoHomeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryDischargingIntoHome;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: false;
+    /** Power in Watts being discharged into the home. */
+    powerW: number;
+    /** Current state of charge as a percentage. */
+    socPercent?: number;
+}
+/** EV charger action: start charging the EV. */
+export interface EnyoDiagnosticsChargerStartChargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.EvStartCharge;
     type: EnyoApplianceTypeEnum.Charger;
-    /** Target appliance ID. */
-    applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
-    timestampIso: string;
-    /** Control decision for the EV charger. */
-    decision: EvDecision;
+    isCommand: true;
     /** Charging power in Watts. */
     chargingPowerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional charging limit in kW. */
     chargingLimitKw?: number;
 }
-/** Heat pump control command for a specific appliance. */
-export interface EnyoDiagnosticsHeatpumpControlCommand {
+/** EV charger action: pause charging the EV. */
+export interface EnyoDiagnosticsChargerPauseChargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.EvPauseCharge;
+    type: EnyoApplianceTypeEnum.Charger;
+    isCommand: true;
+}
+/** Heatpump action: boost domestic hot water production. */
+export interface EnyoDiagnosticsHeatpumpDhwBoostAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpDhwBoost;
     type: EnyoApplianceTypeEnum.Heatpump;
-    /** Target appliance ID. */
-    applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
-    timestampIso: string;
-    /** Control decision for the heat pump. */
-    decision: HeatpumpDecision;
+    isCommand: true;
     /** Target power in Watts. */
     powerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional target temperature in Celsius. */
     targetTempC?: number;
+    /** Optional current domestic hot water temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
+}
+/** Heatpump action: address room overheating. */
+export interface EnyoDiagnosticsHeatpumpRoomOverheatingAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpRoomOverheating;
+    type: EnyoApplianceTypeEnum.Heatpump;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target temperature in Celsius. */
+    targetTempC?: number;
+    /** Optional current room temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
+}
+/** Heatpump action: boost buffer tank temperature. */
+export interface EnyoDiagnosticsHeatpumpBufferTankBoostAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpBufferTankBoost;
+    type: EnyoApplianceTypeEnum.Heatpump;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target temperature in Celsius. */
+    targetTempC?: number;
+    /** Optional current room temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
 }
-/** Union of all appliance control command types. */
-export type EnyoDiagnosticsApplianceControlCommand = EnyoDiagnosticsStorageControlCommand | EnyoDiagnosticsChargerControlCommand | EnyoDiagnosticsHeatpumpControlCommand;
-/** Complete control plan with duration-based commands and cost estimates. */
+/** Union of all control plan action types. */
+export type EnyoDiagnosticsControlAction = EnyoDiagnosticsStorageBlockDischargeAction | EnyoDiagnosticsStorageChargeFromGridAction | EnyoDiagnosticsStorageForceDischargeAction | EnyoDiagnosticsStorageChargingFromPvAction | EnyoDiagnosticsStorageDischargingIntoHomeAction | EnyoDiagnosticsChargerStartChargeAction | EnyoDiagnosticsChargerPauseChargeAction | EnyoDiagnosticsHeatpumpDhwBoostAction | EnyoDiagnosticsHeatpumpRoomOverheatingAction | EnyoDiagnosticsHeatpumpBufferTankBoostAction;
+/** Complete control plan with duration-based actions and cost estimates. */
 export interface EnyoDiagnosticsControlPlan {
-    /** Sequence of appliance control commands, each with its own duration. */
-    commands: EnyoDiagnosticsApplianceControlCommand[];
+    /** Sequence of planned actions, each with its own duration. */
+    actions: EnyoDiagnosticsControlAction[];
     /** ISO 8601 timestamp when this plan was generated. */
     generatedAtIso: string;
     /** Total estimated cost in EUR. */

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.100';
+exports.SDK_VERSION = '0.0.102';
 /**
  * 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.100";
+export declare const SDK_VERSION = "0.0.102";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/packages/energy-app-diagnostics.d.ts

@@ -12,7 +12,7 @@ export interface EnergyAppDiagnostics {
      *   system-level power values, per-appliance snapshots, and derived energy values
      * @param forecast - The forecast containing time-bucketed predictions for consumption,
      *   production, pricing, and appliance-specific data
-     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     * @param controlPlan - The time-slotted control plan with actions for each appliance
      *   and estimated costs
      *
      * @example

package/dist/packages/energy-app-energy-manager.d.ts

@@ -26,23 +26,29 @@ export interface EnergyAppEnergyManager {
     registerFeatures(features: EnergyManagerFeatureEnum[]): void;
     /**
      * Only for Energy Manager Energy Apps: Publishes the energy manager's control plan forecast.
-     * The control plan contains time-slotted commands for each appliance along with
+     * The control plan contains time-slotted actions for each appliance along with
      * estimated costs and grid power values.
      *
-     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     * @param controlPlan - The time-slotted control plan with actions for each appliance
      *   and estimated costs
      *
      * @example
      * ```typescript
      * const energyManager = energyApp.useEnergyManager();
      * energyManager.publishForecast({
-     *     commands: [
+     *     actions: [
      *         {
+     *             action: EnyoDiagnosticsControlActionEnum.BatteryChargeFromGrid,
      *             type: EnyoApplianceTypeEnum.Storage,
      *             applianceId: 'battery-1',
-     *             decision: BatteryDecision.Charge,
+     *             timestampIso: new Date().toISOString(),
+     *             isCommand: true,
      *             powerW: 3000,
-     *             durationInMinutes: 60
+     *             durationInMinutes: 60,
+     *             reason: {
+     *                 type: EnyoDiagnosticsActionReasonTypeEnum.ElectricityPriceBelowThreshold,
+     *                 electricityPricePerKwh: 0.15,
+     *             }
      *         }
      *     ],
      *     generatedAtIso: new Date().toISOString(),

package/dist/types/enyo-diagnostics.d.ts

@@ -1,4 +1,5 @@
 import { EnyoApplianceTypeEnum } from "./enyo-appliance.js";
+import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoChargeModeEnum } from "./enyo-data-bus-value.js";
 /** Energy source type for price table entries. */
 export declare enum EnyoDiagnosticsPriceTableSourceEnum {
@@ -19,12 +20,6 @@ export interface EnyoDiagnosticsPriceTableEntry {
 export type DhwState = "charging" | "discharging" | "idle";
 /** Heating circuit state. */
 export type HeatingState = "active" | "idle";
-/** Battery control decision issued by the energy manager. */
-export type BatteryDecision = "block_discharge" | "charge_from_grid" | "force_discharge";
-/** EV charging control decision issued by the energy manager. */
-export type EvDecision = "charging_pv" | "charging_grid" | "charging_mixed";
-/** Heat pump control decision issued by the energy manager. */
-export type HeatpumpDecision = "dhw_boost" | "room_overheating" | "buffer_tank_boost";
 export interface EnyoDiagnosticsForecastInverterAppliance {
     type: EnyoApplianceTypeEnum.Inverter;
     applianceId: string;
@@ -154,60 +149,220 @@ export interface EnyoDiagnosticsForecast {
     /** Total estimated grid export in kWh. */
     totalGridExportKwh: number;
 }
-/** Battery control command for a specific appliance. */
-export interface EnyoDiagnosticsStorageControlCommand {
-    type: EnyoApplianceTypeEnum.Storage;
+/**
+ * Enum of all control plan action types.
+ * Each value represents a specific action the energy manager can plan for an appliance.
+ */
+export declare enum EnyoDiagnosticsControlActionEnum {
+    /** Block the battery from discharging. */
+    BatteryBlockDischarge = "battery_block_discharge",
+    /** Charge the battery from the grid. */
+    BatteryChargeFromGrid = "battery_charge_from_grid",
+    /** Force the battery to discharge. */
+    BatteryForceDischarge = "battery_force_discharge",
+    /** Battery is charging from PV surplus (observational, not a command). */
+    BatteryChargingFromPv = "battery_charging_from_pv",
+    /** Battery is discharging into the home (observational, not a command). */
+    BatteryDischargingIntoHome = "battery_discharging_into_home",
+    /** Start charging the EV. */
+    EvStartCharge = "ev_start_charge",
+    /** Pause charging the EV. */
+    EvPauseCharge = "ev_pause_charge",
+    /** Boost domestic hot water production via heat pump. */
+    HeatpumpDhwBoost = "heatpump_dhw_boost",
+    /** Address room overheating via heat pump. */
+    HeatpumpRoomOverheating = "heatpump_room_overheating",
+    /** Boost buffer tank temperature via heat pump. */
+    HeatpumpBufferTankBoost = "heatpump_buffer_tank_boost"
+}
+/**
+ * Enum of reason types explaining why an action was planned.
+ * Used to attach context to actions for logging, debugging, and UI display.
+ */
+export declare enum EnyoDiagnosticsActionReasonTypeEnum {
+    /** Action planned because the electricity price is below a configured threshold. */
+    ElectricityPriceBelowThreshold = "electricity-price-below-threshold",
+    /** Action planned because the electricity price is above a configured threshold. */
+    ElectricityPriceAboveThreshold = "electricity-price-above-threshold",
+    /** Action planned because PV surplus is available. */
+    PvSurplusAvailable = "pv-surplus-available",
+    /** Action planned because PV surplus is unavailable. */
+    PvSurplusUnavailable = "pv-surplus-unavailable",
+    /** Action planned because battery capacity is available. */
+    BatteryCapacityAvailable = "battery-capacity-available",
+    /** Action planned because battery capacity is unavailable. */
+    BatteryCapacityUnavailable = "battery-capacity-unavailable",
+    /** Action planned because the battery state of charge is low. */
+    BatterySoCLow = "battery-soc-low",
+    /** Action planned because the battery state of charge is high. */
+    BatterySoCHigh = "battery-soc-high",
+    /** Action planned based on the EV charging schedule. */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Action planned because of a grid operator power limitation. */
+    GridOperatorPowerLimitation = "grid-operator-power-limitation",
+    /** Action planned because the DHW temperature is low. */
+    DhwTemperatureLow = "dhw-temperature-low",
+    /** Action planned because the room temperature is high. */
+    RoomTemperatureHigh = "room-temperature-high",
+    /** Action planned because the buffer tank temperature is low. */
+    BufferTankTemperatureLow = "buffer-tank-temperature-low",
+    /** Action planned because the home consumption is high. */
+    HomeConsumptionHigh = "home-consumption-high"
+}
+/**
+ * Structured reason explaining why an action was planned.
+ * Provides context such as pricing information, capacity, power, or temperature values.
+ */
+export interface EnyoDiagnosticsActionReason {
+    /** The reason type indicating why this action was planned. */
+    type: EnyoDiagnosticsActionReasonTypeEnum;
+    /** Electricity price per kWh that influenced this action. */
+    electricityPricePerKwh?: number;
+    /** Currency of the electricity price. */
+    currency?: EnyoCurrencyEnum;
+    /** Relevant capacity in kWh. */
+    capacityKwh?: number;
+    /** Relevant power in Watts. */
+    powerW?: number;
+    /** Relevant temperature in Celsius. */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage. */
+    socPercent?: number;
+}
+/**
+ * Base interface for all control plan actions.
+ * Each specific action interface extends this with narrowed discriminant fields.
+ */
+export interface EnyoDiagnosticsControlActionBase {
+    /** Discriminant identifying the specific action type. */
+    action: EnyoDiagnosticsControlActionEnum;
+    /** Appliance type this action applies to. */
+    type: EnyoApplianceTypeEnum;
     /** Target appliance ID. */
     applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
+    /** ISO 8601 timestamp when this action starts. */
     timestampIso: string;
-    /** Control decision for the battery. */
-    decision: BatteryDecision;
+    /** Duration of this action in minutes. */
+    durationInMinutes: number;
+    /** Whether this action sends a command to hardware ({@code true}) or is observational ({@code false}). */
+    isCommand: boolean;
+    /** Reason why this action was planned. */
+    reason: EnyoDiagnosticsActionReason;
+}
+/** Battery action: block the battery from discharging. */
+export interface EnyoDiagnosticsStorageBlockDischargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryBlockDischarge;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target state of charge as a percentage. */
+    targetSoCPercent?: number;
+}
+/** Battery action: charge the battery from the grid. */
+export interface EnyoDiagnosticsStorageChargeFromGridAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryChargeFromGrid;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target state of charge as a percentage. */
+    targetSoCPercent?: number;
+}
+/** Battery action: force the battery to discharge. */
+export interface EnyoDiagnosticsStorageForceDischargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryForceDischarge;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: true;
     /** Target power in Watts. */
     powerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional target state of charge as a percentage. */
     targetSoCPercent?: number;
 }
-/** EV charger control command for a specific appliance. */
-export interface EnyoDiagnosticsChargerControlCommand {
+/** Battery action: battery is charging from PV surplus (observational, not a command). */
+export interface EnyoDiagnosticsStorageChargingFromPvAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryChargingFromPv;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: false;
+    /** Power in Watts being charged from PV. */
+    powerW: number;
+    /** Current state of charge as a percentage. */
+    socPercent?: number;
+}
+/** Battery action: battery is discharging into the home (observational, not a command). */
+export interface EnyoDiagnosticsStorageDischargingIntoHomeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.BatteryDischargingIntoHome;
+    type: EnyoApplianceTypeEnum.Storage;
+    isCommand: false;
+    /** Power in Watts being discharged into the home. */
+    powerW: number;
+    /** Current state of charge as a percentage. */
+    socPercent?: number;
+}
+/** EV charger action: start charging the EV. */
+export interface EnyoDiagnosticsChargerStartChargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.EvStartCharge;
     type: EnyoApplianceTypeEnum.Charger;
-    /** Target appliance ID. */
-    applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
-    timestampIso: string;
-    /** Control decision for the EV charger. */
-    decision: EvDecision;
+    isCommand: true;
     /** Charging power in Watts. */
     chargingPowerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional charging limit in kW. */
     chargingLimitKw?: number;
 }
-/** Heat pump control command for a specific appliance. */
-export interface EnyoDiagnosticsHeatpumpControlCommand {
+/** EV charger action: pause charging the EV. */
+export interface EnyoDiagnosticsChargerPauseChargeAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.EvPauseCharge;
+    type: EnyoApplianceTypeEnum.Charger;
+    isCommand: true;
+}
+/** Heatpump action: boost domestic hot water production. */
+export interface EnyoDiagnosticsHeatpumpDhwBoostAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpDhwBoost;
     type: EnyoApplianceTypeEnum.Heatpump;
-    /** Target appliance ID. */
-    applianceId: string;
-    /** ISO 8601 timestamp when this command starts. */
-    timestampIso: string;
-    /** Control decision for the heat pump. */
-    decision: HeatpumpDecision;
+    isCommand: true;
     /** Target power in Watts. */
     powerW: number;
-    /** Duration of this command in minutes. */
-    durationInMinutes: number;
     /** Optional target temperature in Celsius. */
     targetTempC?: number;
+    /** Optional current domestic hot water temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
+}
+/** Heatpump action: address room overheating. */
+export interface EnyoDiagnosticsHeatpumpRoomOverheatingAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpRoomOverheating;
+    type: EnyoApplianceTypeEnum.Heatpump;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target temperature in Celsius. */
+    targetTempC?: number;
+    /** Optional current room temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
+}
+/** Heatpump action: boost buffer tank temperature. */
+export interface EnyoDiagnosticsHeatpumpBufferTankBoostAction extends EnyoDiagnosticsControlActionBase {
+    action: EnyoDiagnosticsControlActionEnum.HeatpumpBufferTankBoost;
+    type: EnyoApplianceTypeEnum.Heatpump;
+    isCommand: true;
+    /** Target power in Watts. */
+    powerW: number;
+    /** Optional target temperature in Celsius. */
+    targetTempC?: number;
+    /** Optional current room temperature in Celsius. */
+    currentTemperatureC?: number;
+    /** Optional current outdoor temperature in Celsius. */
+    outdoorTemperatureC?: number;
 }
-/** Union of all appliance control command types. */
-export type EnyoDiagnosticsApplianceControlCommand = EnyoDiagnosticsStorageControlCommand | EnyoDiagnosticsChargerControlCommand | EnyoDiagnosticsHeatpumpControlCommand;
-/** Complete control plan with duration-based commands and cost estimates. */
+/** Union of all control plan action types. */
+export type EnyoDiagnosticsControlAction = EnyoDiagnosticsStorageBlockDischargeAction | EnyoDiagnosticsStorageChargeFromGridAction | EnyoDiagnosticsStorageForceDischargeAction | EnyoDiagnosticsStorageChargingFromPvAction | EnyoDiagnosticsStorageDischargingIntoHomeAction | EnyoDiagnosticsChargerStartChargeAction | EnyoDiagnosticsChargerPauseChargeAction | EnyoDiagnosticsHeatpumpDhwBoostAction | EnyoDiagnosticsHeatpumpRoomOverheatingAction | EnyoDiagnosticsHeatpumpBufferTankBoostAction;
+/** Complete control plan with duration-based actions and cost estimates. */
 export interface EnyoDiagnosticsControlPlan {
-    /** Sequence of appliance control commands, each with its own duration. */
-    commands: EnyoDiagnosticsApplianceControlCommand[];
+    /** Sequence of planned actions, each with its own duration. */
+    actions: EnyoDiagnosticsControlAction[];
     /** ISO 8601 timestamp when this plan was generated. */
     generatedAtIso: string;
     /** Total estimated cost in EUR. */

package/dist/types/enyo-diagnostics.js

@@ -6,3 +6,66 @@ export var EnyoDiagnosticsPriceTableSourceEnum;
     EnyoDiagnosticsPriceTableSourceEnum["Battery"] = "battery";
     EnyoDiagnosticsPriceTableSourceEnum["Grid"] = "grid";
 })(EnyoDiagnosticsPriceTableSourceEnum || (EnyoDiagnosticsPriceTableSourceEnum = {}));
+// ─── Action-based control plan ──────────────────────────────
+/**
+ * Enum of all control plan action types.
+ * Each value represents a specific action the energy manager can plan for an appliance.
+ */
+export var EnyoDiagnosticsControlActionEnum;
+(function (EnyoDiagnosticsControlActionEnum) {
+    /** Block the battery from discharging. */
+    EnyoDiagnosticsControlActionEnum["BatteryBlockDischarge"] = "battery_block_discharge";
+    /** Charge the battery from the grid. */
+    EnyoDiagnosticsControlActionEnum["BatteryChargeFromGrid"] = "battery_charge_from_grid";
+    /** Force the battery to discharge. */
+    EnyoDiagnosticsControlActionEnum["BatteryForceDischarge"] = "battery_force_discharge";
+    /** Battery is charging from PV surplus (observational, not a command). */
+    EnyoDiagnosticsControlActionEnum["BatteryChargingFromPv"] = "battery_charging_from_pv";
+    /** Battery is discharging into the home (observational, not a command). */
+    EnyoDiagnosticsControlActionEnum["BatteryDischargingIntoHome"] = "battery_discharging_into_home";
+    /** Start charging the EV. */
+    EnyoDiagnosticsControlActionEnum["EvStartCharge"] = "ev_start_charge";
+    /** Pause charging the EV. */
+    EnyoDiagnosticsControlActionEnum["EvPauseCharge"] = "ev_pause_charge";
+    /** Boost domestic hot water production via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpDhwBoost"] = "heatpump_dhw_boost";
+    /** Address room overheating via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpRoomOverheating"] = "heatpump_room_overheating";
+    /** Boost buffer tank temperature via heat pump. */
+    EnyoDiagnosticsControlActionEnum["HeatpumpBufferTankBoost"] = "heatpump_buffer_tank_boost";
+})(EnyoDiagnosticsControlActionEnum || (EnyoDiagnosticsControlActionEnum = {}));
+/**
+ * Enum of reason types explaining why an action was planned.
+ * Used to attach context to actions for logging, debugging, and UI display.
+ */
+export var EnyoDiagnosticsActionReasonTypeEnum;
+(function (EnyoDiagnosticsActionReasonTypeEnum) {
+    /** Action planned because the electricity price is below a configured threshold. */
+    EnyoDiagnosticsActionReasonTypeEnum["ElectricityPriceBelowThreshold"] = "electricity-price-below-threshold";
+    /** Action planned because the electricity price is above a configured threshold. */
+    EnyoDiagnosticsActionReasonTypeEnum["ElectricityPriceAboveThreshold"] = "electricity-price-above-threshold";
+    /** Action planned because PV surplus is available. */
+    EnyoDiagnosticsActionReasonTypeEnum["PvSurplusAvailable"] = "pv-surplus-available";
+    /** Action planned because PV surplus is unavailable. */
+    EnyoDiagnosticsActionReasonTypeEnum["PvSurplusUnavailable"] = "pv-surplus-unavailable";
+    /** Action planned because battery capacity is available. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
+    /** Action planned because battery capacity is unavailable. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatteryCapacityUnavailable"] = "battery-capacity-unavailable";
+    /** Action planned because the battery state of charge is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Action planned because the battery state of charge is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Action planned based on the EV charging schedule. */
+    EnyoDiagnosticsActionReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Action planned because of a grid operator power limitation. */
+    EnyoDiagnosticsActionReasonTypeEnum["GridOperatorPowerLimitation"] = "grid-operator-power-limitation";
+    /** Action planned because the DHW temperature is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["DhwTemperatureLow"] = "dhw-temperature-low";
+    /** Action planned because the room temperature is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["RoomTemperatureHigh"] = "room-temperature-high";
+    /** Action planned because the buffer tank temperature is low. */
+    EnyoDiagnosticsActionReasonTypeEnum["BufferTankTemperatureLow"] = "buffer-tank-temperature-low";
+    /** Action planned because the home consumption is high. */
+    EnyoDiagnosticsActionReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+})(EnyoDiagnosticsActionReasonTypeEnum || (EnyoDiagnosticsActionReasonTypeEnum = {}));

package/dist/version.d.ts

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