@enyo-energy/energy-app-sdk 0.0.183 → 0.0.184

package/README.md

@@ -346,6 +346,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`PvForecastRegister`** / **`PvForecastUse`**: Publish / consume PV forecasts
 - **`DynamicPriceForecastRegister`** / **`DynamicPriceForecastUse`**: Publish / consume dynamic-price forecasts
 - **`PvSystemRegister`** / **`PvSystemUse`**: Register / read PV system configuration
+- **`Savings`**: Publish and read back day-scoped savings reports
 
 #### Site & Identity Permissions
 
@@ -1120,6 +1121,66 @@ diag.energyManagerDiagnostics(
 );
 ```
 
+#### `useSavings(): EnergyAppSavings`
+
+Publish what the energy management saved the customer on a finished day, and read back which days were already reported.
+
+The app settles a day by replaying its **measured** environment through a simulation of the same house running **uncontrolled**, and pricing both worlds against the tariff that actually applied. Publishing is an upsert keyed by `dayIso` + `method`, so a day may be recomputed after a backfill or a bugfix. The platform stores days and owns every aggregation above them (month, year, lifetime) — and excludes `Low` confidence days from those rollups.
+
+```typescript
+const savings = energyApp.useSavings();
+
+// On boot: which days still need settling?
+const { missingDayIsos } = await savings.getDailySavings({
+    startDayIso: '2026-07-01',
+    endDayIso: '2026-07-31'
+});
+
+for (const dayIso of missingDayIsos) {
+    await savings.publishDailySavings({
+        schemaVersion: 1,
+        dayIso,
+        timeZone: 'Europe/Berlin',
+        dayStartUtcMs: startOfLocalDayUtcMs(dayIso),
+        dayEndUtcMs: endOfLocalDayUtcMs(dayIso),   // 23 or 25 h on DST days
+        method: EnyoSavingsMethodEnum.Settled,
+        computedAtIso: new Date().toISOString(),
+        calculatorVersion: '3.2.0',
+        confidence: EnyoSavingsConfidenceEnum.High,
+        confidenceIssues: [],
+        costs: {
+            currency: EnyoCurrencyEnum.EUR,
+            optimizedCost: 1.42,
+            baselineCost: 3.07,
+            savings: 1.65,
+            savingsFromSelfConsumption: 1.12,
+            savingsFromArbitrage: 0.53
+        },
+        energy: { /* both worlds, Wh */ },
+        metrics: { /* both worlds */ },
+        attribution: [
+            { applianceType: EnergyAppApplianceTypeEnum.Charger, savings: 0.91, shiftedEnergyWh: 12400 }
+        ],
+        coverage: [
+            { series: 'pv', source: EnyoSavingsDataSourceEnum.Measured, expectedBuckets: 96, presentBuckets: 96 }
+        ],
+        assumptions: [
+            { key: 'battery.dischargeEfficiency', value: 0.95 }
+        ]
+    });
+}
+```
+
+Notes worth respecting when producing a report:
+
+- **Publish both worlds, never only the delta.** A lone savings number is unauditable and cannot be re-aggregated.
+- **Assumptions travel with the report.** The counterfactual rests on guesses; without them, changing a default silently rewrites history.
+- **`dayIso` is a local calendar date.** The IANA zone and the exact UTC bounds go alongside — anything assuming 96 buckets is wrong twice a year.
+- **Per-slot detail (`slots`) is opt-in.** Settlement is stateless, so the app can regenerate it on demand; only publish it for days under investigation.
+- **Units follow the platform:** energy in Wh, power in W, prices per kWh, currency as `EnyoCurrencyEnum`.
+
+Requires the `Savings` permission.
+
 ### Operational Utilities
 
 #### `useOnboarding(): EnergyAppOnboarding`

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

@@ -50,4 +50,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Udp"] = "Udp";
     EnergyAppPermissionTypeEnum["ProvidedFiles"] = "ProvidedFiles";
     EnergyAppPermissionTypeEnum["Automation"] = "Automation";
+    EnergyAppPermissionTypeEnum["Savings"] = "Savings";
 })(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' | 'Automation';
+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' | 'Savings';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -46,5 +46,6 @@ export declare enum EnergyAppPermissionTypeEnum {
     ChildProcess = "ChildProcess",
     Udp = "Udp",
     ProvidedFiles = "ProvidedFiles",
-    Automation = "Automation"
+    Automation = "Automation",
+    Savings = "Savings"
 }

package/dist/cjs/energy-app.cjs

@@ -352,6 +352,19 @@ class EnergyApp {
     useAutomations() {
         return this.energyAppSdk.useAutomations();
     }
+    /**
+     * Gets the Savings API for publishing day-scoped savings reports and reading
+     * them back. An energy manager app settles a finished day by replaying its
+     * measured environment against an uncontrolled simulation and publishes both
+     * worlds here; the platform stores the days and owns every aggregation above
+     * them (month, year, lifetime).
+     * @returns The Savings API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *         not granted.
+     */
+    useSavings() {
+        return this.energyAppSdk.useSavings();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -39,6 +39,7 @@ import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-a
 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 { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -281,6 +282,17 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         not granted.
      */
     useAutomations(): EnergyAppAutomation;
+    /**
+     * Gets the Savings API for publishing day-scoped savings reports and reading
+     * them back. An energy manager app settles a finished day by replaying its
+     * measured environment against an uncontrolled simulation and publishes both
+     * worlds here; the platform stores the days and owns every aggregation above
+     * them (month, year, lifetime).
+     * @returns The Savings API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *         not granted.
+     */
+    useSavings(): EnergyAppSavings;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -38,6 +38,7 @@ import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-a
 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 { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -145,4 +146,6 @@ export interface EnyoEnergyAppSdk {
     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;
+    /** Get the Savings API for publishing day-scoped savings reports and reading back which days were already reported */
+    useSavings: () => EnergyAppSavings;
 }

package/dist/cjs/index.cjs

@@ -119,6 +119,8 @@ __exportStar(require("./packages/energy-app-battery.cjs"), exports);
 __exportStar(require("./types/enyo-fetch.cjs"), exports);
 __exportStar(require("./types/enyo-file.cjs"), exports);
 __exportStar(require("./packages/energy-app-file.cjs"), exports);
+__exportStar(require("./types/enyo-savings.cjs"), exports);
+__exportStar(require("./packages/energy-app-savings.cjs"), exports);
 __exportStar(require("./types/enyo-automation.cjs"), exports);
 __exportStar(require("./packages/energy-app-automation.cjs"), exports);
 __exportStar(require("./implementations/automation/automation-validators.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -103,6 +103,8 @@ export * from './packages/energy-app-battery.cjs';
 export * from './types/enyo-fetch.cjs';
 export * from './types/enyo-file.cjs';
 export * from './packages/energy-app-file.cjs';
+export * from './types/enyo-savings.cjs';
+export * from './packages/energy-app-savings.cjs';
 export * from './types/enyo-automation.cjs';
 export * from './packages/energy-app-automation.cjs';
 export * from './implementations/automation/automation-validators.cjs';

package/dist/cjs/packages/energy-app-savings.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,126 @@
+import { EnyoDailySavingsReport, EnyoDailySavingsRequest, EnyoDailySavingsResponse } from "../types/enyo-savings.cjs";
+/**
+ * Interface for publishing and reading back day-scoped savings reports.
+ *
+ * An energy manager app replays a finished day's measured environment through a
+ * simulation of the same house running uncontrolled, prices both worlds against
+ * the tariff that actually applied, and publishes the difference here. The
+ * platform stores the day-level records and owns every aggregation above them
+ * (month, year, lifetime) — a device is the wrong place to keep a running annual
+ * figure, because it can be replaced, reset, or offline for a week.
+ *
+ * Publishing is an upsert keyed by {@link EnyoDailySavingsReport.dayIso} plus
+ * {@link EnyoDailySavingsReport.method}, in the same spirit as
+ * {@link EnergyAppFile.registerFile}. This is deliberate: settlement is stateless
+ * and recomputable, so a day may legitimately be recomputed after a backfill, a
+ * bugfix, or a change in assumptions.
+ *
+ * Access to this API requires the `Savings` permission
+ * ({@link EnergyAppPermissionType}); {@link EnergyApp.useSavings} throws when it
+ * has not been granted.
+ *
+ * @example
+ * ```typescript
+ * const savings = energyApp.useSavings();
+ *
+ * // On boot: find the days that still need settling.
+ * const { missingDayIsos } = await savings.getDailySavings({
+ *     startDayIso: '2026-07-01',
+ *     endDayIso: '2026-07-31'
+ * });
+ * for (const dayIso of missingDayIsos) {
+ *     await savings.publishDailySavings(await settleDay(dayIso));
+ * }
+ * ```
+ */
+export interface EnergyAppSavings {
+    /**
+     * Publishes (upserts) the savings report for one day.
+     *
+     * The record is keyed by `report.dayIso` + `report.method`: re-publishing the
+     * same day with the same method replaces the stored record entirely, rather
+     * than appending a second one. Publishing a `Settled` report therefore does
+     * not remove an earlier `Projected` report for the same day — the two are
+     * distinct records and consumers should prefer the settled one.
+     *
+     * The report should carry both worlds, not only the delta: a lone savings
+     * number is unauditable and cannot be re-aggregated.
+     * {@link EnyoDailySavingsReport.confidence} must reflect the state of the
+     * inputs, since the platform excludes low-confidence days from rollups.
+     *
+     * @param report - The complete, self-contained report for one local calendar
+     *   day, including costs, energy terms, coverage and the assumptions the
+     *   counterfactual rested on.
+     * @returns Promise that resolves once the report has been stored by the host.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *   not granted.
+     *
+     * @example
+     * ```typescript
+     * await savings.publishDailySavings({
+     *     schemaVersion: 1,
+     *     dayIso: '2026-07-14',
+     *     timeZone: 'Europe/Berlin',
+     *     dayStartUtcMs: Date.parse('2026-07-14T00:00:00+02:00'),
+     *     dayEndUtcMs: Date.parse('2026-07-15T00:00:00+02:00'),
+     *     method: EnyoSavingsMethodEnum.Settled,
+     *     computedAtIso: '2026-07-15T02:14:03+02:00',
+     *     calculatorVersion: '3.2.0',
+     *     confidence: EnyoSavingsConfidenceEnum.High,
+     *     confidenceIssues: [],
+     *     costs: {
+     *         currency: EnyoCurrencyEnum.EUR,
+     *         optimizedCost: 1.42,
+     *         baselineCost: 3.07,
+     *         savings: 1.65,
+     *         savingsFromSelfConsumption: 1.12,
+     *         savingsFromArbitrage: 0.53
+     *     },
+     *     energy: { ... },
+     *     metrics: { ... },
+     *     attribution: [
+     *         { applianceType: EnergyAppApplianceTypeEnum.Charger, savings: 0.91, shiftedEnergyWh: 12400 }
+     *     ],
+     *     coverage: [
+     *         { series: 'pv', source: EnyoSavingsDataSourceEnum.Measured, expectedBuckets: 96, presentBuckets: 96 }
+     *     ],
+     *     assumptions: [
+     *         { key: 'battery.dischargeEfficiency', value: 0.95 }
+     *     ]
+     * });
+     * ```
+     */
+    publishDailySavings(report: EnyoDailySavingsReport): Promise<void>;
+    /**
+     * Reads back previously published reports for a range of local days.
+     *
+     * This is the counterpart that makes the API usable without duplicated state:
+     * the app asks the host which days it has already reported instead of
+     * maintaining its own shadow index. The response's
+     * {@link EnyoDailySavingsResponse.missingDayIsos} is exactly the backfill
+     * work list.
+     *
+     * Per-slot detail is only returned when it was published AND
+     * {@link EnyoDailySavingsRequest.includeSlots} is set.
+     *
+     * @param request - Inclusive local day range, with optional method filter and
+     *   opt-in per-slot detail.
+     * @returns Promise resolving to the stored reports plus the days in the range
+     *   that carry none.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *   not granted.
+     *
+     * @example
+     * ```typescript
+     * const response = await savings.getDailySavings({
+     *     startDayIso: '2026-07-01',
+     *     endDayIso: '2026-07-07',
+     *     method: EnyoSavingsMethodEnum.Settled
+     * });
+     * const weekTotal = response.reports
+     *     .filter(r => r.confidence === EnyoSavingsConfidenceEnum.High)
+     *     .reduce((sum, r) => sum + r.costs.savings, 0);
+     * ```
+     */
+    getDailySavings(request: EnyoDailySavingsRequest): Promise<EnyoDailySavingsResponse>;
+}

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoSavingsDataSourceEnum = exports.EnyoSavingsIssueCodeEnum = exports.EnyoSavingsConfidenceEnum = exports.EnyoSavingsMethodEnum = void 0;
+/**
+ * How the figures in an {@link EnyoDailySavingsReport} were produced.
+ */
+var EnyoSavingsMethodEnum;
+(function (EnyoSavingsMethodEnum) {
+    /**
+     * Measured day replayed against an uncontrolled simulation, after the fact.
+     *
+     * The environment (PV generation, base load, EV sessions, prices, ...) is
+     * taken from what was actually measured; only the control decisions are
+     * simulated away. This is the authoritative method and the only one that
+     * should feed customer-facing totals.
+     */
+    EnyoSavingsMethodEnum["Settled"] = "Settled";
+    /**
+     * Forward-looking estimate for a day that has not finished yet.
+     *
+     * Both worlds rest on forecasts, so the figure will change until the day is
+     * settled. Consumers should treat a `Projected` report as provisional and
+     * expect it to be replaced by a `Settled` one.
+     */
+    EnyoSavingsMethodEnum["Projected"] = "Projected";
+})(EnyoSavingsMethodEnum || (exports.EnyoSavingsMethodEnum = EnyoSavingsMethodEnum = {}));
+/**
+ * How much trust a consumer may place in a published report.
+ *
+ * Rollups (month, year, lifetime) MUST exclude {@link EnyoSavingsConfidenceEnum.Low}
+ * days. Keeping that rule on the platform side — rather than in every consumer —
+ * is the reason confidence is a first-class field rather than something derived
+ * from {@link EnyoDailySavingsReport.coverage}.
+ */
+var EnyoSavingsConfidenceEnum;
+(function (EnyoSavingsConfidenceEnum) {
+    /** All inputs were complete and the two worlds balanced; safe to aggregate. */
+    EnyoSavingsConfidenceEnum["High"] = "High";
+    /** At least one {@link EnyoSavingsIssue} applies; exclude from rollups. */
+    EnyoSavingsConfidenceEnum["Low"] = "Low";
+})(EnyoSavingsConfidenceEnum || (exports.EnyoSavingsConfidenceEnum = EnyoSavingsConfidenceEnum = {}));
+/**
+ * Machine-readable reason why a report's confidence is not
+ * {@link EnyoSavingsConfidenceEnum.High}.
+ */
+var EnyoSavingsIssueCodeEnum;
+(function (EnyoSavingsIssueCodeEnum) {
+    /** An input series did not cover the whole day. */
+    EnyoSavingsIssueCodeEnum["IncompleteData"] = "IncompleteData";
+    /** The two worlds did not move the same energy — the comparison is not valid. */
+    EnyoSavingsIssueCodeEnum["EnergyImbalance"] = "EnergyImbalance";
+    /** No tariff for (part of) the day; a default price was substituted. */
+    EnyoSavingsIssueCodeEnum["TariffUnavailable"] = "TariffUnavailable";
+    /** PV was curtailed by control, so measured generation understates the roof. */
+    EnyoSavingsIssueCodeEnum["GenerationCurtailed"] = "GenerationCurtailed";
+    /** The day was only partially observed (e.g. commissioning day). */
+    EnyoSavingsIssueCodeEnum["PartialDay"] = "PartialDay";
+})(EnyoSavingsIssueCodeEnum || (exports.EnyoSavingsIssueCodeEnum = EnyoSavingsIssueCodeEnum = {}));
+/**
+ * Origin of one input series used by the calculation, as reported in
+ * {@link EnyoSavingsSeriesCoverage}.
+ */
+var EnyoSavingsDataSourceEnum;
+(function (EnyoSavingsDataSourceEnum) {
+    /** Real measured values from the device / platform timeseries. */
+    EnyoSavingsDataSourceEnum["Measured"] = "Measured";
+    /** Substituted values (defaults, interpolation, a standard load profile). */
+    EnyoSavingsDataSourceEnum["Fallback"] = "Fallback";
+    /** Nothing available — the series contributed no data at all. */
+    EnyoSavingsDataSourceEnum["Missing"] = "Missing";
+})(EnyoSavingsDataSourceEnum || (exports.EnyoSavingsDataSourceEnum = EnyoSavingsDataSourceEnum = {}));