@enyo-energy/energy-app-sdk 0.0.146 → 0.0.147

package/README.md

@@ -49,6 +49,12 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [EvChargingForecast](#evchargingforecast)
   - [HeatpumpConsumptionForecast](#heatpumpconsumptionforecast)
   - [HeatpumpDhwTemperatureForecast](#heatpumpdhwtemperatureforecast)
+- [Appliance Energy-Manager Forecast](#appliance-energy-manager-forecast)
+  - [`useApplianceEnergyManagerForecast()`](#useapplianceenergymanagerforecast-energyappapplianceenergymanagerforecast)
+  - [ChargerForecast](#chargerforecast)
+  - [BatteryCommandForecast](#batterycommandforecast)
+  - [HeatpumpForecast](#heatpumpforecast)
+  - [Validators](#validators)
 - [Examples](#examples)
   - [Basic Energy App](#basic-energy-app)
   - [Device Integration](#device-integration)
@@ -130,6 +136,7 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Forecast EV charging demand | [`EvChargingForecast`](#evchargingforecast) |
 | Forecast heatpump electrical consumption | [`HeatpumpConsumptionForecast`](#heatpumpconsumptionforecast) |
 | Forecast heatpump DHW tank temperature | [`HeatpumpDhwTemperatureForecast`](#heatpumpdhwtemperatureforecast) |
+| Announce a charger / battery / heatpump command plan you **intend to apply** | [`useApplianceEnergyManagerForecast()`](#useapplianceenergymanagerforecast-energyappapplianceenergymanagerforecast) |
 | Talk to an EEBUS / SHIP / SPINE device | [`useEebus()`](#useeebus-energyappeebus) |
 | Speak MQTT (SDK broker or external) | [`useMqtt()`](#usemqtt-energyappmqtt) |
 | Scan or talk to Bluetooth LE peripherals | [`useBluetooth()`](#usebluetooth-energyappbluetooth) |
@@ -1898,6 +1905,183 @@ energyApp.onShutdown(async () => {
 
 > **Tip:** if your app needs more than one forecaster, prefer [`EnergyManagerEnergyApp`](#energymanagerenergyapp) — it manages construction, caching, and disposal for you.
 
+## Appliance Energy-Manager Forecast
+
+The [Forecasting](#forecasting) module above predicts what an appliance will **do** based on history. The Appliance Energy-Manager Forecast package goes the other way: it lets an energy-manager app declare what it **intends to command** each appliance to do over the upcoming horizon, plus the temperature trajectories its commands are expected to produce. Three appliance families are supported today — chargers, batteries, and heatpumps — and the heatpump payload can carry any combination of DHW boost, room pre-heating, buffer-tank boost, and a relative power-announcement schedule in one call.
+
+How the runtime fans these forecasts out to subscribers (data bus, RPC, …) is an internal implementation detail of the SDK runtime — apps just call `publish*` and the SDK takes care of the rest.
+
+**Required permission:** `EnergyManager`.
+
+### `useApplianceEnergyManagerForecast(): EnergyAppApplianceEnergyManagerForecast`
+
+```typescript
+const forecasts = energyApp.useApplianceEnergyManagerForecast();
+```
+
+| Method | Purpose |
+|---|---|
+| `publishChargerForecast(applianceId, forecast: ChargerForecast)` | Publish the planned phase / power schedule for a charger. |
+| `publishBatteryForecast(applianceId, forecast: BatteryCommandForecast)` | Publish the planned charge / discharge / auto cadence for a battery. |
+| `publishHeatpumpForecast(applianceId, forecast: HeatpumpForecast)` | Publish any combination of DHW boost / room pre-heating / buffer-tank boost / power-announcement schedule for a heatpump. |
+
+Every call validates the payload first and rejects with `ApplianceCommandForecastValidationError` if any invariant is broken — `publish*` never goes through the runtime with malformed data.
+
+Every forecast also accepts shared optional metadata via [`ApplianceForecastMetadata`](#validators):
+
+- `generatedAtIso?: string` — ISO 8601 generation timestamp. Stamped by the runtime when omitted.
+- `reason?: string` — free-form note (e.g. `"follow PV peak"`, `"§14a DR event"`).
+- `estimatedSavings?: ApplianceForecastEstimatedSavings` — see below.
+
+```typescript
+interface ApplianceForecastEstimatedSavings {
+    costSavings: number;            // positive = savings, negative = extra cost (in `currency`)
+    currency: string;               // ISO 4217 code
+    co2SavingsGrams?: number;
+    selfConsumptionGainWh?: number;
+    note?: string;                  // e.g. "vs. flat-tariff baseline"
+}
+```
+
+### ChargerForecast
+
+Relative phase / power schedule that mirrors an OCPP TxProfile but adds explicit `numberOfPhases` (1 / 2 / 3).
+
+```typescript
+import { ChargerForecast } from '@enyo-energy/energy-app-sdk';
+
+const forecast: ChargerForecast = {
+    relativeSchedule: [
+        // Right now: 11 kW across three phases
+        { seconds: 0,    powerW: 11_000, numberOfPhases: 3 },
+        // In 30 minutes: derate to 3.7 kW on one phase
+        { seconds: 1800, powerW:  3_700, numberOfPhases: 1 },
+        // In one hour: pause
+        { seconds: 3600, powerW:  0                       },
+    ],
+    estimatedSavings: { costSavings: 0.42, currency: 'EUR', co2SavingsGrams: 120 },
+    reason: 'follow PV peak',
+};
+
+await forecasts.publishChargerForecast('charger-1', forecast);
+```
+
+Per-entry invariants:
+
+- `seconds`: finite, non-negative; first entry `= 0`; subsequent entries strictly increasing.
+- `powerW`: finite, non-negative (`0` means "pause").
+- `numberOfPhases`: optional; if set, must be `1`, `2`, or `3`.
+
+### BatteryCommandForecast
+
+Relative `{seconds, mode, powerW}` schedule where `mode` is one of `'charge'`, `'discharge'`, or `'auto'`. `auto` returns control to the appliance and must always carry `powerW = 0`.
+
+The type is named `BatteryCommandForecast` to make the distinction with the existing [`BatteryForecast`](#batteryforecast) class (which forecasts state-of-charge from history) explicit.
+
+```typescript
+import {
+    BatteryCommandForecast,
+    BatteryCommandForecastModeEnum,
+} from '@enyo-energy/energy-app-sdk';
+
+const forecast: BatteryCommandForecast = {
+    relativeSchedule: [
+        { seconds: 0,    mode: BatteryCommandForecastModeEnum.Charge,    powerW: 3000 },
+        { seconds: 1800, mode: BatteryCommandForecastModeEnum.Discharge, powerW: 2500 },
+        { seconds: 3600, mode: BatteryCommandForecastModeEnum.Auto,      powerW: 0    },
+    ],
+    estimatedSavings: { costSavings: 0.18, currency: 'EUR' },
+};
+
+await forecasts.publishBatteryForecast('battery-1', forecast);
+```
+
+Per-entry invariants:
+
+- `seconds`: finite, non-negative; first entry `= 0`; subsequent entries strictly increasing.
+- `mode`: one of `charge` / `discharge` / `auto`.
+- `powerW`: finite, non-negative. **MUST be `0` when `mode === 'auto'`.**
+
+### HeatpumpForecast
+
+The heatpump payload can carry any combination of the four supported command families in one call — at least one must be present and non-empty. Each command family also accepts its own forecasted temperature trajectory so subscribers can reason about the plan and its expected outcome together.
+
+```typescript
+import { HeatpumpForecast } from '@enyo-energy/energy-app-sdk';
+
+const forecast: HeatpumpForecast = {
+    // ----- DHW boost -----
+    dhwBoosts: [
+        { startIso: '2026-06-10T13:00:00.000Z', endIso: '2026-06-10T15:00:00.000Z', targetTemperatureC: 60 },
+    ],
+    dhwTemperatureForecast: [
+        { timestampIso: '2026-06-10T12:00:00.000Z', temperatureC: 48 },
+        { timestampIso: '2026-06-10T13:00:00.000Z', temperatureC: 52 },
+        { timestampIso: '2026-06-10T15:00:00.000Z', temperatureC: 60 },
+    ],
+
+    // ----- Room pre-heating (per heating circuit) -----
+    roomPreHeatings: [
+        { startIso: '2026-06-10T05:00:00.000Z', endIso: '2026-06-10T07:00:00.000Z', targetTemperatureC: 22, circuitIndex: 0 },
+    ],
+    roomTemperatureForecast: [
+        { timestampIso: '2026-06-10T05:00:00.000Z', temperatureC: 19 },
+        { timestampIso: '2026-06-10T07:00:00.000Z', temperatureC: 22 },
+    ],
+
+    // ----- Buffer-tank boost -----
+    bufferTankBoosts: [
+        { startIso: '2026-06-10T13:00:00.000Z', endIso: '2026-06-10T14:00:00.000Z', targetTemperatureC: 55 },
+    ],
+    bufferTankTemperatureForecast: [
+        { timestampIso: '2026-06-10T13:00:00.000Z', temperatureC: 45 },
+        { timestampIso: '2026-06-10T14:00:00.000Z', temperatureC: 55 },
+    ],
+
+    // ----- Power-announcement schedule (relative) -----
+    powerAnnouncementSchedule: [
+        { seconds: 0,    powerW: 1500 },
+        { seconds: 1800, powerW: 3000 },
+        { seconds: 3600, powerW: 0    },
+    ],
+
+    estimatedSavings: { costSavings: 1.05, currency: 'EUR', co2SavingsGrams: 320 },
+    reason: 'soak PV during 13–15h window',
+};
+
+await forecasts.publishHeatpumpForecast('heatpump-1', forecast);
+```
+
+Per-family invariants:
+
+- **`dhwBoosts` / `bufferTankBoosts`** — each window must satisfy `startIso < endIso`, sorted ascending and non-overlapping, `targetTemperatureC ∈ [0, 100]`.
+- **`roomPreHeatings`** — same shape as the boost windows but `targetTemperatureC ∈ [0, 40]`. Non-overlap is enforced **per `circuitIndex`** so different heating circuits can pre-heat in parallel.
+- **`powerAnnouncementSchedule`** — relative schedule (seconds-since-effective), first entry at `seconds = 0`, strictly increasing thereafter; per-entry `powerW` finite and non-negative.
+- **Temperature trajectories** — strictly increasing `timestampIso`; `temperatureC ∈ [−50, 150]`.
+
+### Validators
+
+The validators that `publish*` runs internally are exported as standalone pure functions so apps can validate forecasts while building them — for instance, to surface user-facing errors in a planning UI before holding the forecast in state.
+
+```typescript
+import {
+    validateChargerForecast,
+    validateBatteryCommandForecast,
+    validateHeatpumpForecast,
+    ApplianceCommandForecastValidationError,
+} from '@enyo-energy/energy-app-sdk';
+
+try {
+    validateHeatpumpForecast(forecast);
+} catch (error) {
+    if (error instanceof ApplianceCommandForecastValidationError) {
+        // surface error.message — it names the offending field / index
+    }
+}
+```
+
+Granular helpers are exported alongside the top-level validators: `validateChargerSchedule`, `validateBatterySchedule`, `validateDhwBoostWindows`, `validateRoomPreHeatingWindows`, `validateBufferTankBoostWindows`, `validatePowerAnnouncementSchedule`, `validateTemperatureForecast`.
+
 ## Examples
 
 ### Basic Energy App

package/dist/cjs/energy-app.cjs

@@ -298,6 +298,15 @@ class EnergyApp {
     useConfigurationManager() {
         return this.energyAppSdk.useConfigurationManager();
     }
+    /**
+     * Gets the Appliance Energy-Manager Forecast API for publishing
+     * forecasted command plans per appliance (charger, battery,
+     * heatpump). The publisher must hold the `EnergyManager` permission.
+     * @returns The Appliance Energy-Manager Forecast API instance
+     */
+    useApplianceEnergyManagerForecast() {
+        return this.energyAppSdk.useApplianceEnergyManagerForecast();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -35,6 +35,7 @@ import { EnergyAppWifi } from "./packages/energy-app-wifi.cjs";
 import { EnergyAppUdp } from "./packages/energy-app-udp.cjs";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.cjs";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
+import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -232,6 +233,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Configuration Manager API instance
      */
     useConfigurationManager(): EnergyAppConfigurationManager;
+    /**
+     * Gets the Appliance Energy-Manager Forecast API for publishing
+     * forecasted command plans per appliance (charger, battery,
+     * heatpump). The publisher must hold the `EnergyManager` permission.
+     * @returns The Appliance Energy-Manager Forecast API instance
+     */
+    useApplianceEnergyManagerForecast(): EnergyAppApplianceEnergyManagerForecast;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -34,6 +34,7 @@ import { EnergyAppWifi } from "./packages/energy-app-wifi.cjs";
 import { EnergyAppUdp } from "./packages/energy-app-udp.cjs";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.cjs";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
+import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -130,4 +131,6 @@ export interface EnyoEnergyAppSdk {
     useGridConnectionPoint: () => EnergyAppGridConnectionPoint;
     /** Get the Configuration Manager API for registering internal (non user-facing) package configurations with change notifications */
     useConfigurationManager: () => EnergyAppConfigurationManager;
+    /** Get the Appliance Energy-Manager Forecast API for publishing forecasted command plans per appliance (charger, battery, heatpump) */
+    useApplianceEnergyManagerForecast: () => EnergyAppApplianceEnergyManagerForecast;
 }

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.cjs

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplianceCommandForecastValidationError = void 0;
+exports.validateChargerForecast = validateChargerForecast;
+exports.validateBatteryCommandForecast = validateBatteryCommandForecast;
+exports.validateHeatpumpForecast = validateHeatpumpForecast;
+exports.validateChargerSchedule = validateChargerSchedule;
+exports.validateBatterySchedule = validateBatterySchedule;
+exports.validateHeatpumpSchedule = validateHeatpumpSchedule;
+exports.validateHeatpumpScheduleEntry = validateHeatpumpScheduleEntry;
+const enyo_appliance_command_forecast_js_1 = require("../../types/enyo-appliance-command-forecast.cjs");
+/**
+ * Thrown when a forecast payload passed to one of the validators (or to
+ * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
+ * and friends) violates the invariants declared on its data interface.
+ *
+ * The message names the offending field / index so callers can surface it
+ * directly to the user.
+ */
+class ApplianceCommandForecastValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApplianceCommandForecastValidationError';
+    }
+}
+exports.ApplianceCommandForecastValidationError = ApplianceCommandForecastValidationError;
+const TEMPERATURE_TRAJECTORY_MIN_C = -50;
+const TEMPERATURE_TRAJECTORY_MAX_C = 150;
+const RESOLUTION_SECONDS = {
+    [enyo_appliance_command_forecast_js_1.ApplianceForecastResolutionEnum.OneMinute]: 60,
+    [enyo_appliance_command_forecast_js_1.ApplianceForecastResolutionEnum.FifteenMinutes]: 900,
+};
+/**
+ * Validates a {@link ChargerForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ */
+function validateChargerForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new ApplianceCommandForecastValidationError('ChargerForecast must be an object.');
+    }
+    validateMetadata(forecast);
+    validateChargerSchedule(forecast.relativeSchedule, forecast.resolution);
+}
+/**
+ * Validates a {@link BatteryCommandForecast}. Throws on the first
+ * violation — the error message names the offending field / index.
+ *
+ * The forecast is a discriminated union on
+ * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
+ * schedule is expected; when `mode = 'schedule'` the embedded
+ * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
+ * by {@link validateBatterySchedule}.
+ */
+function validateBatteryCommandForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new ApplianceCommandForecastValidationError('BatteryCommandForecast must be an object.');
+    }
+    validateMetadata(forecast);
+    const allowedModes = new Set(Object.values(enyo_appliance_command_forecast_js_1.BatteryCommandForecastModeEnum));
+    if (!allowedModes.has(forecast.mode)) {
+        throw new ApplianceCommandForecastValidationError(`BatteryCommandForecast.mode is invalid: ${forecast.mode}.`);
+    }
+    if (forecast.mode === enyo_appliance_command_forecast_js_1.BatteryCommandForecastModeEnum.Auto) {
+        if (forecast.relativeSchedule !== undefined) {
+            throw new ApplianceCommandForecastValidationError("BatteryCommandForecast with mode='auto' must not carry a relativeSchedule.");
+        }
+        return;
+    }
+    validateBatterySchedule(forecast.relativeSchedule, forecast.resolution);
+}
+/**
+ * Validates a {@link HeatpumpForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single unified relative schedule; every entry
+ * is validated by {@link validateHeatpumpScheduleEntry}.
+ */
+function validateHeatpumpForecast(forecast) {
+    if (!forecast || typeof forecast !== 'object') {
+        throw new ApplianceCommandForecastValidationError('HeatpumpForecast must be an object.');
+    }
+    validateMetadata(forecast);
+    validateHeatpumpSchedule(forecast.relativeSchedule, forecast.resolution);
+}
+/**
+ * Validates a charger relative schedule (the inner schedule used by
+ * {@link ChargerForecast.relativeSchedule}). The `resolution` argument
+ * is the value declared on
+ * {@link ApplianceForecastMetadata.resolution}; consecutive entries'
+ * `seconds` must be spaced by exactly that many seconds.
+ */
+function validateChargerSchedule(entries, resolution) {
+    const stepSeconds = resolveResolutionSeconds(resolution);
+    validateNonEmptySchedule(entries, 'relativeSchedule');
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        validateSecondsField(entry.seconds, `relativeSchedule[${i}].seconds`);
+        validatePowerW(entry.powerW, `relativeSchedule[${i}].powerW`);
+        if (entry.numberOfPhases !== undefined && ![1, 2, 3].includes(entry.numberOfPhases)) {
+            throw new ApplianceCommandForecastValidationError(`relativeSchedule[${i}].numberOfPhases must be 1, 2, or 3; got ${entry.numberOfPhases}.`);
+        }
+    }
+    validateFirstEntryStartsAtZero(entries[0].seconds, 'relativeSchedule');
+    validateSecondsMatchResolution(entries.map((e) => e.seconds), stepSeconds, 'relativeSchedule');
+}
+/**
+ * Validates a battery relative schedule (the inner schedule used by
+ * {@link BatteryCommandForecastScheduled.relativeSchedule}). The
+ * `resolution` argument is the value declared on
+ * {@link ApplianceForecastMetadata.resolution}; consecutive entries'
+ * `seconds` must be spaced by exactly that many seconds.
+ */
+function validateBatterySchedule(entries, resolution) {
+    const stepSeconds = resolveResolutionSeconds(resolution);
+    validateNonEmptySchedule(entries, 'relativeSchedule');
+    const allowedDirections = new Set(Object.values(enyo_appliance_command_forecast_js_1.BatteryCommandForecastDirectionEnum));
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        validateSecondsField(entry.seconds, `relativeSchedule[${i}].seconds`);
+        validatePowerW(entry.powerW, `relativeSchedule[${i}].powerW`);
+        if (!allowedDirections.has(entry.direction)) {
+            throw new ApplianceCommandForecastValidationError(`relativeSchedule[${i}].direction is invalid: ${entry.direction}.`);
+        }
+    }
+    validateFirstEntryStartsAtZero(entries[0].seconds, 'relativeSchedule');
+    validateSecondsMatchResolution(entries.map((e) => e.seconds), stepSeconds, 'relativeSchedule');
+}
+/**
+ * Validates a heatpump unified relative schedule (the schedule used by
+ * {@link HeatpumpForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced
+ * by exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on
+ * {@link HeatpumpForecastScheduleEntry}.
+ */
+function validateHeatpumpSchedule(entries, resolution) {
+    const stepSeconds = resolveResolutionSeconds(resolution);
+    validateNonEmptySchedule(entries, 'relativeSchedule');
+    for (let i = 0; i < entries.length; i++) {
+        validateHeatpumpScheduleEntry(entries[i], `relativeSchedule[${i}]`);
+    }
+    validateFirstEntryStartsAtZero(entries[0].seconds, 'relativeSchedule');
+    validateSecondsMatchResolution(entries.map((e) => e.seconds), stepSeconds, 'relativeSchedule');
+}
+/**
+ * Validates a single {@link HeatpumpForecastScheduleEntry}. Used by
+ * {@link validateHeatpumpSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+function validateHeatpumpScheduleEntry(entry, fieldName) {
+    validateSecondsField(entry.seconds, `${fieldName}.seconds`);
+    if (entry.powerW !== undefined) {
+        validatePowerW(entry.powerW, `${fieldName}.powerW`);
+    }
+    validateTemperatureField(entry.dhwTemperatureC, `${fieldName}.dhwTemperatureC`);
+    validateTemperatureField(entry.roomTemperatureC, `${fieldName}.roomTemperatureC`);
+    validateTemperatureField(entry.bufferTankTemperatureC, `${fieldName}.bufferTankTemperatureC`);
+    validateBooleanField(entry.dhwBoostActive, `${fieldName}.dhwBoostActive`);
+    validateBooleanField(entry.roomPreHeatingActive, `${fieldName}.roomPreHeatingActive`);
+    validateBooleanField(entry.bufferTankBoostActive, `${fieldName}.bufferTankBoostActive`);
+}
+function validateMetadata(forecast) {
+    if (!(forecast.resolution in RESOLUTION_SECONDS)) {
+        throw new ApplianceCommandForecastValidationError(`resolution is invalid: ${forecast.resolution}. Allowed values: ${Object.values(enyo_appliance_command_forecast_js_1.ApplianceForecastResolutionEnum).join(', ')}.`);
+    }
+    if (forecast.estimatedSavings !== undefined) {
+        const savings = forecast.estimatedSavings;
+        if (typeof savings.currency !== 'string' || savings.currency.length === 0) {
+            throw new ApplianceCommandForecastValidationError('estimatedSavings.currency must be a non-empty string.');
+        }
+        if (!Number.isFinite(savings.costSavings)) {
+            throw new ApplianceCommandForecastValidationError(`estimatedSavings.costSavings must be a finite number; got ${savings.costSavings}.`);
+        }
+    }
+}
+function resolveResolutionSeconds(resolution) {
+    const step = RESOLUTION_SECONDS[resolution];
+    if (step === undefined) {
+        throw new ApplianceCommandForecastValidationError(`resolution is invalid: ${resolution}. Allowed values: ${Object.values(enyo_appliance_command_forecast_js_1.ApplianceForecastResolutionEnum).join(', ')}.`);
+    }
+    return step;
+}
+function validateNonEmptySchedule(entries, fieldName) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName} must contain at least one entry.`);
+    }
+}
+function validateSecondsField(seconds, fieldName) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}=${seconds} must be a finite non-negative number.`);
+    }
+}
+function validatePowerW(powerW, fieldName) {
+    if (!Number.isFinite(powerW) || powerW < 0) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}=${powerW} must be a finite non-negative number.`);
+    }
+}
+function validateTemperatureField(value, fieldName) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isFinite(value) ||
+        value < TEMPERATURE_TRAJECTORY_MIN_C ||
+        value > TEMPERATURE_TRAJECTORY_MAX_C) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}=${value} is outside the plausible range [${TEMPERATURE_TRAJECTORY_MIN_C}, ${TEMPERATURE_TRAJECTORY_MAX_C}].`);
+    }
+}
+function validateBooleanField(value, fieldName) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== 'boolean') {
+        throw new ApplianceCommandForecastValidationError(`${fieldName} must be a boolean when provided; got ${typeof value}.`);
+    }
+}
+function validateFirstEntryStartsAtZero(firstSeconds, fieldName) {
+    if (firstSeconds !== 0) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}[0].seconds must be 0 (got ${firstSeconds}); the receiving appliance needs an authoritative "right now" setpoint.`);
+    }
+}
+function validateSecondsMatchResolution(secondsList, stepSeconds, fieldName) {
+    for (let i = 1; i < secondsList.length; i++) {
+        const delta = secondsList[i] - secondsList[i - 1];
+        if (delta !== stepSeconds) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}[${i}].seconds (${secondsList[i]}) must be exactly ${stepSeconds}s after the previous entry (${secondsList[i - 1]}); got delta=${delta}s. The forecast's resolution determines the required step.`);
+        }
+    }
+}

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.d.cts

@@ -0,0 +1,67 @@
+import { ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.cjs';
+/**
+ * Thrown when a forecast payload passed to one of the validators (or to
+ * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
+ * and friends) violates the invariants declared on its data interface.
+ *
+ * The message names the offending field / index so callers can surface it
+ * directly to the user.
+ */
+export declare class ApplianceCommandForecastValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a {@link ChargerForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ */
+export declare function validateChargerForecast(forecast: ChargerForecast): void;
+/**
+ * Validates a {@link BatteryCommandForecast}. Throws on the first
+ * violation — the error message names the offending field / index.
+ *
+ * The forecast is a discriminated union on
+ * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
+ * schedule is expected; when `mode = 'schedule'` the embedded
+ * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
+ * by {@link validateBatterySchedule}.
+ */
+export declare function validateBatteryCommandForecast(forecast: BatteryCommandForecast): void;
+/**
+ * Validates a {@link HeatpumpForecast}. Throws on the first violation —
+ * the error message names the offending field / index.
+ *
+ * The forecast carries a single unified relative schedule; every entry
+ * is validated by {@link validateHeatpumpScheduleEntry}.
+ */
+export declare function validateHeatpumpForecast(forecast: HeatpumpForecast): void;
+/**
+ * Validates a charger relative schedule (the inner schedule used by
+ * {@link ChargerForecast.relativeSchedule}). The `resolution` argument
+ * is the value declared on
+ * {@link ApplianceForecastMetadata.resolution}; consecutive entries'
+ * `seconds` must be spaced by exactly that many seconds.
+ */
+export declare function validateChargerSchedule(entries: ChargerForecastScheduleEntry[], resolution: ApplianceForecastResolutionEnum): void;
+/**
+ * Validates a battery relative schedule (the inner schedule used by
+ * {@link BatteryCommandForecastScheduled.relativeSchedule}). The
+ * `resolution` argument is the value declared on
+ * {@link ApplianceForecastMetadata.resolution}; consecutive entries'
+ * `seconds` must be spaced by exactly that many seconds.
+ */
+export declare function validateBatterySchedule(entries: BatteryCommandForecastScheduleEntry[], resolution: ApplianceForecastResolutionEnum): void;
+/**
+ * Validates a heatpump unified relative schedule (the schedule used by
+ * {@link HeatpumpForecast.relativeSchedule}). Enforces that the
+ * schedule is non-empty, starts at `seconds = 0`, has entries spaced
+ * by exactly `resolution`, and that every per-entry value falls in the
+ * plausible range documented on
+ * {@link HeatpumpForecastScheduleEntry}.
+ */
+export declare function validateHeatpumpSchedule(entries: HeatpumpForecastScheduleEntry[], resolution: ApplianceForecastResolutionEnum): void;
+/**
+ * Validates a single {@link HeatpumpForecastScheduleEntry}. Used by
+ * {@link validateHeatpumpSchedule} and exposed for callers that build
+ * entries incrementally.
+ */
+export declare function validateHeatpumpScheduleEntry(entry: HeatpumpForecastScheduleEntry, fieldName: string): void;