@enyo-energy/energy-app-sdk 0.0.174 → 0.0.176

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

@@ -8,6 +8,9 @@ exports.validateChargerSchedule = validateChargerSchedule;
 exports.validateBatterySchedule = validateBatterySchedule;
 exports.validateHeatpumpSchedule = validateHeatpumpSchedule;
 exports.validateHeatpumpScheduleEntry = validateHeatpumpScheduleEntry;
+exports.validateHeatingRodForecast = validateHeatingRodForecast;
+exports.validateHeatingRodSchedule = validateHeatingRodSchedule;
+exports.validateHeatingRodScheduleEntry = validateHeatingRodScheduleEntry;
 const enyo_appliance_command_forecast_js_1 = require("../../types/enyo-appliance-command-forecast.cjs");
 const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
 /**
@@ -172,6 +175,50 @@ function validateHeatpumpScheduleEntry(entry, fieldName) {
     validateBooleanField(entry.bufferTankBoostActive, `${fieldName}.bufferTankBoostActive`);
     validateBooleanField(entry.availablePowerActive, `${fieldName}.availablePowerActive`);
 }
+/**
+ * Validates a {@link HeatingRodForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single relative schedule; every entry is
+ * validated by {@link validateHeatingRodScheduleEntry}.
+ */
+function validateHeatingRodForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new ApplianceCommandForecastValidationError('HeatingRodForecast must be an object.');
+    }
+    validateMetadata(forecast);
+    validateHeatingRodSchedule(forecast.relativeSchedule, forecast.resolution);
+}
+/**
+ * Validates a heating rod relative schedule (the schedule used by
+ * {@link HeatingRodForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced by
+ * exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on {@link HeatingRodForecastScheduleEntry}.
+ */
+function validateHeatingRodSchedule(entries, resolution) {
+    const stepSeconds = resolveResolutionSeconds(resolution);
+    validateNonEmptySchedule(entries, 'relativeSchedule');
+    for (let i = 0; i < entries.length; i++) {
+        validateHeatingRodScheduleEntry(entries[i], `relativeSchedule[${i}]`);
+    }
+    validateFirstEntryStartsAtZero(entries[0].seconds, 'relativeSchedule');
+    validateSecondsMatchResolution(entries.map((e) => e.seconds), stepSeconds, 'relativeSchedule');
+}
+/**
+ * Validates a single {@link HeatingRodForecastScheduleEntry}. Used by
+ * {@link validateHeatingRodSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+function validateHeatingRodScheduleEntry(entry, fieldName) {
+    validateSecondsField(entry.seconds, `${fieldName}.seconds`);
+    if (entry.powerW !== undefined) {
+        validatePowerW(entry.powerW, `${fieldName}.powerW`);
+    }
+    validateTemperatureField(entry.temperatureC, `${fieldName}.temperatureC`);
+    validateBooleanField(entry.heatingActive, `${fieldName}.heatingActive`);
+    validateBooleanField(entry.availablePowerActive, `${fieldName}.availablePowerActive`);
+}
 function validateMetadata(forecast) {
     if (!(forecast.resolution in RESOLUTION_SECONDS)) {
         throw new ApplianceCommandForecastValidationError(`resolution is invalid: ${forecast.resolution}. Allowed values: ${Object.values(enyo_appliance_command_forecast_js_1.ApplianceForecastResolutionEnum).join(', ')}.`);

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

@@ -1,4 +1,4 @@
-import { ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.cjs';
+import { ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatingRodForecast, HeatingRodForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.cjs';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
  * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
@@ -65,3 +65,25 @@ export declare function validateHeatpumpSchedule(entries: HeatpumpForecastSchedu
  * entries incrementally.
  */
 export declare function validateHeatpumpScheduleEntry(entry: HeatpumpForecastScheduleEntry, fieldName: string): void;
+/**
+ * Validates a {@link HeatingRodForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single relative schedule; every entry is
+ * validated by {@link validateHeatingRodScheduleEntry}.
+ */
+export declare function validateHeatingRodForecast(forecast: HeatingRodForecast): void;
+/**
+ * Validates a heating rod relative schedule (the schedule used by
+ * {@link HeatingRodForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced by
+ * exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on {@link HeatingRodForecastScheduleEntry}.
+ */
+export declare function validateHeatingRodSchedule(entries: HeatingRodForecastScheduleEntry[], resolution: ApplianceForecastResolutionEnum): void;
+/**
+ * Validates a single {@link HeatingRodForecastScheduleEntry}. Used by
+ * {@link validateHeatingRodSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+export declare function validateHeatingRodScheduleEntry(entry: HeatingRodForecastScheduleEntry, fieldName: string): void;

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

@@ -300,6 +300,33 @@ class ApplianceManager {
         });
         this.listenerIds.push(removedListenerId);
     }
+    /**
+     * Subscribes to newly-created appliances. Fires only when an appliance is
+     * first created, not on subsequent updates. The optional
+     * {@link EnyoApplianceCreatedFilter filter} controls scope (own package,
+     * all appliances, or only externally-created) and category — `scope: 'all'`
+     * and `scope: 'external'` require the `AllAppliances` permission.
+     *
+     * @param listener - Invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns An unsubscribe function. Any still-active subscription is also
+     *          cleaned up automatically on {@link dispose}.
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    onApplianceCreated(listener, filter) {
+        this.throwIfDisposed();
+        const applianceService = this.energyApp.useAppliances();
+        const listenerId = applianceService.listenForApplianceCreated((appliance) => {
+            if (this.disposed)
+                return;
+            return listener(appliance);
+        }, filter);
+        this.listenerIds.push(listenerId);
+        return () => {
+            applianceService.removeListener(listenerId);
+            this.listenerIds = this.listenerIds.filter(id => id !== listenerId);
+        };
+    }
     /**
      * Clears the internal cache without touching the SDK.
      */

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

