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

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;
+}

package/dist/cjs/implementations/pricing/price-schedule-resolver.d.cts

@@ -0,0 +1,95 @@
+import { EnyoPriceSchedule, EnyoResolvedPriceEntry } from '../../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.
+ */
+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/cjs/index.cjs

@@ -152,3 +152,10 @@ __exportStar(require("./packages/energy-app-epex-spot-price.cjs"), exports);
 __exportStar(require("./types/enyo-automation.cjs"), exports);
 __exportStar(require("./packages/energy-app-automation.cjs"), exports);
 __exportStar(require("./implementations/automation/automation-validators.cjs"), exports);
+__exportStar(require("./types/enyo-price-schedule.cjs"), exports);
+__exportStar(require("./types/enyo-grid-fee.cjs"), exports);
+__exportStar(require("./types/enyo-price-composition.cjs"), exports);
+__exportStar(require("./packages/energy-app-grid-fee.cjs"), exports);
+__exportStar(require("./implementations/pricing/price-schedule-resolver.cjs"), exports);
+__exportStar(require("./implementations/pricing/price-component-validators.cjs"), exports);
+__exportStar(require("./implementations/pricing/compose-electricity-prices.cjs"), exports);

package/dist/cjs/index.d.cts

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

package/dist/cjs/packages/energy-app-charge.d.cts

