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

package/README.md

@@ -2962,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

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

@@ -362,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,
@@ -372,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.

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

@@ -10,6 +10,7 @@
  * before publishing.
  */
 import type { EnyoOnboardingTranslatedContent } from '../../types/enyo-onboarding.cjs';
+import type { EnyoOauthRedirectUrlFilter } from '../../types/enyo-authentication.cjs';
 import { EnyoOnboardingV2ActionKind, EnyoOnboardingV2Credential, EnyoOnboardingV2SelectOption, EnyoOnboardingV2ChoiceLayout, EnyoOnboardingV2DeviceSelection, EnyoOnboardingV2PauseReason } from '../../types/enyo-onboarding-v2.cjs';
 import type { EnyoOnboardingV2ActionOutcome, EnyoOnboardingV2AuthOutcome, EnyoOnboardingV2SetupField, EnyoOnboardingV2SetupOutcome, EnyoOnboardingV2SetupSkipHandle, EnyoOnboardingV2Block, EnyoOnboardingV2ChoiceOption, EnyoOnboardingV2DeviceSelectBlock, EnyoOnboardingV2EebusDeviceSelectBlock, EnyoOnboardingV2DynamicKind, EnyoOnboardingV2Guide, EnyoOnboardingV2HintVariant, EnyoOnboardingV2InputOutcome, EnyoOnboardingV2InputValueType, EnyoOnboardingV2StartVariant, EnyoOnboardingV2Target, EnyoOnboardingV2Transition } from '../../types/enyo-onboarding-v2.cjs';
 /**
@@ -305,12 +306,18 @@ export declare const 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: string, label: EnyoOnboardingTranslatedContent[], outcome: EnyoOnboardingV2AuthOutcome, opts?: {
         help?: EnyoOnboardingTranslatedContent[];
+        /** @deprecated Use `redirectUrlFilter.webOnly`. */
         requiresWebAuthentication?: boolean;