@@ -1,6 +1,7 @@
 import { EnergyApp } from "../../index.cjs";
 import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
 import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
+import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.cjs";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.cjs";
 import type { EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
 import type { EnyoBatteryApplianceMetadata } from "../../types/enyo-battery-appliance.cjs";
@@ -203,6 +204,20 @@ export declare class ApplianceManager {
      * Subscribes to appliance update and removal events to keep the cache in sync.
      */
     private subscribeToEvents;
+    /**
+     * Subscribes to newly-created appliances. Fires only when an appliance is
+     * first created, not on subsequent updates. The optional
+     * {@link EnyoApplianceCreatedFilter filter} controls scope (own package,
+     * all appliances, or only externally-created) and category — `scope: 'all'`
+     * and `scope: 'external'` require the `AllAppliances` permission.
+     *
+     * @param listener - Invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns An unsubscribe function. Any still-active subscription is also
+     *          cleaned up automatically on {@link dispose}.
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    onApplianceCreated(listener: (appliance: EnyoAppliance) => void | Promise<void>, filter?: EnyoApplianceCreatedFilter): () => void;
     /**
      * Clears the internal cache without touching the SDK.
      */

package/dist/cjs/index.cjs

@@ -29,6 +29,8 @@ __exportStar(require("./types/enyo-energy-prices.cjs"), exports);
 __exportStar(require("./types/enyo-notification.cjs"), exports);
 __exportStar(require("./types/enyo-secret-manager.cjs"), exports);
 __exportStar(require("./types/enyo-location.cjs"), exports);
+__exportStar(require("./types/enyo-appliance.cjs"), exports);
+__exportStar(require("./packages/energy-app-appliance.cjs"), exports);
 __exportStar(require("./implementations/appliances/appliance-manager.cjs"), exports);
 __exportStar(require("./implementations/appliances/identifier-strategies.cjs"), exports);
 __exportStar(require("./implementations/network-devices/network-access-guard.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -13,6 +13,8 @@ export * from './types/enyo-energy-prices.cjs';
 export * from './types/enyo-notification.cjs';
 export * from './types/enyo-secret-manager.cjs';
 export * from './types/enyo-location.cjs';
+export * from './types/enyo-appliance.cjs';
+export * from './packages/energy-app-appliance.cjs';
 export * from './implementations/appliances/appliance-manager.cjs';
 export * from './implementations/appliances/identifier-strategies.cjs';
 export * from './implementations/network-devices/network-access-guard.cjs';

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

@@ -1,4 +1,4 @@
-import { BatteryCommandForecast, ChargerForecast, HeatpumpForecast } from '../types/enyo-appliance-command-forecast.cjs';
+import { BatteryCommandForecast, ChargerForecast, HeatingRodForecast, HeatpumpForecast } from '../types/enyo-appliance-command-forecast.cjs';
 /**
  * SDK accessor for the **Appliance Energy-Manager Forecast** package.
  *
@@ -16,6 +16,10 @@ import { BatteryCommandForecast, ChargerForecast, HeatpumpForecast } from '../ty
  *    carry the forecasted DHW / room / buffer-tank temperatures together
  *    with planned boost / pre-heating flags and the available-power
  *    announcement at each slot ({@link HeatpumpForecast}).
+ *  - **Heating rods** — a single relative schedule whose entries carry
+ *    the forecasted target temperature together with the planned heating
+ *    flag and the available-power announcement at each slot
+ *    ({@link HeatingRodForecast}).
  *
  * Every forecast optionally carries
  * {@link ApplianceForecastEstimatedSavings} so downstream consumers can
@@ -85,4 +89,20 @@ export interface EnergyAppApplianceEnergyManagerForecast {
      *   is malformed.
      */
     publishHeatpumpForecast(applianceId: string, forecast: HeatpumpForecast): Promise<void>;
+    /**
+     * Publishes the command-plan forecast for a heating rod (immersion
+     * element). The forecast carries a single relative schedule whose
+     * entries pack the forecasted target temperature together with the
+     * planned heating flag and the available-power announcement at each
+     * slot.
+     *
+     * Validates {@link forecast} against the invariants documented on
+     * {@link HeatingRodForecast}.
+     *
+     * @param applianceId - The heating rod appliance the forecast applies to.
+     * @param forecast - The command-plan forecast and its metadata.
+     * @throws {ApplianceCommandForecastValidationError} If the forecast
+     *   is malformed.
+     */
+    publishHeatingRodForecast(applianceId: string, forecast: HeatingRodForecast): Promise<void>;
 }

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

@@ -1,4 +1,30 @@
-import { EnyoAppliance } from "../types/enyo-appliance.cjs";
+import { EnyoAppliance, EnyoApplianceTypeEnum } from "../types/enyo-appliance.cjs";
+/**
+ * Ownership scope for an appliance-created subscription.
+ * - `'own'`: appliances created by your own package.
+ * - `'all'`: every appliance created system-wide.
+ * - `'external'`: only appliances created by *other* packages (all minus own).
+ */
+export type EnyoApplianceCreatedScope = 'own' | 'all' | 'external';
+/**
+ * Optional filter controlling which appliance-created events a listener receives.
+ * When omitted, defaults to `scope: 'own'` and no category restriction.
+ */
+export interface EnyoApplianceCreatedFilter {
+    /**
+     * Ownership scope of the subscription:
+     * - `'own'` (default): appliances created by your own package.
+     * - `'all'`: every appliance created system-wide. Requires the `AllAppliances` permission.
+     * - `'external'`: only appliances created by *other* packages (all minus own). Requires the `AllAppliances` permission.
+     */
+    scope?: EnyoApplianceCreatedScope;
+    /**
+     * When set, the listener only fires for appliances whose
+     * {@link EnyoApplianceTypeEnum category} is included in this list. When
+     * omitted, appliances of every category are delivered.
+     */
+    types?: EnyoApplianceTypeEnum[];
+}
 /**
  * Interface for managing appliances in enyo packages.
  * Provides CRUD operations for appliance registration and management.
@@ -26,9 +52,24 @@ export interface EnergyAppAppliance {
      * @returns A unique listener ID that can be used to remove the listener
      */
     listenForApplianceRemoved: (listener: (applianceId: string) => void | Promise<void>) => string;
+    /**
+     * Listen for newly-created appliances. Fires only when an appliance is
+     * first created — not on subsequent updates (use
+     * {@link listenForApplianceUpdated} for those).
+     *
+     * The optional {@link EnyoApplianceCreatedFilter filter} controls scope and
+     * category: by default only your own package's creations are delivered;
+     * `scope: 'all'` and `scope: 'external'` observe appliances created by other
+     * packages and require the `AllAppliances` permission.
+     *
+     * @param listener - Callback invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns A unique listener ID that can be used to remove the listener
+     */
+    listenForApplianceCreated: (listener: (appliance: EnyoAppliance) => void | Promise<void>, filter?: EnyoApplianceCreatedFilter) => string;
     /**
      * Removes a previously registered listener.
-     * @param listenerId - The ID returned by listenForApplianceUpdated or listenForApplianceRemoved
+     * @param listenerId - The ID returned by listenForApplianceUpdated, listenForApplianceRemoved, or listenForApplianceCreated
      */
     removeListener: (listenerId: string) => void;
 }

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

@@ -354,3 +354,79 @@ export interface HeatpumpForecast extends ApplianceForecastMetadata {
      */
     relativeSchedule: HeatpumpForecastScheduleEntry[];
 }
+/**
+ * One entry of a heating rod's relative schedule.
+ *
+ * The entry packs every per-slot piece of information the energy-manager
+ * forecast carries for a heating rod (immersion element): the forecasted
+ * target temperature, the planned heating flag, and the available-power
+ * announcement. The setpoint becomes active {@link seconds} after the
+ * forecast becomes effective and stays active until the next entry's
+ * `seconds` is reached.
+ *
+ * Every field other than {@link seconds} is optional — an entry may
+ * describe only the temperature, only the flag, only power, or any
+ * combination. A field that is omitted carries no information for that
+ * slot (it is **not** "set to zero / false"); the previous entry's value
+ * should be treated as still in effect.
+ */
+export interface HeatingRodForecastScheduleEntry {
+    /**
+     * Seconds from the moment the forecast becomes effective at which
+     * this entry becomes active. `0` for the first entry; subsequent
+     * entries must be strictly increasing.
+     */
+    seconds: number;
+    /**
+     * Planned available electrical power in Watts the energy manager
+     * intends to make available to the heating rod during this slot. The
+     * heating rod is free to consume up to this value — and free to
+     * consume less if it cannot use it all. Non-negative when present.
+     */
+    powerW?: number;
+    /**
+     * Forecasted target temperature in °C at this slot (the temperature
+     * the heating rod is driving its tank / buffer toward). Plausible
+     * range: [-50, 150].
+     */
+    temperatureC?: number;
+    /**
+     * Whether the heating rod is planned to be actively heating during
+     * this slot — `true` while the publisher intends to drive the tank
+     * up, `false` (or omitted) otherwise.
+     */
+    heatingActive?: boolean;
+    /**
+     * Whether the publisher is announcing available power for this slot
+     * — `true` when the energy-manager decision for the slot is
+     * "available power", meaning {@link powerW} doubles as the
+     * available-power offer to the heating rod (the heating rod is free
+     * to consume up to that value), `false` (or omitted) otherwise.
+     *
+     * This flag is independent of {@link heatingActive} and may coexist
+     * with it when the publisher offers available power while a heating
+     * window is also planned.
+     */
+    availablePowerActive?: boolean;
+}
+/**
+ * Forecasted command plan for a heating rod appliance, published via
+ * {@link EnergyAppApplianceEnergyManagerForecast.publishHeatingRodForecast}.
+ *
+ * A heating rod forecast is a **single** relative schedule whose entries
+ * carry every per-slot piece of information at once (forecasted target
+ * temperature, heating flag, available-power announcement). One entry per
+ * slot keeps the temperature trajectory and the heating decisions aligned
+ * by construction.
+ *
+ * The schedule must be sorted ascending by `seconds` and start at
+ * `seconds = 0` so the appliance has an authoritative "right now" entry.
+ */
+export interface HeatingRodForecast extends ApplianceForecastMetadata {
+    /**
+     * Relative schedule of forecast entries. Sorted ascending by
+     * `seconds`, starting at `seconds = 0`. Must contain at least one
+     * entry.
+     */
+    relativeSchedule: HeatingRodForecastScheduleEntry[];
+}

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

@@ -625,6 +625,12 @@ export interface EnyoDataBusAggregatedStateValuesV1 extends EnyoDataBusMessage {
         gridPowerPhase2W?: number;
         /** Grid power on phase L3 (in Watt). Negative: grid feed in, positive: grid consumption */
         gridPowerPhase3W?: number;
+        /**
+         * Time resolution of the aggregated grid power values (e.g. the sampling
+         * interval the `gridPowerW` / `gridPowerPhaseXW` values were measured at).
+         * Use `'dynamic'` when the values are forwarded as events occur.
+         */
+        gridPowerResolution: EnyoDataBusMessageResolution;
         gridConsumptionW?: number;
         gridFeedInW?: number;
         homeConsumptionW?: number;

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

@@ -19,12 +19,23 @@ var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["Power"] = "Power";
     /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["ReadyForCalibration"] = "ReadyForCalibration";
+    /** If the heatpump supports cooling (reversible heatpump) */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["Cooling"] = "Cooling";
 })(EnyoHeatpumpApplianceAvailableFeaturesEnum || (exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = EnyoHeatpumpApplianceAvailableFeaturesEnum = {}));
+/**
+ * The current operating state of a heatpump.
+ */
 var EnyoHeatpumpApplianceModeEnum;
 (function (EnyoHeatpumpApplianceModeEnum) {
+    /** The heatpump is idle (not actively heating, cooling, or producing hot water) */
     EnyoHeatpumpApplianceModeEnum["Idle"] = "Idle";
+    /** The heatpump is actively heating */
     EnyoHeatpumpApplianceModeEnum["Heating"] = "Heating";
+    /** The heatpump is actively cooling (reversible heatpumps only) */
+    EnyoHeatpumpApplianceModeEnum["Cooling"] = "Cooling";
+    /** The heatpump is actively producing domestic hot water */
     EnyoHeatpumpApplianceModeEnum["DomesticHotWater"] = "DomesticHotWater";
+    /** The heatpump is running in emergency operation */
     EnyoHeatpumpApplianceModeEnum["EmergencyOperation"] = "EmergencyOperation";
 })(EnyoHeatpumpApplianceModeEnum || (exports.EnyoHeatpumpApplianceModeEnum = EnyoHeatpumpApplianceModeEnum = {}));
 /**

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

@@ -14,12 +14,23 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
     Power = "Power",
     /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
-    ReadyForCalibration = "ReadyForCalibration"
+    ReadyForCalibration = "ReadyForCalibration",
+    /** If the heatpump supports cooling (reversible heatpump) */
+    Cooling = "Cooling"
 }
