@enyo-energy/energy-app-sdk 1.23.0 → 1.24.0

package/README.md

@@ -4453,6 +4453,100 @@ Notes:
   grant can be read against the announcement it answers. It is advisory — the
   command's `powerW` remains the only limit.
 
+#### Announcing Power Flexibility
+
+`ApplianceFlexibilityAnnouncementV2` is the **power-based** sibling of the
+announcement above. Where V1 says "4 kWh by 14:00", V2 says "I can draw
+800–2300 W, you may start me any time between 10:00 and 14:00, and I will then
+run for up to 90 minutes".
+
+Which one to send is decided by the demand, not by preference:
+
+| | Send V1 | Send V2 |
+| --- | --- | --- |
+| The appliance owes a known amount of energy by a deadline | ✅ | |
+| The appliance can absorb power, and the energy falls out of how long it runs | | ✅ |
+| Example | A charging session that needs 22 kWh by 07:00 | A heat pump that will take surplus into its tank |
+
+V2 deliberately has **no `kWh` field**. An energy figure would be read as
+authoritative the moment it existed, and the message would collapse back into V1
+with extra fields. An appliance that knows its energy sends V1.
+
+**The window is a trigger window, not a run window.**
+`availableFromIsoTimestamp` and `availableUntilIsoTimestamp` bound when the run
+may be *started*. `durationMinutes` says how long it then runs — a run started
+one minute before the window closes may still be drawing power long afterwards.
+
+```typescript
+import {
+    EnergyApp,
+    EnyoFlexibilityTargetEnum,
+} from '@enyo-energy/energy-app-sdk';
+
+const energyApp = new EnergyApp();
+const dataBus = energyApp.useDataBus();
+
+dataBus.sendMessage([{
+    type: 'message',
+    message: 'ApplianceFlexibilityAnnouncementV2',
+    applianceId: 'heatpump-1',
+    data: {
+        flexibility: {
+            // Modulating compressor: 800 W to 2300 W in 100 W steps.
+            power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+            // May be started any time this morning ...
+            availableFromIsoTimestamp: '2025-10-01T10:00:00Z',
+            availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+            // ... and then runs for up to 90 minutes, 20 at the very least.
+            durationMinutes: 90,
+            minDurationMinutes: 20,
+            // What the power would go into. Required here, unlike in V1.
+            targets: [
+                {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+                {target: EnyoFlexibilityTargetEnum.BufferTank, powerW: 800},
+            ],
+        },
+    },
+}]);
+```
+
+Integrations built on the SDK's integration base classes can publish the same
+message without assembling the envelope by hand:
+
+```typescript
+class MyHeatpump extends HeatpumpIntegrationEnergyApp {
+    private announce(): void {
+        this.publishFlexibilityAnnouncement('heatpump-1', {
+            power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+            availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+            durationMinutes: 90,
+            targets: [
+                {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+            ],
+        });
+    }
+}
+```
+
+Notes:
+
+- `power` is a band (`minWatt` / `maxWatt` / `stepWatt`), not a single figure,
+  because a modulating appliance is *placed*, not switched. A fixed-power
+  appliance states the same value for both bounds and a `stepWatt` equal to the
+  band's width.
+- `targets` is **required** here. V1 has no need of it — `kWh` is authoritative
+  there and the breakdown is decoration. V2 has no energy figure, so the targets
+  are the substance of the announcement.
+- `durationMinutes` omitted means the appliance sets no limit of its own and is
+  expected to stop itself when it is satisfied. `minDurationMinutes` is the
+  shortest run still worth starting — below it, a consumer filling a short gap
+  should leave the appliance alone rather than cycle it.
+- `context.progress` is worth setting precisely because there is no energy
+  figure: without it a consumer cannot tell a run that has nearly finished from
+  one that has barely started.
+- V1 is unchanged and remains fully supported. V2 is an additive sibling, not a
+  migration.
+
 #### Explaining Why a Command Was Issued
 
 Every data bus command can carry an `EnyoDataBusCommandReason`. Its `type`

