@enyo-energy/energy-app-sdk 0.0.127 → 0.0.129

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

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

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

@@ -0,0 +1,61 @@
+import { EebusHvacOperationMode, EebusHvacZoneState } from '../../types/enyo-eebus-use-cases.cjs';
+/**
+ * Client for the EEBUS **Hvac** feature.
+ *
+ * The Hvac feature reports heating/cooling operation mode and per-zone state
+ * (current temperature, active mode). Pair with the
+ * {@link EebusSetpointClient} Setpoint feature to read or write target values.
+ * Zone ids align with `Identification.identificationListData`, so callers can
+ * map zone state to human-readable zone names.
+ *
+ * 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}
+ *
+ * Consumers that only act in one role simply never call the other half — there
+ * is no `asManager` / `asAppliance` split.
+ */
+export interface EebusHvacClient {
+    /**
+     * Read the active heating/cooling operation mode from the remote node.
+     */
+    getOperationMode: () => Promise<EebusHvacOperationMode>;
+    /**
+     * Request the remote node to switch to the given operation mode. The
+     * remote may reject modes it does not advertise — verify support via
+     * `EebusIdentityService.getSupportedUseCases` before calling.
+     * @param mode The operation mode to select on the remote
+     */
+    setOperationMode: (mode: EebusHvacOperationMode) => Promise<void>;
+    /**
+     * Read per-zone Hvac state (current temperature, active mode) from the
+     * remote node.
+     * @returns The state of each zone reported by the remote.
+     */
+    getZoneStates: () => Promise<EebusHvacZoneState[]>;
+    /**
+     * Subscribe to per-zone Hvac state updates. The listener fires once per
+     * zone whenever the remote republishes its state.
+     * @param listener Callback invoked with the updated zone state
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onZoneStateChanged: (listener: (state: EebusHvacZoneState) => void) => string;
+    /**
+     * Register a provider that supplies this device's current operation mode
+     * when a remote EMS reads it.
+     * @param provider Async callback returning the active operation mode
+     */
+    provideOperationMode: (provider: () => Promise<EebusHvacOperationMode>) => void;
+    /**
+     * Register a provider that supplies this device's current per-zone state
+     * when a remote EMS reads it.
+     * @param provider Async callback returning the current zone-state list
+     */
+    provideZoneStates: (provider: () => Promise<EebusHvacZoneState[]>) => void;
+    /**
+     * Remove a listener previously registered via {@link onZoneStateChanged}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

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

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

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

@@ -0,0 +1,59 @@
+import { EebusSetpointValue } from '../../types/enyo-eebus-use-cases.cjs';
+/**
+ * Client for the EEBUS **Setpoint** feature.
+ *
+ * The Setpoint feature carries the target value(s) of a controllable
+ * parameter on a remote node — most commonly the per-zone target temperature
+ * on a heat pump (paired with the {@link EebusHvacClient} Hvac feature for
+ * measured values). Setpoint ids align with the zone ids reported by
+ * `Identification.identificationListData`, so callers can map setpoints to
+ * human-readable zone names.
+ *
+ * The client exposes both actor roles on a single interface:
+ * - **EMS role (outbound):** {@link getSetpoints}, {@link setSetpoint},
+ *   {@link onSetpointsChanged}
+ * - **CS role (inbound):** {@link provideSetpoints}, {@link onSetpointReceived}
+ *
+ * Consumers that only act in one role simply never call the other half — there
+ * is no `asManager` / `asAppliance` split.
+ */
+export interface EebusSetpointClient {
+    /**
+     * Read the current setpoints reported by the remote node.
+     * @returns The full list of setpoints currently published by the remote.
+     */
+    getSetpoints: () => Promise<EebusSetpointValue[]>;
+    /**
+     * Send a setpoint to the remote node. The remote applies the value to the
+     * setpoint identified by {@link EebusSetpointValue.setpointId}; existing
+     * setpoints at other ids are left unchanged.
+     * @param value The setpoint to apply
+     */
+    setSetpoint: (value: EebusSetpointValue) => Promise<void>;
+    /**
+     * Subscribe to setpoint-list updates from the remote node. The listener is
+     * invoked with the full current list whenever the remote republishes.
+     * @param listener Callback invoked with the new setpoint list
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onSetpointsChanged: (listener: (values: EebusSetpointValue[]) => void) => string;
+    /**
+     * Register a provider that supplies this device's current setpoints when a
+     * remote EMS reads them.
+     * @param provider Async callback returning the current setpoint list
+     */
+    provideSetpoints: (provider: () => Promise<EebusSetpointValue[]>) => void;
+    /**
+     * Register a handler invoked when a remote EMS writes a setpoint to this
+     * device. Implementations should apply the value to the local controller.
+     * @param handler Callback invoked with the incoming setpoint
+     * @returns Listener ID that can be passed to {@link removeListener} to deregister
+     */
+    onSetpointReceived: (handler: (value: EebusSetpointValue) => Promise<void>) => string;
+    /**
+     * Remove a listener previously registered via {@link onSetpointsChanged} or
+     * {@link onSetpointReceived}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

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

@@ -1,8 +1,10 @@
+import { EebusHvacClient } from './eebus-hvac-client.cjs';
 import { EebusLpcClient } 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';
 /**
  * Registry of typed EEBUS use-case clients, scoped per remote device (SKI).
  *
@@ -69,4 +71,18 @@ export interface EebusUseCaseRegistry {
      * @param ski Subject Key Identifier of the remote node
      */
     ohpcf: (ski: string) => 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
+     */
+    setpoint: (ski: string) => 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
+     */
+    hvac: (ski: string) => EebusHvacClient;
 }

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

@@ -6,11 +6,13 @@ export { EebusDeviceManagement } from './eebus-device-management.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 { 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';
 /**
  * Interface for EEbus (SHIP/SPINE) device communication in enyo packages.
  *
@@ -18,7 +20,7 @@ export { EebusOhpcfClient } from './eebus-ohpcf-client.cjs';
  *
  * - {@link devices} — SHIP-level device lifecycle: discovery, pairing, connection
  * - {@link identity} — NID: observable per-node identity, diagnosis state, use-case discovery
- * - {@link useCases} — typed use-case clients: LPC, LPP, MGCP, MPC, OHPCF
+ * - {@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
  *
  * Dual roles (Energy Management System vs Controllable System) are modelled at

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

@@ -1,50 +1,74 @@
-import { EnyoNotification, EnyoNotificationOptions, EnyoNotificationTranslation, EnyoNotificationType } from "../types/enyo-notification.cjs";
+import { EnyoNotificationCategory, EnyoNotificationCategoryRegistration, EnyoNotificationOptions, EnyoNotificationTranslation } from "../types/enyo-notification.cjs";
 /**
  * Interface for managing user notifications within Energy App packages.
- * Provides methods to show, retrieve, and manage notifications with multi-language support.
+ *
+ * Notifications are grouped by {@link EnyoNotificationCategory}. Every
+ * category that a package intends to use must first be registered with the
+ * host via {@link registerNotificationCategory}; attempts to send a
+ * notification for an unregistered category fail with a `not-registered`
+ * error.
+ *
+ * The host may additionally enforce rate limits per category. When the limit
+ * is exceeded, {@link sendNotification} fails with a `rate-limit` error and
+ * the caller must back off before retrying.
  */
 export interface EnergyAppNotification {
     /**
-     * Shows a notification to the user with multi-language support.
-     * The notification will be displayed according to the specified type and options.
+     * Registers a notification category with the host.
+     *
+     * Categories must be registered before any notification using that
+     * category can be sent. Registration is idempotent: calling it again for
+     * the same category updates the translated `name` and `description` used
+     * by the host UI.
      *
-     * @param type - The type of notification (info, warning, error, success) determining visual style
-     * @param options - Configuration options including permanence, expiration, priority, and appliance association
-     * @param translations - Array of translated notification messages for different supported languages
-     * @returns Unique notification ID that can be used for tracking and removal
+     * @param registration - Category identifier together with the translated
+     *   `name` (and optional `description`) shown by the host.
      *
      * @example
      * ```typescript
-     * const notificationId = showNotification('warning',
-     *   { permanent: true, priority: 'high' },
-     *   [
-     *     { language: 'en', notification: 'Battery level is low' },
-     *     { language: 'de', notification: 'Batteriestand ist niedrig' }
+     * registerNotificationCategory({
+     *   category: 'connection-issue',
+     *   name: [
+     *     { language: 'en', name: 'Connection issue' },
+     *     { language: 'de', name: 'Verbindungsproblem' }
      *   ]
-     * );
+     * });
      * ```
      */
-    showNotification(type: EnyoNotificationType, options: EnyoNotificationOptions, translations: EnyoNotificationTranslation[]): string;
+    registerNotificationCategory(registration: EnyoNotificationCategoryRegistration): void;
     /**
-     * Retrieves all currently active notifications.
-     * Returns notifications in chronological order (newest first) unless sorted by priority.
+     * Shows a notification to the user with multi-language support.
      *
-     * @param applianceId - Optional appliance ID to filter notifications for a specific appliance
-     * @returns Array of all current notifications with complete metadata
-     */
-    getNotifications(applianceId?: string): EnyoNotification[];
-    /**
-     * Removes a specific notification from the active notification list.
-     * If the notification doesn't exist, this method completes silently.
+     * The notification's `category` must have been registered first via
+     * {@link registerNotificationCategory}. Each translation supplies both a
+     * `title` (used for list rows and system banners) and a `body` (used in
+     * the expanded detail view). When `options.target` is provided, the host
+     * routes the user to that destination on interaction — e.g. an onboarding
+     * guide for the `onboarding-required` category.
      *
-     * @param notificationId - The unique ID of the notification to remove
-     */
-    removeNotification(notificationId: string): void;
-    /**
-     * Removes all active notifications.
-     * This is a convenience method for clearing the entire notification queue.
+     * @param type - Visual style of the notification (info, warning, error, success).
+     * @param category - Lifecycle category; must be registered beforehand.
+     * @param options - Display/behavior options, including optional routing target.
+     * @param translations - Per-language `title`/`body` pairs.
+     * @returns Unique notification ID that can be used for tracking and removal.
+     * @throws {EnyoNotificationSendError} `not-registered` if the supplied
+     *   category has not been registered with the host.
+     * @throws {EnyoNotificationSendError} `rate-limit` if the host's
+     *   notification rate limit for this category has been exceeded.
      *
-     * @param applianceId - Optional appliance ID to clear only notifications for a specific appliance
+     * @example
+     * ```typescript
+     * const notificationId = sendNotification(
+     *   'onboarding-required',
+     *   {
+     *     target: { type: 'onboarding', onboardingName: 'wallbox-setup' }
+     *   },
+     *   [
+     *     { language: 'en', title: 'Finish setup', body: 'Complete wallbox onboarding to start charging.' },
+     *     { language: 'de', title: 'Einrichtung abschließen', body: 'Schließe das Wallbox-Onboarding ab, um zu laden.' }
+     *   ]
+     * );
+     * ```
      */
-    clearAllNotifications(applianceId?: string): void;
+    sendNotification(category: EnyoNotificationCategory, options: EnyoNotificationOptions, translations: EnyoNotificationTranslation[]): string;
 }

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

@@ -60,7 +60,7 @@ var EnyoApplianceTopologyFeatureEnum;
     /** If the meter is an Intermediate Meter (like the meter of an Inverter) directly behind the Primary Meter */
     EnyoApplianceTopologyFeatureEnum["IntermediateOfPrimaryMeter"] = "IntermediateOfPrimaryMeter";
     /** If the meter is an Intermediate Meter for a single appliance */
-    EnyoApplianceTopologyFeatureEnum["IntermediateMeter"] = "PrimaryMeter";
+    EnyoApplianceTopologyFeatureEnum["IntermediateMeter"] = "IntermediateMeter";
     /** If the inverter does a direct grid feed in without self consumption */
     EnyoApplianceTopologyFeatureEnum["InverterFullGridFeedIn"] = "InverterFullGridFeedIn";
 })(EnyoApplianceTopologyFeatureEnum || (exports.EnyoApplianceTopologyFeatureEnum = EnyoApplianceTopologyFeatureEnum = {}));

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

