@enyo-energy/energy-app-sdk 1.9.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/implementations/appliances/appliance-manager.cjs

@@ -60,6 +60,7 @@ const MERGEABLE_METADATA_KEYS = [
     'temperatureSensor',
     'airConditioning',
     'heatingRod',
+    'smartPlug',
 ];
 /**
  * Manages appliances in the energy system with configurable identification strategies.
@@ -209,6 +210,7 @@ class ApplianceManager {
             temperatureSensor: appliance.temperatureSensor,
             airConditioning: appliance.airConditioning,
             heatingRod: appliance.heatingRod,
+            smartPlug: appliance.smartPlug,
             // Conditionally spread the two optional top-level fields that are NOT
             // covered by MERGEABLE_METADATA_KEYS. If they were always materialized
             // as explicit keys, an omitted (undefined) value would clobber the

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

@@ -10,6 +10,7 @@ import type { EnyoMeterAppliance } from "../../types/enyo-meter-appliance.cjs";
 import type { EnyoTemperatureSensorApplianceMetadata } from "../../types/enyo-temperature-sensor-appliance.cjs";
 import type { EnyoAirConditioningApplianceMetadata } from "../../types/enyo-air-conditioning-appliance.cjs";
 import type { EnyoHeatingRodApplianceMetadata } from "../../types/enyo-heating-rod-appliance.cjs";
+import type { EnyoSmartPlugApplianceMetadata } from "../../types/enyo-smart-plug-appliance.cjs";
 import { IdentifierStrategy } from "./identifier-strategies.cjs";
 /**
  * Thrown when {@link ApplianceManager.createOrUpdateAppliance} is called with
@@ -62,6 +63,7 @@ export interface ApplianceConfig {
     temperatureSensor?: EnyoTemperatureSensorApplianceMetadata;
     airConditioning?: EnyoAirConditioningApplianceMetadata;
     heatingRod?: EnyoHeatingRodApplianceMetadata;
+    smartPlug?: EnyoSmartPlugApplianceMetadata;
     availableFeatures?: EnyoApplianceAvailableFeaturesEnum[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
@@ -437,6 +439,8 @@ export interface PartialEnyoAppliance {
     airConditioning?: Partial<EnyoAirConditioningApplianceMetadata>;
     /** Optional Metadata of the Appliance if of type HeatingRod */
     heatingRod?: Partial<EnyoHeatingRodApplianceMetadata>;