package/dist/cjs/integrations/integration-energy-app.cjs

@@ -176,6 +176,51 @@ class IntegrationEnergyApp extends energy_app_js_1.EnergyApp {
         };
         this.useDataBus().sendMessage([msg]);
     }
+    /**
+     * Publishes an `ApplianceFlexibilityAnnouncementV2` — the power-based
+     * flexibility announcement: a draw the appliance offers inside a trigger
+     * window, with no fixed energy attached.
+     *
+     * Use this when the appliance can absorb power but owes no particular
+     * amount of energy — a heat pump that will take surplus into its tank, an
+     * air conditioner that can pre-cool. When the appliance instead owes a
+     * known `kWh` by a deadline, send an `ApplianceFlexibilityAnnouncementV1`
+     * rather than this; see
+     * {@link EnyoDataBusApplianceFlexibilityAnnouncementV2} for the full
+     * distinction.
+     *
+     * Publish again whenever the offer changes — the announcement describes the
+     * appliance right now, and a consumer keeps the last one it saw.
+     *
+     * @param applianceId - The appliance making the offer.
+     * @param flexibility - The power band, the window it may be triggered in,
+     *   optionally how long it may then run, and what the power is for. See
+     *   {@link EnyoDataBusApplianceFlexibilityAnnouncementV2.data.flexibility}.
+     *
+     * @example
+     * ```typescript
+     * this.publishFlexibilityAnnouncement('heatpump-1', {
+     *     power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+     *     availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+     *     durationMinutes: 90,
+     *     targets: [
+     *         {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+     *     ],
+     * });
+     * ```
+     */
+    publishFlexibilityAnnouncement(applianceId, flexibility) {
+        const msg = {
+            id: this.generateMessageId(),
+            type: 'message',
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2,
+            source: this.source,
+            applianceId,
+            timestampIso: new Date().toISOString(),
+            data: { flexibility }
+        };
+        this.useDataBus().sendMessage([msg]);
+    }
     /**
      * Resolves the list of appliance IDs this integration is responsible for.
      *

package/dist/cjs/integrations/integration-energy-app.d.cts

@@ -1,5 +1,5 @@
 import { EnergyApp } from "../energy-app.cjs";
-import { EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusMessage, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.cjs";
+import { EnyoDataBusApplianceFlexibilityAnnouncementV2, EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusMessage, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.cjs";
 import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.cjs";
 import { EnyoSourceEnum } from "../types/enyo-source.enum.cjs";
 import { DataBusCommandHandler } from "../implementations/data-bus/data-bus-command-handler.cjs";
@@ -132,6 +132,40 @@ export declare abstract class IntegrationEnergyApp extends EnergyApp {
      *   (seconds), and optional command correlation id / reason.
      */
     publishGridOperatorPowerLimitationExecuted(applianceId: string, data: EnyoDataBusGridOperatorPowerLimitationExecutedV1['data']): void;