@@ -136,7 +136,7 @@ export declare enum EnyoApplianceTopologyFeatureEnum {
     /** If the meter is an Intermediate Meter (like the meter of an Inverter) directly behind the Primary Meter */
     IntermediateOfPrimaryMeter = "IntermediateOfPrimaryMeter",
     /** If the meter is an Intermediate Meter for a single appliance */
-    IntermediateMeter = "PrimaryMeter",
+    IntermediateMeter = "IntermediateMeter",
     /** If the inverter does a direct grid feed in without self consumption */
     InverterFullGridFeedIn = "InverterFullGridFeedIn"
 }
@@ -144,6 +144,8 @@ export interface EnyoApplianceTopology {
     features: EnyoApplianceTopologyFeatureEnum[];
     /** Information, behind which meter this appliance is located, for example if the wallbox is behind the primary meter or a submeter. Put the appliance ID of the meter */
     behindMeterApplianceId?: string;
+    /** Information, in front of which appliance this appliance is located (i.e. upstream on the electrical path). Put the appliance ID of the downstream appliance. */
+    inFrontOfApplianceId?: string;
 }
 /**
  * Represents an appliance managed by the enyo system.

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

@@ -1027,6 +1027,12 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
         domesticHotWater?: {
             /** Index of the domestic hot water tank */
             index: number;
