@enyo-energy/energy-app-sdk 1.38.0 → 1.39.0

package/README.md

@@ -1290,32 +1290,150 @@ prices.onPriceChange((newPrice) => {
 
 #### `useNotification(): EnergyAppNotification`
 
-Send notifications to users:
+Send notifications to users. Every category must be registered before it is used; the host uses the category for the
+user's on/off switch and for rate limits.
 
 ```typescript
 const notifications = energyApp.useNotification();
 
-// Send info notification
-await notifications.sendNotification({
-    type: 'info',
-    title: 'Energy Optimization',
-    message: 'Your system is running optimally',
-    timestamp: Date.now()
+notifications.registerNotificationCategory({
+    category: 'connection-issue',
+    name: [
+        { language: 'en', name: 'Connection issue' },
+        { language: 'de', name: 'Verbindungsproblem' }
+    ]
 });
 
-// Send warning
-await notifications.sendNotification({
-    type: 'warning',
-    title: 'High Energy Consumption',
-    message: 'Consider reducing energy usage during peak hours'
-});
+const notificationId = notifications.sendNotification(
+    'connection-issue',
+    { applianceId, target: { type: 'appliance-settings', applianceId } },
+    [
+        { language: 'en', title: 'Inverter offline', body: 'Inverter communication lost - please check the connection.' },
+        { language: 'de', title: 'Wechselrichter offline', body: 'Keine Verbindung zum Wechselrichter - bitte Verbindung prüfen.' }
+    ]
+);
+```
+
+Categories:
+
+| Category | Use when |
+|---|---|
+| `connection-issue` | An appliance, gateway or upstream service is unreachable. |
+| `onboarding-required` | The user has to complete (or revisit) an onboarding flow. |
+| `charging-issue` | The app asked a charger to charge, but it is not charging. See [Charging issues](#charging-issues). |
+| `battery-issue` | The app commanded a battery, but it does not follow the command. See [Battery issues](#battery-issues). |
+| `authentication-required` | A sign-in that used to work was lost. See [Lost sign-in](#lost-sign-in). |
+
+Targets (`options.target`) decide where tapping the notification leads:
+
+| Target | Opens |
+|---|---|
+| `{ type: 'onboarding', onboardingName }` | A registered onboarding guide. |
+| `{ type: 'energy-app-settings' }` | The package's own settings. |
+| `{ type: 'appliance-settings', applianceId }` | The settings screen of an appliance. |
+| `{ type: 'appliance', applianceId }` | The live view of an appliance (current state, power and session). |
+| `{ type: 'authentication', applianceId? }` | The package's pending sign-in, created with `requestAuthentication()`. |
+| `{ type: 'subscription-offer', planKey }` | The offer screen for a subscription plan. |
 
-// Send critical alert
-await notifications.sendNotification({
-    type: 'error',
-    title: 'System Fault',
-    message: 'Inverter communication lost - please check connection'
+`sendNotification` throws an `EnyoNotificationSendError` with `type: 'not-registered'` if the category was not
+registered, or `type: 'rate-limit'` if the host's rate limit for the category is exceeded.
+
+##### Charging issues
+
+Only the app that decided a charger should charge knows that it should be charging, so the app sends
+`charging-issue` notifications. The host relies on these rules and does not re-check them. Send one only when
+**all** of the following hold:
+
+- The app itself asked the charger to charge: it sent a start or resume, or it is giving the charger more than 0 W.
+- The charger has stayed non-charging for at least 5 minutes after that request (status is not `Charging`, or it is
+  `Charging` but draws almost no power).
+- The charger is not `Suspended` with reason `EnyoChargerApplianceSuspendedReasonEnum.Ev`: the car is full or paused
+  charging itself, which is not a fault.
+- No grid-operator limit (§14a / `GridOperatorPowerLimitationV1`) is currently pushing the charger to 0.
+
+Send it **at most once per plug-in**: wait until the charger is `Available` again (car unplugged) before sending
+another one for that appliance. Always pass `applianceId` and the `appliance` target. The host drops more than one
+`charging-issue` per appliance per 30 minutes with a `rate-limit` error.
+
+```typescript
+const notification = energyApp.useNotification();
+
+notification.registerNotificationCategory({
+    category: 'charging-issue',
+    name: [
+        {language: 'de', name: 'Ladeprobleme'},
+        {language: 'en', name: 'Charging issues'},
+    ],
+    description: [
+        {language: 'de', name: 'Ladeprobleme', description: 'Wenn dein Auto nicht lädt, obwohl es laden sollte.'},
+        {language: 'en', name: 'Charging issues', description: 'When your car is not charging although it should.'},
+    ],
 });
+
+notification.sendNotification(
+    'charging-issue',
+    {applianceId, target: {type: 'appliance', applianceId}},
+    [
+        {language: 'de', title: 'Dein Auto lädt nicht', body: 'Die Wallbox sollte gerade laden, tut es aber nicht. Prüfe bitte Auto und Ladekabel.'},
+        {language: 'en', title: 'Your car is not charging', body: 'The wallbox should be charging right now but isn\'t. Please check the car and the charging cable.'},
+    ],
+);
+```
+
+##### Battery issues
+
+`battery-issue` follows the same idea for home batteries. Send one only when **all** of the following hold:
+
+- The app itself commanded the battery (`SetStorageControlV2` with mode `Controlled`, or one of the other storage
+  commands) and that command is still in effect. Never while the battery runs on `Auto`.
+- For at least 5 minutes the battery has not followed it, judged by `batteryPowerW` in `BatteryValuesUpdateV1`:
+  not charging on `Charge`, not discharging on `Discharge`, or moving power noticeably on `Hold`.
+- The battery is not simply at its limit: no charge command at or above `maxSoC` (or 100 %), no discharge command
+  at or below `minSoC`.
+- A discharge to the house is not just capped by low household consumption.
+- No grid-operator limit (§14a) is pushing the battery to 0, and `controlAllowed` is not `false`.
+
+Send it **at most once per issue**: wait until the battery follows a command again, or the app releases it to
+`Auto`, before sending another one. Always pass `applianceId` and the `appliance` target. The host drops more than
+one `battery-issue` per appliance per 30 minutes with a `rate-limit` error.
+
+```typescript
+notification.sendNotification(
+    'battery-issue',
+    {applianceId, target: {type: 'appliance', applianceId}},
+    [
+        {language: 'de', title: 'Dein Speicher reagiert nicht', body: 'Der Batteriespeicher folgt der Steuerung gerade nicht. Prüfe bitte, ob die externe Steuerung am Speicher aktiviert ist.'},
+        {language: 'en', title: 'Your battery is not responding', body: 'The home battery is not following the control right now. Please check that external control is enabled on the battery.'},
+    ],
+);
+```
+
+##### Lost sign-in
+
+`requestAuthentication()` already prompts the user, including for the first sign-in during onboarding.
+`authentication-required` is only for a sign-in that **used to work** and was lost. Send one only when:
+
+- The package was `Authenticated` before, the vendor now rejects the credentials or token, and a refresh failed.
+- The failure is not transient. Timeouts or a vendor outage are a `connection-issue`.
+- The user did not sign out themselves.
+
+Before sending, set the state with `setAuthenticationState()` and create a new request with
+`requestAuthentication()`, so the `authentication` target has a sign-in to open. Send it **at most once per lost
+session**, and not again until the package is `Authenticated` again. The host allows one per package (or per
+appliance, for an appliance sign-in) per 24 hours.
+
+```typescript
+await auth.setAuthenticationState({state: EnyoAuthenticationStateEnum.AuthenticationFailed});
+await auth.requestAuthentication({authenticationType: 'oauth', oauth: {}, oneTimeAuthentication: false});
+
+notification.sendNotification(
+    'authentication-required',
+    {target: {type: 'authentication'}},
+    [
+        {language: 'de', title: 'Bitte erneut anmelden', body: 'Deine Anmeldung ist abgelaufen. Melde dich erneut an, damit wir deine Geräte weiter steuern können.'},
+        {language: 'en', title: 'Please sign in again', body: 'Your sign-in has expired. Sign in again so we can keep controlling your devices.'},
+    ],
+);
 ```
 
 ### App Intelligence

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

@@ -11,6 +11,164 @@ import { EnyoNotificationCategory, EnyoNotificationCategoryRegistration, EnyoNot
  * 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.
+ *
+ * ## Sending a `charging-issue`
+ *
+ * The host relies on these rules and does not re-check them, so every app
+ * must send a `charging-issue` under the same conditions.
+ *
+ * Send it only when **all** of the following hold:
+ * - The app itself asked the charger to charge: it sent a start or resume,
+ *   or it is giving the charger more than 0 W of available power.
+ * - The charger has stayed non-charging for at least 5 minutes after that
+ *   request. Non-charging means its status is not
+ *   {@link EnyoChargerApplianceStatusEnum.Charging}, or it is `Charging` but
+ *   draws (almost) no power.
+ * - The car is not the one holding the charge: do **not** send while the
+ *   charger reports {@link EnyoChargerApplianceStatusEnum.Suspended} with
+ *   reason {@link EnyoChargerApplianceSuspendedReasonEnum.Ev}. That means the
+ *   car's battery is full or the car paused charging itself, which is not a
+ *   fault.
+ * - No grid-operator limit (§14a /
+ *   {@link EnyoDataBusMessageEnum.GridOperatorPowerLimitationV1}) is
+ *   currently pushing the charger to 0.
+ *
+ * Send it **at most once per plug-in**: after sending, wait until the car is
+ * unplugged ({@link EnyoChargerApplianceStatusEnum.Available}) before sending
+ * again for that appliance.
+ *
+ * Always pass `options.applianceId` and
+ * `options.target = { type: 'appliance', applianceId }`.
+ *
+ * The host enforces a rate limit of one `charging-issue` per appliance per
+ * 30 minutes. A notification sent within that window is dropped and the call
+ * fails with a `rate-limit` error.
+ *
+ * @example
+ * ```typescript
+ * const notification = sdk.useNotification();
+ *
+ * notification.registerNotificationCategory({
+ *     category: 'charging-issue',
+ *     name: [
+ *         {language: 'de', name: 'Ladeprobleme'},
+ *         {language: 'en', name: 'Charging issues'},
+ *     ],
+ *     description: [
+ *         {language: 'de', name: 'Ladeprobleme', description: 'Wenn dein Auto nicht lädt, obwohl es laden sollte.'},
+ *         {language: 'en', name: 'Charging issues', description: 'When your car is not charging although it should.'},
+ *     ],
+ * });
+ *
+ * notification.sendNotification(
+ *     'charging-issue',
+ *     {applianceId, target: {type: 'appliance', applianceId}},
+ *     [
+ *         {language: 'de', title: 'Dein Auto lädt nicht', body: 'Die Wallbox sollte gerade laden, tut es aber nicht. Prüfe bitte Auto und Ladekabel.'},
+ *         {language: 'en', title: 'Your car is not charging', body: 'The wallbox should be charging right now but isn\'t. Please check the car and the charging cable.'},
+ *     ],
+ * );
+ * ```
+ *
+ * ## Sending a `battery-issue`
+ *
+ * Send it only when **all** of the following hold:
+ * - The app itself commanded the battery: it sent a
+ *   {@link EnyoDataBusMessageEnum.SetStorageControlV2} with mode `Controlled`
+ *   (or one of the `Start…`/`SetStorage…` storage commands) that is still in
+ *   effect. Never send while the battery runs on its own logic (`Auto`).
+ * - For at least 5 minutes after that command, the battery has not followed
+ *   it, judged by `batteryPowerW` in
+ *   {@link EnyoDataBusMessageEnum.BatteryValuesUpdateV1}:
+ *   - `Charge`: the battery is not charging, or charges at (almost) 0 W.
+ *   - `Discharge`: the battery is not discharging, or discharges at
+ *     (almost) 0 W.
+ *   - `Hold`: the battery charges or discharges noticeably.
+ * - The battery is not simply at its limit: do **not** send for a charge
+ *   command while the state of charge is at or above
+ *   {@link EnyoBatteryApplianceMetadata.maxSoC} (or 100 %), or for a
+ *   discharge command while it is at or below
+ *   {@link EnyoBatteryApplianceMetadata.minSoC}.
+ * - A discharge to the house is not capped by low household consumption.
+ *   Without grid discharging, the battery can only deliver what the house
+ *   draws, which is not a fault.
+ * - No grid-operator limit (§14a / `gridOperatorLimit` in
+ *   `BatteryValuesUpdateV1`, or
+ *   {@link EnyoDataBusMessageEnum.GridOperatorPowerLimitationV1}) is
+ *   currently pushing the battery's power to 0.
+ * - Control is allowed: {@link EnyoBatteryApplianceMetadata.controlAllowed}
+ *   is not `false`. (The app must not command such a battery at all.)
+ *
+ * Send it **at most once per issue**: after sending, wait until the battery
+ * follows a command again, or the app releases it back to `Auto`, before
+ * sending again for that appliance.
+ *
+ * Always pass `options.applianceId` and
+ * `options.target = { type: 'appliance', applianceId }`.
+ *
+ * The host enforces a rate limit of one `battery-issue` per appliance per
+ * 30 minutes. A notification sent within that window is dropped and the call
+ * fails with a `rate-limit` error.
+ *
+ * ## Sending an `authentication-required`
+ *
+ * {@link EnergyAppAuthentication.requestAuthentication} already prompts the
+ * user, including for the first sign-in during onboarding. This category is
+ * only for a sign-in that **used to work** and was lost.
+ *
+ * Send it only when **all** of the following hold:
+ * - The package was authenticated before
+ *   ({@link EnyoAuthenticationStateEnum.Authenticated}) and the session is now
+ *   unusable: the vendor rejects the credentials or token, and a refresh (if
+ *   the vendor supports one) failed.
+ * - The failure is not transient. Timeouts, 5xx responses or the vendor cloud
+ *   being down are a `connection-issue`, not an `authentication-required`.
+ * - The user did not sign out themselves: do **not** send after
+ *   {@link EnergyAppAuthentication.signOut} or a sign-out reported through
+ *   {@link EnergyAppAuthentication.listenForSignOut}.
+ *
+ * Before sending, set the state via
+ * {@link EnergyAppAuthentication.setAuthenticationState} (to
+ * `AuthenticationFailed` or `Unauthenticated`) and create a new request via
+ * {@link EnergyAppAuthentication.requestAuthentication}, so the target has a
+ * sign-in to open.
+ *
+ * Send it **at most once per lost session**: after sending, wait until the
+ * package is `Authenticated` again before sending another one.
+ *
+ * Pass `options.target = { type: 'authentication' }`. For an appliance
+ * sign-in, also pass `options.applianceId` and set the target's
+ * `applianceId`.
+ *
+ * The host enforces a rate limit of one `authentication-required` per
+ * package (or per appliance, for an appliance sign-in) per 24 hours.
+ *
+ * @example
+ * ```typescript
+ * const notification = sdk.useNotification();
+ * const auth = sdk.useAuthentication();
+ *
+ * notification.registerNotificationCategory({
+ *     category: 'authentication-required',
+ *     name: [
+ *         {language: 'de', name: 'Anmeldung erforderlich'},
+ *         {language: 'en', name: 'Sign-in required'},
+ *     ],
+ * });
+ *
+ * // The vendor rejected the refresh token: the session is gone for good.
+ * await auth.setAuthenticationState({state: EnyoAuthenticationStateEnum.AuthenticationFailed});
+ * await auth.requestAuthentication({authenticationType: 'oauth', oauth: {}, oneTimeAuthentication: false});
+ *
+ * notification.sendNotification(
+ *     'authentication-required',
+ *     {target: {type: 'authentication'}},
+ *     [
+ *         {language: 'de', title: 'Bitte erneut anmelden', body: 'Deine Anmeldung ist abgelaufen. Melde dich erneut an, damit wir deine Geräte weiter steuern können.'},
+ *         {language: 'en', title: 'Please sign in again', body: 'Your sign-in has expired. Sign in again so we can keep controlling your devices.'},
+ *     ],
+ * );
+ * ```
  */
 export interface EnergyAppNotification {
     /**
@@ -44,9 +202,13 @@ export interface EnergyAppNotification {
      * `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.
+     * guide for the `onboarding-required` category, or the appliance's live
+     * view (`{ type: 'appliance', applianceId }`) for `charging-issue` and
+     * `battery-issue`, or the pending sign-in (`{ type: 'authentication' }`)
+     * for `authentication-required`. The "Sending a …" sections on
+     * {@link EnergyAppNotification} describe when those categories may be
+     * sent.
      *
-     * @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.

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

@@ -12,8 +12,19 @@ import { EnergyAppPackageLanguage } from "../energy-app-package-definition.cjs";
  *   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.
+ * - `charging-issue`: The app expected an appliance to charge — it sent a
+ *   start or resume, gave the charger power, or scheduled a charge — but the
+ *   appliance is not charging. See "Sending a `charging-issue`" on
+ *   {@link EnergyAppNotification} for when to send it.
+ * - `battery-issue`: The app commanded a battery to charge, discharge or hold,
+ *   but the battery is not following the command. See "Sending a
+ *   `battery-issue`" on {@link EnergyAppNotification} for when to send it.
+ * - `authentication-required`: A sign-in that used to work was lost (expired
+ *   or revoked) and the user has to sign in again before the package can
+ *   continue. See "Sending an `authentication-required`" on
+ *   {@link EnergyAppNotification} for when to send it.
  */
-export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required';
+export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required' | 'charging-issue' | 'battery-issue' | 'authentication-required';
 /**
  * Registration payload describing a notification category to the host.
  *
@@ -45,7 +56,7 @@ export interface EnyoNotificationCategoryTranslation {
  * 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 | EnyoNotificationSubscriptionOfferTarget;
+export type EnyoNotificationTarget = EnyoNotificationOnboardingTarget | EnyoNotificationEnergyAppSettingsTarget | EnyoNotificationApplianceSettingsTarget | EnyoNotificationSubscriptionOfferTarget | EnyoNotificationApplianceTarget | EnyoNotificationAuthenticationTarget;
 /**
  * Target that opens an onboarding guide previously registered with the host.
  *
@@ -73,6 +84,9 @@ export interface EnyoNotificationEnergyAppSettingsTarget {
 /**
  * Target that opens the settings screen for a specific appliance managed by
  * the energy app package.
+ *
+ * To show the appliance's live state instead (e.g. for a `charging-issue`),
+ * use {@link EnyoNotificationApplianceTarget}.
  */
 export interface EnyoNotificationApplianceSettingsTarget {
     /** Discriminator identifying this as an appliance settings target. */
@@ -83,6 +97,42 @@ export interface EnyoNotificationApplianceSettingsTarget {
      */
     applianceId: string;
 }
+/**
+ * Target that opens the live view of a specific appliance (its current
+ * state, power and session), as opposed to its settings screen.
+ *
+ * This is the target to use for `charging-issue` and `battery-issue`
+ * notifications.
+ */
+export interface EnyoNotificationApplianceTarget {
+    /** Discriminator identifying this as an appliance target. */
+    type: 'appliance';
+    /**
+     * Identifier of the appliance to open. Must match an appliance id known
+     * to the host.
+     */
+    applianceId: string;
+}
+/**
+ * Target that opens the package's pending sign-in, i.e. the authentication
+ * request previously created via
+ * {@link EnergyAppAuthentication.requestAuthentication}.
+ *
+ * This is the target to use for `authentication-required` notifications.
+ * Create the authentication request before sending the notification, so that
+ * there is a sign-in for the host to open.
+ */
+export interface EnyoNotificationAuthenticationTarget {
+    /** Discriminator identifying this as an authentication target. */
+    type: 'authentication';
+    /**
+     * Identifier of the appliance the sign-in belongs to. Set it when the
+     * authentication request was created for a specific appliance
+     * ({@link EnyoAuthentication.applianceId}); omit it for a package-wide
+     * sign-in.
+     */
+    applianceId?: string;
+}
 /**
  * Target that opens enyo's offer screen for one of the package's
  * subscription plans, from where the user can buy it.
@@ -136,6 +186,9 @@ export interface EnyoNotificationTranslation {
  *   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.
+ *   For `charging-issue` and `battery-issue` the limit is one notification
+ *   per appliance per 30 minutes; for `authentication-required` it is one
+ *   per package (or per appliance, for an appliance sign-in) per 24 hours.
  */
 export type EnyoNotificationSendErrorType = 'not-registered' | 'rate-limit';
 /**

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.38.0';
+exports.SDK_VERSION = '1.39.0';
 /**
  * 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 = "1.38.0";
+export declare const SDK_VERSION = "1.39.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

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

@@ -11,6 +11,164 @@ import { EnyoNotificationCategory, EnyoNotificationCategoryRegistration, EnyoNot
  * 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.
+ *
+ * ## Sending a `charging-issue`
+ *
+ * The host relies on these rules and does not re-check them, so every app
+ * must send a `charging-issue` under the same conditions.
+ *
+ * Send it only when **all** of the following hold:
+ * - The app itself asked the charger to charge: it sent a start or resume,
+ *   or it is giving the charger more than 0 W of available power.
+ * - The charger has stayed non-charging for at least 5 minutes after that
+ *   request. Non-charging means its status is not
+ *   {@link EnyoChargerApplianceStatusEnum.Charging}, or it is `Charging` but
+ *   draws (almost) no power.
+ * - The car is not the one holding the charge: do **not** send while the
+ *   charger reports {@link EnyoChargerApplianceStatusEnum.Suspended} with
+ *   reason {@link EnyoChargerApplianceSuspendedReasonEnum.Ev}. That means the
+ *   car's battery is full or the car paused charging itself, which is not a
+ *   fault.
+ * - No grid-operator limit (§14a /
+ *   {@link EnyoDataBusMessageEnum.GridOperatorPowerLimitationV1}) is
+ *   currently pushing the charger to 0.
+ *
+ * Send it **at most once per plug-in**: after sending, wait until the car is
+ * unplugged ({@link EnyoChargerApplianceStatusEnum.Available}) before sending
+ * again for that appliance.
+ *
+ * Always pass `options.applianceId` and
+ * `options.target = { type: 'appliance', applianceId }`.
+ *
+ * The host enforces a rate limit of one `charging-issue` per appliance per
+ * 30 minutes. A notification sent within that window is dropped and the call
+ * fails with a `rate-limit` error.
+ *
+ * @example
+ * ```typescript
+ * const notification = sdk.useNotification();
+ *
+ * notification.registerNotificationCategory({
+ *     category: 'charging-issue',
+ *     name: [
+ *         {language: 'de', name: 'Ladeprobleme'},
+ *         {language: 'en', name: 'Charging issues'},
+ *     ],
+ *     description: [
+ *         {language: 'de', name: 'Ladeprobleme', description: 'Wenn dein Auto nicht lädt, obwohl es laden sollte.'},
+ *         {language: 'en', name: 'Charging issues', description: 'When your car is not charging although it should.'},
+ *     ],
+ * });
+ *
+ * notification.sendNotification(
+ *     'charging-issue',
+ *     {applianceId, target: {type: 'appliance', applianceId}},
+ *     [
+ *         {language: 'de', title: 'Dein Auto lädt nicht', body: 'Die Wallbox sollte gerade laden, tut es aber nicht. Prüfe bitte Auto und Ladekabel.'},
+ *         {language: 'en', title: 'Your car is not charging', body: 'The wallbox should be charging right now but isn\'t. Please check the car and the charging cable.'},
+ *     ],
+ * );
+ * ```
+ *
+ * ## Sending a `battery-issue`
+ *
+ * Send it only when **all** of the following hold:
+ * - The app itself commanded the battery: it sent a
+ *   {@link EnyoDataBusMessageEnum.SetStorageControlV2} with mode `Controlled`
+ *   (or one of the `Start…`/`SetStorage…` storage commands) that is still in
+ *   effect. Never send while the battery runs on its own logic (`Auto`).
+ * - For at least 5 minutes after that command, the battery has not followed
+ *   it, judged by `batteryPowerW` in
+ *   {@link EnyoDataBusMessageEnum.BatteryValuesUpdateV1}:
+ *   - `Charge`: the battery is not charging, or charges at (almost) 0 W.
+ *   - `Discharge`: the battery is not discharging, or discharges at
+ *     (almost) 0 W.
+ *   - `Hold`: the battery charges or discharges noticeably.
+ * - The battery is not simply at its limit: do **not** send for a charge
+ *   command while the state of charge is at or above
+ *   {@link EnyoBatteryApplianceMetadata.maxSoC} (or 100 %), or for a
+ *   discharge command while it is at or below
+ *   {@link EnyoBatteryApplianceMetadata.minSoC}.
+ * - A discharge to the house is not capped by low household consumption.
+ *   Without grid discharging, the battery can only deliver what the house
+ *   draws, which is not a fault.
+ * - No grid-operator limit (§14a / `gridOperatorLimit` in
+ *   `BatteryValuesUpdateV1`, or
+ *   {@link EnyoDataBusMessageEnum.GridOperatorPowerLimitationV1}) is
+ *   currently pushing the battery's power to 0.
+ * - Control is allowed: {@link EnyoBatteryApplianceMetadata.controlAllowed}
+ *   is not `false`. (The app must not command such a battery at all.)
+ *
+ * Send it **at most once per issue**: after sending, wait until the battery
+ * follows a command again, or the app releases it back to `Auto`, before
+ * sending again for that appliance.
+ *
+ * Always pass `options.applianceId` and
+ * `options.target = { type: 'appliance', applianceId }`.
+ *
+ * The host enforces a rate limit of one `battery-issue` per appliance per
+ * 30 minutes. A notification sent within that window is dropped and the call
+ * fails with a `rate-limit` error.
+ *
+ * ## Sending an `authentication-required`
+ *
+ * {@link EnergyAppAuthentication.requestAuthentication} already prompts the
+ * user, including for the first sign-in during onboarding. This category is
+ * only for a sign-in that **used to work** and was lost.
+ *
+ * Send it only when **all** of the following hold:
+ * - The package was authenticated before
+ *   ({@link EnyoAuthenticationStateEnum.Authenticated}) and the session is now
+ *   unusable: the vendor rejects the credentials or token, and a refresh (if
+ *   the vendor supports one) failed.
+ * - The failure is not transient. Timeouts, 5xx responses or the vendor cloud
+ *   being down are a `connection-issue`, not an `authentication-required`.
+ * - The user did not sign out themselves: do **not** send after
+ *   {@link EnergyAppAuthentication.signOut} or a sign-out reported through
+ *   {@link EnergyAppAuthentication.listenForSignOut}.
+ *
+ * Before sending, set the state via
+ * {@link EnergyAppAuthentication.setAuthenticationState} (to
+ * `AuthenticationFailed` or `Unauthenticated`) and create a new request via
+ * {@link EnergyAppAuthentication.requestAuthentication}, so the target has a
+ * sign-in to open.
+ *
+ * Send it **at most once per lost session**: after sending, wait until the
+ * package is `Authenticated` again before sending another one.
+ *
+ * Pass `options.target = { type: 'authentication' }`. For an appliance
+ * sign-in, also pass `options.applianceId` and set the target's
+ * `applianceId`.
+ *
+ * The host enforces a rate limit of one `authentication-required` per
+ * package (or per appliance, for an appliance sign-in) per 24 hours.
+ *
+ * @example
+ * ```typescript
+ * const notification = sdk.useNotification();
+ * const auth = sdk.useAuthentication();
+ *
+ * notification.registerNotificationCategory({
+ *     category: 'authentication-required',
+ *     name: [
+ *         {language: 'de', name: 'Anmeldung erforderlich'},
+ *         {language: 'en', name: 'Sign-in required'},
+ *     ],
+ * });
+ *
+ * // The vendor rejected the refresh token: the session is gone for good.
+ * await auth.setAuthenticationState({state: EnyoAuthenticationStateEnum.AuthenticationFailed});
+ * await auth.requestAuthentication({authenticationType: 'oauth', oauth: {}, oneTimeAuthentication: false});
+ *
+ * notification.sendNotification(
+ *     'authentication-required',
+ *     {target: {type: 'authentication'}},
+ *     [
+ *         {language: 'de', title: 'Bitte erneut anmelden', body: 'Deine Anmeldung ist abgelaufen. Melde dich erneut an, damit wir deine Geräte weiter steuern können.'},
+ *         {language: 'en', title: 'Please sign in again', body: 'Your sign-in has expired. Sign in again so we can keep controlling your devices.'},
+ *     ],
+ * );
+ * ```
  */
 export interface EnergyAppNotification {
     /**
@@ -44,9 +202,13 @@ export interface EnergyAppNotification {
      * `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.
+     * guide for the `onboarding-required` category, or the appliance's live
+     * view (`{ type: 'appliance', applianceId }`) for `charging-issue` and
+     * `battery-issue`, or the pending sign-in (`{ type: 'authentication' }`)
+     * for `authentication-required`. The "Sending a …" sections on
+     * {@link EnergyAppNotification} describe when those categories may be
+     * sent.
      *
-     * @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.

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

@@ -12,8 +12,19 @@ import { EnergyAppPackageLanguage } from "../energy-app-package-definition.js";
  *   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.
+ * - `charging-issue`: The app expected an appliance to charge — it sent a
+ *   start or resume, gave the charger power, or scheduled a charge — but the
+ *   appliance is not charging. See "Sending a `charging-issue`" on
+ *   {@link EnergyAppNotification} for when to send it.
+ * - `battery-issue`: The app commanded a battery to charge, discharge or hold,
+ *   but the battery is not following the command. See "Sending a
+ *   `battery-issue`" on {@link EnergyAppNotification} for when to send it.
+ * - `authentication-required`: A sign-in that used to work was lost (expired
+ *   or revoked) and the user has to sign in again before the package can
+ *   continue. See "Sending an `authentication-required`" on
+ *   {@link EnergyAppNotification} for when to send it.
  */
-export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required';
+export type EnyoNotificationCategory = 'connection-issue' | 'onboarding-required' | 'charging-issue' | 'battery-issue' | 'authentication-required';
 /**
  * Registration payload describing a notification category to the host.
  *
@@ -45,7 +56,7 @@ export interface EnyoNotificationCategoryTranslation {
  * 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 | EnyoNotificationSubscriptionOfferTarget;
+export type EnyoNotificationTarget = EnyoNotificationOnboardingTarget | EnyoNotificationEnergyAppSettingsTarget | EnyoNotificationApplianceSettingsTarget | EnyoNotificationSubscriptionOfferTarget | EnyoNotificationApplianceTarget | EnyoNotificationAuthenticationTarget;
 /**
  * Target that opens an onboarding guide previously registered with the host.
  *
@@ -73,6 +84,9 @@ export interface EnyoNotificationEnergyAppSettingsTarget {
 /**
  * Target that opens the settings screen for a specific appliance managed by
  * the energy app package.
+ *
+ * To show the appliance's live state instead (e.g. for a `charging-issue`),
+ * use {@link EnyoNotificationApplianceTarget}.
  */
 export interface EnyoNotificationApplianceSettingsTarget {
     /** Discriminator identifying this as an appliance settings target. */
@@ -83,6 +97,42 @@ export interface EnyoNotificationApplianceSettingsTarget {
      */
     applianceId: string;
 }
+/**
+ * Target that opens the live view of a specific appliance (its current
+ * state, power and session), as opposed to its settings screen.
+ *
+ * This is the target to use for `charging-issue` and `battery-issue`
+ * notifications.
+ */
+export interface EnyoNotificationApplianceTarget {
+    /** Discriminator identifying this as an appliance target. */
+    type: 'appliance';
+    /**
+     * Identifier of the appliance to open. Must match an appliance id known
+     * to the host.
+     */
+    applianceId: string;
+}
+/**
+ * Target that opens the package's pending sign-in, i.e. the authentication
+ * request previously created via
+ * {@link EnergyAppAuthentication.requestAuthentication}.
+ *
+ * This is the target to use for `authentication-required` notifications.
+ * Create the authentication request before sending the notification, so that
+ * there is a sign-in for the host to open.
+ */
+export interface EnyoNotificationAuthenticationTarget {
+    /** Discriminator identifying this as an authentication target. */
+    type: 'authentication';
+    /**
+     * Identifier of the appliance the sign-in belongs to. Set it when the
+     * authentication request was created for a specific appliance
+     * ({@link EnyoAuthentication.applianceId}); omit it for a package-wide
+     * sign-in.
+     */
+    applianceId?: string;
+}
 /**
  * Target that opens enyo's offer screen for one of the package's
  * subscription plans, from where the user can buy it.
@@ -136,6 +186,9 @@ export interface EnyoNotificationTranslation {
  *   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.
+ *   For `charging-issue` and `battery-issue` the limit is one notification
+ *   per appliance per 30 minutes; for `authentication-required` it is one
+ *   per package (or per appliance, for an appliance sign-in) per 24 hours.
  */
 export type EnyoNotificationSendErrorType = 'not-registered' | 'rate-limit';
 /**

package/dist/version.d.ts

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