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

package/dist/implementations/pricing/compose-electricity-prices.d.ts

@@ -0,0 +1,100 @@
+import { EnyoTariffBonus } from '../../types/enyo-electricity-tariff.js';
+import { EnyoEnergyPriceEntry } from '../../types/enyo-energy-prices.js';
+import { EnyoEpexSpotPriceEntry } from '../../types/enyo-epex-spot-price.js';
+import { EnyoComposableEnergyPriceEntry, EnyoComposeElectricityPricesInput, EnyoComposedElectricityPriceEntry } from '../../types/enyo-price-composition.js';
+import { EnyoPriceAppliesToEnum } from '../../types/enyo-price-schedule.js';
+/**
+ * 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
+ */
+export declare function fromEnergyPriceEntries(entries: EnyoEnergyPriceEntry[], direction?: EnyoPriceAppliesToEnum): EnyoComposableEnergyPriceEntry[];
+/**
+ * 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
+ */
+export declare function fromEpexSpotEntries(entries: EnyoEpexSpotPriceEntry[]): EnyoComposableEnergyPriceEntry[];
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare function resolveTariffBonuses(bonuses: EnyoTariffBonus[], options: {
+    /** Start of the range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the range in ISO format (exclusive). */
+    untilIso: string;
+    /** Direction to resolve for; defaults to consumption. */
+    appliesTo?: EnyoPriceAppliesToEnum;
+}): Map<string, {
+    bonusPerKwh: number;
+    appliedBonusIds: string[];
+}>;
+/**
+ * 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));
+ * ```
+ */
+export declare function composeElectricityPrices(input: EnyoComposeElectricityPricesInput): EnyoComposedElectricityPriceEntry[];

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

@@ -0,0 +1,212 @@
+import { EnyoPriceComponentOriginEnum, } from '../../types/enyo-price-composition.js';
+import { EnyoPriceAppliesToEnum } from '../../types/enyo-price-schedule.js';
+import { resolvePriceSchedule } from './price-schedule-resolver.js';
+/**
+ * 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
+ */
+export function fromEnergyPriceEntries(entries, direction = EnyoPriceAppliesToEnum.Consumption) {
+    if (direction === 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
+ */
+export function fromEpexSpotEntries(entries) {
+    return entries.map(entry => ({ timestampIso: entry.timestampIso, pricePerKwh: entry.pricePerKwh }));
+}
+function appliesToDirection(componentAppliesTo, direction) {
+    return componentAppliesTo === 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',
+ * });
+ * ```
+ */
+export function resolveTariffBonuses(bonuses, options) {
+    const direction = options.appliesTo ?? EnyoPriceAppliesToEnum.Consumption;
+    const resolved = bonuses
+        .filter(bonus => appliesToDirection(bonus.appliesTo, direction))
+        .map(bonus => {
+        const entries = 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));
+ * ```
+ */
+export function composeElectricityPrices(input) {
+    const direction = input.appliesTo ?? 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
+            ? EnyoPriceComponentOriginEnum.NotApplicable
+            : gridFeeIncluded
+                ? EnyoPriceComponentOriginEnum.Included
+                : EnyoPriceComponentOriginEnum.Added;
+        const bonus = resolvedBonuses.get(entry.timestampIso);
+        const bonusPerKwh = bonus?.bonusPerKwh ?? 0;
+        const bonusOrigin = bonus === undefined
+            ? EnyoPriceComponentOriginEnum.NotApplicable
+            : bonusesIncluded
+                ? EnyoPriceComponentOriginEnum.Included
+                : EnyoPriceComponentOriginEnum.Added;
+        let effectivePricePerKwh = entry.pricePerKwh;
+        if (gridFeeOrigin === EnyoPriceComponentOriginEnum.Added) {
+            effectivePricePerKwh += gridFeePerKwh;
+        }
+        if (bonusOrigin === 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,
+        };
+    });
+}

package/dist/implementations/pricing/price-component-validators.d.ts