+    /**
+     * Publishes an `ApplianceFlexibilityAnnouncementV2` — the power-based
+     * flexibility announcement: a draw the appliance offers inside a trigger
+     * window, with no fixed energy attached.
+     *
+     * Use this when the appliance can absorb power but owes no particular
+     * amount of energy — a heat pump that will take surplus into its tank, an
+     * air conditioner that can pre-cool. When the appliance instead owes a
+     * known `kWh` by a deadline, send an `ApplianceFlexibilityAnnouncementV1`
+     * rather than this; see
+     * {@link EnyoDataBusApplianceFlexibilityAnnouncementV2} for the full
+     * distinction.
+     *
+     * Publish again whenever the offer changes — the announcement describes the
+     * appliance right now, and a consumer keeps the last one it saw.
+     *
+     * @param applianceId - The appliance making the offer.
+     * @param flexibility - The power band, the window it may be triggered in,
+     *   optionally how long it may then run, and what the power is for. See
+     *   {@link EnyoDataBusApplianceFlexibilityAnnouncementV2.data.flexibility}.
+     *
+     * @example
+     * ```typescript
+     * this.publishFlexibilityAnnouncement('heatpump-1', {
+     *     power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+     *     availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+     *     durationMinutes: 90,
+     *     targets: [
+     *         {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+     *     ],
+     * });
+     * ```
+     */
+    publishFlexibilityAnnouncement(applianceId: string, flexibility: EnyoDataBusApplianceFlexibilityAnnouncementV2['data']['flexibility']): void;
     /**
      * Resolves the list of appliance IDs this integration is responsible for.
      *

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

@@ -425,6 +425,8 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["MeterValuesUpdateV1"] = "MeterValuesUpdateV1";
     EnyoDataBusMessageEnum["BatteryValuesUpdateV1"] = "BatteryValuesUpdateV1";
     EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV1"] = "ApplianceFlexibilityAnnouncementV1";
+    /** Power-based flexibility: a draw the appliance offers inside a trigger window, with no fixed energy. */
+    EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV2"] = "ApplianceFlexibilityAnnouncementV2";
     EnyoDataBusMessageEnum["ApplianceStateUpdateV1"] = "ApplianceStateUpdateV1";
     EnyoDataBusMessageEnum["HeatpumpValuesUpdateV1"] = "HeatpumpValuesUpdateV1";
     EnyoDataBusMessageEnum["HeatingRodValuesUpdateV1"] = "HeatingRodValuesUpdateV1";

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

@@ -9,7 +9,7 @@ import type { EnyoCalibrationRequestOriginEnum, EnyoCalibrationRun } from "./eny
 import { EnyoEnergyPrices } from "./enyo-energy-prices.cjs";
 import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.cjs";
-import type { EnyoFlexibilityTargetEnum, EnyoFlexibilityTargetPower } from "./enyo-flexibility-announcement.cjs";
+import type { EnyoFlexibilityHeatpumpTargetTypeEnum, EnyoFlexibilityPowerBand, EnyoFlexibilityProgress, EnyoFlexibilityTargetEnum, 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";
@@ -696,6 +696,8 @@ export declare enum EnyoDataBusMessageEnum {
     MeterValuesUpdateV1 = "MeterValuesUpdateV1",
     BatteryValuesUpdateV1 = "BatteryValuesUpdateV1",
     ApplianceFlexibilityAnnouncementV1 = "ApplianceFlexibilityAnnouncementV1",
+    /** Power-based flexibility: a draw the appliance offers inside a trigger window, with no fixed energy. */
+    ApplianceFlexibilityAnnouncementV2 = "ApplianceFlexibilityAnnouncementV2",
     ApplianceStateUpdateV1 = "ApplianceStateUpdateV1",
     HeatpumpValuesUpdateV1 = "HeatpumpValuesUpdateV1",
     HeatingRodValuesUpdateV1 = "HeatingRodValuesUpdateV1",
@@ -1073,6 +1075,149 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
         };
     };
 }