+    /** Optional Metadata of the Appliance if of type SmartPlug */
+    smartPlug?: Partial<EnyoSmartPlugApplianceMetadata>;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
     /**

package/dist/cjs/index.cjs

@@ -86,6 +86,7 @@ __exportStar(require("./types/enyo-configuration-manager.cjs"), exports);
 __exportStar(require("./packages/energy-app-configuration-manager.cjs"), exports);
 __exportStar(require("./types/enyo-air-conditioning-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heating-rod-appliance.cjs"), exports);
+__exportStar(require("./types/enyo-smart-plug-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-charger-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-charging-card.cjs"), exports);
 __exportStar(require("./packages/energy-app-charging-card.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -70,6 +70,7 @@ export * from './types/enyo-configuration-manager.cjs';
 export * from './packages/energy-app-configuration-manager.cjs';
 export * from './types/enyo-air-conditioning-appliance.cjs';
 export * from './types/enyo-heating-rod-appliance.cjs';
+export * from './types/enyo-smart-plug-appliance.cjs';
 export * from './types/enyo-charger-appliance.cjs';
 export * from './types/enyo-charging-card.cjs';
 export * from './packages/energy-app-charging-card.cjs';

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-appliance.cjs

@@ -11,6 +11,8 @@ var EnyoApplianceTypeEnum;
     EnyoApplianceTypeEnum["AirConditioning"] = "AirConditioning";
     EnyoApplianceTypeEnum["TemperatureSensor"] = "TemperatureSensor";
     EnyoApplianceTypeEnum["HeatingRod"] = "HeatingRod";
+    /** Switchable socket / relay channel powering an arbitrary load (e.g. a Shelly channel) */
+    EnyoApplianceTypeEnum["SmartPlug"] = "SmartPlug";
 })(EnyoApplianceTypeEnum || (exports.EnyoApplianceTypeEnum = EnyoApplianceTypeEnum = {}));
 var EnyoApplianceStateEnum;
 (function (EnyoApplianceStateEnum) {

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

@@ -8,6 +8,7 @@ import { EnyoMeterAppliance } from "./enyo-meter-appliance.cjs";
 import { EnyoTemperatureSensorApplianceMetadata } from "./enyo-temperature-sensor-appliance.cjs";
 import { EnyoAirConditioningApplianceMetadata } from "./enyo-air-conditioning-appliance.cjs";
 import { EnyoHeatingRodApplianceMetadata } from "./enyo-heating-rod-appliance.cjs";
+import { EnyoSmartPlugApplianceMetadata } from "./enyo-smart-plug-appliance.cjs";
 export declare enum EnyoApplianceTypeEnum {
     Inverter = "Inverter",
     Charger = "Charger",
@@ -16,7 +17,9 @@ export declare enum EnyoApplianceTypeEnum {
     Heatpump = "Heatpump",
     AirConditioning = "AirConditioning",
     TemperatureSensor = "TemperatureSensor",
-    HeatingRod = "HeatingRod"
+    HeatingRod = "HeatingRod",
+    /** Switchable socket / relay channel powering an arbitrary load (e.g. a Shelly channel) */
+    SmartPlug = "SmartPlug"
 }
 export interface EnyoApplianceName {
     language: EnergyAppPackageLanguage;
@@ -270,6 +273,8 @@ export interface EnyoAppliance {
     airConditioning?: EnyoAirConditioningApplianceMetadata;
     /** Optional Metadata of the Appliance if of type HeatingRod */
     heatingRod?: EnyoHeatingRodApplianceMetadata;
+    /** Optional Metadata of the Appliance if of type SmartPlug */
+    smartPlug?: EnyoSmartPlugApplianceMetadata;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
     /**

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

@@ -280,6 +280,10 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["SetHeatingRodAvailablePowerV2"] = "SetHeatingRodAvailablePowerV2";
     /** V2 control command: prescribe a single-setpoint control (mode + direction + power) to a battery/storage appliance. */
     EnyoDataBusMessageEnum["SetStorageControlV2"] = "SetStorageControlV2";
+    /** Live values of a smart plug: relay state, power draw and energy meter reading. */
+    EnyoDataBusMessageEnum["SmartPlugValuesUpdateV1"] = "SmartPlugValuesUpdateV1";
+    /** Control command: switch a smart plug / relay channel on or off. */
+    EnyoDataBusMessageEnum["SetSmartPlugSwitchV1"] = "SetSmartPlugSwitchV1";
     EnyoDataBusMessageEnum["EnergyAppStartedV1"] = "EnergyAppStartedV1";
 })(EnyoDataBusMessageEnum || (exports.EnyoDataBusMessageEnum = EnyoDataBusMessageEnum = {}));
 /**

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

@@ -7,6 +7,8 @@ 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";
 import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.cjs";
@@ -344,6 +346,10 @@ export declare enum EnyoDataBusMessageEnum {
     SetHeatingRodAvailablePowerV2 = "SetHeatingRodAvailablePowerV2",
     /** V2 control command: prescribe a single-setpoint control (mode + direction + power) to a battery/storage appliance. */
     SetStorageControlV2 = "SetStorageControlV2",
+    /** Live values of a smart plug: relay state, power draw and energy meter reading. */
+    SmartPlugValuesUpdateV1 = "SmartPlugValuesUpdateV1",
+    /** Control command: switch a smart plug / relay channel on or off. */
+    SetSmartPlugSwitchV1 = "SetSmartPlugSwitchV1",
     EnergyAppStartedV1 = "EnergyAppStartedV1"
 }
 export type EnyoDataBusMessageResolution = '1s' | '10s' | '30s' | '1m' | '15m' | '1h' | '1d' | 'dynamic';
@@ -574,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;
@@ -584,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[];
+            };
         };
     };
 }
