@enyo-energy/energy-app-sdk 1.13.0 → 1.15.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/appliances/appliance-manager.cjs

@@ -211,7 +211,7 @@ class ApplianceManager {
             airConditioning: appliance.airConditioning,
             heatingRod: appliance.heatingRod,
             smartPlug: appliance.smartPlug,
-            // Conditionally spread the two optional top-level fields that are NOT
+            // Conditionally spread the optional top-level fields that are NOT
             // covered by MERGEABLE_METADATA_KEYS. If they were always materialized
             // as explicit keys, an omitted (undefined) value would clobber the
             // stored value during mergeApplianceData's `{...existing, ...update}`
@@ -219,6 +219,7 @@ class ApplianceManager {
             // while dropping omitted fields so the existing value is preserved.
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
+            ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
         };
         let applianceData = newApplianceData;
         if (existingApplianceId) {

package/dist/cjs/implementations/appliances/appliance-manager.d.cts

@@ -65,6 +65,13 @@ export interface ApplianceConfig {
     heatingRod?: EnyoHeatingRodApplianceMetadata;
     smartPlug?: EnyoSmartPlugApplianceMetadata;
     availableFeatures?: EnyoApplianceAvailableFeaturesEnum[];
+    /**
+     * Optional vendor- or integration-specific compatibility modes. Forwarded to
+     * {@link EnyoAppliance.compatibilityModes} when the appliance is created or
+     * updated. Omit to keep the stored value on an update; pass an explicit `[]`
+     * to clear it.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Forwarded to {@link EnyoAppliance.cloudPackageId} when the
@@ -443,6 +450,11 @@ export interface PartialEnyoAppliance {
     smartPlug?: Partial<EnyoSmartPlugApplianceMetadata>;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
+    /**
+     * Optional list of vendor- or integration-specific compatibility modes that
+     * are active for this appliance. Mirrors {@link EnyoAppliance.compatibilityModes}.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Mirrors {@link EnyoAppliance.cloudPackageId}.

package/dist/cjs/implementations/appliances/in-memory-appliance-manager.cjs

@@ -54,7 +54,8 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
         };
         // Build the incoming appliance data covering every ApplianceConfig field.
         // The two optional top-level fields that are NOT shallow-merged by
-        // mergeApplianceData (`cloudPackageId`, `availableFeatures`) are only
+        // mergeApplianceData (`cloudPackageId`, `availableFeatures`,
+        // `compatibilityModes`) are only
         // materialized when provided so an omitted value cannot clobber the stored
         // one during an update; pass an explicit value (e.g. `[]`) to clear them.
         const newApplianceData = {
@@ -73,6 +74,7 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
             heatingRod: appliance.heatingRod,
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
+            ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
         };
         // On update, merge onto the stored appliance so type-specific metadata and
         // top-level fields that were not supplied in this call are preserved.

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-appliance.d.cts

@@ -277,6 +277,14 @@ export interface EnyoAppliance {
     smartPlug?: EnyoSmartPlugApplianceMetadata;
     /** Optional custom name for the appliance, defined by the user */
     customName?: string;
+    /**
+     * Optional list of vendor- or integration-specific compatibility modes that
+     * are active for this appliance. Each entry is a free-form, non-localized
+     * identifier describing a behavioural deviation the appliance requires
+     * (e.g. a firmware quirk workaround or a legacy protocol dialect).
+     * Consumers that do not know a given mode should ignore it.
+     */
+    compatibilityModes?: string[];
     /**
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Set when the appliance is provisioned and operated by a

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";