@enyo-energy/energy-app-sdk 0.0.190 → 0.0.192

package/README.md

@@ -757,18 +757,33 @@ the update callback cheap.
 
 #### `useChargingCard(): EnergyAppChargingCard`
 
-Handle charging authentication:
+Read registered charging cards and pair new RFID cards:
 
 ```typescript
 const chargingCards = energyApp.useChargingCard();
 
-// Validate charging card
-const isValid = await chargingCards.validateCard('RFID-12345');
+// List all registered charging cards
+const cards = await chargingCards.list();
 
-// Get card information
-const cardInfo = await chargingCards.getCardInfo('RFID-12345');
+// Get a single card
+const card = await chargingCards.getById('card-id');
+
+// Handle pairing requests coming from the app
+const listenerId = chargingCards.listenForPairingStarted(async (request) => {
+    // Put the reader into pairing mode and wait for a card to be presented.
+    // Resolve with the RFID read from the card - the host assigns it to
+    // request.chargingCardId and clears its pendingRegistration flag.
+    return await charger.enterPairingMode(request.applianceId, request.timeoutMs);
+});
+
+chargingCards.removeListener(listenerId);
 ```
 
+Reject the promise returned by the pairing listener when no card was presented or
+the charger refused to enter pairing mode - the host then reports the attempt as
+failed and leaves the card pending. A package managing several chargers should
+check `request.applianceId` and reject requests for appliances it does not own.
+
 ### User Features
 
 #### `useAuthentication(): EnergyAppAuthentication`

package/dist/cjs/index.cjs