+/**
+ * An appliance announces a *power* it can absorb inside a window, with no fixed
+ * energy attached.
+ *
+ * The power-based counterpart to
+ * {@link EnyoDataBusApplianceFlexibilityAnnouncementV1}. V1 answers "how much
+ * energy do I owe, and by when" — the right shape for a charging session with a
+ * target. This one answers "how much can I draw, when may you start me, and how
+ * long may I run" — the right shape for a heat pump that can take surplus into a
+ * tank without ever owing a particular number of kWh.
+ *
+ * Which to send is decided by the demand, not by preference:
+ *
+ * - **Energy is fixed, timing is not** → V1. The appliance owes `kWh` by a
+ *   deadline and the decision maker schedules it.
+ * - **Power is offered, energy falls out of it** → V2. There is no amount the
+ *   appliance is owed; running it longer simply uses more.
+ *
+ * Deliberately no `kWh` field: an energy figure here would be read as
+ * authoritative the moment it exists, and the announcement would collapse back
+ * into V1 with extra fields. An appliance that knows its energy should send V1.
+ *
+ * **The window is a trigger window, not a run window.**
+ * {@link data.flexibility.availableFromIsoTimestamp} and
+ * {@link data.flexibility.availableUntilIsoTimestamp} bound when the run may be
+ * *started*; {@link data.flexibility.durationMinutes} says how long it then
+ * runs, and a run started at the end of the window may finish well past it.
+ *
+ * @example
+ * ```typescript
+ * dataBus.sendMessage([{
+ *     type: 'message',
+ *     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2,
+ *     applianceId: 'heatpump-1',
+ *     data: {
+ *         flexibility: {
+ *             // Modulating compressor: 800 W to 2300 W in 100 W steps.
+ *             power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+ *             // May be started any time this morning ...
+ *             availableFromIsoTimestamp: '2025-10-01T10:00:00Z',
+ *             availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+ *             // ... and then runs for up to 90 minutes, 20 at the very least.
+ *             durationMinutes: 90,
+ *             minDurationMinutes: 20,
+ *             // What the power would go into.
+ *             targets: [
+ *                 {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+ *                 {target: EnyoFlexibilityTargetEnum.BufferTank, powerW: 800},
+ *             ],
+ *         },
+ *     },
+ * }]);
+ * ```
+ */
+export interface EnyoDataBusApplianceFlexibilityAnnouncementV2 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2;
+    /** ID of the appliance */
+    applianceId: string;
+    data: {
+        flexibility: {
+            /**
+             * Power envelope the appliance offers, in Watts — `minWatt`,
+             * `maxWatt` and the `stepWatt` granularity between them.
+             *
+             * A band rather than a single figure because a modulating appliance
+             * is placed, not switched: a decision maker with surplus to spend
+             * needs to know it may run the compressor at 1200 W rather than
+             * choosing between 2300 W and nothing. A fixed-power appliance
+             * states the same value for both bounds and a `stepWatt` equal to
+             * the band's width.
+             */
+            power: EnyoFlexibilityPowerBand;
+            /**
+             * Earliest the run may be triggered, ISO 8601. Omitted means it may
+             * be triggered immediately.
+             */
+            availableFromIsoTimestamp?: string;
+            /**
+             * Latest the run may be triggered, ISO 8601.
+             *
+             * A trigger deadline, not a completion deadline — a run started one
+             * minute before this may still be drawing power long afterwards.
+             * See {@link durationMinutes} for how long.
+             */
+            availableUntilIsoTimestamp: string;
+            /**
+             * How long the run may last once triggered, in minutes.
+             *
+             * Omitted means the appliance sets no limit of its own and the
+             * decision maker may run it for as long as the window and its own
+             * budget allow — the appliance is expected to stop itself when the
+             * tank, the room or the battery is satisfied.
+             */
+            durationMinutes?: number;
+            /**
+             * Shortest contiguous run still worth starting, in minutes.
+             *
+             * Below this the run costs more than it returns — a compressor that
+             * spends its first ten minutes getting up to temperature gains
+             * nothing from a five-minute slot, and a decision maker filling a
+             * short gap should leave it alone rather than cycle it.
+             */
+            minDurationMinutes?: number;
+            /**
+             * What the offered power would go into, and how much of it each
+             * target would draw — e.g. a heat pump splitting between the
+             * domestic hot water tank and the heating buffer tank.
+             *
+             * Required here, unlike on
+             * {@link EnyoDataBusApplianceFlexibilityAnnouncementV1} where it is
+             * optional context beside an authoritative `kWh`: this message has
+             * no energy figure, so the targets are the substance of the
+             * announcement rather than a decoration on it. A given target
+             * SHOULD appear at most once, and the entries' `powerW` SHOULD sit
+             * inside {@link power}.
+             */
+            targets: EnyoFlexibilityTargetPower[];
+            /**
+             * Optional extra context for the consumer of this announcement.
+             * Nested so further context keys can be added without changing the
+             * message shape again.
+             */
+            context?: {
+                /**
+                 * For heat pumps: what the flexibility is aimed at. Narrower
+                 * than {@link targets}, and shared with the category-level
+                 * announcement so both surfaces speak one vocabulary.
+                 */
+                heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
+                /**
+                 * What the run is driving toward and where it stands now — a
+                 * tank at 38 °C heading for 50 °C.
+                 *
+                 * Worth setting precisely because this message carries no
+                 * energy figure: without it a consumer cannot tell a run that
+                 * has nearly finished from one that has barely started.
+                 */
+                progress?: EnyoFlexibilityProgress;
+            };
+        };
+    };
+}
 /**
  * Message sent when an appliance's connectivity state and/or health status
  * changes. At least one of `state` or `status` should be set; both may be
@@ -3213,7 +3358,7 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
  * energyApp.useDataBus().sendMessage([{
  *     type: 'message',
  *     message: 'RequestVehicleSocEstimateV1',
- *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000},
+ *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000, targetSocPercent: 80},
  * }]);
  * ```
  */