@@ -1,93 +1,20 @@
-import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode, EnyoStartChargeRequest, EnyoStopChargeRequest } from "../types/enyo-charge.cjs";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.cjs";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
  */
 export interface EnergyAppCharge {
-    /**
-     * Opens a charging session for an appliance and returns it.
-     *
-     * Use this to start a session — not {@link save}. `save` writes whatever
-     * object it is given and offers no uniqueness guarantee, so two
-     * StartTransactions arriving a few milliseconds apart both pass an app-side
-     * "is one already active?" check and create two sessions for one plug-in.
-     * This call is handled by the host, which holds the invariant that an
-     * appliance has at most one active charge.
-     *
-     * **Idempotent.** When a session is already active for the same
-     * `applianceId` + `transactionId`, that session is returned unchanged
-     * rather than a second one being created — a repeated StartTransaction is
-     * safe. A session that is active on the appliance under a *different*
-     * transaction ID is treated as over: the host finalises it with best-effort
-     * end values before opening this one. If it is really the same physical
-     * session continuing under a new transaction ID (a reconnect, a
-     * re-authorization), use {@link addTransactionIdToActiveCharge} instead.
-     *
-     * The returned charge carries its `id`, so the session can be updated and
-     * later stopped without a {@link findActiveCharge} round-trip first.
-     *
-     * **Required permission:** `Charge`.
-     *
-     * @param request - What is known at plug-in time.
-     * @returns Promise resolving to the started session — or the session that
-     *          was already running for this appliance and transaction.
-     *
-     * @example
-     * ```typescript
-     * const charge = await energyApp.useCharge().startCharge({
-     *     applianceId,
-     *     transactionId: ocppTransactionId,
-     *     meterStartValueWh: meterValue,
-     *     connectorId: 1,
-     * });
-     * ```
-     */
-    startCharge: (request: EnyoStartChargeRequest) => Promise<EnyoCharge>;
-    /**
-     * Closes a charging session and returns the final record.
-     *
-     * The host does the arithmetic, and that is the point of this call: it
-     * derives {@link EnyoCharge.totalEnergyKwh} and
-     * {@link EnyoCharge.paidPriceEuroCent} from the session's meter readings
-     * and the electricity tariff in force while the energy flowed, then moves
-     * the session to a terminal status and notifies
-     * {@link listenForChargeStopped}. An app must not price a session itself —
-     * totals computed app-side would differ between apps, and a customer's bill
-     * would depend on which app happened to close the charge.
-     *
-     * Supply readings, not totals: `meterEndValueWh` and, when the charger
-     * reports it, `energyDeliveredWh`. Anything an app writes into
-     * `paidPriceEuroCent` via {@link save} is overwritten here.
-     *
-     * Stopping a session that is already in a terminal status is a no-op and
-     * returns the stored record — a duplicate StopTransaction will not re-price
-     * a finished charge.
-     *
-     * **Required permission:** `Charge`.
-     *
-     * @param chargeId - The session to close, as returned by
-     *   {@link startCharge} or {@link findActiveCharge}.
-     * @param request - How the session ended.
-     * @returns Promise resolving to the final charge record, totals included.
-     *
-     * @example
-     * ```typescript
-     * const finished = await energyApp.useCharge().stopCharge(charge.id, {
-     *     meterEndValueWh: meterValue,
-     *     energyDeliveredWh: stopTransaction.energyWh,
-     * });
-     * console.log(`${finished.totalEnergyKwh} kWh for ${finished.paidPriceEuroCent} ct`);
-     * ```
-     */
-    stopCharge: (chargeId: string, request: EnyoStopChargeRequest) => Promise<EnyoCharge>;
     /**
      * Save or update a charging session in the system.
      *
      * This is a whole-object write for a session that already exists — a
-     * changed vehicle, a corrected reading. Use {@link startCharge} to open a
-     * session and {@link stopCharge} to close one: calling this without a
-     * `chargeId` creates a row with no uniqueness guarantee, and writing
-     * terminal values by hand skips the host's energy and cost calculation.
+     * changed vehicle, a corrected reading. Calling it without a `chargeId`
+     * creates a row with no uniqueness guarantee, so two StartTransactions
+     * arriving a few milliseconds apart both pass an app-side "is one already
+     * active?" check and create two sessions for one plug-in. Writing terminal
+     * values by hand also skips the host's energy and cost calculation, which
+     * is what turns meter readings into {@link EnyoCharge.totalEnergyKwh} and
+     * {@link EnyoCharge.paidPriceEuroCent}.
      */
     save: (charge: Omit<EnyoCharge, 'id'>, chargeId?: string) => Promise<void>;
     /** Get a list of charging sessions with optional filtering */

package/dist/cjs/packages/energy-app-electricity-tariff.d.cts

@@ -1,63 +1,175 @@
-import { EnyoElectricityTariff, EnyoElectricityTariffWithDefault } from "../types/enyo-electricity-tariff.cjs";
+import { EnyoElectricityTariff, EnyoTariffActivationResult, EnyoTariffChangeEvent, EnyoTariffDirectionEnum, EnyoTariffPricePublication, EnyoTariffPriceSeries } from "../types/enyo-electricity-tariff.cjs";
 /**
- * Interface for managing electricity tariffs.
- * Provides methods to register, retrieve, and remove electricity tariffs
- * used for energy pricing and consumption calculations.
+ * The time range a price query covers.
+ */
+export interface EnyoTariffPriceRange {
+    /** Start of the requested range in ISO format (inclusive). */
+    fromIso: string;
+    /** End of the requested range in ISO format (exclusive). */
+    untilIso: string;
+}
+/**
+ * Interface for reading and supplying the site's electricity tariffs.
+ *
+ * A site has **two tariff slots** — one for consumption, one for feed-in — and
+ * everything here addresses them by {@link EnyoTariffDirectionEnum}. There is no
+ * list of tariffs, no default flag and no tariff id: occupying a slot is what it
+ * means to be the tariff in force.
+ *
+ * Six methods, split by role. A **consumer** asks {@link getTariff} what applies
+ * and {@link getPrices} what it costs, and follows {@link onTariffChanged}. An
+ * **owner** — the app integrating a provider like Tibber or Ostrom — answers
+ * {@link onTariffSelected} when the user picks it, calls {@link setTariff} once
+ * its tariff is usable, and feeds {@link publishPrices} as new prices arrive.
+ *
+ * A tariff carries no grid fee. A network charge belongs to the site's grid
+ * connection, not to the supplier contract — read it from `useGridFee()` and
+ * combine the two with `composeElectricityPrices()`.
+ *
+ * @example
+ * ```typescript
+ * const tariffs = energyApp.useElectricityTariff();
+ *
+ * // Owner: the user picked us in the app UI.
+ * tariffs.onTariffSelected(async direction => {
+ *     if (!await isAuthenticated()) {
+ *         return {
+ *             status: EnyoTariffActivationStatusEnum.AuthenticationRequired,
+ *             authenticationUrl: buildOAuthUrl(direction),
+ *         };
+ *     }
+ *     await tariffs.setTariff(direction, myTariff);
+ *     return {status: EnyoTariffActivationStatusEnum.Success};
+ * });
+ * ```
  */
 export interface EnergyAppElectricityTariff {
     /**
-     * Registers a new electricity tariff or updates an existing one.
-     * Uses upsert logic based on tariffId - if a tariff with the same ID exists,
-     * it will be updated; otherwise, a new tariff will be created.
+     * Returns the tariff currently filling a direction slot, whichever app owns
+     * it, or `null` when the slot is empty.
      *
-     * @param tariff - The tariff registration data including ID, type, name, and vendor
-     * @returns Promise that resolves when the tariff has been registered
+     * `null` is a normal answer — a site with no feed-in contract has no feed-in
+     * tariff — and not an error.
+     *
+     * @param direction - Which slot to read
+     * @returns Promise resolving to the tariff in that slot, or `null`
      */
-    registerTariff(tariff: Omit<EnyoElectricityTariff, 'id'>): Promise<EnyoElectricityTariffWithDefault>;
+    getTariff(direction: EnyoTariffDirectionEnum): Promise<EnyoElectricityTariff | null>;
     /**
-     * Retrieves all registered electricity tariffs.
-     * Each tariff includes a defaultTariff boolean indicating whether
-     * it is the system default tariff.
+     * Returns prices for one direction over a time range, as a **15-minute
+     * series** — the same resolution `useGridFee().getGridFeeValues()` and
+     * `useEpexSpotPrices().getPrices()` use, so all three zip index-by-index.
+     *
+     * The host serves this from what the slot's owning app published with
+     * {@link publishPrices}, so a consumer never has to know which app is behind
+     * the tariff. Returns `null` when the slot is empty or nothing has been
+     * published covering the range.
+     *
+     * Read {@link EnyoTariffPriceSeries.includes} before adding anything to
+     * these prices: a series that already contains the grid fee must not have
+     * one added on top.
      *
-     * @returns Promise that resolves to an array of all registered tariffs with default indicators
+     * @param direction - Which slot to price
+     * @param range - The time range to cover
+     * @returns Promise resolving to the price series, or `null` when none applies
+     *
+     * @example
+     * ```typescript
+     * const prices = await tariffs.getPrices(EnyoTariffDirectionEnum.Consumption, {
+     *     fromIso, untilIso,
+     * });
+     * const needsGridFee = !prices?.includes.includes(EnyoPriceComponentEnum.GridFee);
+     * ```
      */
-    getAllTariffs(filter?: {
-        myTariffs?: boolean;
-    }): Promise<EnyoElectricityTariffWithDefault[]>;
+    getPrices(direction: EnyoTariffDirectionEnum, range: EnyoTariffPriceRange): Promise<EnyoTariffPriceSeries | null>;
     /**
-     * Removes an electricity tariff by its ID.
-     * If the tariff does not exist, this operation is a no-op.
+     * Puts this app's tariff into a direction slot, replacing whatever was
+     * there.
+     *
+     * **Calling this is the activation signal.** An app calls it once its tariff
+     * is actually usable — credentials valid, contract fetched — whether that is
+     * immediately when the user selects it or later, when an OAuth redirect
+     * comes back or an onboarding guide completes. There is nothing else to
+     * report afterwards.
+     *
+     * Full replacement is the only write there is: a partial update would let an
+     * app half-change a tariff another app owns. Re-setting an unchanged tariff
+     * is harmless, so an app that refetches its contract on every start can call
+     * this unconditionally.
+     *
+     * The returned {@link EnyoTariffActivationResult} is the host's answer, not
+     * the app's — it reports whether the slot is now live or whether the host
+     * still needs something from the user.
+     *
+     * Requires the `ElectricityTariff` permission.
      *
-     * @param id - The unique identifier of the tariff to remove
-     * @returns Promise that resolves when the tariff has been removed
+     * @param direction - Which slot to fill
+     * @param tariff - The tariff and its pricing details
+     * @returns Promise resolving to the activation outcome
      */
-    removeTariff(id: string): Promise<void>;
+    setTariff(direction: EnyoTariffDirectionEnum, tariff: EnyoElectricityTariff): Promise<EnyoTariffActivationResult>;
     /**
-     * Requests to make a tariff the default tariff.
+     * Publishes prices for a slot this app owns.
      *
-     * @param id - The unique identifier of the tariff
-     * @returns Promise that resolves with the result
+     * Push, not pull: providers hand out prices on their own schedule — day-ahead
+     * prices land in the afternoon, and provider APIs are rate-limited — so an
+     * app fetches when it makes sense and publishes what it got. The host serves
+     * those to every {@link getPrices} caller afterwards.
+     *
+     * Entries replace previously published entries with the same timestamp and
+     * leave the rest alone, so republishing a corrected day does not erase the
+     * days around it.
+     *
+     * Declare in {@link EnyoTariffPricePublication.includes} what the prices
+     * already contain. An app that folds the grid fee in before publishing must
+     * say so, or every consumer will add it a second time.
+     *
+     * Fails when this app does not own the slot — only the tariff's owner may
+     * price it.
+     *
+     * Requires the `ElectricityTariff` permission.
+     *
+     * @param direction - Which slot the prices belong to
+     * @param prices - The priced intervals and what they already contain
+     * @returns Promise that resolves once the prices are stored and listeners dispatched
      */
-    makeDefaultTariff(id: string): Promise<'accepted' | 'rejected'>;
+    publishPrices(direction: EnyoTariffDirectionEnum, prices: EnyoTariffPricePublication): Promise<void>;
     /**
-     * Retrieves the system default tariff information.
-     * Returns the full tariff including pricing data.
+     * Registers the handler the host calls when the user picks this app's tariff
+     * for a direction — "this should be my consumption tariff".
      *
-     * @returns Promise that resolves to the default tariff info, or null if none is configured
+     * Not a notification: the handler runs the app's activation flow and reports
+     * what it found. Returning
+     * {@link EnyoTariffActivationStatusEnum.AuthenticationRequired} or
+     * {@link EnyoTariffActivationStatusEnum.OnboardingRequired} tells the host to
+     * send the user somewhere, so carry the `authenticationUrl` or
+     * `onboardingGuideId` that makes it actionable. When the flow later
+     * completes, call {@link setTariff} — that is what marks the tariff live.
+     *
+     * Returning {@link EnyoTariffActivationStatusEnum.Success} without having
+     * called {@link setTariff} leaves the slot empty; return it only when the
+     * tariff is already set.
+     *
+     * One handler per app. Registering again replaces the previous one.
+     *
+     * @param handler - Called with the direction the user selected this app for
+     * @returns A function that removes the handler when called
      */
-    getDefaultTariff(): Promise<EnyoElectricityTariff | null>;
-    findTariff(filter: {
-        applianceId?: string;
-        tariffId?: string;
-        externalTariffId?: string;
-    }): Promise<EnyoElectricityTariffWithDefault | null>;
+    onTariffSelected(handler: (direction: EnyoTariffDirectionEnum) => Promise<EnyoTariffActivationResult>): () => void;
     /**
-     * Partially updates an existing electricity tariff.
-     * Only the provided attributes will be modified; all other fields remain unchanged.
+     * Registers a listener invoked whenever either slot changes — a tariff set,
+     * replaced, or cleared.
+     *
+     * This is the signal to recompose prices. It fires for changes made by every
+     * app, so filter on {@link EnyoTariffChangeEvent.direction} when only one
+     * slot matters, and compare
+     * {@link EnyoElectricityTariff.externalTariffId} against your own to notice
+     * that a slot you were publishing for is now owned by someone else.
+     *
+     * Returns the unsubscribe function directly; calling it twice is a no-op.
      *
-     * @param id - The unique identifier of the tariff to update
-     * @param attributes - A partial set of tariff fields to update (excluding `id`)
-     * @returns Promise that resolves to the full updated tariff with its default indicator
+     * @param listener - Callback invoked with the change event
+     * @returns A function that removes this listener when called
      */
-    updateTariff(id: string, attributes: Partial<Omit<EnyoElectricityTariff, 'id'>>): Promise<EnyoElectricityTariffWithDefault>;
+    onTariffChanged(listener: (event: EnyoTariffChangeEvent) => void | Promise<void>): () => void;
 }

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });