@enyo-energy/energy-app-sdk 0.0.128 → 0.0.130

package/dist/cjs/integrations/storage-integration-energy-app.cjs

@@ -10,7 +10,10 @@ const enyo_data_bus_value_js_1 = require("../types/enyo-data-bus-value.cjs");
  * Subscribes to:
  *  - `StartStorageGridChargeV1` — start charging the battery from the grid.
  *  - `StopStorageGridChargeV1` — stop grid charging.
+ *  - `StartStorageGridDischargeV1` — start discharging the battery into the grid.
+ *  - `StopStorageGridDischargeV1` — stop grid discharging.
  *  - `SetStorageDischargeLimitV1` — set the maximum discharge power.
+ *  - `SetStorageChargeLimitV1` — set the maximum charge power.
  *  - `GridOperatorPowerLimitationV1` — §14a EnWG broadcast (handled in base).
  */
 class StorageIntegrationEnergyApp extends integration_energy_app_js_1.IntegrationEnergyApp {
@@ -26,7 +29,10 @@ class StorageIntegrationEnergyApp extends integration_energy_app_js_1.Integratio
     registerHandlers() {
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartStorageGridChargeV1, (m) => this.handleStartStorageGridCharge(m));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopStorageGridChargeV1, (m) => this.handleStopStorageGridCharge(m));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StartStorageGridDischargeV1, (m) => this.handleStartStorageGridDischarge(m));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.StopStorageGridDischargeV1, (m) => this.handleStopStorageGridDischarge(m));
         this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageDischargeLimitV1, (m) => this.handleSetStorageDischargeLimit(m));