@@ -3244,6 +3389,20 @@ export interface EnyoDataBusRequestVehicleSocEstimateV1 extends EnyoDataBusMessa
          * values — find the right one without guessing.
          */
         applianceId?: string;
+        /**
+         * State of charge the caller is planning towards, in percent (0-100) —
+         * the session's target as in
+         * {@link EnyoDataBusStartChargeV1.data.targetSocPercent}, not
+         * a limit on the answer.
+         *
+         * Told to the responder because what the estimate is *for* changes how
+         * much trouble is worth taking to get it: a stored reading already at
+         * or above the target answers the question without waking the car,
+         * while one far below it justifies a fresh fetch. Omitted means the
+         * responder decides on its own; the reading returned is the same
+         * either way.
+         */
+        targetSocPercent?: number;
     };
 }
 /**

package/dist/cjs/version.cjs

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

package/dist/integrations/integration-energy-app.d.ts

@@ -1,5 +1,5 @@
 import { EnergyApp } from "../energy-app.js";
-import { EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusMessage, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.js";
+import { EnyoDataBusApplianceFlexibilityAnnouncementV2, EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusMessage, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.js";
 import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.js";
 import { EnyoSourceEnum } from "../types/enyo-source.enum.js";
 import { DataBusCommandHandler } from "../implementations/data-bus/data-bus-command-handler.js";
@@ -132,6 +132,40 @@ export declare abstract class IntegrationEnergyApp extends EnergyApp {
      *   (seconds), and optional command correlation id / reason.
      */
     publishGridOperatorPowerLimitationExecuted(applianceId: string, data: EnyoDataBusGridOperatorPowerLimitationExecutedV1['data']): void;
