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

package/dist/types/enyo-electricity-tariff.d.ts

@@ -1,3 +1,4 @@
+import { EnyoPriceAppliesToEnum, EnyoPriceSchedule } from './enyo-price-schedule.js';
 /**
  * Enum representing the type of electricity tariff pricing model
  */
@@ -9,10 +10,119 @@ export declare enum ElectricityTariffTypeEnum {
     /** Price changes dynamically based on market conditions */
     Dynamic = "dynamic"
 }
+/**
+ * How the grid fee (network charge) of a tariff is determined.
+ */
+export declare enum GridFeeModeEnum {
+    /**
+     * A single constant fee per kWh, carried by the tariff itself
+     * (see {@link DynamicTariffData.gridFeePerKwh}).
+     */
+    Static = "static",
+    /**
+     * A time-dependent fee, read from the grid fee API with
+     * `useGridFee().getDynamicGridFees()`. The tariff only declares *that* the
+     * fee is time-dependent — which fee applies is a property of the site's grid
+     * connection, not of the tariff.
+     */
+    Dynamic = "dynamic"
+}
+/**
+ * Declares how the grid fee (network charge) that applies alongside a tariff is
+ * determined.
+ *
+ * Mixed into every tariff pricing shape: a fixed energy price combined with
+ * time-variable network charges (e.g. §14a EnWG module 3) is just as real a
+ * product as a spot-market tariff, so the declaration is not exclusive to
+ * dynamic tariffs.
+ *
+ * A grid fee itself is **not** bound to a tariff — it belongs to the site's grid
+ * connection and is registered and resolved through `useGridFee()` independently.
+ * The tariff only says whether its grid fee is a constant it carries itself or a
+ * time-dependent one to be read from that API.
+ *
+ * The grid fee is never applied automatically. Energy apps read the fee and
+ * compose the effective price themselves — see `composeElectricityPrices()`.
+ */
+export interface TariffGridFeeConfig {
+    /**
+     * How the grid fee is determined. Defaults to {@link GridFeeModeEnum.Static}
+     * when omitted, so tariffs registered before this field existed keep their
+     * previous behaviour.
+     *
+     * {@link GridFeeModeEnum.Dynamic} must not be combined with
+     * `priceComposition.includesGridFee === true` — a fee already contained in
+     * the tariff's prices must not be added again.
+     */
+    gridFeeMode?: GridFeeModeEnum;
+}
+/**
+ * Declares which cost components are **already contained** in the prices this
+ * tariff yields.
+ *
+ * Provider APIs differ: some return all-in prices with network charges, levies
+ * and taxes baked in, others return the pure energy price. Consumers must never
+ * add a component that is already included — this declaration is what makes the
+ * difference machine-readable instead of tribal knowledge.
+ *
+ * When omitted, prices are treated as **energy price only**.
+ */
+export interface TariffPriceCompositionInfo {
+    /** `true` when the tariff's prices already contain the grid fee. */
+    includesGridFee: boolean;
+    /** `true` when the tariff's prices already contain taxes and levies. */
+    includesTaxesAndLevies?: boolean;
+    /** `true` when the tariff's prices already have its bonuses applied. */
+    includesBonuses?: boolean;
+}
+/**
+ * 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.
+ *
+ * A tariff may carry several bonuses. 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 EnyoTariffBonus {
+    /** Unique identifier of the bonus within its tariff. */
+    id: string;
+    /** 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;
+}
 /**
  * Pricing data for a static (fixed-price) electricity tariff
  */