@@ -2429,3 +2478,68 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
         batterySizeKwh?: number;
     };
 }
+/**
+ * Live values of a smart plug / switchable relay channel, published by the
+ * integration that owns the appliance.
+ *
+ * Send this whenever the relay state or the measured power changes, so an
+ * energy manager can account for the load and decide whether to switch the plug
+ * via {@link EnyoDataBusSetSmartPlugSwitchV1}.
+ */
+export interface EnyoDataBusSmartPlugValuesV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.SmartPlugValuesUpdateV1;
+    /** ID of the smart plug appliance that delivered these values */
+    applianceId: string;
+    data: {
+        /**
+         * Current relay state of the plug. Omit when the integration cannot
+         * determine it — `undefined` means "not known", which is not the same
+         * as {@link EnyoSmartPlugApplianceStateEnum.Off}.
+         */
+        state?: EnyoSmartPlugApplianceStateEnum;
+        /**
+         * Current active power drawn by the connected load in Watt. Normally
+         * positive (a plug powers a consumer). Omit when the plug cannot
+         * measure it — do not send `0` as a stand-in for "unknown", since a
+         * consumer cannot tell that apart from "nothing is drawing power".
+         */
+        powerW?: number;
+        /** Cumulative energy meter reading of the plug in Watt hours */
+        meterValueWh?: number;
+        /** Voltage measured at the plug in V, when reported */
+        voltageV?: number;
+        /** Current measured at the plug in A, when reported */
+        currentA?: number;
+    };
+}
+/**
+ * Command switching a smart plug / relay channel on or off.
+ *
+ * Only valid for appliances that list
+ * {@link EnyoSmartPlugApplianceAvailableFeaturesEnum.Switching} and whose
+ * metadata does not set `controlAllowed: false`. The receiving integration
+ * should answer with an {@link EnyoDataBusCommandAcknowledgeV1} message
+ * referencing this message's `id`, and reflect the resulting relay state in the
+ * next {@link EnyoDataBusSmartPlugValuesV1}.
+ */
+export interface EnyoDataBusSetSmartPlugSwitchV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.SetSmartPlugSwitchV1;
+    /** ID of the smart plug appliance to switch */
+    applianceId: string;
+    data: {
+        /** Target relay state: `On` closes the relay, `Off` opens it */
+        state: EnyoSmartPlugApplianceStateEnum;
+        /**
+         * Minimum time in minutes the requested state should be held before the
+         * plug may be switched again, to protect the connected load from
+         * short-cycling. When omitted, the integration should fall back to the
+         * appliance's `minOnDurationMinutes` / `minOffDurationMinutes`
+         * metadata, and otherwise switch immediately.
+         */
+        minDurationMinutes?: number;
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}

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-smart-plug-appliance.cjs

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoSmartPlugApplianceIconEnum = exports.EnyoSmartPlugApplianceStateEnum = exports.EnyoSmartPlugApplianceAvailableFeaturesEnum = void 0;
+/**
+ * Capabilities a smart plug / switchable relay appliance may support. A plug
+ * that only reports power without being switchable lists {@link Power} alone;
+ * one that can only be switched lists {@link Switching} alone.
+ */
+var EnyoSmartPlugApplianceAvailableFeaturesEnum;
+(function (EnyoSmartPlugApplianceAvailableFeaturesEnum) {
+    /** If the plug can be switched on and off by the energy manager or an automation */
+    EnyoSmartPlugApplianceAvailableFeaturesEnum["Switching"] = "Switching";
+    /** If the plug measures the active power (W) drawn by the connected load */
+    EnyoSmartPlugApplianceAvailableFeaturesEnum["Power"] = "Power";
+    /** If the plug reports a cumulative energy meter reading (Wh) for the connected load */
+    EnyoSmartPlugApplianceAvailableFeaturesEnum["EnergyMetering"] = "EnergyMetering";
+})(EnyoSmartPlugApplianceAvailableFeaturesEnum || (exports.EnyoSmartPlugApplianceAvailableFeaturesEnum = EnyoSmartPlugApplianceAvailableFeaturesEnum = {}));
+/**
+ * Relay state of a smart plug channel.
+ */
+var EnyoSmartPlugApplianceStateEnum;
+(function (EnyoSmartPlugApplianceStateEnum) {
+    /** The relay is closed — the connected load is powered */
+    EnyoSmartPlugApplianceStateEnum["On"] = "On";
+    /** The relay is open — the connected load is not powered */
+    EnyoSmartPlugApplianceStateEnum["Off"] = "Off";
+})(EnyoSmartPlugApplianceStateEnum || (exports.EnyoSmartPlugApplianceStateEnum = EnyoSmartPlugApplianceStateEnum = {}));
+/**
+ * Icon suggested for a smart plug appliance in end-user surfaces. Describes the
+ * load connected to the plug rather than the plug itself, so a user recognises
+ * "Dishwasher" instead of "Shelly channel 1".
+ *
+ * Purely presentational — consumers must not derive control behaviour from it.
+ * When omitted, or when a consumer does not know the member, it should fall
+ * back to a generic plug icon.
+ */
+var EnyoSmartPlugApplianceIconEnum;
+(function (EnyoSmartPlugApplianceIconEnum) {
+    /** Generic socket / unspecified load */
+    EnyoSmartPlugApplianceIconEnum["SmartPlug"] = "SmartPlug";
+    EnyoSmartPlugApplianceIconEnum["Dishwasher"] = "Dishwasher";
+    EnyoSmartPlugApplianceIconEnum["WashingMachine"] = "WashingMachine";
+    EnyoSmartPlugApplianceIconEnum["Dryer"] = "Dryer";
+    EnyoSmartPlugApplianceIconEnum["Refrigerator"] = "Refrigerator";
+    EnyoSmartPlugApplianceIconEnum["Freezer"] = "Freezer";
+    EnyoSmartPlugApplianceIconEnum["Oven"] = "Oven";
+    EnyoSmartPlugApplianceIconEnum["CoffeeMachine"] = "CoffeeMachine";
+    /** Kettle, toaster and other small kitchen appliances */
+    EnyoSmartPlugApplianceIconEnum["KitchenAppliance"] = "KitchenAppliance";
+    /** TV, hi-fi, console and other entertainment loads */
+    EnyoSmartPlugApplianceIconEnum["Entertainment"] = "Entertainment";
+    /** Desktop, server, network equipment */
+    EnyoSmartPlugApplianceIconEnum["Computer"] = "Computer";
+    EnyoSmartPlugApplianceIconEnum["Lighting"] = "Lighting";
+    /** Pool pump or pool filter system */
+    EnyoSmartPlugApplianceIconEnum["PoolPump"] = "PoolPump";
+    /** Circulation, well or sump pump */
+    EnyoSmartPlugApplianceIconEnum["Pump"] = "Pump";
+    /** Electric water heater / boiler */
+    EnyoSmartPlugApplianceIconEnum["WaterHeater"] = "WaterHeater";
+    /** Portable electric heater */
+    EnyoSmartPlugApplianceIconEnum["Heater"] = "Heater";
+    /** Fan or ventilation unit */
+    EnyoSmartPlugApplianceIconEnum["Fan"] = "Fan";
+    EnyoSmartPlugApplianceIconEnum["Aquarium"] = "Aquarium";
+    /** Garden, irrigation or greenhouse equipment */
+    EnyoSmartPlugApplianceIconEnum["Garden"] = "Garden";
+    /** Workshop machinery and power tools */
+    EnyoSmartPlugApplianceIconEnum["Workshop"] = "Workshop";
+    /** Car / e-bike charging via a plain socket */
+    EnyoSmartPlugApplianceIconEnum["Charging"] = "Charging";
+    /** Known load that none of the other members describe */
+    EnyoSmartPlugApplianceIconEnum["Other"] = "Other";
+})(EnyoSmartPlugApplianceIconEnum || (exports.EnyoSmartPlugApplianceIconEnum = EnyoSmartPlugApplianceIconEnum = {}));