+    /**
+     * Publishes an `ApplianceFlexibilityAnnouncementV2` — the power-based
+     * flexibility announcement: a draw the appliance offers inside a trigger
+     * window, with no fixed energy attached.
+     *
+     * Use this when the appliance can absorb power but owes no particular
+     * amount of energy — a heat pump that will take surplus into its tank, an
+     * air conditioner that can pre-cool. When the appliance instead owes a
+     * known `kWh` by a deadline, send an `ApplianceFlexibilityAnnouncementV1`
+     * rather than this; see
+     * {@link EnyoDataBusApplianceFlexibilityAnnouncementV2} for the full
+     * distinction.
+     *
+     * Publish again whenever the offer changes — the announcement describes the
+     * appliance right now, and a consumer keeps the last one it saw.
+     *
+     * @param applianceId - The appliance making the offer.
+     * @param flexibility - The power band, the window it may be triggered in,
+     *   optionally how long it may then run, and what the power is for. See
+     *   {@link EnyoDataBusApplianceFlexibilityAnnouncementV2.data.flexibility}.
+     *
+     * @example
+     * ```typescript
+     * this.publishFlexibilityAnnouncement('heatpump-1', {
+     *     power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+     *     availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+     *     durationMinutes: 90,
+     *     targets: [
+     *         {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+     *     ],
+     * });
+     * ```
+     */
+    publishFlexibilityAnnouncement(applianceId: string, flexibility: EnyoDataBusApplianceFlexibilityAnnouncementV2['data']['flexibility']): void;
     /**
      * Resolves the list of appliance IDs this integration is responsible for.
      *

package/dist/integrations/integration-energy-app.js

@@ -173,6 +173,51 @@ export class IntegrationEnergyApp extends EnergyApp {
         };
         this.useDataBus().sendMessage([msg]);
     }
+    /**
+     * Publishes an `ApplianceFlexibilityAnnouncementV2` — the power-based
+     * flexibility announcement: a draw the appliance offers inside a trigger
+     * window, with no fixed energy attached.
+     *
+     * Use this when the appliance can absorb power but owes no particular
+     * amount of energy — a heat pump that will take surplus into its tank, an
+     * air conditioner that can pre-cool. When the appliance instead owes a
+     * known `kWh` by a deadline, send an `ApplianceFlexibilityAnnouncementV1`
+     * rather than this; see
+     * {@link EnyoDataBusApplianceFlexibilityAnnouncementV2} for the full
+     * distinction.
+     *
+     * Publish again whenever the offer changes — the announcement describes the
+     * appliance right now, and a consumer keeps the last one it saw.
+     *
+     * @param applianceId - The appliance making the offer.
+     * @param flexibility - The power band, the window it may be triggered in,
+     *   optionally how long it may then run, and what the power is for. See
+     *   {@link EnyoDataBusApplianceFlexibilityAnnouncementV2.data.flexibility}.
+     *
+     * @example
+     * ```typescript
+     * this.publishFlexibilityAnnouncement('heatpump-1', {
+     *     power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+     *     availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+     *     durationMinutes: 90,
+     *     targets: [
+     *         {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+     *     ],
+     * });
+     * ```
+     */
+    publishFlexibilityAnnouncement(applianceId, flexibility) {
+        const msg = {
+            id: this.generateMessageId(),
+            type: 'message',
+            message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2,
+            source: this.source,
+            applianceId,
+            timestampIso: new Date().toISOString(),
+            data: { flexibility }
+        };
+        this.useDataBus().sendMessage([msg]);
+    }
     /**
      * Resolves the list of appliance IDs this integration is responsible for.
      *

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

@@ -9,7 +9,7 @@ import type { EnyoCalibrationRequestOriginEnum, EnyoCalibrationRun } from "./eny
 import { EnyoEnergyPrices } from "./enyo-energy-prices.js";
 import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.js";
-import type { EnyoFlexibilityTargetEnum, EnyoFlexibilityTargetPower } from "./enyo-flexibility-announcement.js";
+import type { EnyoFlexibilityHeatpumpTargetTypeEnum, EnyoFlexibilityPowerBand, EnyoFlexibilityProgress, EnyoFlexibilityTargetEnum, 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";
@@ -696,6 +696,8 @@ export declare enum EnyoDataBusMessageEnum {
     MeterValuesUpdateV1 = "MeterValuesUpdateV1",
     BatteryValuesUpdateV1 = "BatteryValuesUpdateV1",
     ApplianceFlexibilityAnnouncementV1 = "ApplianceFlexibilityAnnouncementV1",
+    /** Power-based flexibility: a draw the appliance offers inside a trigger window, with no fixed energy. */
+    ApplianceFlexibilityAnnouncementV2 = "ApplianceFlexibilityAnnouncementV2",
     ApplianceStateUpdateV1 = "ApplianceStateUpdateV1",
     HeatpumpValuesUpdateV1 = "HeatpumpValuesUpdateV1",
     HeatingRodValuesUpdateV1 = "HeatingRodValuesUpdateV1",
@@ -1073,6 +1075,149 @@ export interface EnyoDataBusApplianceFlexibilityAnnouncementV1 extends EnyoDataB
         };
     };
 }
