@enyo-energy/energy-app-sdk 0.0.95 → 0.0.97

package/README.md

@@ -20,6 +20,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [Data Management](#data-management)
   - [Energy Resources](#energy-resources)
   - [User Features](#user-features)
+  - [App Intelligence](#app-intelligence)
 - [Advanced Modbus Integration](#advanced-modbus-integration)
 - [Examples](#examples)
   - [Basic Energy App](#basic-energy-app)
@@ -615,6 +616,61 @@ await notifications.sendNotification({
 });
 ```
 
+### App Intelligence
+
+#### `useLearningPhase(): EnergyAppLearningPhase`
+
+Track and manage learning phases — periods where an app or a specific appliance is calibrating, gathering data, or optimizing its behavior:
+
+```typescript
+const learningPhase = energyApp.useLearningPhase();
+
+// Register a package-wide learning phase
+const phaseId = await learningPhase.registerLearningPhase({
+    name: 'consumption-pattern-analysis',
+    reason: [
+        { language: 'en', value: 'Analyzing energy consumption patterns' },
+        { language: 'de', value: 'Analyse der Energieverbrauchsmuster' }
+    ],
+    description: [
+        { language: 'en', value: 'The system is learning your household energy consumption patterns to optimize scheduling.' },
+        { language: 'de', value: 'Das System lernt Ihre Energieverbrauchsmuster, um die Planung zu optimieren.' }
+    ]
+});
+
+// Register a learning phase for a specific appliance
+const heatpumpPhaseId = await learningPhase.registerLearningPhase({
+    name: 'heating-curve-optimization',
+    applianceId: 'heatpump-001',
+    reason: [
+        { language: 'en', value: 'Optimizing heating curve' },
+        { language: 'de', value: 'Optimierung der Heizkurve' }
+    ]
+});
+
+// Check if a learning phase is still active
+const isLearning = await learningPhase.isInLearningPhase(heatpumpPhaseId);
+console.log(`Heatpump is ${isLearning ? 'still learning' : 'done learning'}`);
+
+// Check if a learning phase is completed
+const isDone = await learningPhase.isLearningPhaseCompleted(heatpumpPhaseId);
+
+// Get all learning phases with their status and duration
+const allPhases = await learningPhase.getLearningPhases();
+for (const phase of allPhases) {
+    console.log(`${phase.name}: ${phase.durationInHours}h, active: ${!phase.endDate}`);
+}
+
+// Get learning phases for a specific appliance
+const heatpumpPhases = await learningPhase.getLearningPhasesByApplianceId('heatpump-001');
+
+// Complete a learning phase
+await learningPhase.completeLearningPhase(heatpumpPhaseId);
+
+// Remove a learning phase
+await learningPhase.removeLearningPhase(phaseId);
+```
+
 ## Advanced Modbus Integration
 
 The SDK includes a powerful, vendor-agnostic Modbus implementation for energy management systems. This allows you to connect to any Modbus-enabled device through configuration without code changes.

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

@@ -27,6 +27,7 @@ import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.cjs";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.cjs";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.cjs";
+import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -109,4 +110,6 @@ export interface EnyoEnergyAppSdk {
     useMqtt: () => EnergyAppMqtt;
     /** Get the Diagnostics API for submitting energy manager diagnostics data */
     useDiagnostics: () => EnergyAppDiagnostics;
+    /** Get the Learning Phase API for registering and tracking learning phases */
+    useLearningPhase: () => EnergyAppLearningPhase;
 }

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

@@ -165,7 +165,7 @@ export declare class ApplianceManager {
      * @param applianceId The ID of the appliance
      * @param attributes The attributes to update
      */
-    updateAppliance(applianceId: string, attributes: Partial<EnyoAppliance>): Promise<void>;
+    updateAppliance(applianceId: string, attributes: Partial<PartialEnyoAppliance>): Promise<void>;
     /**
      * Removes an appliance by its ID.
      * @param applianceId The ID of the appliance to remove
@@ -218,3 +218,31 @@ export declare class ApplianceManager {
      */
     dispose(): void;
 }
+export interface PartialEnyoAppliance {
+    /** Unique identifier for the appliance */
+    id: string;
+    /** Name of the appliance in different supported languages */
+    name: EnyoApplianceName[];
+    /** Type/category of the appliance */
+    type: EnyoApplianceTypeEnum;
+    /** network device IDs associated with the appliance */
+    networkDeviceIds: string[];
+    /** Optional Metadata of the Appliance */
+    metadata?: Partial<EnyoApplianceMetadata>;
+    /** Topology Information of the appliance */
+    topology?: EnyoApplianceTopology;
+    /** Optional Metadata of the Appliance if of type Meter */
+    meter?: Partial<EnyoMeterAppliance>;
+    /** Optional Metadata of the Appliance if of type Inverter */
+    inverter?: Partial<EnyoInverterApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Charger */
+    charger?: Partial<EnyoChargerApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Heatpump */
+    heatpump?: Partial<EnyoHeatpumpApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Battery */
+    battery?: Partial<EnyoBatteryApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type TemperatureSensor */
+    temperatureSensor?: Partial<EnyoTemperatureSensorApplianceMetadata>;
+    /** Optional custom name for the appliance, defined by the user */
+    customName?: string;
+}

package/dist/cjs/index.cjs

@@ -53,6 +53,8 @@ __exportStar(require("./types/enyo-mqtt.cjs"), exports);
 __exportStar(require("./packages/energy-app-mqtt.cjs"), exports);
 __exportStar(require("./types/enyo-diagnostics.cjs"), exports);
 __exportStar(require("./packages/energy-app-diagnostics.cjs"), exports);
+__exportStar(require("./types/enyo-learning-phase.cjs"), exports);
+__exportStar(require("./packages/energy-app-learning-phase.cjs"), exports);
 class EnergyApp {
     energyAppSdk;
     constructor() {
@@ -254,6 +256,15 @@ class EnergyApp {
     useDiagnostics() {
         return this.energyAppSdk.useDiagnostics();
     }
+    /**
+     * Gets the Learning Phase API for registering and tracking learning phases.
+     * Provides methods to register new learning phases, check their status,
+     * and retrieve learning phase history for the package or specific appliances.
+     * @returns The Learning Phase API instance
+     */
+    useLearningPhase() {
+        return this.energyAppSdk.useLearningPhase();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/index.d.cts

@@ -28,6 +28,7 @@ import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.cjs";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.cjs";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.cjs";
+import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.cjs";
 export * from './energy-app-appliance-type.enum.cjs';
 export * from './energy-app-package-definition.cjs';
 export * from './version.cjs';
@@ -65,6 +66,8 @@ export * from './types/enyo-mqtt.cjs';
 export * from './packages/energy-app-mqtt.cjs';
 export * from './types/enyo-diagnostics.cjs';
 export * from './packages/energy-app-diagnostics.cjs';
+export * from './types/enyo-learning-phase.cjs';
+export * from './packages/energy-app-learning-phase.cjs';
 export declare class EnergyApp implements EnyoEnergyAppSdk {
     private readonly energyAppSdk;
     constructor();
@@ -181,6 +184,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Diagnostics API instance
      */
     useDiagnostics(): EnergyAppDiagnostics;
+    /**
+     * Gets the Learning Phase API for registering and tracking learning phases.
+     * Provides methods to register new learning phases, check their status,
+     * and retrieve learning phase history for the package or specific appliances.
+     * @returns The Learning Phase API instance
+     */
+    useLearningPhase(): EnergyAppLearningPhase;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -1,4 +1,5 @@
 import { EnergyManagerFeatureEnum, EnergyManagerInfo } from "../types/enyo-energy-manager.cjs";
+import { EnyoDiagnosticsControlPlan } from "../types/enyo-diagnostics.cjs";
 /**
  * Interface for retrieving energy manager information and capabilities.
  * The energy manager is responsible for optimizing energy usage across appliances.
@@ -23,4 +24,33 @@ export interface EnergyAppEnergyManager {
     getEnergyManagerInfo(): Promise<EnergyManagerInfo | null>;
     /** Only for Energy Manager Energy Apps: Register the features which are provided*/
     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
+     * estimated costs and grid power values.
+     *
+     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     *   and estimated costs
+     *
+     * @example
+     * ```typescript
+     * const energyManager = energyApp.useEnergyManager();
+     * energyManager.publishForecast({
+     *     commands: [
+     *         {
+     *             type: EnyoApplianceTypeEnum.Storage,
+     *             applianceId: 'battery-1',
+     *             decision: BatteryDecision.Charge,
+     *             powerW: 3000,
+     *             durationInMinutes: 60
+     *         }
+     *     ],
+     *     generatedAtIso: new Date().toISOString(),
+     *     totalEstimatedCostEur: 3.50,
+     *     totalGridImportKwh: 12.5,
+     *     totalGridExportKwh: 4.2
+     * });
+     * ```
+     */
+    publishForecast(controlPlan: EnyoDiagnosticsControlPlan): void;
 }

package/dist/cjs/packages/energy-app-learning-phase.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/packages/energy-app-learning-phase.d.cts

@@ -0,0 +1,88 @@
+import { EnyoLearningPhase, EnyoLearningPhaseRegistration } from "../types/enyo-learning-phase.cjs";
+/**
+ * Interface for managing learning phases within Energy App packages.
+ * Learning phases represent periods where an app or a specific appliance is calibrating,
+ * gathering data, or optimizing its behavior (e.g., a heatpump learning optimal heating curves
+ * after installation, or an energy manager learning consumption patterns).
+ *
+ * Learning phases can be package-wide (no applianceId) or tied to a specific appliance.
+ *
+ * @example
+ * ```typescript
+ * const learningPhase = energyApp.useLearningPhase();
+ *
+ * // Register a learning phase for a specific appliance
+ * const phaseId = await learningPhase.registerLearningPhase({
+ *     name: 'heating-curve-optimization',
+ *     applianceId: 'heatpump-001',
+ *     reason: [
+ *         { language: 'en', value: 'Optimizing heating curve' },
+ *         { language: 'de', value: 'Optimierung der Heizkurve' }
+ *     ],
+ *     description: [
+ *         { language: 'en', value: 'The heatpump is learning the optimal heating curve for your home.' },
+ *         { language: 'de', value: 'Die Wärmepumpe lernt die optimale Heizkurve für Ihr Zuhause.' }
+ *     ]
+ * });
+ *
+ * // Check if still learning
+ * const isLearning = await learningPhase.isInLearningPhase(phaseId);
+ *
+ * // Complete the learning phase
+ * await learningPhase.completeLearningPhase(phaseId);
+ * ```
+ */
+export interface EnergyAppLearningPhase {
+    /**
+     * Registers a new learning phase and starts tracking it.
+     * The learning phase starts immediately upon registration.
+     *
+     * @param registration - The learning phase registration details including name, optional applianceId, reason, and description
+     * @returns Promise that resolves to the unique ID of the newly created learning phase
+     */
+    registerLearningPhase(registration: EnyoLearningPhaseRegistration): Promise<string>;
+    /**
+     * Marks a learning phase as completed by setting its end date.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to complete
+     * @returns Promise that resolves when the learning phase is marked as completed
+     */
+    completeLearningPhase(learningPhaseId: string): Promise<void>;
+    /**
+     * Checks whether a specific learning phase is still active (not yet completed).
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to check
+     * @returns Promise that resolves to `true` if the learning phase is still active, `false` otherwise
+     */
+    isInLearningPhase(learningPhaseId: string): Promise<boolean>;
+    /**
+     * Checks whether a specific learning phase has been completed.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to check
+     * @returns Promise that resolves to `true` if the learning phase is completed, `false` otherwise
+     */
+    isLearningPhaseCompleted(learningPhaseId: string): Promise<boolean>;
+    /**
+     * Retrieves all learning phases registered by this package.
+     * Returns both active and completed learning phases with their current duration.
+     *
+     * @returns Promise that resolves to an array of all learning phases
+     */
+    getLearningPhases(): Promise<EnyoLearningPhase[]>;
+    /**
+     * Retrieves all learning phases associated with a specific appliance.
+     * Returns both active and completed learning phases for the given appliance.
+     *
+     * @param applianceId - The appliance ID to filter learning phases by
+     * @returns Promise that resolves to an array of learning phases for the specified appliance
+     */
+    getLearningPhasesByApplianceId(applianceId: string): Promise<EnyoLearningPhase[]>;
+    /**
+     * Removes a learning phase from the system.
+     * This permanently deletes the learning phase record regardless of its active/completed status.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to remove
+     * @returns Promise that resolves when the learning phase is removed
+     */
+    removeLearningPhase(learningPhaseId: string): Promise<void>;
+}

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

@@ -20,11 +20,11 @@ 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 = "normal" | "block_discharge" | "charge_from_grid" | "force_discharge";
+export type BatteryDecision = "block_discharge" | "charge_from_grid" | "force_discharge";
 /** EV charging control decision issued by the energy manager. */
-export type EvDecision = "normal" | "charging_pv" | "charging_grid" | "charging_mixed";
+export type EvDecision = "charging_pv" | "charging_grid" | "charging_mixed";
 /** Heat pump control decision issued by the energy manager. */
-export type HeatpumpDecision = "normal" | "dhw_boost" | "room_overheating" | "buffer_tank_boost";
+export type HeatpumpDecision = "dhw_boost" | "room_overheating" | "buffer_tank_boost";
 export interface EnyoDiagnosticsForecastInverterAppliance {
     type: EnyoApplianceTypeEnum.Inverter;
     applianceId: string;
@@ -56,6 +56,7 @@ export interface EnyoDiagnosticsForecastHeatpumpAppliance {
     applianceId: string;
     values: {
         powerW?: number;
+        flowTemperatureC?: number;
         roomTemperatureC?: number;
         dhwTemperatureC?: number;
         bufferTankTemperatureC?: number;
@@ -158,10 +159,14 @@ export interface EnyoDiagnosticsStorageControlCommand {
     type: EnyoApplianceTypeEnum.Storage;
     /** Target appliance ID. */
     applianceId: string;
+    /** ISO 8601 timestamp when this command starts. */
+    timestampIso: string;
     /** Control decision for the battery. */
     decision: BatteryDecision;
     /** Target power in Watts. */
     powerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional target state of charge as a percentage. */
     targetSoCPercent?: number;
 }
@@ -170,10 +175,14 @@ export interface EnyoDiagnosticsChargerControlCommand {
     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;
     /** Charging power in Watts. */
     chargingPowerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional charging limit in kW. */
     chargingLimitKw?: number;
 }
@@ -182,30 +191,23 @@ export interface EnyoDiagnosticsHeatpumpControlCommand {
     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;
     /** Target power in Watts. */
     powerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional target temperature in Celsius. */
     targetTempC?: number;
 }
 /** Union of all appliance control command types. */
 export type EnyoDiagnosticsApplianceControlCommand = EnyoDiagnosticsStorageControlCommand | EnyoDiagnosticsChargerControlCommand | EnyoDiagnosticsHeatpumpControlCommand;
-/** A single time slot in a control plan with its associated commands. */
-export interface EnyoDiagnosticsControlSlot {
-    /** ISO 8601 timestamp for this slot. */
-    timestampIso: string;
-    /** Commands to execute during this slot. */
-    commands: EnyoDiagnosticsApplianceControlCommand[];
-    /** Estimated cost for this slot in EUR. */
-    estimatedSlotCostEur: number;
-    /** Estimated grid power in Watts for this slot. */
-    estimatedGridPowerW: number;
-}
-/** Complete control plan with time-slotted commands and cost estimates. */
+/** Complete control plan with duration-based commands and cost estimates. */
 export interface EnyoDiagnosticsControlPlan {
-    /** Time-slotted command sequence. */
-    slots: EnyoDiagnosticsControlSlot[];
+    /** Sequence of appliance control commands, each with its own duration. */
+    commands: EnyoDiagnosticsApplianceControlCommand[];
     /** ISO 8601 timestamp when this plan was generated. */
     generatedAtIso: string;
     /** Total estimated cost in EUR. */

package/dist/cjs/types/enyo-heatpump-appliance.cjs

@@ -5,8 +5,6 @@ var EnyoHeatpumpApplianceAvailableFeaturesEnum;
 (function (EnyoHeatpumpApplianceAvailableFeaturesEnum) {
     /** If the heatpump is capable of domestic hot water*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
-    /** If the heatpump is capable of domestic hot water boost to use more pv energy*/
-    EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWaterBoost"] = "DomesticHotWaterBoost";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
     /** If the heatpump supports room overheating via heating circuits */

package/dist/cjs/types/enyo-heatpump-appliance.d.cts

@@ -1,8 +1,6 @@
 export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump is capable of domestic hot water*/
     DomesticHotWater = "DomesticHotWater",
-    /** If the heatpump is capable of domestic hot water boost to use more pv energy*/
-    DomesticHotWaterBoost = "DomesticHotWaterBoost",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
     /** If the heatpump supports room overheating via heating circuits */

package/dist/cjs/types/enyo-learning-phase.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/enyo-learning-phase.d.cts

@@ -0,0 +1,37 @@
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.cjs";
+/**
+ * Represents a learning phase tracked by an Energy App.
+ * A learning phase is a period during which an app or appliance is calibrating,
+ * gathering data, or optimizing its behavior (e.g., a heatpump learning optimal heating curves).
+ */
+export interface EnyoLearningPhase {
+    /** Unique identifier of the learning phase */
+    id: string;
+    /** Name identifying the learning phase (e.g., 'heating-curve-optimization') */
+    name: string;
+    /** Optional appliance ID — if omitted, the learning phase applies to the entire package */
+    applianceId?: string;
+    /** Optional translated reason explaining why this learning phase is needed */
+    reason?: EnyoPackageConfigurationTranslatedValue[];
+    /** Optional translated description providing details about what is being learned */
+    description?: EnyoPackageConfigurationTranslatedValue[];
+    /** ISO 8601 date string of when the learning phase started */
+    startDate: string;
+    /** ISO 8601 date string of when the learning phase ended — undefined if still active */
+    endDate?: string;
+    /** Duration of the learning phase in hours (elapsed if active, total if completed) */
+    durationInHours: number;
+}
+/**
+ * Registration parameters for creating a new learning phase.
+ */
+export interface EnyoLearningPhaseRegistration {
+    /** Name identifying the learning phase (e.g., 'heating-curve-optimization') */
+    name: string;
+    /** Optional appliance ID — if omitted, the learning phase applies to the entire package */
+    applianceId?: string;
+    /** Optional translated reason explaining why this learning phase is needed */
+    reason?: EnyoPackageConfigurationTranslatedValue[];
+    /** Optional translated description providing details about what is being learned */
+    description?: EnyoPackageConfigurationTranslatedValue[];
+}

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

package/dist/enyo-energy-app-sdk.d.ts

@@ -27,6 +27,7 @@ import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.js";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.js";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.js";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.js";
+import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.js";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -109,4 +110,6 @@ export interface EnyoEnergyAppSdk {
     useMqtt: () => EnergyAppMqtt;
     /** Get the Diagnostics API for submitting energy manager diagnostics data */
     useDiagnostics: () => EnergyAppDiagnostics;
+    /** Get the Learning Phase API for registering and tracking learning phases */
+    useLearningPhase: () => EnergyAppLearningPhase;
 }

package/dist/implementations/appliances/appliance-manager.d.ts

@@ -165,7 +165,7 @@ export declare class ApplianceManager {
      * @param applianceId The ID of the appliance
      * @param attributes The attributes to update
      */
-    updateAppliance(applianceId: string, attributes: Partial<EnyoAppliance>): Promise<void>;
+    updateAppliance(applianceId: string, attributes: Partial<PartialEnyoAppliance>): Promise<void>;
     /**
      * Removes an appliance by its ID.
      * @param applianceId The ID of the appliance to remove
@@ -218,3 +218,31 @@ export declare class ApplianceManager {
      */
     dispose(): void;
 }
+export interface PartialEnyoAppliance {
+    /** Unique identifier for the appliance */
+    id: string;
+    /** Name of the appliance in different supported languages */
+    name: EnyoApplianceName[];
+    /** Type/category of the appliance */
+    type: EnyoApplianceTypeEnum;
+    /** network device IDs associated with the appliance */
+    networkDeviceIds: string[];
+    /** Optional Metadata of the Appliance */
+    metadata?: Partial<EnyoApplianceMetadata>;
+    /** Topology Information of the appliance */
+    topology?: EnyoApplianceTopology;
+    /** Optional Metadata of the Appliance if of type Meter */
+    meter?: Partial<EnyoMeterAppliance>;
+    /** Optional Metadata of the Appliance if of type Inverter */
+    inverter?: Partial<EnyoInverterApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Charger */
+    charger?: Partial<EnyoChargerApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Heatpump */
+    heatpump?: Partial<EnyoHeatpumpApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type Battery */
+    battery?: Partial<EnyoBatteryApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type TemperatureSensor */
+    temperatureSensor?: Partial<EnyoTemperatureSensorApplianceMetadata>;
+    /** Optional custom name for the appliance, defined by the user */
+    customName?: string;
+}

package/dist/index.d.ts

@@ -28,6 +28,7 @@ import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.js";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.js";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.js";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.js";
+import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.js";
 export * from './energy-app-appliance-type.enum.js';
 export * from './energy-app-package-definition.js';
 export * from './version.js';
@@ -65,6 +66,8 @@ export * from './types/enyo-mqtt.js';
 export * from './packages/energy-app-mqtt.js';
 export * from './types/enyo-diagnostics.js';
 export * from './packages/energy-app-diagnostics.js';
+export * from './types/enyo-learning-phase.js';
+export * from './packages/energy-app-learning-phase.js';
 export declare class EnergyApp implements EnyoEnergyAppSdk {
     private readonly energyAppSdk;
     constructor();
@@ -181,6 +184,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Diagnostics API instance
      */
     useDiagnostics(): EnergyAppDiagnostics;
+    /**
+     * Gets the Learning Phase API for registering and tracking learning phases.
+     * Provides methods to register new learning phases, check their status,
+     * and retrieve learning phase history for the package or specific appliances.
+     * @returns The Learning Phase API instance
+     */
+    useLearningPhase(): EnergyAppLearningPhase;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/index.js

@@ -36,6 +36,8 @@ export * from './types/enyo-mqtt.js';
 export * from './packages/energy-app-mqtt.js';
 export * from './types/enyo-diagnostics.js';
 export * from './packages/energy-app-diagnostics.js';
+export * from './types/enyo-learning-phase.js';
+export * from './packages/energy-app-learning-phase.js';
 export class EnergyApp {
     energyAppSdk;
     constructor() {
@@ -237,6 +239,15 @@ export class EnergyApp {
     useDiagnostics() {
         return this.energyAppSdk.useDiagnostics();
     }
+    /**
+     * Gets the Learning Phase API for registering and tracking learning phases.
+     * Provides methods to register new learning phases, check their status,
+     * and retrieve learning phase history for the package or specific appliances.
+     * @returns The Learning Phase API instance
+     */
+    useLearningPhase() {
+        return this.energyAppSdk.useLearningPhase();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -1,4 +1,5 @@
 import { EnergyManagerFeatureEnum, EnergyManagerInfo } from "../types/enyo-energy-manager.js";
+import { EnyoDiagnosticsControlPlan } from "../types/enyo-diagnostics.js";
 /**
  * Interface for retrieving energy manager information and capabilities.
  * The energy manager is responsible for optimizing energy usage across appliances.
@@ -23,4 +24,33 @@ export interface EnergyAppEnergyManager {
     getEnergyManagerInfo(): Promise<EnergyManagerInfo | null>;
     /** Only for Energy Manager Energy Apps: Register the features which are provided*/
     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
+     * estimated costs and grid power values.
+     *
+     * @param controlPlan - The time-slotted control plan with commands for each appliance
+     *   and estimated costs
+     *
+     * @example
+     * ```typescript
+     * const energyManager = energyApp.useEnergyManager();
+     * energyManager.publishForecast({
+     *     commands: [
+     *         {
+     *             type: EnyoApplianceTypeEnum.Storage,
+     *             applianceId: 'battery-1',
+     *             decision: BatteryDecision.Charge,
+     *             powerW: 3000,
+     *             durationInMinutes: 60
+     *         }
+     *     ],
+     *     generatedAtIso: new Date().toISOString(),
+     *     totalEstimatedCostEur: 3.50,
+     *     totalGridImportKwh: 12.5,
+     *     totalGridExportKwh: 4.2
+     * });
+     * ```
+     */
+    publishForecast(controlPlan: EnyoDiagnosticsControlPlan): void;
 }

package/dist/packages/energy-app-learning-phase.d.ts

@@ -0,0 +1,88 @@
+import { EnyoLearningPhase, EnyoLearningPhaseRegistration } from "../types/enyo-learning-phase.js";
+/**
+ * Interface for managing learning phases within Energy App packages.
+ * Learning phases represent periods where an app or a specific appliance is calibrating,
+ * gathering data, or optimizing its behavior (e.g., a heatpump learning optimal heating curves
+ * after installation, or an energy manager learning consumption patterns).
+ *
+ * Learning phases can be package-wide (no applianceId) or tied to a specific appliance.
+ *
+ * @example
+ * ```typescript
+ * const learningPhase = energyApp.useLearningPhase();
+ *
+ * // Register a learning phase for a specific appliance
+ * const phaseId = await learningPhase.registerLearningPhase({
+ *     name: 'heating-curve-optimization',
+ *     applianceId: 'heatpump-001',
+ *     reason: [
+ *         { language: 'en', value: 'Optimizing heating curve' },
+ *         { language: 'de', value: 'Optimierung der Heizkurve' }
+ *     ],
+ *     description: [
+ *         { language: 'en', value: 'The heatpump is learning the optimal heating curve for your home.' },
+ *         { language: 'de', value: 'Die Wärmepumpe lernt die optimale Heizkurve für Ihr Zuhause.' }
+ *     ]
+ * });
+ *
+ * // Check if still learning
+ * const isLearning = await learningPhase.isInLearningPhase(phaseId);
+ *
+ * // Complete the learning phase
+ * await learningPhase.completeLearningPhase(phaseId);
+ * ```
+ */
+export interface EnergyAppLearningPhase {
+    /**
+     * Registers a new learning phase and starts tracking it.
+     * The learning phase starts immediately upon registration.
+     *
+     * @param registration - The learning phase registration details including name, optional applianceId, reason, and description
+     * @returns Promise that resolves to the unique ID of the newly created learning phase
+     */
+    registerLearningPhase(registration: EnyoLearningPhaseRegistration): Promise<string>;
+    /**
+     * Marks a learning phase as completed by setting its end date.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to complete
+     * @returns Promise that resolves when the learning phase is marked as completed
+     */
+    completeLearningPhase(learningPhaseId: string): Promise<void>;
+    /**
+     * Checks whether a specific learning phase is still active (not yet completed).
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to check
+     * @returns Promise that resolves to `true` if the learning phase is still active, `false` otherwise
+     */
+    isInLearningPhase(learningPhaseId: string): Promise<boolean>;
+    /**
+     * Checks whether a specific learning phase has been completed.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to check
+     * @returns Promise that resolves to `true` if the learning phase is completed, `false` otherwise
+     */
+    isLearningPhaseCompleted(learningPhaseId: string): Promise<boolean>;
+    /**
+     * Retrieves all learning phases registered by this package.
+     * Returns both active and completed learning phases with their current duration.
+     *
+     * @returns Promise that resolves to an array of all learning phases
+     */
+    getLearningPhases(): Promise<EnyoLearningPhase[]>;
+    /**
+     * Retrieves all learning phases associated with a specific appliance.
+     * Returns both active and completed learning phases for the given appliance.
+     *
+     * @param applianceId - The appliance ID to filter learning phases by
+     * @returns Promise that resolves to an array of learning phases for the specified appliance
+     */
+    getLearningPhasesByApplianceId(applianceId: string): Promise<EnyoLearningPhase[]>;
+    /**
+     * Removes a learning phase from the system.
+     * This permanently deletes the learning phase record regardless of its active/completed status.
+     *
+     * @param learningPhaseId - The unique ID of the learning phase to remove
+     * @returns Promise that resolves when the learning phase is removed
+     */
+    removeLearningPhase(learningPhaseId: string): Promise<void>;
+}

package/dist/packages/energy-app-learning-phase.js

@@ -0,0 +1 @@
+export {};

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

@@ -20,11 +20,11 @@ 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 = "normal" | "block_discharge" | "charge_from_grid" | "force_discharge";
+export type BatteryDecision = "block_discharge" | "charge_from_grid" | "force_discharge";
 /** EV charging control decision issued by the energy manager. */
-export type EvDecision = "normal" | "charging_pv" | "charging_grid" | "charging_mixed";
+export type EvDecision = "charging_pv" | "charging_grid" | "charging_mixed";
 /** Heat pump control decision issued by the energy manager. */
-export type HeatpumpDecision = "normal" | "dhw_boost" | "room_overheating" | "buffer_tank_boost";
+export type HeatpumpDecision = "dhw_boost" | "room_overheating" | "buffer_tank_boost";
 export interface EnyoDiagnosticsForecastInverterAppliance {
     type: EnyoApplianceTypeEnum.Inverter;
     applianceId: string;
@@ -56,6 +56,7 @@ export interface EnyoDiagnosticsForecastHeatpumpAppliance {
     applianceId: string;
     values: {
         powerW?: number;
+        flowTemperatureC?: number;
         roomTemperatureC?: number;
         dhwTemperatureC?: number;
         bufferTankTemperatureC?: number;
@@ -158,10 +159,14 @@ export interface EnyoDiagnosticsStorageControlCommand {
     type: EnyoApplianceTypeEnum.Storage;
     /** Target appliance ID. */
     applianceId: string;
+    /** ISO 8601 timestamp when this command starts. */
+    timestampIso: string;
     /** Control decision for the battery. */
     decision: BatteryDecision;
     /** Target power in Watts. */
     powerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional target state of charge as a percentage. */
     targetSoCPercent?: number;
 }
@@ -170,10 +175,14 @@ export interface EnyoDiagnosticsChargerControlCommand {
     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;
     /** Charging power in Watts. */
     chargingPowerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional charging limit in kW. */
     chargingLimitKw?: number;
 }
@@ -182,30 +191,23 @@ export interface EnyoDiagnosticsHeatpumpControlCommand {
     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;
     /** Target power in Watts. */
     powerW: number;
+    /** Duration of this command in minutes. */
+    durationInMinutes: number;
     /** Optional target temperature in Celsius. */
     targetTempC?: number;
 }
 /** Union of all appliance control command types. */
 export type EnyoDiagnosticsApplianceControlCommand = EnyoDiagnosticsStorageControlCommand | EnyoDiagnosticsChargerControlCommand | EnyoDiagnosticsHeatpumpControlCommand;
-/** A single time slot in a control plan with its associated commands. */
-export interface EnyoDiagnosticsControlSlot {
-    /** ISO 8601 timestamp for this slot. */
-    timestampIso: string;
-    /** Commands to execute during this slot. */
-    commands: EnyoDiagnosticsApplianceControlCommand[];
-    /** Estimated cost for this slot in EUR. */
-    estimatedSlotCostEur: number;
-    /** Estimated grid power in Watts for this slot. */
-    estimatedGridPowerW: number;
-}
-/** Complete control plan with time-slotted commands and cost estimates. */
+/** Complete control plan with duration-based commands and cost estimates. */
 export interface EnyoDiagnosticsControlPlan {
-    /** Time-slotted command sequence. */
-    slots: EnyoDiagnosticsControlSlot[];
+    /** Sequence of appliance control commands, each with its own duration. */
+    commands: EnyoDiagnosticsApplianceControlCommand[];
     /** ISO 8601 timestamp when this plan was generated. */
     generatedAtIso: string;
     /** Total estimated cost in EUR. */

package/dist/types/enyo-heatpump-appliance.d.ts

@@ -1,8 +1,6 @@
 export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump is capable of domestic hot water*/
     DomesticHotWater = "DomesticHotWater",
-    /** If the heatpump is capable of domestic hot water boost to use more pv energy*/
-    DomesticHotWaterBoost = "DomesticHotWaterBoost",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
     /** If the heatpump supports room overheating via heating circuits */

package/dist/types/enyo-heatpump-appliance.js

@@ -2,8 +2,6 @@ export var EnyoHeatpumpApplianceAvailableFeaturesEnum;
 (function (EnyoHeatpumpApplianceAvailableFeaturesEnum) {
     /** If the heatpump is capable of domestic hot water*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
-    /** If the heatpump is capable of domestic hot water boost to use more pv energy*/
-    EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWaterBoost"] = "DomesticHotWaterBoost";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
     /** If the heatpump supports room overheating via heating circuits */

package/dist/types/enyo-learning-phase.d.ts

@@ -0,0 +1,37 @@
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.js";
+/**
+ * Represents a learning phase tracked by an Energy App.
+ * A learning phase is a period during which an app or appliance is calibrating,
+ * gathering data, or optimizing its behavior (e.g., a heatpump learning optimal heating curves).
+ */
+export interface EnyoLearningPhase {
+    /** Unique identifier of the learning phase */
+    id: string;
+    /** Name identifying the learning phase (e.g., 'heating-curve-optimization') */
+    name: string;
+    /** Optional appliance ID — if omitted, the learning phase applies to the entire package */
+    applianceId?: string;
+    /** Optional translated reason explaining why this learning phase is needed */
+    reason?: EnyoPackageConfigurationTranslatedValue[];
+    /** Optional translated description providing details about what is being learned */
+    description?: EnyoPackageConfigurationTranslatedValue[];
+    /** ISO 8601 date string of when the learning phase started */
+    startDate: string;
+    /** ISO 8601 date string of when the learning phase ended — undefined if still active */
+    endDate?: string;
+    /** Duration of the learning phase in hours (elapsed if active, total if completed) */
+    durationInHours: number;
+}
+/**
+ * Registration parameters for creating a new learning phase.
+ */
+export interface EnyoLearningPhaseRegistration {
+    /** Name identifying the learning phase (e.g., 'heating-curve-optimization') */
+    name: string;
+    /** Optional appliance ID — if omitted, the learning phase applies to the entire package */
+    applianceId?: string;
+    /** Optional translated reason explaining why this learning phase is needed */
+    reason?: EnyoPackageConfigurationTranslatedValue[];
+    /** Optional translated description providing details about what is being learned */
+    description?: EnyoPackageConfigurationTranslatedValue[];
+}

package/dist/types/enyo-learning-phase.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

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