+        this.registerCommandHandler(enyo_data_bus_value_js_1.EnyoDataBusMessageEnum.SetStorageChargeLimitV1, (m) => this.handleSetStorageChargeLimit(m));
     }
     /**
      * Publishes a `BatteryValuesUpdateV1` message with the battery's current

package/dist/cjs/integrations/storage-integration-energy-app.d.cts

@@ -1,14 +1,17 @@
 import { IntegrationEnergyApp } from "./integration-energy-app.cjs";
 import { IntegrationCommandResponse, IntegrationEnergyAppOptions } from "./integration-types.cjs";
 import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.cjs";
-import { EnyoDataBusBatteryValuesUpdateV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusSetStorageDischargeLimitV1, EnyoDataBusStartStorageGridChargeV1, EnyoDataBusStopStorageGridChargeV1 } from "../types/enyo-data-bus-value.cjs";
+import { EnyoDataBusBatteryValuesUpdateV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusSetStorageChargeLimitV1, EnyoDataBusSetStorageDischargeLimitV1, EnyoDataBusStartStorageGridChargeV1, EnyoDataBusStartStorageGridDischargeV1, EnyoDataBusStopStorageGridChargeV1, EnyoDataBusStopStorageGridDischargeV1 } from "../types/enyo-data-bus-value.cjs";
 /**
  * Abstract base class for battery / storage integrations.
  *
  * Subscribes to:
  *  - `StartStorageGridChargeV1` — start charging the battery from the grid.
  *  - `StopStorageGridChargeV1` — stop grid charging.
+ *  - `StartStorageGridDischargeV1` — start discharging the battery into the grid.
+ *  - `StopStorageGridDischargeV1` — stop grid discharging.
  *  - `SetStorageDischargeLimitV1` — set the maximum discharge power.
+ *  - `SetStorageChargeLimitV1` — set the maximum charge power.
  *  - `GridOperatorPowerLimitationV1` — §14a EnWG broadcast (handled in base).
  */
 export declare abstract class StorageIntegrationEnergyApp extends IntegrationEnergyApp {
@@ -27,11 +30,25 @@ export declare abstract class StorageIntegrationEnergyApp extends IntegrationEne
      * Handles a `StopStorageGridChargeV1` command — end an active grid charge.
      */
     protected abstract handleStopStorageGridCharge(message: EnyoDataBusStopStorageGridChargeV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `StartStorageGridDischargeV1` command — start discharging the
+     * battery into the grid up to `data.powerLimitW`.
+     */
+    protected abstract handleStartStorageGridDischarge(message: EnyoDataBusStartStorageGridDischargeV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `StopStorageGridDischargeV1` command — end an active grid discharge.
+     */
+    protected abstract handleStopStorageGridDischarge(message: EnyoDataBusStopStorageGridDischargeV1): Promise<IntegrationCommandResponse>;
     /**
      * Handles a `SetStorageDischargeLimitV1` command — set the maximum
      * discharge power in watts.
      */
     protected abstract handleSetStorageDischargeLimit(message: EnyoDataBusSetStorageDischargeLimitV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `SetStorageChargeLimitV1` command — set the maximum
+     * charge power in watts.
+     */
+    protected abstract handleSetStorageChargeLimit(message: EnyoDataBusSetStorageChargeLimitV1): Promise<IntegrationCommandResponse>;
     /**
      * @inheritDoc
      */

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-battery-appliance.cjs

@@ -11,9 +11,14 @@ var EnyoBatteryStorageMode;
 })(EnyoBatteryStorageMode || (exports.EnyoBatteryStorageMode = EnyoBatteryStorageMode = {}));
 var EnyoBatteryFeature;
 (function (EnyoBatteryFeature) {
+    /** If the battery supports being charged from the grid */
     EnyoBatteryFeature["GridCharging"] = "grid-charging";
+    /** If the battery supports discharging into the grid */
+    EnyoBatteryFeature["GridDischarging"] = "grid-discharging";
     /** If the battery supports discharge power limitation */
     EnyoBatteryFeature["DischargeLimitation"] = "discharge-limitation";
+    /** If the battery supports charge power limitation */
+    EnyoBatteryFeature["ChargeLimitation"] = "charge-limitation";
     /** If the battery is connected between DC strings and the inverter */
     EnyoBatteryFeature["BetweenDcStringAndInverter"] = "between-dc-string-and-inverter";
 })(EnyoBatteryFeature || (exports.EnyoBatteryFeature = EnyoBatteryFeature = {}));

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

@@ -6,9 +6,14 @@ export declare enum EnyoBatteryStorageMode {
     Unknown = "unknown"
 }
 export declare enum EnyoBatteryFeature {
+    /** If the battery supports being charged from the grid */
     GridCharging = "grid-charging",
+    /** If the battery supports discharging into the grid */
+    GridDischarging = "grid-discharging",
     /** If the battery supports discharge power limitation */
     DischargeLimitation = "discharge-limitation",
+    /** If the battery supports charge power limitation */
+    ChargeLimitation = "charge-limitation",
     /** If the battery is connected between DC strings and the inverter */
     BetweenDcStringAndInverter = "between-dc-string-and-inverter"
 }

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

@@ -139,7 +139,10 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["HeatpumpDhwTemperatureForecastV1"] = "HeatpumpDhwTemperatureForecastV1";
     EnyoDataBusMessageEnum["StartStorageGridChargeV1"] = "StartStorageGridChargeV1";
     EnyoDataBusMessageEnum["StopStorageGridChargeV1"] = "StopStorageGridChargeV1";
+    EnyoDataBusMessageEnum["StartStorageGridDischargeV1"] = "StartStorageGridDischargeV1";
+    EnyoDataBusMessageEnum["StopStorageGridDischargeV1"] = "StopStorageGridDischargeV1";
     EnyoDataBusMessageEnum["SetStorageDischargeLimitV1"] = "SetStorageDischargeLimitV1";
+    EnyoDataBusMessageEnum["SetStorageChargeLimitV1"] = "SetStorageChargeLimitV1";
     EnyoDataBusMessageEnum["SetInverterFeedInLimitV1"] = "SetInverterFeedInLimitV1";
     EnyoDataBusMessageEnum["CommandAcknowledgeV1"] = "CommandAcknowledgeV1";
     EnyoDataBusMessageEnum["TemperatureSensorValuesUpdateV1"] = "TemperatureSensorValuesUpdateV1";

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

@@ -179,7 +179,10 @@ export declare enum EnyoDataBusMessageEnum {
     HeatpumpDhwTemperatureForecastV1 = "HeatpumpDhwTemperatureForecastV1",
     StartStorageGridChargeV1 = "StartStorageGridChargeV1",
     StopStorageGridChargeV1 = "StopStorageGridChargeV1",
+    StartStorageGridDischargeV1 = "StartStorageGridDischargeV1",
+    StopStorageGridDischargeV1 = "StopStorageGridDischargeV1",
     SetStorageDischargeLimitV1 = "SetStorageDischargeLimitV1",
+    SetStorageChargeLimitV1 = "SetStorageChargeLimitV1",
     SetInverterFeedInLimitV1 = "SetInverterFeedInLimitV1",
     CommandAcknowledgeV1 = "CommandAcknowledgeV1",
     TemperatureSensorValuesUpdateV1 = "TemperatureSensorValuesUpdateV1",
@@ -921,6 +924,36 @@ export interface EnyoDataBusStopStorageGridChargeV1 extends EnyoDataBusMessage {
         reason?: EnyoDataBusCommandReason;
     };
 }
+/**
+ * Command message to start discharging a storage/battery into the grid.
+ * Instructs the battery system to begin feeding power into the grid up to the specified limit.
+ */
+export interface EnyoDataBusStartStorageGridDischargeV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.StartStorageGridDischargeV1;
+    /** ID of the battery/storage appliance to discharge */
+    applianceId: string;
+    data: {
+        /** Maximum power in watts for storage-to-grid discharging */
+        powerLimitW: number;
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
+/**
+ * Command message to stop discharging a storage/battery into the grid.
+ * Instructs the battery system to end storage-to-grid discharging.
+ */
+export interface EnyoDataBusStopStorageGridDischargeV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.StopStorageGridDischargeV1;
+    /** ID of the battery/storage appliance to stop discharging */
+    applianceId: string;
+    data: {
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
 /**
  * Command message to limit the discharge rate of a storage/battery.
  * Sets the maximum discharge power as a percentage of the battery's maximum discharge capacity.
@@ -937,6 +970,22 @@ export interface EnyoDataBusSetStorageDischargeLimitV1 extends EnyoDataBusMessag
         reason?: EnyoDataBusCommandReason;
     };
 }
+/**
+ * Command message to limit the charge rate of a storage/battery.
+ * Sets the maximum charge power in watts that the battery is allowed to draw while charging.
+ */
+export interface EnyoDataBusSetStorageChargeLimitV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.SetStorageChargeLimitV1;
+    /** ID of the battery/storage appliance to limit */
+    applianceId: string;
+    data: {
+        /** Charge limit in W to limit the battery's charge power */
+        chargeLimitW: number;
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
 /**
  * Command message to set or reset the inverter's grid feed-in power limit.
  * When a limit is set, the inverter will not feed more than the specified power into the grid.

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

@@ -17,6 +17,8 @@ var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["AvailablePowerAnnouncement"] = "AvailablePowerAnnouncement";
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["Power"] = "Power";
+    /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["ReadyForCalibration"] = "ReadyForCalibration";
 })(EnyoHeatpumpApplianceAvailableFeaturesEnum || (exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = EnyoHeatpumpApplianceAvailableFeaturesEnum = {}));
 var EnyoHeatpumpApplianceModeEnum;
 (function (EnyoHeatpumpApplianceModeEnum) {

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

@@ -12,7 +12,9 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump supports available power announcements */
     AvailablePowerAnnouncement = "AvailablePowerAnnouncement",
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
-    Power = "Power"
+    Power = "Power",
+    /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
+    ReadyForCalibration = "ReadyForCalibration"
 }
 export declare enum EnyoHeatpumpApplianceModeEnum {
     Idle = "Idle",

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

package/dist/integrations/storage-integration-energy-app.d.ts

@@ -1,14 +1,17 @@
 import { IntegrationEnergyApp } from "./integration-energy-app.js";
 import { IntegrationCommandResponse, IntegrationEnergyAppOptions } from "./integration-types.js";
 import { EnyoApplianceTypeEnum } from "../types/enyo-appliance.js";
-import { EnyoDataBusBatteryValuesUpdateV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusSetStorageDischargeLimitV1, EnyoDataBusStartStorageGridChargeV1, EnyoDataBusStopStorageGridChargeV1 } from "../types/enyo-data-bus-value.js";
+import { EnyoDataBusBatteryValuesUpdateV1, EnyoDataBusGridOperatorPowerLimitationV1, EnyoDataBusSetStorageChargeLimitV1, EnyoDataBusSetStorageDischargeLimitV1, EnyoDataBusStartStorageGridChargeV1, EnyoDataBusStartStorageGridDischargeV1, EnyoDataBusStopStorageGridChargeV1, EnyoDataBusStopStorageGridDischargeV1 } from "../types/enyo-data-bus-value.js";
 /**
  * Abstract base class for battery / storage integrations.
  *
  * Subscribes to:
  *  - `StartStorageGridChargeV1` — start charging the battery from the grid.
  *  - `StopStorageGridChargeV1` — stop grid charging.
+ *  - `StartStorageGridDischargeV1` — start discharging the battery into the grid.
+ *  - `StopStorageGridDischargeV1` — stop grid discharging.
  *  - `SetStorageDischargeLimitV1` — set the maximum discharge power.
+ *  - `SetStorageChargeLimitV1` — set the maximum charge power.
  *  - `GridOperatorPowerLimitationV1` — §14a EnWG broadcast (handled in base).
  */
 export declare abstract class StorageIntegrationEnergyApp extends IntegrationEnergyApp {
@@ -27,11 +30,25 @@ export declare abstract class StorageIntegrationEnergyApp extends IntegrationEne
      * Handles a `StopStorageGridChargeV1` command — end an active grid charge.
      */
     protected abstract handleStopStorageGridCharge(message: EnyoDataBusStopStorageGridChargeV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `StartStorageGridDischargeV1` command — start discharging the
+     * battery into the grid up to `data.powerLimitW`.
+     */
+    protected abstract handleStartStorageGridDischarge(message: EnyoDataBusStartStorageGridDischargeV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `StopStorageGridDischargeV1` command — end an active grid discharge.
+     */
+    protected abstract handleStopStorageGridDischarge(message: EnyoDataBusStopStorageGridDischargeV1): Promise<IntegrationCommandResponse>;
     /**
      * Handles a `SetStorageDischargeLimitV1` command — set the maximum
      * discharge power in watts.
      */
     protected abstract handleSetStorageDischargeLimit(message: EnyoDataBusSetStorageDischargeLimitV1): Promise<IntegrationCommandResponse>;
+    /**
+     * Handles a `SetStorageChargeLimitV1` command — set the maximum
+     * charge power in watts.
+     */
+    protected abstract handleSetStorageChargeLimit(message: EnyoDataBusSetStorageChargeLimitV1): Promise<IntegrationCommandResponse>;
     /**
      * @inheritDoc
      */

package/dist/integrations/storage-integration-energy-app.js

@@ -7,7 +7,10 @@ import { EnyoDataBusMessageEnum } from "../types/enyo-data-bus-value.js";
  * Subscribes to:
  *  - `StartStorageGridChargeV1` — start charging the battery from the grid.
  *  - `StopStorageGridChargeV1` — stop grid charging.
+ *  - `StartStorageGridDischargeV1` — start discharging the battery into the grid.
+ *  - `StopStorageGridDischargeV1` — stop grid discharging.
  *  - `SetStorageDischargeLimitV1` — set the maximum discharge power.
+ *  - `SetStorageChargeLimitV1` — set the maximum charge power.
  *  - `GridOperatorPowerLimitationV1` — §14a EnWG broadcast (handled in base).
  */
 export class StorageIntegrationEnergyApp extends IntegrationEnergyApp {
@@ -23,7 +26,10 @@ export class StorageIntegrationEnergyApp extends IntegrationEnergyApp {
     registerHandlers() {
         this.registerCommandHandler(EnyoDataBusMessageEnum.StartStorageGridChargeV1, (m) => this.handleStartStorageGridCharge(m));
         this.registerCommandHandler(EnyoDataBusMessageEnum.StopStorageGridChargeV1, (m) => this.handleStopStorageGridCharge(m));
+        this.registerCommandHandler(EnyoDataBusMessageEnum.StartStorageGridDischargeV1, (m) => this.handleStartStorageGridDischarge(m));
+        this.registerCommandHandler(EnyoDataBusMessageEnum.StopStorageGridDischargeV1, (m) => this.handleStopStorageGridDischarge(m));
         this.registerCommandHandler(EnyoDataBusMessageEnum.SetStorageDischargeLimitV1, (m) => this.handleSetStorageDischargeLimit(m));
+        this.registerCommandHandler(EnyoDataBusMessageEnum.SetStorageChargeLimitV1, (m) => this.handleSetStorageChargeLimit(m));
     }
     /**
      * Publishes a `BatteryValuesUpdateV1` message with the battery's current

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-battery-appliance.d.ts

@@ -6,9 +6,14 @@ export declare enum EnyoBatteryStorageMode {
     Unknown = "unknown"
 }
 export declare enum EnyoBatteryFeature {
+    /** If the battery supports being charged from the grid */
     GridCharging = "grid-charging",
+    /** If the battery supports discharging into the grid */
+    GridDischarging = "grid-discharging",
     /** If the battery supports discharge power limitation */
     DischargeLimitation = "discharge-limitation",
+    /** If the battery supports charge power limitation */
+    ChargeLimitation = "charge-limitation",
     /** If the battery is connected between DC strings and the inverter */
     BetweenDcStringAndInverter = "between-dc-string-and-inverter"
 }

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

@@ -8,9 +8,14 @@ export var EnyoBatteryStorageMode;
 })(EnyoBatteryStorageMode || (EnyoBatteryStorageMode = {}));
 export var EnyoBatteryFeature;
 (function (EnyoBatteryFeature) {
+    /** If the battery supports being charged from the grid */
     EnyoBatteryFeature["GridCharging"] = "grid-charging";
+    /** If the battery supports discharging into the grid */
+    EnyoBatteryFeature["GridDischarging"] = "grid-discharging";
     /** If the battery supports discharge power limitation */
     EnyoBatteryFeature["DischargeLimitation"] = "discharge-limitation";
+    /** If the battery supports charge power limitation */
+    EnyoBatteryFeature["ChargeLimitation"] = "charge-limitation";
     /** If the battery is connected between DC strings and the inverter */
     EnyoBatteryFeature["BetweenDcStringAndInverter"] = "between-dc-string-and-inverter";
 })(EnyoBatteryFeature || (EnyoBatteryFeature = {}));

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

@@ -179,7 +179,10 @@ export declare enum EnyoDataBusMessageEnum {
     HeatpumpDhwTemperatureForecastV1 = "HeatpumpDhwTemperatureForecastV1",
     StartStorageGridChargeV1 = "StartStorageGridChargeV1",
     StopStorageGridChargeV1 = "StopStorageGridChargeV1",
+    StartStorageGridDischargeV1 = "StartStorageGridDischargeV1",
+    StopStorageGridDischargeV1 = "StopStorageGridDischargeV1",
     SetStorageDischargeLimitV1 = "SetStorageDischargeLimitV1",
+    SetStorageChargeLimitV1 = "SetStorageChargeLimitV1",
     SetInverterFeedInLimitV1 = "SetInverterFeedInLimitV1",
     CommandAcknowledgeV1 = "CommandAcknowledgeV1",
     TemperatureSensorValuesUpdateV1 = "TemperatureSensorValuesUpdateV1",
@@ -921,6 +924,36 @@ export interface EnyoDataBusStopStorageGridChargeV1 extends EnyoDataBusMessage {
         reason?: EnyoDataBusCommandReason;
     };
 }
+/**
+ * Command message to start discharging a storage/battery into the grid.
+ * Instructs the battery system to begin feeding power into the grid up to the specified limit.
+ */
+export interface EnyoDataBusStartStorageGridDischargeV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.StartStorageGridDischargeV1;
+    /** ID of the battery/storage appliance to discharge */
+    applianceId: string;
+    data: {
+        /** Maximum power in watts for storage-to-grid discharging */
+        powerLimitW: number;
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
+/**
+ * Command message to stop discharging a storage/battery into the grid.
+ * Instructs the battery system to end storage-to-grid discharging.
+ */
+export interface EnyoDataBusStopStorageGridDischargeV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.StopStorageGridDischargeV1;
+    /** ID of the battery/storage appliance to stop discharging */
+    applianceId: string;
+    data: {
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
 /**
  * Command message to limit the discharge rate of a storage/battery.
  * Sets the maximum discharge power as a percentage of the battery's maximum discharge capacity.
@@ -937,6 +970,22 @@ export interface EnyoDataBusSetStorageDischargeLimitV1 extends EnyoDataBusMessag
         reason?: EnyoDataBusCommandReason;
     };
 }
+/**
+ * Command message to limit the charge rate of a storage/battery.
+ * Sets the maximum charge power in watts that the battery is allowed to draw while charging.
+ */
+export interface EnyoDataBusSetStorageChargeLimitV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.SetStorageChargeLimitV1;
+    /** ID of the battery/storage appliance to limit */
+    applianceId: string;
+    data: {
+        /** Charge limit in W to limit the battery's charge power */
+        chargeLimitW: number;
+        /** Optional reason why this command was issued */
+        reason?: EnyoDataBusCommandReason;
+    };
+}
 /**
  * Command message to set or reset the inverter's grid feed-in power limit.
  * When a limit is set, the inverter will not feed more than the specified power into the grid.

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

@@ -136,7 +136,10 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["HeatpumpDhwTemperatureForecastV1"] = "HeatpumpDhwTemperatureForecastV1";
     EnyoDataBusMessageEnum["StartStorageGridChargeV1"] = "StartStorageGridChargeV1";
     EnyoDataBusMessageEnum["StopStorageGridChargeV1"] = "StopStorageGridChargeV1";
+    EnyoDataBusMessageEnum["StartStorageGridDischargeV1"] = "StartStorageGridDischargeV1";
+    EnyoDataBusMessageEnum["StopStorageGridDischargeV1"] = "StopStorageGridDischargeV1";
     EnyoDataBusMessageEnum["SetStorageDischargeLimitV1"] = "SetStorageDischargeLimitV1";
+    EnyoDataBusMessageEnum["SetStorageChargeLimitV1"] = "SetStorageChargeLimitV1";
     EnyoDataBusMessageEnum["SetInverterFeedInLimitV1"] = "SetInverterFeedInLimitV1";
     EnyoDataBusMessageEnum["CommandAcknowledgeV1"] = "CommandAcknowledgeV1";
     EnyoDataBusMessageEnum["TemperatureSensorValuesUpdateV1"] = "TemperatureSensorValuesUpdateV1";

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

@@ -12,7 +12,9 @@ export declare enum EnyoHeatpumpApplianceAvailableFeaturesEnum {
     /** If the heatpump supports available power announcements */
     AvailablePowerAnnouncement = "AvailablePowerAnnouncement",
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
-    Power = "Power"
+    Power = "Power",
+    /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
+    ReadyForCalibration = "ReadyForCalibration"
 }
 export declare enum EnyoHeatpumpApplianceModeEnum {
     Idle = "Idle",

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

@@ -14,6 +14,8 @@ export var EnyoHeatpumpApplianceAvailableFeaturesEnum;
     EnyoHeatpumpApplianceAvailableFeaturesEnum["AvailablePowerAnnouncement"] = "AvailablePowerAnnouncement";
     /** If the heatpump reports power values (e.g. electrical power consumption in watts) */
     EnyoHeatpumpApplianceAvailableFeaturesEnum["Power"] = "Power";
+    /** If the heatpump is ready for calibration (i.e. has all prerequisites in place to start a calibration run) */
+    EnyoHeatpumpApplianceAvailableFeaturesEnum["ReadyForCalibration"] = "ReadyForCalibration";
 })(EnyoHeatpumpApplianceAvailableFeaturesEnum || (EnyoHeatpumpApplianceAvailableFeaturesEnum = {}));
 export var EnyoHeatpumpApplianceModeEnum;
 (function (EnyoHeatpumpApplianceModeEnum) {

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.128";
+export declare const SDK_VERSION = "0.0.130";
 /**
  * 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.128';
+export const SDK_VERSION = '0.0.130';
 /**
  * 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.128",
+  "version": "0.0.130",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",