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

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

@@ -0,0 +1,199 @@
+import { EnyoDynamicGridFee, EnyoDynamicGridFeeRegistration, EnyoGridFeeChangeEvent, EnyoGridFeeInfo, EnyoGridFeeSeries, EnyoGridFeeValuesFilter } from '../types/enyo-grid-fee.cjs';
+/**
+ * Interface for publishing and consuming grid fees (network charges).
+ *
+ * Five methods, split by role. A **producer** — an app that knows the local grid
+ * operator's tariff sheet or fetches a published series — owns
+ * {@link registerGridFee} and {@link removeGridFee}. A **consumer** asks
+ * {@link getGridFee} what applies and {@link getGridFeeValues} for the numbers
+ * over a range, and subscribes with {@link onGridFeeChanged}. Nothing else is
+ * needed, so nothing else is offered.
+ *
+ * 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. This API is the *only* place a
+ * grid fee lives — a tariff declares nothing about how the fee is determined,
+ * so there is no second source to reconcile against.
+ *
+ * **A site has exactly one grid fee.** It has one grid connection, and the
+ * operator of that connection publishes one network charge for it. So nothing
+ * here takes an identifier: registering replaces whatever was there, and reading
+ * needs no selector.
+ *
+ * **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
+ * price series' `includes` list and composes the effective price
+ * itself with `composeElectricityPrices()`. That flag is the one thing a tariff
+ * says about grid fees, and it describes the provider's price feed rather than
+ * the fee.
+ *
+ * @example
+ * ```typescript
+ * // Producer: a §14a EnWG module 3 HT/NT network charge
+ * const gridFee = energyApp.useGridFee();
+ * await gridFee.registerGridFee({
+ *     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.getGridFeeValues({
+ *     fromIso: new Date().toISOString(),
+ *     untilIso: new Date(Date.now() + 86_400_000).toISOString(),
+ * });
+ * ```
+ */
+export interface EnergyAppGridFee {
+    /**
+     * Sets the site's grid fee, replacing whatever was registered before.
+     *
+     * Full replacement is the only write there is, and it is enough for every
+     * case — correcting a name, moving to next year's tariff sheet, or
+     * republishing a day-ahead schedule are all "here is the fee now". A partial
+     * update would only add a second way to say the same thing, and a
+     * schedule-only write would let metadata and windows drift apart.
+     *
+     * There is no identifier and no create-versus-update distinction: the site
+     * has one grid connection and therefore one grid fee. Two apps that both
+     * register one will overwrite each other, so an app should only publish a
+     * fee it is actually authoritative for.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @param registration - The complete grid fee, including its schedule
+     * @returns Promise that resolves to the stored grid fee, including the host-assigned `publishedAtIso`
+     *
+     * @example
+     * ```typescript
+     * // Republishing tomorrow's day-ahead windows is the same call.
+     * await gridFee.registerGridFee({...fee, schedule: {
+     *     type: EnyoPriceScheduleTypeEnum.Absolute,
+     *     windows: tomorrowsWindows,
+     * }});
+     * ```
+     */
+    registerGridFee(registration: EnyoDynamicGridFeeRegistration): Promise<EnyoDynamicGridFee>;
+    /**
+     * Removes the site's grid fee. {@link getGridFee} and
+     * {@link getGridFeeValues} resolve to `null` afterwards. If no fee is
+     * registered, this operation is a no-op.
+     *
+     * Requires the `GridFeeRegister` permission.
+     *
+     * @returns Promise that resolves when the grid fee has been removed
+     */
+    removeGridFee(): Promise<void>;
+    /**
+     * Answers "what grid fee applies here?" in one call.
+     *
+     * This is the entry point for consuming a grid fee. The returned
+     * {@link EnyoGridFeeInfo} says whether the fee is
+     * {@link EnyoGridFeeTypeEnum.Static static} or
+     * {@link EnyoGridFeeTypeEnum.Dynamic dynamic}, carries the gross cent per
+     * kWh outright when it is static, and reports any additional fixed charges
+     * separately. A static fee needs no second call; a dynamic one is fetched
+     * interval by interval with {@link getGridFeeValues}.
+     *
+     * Takes no arguments — the site has one grid fee, so there is nothing to
+     * select. Returns `null` when none is registered, which is a normal answer
+     * and not an error.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @returns Promise resolving to the site's grid fee, or `null` when none is registered
+     *
+     * @example
+     * ```typescript
+     * const fee = await gridFee.getGridFee();
+     * if (fee?.type === EnyoGridFeeTypeEnum.Static) {
+     *     show(fee.grossCentPerKwh, fee.additionalFeesGrossCentPerKwh);
+     * } else if (fee) {
+     *     const series = await gridFee.getGridFeeValues({fromIso, untilIso});
+     * }
+     * ```
+     */
+    getGridFee(): Promise<EnyoGridFeeInfo | null>;
+    /**
+     * Resolves the applicable grid fee to a flat **15-minute series** of gross
+     * cent per kWh over the requested range — the same resolution
+     * {@link EnergyAppEnergyPrices.getPrices} uses, so both series can be
+     * combined interval by interval.
+     *
+     * Works for every fee, static or dynamic: a flat charge resolves to a series
+     * whose entries all carry the same amount, so a caller that only wants
+     * numbers over a range never has to branch on {@link EnyoGridFeeInfo.type}
+     * at all.
+     *
+     * Set `includeAdditionalFees` to fold the fee's fixed charges into every
+     * interval and get the full gross charge per kWh; leave it off for the
+     * network charge alone. The result reports which of the two you got in
+     * {@link EnyoGridFeeSeries.includesAdditionalFees}, so a fee that declares
+     * no additional charges is never mistaken for a total.
+     *
+     * Returns `null` when the site has no grid fee registered. Intervals no
+     * window covers resolve to `0`, and intervals outside the fee's
+     * `validFromIso` / `validUntilIso` window are omitted.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @param filter - The time range and whether to include additional fees
+     * @returns Promise that resolves to the 15-minute fee series, or `null` when no fee applies
+     *
+     * @example
+     * ```typescript
+     * // network charge only
+     * const net = await gridFee.getGridFeeValues({fromIso, untilIso});
+     *
+     * // everything the customer pays per kWh
+     * const total = await gridFee.getGridFeeValues({
+     *     fromIso,
+     *     untilIso,
+     *     includeAdditionalFees: true,
+     * });
+     * total?.entries.forEach(e => console.log(e.timestampIso, e.grossCentPerKwh));
+     * ```
+     */
+    getGridFeeValues(filter: EnyoGridFeeValuesFilter): Promise<EnyoGridFeeSeries | null>;
+    /**
+     * Registers a listener invoked whenever any grid fee is registered, replaced
+     * or removed.
+     *
+     * 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.
+     *
+     * Returns the unsubscribe function directly rather than an id to hand back
+     * to a second method — calling it twice is a no-op.
+     *
+     * Requires the `GridFeeUse` permission.
+     *
+     * @param listener - Callback invoked with the change event
+     * @returns A function that removes this listener when called
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = gridFee.onGridFeeChanged(async () => {
+     *     await recomputePrices();
+     * });
+     * // later
+     * unsubscribe();
+     * ```
+     */
+    onGridFeeChanged(listener: (event: EnyoGridFeeChangeEvent) => void | Promise<void>): () => void;
+}

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