+/**
+ * The current operating state of a heatpump.
+ */
 export declare enum EnyoHeatpumpApplianceModeEnum {
+    /** The heatpump is idle (not actively heating, cooling, or producing hot water) */
     Idle = "Idle",
+    /** The heatpump is actively heating */
     Heating = "Heating",
+    /** The heatpump is actively cooling (reversible heatpumps only) */
+    Cooling = "Cooling",
+    /** The heatpump is actively producing domestic hot water */
     DomesticHotWater = "DomesticHotWater",
+    /** The heatpump is running in emergency operation */
     EmergencyOperation = "EmergencyOperation"
 }
 /**
@@ -51,7 +62,10 @@ export interface EnyoHeatpumpApplianceCompressor {
 }
 export interface EnyoHeatpumpApplianceHeatingCircuit {
     index: number;
+    /** Target room temperature setpoint when heating (in °C) */
     targetRoomTemperatureC?: number;
+    /** Target room temperature setpoint when cooling (in °C). Only meaningful for cooling-capable heatpumps. */
+    targetCoolingRoomTemperatureC?: number;
 }
 export interface EnyoHeatpumpApplianceMetadata {
     availableFeatures: EnyoHeatpumpApplianceAvailableFeaturesEnum[];

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

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

@@ -1,4 +1,4 @@
-import { ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.js';
+import { ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatingRodForecast, HeatingRodForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.js';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
  * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
@@ -65,3 +65,25 @@ export declare function validateHeatpumpSchedule(entries: HeatpumpForecastSchedu
  * entries incrementally.
  */
 export declare function validateHeatpumpScheduleEntry(entry: HeatpumpForecastScheduleEntry, fieldName: string): void;
+/**
+ * Validates a {@link HeatingRodForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single relative schedule; every entry is
+ * validated by {@link validateHeatingRodScheduleEntry}.
+ */
+export declare function validateHeatingRodForecast(forecast: HeatingRodForecast): void;
+/**
+ * Validates a heating rod relative schedule (the schedule used by
+ * {@link HeatingRodForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced by
+ * exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on {@link HeatingRodForecastScheduleEntry}.
+ */
+export declare function validateHeatingRodSchedule(entries: HeatingRodForecastScheduleEntry[], resolution: ApplianceForecastResolutionEnum): void;
+/**
+ * Validates a single {@link HeatingRodForecastScheduleEntry}. Used by
+ * {@link validateHeatingRodSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+export declare function validateHeatingRodScheduleEntry(entry: HeatingRodForecastScheduleEntry, fieldName: string): void;

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

@@ -161,6 +161,50 @@ export function validateHeatpumpScheduleEntry(entry, fieldName) {
     validateBooleanField(entry.bufferTankBoostActive, `${fieldName}.bufferTankBoostActive`);
     validateBooleanField(entry.availablePowerActive, `${fieldName}.availablePowerActive`);
 }
+/**
+ * Validates a {@link HeatingRodForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single relative schedule; every entry is
+ * validated by {@link validateHeatingRodScheduleEntry}.
+ */
+export function validateHeatingRodForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new ApplianceCommandForecastValidationError('HeatingRodForecast must be an object.');
+    }
+    validateMetadata(forecast);
+    validateHeatingRodSchedule(forecast.relativeSchedule, forecast.resolution);
+}
+/**
+ * Validates a heating rod relative schedule (the schedule used by
+ * {@link HeatingRodForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced by
+ * exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on {@link HeatingRodForecastScheduleEntry}.
+ */
+export function validateHeatingRodSchedule(entries, resolution) {
+    const stepSeconds = resolveResolutionSeconds(resolution);
+    validateNonEmptySchedule(entries, 'relativeSchedule');
+    for (let i = 0; i < entries.length; i++) {
+        validateHeatingRodScheduleEntry(entries[i], `relativeSchedule[${i}]`);
+    }
+    validateFirstEntryStartsAtZero(entries[0].seconds, 'relativeSchedule');
+    validateSecondsMatchResolution(entries.map((e) => e.seconds), stepSeconds, 'relativeSchedule');
+}
+/**
+ * Validates a single {@link HeatingRodForecastScheduleEntry}. Used by
+ * {@link validateHeatingRodSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+export function validateHeatingRodScheduleEntry(entry, fieldName) {
+    validateSecondsField(entry.seconds, `${fieldName}.seconds`);
+    if (entry.powerW !== undefined) {
+        validatePowerW(entry.powerW, `${fieldName}.powerW`);
+    }
+    validateTemperatureField(entry.temperatureC, `${fieldName}.temperatureC`);
+    validateBooleanField(entry.heatingActive, `${fieldName}.heatingActive`);
+    validateBooleanField(entry.availablePowerActive, `${fieldName}.availablePowerActive`);
+}
 function validateMetadata(forecast) {
     if (!(forecast.resolution in RESOLUTION_SECONDS)) {
         throw new ApplianceCommandForecastValidationError(`resolution is invalid: ${forecast.resolution}. Allowed values: ${Object.values(ApplianceForecastResolutionEnum).join(', ')}.`);

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

@@ -1,6 +1,7 @@
 import { EnergyApp } from "../../index.js";
 import type { EnyoNetworkDevice } from "../../types/enyo-network-device.js";
 import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.js";
+import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.js";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.js";
 import type { EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.js";
 import type { EnyoBatteryApplianceMetadata } from "../../types/enyo-battery-appliance.js";
@@ -203,6 +204,20 @@ export declare class ApplianceManager {
      * Subscribes to appliance update and removal events to keep the cache in sync.
      */
     private subscribeToEvents;
+    /**
+     * Subscribes to newly-created appliances. Fires only when an appliance is
+     * first created, not on subsequent updates. The optional
+     * {@link EnyoApplianceCreatedFilter filter} controls scope (own package,
+     * all appliances, or only externally-created) and category — `scope: 'all'`
+     * and `scope: 'external'` require the `AllAppliances` permission.
+     *
+     * @param listener - Invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns An unsubscribe function. Any still-active subscription is also
+     *          cleaned up automatically on {@link dispose}.
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    onApplianceCreated(listener: (appliance: EnyoAppliance) => void | Promise<void>, filter?: EnyoApplianceCreatedFilter): () => void;
     /**
      * Clears the internal cache without touching the SDK.
      */

package/dist/implementations/appliances/appliance-manager.js

@@ -294,6 +294,33 @@ export class ApplianceManager {
         });
         this.listenerIds.push(removedListenerId);
     }
