@enyo-energy/energy-app-sdk 1.1.0 → 1.3.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
 
@@ -1227,15 +1237,47 @@ Register, retrieve, and manage electricity tariffs. One tariff can be marked as
 ```typescript
 const tariffs = energyApp.useElectricityTariff();
 
-await tariffs.registerTariff({ id: 't1', name: 'Spot 2026', pricePerKwh: 0.21 });
+await tariffs.registerTariff({
+    tariffType: ElectricityTariffTypeEnum.Dynamic,
+    tariffName: 'Spot 2026',
+    vendorName: 'enyo',
+    dynamicTariffData: { currency: 'EUR', gridFeePerKwh: 0.0912 },
+});
 await tariffs.makeDefaultTariff('t1');
 
 const defaultTariff = await tariffs.getDefaultTariff();
 const all = await tariffs.getAllTariffs();
 ```
 
+A tariff can also declare that its grid fee is **dynamic**, state what its prices already include, and
+carry any number of **bonuses** — see [Dynamic Grid Fees & Tariff Bonuses](#dynamic-grid-fees--tariff-bonuses).
+
+Register a listener to be told when any tariff changes — a new default, a changed grid fee link, an
+added or expired bonus all invalidate a previously composed price series:
+
+```typescript
+const listenerId = tariffs.onTariffChanged(async event => {
+    if (event.changeType === EnyoTariffChangeTypeEnum.Removed) return;
+    await recomposePrices(event.tariff);
+});
+// later
+tariffs.offTariffChanged(listenerId);
+```
+
 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.getDynamicGridFees({ 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 +2972,174 @@ 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 tariff, and composes accordingly. A host that silently added
+network charges would double-count for half the providers on the market.
+
+```typescript
+const tariff = await energyApp.useElectricityTariff().getDefaultTariff();
+const fees   = await energyApp.useGridFee().getDynamicGridFees({ fromIso, untilIso });
+const spot   = await energyApp.useEpexSpotPrices().getPrices({ fromIso, untilIso });
+
+const prices = composeElectricityPrices({
+    energyPrices: fromEpexSpotEntries(spot.entries),
+    energyPriceComposition: tariff?.priceComposition,  // ← what the prices already contain
+    gridFees: fees,
+    bonuses: tariff?.bonuses,
+    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 `publishGridFeeWindows()` |
+
+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 tariff
+
+```typescript
+await energyApp.useElectricityTariff().registerTariff({
+    tariffType: ElectricityTariffTypeEnum.Dynamic,
+    tariffName: 'Spot 2026',
+    vendorName: 'enyo',
+    priceComposition: { includesGridFee: false },   // provider returns the bare energy price
+    dynamicTariffData: {
+        currency: 'EUR',
+        gridFeeMode: GridFeeModeEnum.Dynamic,       // read the fee from useGridFee(), don't carry one
+    },
+    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 }],
+        },
+    }],
+});
+```
+
+The tariff declares only *that* its grid fee is time-dependent, never *which* fee applies. **A grid fee
+is not bound to a tariff** — it belongs to the site's grid connection, is registered independently, and
+stays the same whichever supplier the site buys from. That is why `getDynamicGridFees()` takes no
+tariff selector.
+
+`gridFeeMode` defaults to `Static`, so tariffs written before this existed keep working unchanged, and
+`DynamicTariffData.gridFeePerKwh` remains the constant fallback (now deprecated). The declaration is
+available on **all three** tariff shapes — a fixed energy price with time-variable network charges is a
+real product.
+
+If the provider ships all-in prices instead, set `priceComposition.includesGridFee: true` and leave
+`gridFeeMode` alone. Combining it with `Dynamic` is rejected by `validateElectricityTariffPricing()` —
+it is the exact configuration that double-counts.
+
+### 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()` / `validateElectricityTariffPricing()` | catch overlapping windows, negative amounts and double-count configurations 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,22 @@ class EnergyApp {
     useEpexSpotPrices() {
         return this.energyAppSdk.useEpexSpotPrices();
     }
+    /**
+     * Gets the Grid Fee API for publishing time-dependent grid fees (network
+     * charges) and resolving them to a 15-minute series.
+     *
+     * Nothing published here is folded into a price automatically — provider
+     * APIs differ in whether their prices already contain the network charge, so
+     * the app that owns the tariff declares that via the tariff's
+     * `priceComposition` 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,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useEpexSpotPrices(): EnergyAppEpexSpotPrice;
+    /**
+     * Gets the Grid Fee API for publishing time-dependent grid fees (network
+     * charges) and resolving them to a 15-minute series.
+     *
+     * Nothing published here is folded into a price automatically — provider
+     * APIs differ in whether their prices already contain the network charge, so
+     * the app that owns the tariff declares that via the tariff's
+     * `priceComposition` 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/onboarding-v2/onboarding-v2-provider-validators.cjs

@@ -47,14 +47,18 @@ const ANY_MODEL = '*';
 /**
  * A short human-readable label for a guide, for use in messages.
  *
- * Prefers the first translated title, since ids are not required at guide level;
- * falls back to the start variant so a titleless guide is still identifiable.
+ * Prefers {@link EnyoOnboardingV2Guide.name} — it is the handle the author will
+ * search for — then the first translated title, then the start variant, so a
+ * guide with neither a name nor a title is still identifiable.
  *
  * @param guide - The guide to label.
  * @param index - Its position in the answer's `guides` array.
  * @returns A message prefix such as ``guides[2] ("Wallbox über OCPP")``.
  */
 function guideLabel(guide, index) {
+    const name = guide.name?.trim();
+    if (name)
+        return `guides[${index}] ("${name}")`;
     const title = guide.title?.[0]?.value;
     return `guides[${index}] (${title ? `"${title}"` : (guide.startVariant ?? '?')})`;
 }
@@ -122,6 +126,9 @@ function validateOnboardingV2GuidesResult(result, context) {
     }
     // Which guide(s) claimed each binding, so a collision can name both sides.
     const claimedBy = new Map();
+    // Same, for the explicit `name` handles — a duplicate makes an app unable to
+    // say which of the two it means.
+    const namedBy = new Map();
     for (const [i, guide] of result.guides.entries()) {
         const at = guideLabel(guide, i);
         const guideResult = (0, onboarding_v2_validators_js_1.validateOnboardingGuideV2)(guide, context);
@@ -134,6 +141,17 @@ function validateOnboardingV2GuidesResult(result, context) {
         else if (!guide.modelIds?.length) {
             warnings.push(`${at}: no modelIds — this guide applies to every model of "${guide.vendorId}".`);
         }
+        const name = guide.name?.trim();
+        if (name) {
+            const previouslyNamed = namedBy.get(name);
+            if (previouslyNamed) {
+                errors.push(`${at}: name "${name}" is already used by ${previouslyNamed} — ` +
+                    'a name is how an app addresses one specific guide, so two guides cannot share one.');
+            }
+            else {
+                namedBy.set(name, at);
+            }
+        }
         for (const key of bindingKeys(guide)) {
             const previous = claimedBy.get(key);
             if (previous) {

package/dist/cjs/implementations/onboarding-v2/onboarding-v2-validators.cjs

@@ -149,6 +149,7 @@ function validateOnboardingGuideV2(guide, context) {
     validateNetworkScanFlag(guide, warnings);
     validateApplianceBinding(guide, errors, warnings);
     validateUserNotification(guide, warnings);
+    validateGuideName(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -682,6 +683,37 @@ function validateApplianceBinding(guide, errors, warnings) {
             '` guide binds an existing appliance.');
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.name} is usable as a handle.
+ *
+ * The property is optional — a guide that never needs to be addressed does not
+ * need one, and the host falls back to a name derived from the guide's
+ * bindings. But a name that is *present* and blank is worse than absent: it
+ * looks like a handle at the call site and matches nothing, so
+ * `removeOnboardingGuide('')` would silently do nothing. That is an error.
+ *
+ * Whitespace around a name is trimmed by the host before it is compared, so
+ * `" setup "` and `"setup"` are the same handle; a name carrying padding is
+ * only warned about, since it works but will not look like what the author
+ * typed in a log line.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateGuideName(guide, errors, warnings) {
+    if (guide.name === undefined)
+        return;
+    if (typeof guide.name !== 'string' || guide.name.trim() === '') {
+        errors.push('`name` is present but blank — a guide either carries a handle an app can address ' +
+            'it by or omits the property entirely; an empty name matches nothing.');
+        return;
+    }
+    if (guide.name !== guide.name.trim()) {
+        warnings.push(`\`name\` "${guide.name}" has leading or trailing whitespace, which the host trims — ` +
+            'the guide is addressed as `' + guide.name.trim() + '`.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.notifyUser} against the guide's
  * {@link EnyoOnboardingV2Guide.startVariant}.

package/dist/cjs/implementations/pricing/compose-electricity-prices.cjs

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromEnergyPriceEntries = fromEnergyPriceEntries;
+exports.fromEpexSpotEntries = fromEpexSpotEntries;
+exports.resolveTariffBonuses = resolveTariffBonuses;
+exports.composeElectricityPrices = composeElectricityPrices;
+const enyo_price_composition_js_1 = require("../../types/enyo-price-composition.cjs");
+const enyo_price_schedule_js_1 = require("../../types/enyo-price-schedule.cjs");
+const price_schedule_resolver_js_1 = require("./price-schedule-resolver.cjs");
+/**
+ * Adapts a tariff price series from `useElectricityPrices().getPrices()` into
+ * composer input.
+ *
+ * @param entries - Price entries as returned by the electricity prices API
+ * @param direction - Which price to take; defaults to consumption. Feed-in
+ *   entries without a `feedInPricePerKwh` are skipped.
+ * @returns Composable energy price entries
+ */
+function fromEnergyPriceEntries(entries, direction = enyo_price_schedule_js_1.EnyoPriceAppliesToEnum.Consumption) {
+    if (direction === enyo_price_schedule_js_1.EnyoPriceAppliesToEnum.FeedIn) {
+        return entries
+            .filter(entry => entry.feedInPricePerKwh !== undefined)
+            .map(entry => ({ timestampIso: entry.timestampIso, pricePerKwh: entry.feedInPricePerKwh }));
+    }
+    return entries.map(entry => ({
+        timestampIso: entry.timestampIso,
+        pricePerKwh: entry.consumptionPricePerKwh,
+    }));
+}
+/**
+ * Adapts an EPEX SPOT day-ahead series into composer input.
+ *
+ * Spot prices are the raw exchange result and contain neither grid fees nor
+ * levies, taxes or supplier margin — so the tariff's `priceComposition` for such
+ * a series should leave every `includes*` flag `false`.
+ *
+ * @param entries - Spot price entries as returned by the EPEX SPOT price API
+ * @returns Composable energy price entries
+ */
+function fromEpexSpotEntries(entries) {
+    return entries.map(entry => ({ timestampIso: entry.timestampIso, pricePerKwh: entry.pricePerKwh }));
+}
+function appliesToDirection(componentAppliesTo, direction) {
+    return componentAppliesTo === enyo_price_schedule_js_1.EnyoPriceAppliesToEnum.Both || componentAppliesTo === direction;
+}
+/**
+ * Resolves a tariff's bonuses over a time range and combines them per interval
+ * according to the SDK's stacking rule.
+ *
+ * **Stacking rule:** overlapping bonuses add up, unless at least one bonus
+ * covering the interval is {@link EnyoTariffBonus.exclusive} — then the
+ * exclusive bonus with the highest `priority` applies alone (ties are broken by
+ * array order). Bonuses whose `appliesTo` does not match the requested
+ * direction, and intervals outside a bonus's validity window, contribute
+ * nothing.
+ *
+ * @param bonuses - The tariff's bonuses
+ * @param options - Range and direction to resolve for
+ * @returns A map from interval start (ISO) to the total discount and the contributing bonus ids
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolveTariffBonuses(tariff.bonuses ?? [], {
+ *     fromIso: '2026-09-02T00:00:00Z',
+ *     untilIso: '2026-09-03T00:00:00Z',
+ * });
+ * ```
+ */
+function resolveTariffBonuses(bonuses, options) {
+    const direction = options.appliesTo ?? enyo_price_schedule_js_1.EnyoPriceAppliesToEnum.Consumption;
+    const resolved = bonuses
+        .filter(bonus => appliesToDirection(bonus.appliesTo, direction))
+        .map(bonus => {
+        const entries = (0, price_schedule_resolver_js_1.resolvePriceSchedule)(bonus.schedule, {
+            fromIso: options.fromIso,
+            untilIso: options.untilIso,
+            timezone: bonus.timezone,
+            validFromIso: bonus.validFromIso,
+            validUntilIso: bonus.validUntilIso,
+        });
+        const amountByTimestamp = new Map();
+        for (const entry of entries) {
+            if (entry.amountPerKwh > 0) {
+                amountByTimestamp.set(entry.timestampIso, entry.amountPerKwh);
+            }
+        }
+        return { bonus, amountByTimestamp };
+    });
+    const timestamps = new Set();
+    for (const candidate of resolved) {
+        for (const timestampIso of candidate.amountByTimestamp.keys()) {
+            timestamps.add(timestampIso);
+        }
+    }
+    const combined = new Map();
+    for (const timestampIso of timestamps) {
+        const active = resolved.filter(candidate => candidate.amountByTimestamp.has(timestampIso));
+        const exclusive = active.filter(candidate => candidate.bonus.exclusive === true);
+        if (exclusive.length > 0) {
+            const winner = exclusive.reduce((best, candidate) => (candidate.bonus.priority ?? 0) > (best.bonus.priority ?? 0) ? candidate : best);
+            combined.set(timestampIso, {
+                bonusPerKwh: winner.amountByTimestamp.get(timestampIso),
+                appliedBonusIds: [winner.bonus.id],
+            });
+            continue;
+        }
+        combined.set(timestampIso, {
+            bonusPerKwh: active.reduce((sum, candidate) => sum + candidate.amountByTimestamp.get(timestampIso), 0),
+            appliedBonusIds: active.map(candidate => candidate.bonus.id),
+        });
+    }
+    return combined;
+}
+function gridFeeByTimestamp(series) {
+    const map = new Map();
+    for (const entry of series?.entries ?? []) {
+        map.set(entry.timestampIso, entry.feePerKwh);
+    }
+    return map;
+}
+/**
+ * Composes the effective electricity price per 15-minute interval from an energy
+ * price series, a dynamic grid fee and a tariff's bonuses.
+ *
+ * This runs **in the energy app**, never in the host, because only the app knows
+ * what its provider's API already returns: some providers deliver all-in prices
+ * with the network charge baked in, others deliver the pure energy price. Pass
+ * the tariff's `priceComposition` as `energyPriceComposition` and the composer
+ * reports each component without adding one that is already included.
+ *
+ * Every component is reported separately — `gridFeePerKwh` with its
+ * {@link EnyoPriceComponentOriginEnum}, the total `bonusPerKwh` and the
+ * `appliedBonusIds` behind it — so a UI can explain the number and an optimizer
+ * can reason about the parts.
+ *
+ * Entries are produced for the intervals present in `energyPrices`; grid fee and
+ * bonus values are matched by `timestampIso`, and an interval without a matching
+ * fee or bonus simply contributes `0`.
+ *
+ * @param input - Energy prices, what they already include, the grid fee and the bonuses
+ * @returns Composed entries in the order of the input energy prices
+ *
+ * @example
+ * ```typescript
+ * const tariff = await energyApp.useElectricityTariff().getDefaultTariff();
+ * const fees = await energyApp.useGridFee().getDynamicGridFees({fromIso, untilIso});
+ * const spot = await energyApp.useEpexSpotPrices().getPrices({fromIso, untilIso});
+ *
+ * const prices = composeElectricityPrices({
+ *     energyPrices: fromEpexSpotEntries(spot.entries),
+ *     energyPriceComposition: tariff?.priceComposition,
+ *     gridFees: fees,
+ *     bonuses: tariff?.bonuses,
+ *     currency: 'EUR',
+ * });
+ *
+ * const cheapest = prices.reduce((a, b) => (b.effectivePricePerKwh < a.effectivePricePerKwh ? b : a));
+ * ```
+ */
+function composeElectricityPrices(input) {
+    const direction = input.appliesTo ?? enyo_price_schedule_js_1.EnyoPriceAppliesToEnum.Consumption;
+    const gridFeeIncluded = input.energyPriceComposition?.includesGridFee === true;
+    const bonusesIncluded = input.energyPriceComposition?.includesBonuses === true;
+    const gridFeeSeriesApplies = input.gridFees != null && appliesToDirection(input.gridFees.appliesTo, direction);
+    const resolvedGridFees = gridFeeSeriesApplies ? gridFeeByTimestamp(input.gridFees) : new Map();
+    const constantGridFee = !gridFeeSeriesApplies && input.constantGridFeePerKwh !== undefined ? input.constantGridFeePerKwh : undefined;
+    const hasGridFeeSource = gridFeeSeriesApplies || constantGridFee !== undefined;
+    const range = {
+        fromIso: input.energyPrices[0]?.timestampIso,
+        untilIso: input.energyPrices[input.energyPrices.length - 1]?.timestampIso,
+    };
+    const resolvedBonuses = input.bonuses === undefined || input.bonuses.length === 0 || range.fromIso === undefined
+        ? new Map()
+        : resolveTariffBonuses(input.bonuses, {
+            fromIso: range.fromIso,
+            // The last entry starts the final interval, so extend past it.
+            untilIso: new Date(Date.parse(range.untilIso) + 1).toISOString(),
+            appliesTo: direction,
+        });
+    return input.energyPrices.map(entry => {
+        const gridFeePerKwh = hasGridFeeSource
+            ? constantGridFee ?? resolvedGridFees.get(entry.timestampIso) ?? 0
+            : 0;
+        const gridFeeOrigin = !hasGridFeeSource
+            ? enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.NotApplicable
+            : gridFeeIncluded
+                ? enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Included
+                : enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Added;
+        const bonus = resolvedBonuses.get(entry.timestampIso);
+        const bonusPerKwh = bonus?.bonusPerKwh ?? 0;
+        const bonusOrigin = bonus === undefined
+            ? enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.NotApplicable
+            : bonusesIncluded
+                ? enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Included
+                : enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Added;
+        let effectivePricePerKwh = entry.pricePerKwh;
+        if (gridFeeOrigin === enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Added) {
+            effectivePricePerKwh += gridFeePerKwh;
+        }
+        if (bonusOrigin === enyo_price_composition_js_1.EnyoPriceComponentOriginEnum.Added) {
+            effectivePricePerKwh -= bonusPerKwh;
+        }
+        if (input.minEffectivePricePerKwh !== undefined) {
+            effectivePricePerKwh = Math.max(effectivePricePerKwh, input.minEffectivePricePerKwh);
+        }
+        return {
+            timestampIso: entry.timestampIso,
+            energyPricePerKwh: entry.pricePerKwh,
+            gridFeePerKwh,
+            gridFeeOrigin,
+            bonusPerKwh,
+            bonusOrigin,
+            appliedBonusIds: bonus?.appliedBonusIds ?? [],
+            effectivePricePerKwh,
+            currency: input.currency,
+        };
+    });
+}