@@ -53,6 +53,18 @@ export interface ModbusOptions {
     staleSocketMs?: number;
     /** TCP keepalive idle interval in ms on the live socket, so a dead peer surfaces fast. Default 10000; 0 disables. */
     keepAliveMs?: number;
+    /**
+     * When `true`, the connection is taken from a shared pool of sockets keyed by the target
+     * device (host, port, unit id and transport settings) instead of opening a socket that belongs
+     * exclusively to this caller. Pooling lets several parts of an app — or several `connect()`
+     * calls for the same device — reuse one TCP connection, which matters for devices that accept
+     * only a small number of simultaneous Modbus clients. A pooled instance's `disconnect()`
+     * releases the connection back to the pool rather than necessarily closing the socket, and the
+     * socket stays open while other users still hold it.
+     *
+     * Defaults to `true` (a dedicated connection per `connect()` call).
+     */
+    pooledConnection?: boolean;
 }
 /**
  * Interface for Modbus TCP/IP communication in enyo packages.

package/dist/cjs/types/enyo-charge.d.cts

@@ -118,77 +118,6 @@ export interface EnyoCharge {
     /** Target completion time for the charging session as an ISO 8601 timestamp */
     completeAtIsoTimestamp?: string;
 }
-/**
- * What is known when a charging session opens — the input to
- * {@link EnergyAppCharge.startCharge}.
- *
- * Everything here is fact at plug-in time. The totals a session is judged by
- * ({@link EnyoCharge.totalEnergyKwh}, {@link EnyoCharge.paidPriceEuroCent}) are
- * absent on purpose: they are the host's to compute when the session ends, from
- * the meter readings and the tariff in force while the energy flowed.
- */
-export interface EnyoStartChargeRequest {
-    /** The appliance (charger) running the session. */
-    applianceId: string;
-    /**
-     * The charger's transaction ID for this session (OCPP `transactionId` or
-     * the protocol's equivalent).
-     *
-     * Together with `applianceId` this identifies the session: two chargers may
-     * independently issue the same transaction ID, so it is unique per
-     * appliance, not globally. It is also the idempotency key —
-     * {@link EnergyAppCharge.startCharge} returns the existing session rather
-     * than opening a second one when this pair is already active.
-     */
-    transactionId: string;
-    /** When charging started. Defaults to the moment the host handles the call. */
-    startTime?: Date;
-    /** The charger's meter reading at session start, in Watt hours. */
-    meterStartValueWh?: number;
-    /** Connector on the charge point the vehicle is plugged into. */
-    connectorId?: number;
-    /** The charging card that authorized the session, if any. */
-    chargingCardId?: string;
-    /** The vehicle being charged, if known. */
-    vehicleId?: string;
-    /** Number of phases charging over. Defaults to 3. */
-    numberOfPhases?: number;
-    /** Charging mode to apply. Defaults to the appliance's configured default. */
-    chargeMode?: EnyoChargeModeEnum;
-    /** Target completion time as an ISO 8601 timestamp, for optimized modes. */
-    completeAtIsoTimestamp?: string;
-}
-/**
- * How a charging session ended — the input to
- * {@link EnergyAppCharge.stopCharge}.
- *
- * Meter readings, not totals: give the host what the charger reported and it
- * derives the delivered energy and the price. See
- * {@link EnergyAppCharge.stopCharge}.
- */
-export interface EnyoStopChargeRequest {
-    /** When charging ended. Defaults to the moment the host handles the call. */
-    endTime?: Date;
-    /** The charger's meter reading at session end, in Watt hours. */
-    meterEndValueWh?: number;
-    /**
-     * Energy delivered over the session in Watt hours, when the charger reports
-     * it directly (OCPP `StopTransaction`).
-     *
-     * Preferred over the meter delta when present — a charger that meters its
-     * own session knows better than a subtraction across two readings that may
-     * span a meter reset.
-     */
-    energyDeliveredWh?: number;
-    /**
-     * How the session ended. Defaults to {@link EnyoChargeStatus.Completed};
-     * pass {@link EnyoChargeStatus.Failed} for a session cut short by a fault.
-     *
-     * Both are terminal and both fire the stopped listener — a handler that
-     * assumes success will mis-report faulted sessions.
-     */
-    status?: EnyoChargeStatus;
-}
 /**
  * Represents a single entry in a charging schedule.
  * Defines a time-bound current limit for smart charging.

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -646,6 +646,13 @@ export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
         vehicleId?: string;
         /** Meter reading at session start in Watt hours */
         meterValueWh: number;
