@enyo-energy/energy-app-sdk 1.27.0 → 1.28.0

package/README.md

@@ -1759,8 +1759,17 @@ An entry may carry an optional `gridFeeGrossPerKwh`: the gross grid fee **contai
 `pricePerKwh`, in currency units per kWh. It is a breakdown only — `pricePerKwh` is always the
 total, so never compute `pricePerKwh + gridFeeGrossPerKwh`.
 
+It may also carry an optional `spotPricePerKwh`: the net wholesale (e.g. EPEX day-ahead) price the
+interval's price is based on, as the provider reports it — in currency units per kWh, possibly negative.
+Informational too: never add it to `pricePerKwh`.
+
 ```typescript
-entries.push({ timestampIso: '2026-05-23T10:00:00Z', pricePerKwh: 0.31, gridFeeGrossPerKwh: 0.09 });
+entries.push({
+    timestampIso: '2026-05-23T10:00:00Z',
+    pricePerKwh: 0.31,
+    gridFeeGrossPerKwh: 0.09,
+    spotPricePerKwh: 0.084,
+});
 ```
 
 **Calling `setTariff` is the activation signal.** Return `AuthenticationRequired` or
@@ -4175,6 +4184,8 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 A hold that keeps an appliance **off** after a stop has its own type, `RestartDelay` (category `DeviceProtection`): set `context.switching` with `hold: KeptOff`, `minOffSeconds` and `untilIso` (when it may restart), and `powerW` to the power waiting for it — e.g. "Short pause after switching off — charging resumes at 13:15 so the car isn't switched on and off too often."
 
+**Fluctuating PV surplus.** When the surplus jumps around (clouds passing) and the energy manager holds an appliance's power steady instead of following every dip, state `PvSurplusFluctuating` (category `PvSurplus`) with `powerW` set to the power being held — e.g. "Charging power held steady while clouds pass." / "Ladeleistung wird gehalten, solange Wolken durchziehen." It is a smoothing decision, told apart from `PvSurplusAvailable` / `PvSurplusUnavailable`.
+
 ## Dynamic Grid Fees & Tariff Bonuses
 
 An electricity price is rarely one number. It is the energy price, plus the grid operator's network

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

@@ -38,6 +38,19 @@ var EnyoDataBusCommandReasonTypeEnum;
      * saying "elsewhere".
      */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusFluctuating"] = "pv-surplus-fluctuating";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */

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

@@ -54,6 +54,19 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * saying "elsewhere".
      */
     PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    PvSurplusFluctuating = "pv-surplus-fluctuating",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */

package/dist/cjs/types/enyo-electricity-tariff.d.cts

@@ -189,6 +189,19 @@ export interface EnyoTariffPriceEntry {
      * series declares {@link EnyoPriceComponentEnum.GridFee} in its `includes`.
      */
     gridFeeGrossPerKwh?: number;
+    /**
+     * Optional wholesale spot price per kWh this interval's price is based on,
+     * as the provider reports it — typically the EPEX day-ahead price for a
+     * dynamic tariff. In the tariff's currency (not cent), net: without grid
+     * fee, taxes, levies or supplier margin. May be negative.
+     *
+     * Informational only, like {@link gridFeeGrossPerKwh}: it shows what the
+     * price was derived from and is **never added** to {@link pricePerKwh},
+     * which is always the total price. Set it when the provider hands it out;
+     * omit it otherwise — consumers needing a spot price without it can read
+     * `useEpexSpotPrices()`.
+     */
+    spotPricePerKwh?: number;
 }
 /**
  * Prices for one direction over a requested range.

package/dist/cjs/version.cjs

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

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

@@ -54,6 +54,19 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
      * saying "elsewhere".
      */
     PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    PvSurplusFluctuating = "pv-surplus-fluctuating",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */

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

@@ -35,6 +35,19 @@ export var EnyoDataBusCommandReasonTypeEnum;
      * saying "elsewhere".
      */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
+    /**
+     * The PV surplus is fluctuating (e.g. clouds passing) and the energy manager
+     * deliberately holds the appliance's power steady instead of following
+     * every dip and peak — "Ladeleistung wird gehalten, solange Wolken
+     * durchziehen." / "Charging power held steady while clouds pass."
+     *
+     * Says the command is a smoothing decision, not a reaction to the surplus
+     * being there or gone: told apart from {@link PvSurplusAvailable} and
+     * {@link PvSurplusUnavailable}. Set {@link EnyoDataBusCommandReason.powerW}
+     * to the power being held. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusFluctuating"] = "pv-surplus-fluctuating";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */

package/dist/types/enyo-electricity-tariff.d.ts

@@ -189,6 +189,19 @@ export interface EnyoTariffPriceEntry {
      * series declares {@link EnyoPriceComponentEnum.GridFee} in its `includes`.
      */
     gridFeeGrossPerKwh?: number;
+    /**
+     * Optional wholesale spot price per kWh this interval's price is based on,
+     * as the provider reports it — typically the EPEX day-ahead price for a
+     * dynamic tariff. In the tariff's currency (not cent), net: without grid
+     * fee, taxes, levies or supplier margin. May be negative.
+     *
+     * Informational only, like {@link gridFeeGrossPerKwh}: it shows what the
+     * price was derived from and is **never added** to {@link pricePerKwh},
+     * which is always the total price. Set it when the provider hands it out;
+     * omit it otherwise — consumers needing a spot price without it can read
+     * `useEpexSpotPrices()`.
+     */
+    spotPricePerKwh?: number;
 }
 /**
  * Prices for one direction over a requested range.

package/dist/version.d.ts

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