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

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

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-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.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.128';
+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.128",
+  "version": "0.0.129",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",