@enyo-energy/energy-app-sdk 1.12.0 → 1.14.0

package/README.md

@@ -85,6 +85,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [Device Integration](#device-integration)
   - [Data Bus Messaging](#data-bus-messaging)
     - [Announcing Appliance Flexibility](#announcing-appliance-flexibility)
+    - [Explaining Why a Command Was Issued](#explaining-why-a-command-was-issued)
   - [Settings Management](#settings-management)
 - [Troubleshooting](#troubleshooting)
 - [External Libraries](#external-libraries)
@@ -1680,9 +1681,27 @@ await energyApp.useOnboardingV2().registerAdditionalSetupHandler(async (request)
 
 Every such block must declare a `failed` outcome — it absorbs a rejection, a timeout, a missing handler, and an outcome value matching no branch (guide and handler are linked only by strings). Secrets are never logged, never prefilled, and not kept in run state. See [ONBOARDING.md](./ONBOARDING.md#app-defined-setups-additional-setup).
 
+Guides pick the device on a screen of their own. `device-select` lists the network devices the run found; `eebus-device-select` lists the discovered EEBUS peers, filtered by the SHIP device type they announce (`EnyoEebusDeviceTypeEnum`). Both carry their own `headline`/`description`, and both **skip the screen entirely** when exactly one candidate matches the filter — the handler still runs and the run is still bound, with `autoSelected: true` on the request. Register one handler per kind; a network device and an EEBUS peer are different things and neither handler is a fallback for the other:
+
+```typescript
+const onboarding = energyApp.useOnboardingV2();
+
+await onboarding.registerDeviceSelectHandler(async (request) => ({
+    requestId: request.requestId,
+    applianceIds: await adoptDevices(request.devices, request.applianceId),
+}));
+
+await onboarding.registerEebusDeviceSelectHandler(async (request) => ({
+    requestId: request.requestId,   // request.peer.ski identifies the paired device
+    applianceIds: await adoptEebusPeer(request.peer, request.applianceId),
+}));
+```
+
+On an `offline-reconnect` run the request carries the appliance that went offline — re-point it and answer with the same `applianceId` rather than creating a second one. See [ONBOARDING.md](./ONBOARDING.md#picking-the-device-device-select).
+
 Your answer wins over the host's own resolution, so a wrong value is worse than none — the installer pastes it into a charger and it fails minutes later as an `ocpp-connect` timeout. `validateOnboardingV2DynamicResult()` catches the copy-target mistakes (whitespace, a non-absolute URL, a plaintext scheme).
 
-Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
+Each guide declares the `startVariant` it applies to (`device-not-found`, `device-found-config`, `manual-setup`, `maintenance`, `offline-reconnect`). It must **not** declare `vendorId` or `modelIds`: enyo attaches those bindings when the guide is registered, an app-supplied value is overwritten, and `validateOnboardingGuideV2()` warns about it. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
 
 Not permission-gated.
 
@@ -2943,17 +2962,21 @@ An `EnyoAutomation` is `{ id, name, enabled, trigger, actions[] }`. The pieces:
 
 | Concept | Type | Values / fields |
 | --- | --- | --- |
-| **Trigger** | `EnyoAutomationTriggerTypeEnum` | `PvSurplusThreshold` → `{ thresholdW }` (activate above, deactivate below) |
-| **Action — smart plug** | `EnyoAutomationActionTypeEnum.SmartPlugSwitch` | `{ applianceId, minDurationMinutes }` — `minDurationMinutes` is `5…360` in steps of `5` |
+| **Trigger — PV surplus above** | `EnyoAutomationTriggerTypeEnum.PvSurplusThreshold` | `{ thresholdW }` (activate above, deactivate below) |
+| **Trigger — PV surplus below** | `EnyoAutomationTriggerTypeEnum.PvSurplusBelowThreshold` | `{ thresholdW }` — the inverse: active while surplus stays below, deactivates (turns the target **off**) as soon as `surplusW >= thresholdW` |
+| **Trigger — below price limit** | `EnyoAutomationTriggerTypeEnum.BelowPriceLimit` | `{ limitPerKwh, currency? }` — active while the current **full gross** price per kWh (incl. taxes, grid fees and all other components) is strictly below the limit; negative limits are allowed |
+| **Trigger — cheapest share of day** | `EnyoAutomationTriggerTypeEnum.CheapestShareOfDay` | `{ sharePercent }` — active during the cheapest `sharePercent` % of the day's price intervals (e.g. `25` for the cheapest 25 %); integer `1…100` |
+| **Trigger — schedule ("Zeitplan")** | `EnyoAutomationTriggerTypeEnum.Schedule` | `{ windows[], timezone? }` — each window is `{ startTimeOfDay, endTimeOfDay, daysOfWeek? }` in local `HH:mm` (`0` = Sunday … `6` = Saturday, omit for every day); windows may wrap past midnight and may overlap — the trigger is active while **any** window covers the current time |
+| **Action — smart plug** | `EnyoAutomationActionTypeEnum.SmartPlugSwitch` | `{ applianceId, minDurationMinutes }` — `minDurationMinutes` is `1…360`: whole minutes up to `5` (so a **1-minute** runtime is supported), multiples of `5` above that |
 | **Action — MQTT** | `EnyoAutomationActionTypeEnum.Mqtt` | `{ topic, payloadTemplate, updateChargingPvSurplus, publishOptions? }` |
 | **Scheduling** | `EnyoAutomationSchedulingModeEnum` | `Mandatory` (run exactly while active) or `Flexible` (Energy Manager may choose whether/when within the active window) |
 | **Target kind** | `EnyoAutomationTargetKindEnum` | `Load` (consumes power — counts in the energy balance) or `Signal` (control signal only) |
 
-The **MQTT** `payloadTemplate` is JSON that may embed the placeholders in `EnyoAutomationMqttPlaceholderEnum` — `{{state}}` (`on`/`off`), `{{surplusW}}`, `{{timestampIso}}`, `{{automationId}}` — which the platform substitutes before publishing.
+The **MQTT** `payloadTemplate` is JSON that may embed the placeholders in `EnyoAutomationMqttPlaceholderEnum` — `{{state}}` (`on`/`off`), `{{surplusW}}`, `{{pricePerKwh}}`, `{{timestampIso}}`, `{{automationId}}` — which the platform substitutes before publishing.
 
 Two things travel over the **data bus** vs. the **API**:
 
-- **Trigger state** is the data-bus message `AutomationTriggerV1` (`EnyoDataBusAutomationTriggerV1`): `{ automationId, data: { active, trigger } }`, where `trigger` is the per-type `EnyoAutomationTriggerData` (for PV surplus: `{ triggerType, surplusW, thresholdW }`).
+- **Trigger state** is the data-bus message `AutomationTriggerV1` (`EnyoDataBusAutomationTriggerV1`): `{ automationId, data: { active, trigger } }`, where `trigger` is the per-type `EnyoAutomationTriggerData` (PV surplus: `{ triggerType, surplusW, thresholdW }`; below-price-limit: `{ triggerType, pricePerKwh, limitPerKwh, currency }`; cheapest-share-of-day: `{ triggerType, pricePerKwh, sharePercent, thresholdPricePerKwh, currency }`; schedule: `{ triggerType, windowIndex?, windowStartIso?, windowEndIso? }`).
 - The **forecast** is a method — `publishAutomationForecast()` — not a data-bus message.
 
 ### ⚡ Guide: Energy Manager apps
@@ -3603,6 +3626,112 @@ Notes:
   grant can be read against the announcement it answers. It is advisory — the
   command's `powerW` remains the only limit.
 
+#### Explaining Why a Command Was Issued
+
+Every data bus command can carry an `EnyoDataBusCommandReason`. Its `type`
+(`EnyoDataBusCommandReasonTypeEnum`) and `category` are **closed, coarse
+vocabularies** — they exist for filtering, iconography and analytics, not for
+narrating a decision. There is no "thermal cost" or "efficiency" member, and you
+must not synthesize one: pick the honest type and attach the numbers.
+
+The prose for the end user lives in `translation` (per language). The numbers
+behind that prose live in the optional `context`
+(`EnyoDataBusCommandReasonContext`), so a consumer can verify, re-render or audit
+the explanation instead of taking it on trust:
+
+| Section | Answers | Key fields |
+| --- | --- | --- |
+| `proactive` | Did we act on a forecast rather than a measurement? | `boolean` |
+| `forecast` | What did we see coming? | `outdoorTemperatureC`, `thresholdTemperatureC`, `windowStartIso`/`windowEndIso`, `triggerTimestampIso` |
+| `placement` | When does the block run, and by when must it be done? | `startIso`, `endIso`, `durationMinutes`, `deadlineIso` |
+| `efficiency` | Why this slot and not the cheaper-looking one? | `coefficientOfPerformance`, `effectiveCostPerKwhThermal`, `compared*` |
+| `thermalStorage` | What ends the block? | `target`, `energyPerKelvinKwh`, `overheatKelvin`, `plannedEnergyKwh`, `absorbableEnergyKwh` |
+
+Worked example — a buffer tank charged ahead of a cold front. The command is
+`ScheduledOptimization` (category `Schedule`), which is the honest type for a
+block an optimizer placed in advance:
+
+```typescript
+import {
+    EnyoCurrencyEnum,
+    EnyoDataBusCommandReason,
+    EnyoDataBusCommandReasonCategoryEnum,
+    EnyoDataBusCommandReasonTypeEnum,
+    EnyoFlexibilityTargetEnum,
+} from '@enyo-energy/energy-app-sdk';
+
+const reason: EnyoDataBusCommandReason = {
+    type: EnyoDataBusCommandReasonTypeEnum.ScheduledOptimization,
+    category: EnyoDataBusCommandReasonCategoryEnum.Schedule,
+    translation: [
+        {
+            language: 'en',
+            value:
+                'Banking 2 hours of cheap heat into the buffer tank before tonight\'s cold front, ' +
+                'so the compressor can coast through the expensive hours.',
+        },
+    ],
+    // Per kWh of *electricity* — the raw price of the chosen slot.
+    electricityPricePerKwh: 0.30,
+    currency: EnyoCurrencyEnum.EUR,
+    context: {
+        // We watch the weather, not the tank.
+        proactive: true,
+        forecast: {
+            outdoorTemperatureC: 6.5,
+            thresholdTemperatureC: 10,
+            windowStartIso: '2026-01-14T12:00:00Z',
+            windowEndIso: '2026-01-15T12:00:00Z',
+            triggerTimestampIso: '2026-01-14T21:00:00Z',
+        },
+        // A 120-minute block, finished before that cold front arrives.
+        placement: {
+            startIso: '2026-01-14T12:00:00Z',
+            endIso: '2026-01-14T14:00:00Z',
+            durationMinutes: 120,
+            deadlineIso: '2026-01-14T21:00:00Z',
+        },
+        // Placed by price ÷ COP, not price alone: a warm midday hour at 30 ct
+        // delivers cheaper heat than a cold night hour at 20 ct.
+        efficiency: {
+            coefficientOfPerformance: 4.2,
+            effectiveCostPerKwhThermal: 0.0714,
+            comparedElectricityPricePerKwh: 0.20,
+            comparedCoefficientOfPerformance: 2.4,
+            comparedEffectiveCostPerKwhThermal: 0.0833,
+            comparedStartIso: '2026-01-14T02:00:00Z',
+        },
+        // And it stops once the store is physically full: the pump tells us one
+        // Kelvin of overheat absorbs 1.2 kWh, so 5 K of headroom is 6.1 kWh.
+        thermalStorage: {
+            target: EnyoFlexibilityTargetEnum.BufferTank,
+            energyPerKelvinKwh: 1.2,
+            overheatKelvin: 5,
+            plannedEnergyKwh: 6.0,
+            absorbableEnergyKwh: 6.1,
+        },
+    },
+};
+```
+
+Notes:
+
+- **`context` is entirely optional and additive.** A reason that sets none of it
+  behaves exactly as before; consumers must tolerate every section being absent.
+- **Costs are not all per kWh of electricity.** `electricityPricePerKwh` is per
+  kWh drawn; `effectiveCostPerKwhThermal` is per kWh *delivered*, in the same
+  `currency`. Mixing the two is what makes an efficiency-placed command look like
+  a mistake.
+- **One rejected alternative, not a solver dump.** The `compared*` fields describe
+  the single best slot that lost, because that is what explains the choice to a
+  person.
+- **Nothing in a reason controls anything.** It explains a command; the command's
+  own fields stay authoritative.
+- **`thermalStorage.target` reuses `EnyoFlexibilityTargetEnum`**, the same
+  vocabulary as flexibility announcements and the `targets` breakdown on
+  available-power commands — so a grant and its justification name the same
+  physical sink without a mapping table.
+
 ### Settings Management
 
 Dynamic configuration with user interface:

package/dist/cjs/implementations/automation/automation-validators.cjs

@@ -1,13 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTOMATION_DURATION_STEP_MINUTES = exports.AUTOMATION_MAX_DURATION_MINUTES = exports.AUTOMATION_MIN_DURATION_MINUTES = exports.AutomationValidationError = void 0;
+exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT = exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT = exports.AUTOMATION_DURATION_STEP_MINUTES = exports.AUTOMATION_MAX_DURATION_MINUTES = exports.AUTOMATION_MIN_DURATION_MINUTES = exports.AutomationValidationError = void 0;
 exports.validateAutomation = validateAutomation;
 exports.validateTrigger = validateTrigger;
 exports.validateAction = validateAction;
 exports.validateAutomationForecast = validateAutomationForecast;
 exports.validateAutomationTriggerData = validateAutomationTriggerData;
 const enyo_automation_js_1 = require("../../types/enyo-automation.cjs");
+const enyo_currency_js_1 = require("../../types/enyo-currency.cjs");
 const enyo_mqtt_js_1 = require("../../types/enyo-mqtt.cjs");
+const price_schedule_resolver_js_1 = require("../pricing/price-schedule-resolver.cjs");
 /**
  * Thrown when an automation, action or automation forecast violates one of the
  * invariants enforced by this module. The message names the offending field /
@@ -20,12 +22,24 @@ class AutomationValidationError extends Error {
     }
 }
 exports.AutomationValidationError = AutomationValidationError;
-/** Minimum smart-plug on-duration, in minutes. */
-exports.AUTOMATION_MIN_DURATION_MINUTES = 5;
+/**
+ * Minimum smart-plug on-duration, in minutes. Short runtimes below
+ * {@link AUTOMATION_DURATION_STEP_MINUTES} are allowed at a one-minute
+ * granularity, so a one-minute runtime is valid.
+ */
+exports.AUTOMATION_MIN_DURATION_MINUTES = 1;
 /** Maximum smart-plug on-duration, in minutes (6 hours). */
 exports.AUTOMATION_MAX_DURATION_MINUTES = 360;
-/** Step size the smart-plug on-duration must be a multiple of, in minutes. */
+/**
+ * Step size the smart-plug on-duration must be a multiple of, in minutes, once
+ * it exceeds {@link AUTOMATION_DURATION_STEP_MINUTES}. Durations at or below
+ * this value are free to use any whole minute (1, 2, 3, 4, 5).
+ */
 exports.AUTOMATION_DURATION_STEP_MINUTES = 5;
+/** Minimum share of the day, in percent, a cheapest-share trigger may select. */
+exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT = 1;
+/** Maximum share of the day, in percent, a cheapest-share trigger may select. */
+exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT = 100;
 /** Duration in seconds of each {@link EnyoForecastResolution} value. */
 const FORECAST_RESOLUTION_SECONDS = {
     '10s': 10,
@@ -87,6 +101,31 @@ function validateTrigger(trigger) {
                 throw new AutomationValidationError('PvSurplusThreshold trigger.thresholdW must be a finite number >= 0.');
             }
             break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.PvSurplusBelowThreshold:
+            if (typeof trigger.thresholdW !== 'number' || !Number.isFinite(trigger.thresholdW) || trigger.thresholdW < 0) {
+                throw new AutomationValidationError('PvSurplusBelowThreshold trigger.thresholdW must be a finite number >= 0.');
+            }
+            break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.BelowPriceLimit:
+            // Negative limits are valid: dynamic prices can turn negative.
+            if (typeof trigger.limitPerKwh !== 'number' || !Number.isFinite(trigger.limitPerKwh)) {
+                throw new AutomationValidationError('BelowPriceLimit trigger.limitPerKwh must be a finite number.');
+            }
+            if (trigger.currency !== undefined) {
+                requireEnumMember(trigger.currency, enyo_currency_js_1.EnyoCurrencyEnum, 'BelowPriceLimit trigger.currency');
+            }
+            break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.CheapestShareOfDay:
+            if (typeof trigger.sharePercent !== 'number' ||
+                !Number.isInteger(trigger.sharePercent) ||
+                trigger.sharePercent < exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT ||
+                trigger.sharePercent > exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT) {
+                throw new AutomationValidationError(`CheapestShareOfDay trigger.sharePercent must be an integer between ${exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT} and ${exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT}.`);
+            }
+            break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.Schedule:
+            validateScheduleTrigger(trigger);
+            break;
         default:
             throw new AutomationValidationError(`Automation.trigger.type is invalid: ${trigger.type}.`);
     }
@@ -173,13 +212,90 @@ function validateAutomationTriggerData(trigger) {
     }
     switch (trigger.triggerType) {
         case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.PvSurplusThreshold:
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.PvSurplusBelowThreshold:
             requireFiniteNonNegative(trigger.surplusW, 'AutomationTriggerData.surplusW');
             requireFiniteNonNegative(trigger.thresholdW, 'AutomationTriggerData.thresholdW');
             break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.BelowPriceLimit:
+            requireFinite(trigger.pricePerKwh, 'AutomationTriggerData.pricePerKwh');
+            requireFinite(trigger.limitPerKwh, 'AutomationTriggerData.limitPerKwh');
+            requireEnumMember(trigger.currency, enyo_currency_js_1.EnyoCurrencyEnum, 'AutomationTriggerData.currency');
+            break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.CheapestShareOfDay:
+            requireFinite(trigger.pricePerKwh, 'AutomationTriggerData.pricePerKwh');
+            requireFinite(trigger.thresholdPricePerKwh, 'AutomationTriggerData.thresholdPricePerKwh');
+            if (typeof trigger.sharePercent !== 'number' ||
+                !Number.isInteger(trigger.sharePercent) ||
+                trigger.sharePercent < exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT ||
+                trigger.sharePercent > exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT) {
+                throw new AutomationValidationError(`AutomationTriggerData.sharePercent must be an integer between ${exports.AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT} and ${exports.AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT}.`);
+            }
+            requireEnumMember(trigger.currency, enyo_currency_js_1.EnyoCurrencyEnum, 'AutomationTriggerData.currency');
+            break;
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.Schedule:
+            if (trigger.windowIndex !== undefined && (!Number.isInteger(trigger.windowIndex) || trigger.windowIndex < 0)) {
+                throw new AutomationValidationError('AutomationTriggerData.windowIndex must be an integer >= 0.');
+            }
+            requireOptionalIsoTimestamp(trigger.windowStartIso, 'AutomationTriggerData.windowStartIso');
+            requireOptionalIsoTimestamp(trigger.windowEndIso, 'AutomationTriggerData.windowEndIso');
+            break;
         default:
             throw new AutomationValidationError(`AutomationTriggerData.triggerType is invalid: ${trigger.triggerType}.`);
     }
 }
+/**
+ * Validates the windows of a {@link EnyoAutomationTriggerTypeEnum.Schedule}
+ * ("Zeitplan") trigger: at least one window, well-formed `HH:mm` times that do
+ * not start and end at the same minute, weekday numbers in range, and a valid
+ * IANA timezone when given. Windows are a union and may overlap, so no overlap
+ * check is performed.
+ */
+function validateScheduleTrigger(trigger) {
+    if (!Array.isArray(trigger.windows) || trigger.windows.length === 0) {
+        throw new AutomationValidationError('Schedule trigger.windows must contain at least one window.');
+    }
+    trigger.windows.forEach((window, index) => {
+        const label = `Schedule trigger.windows[${index}]`;
+        if (!window || typeof window !== 'object') {
+            throw new AutomationValidationError(`${label} must be an object.`);
+        }
+        const start = (0, price_schedule_resolver_js_1.parseTimeOfDay)(window.startTimeOfDay);
+        if (start === null) {
+            throw new AutomationValidationError(`${label}.startTimeOfDay must be a 24-hour 'HH:mm' time, got '${window.startTimeOfDay}'.`);
+        }
+        const end = (0, price_schedule_resolver_js_1.parseTimeOfDay)(window.endTimeOfDay);
+        if (end === null) {
+            throw new AutomationValidationError(`${label}.endTimeOfDay must be a 24-hour 'HH:mm' time, got '${window.endTimeOfDay}'.`);
+        }
+        if (start === end) {
+            throw new AutomationValidationError(`${label} must not start and end at the same time of day.`);
+        }
+        if (window.daysOfWeek !== undefined) {
+            if (!Array.isArray(window.daysOfWeek) || window.daysOfWeek.length === 0) {
+                throw new AutomationValidationError(`${label}.daysOfWeek must not be empty — omit it for 'every day'.`);
+            }
+            const seenDays = new Set();
+            for (const day of window.daysOfWeek) {
+                if (!Number.isInteger(day) || day < 0 || day > 6) {
+                    throw new AutomationValidationError(`${label}.daysOfWeek must contain integers 0 (Sunday) to 6 (Saturday), got ${day}.`);
+                }
+                if (seenDays.has(day)) {
+                    throw new AutomationValidationError(`${label}.daysOfWeek contains the duplicate day ${day}.`);
+                }
+                seenDays.add(day);
+            }
+        }
+    });
+    if (trigger.timezone !== undefined) {
+        requireNonEmptyString(trigger.timezone, 'Schedule trigger.timezone');
+        try {
+            new Intl.DateTimeFormat('en-US', { timeZone: trigger.timezone });
+        }
+        catch {
+            throw new AutomationValidationError(`Schedule trigger.timezone must be a valid IANA time zone identifier, got '${trigger.timezone}'.`);
+        }
+    }
+}
 function validateMqttAction(action, label) {
     requireNonEmptyString(action.topic, `${label}.topic`);
     if (typeof action.updateChargingPvSurplus !== 'boolean') {
@@ -203,12 +319,16 @@ function validateSmartPlugSwitchAction(action, label, knownSmartPlugApplianceIds
         throw new AutomationValidationError(`${label}.applianceId does not reference a smart-plug appliance that supports the smart-plug-switch action: ${action.applianceId}.`);
     }
     const { minDurationMinutes } = action;
-    if (typeof minDurationMinutes !== 'number' ||
-        !Number.isInteger(minDurationMinutes) ||
-        minDurationMinutes < exports.AUTOMATION_MIN_DURATION_MINUTES ||
-        minDurationMinutes > exports.AUTOMATION_MAX_DURATION_MINUTES ||
-        minDurationMinutes % exports.AUTOMATION_DURATION_STEP_MINUTES !== 0) {
-        throw new AutomationValidationError(`${label}.minDurationMinutes must be an integer between ${exports.AUTOMATION_MIN_DURATION_MINUTES} and ${exports.AUTOMATION_MAX_DURATION_MINUTES} in steps of ${exports.AUTOMATION_DURATION_STEP_MINUTES}.`);
+    // Short runtimes (1-5 minutes) are allowed at whole-minute granularity so a
+    // one-minute pulse can be configured; anything longer keeps the 5-minute step.
+    const isWholeMinutesInRange = typeof minDurationMinutes === 'number' &&
+        Number.isInteger(minDurationMinutes) &&
+        minDurationMinutes >= exports.AUTOMATION_MIN_DURATION_MINUTES &&
+        minDurationMinutes <= exports.AUTOMATION_MAX_DURATION_MINUTES;
+    const matchesStep = minDurationMinutes <= exports.AUTOMATION_DURATION_STEP_MINUTES ||
+        minDurationMinutes % exports.AUTOMATION_DURATION_STEP_MINUTES === 0;
+    if (!isWholeMinutesInRange || !matchesStep) {
+        throw new AutomationValidationError(`${label}.minDurationMinutes must be an integer between ${exports.AUTOMATION_MIN_DURATION_MINUTES} and ${exports.AUTOMATION_MAX_DURATION_MINUTES}; values above ${exports.AUTOMATION_DURATION_STEP_MINUTES} must be a multiple of ${exports.AUTOMATION_DURATION_STEP_MINUTES}.`);
     }
 }
 /**
@@ -233,6 +353,19 @@ function validatePayloadTemplate(template, label) {
         throw new AutomationValidationError(`${label} is not valid JSON once placeholders are substituted.`);
     }
 }
+function requireOptionalIsoTimestamp(value, label) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) {
+        throw new AutomationValidationError(`${label} must be a valid ISO 8601 timestamp: ${String(value)}.`);
+    }
+}
+function requireFinite(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new AutomationValidationError(`${label} must be a finite number.`);
+    }
+}
 function requireFiniteNonNegative(value, label) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
         throw new AutomationValidationError(`${label} must be a finite number >= 0.`);

package/dist/cjs/implementations/automation/automation-validators.d.cts

@@ -7,12 +7,24 @@ import { EnyoAutomation, EnyoAutomationAction, EnyoAutomationForecast, EnyoAutom
 export declare class AutomationValidationError extends Error {
     constructor(message: string);
 }
-/** Minimum smart-plug on-duration, in minutes. */
-export declare const AUTOMATION_MIN_DURATION_MINUTES = 5;
+/**
+ * Minimum smart-plug on-duration, in minutes. Short runtimes below
+ * {@link AUTOMATION_DURATION_STEP_MINUTES} are allowed at a one-minute
+ * granularity, so a one-minute runtime is valid.
+ */
+export declare const AUTOMATION_MIN_DURATION_MINUTES = 1;
 /** Maximum smart-plug on-duration, in minutes (6 hours). */
 export declare const AUTOMATION_MAX_DURATION_MINUTES = 360;
-/** Step size the smart-plug on-duration must be a multiple of, in minutes. */
+/**
+ * Step size the smart-plug on-duration must be a multiple of, in minutes, once
+ * it exceeds {@link AUTOMATION_DURATION_STEP_MINUTES}. Durations at or below
+ * this value are free to use any whole minute (1, 2, 3, 4, 5).
+ */
 export declare const AUTOMATION_DURATION_STEP_MINUTES = 5;
+/** Minimum share of the day, in percent, a cheapest-share trigger may select. */
+export declare const AUTOMATION_MIN_CHEAPEST_SHARE_PERCENT = 1;
+/** Maximum share of the day, in percent, a cheapest-share trigger may select. */
+export declare const AUTOMATION_MAX_CHEAPEST_SHARE_PERCENT = 100;
 /**
  * Validates a complete {@link EnyoAutomation}. Throws on the first violation.
  *

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

@@ -243,69 +243,111 @@ exports.onboardingV2Block = {
         outcomes,
     }),
     /**
-     * An EEBUS-pair action block: the installer picks one of the discovered
-     * EEBUS peers and the host trusts its SKI.
+     * A device-select picker: its own screen listing the network devices the run
+     * has found, so the installer can say which one is being onboarded.
      *
-     * A convenience wrapper over {@link onboardingV2Block.action} that pins the
-     * action kind. The picker is drawn from what mDNS discovery found, so the
-     * guide must have scanned — keep
-     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default or place
-     * a {@link EnyoOnboardingV2ActionKind.NetworkScan} block ahead of this one.
+     * Use it whenever a scan can turn up more than one candidate. A
+     * {@link onboardingV2Block.networkScan} branches on found/not-found but binds
+     * nothing, so without this the run does not know *which* device it is working
+     * on — and {@link EnyoOnboardingV2DeviceSelection.Current} and
+     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
+     * against.
      *
-     * Most EEBUS devices only announce themselves once pairing is enabled in
-     * their own menu or portal, and many ask for a confirmation there while the
-     * handshake runs, so put that instruction in a text/hint block on the
-     * preceding step — the app cannot do it for the installer.
+     * The block owns the step: give it one of its own, put the screen's wording
+     * in `headline`/`description` rather than in neighbouring blocks, and let it
+     * disappear when it has nothing to ask — with `autoSelectSingleMatch` left at
+     * its default, a single matching device is bound without rendering anything.
      *
-     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
-     * route `not-found` to troubleshooting and `failure` to a step describing
-     * the confirmation on the device. A retry must lead into a *second* pairing
-     * step: a back-edge onto the same step reads as a loop and ends the run.
+     * The list is what discovery found, so the guide must have scanned: keep
+     * {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or place a
+     * {@link onboardingV2Block.networkScan} ahead of this one.
+     *
+     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
+     * members; route `not-found` to troubleshooting rather than to a step that
+     * assumes a device exists.
+     *
+     * Register an {@link EnyoOnboardingV2DeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerDeviceSelectHandler}) to turn the pick
+     * into appliances — the host awaits it and binds the run to the ids it
+     * returns, whether or not the screen was shown. Without one the pick binds an
+     * address and nothing more.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `paired` / `not-found` / `failure` results; each is a routing handle.
+     * @param options - Screen wording, optional `detectedAt` filter, skip
+     *   behaviour, and the `selected` / `not-found` routing handles.
+     * @returns The device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.deviceSelect('pick', {
+     *     headline: t('Gerät auswählen', 'Select the device'),
+     *     description: t(
+     *         'Vergleichen Sie die Seriennummer auf dem Typenschild.',
+     *         'Compare the serial number on the type plate.',
+     *     ),
+     *     detectedAt: [EnyoNetworkDeviceDetectedAtEnum.Modbus],
+     *     outcomes: [
+     *         {id: 'ok',   value: EnyoOnboardingV2DeviceSelectOutcome.Selected, label: t('Ausgewählt', 'Selected')},
+     *         {id: 'none', value: EnyoOnboardingV2DeviceSelectOutcome.NotFound, label: t('Nicht dabei', 'Not listed')},
+     *     ],
+     * });
+     * ```
      */
-    eebusPair: (id, label, outcomes) => ({
+    deviceSelect: (id, options) => ({
         id,
-        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
-        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.EebusPair,
-        label,
-        outcomes,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.DeviceSelect,
+        ...options,
     }),
     /**
-     * A device-select block: the installer picks the device being onboarded from
-     * everything the run has found.
+     * An EEBUS device-select picker: its own screen listing the discovered EEBUS
+     * peers, so the installer can pick the one to trust — the host pairs it and
+     * records its SKI.
      *
-     * Use it whenever a scan can turn up more than one candidate. A
-     * {@link block.networkScan} branches on found/not-found but binds nothing,
-     * so without this the run does not know *which* device it is working on —
-     * and {@link EnyoOnboardingV2DeviceSelection.Current} and
-     * {@link EnyoOnboardingV2DynamicKind.DeviceIp} have nothing to resolve
-     * against.
+     * 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.
      *
-     * The picker renders what discovery found, so the guide must have scanned:
-     * keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its default, or
-     * place a {@link block.networkScan} ahead of this one.
+     * The picker is drawn from what mDNS discovery found, so the guide must have
+     * scanned — keep {@link EnyoOnboardingV2Guide.requiresNetworkScan} at its
+     * default or place a {@link onboardingV2Block.networkScan} ahead of this one.
      *
-     * Outcome `value`s must be {@link EnyoOnboardingV2DeviceSelectOutcome}
-     * members; route `not-found` to troubleshooting rather than to a step that
-     * assumes a device exists.
+     * Most EEBUS devices only announce themselves once pairing is enabled in
+     * their own menu or portal, and many ask for a confirmation there while the
+     * handshake runs, so put that instruction in a text/hint block on the
+     * preceding step — the app cannot do it for the installer.
      *
-     * Register an {@link EnyoOnboardingV2DeviceSelectHandler} to turn the pick
-     * into appliances — the host awaits it and binds the run to the ids it
-     * returns. Without one the pick binds an address and nothing more.
+     * Outcome `value`s must be {@link EnyoOnboardingV2EebusPairOutcome} members;
+     * route `not-found` to troubleshooting and `failure` to a step describing the
+     * confirmation on the device. A retry must lead into a *second* picker step:
+     * a back-edge onto the same step reads as a loop and ends the run.
+     *
+     * Register an {@link EnyoOnboardingV2EebusDeviceSelectHandler}
+     * ({@link EnergyAppOnboardingV2.registerEebusDeviceSelectHandler}) to turn the
+     * paired peer into appliances.
      *
      * @param id - Stable block id, unique within the guide.
-     * @param label - Translated trigger button text (de/en).
-     * @param outcomes - The `selected` / `not-found` results; each is a routing handle.
+     * @param options - Screen wording, optional `deviceTypes` filter, skip
+     *   behaviour, and the `paired` / `not-found` / `failure` routing handles.
+     * @returns The EEBUS device-select block.
+     *
+     * @example
+     * ```ts
+     * onboardingV2Block.eebusDeviceSelect('pair', {
+     *     headline: t('Wärmepumpe auswählen', 'Select the heat pump'),
+     *     deviceTypes: [EnyoEebusDeviceTypeEnum.HeatPumpAppliance],
+     *     outcomes: [
+     *         {id: 'ok',    value: EnyoOnboardingV2EebusPairOutcome.Paired,   label: t('Gekoppelt', 'Paired')},
+     *         {id: 'none',  value: EnyoOnboardingV2EebusPairOutcome.NotFound, label: t('Nichts gefunden', 'Nothing found')},
+     *         {id: 'error', value: EnyoOnboardingV2EebusPairOutcome.Failure,  label: t('Kopplung fehlgeschlagen', 'Pairing failed')},
+     *     ],
+     * });
+     * ```
      */
-    deviceSelect: (id, label, outcomes) => ({
+    eebusDeviceSelect: (id, options) => ({
         id,
-        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Action,
-        action: enyo_onboarding_v2_js_1.EnyoOnboardingV2ActionKind.DeviceSelect,
-        label,
-        outcomes,
+        type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.EebusDeviceSelect,
+        ...options,
     }),
     /**
      * An auth block: the installer signs into the energy app's own account
@@ -320,8 +362,12 @@ exports.onboardingV2Block = {
      * @param label - Translated sign-in button text (de/en).
      * @param outcome - The single success handle (`{id, label}`).
      * @param opts - Optional translated `help` naming the account that is needed,
-     *   and `requiresWebAuthentication` to force the login into a web browser
-     *   when the provider rejects a custom-scheme redirect such as `enyoapp://`.
+     *   and `redirectUrlFilter` to constrain the enyo callback URL the host
+     *   generates — `webOnly` when the provider rejects a custom-scheme redirect
+     *   such as `enyoapp://`, `pattern` when its OAuth app was registered with a
+     *   redirect URI that carries the request id as a path segment rather than a
+     *   query parameter. `requiresWebAuthentication` is the deprecated spelling
+     *   of `redirectUrlFilter.webOnly`.
      */
     auth: (id, label, outcome, opts) => ({
         id,
@@ -330,6 +376,7 @@ exports.onboardingV2Block = {
         outcome,
         help: opts?.help,
         requiresWebAuthentication: opts?.requiresWebAuthentication,
+        redirectUrlFilter: opts?.redirectUrlFilter,
     }),
     /**
      * A link block: a fixed URL the installer opens or copies.