@@ -83,6 +83,8 @@ __exportStar(require("./packages/energy-app-configuration-manager.cjs"), exports
 __exportStar(require("./types/enyo-air-conditioning-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heating-rod-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-charger-appliance.cjs"), exports);
+__exportStar(require("./types/enyo-charging-card.cjs"), exports);
+__exportStar(require("./packages/energy-app-charging-card.cjs"), exports);
 __exportStar(require("./types/enyo-battery-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-heatpump-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-inverter-appliance.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -67,6 +67,8 @@ export * from './packages/energy-app-configuration-manager.cjs';
 export * from './types/enyo-air-conditioning-appliance.cjs';
 export * from './types/enyo-heating-rod-appliance.cjs';
 export * from './types/enyo-charger-appliance.cjs';
+export * from './types/enyo-charging-card.cjs';
+export * from './packages/energy-app-charging-card.cjs';
 export * from './types/enyo-battery-appliance.cjs';
 export * from './types/enyo-heatpump-appliance.cjs';
 export * from './types/enyo-inverter-appliance.cjs';

package/dist/cjs/packages/energy-app-charging-card.d.cts

@@ -1,11 +1,56 @@
-import { EnyoChargingCard } from "../types/enyo-charging-card.cjs";
+import { EnyoChargingCard, EnyoChargingCardPairingRequest } from "../types/enyo-charging-card.cjs";
 /**
  * Interface for managing charging cards in enyo packages.
- * Provides read-only operations for charging card information.
+ * Provides read-only operations for charging card information as well as
+ * RFID pairing support.
  */
 export interface EnergyAppChargingCard {
     /** Get a list of all registered charging cards */
     list: () => Promise<EnyoChargingCard[]>;
     /** Get a specific charging card by its ID */
     getById: (id: string) => Promise<EnyoChargingCard | null>;
+    /**
+     * Listen for pairing requests, i.e. the host asking this package to put its
+     * RFID reader into pairing mode — typically because a user started adding a
+     * new charging card in the app.
+     *
+     * The listener owns the whole pairing attempt: it enables pairing mode on
+     * the charger, waits for a card to be held against the reader and resolves
+     * with the RFID identifier that was read (the value stored in
+     * {@link EnyoChargingCard.rfid}). The host assigns it to the charging card
+     * named by {@link EnyoChargingCardPairingRequest.chargingCardId} and clears
+     * that card's {@link EnyoChargingCard.pendingRegistration} flag.
+     *
+     * Reject the returned promise when no card was presented or the charger
+     * refused to enter pairing mode; the host then reports the attempt as
+     * failed and leaves the card pending. Honour
+     * {@link EnyoChargingCardPairingRequest.timeoutMs} when it is set — the host
+     * ignores a result that arrives after the deadline.
+     *
+     * Only register a listener when the package actually drives an RFID reader.
+     * Requests carry an optional
+     * {@link EnyoChargingCardPairingRequest.applianceId}; a package managing
+     * several chargers should check it and reject requests for appliances it
+     * does not own.
+     *
+     * @param listener - Callback invoked for every pairing request, resolving
+     *   with the RFID identifier read from the presented card
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * const chargingCard = energyApp.useChargingCard();
+     * const listenerId = chargingCard.listenForPairingStarted(async (request) => {
+     *     const rfid = await charger.enterPairingMode(request.applianceId, request.timeoutMs);
+     *     return rfid;
+     * });
+     * ```
+     */
+    listenForPairingStarted: (listener: (request: EnyoChargingCardPairingRequest) => Promise<string>) => string;
+    /**
+     * Removes a previously registered listener.
+     *
+     * @param listenerId - The ID returned by {@link listenForPairingStarted}
+     */
+    removeListener: (listenerId: string) => void;
 }

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

@@ -98,6 +98,7 @@ export interface EnergyAppDiagnostics {
      *     generatedAtIso: new Date().toISOString(),
      *     announced: [
      *         {
+     *             id: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -110,6 +111,8 @@ export interface EnergyAppDiagnostics {
      *             },
      *         },
      *         {
+     *             id: 'storage:flexible-discharge',
+     *             applianceId: 'battery-1',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,
@@ -124,6 +127,7 @@ export interface EnergyAppDiagnostics {
      *     ],
      *     granted: [
      *         {
+     *             announcementId: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -134,6 +138,7 @@ export interface EnergyAppDiagnostics {
      *             reason: 'grid connection point limit',
      *         },
      *         {
+     *             announcementId: 'storage:flexible-discharge',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,

package/dist/cjs/types/enyo-charging-card.d.cts

@@ -9,3 +9,24 @@ export interface EnyoChargingCard {
     rfid?: string;
     pendingRegistration?: boolean;
 }
+/**
+ * Details of a pairing request handed to a
+ * {@link EnergyAppChargingCard.listenForPairingStarted} listener when the
+ * host asks a package to put its RFID reader into pairing mode.
+ */
+export interface EnyoChargingCardPairingRequest {
+    /** ID of the charging card record the scanned RFID should be assigned to */
+    chargingCardId: string;
+    /**
+     * Appliance (charger) whose RFID reader should enter pairing mode. Omitted
+     * when the host does not target a specific charger — in that case the
+     * package decides which of its readers to use.
+     */
+    applianceId?: string;
+    /**
+     * Time budget, in milliseconds, the package has to deliver a scanned card.
+     * The host stops waiting once it elapses, so a listener that resolves later
+     * has no effect. Omitted when the host does not impose a deadline.
+     */
+    timeoutMs?: number;
+}

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

@@ -15,6 +15,15 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAvailable"] = "pv-surplus-available";
     /** Command issued because PV surplus is unavailable */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusUnavailable"] = "pv-surplus-unavailable";
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */

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

@@ -23,6 +23,15 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     PvSurplusAvailable = "pv-surplus-available",
     /** Command issued because PV surplus is unavailable */
     PvSurplusUnavailable = "pv-surplus-unavailable",
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
@@ -100,6 +109,16 @@ export interface EnyoDataBusCommandReason {
     temperatureC?: number;
     /** Relevant state of charge as a percentage (battery-driven reasons) */
     socPercent?: number;
+    /**
+     * The appliance category the decision was made in favour of.
+     *
+     * Set on reasons that describe a trade-off between appliances — most
+     * notably
+     * {@link EnyoDataBusCommandReasonTypeEnum.PvSurplusAllocatedElsewhere} —
+     * so the end-user text can name the winning appliance (e.g. "the battery")
+     * rather than saying "elsewhere".
+     */
+    inFavourOfApplianceType?: EnyoApplianceTypeEnum;
 }
 /**
  * Whether a grid operator power limitation caps power drawn from the grid

package/dist/cjs/types/enyo-flexibility-announcement.d.cts

@@ -125,11 +125,49 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * For storage announcements: the round-trip cost of cycling the battery, in
+     * EUR per kWh. The floor a discharge has to beat to be worth licensing.
+     */
+    storageCycleCostEurPerKwh?: number;
+    /**
+     * For storage announcements: the physical discharge floor, in Watts. Signed —
+     * negative means discharge, so this is the most negative power the storage can
+     * physically reach.
+     */
+    storageMinPowerW?: number;
+    /** For storage announcements: the physical charge ceiling, in Watts. */
+    storageMaxPowerW?: number;
+    /** For storage announcements: usable capacity of the storage, in Wh. */
+    storageCapacityWh?: number;
+    /**
+     * For storage announcements: the discharge power we will actually command, in
+     * Watts. May be well inside {@link storageMinPowerW} — today it is `0`, i.e. we
+     * license discharge without commanding it.
+     */
+    storageCommandableDischargeW?: number;
+    /**
+     * For storage announcements: whether the storage accepts an explicit
+     * `Discharge 0` command, i.e. can be told to hold rather than only being left
+     * alone.
+     */
+    storageCanHold?: boolean;
 }
 /** Fields shared by every category-scoped flexibility announcement. */
 export interface EnyoCategoryFlexibilityAnnouncementBase {
+    /**
+     * What this announcement IS, stable across cycles — e.g. `storage:peak-requirement`.
+     * A category speaks with several at once and (category, type) does not tell them
+     * apart. REQUIRED: a positional identity changes whenever a neighbour appears.
+     */
+    id: string;
     /** The appliance category this demand aggregates (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
+    /**
+     * The appliance this announcement speaks for, when a category announces per
+     * appliance rather than as one aggregate. Absent = the whole category.
+     */
+    applianceId?: string;
     /** Optional extra context for the decision maker; absent for most announcements. */
     context?: EnyoFlexibilityAnnouncementContext;
 }
@@ -143,6 +181,12 @@ export interface EnyoCategoryRequiredKwhTargetAnnouncement extends EnyoCategoryF
         kwh: number;
         /** Power band the delivery may use. */
         power: EnyoFlexibilityPowerBand;
+        /**
+         * Price ceiling, when the requirement is economic rather than absolute.
+         * Present on the wire today; without it every economic requirement looked
+         * like a MUST-RUN in diagnostics.
+         */
+        priceLimitEuroCent?: number;
     };
 }
 /** Deliver `kwh` flexibly (cost-/PV-optimized), aggregated across the category. */
@@ -224,10 +268,13 @@ export declare enum EnyoCategoryFlexibilityGrantStatusEnum {
  * A grant is deliberately flatter than the announcement it answers: the decision
  * maker replies with one allocation — a window, a power envelope, and (for the
  * energy-target and discharge variants) an amount of energy — regardless of which
- * announcement variant produced it. Pairing is by `category` +
- * `flexibilityAnnouncementType`, which is unique within a single publish.
+ * announcement variant produced it. Pairing is by `announcementId` — the `id` of
+ * the announcement being answered — which stays stable across cycles and tells
+ * apart the several announcements one category may speak with at once.
  */
 export interface EnyoCategoryFlexibilityGrant {
+    /** The `id` of the announcement this answers. */
+    announcementId: string;
     /** The appliance category this allocation is for (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
     /** Which announcement variant this grant answers. */
@@ -270,14 +317,13 @@ export interface EnyoCategoryFlexibilityDiagnostics {
     /** ISO 8601 timestamp when this snapshot was taken. */
     generatedAtIso: string;
     /**
-     * The flexibility the managers announced, one entry per
-     * (category, announcement variant).
+     * The flexibility the managers announced, one entry per announcement `id`.
      */
     announced: EnyoCategoryFlexibilityAnnouncement[];
     /**
      * What the decision maker granted in answer to `announced`. Every entry SHOULD
-     * pair with an `announced` entry by `category` + `flexibilityAnnouncementType`;
-     * an announcement with no matching grant means the decision had not been taken
+     * pair with an `announced` entry by `announcementId`; an announcement with no
+     * matching grant means the decision had not been taken
      * yet when the snapshot was produced.
      */
     granted: EnyoCategoryFlexibilityGrant[];

package/dist/cjs/types/enyo-heatpump-appliance.cjs

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
+exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
 var EnyoHeatpumpApplianceAvailableFeaturesEnum;
 (function (EnyoHeatpumpApplianceAvailableFeaturesEnum) {
     /** If the heatpump is capable of domestic hot water*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRodControllable"] = "HeatingRodControllable";
     /** If the heatpump supports room overheating via heating circuits */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["RoomOverheating"] = "RoomOverheating";
     /** If the heatpump supports buffer tank overheating */
@@ -62,6 +64,18 @@ var EnyoHeatpumpApplianceAdditionalDeviceEnum;
     /** A solar thermal system is present in the installation */
     EnyoHeatpumpApplianceAdditionalDeviceEnum["SolarThermal"] = "SolarThermal";
 })(EnyoHeatpumpApplianceAdditionalDeviceEnum || (exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = EnyoHeatpumpApplianceAdditionalDeviceEnum = {}));
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+var EnyoHeatpumpApplianceHeatingRodUsageEnum;
+(function (EnyoHeatpumpApplianceHeatingRodUsageEnum) {
+    /** The heating rod is the only heat source used (no compressor support) */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["OnlyHeatingRot"] = "OnlyHeatingRot";
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["HeatingRodForTemperatureIncrease"] = "HeatingRodForTemperatureIncrease";
+})(EnyoHeatpumpApplianceHeatingRodUsageEnum || (exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = EnyoHeatpumpApplianceHeatingRodUsageEnum = {}));
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at

package/dist/cjs/types/enyo-heatpump-appliance.d.cts

@@ -3,6 +3,8 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     DomesticHotWater = "DomesticHotWater",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    HeatingRodControllable = "HeatingRodControllable",
     /** If the heatpump supports room overheating via heating circuits */
     RoomOverheating = "RoomOverheating",
     /** If the heatpump supports buffer tank overheating */
@@ -55,6 +57,17 @@ export declare enum EnyoHeatpumpApplianceAdditionalDeviceEnum {
     /** A solar thermal system is present in the installation */
     SolarThermal = "SolarThermal"
 }
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export declare enum EnyoHeatpumpApplianceHeatingRodUsageEnum {
+    /** The heating rod is the only heat source used (no compressor support) */
+    OnlyHeatingRot = "OnlyHeatingRot",
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    HeatingRodForTemperatureIncrease = "HeatingRodForTemperatureIncrease"
+}
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at
@@ -124,4 +137,11 @@ export interface EnyoHeatpumpApplianceMetadata {
      * heatpump (e.g. a heating rod or a solar thermal system).
      */
     additionalDevices?: EnyoHeatpumpApplianceAdditionalDeviceEnum[];
+    /**
+     * How the heating rod of the installation is used (e.g. as the only heat
+     * source or only to further increase the temperature on top of the
+     * compressor). Only meaningful if the heatpump has a heating rod
+     * (see {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingRod}).
+     */
+    heatingRodUsage?: EnyoHeatpumpApplianceHeatingRodUsageEnum;
 }

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.190';
+exports.SDK_VERSION = '0.0.192';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.190";
+export declare const SDK_VERSION = "0.0.192";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/index.d.ts

@@ -67,6 +67,8 @@ export * from './packages/energy-app-configuration-manager.js';
 export * from './types/enyo-air-conditioning-appliance.js';
 export * from './types/enyo-heating-rod-appliance.js';
 export * from './types/enyo-charger-appliance.js';
+export * from './types/enyo-charging-card.js';
+export * from './packages/energy-app-charging-card.js';
 export * from './types/enyo-battery-appliance.js';
 export * from './types/enyo-heatpump-appliance.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/index.js

@@ -67,6 +67,8 @@ export * from './packages/energy-app-configuration-manager.js';
 export * from './types/enyo-air-conditioning-appliance.js';
 export * from './types/enyo-heating-rod-appliance.js';
 export * from './types/enyo-charger-appliance.js';
+export * from './types/enyo-charging-card.js';
+export * from './packages/energy-app-charging-card.js';
 export * from './types/enyo-battery-appliance.js';
 export * from './types/enyo-heatpump-appliance.js';
 export * from './types/enyo-inverter-appliance.js';

package/dist/packages/energy-app-charging-card.d.ts

@@ -1,11 +1,56 @@
-import { EnyoChargingCard } from "../types/enyo-charging-card.js";
+import { EnyoChargingCard, EnyoChargingCardPairingRequest } from "../types/enyo-charging-card.js";
 /**
  * Interface for managing charging cards in enyo packages.
- * Provides read-only operations for charging card information.
+ * Provides read-only operations for charging card information as well as
+ * RFID pairing support.
  */
 export interface EnergyAppChargingCard {
     /** Get a list of all registered charging cards */
     list: () => Promise<EnyoChargingCard[]>;
     /** Get a specific charging card by its ID */
     getById: (id: string) => Promise<EnyoChargingCard | null>;
+    /**
+     * Listen for pairing requests, i.e. the host asking this package to put its
+     * RFID reader into pairing mode — typically because a user started adding a
+     * new charging card in the app.
+     *
+     * The listener owns the whole pairing attempt: it enables pairing mode on
+     * the charger, waits for a card to be held against the reader and resolves
+     * with the RFID identifier that was read (the value stored in
+     * {@link EnyoChargingCard.rfid}). The host assigns it to the charging card
+     * named by {@link EnyoChargingCardPairingRequest.chargingCardId} and clears
+     * that card's {@link EnyoChargingCard.pendingRegistration} flag.
+     *
+     * Reject the returned promise when no card was presented or the charger
+     * refused to enter pairing mode; the host then reports the attempt as
+     * failed and leaves the card pending. Honour
+     * {@link EnyoChargingCardPairingRequest.timeoutMs} when it is set — the host
+     * ignores a result that arrives after the deadline.
+     *
+     * Only register a listener when the package actually drives an RFID reader.
+     * Requests carry an optional
+     * {@link EnyoChargingCardPairingRequest.applianceId}; a package managing
+     * several chargers should check it and reject requests for appliances it
+     * does not own.
+     *
+     * @param listener - Callback invoked for every pairing request, resolving
+     *   with the RFID identifier read from the presented card
+     * @returns A unique listener ID that can be used to remove the listener
+     *
+     * @example
+     * ```typescript
+     * const chargingCard = energyApp.useChargingCard();
+     * const listenerId = chargingCard.listenForPairingStarted(async (request) => {
+     *     const rfid = await charger.enterPairingMode(request.applianceId, request.timeoutMs);
+     *     return rfid;
+     * });
+     * ```
+     */
+    listenForPairingStarted: (listener: (request: EnyoChargingCardPairingRequest) => Promise<string>) => string;
+    /**
+     * Removes a previously registered listener.
+     *
+     * @param listenerId - The ID returned by {@link listenForPairingStarted}
+     */
+    removeListener: (listenerId: string) => void;
 }

package/dist/packages/energy-app-diagnostics.d.ts

@@ -98,6 +98,7 @@ export interface EnergyAppDiagnostics {
      *     generatedAtIso: new Date().toISOString(),
      *     announced: [
      *         {
+     *             id: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -110,6 +111,8 @@ export interface EnergyAppDiagnostics {
      *             },
      *         },
      *         {
+     *             id: 'storage:flexible-discharge',
+     *             applianceId: 'battery-1',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,
@@ -124,6 +127,7 @@ export interface EnergyAppDiagnostics {
      *     ],
      *     granted: [
      *         {
+     *             announcementId: 'charger:flexible-kwh',
      *             category: EnyoApplianceTypeEnum.Charger,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleKwhTarget,
@@ -134,6 +138,7 @@ export interface EnergyAppDiagnostics {
      *             reason: 'grid connection point limit',
      *         },
      *         {
+     *             announcementId: 'storage:flexible-discharge',
      *             category: EnyoApplianceTypeEnum.Storage,
      *             flexibilityAnnouncementType:
      *                 EnyoFlexibilityAnnouncementTypeEnum.FlexibleDischarge,

package/dist/types/enyo-charging-card.d.ts

@@ -9,3 +9,24 @@ export interface EnyoChargingCard {
     rfid?: string;
     pendingRegistration?: boolean;
 }
+/**
+ * Details of a pairing request handed to a
+ * {@link EnergyAppChargingCard.listenForPairingStarted} listener when the
+ * host asks a package to put its RFID reader into pairing mode.
+ */
+export interface EnyoChargingCardPairingRequest {
+    /** ID of the charging card record the scanned RFID should be assigned to */
+    chargingCardId: string;
+    /**
+     * Appliance (charger) whose RFID reader should enter pairing mode. Omitted
+     * when the host does not target a specific charger — in that case the
+     * package decides which of its readers to use.
+     */
+    applianceId?: string;
+    /**
+     * Time budget, in milliseconds, the package has to deliver a scanned card.
+     * The host stops waiting once it elapses, so a listener that resolves later
+     * has no effect. Omitted when the host does not impose a deadline.
+     */
+    timeoutMs?: number;
+}

package/dist/types/enyo-data-bus-value.d.ts

@@ -23,6 +23,15 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     PvSurplusAvailable = "pv-surplus-available",
     /** Command issued because PV surplus is unavailable */
     PvSurplusUnavailable = "pv-surplus-unavailable",
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    PvSurplusAllocatedElsewhere = "pv-surplus-allocated-elsewhere",
     /** Command issued because battery capacity is available */
     BatteryCapacityAvailable = "battery-capacity-available",
     /** Command issued because battery capacity is unavailable */
@@ -100,6 +109,16 @@ export interface EnyoDataBusCommandReason {
     temperatureC?: number;
     /** Relevant state of charge as a percentage (battery-driven reasons) */
     socPercent?: number;
+    /**
+     * The appliance category the decision was made in favour of.
+     *
+     * Set on reasons that describe a trade-off between appliances — most
+     * notably
+     * {@link EnyoDataBusCommandReasonTypeEnum.PvSurplusAllocatedElsewhere} —
+     * so the end-user text can name the winning appliance (e.g. "the battery")
+     * rather than saying "elsewhere".
+     */
+    inFavourOfApplianceType?: EnyoApplianceTypeEnum;
 }
 /**
  * Whether a grid operator power limitation caps power drawn from the grid

package/dist/types/enyo-data-bus-value.js

@@ -12,6 +12,15 @@ export var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["PvSurplusAvailable"] = "pv-surplus-available";
     /** Command issued because PV surplus is unavailable */
     EnyoDataBusCommandReasonTypeEnum["PvSurplusUnavailable"] = "pv-surplus-unavailable";
+    /**
+     * Command issued because PV surplus exists but is allocated to another
+     * appliance. Belongs to the
+     * {@link EnyoDataBusCommandReasonCategoryEnum.PvSurplus} category. Set
+     * {@link EnyoDataBusCommandReason.inFavourOfApplianceType} so the
+     * end-user text can name the appliance that got the surplus instead of
+     * saying "elsewhere".
+     */
+    EnyoDataBusCommandReasonTypeEnum["PvSurplusAllocatedElsewhere"] = "pv-surplus-allocated-elsewhere";
     /** Command issued because battery capacity is available */
     EnyoDataBusCommandReasonTypeEnum["BatteryCapacityAvailable"] = "battery-capacity-available";
     /** Command issued because battery capacity is unavailable */

package/dist/types/enyo-flexibility-announcement.d.ts

@@ -125,11 +125,49 @@ export interface EnyoFlexibilityAnnouncementContext {
     heatpumpTargetType?: EnyoFlexibilityHeatpumpTargetTypeEnum;
     /** For air-conditioning announcements: what the flexibility is aimed at. */
     airConditioningTargetType?: EnyoFlexibilityAirConditioningTargetTypeEnum;
+    /**
+     * For storage announcements: the round-trip cost of cycling the battery, in
+     * EUR per kWh. The floor a discharge has to beat to be worth licensing.
+     */
+    storageCycleCostEurPerKwh?: number;
+    /**
+     * For storage announcements: the physical discharge floor, in Watts. Signed —
+     * negative means discharge, so this is the most negative power the storage can
+     * physically reach.
+     */
+    storageMinPowerW?: number;
+    /** For storage announcements: the physical charge ceiling, in Watts. */
+    storageMaxPowerW?: number;
+    /** For storage announcements: usable capacity of the storage, in Wh. */
+    storageCapacityWh?: number;
+    /**
+     * For storage announcements: the discharge power we will actually command, in
+     * Watts. May be well inside {@link storageMinPowerW} — today it is `0`, i.e. we
+     * license discharge without commanding it.
+     */
+    storageCommandableDischargeW?: number;
+    /**
+     * For storage announcements: whether the storage accepts an explicit
+     * `Discharge 0` command, i.e. can be told to hold rather than only being left
+     * alone.
+     */
+    storageCanHold?: boolean;
 }
 /** Fields shared by every category-scoped flexibility announcement. */
 export interface EnyoCategoryFlexibilityAnnouncementBase {
+    /**
+     * What this announcement IS, stable across cycles — e.g. `storage:peak-requirement`.
+     * A category speaks with several at once and (category, type) does not tell them
+     * apart. REQUIRED: a positional identity changes whenever a neighbour appears.
+     */
+    id: string;
     /** The appliance category this demand aggregates (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
+    /**
+     * The appliance this announcement speaks for, when a category announces per
+     * appliance rather than as one aggregate. Absent = the whole category.
+     */
+    applianceId?: string;
     /** Optional extra context for the decision maker; absent for most announcements. */
     context?: EnyoFlexibilityAnnouncementContext;
 }
@@ -143,6 +181,12 @@ export interface EnyoCategoryRequiredKwhTargetAnnouncement extends EnyoCategoryF
         kwh: number;
         /** Power band the delivery may use. */
         power: EnyoFlexibilityPowerBand;
+        /**
+         * Price ceiling, when the requirement is economic rather than absolute.
+         * Present on the wire today; without it every economic requirement looked
+         * like a MUST-RUN in diagnostics.
+         */
+        priceLimitEuroCent?: number;
     };
 }
 /** Deliver `kwh` flexibly (cost-/PV-optimized), aggregated across the category. */
@@ -224,10 +268,13 @@ export declare enum EnyoCategoryFlexibilityGrantStatusEnum {
  * A grant is deliberately flatter than the announcement it answers: the decision
  * maker replies with one allocation — a window, a power envelope, and (for the
  * energy-target and discharge variants) an amount of energy — regardless of which
- * announcement variant produced it. Pairing is by `category` +
- * `flexibilityAnnouncementType`, which is unique within a single publish.
+ * announcement variant produced it. Pairing is by `announcementId` — the `id` of
+ * the announcement being answered — which stays stable across cycles and tells
+ * apart the several announcements one category may speak with at once.
  */
 export interface EnyoCategoryFlexibilityGrant {
+    /** The `id` of the announcement this answers. */
+    announcementId: string;
     /** The appliance category this allocation is for (e.g. `Charger`). */
     category: EnyoApplianceTypeEnum;
     /** Which announcement variant this grant answers. */
@@ -270,14 +317,13 @@ export interface EnyoCategoryFlexibilityDiagnostics {
     /** ISO 8601 timestamp when this snapshot was taken. */
     generatedAtIso: string;
     /**
-     * The flexibility the managers announced, one entry per
-     * (category, announcement variant).
+     * The flexibility the managers announced, one entry per announcement `id`.
      */
     announced: EnyoCategoryFlexibilityAnnouncement[];
     /**
      * What the decision maker granted in answer to `announced`. Every entry SHOULD
-     * pair with an `announced` entry by `category` + `flexibilityAnnouncementType`;
-     * an announcement with no matching grant means the decision had not been taken
+     * pair with an `announced` entry by `announcementId`; an announcement with no
+     * matching grant means the decision had not been taken
      * yet when the snapshot was produced.
      */
     granted: EnyoCategoryFlexibilityGrant[];

package/dist/types/enyo-heatpump-appliance.d.ts

@@ -3,6 +3,8 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     DomesticHotWater = "DomesticHotWater",
     /** If the heatpump has a heating rod*/
     HeatingRod = "HeatingRod",
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    HeatingRodControllable = "HeatingRodControllable",
     /** If the heatpump supports room overheating via heating circuits */
     RoomOverheating = "RoomOverheating",
     /** If the heatpump supports buffer tank overheating */
@@ -55,6 +57,17 @@ export declare enum EnyoHeatpumpApplianceAdditionalDeviceEnum {
     /** A solar thermal system is present in the installation */
     SolarThermal = "SolarThermal"
 }
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export declare enum EnyoHeatpumpApplianceHeatingRodUsageEnum {
+    /** The heating rod is the only heat source used (no compressor support) */
+    OnlyHeatingRot = "OnlyHeatingRot",
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    HeatingRodForTemperatureIncrease = "HeatingRodForTemperatureIncrease"
+}
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at
@@ -124,4 +137,11 @@ export interface EnyoHeatpumpApplianceMetadata {
      * heatpump (e.g. a heating rod or a solar thermal system).
      */
     additionalDevices?: EnyoHeatpumpApplianceAdditionalDeviceEnum[];
+    /**
+     * How the heating rod of the installation is used (e.g. as the only heat
+     * source or only to further increase the temperature on top of the
+     * compressor). Only meaningful if the heatpump has a heating rod
+     * (see {@link EnyoHeatpumpApplianceAvailableFeaturesEnum.HeatingRod}).
+     */
+    heatingRodUsage?: EnyoHeatpumpApplianceHeatingRodUsageEnum;
 }

package/dist/types/enyo-heatpump-appliance.js

@@ -4,6 +4,8 @@ export var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["DomesticHotWater"] = "DomesticHotWater";
     /** If the heatpump has a heating rod*/
     EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRod"] = "HeatingRod";
+    /** If the heating rod of the heatpump can be actively controlled (steered) by the energy manager */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["HeatingRodControllable"] = "HeatingRodControllable";
     /** If the heatpump supports room overheating via heating circuits */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["RoomOverheating"] = "RoomOverheating";
     /** If the heatpump supports buffer tank overheating */
@@ -59,6 +61,18 @@ export var EnyoHeatpumpApplianceAdditionalDeviceEnum;
     /** A solar thermal system is present in the installation */
     EnyoHeatpumpApplianceAdditionalDeviceEnum["SolarThermal"] = "SolarThermal";
 })(EnyoHeatpumpApplianceAdditionalDeviceEnum || (EnyoHeatpumpApplianceAdditionalDeviceEnum = {}));
+/**
+ * Describes how the heating rod of a heatpump installation is used.
+ * Consumers (UI, energy manager) use this to decide whether the heating rod is
+ * the sole heat source or only assists the compressor.
+ */
+export var EnyoHeatpumpApplianceHeatingRodUsageEnum;
+(function (EnyoHeatpumpApplianceHeatingRodUsageEnum) {
+    /** The heating rod is the only heat source used (no compressor support) */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["OnlyHeatingRot"] = "OnlyHeatingRot";
+    /** The heating rod is used in addition to the compressor to further increase the temperature */
+    EnyoHeatpumpApplianceHeatingRodUsageEnum["HeatingRodForTemperatureIncrease"] = "HeatingRodForTemperatureIncrease";
+})(EnyoHeatpumpApplianceHeatingRodUsageEnum || (EnyoHeatpumpApplianceHeatingRodUsageEnum = {}));
 /**
  * The type of heat emitter connected to a heating circuit. Influences the
  * flow temperatures the circuit operates at (floor heating typically runs at

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.190";
+export declare const SDK_VERSION = "0.0.192";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '0.0.190';
+export const SDK_VERSION = '0.0.192';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "0.0.190",
+  "version": "0.0.192",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",