-export interface StaticTariffData {
+export interface StaticTariffData extends TariffGridFeeConfig {
     /** Price per kWh for consumption */
     pricePerKwh: number;
     /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
@@ -21,8 +131,15 @@ export interface StaticTariffData {
 /**
  * Pricing data for a dynamic electricity tariff
  */
-export interface DynamicTariffData {
-    /** Price per kWh for grid fees */
+export interface DynamicTariffData extends TariffGridFeeConfig {
+    /**
+     * Constant price per kWh for grid fees.
+     *
+     * @deprecated Set {@link TariffGridFeeConfig.gridFeeMode} to
+     * {@link GridFeeModeEnum.Dynamic} and read the fee from
+     * `useGridFee().getDynamicGridFees()` instead. Still honoured as the
+     * constant fallback while `gridFeeMode` is Static or omitted.
+     */
     gridFeePerKwh?: number;
     /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
     currency: string;
@@ -39,7 +156,7 @@ export interface TimeVariableScheduleEntry {
 /**
  * Pricing data for a time-variable electricity tariff
  */
-export interface TimeVariableTariffData {
+export interface TimeVariableTariffData extends TariffGridFeeConfig {
     /** Schedule of time-based price entries */
     schedule: TimeVariableScheduleEntry[];
     /** Currency code (ISO 4217, e.g., 'EUR', 'USD') */
@@ -67,6 +184,17 @@ export interface EnyoElectricityTariff {
     dynamicTariffData?: DynamicTariffData;
     /** Optional external tariff id for easy identification */
     externalTariffId?: string;
+    /**
+     * Optional declaration of which cost components the tariff's prices already
+     * contain. Omitted means "energy price only".
+     */
+    priceComposition?: TariffPriceCompositionInfo;
+    /**
+     * Optional discounts granted on top of this tariff. Several bonuses may
+     * apply at the same time — overlapping bonuses stack additively unless one
+     * of them is {@link EnyoTariffBonus.exclusive}.
+     */
+    bonuses?: EnyoTariffBonus[];
 }
 /**
  * Tariff registration data extended with default indicator.
@@ -76,3 +204,32 @@ export interface EnyoElectricityTariffWithDefault extends EnyoElectricityTariff
     /** Indicates whether this tariff is the system default */
     defaultTariff: boolean;
 }
+/**
+ * What happened to a tariff registration.
+ */
+export declare enum EnyoTariffChangeTypeEnum {
+    /** A new tariff was registered. */
+    Registered = "registered",
+    /** An existing tariff's attributes, grid fee link or bonuses changed. */
+    Updated = "updated",
+    /** A tariff was removed. */
+    Removed = "removed",
+    /** A different tariff became the system default. */
+    DefaultChanged = "default-changed"
+}
+/**
+ * Event delivered to listeners registered via
+ * {@link EnergyAppElectricityTariff.onTariffChanged}.
+ */
+export interface EnyoTariffChangeEvent {
+    /** What happened. */
+    changeType: EnyoTariffChangeTypeEnum;
+    /** Identifier of the affected tariff. */
+    tariffId: string;
+    /**
+     * The tariff after the change, or `null` when it was removed. For
+     * {@link EnyoTariffChangeTypeEnum.DefaultChanged} this is the tariff that
+     * became the new default.
+     */
+    tariff: EnyoElectricityTariffWithDefault | null;
+}

package/dist/types/enyo-electricity-tariff.js

@@ -10,3 +10,35 @@ export var ElectricityTariffTypeEnum;
     /** Price changes dynamically based on market conditions */
     ElectricityTariffTypeEnum["Dynamic"] = "dynamic";
 })(ElectricityTariffTypeEnum || (ElectricityTariffTypeEnum = {}));
+/**
+ * How the grid fee (network charge) of a tariff is determined.
+ */
+export var GridFeeModeEnum;
+(function (GridFeeModeEnum) {
+    /**
+     * A single constant fee per kWh, carried by the tariff itself
+     * (see {@link DynamicTariffData.gridFeePerKwh}).
+     */
+    GridFeeModeEnum["Static"] = "static";
+    /**
+     * A time-dependent fee, read from the grid fee API with
+     * `useGridFee().getDynamicGridFees()`. The tariff only declares *that* the
+     * fee is time-dependent — which fee applies is a property of the site's grid
+     * connection, not of the tariff.
+     */
+    GridFeeModeEnum["Dynamic"] = "dynamic";
+})(GridFeeModeEnum || (GridFeeModeEnum = {}));
+/**
+ * What happened to a tariff registration.
+ */
+export var EnyoTariffChangeTypeEnum;
+(function (EnyoTariffChangeTypeEnum) {
+    /** A new tariff was registered. */
+    EnyoTariffChangeTypeEnum["Registered"] = "registered";
+    /** An existing tariff's attributes, grid fee link or bonuses changed. */
+    EnyoTariffChangeTypeEnum["Updated"] = "updated";
+    /** A tariff was removed. */
+    EnyoTariffChangeTypeEnum["Removed"] = "removed";
+    /** A different tariff became the system default. */
+    EnyoTariffChangeTypeEnum["DefaultChanged"] = "default-changed";
+})(EnyoTariffChangeTypeEnum || (EnyoTariffChangeTypeEnum = {}));

package/dist/types/enyo-grid-fee.d.ts

@@ -0,0 +1,129 @@
+import { EnyoCurrencyEnum } from './enyo-currency.js';
+import { ForecastResolutionEnum } from './enyo-forecasting.js';
+import { EnyoPriceAppliesToEnum, EnyoPriceSchedule } from './enyo-price-schedule.js';
+/**
+ * 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.getDynamicGridFees} 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.
+ */
+export interface EnyoDynamicGridFee {
+    /** Unique identifier of this grid fee. */
+    id: string;
+    /** 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 is bound to (e.g. a German Marktlokations-ID). */
+    meteringPointId?: string;
+    /**
+     * 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.
+ */
+export type EnyoDynamicGridFeeRegistration = Omit<EnyoDynamicGridFee, 'publishedAtIso'>;
+/**
+ * One resolved 15-minute interval of a dynamic grid fee.
+ */
+export interface EnyoDynamicGridFeeEntry {
+    /** Start of the 15-minute interval in ISO format. */
+    timestampIso: string;
+    /**
+     * Grid fee per kWh for this interval, in the series' currency. Always
+     * `>= 0`; `0` for intervals no window covers.
+     */
+    feePerKwh: number;
+}
+/**
+ * A dynamic 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.
+ */
+export interface EnyoDynamicGridFeeSeries {
+    /** Identifier of the grid fee this series was resolved from. */
+    gridFeeId: string;
+    /** 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;
+    /** Resolved entries sorted ascending by `timestampIso`, without gaps. */
+    entries: EnyoDynamicGridFeeEntry[];
+}
+/**
+ * Selects which grid fee to resolve, and over which range.
+ *
+ * A grid fee belongs to the site's grid connection, not to a supplier contract —
+ * so there is deliberately no tariff selector here. With no selector at all, the
+ * grid fee that applies to this device is resolved.
+ */
+export interface EnyoDynamicGridFeeFilter {
+    /** Start of the requested range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the requested range in ISO format (exclusive). */
+    untilIso: string;
+    /** Resolve this specific grid fee. */
+    gridFeeId?: string;
+    /** Resolve the grid fee registered for this metering point. */
+    meteringPointId?: string;
+}
+/**
+ * What happened to a grid fee registration.
+ */
+export declare enum EnyoGridFeeChangeTypeEnum {
+    /** A new grid fee was registered. */
+    Registered = "registered",
+    /** An existing grid fee's attributes or schedule changed. */
+    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;
+    /** Identifier of the affected grid fee. */
+    gridFeeId: string;
+    /** The grid fee after the change, or `null` when it was removed. */
+    gridFee: EnyoDynamicGridFee | null;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * What happened to a grid fee registration.
+ */
+export var EnyoGridFeeChangeTypeEnum;
+(function (EnyoGridFeeChangeTypeEnum) {
+    /** A new grid fee was registered. */
+    EnyoGridFeeChangeTypeEnum["Registered"] = "registered";
+    /** An existing grid fee's attributes or schedule changed. */
+    EnyoGridFeeChangeTypeEnum["Updated"] = "updated";
+    /** A grid fee was removed. */
+    EnyoGridFeeChangeTypeEnum["Removed"] = "removed";
+})(EnyoGridFeeChangeTypeEnum || (EnyoGridFeeChangeTypeEnum = {}));

package/dist/types/enyo-price-composition.d.ts

@@ -0,0 +1,126 @@
+import { EnyoTariffBonus, TariffPriceCompositionInfo } from './enyo-electricity-tariff.js';
+import { EnyoDynamicGridFeeSeries } from './enyo-grid-fee.js';
+import { EnyoPriceAppliesToEnum } from './enyo-price-schedule.js';
+/**
+ * Where a price component in a composed entry came from.
+ */
+export declare enum EnyoPriceComponentOriginEnum {
+    /** The component was already contained in the energy price series. */
+    Included = "included",
+    /** The component was added by the composer on top of the energy price. */
+    Added = "added",
+    /** No such component applies to this interval. */
+    NotApplicable = "not-applicable"
+}
+/**
+ * A single energy price point fed into
+ * {@link composeElectricityPrices}.
+ *
+ * Deliberately minimal so any source can be used — spot prices from
+ * `useEpexSpotPrices()`, tariff prices from `useElectricityPrices()`, or a
+ * series fetched from the provider's own API. Use
+ * `fromEnergyPriceEntries()` / `fromEpexSpotEntries()` to adapt the SDK's own
+ * shapes.
+ */
+export interface EnyoComposableEnergyPriceEntry {
+    /** Start of the interval in ISO format. */
+    timestampIso: string;
+    /** Energy price per kWh for this interval, in the composition's currency. */
+    pricePerKwh: number;
+}
+/**
+ * Input for {@link composeElectricityPrices}.
+ */
+export interface EnyoComposeElectricityPricesInput {
+    /**
+     * The energy price series to compose on top of. Entries are matched to the
+     * grid fee and bonus series by `timestampIso`, so all inputs should cover
+     * the same range at 15-minute resolution.
+     */
+    energyPrices: EnyoComposableEnergyPriceEntry[];
+    /**
+     * What the {@link energyPrices} already contain, taken from the tariff's
+     * `priceComposition`. Components flagged as included are reported in the
+     * result but **not added again**. Omitted means "energy price only".
+     */
+    energyPriceComposition?: TariffPriceCompositionInfo;
+    /**
+     * The resolved dynamic grid fee series, e.g. from
+     * `useGridFee().getDynamicGridFees()`. Ignored when the energy prices
+     * already include the grid fee, and may be `null` or omitted when the
+     * tariff has no dynamic grid fee.
+     */
+    gridFees?: EnyoDynamicGridFeeSeries | null;
+    /**
+     * A constant grid fee per kWh, used when the tariff carries one instead of
+     * referencing a dynamic fee. Ignored when {@link gridFees} is given or when
+     * the energy prices already include the grid fee.
+     */
+    constantGridFeePerKwh?: number;
+    /**
+     * The tariff's bonuses. Overlapping bonuses stack additively unless one is
+     * {@link EnyoTariffBonus.exclusive}. Ignored when the energy prices already
+     * have bonuses applied.
+     */
+    bonuses?: EnyoTariffBonus[];
+    /**
+     * Which direction to compose for. Components whose `appliesTo` does not
+     * match are skipped. Defaults to {@link EnyoPriceAppliesToEnum.Consumption}.
+     */
+    appliesTo?: EnyoPriceAppliesToEnum;
+    /**
+     * Optional lower bound for {@link EnyoComposedElectricityPriceEntry.effectivePricePerKwh}.
+     * Left unset by default — effective prices may legitimately go negative,
+     * because wholesale prices do.
+     */
+    minEffectivePricePerKwh?: number;
+    /** Currency code carried through to the result, e.g. `'EUR'`. */
+    currency?: string;
+}
+/**
+ * One fully composed 15-minute price interval, with every component reported
+ * separately so a UI can explain the number and an optimizer can reason about
+ * its parts.
+ */
+export interface EnyoComposedElectricityPriceEntry {
+    /** Start of the interval in ISO format. */
+    timestampIso: string;
+    /**
+     * The price taken from the source series for this interval. When the source
+     * was all-in, it already contains the components whose origin is
+     * `included`.
+     */
+    energyPricePerKwh: number;
+    /**
+     * Grid fee per kWh attributable to this interval; `0` when none applies.
+     *
+     * Reported even when {@link gridFeeOrigin} is
+     * {@link EnyoPriceComponentOriginEnum.Included} — provided a fee series was
+     * passed in — so a UI can break down an all-in price without the composer
+     * adding the amount a second time.
+     */
+    gridFeePerKwh: number;
+    /**
+     * Whether {@link gridFeePerKwh} was added by the composer, was already part
+     * of the energy price, or does not apply.
+     */
+    gridFeeOrigin: EnyoPriceComponentOriginEnum;
+    /** Total discount per kWh applied to this interval; `0` when none applies. */
+    bonusPerKwh: number;
+    /**
+     * Whether {@link bonusPerKwh} was applied by the composer, was already part
+     * of the energy price, or does not apply.
+     */
+    bonusOrigin: EnyoPriceComponentOriginEnum;
+    /** Ids of the bonuses that contributed to {@link bonusPerKwh}. */
+    appliedBonusIds: string[];
+    /**
+     * The final price per kWh for this interval:
+     * `energyPricePerKwh + gridFeePerKwh - bonusPerKwh`, with components whose
+     * origin is `included` already contained in `energyPricePerKwh` and
+     * therefore not counted twice.
+     */
+    effectivePricePerKwh: number;
+    /** Currency of every amount in this entry, when known. */
+    currency?: string;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Where a price component in a composed entry came from.
+ */
+export 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 || (EnyoPriceComponentOriginEnum = {}));

package/dist/types/enyo-price-schedule.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared scheduling primitives for time-dependent price components
+ * (dynamic grid fees and tariff bonuses).
+ *
+ * All amounts in this module are expressed **per kilowatt hour** and are always
+ * a positive magnitude — the direction is defined by the component that carries
+ * the schedule: a grid fee is *added* to the energy price, a tariff bonus is
+ * *subtracted* from it. Keeping magnitudes unsigned removes the single most
+ * common integration mistake (an inverted sign silently flipping an optimizer's
+ * decisions) and is enforced by the validators in
+ * `implementations/pricing/price-schedule-validators.ts`.
+ */
+/**
+ * The kind of schedule a price component follows.
+ */
+export declare enum EnyoPriceScheduleTypeEnum {
+    /** One amount that applies at every point in time. */
+    Constant = "constant",
+    /**
+     * Calendar-recurring windows — used for high-tariff/low-tariff (HT/NT)
+     * network charges, seasonal charges, and weekday-dependent bonuses.
+     */
+    Recurring = "recurring",
+    /**
+     * Explicit absolute time windows — used for grid fees or bonuses published
+     * as a dated series (e.g. a day-ahead publication by the grid operator).
+     */
+    Absolute = "absolute"
+}
+/**
+ * Which energy direction a price component applies to.
+ */
+export declare enum EnyoPriceAppliesToEnum {
+    /** Applies to energy drawn from the grid. */
+    Consumption = "consumption",
+    /** Applies to energy fed into the grid. */
+    FeedIn = "feed-in",
+    /** Applies to both directions. */
+    Both = "both"
+}
+/**
+ * A calendar-recurring price window.
+ *
+ * Times are wall-clock times in the owning component's `timezone`, so a window
+ * survives daylight-saving transitions: `'22:00'` stays 22:00 local time all
+ * year round.
+ */
+export interface EnyoRecurringPriceWindow {
+    /**
+     * Inclusive start of the window as a local wall-clock time in `HH:mm`
+     * 24-hour notation, e.g. `'22:00'`.
+     */
+    startTimeOfDay: string;
+    /**
+     * Exclusive end of the window as a local wall-clock time in `HH:mm`
+     * notation. May be **earlier** than `startTimeOfDay`, in which case the
+     * window wraps past midnight (e.g. `'22:00'` → `'06:00'`).
+     */
+    endTimeOfDay: string;
+    /**
+     * Days of the week the window applies to, `0` = Sunday … `6` = Saturday.
+     * Omit for "every day".
+     *
+     * For a window that wraps past midnight the day is evaluated against the
+     * day the window **starts** — a Monday 22:00–06:00 window covers Monday
+     * evening and the early hours of Tuesday.
+     */
+    daysOfWeek?: number[];
+    /**
+     * Months the window applies to, `1` = January … `12` = December. Omit for
+     * "every month". Evaluated against the day the window starts, exactly as
+     * {@link daysOfWeek}.
+     */
+    months?: number[];
+    /** Positive amount per kWh that applies inside the window. */
+    amountPerKwh: number;
+}
+/**
+ * An explicit, absolutely-dated price window.
+ */
+export interface EnyoAbsolutePriceWindow {
+    /** Inclusive start of the window in ISO format. */
+    startIso: string;
+    /** Exclusive end of the window in ISO format. */
+    endIso: string;
+    /** Positive amount per kWh that applies inside the window. */
+    amountPerKwh: number;
+}
+/**
+ * A single amount that applies at all times.
+ */
+export interface EnyoConstantPriceSchedule {
+    type: EnyoPriceScheduleTypeEnum.Constant;
+    /** Positive amount per kWh, applied to every interval. */
+    amountPerKwh: number;
+}
+/**
+ * A set of calendar-recurring windows. Intervals not covered by any window
+ * resolve to `0`.
+ */
+export interface EnyoRecurringPriceSchedule {
+    type: EnyoPriceScheduleTypeEnum.Recurring;
+    /** The recurring windows. Must not overlap each other. */
+    windows: EnyoRecurringPriceWindow[];
+}
+/**
+ * A set of absolutely-dated windows. Intervals not covered by any window
+ * resolve to `0`.
+ */
+export interface EnyoAbsolutePriceSchedule {
+    type: EnyoPriceScheduleTypeEnum.Absolute;
+    /** The dated windows. Must not overlap each other. */
+    windows: EnyoAbsolutePriceWindow[];
+}
+/**
+ * Any supported price component schedule, discriminated by `type`.
+ */
+export type EnyoPriceSchedule = EnyoConstantPriceSchedule | EnyoRecurringPriceSchedule | EnyoAbsolutePriceSchedule;
+/**
+ * One resolved 15-minute interval produced by expanding an
+ * {@link EnyoPriceSchedule} over a time range.
+ */
+export interface EnyoResolvedPriceEntry {
+    /** Start of the 15-minute interval in ISO format. */
+    timestampIso: string;
+    /** Resolved positive amount per kWh for this interval; `0` when uncovered. */
+    amountPerKwh: number;
+}
+/**
+ * Restricts a price component query to a time range.
+ */
+export interface EnyoPriceRangeFilter {
+    /** Start of the requested range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the requested range in ISO format (exclusive). */
+    untilIso: string;
+}