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

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[];

package/dist/implementations/pricing/price-schedule-resolver.js

@@ -0,0 +1,175 @@
+import { EnyoPriceScheduleTypeEnum, } 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 const PRICE_SCHEDULE_INTERVAL_MINUTES = 15;
+const INTERVAL_MS = 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
+ */
+export 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
+ */
+export 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
+ */
+export 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 === EnyoPriceScheduleTypeEnum.Constant) {
+        return schedule.amountPerKwh;
+    }
+    if (schedule.type === 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' },
+ * );
+ * ```
+ */
+export 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;
+}

package/dist/index.d.ts

@@ -136,3 +136,10 @@ export * from './packages/energy-app-epex-spot-price.js';
 export * from './types/enyo-automation.js';
 export * from './packages/energy-app-automation.js';
 export * from './implementations/automation/automation-validators.js';
+export * from './types/enyo-price-schedule.js';
+export * from './types/enyo-grid-fee.js';
+export * from './types/enyo-price-composition.js';
+export * from './packages/energy-app-grid-fee.js';
+export * from './implementations/pricing/price-schedule-resolver.js';
+export * from './implementations/pricing/price-component-validators.js';
+export * from './implementations/pricing/compose-electricity-prices.js';

package/dist/index.js

@@ -136,3 +136,10 @@ export * from './packages/energy-app-epex-spot-price.js';
 export * from './types/enyo-automation.js';
 export * from './packages/energy-app-automation.js';
 export * from './implementations/automation/automation-validators.js';
+export * from './types/enyo-price-schedule.js';
+export * from './types/enyo-grid-fee.js';
+export * from './types/enyo-price-composition.js';
+export * from './packages/energy-app-grid-fee.js';
+export * from './implementations/pricing/price-schedule-resolver.js';
+export * from './implementations/pricing/price-component-validators.js';
+export * from './implementations/pricing/compose-electricity-prices.js';

package/dist/packages/energy-app-electricity-tariff.d.ts

@@ -1,4 +1,4 @@
-import { EnyoElectricityTariff, EnyoElectricityTariffWithDefault } from "../types/enyo-electricity-tariff.js";
+import { EnyoElectricityTariff, EnyoElectricityTariffWithDefault, EnyoTariffChangeEvent } from "../types/enyo-electricity-tariff.js";
 /**
  * Interface for managing electricity tariffs.
  * Provides methods to register, retrieve, and remove electricity tariffs
@@ -60,4 +60,37 @@ export interface EnergyAppElectricityTariff {
      * @returns Promise that resolves to the full updated tariff with its default indicator
      */
     updateTariff(id: string, attributes: Partial<Omit<EnyoElectricityTariff, 'id'>>): Promise<EnyoElectricityTariffWithDefault>;
+    /**
+     * Registers a listener invoked whenever any tariff is registered, updated
+     * or removed, or whenever a different tariff becomes the system default.
+     *
+     * Listeners see changes made by every energy app on the system, not just
+     * this one — filter on {@link EnyoTariffChangeEvent.tariffId} when only one
+     * tariff matters. This is the signal to recompose prices: a changed grid fee
+     * link, an added or expired bonus, or a new default tariff all invalidate a
+     * previously composed price series.
+     *
+     * Requires the `ElectricityTariff` permission.
+     *
+     * @param listener - Callback invoked with the tariff change event
+     * @returns A unique listener id that can be passed to {@link offTariffChanged}
+     *
+     * @example
+     * ```typescript
+     * const listenerId = tariffs.onTariffChanged(async event => {
+     *     if (event.changeType === EnyoTariffChangeTypeEnum.Removed) return;
+     *     await recomposePrices(event.tariff);
+     * });
+     * // later
+     * tariffs.offTariffChanged(listenerId);
+     * ```
+     */
+    onTariffChanged(listener: (event: EnyoTariffChangeEvent) => void | Promise<void>): string;
+    /**
+     * Removes a previously registered tariff change listener. If the listener id
+     * is unknown, this operation is a no-op.
+     *
+     * @param listenerId - The id returned from {@link onTariffChanged}
+     */
+    offTariffChanged(listenerId: string): void;
 }

package/dist/packages/energy-app-grid-fee.d.ts

@@ -0,0 +1,181 @@
+import { EnyoDynamicGridFee, EnyoDynamicGridFeeFilter, EnyoDynamicGridFeeRegistration, EnyoDynamicGridFeeSeries, EnyoGridFeeChangeEvent } from '../types/enyo-grid-fee.js';
+import { EnyoAbsolutePriceWindow } from '../types/enyo-price-schedule.js';
+/**
+ * Interface for publishing and consuming dynamic grid fees (network charges).
+ *
+ * Any energy app can act as a producer by registering a grid fee — typically an
+ * app that knows the local grid operator's tariff sheet or fetches a published
+ * series — and any energy app can act as a consumer by resolving that fee for a
+ * time range with {@link getDynamicGridFees}.
+ *
+ * Publishing requires the `GridFeeRegister` permission; consuming requires
+ * `GridFeeUse`.
+ *
+ * A grid fee describes the site's **grid connection**, not a supplier contract:
+ * it is registered and resolved independently of any tariff, and the same fee
+ * applies whichever supplier the site buys from.
+ *
+ * **Nothing here is applied to a price automatically.** The host never folds a
+ * grid fee into {@link EnergyAppEnergyPrices.getPrices}, because provider APIs
+ * differ: some already return grid-fee-inclusive prices, some do not. The app
+ * that owns the tariff knows which is the case — it declares it via the
+ * tariff's `priceComposition` and composes the effective price itself with
+ * `composeElectricityPrices()`.
+ *
+ * @example
+ * ```typescript
+ * // Producer: a §14a EnWG module 3 HT/NT network charge
+ * const gridFee = energyApp.useGridFee();
+ * await gridFee.registerGridFee({
+ *     id: 'dso-hd-2026',
+ *     name: 'Netzentgelt HT/NT 2026',
+ *     gridOperator: 'Netze BW',
+ *     currency: EnyoCurrencyEnum.EUR,
+ *     timezone: 'Europe/Berlin',
+ *     appliesTo: EnyoPriceAppliesToEnum.Consumption,
+ *     moduleThreeCompliant: true,
+ *     schedule: {
+ *         type: EnyoPriceScheduleTypeEnum.Recurring,
+ *         windows: [
+ *             { startTimeOfDay: '06:00', endTimeOfDay: '22:00', amountPerKwh: 0.0912 },
+ *             { startTimeOfDay: '22:00', endTimeOfDay: '06:00', amountPerKwh: 0.0431 },
+ *         ],
+ *     },
+ * });
+ *
+ * // Consumer: resolve it for the next 24 hours
+ * const fees = await gridFee.getDynamicGridFees({
+ *     fromIso: new Date().toISOString(),
+ *     untilIso: new Date(Date.now() + 86_400_000).toISOString(),
+ * });
+ * ```
+ */
+export interface EnergyAppGridFee {
+    /**
+     * Registers a new dynamic grid fee or updates an existing one. Uses upsert
+     * logic based on `id` — if a fee with the same id already exists it is
+     * replaced, otherwise a new one is created.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @param registration - The grid fee to register, including its schedule
+     * @returns Promise that resolves to the stored grid fee, including the host-assigned `publishedAtIso`
+     */
+    registerGridFee(registration: EnyoDynamicGridFeeRegistration): Promise<EnyoDynamicGridFee>;
+    /**
+     * Partially updates a registered grid fee. Only the provided attributes are
+     * modified; all other fields remain unchanged.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @param id - The unique identifier of the grid fee to update
+     * @param attributes - A partial set of grid fee fields to update (excluding `id`)
+     * @returns Promise that resolves to the full updated grid fee
+     */
+    updateGridFee(id: string, attributes: Partial<Omit<EnyoDynamicGridFeeRegistration, 'id'>>): Promise<EnyoDynamicGridFee>;
+    /**
+     * Removes a registered grid fee. {@link getDynamicGridFees} resolves to
+     * `null` for it afterwards. If the fee does not exist, this operation is a
+     * no-op.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @param id - The unique identifier of the grid fee to remove
+     * @returns Promise that resolves when the grid fee has been removed
+     */
+    removeGridFee(id: string): Promise<void>;
+    /**
+     * Retrieves all registered grid fees across all energy apps on the system.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @returns Promise that resolves to an array of all registered grid fees
+     */
+    listGridFees(): Promise<EnyoDynamicGridFee[]>;
+    /**
+     * Retrieves a single registered grid fee by its id, or `null` when no fee
+     * with that id exists.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @param id - The unique identifier of the grid fee
+     * @returns Promise that resolves to the grid fee, or `null`
+     */
+    getGridFee(id: string): Promise<EnyoDynamicGridFee | null>;
+    /**
+     * Replaces the absolute windows of a grid fee whose schedule is
+     * {@link EnyoPriceScheduleTypeEnum.Absolute}. Use this for fees the grid
+     * operator publishes as a dated series (for example day-ahead), where the
+     * schedule changes far more often than the fee's metadata.
+     *
+     * Windows must not overlap and are stored sorted ascending by `startIso`.
+     * Publishing replaces the previously stored windows in full.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @param id - The unique identifier of the registered grid fee
+     * @param windows - The complete set of absolute windows to store
+     * @returns Promise that resolves when the windows have been stored and change listeners dispatched
+     */
+    publishGridFeeWindows(id: string, windows: EnyoAbsolutePriceWindow[]): Promise<void>;
+    /**
+     * Resolves a dynamic grid fee to a flat **15-minute series** over the
+     * requested range — the same resolution
+     * {@link EnergyAppEnergyPrices.getPrices} uses, so both series can be
+     * combined interval by interval.
+     *
+     * The fee is selected by `gridFeeId` or `meteringPointId`; with no selector
+     * the grid fee that applies to this device is used. Grid fees are **not**
+     * bound to a tariff — a network charge is a property of the grid connection,
+     * and the same fee applies no matter which supplier the site buys from.
+     * Returns `null` when no fee matches the selector.
+     *
+     * Intervals no window covers resolve to `feePerKwh: 0`, and intervals
+     * outside the fee's `validFromIso` / `validUntilIso` window are omitted.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @param filter - The time range and the selector identifying which fee to resolve
+     * @returns Promise that resolves to the 15-minute fee series, or `null` when no fee applies
+     *
+     * @example
+     * ```typescript
+     * const fees = await gridFee.getDynamicGridFees({
+     *     fromIso: '2026-09-02T00:00:00Z',
+     *     untilIso: '2026-09-03T00:00:00Z',
+     * });
+     * fees?.entries.forEach(e => console.log(e.timestampIso, e.feePerKwh));
+     * ```
+     */
+    getDynamicGridFees(filter: EnyoDynamicGridFeeFilter): Promise<EnyoDynamicGridFeeSeries | null>;
+    /**
+     * Registers a listener invoked whenever any grid fee is registered, updated
+     * or removed — including when its absolute windows are republished.
+     *
+     * Use it to recompute composed prices without polling: a grid operator that
+     * publishes a new day-ahead series mid-day changes the cost of every future
+     * interval.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @param listener - Callback invoked with the change event
+     * @returns A unique listener id that can be passed to {@link offGridFeeChanged}
+     *
+     * @example
+     * ```typescript
+     * const id = gridFee.onGridFeeChanged(async event => {
+     *     if (event.gridFeeId === myFeeId) await recomputePrices();
+     * });
+     * // later
+     * gridFee.offGridFeeChanged(id);
+     * ```
+     */
+    onGridFeeChanged(listener: (event: EnyoGridFeeChangeEvent) => void | Promise<void>): string;
+    /**
+     * Removes a previously registered grid fee change listener. If the listener
+     * id is unknown, this operation is a no-op.
+     *
+     * @param listenerId - The id returned from {@link onGridFeeChanged}
+     */
+    offGridFeeChanged(listenerId: string): void;
+}

package/dist/packages/energy-app-grid-fee.js

@@ -0,0 +1 @@
+export {};