@enyo-energy/energy-app-sdk 1.2.0 → 1.4.0

package/README.md

@@ -64,6 +64,14 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [BatteryCommandForecast](#batterycommandforecast)
   - [HeatpumpForecast](#heatpumpforecast)
   - [Validators](#validators)
+- [Dynamic Grid Fees & Tariff Bonuses](#dynamic-grid-fees--tariff-bonuses)
+  - [The rule that shapes this API](#the-rule-that-shapes-this-api)
+  - [Publishing a dynamic grid fee](#publishing-a-dynamic-grid-fee)
+  - [Declaring it on a tariff](#declaring-it-on-a-tariff)
+  - [Multiple bonuses, and how they stack](#multiple-bonuses-and-how-they-stack)
+  - [Reading the result](#reading-the-result)
+  - [Staying current](#staying-current)
+  - [Helpers](#helpers)
 - [Automations](#automations)
   - [The model](#-the-model)
   - [Guide: Energy Manager apps](#-guide-energy-manager-apps)
@@ -170,6 +178,7 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Register a weather / PV / dynamic-price forecast provider | [`useWeatherForecasting()`](#useweatherforecasting-energyappweatherforecasting) / [`usePvForecasting()`](#usepvforecasting-energyapppvforecasting) / [`useDynamicPriceForecast()`](#usedynamicpriceforecast-energyappdynamicpriceforecast) |
 | Read EPEX SPOT wholesale prices (incl. negative-price windows) | [`useEpexSpotPrices()`](#useepexspotprices-energyappepexspotprice) |
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
+| Publish or resolve time-variable grid fees (§14a HT/NT) | [`useGridFee()`](#usegridfee-energyappgridfee) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
 | Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
@@ -357,6 +366,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`PvSystemRegister`** / **`PvSystemUse`**: Register / read PV system configuration
 - **`Savings`**: Publish and read back day-scoped savings reports
 - **`EpexSpotPrices`**: Read EPEX SPOT day-ahead wholesale market prices
+- **`GridFeeRegister`** / **`GridFeeUse`**: Publish / resolve dynamic grid fees (time-variable network charges)
 
 #### Site & Identity Permissions
 
@@ -1222,20 +1232,84 @@ Three things to get right:
 
 #### `useElectricityTariff(): EnergyAppElectricityTariff`
 
-Register, retrieve, and manage electricity tariffs. One tariff can be marked as the system default.
+A site has **two tariff slots** — one for consumption, one for feed-in — and every method addresses
+them by `EnyoTariffDirectionEnum`. There is no tariff list, no default flag and no tariff id:
+occupying a slot is what it means to be the tariff in force.
+
+Consumers read:
 
 ```typescript
 const tariffs = energyApp.useElectricityTariff();
 
-await tariffs.registerTariff({ id: 't1', name: 'Spot 2026', pricePerKwh: 0.21 });
-await tariffs.makeDefaultTariff('t1');
+const tariff = await tariffs.getTariff(EnyoTariffDirectionEnum.Consumption);
+const prices = await tariffs.getPrices(EnyoTariffDirectionEnum.Consumption, { fromIso, untilIso });
+
+// Never add a component the series already contains.
+const needsGridFee = !prices?.includes.includes(EnyoPriceComponentEnum.GridFee);
+```
+
+The app that integrates a provider owns the other side. It answers when the user picks it, sets the
+tariff once it is actually usable, and pushes prices as they arrive:
+
+```typescript
+tariffs.onTariffSelected(async direction => {
+    if (!await isAuthenticated()) {
+        return {
+            status: EnyoTariffActivationStatusEnum.AuthenticationRequired,
+            authenticationUrl: buildOAuthUrl(direction),
+        };
+    }
+    await tariffs.setTariff(direction, {
+        name: 'Spot 2026',
+        vendorName: 'enyo',
+        currency: EnyoCurrencyEnum.EUR,
+        pricing: { type: EnyoTariffPricingTypeEnum.Dynamic },
+        externalTariffId: contract.id,
+    });
+    return { status: EnyoTariffActivationStatusEnum.Success };
+});
+
+await tariffs.publishPrices(EnyoTariffDirectionEnum.Consumption, {
+    includes: [EnyoPriceComponentEnum.GridFee],   // ← we folded the fee in ourselves
+    entries,
+});
+```
+
+**Calling `setTariff` is the activation signal.** Return `AuthenticationRequired` or
+`OnboardingRequired` from the handler to have the host send the user somewhere, and carry the
+`authenticationUrl` / `onboardingGuideId` that makes it actionable; when that flow later completes,
+call `setTariff` and the slot goes live. There is nothing else to report.
+
+Prices are **pushed, not pulled** — providers publish day-ahead prices on their own schedule and
+rate-limit their APIs, so an app fetches when it makes sense and publishes what it got.
 
-const defaultTariff = await tariffs.getDefaultTariff();
-const all = await tariffs.getAllTariffs();
+Listen for slot changes to know when to recompose:
+
+```typescript
+const unsubscribe = tariffs.onTariffChanged(async event => {
+    if (event.direction !== EnyoTariffDirectionEnum.Consumption) return;
+    await recomposePrices(event.tariff);
+});
+// later
+unsubscribe();
 ```
 
+A tariff carries **no grid fee** — see [Dynamic Grid Fees & Tariff Bonuses](#dynamic-grid-fees--tariff-bonuses).
+
 Requires the `ElectricityTariff` permission.
 
+#### `useGridFee(): EnergyAppGridFee`
+
+Publish time-dependent grid fees (network charges) and resolve them to a 15-minute series. See
+[Dynamic Grid Fees & Tariff Bonuses](#dynamic-grid-fees--tariff-bonuses) for the full picture.
+
+```typescript
+const gridFee = energyApp.useGridFee();
+const fees = await gridFee.getGridFeeValues({ fromIso, untilIso });
+```
+
+Publishers need `GridFeeRegister`; consumers need `GridFeeUse`.
+
 #### `useWeatherForecasting(): EnergyAppWeatherForecasting`
 
 Register a weather-forecast provider (e.g. wraps an external API) and / or consume forecasts by zip code or coordinates.
@@ -2930,6 +3004,172 @@ try {
 }
 ```
 
+## Dynamic Grid Fees & Tariff Bonuses
+
+An electricity price is rarely one number. It is the energy price, plus the grid operator's network
+charge, minus whatever discounts the supplier grants. Both of the latter vary over time: §14a EnWG
+module 3 network charges switch between high- and low-tariff windows by time of day, weekday and
+season, and a supplier bonus may run "−5 ct/kWh between 22:00 and 06:00" or for a fixed promotional
+period.
+
+### The rule that shapes this API
+
+**The energy app composes the price. The host never adds anything.**
+
+That is not a stylistic choice. Provider APIs disagree with each other: some already return
+grid-fee-inclusive prices, others return the bare energy price. Only the app that owns the tariff
+knows which — so it *declares* it on the price series it publishes, and composes accordingly. A host
+that silently added network charges would double-count for half the providers on the market.
+
+```typescript
+const series = await energyApp.useElectricityTariff().getPrices(direction, { fromIso, untilIso });
+const fees   = await energyApp.useGridFee().getGridFeeValues({ fromIso, untilIso });
+const spot   = await energyApp.useEpexSpotPrices().getPrices({ fromIso, untilIso });
+
+const prices = composeElectricityPrices({
+    energyPrices: fromEpexSpotEntries(spot.entries),
+    energyPriceComposition: series?.includes,   // ← what the prices already contain
+    gridFees: fromGridFeeEntries(fees),         // ← gross cent → currency units
+    bonuses: myBonuses,
+    currency: 'EUR',
+});
+
+const cheapest = prices.reduce((a, b) => (b.effectivePricePerKwh < a.effectivePricePerKwh ? b : a));
+```
+
+### Publishing a dynamic grid fee
+
+Amounts are always **unsigned magnitudes**: a grid fee is added, a bonus is subtracted. There is no
+signed number to get backwards.
+
+```typescript
+await energyApp.useGridFee().registerGridFee({
+    id: 'dso-hd-2026',
+    name: 'Netzentgelt HT/NT 2026',
+    gridOperator: 'Netze BW',
+    currency: EnyoCurrencyEnum.EUR,
+    timezone: 'Europe/Berlin',          // required — windows are wall-clock, and DST is real
+    appliesTo: EnyoPriceAppliesToEnum.Consumption,
+    moduleThreeCompliant: true,
+    schedule: {
+        type: EnyoPriceScheduleTypeEnum.Recurring,
+        windows: [
+            { startTimeOfDay: '06:00', endTimeOfDay: '22:00', amountPerKwh: 0.0912 },
+            { startTimeOfDay: '22:00', endTimeOfDay: '06:00', amountPerKwh: 0.0431 },
+        ],
+    },
+});
+```
+
+Three schedule types cover what grid operators and suppliers actually publish:
+
+| Type | Use it for |
+|---|---|
+| `Constant` | one amount that never changes |
+| `Recurring` | HT/NT, weekday-dependent and seasonal windows (`daysOfWeek`, `months`) |
+| `Absolute` | dated series, e.g. a day-ahead publication — republish with `registerGridFee()` |
+
+A `Recurring` window may wrap past midnight (`22:00` → `06:00`). When it does, `daysOfWeek` and
+`months` are evaluated against the day the window **starts** — a Monday-only 22:00–06:00 window covers
+Monday evening *and* the early hours of Tuesday.
+
+### Declaring it on a price series
+
+A tariff carries **no grid fee at all**. It is neither a field on the tariff nor something the tariff
+declares a mode for: a network charge belongs to the site's grid connection, is registered
+independently with `useGridFee()`, and stays the same whichever supplier the site buys from. That is
+why `getGridFee()` takes no arguments and `getGridFeeValues()` takes no tariff selector.
+
+What the owning app *does* declare is what its published prices already contain:
+
+```typescript
+await energyApp.useElectricityTariff().publishPrices(EnyoTariffDirectionEnum.Consumption, {
+    includes: [],   // the bare energy price — the consumer adds the grid fee
+    entries,
+});
+```
+
+If the provider ships all-in prices instead, publish `includes: [EnyoPriceComponentEnum.GridFee]` and
+consumers will report the fee without adding it a second time. Declaring an included component you did
+not actually apply is the one mistake that silently under-prices every interval.
+
+Bonuses work the same way — either apply them yourself and declare
+`EnyoPriceComponentEnum.Bonuses`, or hand them to `composeElectricityPrices()` and have them applied
+and reported separately:
+
+```typescript
+const bonuses = [{
+    id: 'night',
+    name: 'Nachtbonus',
+    timezone: 'Europe/Berlin',
+    appliesTo: EnyoPriceAppliesToEnum.Consumption,
+    schedule: {
+        type: EnyoPriceScheduleTypeEnum.Recurring,
+        windows: [{ startTimeOfDay: '22:00', endTimeOfDay: '06:00', amountPerKwh: 0.05 }],
+    },
+}];
+```
+
+### Multiple bonuses, and how they stack
+
+A tariff may carry several bonuses at once. Overlapping bonuses **add up**, unless one of them is
+`exclusive` — then the exclusive bonus with the highest `priority` applies alone.
+
+```typescript
+bonuses: [
+    { id: 'night',  schedule: nightWindow,  /* … */ },                          // −5 ct
+    { id: 'summer', schedule: summerWindow, /* … */ },                          // −2 ct → −7 ct together
+    { id: 'launch', schedule: promo, exclusive: true, priority: 10, /* … */ },  // wins alone where it applies
+]
+```
+
+### Reading the result
+
+Every component is reported separately, so a UI can explain the number and an optimizer can reason
+about its parts:
+
+```typescript
+{
+    timestampIso: '2026-09-02T22:00:00.000Z',
+    energyPricePerKwh: 0.18,
+    gridFeePerKwh: 0.0431,
+    gridFeeOrigin: 'added',        // 'included' when the provider already had it, 'not-applicable' when none
+    bonusPerKwh: 0.05,
+    bonusOrigin: 'added',
+    appliedBonusIds: ['night'],
+    effectivePricePerKwh: 0.1731,
+    currency: 'EUR',
+}
+```
+
+A component flagged `included` is still reported — you can break down an all-in price — but it is never
+added a second time. Effective prices may go negative, because wholesale prices do; pass
+`minEffectivePricePerKwh` only if your use case genuinely needs a floor.
+
+### Staying current
+
+Both sides change under you. Listen to both:
+
+```typescript
+energyApp.useGridFee().onGridFeeChanged(() => recompose());          // new day-ahead fee series
+energyApp.useElectricityTariff().onTariffChanged(() => recompose()); // new default, bonus, or fee link
+```
+
+### Helpers
+
+| Function | Purpose |
+|---|---|
+| `composeElectricityPrices()` | energy price + grid fee − bonuses → effective price, with full breakdown |
+| `fromEnergyPriceEntries()` / `fromEpexSpotEntries()` | adapt the SDK's price shapes into composer input |
+| `resolveTariffBonuses()` | resolve a tariff's bonuses to 15-min intervals, stacking rule applied |
+| `resolvePriceSchedule()` | expand any schedule to a 15-min series (DST-aware, dependency-free) |
+| `validateDynamicGridFee()` / `validateTariffBonuses()` | catch overlapping windows and negative amounts before registering |
+
+### Not covered
+
+Consumption-quota bonuses — "the first 100 kWh each month are free", "1000 free charging kWh per year" —
+are **not** expressible. They need consumption accounting that this model deliberately does not carry.
+
 ## Examples
 
 ### Basic Energy App

package/dist/cjs/energy-app-package-definition.cjs

@@ -18,6 +18,7 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["TemperatureSensor"] = "temperature-sensor";
     EnergyAppPackageCategory["SmartPlug"] = "smart-plug";
     EnergyAppPackageCategory["HeatingRod"] = "heating-rod";
+    EnergyAppPackageCategory["GridOperator"] = "grid-operator";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
 /**

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

@@ -16,6 +16,7 @@ export declare enum EnergyAppPackageCategory {
     TemperatureSensor = "temperature-sensor",
     SmartPlug = "smart-plug",
     HeatingRod = "heating-rod",
+    GridOperator = "grid-operator",
     Other = "other"
 }
 /**

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

@@ -60,4 +60,6 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Savings"] = "Savings";
     EnergyAppPermissionTypeEnum["EpexSpotPrices"] = "EpexSpotPrices";
     EnergyAppPermissionTypeEnum["FirmwareRegistry"] = "FirmwareRegistry";
+    EnergyAppPermissionTypeEnum["GridFeeRegister"] = "GridFeeRegister";
+    EnergyAppPermissionTypeEnum["GridFeeUse"] = "GridFeeUse";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

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

@@ -55,7 +55,9 @@ export declare enum EnergyAppPermissionTypeEnum {
     Automation = "Automation",
     Savings = "Savings",
     EpexSpotPrices = "EpexSpotPrices",
-    FirmwareRegistry = "FirmwareRegistry"
+    FirmwareRegistry = "FirmwareRegistry",
+    GridFeeRegister = "GridFeeRegister",
+    GridFeeUse = "GridFeeUse"
 }
 /**
  * String union of every permission name, derived from

package/dist/cjs/energy-app.cjs

@@ -443,6 +443,28 @@ class EnergyApp {
     useEpexSpotPrices() {
         return this.energyAppSdk.useEpexSpotPrices();
     }
+    /**
+     * Gets the Grid Fee API for publishing grid fees (network charges), asking
+     * which one applies, and resolving it to a 15-minute series.
+     *
+     * This is the single source for grid fees. A network charge belongs to the
+     * site's grid connection rather than to a supplier contract, so a tariff
+     * carries no fee of its own and declares nothing about how one is
+     * determined — constant and time-dependent fees are both registered and read
+     * here.
+     *
+     * Nothing published here is folded into a price automatically — provider
+     * APIs differ in whether their prices already contain the network charge.
+     * The app that owns the tariff declares that one fact via the tariff's
+     * the price series' `includes` and composes the effective price itself
+     * with `composeElectricityPrices()`.
+     * @returns The Grid Fee API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `GridFeeRegister` or
+     *         `GridFeeUse` permission required by the called method is not granted.
+     */
+    useGridFee() {
+        return this.energyAppSdk.useGridFee();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -45,6 +45,7 @@ import { EnergyAppAutomation } from "./packages/energy-app-automation.cjs";
 import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
+import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -366,6 +367,26 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useEpexSpotPrices(): EnergyAppEpexSpotPrice;
+    /**
+     * Gets the Grid Fee API for publishing grid fees (network charges), asking
+     * which one applies, and resolving it to a 15-minute series.
+     *
+     * This is the single source for grid fees. A network charge belongs to the
+     * site's grid connection rather than to a supplier contract, so a tariff
+     * carries no fee of its own and declares nothing about how one is
+     * determined — constant and time-dependent fees are both registered and read
+     * here.
+     *
+     * Nothing published here is folded into a price automatically — provider
+     * APIs differ in whether their prices already contain the network charge.
+     * The app that owns the tariff declares that one fact via the tariff's
+     * the price series' `includes` and composes the effective price itself
+     * with `composeElectricityPrices()`.
+     * @returns The Grid Fee API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `GridFeeRegister` or
+     *         `GridFeeUse` permission required by the called method is not granted.
+     */
+    useGridFee(): EnergyAppGridFee;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -44,6 +44,7 @@ import { EnergyAppAutomation } from "./packages/energy-app-automation.cjs";
 import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
 import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { EnergyAppEpexSpotPrice } from "./packages/energy-app-epex-spot-price.cjs";
+import { EnergyAppGridFee } from "./packages/energy-app-grid-fee.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
@@ -163,4 +164,6 @@ export interface EnyoEnergyAppSdk {
     useDeviceTest: () => EnergyAppDeviceTest;
     /** Get the EPEX SPOT Price API for reading the cleared day-ahead wholesale electricity prices that apply to this device */
     useEpexSpotPrices: () => EnergyAppEpexSpotPrice;
+    /** Get the Grid Fee API for publishing time-dependent network charges and resolving them to a 15-minute series */
+    useGridFee: () => EnergyAppGridFee;
 }

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

@@ -290,12 +290,18 @@ class ApplianceManager {
         const updatedListenerId = applianceService.listenForApplianceUpdated((appliance) => {
             if (this.disposed)
                 return;
+            if (this.config.enableLogging) {
+                console.debug(`Appliance updated event for ${appliance.id}`);
+            }
             this.updateCache(appliance);
         });
         this.listenerIds.push(updatedListenerId);
         const removedListenerId = applianceService.listenForApplianceRemoved((applianceId) => {
             if (this.disposed)
                 return;
+            if (this.config.enableLogging) {
+                console.debug(`Appliance removed event for ${applianceId}`);
+            }
             this.removeFromCache(applianceId);
         });
         this.listenerIds.push(removedListenerId);