@enyo-energy/energy-app-sdk 0.0.190 → 0.0.191

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

@@ -98,6 +98,7 @@ export interface EnergyAppDiagnostics {
      *     generatedAtIso: new Date().toISOString(),
      *     announced: [
      *         {
+     *             id: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -110,6 +111,8 @@ export interface EnergyAppDiagnostics {
      *             },
      *         },
      *         {
+     *             id: 'storage:flexible-discharge',
+     *             applianceId: 'battery-1',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,
@@ -124,6 +127,7 @@ export interface EnergyAppDiagnostics {
      *     ],
      *     granted: [
      *         {
+     *             announcementId: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -134,6 +138,7 @@ export interface EnergyAppDiagnostics {
      *             reason: 'grid connection point limit',
      *         },
      *         {
+     *             announcementId: 'storage:flexible-discharge',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,

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

@@ -125,11 +125,49 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * 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.
+     */
+    storageCycleCostEurPerKwh?: number;
+    /**
+     * For storage announcements: the physical discharge floor, in Watts. Signed —
+     * negative means discharge, so this is the most negative power the storage can
+     * physically reach.
+     */
+    storageMinPowerW?: number;
+    /** For storage announcements: the physical charge ceiling, in Watts. */
+    storageMaxPowerW?: number;
+    /** For storage announcements: usable capacity of the storage, in Wh. */
+    storageCapacityWh?: number;
+    /**
+     * For storage announcements: the discharge power we will actually command, in
+     * Watts. May be well inside {@link storageMinPowerW} — today it is `0`, i.e. we
+     * license discharge without commanding it.
+     */
+    storageCommandableDischargeW?: number;
+    /**
+     * For storage announcements: whether the storage accepts an explicit
+     * `Discharge 0` command, i.e. can be told to hold rather than only being left
+     * alone.
+     */
+    storageCanHold?: boolean;
 }
 /** Fields shared by every category-scoped flexibility announcement. */
 export interface EnyoCategoryFlexibilityAnnouncementBase {
+    /**
+     * What this announcement IS, stable across cycles — e.g. `storage:peak-requirement`.
+     * A category speaks with several at once and (category, type) does not tell them
+     * apart. REQUIRED: a positional identity changes whenever a neighbour appears.
+     */
+    id: string;
     /** The appliance category this demand aggregates (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
+    /**
+     * The appliance this announcement speaks for, when a category announces per
+     * appliance rather than as one aggregate. Absent = the whole category.
+     */
+    applianceId?: string;
     /** Optional extra context for the decision maker; absent for most announcements. */
     context?: EnyoFlexibilityAnnouncementContext;
 }
@@ -143,6 +181,12 @@ export interface EnyoCategoryRequiredKwhTargetAnnouncement extends EnyoCategoryF
         kwh: number;
         /** Power band the delivery may use. */
         power: EnyoFlexibilityPowerBand;
+        /**
+         * Price ceiling, when the requirement is economic rather than absolute.
+         * Present on the wire today; without it every economic requirement looked
+         * like a MUST-RUN in diagnostics.
+         */
+        priceLimitEuroCent?: number;
     };
 }
 /** Deliver `kwh` flexibly (cost-/PV-optimized), aggregated across the category. */
@@ -224,10 +268,13 @@ export declare enum EnyoCategoryFlexibilityGrantStatusEnum {
  * A grant is deliberately flatter than the announcement it answers: the decision
  * maker replies with one allocation — a window, a power envelope, and (for the
  * energy-target and discharge variants) an amount of energy — regardless of which
- * announcement variant produced it. Pairing is by `category` +
- * `flexibilityAnnouncementType`, which is unique within a single publish.
+ * announcement variant produced it. Pairing is by `announcementId` — the `id` of
+ * the announcement being answered — which stays stable across cycles and tells
+ * apart the several announcements one category may speak with at once.
  */
 export interface EnyoCategoryFlexibilityGrant {
+    /** The `id` of the announcement this answers. */
+    announcementId: string;
     /** The appliance category this allocation is for (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
     /** Which announcement variant this grant answers. */
@@ -270,14 +317,13 @@ export interface EnyoCategoryFlexibilityDiagnostics {
     /** ISO 8601 timestamp when this snapshot was taken. */
     generatedAtIso: string;
     /**
-     * The flexibility the managers announced, one entry per
-     * (category, announcement variant).
+     * The flexibility the managers announced, one entry per announcement `id`.
      */
     announced: EnyoCategoryFlexibilityAnnouncement[];
     /**
      * What the decision maker granted in answer to `announced`. Every entry SHOULD
-     * pair with an `announced` entry by `category` + `flexibilityAnnouncementType`;
-     * an announcement with no matching grant means the decision had not been taken
+     * pair with an `announced` entry by `announcementId`; an announcement with no
+     * matching grant means the decision had not been taken
      * yet when the snapshot was produced.
      */
     granted: EnyoCategoryFlexibilityGrant[];

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

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
+exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
 var EnyoHeatpumpApplianceAvailableFeaturesEnum;
 (function (EnyoHeatpumpApplianceAvailableFeaturesEnum) {
     /** If the heatpump is capable of domestic hot water*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRodControllable"] = "HeatingRodControllable";
     /** If the heatpump supports room overheating via heating circuits */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["RoomOverheating"] = "RoomOverheating";
     /** If the heatpump supports buffer tank overheating */
@@ -62,6 +64,18 @@ var EnyoHeatpumpApplianceAdditionalDeviceEnum;
     /** A solar thermal system is present in the installation */
     EnyoHeatpumpApplianceAdditionalDeviceEnum["SolarThermal"] = "SolarThermal";
 })(EnyoHeatpumpApplianceAdditionalDeviceEnum || (exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = EnyoHeatpumpApplianceAdditionalDeviceEnum = {}));
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+var EnyoHeatpumpApplianceHeatingRodUsageEnum;
+(function (EnyoHeatpumpApplianceHeatingRodUsageEnum) {
+    /** The heating rod is the only heat source used (no compressor support) */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["OnlyHeatingRot"] = "OnlyHeatingRot";
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["HeatingRodForTemperatureIncrease"] = "HeatingRodForTemperatureIncrease";
+})(EnyoHeatpumpApplianceHeatingRodUsageEnum || (exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = EnyoHeatpumpApplianceHeatingRodUsageEnum = {}));
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at

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

@@ -3,6 +3,8 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     DomesticHotWater = "DomesticHotWater",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    HeatingRodControllable = "HeatingRodControllable",
     /** If the heatpump supports room overheating via heating circuits */
     RoomOverheating = "RoomOverheating",
     /** If the heatpump supports buffer tank overheating */
@@ -55,6 +57,17 @@ export declare enum EnyoHeatpumpApplianceAdditionalDeviceEnum {
     /** A solar thermal system is present in the installation */
     SolarThermal = "SolarThermal"
 }
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export declare enum EnyoHeatpumpApplianceHeatingRodUsageEnum {
+    /** The heating rod is the only heat source used (no compressor support) */
+    OnlyHeatingRot = "OnlyHeatingRot",
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    HeatingRodForTemperatureIncrease = "HeatingRodForTemperatureIncrease"
+}
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at
@@ -124,4 +137,11 @@ export interface EnyoHeatpumpApplianceMetadata {
      * heatpump (e.g. a heating rod or a solar thermal system).
      */
     additionalDevices?: EnyoHeatpumpApplianceAdditionalDeviceEnum[];
+    /**
+     * How the heating rod of the installation is used (e.g. as the only heat
+     * source or only to further increase the temperature on top of the
+     * compressor). Only meaningful if the heatpump has a heating rod
+     * (see {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingRod}).
+     */
+    heatingRodUsage?: EnyoHeatpumpApplianceHeatingRodUsageEnum;
 }

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

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

@@ -98,6 +98,7 @@ export interface EnergyAppDiagnostics {
      *     generatedAtIso: new Date().toISOString(),
      *     announced: [
      *         {
+     *             id: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -110,6 +111,8 @@ export interface EnergyAppDiagnostics {
      *             },
      *         },
      *         {
+     *             id: 'storage:flexible-discharge',
+     *             applianceId: 'battery-1',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,
@@ -124,6 +127,7 @@ export interface EnergyAppDiagnostics {
      *     ],
      *     granted: [
      *         {
+     *             announcementId: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -134,6 +138,7 @@ export interface EnergyAppDiagnostics {
      *             reason: 'grid connection point limit',
      *         },
      *         {
+     *             announcementId: 'storage:flexible-discharge',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,

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

@@ -125,11 +125,49 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * 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.
+     */
+    storageCycleCostEurPerKwh?: number;
+    /**
+     * For storage announcements: the physical discharge floor, in Watts. Signed —
+     * negative means discharge, so this is the most negative power the storage can
+     * physically reach.
+     */
+    storageMinPowerW?: number;
+    /** For storage announcements: the physical charge ceiling, in Watts. */
+    storageMaxPowerW?: number;
+    /** For storage announcements: usable capacity of the storage, in Wh. */
+    storageCapacityWh?: number;
+    /**
+     * For storage announcements: the discharge power we will actually command, in
+     * Watts. May be well inside {@link storageMinPowerW} — today it is `0`, i.e. we
+     * license discharge without commanding it.
+     */
+    storageCommandableDischargeW?: number;
+    /**
+     * For storage announcements: whether the storage accepts an explicit
+     * `Discharge 0` command, i.e. can be told to hold rather than only being left
+     * alone.
+     */
+    storageCanHold?: boolean;
 }
 /** Fields shared by every category-scoped flexibility announcement. */
 export interface EnyoCategoryFlexibilityAnnouncementBase {
+    /**
+     * What this announcement IS, stable across cycles — e.g. `storage:peak-requirement`.
+     * A category speaks with several at once and (category, type) does not tell them
+     * apart. REQUIRED: a positional identity changes whenever a neighbour appears.
+     */
+    id: string;
     /** The appliance category this demand aggregates (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
+    /**
+     * The appliance this announcement speaks for, when a category announces per
+     * appliance rather than as one aggregate. Absent = the whole category.
+     */
+    applianceId?: string;
     /** Optional extra context for the decision maker; absent for most announcements. */
     context?: EnyoFlexibilityAnnouncementContext;
 }
@@ -143,6 +181,12 @@ export interface EnyoCategoryRequiredKwhTargetAnnouncement extends EnyoCategoryF
         kwh: number;
         /** Power band the delivery may use. */
         power: EnyoFlexibilityPowerBand;
+        /**
+         * Price ceiling, when the requirement is economic rather than absolute.
+         * Present on the wire today; without it every economic requirement looked
+         * like a MUST-RUN in diagnostics.
+         */
+        priceLimitEuroCent?: number;
     };
 }
 /** Deliver `kwh` flexibly (cost-/PV-optimized), aggregated across the category. */
@@ -224,10 +268,13 @@ export declare enum EnyoCategoryFlexibilityGrantStatusEnum {
  * A grant is deliberately flatter than the announcement it answers: the decision
  * maker replies with one allocation — a window, a power envelope, and (for the
  * energy-target and discharge variants) an amount of energy — regardless of which
- * announcement variant produced it. Pairing is by `category` +
- * `flexibilityAnnouncementType`, which is unique within a single publish.
+ * announcement variant produced it. Pairing is by `announcementId` — the `id` of
+ * the announcement being answered — which stays stable across cycles and tells
+ * apart the several announcements one category may speak with at once.
  */
 export interface EnyoCategoryFlexibilityGrant {
+    /** The `id` of the announcement this answers. */
+    announcementId: string;
     /** The appliance category this allocation is for (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
     /** Which announcement variant this grant answers. */
@@ -270,14 +317,13 @@ export interface EnyoCategoryFlexibilityDiagnostics {
     /** ISO 8601 timestamp when this snapshot was taken. */
     generatedAtIso: string;
     /**
-     * The flexibility the managers announced, one entry per
-     * (category, announcement variant).
+     * The flexibility the managers announced, one entry per announcement `id`.
      */
     announced: EnyoCategoryFlexibilityAnnouncement[];
     /**
      * What the decision maker granted in answer to `announced`. Every entry SHOULD
-     * pair with an `announced` entry by `category` + `flexibilityAnnouncementType`;
-     * an announcement with no matching grant means the decision had not been taken
+     * pair with an `announced` entry by `announcementId`; an announcement with no
+     * matching grant means the decision had not been taken
      * yet when the snapshot was produced.
      */
     granted: EnyoCategoryFlexibilityGrant[];

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

@@ -3,6 +3,8 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     DomesticHotWater = "DomesticHotWater",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    HeatingRodControllable = "HeatingRodControllable",
     /** If the heatpump supports room overheating via heating circuits */
     RoomOverheating = "RoomOverheating",
     /** If the heatpump supports buffer tank overheating */
@@ -55,6 +57,17 @@ export declare enum EnyoHeatpumpApplianceAdditionalDeviceEnum {
     /** A solar thermal system is present in the installation */
     SolarThermal = "SolarThermal"
 }
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export declare enum EnyoHeatpumpApplianceHeatingRodUsageEnum {
+    /** The heating rod is the only heat source used (no compressor support) */
+    OnlyHeatingRot = "OnlyHeatingRot",
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    HeatingRodForTemperatureIncrease = "HeatingRodForTemperatureIncrease"
+}
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at
@@ -124,4 +137,11 @@ export interface EnyoHeatpumpApplianceMetadata {
      * heatpump (e.g. a heating rod or a solar thermal system).
      */
     additionalDevices?: EnyoHeatpumpApplianceAdditionalDeviceEnum[];
+    /**
+     * How the heating rod of the installation is used (e.g. as the only heat
+     * source or only to further increase the temperature on top of the
+     * compressor). Only meaningful if the heatpump has a heating rod
+     * (see {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingRod}).
+     */
+    heatingRodUsage?: EnyoHeatpumpApplianceHeatingRodUsageEnum;
 }

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

@@ -4,6 +4,8 @@ export var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRodControllable"] = "HeatingRodControllable";
     /** If the heatpump supports room overheating via heating circuits */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["RoomOverheating"] = "RoomOverheating";
     /** If the heatpump supports buffer tank overheating */
@@ -59,6 +61,18 @@ export var EnyoHeatpumpApplianceAdditionalDeviceEnum;
     /** A solar thermal system is present in the installation */
     EnyoHeatpumpApplianceAdditionalDeviceEnum["SolarThermal"] = "SolarThermal";
 })(EnyoHeatpumpApplianceAdditionalDeviceEnum || (EnyoHeatpumpApplianceAdditionalDeviceEnum = {}));
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export var EnyoHeatpumpApplianceHeatingRodUsageEnum;
+(function (EnyoHeatpumpApplianceHeatingRodUsageEnum) {
+    /** The heating rod is the only heat source used (no compressor support) */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["OnlyHeatingRot"] = "OnlyHeatingRot";
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["HeatingRodForTemperatureIncrease"] = "HeatingRodForTemperatureIncrease";
+})(EnyoHeatpumpApplianceHeatingRodUsageEnum || (EnyoHeatpumpApplianceHeatingRodUsageEnum = {}));
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at

package/dist/version.d.ts

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