@@ -0,0 +1,90 @@
+import { EnyoElectricityTariff, EnyoTariffBonus, TariffGridFeeConfig, TariffPriceCompositionInfo } from '../../types/enyo-electricity-tariff.js';
+import { EnyoDynamicGridFeeRegistration } from '../../types/enyo-grid-fee.js';
+import { EnyoPriceSchedule } from '../../types/enyo-price-schedule.js';
+/**
+ * Thrown when a grid fee, tariff bonus or price schedule violates one of the
+ * invariants enforced by this module. The message names the offending field or
+ * window index so callers can surface it directly to the user.
+ */
+export declare class PriceComponentValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a {@link EnyoPriceSchedule}. Throws on the first violation.
+ *
+ * Enforces finite, non-negative amounts, well-formed `HH:mm` times, day and
+ * month ranges, ordered absolute windows, and that no two windows which can
+ * occur on the same day overlap in time — an overlap would make the resolved
+ * amount depend on array order rather than on the schedule itself.
+ *
+ * Overlap detection for recurring windows is conservative: two windows are only
+ * compared when their day-of-week and month sets can intersect. A window that
+ * wraps past midnight is compared on both of its legs.
+ *
+ * @param schedule - The schedule to validate
+ * @param label - Prefix used in error messages, e.g. `'gridFee.schedule'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export declare function validatePriceSchedule(schedule: EnyoPriceSchedule, label?: string): void;
+/**
+ * Validates a dynamic grid fee registration. Throws on the first violation.
+ *
+ * @param registration - The grid fee to validate
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ *
+ * @example
+ * ```typescript
+ * validateDynamicGridFee(registration);
+ * await energyApp.useGridFee().registerGridFee(registration);
+ * ```
+ */
+export declare function validateDynamicGridFee(registration: EnyoDynamicGridFeeRegistration): void;
+/**
+ * Validates a single tariff bonus. Throws on the first violation.
+ *
+ * @param bonus - The bonus to validate
+ * @param label - Prefix used in error messages, e.g. `'bonuses[0]'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export declare function validateTariffBonus(bonus: EnyoTariffBonus, label?: string): void;
+/**
+ * Validates a tariff's bonus list: every bonus is individually valid and ids are
+ * unique within the tariff.
+ *
+ * @param bonuses - The bonuses to validate
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export declare function validateTariffBonuses(bonuses: EnyoTariffBonus[]): void;
+/**
+ * Validates how a tariff's pricing data declares its grid fee.
+ *
+ * Catches the configuration that silently double-charges the customer: declaring
+ * a dynamic grid fee while also declaring that the tariff's prices already
+ * include the grid fee. Anyone trusting the declaration would add the fee on top
+ * of prices that already contain it.
+ *
+ * @param config - The grid fee configuration of one tariff pricing shape
+ * @param priceComposition - The tariff's price composition declaration, if any
+ * @param label - Prefix used in error messages, e.g. `'dynamicTariffData'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export declare function validateTariffGridFeeConfig(config: TariffGridFeeConfig, priceComposition: TariffPriceCompositionInfo | undefined, label?: string): void;
+/**
+ * Validates the pricing-related parts of a complete electricity tariff: the grid
+ * fee link of whichever pricing shape is present, and the tariff's bonuses.
+ *
+ * Call it before {@link EnergyAppElectricityTariff.registerTariff} to turn what
+ * would otherwise be a silently mispriced tariff into an actionable error.
+ *
+ * @param tariff - The tariff to validate (with or without its `id`)
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ *
+ * @example
+ * ```typescript
+ * validateElectricityTariffPricing(tariff);
+ * await energyApp.useElectricityTariff().registerTariff(tariff);
+ * ```
+ */
+export declare function validateElectricityTariffPricing(tariff: Omit<EnyoElectricityTariff, 'id'> & {
+    id?: string;
+}): void;

package/dist/implementations/pricing/price-component-validators.js

