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

package/README.md

@@ -184,7 +184,7 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | List known WiFi SSIDs in range | [`useWifi()`](#usewifi-energyappwifi) |
 | Query historical timeseries (PV, battery, meter, …) | [`useTimeseries()`](#usetimeseries-energyapptimeseries) |
 | Read site location (zip or coordinates) | [`useLocation()`](#uselocation-energyapplocation) |
-| Read grid connection point (fuse, phases, max power) | [`useGridConnectionPoint()`](#usegridconnectionpoint-energyappgridconnectionpoint) |
+| Read grid connection point (fuse, phases, max power, charger limit) | [`useGridConnectionPoint()`](#usegridconnectionpoint-energyappgridconnectionpoint) |
 | Retrieve secrets from the developer org secret store | [`useSecretManager()`](#usesecretmanager-energyappsecretmanager) |
 | Submit energy-manager diagnostics | [`useDiagnostics()`](#usediagnostics-energyappdiagnostics) |
 | Register a weather / PV / dynamic-price forecast provider | [`useWeatherForecasting()`](#useweatherforecasting-energyappweatherforecasting) / [`usePvForecasting()`](#usepvforecasting-energyapppvforecasting) / [`useDynamicPriceForecast()`](#usedynamicpriceforecast-energyappdynamicpriceforecast) |
@@ -249,6 +249,7 @@ Every Energy App must be defined using `defineEnergyAppPackage()`:
 import {
     defineEnergyAppPackage,
     EnergyAppPackageCategory,
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum,
     EnergyAppPermissionTypeEnum
 } from '@enyo-energy/energy-app-sdk';
 
@@ -291,11 +292,22 @@ const packageDef = defineEnergyAppPackage({
         },
         deviceDetection: {
             modbus: [{
+                // Optional, only on the first entry: how the entries and their matching
+                // values combine. Default: RegistersOr_MatchingValuesOr.
+                mode: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersAnd_MatchingValuesOr,
                 unitIds: [1],
                 registerAddress: 40001,
                 registerSize: 2,
                 type: 'string',
                 matchingValues: ['SolarMax', 'SMA']
+            }, {
+                unitIds: [1],
+                // `registerType` defaults to 'holding'; use 'input' for function code 4.
+                registerType: 'input',
+                registerAddress: 30053,
+                registerSize: 2,
+                type: 'UInt32BE',
+                matchingValues: ['9401', '9402']
             }],
             mdns: [{
                 // The Envoy advertises under a vendor-specific service type; without
@@ -1592,13 +1604,18 @@ if (full) console.log(`lat=${full.latitude} lon=${full.longitude}`);
 
 #### `useGridConnectionPoint(): EnergyAppGridConnectionPoint`
 
-Read the site's grid connection details — main fuse rating, number of phases, and the maximum allowed grid power. Use this to size dispatch envelopes and avoid violating the contractual cap.
+Read the site's grid connection details — main fuse rating, number of phases, the maximum allowed grid power, and the total power that load balancing may allocate to EV chargers. Use this to size dispatch envelopes and avoid violating the contractual cap.
+
+`chargerLimitW` is optional: when it is not configured, load balancing falls back to `DEFAULT_CHARGER_LIMIT_W` (11 kW).
 
 ```typescript
+import {DEFAULT_CHARGER_LIMIT_W} from "@enyo-energy/energy-app-sdk";
+
 const gcp = energyApp.useGridConnectionPoint();
 const point = await gcp.getGridConnectionPoint();
 if (point) {
     console.log(`Fuse ${point.fuseAmpere}A across ${point.numberOfPhases} phases`);
+    console.log(`Charger limit ${point.chargerLimitW ?? DEFAULT_CHARGER_LIMIT_W} W`);
 }
 ```
 
@@ -1725,6 +1742,14 @@ await tariffs.publishPrices(EnyoTariffDirectionEnum.Consumption, {
 });
 ```
 
+An entry may carry an optional `gridFeeGrossPerKwh`: the gross grid fee **contained in**
+`pricePerKwh`, in currency units per kWh. It is a breakdown only — `pricePerKwh` is always the
+total, so never compute `pricePerKwh + gridFeeGrossPerKwh`.
+
+```typescript
+entries.push({ timestampIso: '2026-05-23T10:00:00Z', pricePerKwh: 0.31, gridFeeGrossPerKwh: 0.09 });
+```
+
 **Calling `setTariff` is the activation signal.** Return `AuthenticationRequired` or
 `OnboardingRequired` from the handler to have the host send the user somewhere, and carry the
 `authenticationUrl` / `onboardingGuideId` that makes it actionable; when that flow later completes,
@@ -1847,6 +1872,11 @@ forecast series concatenate into one timeline without translation. Every measure
 optional: you get what the provider holds and you asked for, and a measure it does not hold is simply
 absent rather than an error.
 
+`timestampIso` is the **start** of the bucket a reading or forecast entry covers. The irradiance
+fields are the mean over `[timestampIso, timestampIso + resolution)` — not the value at that moment,
+and not the mean of the preceding hour. Temperature, wind and cloud cover are the value at the start
+of the bucket for an hourly source, and the time-weighted mean over the bucket at coarser resolutions.
+
 Aggregates per measure live in `statistics`, keyed by `WeatherHistoryMeasureEnum`. `averageValue` is
 time-weighted; for the irradiance measures it is a mean power density in W/m², so multiply by the
 covered duration in hours to get received energy in Wh/m². `symbol` is categorical and therefore
@@ -3980,6 +4010,12 @@ Each event carries the **complete** picture of the slot — render it as it arri
 
 New reason types came with this surface, so a skipped row can say *why* instead of falling back to a generic "scheduled optimization": `SessionComplete`, `AppliancePaused`, `NothingConnected`, `DeadlinePassed`, `WaitingForCheaperSlot`, `AboveOwnPriceLimit`, `BelowMinPower`, `OtherApplianceTurn`, `SupplyExhausted`, `OutsideSchedule` — grouped by the new `SessionState` and `Contention` reason categories. `ApplianceInitiatedDraw` and `PowerOffered` came with the waterfall states above.
 
+**Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history.
+
+**Short-cycling protection.** When an appliance is kept running (or kept off) to honour its minimum on/off time, state `DeviceProtection` with `context.switching` (`EnyoDataBusCommandReasonSwitchingContext`): `hold` (`EnyoSwitchingProtectionHoldEnum.KeptOn` / `KeptOff`), `minOnSeconds`, `minOffSeconds` and `untilIso`. The text can then say "Kept running for another 4 minutes to protect the compressor" instead of a generic "Protecting the device".
+
+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."
+
 ## Dynamic Grid Fees & Tariff Bonuses
 
 An electricity price is rarely one number. It is the energy price, plus the grid operator's network
@@ -4547,6 +4583,28 @@ Notes:
 - V1 is unchanged and remains fully supported. V2 is an additive sibling, not a
   migration.
 
+#### Forecasting When a Heat Pump Runs
+
+A heat pump integration can publish its own forecast of when the heat pump will run with
+`HeatpumpOperationForecastV1` (or `publishHeatpumpOperationForecast()` on `IntegrationEnergyApp`).
+It is a prediction, not a request for power — to offer power, send `ApplianceFlexibilityAnnouncementV2`.
+
+Each entry covers one slot of `resolution`, starting at `timestampIso`. `outdoorTemperatureC` and
+`running` are always present; `flowTemperatureC`, `generatedHeatWh`, `consumptionWh` and
+`averagePowerW` are optional. Energy values are per slot, and `averagePowerW` is averaged over the
+whole slot. Each message replaces the previous forecast for the appliance.
+
+```typescript
+this.publishHeatpumpOperationForecast('heatpump-1', {
+    resolution: ForecastResolutionEnum.OneHour,
+    entries: [
+        {timestampIso: '2026-10-06T06:00:00Z', outdoorTemperatureC: 4.5, running: true,
+         flowTemperatureC: 38, generatedHeatWh: 5200, consumptionWh: 1600, averagePowerW: 1600},
+        {timestampIso: '2026-10-06T07:00:00Z', outdoorTemperatureC: 5.0, running: false},
+    ],
+});
+```
+
 #### Explaining Why a Command Was Issued
 
 Every data bus command can carry an `EnyoDataBusCommandReason`. Its `type`

package/dist/cjs/energy-app-package-definition.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageCategory = void 0;
+exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCompatibilityStatus = exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -27,6 +27,34 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["Vehicle"] = "vehicle";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
+/**
+ * How the Modbus device detection rules in
+ * {@link EnergyAppPackageOptionsDeviceDetection.modbus} are combined.
+ *
+ * Each name has two parts:
+ * - `Registers…`: how the entries (registers) of the `modbus` list combine.
+ *   `Or` means one matching register is enough; `And` means every register has
+ *   to match, all on the same unit id.
+ * - `MatchingValues…`: how the `matchingValues` within one register combine.
+ *   `Or` means the register's value has to match one of them; `And` means it
+ *   has to match all of them.
+ *
+ * Only read from the **first** entry of the `modbus` list and applies to the
+ * whole list; set it there and nowhere else. Defaults to
+ * {@link RegistersOr_MatchingValuesOr} when omitted, which is the behaviour of
+ * all existing rules.
+ */
+var EnergyAppPackageOptionsDeviceDetectionModbusModeEnum;
+(function (EnergyAppPackageOptionsDeviceDetectionModbusModeEnum) {
+    /** One register has to match, with one of its matching values. The default. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersOr_MatchingValuesOr"] = "RegistersOr_MatchingValuesOr";
+    /** One register has to match, with all of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersOr_MatchingValuesAnd"] = "RegistersOr_MatchingValuesAnd";
+    /** Every register has to match, each with one of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersAnd_MatchingValuesOr"] = "RegistersAnd_MatchingValuesOr";
+    /** Every register has to match, each with all of its matching values. */
+    EnergyAppPackageOptionsDeviceDetectionModbusModeEnum["RegistersAnd_MatchingValuesAnd"] = "RegistersAnd_MatchingValuesAnd";
+})(EnergyAppPackageOptionsDeviceDetectionModbusModeEnum || (exports.EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = EnergyAppPackageOptionsDeviceDetectionModbusModeEnum = {}));
 /**
  * Whether a declared compatibility entry means "this works" or "this is known
  * not to work".

package/dist/cjs/energy-app-package-definition.d.cts

@@ -40,8 +40,85 @@ export interface EnergyAppPackageOptionsDeviceDetectionHostname {
     operation: 'eq' | 'startsWith';
     matchingValue: string;
 }
+/**
+ * Which Modbus register bank a device detection rule reads.
+ * - `'holding'`: holding registers, function code 3
+ * - `'input'`: input registers, function code 4
+ *
+ * The two banks are separate address spaces, so the same address may hold
+ * different data (or nothing) in each.
+ */
+export type EnergyAppPackageOptionsDeviceDetectionModbusRegisterType = 'holding' | 'input';
+/**
+ * How the Modbus device detection rules in
+ * {@link EnergyAppPackageOptionsDeviceDetection.modbus} are combined.
+ *
+ * Each name has two parts:
+ * - `Registers…`: how the entries (registers) of the `modbus` list combine.
+ *   `Or` means one matching register is enough; `And` means every register has
+ *   to match, all on the same unit id.
+ * - `MatchingValues…`: how the `matchingValues` within one register combine.
+ *   `Or` means the register's value has to match one of them; `And` means it
+ *   has to match all of them.
+ *
+ * Only read from the **first** entry of the `modbus` list and applies to the
+ * whole list; set it there and nowhere else. Defaults to
+ * {@link RegistersOr_MatchingValuesOr} when omitted, which is the behaviour of
+ * all existing rules.
+ */
+export declare enum EnergyAppPackageOptionsDeviceDetectionModbusModeEnum {
+    /** One register has to match, with one of its matching values. The default. */
+    RegistersOr_MatchingValuesOr = "RegistersOr_MatchingValuesOr",
+    /** One register has to match, with all of its matching values. */
+    RegistersOr_MatchingValuesAnd = "RegistersOr_MatchingValuesAnd",
+    /** Every register has to match, each with one of its matching values. */
+    RegistersAnd_MatchingValuesOr = "RegistersAnd_MatchingValuesOr",
+    /** Every register has to match, each with all of its matching values. */
+    RegistersAnd_MatchingValuesAnd = "RegistersAnd_MatchingValuesAnd"
+}
+/**
+ * Optional device detection configuration for Modbus TCP register matching:
+ * read a register range and compare its decoded value against the matching
+ * values.
+ *
+ * How several entries and several matching values combine is set by
+ * {@link mode} on the first entry of the list.
+ *
+ * @example
+ * // Vendor name in holding registers AND model id in an input register:
+ * modbus: [
+ *   {
+ *     mode: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersAnd_MatchingValuesOr,
+ *     unitIds: [1],
+ *     registerAddress: 40001,
+ *     registerSize: 2,
+ *     type: 'string',
+ *     matchingValues: ['SMA'],
+ *   },
+ *   {
+ *     unitIds: [1],
+ *     registerType: 'input',
+ *     registerAddress: 30053,
+ *     registerSize: 2,
+ *     type: 'UInt32BE',
+ *     matchingValues: ['9401', '9402'],
+ *   },
+ * ]
+ */
 export interface EnergyAppPackageOptionsDeviceDetectionModbus {
+    /**
+     * How all entries of the `modbus` list and their matching values combine.
+     * Only read from the first entry of the list — set it there and leave it
+     * out on the others. Defaults to
+     * {@link EnergyAppPackageOptionsDeviceDetectionModbusModeEnum.RegistersOr_MatchingValuesOr}.
+     */
+    mode?: EnergyAppPackageOptionsDeviceDetectionModbusModeEnum;
     unitIds: number[];
+    /**
+     * Which register bank to read. Defaults to `'holding'` when omitted,
+     * which is the behaviour of all existing rules.
+     */
+    registerType?: EnergyAppPackageOptionsDeviceDetectionModbusRegisterType;
     /** Register address, for example 30001 */
     registerAddress: number;
     /** Register size, for example 2 for 30001 - 30002 */

package/dist/cjs/implementations/onboarding-v2/define-onboarding-guide-v2.cjs

@@ -306,7 +306,11 @@ exports.onboardingV2Block = {
      * Filter it. `deviceTypes` is what turns this from "here are the six EEBUS
      * devices in the house" into "here is your heat pump", and with one match it
      * skips the screen entirely instead of asking a question with one possible
-     * answer.
+     * answer. `vendors` narrows it further, by the `brand` a peer announces —
+     * use it where the device type cannot separate the candidates (two EEBUS
+     * heat pumps in one house), or where the guide is written for one
+     * manufacturer and must not offer a competitor's device. The two filters are
+     * conjunctive: a peer must satisfy both to be offered.
      *
      * The picker is drawn from what mDNS discovery found, so the guide must have
      * scanned — keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its
@@ -327,8 +331,9 @@ exports.onboardingV2Block = {
      * paired peer into appliances.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param options - Screen wording, optional `deviceTypes` filter, skip
-     *   behaviour, and the `paired` / `not-found` / `failure` routing handles.
+     * @param options - Screen wording, optional `deviceTypes` and `vendors`
+     *   filters, skip behaviour, and the `paired` / `not-found` / `failure`
+     *   routing handles.
      * @returns The EEBUS device-select block.
      *
      * @example
@@ -336,6 +341,7 @@ exports.onboardingV2Block = {
      * onboardingV2Block.eebusDeviceSelect('pair', {
      *     headline: t('Wärmepumpe auswählen', 'Select the heat pump'),
      *     deviceTypes: [EnyoEebusDeviceTypeEnum.HeatPumpAppliance],
+     *     vendors: ['Vaillant'],
      *     outcomes: [
      *         {id: 'ok',    value: EnyoOnboardingV2EebusPairOutcome.Paired,   label: t('Gekoppelt', 'Paired')},
      *         {id: 'none',  value: EnyoOnboardingV2EebusPairOutcome.NotFound, label: t('Nichts gefunden', 'Nothing found')},

package/dist/cjs/implementations/onboarding-v2/define-onboarding-guide-v2.d.cts

@@ -254,7 +254,11 @@ export declare const onboardingV2Block: {
      * Filter it. `deviceTypes` is what turns this from "here are the six EEBUS
      * devices in the house" into "here is your heat pump", and with one match it
      * skips the screen entirely instead of asking a question with one possible
-     * answer.
+     * answer. `vendors` narrows it further, by the `brand` a peer announces —
+     * use it where the device type cannot separate the candidates (two EEBUS
+     * heat pumps in one house), or where the guide is written for one
+     * manufacturer and must not offer a competitor's device. The two filters are
+     * conjunctive: a peer must satisfy both to be offered.
      *
      * The picker is drawn from what mDNS discovery found, so the guide must have
      * scanned — keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its
@@ -275,8 +279,9 @@ export declare const onboardingV2Block: {
      * paired peer into appliances.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param options - Screen wording, optional `deviceTypes` filter, skip
-     *   behaviour, and the `paired` / `not-found` / `failure` routing handles.
+     * @param options - Screen wording, optional `deviceTypes` and `vendors`
+     *   filters, skip behaviour, and the `paired` / `not-found` / `failure`
+     *   routing handles.
      * @returns The EEBUS device-select block.
      *
      * @example
@@ -284,6 +289,7 @@ export declare const onboardingV2Block: {
      * onboardingV2Block.eebusDeviceSelect('pair', {
      *     headline: t('Wärmepumpe auswählen', 'Select the heat pump'),
      *     deviceTypes: [EnyoEebusDeviceTypeEnum.HeatPumpAppliance],
+     *     vendors: ['Vaillant'],
      *     outcomes: [
      *         {id: 'ok',    value: EnyoOnboardingV2EebusPairOutcome.Paired,   label: t('Gekoppelt', 'Paired')},
      *         {id: 'none',  value: EnyoOnboardingV2EebusPairOutcome.NotFound, label: t('Nichts gefunden', 'Nothing found')},

package/dist/cjs/implementations/onboarding-v2/onboarding-v2-validators.cjs

@@ -614,9 +614,9 @@ function isPickerBlock(block) {
  *   it would either be skipped along with it or offer a way past the pick. Both
  *   are errors rather than warnings, because there is no reading of the step
  *   that behaves sensibly.
- * - **An empty filter is not a filter.** `detectedAt: []` / `deviceTypes: []`
- *   match nothing, so the picker can only ever reach its `not-found` branch.
- *   Omitting the property is how "no filter" is expressed.
+ * - **An empty filter is not a filter.** `detectedAt: []` / `deviceTypes: []` /
+ *   `vendors: []` match nothing, so the picker can only ever reach its
+ *   `not-found` branch. Omitting the property is how "no filter" is expressed.
  * - **A picker that renders should say something.** With neither a headline of
  *   its own nor a step title, the installer gets a bare list — a warning, since
  *   the host has a default caption.
@@ -655,6 +655,10 @@ function validatePickerBlocks(step, at, errors, warnings) {
                 errors.push(`${at}: ${label(block)} has an empty \`deviceTypes\` filter, which matches no peer — ` +
                     'omit the property to offer every discovered peer.');
             }
+            if (block.vendors && block.vendors.length === 0) {
+                errors.push(`${at}: ${label(block)} has an empty \`vendors\` filter, which matches no peer — ` +
+                    'omit the property to offer peers of every vendor.');
+            }
         }
         if (!block.headline?.length && !step.title?.length) {
             warnings.push(`${at}: ${label(block)} has no headline and sits on a step with no title — ` +

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

@@ -221,6 +221,42 @@ class IntegrationEnergyApp extends energy_app_js_1.EnergyApp {
         };
         this.useDataBus().sendMessage([msg]);
     }
+    /**
+     * Publishes a `HeatpumpOperationForecastV1` — this heat pump's own forecast
+     * of when it will run, slot by slot.
+     *
+     * A prediction, not a request for power: to offer power the heat pump could
+     * absorb, use {@link publishFlexibilityAnnouncement}. Publish again whenever
+     * the forecast changes; each message replaces the previous one for the
+     * appliance.
+     *
+     * @param applianceId - The heat pump appliance the forecast is for.
+     * @param forecast - The slot length and the slots. See
+     *   {@link EnyoDataBusHeatpumpOperationForecastV1.data}.
+     *
+     * @example
+     * ```typescript
+     * this.publishHeatpumpOperationForecast('heatpump-1', {
+     *     resolution: ForecastResolutionEnum.OneHour,
+     *     entries: [
+     *         {timestampIso: '2026-10-06T06:00:00Z', outdoorTemperatureC: 4.5, running: true, averagePowerW: 1600},
+     *         {timestampIso: '2026-10-06T07:00:00Z', outdoorTemperatureC: 5.0, running: false},
+     *     ],
+     * });
+     * ```
+     */
+    publishHeatpumpOperationForecast(applianceId, forecast) {
+        const msg = {
+            id: this.generateMessageId(),
+            type: 'message',
+            message: enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.HeatpumpOperationForecastV1,
+            source: this.source,
+            applianceId,
+            timestampIso: new Date().toISOString(),
+            data: forecast
+        };
+        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 { EnyoDataBusApplianceFlexibilityAnnouncementV2, EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusMessage, EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.cjs";
+import { EnyoDataBusApplianceFlexibilityAnnouncementV2, EnyoDataBusGridOperatorPowerLimitationExecutedV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusHeatpumpOperationForecastV1, 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";
@@ -166,6 +166,31 @@ export declare abstract class IntegrationEnergyApp extends EnergyApp {
      * ```
      */
     publishFlexibilityAnnouncement(applianceId: string, flexibility: EnyoDataBusApplianceFlexibilityAnnouncementV2['data']['flexibility']): void;
+    /**
+     * Publishes a `HeatpumpOperationForecastV1` — this heat pump's own forecast
+     * of when it will run, slot by slot.
+     *
+     * A prediction, not a request for power: to offer power the heat pump could
+     * absorb, use {@link publishFlexibilityAnnouncement}. Publish again whenever
+     * the forecast changes; each message replaces the previous one for the
+     * appliance.
+     *
+     * @param applianceId - The heat pump appliance the forecast is for.
+     * @param forecast - The slot length and the slots. See
+     *   {@link EnyoDataBusHeatpumpOperationForecastV1.data}.
+     *
+     * @example
+     * ```typescript
+     * this.publishHeatpumpOperationForecast('heatpump-1', {
+     *     resolution: ForecastResolutionEnum.OneHour,
+     *     entries: [
+     *         {timestampIso: '2026-10-06T06:00:00Z', outdoorTemperatureC: 4.5, running: true, averagePowerW: 1600},
+     *         {timestampIso: '2026-10-06T07:00:00Z', outdoorTemperatureC: 5.0, running: false},
+     *     ],
+     * });
+     * ```
+     */
+    publishHeatpumpOperationForecast(applianceId: string, forecast: EnyoDataBusHeatpumpOperationForecastV1['data']): void;
     /**
      * Resolves the list of appliance IDs this integration is responsible for.
      *

package/dist/cjs/packages/energy-app-grid-connection-point.d.cts

@@ -4,7 +4,8 @@ import { EnyoGridConnectionPoint } from "../types/enyo-grid-connection-point.cjs
  *
  * The grid connection point describes the physical interface between the
  * local electrical installation and the public grid, including the main
- * fuse rating, the number of phases, and the maximum allowed grid power.
+ * fuse rating, the number of phases, the maximum allowed grid power, and the
+ * total power that load balancing may allocate to EV chargers.
  * Energy apps consume this information to size grid-import/export budgets,
  * enforce per-phase current limits, and respect contractual or regulatory
  * power caps.
@@ -21,12 +22,16 @@ export interface EnergyAppGridConnectionPoint {
      *
      * @example
      * ```typescript
+     * import {DEFAULT_CHARGER_LIMIT_W} from "@enyo-energy/energy-app-sdk";
+     *
      * const gridConnectionPoint = energyApp.useGridConnectionPoint();
      * const details = await gridConnectionPoint.getGridConnectionPoint();
      * if (details) {
      *     console.log(`Fuse: ${details.fuseAmpere} A`);
      *     console.log(`Phases: ${details.numberOfPhases}`);
      *     console.log(`Power limit: ${details.powerLimitW} W`);
+     *     const chargerLimitW = details.chargerLimitW ?? DEFAULT_CHARGER_LIMIT_W;
+     *     console.log(`Charger limit: ${chargerLimitW} W`);
      * }
      * ```
      */

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

@@ -69,4 +69,10 @@ var EnyoChargerApplianceAvailableFeaturesEnum;
     EnyoChargerApplianceAvailableFeaturesEnum["PvSurplusMode"] = "PvSurplusMode";
     /** If the charger supports switching between three-phase and one-phase charging */
     EnyoChargerApplianceAvailableFeaturesEnum["ThreeToOnePhaseSwitch"] = "ThreeToOnePhaseSwitch";
+    /**
+     * If the charger requires the vehicle to be disconnected before a new charge can be started.
+     * Once the charger is in {@link EnyoChargerApplianceStatusEnum.Finishing}, no new charge can be
+     * started remotely; the customer has to unplug the vehicle and plug it in again.
+     */
+    EnyoChargerApplianceAvailableFeaturesEnum["DisconnectToRestartCharge"] = "DisconnectToRestartCharge";
 })(EnyoChargerApplianceAvailableFeaturesEnum || (exports.EnyoChargerApplianceAvailableFeaturesEnum = EnyoChargerApplianceAvailableFeaturesEnum = {}));

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

@@ -82,7 +82,13 @@ export declare enum EnyoChargerApplianceAvailableFeaturesEnum {
     /** If the Charger supprots a pv surplus mode */
     PvSurplusMode = "PvSurplusMode",
     /** If the charger supports switching between three-phase and one-phase charging */
-    ThreeToOnePhaseSwitch = "ThreeToOnePhaseSwitch"
+    ThreeToOnePhaseSwitch = "ThreeToOnePhaseSwitch",
+    /**
+     * If the charger requires the vehicle to be disconnected before a new charge can be started.
+     * Once the charger is in {@link EnyoChargerApplianceStatusEnum.Finishing}, no new charge can be
+     * started remotely; the customer has to unplug the vehicle and plug it in again.
+     */
+    DisconnectToRestartCharge = "DisconnectToRestartCharge"
 }
 /**
  * Phase configurations a charger can operate in.

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoPriceLimitModeEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
+exports.EnyoPowerSourceEnum = exports.EnyoHeatpumpHeatSourceEnum = exports.EnyoHeatpumpControlPurposeEnum = exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageControlDirectionEnum = exports.EnyoStorageControlModeEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoChargingLimitRequestResultEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoPriceLimitModeEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoHeatingRodStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoGridOperatorLimitTypeEnum = exports.EnyoSwitchingProtectionHoldEnum = exports.EnyoBatteryToEvHoldTriggerEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -71,7 +71,16 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
     /** Command issued because the user explicitly requested it */
     EnyoDataBusCommandReasonTypeEnum["UserRequest"] = "user-request";
-    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    /**
+     * Command issued to protect the device (e.g. overheating or safety limit).
+     *
+     * When the protection is a minimum on/off time — an appliance kept running
+     * (or kept off) to avoid short-cycling its compressor — set
+     * {@link EnyoDataBusCommandReasonContext.switching} so the text can say how
+     * long the hold lasts instead of a generic "protecting the device". A hold
+     * that keeps an appliance OFF after a stop has its own type,
+     * {@link RestartDelay}.
+     */
     EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
     /** Command issued because home consumption is high */
     EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
@@ -173,6 +182,53 @@ var EnyoDataBusCommandReasonTypeEnum;
      * other constraint were lifted, the appliance would still stay off.
      */
     EnyoDataBusCommandReasonTypeEnum["OutsideSchedule"] = "outside-schedule";
+    /**
+     * The house battery is held (`Discharge 0`) so that stored energy does not
+     * flow into a charging car.
+     *
+     * Stated by the decision maker that judged the owner's
+     * `batteryEvDischargeMode`, never inferred by the battery's own command
+     * path. Says WHY through {@link EnyoDataBusCommandReasonContext.batteryToEv}
+     * — the owner blocked it, the SoC limit is reached, the watt-hour allowance
+     * is spent, or the battery's power cannot be measured. Set
+     * {@link EnyoDataBusCommandReason.socPercent} to the pack's current SoC.
+     *
+     * Told apart from {@link BatterySoCLow}: the pack is not low, it is at the
+     * floor the owner chose for the car. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["BatteryReservedFromEv"] = "battery-reserved-from-ev";
+    /**
+     * While a car charges, the house battery is left to self-manage
+     * (`mode=Auto`) and may cover part of the car's draw — within what the
+     * owner allowed.
+     *
+     * The counterpart of {@link BatteryReservedFromEv}. Set
+     * {@link EnyoDataBusCommandReasonContext.batteryToEv} so the text can say
+     * how far: down to an SoC limit, or how many watt-hours of the allowance
+     * are left. A short re-check of an existing hold sets `batteryToEv.probe` —
+     * consumers SHOULD NOT show a probe as a separate history entry. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.BatteryState}.
+     */
+    EnyoDataBusCommandReasonTypeEnum["BatterySupportsEvCharging"] = "battery-supports-ev-charging";
+    /**
+     * The appliance was switched off a moment ago and is held off for its
+     * declared minimum off-time, so it is not cycled on and off. Stated by the
+     * energy manager's switching protection.
+     *
+     * Set {@link EnyoDataBusCommandReasonContext.switching} with
+     * {@link EnyoSwitchingProtectionHoldEnum.KeptOff}, `minOffSeconds` and
+     * `untilIso` — when it may restart, i.e. the last stop plus the minimum
+     * off-time — and {@link EnyoDataBusCommandReason.powerW} to the power that
+     * is waiting for it, so the text can say why it will start.
+     *
+     * The specific form of {@link DeviceProtection} for a hold after a stop;
+     * a hold that keeps an appliance RUNNING stays `DeviceProtection` with
+     * {@link EnyoSwitchingProtectionHoldEnum.KeptOn}. Category
+     * {@link EnyoDataBusCommandReasonCategoryEnum.DeviceProtection} — it protects
+     * the appliance from short-cycling and is not about price, sun or contention.
+     */
+    EnyoDataBusCommandReasonTypeEnum["RestartDelay"] = "restart-delay";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
 /**
  * Coarse, machine-readable grouping of why a data bus command was issued.
@@ -215,6 +271,54 @@ var EnyoDataBusCommandReasonCategoryEnum;
     /** Any reason not covered by the categories above. */
     EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
 })(EnyoDataBusCommandReasonCategoryEnum || (exports.EnyoDataBusCommandReasonCategoryEnum = EnyoDataBusCommandReasonCategoryEnum = {}));
+/**
+ * Which part of the owner's battery-to-EV setting
+ * (`batteryEvDischargeMode`) caused a
+ * {@link EnyoDataBusCommandReasonTypeEnum.BatteryReservedFromEv} hold.
+ */
+var EnyoBatteryToEvHoldTriggerEnum;
+(function (EnyoBatteryToEvHoldTriggerEnum) {
+    /**
+     * {@link EnergyManagerBatteryEvDischargeModeEnum.BlockDischarge}: the owner
+     * never lets the battery charge the car.
+     */
+    EnyoBatteryToEvHoldTriggerEnum["OwnerBlocked"] = "owner-blocked";
+    /**
+     * {@link EnergyManagerBatteryEvDischargeModeEnum.SocLimit}: the pack has
+     * reached the owner's floor
+     * ({@link EnyoDataBusCommandReasonBatteryToEvContext.socLimitPercent}).
+     */
+    EnyoBatteryToEvHoldTriggerEnum["SocLimitReached"] = "soc-limit-reached";
+    /**
+     * {@link EnergyManagerBatteryEvDischargeModeEnum.FixedWh}: this session's
+     * allowance ({@link EnyoDataBusCommandReasonBatteryToEvContext.allowanceWh})
+     * has gone into the car.
+     */
+    EnyoBatteryToEvHoldTriggerEnum["AllowanceSpent"] = "allowance-spent";
+    /**
+     * The pack's live power cannot be read, so it cannot be shown NOT to feed
+     * the car. A fail-safe, stated out loud so that a site whose battery app
+     * publishes no power is diagnosable.
+     */
+    EnyoBatteryToEvHoldTriggerEnum["NoMeasurement"] = "no-measurement";
+})(EnyoBatteryToEvHoldTriggerEnum || (exports.EnyoBatteryToEvHoldTriggerEnum = EnyoBatteryToEvHoldTriggerEnum = {}));
+/**
+ * Which way a short-cycling protection holds an appliance.
+ */
+var EnyoSwitchingProtectionHoldEnum;
+(function (EnyoSwitchingProtectionHoldEnum) {
+    /**
+     * Kept running although the plan would stop it, because it has not yet run
+     * its minimum on-time — it may be drawing grid power meanwhile.
+     */
+    EnyoSwitchingProtectionHoldEnum["KeptOn"] = "kept-on";
+    /**
+     * Kept off although the plan would start it, because it has not yet rested
+     * its minimum off-time (e.g. the compressor gap between two starts). Goes
+     * with {@link EnyoDataBusCommandReasonTypeEnum.RestartDelay}.
+     */
+    EnyoSwitchingProtectionHoldEnum["KeptOff"] = "kept-off";
+})(EnyoSwitchingProtectionHoldEnum || (exports.EnyoSwitchingProtectionHoldEnum = EnyoSwitchingProtectionHoldEnum = {}));
 /**
  * Whether a grid operator power limitation caps power drawn from the grid
  * (consumption) or power fed into the grid (production).
@@ -429,6 +533,8 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["ApplianceFlexibilityAnnouncementV2"] = "ApplianceFlexibilityAnnouncementV2";
     EnyoDataBusMessageEnum["ApplianceStateUpdateV1"] = "ApplianceStateUpdateV1";
     EnyoDataBusMessageEnum["HeatpumpValuesUpdateV1"] = "HeatpumpValuesUpdateV1";
+    /** A heat pump integration's forecast of when its heat pump will run, slot by slot. */
+    EnyoDataBusMessageEnum["HeatpumpOperationForecastV1"] = "HeatpumpOperationForecastV1";
     EnyoDataBusMessageEnum["HeatingRodValuesUpdateV1"] = "HeatingRodValuesUpdateV1";
     EnyoDataBusMessageEnum["ChargingStartedV1"] = "ChargingStartedV1";
     EnyoDataBusMessageEnum["ChargingMeterValuesUpdateV1"] = "ChargingMeterValuesUpdateV1";