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

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

@@ -0,0 +1,248 @@
+import { EnyoPriceComponentEnum } from '../../types/enyo-electricity-tariff.js';
+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,
+    }));
+}
+/**
+ * Converts a grid fee series from `useGridFee().getGridFeeValues()` into the
+ * unit the composer works in.
+ *
+ * This is the **only** place cent meets currency in the pricing path, and it
+ * exists so the conversion happens once, visibly, instead of at every call site.
+ * Grid fees are published and read as gross **cent** per kWh because that is how
+ * they are quoted and configured; energy prices are in whole currency units
+ * (EUR/kWh), so a fee added to a price without dividing by 100 overstates it by
+ * a factor of 100 — a mistake that survives review because both numbers look
+ * plausible.
+ *
+ * Pass the result as {@link EnyoComposeElectricityPricesInput.gridFees}. Whether
+ * the amounts include the fee's additional charges is decided when the series is
+ * fetched, not here.
+ *
+ * @param series - The series returned by `getGridFeeValues()`, or `null`
+ * @returns The same series with amounts in currency per kWh, or `null` when the input was
+ */
+export function fromGridFeeEntries(series) {
+    if (series == null) {
+        return null;
+    }
+    return {
+        appliesTo: series.appliesTo,
+        entries: series.entries.map(entry => ({
+            timestampIso: entry.timestampIso,
+            feePerKwh: entry.grossCentPerKwh / 100,
+        })),
+    };
+}
+/**
+ * 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 a series built from them should declare
+ * no included components at all.
+ *
+ * @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 grid fee and a tariff's bonuses.
+ *
+ * The three inputs come from three independent sources and are deliberately not
+ * coupled: energy prices from the tariff or the spot market, the grid fee from
+ * `useGridFee()`, the bonuses from the tariff. Pass whichever apply.
+ *
+ * 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 price series' `includes` 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 series = await energyApp.useElectricityTariff().getPrices(direction, {fromIso, untilIso});
+ * const fees = await energyApp.useGridFee().getGridFeeValues({fromIso, untilIso});
+ * const spot = await energyApp.useEpexSpotPrices().getPrices({fromIso, untilIso});
+ *
+ * const prices = composeElectricityPrices({
+ *     energyPrices: fromEpexSpotEntries(spot.entries),
+ *     energyPriceComposition: series?.includes,
+ *     gridFees: fees,
+ *     bonuses: myBonuses,
+ *     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?.includes(EnyoPriceComponentEnum.GridFee) === true;
+    const bonusesIncluded = input.energyPriceComposition?.includes(EnyoPriceComponentEnum.Bonuses) === 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,57 @@
+import { EnyoTariffBonus } 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;

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

@@ -0,0 +1,230 @@
+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.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);
+    });
+}

package/dist/implementations/pricing/price-schedule-resolver.d.ts

@@ -0,0 +1,95 @@
+import { EnyoPriceSchedule, EnyoResolvedPriceEntry } from '../../types/enyo-price-schedule.js';
+/**
+ * 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.
+ */
+export declare const PRICE_SCHEDULE_INTERVAL_MINUTES = 15;
+/**
+ * Wall-clock calendar fields of an instant, as seen in a specific time zone.
+ */
+export interface ZonedDateParts {
+    /** Full year, e.g. `2026`. */
+    year: number;
+    /** Month, `1` = January … `12` = December. */
+    month: number;
+    /** Day of the month, starting at `1`. */
+    day: number;
+    /** Day of the week, `0` = Sunday … `6` = Saturday. */
+    weekday: number;
+    /** Hour in 24-hour notation, `0`–`23`. */
+    hour: number;
+    /** Minute, `0`–`59`. */
+    minute: number;
+    /** Minutes since local midnight (`hour * 60 + minute`). */
+    minutesOfDay: number;
+}
+/**
+ * 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
+ */
+export declare function getZonedDateParts(date: Date, timezone: string): ZonedDateParts;
+/**
+ * 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
+ */
+export declare function parseTimeOfDay(value: string): number | null;
+/**
+ * Rounds an instant down to the start of its 15-minute interval.
+ *
+ * @param timestampMs - Epoch milliseconds
+ * @returns Epoch milliseconds of the interval start
+ */
+export declare function floorToInterval(timestampMs: number): number;
+/**
+ * Options for {@link resolvePriceSchedule}.
+ */
+export interface ResolvePriceScheduleOptions {
+    /** Start of the range to resolve, in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the range to resolve, in ISO format (exclusive). */
+    untilIso: string;
+    /** IANA time zone the schedule's wall-clock times are expressed in. */
+    timezone: string;
+    /** Optional start of the component's validity in ISO format (inclusive). */
+    validFromIso?: string;
+    /** Optional end of the component's validity in ISO format (exclusive). */
+    validUntilIso?: string;
+}
+/**
+ * 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' },
+ * );
+ * ```
+ */
+export declare function resolvePriceSchedule(schedule: EnyoPriceSchedule, options: ResolvePriceScheduleOptions): EnyoResolvedPriceEntry[];