+    /**
+     * Subscribes to newly-created appliances. Fires only when an appliance is
+     * first created, not on subsequent updates. The optional
+     * {@link EnyoApplianceCreatedFilter filter} controls scope (own package,
+     * all appliances, or only externally-created) and category — `scope: 'all'`
+     * and `scope: 'external'` require the `AllAppliances` permission.
+     *
+     * @param listener - Invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns An unsubscribe function. Any still-active subscription is also
+     *          cleaned up automatically on {@link dispose}.
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    onApplianceCreated(listener, filter) {
+        this.throwIfDisposed();
+        const applianceService = this.energyApp.useAppliances();
+        const listenerId = applianceService.listenForApplianceCreated((appliance) => {
+            if (this.disposed)
+                return;
+            return listener(appliance);
+        }, filter);
+        this.listenerIds.push(listenerId);
+        return () => {
+            applianceService.removeListener(listenerId);
+            this.listenerIds = this.listenerIds.filter(id => id !== listenerId);
+        };
+    }
     /**
      * Clears the internal cache without touching the SDK.
      */

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export * from './types/enyo-energy-prices.js';
 export * from './types/enyo-notification.js';
 export * from './types/enyo-secret-manager.js';
 export * from './types/enyo-location.js';
+export * from './types/enyo-appliance.js';
+export * from './packages/energy-app-appliance.js';
 export * from './implementations/appliances/appliance-manager.js';
 export * from './implementations/appliances/identifier-strategies.js';
 export * from './implementations/network-devices/network-access-guard.js';