+/**
+ * An appliance announces a *power* it can absorb inside a window, with no fixed
+ * energy attached.
+ *
+ * The power-based counterpart to
+ * {@link EnyoDataBusApplianceFlexibilityAnnouncementV1}. V1 answers "how much
+ * energy do I owe, and by when" — the right shape for a charging session with a
+ * target. This one answers "how much can I draw, when may you start me, and how
+ * long may I run" — the right shape for a heat pump that can take surplus into a
+ * tank without ever owing a particular number of kWh.
+ *
+ * Which to send is decided by the demand, not by preference:
+ *
+ * - **Energy is fixed, timing is not** → V1. The appliance owes `kWh` by a
+ *   deadline and the decision maker schedules it.
+ * - **Power is offered, energy falls out of it** → V2. There is no amount the
+ *   appliance is owed; running it longer simply uses more.
+ *
+ * Deliberately no `kWh` field: an energy figure here would be read as
+ * authoritative the moment it exists, and the announcement would collapse back
+ * into V1 with extra fields. An appliance that knows its energy should send V1.
+ *
+ * **The window is a trigger window, not a run window.**
+ * {@link data.flexibility.availableFromIsoTimestamp} and
+ * {@link data.flexibility.availableUntilIsoTimestamp} bound when the run may be
+ * *started*; {@link data.flexibility.durationMinutes} says how long it then
+ * runs, and a run started at the end of the window may finish well past it.
+ *
+ * @example
+ * ```typescript
+ * dataBus.sendMessage([{
+ *     type: 'message',
+ *     message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2,
+ *     applianceId: 'heatpump-1',
+ *     data: {
+ *         flexibility: {
+ *             // Modulating compressor: 800 W to 2300 W in 100 W steps.
+ *             power: {minWatt: 800, maxWatt: 2300, stepWatt: 100},
+ *             // May be started any time this morning ...
+ *             availableFromIsoTimestamp: '2025-10-01T10:00:00Z',
+ *             availableUntilIsoTimestamp: '2025-10-01T14:00:00Z',
+ *             // ... and then runs for up to 90 minutes, 20 at the very least.
+ *             durationMinutes: 90,
+ *             minDurationMinutes: 20,
+ *             // What the power would go into.
+ *             targets: [
+ *                 {target: EnyoFlexibilityTargetEnum.DomesticHotWater, powerW: 1500},
+ *                 {target: EnyoFlexibilityTargetEnum.BufferTank, powerW: 800},
+ *             ],
+ *         },
+ *     },
+ * }]);
+ * ```
+ */
+export interface EnyoDataBusApplianceFlexibilityAnnouncementV2 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.ApplianceFlexibilityAnnouncementV2;
+    /** ID of the appliance */
+    applianceId: string;
+    data: {
+        flexibility: {
+            /**
+             * Power envelope the appliance offers, in Watts — `minWatt`,
+             * `maxWatt` and the `stepWatt` granularity between them.
+             *
+             * A band rather than a single figure because a modulating appliance
+             * is placed, not switched: a decision maker with surplus to spend
+             * needs to know it may run the compressor at 1200 W rather than
+             * choosing between 2300 W and nothing. A fixed-power appliance
+             * states the same value for both bounds and a `stepWatt` equal to
+             * the band's width.
+             */
+            power: EnyoFlexibilityPowerBand;
+            /**
+             * Earliest the run may be triggered, ISO 8601. Omitted means it may
+             * be triggered immediately.
+             */
+            availableFromIsoTimestamp?: string;
+            /**
+             * Latest the run may be triggered, ISO 8601.
+             *
+             * A trigger deadline, not a completion deadline — a run started one
+             * minute before this may still be drawing power long afterwards.
+             * See {@link durationMinutes} for how long.
+             */
+            availableUntilIsoTimestamp: string;
+            /**
+             * How long the run may last once triggered, in minutes.
+             *
+             * Omitted means the appliance sets no limit of its own and the
+             * decision maker may run it for as long as the window and its own
+             * budget allow — the appliance is expected to stop itself when the
+             * tank, the room or the battery is satisfied.
+             */
+            durationMinutes?: number;
+            /**
+             * Shortest contiguous run still worth starting, in minutes.
+             *
+             * Below this the run costs more than it returns — a compressor that
+             * spends its first ten minutes getting up to temperature gains
+             * nothing from a five-minute slot, and a decision maker filling a
+             * short gap should leave it alone rather than cycle it.
+             */
+            minDurationMinutes?: number;
+            /**
+             * What the offered power would go into, and how much of it each
+             * target would draw — e.g. a heat pump splitting between the
+             * domestic hot water tank and the heating buffer tank.
+             *
+             * Required here, unlike on
+             * {@link EnyoDataBusApplianceFlexibilityAnnouncementV1} where it is
+             * optional context beside an authoritative `kWh`: this message has
+             * no energy figure, so the targets are the substance of the
+             * announcement rather than a decoration on it. A given target
+             * SHOULD appear at most once, and the entries' `powerW` SHOULD sit
+             * inside {@link power}.
+             */
+            targets: EnyoFlexibilityTargetPower[];
+            /**
+             * Optional extra context for the consumer of this announcement.
+             * Nested so further context keys can be added without changing the
+             * message shape again.
+             */
+            context?: {
+                /**
+                 * For heat pumps: what the flexibility is aimed at. Narrower
+                 * than {@link targets}, and shared with the category-level
+                 * announcement so both surfaces speak one vocabulary.
+                 */
+                heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
+                /**
+                 * What the run is driving toward and where it stands now — a
+                 * tank at 38 °C heading for 50 °C.
+                 *
+                 * Worth setting precisely because this message carries no
+                 * energy figure: without it a consumer cannot tell a run that
+                 * has nearly finished from one that has barely started.
+                 */
+                progress?: EnyoFlexibilityProgress;
+            };
+        };
+    };
+}
 /**
  * Message sent when an appliance's connectivity state and/or health status
  * changes. At least one of `state` or `status` should be set; both may be
@@ -3213,7 +3358,7 @@ export interface EnyoDataBusVehicleSocUpdateV1 extends EnyoDataBusMessage {
  * energyApp.useDataBus().sendMessage([{
  *     type: 'message',
  *     message: 'RequestVehicleSocEstimateV1',
- *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000},
+ *     data: {requestId, vehicleId, maxAgeMs: 15 * 60 * 1000, targetSocPercent: 80},
  * }]);
  * ```
  */