+            /**
+             * Human-readable zone name (e.g. the `description` from SPINE
+             * `Identification.identificationListData` for this zone index).
+             * Omit when no identification is available.
+             */
+            name?: string;
             /** Target temperature in Celsius */
             targetTemperatureC: number;
             /** Current temperature in Celsius */
@@ -1038,6 +1044,12 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
         heatingCircuits?: {
             /** Index of the heating circuit */
             index: number;
+            /**
+             * Human-readable zone name (e.g. the `description` from SPINE
+             * `Identification.identificationListData` for this zone index).
+             * Omit when no identification is available.
+             */
+            name?: string;
             /** Target temperature in Celsius */
             targetTemperatureC: number;
             /** Current temperature in Celsius */

package/dist/cjs/types/enyo-eebus-use-cases.d.cts

@@ -185,3 +185,57 @@ export interface EebusOhpcfFlexibility {
     /** Whether the compressor is currently running */
     isRunning: boolean;
 }
+/**
+ * A single setpoint reported or written via the EEBUS **Setpoint** feature.
+ *
+ * Setpoints carry the target value for a controllable parameter on a remote
+ * node — most commonly the per-zone target temperature on a heat pump.
+ * The {@link setpointId} matches the corresponding zone in
+ * `Identification.identificationListData`, so a caller can join setpoints to
+ * human-readable zone names.
+ */
+export interface EebusSetpointValue {
+    /**
+     * Setpoint list identifier. Matches the zone index used by
+     * `Identification.identificationListData`.
+     */
+    setpointId: number;
+    /** Target value (interpret using {@link unit}; e.g. °C for HVAC zones) */
+    value: number;
+    /**
+     * SPINE unit string for {@link value}, e.g. `'Cel'` for Celsius.
+     * Following the SPINE unit catalog.
+     */
+    unit: string;
+    /** Whether the setpoint is currently active on the remote */
+    isActive: boolean;
+}
+/**
+ * A heating/cooling operation mode advertised or selected via the EEBUS
+ * **Hvac** feature. Operation modes are vendor-defined identifiers (e.g.
+ * heating, cooling, auto, standby) accompanied by an optional description.
+ */
+export interface EebusHvacOperationMode {
+    /** SPINE operation mode identifier */
+    modeId: number;
+    /** Human-readable mode description as advertised by the remote */
+    description?: string;
+}
+/**
+ * Per-zone state reported via the EEBUS **Hvac** feature.
+ *
+ * The {@link zoneId} matches the zone index used by
+ * `Identification.identificationListData`, so a caller can join zone state to
+ * human-readable zone names.
+ */
+export interface EebusHvacZoneState {
+    /**
+     * Zone identifier. Matches the zone index used by
+     * `Identification.identificationListData`.
+     */
+    zoneId: number;
+    /** Current measured temperature in Celsius, if reported */
+    currentTemperatureC?: number;
+    /** Active operation mode for this zone, if reported */
+    operationMode?: EebusHvacOperationMode;
+}

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

@@ -1,48 +1,143 @@
 import { EnergyAppPackageLanguage } from "../energy-app-package-definition.cjs";
 /**
- * Types of notifications that can be displayed to users
+ * Lifecycle category of a notification.
+ *
+ * Categories must be registered with the host (via
+ * {@link EnergyAppNotification.registerNotificationCategory}) before any
+ * notification using that category can be sent. This allows the host to
+ * pre-allocate UI surfaces (badges, sections, inbox tabs) and to enforce
+ * per-category rate limits.
+ *
+ * - `connection-issue`: The package has detected a connectivity problem with
+ *   an appliance, gateway, or upstream service that requires user attention.
+ * - `onboarding-required`: The package needs the user to complete (or revisit)
+ *   an onboarding flow before it can continue operating normally.
  */
-export type EnyoNotificationType = 'info' | 'warning' | 'error' | 'success';
+export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required';
 /**
- * Priority levels for notifications affecting display order and importance
+ * Registration payload describing a notification category to the host.
+ *
+ * The host uses the translated `name` and optional `description` to render
+ * the category in user-facing surfaces (settings screens, inbox filters,
+ * etc.) without the package needing to ship per-host UI strings.
  */
-export type EnyoNotificationPriority = 'low' | 'normal' | 'high';
+export interface EnyoNotificationCategoryRegistration {
+    /** Category identifier this registration applies to. */
+    category: EnyoNotificationCategory;
+    /** Translated, human-readable name of the category. */
+    name: EnyoNotificationCategoryTranslation[];
+    /** Optional translated description shown alongside the category name. */
+    description?: EnyoNotificationCategoryTranslation[];
+}
+/**
+ * Translated label for a notification category, used during registration.
+ */
+export interface EnyoNotificationCategoryTranslation {
+    /** Language code for this translation. */
+    language: EnergyAppPackageLanguage;
+    /** Display name of the category in the given language. */
+    name: string;
+    /** Optional description of the category in the given language. */
+    description?: string;
+}
 /**
- * Configuration options for notification display and behavior
+ * Target object describing an in-app destination the user is routed to when
+ * they interact with a notification. Discriminated by the `type` field so
+ * additional target kinds can be added without breaking existing consumers.
+ */
+export type EnyoNotificationTarget = EnyoNotificationOnboardingTarget | EnyoNotificationEnergyAppSettingsTarget | EnyoNotificationApplianceSettingsTarget;
+/**
+ * Target that opens an onboarding guide previously registered with the host.
+ *
+ * Use this for notifications whose category is `onboarding-required` (or any
+ * other case where the resolution is "walk the user through onboarding").
+ */
+export interface EnyoNotificationOnboardingTarget {
+    /** Discriminator identifying this as an onboarding target. */
+    type: 'onboarding';
+    /**
+     * Name of the onboarding guide to open. Must match the `guideName` of a
+     * guide previously registered via the onboarding package.
+     */
+    onboardingName: string;
+}
+/**
+ * Target that opens the settings screen for the energy app package itself
+ * (package-wide settings registered via the settings package, not scoped to
+ * a specific appliance).
+ */
+export interface EnyoNotificationEnergyAppSettingsTarget {
+    /** Discriminator identifying this as an energy app settings target. */
+    type: 'energy-app-settings';
+}
+/**
+ * Target that opens the settings screen for a specific appliance managed by
+ * the energy app package.
+ */
+export interface EnyoNotificationApplianceSettingsTarget {
+    /** Discriminator identifying this as an appliance settings target. */
+    type: 'appliance-settings';
+    /**
+     * Identifier of the appliance whose settings should be opened. Must match
+     * an appliance id known to the host.
+     */
+    applianceId: string;
+}
+/**
+ * Configuration options for notification display and behavior.
  */
 export interface EnyoNotificationOptions {
-    /** Whether the notification persists until manually dismissed by the user */
-    permanent?: boolean;
-    /** Optional expiration time in ISO format for auto-dismissal */
-    expiresAtIso?: string;
-    /** Priority level affecting display order and visual emphasis */
-    priority?: EnyoNotificationPriority;
-    /** Optional appliance ID if notification is specific to an appliance */
+    /** Optional appliance ID if notification is specific to an appliance. */
     applianceId?: string;
+    /**
+     * Optional in-app destination the user is routed to when they interact
+     * with the notification.
+     */
+    target?: EnyoNotificationTarget;
 }
 /**
- * Translated notification content for multi-language support
+ * Translated notification content for multi-language support.
+ *
+ * Each translation provides both a short `title` (shown in lists, headers
+ * and system notifications) and a longer `body` (shown in the expanded
+ * detail view).
  */
 export interface EnyoNotificationTranslation {
-    /** Language code for this translation */
+    /** Language code for this translation. */
     language: EnergyAppPackageLanguage;
-    /** Notification message content in the specified language */
-    notification: string;
+    /** Short headline shown in notification lists and system banners. */
+    title: string;
+    /** Longer message body shown when the notification is expanded. */
+    body: string;
+}
+/**
+ * Error reasons returned by {@link EnergyAppNotification.sendNotification}
+ * when a notification cannot be delivered.
+ *
+ * - `not-registered`: The supplied category has not been registered with the
+ *   host via {@link EnergyAppNotification.registerNotificationCategory}.
+ * - `rate-limit`: The package has exceeded the host's notification rate
+ *   limit for the supplied category and must back off before retrying.
+ */
+export type EnyoNotificationSendErrorType = 'not-registered' | 'rate-limit';
+/**
+ * Error thrown or returned by {@link EnergyAppNotification.sendNotification}
+ * when a notification cannot be delivered.
+ */
+export interface EnyoNotificationSendError {
+    /** Machine-readable error reason. */
+    type: EnyoNotificationSendErrorType;
+    /** Optional human-readable detail describing the error. */
+    message?: string;
 }
 /**
- * Complete notification object containing all notification data
+ * Complete notification object containing all notification data.
  */
 export interface EnyoNotification {
-    /** Unique identifier for this notification */
-    id: string;
-    /** Type of notification determining visual style and urgency */
-    type: EnyoNotificationType;
-    /** Configuration options for display and behavior */
+    /** Category of the notification; must be registered before sending. */
+    category: EnyoNotificationCategory;
+    /** Configuration options for display and behavior. */
     options: EnyoNotificationOptions;
-    /** Array of translated notification messages for different languages */
+    /** Array of translated notification messages for different languages. */
     translations: EnyoNotificationTranslation[];
-    /** ISO timestamp when the notification was created */
-    createdAtIso: string;
-    /** Optional ISO timestamp when the notification was last updated */
-    updatedAtIso?: string;
 }

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

package/dist/packages/eebus/eebus-hvac-client.d.ts

@@ -0,0 +1,61 @@
+import { EebusHvacOperationMode, EebusHvacZoneState } from '../../types/enyo-eebus-use-cases.js';
+/**
+ * Client for the EEBUS **Hvac** feature.
+ *
+ * The Hvac feature reports heating/cooling operation mode and per-zone state
+ * (current temperature, active mode). Pair with the
+ * {@link EebusSetpointClient} Setpoint feature to read or write target values.
+ * Zone ids align with `Identification.identificationListData`, so callers can
+ * map zone state to human-readable zone names.
+ *
+ * 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}
+ *
+ * Consumers that only act in one role simply never call the other half — there
+ * is no `asManager` / `asAppliance` split.
+ */
+export interface EebusHvacClient {
+    /**
+     * Read the active heating/cooling operation mode from the remote node.
+     */
+    getOperationMode: () => Promise<EebusHvacOperationMode>;
+    /**
+     * Request the remote node to switch to the given operation mode. The
+     * remote may reject modes it does not advertise — verify support via
+     * `EebusIdentityService.getSupportedUseCases` before calling.
+     * @param mode The operation mode to select on the remote
+     */
+    setOperationMode: (mode: EebusHvacOperationMode) => Promise<void>;
+    /**
+     * Read per-zone Hvac state (current temperature, active mode) from the
+     * remote node.
+     * @returns The state of each zone reported by the remote.
+     */
+    getZoneStates: () => Promise<EebusHvacZoneState[]>;
+    /**
+     * Subscribe to per-zone Hvac state updates. The listener fires once per
+     * zone whenever the remote republishes its state.
+     * @param listener Callback invoked with the updated zone state
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onZoneStateChanged: (listener: (state: EebusHvacZoneState) => void) => string;
+    /**
+     * Register a provider that supplies this device's current operation mode
+     * when a remote EMS reads it.
+     * @param provider Async callback returning the active operation mode
+     */
+    provideOperationMode: (provider: () => Promise<EebusHvacOperationMode>) => void;
+    /**
+     * Register a provider that supplies this device's current per-zone state
+     * when a remote EMS reads it.
+     * @param provider Async callback returning the current zone-state list
+     */
+    provideZoneStates: (provider: () => Promise<EebusHvacZoneState[]>) => void;
+    /**
+     * Remove a listener previously registered via {@link onZoneStateChanged}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

package/dist/packages/eebus/eebus-hvac-client.js

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

package/dist/packages/eebus/eebus-setpoint-client.d.ts

@@ -0,0 +1,59 @@
+import { EebusSetpointValue } from '../../types/enyo-eebus-use-cases.js';
+/**
+ * Client for the EEBUS **Setpoint** feature.
+ *
+ * The Setpoint feature carries the target value(s) of a controllable
+ * parameter on a remote node — most commonly the per-zone target temperature
+ * on a heat pump (paired with the {@link EebusHvacClient} Hvac feature for
+ * measured values). Setpoint ids align with the zone ids reported by
+ * `Identification.identificationListData`, so callers can map setpoints to
+ * human-readable zone names.
+ *
+ * The client exposes both actor roles on a single interface:
+ * - **EMS role (outbound):** {@link getSetpoints}, {@link setSetpoint},
+ *   {@link onSetpointsChanged}
+ * - **CS role (inbound):** {@link provideSetpoints}, {@link onSetpointReceived}
+ *
+ * Consumers that only act in one role simply never call the other half — there
+ * is no `asManager` / `asAppliance` split.
+ */
+export interface EebusSetpointClient {
+    /**
+     * Read the current setpoints reported by the remote node.
+     * @returns The full list of setpoints currently published by the remote.
+     */
+    getSetpoints: () => Promise<EebusSetpointValue[]>;
+    /**
+     * Send a setpoint to the remote node. The remote applies the value to the
+     * setpoint identified by {@link EebusSetpointValue.setpointId}; existing
+     * setpoints at other ids are left unchanged.
+     * @param value The setpoint to apply
+     */
+    setSetpoint: (value: EebusSetpointValue) => Promise<void>;
+    /**
+     * Subscribe to setpoint-list updates from the remote node. The listener is
+     * invoked with the full current list whenever the remote republishes.
+     * @param listener Callback invoked with the new setpoint list
+     * @returns Listener ID that can be passed to {@link removeListener} to cancel
+     */
+    onSetpointsChanged: (listener: (values: EebusSetpointValue[]) => void) => string;
+    /**
+     * Register a provider that supplies this device's current setpoints when a
+     * remote EMS reads them.
+     * @param provider Async callback returning the current setpoint list
+     */
+    provideSetpoints: (provider: () => Promise<EebusSetpointValue[]>) => void;
+    /**
+     * Register a handler invoked when a remote EMS writes a setpoint to this
+     * device. Implementations should apply the value to the local controller.
+     * @param handler Callback invoked with the incoming setpoint
+     * @returns Listener ID that can be passed to {@link removeListener} to deregister
+     */
+    onSetpointReceived: (handler: (value: EebusSetpointValue) => Promise<void>) => string;
+    /**
+     * Remove a listener previously registered via {@link onSetpointsChanged} or
+     * {@link onSetpointReceived}.
+     * @param listenerId The ID returned by the registration method
+     */
+    removeListener: (listenerId: string) => void;
+}

package/dist/packages/eebus/eebus-setpoint-client.js

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

package/dist/packages/eebus/eebus-use-case-registry.d.ts

@@ -1,8 +1,10 @@
+import { EebusHvacClient } from './eebus-hvac-client.js';
 import { EebusLpcClient } from './eebus-lpc-client.js';
 import { EebusLppClient } from './eebus-lpp-client.js';
 import { EebusMgcpClient } from './eebus-mgcp-client.js';
 import { EebusMpcClient } from './eebus-mpc-client.js';
 import { EebusOhpcfClient } from './eebus-ohpcf-client.js';
+import { EebusSetpointClient } from './eebus-setpoint-client.js';
 /**
  * Registry of typed EEBUS use-case clients, scoped per remote device (SKI).
  *
@@ -69,4 +71,18 @@ export interface EebusUseCaseRegistry {
      * @param ski Subject Key Identifier of the remote node
      */
     ohpcf: (ski: string) => 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
+     */
+    setpoint: (ski: string) => 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
+     */
+    hvac: (ski: string) => EebusHvacClient;
 }

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

@@ -6,11 +6,13 @@ export { EebusDeviceManagement } from './eebus-device-management.js';
 export { EebusIdentityService } from './eebus-identity-service.js';
 export { EebusSpineLowLevel } from './eebus-spine-low-level.js';
 export { EebusUseCaseRegistry } from './eebus-use-case-registry.js';
+export { EebusHvacClient } from './eebus-hvac-client.js';
 export { EebusLpcClient } from './eebus-lpc-client.js';
 export { EebusLppClient } from './eebus-lpp-client.js';
 export { EebusMgcpClient } from './eebus-mgcp-client.js';
 export { EebusMpcClient } from './eebus-mpc-client.js';
 export { EebusOhpcfClient } from './eebus-ohpcf-client.js';
+export { EebusSetpointClient } from './eebus-setpoint-client.js';
 /**
  * Interface for EEbus (SHIP/SPINE) device communication in enyo packages.
  *
@@ -18,7 +20,7 @@ export { EebusOhpcfClient } from './eebus-ohpcf-client.js';
  *
  * - {@link devices} — SHIP-level device lifecycle: discovery, pairing, connection
  * - {@link identity} — NID: observable per-node identity, diagnosis state, use-case discovery
- * - {@link useCases} — typed use-case clients: LPC, LPP, MGCP, MPC, OHPCF
+ * - {@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
  *
  * Dual roles (Energy Management System vs Controllable System) are modelled at

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

@@ -1,50 +1,74 @@
-import { EnyoNotification, EnyoNotificationOptions, EnyoNotificationTranslation, EnyoNotificationType } from "../types/enyo-notification.js";
+import { EnyoNotificationCategory, EnyoNotificationCategoryRegistration, EnyoNotificationOptions, EnyoNotificationTranslation } from "../types/enyo-notification.js";
 /**
  * Interface for managing user notifications within Energy App packages.
- * Provides methods to show, retrieve, and manage notifications with multi-language support.
+ *
+ * Notifications are grouped by {@link EnyoNotificationCategory}. Every
+ * category that a package intends to use must first be registered with the
+ * host via {@link registerNotificationCategory}; attempts to send a
+ * notification for an unregistered category fail with a `not-registered`
+ * error.
+ *
+ * The host may additionally enforce rate limits per category. When the limit
+ * is exceeded, {@link sendNotification} fails with a `rate-limit` error and
+ * the caller must back off before retrying.
  */
 export interface EnergyAppNotification {
     /**
-     * Shows a notification to the user with multi-language support.
-     * The notification will be displayed according to the specified type and options.
+     * Registers a notification category with the host.
+     *
+     * Categories must be registered before any notification using that
+     * category can be sent. Registration is idempotent: calling it again for
+     * the same category updates the translated `name` and `description` used
+     * by the host UI.
      *
-     * @param type - The type of notification (info, warning, error, success) determining visual style
-     * @param options - Configuration options including permanence, expiration, priority, and appliance association
-     * @param translations - Array of translated notification messages for different supported languages
-     * @returns Unique notification ID that can be used for tracking and removal
+     * @param registration - Category identifier together with the translated
+     *   `name` (and optional `description`) shown by the host.
      *
      * @example
      * ```typescript
-     * const notificationId = showNotification('warning',
-     *   { permanent: true, priority: 'high' },
-     *   [
-     *     { language: 'en', notification: 'Battery level is low' },
-     *     { language: 'de', notification: 'Batteriestand ist niedrig' }
+     * registerNotificationCategory({
+     *   category: 'connection-issue',
+     *   name: [
+     *     { language: 'en', name: 'Connection issue' },
+     *     { language: 'de', name: 'Verbindungsproblem' }
      *   ]
-     * );
+     * });
      * ```
      */
-    showNotification(type: EnyoNotificationType, options: EnyoNotificationOptions, translations: EnyoNotificationTranslation[]): string;
+    registerNotificationCategory(registration: EnyoNotificationCategoryRegistration): void;
     /**
-     * Retrieves all currently active notifications.
-     * Returns notifications in chronological order (newest first) unless sorted by priority.
+     * Shows a notification to the user with multi-language support.
      *
-     * @param applianceId - Optional appliance ID to filter notifications for a specific appliance
-     * @returns Array of all current notifications with complete metadata
-     */
-    getNotifications(applianceId?: string): EnyoNotification[];
-    /**
-     * Removes a specific notification from the active notification list.
-     * If the notification doesn't exist, this method completes silently.
+     * The notification's `category` must have been registered first via
+     * {@link registerNotificationCategory}. Each translation supplies both a
+     * `title` (used for list rows and system banners) and a `body` (used in
+     * the expanded detail view). When `options.target` is provided, the host
+     * routes the user to that destination on interaction — e.g. an onboarding
+     * guide for the `onboarding-required` category.
      *
-     * @param notificationId - The unique ID of the notification to remove
-     */
-    removeNotification(notificationId: string): void;
-    /**
-     * Removes all active notifications.
-     * This is a convenience method for clearing the entire notification queue.
+     * @param type - Visual style of the notification (info, warning, error, success).
+     * @param category - Lifecycle category; must be registered beforehand.
+     * @param options - Display/behavior options, including optional routing target.
+     * @param translations - Per-language `title`/`body` pairs.
+     * @returns Unique notification ID that can be used for tracking and removal.
+     * @throws {EnyoNotificationSendError} `not-registered` if the supplied
+     *   category has not been registered with the host.
+     * @throws {EnyoNotificationSendError} `rate-limit` if the host's
+     *   notification rate limit for this category has been exceeded.
      *
-     * @param applianceId - Optional appliance ID to clear only notifications for a specific appliance
+     * @example
+     * ```typescript
+     * const notificationId = sendNotification(
+     *   'onboarding-required',
+     *   {
+     *     target: { type: 'onboarding', onboardingName: 'wallbox-setup' }
+     *   },
+     *   [
+     *     { language: 'en', title: 'Finish setup', body: 'Complete wallbox onboarding to start charging.' },
+     *     { language: 'de', title: 'Einrichtung abschließen', body: 'Schließe das Wallbox-Onboarding ab, um zu laden.' }
+     *   ]
+     * );
+     * ```
      */
-    clearAllNotifications(applianceId?: string): void;
+    sendNotification(category: EnyoNotificationCategory, options: EnyoNotificationOptions, translations: EnyoNotificationTranslation[]): string;
 }

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

@@ -136,7 +136,7 @@ export declare enum EnyoApplianceTopologyFeatureEnum {
     /** If the meter is an Intermediate Meter (like the meter of an Inverter) directly behind the Primary Meter */
     IntermediateOfPrimaryMeter = "IntermediateOfPrimaryMeter",
     /** If the meter is an Intermediate Meter for a single appliance */
-    IntermediateMeter = "PrimaryMeter",
+    IntermediateMeter = "IntermediateMeter",
     /** If the inverter does a direct grid feed in without self consumption */
     InverterFullGridFeedIn = "InverterFullGridFeedIn"
 }
@@ -144,6 +144,8 @@ export interface EnyoApplianceTopology {
     features: EnyoApplianceTopologyFeatureEnum[];
     /** Information, behind which meter this appliance is located, for example if the wallbox is behind the primary meter or a submeter. Put the appliance ID of the meter */
     behindMeterApplianceId?: string;
+    /** Information, in front of which appliance this appliance is located (i.e. upstream on the electrical path). Put the appliance ID of the downstream appliance. */
+    inFrontOfApplianceId?: string;
 }
 /**
  * Represents an appliance managed by the enyo system.

package/dist/types/enyo-appliance.js

@@ -57,7 +57,7 @@ export var EnyoApplianceTopologyFeatureEnum;
     /** If the meter is an Intermediate Meter (like the meter of an Inverter) directly behind the Primary Meter */
     EnyoApplianceTopologyFeatureEnum["IntermediateOfPrimaryMeter"] = "IntermediateOfPrimaryMeter";
     /** If the meter is an Intermediate Meter for a single appliance */
-    EnyoApplianceTopologyFeatureEnum["IntermediateMeter"] = "PrimaryMeter";
+    EnyoApplianceTopologyFeatureEnum["IntermediateMeter"] = "IntermediateMeter";
     /** If the inverter does a direct grid feed in without self consumption */
     EnyoApplianceTopologyFeatureEnum["InverterFullGridFeedIn"] = "InverterFullGridFeedIn";
 })(EnyoApplianceTopologyFeatureEnum || (EnyoApplianceTopologyFeatureEnum = {}));

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