package/dist/index.js

@@ -13,6 +13,8 @@ export * from './types/enyo-energy-prices.js';
 export * from './types/enyo-notification.js';
 export * from './types/enyo-secret-manager.js';
 export * from './types/enyo-location.js';
+export * from './types/enyo-appliance.js';
+export * from './packages/energy-app-appliance.js';
 export * from './implementations/appliances/appliance-manager.js';
 export * from './implementations/appliances/identifier-strategies.js';
 export * from './implementations/network-devices/network-access-guard.js';

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

@@ -1,4 +1,4 @@
-import { BatteryCommandForecast, ChargerForecast, HeatpumpForecast } from '../types/enyo-appliance-command-forecast.js';
+import { BatteryCommandForecast, ChargerForecast, HeatingRodForecast, HeatpumpForecast } from '../types/enyo-appliance-command-forecast.js';
 /**
  * SDK accessor for the **Appliance Energy-Manager Forecast** package.
  *
@@ -16,6 +16,10 @@ import { BatteryCommandForecast, ChargerForecast, HeatpumpForecast } from '../ty
  *    carry the forecasted DHW / room / buffer-tank temperatures together
  *    with planned boost / pre-heating flags and the available-power
  *    announcement at each slot ({@link HeatpumpForecast}).
+ *  - **Heating rods** — a single relative schedule whose entries carry
+ *    the forecasted target temperature together with the planned heating
+ *    flag and the available-power announcement at each slot
+ *    ({@link HeatingRodForecast}).
  *
  * Every forecast optionally carries
  * {@link ApplianceForecastEstimatedSavings} so downstream consumers can
@@ -85,4 +89,20 @@ export interface EnergyAppApplianceEnergyManagerForecast {
      *   is malformed.
      */
     publishHeatpumpForecast(applianceId: string, forecast: HeatpumpForecast): Promise<void>;