@@ -3244,6 +3389,20 @@ export interface EnyoDataBusRequestVehicleSocEstimateV1 extends EnyoDataBusMessa
          * values — find the right one without guessing.
          */
         applianceId?: string;
+        /**
+         * State of charge the caller is planning towards, in percent (0-100) —
+         * the session's target as in
+         * {@link EnyoDataBusStartChargeV1.data.targetSocPercent}, not
+         * a limit on the answer.
+         *
+         * Told to the responder because what the estimate is *for* changes how
+         * much trouble is worth taking to get it: a stored reading already at
+         * or above the target answers the question without waking the car,
+         * while one far below it justifies a fresh fetch. Omitted means the
+         * responder decides on its own; the reading returned is the same
+         * either way.
+         */
+        targetSocPercent?: number;
     };
 }
 /**

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

@@ -422,6 +422,8 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["MeterValuesUpdateV1"] = "MeterValuesUpdateV1";
     EnyoDataBusMessageEnum["BatteryValuesUpdateV1"] = "BatteryValuesUpdateV1";
     EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV1"] = "ApplianceFlexibilityAnnouncementV1";
+    /** Power-based flexibility: a draw the appliance offers inside a trigger window, with no fixed energy. */
+    EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV2"] = "ApplianceFlexibilityAnnouncementV2";
     EnyoDataBusMessageEnum["ApplianceStateUpdateV1"] = "ApplianceStateUpdateV1";
     EnyoDataBusMessageEnum["HeatpumpValuesUpdateV1"] = "HeatpumpValuesUpdateV1";
     EnyoDataBusMessageEnum["HeatingRodValuesUpdateV1"] = "HeatingRodValuesUpdateV1";

package/dist/version.d.ts

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