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

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

@@ -0,0 +1,100 @@
+import { EnyoTariffBonus } from '../../types/enyo-electricity-tariff.cjs';
+import { EnyoEnergyPriceEntry } from '../../types/enyo-energy-prices.cjs';
+import { EnyoEpexSpotPriceEntry } from '../../types/enyo-epex-spot-price.cjs';
+import { EnyoComposableEnergyPriceEntry, EnyoComposeElectricityPricesInput, EnyoComposedElectricityPriceEntry } from '../../types/enyo-price-composition.cjs';
+import { EnyoPriceAppliesToEnum } from '../../types/enyo-price-schedule.cjs';
+/**
+ * Adapts a tariff price series from `useElectricityPrices().getPrices()` into
+ * composer input.
+ *
+ * @param entries - Price entries as returned by the electricity prices API
+ * @param direction - Which price to take; defaults to consumption. Feed-in
+ *   entries without a `feedInPricePerKwh` are skipped.
+ * @returns Composable energy price entries
+ */
+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/cjs/implementations/pricing/price-component-validators.cjs

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriceComponentValidationError = void 0;
+exports.validatePriceSchedule = validatePriceSchedule;
+exports.validateDynamicGridFee = validateDynamicGridFee;
+exports.validateTariffBonus = validateTariffBonus;
+exports.validateTariffBonuses = validateTariffBonuses;
+exports.validateTariffGridFeeConfig = validateTariffGridFeeConfig;
+exports.validateElectricityTariffPricing = validateElectricityTariffPricing;
+const enyo_electricity_tariff_js_1 = require("../../types/enyo-electricity-tariff.cjs");
+const enyo_price_schedule_js_1 = require("../../types/enyo-price-schedule.cjs");
+const price_schedule_resolver_js_1 = require("./price-schedule-resolver.cjs");
+/**
+ * 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.
+ */
+class PriceComponentValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PriceComponentValidationError';
+    }
+}
+exports.PriceComponentValidationError = 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(enyo_price_schedule_js_1.EnyoPriceAppliesToEnum).includes(appliesTo)) {
+        fail(`${field} must be one of ${Object.values(enyo_price_schedule_js_1.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
+ */
+function validatePriceSchedule(schedule, label = 'schedule') {
+    if (schedule === null || typeof schedule !== 'object') {
+        fail(`${label} must be an object`);
+    }
+    if (schedule.type === enyo_price_schedule_js_1.EnyoPriceScheduleTypeEnum.Constant) {
+        requireNonNegativeAmount(schedule.amountPerKwh, `${label}.amountPerKwh`);
+        return;
+    }
+    if (schedule.type === enyo_price_schedule_js_1.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 === enyo_price_schedule_js_1.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 = (0, price_schedule_resolver_js_1.parseTimeOfDay)(window.startTimeOfDay);
+            const end = (0, price_schedule_resolver_js_1.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(enyo_price_schedule_js_1.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);
+ * ```
+ */
+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
+ */
+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
+ */
+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
+ */
+function validateTariffGridFeeConfig(config, priceComposition, label = 'tariffData') {
+    const mode = config.gridFeeMode ?? enyo_electricity_tariff_js_1.GridFeeModeEnum.Static;
+    if (!Object.values(enyo_electricity_tariff_js_1.GridFeeModeEnum).includes(mode)) {
+        fail(`${label}.gridFeeMode must be one of ${Object.values(enyo_electricity_tariff_js_1.GridFeeModeEnum).join(', ')}`);
+    }
+    if (mode === enyo_electricity_tariff_js_1.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);
+ * ```
+ */
+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);
+    }
+}

package/dist/cjs/implementations/pricing/price-component-validators.d.cts

@@ -0,0 +1,90 @@
+import { EnyoElectricityTariff, EnyoTariffBonus, TariffGridFeeConfig, TariffPriceCompositionInfo } from '../../types/enyo-electricity-tariff.cjs';
+import { EnyoDynamicGridFeeRegistration } from '../../types/enyo-grid-fee.cjs';
+import { EnyoPriceSchedule } from '../../types/enyo-price-schedule.cjs';
+/**
+ * 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/cjs/implementations/pricing/price-schedule-resolver.cjs

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRICE_SCHEDULE_INTERVAL_MINUTES = void 0;
+exports.getZonedDateParts = getZonedDateParts;
+exports.parseTimeOfDay = parseTimeOfDay;
+exports.floorToInterval = floorToInterval;
+exports.resolvePriceSchedule = resolvePriceSchedule;
+const enyo_price_schedule_js_1 = require("../../types/enyo-price-schedule.cjs");
+/**
+ * Length of one resolved interval, in minutes. Matches the resolution of
+ * `useElectricityPrices().getPrices()` so resolved schedules can be combined
+ * with a price series interval by interval.
+ */
+exports.PRICE_SCHEDULE_INTERVAL_MINUTES = 15;
+const INTERVAL_MS = exports.PRICE_SCHEDULE_INTERVAL_MINUTES * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEKDAY_INDEX = {
+    Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6,
+};
+const formatterCache = new Map();
+function zonedFormatter(timezone) {
+    let formatter = formatterCache.get(timezone);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            weekday: 'short',
+            hour: 'numeric',
+            minute: 'numeric',
+        });
+        formatterCache.set(timezone, formatter);
+    }
+    return formatter;
+}
+/**
+ * Projects an instant onto the wall clock of a time zone.
+ *
+ * Uses `Intl.DateTimeFormat`, so daylight-saving transitions are handled by the
+ * platform's time zone database without pulling in a dependency.
+ *
+ * @param date - The instant to project
+ * @param timezone - IANA time zone identifier, e.g. `'Europe/Berlin'`
+ * @returns The wall-clock calendar fields of `date` in `timezone`
+ * @throws {RangeError} If `timezone` is not a valid IANA identifier
+ */
+function getZonedDateParts(date, timezone) {
+    const parts = zonedFormatter(timezone).formatToParts(date);
+    const lookup = {};
+    for (const part of parts) {
+        lookup[part.type] = part.value;
+    }
+    const hour = Number(lookup.hour);
+    const minute = Number(lookup.minute);
+    return {
+        year: Number(lookup.year),
+        month: Number(lookup.month),
+        day: Number(lookup.day),
+        weekday: WEEKDAY_INDEX[lookup.weekday] ?? 0,
+        hour,
+        minute,
+        minutesOfDay: hour * 60 + minute,
+    };
+}
+/**
+ * Parses an `HH:mm` wall-clock time into minutes since midnight.
+ *
+ * @param value - Time in 24-hour `HH:mm` notation, e.g. `'22:00'`
+ * @returns Minutes since midnight, or `null` when the value is malformed
+ */
+function parseTimeOfDay(value) {
+    const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
+    if (match === null) {
+        return null;
+    }
+    return Number(match[1]) * 60 + Number(match[2]);
+}
+/**
+ * Rounds an instant down to the start of its 15-minute interval.
+ *
+ * @param timestampMs - Epoch milliseconds
+ * @returns Epoch milliseconds of the interval start
+ */
+function floorToInterval(timestampMs) {
+    return Math.floor(timestampMs / INTERVAL_MS) * INTERVAL_MS;
+}
+function matchesRecurringWindow(window, timestampMs, timezone) {
+    const start = parseTimeOfDay(window.startTimeOfDay);
+    const end = parseTimeOfDay(window.endTimeOfDay);
+    if (start === null || end === null || start === end) {
+        return false;
+    }
+    const parts = getZonedDateParts(new Date(timestampMs), timezone);
+    let inWindow;
+    let anchor;
+    if (start < end) {
+        inWindow = parts.minutesOfDay >= start && parts.minutesOfDay < end;
+        anchor = parts;
+    }
+    else if (parts.minutesOfDay >= start) {
+        // Evening leg of a window that wraps past midnight.
+        inWindow = true;
+        anchor = parts;
+    }
+    else if (parts.minutesOfDay < end) {
+        // Early-morning leg — the window belongs to the previous local day.
+        inWindow = true;
+        anchor = getZonedDateParts(new Date(timestampMs - DAY_MS), timezone);
+    }
+    else {
+        return false;
+    }
+    if (!inWindow) {
+        return false;
+    }
+    if (window.daysOfWeek !== undefined && !window.daysOfWeek.includes(anchor.weekday)) {
+        return false;
+    }
+    return window.months === undefined || window.months.includes(anchor.month);
+}
+function matchesAbsoluteWindow(window, timestampMs) {
+    return timestampMs >= Date.parse(window.startIso) && timestampMs < Date.parse(window.endIso);
+}
+function amountAt(schedule, timestampMs, timezone) {
+    if (schedule.type === enyo_price_schedule_js_1.EnyoPriceScheduleTypeEnum.Constant) {
+        return schedule.amountPerKwh;
+    }
+    if (schedule.type === enyo_price_schedule_js_1.EnyoPriceScheduleTypeEnum.Absolute) {
+        const window = schedule.windows.find(candidate => matchesAbsoluteWindow(candidate, timestampMs));
+        return window?.amountPerKwh ?? 0;
+    }
+    const window = schedule.windows.find(candidate => matchesRecurringWindow(candidate, timestampMs, timezone));
+    return window?.amountPerKwh ?? 0;
+}
+/**
+ * Expands a price schedule into a flat 15-minute series over a time range.
+ *
+ * The range start is rounded down to the enclosing 15-minute interval. Intervals
+ * no window covers resolve to `amountPerKwh: 0`; intervals outside the
+ * component's validity window are omitted entirely, so an empty result means
+ * "this component does not apply here" rather than "it is free here".
+ *
+ * Windows are evaluated in array order and the first match wins — schedules are
+ * expected to be overlap-free, which the validators enforce at registration
+ * time.
+ *
+ * @param schedule - The schedule to expand
+ * @param options - Range, time zone and optional validity bounds
+ * @returns Resolved entries sorted ascending by `timestampIso`
+ *
+ * @example
+ * ```typescript
+ * const entries = resolvePriceSchedule(
+ *     {
+ *         type: EnyoPriceScheduleTypeEnum.Recurring,
+ *         windows: [{ startTimeOfDay: '22:00', endTimeOfDay: '06:00', amountPerKwh: 0.05 }],
+ *     },
+ *     { fromIso: '2026-09-02T00:00:00Z', untilIso: '2026-09-03T00:00:00Z', timezone: 'Europe/Berlin' },
+ * );
+ * ```
+ */
+function resolvePriceSchedule(schedule, options) {
+    const untilMs = Date.parse(options.untilIso);
+    const validFromMs = options.validFromIso === undefined ? undefined : Date.parse(options.validFromIso);
+    const validUntilMs = options.validUntilIso === undefined ? undefined : Date.parse(options.validUntilIso);
+    const entries = [];
+    for (let cursor = floorToInterval(Date.parse(options.fromIso)); cursor < untilMs; cursor += INTERVAL_MS) {
+        if (validFromMs !== undefined && cursor < validFromMs) {
+            continue;
+        }
+        if (validUntilMs !== undefined && cursor >= validUntilMs) {
+            break;
+        }
+        entries.push({
+            timestampIso: new Date(cursor).toISOString(),
+            amountPerKwh: amountAt(schedule, cursor, options.timezone),
+        });
+    }
+    return entries;
+}