@enyo-energy/energy-app-sdk 0.0.170 → 0.0.172

package/README.md

@@ -55,6 +55,14 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [BatteryCommandForecast](#batterycommandforecast)
   - [HeatpumpForecast](#heatpumpforecast)
   - [Validators](#validators)
+- [Automations](#automations)
+  - [The model](#-the-model)
+  - [Guide: Energy Manager apps](#-guide-energy-manager-apps)
+  - [Guide: regular energy apps (smart plugs like Shelly)](#-guide-regular-energy-apps-smart-plugs-like-shelly)
+  - [End-to-end: pool pump on solar](#-end-to-end-pool-pump-on-solar)
+  - [Mandatory vs Flexible (current limitation)](#-mandatory-vs-flexible-current-limitation)
+  - [Permissions](#-permissions)
+  - [Validators](#-validators)
 - [Examples](#examples)
   - [Basic Energy App](#basic-energy-app)
   - [Device Integration](#device-integration)
@@ -2082,6 +2090,213 @@ try {
 
 Granular helpers are exported alongside the top-level validators: `validateChargerSchedule`, `validateBatterySchedule`, `validateDhwBoostWindows`, `validateRoomPreHeatingWindows`, `validateBufferTankBoostWindows`, `validatePowerAnnouncementSchedule`, `validateTemperatureForecast`.
 
+## Automations
+
+Automations let the end-user wire up simple **"when a trigger is active, do one or more actions"** rules — for example *"when PV surplus is above 2000 W, switch my pool pump for at least 10 minutes."* They are composed by the user in the platform UI from building blocks that energy apps contribute:
+
+- An **Energy Manager app** *registers the trigger types* it can evaluate and publishes the live trigger state (and, optionally, a forecast).
+- A **regular energy app** (e.g. a Shelly smart-plug integration) *declares which of its appliances can be an action target* and *executes the switching* when the trigger fires.
+- The **user** creates the concrete automation in the app; energy apps only **read and observe** automations through the SDK — there is no `create()` on the SDK (authoring lives in the platform).
+
+Access the API via `useAutomations()`:
+
+```typescript
+const automations = sdk.useAutomations();
+```
+
+### 🧩 The model
+
+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` |
+| **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.
+
+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 }`).
+- The **forecast** is a method — `publishAutomationForecast()` — not a data-bus message.
+
+### ⚡ Guide: Energy Manager apps
+
+Requires the **`EnergyManager`** permission (to register triggers / publish forecasts) and **`SendDataBusValues`** (to emit the trigger message).
+
+**1. Register the trigger type once, at startup.** Registration is by enum value only — all user-facing wording is handled by the UI.
+
+```typescript
+import {EnergyApp, EnyoAutomationTriggerTypeEnum} from '@enyo-energy/energy-app-sdk';
+
+const sdk = new EnergyApp();
+const automations = sdk.useAutomations();
+
+sdk.register(async () => {
+    await automations.registerTrigger(EnyoAutomationTriggerTypeEnum.PvSurplusThreshold);
+});
+```
+
+**2. Evaluate the condition and publish trigger state.** Watch the aggregated PV surplus and, for every automation that uses your trigger, publish an `AutomationTriggerV1` message whenever it crosses the user-configured `thresholdW`.
+
+Message-type identifiers are the `EnyoDataBusMessageEnum` values passed as strings, the same convention used everywhere else in the data-bus API.
+
+```typescript
+import {EnyoAutomationTriggerTypeEnum} from '@enyo-energy/energy-app-sdk';
+
+const dataBus = sdk.useDataBus();
+
+dataBus.listenForMessages(['AggregatedStateUpdateV1'], (message: any) => {
+    // gridFeedInW is the surplus fed to the grid (or derive from -gridPowerW when negative)
+    const surplusW = message.data?.gridFeedInW ?? 0;
+
+    for (const automation of currentAutomations) {
+        if (automation.trigger.type !== EnyoAutomationTriggerTypeEnum.PvSurplusThreshold) continue;
+        const thresholdW = automation.trigger.thresholdW;
+        const active = surplusW > thresholdW;
+
+        dataBus.sendMessage([{
+            type: 'message',
+            message: 'AutomationTriggerV1',
+            automationId: automation.id,
+            data: {
+                active,
+                trigger: {
+                    triggerType: EnyoAutomationTriggerTypeEnum.PvSurplusThreshold,
+                    surplusW,
+                    thresholdW,
+                },
+            },
+        }]);
+    }
+});
+```
+
+> Debounce/hysteresis (e.g. only emit on a real transition, add a deactivate margin) is the Energy Manager's responsibility — send a message when the `active` state actually changes, not on every tick.
+
+**3. (Optional) Publish a forecast.** Combine your PV-surplus forecast with each automation's threshold to predict the windows where the trigger will be active, so the system can plan ahead. The forecast marks occupied windows only (no watts).
+
+```typescript
+await automations.publishAutomationForecast({
+    automationId: 'pool-pump',
+    resolution: '15m',
+    entries: [
+        { timestampIso: '2026-07-04T10:00:00.000Z', active: true, mandatory: false, hasLoad: true },
+        { timestampIso: '2026-07-04T10:15:00.000Z', active: true, mandatory: false, hasLoad: true },
+        { timestampIso: '2026-07-04T10:30:00.000Z', active: false },
+    ],
+});
+```
+
+### 🔌 Guide: regular energy apps (smart plugs like Shelly)
+
+Requires the **`Automation`** permission (to read/observe automations) plus whatever your device needs to switch (e.g. network device access, Modbus, or `RestrictedInternetAccess` for a Shelly HTTP call).
+
+**1. Advertise which appliances can be an action target.** When you register (or update) an appliance, set `supportedAutomationActions`. The automation UI then offers this appliance only for the action types it lists. A three-channel Shelly registers three `SmartPlug` appliances, one per channel.
+
+```typescript
+import {EnyoApplianceTypeEnum, EnyoAutomationActionTypeEnum} from '@enyo-energy/energy-app-sdk';
+
+await sdk.useAppliances().save(
+    {
+        name: [{language: 'en', name: 'Pool pump'}],
+        type: EnyoApplianceTypeEnum.SmartPlug,
+        networkDeviceIds: [shellyDeviceId],
+        supportedAutomationActions: [EnyoAutomationActionTypeEnum.SmartPlugSwitch],
+    },
+    'shelly-pool-ch0',
+);
+```
+
+**2. Learn which automations target your appliances.** Fetch on startup and keep in sync with the listeners. Each listener returns an id you can pass to `removeListener()`.
+
+```typescript
+const automations = sdk.useAutomations();
+
+let mine = (await automations.list()).filter(hasSmartPlugActionForMyAppliances);
+
+automations.listenForAutomationCreated((a) => { /* add if it targets my appliance */ });
+automations.listenForAutomationUpdated((a) => { /* replace */ });
+automations.listenForAutomationRemoved((automationId) => { /* drop + switch off */ });
+```
+
+**3. Switch on the trigger message.** Subscribe to `AutomationTriggerV1`, resolve the automation's `SmartPlugSwitch` action to one of your appliances, and drive the relay. Honor `minDurationMinutes` locally (keep it on for at least that long after switching on).
+
+```typescript
+import {EnyoAutomationActionTypeEnum} from '@enyo-energy/energy-app-sdk';
+
+sdk.useDataBus().listenForMessages(['AutomationTriggerV1'], async (message: any) => {
+    const {automationId, data} = message; // data: { active, trigger }
+    const automation = mine.find((a) => a.id === automationId);
+    if (!automation) return;
+
+    for (const action of automation.actions) {
+        if (action.type !== EnyoAutomationActionTypeEnum.SmartPlugSwitch) continue;
+        if (data.active) {
+            await switchOn(action.applianceId);
+            scheduleMinRuntimeGuard(action.applianceId, action.minDurationMinutes);
+        } else if (minRuntimeElapsed(action.applianceId)) {
+            await switchOff(action.applianceId);
+        }
+    }
+});
+```
+
+### 🅿️ End-to-end: pool pump on solar
+
+The user's automation object (authored in the app) for *"when PV surplus > 2000 W, run the pool pump for at least 10 minutes, Energy Manager may choose the timing":*
+
+```typescript
+const automation = {
+    id: 'pool-pump',
+    name: 'Pool pump on solar',
+    enabled: true,
+    trigger: {type: EnyoAutomationTriggerTypeEnum.PvSurplusThreshold, thresholdW: 2000},
+    actions: [{
+        id: 'switch-pump',
+        type: EnyoAutomationActionTypeEnum.SmartPlugSwitch,
+        applianceId: 'shelly-pool-ch0',
+        minDurationMinutes: 10,
+        schedulingMode: EnyoAutomationSchedulingModeEnum.Flexible,
+        targetKind: EnyoAutomationTargetKindEnum.Load,
+    }],
+};
+```
+
+The **Energy Manager** publishes `AutomationTriggerV1` as the surplus crosses 2000 W; the **Shelly app** receives it and switches `shelly-pool-ch0`, keeping it on for ≥ 10 minutes.
+
+### ⏳ Mandatory vs Flexible (current limitation)
+
+- **`Mandatory`** works fully today: the device app reacts directly to the `AutomationTriggerV1` `active` flag (on when `true`, off when `false` once the minimum runtime has elapsed).
+- **`Flexible`** lets the Energy Manager decide *whether and when* to actually run the action inside the active window. That decision does **not yet** have a dedicated Energy-Manager→device dispatch message — `AutomationTriggerV1` only reports that the *condition* holds. Until a dispatch message (planned: `AutomationActionCommandV1`, carrying `automationId`, `actionId`, `command`, and a run duration) is added, a device app treats `Flexible` like `Mandatory` and self-enforces `minDurationMinutes`.
+
+### 🔐 Permissions
+
+| Capability | Permission |
+| --- | --- |
+| `list` / `getById` / `listenFor*` automations | `Automation` |
+| `registerTrigger` / `deregisterTrigger` / `publishAutomationForecast` | `EnergyManager` |
+| Emit the `AutomationTriggerV1` data-bus message | `SendDataBusValues` |
+
+### ✅ Validators
+
+`validateAutomation`, `validateAutomationTriggerData`, and `validateAutomationForecast` are exported as pure functions (throwing `AutomationValidationError`, whose message names the offending field) so you can validate before persisting or publishing.
+
+```typescript
+import {validateAutomation, AutomationValidationError} from '@enyo-energy/energy-app-sdk';
+
+try {
+    validateAutomation(automation, knownSmartPlugApplianceIds);
+} catch (error) {
+    if (error instanceof AutomationValidationError) {
+        // surface error.message
+    }
+}
+```
+
 ## Examples
 
 ### Basic Energy App

package/dist/cjs/energy-app-permission.type.cjs

@@ -49,4 +49,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["ChildProcess"] = "ChildProcess";
     EnergyAppPermissionTypeEnum["Udp"] = "Udp";
     EnergyAppPermissionTypeEnum["ProvidedFiles"] = "ProvidedFiles";
+    EnergyAppPermissionTypeEnum["Automation"] = "Automation";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

package/dist/cjs/energy-app-permission.type.d.cts

@@ -1,4 +1,4 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp' | 'ProvidedFiles';
+export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp' | 'ProvidedFiles' | 'Automation';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -45,5 +45,6 @@ export declare enum EnergyAppPermissionTypeEnum {
     Wifi = "Wifi",
     ChildProcess = "ChildProcess",
     Udp = "Udp",
-    ProvidedFiles = "ProvidedFiles"
+    ProvidedFiles = "ProvidedFiles",
+    Automation = "Automation"
 }

package/dist/cjs/energy-app.cjs

@@ -34,6 +34,9 @@ class EnergyApp {
             this.energyAppSdk = energyAppSdkInstance;
         }
     }
+    healthcheck() {
+        return new Date();
+    }
     isSystemOnline() {
         return this.energyAppSdk.isSystemOnline();
     }
@@ -336,6 +339,19 @@ class EnergyApp {
     useFiles() {
         return this.energyAppSdk.useFiles();
     }
+    /**
+     * Gets the Automation API for reading user-configured automations and
+     * listening for their creation, update and removal. Apps holding the
+     * `EnergyManager` permission can additionally register trigger types,
+     * report live trigger state, and publish automation forecasts.
+     * @returns The Automation API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the required permission
+     *         (`Automation` for reads, `EnergyManager` for provider methods) is
+     *         not granted.
+     */
+    useAutomations() {
+        return this.energyAppSdk.useAutomations();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -38,6 +38,7 @@ import { EnergyAppConfigurationManager } from "./packages/energy-app-configurati
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
 import { EnergyAppFile } from "./packages/energy-app-file.cjs";
+import { EnergyAppAutomation } from "./packages/energy-app-automation.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -60,6 +61,7 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
     private readonly energyAppSdk;
     private udpInstance;
     constructor();
+    healthcheck(): Date;
     isSystemOnline(): boolean;
     /**
      * Registers a listener that gets called when the network status changes.
@@ -268,6 +270,17 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useFiles(): EnergyAppFile;
+    /**
+     * Gets the Automation API for reading user-configured automations and
+     * listening for their creation, update and removal. Apps holding the
+     * `EnergyManager` permission can additionally register trigger types,
+     * report live trigger state, and publish automation forecasts.
+     * @returns The Automation API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the required permission
+     *         (`Automation` for reads, `EnergyManager` for provider methods) is
+     *         not granted.
+     */
+    useAutomations(): EnergyAppAutomation;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -37,6 +37,7 @@ import { EnergyAppConfigurationManager } from "./packages/energy-app-configurati
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
 import { EnergyAppFile } from "./packages/energy-app-file.cjs";
+import { EnergyAppAutomation } from "./packages/energy-app-automation.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -54,6 +55,8 @@ export declare enum EnergyAppStateEnum {
 export interface EnyoEnergyAppSdk {
     /** Register a callback that gets called when the package is initialized */
     register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>) => void;
+    /** health check - returns the current date to check if alive */
+    healthcheck: () => Date;
     /** Register a callback that gets called when the system is shutting down */
     onShutdown: (callback: () => void | Promise<void>) => void;
     /** Update the state of the Energy App. Default state set is launching*/
@@ -140,4 +143,6 @@ export interface EnyoEnergyAppSdk {
     useBatteries: () => EnergyAppBattery;
     /** Get the File API for providing user-facing files whose translated names/explanations are shown by the host and whose content is produced on demand when the user stores them */
     useFiles: () => EnergyAppFile;
+    /** Get the Automation API for reading user-configured automations and (with EnergyManager permission) registering triggers, reporting trigger state, and publishing automation forecasts */
+    useAutomations: () => EnergyAppAutomation;
 }

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

@@ -0,0 +1,254 @@
+"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.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_mqtt_js_1 = require("../../types/enyo-mqtt.cjs");
+/**
+ * Thrown when an automation, action or automation forecast violates one of the
+ * invariants enforced by this module. The message names the offending field /
+ * index so callers can surface it directly to the user.
+ */
+class AutomationValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AutomationValidationError';
+    }
+}
+exports.AutomationValidationError = AutomationValidationError;
+/** Minimum smart-plug on-duration, in minutes. */
+exports.AUTOMATION_MIN_DURATION_MINUTES = 5;
+/** 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. */
+exports.AUTOMATION_DURATION_STEP_MINUTES = 5;
+/** Duration in seconds of each {@link EnyoForecastResolution} value. */
+const FORECAST_RESOLUTION_SECONDS = {
+    '10s': 10,
+    '1m': 60,
+    '5m': 300,
+    '15m': 900,
+    '1h': 3600,
+};
+/**
+ * Validates a complete {@link EnyoAutomation}. Throws on the first violation.
+ *
+ * When `knownSmartPlugApplianceIds` is provided, every smart-plug action's
+ * `applianceId` must be a member of it — use this to ensure the action targets
+ * an appliance that actually supports {@link EnyoAutomationActionTypeEnum.SmartPlugSwitch}.
+ *
+ * @param automation - The automation to validate.
+ * @param knownSmartPlugApplianceIds - Optional set/array of appliance ids that
+ *   support the smart-plug-switch action; when given, smart-plug action targets
+ *   are checked against it.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+function validateAutomation(automation, knownSmartPlugApplianceIds) {
+    if (!automation || typeof automation !== 'object') {
+        throw new AutomationValidationError('Automation must be an object.');
+    }
+    requireNonEmptyString(automation.id, 'Automation.id');
+    requireNonEmptyString(automation.name, 'Automation.name');
+    if (typeof automation.enabled !== 'boolean') {
+        throw new AutomationValidationError('Automation.enabled must be a boolean.');
+    }
+    validateTrigger(automation.trigger);
+    if (!Array.isArray(automation.actions) || automation.actions.length === 0) {
+        throw new AutomationValidationError('Automation.actions must contain at least one action.');
+    }
+    const knownIds = knownSmartPlugApplianceIds ? new Set(knownSmartPlugApplianceIds) : undefined;
+    const seenActionIds = new Set();
+    automation.actions.forEach((action, index) => {
+        requireNonEmptyString(action?.id, `Automation.actions[${index}].id`);
+        if (seenActionIds.has(action.id)) {
+            throw new AutomationValidationError(`Automation.actions[${index}].id is not unique: ${action.id}.`);
+        }
+        seenActionIds.add(action.id);
+        validateAction(action, index, knownIds);
+    });
+}
+/**
+ * Validates the trigger of an automation. Throws on the first violation.
+ *
+ * @param trigger - The trigger configuration.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+function validateTrigger(trigger) {
+    if (!trigger || typeof trigger !== 'object') {
+        throw new AutomationValidationError('Automation.trigger must be an object.');
+    }
+    switch (trigger.type) {
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.PvSurplusThreshold:
+            if (typeof trigger.thresholdW !== 'number' || !Number.isFinite(trigger.thresholdW) || trigger.thresholdW < 0) {
+                throw new AutomationValidationError('PvSurplusThreshold trigger.thresholdW must be a finite number >= 0.');
+            }
+            break;
+        default:
+            throw new AutomationValidationError(`Automation.trigger.type is invalid: ${trigger.type}.`);
+    }
+}
+/**
+ * Validates a single automation action. Throws on the first violation.
+ *
+ * @param action - The action to validate.
+ * @param index - Index of the action within its automation (for error messages).
+ * @param knownSmartPlugApplianceIds - Optional set of appliance ids that support
+ *   the smart-plug-switch action.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+function validateAction(action, index = 0, knownSmartPlugApplianceIds) {
+    const label = `Automation.actions[${index}]`;
+    if (!action || typeof action !== 'object') {
+        throw new AutomationValidationError(`${label} must be an object.`);
+    }
+    requireEnumMember(action.schedulingMode, enyo_automation_js_1.EnyoAutomationSchedulingModeEnum, `${label}.schedulingMode`);
+    requireEnumMember(action.targetKind, enyo_automation_js_1.EnyoAutomationTargetKindEnum, `${label}.targetKind`);
+    switch (action.type) {
+        case enyo_automation_js_1.EnyoAutomationActionTypeEnum.Mqtt:
+            validateMqttAction(action, label);
+            break;
+        case enyo_automation_js_1.EnyoAutomationActionTypeEnum.SmartPlugSwitch:
+            validateSmartPlugSwitchAction(action, label, knownSmartPlugApplianceIds);
+            break;
+        default:
+            throw new AutomationValidationError(`${label}.type is invalid: ${action.type}.`);
+    }
+}
+/**
+ * Validates an {@link EnyoAutomationForecast}: resolution must be known and the
+ * entries must be chronologically ordered, non-overlapping, and spaced exactly
+ * one resolution step apart. Throws on the first violation.
+ *
+ * @param forecast - The forecast to validate.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+function validateAutomationForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new AutomationValidationError('AutomationForecast must be an object.');
+    }
+    requireNonEmptyString(forecast.automationId, 'AutomationForecast.automationId');
+    const stepSeconds = FORECAST_RESOLUTION_SECONDS[forecast.resolution];
+    if (stepSeconds === undefined) {
+        throw new AutomationValidationError(`AutomationForecast.resolution is invalid: ${forecast.resolution}.`);
+    }
+    if (!Array.isArray(forecast.entries)) {
+        throw new AutomationValidationError('AutomationForecast.entries must be an array.');
+    }
+    let previousMs;
+    forecast.entries.forEach((entry, index) => {
+        const entryLabel = `AutomationForecast.entries[${index}]`;
+        if (!entry || typeof entry !== 'object') {
+            throw new AutomationValidationError(`${entryLabel} must be an object.`);
+        }
+        if (typeof entry.active !== 'boolean') {
+            throw new AutomationValidationError(`${entryLabel}.active must be a boolean.`);
+        }
+        const currentMs = Date.parse(entry.timestampIso);
+        if (Number.isNaN(currentMs)) {
+            throw new AutomationValidationError(`${entryLabel}.timestampIso is not a valid ISO 8601 timestamp: ${entry.timestampIso}.`);
+        }
+        if (previousMs !== undefined) {
+            const deltaSeconds = (currentMs - previousMs) / 1000;
+            if (deltaSeconds !== stepSeconds) {
+                throw new AutomationValidationError(`${entryLabel} is spaced ${deltaSeconds}s from the previous entry; expected ${stepSeconds}s for resolution ${forecast.resolution}.`);
+            }
+        }
+        previousMs = currentMs;
+    });
+}
+/**
+ * Validates the trigger-type-specific metadata carried by the
+ * `AutomationTriggerV1` data-bus message. Throws on the first violation.
+ *
+ * @param trigger - The trigger metadata payload.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+function validateAutomationTriggerData(trigger) {
+    if (!trigger || typeof trigger !== 'object') {
+        throw new AutomationValidationError('AutomationTriggerData must be an object.');
+    }
+    switch (trigger.triggerType) {
+        case enyo_automation_js_1.EnyoAutomationTriggerTypeEnum.PvSurplusThreshold:
+            requireFiniteNonNegative(trigger.surplusW, 'AutomationTriggerData.surplusW');
+            requireFiniteNonNegative(trigger.thresholdW, 'AutomationTriggerData.thresholdW');
+            break;
+        default:
+            throw new AutomationValidationError(`AutomationTriggerData.triggerType is invalid: ${trigger.triggerType}.`);
+    }
+}
+function validateMqttAction(action, label) {
+    requireNonEmptyString(action.topic, `${label}.topic`);
+    if (typeof action.updateChargingPvSurplus !== 'boolean') {
+        throw new AutomationValidationError(`${label}.updateChargingPvSurplus must be a boolean.`);
+    }
+    if (typeof action.payloadTemplate !== 'string' || action.payloadTemplate.length === 0) {
+        throw new AutomationValidationError(`${label}.payloadTemplate must be a non-empty string.`);
+    }
+    validatePayloadTemplate(action.payloadTemplate, `${label}.payloadTemplate`);
+    const { qos } = action.publishOptions ?? {};
+    if (qos !== undefined && qos !== enyo_mqtt_js_1.MqttQos.AtMostOnce && qos !== enyo_mqtt_js_1.MqttQos.AtLeastOnce && qos !== enyo_mqtt_js_1.MqttQos.ExactlyOnce) {
+        throw new AutomationValidationError(`${label}.publishOptions.qos must be one of 0, 1, 2.`);
+    }
+    if (action.publishOptions?.retain !== undefined && typeof action.publishOptions.retain !== 'boolean') {
+        throw new AutomationValidationError(`${label}.publishOptions.retain must be a boolean.`);
+    }
+}
+function validateSmartPlugSwitchAction(action, label, knownSmartPlugApplianceIds) {
+    requireNonEmptyString(action.applianceId, `${label}.applianceId`);
+    if (knownSmartPlugApplianceIds && !knownSmartPlugApplianceIds.has(action.applianceId)) {
+        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}.`);
+    }
+}
+/**
+ * Ensures a payload template only references known placeholders and is
+ * structurally valid JSON once its placeholders are neutralised.
+ */
+function validatePayloadTemplate(template, label) {
+    const knownPlaceholders = new Set(Object.values(enyo_automation_js_1.EnyoAutomationMqttPlaceholderEnum));
+    const tokens = template.match(/{{[^}]*}}/g) ?? [];
+    for (const token of tokens) {
+        if (!knownPlaceholders.has(token)) {
+            throw new AutomationValidationError(`${label} references an unknown placeholder: ${token}. Allowed: ${Object.values(enyo_automation_js_1.EnyoAutomationMqttPlaceholderEnum).join(', ')}.`);
+        }
+    }
+    // Replace every placeholder with a neutral JSON scalar so the surrounding
+    // structure can be validated regardless of the placeholder's runtime value.
+    const neutralised = template.replace(/{{[^}]*}}/g, '0');
+    try {
+        JSON.parse(neutralised);
+    }
+    catch {
+        throw new AutomationValidationError(`${label} is not valid JSON once placeholders are substituted.`);
+    }
+}
+function requireFiniteNonNegative(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new AutomationValidationError(`${label} must be a finite number >= 0.`);
+    }
+}
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new AutomationValidationError(`${label} must be a non-empty string.`);
+    }
+}
+function requireEnumMember(value, enumObject, label) {
+    const allowed = new Set(Object.values(enumObject));
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new AutomationValidationError(`${label} is required.`);
+    }
+    if (!allowed.has(value)) {
+        throw new AutomationValidationError(`${label} is invalid: ${value}. Allowed values: ${Object.values(enumObject).join(', ')}.`);
+    }
+}

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

@@ -0,0 +1,63 @@
+import { EnyoAutomation, EnyoAutomationAction, EnyoAutomationForecast, EnyoAutomationTriggerData } from '../../types/enyo-automation.cjs';
+/**
+ * Thrown when an automation, action or automation forecast violates one of the
+ * invariants enforced by this module. The message names the offending field /
+ * index so callers can surface it directly to the user.
+ */
+export declare class AutomationValidationError extends Error {
+    constructor(message: string);
+}
+/** Minimum smart-plug on-duration, in minutes. */
+export declare const AUTOMATION_MIN_DURATION_MINUTES = 5;
+/** 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. */
+export declare const AUTOMATION_DURATION_STEP_MINUTES = 5;
+/**
+ * Validates a complete {@link EnyoAutomation}. Throws on the first violation.
+ *
+ * When `knownSmartPlugApplianceIds` is provided, every smart-plug action's
+ * `applianceId` must be a member of it — use this to ensure the action targets
+ * an appliance that actually supports {@link EnyoAutomationActionTypeEnum.SmartPlugSwitch}.
+ *
+ * @param automation - The automation to validate.
+ * @param knownSmartPlugApplianceIds - Optional set/array of appliance ids that
+ *   support the smart-plug-switch action; when given, smart-plug action targets
+ *   are checked against it.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+export declare function validateAutomation(automation: EnyoAutomation, knownSmartPlugApplianceIds?: Iterable<string>): void;
+/**
+ * Validates the trigger of an automation. Throws on the first violation.
+ *
+ * @param trigger - The trigger configuration.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+export declare function validateTrigger(trigger: EnyoAutomation['trigger']): void;
+/**
+ * Validates a single automation action. Throws on the first violation.
+ *
+ * @param action - The action to validate.
+ * @param index - Index of the action within its automation (for error messages).
+ * @param knownSmartPlugApplianceIds - Optional set of appliance ids that support
+ *   the smart-plug-switch action.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+export declare function validateAction(action: EnyoAutomationAction, index?: number, knownSmartPlugApplianceIds?: Set<string>): void;
+/**
+ * Validates an {@link EnyoAutomationForecast}: resolution must be known and the
+ * entries must be chronologically ordered, non-overlapping, and spaced exactly
+ * one resolution step apart. Throws on the first violation.
+ *
+ * @param forecast - The forecast to validate.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+export declare function validateAutomationForecast(forecast: EnyoAutomationForecast): void;
+/**
+ * Validates the trigger-type-specific metadata carried by the
+ * `AutomationTriggerV1` data-bus message. Throws on the first violation.
+ *
+ * @param trigger - The trigger metadata payload.
+ * @throws {AutomationValidationError} On the first invariant violation.
+ */
+export declare function validateAutomationTriggerData(trigger: EnyoAutomationTriggerData): void;