@@ -1027,6 +1027,12 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
         domesticHotWater?: {
             /** Index of the domestic hot water tank */
             index: number;
+            /**
+             * Human-readable zone name (e.g. the `description` from SPINE
+             * `Identification.identificationListData` for this zone index).
+             * Omit when no identification is available.
+             */
+            name?: string;
             /** Target temperature in Celsius */
             targetTemperatureC: number;
             /** Current temperature in Celsius */
@@ -1038,6 +1044,12 @@ export interface EnyoDataBusHeatpumpTemperaturesV1 extends EnyoDataBusMessage {
         heatingCircuits?: {
             /** Index of the heating circuit */
             index: number;
+            /**
+             * Human-readable zone name (e.g. the `description` from SPINE
+             * `Identification.identificationListData` for this zone index).
+             * Omit when no identification is available.
+             */
+            name?: string;
             /** Target temperature in Celsius */
             targetTemperatureC: number;
             /** Current temperature in Celsius */

package/dist/types/enyo-eebus-use-cases.d.ts

@@ -185,3 +185,57 @@ export interface EebusOhpcfFlexibility {
     /** Whether the compressor is currently running */
     isRunning: boolean;
 }
+/**
+ * A single setpoint reported or written via the EEBUS **Setpoint** feature.
+ *
+ * Setpoints carry the target value for a controllable parameter on a remote
+ * node — most commonly the per-zone target temperature on a heat pump.
+ * The {@link setpointId} matches the corresponding zone in
+ * `Identification.identificationListData`, so a caller can join setpoints to
+ * human-readable zone names.
+ */
+export interface EebusSetpointValue {
+    /**
+     * Setpoint list identifier. Matches the zone index used by
+     * `Identification.identificationListData`.
+     */
+    setpointId: number;
+    /** Target value (interpret using {@link unit}; e.g. °C for HVAC zones) */
+    value: number;
+    /**
+     * SPINE unit string for {@link value}, e.g. `'Cel'` for Celsius.
+     * Following the SPINE unit catalog.
+     */
+    unit: string;
+    /** Whether the setpoint is currently active on the remote */
+    isActive: boolean;
+}
+/**
+ * A heating/cooling operation mode advertised or selected via the EEBUS
+ * **Hvac** feature. Operation modes are vendor-defined identifiers (e.g.
+ * heating, cooling, auto, standby) accompanied by an optional description.
+ */
+export interface EebusHvacOperationMode {
+    /** SPINE operation mode identifier */
+    modeId: number;
+    /** Human-readable mode description as advertised by the remote */
+    description?: string;
+}
+/**
+ * Per-zone state reported via the EEBUS **Hvac** feature.
+ *
+ * The {@link zoneId} matches the zone index used by
+ * `Identification.identificationListData`, so a caller can join zone state to
+ * human-readable zone names.
+ */
+export interface EebusHvacZoneState {
+    /**
+     * Zone identifier. Matches the zone index used by
+     * `Identification.identificationListData`.
+     */
+    zoneId: number;
+    /** Current measured temperature in Celsius, if reported */
+    currentTemperatureC?: number;
+    /** Active operation mode for this zone, if reported */
+    operationMode?: EebusHvacOperationMode;
+}

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

@@ -1,48 +1,143 @@
 import { EnergyAppPackageLanguage } from "../energy-app-package-definition.js";
 /**
- * Types of notifications that can be displayed to users
+ * Lifecycle category of a notification.
+ *
+ * Categories must be registered with the host (via
+ * {@link EnergyAppNotification.registerNotificationCategory}) before any
+ * notification using that category can be sent. This allows the host to
+ * pre-allocate UI surfaces (badges, sections, inbox tabs) and to enforce
+ * per-category rate limits.
+ *
+ * - `connection-issue`: The package has detected a connectivity problem with
+ *   an appliance, gateway, or upstream service that requires user attention.
+ * - `onboarding-required`: The package needs the user to complete (or revisit)
+ *   an onboarding flow before it can continue operating normally.
  */
-export type EnyoNotificationType = 'info' | 'warning' | 'error' | 'success';
+export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required';
 /**
- * Priority levels for notifications affecting display order and importance
+ * Registration payload describing a notification category to the host.
+ *
+ * The host uses the translated `name` and optional `description` to render
+ * the category in user-facing surfaces (settings screens, inbox filters,
+ * etc.) without the package needing to ship per-host UI strings.
  */
-export type EnyoNotificationPriority = 'low' | 'normal' | 'high';
+export interface EnyoNotificationCategoryRegistration {
+    /** Category identifier this registration applies to. */
+    category: EnyoNotificationCategory;
+    /** Translated, human-readable name of the category. */
+    name: EnyoNotificationCategoryTranslation[];
+    /** Optional translated description shown alongside the category name. */
+    description?: EnyoNotificationCategoryTranslation[];
+}
+/**
+ * Translated label for a notification category, used during registration.
+ */
+export interface EnyoNotificationCategoryTranslation {
+    /** Language code for this translation. */
+    language: EnergyAppPackageLanguage;
+    /** Display name of the category in the given language. */
+    name: string;
+    /** Optional description of the category in the given language. */
+    description?: string;
+}
 /**
- * Configuration options for notification display and behavior
+ * Target object describing an in-app destination the user is routed to when
+ * they interact with a notification. Discriminated by the `type` field so
+ * additional target kinds can be added without breaking existing consumers.
+ */
+export type EnyoNotificationTarget = EnyoNotificationOnboardingTarget | EnyoNotificationEnergyAppSettingsTarget | EnyoNotificationApplianceSettingsTarget;
+/**
+ * Target that opens an onboarding guide previously registered with the host.
+ *
+ * Use this for notifications whose category is `onboarding-required` (or any
+ * other case where the resolution is "walk the user through onboarding").
+ */
+export interface EnyoNotificationOnboardingTarget {
+    /** Discriminator identifying this as an onboarding target. */
+    type: 'onboarding';
+    /**
+     * Name of the onboarding guide to open. Must match the `guideName` of a
+     * guide previously registered via the onboarding package.
+     */
+    onboardingName: string;
+}
+/**
+ * Target that opens the settings screen for the energy app package itself
+ * (package-wide settings registered via the settings package, not scoped to
+ * a specific appliance).
+ */
+export interface EnyoNotificationEnergyAppSettingsTarget {
+    /** Discriminator identifying this as an energy app settings target. */
+    type: 'energy-app-settings';
+}
+/**
+ * Target that opens the settings screen for a specific appliance managed by
+ * the energy app package.
+ */
+export interface EnyoNotificationApplianceSettingsTarget {
+    /** Discriminator identifying this as an appliance settings target. */
+    type: 'appliance-settings';
+    /**
+     * Identifier of the appliance whose settings should be opened. Must match
+     * an appliance id known to the host.
+     */
+    applianceId: string;
+}
+/**
+ * Configuration options for notification display and behavior.
  */
 export interface EnyoNotificationOptions {
-    /** Whether the notification persists until manually dismissed by the user */
-    permanent?: boolean;
-    /** Optional expiration time in ISO format for auto-dismissal */
-    expiresAtIso?: string;
-    /** Priority level affecting display order and visual emphasis */
-    priority?: EnyoNotificationPriority;
-    /** Optional appliance ID if notification is specific to an appliance */
+    /** Optional appliance ID if notification is specific to an appliance. */
     applianceId?: string;
+    /**
+     * Optional in-app destination the user is routed to when they interact
+     * with the notification.
+     */
+    target?: EnyoNotificationTarget;
 }
 /**
- * Translated notification content for multi-language support
+ * Translated notification content for multi-language support.
+ *
+ * Each translation provides both a short `title` (shown in lists, headers
+ * and system notifications) and a longer `body` (shown in the expanded
+ * detail view).
  */
 export interface EnyoNotificationTranslation {
-    /** Language code for this translation */
+    /** Language code for this translation. */
     language: EnergyAppPackageLanguage;
-    /** Notification message content in the specified language */
-    notification: string;
+    /** Short headline shown in notification lists and system banners. */
+    title: string;
+    /** Longer message body shown when the notification is expanded. */
+    body: string;
+}
+/**
+ * Error reasons returned by {@link EnergyAppNotification.sendNotification}
+ * when a notification cannot be delivered.
+ *
+ * - `not-registered`: The supplied category has not been registered with the
+ *   host via {@link EnergyAppNotification.registerNotificationCategory}.
+ * - `rate-limit`: The package has exceeded the host's notification rate
+ *   limit for the supplied category and must back off before retrying.
+ */
+export type EnyoNotificationSendErrorType = 'not-registered' | 'rate-limit';
+/**
+ * Error thrown or returned by {@link EnergyAppNotification.sendNotification}
+ * when a notification cannot be delivered.
+ */
+export interface EnyoNotificationSendError {
+    /** Machine-readable error reason. */
+    type: EnyoNotificationSendErrorType;
+    /** Optional human-readable detail describing the error. */
+    message?: string;
 }
 /**
- * Complete notification object containing all notification data
+ * Complete notification object containing all notification data.
  */
 export interface EnyoNotification {
-    /** Unique identifier for this notification */
-    id: string;
-    /** Type of notification determining visual style and urgency */
-    type: EnyoNotificationType;
-    /** Configuration options for display and behavior */
+    /** Category of the notification; must be registered before sending. */
+    category: EnyoNotificationCategory;
+    /** Configuration options for display and behavior. */
     options: EnyoNotificationOptions;
-    /** Array of translated notification messages for different languages */
+    /** Array of translated notification messages for different languages. */
     translations: EnyoNotificationTranslation[];
-    /** ISO timestamp when the notification was created */
-    createdAtIso: string;
-    /** Optional ISO timestamp when the notification was last updated */
-    updatedAtIso?: string;
 }

package/dist/version.d.ts

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