+        redirectUrlFilter?: EnyoOauthRedirectUrlFilter;
     }) => EnyoOnboardingV2Block;
     /**
      * A link block: a fixed URL the installer opens or copies.

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

@@ -20,6 +20,7 @@ exports.validateOnboardingGuideV2 = validateOnboardingGuideV2;
 exports.assertValidOnboardingGuideV2 = assertValidOnboardingGuideV2;
 const enyo_onboarding_v2_js_1 = require("../../types/enyo-onboarding-v2.cjs");
 const enyo_device_test_js_1 = require("../../types/enyo-device-test.cjs");
+const enyo_authentication_js_1 = require("../../types/enyo-authentication.cjs");
 const enyo_onboarding_v2_additional_setup_js_1 = require("../../types/enyo-onboarding-v2-additional-setup.cjs");
 const public_file_validators_js_1 = require("../files/public-file-validators.cjs");
 const define_public_file_js_1 = require("../files/define-public-file.cjs");
@@ -581,6 +582,8 @@ function validateEebusPairOutcomes(block, at, errors, warnings) {
             'a successful pairing would have nowhere to go.');
     }
 }
+/** The redirect-URL patterns an auth block's `redirectUrlFilter` may name. */
+const REDIRECT_URL_PATTERNS = new Set(Object.values(enyo_authentication_js_1.EnyoOauthRedirectUrlPatternEnum));
 /**
  * Every block type that owns a decision — a picker shares a step with none of
  * them.
@@ -685,6 +688,27 @@ function validateAuthBlocks(step, at, errors, warnings) {
         if (!block.outcome?.label?.length) {
             warnings.push(`${at}: auth block "${block.id}" outcome has no label.`);
         }
+        const filter = block.redirectUrlFilter;
+        if (filter !== undefined) {
+            if (typeof filter !== 'object') {
+                errors.push(`${at}: auth block "${block.id}" redirectUrlFilter must be an object.`);
+            }
+            else {
+                if (filter.webOnly !== undefined && typeof filter.webOnly !== 'boolean') {
+                    errors.push(`${at}: auth block "${block.id}" redirectUrlFilter.webOnly must be a boolean.`);
+                }
+                if (filter.pattern !== undefined &&
+                    !REDIRECT_URL_PATTERNS.has(filter.pattern)) {
+                    errors.push(`${at}: auth block "${block.id}" redirectUrlFilter.pattern is invalid: ${filter.pattern}. ` +
+                        `Allowed values: ${[...REDIRECT_URL_PATTERNS].join(', ')}.`);
+                }
+                if (block.requiresWebAuthentication === true &&
+                    filter.webOnly === false) {
+                    warnings.push(`${at}: auth block "${block.id}" sets requiresWebAuthentication but redirectUrlFilter.webOnly is false — ` +
+                        'the filter wins; drop the deprecated flag.');
+                }
+            }
+        }
     }
     if (authBlocks.length > 1) {
         errors.push(`${at}: more than one auth block; a step can hold at most one login.`);

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

@@ -17,6 +17,14 @@ import { EnyoAutomation, EnyoAutomationForecast, EnyoAutomationTriggerTypeEnum }
  *   (via `useDataBus()`) whenever the configured threshold is crossed. Trigger
  *   state is a data-bus message, not a method on this package.
  *
+ * Supported triggers (see {@link EnyoAutomationTriggerTypeEnum}):
+ * `PvSurplusThreshold` (surplus above X W), `PvSurplusBelowThreshold` (turn the
+ * target off once the surplus reaches X W), `BelowPriceLimit` (price per kWh
+ * below a limit), `CheapestShareOfDay` (the cheapest N % of the day, e.g. 25 %)
+ * and `Schedule` (the "Zeitplan" trigger — one or more start/end time windows,
+ * each optionally restricted to certain weekdays). A provider registers each
+ * type it can evaluate independently.
+ *
  * @example
  * ```typescript
  * // A "pool pump on solar" automation the user created:
@@ -58,6 +66,42 @@ import { EnyoAutomation, EnyoAutomationForecast, EnyoAutomationTriggerTypeEnum }
  *         },
  *     },
  * }]);
+ *
+ * // A price-driven automation: run the pump during the cheapest 25 % of the day
+ * // for at least one minute per activation.
+ * const cheapHours: EnyoAutomation = {
+ *     id: 'pump-cheap-hours',
+ *     name: 'Pool pump in cheap hours',
+ *     enabled: true,
+ *     trigger: {type: EnyoAutomationTriggerTypeEnum.CheapestShareOfDay, sharePercent: 25},
+ *     actions: [
+ *         {
+ *             id: 'switch-pump',
+ *             type: EnyoAutomationActionTypeEnum.SmartPlugSwitch,
+ *             schedulingMode: EnyoAutomationSchedulingModeEnum.Flexible,
+ *             targetKind: EnyoAutomationTargetKindEnum.Load,
+ *             applianceId: 'shelly-pool-ch0',
+ *             minDurationMinutes: 1,
+ *         },
+ *     ],
+ * };
+ *
+ * // A "Zeitplan": weekday mornings and evenings, plus all day on Sunday.
+ * const schedule: EnyoAutomation['trigger'] = {
+ *     type: EnyoAutomationTriggerTypeEnum.Schedule,
+ *     windows: [
+ *         {startTimeOfDay: '06:00', endTimeOfDay: '08:00', daysOfWeek: [1, 2, 3, 4, 5]},
+ *         {startTimeOfDay: '18:00', endTimeOfDay: '22:00', daysOfWeek: [1, 2, 3, 4, 5]},
+ *         {startTimeOfDay: '00:00', endTimeOfDay: '23:59', daysOfWeek: [0]},
+ *     ],
+ *     timezone: 'Europe/Berlin',
+ * };
+ *
+ * // "Turn the heating rod off as soon as the PV surplus reaches 3 kW":
+ * const offOnSurplus: EnyoAutomation['trigger'] = {
+ *     type: EnyoAutomationTriggerTypeEnum.PvSurplusBelowThreshold,
+ *     thresholdW: 3000,
+ * };
  * ```
  */
 export interface EnergyAppAutomation {

package/dist/cjs/types/enyo-authentication.cjs

@@ -1,6 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoAuthenticationStateEnum = void 0;
+exports.EnyoAuthenticationStateEnum = exports.EnyoOauthRedirectUrlPatternEnum = void 0;
+/**
+ * How the host encodes the pending request into the enyo callback URL it hands
+ * out as {@link EnyoOauthAuthenticationStart.enyoRedirectUrl}.
+ *
+ * OAuth providers differ in what they accept as a registered `redirect_uri`:
+ * some match the URL exactly and reject anything carrying a query string,
+ * others match only the path prefix. Declaring the shape the provider's OAuth
+ * app was registered with avoids a generic "invalid redirect_uri" that only
+ * surfaces after the user has already typed a password.
+ */
+var EnyoOauthRedirectUrlPatternEnum;
+(function (EnyoOauthRedirectUrlPatternEnum) {
+    /**
+     * The request id is carried as a query parameter, e.g.
+     * `https://api.enyo-energy.de/oauth-callback?from=<requestId>`. The host's
+     * default.
+     */
+    EnyoOauthRedirectUrlPatternEnum["QueryParam"] = "query-param";
+    /**
+     * The request id is carried as a trailing path segment, e.g.
+     * `https://api.enyo-energy.de/oauth-callback/<requestId>`. Use this for
+     * providers that reject a registered `redirect_uri` containing a query
+     * string.
+     */
+    EnyoOauthRedirectUrlPatternEnum["PathSegment"] = "path-segment";
+})(EnyoOauthRedirectUrlPatternEnum || (exports.EnyoOauthRedirectUrlPatternEnum = EnyoOauthRedirectUrlPatternEnum = {}));
 var EnyoAuthenticationStateEnum;
 (function (EnyoAuthenticationStateEnum) {
     EnyoAuthenticationStateEnum["Authenticated"] = "Authenticated";

package/dist/cjs/types/enyo-authentication.d.cts

@@ -34,11 +34,78 @@ export interface EnyoUsernamePasswordAuthentication {
     /** Optional additional fields to display in the authentication form */
     additionalFields?: EnyoAuthenticationAdditionalField[];
 }
+/**
+ * How the host encodes the pending request into the enyo callback URL it hands
+ * out as {@link EnyoOauthAuthenticationStart.enyoRedirectUrl}.
+ *
+ * OAuth providers differ in what they accept as a registered `redirect_uri`:
+ * some match the URL exactly and reject anything carrying a query string,
+ * others match only the path prefix. Declaring the shape the provider's OAuth
+ * app was registered with avoids a generic "invalid redirect_uri" that only
+ * surfaces after the user has already typed a password.
+ */
+export declare enum EnyoOauthRedirectUrlPatternEnum {
+    /**
+     * The request id is carried as a query parameter, e.g.
+     * `https://api.enyo-energy.de/oauth-callback?from=<requestId>`. The host's
+     * default.
+     */
+    QueryParam = "query-param",
+    /**
+     * The request id is carried as a trailing path segment, e.g.
+     * `https://api.enyo-energy.de/oauth-callback/<requestId>`. Use this for
+     * providers that reject a registered `redirect_uri` containing a query
+     * string.
+     */
+    PathSegment = "path-segment"
+}
+/**
+ * Constraints a package puts on the enyo callback URL the host generates for an
+ * OAuth flow. Every field is optional — an omitted field leaves the choice to
+ * the host.
+ *
+ * These are properties of the *provider*, not preferences: set them because the
+ * vendor's OAuth app rejects the alternative, not because one shape looks
+ * tidier. The filter the host applied travels back with the request as
+ * {@link EnyoOauthAuthenticationStart.redirectUrlFilter}, so an app can confirm
+ * what it got instead of parsing the URL.
+ */
+export interface EnyoOauthRedirectUrlFilter {
+    /**
+     * Require an `https` callback URL rather than a custom app scheme such as
+     * `enyoapp://`, which forces the login to run in a web browser instead of an
+     * in-app / native flow.
+     *
+     * Set it when the provider will not accept a custom-scheme redirect. Many
+     * OAuth providers reject anything that is not `https`, so a redirect of
+     * `enyoapp://…` fails at the authorization server before the installer has
+     * typed a password, with nothing on screen that points at the cause. The
+     * native flow is the better experience where it works — it keeps the
+     * installer inside the app — so only turn this on when the provider forces
+     * it.
+     */
+    webOnly?: boolean;
+    /**
+     * Which {@link EnyoOauthRedirectUrlPatternEnum} the callback URL must
+     * follow. Omit to let the host choose (today: `QueryParam`).
+     */
+    pattern?: EnyoOauthRedirectUrlPatternEnum;
+}
 export interface EnyoOauthAuthentication {
     description?: EnyoPackageConfigurationTranslatedValue[];
     /** If the client id and client secret need to be provided by the user*/
     clientIdName?: EnyoPackageConfigurationTranslatedValue[];
     clientSecretName?: EnyoPackageConfigurationTranslatedValue[];
+    /**
+     * Constraints on the enyo callback URL the host generates for this flow —
+     * `https`-only and/or a specific URL pattern. The host applies them when
+     * building {@link EnyoOauthAuthenticationStart.enyoRedirectUrl}, before the
+     * request ever reaches the package's `listenForOauthStart` listener.
+     *
+     * Omit it to let the host pick, which is right unless the provider's OAuth
+     * app was registered with a redirect URI the default does not match.
+     */
+    redirectUrlFilter?: EnyoOauthRedirectUrlFilter;
 }
 /**
  * OAuth authentication start configuration
@@ -60,19 +127,31 @@ export interface EnyoOauthAuthenticationStart {
      * such as `enyoapp://`.
      *
      * Set by the host when the flow that started the login declared the
-     * constraint — today
-     * {@link EnyoOnboardingV2AuthBlock.requiresWebAuthentication} on an
-     * onboarding v2 auth block. It is reported here so a package building the
-     * provider's authorize URL can act on it explicitly: pick the matching
-     * registered OAuth client, or fail fast with a clear message instead of
-     * letting the authorization server answer "invalid redirect_uri" after the
-     * user has already typed a password.
+     * constraint. It is reported here so a package building the provider's
+     * authorize URL can act on it explicitly: pick the matching registered
+     * OAuth client, or fail fast with a clear message instead of letting the
+     * authorization server answer "invalid redirect_uri" after the user has
+     * already typed a password.
      *
      * Absent or `false` means the host chose the redirect itself and it may
      * carry a custom scheme. Prefer reading this flag over sniffing
      * {@link enyoRedirectUrl}'s scheme.
+     *
+     * @deprecated Read {@link redirectUrlFilter}`.webOnly` instead, which
+     * carries the same information alongside the URL-pattern constraint. The
+     * host keeps both in sync: whenever this flag is `true`,
+     * `redirectUrlFilter.webOnly` is `true` as well.
      */
     requiresWebAuthentication?: boolean;
+    /**
+     * The {@link EnyoOauthRedirectUrlFilter} the host applied when building
+     * {@link enyoRedirectUrl} — the resolved constraints, not the requested
+     * ones, so a package can confirm which callback shape it got rather than
+     * parsing the URL.
+     *
+     * Absent when the flow declared no constraints and the host chose freely.
+     */
+    redirectUrlFilter?: EnyoOauthRedirectUrlFilter;
 }
 export interface EnyoOauthAuthenticationRedirectUrlResponse {
     redirectUrl: string;

package/dist/cjs/types/enyo-automation.cjs

@@ -19,6 +19,38 @@ var EnyoAutomationTriggerTypeEnum;
      * falls below.
      */
     EnyoAutomationTriggerTypeEnum["PvSurplusThreshold"] = "pv-surplus-threshold";
+    /**
+     * Fires while the current PV surplus is *below* a user-configured threshold
+     * (see {@link EnyoAutomationPvSurplusBelowThresholdTrigger}). This is the
+     * inverse of {@link PvSurplusThreshold} and expresses the "turn the target
+     * off once the PV surplus reaches X Watt" use case: the automation is
+     * active (target on) while the surplus stays below the threshold and is
+     * deactivated (target off) as soon as the surplus reaches or exceeds it.
+     */
+    EnyoAutomationTriggerTypeEnum["PvSurplusBelowThreshold"] = "pv-surplus-below-threshold";
+    /**
+     * Fires while the current electricity price per kWh is below a
+     * user-configured limit (see {@link EnyoAutomationBelowPriceLimitTrigger}).
+     * The automation is activated when the price drops below the limit and
+     * deactivated when it reaches or exceeds it again.
+     */
+    EnyoAutomationTriggerTypeEnum["BelowPriceLimit"] = "below-price-limit";
+    /**
+     * Fires during the cheapest share of the day — e.g. the cheapest 25 % of
+     * the day's price intervals (see
+     * {@link EnyoAutomationCheapestShareOfDayTrigger}). The provider ranks the
+     * day's known prices and marks the cheapest intervals as active, so the
+     * automation follows the price ranking rather than an absolute price.
+     */
+    EnyoAutomationTriggerTypeEnum["CheapestShareOfDay"] = "cheapest-share-of-day";
+    /**
+     * Fires during user-defined time windows — the "Zeitplan" trigger (see
+     * {@link EnyoAutomationScheduleTrigger}). A schedule holds one or more
+     * windows, each with a start and end time of day and an optional set of
+     * weekdays it applies to, so "weekdays 06:00-08:00 and 18:00-22:00, and all
+     * day on Sunday" is a single trigger.
+     */
+    EnyoAutomationTriggerTypeEnum["Schedule"] = "schedule";
 })(EnyoAutomationTriggerTypeEnum || (exports.EnyoAutomationTriggerTypeEnum = EnyoAutomationTriggerTypeEnum = {}));
 /**
  * The kinds of action an automation can perform when its trigger is active.
@@ -70,6 +102,14 @@ var EnyoAutomationMqttPlaceholderEnum;
     EnyoAutomationMqttPlaceholderEnum["State"] = "{{state}}";
     /** Replaced with the current PV surplus in Watts at the moment of publishing. */
     EnyoAutomationMqttPlaceholderEnum["SurplusW"] = "{{surplusW}}";
+    /**
+     * Replaced with the current electricity price per kWh at the moment of
+     * publishing. Only meaningful for price-based triggers
+     * ({@link EnyoAutomationTriggerTypeEnum.BelowPriceLimit} and
+     * {@link EnyoAutomationTriggerTypeEnum.CheapestShareOfDay}); resolves to
+     * `null` when no price is known.
+     */
+    EnyoAutomationMqttPlaceholderEnum["PricePerKwh"] = "{{pricePerKwh}}";
     /** Replaced with the ISO 8601 timestamp of the event. */
     EnyoAutomationMqttPlaceholderEnum["TimestampIso"] = "{{timestampIso}}";
     /** Replaced with the id of the automation that fired. */