+    /**
+     * Publishes the command-plan forecast for a heating rod (immersion
+     * element). The forecast carries a single relative schedule whose
+     * entries pack the forecasted target temperature together with the
+     * planned heating flag and the available-power announcement at each
+     * slot.
+     *
+     * Validates {@link forecast} against the invariants documented on
+     * {@link HeatingRodForecast}.
+     *
+     * @param applianceId - The heating rod appliance the forecast applies to.
+     * @param forecast - The command-plan forecast and its metadata.
+     * @throws {ApplianceCommandForecastValidationError} If the forecast
+     *   is malformed.
+     */
+    publishHeatingRodForecast(applianceId: string, forecast: HeatingRodForecast): Promise<void>;
 }

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

@@ -1,4 +1,30 @@
-import { EnyoAppliance } from "../types/enyo-appliance.js";
+import { EnyoAppliance, EnyoApplianceTypeEnum } from "../types/enyo-appliance.js";
+/**
+ * Ownership scope for an appliance-created subscription.
+ * - `'own'`: appliances created by your own package.
+ * - `'all'`: every appliance created system-wide.
+ * - `'external'`: only appliances created by *other* packages (all minus own).
+ */
+export type EnyoApplianceCreatedScope = 'own' | 'all' | 'external';
+/**
+ * Optional filter controlling which appliance-created events a listener receives.
+ * When omitted, defaults to `scope: 'own'` and no category restriction.
+ */
+export interface EnyoApplianceCreatedFilter {
+    /**
+     * Ownership scope of the subscription:
+     * - `'own'` (default): appliances created by your own package.
+     * - `'all'`: every appliance created system-wide. Requires the `AllAppliances` permission.
+     * - `'external'`: only appliances created by *other* packages (all minus own). Requires the `AllAppliances` permission.
+     */
+    scope?: EnyoApplianceCreatedScope;
+    /**
+     * When set, the listener only fires for appliances whose
+     * {@link EnyoApplianceTypeEnum category} is included in this list. When
+     * omitted, appliances of every category are delivered.
+     */
+    types?: EnyoApplianceTypeEnum[];
+}
 /**
  * Interface for managing appliances in enyo packages.
  * Provides CRUD operations for appliance registration and management.
@@ -26,9 +52,24 @@ export interface EnergyAppAppliance {
      * @returns A unique listener ID that can be used to remove the listener
      */
     listenForApplianceRemoved: (listener: (applianceId: string) => void | Promise<void>) => string;
