@enyo-energy/energy-app-sdk 0.0.137 → 0.0.139

package/dist/cjs/index.cjs

@@ -50,9 +50,11 @@ __exportStar(require("./types/enyo-currency.cjs"), exports);
 __exportStar(require("./packages/energy-app-sequence-generator.cjs"), exports);
 __exportStar(require("./packages/energy-app-energy-prices.cjs"), exports);
 __exportStar(require("./packages/energy-app-modbus-rtu.cjs"), exports);
+__exportStar(require("./types/enyo-spine.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("./types/enyo-eebus-errors.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

@@ -34,9 +34,11 @@ export * from './types/enyo-currency.cjs';
 export * from './packages/energy-app-sequence-generator.cjs';
 export * from './packages/energy-app-energy-prices.cjs';
 export * from './packages/energy-app-modbus-rtu.cjs';
+export * from './types/enyo-spine.cjs';
 export * from './types/enyo-eebus.cjs';
 export * from './types/enyo-eebus-use-cases.cjs';
 export * from './types/enyo-eebus-features.cjs';
+export * from './types/enyo-eebus-errors.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.d.cts

@@ -1,4 +1,35 @@
-import { EebusRemoteFeatureCatalog } from '../../types/enyo-eebus-features.cjs';
+import { EebusFeatureRole, EebusRemoteFeatureCatalog } from '../../types/enyo-eebus-features.cjs';
+import { SpineEntityType, SpineFeatureType, SpineFunctionType } from '../../types/enyo-spine.cjs';
+/**
+ * One match returned by {@link EebusFeatureCatalog.findFeatureAddresses}.
+ *
+ * Carries enough context for a caller to pick *which* entity it wants to
+ * target without having to walk the full {@link EebusRemoteFeatureCatalog}
+ * tree itself. {@link entityType} is the deciding field on heat pumps —
+ * it lets a caller say "the compressor's `Measurement`, not the heat
+ * pump's" without hard-coding entity addresses.
+ */
+export interface EebusFeatureAddressMatch {
+    /** SPINE entity address that hosts the feature (e.g. `[3, 1]`) */
+    entity: number[];
+    /**
+     * SPINE entity type that hosts the feature, from the
+     * {@link SpineEntityType} catalogue
+     * (e.g. `SpineEntityType.HM_COMPRESSOR`,
+     * `SpineEntityType.HVAC_ROOM`).
+     */
+    entityType: SpineEntityType;
+    /** SPINE feature index within {@link entity} */
+    feature: number;
+    /**
+     * Functions the remote advertises as supported on this feature
+     * (e.g. `[SpineFunctionType.MeasurementListData,
+     * SpineFunctionType.MeasurementDescriptionListData]`). Useful for
+     * picking between entities that nominally host the same feature
+     * type but expose different functions.
+     */
+    supportedFunctions: SpineFunctionType[];
+}
 /**
  * Per-peer SPINE entity/feature catalog for paired EEbus remotes.
  *
@@ -81,6 +112,31 @@ export interface EebusFeatureCatalog {
      * @returns Listener ID that can be passed to {@link removeListener} to cancel
      */
     onFeaturesChanged: (ski: string, listener: (catalog: EebusRemoteFeatureCatalog) => void) => string;
+    /**
+     * Enumerate every entity on a remote node that advertises a feature of
+     * the given type and role, with enough context for the caller to pick
+     * meaningfully between them.
+     *
+     * The canonical use case is multi-entity heat pumps: a Vaillant VR940
+     * advertises `Measurement` (server) on its `HeatPumpAppliance`,
+     * `Compressor`, `HVACRoom`, and `TemperatureSensor` entities. A caller
+     * that wants the compressor's electrical measurement (not the
+     * appliance-wide MPC roll-up) walks this list, filters by
+     * `entityType === 'Compressor'`, and passes the resulting `entity` /
+     * `feature` to {@link EebusSpineLowLevel.subscribe} (or to a typed
+     * use-case client's `address` option).
+     *
+     * The result is derived from the current {@link get} snapshot — it
+     * does not trigger a re-fetch from the remote. When the peer is not
+     * paired or not currently connected the call resolves to an empty
+     * array rather than throwing.
+     *
+     * @param ski Subject Key Identifier of the remote node
+     * @param featureType SPINE feature type from the {@link SpineFeatureType} catalogue (e.g. `SpineFeatureType.MEASUREMENT`, `SpineFeatureType.SMART_ENERGY_MANAGEMENT_PS`)
+     * @param role SPINE role to match: `'server'` for features the remote *hosts*, `'client'` for features it *consumes*
+     * @returns Every matching feature address on the peer, in catalog order
+     */
+    findFeatureAddresses: (ski: string, featureType: SpineFeatureType, role: EebusFeatureRole) => Promise<EebusFeatureAddressMatch[]>;
     /**
      * Remove a feature-catalog listener previously registered via
      * {@link onFeaturesChanged}.

package/dist/cjs/packages/eebus/eebus-hvac-client.d.cts

@@ -1,4 +1,33 @@
+import { SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
 import { EebusHvacOperationMode, EebusHvacZoneState } from '../../types/enyo-eebus-use-cases.cjs';
+import { SpineEntityType } from '../../types/enyo-spine.cjs';
+/**
+ * Per-call configuration for {@link EebusUseCaseRegistry.hvac}.
+ *
+ * Heat pumps expose `Hvac` on the entity that owns the zone, typically
+ * `HVACRoom`. Multi-zone peers may host the feature on more than one
+ * entity — pin the target via {@link address} or {@link prefer} to talk
+ * to a specific zone.
+ */
+export interface HvacClientOptions {
+    /**
+     * Bind the client to a specific entity (and optionally feature index)
+     * on the remote. Wins over {@link prefer} when both are supplied.
+     */
+    address?: SpineRemoteTarget;
+    /**
+     * Resolution hint when {@link address} is omitted. Pin to a
+     * {@link SpineEntityType} value — typically
+     * {@link SpineEntityType.HVAC_ROOM} or
+     * {@link SpineEntityType.HEATING_ZONE} on a multi-zone heat pump.
+     */
+    prefer?: SpineEntityType | 'auto';
+    /**
+     * Override the internal `hvacOperationModeDescriptionListData` read
+     * timeout (default 5_000 ms).
+     */
+    descriptionReadTimeoutMs?: number;
+}
 /**
  * Client for the EEBUS **Hvac** feature.
  *
@@ -11,10 +40,18 @@ import { EebusHvacOperationMode, EebusHvacZoneState } from '../../types/enyo-eeb
  * The client exposes both actor roles on a single interface:
  * - **EMS role (outbound):** {@link getOperationMode}, {@link setOperationMode},
  *   {@link getZoneStates}, {@link onZoneStateChanged}
- * - **CS role (inbound):** {@link provideOperationMode}, {@link provideZoneStates}
+ * - **CS role (inbound):** {@link provideOperationMode}, {@link provideZoneStates},
+ *   {@link onOperationModeReceived}
  *
  * Consumers that only act in one role simply never call the other half — there
  * is no `asManager` / `asAppliance` split.
+ *
+ * **Resolution.** The client resolves the remote `Hvac` feature via the
+ * SPINE feature catalog rather than the peer's `NodeManagement.UseCaseData`
+ * advertisement, so peers that expose `Hvac` without advertising a
+ * matching use case (e.g. Vaillant VR940) are supported.
+ * `EebusFeatureUnavailableError` is thrown only when no `Hvac` server
+ * feature exists on the peer at all.
  */
 export interface EebusHvacClient {
     /**
@@ -54,7 +91,17 @@ export interface EebusHvacClient {
      */
     provideZoneStates: (provider: () => Promise<EebusHvacZoneState[]>) => void;
     /**
-     * Remove a listener previously registered via {@link onZoneStateChanged}.
+     * Register a handler invoked when a remote EMS writes the operation mode
+     * to this device. Implementations should apply the mode to the local
+     * controller. Mirrors {@link EebusSetpointClient.onSetpointReceived} so
+     * package authors see a consistent write-handler shape across features.
+     * @param handler Callback invoked with the incoming operation mode
+     * @returns Listener ID that can be passed to {@link removeListener} to deregister
+     */
+    onOperationModeReceived: (handler: (mode: EebusHvacOperationMode) => Promise<void>) => string;
+    /**
+     * Remove a listener previously registered via {@link onZoneStateChanged}
+     * or {@link onOperationModeReceived}.
      * @param listenerId The ID returned by the registration method
      */
     removeListener: (listenerId: string) => void;

package/dist/cjs/packages/eebus/eebus-lpc-client.d.cts

@@ -1,4 +1,35 @@
+import { SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
 import { EebusLpcAck, EebusLpcFailsafe, EebusLpcLimit } from '../../types/enyo-eebus-use-cases.cjs';
+import { SpineEntityType } from '../../types/enyo-spine.cjs';
+/**
+ * Per-call configuration for {@link EebusUseCaseRegistry.lpc}.
+ *
+ * On flat peers (a single controllable system per node) the defaults
+ * resolve correctly. Multi-entity peers — notably heat pumps that host
+ * `LoadControl` on both a top-level `HeatPumpAppliance` entity and an
+ * inner controllable entity — should pin the client to the entity whose
+ * limit semantics they want.
+ */
+export interface LpcClientOptions {
+    /**
+     * Bind the client to a specific entity (and optionally feature index)
+     * on the remote. Wins over {@link prefer} when both are supplied.
+     */
+    address?: SpineRemoteTarget;
+    /**
+     * Resolution hint when {@link address} is omitted. `'auto'` (default)
+     * keeps current first-match behaviour. Otherwise pin the resolver
+     * to a {@link SpineEntityType} value — typically
+     * {@link SpineEntityType.HM_HEAT_PUMP} for an appliance-level
+     * `LoadControl` server.
+     */
+    prefer?: SpineEntityType | 'auto';
+    /**
+     * Override the internal `loadControlLimitDescriptionListData` read
+     * timeout (default 5_000 ms).
+     */
+    descriptionReadTimeoutMs?: number;
+}
 /**
  * Client for the EEBUS **Limitation of Power Consumption (LPC)** use case.
  *

package/dist/cjs/packages/eebus/eebus-mpc-client.d.cts

@@ -1,4 +1,48 @@
+import { SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
 import { EebusMpcReading } from '../../types/enyo-eebus-use-cases.cjs';
+import { SpineEntityType } from '../../types/enyo-spine.cjs';
+/**
+ * Per-call configuration for {@link EebusUseCaseRegistry.mpc}.
+ *
+ * Heat pumps frequently expose `Measurement` (server) on more than one
+ * entity — typically both the `HeatPumpAppliance` (whole-appliance
+ * roll-up) and the `Compressor` (compressor-only draw). Without targeting
+ * the SDK resolves the first match it encounters, which has historically
+ * meant consumers silently picked up the wrong vantage point. These
+ * options give the caller direct control.
+ */
+export interface MpcClientOptions {
+    /**
+     * Bind the client to a specific entity (and optionally feature index)
+     * on the remote. Wins over {@link prefer} when both are supplied.
+     * Use {@link EebusFeatureCatalog.findFeatureAddresses} to enumerate
+     * candidates.
+     */
+    address?: SpineRemoteTarget;
+    /**
+     * Resolution hint when {@link address} is omitted. `'auto'` (the
+     * default) keeps current behaviour — first match wins. Otherwise
+     * pin the resolver to a {@link SpineEntityType} value — most
+     * commonly {@link SpineEntityType.HM_COMPRESSOR} or
+     * {@link SpineEntityType.HM_HEAT_PUMP} on heat-pump peers.
+     */
+    prefer?: SpineEntityType | 'auto';
+    /**
+     * Override the internal `measurementDescriptionListData` read timeout
+     * (default 5_000 ms). Useful for peers whose description-list reply is
+     * sluggish but functional — extend rather than disable.
+     */
+    descriptionReadTimeoutMs?: number;
+    /**
+     * When the internal description read fails (timeout or
+     * not-supported), fall back to extracting `scopeType` from each
+     * inbound notify (`acPowerTotal` → {@link EebusMpcReading.activePowerW},
+     * `acEnergyConsumed` → {@link EebusMpcReading.totalEnergyConsumedWh})
+     * so the client keeps emitting readings instead of going silent.
+     * Defaults to `true`.
+     */
+    fallbackToInlineScope?: boolean;
+}
 /**
  * Client for the EEBUS **Monitoring of Power Consumption (MPC)** use case.
  *
@@ -8,6 +52,15 @@ import { EebusMpcReading } from '../../types/enyo-eebus-use-cases.cjs';
  * The client exposes both actor roles on a single interface:
  * - **EMS role (consume):** {@link getReading}, {@link onReading}
  * - **CS role (provide):** {@link provideReading}
+ *
+ * **Resolution.** From SDK 0.0.139 onward this client resolves the remote
+ * `Measurement` feature via the SPINE feature catalog rather than via the
+ * peer's advertised `monitoringOfPowerConsumption` use-case entry. Many
+ * non-certified peers (notably Vaillant heat pumps) expose the feature
+ * without advertising the use case; the previous resolution path silently
+ * no-op'd on them. The client now only throws
+ * `EebusFeatureUnavailableError` when no `Measurement` server feature
+ * exists at all on the peer.
  */
 export interface EebusMpcClient {
     /**

package/dist/cjs/packages/eebus/eebus-ohpcf-client.d.cts

@@ -1,4 +1,38 @@
-import { EebusOhpcfFlexibility, EebusOhpcfIncentiveTable, EebusOhpcfPlanState } from '../../types/enyo-eebus-use-cases.cjs';
+import { SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
+import { EebusOhpcfAnnouncement, EebusOhpcfApplianceContext, EebusOhpcfFlavour, EebusOhpcfFlexibility, EebusOhpcfIncentiveTable, EebusOhpcfPlanState } from '../../types/enyo-eebus-use-cases.cjs';
+/**
+ * Per-call configuration for {@link EebusUseCaseRegistry.ohpcf}.
+ *
+ * On Vaillant peers — where OHPCF is layered on `SmartEnergyManagementPs`
+ * and the feature lives on the `Compressor` sub-entity — pass
+ * {@link address} (or `prefer`-equivalent: `flavour: 'smartEnergyManagementPs'`)
+ * so the client targets the correct entity without falling back to raw
+ * SPINE writes.
+ */
+export interface OhpcfClientOptions {
+    /**
+     * Pin the on-wire flavour. `'auto'` (the default) inspects the peer's
+     * feature catalog and selects whichever flavour it advertises.
+     */
+    flavour?: EebusOhpcfFlavour;
+    /**
+     * Bind the client to a specific entity (and optionally feature
+     * index). Required on multi-entity peers where the OHPCF-bearing
+     * feature is hosted on more than one entity. Use
+     * {@link EebusFeatureCatalog.findFeatureAddresses} with
+     * `SpineFeatureType.INCENTIVE_TABLE` or
+     * `SpineFeatureType.SMART_ENERGY_MANAGEMENT_PS` to enumerate
+     * candidates.
+     */
+    address?: SpineRemoteTarget;
+    /**
+     * Override the internal description-list read timeout (default
+     * 5_000 ms). Applies to the flavour-appropriate description function
+     * (`incentiveDescriptionData` or
+     * `smartEnergyManagementPsConfigurationData`).
+     */
+    descriptionReadTimeoutMs?: number;
+}
 /**
  * Client for the EEBUS **Optimization of Self Consumption by Heat Pump
  * Compressor Flexibility (OHPCF)** use case.
@@ -11,10 +45,17 @@ import { EebusOhpcfFlexibility, EebusOhpcfIncentiveTable, EebusOhpcfPlanState }
  *
  * The client exposes both actor roles on a single interface:
  * - **CEM role:** {@link sendIncentiveTable}, {@link getCurrentPlanState},
- *   {@link onFlexibilityUpdate}
+ *   {@link onFlexibilityUpdate}, {@link onAnnouncement}, {@link activateNow}
  * - **Heat Pump role:** {@link provideFlexibility}, {@link providePlanState},
  *   {@link onIncentiveTableReceived}
  *
+ * **Flavours.** OHPCF ships in two interoperable encodings — the
+ * canonical `IncentiveTable` flavour and Vaillant's
+ * `SmartEnergyManagementPs` flavour. Pin the flavour via
+ * {@link OhpcfClientOptions.flavour} when known, or rely on the default
+ * `'auto'` to probe the feature catalog. Methods that are flavour-specific
+ * are documented as such on each method.
+ *
  * @see https://techdocs.wago.com/Software/EEBUS_Connector/en-US/3657311371.html
  * @see https://github.com/enbility/eebus-go/pull/122
  */
@@ -22,6 +63,10 @@ export interface EebusOhpcfClient {
     /**
      * Send an incentive table to the heat pump. The heat pump will use
      * the table to plan its compressor operation over the covered horizon.
+     *
+     * **Flavour:** `incentiveTable`. Throws on a client pinned to
+     * `smartEnergyManagementPs` — use {@link activateNow} there instead.
+     *
      * @param table The incentive table to send
      */
     sendIncentiveTable: (table: EebusOhpcfIncentiveTable) => Promise<void>;
@@ -37,6 +82,31 @@ export interface EebusOhpcfClient {
      * @returns Listener ID that can be passed to {@link removeListener} to cancel
      */
     onFlexibilityUpdate: (listener: (flexibility: EebusOhpcfFlexibility) => void) => string;
+    /**
+     * Subscribe to OHPCF announcements emitted by the heat pump. Each
+     * announcement describes a planned consumption window the CEM may
+     * activate via {@link activateNow}.
+     *
+     * **Flavour:** `smartEnergyManagementPs`. Returns a no-op listener
+     * id on `incentiveTable` peers — those peers do not emit
+     * announcements.
+     *
+     * @param listener Callback invoked with each new announcement
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onAnnouncement: (listener: (announcement: EebusOhpcfAnnouncement) => void) => string;
+    /**
+     * Activate a previously-announced consumption window on the heat
+     * pump. The heat pump starts the compressor under the parameters
+     * carried in {@link EebusOhpcfApplianceContext}.
+     *
+     * **Flavour:** `smartEnergyManagementPs`. Throws on a client pinned
+     * to `incentiveTable` — those peers schedule themselves from the
+     * incentive table without an explicit activation.
+     *
+     * @param context Activation context (announcement id + optional overrides)
+     */
+    activateNow: (context: EebusOhpcfApplianceContext) => Promise<void>;
     /**
      * Register a provider that reports the heat pump's current compressor
      * flexibility when a remote CEM reads it.

package/dist/cjs/packages/eebus/eebus-setpoint-client.d.cts

@@ -1,4 +1,34 @@
+import { SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
 import { EebusSetpointValue } from '../../types/enyo-eebus-use-cases.cjs';
+import { SpineEntityType } from '../../types/enyo-spine.cjs';
+/**
+ * Per-call configuration for {@link EebusUseCaseRegistry.setpoint}.
+ *
+ * Heat pumps expose `Setpoint` on the entity that owns the zone — most
+ * commonly `HVACRoom`, occasionally `HeatingZone`. The default resolution
+ * scans the catalog and picks the first match. Pin the target via
+ * {@link address} or {@link prefer} when the peer hosts multiple
+ * candidates.
+ */
+export interface SetpointClientOptions {
+    /**
+     * Bind the client to a specific entity (and optionally feature index)
+     * on the remote. Wins over {@link prefer} when both are supplied.
+     */
+    address?: SpineRemoteTarget;
+    /**
+     * Resolution hint when {@link address} is omitted. Pin to a
+     * {@link SpineEntityType} value — typically
+     * {@link SpineEntityType.HVAC_ROOM} or
+     * {@link SpineEntityType.HEATING_ZONE} on a multi-zone heat pump.
+     */
+    prefer?: SpineEntityType | 'auto';
+    /**
+     * Override the internal `setpointDescriptionListData` read timeout
+     * (default 5_000 ms).
+     */
+    descriptionReadTimeoutMs?: number;
+}
 /**
  * Client for the EEBUS **Setpoint** feature.
  *
@@ -16,6 +46,13 @@ import { EebusSetpointValue } from '../../types/enyo-eebus-use-cases.cjs';
  *
  * Consumers that only act in one role simply never call the other half — there
  * is no `asManager` / `asAppliance` split.
+ *
+ * **Resolution.** The client resolves the remote `Setpoint` feature via
+ * the SPINE feature catalog rather than the peer's
+ * `NodeManagement.UseCaseData` advertisement. Peers that expose `Setpoint`
+ * without advertising a matching use case (e.g. Vaillant VR940) are now
+ * supported. `EebusFeatureUnavailableError` is thrown only when no
+ * `Setpoint` server feature exists on the peer at all.
  */
 export interface EebusSetpointClient {
     /**

package/dist/cjs/packages/eebus/eebus-spine-low-level.d.cts

@@ -1,4 +1,4 @@
-import { EebusDataPoint } from '../../types/enyo-eebus.cjs';
+import { EebusDataPoint, SpineRemoteTarget } from '../../types/enyo-eebus.cjs';
 /**
  * Low-level SPINE escape hatch for direct feature data access.
  *
@@ -17,34 +17,66 @@ import { EebusDataPoint } from '../../types/enyo-eebus.cjs';
  * `'Measurement'`, `'LoadControl'`, `'DeviceConfiguration'`,
  * `'Identification'`, `'IncentiveTable'`, `'TimeSeries'`, `'Hvac'`,
  * `'SmartEnergyManagementPs'`, and many more — consult the SPINE spec.
+ *
+ * **Entity targeting.** Heat pumps and other multi-entity peers routinely
+ * expose the same `featureType` on more than one entity (e.g. `Measurement`
+ * on both `HeatPumpAppliance` and `Compressor`). Without a {@link SpineRemoteTarget}
+ * the SDK picks the first matching entity it resolves, which can deliver
+ * notifies from the wrong vantage point. Pass a `target` to scope reads /
+ * writes / subscriptions to a specific entity; inbound data points then
+ * carry `source` on every event so consumers can attribute multi-entity
+ * subscriptions. Use {@link EebusFeatureCatalog.findFeatureAddresses} to
+ * enumerate candidates before targeting.
  */
 export interface EebusSpineLowLevel {
     /**
      * Read specific data points from a SPINE feature on a remote device.
+     *
+     * When `target` is omitted the SDK reads from whichever entity it
+     * resolves first — fine on flat peers, ambiguous on peers that expose
+     * the feature type on multiple entities. Pass `target` to bind the read
+     * to a specific entity.
+     *
      * @param ski Subject Key Identifier of the target device
      * @param featureType SPINE feature type name (e.g. `'Measurement'`)
      * @param functionName Specific function or data set to read (e.g. `'measurementListData'`)
+     * @param target Optional remote entity (and feature) to scope the read to
      * @returns The data point containing the raw value, timestamp, and optional unit
      */
-    readData: (ski: string, featureType: string, functionName: string) => Promise<EebusDataPoint>;
+    readData: (ski: string, featureType: string, functionName: string, target?: SpineRemoteTarget) => Promise<EebusDataPoint>;
     /**
      * Write data or send a command to a SPINE feature on a remote device.
+     *
+     * When `target` is omitted the SDK writes to whichever entity it
+     * resolves first. Use `target` to bind the write to a specific entity
+     * (e.g. `SmartEnergyManagementPs` on `Compressor` rather than on
+     * `HeatPumpAppliance`).
+     *
      * @param ski Subject Key Identifier of the target device
      * @param featureType SPINE feature type name (e.g. `'LoadControl'`)
      * @param functionName Specific function or command to invoke (e.g. `'loadControlLimitListData'`)
      * @param payload The raw data payload to send — caller is responsible for matching the SPINE schema
+     * @param target Optional remote entity (and feature) to scope the write to
      */
-    writeData: (ski: string, featureType: string, functionName: string, payload: unknown) => Promise<void>;
+    writeData: (ski: string, featureType: string, functionName: string, payload: unknown, target?: SpineRemoteTarget) => Promise<void>;
     /**
      * Subscribe to automatic notifications when a SPINE feature's data changes.
      * Sets up a SPINE binding so the local device is notified whenever the
      * subscribed data changes.
+     *
+     * When `target` is omitted the subscription matches the feature type
+     * across every entity that hosts it on the remote, and the listener is
+     * invoked once per source — inspect {@link EebusDataPoint.source} to
+     * attribute each notify. Pass `target` to bind the subscription to a
+     * single entity (the recommended shape on multi-entity peers).
+     *
      * @param ski Subject Key Identifier of the target device
      * @param featureType SPINE feature type name to subscribe to
      * @param listener Callback invoked with updated data whenever the value changes
+     * @param target Optional remote entity (and feature) to scope the subscription to
      * @returns Listener ID that can be passed to {@link removeListener} to cancel the subscription
      */
-    subscribe: (ski: string, featureType: string, listener: (data: EebusDataPoint) => void) => string;
+    subscribe: (ski: string, featureType: string, listener: (data: EebusDataPoint) => void, target?: SpineRemoteTarget) => string;
     /**
      * Remove a subscription previously registered via {@link subscribe}.
      * @param listenerId The ID returned by the registration method

package/dist/cjs/packages/eebus/eebus-use-case-registry.d.cts

@@ -1,10 +1,10 @@
-import { EebusHvacClient } from './eebus-hvac-client.cjs';
-import { EebusLpcClient } from './eebus-lpc-client.cjs';
+import { EebusHvacClient, HvacClientOptions } from './eebus-hvac-client.cjs';
+import { EebusLpcClient, LpcClientOptions } from './eebus-lpc-client.cjs';
 import { EebusLppClient } from './eebus-lpp-client.cjs';
 import { EebusMgcpClient } from './eebus-mgcp-client.cjs';
-import { EebusMpcClient } from './eebus-mpc-client.cjs';
-import { EebusOhpcfClient } from './eebus-ohpcf-client.cjs';
-import { EebusSetpointClient } from './eebus-setpoint-client.cjs';
+import { EebusMpcClient, MpcClientOptions } from './eebus-mpc-client.cjs';
+import { EebusOhpcfClient, OhpcfClientOptions } from './eebus-ohpcf-client.cjs';
+import { EebusSetpointClient, SetpointClientOptions } from './eebus-setpoint-client.cjs';
 /**
  * Registry of typed EEBUS use-case clients, scoped per remote device (SKI).
  *
@@ -43,9 +43,17 @@ export interface EebusUseCaseRegistry {
     /**
      * Get the **Limitation of Power Consumption** client for a remote node.
      * LPC limits are obligations the remote MUST respect.
+     *
+     * Multi-entity peers (e.g. a heat pump that hosts `LoadControl` on
+     * more than one entity) should pass {@link LpcClientOptions.address}
+     * or {@link LpcClientOptions.prefer} to pin the client to a specific
+     * entity. Omitting `options` keeps the existing first-match
+     * behaviour.
+     *
      * @param ski Subject Key Identifier of the remote node
+     * @param options Optional address/timeout configuration
      */
-    lpc: (ski: string) => EebusLpcClient;
+    lpc: (ski: string, options?: LpcClientOptions) => EebusLpcClient;
     /**
      * Get the **Limitation of Power Production** client for a remote node.
      * LPP limits are recommendations the remote SHOULD respect.
@@ -61,28 +69,50 @@ export interface EebusUseCaseRegistry {
     /**
      * Get the **Monitoring of Power Consumption** client for a remote node.
      * Read-only telemetry from a controllable system reporting its own consumption.
+     *
+     * Heat pumps that host `Measurement` on both `HeatPumpAppliance` and
+     * `Compressor` should pass {@link MpcClientOptions.prefer} (or
+     * {@link MpcClientOptions.address} when the address is already
+     * known). Without a hint the client picks the first server match the
+     * SDK resolves.
+     *
+     * The default options enable `fallbackToInlineScope`, so a single
+     * slow `measurementDescriptionListData` read on a flaky peer no
+     * longer silences the client — it falls back to extracting scope
+     * from inbound notifies.
+     *
      * @param ski Subject Key Identifier of the remote node
+     * @param options Optional address/timeout/fallback configuration
      */
-    mpc: (ski: string) => EebusMpcClient;
+    mpc: (ski: string, options?: MpcClientOptions) => EebusMpcClient;
     /**
      * Get the **Optimization of Self Consumption by Heat Pump Compressor
      * Flexibility** client for a remote node. Incentive-table-driven heat
      * pump coordination.
+     *
+     * Two on-wire flavours exist (see {@link OhpcfClientOptions.flavour}):
+     * `IncentiveTable` (canonical) and `SmartEnergyManagementPs`
+     * (Vaillant). `auto` (the default) probes the feature catalog and
+     * picks whichever the peer advertises.
+     *
      * @param ski Subject Key Identifier of the remote node
+     * @param options Optional address/flavour configuration
      */
-    ohpcf: (ski: string) => EebusOhpcfClient;
+    ohpcf: (ski: string, options?: OhpcfClientOptions) => EebusOhpcfClient;
     /**
      * Get the **Setpoint** client for a remote node. Manages target values
      * for controllable parameters such as per-zone heat-pump temperature
      * setpoints. Pair with {@link hvac} to read measured values.
      * @param ski Subject Key Identifier of the remote node
+     * @param options Optional address/timeout configuration
      */
-    setpoint: (ski: string) => EebusSetpointClient;
+    setpoint: (ski: string, options?: SetpointClientOptions) => EebusSetpointClient;
     /**
      * Get the **Hvac** client for a remote node. Observes heating/cooling
      * operation mode and per-zone state on a heat-pump appliance. Pair with
      * {@link setpoint} to write target values.
      * @param ski Subject Key Identifier of the remote node
+     * @param options Optional address/timeout configuration
      */
-    hvac: (ski: string) => EebusHvacClient;
+    hvac: (ski: string, options?: HvacClientOptions) => EebusHvacClient;
 }

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

@@ -4,17 +4,17 @@ 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 { EebusFeatureCatalog, EebusFeatureAddressMatch } 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';
-export { EebusHvacClient } from './eebus-hvac-client.cjs';
-export { EebusLpcClient } from './eebus-lpc-client.cjs';
+export { EebusHvacClient, HvacClientOptions } from './eebus-hvac-client.cjs';
+export { EebusLpcClient, LpcClientOptions } from './eebus-lpc-client.cjs';
 export { EebusLppClient } from './eebus-lpp-client.cjs';
 export { EebusMgcpClient } from './eebus-mgcp-client.cjs';
-export { EebusMpcClient } from './eebus-mpc-client.cjs';
-export { EebusOhpcfClient } from './eebus-ohpcf-client.cjs';
-export { EebusSetpointClient } from './eebus-setpoint-client.cjs';
+export { EebusMpcClient, MpcClientOptions } from './eebus-mpc-client.cjs';
+export { EebusOhpcfClient, OhpcfClientOptions } from './eebus-ohpcf-client.cjs';
+export { EebusSetpointClient, SetpointClientOptions } from './eebus-setpoint-client.cjs';
 /**
  * Interface for EEbus (SHIP/SPINE) device communication in enyo packages.
  *

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

@@ -206,7 +206,7 @@ export declare enum EnyoDataBusMessageEnum {
     StartCalibrationV1 = "StartCalibrationV1",
     StopCalibrationV1 = "StopCalibrationV1"
 }
-export type EnyoDataBusMessageResolution = '10s' | '30s' | '1m' | '15m' | '1h' | '1d' | 'dynamic';
+export type EnyoDataBusMessageResolution = '1s' | '10s' | '30s' | '1m' | '15m' | '1h' | '1d' | 'dynamic';
 /**
  * Optional addressing information for a {@link EnyoDataBusMessage}. When omitted
  * the message is broadcast to all subscribers; when set, the message is only