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

package/dist/cjs/types/enyo-electricity-tariff.d.cts

@@ -1,78 +1,288 @@
+import { EnyoCurrencyEnum } from './enyo-currency.cjs';
+import { ForecastResolutionEnum } from './enyo-forecasting.cjs';
+import { EnyoPriceAppliesToEnum, EnyoPriceSchedule } from './enyo-price-schedule.cjs';
 /**
- * Enum representing the type of electricity tariff pricing model
+ * Which direction of energy flow a tariff prices.
+ *
+ * A site has exactly one tariff per direction: what it pays for energy drawn
+ * from the grid, and what it earns for energy fed back. These are the two slots
+ * the whole tariff API is built around — a tariff is not registered into a list
+ * and later marked default, it is set into one of these two places.
+ *
+ * Deliberately not {@link EnyoPriceAppliesToEnum}, which carries a third member
+ * (`Both`) that a slot cannot be.
  */
-export declare enum ElectricityTariffTypeEnum {
-    /** Fixed price that doesn't change over time */
+export declare enum EnyoTariffDirectionEnum {
+    /** Energy drawn from the grid — what the customer pays. */
+    Consumption = "consumption",
+    /** Energy fed into the grid — what the customer earns. */
+    FeedIn = "feed-in"
+}
+/**
+ * The pricing model a tariff follows.
+ */
+export declare enum EnyoTariffPricingTypeEnum {
+    /** One price that does not change over time. */
     Static = "static",
-    /** Price varies based on time of day (e.g., peak/off-peak) */
+    /** Price varies by time of day, weekday or season (e.g. peak/off-peak). */
     TimeVariable = "time-variable",
-    /** Price changes dynamically based on market conditions */
+    /** Price changes with the market and is published as a dated series. */
     Dynamic = "dynamic"
 }
 /**
- * Pricing data for a static (fixed-price) electricity tariff
+ * A fixed price per kWh, unchanged around the clock.
  */
-export interface StaticTariffData {
-    /** Price per kWh for consumption */
+export interface EnyoStaticTariffPricing {
+    type: EnyoTariffPricingTypeEnum.Static;
+    /** The price per kWh, in the tariff's currency. */
     pricePerKwh: number;
-    /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
-    currency: string;
 }
 /**
- * Pricing data for a dynamic electricity tariff
+ * A price that follows a calendar schedule — HT/NT, weekend rates, seasonal
+ * bands.
+ *
+ * Uses the same {@link EnyoPriceSchedule} as grid fees and bonuses, so it gets
+ * the shared resolver and validator, and so the SDK has one schedule concept
+ * rather than one per feature.
  */
-export interface DynamicTariffData {
-    /** Price per kWh for grid fees */
-    gridFeePerKwh?: number;
-    /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
-    currency: string;
+export interface EnyoTimeVariableTariffPricing {
+    type: EnyoTariffPricingTypeEnum.TimeVariable;
+    /** When each price applies. Amounts are the price per kWh. */
+    schedule: EnyoPriceSchedule;
+    /**
+     * IANA time zone the schedule's wall-clock times are expressed in, e.g.
+     * `'Europe/Berlin'`. Required — price windows are quoted in local time and
+     * must survive daylight-saving transitions.
+     */
+    timezone: string;
 }
 /**
- * A single entry in a time-variable tariff schedule
+ * A market-following price, carried by the published series rather than by the
+ * tariff.
+ *
+ * Has no fields of its own on purpose: everything about a dynamic price is in
+ * the series the owning app publishes with
+ * {@link EnergyAppElectricityTariff.publishPrices}, and there is nothing
+ * meaningful to state up front.
  */
-export interface TimeVariableScheduleEntry {
-    /** Relative start offset (e.g., minutes from start of day) */
-    start: number;
-    /** Price per kWh during this period */
-    pricePerKwh: number;
+export interface EnyoDynamicTariffPricing {
+    type: EnyoTariffPricingTypeEnum.Dynamic;
 }
 /**
- * Pricing data for a time-variable electricity tariff
+ * How a tariff prices energy.
+ *
+ * A discriminated union on {@link EnyoTariffPricingTypeEnum}, so the payload a
+ * pricing model needs is the payload it carries — a `Static` tariff without a
+ * price, or a `Dynamic` one carrying a schedule, does not compile. Narrow it
+ * with `switch (tariff.pricing.type)`.
  */
-export interface TimeVariableTariffData {
-    /** Schedule of time-based price entries */
-    schedule: TimeVariableScheduleEntry[];
-    /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
-    currency: string;
+export type EnyoTariffPricing = EnyoStaticTariffPricing | EnyoTimeVariableTariffPricing | EnyoDynamicTariffPricing;
+/**
+ * A cost component that may or may not already be contained in a published
+ * price.
+ *
+ * Provider APIs differ: some return all-in prices with network charges, levies
+ * and discounts baked in, others return the pure energy price. A consumer must
+ * never add a component that is already there, so the publishing app declares
+ * what its prices contain — see {@link EnyoTariffPriceSeries.includes}.
+ */
+export declare enum EnyoPriceComponentEnum {
+    /** The grid operator's network charge. */
+    GridFee = "grid-fee",
+    /** Taxes and statutory levies. */
+    TaxesAndLevies = "taxes-and-levies",
+    /** Discounts granted on top of the tariff. */
+    Bonuses = "bonuses"
 }
 /**
- * Input data for registering or updating an electricity tariff
+ * A time-dependent discount granted on top of a tariff, expressed in currency
+ * per kWh — for example "5 ct/kWh cheaper between 22:00 and 06:00" or a
+ * promotional rebate that runs for a fixed number of months.
+ *
+ * Not carried by the tariff itself: the app that owns a tariff knows its own
+ * bonuses and either applies them before publishing prices — declaring
+ * {@link EnyoPriceComponentEnum.Bonuses} in
+ * {@link EnyoTariffPriceSeries.includes} — or passes them to
+ * `composeElectricityPrices()` to have them applied and reported separately.
+ *
+ * Amounts in {@link schedule} are positive magnitudes and are **subtracted**
+ * from the price.
+ *
+ * Consumption-quota bonuses ("the first 100 kWh each month are free") are not
+ * expressible here — they require consumption accounting that this model
+ * deliberately does not carry.
  */
-export interface EnyoElectricityTariff {
-    /** Unique identifier for the tariff */
+export interface EnyoTariffBonus {
+    /** Unique identifier of the bonus within its tariff. */
     id: string;
-    /** The pricing model type of this tariff */
-    tariffType: ElectricityTariffTypeEnum;
-    /** Human-readable name of the tariff */
-    tariffName: string;
-    /** Name of the energy vendor/provider */
+    /** Human-readable name shown to the user, e.g. `'Nachtbonus'`. */
+    name: string;
+    /**
+     * When and how much the discount is. Amounts are positive and subtracted
+     * from the price.
+     */
+    schedule: EnyoPriceSchedule;
+    /**
+     * IANA time zone the schedule's wall-clock times are expressed in, e.g.
+     * `'Europe/Berlin'`.
+     */
+    timezone: string;
+    /** Whether the bonus applies to consumption, feed-in, or both. */
+    appliesTo: EnyoPriceAppliesToEnum;
+    /** Optional start of the bonus's validity in ISO format (inclusive). */
+    validFromIso?: string;
+    /** Optional end of the bonus's validity in ISO format (exclusive). */
+    validUntilIso?: string;
+    /**
+     * When `true`, this bonus suppresses every lower-priority bonus in the
+     * intervals it covers instead of stacking with them.
+     */
+    exclusive?: boolean;
+    /**
+     * Ranking used to pick between competing exclusive bonuses — higher wins.
+     * Defaults to `0`.
+     */
+    priority?: number;
+}
+/**
+ * An electricity tariff filling one of the site's two direction slots.
+ *
+ * Carries no identifier: a tariff is addressed by the direction it prices, and
+ * setting one replaces whatever was in that slot. It also carries no grid fee —
+ * a network charge belongs to the site's grid connection and is read from
+ * `useGridFee()` — and no default flag, because occupying a slot *is* being the
+ * tariff in force.
+ */
+export interface EnyoElectricityTariff {
+    /** Human-readable name of the tariff, e.g. `'Tibber Stromvertrag'`. */
+    name: string;
+    /** Name of the energy vendor/provider. */
     vendorName: string;
-    /** Optional ID of the primary meter appliance associated with this tariff */
-    primaryMeterApplianceId?: string;
-    /** Optional static pricing data (relevant when tariffType is Static) */
-    staticTariffData?: StaticTariffData;
-    /** Optional time-variable pricing data (relevant when tariffType is TimeVariable) */
-    timeVariableTariffData?: TimeVariableTariffData;
-    /** Optional dynamic pricing data*/
-    dynamicTariffData?: DynamicTariffData;
-    /** Optional external tariff id for easy identification */
+    /** Currency of every amount in this tariff and in the prices published for it. */
+    currency: EnyoCurrencyEnum;
+    /** How the tariff prices energy. */
+    pricing: EnyoTariffPricing;
+    /**
+     * The owning app's own identifier for this tariff — a contract id, a
+     * product code.
+     *
+     * Optional for the host, which never interprets it, but it is the stable key
+     * an app should compare against to notice that the tariff behind a slot is
+     * no longer the one it published prices for.
+     */
     externalTariffId?: string;
 }
 /**
- * Tariff registration data extended with default indicator.
- * Used in list responses to indicate which tariff is the system default.
+ * A single priced interval.
+ */
+export interface EnyoTariffPriceEntry {
+    /** Start of the interval in ISO format. */
+    timestampIso: string;
+    /** Price per kWh for this interval, in the tariff's currency. */
+    pricePerKwh: number;
+}
+/**
+ * Prices for one direction over a requested range.
+ *
+ * {@link includes} travels with the series rather than with the tariff because
+ * what a price contains is a fact about *that series*: an app may publish pure
+ * energy prices today and all-in prices tomorrow, and a consumer composing a
+ * price must go by what it was actually handed.
+ */
+export interface EnyoTariffPriceSeries {
+    /** Which direction these prices are for. */
+    direction: EnyoTariffDirectionEnum;
+    /** Currency of every amount in {@link entries}. */
+    currency: EnyoCurrencyEnum;
+    /** Always {@link ForecastResolutionEnum.FifteenMinutes} — matches the grid fee and spot price series. */
+    resolution: ForecastResolutionEnum;
+    /**
+     * Cost components already contained in {@link entries}. Empty means the
+     * pure energy price; a component listed here must not be added again.
+     */
+    includes: EnyoPriceComponentEnum[];
+    /** Entries sorted ascending by `timestampIso`. */
+    entries: EnyoTariffPriceEntry[];
+}
+/**
+ * What an app publishes with
+ * {@link EnergyAppElectricityTariff.publishPrices}.
+ *
+ * Carries no currency or resolution: both come from the tariff occupying the
+ * slot, so they cannot disagree with it.
+ */
+export interface EnyoTariffPricePublication {
+    /**
+     * Cost components already applied to {@link entries}. Omitted means the
+     * pure energy price.
+     */
+    includes?: EnyoPriceComponentEnum[];
+    /** The priced intervals. Replaces any previously published interval with the same timestamp. */
+    entries: EnyoTariffPriceEntry[];
+}
+/**
+ * The outcome of a user choosing a tariff.
+ */
+export declare enum EnyoTariffActivationStatusEnum {
+    /** The tariff is set and usable; prices can be published. */
+    Success = "success",
+    /** The user must authenticate with the provider before the tariff works. */
+    AuthenticationRequired = "authentication-required",
+    /** The user must complete an onboarding guide before the tariff works. */
+    OnboardingRequired = "onboarding-required",
+    /** The tariff could not be activated. */
+    Failed = "failed"
+}
+/**
+ * What an app reports back when the user picks its tariff.
+ *
+ * The three non-success states are not failures to be retried — they are
+ * requests for the host to send the user somewhere. Carry the pointer that makes
+ * each actionable, or the host knows only that something is needed and not what.
+ *
+ * When a flow finishes later (an OAuth redirect returns, an onboarding guide
+ * completes), the app calls
+ * {@link EnergyAppElectricityTariff.setTariff} — setting the tariff *is* the
+ * activation signal, so there is nothing else to report.
+ */
+export interface EnyoTariffActivationResult {
+    /** The outcome. */
+    status: EnyoTariffActivationStatusEnum;
+    /**
+     * Where to send the user, when the status is
+     * {@link EnyoTariffActivationStatusEnum.AuthenticationRequired}.
+     */
+    authenticationUrl?: string;
+    /**
+     * Which onboarding guide to run, when the status is
+     * {@link EnyoTariffActivationStatusEnum.OnboardingRequired}. An onboarding
+     * v2 guide id registered by this app.
+     */
+    onboardingGuideId?: string;
+    /**
+     * Human-readable detail, shown to the user on
+     * {@link EnyoTariffActivationStatusEnum.Failed}.
+     */
+    message?: string;
+}
+/**
+ * What happened to a direction slot.
+ */
+export declare enum EnyoTariffChangeTypeEnum {
+    /** A tariff was set into a slot that was empty, or replaced the one in it. */
+    Set = "set",
+    /** The slot was emptied. */
+    Cleared = "cleared"
+}
+/**
+ * Event delivered to listeners registered via
+ * {@link EnergyAppElectricityTariff.onTariffChanged}.
  */
-export interface EnyoElectricityTariffWithDefault extends EnyoElectricityTariff {
-    /** Indicates whether this tariff is the system default */
-    defaultTariff: boolean;
+export interface EnyoTariffChangeEvent {
+    /** What happened. */
+    changeType: EnyoTariffChangeTypeEnum;
+    /** Which slot changed. */
+    direction: EnyoTariffDirectionEnum;
+    /** The tariff now in the slot, or `null` when it was cleared. */
+    tariff: EnyoElectricityTariff | null;
 }

package/dist/cjs/types/enyo-energy-prices.d.cts

@@ -1,11 +1,17 @@
-import { ElectricityTariffTypeEnum } from "./enyo-electricity-tariff.cjs";
+import { EnyoTariffPricingTypeEnum } from "./enyo-electricity-tariff.cjs";
 /**
- * Represents complete energy tariff information
+ * Represents complete energy tariff information carried on the data bus by
+ * `EnergyTariffUpdateV1`.
+ *
+ * Predates {@link EnergyAppElectricityTariff.publishPrices}, which is the
+ * supported way to publish prices for a tariff slot. This shape still carries a
+ * `tariffId`, a concept the tariff API no longer has — the two are not
+ * interchangeable, and new code should publish through the tariff API.
  */
 export interface EnyoEnergyPrices {
     /** Unique identifier for this tariff */
     tariffId: string;
-    type: ElectricityTariffTypeEnum;
+    type: EnyoTariffPricingTypeEnum;
     /** Pricing data structure */
     prices: EnyoEnergyPriceEntry[];
 }

package/dist/cjs/types/enyo-grid-fee.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoGridFeeChangeTypeEnum = exports.EnyoGridFeeTypeEnum = void 0;
+/**
+ * Whether the grid fee that applies to a site is one number or a time-dependent
+ * series.
+ */
+var EnyoGridFeeTypeEnum;
+(function (EnyoGridFeeTypeEnum) {
+    /** One constant charge that applies around the clock. */
+    EnyoGridFeeTypeEnum["Static"] = "static";
+    /** The charge varies by time of day, weekday or season (e.g. HT/NT). */
+    EnyoGridFeeTypeEnum["Dynamic"] = "dynamic";
+})(EnyoGridFeeTypeEnum || (exports.EnyoGridFeeTypeEnum = EnyoGridFeeTypeEnum = {}));
+/**
+ * What happened to a grid fee registration.
+ */
+var EnyoGridFeeChangeTypeEnum;
+(function (EnyoGridFeeChangeTypeEnum) {
+    /** A grid fee was registered where the site had none. */
+    EnyoGridFeeChangeTypeEnum["Registered"] = "registered";
+    /** The site's existing grid fee was replaced. */
+    EnyoGridFeeChangeTypeEnum["Updated"] = "updated";
+    /** A grid fee was removed. */
+    EnyoGridFeeChangeTypeEnum["Removed"] = "removed";
+})(EnyoGridFeeChangeTypeEnum || (exports.EnyoGridFeeChangeTypeEnum = EnyoGridFeeChangeTypeEnum = {}));

package/dist/cjs/types/enyo-grid-fee.d.cts

@@ -0,0 +1,247 @@
+import { EnyoCurrencyEnum } from './enyo-currency.cjs';
+import { ForecastResolutionEnum } from './enyo-forecasting.cjs';
+import { EnyoPriceAppliesToEnum, EnyoPriceSchedule } from './enyo-price-schedule.cjs';
+/**
+ * A registered dynamic grid fee (network charge).
+ *
+ * A grid fee is the component of the electricity price the grid operator (DSO)
+ * charges for transporting the energy. Historically it was a single constant
+ * ct/kWh value; with time-variable network charges (e.g. §14a EnWG module 3 in
+ * Germany) it varies by time of day, weekday and season, and grid operators
+ * increasingly publish it as a dated series.
+ *
+ * A fee registered here is **not** automatically applied to any price. It is
+ * published so that energy apps can read it via
+ * {@link EnergyAppGridFee.getGridFee} and compose the effective electricity
+ * price themselves — see `composeElectricityPrices()`. This is deliberate: some
+ * tariff providers already return grid-fee-inclusive prices from their own API
+ * and must not add the fee a second time.
+ *
+ * Constant and time-dependent fees are the same shape: a flat ct/kWh charge is
+ * a {@link schedule} with one all-day window. There is no mode to declare and
+ * nothing on the tariff side that has to agree with it.
+ */
+export interface EnyoDynamicGridFee {
+    /** Human-readable name, e.g. `'Netzentgelt HT/NT 2026'`. */
+    name: string;
+    /** Name of the grid operator (DSO) that publishes this fee. */
+    gridOperator: string;
+    /** Currency of every amount in {@link schedule}. */
+    currency: EnyoCurrencyEnum;
+    /**
+     * IANA time zone the schedule's wall-clock times are expressed in, e.g.
+     * `'Europe/Berlin'`. Required — network charge windows are published in
+     * local time and must survive daylight-saving transitions.
+     */
+    timezone: string;
+    /** Whether the fee applies to consumption, feed-in, or both. */
+    appliesTo: EnyoPriceAppliesToEnum;
+    /** When and how much the fee is. Amounts are positive and **added** to the energy price. */
+    schedule: EnyoPriceSchedule;
+    /** Optional start of the fee's validity in ISO format (inclusive). */
+    validFromIso?: string;
+    /** Optional end of the fee's validity in ISO format (exclusive). */
+    validUntilIso?: string;
+    /**
+     * Optional metering point this fee was published for (e.g. a German
+     * Marktlokations-ID). Informational only — a site has exactly one grid fee,
+     * so this never selects between fees; it records which metering point the
+     * grid operator quoted it for.
+     */
+    meteringPointId?: string;
+    /**
+     * Fixed charges billed alongside the network charge itself — metering point
+     * operation, concession levy and the like — as a **gross** amount in cent
+     * per kWh.
+     *
+     * Kept separate from {@link schedule} rather than folded into it because it
+     * is a different kind of number: the schedule varies by time of day, this
+     * does not. Consumers decide per call whether to include it — see
+     * `getGridFeeValues()`'s `includeAdditionalFees`.
+     *
+     * Omit when the schedule already accounts for everything the customer pays.
+     */
+    additionalFeesGrossCentPerKwh?: number;
+    /**
+     * Marks the fee as a time-variable network charge under §14a EnWG module 3.
+     * Purely informational — it does not change how the fee is resolved.
+     */
+    moduleThreeCompliant?: boolean;
+    /** When the fee was last registered or updated, in ISO format. Set by the host. */
+    publishedAtIso?: string;
+}
+/**
+ * Registration payload for {@link EnergyAppGridFee.registerGridFee}.
+ *
+ * `publishedAtIso` is assigned by the host and therefore not part of the input.
+ * There is no identifier: a site has exactly one grid fee, and registering
+ * replaces it.
+ */
+export type EnyoDynamicGridFeeRegistration = Omit<EnyoDynamicGridFee, 'publishedAtIso'>;
+/**
+ * Whether the grid fee that applies to a site is one number or a time-dependent
+ * series.
+ */
+export declare enum EnyoGridFeeTypeEnum {
+    /** One constant charge that applies around the clock. */
+    Static = "static",
+    /** The charge varies by time of day, weekday or season (e.g. HT/NT). */
+    Dynamic = "dynamic"
+}
+/**
+ * The grid fee that applies to a site, in the form most callers actually want:
+ * "is it one number or a series, and if it is one number, which?"
+ *
+ * Returned by `getGridFee()`. Read {@link type} first — it decides which of the
+ * two remaining questions is worth asking:
+ *
+ * - {@link EnyoGridFeeTypeEnum.Static}: {@link grossCentPerKwh} holds the whole
+ *   answer. No range query needed.
+ * - {@link EnyoGridFeeTypeEnum.Dynamic}: {@link grossCentPerKwh} is `undefined`
+ *   on purpose — there is no single honest value for an HT/NT charge. Fetch the
+ *   intervals with `getGridFeeValues()`.
+ *
+ * {@link additionalFeesGrossCentPerKwh} applies to both and is reported
+ * separately so a caller can show "network charge" and "other charges" as
+ * distinct lines, or add them together.
+ *
+ * **All amounts here are gross cent per kWh** — VAT included, cent not euro.
+ * This differs from {@link EnyoDynamicGridFee.schedule}, whose `amountPerKwh` is
+ * in whole currency units, because this shape is what gets displayed and
+ * configured while the schedule is what gets registered.
+ */
+export interface EnyoGridFeeInfo {
+    /** Human-readable name, e.g. `'Netzentgelt HT/NT 2026'`. */
+    name: string;
+    /** Name of the grid operator (DSO) that publishes this fee. */
+    gridOperator: string;
+    /** Currency of every amount in this object. */
+    currency: EnyoCurrencyEnum;
+    /** IANA time zone the underlying schedule is expressed in. */
+    timezone: string;
+    /** Whether the fee applies to consumption, feed-in, or both. */
+    appliesTo: EnyoPriceAppliesToEnum;
+    /**
+     * Whether the fee is one constant number or a time-dependent series.
+     * Derived by the host from the registered schedule: a constant schedule, or
+     * one whose windows all carry the same amount and cover the whole day, is
+     * {@link EnyoGridFeeTypeEnum.Static}; anything else is
+     * {@link EnyoGridFeeTypeEnum.Dynamic}.
+     */
+    type: EnyoGridFeeTypeEnum;
+    /**
+     * The network charge as a gross amount in cent per kWh — set when
+     * {@link type} is {@link EnyoGridFeeTypeEnum.Static}, `undefined` when it is
+     * {@link EnyoGridFeeTypeEnum.Dynamic}.
+     *
+     * Excludes {@link additionalFeesGrossCentPerKwh}; add them for the total the
+     * customer pays per kWh.
+     */
+    grossCentPerKwh?: number;
+    /**
+     * Fixed charges billed alongside the network charge — metering point
+     * operation, concession levy and the like — as a gross amount in cent per
+     * kWh. `undefined` when the fee declares none.
+     */
+    additionalFeesGrossCentPerKwh?: number;
+    /** Metering point the grid operator quoted this fee for, when known. */
+    meteringPointId?: string;
+    /** Whether the fee is a §14a EnWG module 3 time-variable network charge. */
+    moduleThreeCompliant?: boolean;
+    /** Start of the fee's validity in ISO format (inclusive), when limited. */
+    validFromIso?: string;
+    /** End of the fee's validity in ISO format (exclusive), when limited. */
+    validUntilIso?: string;
+    /** When the fee was last registered or updated, in ISO format. */
+    publishedAtIso?: string;
+}
+/**
+ * One resolved 15-minute interval of a grid fee.
+ */
+export interface EnyoGridFeeEntry {
+    /** Start of the 15-minute interval in ISO format. */
+    timestampIso: string;
+    /**
+     * The grid fee for this interval as a **gross amount in cent per kWh**,
+     * always `>= 0` and `0` for intervals no window covers.
+     *
+     * Whether this includes the fee's additional charges depends on the
+     * `includeAdditionalFees` flag of the request — see
+     * {@link EnyoGridFeeSeries.includesAdditionalFees}, which reports what was
+     * actually done rather than what was asked for.
+     */
+    grossCentPerKwh: number;
+}
+/**
+ * A grid fee resolved to a flat 15-minute series over a requested range.
+ *
+ * The resolution matches {@link EnergyAppEnergyPrices.getPrices}, so entries can
+ * be zipped with a price series index-by-index once both cover the same range —
+ * but mind the unit: this series is in **gross cent** per kWh while price series
+ * are in whole currency units. `fromGridFeeEntries()` converts.
+ */
+export interface EnyoGridFeeSeries {
+    /** Currency of every amount in {@link entries}. */
+    currency: EnyoCurrencyEnum;
+    /** Always {@link ForecastResolutionEnum.FifteenMinutes} — present for symmetry with other price APIs. */
+    resolution: ForecastResolutionEnum;
+    /** IANA time zone the underlying schedule was resolved in. */
+    timezone: string;
+    /** Direction the fee applies to. */
+    appliesTo: EnyoPriceAppliesToEnum;
+    /**
+     * Whether {@link EnyoGridFeeEntry.grossCentPerKwh} has the fee's additional
+     * charges baked in.
+     *
+     * Reports what happened, not what was requested: asking for additional fees
+     * on a grid fee that declares none yields `false`, so a caller never has to
+     * guess whether a flat total is missing a component.
+     */
+    includesAdditionalFees: boolean;
+    /** Resolved entries sorted ascending by `timestampIso`, without gaps. */
+    entries: EnyoGridFeeEntry[];
+}
+/**
+ * The range to resolve the site's grid fee over, and whether the fee's
+ * additional charges are folded into the resolved amounts.
+ *
+ * Carries no selector: a site has exactly one grid fee, belonging to its grid
+ * connection rather than to a supplier contract, so there is nothing to choose
+ * between.
+ */
+export interface EnyoGridFeeValuesFilter {
+    /** Start of the requested range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the requested range in ISO format (exclusive). */
+    untilIso: string;
+    /**
+     * When `true`, {@link EnyoGridFeeInfo.additionalFeesGrossCentPerKwh} is
+     * added to every resolved interval, so each amount is the full gross charge
+     * per kWh. Defaults to `false` — the network charge alone.
+     *
+     * The result reports what was actually applied in
+     * {@link EnyoGridFeeSeries.includesAdditionalFees}.
+     */
+    includeAdditionalFees?: boolean;
+}
+/**
+ * What happened to a grid fee registration.
+ */
+export declare enum EnyoGridFeeChangeTypeEnum {
+    /** A grid fee was registered where the site had none. */
+    Registered = "registered",
+    /** The site's existing grid fee was replaced. */
+    Updated = "updated",
+    /** A grid fee was removed. */
+    Removed = "removed"
+}
+/**
+ * Event delivered to listeners registered via
+ * {@link EnergyAppGridFee.onGridFeeChanged}.
+ */
+export interface EnyoGridFeeChangeEvent {
+    /** What happened. */
+    changeType: EnyoGridFeeChangeTypeEnum;
+    /** The grid fee after the change, or `null` when it was removed. */
+    gridFee: EnyoDynamicGridFee | null;
+}

package/dist/cjs/types/enyo-price-composition.cjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoPriceComponentOriginEnum = void 0;
+/**
+ * Where a price component in a composed entry came from.
+ */
+var EnyoPriceComponentOriginEnum;
+(function (EnyoPriceComponentOriginEnum) {
+    /** The component was already contained in the energy price series. */
+    EnyoPriceComponentOriginEnum["Included"] = "included";
+    /** The component was added by the composer on top of the energy price. */
+    EnyoPriceComponentOriginEnum["Added"] = "added";
+    /** No such component applies to this interval. */
+    EnyoPriceComponentOriginEnum["NotApplicable"] = "not-applicable";
+})(EnyoPriceComponentOriginEnum || (exports.EnyoPriceComponentOriginEnum = EnyoPriceComponentOriginEnum = {}));