@enyo-energy/energy-app-sdk 0.0.110 → 0.0.112

package/dist/cjs/implementations/forecasts/heatpump-consumption-forecast.cjs

@@ -6,8 +6,10 @@ const forecast_types_js_1 = require("./forecast-types.cjs");
 const forecast_utils_js_1 = require("./forecast-utils.cjs");
 /**
  * Builds a 24-hour heatpump electrical consumption forecast for a single
- * heatpump appliance from historical `HeatpumpValuesUpdateV1` data-bus
- * messages, with live updates merged in as new readings arrive.
+ * heatpump appliance. Historical buckets are sourced from the dedicated
+ * `useTimeseries().getHeatpumpPowerTimeseries()` endpoint, and live
+ * `HeatpumpValuesUpdateV1` data-bus messages are merged in as new readings
+ * arrive.
  *
  * Heatpump operation is strongly tied to outdoor temperature (which itself is
  * weekday-cyclic on average), so the algorithm uses a same-weekday
@@ -50,8 +52,9 @@ class HeatpumpConsumptionForecast {
         this.source = options.source;
     }
     /**
-     * Pulls historical `HeatpumpValuesUpdateV1` messages, aggregates them into
-     * 15-minute slots, and starts listening to live heatpump events. Idempotent.
+     * Loads historical heatpump power buckets via
+     * `useTimeseries().getHeatpumpPowerTimeseries()` and starts listening to
+     * live `HeatpumpValuesUpdateV1` events for ongoing updates. Idempotent.
      */
     async initialize() {
         if (this.initialized)
@@ -59,35 +62,20 @@ class HeatpumpConsumptionForecast {
         this.initialized = true;
         const now = Date.now();
         const startMs = now - this.config.historyDays * 24 * 60 * 60 * 1000;
-        const response = await this.app.useTimeseries().queryDataBusMessages({
-            applianceId: this.applianceId,
+        const response = await this.app.useTimeseries().getHeatpumpPowerTimeseries({
             startDateIso: new Date(startMs).toISOString(),
             endDateIso: new Date(now).toISOString(),
-            messageTypes: [enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpValuesUpdateV1],
-            limit: 100000,
+            applianceIds: [this.applianceId],
+            resolution: this.config.resolution,
         });
-        const slotAggregator = new Map();
-        for (const raw of response.messages) {
-            const message = raw;
-            const power = message.data.values.powerW;
-            if (typeof power !== 'number' || Number.isNaN(power))
-                continue;
-            const slotMs = (0, forecast_utils_js_1.roundDownTo15Minutes)(new Date(message.timestampIso).getTime());
-            const existing = slotAggregator.get(slotMs);
-            if (existing) {
-                existing.sum += power;
-                existing.count += 1;
-            }
-            else {
-                slotAggregator.set(slotMs, { sum: power, count: 1 });
-            }
-        }
-        const slots = Array.from(slotAggregator.keys()).sort((a, b) => a - b);
-        for (const slotMs of slots) {
-            const agg = slotAggregator.get(slotMs);
+        for (const entry of response.entries) {
             this.history.push({
-                timestampIso: new Date(slotMs).toISOString(),
-                values: { powerW: agg.sum / agg.count, samples: agg.count },
+                timestampIso: entry.timestampIso,
+                values: {
+                    powerW: entry.heatpumpPowerW,
+                    powerWh: entry.heatpumpPowerWh,
+                    samples: 1,
+                },
             });
         }
         this.listenerId = this.app.useDataBus().listenForMessages([enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpValuesUpdateV1], (msg) => this.onHeatpumpValues(msg));
@@ -179,10 +167,12 @@ class HeatpumpConsumptionForecast {
         if (this.currentSlotMs === undefined || this.currentSlotSamples === 0)
             return;
         const avg = this.currentSlotPowerSum / this.currentSlotSamples;
-        (0, forecast_utils_js_1.upsertLiveBucket)(this.history, this.currentSlotMs, { powerW: avg, samples: this.currentSlotSamples }, (existing, incoming) => {
+        (0, forecast_utils_js_1.upsertLiveBucket)(this.history, this.currentSlotMs, { powerW: avg, powerWh: (0, forecast_utils_js_1.wToWhPer15Min)(avg), samples: this.currentSlotSamples }, (existing, incoming) => {
             const total = existing.samples + incoming.samples;
+            const mergedPowerW = (existing.powerW * existing.samples + incoming.powerW * incoming.samples) / total;
             return {
-                powerW: (existing.powerW * existing.samples + incoming.powerW * incoming.samples) / total,
+                powerW: mergedPowerW,
+                powerWh: (0, forecast_utils_js_1.wToWhPer15Min)(mergedPowerW),
                 samples: total,
             };
         });

package/dist/cjs/implementations/forecasts/heatpump-consumption-forecast.d.cts

@@ -9,8 +9,10 @@ import { BaseForecast, Forecaster, ForecastConfig } from './forecast-types.cjs';
 export type HeatpumpConsumptionForecastResult = BaseForecast<EnyoDataBusHeatpumpConsumptionForecastV1['data']>;
 /**
  * Builds a 24-hour heatpump electrical consumption forecast for a single
- * heatpump appliance from historical `HeatpumpValuesUpdateV1` data-bus
- * messages, with live updates merged in as new readings arrive.
+ * heatpump appliance. Historical buckets are sourced from the dedicated
+ * `useTimeseries().getHeatpumpPowerTimeseries()` endpoint, and live
+ * `HeatpumpValuesUpdateV1` data-bus messages are merged in as new readings
+ * arrive.
  *
  * Heatpump operation is strongly tied to outdoor temperature (which itself is
  * weekday-cyclic on average), so the algorithm uses a same-weekday
@@ -51,8 +53,9 @@ export declare class HeatpumpConsumptionForecast implements Forecaster {
         config?: ForecastConfig;
     });
     /**
-     * Pulls historical `HeatpumpValuesUpdateV1` messages, aggregates them into
-     * 15-minute slots, and starts listening to live heatpump events. Idempotent.
+     * Loads historical heatpump power buckets via
+     * `useTimeseries().getHeatpumpPowerTimeseries()` and starts listening to
+     * live `HeatpumpValuesUpdateV1` events for ongoing updates. Idempotent.
      */
     initialize(): Promise<void>;
     /**

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

@@ -1,4 +1,4 @@
-import { DataBusMessageQueryRequest, DataBusMessageQueryResponse, PvProductionTimeseriesRequest, PvProductionTimeseriesResponse, BatterySocTimeseriesRequest, BatterySocTimeseriesResponse, BatteryPowerTimeseriesRequest, BatteryPowerTimeseriesResponse, MeterValuesTimeseriesRequest, MeterValuesTimeseriesResponse, GridPowerTimeseriesRequest, GridPowerTimeseriesResponse, HomeConsumptionTimeseriesRequest, HomeConsumptionTimeseriesResponse, HeatpumpTemperatureTimeseriesRequest, HeatpumpTemperatureTimeseriesResponse, TemperatureSensorTimeseriesRequest, TemperatureSensorTimeseriesResponse, AirConditioningPowerTimeseriesRequest, AirConditioningPowerTimeseriesResponse, AirConditioningTemperatureTimeseriesRequest, AirConditioningTemperatureTimeseriesResponse } from "../types/enyo-timeseries.cjs";
+import { DataBusMessageQueryRequest, DataBusMessageQueryResponse, PvProductionTimeseriesRequest, PvProductionTimeseriesResponse, BatterySocTimeseriesRequest, BatterySocTimeseriesResponse, BatteryPowerTimeseriesRequest, BatteryPowerTimeseriesResponse, MeterValuesTimeseriesRequest, MeterValuesTimeseriesResponse, GridPowerTimeseriesRequest, GridPowerTimeseriesResponse, HomeConsumptionTimeseriesRequest, HomeConsumptionTimeseriesResponse, HeatpumpTemperatureTimeseriesRequest, HeatpumpTemperatureTimeseriesResponse, HeatpumpPowerTimeseriesRequest, HeatpumpPowerTimeseriesResponse, TemperatureSensorTimeseriesRequest, TemperatureSensorTimeseriesResponse, AirConditioningPowerTimeseriesRequest, AirConditioningPowerTimeseriesResponse, AirConditioningTemperatureTimeseriesRequest, AirConditioningTemperatureTimeseriesResponse } from "../types/enyo-timeseries.cjs";
 /**
  * Interface for querying historical energy data with configurable bucket granularity.
  * Provides methods to retrieve aggregated timeseries data for various energy metrics
@@ -159,6 +159,33 @@ export interface EnergyAppTimeseries {
      * ```
      */
     getHeatpumpTemperatureTimeseries(request: HeatpumpTemperatureTimeseriesRequest): Promise<HeatpumpTemperatureTimeseriesResponse>;
+    /**
+     * Retrieves heatpump power timeseries data aggregated in time buckets.
+     * Returns time-weighted average electrical power (W) and cumulative
+     * electrical energy (Wh) for each bucket. When the heatpump reports them,
+     * also returns the split between space heating and domestic hot water for
+     * both electrical consumption and thermal energy delivered.
+     *
+     * Split fields are optional because not all heatpumps report meter values
+     * for the heating / domestic-hot-water categories.
+     *
+     * @param request - The query parameters including date range and optional appliance filter
+     * @returns Promise resolving to heatpump power entries with total electrical consumption
+     *
+     * @example
+     * ```typescript
+     * const response = await timeseries.getHeatpumpPowerTimeseries({
+     *     startDateIso: '2024-01-01T00:00:00Z',
+     *     endDateIso: '2024-01-02T00:00:00Z'
+     * });
+     * console.log(`Total heatpump consumption: ${response.totalHeatpumpPowerWh} Wh`);
+     * if (response.totalHeatGenerationHeatingWh && response.totalPowerConsumptionHeatingWh) {
+     *     const cop = response.totalHeatGenerationHeatingWh / response.totalPowerConsumptionHeatingWh;
+     *     console.log(`Heating COP: ${cop.toFixed(2)}`);
+     * }
+     * ```
+     */
+    getHeatpumpPowerTimeseries(request: HeatpumpPowerTimeseriesRequest): Promise<HeatpumpPowerTimeseriesResponse>;
     /**
      * Retrieves temperature sensor timeseries data aggregated in time buckets.
      * Returns per-sensor average temperature readings for each bucket, along with

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoApplianceTopologyFeatureEnum = exports.EnyoApplianceConnectionType = exports.EnyoApplianceStateEnum = exports.EnyoApplianceTypeEnum = void 0;
+exports.EnyoApplianceTopologyFeatureEnum = exports.EnyoApplianceConnectionType = exports.EnyoApplianceStatusEnum = exports.EnyoApplianceStateEnum = exports.EnyoApplianceTypeEnum = void 0;
 var EnyoApplianceTypeEnum;
 (function (EnyoApplianceTypeEnum) {
     EnyoApplianceTypeEnum["Inverter"] = "Inverter";
@@ -18,6 +18,20 @@ var EnyoApplianceStateEnum;
     EnyoApplianceStateEnum["Offline"] = "offline";
     EnyoApplianceStateEnum["ConfigurationRequired"] = "configuration-required";
 })(EnyoApplianceStateEnum || (exports.EnyoApplianceStateEnum = EnyoApplianceStateEnum = {}));
+/**
+ * Health status of an appliance. Orthogonal to {@link EnyoApplianceStateEnum},
+ * which describes connectivity. `Healthy` means the appliance is operating
+ * normally; `Faulted` means it has reported an internal error and may need
+ * attention. Vendor- or protocol-specific details should be conveyed via
+ * accompanying error codes.
+ */
+var EnyoApplianceStatusEnum;
+(function (EnyoApplianceStatusEnum) {
+    /** Appliance is operating normally */
+    EnyoApplianceStatusEnum["Healthy"] = "healthy";
+    /** Appliance has reported an internal fault */
+    EnyoApplianceStatusEnum["Faulted"] = "faulted";
+})(EnyoApplianceStatusEnum || (exports.EnyoApplianceStatusEnum = EnyoApplianceStatusEnum = {}));
 var EnyoApplianceConnectionType;
 (function (EnyoApplianceConnectionType) {
     EnyoApplianceConnectionType["Connector"] = "Connector";

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

@@ -25,6 +25,19 @@ export declare enum EnyoApplianceStateEnum {
     Offline = "offline",
     ConfigurationRequired = "configuration-required"
 }
+/**
+ * Health status of an appliance. Orthogonal to {@link EnyoApplianceStateEnum},
+ * which describes connectivity. `Healthy` means the appliance is operating
+ * normally; `Faulted` means it has reported an internal error and may need
+ * attention. Vendor- or protocol-specific details should be conveyed via
+ * accompanying error codes.
+ */
+export declare enum EnyoApplianceStatusEnum {
+    /** Appliance is operating normally */
+    Healthy = "healthy",
+    /** Appliance has reported an internal fault */
+    Faulted = "faulted"
+}
 export interface EnyoApplianceNetworkMetadata {
     /** If the appliance is connected via cellular network, you can put the imsi here*/
     imsi?: string;
@@ -55,6 +68,8 @@ export interface EnyoApplianceMetadata {
     hostname?: string;
     ipAddress?: string;
     state?: EnyoApplianceStateEnum;
+    /** Health status of the appliance (e.g. healthy or faulted) */
+    status?: EnyoApplianceStatusEnum;
     network?: EnyoApplianceNetworkMetadata;
     modbus?: EnyoApplianceModbusMetadata;
     /** Optional MQTT configuration */

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

@@ -113,6 +113,7 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["MeterValuesUpdateV1"] = "MeterValuesUpdateV1";
     EnyoDataBusMessageEnum["BatteryValuesUpdateV1"] = "BatteryValuesUpdateV1";
     EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV1"] = "ApplianceFlexibilityAnnouncementV1";
+    EnyoDataBusMessageEnum["ApplianceStateUpdateV1"] = "ApplianceStateUpdateV1";
     EnyoDataBusMessageEnum["HeatpumpValuesUpdateV1"] = "HeatpumpValuesUpdateV1";
     EnyoDataBusMessageEnum["ChargingStartedV1"] = "ChargingStartedV1";
     EnyoDataBusMessageEnum["ChargingMeterValuesUpdateV1"] = "ChargingMeterValuesUpdateV1";

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

@@ -1,4 +1,4 @@
-import { EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "./enyo-appliance.cjs";
+import { EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTypeEnum } from "./enyo-appliance.cjs";
 import { EnyoSourceEnum } from "./enyo-source.enum.cjs";
 import { EnyoOcppRelativeSchedule } from "./enyo-ocpp.cjs";
 import { EnyoChargerApplianceStatusEnum } from "./enyo-charger-appliance.cjs";
@@ -152,6 +152,7 @@ export declare enum EnyoDataBusMessageEnum {
     MeterValuesUpdateV1 = "MeterValuesUpdateV1",
     BatteryValuesUpdateV1 = "BatteryValuesUpdateV1",
     ApplianceFlexibilityAnnouncementV1 = "ApplianceFlexibilityAnnouncementV1",
+    ApplianceStateUpdateV1 = "ApplianceStateUpdateV1",
     HeatpumpValuesUpdateV1 = "HeatpumpValuesUpdateV1",
     ChargingStartedV1 = "ChargingStartedV1",
     ChargingMeterValuesUpdateV1 = "ChargingMeterValuesUpdateV1",
@@ -276,6 +277,8 @@ export interface EnyoDataBusInverterValuesV1String {
     powerW?: number;
     current?: number;
     state?: EnyoStringStateEnum;
+    /** Cumulative energy meter reading for this DC string in Watt hours */
+    meterValueWh?: number;
 }
 export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
     type: 'message';
@@ -303,6 +306,8 @@ export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
         dcPowerW?: number;
         /** Active power Limitation of the Inverter */
         activePowerLimitationW?: number;
+        /** Cumulative AC energy meter reading of the inverter in Watt hours */
+        meterValueWh?: number;
         /** DC String values. Please only provide active strings */
         strings?: EnyoDataBusInverterValuesV1String[];
     };
@@ -320,6 +325,31 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
         };
     };
 }
+/**
+ * Message sent when an appliance's connectivity state and/or health status
+ * changes. At least one of `state` or `status` should be set; both may be
+ * provided together if they change in the same event. `errorCodes` carries
+ * vendor- or protocol-specific codes that explain a transition into a
+ * `faulted` status.
+ */
+export interface EnyoDataBusApplianceStateUpdateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.ApplianceStateUpdateV1;
+    /** ID of the appliance whose state and/or status changed */
+    applianceId: string;
+    data: {
+        /** New connectivity state of the appliance, if it changed */
+        state?: EnyoApplianceStateEnum;
+        /** New health status of the appliance, if it changed */
+        status?: EnyoApplianceStatusEnum;
+        /**
+         * Optional vendor- or protocol-specific error codes that explain the
+         * current status. Typically populated when transitioning into
+         * `faulted`; omitted or empty when there is nothing to report.
+         */
+        errorCodes?: string[];
+    };
+}
 export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ChargingStartedV1;

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

@@ -342,6 +342,51 @@ export interface HeatpumpTemperatureTimeseriesResponse extends TimeseriesRespons
     /** Average buffer tank temperature in degrees Celsius across all buckets */
     averageBufferTankTemperatureC?: number;
 }
+/**
+ * A single entry in the heatpump power timeseries.
+ * Contains electrical power and energy values, optional split between space
+ * heating and domestic hot water consumption, and optional thermal energy
+ * delivered (heat generation) for the same split, for a single time bucket.
+ */
+export interface HeatpumpPowerTimeseriesEntry extends TimeseriesEntryBase {
+    /** Time-weighted average heatpump electrical power consumption in Watts for this bucket */
+    heatpumpPowerW: number;
+    /** Cumulative heatpump electrical energy consumption in Watt-hours for this bucket */
+    heatpumpPowerWh: number;
+    /** Electrical energy consumed for space heating in Watt-hours for this bucket */
+    powerConsumptionHeatingWh?: number;
+    /** Electrical energy consumed for domestic hot water in Watt-hours for this bucket */
+    powerConsumptionDomesticHotWaterWh?: number;
+    /** Thermal energy delivered for space heating in Watt-hours for this bucket */
+    heatGenerationHeatingWh?: number;
+    /** Thermal energy delivered for domestic hot water in Watt-hours for this bucket */
+    heatGenerationDomesticHotWaterWh?: number;
+}
+/**
+ * Request parameters for querying heatpump power timeseries data.
+ */
+export interface HeatpumpPowerTimeseriesRequest extends TimeseriesRequestBase {
+}
+/**
+ * Response containing heatpump power timeseries data.
+ * Aggregated totals for the heating / domestic-hot-water splits and for
+ * heat generation are optional because not all heatpumps report meter values
+ * for every category.
+ */
+export interface HeatpumpPowerTimeseriesResponse extends TimeseriesResponseBase {
+    /** Array of heatpump power entries, one per time bucket */
+    entries: HeatpumpPowerTimeseriesEntry[];
+    /** Total heatpump electrical energy consumption in Watt-hours across all buckets */
+    totalHeatpumpPowerWh: number;
+    /** Total electrical energy consumed for space heating in Watt-hours across all buckets */
+    totalPowerConsumptionHeatingWh?: number;
+    /** Total electrical energy consumed for domestic hot water in Watt-hours across all buckets */
+    totalPowerConsumptionDomesticHotWaterWh?: number;
+    /** Total thermal energy delivered for space heating in Watt-hours across all buckets */
+    totalHeatGenerationHeatingWh?: number;
+    /** Total thermal energy delivered for domestic hot water in Watt-hours across all buckets */
+    totalHeatGenerationDomesticHotWaterWh?: number;
+}
 /**
  * A single entry in the temperature sensor timeseries.
  * Contains per-sensor average temperature readings for a single time bucket.

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

package/dist/implementations/forecasts/heatpump-consumption-forecast.d.ts

@@ -9,8 +9,10 @@ import { BaseForecast, Forecaster, ForecastConfig } from './forecast-types.js';
 export type HeatpumpConsumptionForecastResult = BaseForecast<EnyoDataBusHeatpumpConsumptionForecastV1['data']>;
 /**
  * Builds a 24-hour heatpump electrical consumption forecast for a single
- * heatpump appliance from historical `HeatpumpValuesUpdateV1` data-bus
- * messages, with live updates merged in as new readings arrive.
+ * heatpump appliance. Historical buckets are sourced from the dedicated
+ * `useTimeseries().getHeatpumpPowerTimeseries()` endpoint, and live
+ * `HeatpumpValuesUpdateV1` data-bus messages are merged in as new readings
+ * arrive.
  *
  * Heatpump operation is strongly tied to outdoor temperature (which itself is
  * weekday-cyclic on average), so the algorithm uses a same-weekday
@@ -51,8 +53,9 @@ export declare class HeatpumpConsumptionForecast implements Forecaster {
         config?: ForecastConfig;
     });
     /**
-     * Pulls historical `HeatpumpValuesUpdateV1` messages, aggregates them into
-     * 15-minute slots, and starts listening to live heatpump events. Idempotent.
+     * Loads historical heatpump power buckets via
+     * `useTimeseries().getHeatpumpPowerTimeseries()` and starts listening to
+     * live `HeatpumpValuesUpdateV1` events for ongoing updates. Idempotent.
      */
     initialize(): Promise<void>;
     /**

package/dist/implementations/forecasts/heatpump-consumption-forecast.js

@@ -3,8 +3,10 @@ import { resolveForecastConfig, } from './forecast-types.js';
 import { FIFTEEN_MIN_MS, alignForecastToRecentActuals, buildForecastSlots, buildIsoIndex, buildSlotMap, parseHistory, roundDownTo15Minutes, trimHistory, upsertLiveBucket, weightedAverageBySlot, wToWhPer15Min, } from './forecast-utils.js';
 /**
  * Builds a 24-hour heatpump electrical consumption forecast for a single
- * heatpump appliance from historical `HeatpumpValuesUpdateV1` data-bus
- * messages, with live updates merged in as new readings arrive.
+ * heatpump appliance. Historical buckets are sourced from the dedicated
+ * `useTimeseries().getHeatpumpPowerTimeseries()` endpoint, and live
+ * `HeatpumpValuesUpdateV1` data-bus messages are merged in as new readings
+ * arrive.
  *
  * Heatpump operation is strongly tied to outdoor temperature (which itself is
  * weekday-cyclic on average), so the algorithm uses a same-weekday
@@ -47,8 +49,9 @@ export class HeatpumpConsumptionForecast {
         this.source = options.source;
     }
     /**
-     * Pulls historical `HeatpumpValuesUpdateV1` messages, aggregates them into
-     * 15-minute slots, and starts listening to live heatpump events. Idempotent.
+     * Loads historical heatpump power buckets via
+     * `useTimeseries().getHeatpumpPowerTimeseries()` and starts listening to
+     * live `HeatpumpValuesUpdateV1` events for ongoing updates. Idempotent.
      */
     async initialize() {
         if (this.initialized)
@@ -56,35 +59,20 @@ export class HeatpumpConsumptionForecast {
         this.initialized = true;
         const now = Date.now();
         const startMs = now - this.config.historyDays * 24 * 60 * 60 * 1000;
-        const response = await this.app.useTimeseries().queryDataBusMessages({
-            applianceId: this.applianceId,
+        const response = await this.app.useTimeseries().getHeatpumpPowerTimeseries({
             startDateIso: new Date(startMs).toISOString(),
             endDateIso: new Date(now).toISOString(),
-            messageTypes: [EnyoDataBusMessageEnum.HeatpumpValuesUpdateV1],
-            limit: 100000,
+            applianceIds: [this.applianceId],
+            resolution: this.config.resolution,
         });
-        const slotAggregator = new Map();
-        for (const raw of response.messages) {
-            const message = raw;
-            const power = message.data.values.powerW;
-            if (typeof power !== 'number' || Number.isNaN(power))
-                continue;
-            const slotMs = roundDownTo15Minutes(new Date(message.timestampIso).getTime());
-            const existing = slotAggregator.get(slotMs);
-            if (existing) {
-                existing.sum += power;
-                existing.count += 1;
-            }
-            else {
-                slotAggregator.set(slotMs, { sum: power, count: 1 });
-            }
-        }
-        const slots = Array.from(slotAggregator.keys()).sort((a, b) => a - b);
-        for (const slotMs of slots) {
-            const agg = slotAggregator.get(slotMs);
+        for (const entry of response.entries) {
             this.history.push({
-                timestampIso: new Date(slotMs).toISOString(),
-                values: { powerW: agg.sum / agg.count, samples: agg.count },
+                timestampIso: entry.timestampIso,
+                values: {
+                    powerW: entry.heatpumpPowerW,
+                    powerWh: entry.heatpumpPowerWh,
+                    samples: 1,
+                },
             });
         }
         this.listenerId = this.app.useDataBus().listenForMessages([EnyoDataBusMessageEnum.HeatpumpValuesUpdateV1], (msg) => this.onHeatpumpValues(msg));
@@ -176,10 +164,12 @@ export class HeatpumpConsumptionForecast {
         if (this.currentSlotMs === undefined || this.currentSlotSamples === 0)
             return;
         const avg = this.currentSlotPowerSum / this.currentSlotSamples;
-        upsertLiveBucket(this.history, this.currentSlotMs, { powerW: avg, samples: this.currentSlotSamples }, (existing, incoming) => {
+        upsertLiveBucket(this.history, this.currentSlotMs, { powerW: avg, powerWh: wToWhPer15Min(avg), samples: this.currentSlotSamples }, (existing, incoming) => {
             const total = existing.samples + incoming.samples;
+            const mergedPowerW = (existing.powerW * existing.samples + incoming.powerW * incoming.samples) / total;
             return {
-                powerW: (existing.powerW * existing.samples + incoming.powerW * incoming.samples) / total,
+                powerW: mergedPowerW,
+                powerWh: wToWhPer15Min(mergedPowerW),
                 samples: total,
             };
         });

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

@@ -1,4 +1,4 @@
-import { DataBusMessageQueryRequest, DataBusMessageQueryResponse, PvProductionTimeseriesRequest, PvProductionTimeseriesResponse, BatterySocTimeseriesRequest, BatterySocTimeseriesResponse, BatteryPowerTimeseriesRequest, BatteryPowerTimeseriesResponse, MeterValuesTimeseriesRequest, MeterValuesTimeseriesResponse, GridPowerTimeseriesRequest, GridPowerTimeseriesResponse, HomeConsumptionTimeseriesRequest, HomeConsumptionTimeseriesResponse, HeatpumpTemperatureTimeseriesRequest, HeatpumpTemperatureTimeseriesResponse, TemperatureSensorTimeseriesRequest, TemperatureSensorTimeseriesResponse, AirConditioningPowerTimeseriesRequest, AirConditioningPowerTimeseriesResponse, AirConditioningTemperatureTimeseriesRequest, AirConditioningTemperatureTimeseriesResponse } from "../types/enyo-timeseries.js";
+import { DataBusMessageQueryRequest, DataBusMessageQueryResponse, PvProductionTimeseriesRequest, PvProductionTimeseriesResponse, BatterySocTimeseriesRequest, BatterySocTimeseriesResponse, BatteryPowerTimeseriesRequest, BatteryPowerTimeseriesResponse, MeterValuesTimeseriesRequest, MeterValuesTimeseriesResponse, GridPowerTimeseriesRequest, GridPowerTimeseriesResponse, HomeConsumptionTimeseriesRequest, HomeConsumptionTimeseriesResponse, HeatpumpTemperatureTimeseriesRequest, HeatpumpTemperatureTimeseriesResponse, HeatpumpPowerTimeseriesRequest, HeatpumpPowerTimeseriesResponse, TemperatureSensorTimeseriesRequest, TemperatureSensorTimeseriesResponse, AirConditioningPowerTimeseriesRequest, AirConditioningPowerTimeseriesResponse, AirConditioningTemperatureTimeseriesRequest, AirConditioningTemperatureTimeseriesResponse } from "../types/enyo-timeseries.js";
 /**
  * Interface for querying historical energy data with configurable bucket granularity.
  * Provides methods to retrieve aggregated timeseries data for various energy metrics
@@ -159,6 +159,33 @@ export interface EnergyAppTimeseries {
      * ```
      */
     getHeatpumpTemperatureTimeseries(request: HeatpumpTemperatureTimeseriesRequest): Promise<HeatpumpTemperatureTimeseriesResponse>;
+    /**
+     * Retrieves heatpump power timeseries data aggregated in time buckets.
+     * Returns time-weighted average electrical power (W) and cumulative
+     * electrical energy (Wh) for each bucket. When the heatpump reports them,
+     * also returns the split between space heating and domestic hot water for
+     * both electrical consumption and thermal energy delivered.
+     *
+     * Split fields are optional because not all heatpumps report meter values
+     * for the heating / domestic-hot-water categories.
+     *
+     * @param request - The query parameters including date range and optional appliance filter
+     * @returns Promise resolving to heatpump power entries with total electrical consumption
+     *
+     * @example
+     * ```typescript
+     * const response = await timeseries.getHeatpumpPowerTimeseries({
+     *     startDateIso: '2024-01-01T00:00:00Z',
+     *     endDateIso: '2024-01-02T00:00:00Z'
+     * });
+     * console.log(`Total heatpump consumption: ${response.totalHeatpumpPowerWh} Wh`);
+     * if (response.totalHeatGenerationHeatingWh && response.totalPowerConsumptionHeatingWh) {
+     *     const cop = response.totalHeatGenerationHeatingWh / response.totalPowerConsumptionHeatingWh;
+     *     console.log(`Heating COP: ${cop.toFixed(2)}`);
+     * }
+     * ```
+     */
+    getHeatpumpPowerTimeseries(request: HeatpumpPowerTimeseriesRequest): Promise<HeatpumpPowerTimeseriesResponse>;
     /**
      * Retrieves temperature sensor timeseries data aggregated in time buckets.
      * Returns per-sensor average temperature readings for each bucket, along with

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

@@ -25,6 +25,19 @@ export declare enum EnyoApplianceStateEnum {
     Offline = "offline",
     ConfigurationRequired = "configuration-required"
 }
+/**
+ * Health status of an appliance. Orthogonal to {@link EnyoApplianceStateEnum},
+ * which describes connectivity. `Healthy` means the appliance is operating
+ * normally; `Faulted` means it has reported an internal error and may need
+ * attention. Vendor- or protocol-specific details should be conveyed via
+ * accompanying error codes.
+ */
+export declare enum EnyoApplianceStatusEnum {
+    /** Appliance is operating normally */
+    Healthy = "healthy",
+    /** Appliance has reported an internal fault */
+    Faulted = "faulted"
+}
 export interface EnyoApplianceNetworkMetadata {
     /** If the appliance is connected via cellular network, you can put the imsi here*/
     imsi?: string;
@@ -55,6 +68,8 @@ export interface EnyoApplianceMetadata {
     hostname?: string;
     ipAddress?: string;
     state?: EnyoApplianceStateEnum;
+    /** Health status of the appliance (e.g. healthy or faulted) */
+    status?: EnyoApplianceStatusEnum;
     network?: EnyoApplianceNetworkMetadata;
     modbus?: EnyoApplianceModbusMetadata;
     /** Optional MQTT configuration */

package/dist/types/enyo-appliance.js

@@ -15,6 +15,20 @@ export var EnyoApplianceStateEnum;
     EnyoApplianceStateEnum["Offline"] = "offline";
     EnyoApplianceStateEnum["ConfigurationRequired"] = "configuration-required";
 })(EnyoApplianceStateEnum || (EnyoApplianceStateEnum = {}));
+/**
+ * Health status of an appliance. Orthogonal to {@link EnyoApplianceStateEnum},
+ * which describes connectivity. `Healthy` means the appliance is operating
+ * normally; `Faulted` means it has reported an internal error and may need
+ * attention. Vendor- or protocol-specific details should be conveyed via
+ * accompanying error codes.
+ */
+export var EnyoApplianceStatusEnum;
+(function (EnyoApplianceStatusEnum) {
+    /** Appliance is operating normally */
+    EnyoApplianceStatusEnum["Healthy"] = "healthy";
+    /** Appliance has reported an internal fault */
+    EnyoApplianceStatusEnum["Faulted"] = "faulted";
+})(EnyoApplianceStatusEnum || (EnyoApplianceStatusEnum = {}));
 export var EnyoApplianceConnectionType;
 (function (EnyoApplianceConnectionType) {
     EnyoApplianceConnectionType["Connector"] = "Connector";

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

@@ -1,4 +1,4 @@
-import { EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "./enyo-appliance.js";
+import { EnyoApplianceStateEnum, EnyoApplianceStatusEnum, EnyoApplianceTypeEnum } from "./enyo-appliance.js";
 import { EnyoSourceEnum } from "./enyo-source.enum.js";
 import { EnyoOcppRelativeSchedule } from "./enyo-ocpp.js";
 import { EnyoChargerApplianceStatusEnum } from "./enyo-charger-appliance.js";
@@ -152,6 +152,7 @@ export declare enum EnyoDataBusMessageEnum {
     MeterValuesUpdateV1 = "MeterValuesUpdateV1",
     BatteryValuesUpdateV1 = "BatteryValuesUpdateV1",
     ApplianceFlexibilityAnnouncementV1 = "ApplianceFlexibilityAnnouncementV1",
+    ApplianceStateUpdateV1 = "ApplianceStateUpdateV1",
     HeatpumpValuesUpdateV1 = "HeatpumpValuesUpdateV1",
     ChargingStartedV1 = "ChargingStartedV1",
     ChargingMeterValuesUpdateV1 = "ChargingMeterValuesUpdateV1",
@@ -276,6 +277,8 @@ export interface EnyoDataBusInverterValuesV1String {
     powerW?: number;
     current?: number;
     state?: EnyoStringStateEnum;
+    /** Cumulative energy meter reading for this DC string in Watt hours */
+    meterValueWh?: number;
 }
 export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
     type: 'message';
@@ -303,6 +306,8 @@ export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
         dcPowerW?: number;
         /** Active power Limitation of the Inverter */
         activePowerLimitationW?: number;
+        /** Cumulative AC energy meter reading of the inverter in Watt hours */
+        meterValueWh?: number;
         /** DC String values. Please only provide active strings */
         strings?: EnyoDataBusInverterValuesV1String[];
     };
@@ -320,6 +325,31 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
         };
     };
 }
+/**
+ * Message sent when an appliance's connectivity state and/or health status
+ * changes. At least one of `state` or `status` should be set; both may be
+ * provided together if they change in the same event. `errorCodes` carries
+ * vendor- or protocol-specific codes that explain a transition into a
+ * `faulted` status.
+ */
+export interface EnyoDataBusApplianceStateUpdateV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.ApplianceStateUpdateV1;
+    /** ID of the appliance whose state and/or status changed */
+    applianceId: string;
+    data: {
+        /** New connectivity state of the appliance, if it changed */
+        state?: EnyoApplianceStateEnum;
+        /** New health status of the appliance, if it changed */
+        status?: EnyoApplianceStatusEnum;
+        /**
+         * Optional vendor- or protocol-specific error codes that explain the
+         * current status. Typically populated when transitioning into
+         * `faulted`; omitted or empty when there is nothing to report.
+         */
+        errorCodes?: string[];
+    };
+}
 export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ChargingStartedV1;

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

@@ -110,6 +110,7 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["MeterValuesUpdateV1"] = "MeterValuesUpdateV1";
     EnyoDataBusMessageEnum["BatteryValuesUpdateV1"] = "BatteryValuesUpdateV1";
     EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV1"] = "ApplianceFlexibilityAnnouncementV1";
+    EnyoDataBusMessageEnum["ApplianceStateUpdateV1"] = "ApplianceStateUpdateV1";
     EnyoDataBusMessageEnum["HeatpumpValuesUpdateV1"] = "HeatpumpValuesUpdateV1";
     EnyoDataBusMessageEnum["ChargingStartedV1"] = "ChargingStartedV1";
     EnyoDataBusMessageEnum["ChargingMeterValuesUpdateV1"] = "ChargingMeterValuesUpdateV1";

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

@@ -342,6 +342,51 @@ export interface HeatpumpTemperatureTimeseriesResponse extends TimeseriesRespons
     /** Average buffer tank temperature in degrees Celsius across all buckets */
     averageBufferTankTemperatureC?: number;
 }
+/**
+ * A single entry in the heatpump power timeseries.
+ * Contains electrical power and energy values, optional split between space
+ * heating and domestic hot water consumption, and optional thermal energy
+ * delivered (heat generation) for the same split, for a single time bucket.
+ */
+export interface HeatpumpPowerTimeseriesEntry extends TimeseriesEntryBase {
+    /** Time-weighted average heatpump electrical power consumption in Watts for this bucket */
+    heatpumpPowerW: number;
+    /** Cumulative heatpump electrical energy consumption in Watt-hours for this bucket */
+    heatpumpPowerWh: number;
+    /** Electrical energy consumed for space heating in Watt-hours for this bucket */
+    powerConsumptionHeatingWh?: number;
+    /** Electrical energy consumed for domestic hot water in Watt-hours for this bucket */
+    powerConsumptionDomesticHotWaterWh?: number;
+    /** Thermal energy delivered for space heating in Watt-hours for this bucket */
+    heatGenerationHeatingWh?: number;
+    /** Thermal energy delivered for domestic hot water in Watt-hours for this bucket */
+    heatGenerationDomesticHotWaterWh?: number;
+}
+/**
+ * Request parameters for querying heatpump power timeseries data.
+ */
+export interface HeatpumpPowerTimeseriesRequest extends TimeseriesRequestBase {
+}
+/**
+ * Response containing heatpump power timeseries data.
+ * Aggregated totals for the heating / domestic-hot-water splits and for
+ * heat generation are optional because not all heatpumps report meter values
+ * for every category.
+ */
+export interface HeatpumpPowerTimeseriesResponse extends TimeseriesResponseBase {
+    /** Array of heatpump power entries, one per time bucket */
+    entries: HeatpumpPowerTimeseriesEntry[];
+    /** Total heatpump electrical energy consumption in Watt-hours across all buckets */
+    totalHeatpumpPowerWh: number;
+    /** Total electrical energy consumed for space heating in Watt-hours across all buckets */
+    totalPowerConsumptionHeatingWh?: number;
+    /** Total electrical energy consumed for domestic hot water in Watt-hours across all buckets */
+    totalPowerConsumptionDomesticHotWaterWh?: number;
+    /** Total thermal energy delivered for space heating in Watt-hours across all buckets */
+    totalHeatGenerationHeatingWh?: number;
+    /** Total thermal energy delivered for domestic hot water in Watt-hours across all buckets */
+    totalHeatGenerationDomesticHotWaterWh?: number;
+}
 /**
  * A single entry in the temperature sensor timeseries.
  * Contains per-sensor average temperature readings for a single time bucket.

package/dist/version.d.ts

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