@enyo-energy/energy-app-sdk 1.10.0 → 1.11.0

package/README.md

@@ -84,6 +84,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [Basic Energy App](#basic-energy-app)
   - [Device Integration](#device-integration)
   - [Data Bus Messaging](#data-bus-messaging)
+    - [Announcing Appliance Flexibility](#announcing-appliance-flexibility)
   - [Settings Management](#settings-management)
 - [Troubleshooting](#troubleshooting)
 - [External Libraries](#external-libraries)
@@ -1494,7 +1495,7 @@ Publishers need `PvSystemRegister`; consumers need `PvSystemUse`.
 
 #### `useTimeseries(): EnergyAppTimeseries`
 
-Query historical 15-minute aggregated data across the energy domain (PV production, battery SoC / power, meter values, grid power, home consumption, heatpump electrical / thermal, air-conditioning, temperature sensors). Some endpoints also support 1-minute resolution.
+Query historical 15-minute aggregated data across the energy domain (PV production, battery SoC / power, meter values, grid power, home consumption, heatpump electrical / thermal, air-conditioning, temperature sensors, smart plugs). Some endpoints also support 1-minute resolution.
 
 ```typescript
 const ts = energyApp.useTimeseries();
@@ -3529,6 +3530,74 @@ energyApp.register(async (packageName, version) => {
 });
 ```
 
+#### Announcing Appliance Flexibility
+
+An appliance tells the rest of the system how much energy it can shift, and
+until when, with `ApplianceFlexibilityAnnouncementV1`. Optionally it can also say
+**how much watt for what** — which part of the system the energy would go into —
+so the consumer of the announcement can reason about the demand behind the number
+instead of treating it as one opaque block.
+
+The breakdown is a list of `EnyoFlexibilityTargetPower` entries under
+`data.flexibility.context.targets`. Each entry names a `EnyoFlexibilityTargetEnum`
+target, the power that share would draw in Watts, and optionally the share of the
+announced energy in kWh.
+
+`EnyoFlexibilityTargetEnum` is an open vocabulary. Today it covers
+`domesticHotWater`, `bufferTank`, and `heating`, since thermal appliances are the
+first to split their draw — but it is not limited to thermal targets, and further
+members may describe non-thermal ones. Treat an unknown value as "some other
+target" rather than assuming it is a heat sink.
+
+```typescript
+import {
+    EnergyApp,
+    EnyoFlexibilityTargetEnum,
+} from '@enyo-energy/energy-app-sdk';
+
+const energyApp = new EnergyApp();
+const dataBus = energyApp.useDataBus();
+
+dataBus.sendMessage([{
+    type: 'message',
+    message: 'ApplianceFlexibilityAnnouncementV1',
+    applianceId: 'heatpump-1',
+    data: {
+        flexibility: {
+            // Authoritative total: 4 kWh can be shifted until 14:00.
+            kWh: 4,
+            availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+            // Optional: what those 4 kWh are for, and at which power.
+            context: {
+                targets: [
+                    {
+                        target: EnyoFlexibilityTargetEnum.DomesticHotWater,
+                        powerW: 1500,
+                        kWh: 2.5,
+                    },
+                    {
+                        target: EnyoFlexibilityTargetEnum.BufferTank,
+                        powerW: 800,
+                        kWh: 1.5,
+                    },
+                ],
+            },
+        },
+    },
+}]);
+```
+
+Notes:
+
+- `context` is entirely optional — existing publishers that only send `kWh` and
+  `availableUntilIsoTimestamp` stay valid.
+- The breakdown may be **partial**: its entries do not have to sum to `kWh` or to
+  the appliance's full draw. Only `kWh` is authoritative.
+- A given target should appear at most once per breakdown.
+- The same breakdown is available on category-level announcements via
+  `context.targets` on `EnyoFlexibilityAnnouncementContext`, so the
+  per-appliance and aggregated surfaces stay in step.
+
 ### Settings Management
 
 Dynamic configuration with user interface:

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, HeatpumpPowerTimeseriesRequest, HeatpumpPowerTimeseriesResponse, 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, SmartPlugTimeseriesRequest, SmartPlugTimeseriesResponse } 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
@@ -253,4 +253,33 @@ export interface EnergyAppTimeseries {
      * ```
      */
     getAirConditioningTemperatureTimeseries(request: AirConditioningTemperatureTimeseriesRequest): Promise<AirConditioningTemperatureTimeseriesResponse>;
+    /**
+     * Retrieves smart plug timeseries data aggregated in time buckets.
+     *
+     * Every bucket carries the aggregate across all included plugs
+     * (`smartPlugPowerW` / `Wh`) plus a per-plug breakdown, since a plug measures
+     * an arbitrary load and the total alone does not say which load ran. The
+     * response additionally summarises each plug across the full period.
+     *
+     * Per-plug fields are optional because plug capabilities differ: a
+     * measure-only plug reports power but no runtime, a switch-only plug reports
+     * runtime (`onDurationMinutes`, `switchCount`) but no power.
+     *
+     * @param request - The query parameters including date range and optional appliance filter
+     * @returns Promise resolving to smart plug entries with the total and per-plug summaries
+     *
+     * @example
+     * ```typescript
+     * const response = await timeseries.getSmartPlugTimeseries({
+     *     startDateIso: '2024-01-01T00:00:00Z',
+     *     endDateIso: '2024-01-02T00:00:00Z'
+     * });
+     * console.log(`Total plug consumption: ${response.totalSmartPlugPowerWh} Wh`);
+     * response.plugs.forEach(plug => {
+     *     console.log(`${plug.applianceId}: ${plug.totalPowerWh ?? 0} Wh, ` +
+     *         `on for ${plug.totalOnDurationMinutes ?? 0} min`);
+     * });
+     * ```
+     */
+    getSmartPlugTimeseries(request: SmartPlugTimeseriesRequest): Promise<SmartPlugTimeseriesResponse>;
 }

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

@@ -7,6 +7,7 @@ import { PreviewChargingSchedule, PreviewChargingScheduleCostComparison, Preview
 import { EnyoEnergyPrices } from "./enyo-energy-prices.cjs";
 import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.cjs";
+import type { EnyoFlexibilityTargetPower } from "./enyo-flexibility-announcement.cjs";
 import { EnyoSmartPlugApplianceStateEnum } from "./enyo-smart-plug-appliance.cjs";
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum } from "./enyo-air-conditioning-appliance.cjs";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.cjs";
@@ -579,6 +580,36 @@ export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
         gridOperatorLimit?: EnyoGridOperatorLimit;
     };
 }
+/**
+ * An appliance announces how much energy it can shift, and until when.
+ *
+ * Optionally it can also say *what the energy is for and at which power* via
+ * `data.flexibility.context.targets` — e.g. a heat pump splitting its draw
+ * between the domestic hot water tank, the heating buffer tank, and the space
+ * heating circuit. That breakdown is additive context for the decision maker;
+ * `kWh` remains the authoritative total.
+ *
+ * @example
+ * ```typescript
+ * dataBus.sendMessage([{
+ *     type: 'message',
+ *     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV1,
+ *     applianceId: 'heatpump-1',
+ *     data: {
+ *         flexibility: {
+ *             kWh: 4,
+ *             availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+ *             context: {
+ *                 targets: [
+ *                     {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500, kWh: 2.5},
+ *                     {target: EnyoFlexibilityTargetEnum.BufferTank, powerW: 800, kWh: 1.5},
+ *                 ],
+ *             },
+ *         },
+ *     },
+ * }]);
+ * ```
+ */
 export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV1;
@@ -589,6 +620,19 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
             kWh: number;
             /** Defines until the kWh flexibility can be shifted. If for Example 10 kWh can be shifted until 2025-10-01T14:00:00 (current time 2025-10-01T10:00:00), the control can shift the 10 kWh in the next 4 hours */
             availableUntilIsoTimestamp: string;
+            /**
+             * Optional extra context for the consumer of this announcement.
+             * Nested so further context keys can be added without changing the
+             * message shape again.
+             */
+            context?: {
+                /**
+                 * Breakdown of what the announced flexibility is for and at which
+                 * power. May be partial — entries need not sum to the appliance's
+                 * full draw — and a given target SHOULD appear at most once.
+                 */
+                targets: EnyoFlexibilityTargetPower[];
+            };
         };
     };
 }

package/dist/cjs/types/enyo-flexibility-announcement.cjs

@@ -14,7 +14,7 @@
 // deliberately uses TS enums — the values below are the exact on-the-wire
 // strings, so the enums stay wire-compatible while giving callers named members.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoCategoryFlexibilityGrantStatusEnum = exports.EnyoFlexibilityOptimizationModeEnum = exports.EnyoFlexibilityTimingTargetEnum = exports.EnyoFlexibilityAirConditioningTargetTypeEnum = exports.EnyoFlexibilityHeatpumpTargetTypeEnum = exports.EnyoFlexibilityAnnouncementTypeEnum = void 0;
+exports.EnyoCategoryFlexibilityGrantStatusEnum = exports.EnyoFlexibilityOptimizationModeEnum = exports.EnyoFlexibilityTimingTargetEnum = exports.EnyoFlexibilityAirConditioningTargetTypeEnum = exports.EnyoFlexibilityTargetEnum = exports.EnyoFlexibilityHeatpumpTargetTypeEnum = exports.EnyoFlexibilityAnnouncementTypeEnum = void 0;
 // ─── Vocabulary enums ───────────────────────────────────────
 /** Discriminant tag for the four flexibility-announcement variants. */
 var EnyoFlexibilityAnnouncementTypeEnum;
@@ -32,6 +32,13 @@ var EnyoFlexibilityAnnouncementTypeEnum;
  * What a heat pump's flexibility is aimed at — gives the decision maker extra
  * context on the demand behind a heat-pump announcement. `Cooling` is reserved
  * for a future cooling mode and is not emitted yet.
+ *
+ * This enum describes the *mode* a heat pump runs in. To say what the announced
+ * energy is for — and how much power goes to each target — use
+ * {@link EnyoFlexibilityTargetEnum} together with
+ * {@link EnyoFlexibilityTargetPower}. The overlap between the two
+ * (`heating` / `dhw`) is intentional: both vocabularies stay wire-stable on
+ * their own.
  */
 var EnyoFlexibilityHeatpumpTargetTypeEnum;
 (function (EnyoFlexibilityHeatpumpTargetTypeEnum) {
@@ -39,6 +46,38 @@ var EnyoFlexibilityHeatpumpTargetTypeEnum;
     EnyoFlexibilityHeatpumpTargetTypeEnum["Cooling"] = "cooling";
     EnyoFlexibilityHeatpumpTargetTypeEnum["Dhw"] = "dhw";
 })(EnyoFlexibilityHeatpumpTargetTypeEnum || (exports.EnyoFlexibilityHeatpumpTargetTypeEnum = EnyoFlexibilityHeatpumpTargetTypeEnum = {}));
+/**
+ * What an announced share of flexibility is physically aimed at — the open
+ * vocabulary behind the "how much watt for what" breakdown carried by
+ * {@link EnyoFlexibilityTargetPower}.
+ *
+ * The members present today all describe heat sinks, because thermal appliances
+ * are the first ones to split their draw. The enum is deliberately **not**
+ * scoped to thermal loads though: further members may describe non-thermal
+ * targets (a vehicle battery, a stationary storage, a dedicated household
+ * circuit) as other appliance types start announcing a breakdown. Consumers
+ * should therefore treat an unknown value as "some other target" rather than
+ * assuming every value maps to a heat sink.
+ *
+ * Broader than {@link EnyoFlexibilityHeatpumpTargetTypeEnum}, which names the
+ * *mode* a heat pump runs in: this enum adds the heating buffer tank, is not
+ * heat-pump specific (a heating rod announces against the same sinks), and
+ * carries no `cooling` member — cooling is a run mode, not a target.
+ *
+ * Values match the vocabulary used elsewhere in the SDK for the same physical
+ * parts (e.g. `domesticHotWater` and `bufferTank...` in the timeseries types),
+ * so a consumer can correlate an announcement with measured values without a
+ * mapping table.
+ */
+var EnyoFlexibilityTargetEnum;
+(function (EnyoFlexibilityTargetEnum) {
+    /** Domestic hot water tank. */
+    EnyoFlexibilityTargetEnum["DomesticHotWater"] = "domesticHotWater";
+    /** Heating buffer / storage tank. */
+    EnyoFlexibilityTargetEnum["BufferTank"] = "bufferTank";
+    /** Space heating circuit. */
+    EnyoFlexibilityTargetEnum["Heating"] = "heating";
+})(EnyoFlexibilityTargetEnum || (exports.EnyoFlexibilityTargetEnum = EnyoFlexibilityTargetEnum = {}));
 /**
  * What an air-conditioning unit's flexibility is aimed at — extra context for
  * the decision maker. Cooling-only today; a heating variant may follow.

package/dist/cjs/types/enyo-flexibility-announcement.d.cts

@@ -24,12 +24,50 @@ export declare enum EnyoFlexibilityAnnouncementTypeEnum {
  * What a heat pump's flexibility is aimed at — gives the decision maker extra
  * context on the demand behind a heat-pump announcement. `Cooling` is reserved
  * for a future cooling mode and is not emitted yet.
+ *
+ * This enum describes the *mode* a heat pump runs in. To say what the announced
+ * energy is for — and how much power goes to each target — use
+ * {@link EnyoFlexibilityTargetEnum} together with
+ * {@link EnyoFlexibilityTargetPower}. The overlap between the two
+ * (`heating` / `dhw`) is intentional: both vocabularies stay wire-stable on
+ * their own.
  */
 export declare enum EnyoFlexibilityHeatpumpTargetTypeEnum {
     Heating = "heating",
     Cooling = "cooling",
     Dhw = "dhw"
 }
+/**
+ * What an announced share of flexibility is physically aimed at — the open
+ * vocabulary behind the "how much watt for what" breakdown carried by
+ * {@link EnyoFlexibilityTargetPower}.
+ *
+ * The members present today all describe heat sinks, because thermal appliances
+ * are the first ones to split their draw. The enum is deliberately **not**
+ * scoped to thermal loads though: further members may describe non-thermal
+ * targets (a vehicle battery, a stationary storage, a dedicated household
+ * circuit) as other appliance types start announcing a breakdown. Consumers
+ * should therefore treat an unknown value as "some other target" rather than
+ * assuming every value maps to a heat sink.
+ *
+ * Broader than {@link EnyoFlexibilityHeatpumpTargetTypeEnum}, which names the
+ * *mode* a heat pump runs in: this enum adds the heating buffer tank, is not
+ * heat-pump specific (a heating rod announces against the same sinks), and
+ * carries no `cooling` member — cooling is a run mode, not a target.
+ *
+ * Values match the vocabulary used elsewhere in the SDK for the same physical
+ * parts (e.g. `domesticHotWater` and `bufferTank...` in the timeseries types),
+ * so a consumer can correlate an announcement with measured values without a
+ * mapping table.
+ */
+export declare enum EnyoFlexibilityTargetEnum {
+    /** Domestic hot water tank. */
+    DomesticHotWater = "domesticHotWater",
+    /** Heating buffer / storage tank. */
+    BufferTank = "bufferTank",
+    /** Space heating circuit. */
+    Heating = "heating"
+}
 /**
  * What an air-conditioning unit's flexibility is aimed at — extra context for
  * the decision maker. Cooling-only today; a heating variant may follow.
@@ -60,6 +98,35 @@ export declare enum EnyoFlexibilityOptimizationModeEnum {
     PvSurplusPreferred = "pv-surplus-preferred",
     PriceLimit = "price-limit"
 }
+/**
+ * How much power the announced flexibility would draw for one target — one
+ * entry of the "how much watt for what" breakdown behind an announcement.
+ *
+ * Purely informational context: the announcement's own energy figure stays
+ * authoritative. A breakdown may be partial — its entries need not sum to the
+ * appliance's full draw — but a given {@link target} SHOULD appear at most once
+ * per breakdown.
+ *
+ * @example
+ * ```typescript
+ * // A heat pump that would put 1500 W into the DHW tank and 800 W into heating
+ * const targets: EnyoFlexibilityTargetPower[] = [
+ *     {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500, kWh: 2.5},
+ *     {target: EnyoFlexibilityTargetEnum.Heating, powerW: 800},
+ * ];
+ * ```
+ */
+export interface EnyoFlexibilityTargetPower {
+    /** What this share is for. */
+    target: EnyoFlexibilityTargetEnum;
+    /** Electrical power this share would draw, in Watts. Non-negative. */
+    powerW: number;
+    /**
+     * Share of the announced energy attributable to this target, in kWh.
+     * Optional — omit when only the power split is known.
+     */
+    kWh?: number;
+}
 /** Discrete power band the solver may pick from: [minWatt, maxWatt] in stepWatt steps. */
 export interface EnyoFlexibilityPowerBand {
     /** Lower bound of the band, in Watts. Non-negative. */
@@ -125,6 +192,13 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * How much power the announced flexibility would draw per target — "how much
+     * watt for what". Keeps the category surface in step with the per-appliance
+     * announcement, which carries the same breakdown under
+     * `data.flexibility.context.targets`.
+     */
+    targets?: EnyoFlexibilityTargetPower[];
     /**
      * For storage announcements: the round-trip cost of cycling the battery, in
      * EUR per kWh. The floor a discharge has to beat to be worth licensing.

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

@@ -538,3 +538,94 @@ export interface AirConditioningTemperatureTimeseriesResponse extends Timeseries
     /** Array of air conditioning temperature entries, one per time bucket */
     entries: AirConditioningTemperatureTimeseriesEntry[];
 }
+/**
+ * Power and runtime figures for a single smart plug within one time bucket.
+ *
+ * A smart plug measures an arbitrary load, so the per-plug breakdown matters
+ * more here than for other appliance types: summing several plugs gives the
+ * total switchable load, but only the per-plug values say *which* load ran.
+ *
+ * Every field other than the identity is optional, because plug capabilities
+ * differ (see {@link EnyoSmartPlugApplianceAvailableFeaturesEnum}): a
+ * switch-only plug reports runtime but no power, a measure-only plug reports
+ * power but no runtime.
+ */
+export interface SmartPlugTimeseriesPlugValues {
+    /** ID of the smart plug appliance these values belong to */
+    applianceId: string;
+    /**
+     * Time-weighted average power drawn by the connected load in Watts for this
+     * bucket. Omitted for plugs that cannot measure power — this is not the same
+     * as `0`, which means "measured, nothing drawing".
+     */
+    averagePowerW?: number;
+    /** Cumulative energy drawn by the connected load in Watt-hours for this bucket */
+    powerWh?: number;
+    /** Lowest power in Watts observed in this bucket */
+    minPowerW?: number;
+    /** Highest power in Watts observed in this bucket */
+    maxPowerW?: number;
+    /**
+     * Minutes the relay was on within this bucket, for plugs that report their
+     * state. `0` means the plug was known to be off for the whole bucket; the
+     * value never exceeds the bucket length.
+     */
+    onDurationMinutes?: number;
+    /**
+     * Number of relay state changes observed in this bucket. Useful for spotting
+     * short-cycling of the connected load.
+     */
+    switchCount?: number;
+}
+/**
+ * A single entry in the smart plug timeseries.
+ *
+ * Carries the aggregate across every included plug plus the per-plug breakdown
+ * for the same bucket, so a consumer can chart the total switchable load and
+ * the individual loads from one response.
+ */
+export interface SmartPlugTimeseriesEntry extends TimeseriesEntryBase {
+    /** Time-weighted average power across all included plugs in Watts for this bucket */
+    smartPlugPowerW: number;
+    /** Cumulative energy across all included plugs in Watt-hours for this bucket */
+    smartPlugPowerWh: number;
+    /** Per-plug values for this bucket, one entry per included plug */
+    plugs: SmartPlugTimeseriesPlugValues[];
+}
+/**
+ * Request parameters for querying smart plug timeseries data.
+ *
+ * Pass `applianceIds` to restrict the query to specific plugs; omit it to
+ * include every smart plug of the device.
+ */
+export interface SmartPlugTimeseriesRequest extends TimeseriesRequestBase {
+}
+/**
+ * Per-plug summary across the full queried period.
+ *
+ * Mirrors the optionality of {@link SmartPlugTimeseriesPlugValues}: a field is
+ * only present when the plug reported the underlying values.
+ */
+export interface SmartPlugTimeseriesPlugSummary {
+    /** ID of the smart plug appliance this summary belongs to */
+    applianceId: string;
+    /** Total energy drawn by the connected load in Watt-hours across all buckets */
+    totalPowerWh?: number;
+    /** Time-weighted average power in Watts across the full period */
+    averagePowerW?: number;
+    /** Total minutes the relay was on across the full period */
+    totalOnDurationMinutes?: number;
+    /** Total number of relay state changes across the full period */
+    totalSwitchCount?: number;
+}
+/**
+ * Response containing smart plug timeseries data.
+ */
+export interface SmartPlugTimeseriesResponse extends TimeseriesResponseBase {
+    /** Array of smart plug entries, one per time bucket */
+    entries: SmartPlugTimeseriesEntry[];
+    /** Total energy across all included plugs in Watt-hours across all buckets */
+    totalSmartPlugPowerWh: number;
+    /** Per-plug summaries across the full queried period */
+    plugs: SmartPlugTimeseriesPlugSummary[];
+}

package/dist/cjs/version.cjs

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

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, HeatpumpPowerTimeseriesRequest, HeatpumpPowerTimeseriesResponse, 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, SmartPlugTimeseriesRequest, SmartPlugTimeseriesResponse } 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
@@ -253,4 +253,33 @@ export interface EnergyAppTimeseries {
      * ```
      */
     getAirConditioningTemperatureTimeseries(request: AirConditioningTemperatureTimeseriesRequest): Promise<AirConditioningTemperatureTimeseriesResponse>;
+    /**
+     * Retrieves smart plug timeseries data aggregated in time buckets.
+     *
+     * Every bucket carries the aggregate across all included plugs
+     * (`smartPlugPowerW` / `Wh`) plus a per-plug breakdown, since a plug measures
+     * an arbitrary load and the total alone does not say which load ran. The
+     * response additionally summarises each plug across the full period.
+     *
+     * Per-plug fields are optional because plug capabilities differ: a
+     * measure-only plug reports power but no runtime, a switch-only plug reports
+     * runtime (`onDurationMinutes`, `switchCount`) but no power.
+     *
+     * @param request - The query parameters including date range and optional appliance filter
+     * @returns Promise resolving to smart plug entries with the total and per-plug summaries
+     *
+     * @example
+     * ```typescript
+     * const response = await timeseries.getSmartPlugTimeseries({
+     *     startDateIso: '2024-01-01T00:00:00Z',
+     *     endDateIso: '2024-01-02T00:00:00Z'
+     * });
+     * console.log(`Total plug consumption: ${response.totalSmartPlugPowerWh} Wh`);
+     * response.plugs.forEach(plug => {
+     *     console.log(`${plug.applianceId}: ${plug.totalPowerWh ?? 0} Wh, ` +
+     *         `on for ${plug.totalOnDurationMinutes ?? 0} min`);
+     * });
+     * ```
+     */
+    getSmartPlugTimeseries(request: SmartPlugTimeseriesRequest): Promise<SmartPlugTimeseriesResponse>;
 }

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

@@ -7,6 +7,7 @@ import { PreviewChargingSchedule, PreviewChargingScheduleCostComparison, Preview
 import { EnyoEnergyPrices } from "./enyo-energy-prices.js";
 import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.js";
+import type { EnyoFlexibilityTargetPower } from "./enyo-flexibility-announcement.js";
 import { EnyoSmartPlugApplianceStateEnum } from "./enyo-smart-plug-appliance.js";
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum } from "./enyo-air-conditioning-appliance.js";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.js";
@@ -579,6 +580,36 @@ export interface EnyoDataBusInverterValuesV1 extends EnyoDataBusMessage {
         gridOperatorLimit?: EnyoGridOperatorLimit;
     };
 }
+/**
+ * An appliance announces how much energy it can shift, and until when.
+ *
+ * Optionally it can also say *what the energy is for and at which power* via
+ * `data.flexibility.context.targets` — e.g. a heat pump splitting its draw
+ * between the domestic hot water tank, the heating buffer tank, and the space
+ * heating circuit. That breakdown is additive context for the decision maker;
+ * `kWh` remains the authoritative total.
+ *
+ * @example
+ * ```typescript
+ * dataBus.sendMessage([{
+ *     type: 'message',
+ *     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV1,
+ *     applianceId: 'heatpump-1',
+ *     data: {
+ *         flexibility: {
+ *             kWh: 4,
+ *             availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+ *             context: {
+ *                 targets: [
+ *                     {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500, kWh: 2.5},
+ *                     {target: EnyoFlexibilityTargetEnum.BufferTank, powerW: 800, kWh: 1.5},
+ *                 ],
+ *             },
+ *         },
+ *     },
+ * }]);
+ * ```
+ */
 export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV1;
@@ -589,6 +620,19 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
             kWh: number;
             /** Defines until the kWh flexibility can be shifted. If for Example 10 kWh can be shifted until 2025-10-01T14:00:00 (current time 2025-10-01T10:00:00), the control can shift the 10 kWh in the next 4 hours */
             availableUntilIsoTimestamp: string;
+            /**
+             * Optional extra context for the consumer of this announcement.
+             * Nested so further context keys can be added without changing the
+             * message shape again.
+             */
+            context?: {
+                /**
+                 * Breakdown of what the announced flexibility is for and at which
+                 * power. May be partial — entries need not sum to the appliance's
+                 * full draw — and a given target SHOULD appear at most once.
+                 */
+                targets: EnyoFlexibilityTargetPower[];
+            };
         };
     };
 }

package/dist/types/enyo-flexibility-announcement.d.ts

@@ -24,12 +24,50 @@ export declare enum EnyoFlexibilityAnnouncementTypeEnum {
  * What a heat pump's flexibility is aimed at — gives the decision maker extra
  * context on the demand behind a heat-pump announcement. `Cooling` is reserved
  * for a future cooling mode and is not emitted yet.
+ *
+ * This enum describes the *mode* a heat pump runs in. To say what the announced
+ * energy is for — and how much power goes to each target — use
+ * {@link EnyoFlexibilityTargetEnum} together with
+ * {@link EnyoFlexibilityTargetPower}. The overlap between the two
+ * (`heating` / `dhw`) is intentional: both vocabularies stay wire-stable on
+ * their own.
  */
 export declare enum EnyoFlexibilityHeatpumpTargetTypeEnum {
     Heating = "heating",
     Cooling = "cooling",
     Dhw = "dhw"
 }
+/**
+ * What an announced share of flexibility is physically aimed at — the open
+ * vocabulary behind the "how much watt for what" breakdown carried by
+ * {@link EnyoFlexibilityTargetPower}.
+ *
+ * The members present today all describe heat sinks, because thermal appliances
+ * are the first ones to split their draw. The enum is deliberately **not**
+ * scoped to thermal loads though: further members may describe non-thermal
+ * targets (a vehicle battery, a stationary storage, a dedicated household
+ * circuit) as other appliance types start announcing a breakdown. Consumers
+ * should therefore treat an unknown value as "some other target" rather than
+ * assuming every value maps to a heat sink.
+ *
+ * Broader than {@link EnyoFlexibilityHeatpumpTargetTypeEnum}, which names the
+ * *mode* a heat pump runs in: this enum adds the heating buffer tank, is not
+ * heat-pump specific (a heating rod announces against the same sinks), and
+ * carries no `cooling` member — cooling is a run mode, not a target.
+ *
+ * Values match the vocabulary used elsewhere in the SDK for the same physical
+ * parts (e.g. `domesticHotWater` and `bufferTank...` in the timeseries types),
+ * so a consumer can correlate an announcement with measured values without a
+ * mapping table.
+ */
+export declare enum EnyoFlexibilityTargetEnum {
+    /** Domestic hot water tank. */
+    DomesticHotWater = "domesticHotWater",
+    /** Heating buffer / storage tank. */
+    BufferTank = "bufferTank",
+    /** Space heating circuit. */
+    Heating = "heating"
+}
 /**
  * What an air-conditioning unit's flexibility is aimed at — extra context for
  * the decision maker. Cooling-only today; a heating variant may follow.
@@ -60,6 +98,35 @@ export declare enum EnyoFlexibilityOptimizationModeEnum {
     PvSurplusPreferred = "pv-surplus-preferred",
     PriceLimit = "price-limit"
 }
+/**
+ * How much power the announced flexibility would draw for one target — one
+ * entry of the "how much watt for what" breakdown behind an announcement.
+ *
+ * Purely informational context: the announcement's own energy figure stays
+ * authoritative. A breakdown may be partial — its entries need not sum to the
+ * appliance's full draw — but a given {@link target} SHOULD appear at most once
+ * per breakdown.
+ *
+ * @example
+ * ```typescript
+ * // A heat pump that would put 1500 W into the DHW tank and 800 W into heating
+ * const targets: EnyoFlexibilityTargetPower[] = [
+ *     {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500, kWh: 2.5},
+ *     {target: EnyoFlexibilityTargetEnum.Heating, powerW: 800},
+ * ];
+ * ```
+ */
+export interface EnyoFlexibilityTargetPower {
+    /** What this share is for. */
+    target: EnyoFlexibilityTargetEnum;
+    /** Electrical power this share would draw, in Watts. Non-negative. */
+    powerW: number;
+    /**
+     * Share of the announced energy attributable to this target, in kWh.
+     * Optional — omit when only the power split is known.
+     */
+    kWh?: number;
+}
 /** Discrete power band the solver may pick from: [minWatt, maxWatt] in stepWatt steps. */
 export interface EnyoFlexibilityPowerBand {
     /** Lower bound of the band, in Watts. Non-negative. */
@@ -125,6 +192,13 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * How much power the announced flexibility would draw per target — "how much
+     * watt for what". Keeps the category surface in step with the per-appliance
+     * announcement, which carries the same breakdown under
+     * `data.flexibility.context.targets`.
+     */
+    targets?: EnyoFlexibilityTargetPower[];
     /**
      * For storage announcements: the round-trip cost of cycling the battery, in
      * EUR per kWh. The floor a discharge has to beat to be worth licensing.

package/dist/types/enyo-flexibility-announcement.js

@@ -29,6 +29,13 @@ export var EnyoFlexibilityAnnouncementTypeEnum;
  * What a heat pump's flexibility is aimed at — gives the decision maker extra
  * context on the demand behind a heat-pump announcement. `Cooling` is reserved
  * for a future cooling mode and is not emitted yet.
+ *
+ * This enum describes the *mode* a heat pump runs in. To say what the announced
+ * energy is for — and how much power goes to each target — use
+ * {@link EnyoFlexibilityTargetEnum} together with
+ * {@link EnyoFlexibilityTargetPower}. The overlap between the two
+ * (`heating` / `dhw`) is intentional: both vocabularies stay wire-stable on
+ * their own.
  */
 export var EnyoFlexibilityHeatpumpTargetTypeEnum;
 (function (EnyoFlexibilityHeatpumpTargetTypeEnum) {
@@ -36,6 +43,38 @@ export var EnyoFlexibilityHeatpumpTargetTypeEnum;
     EnyoFlexibilityHeatpumpTargetTypeEnum["Cooling"] = "cooling";
     EnyoFlexibilityHeatpumpTargetTypeEnum["Dhw"] = "dhw";
 })(EnyoFlexibilityHeatpumpTargetTypeEnum || (EnyoFlexibilityHeatpumpTargetTypeEnum = {}));
+/**
+ * What an announced share of flexibility is physically aimed at — the open
+ * vocabulary behind the "how much watt for what" breakdown carried by
+ * {@link EnyoFlexibilityTargetPower}.
+ *
+ * The members present today all describe heat sinks, because thermal appliances
+ * are the first ones to split their draw. The enum is deliberately **not**
+ * scoped to thermal loads though: further members may describe non-thermal
+ * targets (a vehicle battery, a stationary storage, a dedicated household
+ * circuit) as other appliance types start announcing a breakdown. Consumers
+ * should therefore treat an unknown value as "some other target" rather than
+ * assuming every value maps to a heat sink.
+ *
+ * Broader than {@link EnyoFlexibilityHeatpumpTargetTypeEnum}, which names the
+ * *mode* a heat pump runs in: this enum adds the heating buffer tank, is not
+ * heat-pump specific (a heating rod announces against the same sinks), and
+ * carries no `cooling` member — cooling is a run mode, not a target.
+ *
+ * Values match the vocabulary used elsewhere in the SDK for the same physical
+ * parts (e.g. `domesticHotWater` and `bufferTank...` in the timeseries types),
+ * so a consumer can correlate an announcement with measured values without a
+ * mapping table.
+ */
+export var EnyoFlexibilityTargetEnum;
+(function (EnyoFlexibilityTargetEnum) {
+    /** Domestic hot water tank. */
+    EnyoFlexibilityTargetEnum["DomesticHotWater"] = "domesticHotWater";
+    /** Heating buffer / storage tank. */
+    EnyoFlexibilityTargetEnum["BufferTank"] = "bufferTank";
+    /** Space heating circuit. */
+    EnyoFlexibilityTargetEnum["Heating"] = "heating";
+})(EnyoFlexibilityTargetEnum || (EnyoFlexibilityTargetEnum = {}));
 /**
  * What an air-conditioning unit's flexibility is aimed at — extra context for
  * the decision maker. Cooling-only today; a heating variant may follow.

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

@@ -538,3 +538,94 @@ export interface AirConditioningTemperatureTimeseriesResponse extends Timeseries
     /** Array of air conditioning temperature entries, one per time bucket */
     entries: AirConditioningTemperatureTimeseriesEntry[];
 }
+/**
+ * Power and runtime figures for a single smart plug within one time bucket.
+ *
+ * A smart plug measures an arbitrary load, so the per-plug breakdown matters
+ * more here than for other appliance types: summing several plugs gives the
+ * total switchable load, but only the per-plug values say *which* load ran.
+ *
+ * Every field other than the identity is optional, because plug capabilities
+ * differ (see {@link EnyoSmartPlugApplianceAvailableFeaturesEnum}): a
+ * switch-only plug reports runtime but no power, a measure-only plug reports
+ * power but no runtime.
+ */
+export interface SmartPlugTimeseriesPlugValues {
+    /** ID of the smart plug appliance these values belong to */
+    applianceId: string;
+    /**
+     * Time-weighted average power drawn by the connected load in Watts for this
+     * bucket. Omitted for plugs that cannot measure power — this is not the same
+     * as `0`, which means "measured, nothing drawing".
+     */
+    averagePowerW?: number;
+    /** Cumulative energy drawn by the connected load in Watt-hours for this bucket */
+    powerWh?: number;
+    /** Lowest power in Watts observed in this bucket */
+    minPowerW?: number;
+    /** Highest power in Watts observed in this bucket */
+    maxPowerW?: number;
+    /**
+     * Minutes the relay was on within this bucket, for plugs that report their
+     * state. `0` means the plug was known to be off for the whole bucket; the
+     * value never exceeds the bucket length.
+     */
+    onDurationMinutes?: number;
+    /**
+     * Number of relay state changes observed in this bucket. Useful for spotting
+     * short-cycling of the connected load.
+     */
+    switchCount?: number;
+}
+/**
+ * A single entry in the smart plug timeseries.
+ *
+ * Carries the aggregate across every included plug plus the per-plug breakdown
+ * for the same bucket, so a consumer can chart the total switchable load and
+ * the individual loads from one response.
+ */
+export interface SmartPlugTimeseriesEntry extends TimeseriesEntryBase {
+    /** Time-weighted average power across all included plugs in Watts for this bucket */
+    smartPlugPowerW: number;
+    /** Cumulative energy across all included plugs in Watt-hours for this bucket */
+    smartPlugPowerWh: number;
+    /** Per-plug values for this bucket, one entry per included plug */
+    plugs: SmartPlugTimeseriesPlugValues[];
+}
+/**
+ * Request parameters for querying smart plug timeseries data.
+ *
+ * Pass `applianceIds` to restrict the query to specific plugs; omit it to
+ * include every smart plug of the device.
+ */
+export interface SmartPlugTimeseriesRequest extends TimeseriesRequestBase {
+}
+/**
+ * Per-plug summary across the full queried period.
+ *
+ * Mirrors the optionality of {@link SmartPlugTimeseriesPlugValues}: a field is
+ * only present when the plug reported the underlying values.
+ */
+export interface SmartPlugTimeseriesPlugSummary {
+    /** ID of the smart plug appliance this summary belongs to */
+    applianceId: string;
+    /** Total energy drawn by the connected load in Watt-hours across all buckets */
+    totalPowerWh?: number;
+    /** Time-weighted average power in Watts across the full period */
+    averagePowerW?: number;
+    /** Total minutes the relay was on across the full period */
+    totalOnDurationMinutes?: number;
+    /** Total number of relay state changes across the full period */
+    totalSwitchCount?: number;
+}
+/**
+ * Response containing smart plug timeseries data.
+ */
+export interface SmartPlugTimeseriesResponse extends TimeseriesResponseBase {
+    /** Array of smart plug entries, one per time bucket */
+    entries: SmartPlugTimeseriesEntry[];
+    /** Total energy across all included plugs in Watt-hours across all buckets */
+    totalSmartPlugPowerWh: number;
+    /** Per-plug summaries across the full queried period */
+    plugs: SmartPlugTimeseriesPlugSummary[];
+}

package/dist/version.d.ts

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