@@ -0,0 +1,285 @@
+import { GridFeeModeEnum, } from '../../types/enyo-electricity-tariff.js';
+import { EnyoPriceAppliesToEnum, EnyoPriceScheduleTypeEnum, } from '../../types/enyo-price-schedule.js';
+import { parseTimeOfDay } from './price-schedule-resolver.js';
+/**
+ * Thrown when a grid fee, tariff bonus or price schedule violates one of the
+ * invariants enforced by this module. The message names the offending field or
+ * window index so callers can surface it directly to the user.
+ */
+export class PriceComponentValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PriceComponentValidationError';
+    }
+}
+function fail(message) {
+    throw new PriceComponentValidationError(message);
+}
+function requireNonEmpty(value, field) {
+    if (value === undefined || value.trim().length === 0) {
+        fail(`${field} must be a non-empty string`);
+    }
+}
+function requireValidTimezone(timezone, field) {
+    requireNonEmpty(timezone, field);
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+    }
+    catch {
+        fail(`${field} must be a valid IANA time zone identifier, got '${timezone}'`);
+    }
+}
+function requireNonNegativeAmount(amount, field) {
+    if (!Number.isFinite(amount)) {
+        fail(`${field} must be a finite number`);
+    }
+    if (amount < 0) {
+        fail(`${field} must not be negative — amounts are unsigned magnitudes; ` +
+            `grid fees are added to and bonuses subtracted from the energy price`);
+    }
+}
+function requireIsoTimestamp(value, field) {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        fail(`${field} must be a valid ISO timestamp, got '${value}'`);
+    }
+    return parsed;
+}
+function requireValidityRange(validFromIso, validUntilIso, label) {
+    const from = validFromIso === undefined ? undefined : requireIsoTimestamp(validFromIso, `${label}.validFromIso`);
+    const until = validUntilIso === undefined ? undefined : requireIsoTimestamp(validUntilIso, `${label}.validUntilIso`);
+    if (from !== undefined && until !== undefined && until <= from) {
+        fail(`${label}.validUntilIso must be after ${label}.validFromIso`);
+    }
+}
+function requireAppliesTo(appliesTo, field) {
+    if (!Object.values(EnyoPriceAppliesToEnum).includes(appliesTo)) {
+        fail(`${field} must be one of ${Object.values(EnyoPriceAppliesToEnum).join(', ')}`);
+    }
+}
+function toMinuteIntervals(start, end) {
+    return start < end
+        ? [{ start, end }]
+        : [{ start, end: 1440 }, { start: 0, end }];
+}
+function intervalsOverlap(a, b) {
+    return a.some(left => b.some(right => left.start < right.end && right.start < left.end));
+}
+function setsIntersect(a, b) {
+    if (a === undefined || b === undefined) {
+        return true;
+    }
+    return a.some(value => b.includes(value));
+}
+/**
+ * Validates a {@link EnyoPriceSchedule}. Throws on the first violation.
+ *
+ * Enforces finite, non-negative amounts, well-formed `HH:mm` times, day and
+ * month ranges, ordered absolute windows, and that no two windows which can
+ * occur on the same day overlap in time — an overlap would make the resolved
+ * amount depend on array order rather than on the schedule itself.
+ *
+ * Overlap detection for recurring windows is conservative: two windows are only
+ * compared when their day-of-week and month sets can intersect. A window that
+ * wraps past midnight is compared on both of its legs.
+ *
+ * @param schedule - The schedule to validate
+ * @param label - Prefix used in error messages, e.g. `'gridFee.schedule'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export function validatePriceSchedule(schedule, label = 'schedule') {
+    if (schedule === null || typeof schedule !== 'object') {
+        fail(`${label} must be an object`);
+    }
+    if (schedule.type === EnyoPriceScheduleTypeEnum.Constant) {
+        requireNonNegativeAmount(schedule.amountPerKwh, `${label}.amountPerKwh`);
+        return;
+    }
+    if (schedule.type === EnyoPriceScheduleTypeEnum.Absolute) {
+        if (schedule.windows.length === 0) {
+            fail(`${label}.windows must contain at least one window`);
+        }
+        const ranges = schedule.windows.map((window, index) => {
+            const start = requireIsoTimestamp(window.startIso, `${label}.windows[${index}].startIso`);
+            const end = requireIsoTimestamp(window.endIso, `${label}.windows[${index}].endIso`);
+            if (end <= start) {
+                fail(`${label}.windows[${index}].endIso must be after startIso`);
+            }
+            requireNonNegativeAmount(window.amountPerKwh, `${label}.windows[${index}].amountPerKwh`);
+            return { start, end, index };
+        }).sort((a, b) => a.start - b.start);
+        for (let i = 1; i < ranges.length; i++) {
+            if (ranges[i].start < ranges[i - 1].end) {
+                fail(`${label}.windows[${ranges[i].index}] overlaps windows[${ranges[i - 1].index}]`);
+            }
+        }
+        return;
+    }
+    if (schedule.type === EnyoPriceScheduleTypeEnum.Recurring) {
+        if (schedule.windows.length === 0) {
+            fail(`${label}.windows must contain at least one window`);
+        }
+        const parsed = schedule.windows.map((window, index) => {
+            const start = parseTimeOfDay(window.startTimeOfDay);
+            const end = parseTimeOfDay(window.endTimeOfDay);
+            if (start === null) {
+                fail(`${label}.windows[${index}].startTimeOfDay must be a 'HH:mm' time, got '${window.startTimeOfDay}'`);
+            }
+            if (end === null) {
+                fail(`${label}.windows[${index}].endTimeOfDay must be a 'HH:mm' time, got '${window.endTimeOfDay}'`);
+            }
+            if (start === end) {
+                fail(`${label}.windows[${index}] must not start and end at the same time of day`);
+            }
+            if (window.daysOfWeek !== undefined) {
+                if (window.daysOfWeek.length === 0) {
+                    fail(`${label}.windows[${index}].daysOfWeek must not be empty — omit it for 'every day'`);
+                }
+                for (const day of window.daysOfWeek) {
+                    if (!Number.isInteger(day) || day < 0 || day > 6) {
+                        fail(`${label}.windows[${index}].daysOfWeek must contain integers 0 (Sunday) to 6 (Saturday), got ${day}`);
+                    }
+                }
+            }
+            if (window.months !== undefined) {
+                if (window.months.length === 0) {
+                    fail(`${label}.windows[${index}].months must not be empty — omit it for 'every month'`);
+                }
+                for (const month of window.months) {
+                    if (!Number.isInteger(month) || month < 1 || month > 12) {
+                        fail(`${label}.windows[${index}].months must contain integers 1 to 12, got ${month}`);
+                    }
+                }
+            }
+            requireNonNegativeAmount(window.amountPerKwh, `${label}.windows[${index}].amountPerKwh`);
+            return { window, index, intervals: toMinuteIntervals(start, end) };
+        });
+        for (let i = 0; i < parsed.length; i++) {
+            for (let j = i + 1; j < parsed.length; j++) {
+                const left = parsed[i];
+                const right = parsed[j];
+                if (!setsIntersect(left.window.daysOfWeek, right.window.daysOfWeek)) {
+                    continue;
+                }
+                if (!setsIntersect(left.window.months, right.window.months)) {
+                    continue;
+                }
+                if (intervalsOverlap(left.intervals, right.intervals)) {
+                    fail(`${label}.windows[${right.index}] overlaps windows[${left.index}]`);
+                }
+            }
+        }
+        return;
+    }
+    fail(`${label}.type must be one of ${Object.values(EnyoPriceScheduleTypeEnum).join(', ')}`);
+}
+/**
+ * Validates a dynamic grid fee registration. Throws on the first violation.
+ *
+ * @param registration - The grid fee to validate
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ *
+ * @example
+ * ```typescript
+ * validateDynamicGridFee(registration);
+ * await energyApp.useGridFee().registerGridFee(registration);
+ * ```
+ */
+export function validateDynamicGridFee(registration) {
+    requireNonEmpty(registration.id, 'gridFee.id');
+    requireNonEmpty(registration.name, 'gridFee.name');
+    requireNonEmpty(registration.gridOperator, 'gridFee.gridOperator');
+    requireNonEmpty(registration.currency, 'gridFee.currency');
+    requireValidTimezone(registration.timezone, 'gridFee.timezone');
+    requireAppliesTo(registration.appliesTo, 'gridFee.appliesTo');
+    requireValidityRange(registration.validFromIso, registration.validUntilIso, 'gridFee');
+    validatePriceSchedule(registration.schedule, 'gridFee.schedule');
+}
+/**
+ * Validates a single tariff bonus. Throws on the first violation.
+ *
+ * @param bonus - The bonus to validate
+ * @param label - Prefix used in error messages, e.g. `'bonuses[0]'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export function validateTariffBonus(bonus, label = 'bonus') {
+    requireNonEmpty(bonus.id, `${label}.id`);
+    requireNonEmpty(bonus.name, `${label}.name`);
+    requireValidTimezone(bonus.timezone, `${label}.timezone`);
+    requireAppliesTo(bonus.appliesTo, `${label}.appliesTo`);
+    requireValidityRange(bonus.validFromIso, bonus.validUntilIso, label);
+    if (bonus.priority !== undefined && !Number.isFinite(bonus.priority)) {
+        fail(`${label}.priority must be a finite number`);
+    }
+    validatePriceSchedule(bonus.schedule, `${label}.schedule`);
+}
+/**
+ * Validates a tariff's bonus list: every bonus is individually valid and ids are
+ * unique within the tariff.
+ *
+ * @param bonuses - The bonuses to validate
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export function validateTariffBonuses(bonuses) {
+    const seen = new Set();
+    bonuses.forEach((bonus, index) => {
+        validateTariffBonus(bonus, `bonuses[${index}]`);
+        if (seen.has(bonus.id)) {
+            fail(`bonuses[${index}].id '${bonus.id}' is used more than once in the same tariff`);
+        }
+        seen.add(bonus.id);
+    });
+}
+/**
+ * Validates how a tariff's pricing data declares its grid fee.
+ *
+ * Catches the configuration that silently double-charges the customer: declaring
+ * a dynamic grid fee while also declaring that the tariff's prices already
+ * include the grid fee. Anyone trusting the declaration would add the fee on top
+ * of prices that already contain it.
+ *
+ * @param config - The grid fee configuration of one tariff pricing shape
+ * @param priceComposition - The tariff's price composition declaration, if any
+ * @param label - Prefix used in error messages, e.g. `'dynamicTariffData'`
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ */
+export function validateTariffGridFeeConfig(config, priceComposition, label = 'tariffData') {
+    const mode = config.gridFeeMode ?? GridFeeModeEnum.Static;
+    if (!Object.values(GridFeeModeEnum).includes(mode)) {
+        fail(`${label}.gridFeeMode must be one of ${Object.values(GridFeeModeEnum).join(', ')}`);
+    }
+    if (mode === GridFeeModeEnum.Dynamic && priceComposition?.includesGridFee === true) {
+        fail(`${label} declares a dynamic grid fee while priceComposition.includesGridFee is true — ` +
+            `the fee is already contained in the tariff's prices and must not be added again`);
+    }
+}
+/**
+ * Validates the pricing-related parts of a complete electricity tariff: the grid
+ * fee link of whichever pricing shape is present, and the tariff's bonuses.
+ *
+ * Call it before {@link EnergyAppElectricityTariff.registerTariff} to turn what
+ * would otherwise be a silently mispriced tariff into an actionable error.
+ *
+ * @param tariff - The tariff to validate (with or without its `id`)
+ * @throws {PriceComponentValidationError} On the first invariant violation
+ *
+ * @example
+ * ```typescript
+ * validateElectricityTariffPricing(tariff);
+ * await energyApp.useElectricityTariff().registerTariff(tariff);
+ * ```
+ */
+export function validateElectricityTariffPricing(tariff) {
+    if (tariff.staticTariffData !== undefined) {
+        validateTariffGridFeeConfig(tariff.staticTariffData, tariff.priceComposition, 'staticTariffData');
+    }
+    if (tariff.timeVariableTariffData !== undefined) {
+        validateTariffGridFeeConfig(tariff.timeVariableTariffData, tariff.priceComposition, 'timeVariableTariffData');
+    }
+    if (tariff.dynamicTariffData !== undefined) {
+        validateTariffGridFeeConfig(tariff.dynamicTariffData, tariff.priceComposition, 'dynamicTariffData');
+    }
+    if (tariff.bonuses !== undefined) {
+        validateTariffBonuses(tariff.bonuses);
+    }
+}