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

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

@@ -1,93 +1,20 @@
-import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode, EnyoStartChargeRequest, EnyoStopChargeRequest } from "../types/enyo-charge.cjs";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.cjs";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
  */
 export interface EnergyAppCharge {
-    /**
-     * Opens a charging session for an appliance and returns it.
-     *
-     * Use this to start a session — not {@link save}. `save` writes whatever
-     * object it is given and offers no uniqueness guarantee, so two
-     * StartTransactions arriving a few milliseconds apart both pass an app-side
-     * "is one already active?" check and create two sessions for one plug-in.
-     * This call is handled by the host, which holds the invariant that an
-     * appliance has at most one active charge.
-     *
-     * **Idempotent.** When a session is already active for the same
-     * `applianceId` + `transactionId`, that session is returned unchanged
-     * rather than a second one being created — a repeated StartTransaction is
-     * safe. A session that is active on the appliance under a *different*
-     * transaction ID is treated as over: the host finalises it with best-effort
-     * end values before opening this one. If it is really the same physical
-     * session continuing under a new transaction ID (a reconnect, a
-     * re-authorization), use {@link addTransactionIdToActiveCharge} instead.
-     *
-     * The returned charge carries its `id`, so the session can be updated and
-     * later stopped without a {@link findActiveCharge} round-trip first.
-     *
-     * **Required permission:** `Charge`.
-     *
-     * @param request - What is known at plug-in time.
-     * @returns Promise resolving to the started session — or the session that
-     *          was already running for this appliance and transaction.
-     *
-     * @example
-     * ```typescript
-     * const charge = await energyApp.useCharge().startCharge({
-     *     applianceId,
-     *     transactionId: ocppTransactionId,
-     *     meterStartValueWh: meterValue,
-     *     connectorId: 1,
-     * });
-     * ```
-     */
-    startCharge: (request: EnyoStartChargeRequest) => Promise<EnyoCharge>;
-    /**
-     * Closes a charging session and returns the final record.
-     *
-     * The host does the arithmetic, and that is the point of this call: it
-     * derives {@link EnyoCharge.totalEnergyKwh} and
-     * {@link EnyoCharge.paidPriceEuroCent} from the session's meter readings
-     * and the electricity tariff in force while the energy flowed, then moves
-     * the session to a terminal status and notifies
-     * {@link listenForChargeStopped}. An app must not price a session itself —
-     * totals computed app-side would differ between apps, and a customer's bill
-     * would depend on which app happened to close the charge.
-     *
-     * Supply readings, not totals: `meterEndValueWh` and, when the charger
-     * reports it, `energyDeliveredWh`. Anything an app writes into
-     * `paidPriceEuroCent` via {@link save} is overwritten here.
-     *
-     * Stopping a session that is already in a terminal status is a no-op and
-     * returns the stored record — a duplicate StopTransaction will not re-price
-     * a finished charge.
-     *
-     * **Required permission:** `Charge`.
-     *
-     * @param chargeId - The session to close, as returned by
-     *   {@link startCharge} or {@link findActiveCharge}.
-     * @param request - How the session ended.
-     * @returns Promise resolving to the final charge record, totals included.
-     *
-     * @example
-     * ```typescript
-     * const finished = await energyApp.useCharge().stopCharge(charge.id, {
-     *     meterEndValueWh: meterValue,
-     *     energyDeliveredWh: stopTransaction.energyWh,
-     * });
-     * console.log(`${finished.totalEnergyKwh} kWh for ${finished.paidPriceEuroCent} ct`);
-     * ```
-     */
-    stopCharge: (chargeId: string, request: EnyoStopChargeRequest) => Promise<EnyoCharge>;
     /**
      * Save or update a charging session in the system.
      *
      * This is a whole-object write for a session that already exists — a
-     * changed vehicle, a corrected reading. Use {@link startCharge} to open a
-     * session and {@link stopCharge} to close one: calling this without a
-     * `chargeId` creates a row with no uniqueness guarantee, and writing
-     * terminal values by hand skips the host's energy and cost calculation.
+     * changed vehicle, a corrected reading. Calling it without a `chargeId`
+     * creates a row with no uniqueness guarantee, so two StartTransactions
+     * arriving a few milliseconds apart both pass an app-side "is one already
+     * active?" check and create two sessions for one plug-in. Writing terminal
+     * values by hand also skips the host's energy and cost calculation, which
+     * is what turns meter readings into {@link EnyoCharge.totalEnergyKwh} and
+     * {@link EnyoCharge.paidPriceEuroCent}.
      */
     save: (charge: Omit<EnyoCharge, 'id'>, chargeId?: string) => Promise<void>;
     /** Get a list of charging sessions with optional filtering */

package/dist/cjs/packages/energy-app-electricity-tariff.d.cts

@@ -1,96 +1,175 @@
-import { EnyoElectricityTariff, EnyoElectricityTariffWithDefault, EnyoTariffChangeEvent } from "../types/enyo-electricity-tariff.cjs";
+import { EnyoElectricityTariff, EnyoTariffActivationResult, EnyoTariffChangeEvent, EnyoTariffDirectionEnum, EnyoTariffPricePublication, EnyoTariffPriceSeries } from "../types/enyo-electricity-tariff.cjs";
 /**
- * Interface for managing electricity tariffs.
- * Provides methods to register, retrieve, and remove electricity tariffs
- * used for energy pricing and consumption calculations.
+ * The time range a price query covers.
+ */
+export interface EnyoTariffPriceRange {
+    /** Start of the requested range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the requested range in ISO format (exclusive). */
+    untilIso: string;
+}
+/**
+ * Interface for reading and supplying the site's electricity tariffs.
+ *
+ * A site has **two tariff slots** — one for consumption, one for feed-in — and
+ * everything here addresses them by {@link EnyoTariffDirectionEnum}. There is no
+ * list of tariffs, no default flag and no tariff id: occupying a slot is what it
+ * means to be the tariff in force.
+ *
+ * Six methods, split by role. A **consumer** asks {@link getTariff} what applies
+ * and {@link getPrices} what it costs, and follows {@link onTariffChanged}. An
+ * **owner** — the app integrating a provider like Tibber or Ostrom — answers
+ * {@link onTariffSelected} when the user picks it, calls {@link setTariff} once
+ * its tariff is usable, and feeds {@link publishPrices} as new prices arrive.
+ *
+ * A tariff carries no grid fee. A network charge belongs to the site's grid
+ * connection, not to the supplier contract — read it from `useGridFee()` and
+ * combine the two with `composeElectricityPrices()`.
+ *
+ * @example
+ * ```typescript
+ * const tariffs = energyApp.useElectricityTariff();
+ *
+ * // Owner: the user picked us in the app UI.
+ * tariffs.onTariffSelected(async direction => {
+ *     if (!await isAuthenticated()) {
+ *         return {
+ *             status: EnyoTariffActivationStatusEnum.AuthenticationRequired,
+ *             authenticationUrl: buildOAuthUrl(direction),
+ *         };
+ *     }
+ *     await tariffs.setTariff(direction, myTariff);
+ *     return {status: EnyoTariffActivationStatusEnum.Success};
+ * });
+ * ```
  */
 export interface EnergyAppElectricityTariff {
     /**
-     * Registers a new electricity tariff or updates an existing one.
-     * Uses upsert logic based on tariffId - if a tariff with the same ID exists,
-     * it will be updated; otherwise, a new tariff will be created.
+     * Returns the tariff currently filling a direction slot, whichever app owns
+     * it, or `null` when the slot is empty.
      *
-     * @param tariff - The tariff registration data including ID, type, name, and vendor
-     * @returns Promise that resolves when the tariff has been registered
-     */
-    registerTariff(tariff: Omit<EnyoElectricityTariff, 'id'>): Promise<EnyoElectricityTariffWithDefault>;
-    /**
-     * Retrieves all registered electricity tariffs.
-     * Each tariff includes a defaultTariff boolean indicating whether
-     * it is the system default tariff.
+     * `null` is a normal answer — a site with no feed-in contract has no feed-in
+     * tariff — and not an error.
      *
-     * @returns Promise that resolves to an array of all registered tariffs with default indicators
+     * @param direction - Which slot to read
+     * @returns Promise resolving to the tariff in that slot, or `null`
      */
-    getAllTariffs(filter?: {
-        myTariffs?: boolean;
-    }): Promise<EnyoElectricityTariffWithDefault[]>;
+    getTariff(direction: EnyoTariffDirectionEnum): Promise<EnyoElectricityTariff | null>;
     /**
-     * Removes an electricity tariff by its ID.
-     * If the tariff does not exist, this operation is a no-op.
+     * Returns prices for one direction over a time range, as a **15-minute
+     * series** — the same resolution `useGridFee().getGridFeeValues()` and
+     * `useEpexSpotPrices().getPrices()` use, so all three zip index-by-index.
      *
-     * @param id - The unique identifier of the tariff to remove
-     * @returns Promise that resolves when the tariff has been removed
-     */
-    removeTariff(id: string): Promise<void>;
-    /**
-     * Requests to make a tariff the default tariff.
+     * The host serves this from what the slot's owning app published with
+     * {@link publishPrices}, so a consumer never has to know which app is behind
+     * the tariff. Returns `null` when the slot is empty or nothing has been
+     * published covering the range.
+     *
+     * Read {@link EnyoTariffPriceSeries.includes} before adding anything to
+     * these prices: a series that already contains the grid fee must not have
+     * one added on top.
      *
-     * @param id - The unique identifier of the tariff
-     * @returns Promise that resolves with the result
+     * @param direction - Which slot to price
+     * @param range - The time range to cover
+     * @returns Promise resolving to the price series, or `null` when none applies
+     *
+     * @example
+     * ```typescript
+     * const prices = await tariffs.getPrices(EnyoTariffDirectionEnum.Consumption, {
+     *     fromIso, untilIso,
+     * });
+     * const needsGridFee = !prices?.includes.includes(EnyoPriceComponentEnum.GridFee);
+     * ```
      */
-    makeDefaultTariff(id: string): Promise<'accepted' | 'rejected'>;
+    getPrices(direction: EnyoTariffDirectionEnum, range: EnyoTariffPriceRange): Promise<EnyoTariffPriceSeries | null>;
     /**
-     * Retrieves the system default tariff information.
-     * Returns the full tariff including pricing data.
+     * Puts this app's tariff into a direction slot, replacing whatever was
+     * there.
+     *
+     * **Calling this is the activation signal.** An app calls it once its tariff
+     * is actually usable — credentials valid, contract fetched — whether that is
+     * immediately when the user selects it or later, when an OAuth redirect
+     * comes back or an onboarding guide completes. There is nothing else to
+     * report afterwards.
+     *
+     * Full replacement is the only write there is: a partial update would let an
+     * app half-change a tariff another app owns. Re-setting an unchanged tariff
+     * is harmless, so an app that refetches its contract on every start can call
+     * this unconditionally.
+     *
+     * The returned {@link EnyoTariffActivationResult} is the host's answer, not
+     * the app's — it reports whether the slot is now live or whether the host
+     * still needs something from the user.
      *
-     * @returns Promise that resolves to the default tariff info, or null if none is configured
+     * Requires the `ElectricityTariff` permission.
+     *
+     * @param direction - Which slot to fill
+     * @param tariff - The tariff and its pricing details
+     * @returns Promise resolving to the activation outcome
      */
-    getDefaultTariff(): Promise<EnyoElectricityTariff | null>;
-    findTariff(filter: {
-        applianceId?: string;
-        tariffId?: string;
-        externalTariffId?: string;
-    }): Promise<EnyoElectricityTariffWithDefault | null>;
+    setTariff(direction: EnyoTariffDirectionEnum, tariff: EnyoElectricityTariff): Promise<EnyoTariffActivationResult>;
     /**
-     * Partially updates an existing electricity tariff.
-     * Only the provided attributes will be modified; all other fields remain unchanged.
+     * Publishes prices for a slot this app owns.
+     *
+     * Push, not pull: providers hand out prices on their own schedule — day-ahead
+     * prices land in the afternoon, and provider APIs are rate-limited — so an
+     * app fetches when it makes sense and publishes what it got. The host serves
+     * those to every {@link getPrices} caller afterwards.
+     *
+     * Entries replace previously published entries with the same timestamp and
+     * leave the rest alone, so republishing a corrected day does not erase the
+     * days around it.
+     *
+     * Declare in {@link EnyoTariffPricePublication.includes} what the prices
+     * already contain. An app that folds the grid fee in before publishing must
+     * say so, or every consumer will add it a second time.
+     *
+     * Fails when this app does not own the slot — only the tariff's owner may
+     * price it.
+     *
+     * Requires the `ElectricityTariff` permission.
      *
-     * @param id - The unique identifier of the tariff to update
-     * @param attributes - A partial set of tariff fields to update (excluding `id`)
-     * @returns Promise that resolves to the full updated tariff with its default indicator
+     * @param direction - Which slot the prices belong to
+     * @param prices - The priced intervals and what they already contain
+     * @returns Promise that resolves once the prices are stored and listeners dispatched
      */
-    updateTariff(id: string, attributes: Partial<Omit<EnyoElectricityTariff, 'id'>>): Promise<EnyoElectricityTariffWithDefault>;
+    publishPrices(direction: EnyoTariffDirectionEnum, prices: EnyoTariffPricePublication): Promise<void>;
     /**
-     * Registers a listener invoked whenever any tariff is registered, updated
-     * or removed, or whenever a different tariff becomes the system default.
+     * Registers the handler the host calls when the user picks this app's tariff
+     * for a direction — "this should be my consumption tariff".
      *
-     * Listeners see changes made by every energy app on the system, not just
-     * this one — filter on {@link EnyoTariffChangeEvent.tariffId} when only one
-     * tariff matters. This is the signal to recompose prices: a changed grid fee
-     * link, an added or expired bonus, or a new default tariff all invalidate a
-     * previously composed price series.
+     * Not a notification: the handler runs the app's activation flow and reports
+     * what it found. Returning
+     * {@link EnyoTariffActivationStatusEnum.AuthenticationRequired} or
+     * {@link EnyoTariffActivationStatusEnum.OnboardingRequired} tells the host to
+     * send the user somewhere, so carry the `authenticationUrl` or
+     * `onboardingGuideId` that makes it actionable. When the flow later
+     * completes, call {@link setTariff} — that is what marks the tariff live.
      *
-     * Requires the `ElectricityTariff` permission.
+     * Returning {@link EnyoTariffActivationStatusEnum.Success} without having
+     * called {@link setTariff} leaves the slot empty; return it only when the
+     * tariff is already set.
      *
-     * @param listener - Callback invoked with the tariff change event
-     * @returns A unique listener id that can be passed to {@link offTariffChanged}
+     * One handler per app. Registering again replaces the previous one.
      *
-     * @example
-     * ```typescript
-     * const listenerId = tariffs.onTariffChanged(async event => {
-     *     if (event.changeType === EnyoTariffChangeTypeEnum.Removed) return;
-     *     await recomposePrices(event.tariff);
-     * });
-     * // later
-     * tariffs.offTariffChanged(listenerId);
-     * ```
+     * @param handler - Called with the direction the user selected this app for
+     * @returns A function that removes the handler when called
      */
-    onTariffChanged(listener: (event: EnyoTariffChangeEvent) => void | Promise<void>): string;
+    onTariffSelected(handler: (direction: EnyoTariffDirectionEnum) => Promise<EnyoTariffActivationResult>): () => void;
     /**
-     * Removes a previously registered tariff change listener. If the listener id
-     * is unknown, this operation is a no-op.
+     * Registers a listener invoked whenever either slot changes — a tariff set,
+     * replaced, or cleared.
+     *
+     * This is the signal to recompose prices. It fires for changes made by every
+     * app, so filter on {@link EnyoTariffChangeEvent.direction} when only one
+     * slot matters, and compare
+     * {@link EnyoElectricityTariff.externalTariffId} against your own to notice
+     * that a slot you were publishing for is now owned by someone else.
+     *
+     * Returns the unsubscribe function directly; calling it twice is a no-op.
      *
-     * @param listenerId - The id returned from {@link onTariffChanged}
+     * @param listener - Callback invoked with the change event
+     * @returns A function that removes this listener when called
      */
-    offTariffChanged(listenerId: string): void;
+    onTariffChanged(listener: (event: EnyoTariffChangeEvent) => void | Promise<void>): () => void;
 }

package/dist/cjs/packages/energy-app-grid-fee.d.cts

@@ -1,33 +1,42 @@
-import { EnyoDynamicGridFee, EnyoDynamicGridFeeFilter, EnyoDynamicGridFeeRegistration, EnyoDynamicGridFeeSeries, EnyoGridFeeChangeEvent } from '../types/enyo-grid-fee.cjs';
-import { EnyoAbsolutePriceWindow } from '../types/enyo-price-schedule.cjs';
+import { EnyoDynamicGridFee, EnyoDynamicGridFeeRegistration, EnyoGridFeeChangeEvent, EnyoGridFeeInfo, EnyoGridFeeSeries, EnyoGridFeeValuesFilter } from '../types/enyo-grid-fee.cjs';
 /**
- * Interface for publishing and consuming dynamic grid fees (network charges).
+ * Interface for publishing and consuming grid fees (network charges).
  *
- * Any energy app can act as a producer by registering a grid fee — typically an
- * app that knows the local grid operator's tariff sheet or fetches a published
- * series — and any energy app can act as a consumer by resolving that fee for a
- * time range with {@link getDynamicGridFees}.
+ * Five methods, split by role. A **producer** — an app that knows the local grid
+ * operator's tariff sheet or fetches a published series — owns
+ * {@link registerGridFee} and {@link removeGridFee}. A **consumer** asks
+ * {@link getGridFee} what applies and {@link getGridFeeValues} for the numbers
+ * over a range, and subscribes with {@link onGridFeeChanged}. Nothing else is
+ * needed, so nothing else is offered.
  *
  * Publishing requires the `GridFeeRegister` permission; consuming requires
  * `GridFeeUse`.
  *
  * A grid fee describes the site's **grid connection**, not a supplier contract:
  * it is registered and resolved independently of any tariff, and the same fee
- * applies whichever supplier the site buys from.
+ * applies whichever supplier the site buys from. This API is the *only* place a
+ * grid fee lives — a tariff declares nothing about how the fee is determined,
+ * so there is no second source to reconcile against.
+ *
+ * **A site has exactly one grid fee.** It has one grid connection, and the
+ * operator of that connection publishes one network charge for it. So nothing
+ * here takes an identifier: registering replaces whatever was there, and reading
+ * needs no selector.
  *
  * **Nothing here is applied to a price automatically.** The host never folds a
  * grid fee into {@link EnergyAppEnergyPrices.getPrices}, because provider APIs
  * differ: some already return grid-fee-inclusive prices, some do not. The app
  * that owns the tariff knows which is the case — it declares it via the
- * tariff's `priceComposition` and composes the effective price itself with
- * `composeElectricityPrices()`.
+ * price series' `includes` list and composes the effective price
+ * itself with `composeElectricityPrices()`. That flag is the one thing a tariff
+ * says about grid fees, and it describes the provider's price feed rather than
+ * the fee.
  *
  * @example
  * ```typescript
  * // Producer: a §14a EnWG module 3 HT/NT network charge
  * const gridFee = energyApp.useGridFee();
  * await gridFee.registerGridFee({
- *     id: 'dso-hd-2026',
  *     name: 'Netzentgelt HT/NT 2026',
  *     gridOperator: 'Netze BW',
  *     currency: EnyoCurrencyEnum.EUR,
@@ -44,7 +53,7 @@ import { EnyoAbsolutePriceWindow } from '../types/enyo-price-schedule.cjs';
  * });
  *
  * // Consumer: resolve it for the next 24 hours
- * const fees = await gridFee.getDynamicGridFees({
+ * const fees = await gridFee.getGridFeeValues({
  *     fromIso: new Date().toISOString(),
  *     untilIso: new Date(Date.now() + 86_400_000).toISOString(),
  * });
@@ -52,130 +61,139 @@ import { EnyoAbsolutePriceWindow } from '../types/enyo-price-schedule.cjs';
  */
 export interface EnergyAppGridFee {
     /**
-     * Registers a new dynamic grid fee or updates an existing one. Uses upsert
-     * logic based on `id` — if a fee with the same id already exists it is
-     * replaced, otherwise a new one is created.
+     * Sets the site's grid fee, replacing whatever was registered before.
      *
-     * Requires the `GridFeeRegister` permission.
+     * Full replacement is the only write there is, and it is enough for every
+     * case — correcting a name, moving to next year's tariff sheet, or
+     * republishing a day-ahead schedule are all "here is the fee now". A partial
+     * update would only add a second way to say the same thing, and a
+     * schedule-only write would let metadata and windows drift apart.
      *
-     * @param registration - The grid fee to register, including its schedule
-     * @returns Promise that resolves to the stored grid fee, including the host-assigned `publishedAtIso`
-     */
-    registerGridFee(registration: EnyoDynamicGridFeeRegistration): Promise<EnyoDynamicGridFee>;
-    /**
-     * Partially updates a registered grid fee. Only the provided attributes are
-     * modified; all other fields remain unchanged.
+     * There is no identifier and no create-versus-update distinction: the site
+     * has one grid connection and therefore one grid fee. Two apps that both
+     * register one will overwrite each other, so an app should only publish a
+     * fee it is actually authoritative for.
      *
      * Requires the `GridFeeRegister` permission.
      *
-     * @param id - The unique identifier of the grid fee to update
-     * @param attributes - A partial set of grid fee fields to update (excluding `id`)
-     * @returns Promise that resolves to the full updated grid fee
+     * @param registration - The complete grid fee, including its schedule
+     * @returns Promise that resolves to the stored grid fee, including the host-assigned `publishedAtIso`
+     *
+     * @example
+     * ```typescript
+     * // Republishing tomorrow's day-ahead windows is the same call.
+     * await gridFee.registerGridFee({...fee, schedule: {
+     *     type: EnyoPriceScheduleTypeEnum.Absolute,
+     *     windows: tomorrowsWindows,
+     * }});
+     * ```
      */
-    updateGridFee(id: string, attributes: Partial<Omit<EnyoDynamicGridFeeRegistration, 'id'>>): Promise<EnyoDynamicGridFee>;
+    registerGridFee(registration: EnyoDynamicGridFeeRegistration): Promise<EnyoDynamicGridFee>;
     /**
-     * Removes a registered grid fee. {@link getDynamicGridFees} resolves to
-     * `null` for it afterwards. If the fee does not exist, this operation is a
-     * no-op.
+     * Removes the site's grid fee. {@link getGridFee} and
+     * {@link getGridFeeValues} resolve to `null` afterwards. If no fee is
+     * registered, this operation is a no-op.
      *
      * Requires the `GridFeeRegister` permission.
      *
-     * @param id - The unique identifier of the grid fee to remove
      * @returns Promise that resolves when the grid fee has been removed
      */
-    removeGridFee(id: string): Promise<void>;
+    removeGridFee(): Promise<void>;
     /**
-     * Retrieves all registered grid fees across all energy apps on the system.
+     * Answers "what grid fee applies here?" in one call.
      *
-     * Requires the `GridFeeUse` permission.
+     * This is the entry point for consuming a grid fee. The returned
+     * {@link EnyoGridFeeInfo} says whether the fee is
+     * {@link EnyoGridFeeTypeEnum.Static static} or
+     * {@link EnyoGridFeeTypeEnum.Dynamic dynamic}, carries the gross cent per
+     * kWh outright when it is static, and reports any additional fixed charges
+     * separately. A static fee needs no second call; a dynamic one is fetched
+     * interval by interval with {@link getGridFeeValues}.
      *
-     * @returns Promise that resolves to an array of all registered grid fees
-     */
-    listGridFees(): Promise<EnyoDynamicGridFee[]>;
-    /**
-     * Retrieves a single registered grid fee by its id, or `null` when no fee
-     * with that id exists.
+     * Takes no arguments — the site has one grid fee, so there is nothing to
+     * select. Returns `null` when none is registered, which is a normal answer
+     * and not an error.
      *
      * Requires the `GridFeeUse` permission.
      *
-     * @param id - The unique identifier of the grid fee
-     * @returns Promise that resolves to the grid fee, or `null`
-     */
-    getGridFee(id: string): Promise<EnyoDynamicGridFee | null>;
-    /**
-     * Replaces the absolute windows of a grid fee whose schedule is
-     * {@link EnyoPriceScheduleTypeEnum.Absolute}. Use this for fees the grid
-     * operator publishes as a dated series (for example day-ahead), where the
-     * schedule changes far more often than the fee's metadata.
-     *
-     * Windows must not overlap and are stored sorted ascending by `startIso`.
-     * Publishing replaces the previously stored windows in full.
+     * @returns Promise resolving to the site's grid fee, or `null` when none is registered
      *
-     * Requires the `GridFeeRegister` permission.
-     *
-     * @param id - The unique identifier of the registered grid fee
-     * @param windows - The complete set of absolute windows to store
-     * @returns Promise that resolves when the windows have been stored and change listeners dispatched
+     * @example
+     * ```typescript
+     * const fee = await gridFee.getGridFee();
+     * if (fee?.type === EnyoGridFeeTypeEnum.Static) {
+     *     show(fee.grossCentPerKwh, fee.additionalFeesGrossCentPerKwh);
+     * } else if (fee) {
+     *     const series = await gridFee.getGridFeeValues({fromIso, untilIso});
+     * }
+     * ```
      */
-    publishGridFeeWindows(id: string, windows: EnyoAbsolutePriceWindow[]): Promise<void>;
+    getGridFee(): Promise<EnyoGridFeeInfo | null>;
     /**
-     * Resolves a dynamic grid fee to a flat **15-minute series** over the
-     * requested range — the same resolution
+     * Resolves the applicable grid fee to a flat **15-minute series** of gross
+     * cent per kWh over the requested range — the same resolution
      * {@link EnergyAppEnergyPrices.getPrices} uses, so both series can be
      * combined interval by interval.
      *
-     * The fee is selected by `gridFeeId` or `meteringPointId`; with no selector
-     * the grid fee that applies to this device is used. Grid fees are **not**
-     * bound to a tariff — a network charge is a property of the grid connection,
-     * and the same fee applies no matter which supplier the site buys from.
-     * Returns `null` when no fee matches the selector.
+     * Works for every fee, static or dynamic: a flat charge resolves to a series
+     * whose entries all carry the same amount, so a caller that only wants
+     * numbers over a range never has to branch on {@link EnyoGridFeeInfo.type}
+     * at all.
      *
-     * Intervals no window covers resolve to `feePerKwh: 0`, and intervals
-     * outside the fee's `validFromIso` / `validUntilIso` window are omitted.
+     * Set `includeAdditionalFees` to fold the fee's fixed charges into every
+     * interval and get the full gross charge per kWh; leave it off for the
+     * network charge alone. The result reports which of the two you got in
+     * {@link EnyoGridFeeSeries.includesAdditionalFees}, so a fee that declares
+     * no additional charges is never mistaken for a total.
+     *
+     * Returns `null` when the site has no grid fee registered. Intervals no
+     * window covers resolve to `0`, and intervals outside the fee's
+     * `validFromIso` / `validUntilIso` window are omitted.
      *
      * Requires the `GridFeeUse` permission.
      *
-     * @param filter - The time range and the selector identifying which fee to resolve
+     * @param filter - The time range and whether to include additional fees
      * @returns Promise that resolves to the 15-minute fee series, or `null` when no fee applies
      *
      * @example
      * ```typescript
-     * const fees = await gridFee.getDynamicGridFees({
-     *     fromIso: '2026-09-02T00:00:00Z',
-     *     untilIso: '2026-09-03T00:00:00Z',
+     * // network charge only
+     * const net = await gridFee.getGridFeeValues({fromIso, untilIso});
+     *
+     * // everything the customer pays per kWh
+     * const total = await gridFee.getGridFeeValues({
+     *     fromIso,
+     *     untilIso,
+     *     includeAdditionalFees: true,
      * });
-     * fees?.entries.forEach(e => console.log(e.timestampIso, e.feePerKwh));
+     * total?.entries.forEach(e => console.log(e.timestampIso, e.grossCentPerKwh));
      * ```
      */
-    getDynamicGridFees(filter: EnyoDynamicGridFeeFilter): Promise<EnyoDynamicGridFeeSeries | null>;
+    getGridFeeValues(filter: EnyoGridFeeValuesFilter): Promise<EnyoGridFeeSeries | null>;
     /**
-     * Registers a listener invoked whenever any grid fee is registered, updated
-     * or removed — including when its absolute windows are republished.
+     * Registers a listener invoked whenever any grid fee is registered, replaced
+     * or removed.
      *
      * Use it to recompute composed prices without polling: a grid operator that
      * publishes a new day-ahead series mid-day changes the cost of every future
      * interval.
      *
+     * Returns the unsubscribe function directly rather than an id to hand back
+     * to a second method — calling it twice is a no-op.
+     *
      * Requires the `GridFeeUse` permission.
      *
      * @param listener - Callback invoked with the change event
-     * @returns A unique listener id that can be passed to {@link offGridFeeChanged}
+     * @returns A function that removes this listener when called
      *
      * @example
      * ```typescript
-     * const id = gridFee.onGridFeeChanged(async event => {
-     *     if (event.gridFeeId === myFeeId) await recomputePrices();
+     * const unsubscribe = gridFee.onGridFeeChanged(async () => {
+     *     await recomputePrices();
      * });
      * // later
-     * gridFee.offGridFeeChanged(id);
+     * unsubscribe();
      * ```
      */
-    onGridFeeChanged(listener: (event: EnyoGridFeeChangeEvent) => void | Promise<void>): string;
-    /**
-     * Removes a previously registered grid fee change listener. If the listener
-     * id is unknown, this operation is a no-op.
-     *
-     * @param listenerId - The id returned from {@link onGridFeeChanged}
-     */
-    offGridFeeChanged(listenerId: string): void;
+    onGridFeeChanged(listener: (event: EnyoGridFeeChangeEvent) => void | Promise<void>): () => void;
 }