+        /**
+         * Number of phases the vehicle is charging over, when the charger
+         * reports it. Defaults to 3 when omitted — a single-phase session left
+         * unset is billed and forecast as if it drew three times the current it
+         * really does.
+         */
+        numberOfPhases?: number;
     };
 }
 export interface EnyoDataBusChargingMeterValuesV1 extends EnyoDataBusMessage {

package/dist/cjs/types/enyo-electricity-tariff.cjs

@@ -1,15 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ElectricityTariffTypeEnum = void 0;
-/**
- * Enum representing the type of electricity tariff pricing model
- */
-var ElectricityTariffTypeEnum;
-(function (ElectricityTariffTypeEnum) {
-    /** Fixed price that doesn't change over time */
-    ElectricityTariffTypeEnum["Static"] = "static";
-    /** Price varies based on time of day (e.g., peak/off-peak) */
-    ElectricityTariffTypeEnum["TimeVariable"] = "time-variable";
-    /** Price changes dynamically based on market conditions */
-    ElectricityTariffTypeEnum["Dynamic"] = "dynamic";
-})(ElectricityTariffTypeEnum || (exports.ElectricityTariffTypeEnum = ElectricityTariffTypeEnum = {}));
+exports.EnyoTariffChangeTypeEnum = exports.EnyoTariffActivationStatusEnum = exports.EnyoPriceComponentEnum = exports.EnyoTariffPricingTypeEnum = exports.EnyoTariffDirectionEnum = void 0;
+/**
+ * Which direction of energy flow a tariff prices.
+ *
+ * A site has exactly one tariff per direction: what it pays for energy drawn
+ * from the grid, and what it earns for energy fed back. These are the two slots
+ * the whole tariff API is built around — a tariff is not registered into a list
+ * and later marked default, it is set into one of these two places.
+ *
+ * Deliberately not {@link EnyoPriceAppliesToEnum}, which carries a third member
+ * (`Both`) that a slot cannot be.
+ */
+var EnyoTariffDirectionEnum;
+(function (EnyoTariffDirectionEnum) {
+    /** Energy drawn from the grid — what the customer pays. */
+    EnyoTariffDirectionEnum["Consumption"] = "consumption";
+    /** Energy fed into the grid — what the customer earns. */
+    EnyoTariffDirectionEnum["FeedIn"] = "feed-in";
+})(EnyoTariffDirectionEnum || (exports.EnyoTariffDirectionEnum = EnyoTariffDirectionEnum = {}));
+/**
+ * The pricing model a tariff follows.
+ */
+var EnyoTariffPricingTypeEnum;
+(function (EnyoTariffPricingTypeEnum) {
+    /** One price that does not change over time. */
+    EnyoTariffPricingTypeEnum["Static"] = "static";
+    /** Price varies by time of day, weekday or season (e.g. peak/off-peak). */
+    EnyoTariffPricingTypeEnum["TimeVariable"] = "time-variable";
+    /** Price changes with the market and is published as a dated series. */
+    EnyoTariffPricingTypeEnum["Dynamic"] = "dynamic";
+})(EnyoTariffPricingTypeEnum || (exports.EnyoTariffPricingTypeEnum = EnyoTariffPricingTypeEnum = {}));
+/**
+ * A cost component that may or may not already be contained in a published
+ * price.
+ *
+ * Provider APIs differ: some return all-in prices with network charges, levies
+ * and discounts baked in, others return the pure energy price. A consumer must
+ * never add a component that is already there, so the publishing app declares
+ * what its prices contain — see {@link EnyoTariffPriceSeries.includes}.
+ */
+var EnyoPriceComponentEnum;
+(function (EnyoPriceComponentEnum) {
+    /** The grid operator's network charge. */
+    EnyoPriceComponentEnum["GridFee"] = "grid-fee";
+    /** Taxes and statutory levies. */
+    EnyoPriceComponentEnum["TaxesAndLevies"] = "taxes-and-levies";
+    /** Discounts granted on top of the tariff. */
+    EnyoPriceComponentEnum["Bonuses"] = "bonuses";
+})(EnyoPriceComponentEnum || (exports.EnyoPriceComponentEnum = EnyoPriceComponentEnum = {}));
+/**
+ * The outcome of a user choosing a tariff.
+ */
+var EnyoTariffActivationStatusEnum;
+(function (EnyoTariffActivationStatusEnum) {
+    /** The tariff is set and usable; prices can be published. */
+    EnyoTariffActivationStatusEnum["Success"] = "success";
+    /** The user must authenticate with the provider before the tariff works. */
+    EnyoTariffActivationStatusEnum["AuthenticationRequired"] = "authentication-required";
+    /** The user must complete an onboarding guide before the tariff works. */
+    EnyoTariffActivationStatusEnum["OnboardingRequired"] = "onboarding-required";
+    /** The tariff could not be activated. */
+    EnyoTariffActivationStatusEnum["Failed"] = "failed";
+})(EnyoTariffActivationStatusEnum || (exports.EnyoTariffActivationStatusEnum = EnyoTariffActivationStatusEnum = {}));
+/**
+ * What happened to a direction slot.
+ */
+var EnyoTariffChangeTypeEnum;
+(function (EnyoTariffChangeTypeEnum) {
+    /** A tariff was set into a slot that was empty, or replaced the one in it. */
+    EnyoTariffChangeTypeEnum["Set"] = "set";
+    /** The slot was emptied. */
+    EnyoTariffChangeTypeEnum["Cleared"] = "cleared";
+})(EnyoTariffChangeTypeEnum || (exports.EnyoTariffChangeTypeEnum = EnyoTariffChangeTypeEnum = {}));