+    /**
+     * Listen for newly-created appliances. Fires only when an appliance is
+     * first created — not on subsequent updates (use
+     * {@link listenForApplianceUpdated} for those).
+     *
+     * The optional {@link EnyoApplianceCreatedFilter filter} controls scope and
+     * category: by default only your own package's creations are delivered;
+     * `scope: 'all'` and `scope: 'external'` observe appliances created by other
+     * packages and require the `AllAppliances` permission.
+     *
+     * @param listener - Callback invoked with each newly-created appliance
+     * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`
+     * @returns A unique listener ID that can be used to remove the listener
+     */
+    listenForApplianceCreated: (listener: (appliance: EnyoAppliance) => void | Promise<void>, filter?: EnyoApplianceCreatedFilter) => string;
     /**
      * Removes a previously registered listener.
-     * @param listenerId - The ID returned by listenForApplianceUpdated or listenForApplianceRemoved
+     * @param listenerId - The ID returned by listenForApplianceUpdated, listenForApplianceRemoved, or listenForApplianceCreated
      */
     removeListener: (listenerId: string) => void;
 }

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

@@ -354,3 +354,79 @@ export interface HeatpumpForecast extends ApplianceForecastMetadata {
      */
     relativeSchedule: HeatpumpForecastScheduleEntry[];
 }
+/**
+ * One entry of a heating rod's relative schedule.
+ *
+ * The entry packs every per-slot piece of information the energy-manager
+ * forecast carries for a heating rod (immersion element): the forecasted
+ * target temperature, the planned heating flag, and the available-power
+ * announcement. The setpoint becomes active {@link seconds} after the
+ * forecast becomes effective and stays active until the next entry's
+ * `seconds` is reached.
+ *
+ * Every field other than {@link seconds} is optional — an entry may
+ * describe only the temperature, only the flag, only power, or any
+ * combination. A field that is omitted carries no information for that
+ * slot (it is **not** "set to zero / false"); the previous entry's value
+ * should be treated as still in effect.
+ */
+export interface HeatingRodForecastScheduleEntry {
+    /**
+     * Seconds from the moment the forecast becomes effective at which
+     * this entry becomes active. `0` for the first entry; subsequent
+     * entries must be strictly increasing.
+     */
+    seconds: number;
+    /**
+     * Planned available electrical power in Watts the energy manager
+     * intends to make available to the heating rod during this slot. The
+     * heating rod is free to consume up to this value — and free to
+     * consume less if it cannot use it all. Non-negative when present.
+     */
+    powerW?: number;
+    /**
+     * Forecasted target temperature in °C at this slot (the temperature
+     * the heating rod is driving its tank / buffer toward). Plausible
+     * range: [-50, 150].
+     */
+    temperatureC?: number;
+    /**
+     * Whether the heating rod is planned to be actively heating during
+     * this slot — `true` while the publisher intends to drive the tank
+     * up, `false` (or omitted) otherwise.
+     */
+    heatingActive?: boolean;
+    /**
+     * Whether the publisher is announcing available power for this slot
+     * — `true` when the energy-manager decision for the slot is
+     * "available power", meaning {@link powerW} doubles as the
+     * available-power offer to the heating rod (the heating rod is free
+     * to consume up to that value), `false` (or omitted) otherwise.
+     *
+     * This flag is independent of {@link heatingActive} and may coexist
+     * with it when the publisher offers available power while a heating
+     * window is also planned.
+     */
+    availablePowerActive?: boolean;
+}
+/**
+ * Forecasted command plan for a heating rod appliance, published via
+ * {@link EnergyAppApplianceEnergyManagerForecast.publishHeatingRodForecast}.
+ *
+ * A heating rod forecast is a **single** relative schedule whose entries
+ * carry every per-slot piece of information at once (forecasted target
+ * temperature, heating flag, available-power announcement). One entry per
+ * slot keeps the temperature trajectory and the heating decisions aligned
+ * by construction.
+ *
+ * The schedule must be sorted ascending by `seconds` and start at
+ * `seconds = 0` so the appliance has an authoritative "right now" entry.
+ */
+export interface HeatingRodForecast extends ApplianceForecastMetadata {
+    /**
+     * Relative schedule of forecast entries. Sorted ascending by
+     * `seconds`, starting at `seconds = 0`. Must contain at least one
+     * entry.
+     */
+    relativeSchedule: HeatingRodForecastScheduleEntry[];
+}

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

