@enyo-energy/energy-app-sdk 0.0.134 → 0.0.136

package/dist/cjs/index.cjs

@@ -52,6 +52,7 @@ __exportStar(require("./packages/energy-app-energy-prices.cjs"), exports);
 __exportStar(require("./packages/energy-app-modbus-rtu.cjs"), exports);
 __exportStar(require("./types/enyo-eebus.cjs"), exports);
 __exportStar(require("./types/enyo-eebus-use-cases.cjs"), exports);
+__exportStar(require("./types/enyo-eebus-features.cjs"), exports);
 __exportStar(require("./packages/energy-app-eebus.cjs"), exports);
 __exportStar(require("./types/enyo-mqtt.cjs"), exports);
 __exportStar(require("./packages/energy-app-mqtt.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -36,6 +36,7 @@ export * from './packages/energy-app-energy-prices.cjs';
 export * from './packages/energy-app-modbus-rtu.cjs';
 export * from './types/enyo-eebus.cjs';
 export * from './types/enyo-eebus-use-cases.cjs';
+export * from './types/enyo-eebus-features.cjs';
 export * from './packages/energy-app-eebus.cjs';
 export * from './types/enyo-mqtt.cjs';
 export * from './packages/energy-app-mqtt.cjs';

package/dist/cjs/packages/eebus/eebus-feature-catalog.cjs

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

package/dist/cjs/packages/eebus/eebus-feature-catalog.d.cts

@@ -0,0 +1,90 @@
+import { EebusRemoteFeatureCatalog } from '../../types/enyo-eebus-features.cjs';
+/**
+ * Per-peer SPINE entity/feature catalog for paired EEbus remotes.
+ *
+ * Exposes the lib's `RemoteDevice` view — the set of entities and
+ * features the peer actually advertises via
+ * `NodeManagement.DetailedDiscoveryData`, kept in sync by the SDK as the
+ * remote emits `NodeManagement.NotifyChange` events.
+ *
+ * Use this service in preference to {@link EebusIdentityService.getSupportedUseCases}
+ * when gating package behaviour on remote capability. Non-certified peers
+ * and simulators routinely under-populate `NodeManagement.UseCaseData`
+ * while still exposing the matching SPINE features (e.g. a `LoadControl`
+ * server with `loadControlLimitDescriptionData` of
+ * `limitDirection: 'consume'` but no corresponding
+ * `limitationOfPowerConsumption` use case). Feature-level gates work on
+ * these peers; use-case gates do not.
+ *
+ * Identity, like the use-case list, is observable rather than one-shot:
+ * remotes add or remove entities and features after a firmware update or
+ * a runtime mode change. Always pair {@link get} with
+ * {@link onFeaturesChanged} for any package that reacts to peer
+ * capabilities, otherwise the package will keep operating against a
+ * stale snapshot.
+ *
+ * @example
+ * ```typescript
+ * // Feature-based LPC gate that works on peers with incomplete UseCaseData
+ * const catalog = await eebus.features.get(ski);
+ * const loadControl = catalog.entities
+ *   .flatMap(e => e.features)
+ *   .find(f =>
+ *     f.type === 'LoadControl'
+ *     && f.role === 'server'
+ *     && f.supportedFunctions.some(s => s.function === 'loadControlLimitListData'),
+ *   );
+ * if (loadControl) {
+ *   await eebus.useCases.lpc(ski).setConsumptionLimit({ value: 11000, isActive: true });
+ * }
+ *
+ * // React to the peer adding or removing features at runtime
+ * const listenerId = eebus.features.onFeaturesChanged(ski, next => {
+ *   refreshCapabilityGates(next);
+ * });
+ * ```
+ */
+export interface EebusFeatureCatalog {
+    /**
+     * Get the current SPINE entity/feature catalog snapshot for a remote node.
+     *
+     * The snapshot reflects the most recent `NodeManagement.DetailedDiscoveryData`
+     * state the SDK has observed; it does not trigger a re-fetch from the
+     * remote. To observe live additions, removals, and updates use
+     * {@link onFeaturesChanged}.
+     *
+     * If the peer identified by `ski` is not paired or not currently
+     * connected, the returned snapshot resolves with `found: false` and an
+     * empty `entities` list rather than throwing — so packages can use the
+     * call as a capability gate without wrapping it in `try`/`catch`.
+     *
+     * @param ski Subject Key Identifier of the remote node
+     * @returns The current entity/feature catalog snapshot
+     */
+    get: (ski: string) => Promise<EebusRemoteFeatureCatalog>;
+    /**
+     * Subscribe to feature/entity catalog changes for a remote node.
+     *
+     * The listener is invoked with the full updated snapshot whenever the
+     * lib emits `featureAdded`, `featureUpdated`, `featureRemoved`,
+     * `entityAdded`, or `entityRemoved` for the peer. The payload shape
+     * matches {@link get} so subscribers can replace their cached catalog
+     * on every event without diffing.
+     *
+     * Subscriptions are scoped to the peer identified by `ski`. If the
+     * peer disconnects, the listener remains registered and resumes
+     * delivering events when the peer reconnects — packages do not need
+     * to re-subscribe after a transient disconnect.
+     *
+     * @param ski Subject Key Identifier of the remote node
+     * @param listener Callback invoked with the full updated catalog snapshot
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onFeaturesChanged: (ski: string, listener: (catalog: EebusRemoteFeatureCatalog) => void) => string;
+    /**
+     * Remove a feature-catalog listener previously registered via
+     * {@link onFeaturesChanged}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

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

@@ -1,8 +1,10 @@
 import { EebusDeviceManagement } from './eebus-device-management.cjs';
+import { EebusFeatureCatalog } from './eebus-feature-catalog.cjs';
 import { EebusIdentityService } from './eebus-identity-service.cjs';
 import { EebusSpineLowLevel } from './eebus-spine-low-level.cjs';
 import { EebusUseCaseRegistry } from './eebus-use-case-registry.cjs';
 export { EebusDeviceManagement } from './eebus-device-management.cjs';
+export { EebusFeatureCatalog } from './eebus-feature-catalog.cjs';
 export { EebusIdentityService } from './eebus-identity-service.cjs';
 export { EebusSpineLowLevel } from './eebus-spine-low-level.cjs';
 export { EebusUseCaseRegistry } from './eebus-use-case-registry.cjs';
@@ -16,10 +18,11 @@ export { EebusSetpointClient } from './eebus-setpoint-client.cjs';
 /**
  * Interface for EEbus (SHIP/SPINE) device communication in enyo packages.
  *
- * The API is split into four orthogonal concerns, each its own sub-interface:
+ * The API is split into five orthogonal concerns, each its own sub-interface:
  *
  * - {@link devices} — SHIP-level device lifecycle: discovery, pairing, connection
  * - {@link identity} — NID: observable per-node identity, diagnosis state, use-case discovery
+ * - {@link features} — observable per-peer SPINE entity/feature catalog
  * - {@link useCases} — typed use-case clients: LPC, LPP, MGCP, MPC, OHPCF, Setpoint, Hvac
  * - {@link spine} — low-level SPINE escape hatch for features not yet wrapped
  *
@@ -41,16 +44,21 @@ export { EebusSetpointClient } from './eebus-setpoint-client.cjs';
  * console.log(`${identity.brandName} ${identity.deviceName} v${identity.softwareRevision}`);
  * eebus.identity.onIdentityChanged(device.ski, next => updateStatusBadge(next));
  *
- * // 3. Use cases — typed, role-aware
- * const supported = await eebus.identity.getSupportedUseCases(device.ski);
- * if (supported.some(u => u.name === 'limitationOfPowerConsumption')) {
+ * // 3. Feature catalog — gate behaviour on what the peer actually advertises
+ * const catalog = await eebus.features.get(device.ski);
+ * const hasLpcServer = catalog.entities
+ *   .flatMap(e => e.features)
+ *   .some(f => f.type === 'LoadControl' && f.role === 'server');
+ *
+ * // 4. Use cases — typed, role-aware
+ * if (hasLpcServer) {
  *   await eebus.useCases.lpc(device.ski).setConsumptionLimit({
  *     value: 11000,
  *     isActive: true,
  *   });
  * }
  *
- * // 4. Escape hatch — raw SPINE for unmodelled features
+ * // 5. Escape hatch — raw SPINE for unmodelled features
  * const dp = await eebus.spine.readData(device.ski, 'DeviceConfiguration', 'keyValueListData');
  * ```
  */
@@ -59,6 +67,12 @@ export interface EnergyAppEebus {
     devices: EebusDeviceManagement;
     /** EEBUS Node Identification (NID) — observable identity + use-case discovery */
     identity: EebusIdentityService;
+    /**
+     * Observable per-peer SPINE entity/feature catalog. Prefer feature-level
+     * gates from this catalog over use-case gates from {@link identity} when
+     * the peer is known to under-populate `NodeManagement.UseCaseData`.
+     */
+    features: EebusFeatureCatalog;
     /** Typed use-case clients for the implemented EEBUS use cases */
     useCases: EebusUseCaseRegistry;
     /** Low-level SPINE escape hatch for features not yet wrapped by a typed client */

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

@@ -98,6 +98,67 @@ export interface EnyoApplianceModbusMetadata {
     /** Optional base address for the appliance's Modbus registers */
     baseAddress?: number;
 }
+/**
+ * EEBUS connection metadata for the appliance.
+ *
+ * Holds EEBUS-/SPINE-specific identifiers that identify the underlying
+ * remote node and entity. Vendor-neutral fields such as `vendorName`,
+ * `serialNumber`, `firmwareVersion` and `modelName` are already exposed on
+ * the top-level {@link EnyoApplianceMetadata} and should not be duplicated
+ * here — this interface only carries identifiers that have no meaningful
+ * equivalent outside of EEBUS.
+ */
+export interface EnyoApplianceEebusMetadata {
+    /**
+     * Subject Key Identifier — the unique cryptographic identifier of the
+     * remote EEBUS node this appliance is bound to. Stable across firmware
+     * upgrades and the primary key for EEBUS pairing/trust.
+     */
+    ski: string;
+    /**
+     * SPINE entity type of the appliance within the remote node (e.g.
+     * `'EVSE'`, `'EV'`, `'HeatPumpAppliance'`). Comes from
+     * `NodeManagement.DetailedDiscoveryData` and identifies which sub-entity
+     * of the node represents this appliance when a node exposes multiple.
+     */
+    deviceType?: string;
+    /**
+     * SPINE entity address of the appliance within the remote node — a
+     * sequence of integers identifying the entity. Useful when the node
+     * exposes multiple entities of the same {@link deviceType}.
+     */
+    entityAddress?: number[];
+    /**
+     * Vendor company code as reported via SPINE
+     * `DeviceClassification.ManufacturerData.VendorCode`. EEBUS-specific
+     * counterpart to the human-readable `vendorName` on the parent
+     * metadata.
+     */
+    vendorCode?: string;
+    /**
+     * Brand name under which the device is sold, as reported via SPINE
+     * `DeviceClassification.ManufacturerData.BrandName`.
+     */
+    brandName?: string;
+    /**
+     * Manufacturer-assigned device code (model identifier) as reported via
+     * SPINE `DeviceClassification.ManufacturerData.DeviceCode`.
+     */
+    deviceCode?: string;
+    /**
+     * Manufacturer-assigned node identifier — the literal
+     * `ManufacturerNodeIdentification` field from SPINE
+     * `DeviceClassificationManufacturerDataType`. Often used by vendors as
+     * a stable identifier across firmware upgrades.
+     */
+    manufacturerNodeIdentification?: string;
+    /**
+     * User-assigned node identifier — the literal `UserNodeIdentification`
+     * field from SPINE `DeviceClassificationUserDataType`. May be changed
+     * by the end user via the device's UI at any time.
+     */
+    userNodeIdentification?: string;
+}
 export declare enum EnyoApplianceConnectionType {
     Connector = "Connector",
     Cloud = "Cloud"
@@ -114,6 +175,8 @@ export interface EnyoApplianceMetadata {
     status?: EnyoApplianceStatusEnum;
     network?: EnyoApplianceNetworkMetadata;
     modbus?: EnyoApplianceModbusMetadata;
+    /** Optional EEBUS connection metadata (SKI, SPINE entity type, vendor code, …) */
+    eebus?: EnyoApplianceEebusMetadata;
     /** Optional MQTT configuration */
     mqtt?: EnyoApplianceMqttConfig;
     connectionType: EnyoApplianceConnectionType;

package/dist/cjs/types/enyo-eebus-features.cjs

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Types describing the SPINE feature/entity catalog advertised by a remote
+ * EEbus peer.
+ *
+ * The catalog is the **authoritative source of truth** for what a peer can
+ * actually do. It is derived from the lib's `RemoteDevice` view, which is
+ * itself kept in sync with `NodeManagement.DetailedDiscoveryData` replies
+ * and `NodeManagement.NotifyChange` events from the remote.
+ *
+ * Prefer feature/role gates based on this catalog over use-case gates from
+ * {@link EebusUseCaseSupport}: many non-certified peers and simulators
+ * implement working SPINE features (e.g. a `LoadControl` server with a
+ * `loadControlLimitDescriptionData` of `limitDirection: 'consume'`) without
+ * advertising the matching use case in `NodeManagement.UseCaseData`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/enyo-eebus-features.d.cts

@@ -0,0 +1,131 @@
+/**
+ * Types describing the SPINE feature/entity catalog advertised by a remote
+ * EEbus peer.
+ *
+ * The catalog is the **authoritative source of truth** for what a peer can
+ * actually do. It is derived from the lib's `RemoteDevice` view, which is
+ * itself kept in sync with `NodeManagement.DetailedDiscoveryData` replies
+ * and `NodeManagement.NotifyChange` events from the remote.
+ *
+ * Prefer feature/role gates based on this catalog over use-case gates from
+ * {@link EebusUseCaseSupport}: many non-certified peers and simulators
+ * implement working SPINE features (e.g. a `LoadControl` server with a
+ * `loadControlLimitDescriptionData` of `limitDirection: 'consume'`) without
+ * advertising the matching use case in `NodeManagement.UseCaseData`.
+ */
+/**
+ * SPINE role under which a feature is advertised by the remote node.
+ *
+ * The set is intentionally widened with `string` so that lib upgrades that
+ * introduce new SPINE role variants do not break consumer code that
+ * pattern-matches on the role.
+ */
+export type EebusFeatureRole = 'client' | 'server' | 'special' | string;
+/**
+ * SPINE address triple identifying a feature within the EEbus topology.
+ *
+ * - {@link entity} addresses the entity within the remote node (e.g. `[1]`
+ *   for a flat node, `[1, 1]` when the node nests sub-entities such as a
+ *   compressor under a heat-pump appliance).
+ * - {@link feature} addresses the feature within that entity.
+ * - {@link device} optionally carries the remote node's SPINE
+ *   `NetworkAddressDeviceID`. Usually omitted because the surrounding
+ *   {@link EebusRemoteFeatureCatalog.deviceAddress} already provides it.
+ */
+export interface EebusFeatureAddress {
+    /** SPINE entity address — a sequence of integers identifying the entity within the node */
+    entity: number[];
+    /** SPINE feature address within the entity */
+    feature: number;
+    /** Optional SPINE `NetworkAddressDeviceID` of the remote node */
+    device?: string;
+}
+/**
+ * A SPINE function the remote advertises as supported on a feature,
+ * together with the operations (read / write) the remote permits on it.
+ *
+ * The operation payloads are intentionally opaque (`object`) — SPINE
+ * permits per-function filters and bindings whose shape varies by
+ * function and is irrelevant to most callers. Pass them through verbatim
+ * when forwarding to {@link EebusSpineLowLevel}.
+ */
+export interface EebusSupportedFunction {
+    /** SPINE function/data-set name (e.g. `'loadControlLimitListData'`, `'measurementListData'`) */
+    function: string;
+    /** Operations the remote permits on this function */
+    possibleOperations: {
+        /** Present when the remote permits reads; payload mirrors the SPINE `read` operation parameters */
+        read?: object;
+        /** Present when the remote permits writes; payload mirrors the SPINE `write` operation parameters */
+        write?: object;
+    };
+}
+/**
+ * A single SPINE feature advertised by a remote entity.
+ *
+ * The {@link type} is a wire string (e.g. `'LoadControl'`,
+ * `'Measurement'`, `'DeviceClassification'`) rather than a closed enum
+ * so that lib upgrades that introduce new SPINE feature types do not
+ * break existing packages — see {@link EebusSpineLowLevel} for the same
+ * rationale applied to the low-level escape hatch.
+ */
+export interface EebusRemoteFeature {
+    /** SPINE address triple for this feature */
+    address: EebusFeatureAddress;
+    /** SPINE feature type wire string (e.g. `'LoadControl'`, `'Measurement'`) */
+    type: string;
+    /** SPINE role under which the feature is advertised */
+    role: EebusFeatureRole;
+    /** Functions the remote advertises as supported on this feature */
+    supportedFunctions: EebusSupportedFunction[];
+    /** Optional manufacturer-provided label */
+    label?: string;
+    /** Optional manufacturer-provided description */
+    description?: string;
+}
+/**
+ * A SPINE entity advertised by a remote node.
+ *
+ * A node usually exposes a `DeviceInformation` entity (the node itself)
+ * plus one or more application-specific entities (e.g. `EVSE`, `EV`,
+ * `HeatPumpAppliance`, `Compressor`). Sub-entities are flattened into
+ * this list with their full {@link address} path preserved (e.g. `[1, 1]`
+ * for a compressor under a heat-pump appliance), so consumers can
+ * reconstruct the hierarchy when needed.
+ */
+export interface EebusRemoteEntity {
+    /** SPINE entity address — a sequence of integers identifying the entity (e.g. `[1]` or `[1, 1]`) */
+    address: number[];
+    /** SPINE entity type wire string (e.g. `'HeatPumpAppliance'`, `'Compressor'`, `'EVSE'`) */
+    type: string;
+    /** Optional manufacturer-provided label */
+    label?: string;
+    /** Optional manufacturer-provided description */
+    description?: string;
+    /** Features advertised on this entity */
+    features: EebusRemoteFeature[];
+}
+/**
+ * Snapshot of the full SPINE entity/feature catalog advertised by a
+ * remote EEbus peer.
+ *
+ * Returned by {@link EebusFeatureCatalog.get} and delivered to
+ * {@link EebusFeatureCatalog.onFeaturesChanged} listeners. The shape is
+ * intentionally identical between the two so that change subscribers can
+ * drop and replace their cached catalog on every event without diffing.
+ *
+ * When the peer identified by {@link ski} is not known (never paired or
+ * not currently connected), {@link found} is `false` and {@link entities}
+ * is an empty array — the call resolves cleanly rather than throwing, so
+ * packages can use the snapshot as a feature gate without try/catch.
+ */
+export interface EebusRemoteFeatureCatalog {
+    /** Subject Key Identifier of the remote node this catalog describes */
+    ski: string;
+    /** Whether the peer is currently known to the SDK (paired AND reachable) */
+    found: boolean;
+    /** Remote node's SPINE `NetworkAddressDeviceID`, when known */
+    deviceAddress?: string;
+    /** SPINE entities advertised by the remote node, flattened with their address path preserved */
+    entities: EebusRemoteEntity[];
+}

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.134';
+exports.SDK_VERSION = '0.0.136';
 /**
  * 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.134";
+export declare const SDK_VERSION = "0.0.136";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export * from './packages/energy-app-energy-prices.js';
 export * from './packages/energy-app-modbus-rtu.js';
 export * from './types/enyo-eebus.js';
 export * from './types/enyo-eebus-use-cases.js';
+export * from './types/enyo-eebus-features.js';
 export * from './packages/energy-app-eebus.js';
 export * from './types/enyo-mqtt.js';
 export * from './packages/energy-app-mqtt.js';

package/dist/index.js

@@ -36,6 +36,7 @@ export * from './packages/energy-app-energy-prices.js';
 export * from './packages/energy-app-modbus-rtu.js';
 export * from './types/enyo-eebus.js';
 export * from './types/enyo-eebus-use-cases.js';
+export * from './types/enyo-eebus-features.js';
 export * from './packages/energy-app-eebus.js';
 export * from './types/enyo-mqtt.js';
 export * from './packages/energy-app-mqtt.js';

package/dist/packages/eebus/eebus-feature-catalog.d.ts

@@ -0,0 +1,90 @@
+import { EebusRemoteFeatureCatalog } from '../../types/enyo-eebus-features.js';
+/**
+ * Per-peer SPINE entity/feature catalog for paired EEbus remotes.
+ *
+ * Exposes the lib's `RemoteDevice` view — the set of entities and
+ * features the peer actually advertises via
+ * `NodeManagement.DetailedDiscoveryData`, kept in sync by the SDK as the
+ * remote emits `NodeManagement.NotifyChange` events.
+ *
+ * Use this service in preference to {@link EebusIdentityService.getSupportedUseCases}
+ * when gating package behaviour on remote capability. Non-certified peers
+ * and simulators routinely under-populate `NodeManagement.UseCaseData`
+ * while still exposing the matching SPINE features (e.g. a `LoadControl`
+ * server with `loadControlLimitDescriptionData` of
+ * `limitDirection: 'consume'` but no corresponding
+ * `limitationOfPowerConsumption` use case). Feature-level gates work on
+ * these peers; use-case gates do not.
+ *
+ * Identity, like the use-case list, is observable rather than one-shot:
+ * remotes add or remove entities and features after a firmware update or
+ * a runtime mode change. Always pair {@link get} with
+ * {@link onFeaturesChanged} for any package that reacts to peer
+ * capabilities, otherwise the package will keep operating against a
+ * stale snapshot.
+ *
+ * @example
+ * ```typescript
+ * // Feature-based LPC gate that works on peers with incomplete UseCaseData
+ * const catalog = await eebus.features.get(ski);
+ * const loadControl = catalog.entities
+ *   .flatMap(e => e.features)
+ *   .find(f =>
+ *     f.type === 'LoadControl'
+ *     && f.role === 'server'
+ *     && f.supportedFunctions.some(s => s.function === 'loadControlLimitListData'),
+ *   );
+ * if (loadControl) {
+ *   await eebus.useCases.lpc(ski).setConsumptionLimit({ value: 11000, isActive: true });
+ * }
+ *
+ * // React to the peer adding or removing features at runtime
+ * const listenerId = eebus.features.onFeaturesChanged(ski, next => {
+ *   refreshCapabilityGates(next);
+ * });
+ * ```
+ */
+export interface EebusFeatureCatalog {
+    /**
+     * Get the current SPINE entity/feature catalog snapshot for a remote node.
+     *
+     * The snapshot reflects the most recent `NodeManagement.DetailedDiscoveryData`
+     * state the SDK has observed; it does not trigger a re-fetch from the
+     * remote. To observe live additions, removals, and updates use
+     * {@link onFeaturesChanged}.
+     *
+     * If the peer identified by `ski` is not paired or not currently
+     * connected, the returned snapshot resolves with `found: false` and an
+     * empty `entities` list rather than throwing — so packages can use the
+     * call as a capability gate without wrapping it in `try`/`catch`.
+     *
+     * @param ski Subject Key Identifier of the remote node
+     * @returns The current entity/feature catalog snapshot
+     */
+    get: (ski: string) => Promise<EebusRemoteFeatureCatalog>;
+    /**
+     * Subscribe to feature/entity catalog changes for a remote node.
+     *
+     * The listener is invoked with the full updated snapshot whenever the
+     * lib emits `featureAdded`, `featureUpdated`, `featureRemoved`,
+     * `entityAdded`, or `entityRemoved` for the peer. The payload shape
+     * matches {@link get} so subscribers can replace their cached catalog
+     * on every event without diffing.
+     *
+     * Subscriptions are scoped to the peer identified by `ski`. If the
+     * peer disconnects, the listener remains registered and resumes
+     * delivering events when the peer reconnects — packages do not need
+     * to re-subscribe after a transient disconnect.
+     *
+     * @param ski Subject Key Identifier of the remote node
+     * @param listener Callback invoked with the full updated catalog snapshot
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onFeaturesChanged: (ski: string, listener: (catalog: EebusRemoteFeatureCatalog) => void) => string;
+    /**
+     * Remove a feature-catalog listener previously registered via
+     * {@link onFeaturesChanged}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

package/dist/packages/eebus/eebus-feature-catalog.js

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

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

@@ -1,8 +1,10 @@
 import { EebusDeviceManagement } from './eebus-device-management.js';
+import { EebusFeatureCatalog } from './eebus-feature-catalog.js';
 import { EebusIdentityService } from './eebus-identity-service.js';
 import { EebusSpineLowLevel } from './eebus-spine-low-level.js';
 import { EebusUseCaseRegistry } from './eebus-use-case-registry.js';
 export { EebusDeviceManagement } from './eebus-device-management.js';
+export { EebusFeatureCatalog } from './eebus-feature-catalog.js';
 export { EebusIdentityService } from './eebus-identity-service.js';
 export { EebusSpineLowLevel } from './eebus-spine-low-level.js';
 export { EebusUseCaseRegistry } from './eebus-use-case-registry.js';
@@ -16,10 +18,11 @@ export { EebusSetpointClient } from './eebus-setpoint-client.js';
 /**
  * Interface for EEbus (SHIP/SPINE) device communication in enyo packages.
  *
- * The API is split into four orthogonal concerns, each its own sub-interface:
+ * The API is split into five orthogonal concerns, each its own sub-interface:
  *
  * - {@link devices} — SHIP-level device lifecycle: discovery, pairing, connection
  * - {@link identity} — NID: observable per-node identity, diagnosis state, use-case discovery
+ * - {@link features} — observable per-peer SPINE entity/feature catalog
  * - {@link useCases} — typed use-case clients: LPC, LPP, MGCP, MPC, OHPCF, Setpoint, Hvac
  * - {@link spine} — low-level SPINE escape hatch for features not yet wrapped
  *
@@ -41,16 +44,21 @@ export { EebusSetpointClient } from './eebus-setpoint-client.js';
  * console.log(`${identity.brandName} ${identity.deviceName} v${identity.softwareRevision}`);
  * eebus.identity.onIdentityChanged(device.ski, next => updateStatusBadge(next));
  *
- * // 3. Use cases — typed, role-aware
- * const supported = await eebus.identity.getSupportedUseCases(device.ski);
- * if (supported.some(u => u.name === 'limitationOfPowerConsumption')) {
+ * // 3. Feature catalog — gate behaviour on what the peer actually advertises
+ * const catalog = await eebus.features.get(device.ski);
+ * const hasLpcServer = catalog.entities
+ *   .flatMap(e => e.features)
+ *   .some(f => f.type === 'LoadControl' && f.role === 'server');
+ *
+ * // 4. Use cases — typed, role-aware
+ * if (hasLpcServer) {
  *   await eebus.useCases.lpc(device.ski).setConsumptionLimit({
  *     value: 11000,
  *     isActive: true,
  *   });
  * }
  *
- * // 4. Escape hatch — raw SPINE for unmodelled features
+ * // 5. Escape hatch — raw SPINE for unmodelled features
  * const dp = await eebus.spine.readData(device.ski, 'DeviceConfiguration', 'keyValueListData');
  * ```
  */
@@ -59,6 +67,12 @@ export interface EnergyAppEebus {
     devices: EebusDeviceManagement;
     /** EEBUS Node Identification (NID) — observable identity + use-case discovery */
     identity: EebusIdentityService;
+    /**
+     * Observable per-peer SPINE entity/feature catalog. Prefer feature-level
+     * gates from this catalog over use-case gates from {@link identity} when
+     * the peer is known to under-populate `NodeManagement.UseCaseData`.
+     */
+    features: EebusFeatureCatalog;
     /** Typed use-case clients for the implemented EEBUS use cases */
     useCases: EebusUseCaseRegistry;
     /** Low-level SPINE escape hatch for features not yet wrapped by a typed client */

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

@@ -98,6 +98,67 @@ export interface EnyoApplianceModbusMetadata {
     /** Optional base address for the appliance's Modbus registers */
     baseAddress?: number;
 }
+/**
+ * EEBUS connection metadata for the appliance.
+ *
+ * Holds EEBUS-/SPINE-specific identifiers that identify the underlying
+ * remote node and entity. Vendor-neutral fields such as `vendorName`,
+ * `serialNumber`, `firmwareVersion` and `modelName` are already exposed on
+ * the top-level {@link EnyoApplianceMetadata} and should not be duplicated
+ * here — this interface only carries identifiers that have no meaningful
+ * equivalent outside of EEBUS.
+ */
+export interface EnyoApplianceEebusMetadata {
+    /**
+     * Subject Key Identifier — the unique cryptographic identifier of the
+     * remote EEBUS node this appliance is bound to. Stable across firmware
+     * upgrades and the primary key for EEBUS pairing/trust.
+     */
+    ski: string;
+    /**
+     * SPINE entity type of the appliance within the remote node (e.g.
+     * `'EVSE'`, `'EV'`, `'HeatPumpAppliance'`). Comes from
+     * `NodeManagement.DetailedDiscoveryData` and identifies which sub-entity
+     * of the node represents this appliance when a node exposes multiple.
+     */
+    deviceType?: string;
+    /**
+     * SPINE entity address of the appliance within the remote node — a
+     * sequence of integers identifying the entity. Useful when the node
+     * exposes multiple entities of the same {@link deviceType}.
+     */
+    entityAddress?: number[];
+    /**
+     * Vendor company code as reported via SPINE
+     * `DeviceClassification.ManufacturerData.VendorCode`. EEBUS-specific
+     * counterpart to the human-readable `vendorName` on the parent
+     * metadata.
+     */
+    vendorCode?: string;
+    /**
+     * Brand name under which the device is sold, as reported via SPINE
+     * `DeviceClassification.ManufacturerData.BrandName`.
+     */
+    brandName?: string;
+    /**
+     * Manufacturer-assigned device code (model identifier) as reported via
+     * SPINE `DeviceClassification.ManufacturerData.DeviceCode`.
+     */
+    deviceCode?: string;
+    /**
+     * Manufacturer-assigned node identifier — the literal
+     * `ManufacturerNodeIdentification` field from SPINE
+     * `DeviceClassificationManufacturerDataType`. Often used by vendors as
+     * a stable identifier across firmware upgrades.
+     */
+    manufacturerNodeIdentification?: string;
+    /**
+     * User-assigned node identifier — the literal `UserNodeIdentification`
+     * field from SPINE `DeviceClassificationUserDataType`. May be changed
+     * by the end user via the device's UI at any time.
+     */
+    userNodeIdentification?: string;
+}
 export declare enum EnyoApplianceConnectionType {
     Connector = "Connector",
     Cloud = "Cloud"
@@ -114,6 +175,8 @@ export interface EnyoApplianceMetadata {
     status?: EnyoApplianceStatusEnum;
     network?: EnyoApplianceNetworkMetadata;
     modbus?: EnyoApplianceModbusMetadata;
+    /** Optional EEBUS connection metadata (SKI, SPINE entity type, vendor code, …) */
+    eebus?: EnyoApplianceEebusMetadata;
     /** Optional MQTT configuration */
     mqtt?: EnyoApplianceMqttConfig;
     connectionType: EnyoApplianceConnectionType;

package/dist/types/enyo-eebus-features.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Types describing the SPINE feature/entity catalog advertised by a remote
+ * EEbus peer.
+ *
+ * The catalog is the **authoritative source of truth** for what a peer can
+ * actually do. It is derived from the lib's `RemoteDevice` view, which is
+ * itself kept in sync with `NodeManagement.DetailedDiscoveryData` replies
+ * and `NodeManagement.NotifyChange` events from the remote.
+ *
+ * Prefer feature/role gates based on this catalog over use-case gates from
+ * {@link EebusUseCaseSupport}: many non-certified peers and simulators
+ * implement working SPINE features (e.g. a `LoadControl` server with a
+ * `loadControlLimitDescriptionData` of `limitDirection: 'consume'`) without
+ * advertising the matching use case in `NodeManagement.UseCaseData`.
+ */
+/**
+ * SPINE role under which a feature is advertised by the remote node.
+ *
+ * The set is intentionally widened with `string` so that lib upgrades that
+ * introduce new SPINE role variants do not break consumer code that
+ * pattern-matches on the role.
+ */
+export type EebusFeatureRole = 'client' | 'server' | 'special' | string;
+/**
+ * SPINE address triple identifying a feature within the EEbus topology.
+ *
+ * - {@link entity} addresses the entity within the remote node (e.g. `[1]`
+ *   for a flat node, `[1, 1]` when the node nests sub-entities such as a
+ *   compressor under a heat-pump appliance).
+ * - {@link feature} addresses the feature within that entity.
+ * - {@link device} optionally carries the remote node's SPINE
+ *   `NetworkAddressDeviceID`. Usually omitted because the surrounding
+ *   {@link EebusRemoteFeatureCatalog.deviceAddress} already provides it.
+ */
+export interface EebusFeatureAddress {
+    /** SPINE entity address — a sequence of integers identifying the entity within the node */
+    entity: number[];
+    /** SPINE feature address within the entity */
+    feature: number;
+    /** Optional SPINE `NetworkAddressDeviceID` of the remote node */
+    device?: string;
+}
+/**
+ * A SPINE function the remote advertises as supported on a feature,
+ * together with the operations (read / write) the remote permits on it.
+ *
+ * The operation payloads are intentionally opaque (`object`) — SPINE
+ * permits per-function filters and bindings whose shape varies by
+ * function and is irrelevant to most callers. Pass them through verbatim
+ * when forwarding to {@link EebusSpineLowLevel}.
+ */
+export interface EebusSupportedFunction {
+    /** SPINE function/data-set name (e.g. `'loadControlLimitListData'`, `'measurementListData'`) */
+    function: string;
+    /** Operations the remote permits on this function */
+    possibleOperations: {
+        /** Present when the remote permits reads; payload mirrors the SPINE `read` operation parameters */
+        read?: object;
+        /** Present when the remote permits writes; payload mirrors the SPINE `write` operation parameters */
+        write?: object;
+    };
+}
+/**
+ * A single SPINE feature advertised by a remote entity.
+ *
+ * The {@link type} is a wire string (e.g. `'LoadControl'`,
+ * `'Measurement'`, `'DeviceClassification'`) rather than a closed enum
+ * so that lib upgrades that introduce new SPINE feature types do not
+ * break existing packages — see {@link EebusSpineLowLevel} for the same
+ * rationale applied to the low-level escape hatch.
+ */
+export interface EebusRemoteFeature {
+    /** SPINE address triple for this feature */
+    address: EebusFeatureAddress;
+    /** SPINE feature type wire string (e.g. `'LoadControl'`, `'Measurement'`) */
+    type: string;
+    /** SPINE role under which the feature is advertised */
+    role: EebusFeatureRole;
+    /** Functions the remote advertises as supported on this feature */
+    supportedFunctions: EebusSupportedFunction[];
+    /** Optional manufacturer-provided label */
+    label?: string;
+    /** Optional manufacturer-provided description */
+    description?: string;
+}
+/**
+ * A SPINE entity advertised by a remote node.
+ *
+ * A node usually exposes a `DeviceInformation` entity (the node itself)
+ * plus one or more application-specific entities (e.g. `EVSE`, `EV`,
+ * `HeatPumpAppliance`, `Compressor`). Sub-entities are flattened into
+ * this list with their full {@link address} path preserved (e.g. `[1, 1]`
+ * for a compressor under a heat-pump appliance), so consumers can
+ * reconstruct the hierarchy when needed.
+ */
+export interface EebusRemoteEntity {
+    /** SPINE entity address — a sequence of integers identifying the entity (e.g. `[1]` or `[1, 1]`) */
+    address: number[];
+    /** SPINE entity type wire string (e.g. `'HeatPumpAppliance'`, `'Compressor'`, `'EVSE'`) */
+    type: string;
+    /** Optional manufacturer-provided label */
+    label?: string;
+    /** Optional manufacturer-provided description */
+    description?: string;
+    /** Features advertised on this entity */
+    features: EebusRemoteFeature[];
+}
+/**
+ * Snapshot of the full SPINE entity/feature catalog advertised by a
+ * remote EEbus peer.
+ *
+ * Returned by {@link EebusFeatureCatalog.get} and delivered to
+ * {@link EebusFeatureCatalog.onFeaturesChanged} listeners. The shape is
+ * intentionally identical between the two so that change subscribers can
+ * drop and replace their cached catalog on every event without diffing.
+ *
+ * When the peer identified by {@link ski} is not known (never paired or
+ * not currently connected), {@link found} is `false` and {@link entities}
+ * is an empty array — the call resolves cleanly rather than throwing, so
+ * packages can use the snapshot as a feature gate without try/catch.
+ */
+export interface EebusRemoteFeatureCatalog {
+    /** Subject Key Identifier of the remote node this catalog describes */
+    ski: string;
+    /** Whether the peer is currently known to the SDK (paired AND reachable) */
+    found: boolean;
+    /** Remote node's SPINE `NetworkAddressDeviceID`, when known */
+    deviceAddress?: string;
+    /** SPINE entities advertised by the remote node, flattened with their address path preserved */
+    entities: EebusRemoteEntity[];
+}

package/dist/types/enyo-eebus-features.js

@@ -0,0 +1,16 @@
+/**
+ * Types describing the SPINE feature/entity catalog advertised by a remote
+ * EEbus peer.
+ *
+ * The catalog is the **authoritative source of truth** for what a peer can
+ * actually do. It is derived from the lib's `RemoteDevice` view, which is
+ * itself kept in sync with `NodeManagement.DetailedDiscoveryData` replies
+ * and `NodeManagement.NotifyChange` events from the remote.
+ *
+ * Prefer feature/role gates based on this catalog over use-case gates from
+ * {@link EebusUseCaseSupport}: many non-certified peers and simulators
+ * implement working SPINE features (e.g. a `LoadControl` server with a
+ * `loadControlLimitDescriptionData` of `limitDirection: 'consume'`) without
+ * advertising the matching use case in `NodeManagement.UseCaseData`.
+ */
+export {};

package/dist/version.d.ts

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