@enyo-energy/energy-app-sdk 0.0.191 → 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/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/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '0.0.191';
+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.191";
+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/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/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "0.0.191";
+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.191';
+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.191",
+  "version": "0.0.192",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",