@@ -625,6 +625,12 @@ export interface EnyoDataBusAggregatedStateValuesV1 extends EnyoDataBusMessage {
         gridPowerPhase2W?: number;
         /** Grid power on phase L3 (in Watt). Negative: grid feed in, positive: grid consumption */
         gridPowerPhase3W?: number;
+        /**
+         * Time resolution of the aggregated grid power values (e.g. the sampling
+         * interval the `gridPowerW` / `gridPowerPhaseXW` values were measured at).
+         * Use `'dynamic'` when the values are forwarded as events occur.
+         */
+        gridPowerResolution: EnyoDataBusMessageResolution;
         gridConsumptionW?: number;
         gridFeedInW?: number;
         homeConsumptionW?: number;

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

@@ -14,12 +14,23 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
     Power = "Power",
     /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
-    ReadyForCalibration = "ReadyForCalibration"
+    ReadyForCalibration = "ReadyForCalibration",
+    /** If the heatpump supports cooling (reversible heatpump) */
+    Cooling = "Cooling"
 }
+/**
+ * The current operating state of a heatpump.
+ */
 export declare enum EnyoHeatpumpApplianceModeEnum {
+    /** The heatpump is idle (not actively heating, cooling, or producing hot water) */
     Idle = "Idle",
+    /** The heatpump is actively heating */
     Heating = "Heating",
+    /** The heatpump is actively cooling (reversible heatpumps only) */
+    Cooling = "Cooling",
+    /** The heatpump is actively producing domestic hot water */
     DomesticHotWater = "DomesticHotWater",
+    /** The heatpump is running in emergency operation */
     EmergencyOperation = "EmergencyOperation"
 }
 /**
@@ -51,7 +62,10 @@ export interface EnyoHeatpumpApplianceCompressor {
 }
 export interface EnyoHeatpumpApplianceHeatingCircuit {
     index: number;
+    /** Target room temperature setpoint when heating (in °C) */
     targetRoomTemperatureC?: number;
+    /** Target room temperature setpoint when cooling (in °C). Only meaningful for cooling-capable heatpumps. */
+    targetCoolingRoomTemperatureC?: number;
 }
 export interface EnyoHeatpumpApplianceMetadata {
     availableFeatures: EnyoHeatpumpApplianceAvailableFeaturesEnum[];

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

@@ -16,12 +16,23 @@ export var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["Power"] = "Power";
     /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["ReadyForCalibration"] = "ReadyForCalibration";
+    /** If the heatpump supports cooling (reversible heatpump) */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["Cooling"] = "Cooling";
 })(EnyoHeatpumpApplianceAvailableFeaturesEnum || (EnyoHeatpumpApplianceAvailableFeaturesEnum = {}));
+/**
+ * The current operating state of a heatpump.
+ */
 export var EnyoHeatpumpApplianceModeEnum;
 (function (EnyoHeatpumpApplianceModeEnum) {
+    /** The heatpump is idle (not actively heating, cooling, or producing hot water) */
     EnyoHeatpumpApplianceModeEnum["Idle"] = "Idle";
+    /** The heatpump is actively heating */
     EnyoHeatpumpApplianceModeEnum["Heating"] = "Heating";
+    /** The heatpump is actively cooling (reversible heatpumps only) */
+    EnyoHeatpumpApplianceModeEnum["Cooling"] = "Cooling";
+    /** The heatpump is actively producing domestic hot water */
     EnyoHeatpumpApplianceModeEnum["DomesticHotWater"] = "DomesticHotWater";
+    /** The heatpump is running in emergency operation */
     EnyoHeatpumpApplianceModeEnum["EmergencyOperation"] = "EmergencyOperation";
 })(EnyoHeatpumpApplianceModeEnum || (EnyoHeatpumpApplianceModeEnum = {}));
 /**

package/dist/version.d.ts

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