@enyo-energy/energy-app-sdk 0.0.155 → 0.0.157

package/dist/cjs/energy-app-permission.type.cjs

@@ -38,6 +38,7 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["PvSystemUse"] = "PvSystemUse";
     EnergyAppPermissionTypeEnum["InverterControlCommands"] = "InverterControlCommands";
     EnergyAppPermissionTypeEnum["BatteryControlCommands"] = "BatteryControlCommands";
+    EnergyAppPermissionTypeEnum["BatteryStorageState"] = "BatteryStorageState";
     EnergyAppPermissionTypeEnum["ChargerControlCommands"] = "ChargerControlCommands";
     EnergyAppPermissionTypeEnum["EebusDeviceManagement"] = "EebusDeviceManagement";
     EnergyAppPermissionTypeEnum["EebusDataAccess"] = "EebusDataAccess";

package/dist/cjs/energy-app-permission.type.d.cts

@@ -1,4 +1,4 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
+export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -35,6 +35,7 @@ export declare enum EnergyAppPermissionTypeEnum {
     PvSystemUse = "PvSystemUse",
     InverterControlCommands = "InverterControlCommands",
     BatteryControlCommands = "BatteryControlCommands",
+    BatteryStorageState = "BatteryStorageState",
     ChargerControlCommands = "ChargerControlCommands",
     EebusDeviceManagement = "EebusDeviceManagement",
     EebusDataAccess = "EebusDataAccess",

package/dist/cjs/energy-app.cjs

@@ -307,6 +307,16 @@ class EnergyApp {
     useApplianceEnergyManagerForecast() {
         return this.energyAppSdk.useApplianceEnergyManagerForecast();
     }
+    /**
+     * Gets the Battery API for retrieving the current runtime state of each
+     * battery storage (state of charge, stored kWh, average price per kWh,
+     * optional solar share). Read-only; query by appliance ID or list all
+     * storages.
+     * @returns The Battery API instance
+     */
+    useBatteries() {
+        return this.energyAppSdk.useBatteries();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -36,6 +36,7 @@ import { EnergyAppUdp } from "./packages/energy-app-udp.cjs";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.cjs";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
+import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -240,6 +241,14 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Appliance Energy-Manager Forecast API instance
      */
     useApplianceEnergyManagerForecast(): EnergyAppApplianceEnergyManagerForecast;
+    /**
+     * Gets the Battery API for retrieving the current runtime state of each
+     * battery storage (state of charge, stored kWh, average price per kWh,
+     * optional solar share). Read-only; query by appliance ID or list all
+     * storages.
+     * @returns The Battery API instance
+     */
+    useBatteries(): EnergyAppBattery;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -35,6 +35,7 @@ import { EnergyAppUdp } from "./packages/energy-app-udp.cjs";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.cjs";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.cjs";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
+import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -133,4 +134,6 @@ export interface EnyoEnergyAppSdk {
     useConfigurationManager: () => EnergyAppConfigurationManager;
     /** Get the Appliance Energy-Manager Forecast API for publishing forecasted command plans per appliance (charger, battery, heatpump) */
     useApplianceEnergyManagerForecast: () => EnergyAppApplianceEnergyManagerForecast;
+    /** Get the Battery API for retrieving the current runtime state of each battery storage (SoC, stored kWh, average price per kWh, optional solar share) */
+    useBatteries: () => EnergyAppBattery;
 }

package/dist/cjs/index.cjs

@@ -99,3 +99,5 @@ __exportStar(require("./types/enyo-appliance-command-forecast.cjs"), exports);
 __exportStar(require("./packages/energy-app-appliance-energy-manager-forecast.cjs"), exports);
 __exportStar(require("./implementations/appliance-command-forecast/appliance-command-forecast-validators.cjs"), exports);
 __exportStar(require("./implementations/energy-manager-diagnostics/energy-manager-diagnostics-validators.cjs"), exports);
+__exportStar(require("./types/enyo-battery-state.cjs"), exports);
+__exportStar(require("./packages/energy-app-battery.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -83,3 +83,5 @@ export * from './types/enyo-appliance-command-forecast.cjs';
 export * from './packages/energy-app-appliance-energy-manager-forecast.cjs';
 export * from './implementations/appliance-command-forecast/appliance-command-forecast-validators.cjs';
 export * from './implementations/energy-manager-diagnostics/energy-manager-diagnostics-validators.cjs';
+export * from './types/enyo-battery-state.cjs';
+export * from './packages/energy-app-battery.cjs';

package/dist/cjs/packages/energy-app-battery.cjs

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

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

@@ -0,0 +1,31 @@
+import { EnyoBatteryState } from "../types/enyo-battery-state.cjs";
+/**
+ * Interface for retrieving the current runtime state of battery storages
+ * managed by the enyo system. Read-only snapshots keyed by appliance ID.
+ *
+ * Static battery configuration (capacity, mode, features, …) remains on
+ * `EnyoBatteryApplianceMetadata` via the Appliance API; this package is
+ * intentionally limited to volatile runtime values (SoC, stored kWh,
+ * price per kWh, optional solar share).
+ *
+ * Requires the `BatteryStorageState` permission.
+ */
+export interface EnergyAppBattery {
+    /**
+     * Returns the current state for every known battery storage.
+     * Batteries without a reported state are omitted from the result.
+     *
+     * @returns Promise resolving to the list of current battery states
+     */
+    list: () => Promise<EnyoBatteryState[]>;
+    /**
+     * Returns the current state of a single battery storage by its
+     * appliance ID, or `null` if no state is known for that ID (e.g.
+     * the appliance is not a battery, is unknown, or has not yet
+     * reported a value).
+     *
+     * @param applianceId - The ID of the battery appliance (`EnyoAppliance.id`)
+     * @returns Promise resolving to the current battery state, or `null` if unknown
+     */
+    getByApplianceId: (applianceId: string) => Promise<EnyoBatteryState | null>;
+}

package/dist/cjs/types/enyo-battery-state.cjs

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

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

@@ -0,0 +1,28 @@
+import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
+/**
+ * Current runtime state of a single battery storage, keyed by the
+ * battery's appliance ID. Returned by {@link EnergyAppBattery.getByApplianceId}
+ * and {@link EnergyAppBattery.list}.
+ *
+ * Static battery configuration (capacity, mode, features, …) lives on
+ * `EnyoBatteryApplianceMetadata` (accessible via the Appliance API); this
+ * type intentionally only carries volatile runtime values.
+ */
+export interface EnyoBatteryState {
+    /** Appliance ID of the battery (matches `EnyoAppliance.id` where `type === Storage`) */
+    applianceId: string;
+    /** Current state of charge in percent (0–100) */
+    socPercent: number;
+    /** Currently stored energy in kWh */
+    energyKwh: number;
+    /** Average price per kWh of the energy currently stored in the battery */
+    pricePerKwh: number;
+    /** Currency of {@link pricePerKwh} */
+    currency: EnyoCurrencyEnum;
+    /**
+     * Optional share of the currently stored energy that originated from
+     * solar production, in percent (0–100). Omitted when the runtime cannot
+     * attribute energy provenance (e.g. no PV system or insufficient data).
+     */
+    solarSharePercent?: number;
+}

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

@@ -170,6 +170,7 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StartAirConditioningV1"] = "StartAirConditioningV1";
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    EnyoDataBusMessageEnum["EnergyAppStartedV1"] = "EnergyAppStartedV1";
 })(EnyoDataBusMessageEnum || (exports.EnyoDataBusMessageEnum = EnyoDataBusMessageEnum = {}));
 /**
  * Storage control mode carried by {@link EnyoDataBusSetStorageScheduleV1}.

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

@@ -194,7 +194,8 @@ export declare enum EnyoDataBusMessageEnum {
     AirConditioningTemperaturesUpdateV1 = "AirConditioningTemperaturesUpdateV1",
     StartAirConditioningV1 = "StartAirConditioningV1",
     StopAirConditioningV1 = "StopAirConditioningV1",
-    VehicleSocUpdateV1 = "VehicleSocUpdateV1"
+    VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    EnergyAppStartedV1 = "EnergyAppStartedV1"
 }
 export type EnyoDataBusMessageResolution = '1s' | '10s' | '30s' | '1m' | '15m' | '1h' | '1d' | 'dynamic';
 /**
@@ -389,6 +390,44 @@ export interface EnyoDataBusApplianceStateUpdateV1 extends EnyoDataBusMessage {
         errorCodes?: EnyoApplianceErrorCode[];
     };
 }
+/**
+ * Message emitted when an energy app package finishes startup and is now
+ * actively driving its appliances. Carries the running package's identity
+ * plus the full set of appliance ids it has registered against, so
+ * consumers can correlate subsequent activity to this package instance
+ * and learn which appliances are now under its influence.
+ *
+ * Broadcast (no `target`) — anyone observing the data bus may listen.
+ * The base {@link EnyoDataBusMessage.applianceId} field is intentionally
+ * left unset; this message scopes to *all* affected appliances via
+ * `data.applianceIds` rather than a single one.
+ */
+export interface EnyoDataBusEnergyAppStartedV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.EnergyAppStartedV1;
+    data: {
+        /**
+         * Cloud-deployment id of the started package. Matches
+         * {@link EnyoDataBusMessageTarget.cloudPackageId} so consumers
+         * can address replies back at this package instance.
+         */
+        cloudPackageId: string;
+        /**
+         * Package slug from the started package's
+         * {@link EnergyAppPackageDefinition.packageName}. Stable across
+         * deployments of the same package, suitable for grouping
+         * activity by package implementation rather than by instance.
+         */
+        packageName: string;
+        /**
+         * Ids of every appliance this package has registered against —
+         * the appliances whose lifecycle is now influenced by the
+         * running app. Empty array is legal (the package started but
+         * has not yet resolved any appliances).
+         */
+        applianceIds: string[];
+    };
+}
 export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ChargingStartedV1;

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

package/dist/energy-app-permission.type.d.ts

@@ -1,4 +1,4 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
+export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -35,6 +35,7 @@ export declare enum EnergyAppPermissionTypeEnum {
     PvSystemUse = "PvSystemUse",
     InverterControlCommands = "InverterControlCommands",
     BatteryControlCommands = "BatteryControlCommands",
+    BatteryStorageState = "BatteryStorageState",
     ChargerControlCommands = "ChargerControlCommands",
     EebusDeviceManagement = "EebusDeviceManagement",
     EebusDataAccess = "EebusDataAccess",

package/dist/energy-app-permission.type.js

@@ -35,6 +35,7 @@ export var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["PvSystemUse"] = "PvSystemUse";
     EnergyAppPermissionTypeEnum["InverterControlCommands"] = "InverterControlCommands";
     EnergyAppPermissionTypeEnum["BatteryControlCommands"] = "BatteryControlCommands";
+    EnergyAppPermissionTypeEnum["BatteryStorageState"] = "BatteryStorageState";
     EnergyAppPermissionTypeEnum["ChargerControlCommands"] = "ChargerControlCommands";
     EnergyAppPermissionTypeEnum["EebusDeviceManagement"] = "EebusDeviceManagement";
     EnergyAppPermissionTypeEnum["EebusDataAccess"] = "EebusDataAccess";

package/dist/energy-app.d.ts

@@ -36,6 +36,7 @@ import { EnergyAppUdp } from "./packages/energy-app-udp.js";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.js";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.js";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.js";
+import { EnergyAppBattery } from "./packages/energy-app-battery.js";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -240,6 +241,14 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Appliance Energy-Manager Forecast API instance
      */
     useApplianceEnergyManagerForecast(): EnergyAppApplianceEnergyManagerForecast;
+    /**
+     * Gets the Battery API for retrieving the current runtime state of each
+     * battery storage (state of charge, stored kWh, average price per kWh,
+     * optional solar share). Read-only; query by appliance ID or list all
+     * storages.
+     * @returns The Battery API instance
+     */
+    useBatteries(): EnergyAppBattery;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/energy-app.js

@@ -304,6 +304,16 @@ export class EnergyApp {
     useApplianceEnergyManagerForecast() {
         return this.energyAppSdk.useApplianceEnergyManagerForecast();
     }
+    /**
+     * Gets the Battery API for retrieving the current runtime state of each
+     * battery storage (state of charge, stored kWh, average price per kWh,
+     * optional solar share). Read-only; query by appliance ID or list all
+     * storages.
+     * @returns The Battery API instance
+     */
+    useBatteries() {
+        return this.energyAppSdk.useBatteries();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/enyo-energy-app-sdk.d.ts

@@ -35,6 +35,7 @@ import { EnergyAppUdp } from "./packages/energy-app-udp.js";
 import { EnergyAppGridConnectionPoint } from "./packages/energy-app-grid-connection-point.js";
 import { EnergyAppConfigurationManager } from "./packages/energy-app-configuration-manager.js";
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.js";
+import { EnergyAppBattery } from "./packages/energy-app-battery.js";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -133,4 +134,6 @@ export interface EnyoEnergyAppSdk {
     useConfigurationManager: () => EnergyAppConfigurationManager;
     /** Get the Appliance Energy-Manager Forecast API for publishing forecasted command plans per appliance (charger, battery, heatpump) */
     useApplianceEnergyManagerForecast: () => EnergyAppApplianceEnergyManagerForecast;
+    /** Get the Battery API for retrieving the current runtime state of each battery storage (SoC, stored kWh, average price per kWh, optional solar share) */
+    useBatteries: () => EnergyAppBattery;
 }

package/dist/index.d.ts

@@ -83,3 +83,5 @@ export * from './types/enyo-appliance-command-forecast.js';
 export * from './packages/energy-app-appliance-energy-manager-forecast.js';
 export * from './implementations/appliance-command-forecast/appliance-command-forecast-validators.js';
 export * from './implementations/energy-manager-diagnostics/energy-manager-diagnostics-validators.js';
+export * from './types/enyo-battery-state.js';
+export * from './packages/energy-app-battery.js';

package/dist/index.js

@@ -83,3 +83,5 @@ export * from './types/enyo-appliance-command-forecast.js';
 export * from './packages/energy-app-appliance-energy-manager-forecast.js';
 export * from './implementations/appliance-command-forecast/appliance-command-forecast-validators.js';
 export * from './implementations/energy-manager-diagnostics/energy-manager-diagnostics-validators.js';
+export * from './types/enyo-battery-state.js';
+export * from './packages/energy-app-battery.js';

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

@@ -0,0 +1,31 @@
+import { EnyoBatteryState } from "../types/enyo-battery-state.js";
+/**
+ * Interface for retrieving the current runtime state of battery storages
+ * managed by the enyo system. Read-only snapshots keyed by appliance ID.
+ *
+ * Static battery configuration (capacity, mode, features, …) remains on
+ * `EnyoBatteryApplianceMetadata` via the Appliance API; this package is
+ * intentionally limited to volatile runtime values (SoC, stored kWh,
+ * price per kWh, optional solar share).
+ *
+ * Requires the `BatteryStorageState` permission.
+ */
+export interface EnergyAppBattery {
+    /**
+     * Returns the current state for every known battery storage.
+     * Batteries without a reported state are omitted from the result.
+     *
+     * @returns Promise resolving to the list of current battery states
+     */
+    list: () => Promise<EnyoBatteryState[]>;
+    /**
+     * Returns the current state of a single battery storage by its
+     * appliance ID, or `null` if no state is known for that ID (e.g.
+     * the appliance is not a battery, is unknown, or has not yet
+     * reported a value).
+     *
+     * @param applianceId - The ID of the battery appliance (`EnyoAppliance.id`)
+     * @returns Promise resolving to the current battery state, or `null` if unknown
+     */
+    getByApplianceId: (applianceId: string) => Promise<EnyoBatteryState | null>;
+}

package/dist/packages/energy-app-battery.js

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

package/dist/types/enyo-battery-state.d.ts

@@ -0,0 +1,28 @@
+import { EnyoCurrencyEnum } from "./enyo-currency.js";
+/**
+ * Current runtime state of a single battery storage, keyed by the
+ * battery's appliance ID. Returned by {@link EnergyAppBattery.getByApplianceId}
+ * and {@link EnergyAppBattery.list}.
+ *
+ * Static battery configuration (capacity, mode, features, …) lives on
+ * `EnyoBatteryApplianceMetadata` (accessible via the Appliance API); this
+ * type intentionally only carries volatile runtime values.
+ */
+export interface EnyoBatteryState {
+    /** Appliance ID of the battery (matches `EnyoAppliance.id` where `type === Storage`) */
+    applianceId: string;
+    /** Current state of charge in percent (0–100) */
+    socPercent: number;
+    /** Currently stored energy in kWh */
+    energyKwh: number;
+    /** Average price per kWh of the energy currently stored in the battery */
+    pricePerKwh: number;
+    /** Currency of {@link pricePerKwh} */
+    currency: EnyoCurrencyEnum;
+    /**
+     * Optional share of the currently stored energy that originated from
+     * solar production, in percent (0–100). Omitted when the runtime cannot
+     * attribute energy provenance (e.g. no PV system or insufficient data).
+     */
+    solarSharePercent?: number;
+}

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

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

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

@@ -194,7 +194,8 @@ export declare enum EnyoDataBusMessageEnum {
     AirConditioningTemperaturesUpdateV1 = "AirConditioningTemperaturesUpdateV1",
     StartAirConditioningV1 = "StartAirConditioningV1",
     StopAirConditioningV1 = "StopAirConditioningV1",
-    VehicleSocUpdateV1 = "VehicleSocUpdateV1"
+    VehicleSocUpdateV1 = "VehicleSocUpdateV1",
+    EnergyAppStartedV1 = "EnergyAppStartedV1"
 }
 export type EnyoDataBusMessageResolution = '1s' | '10s' | '30s' | '1m' | '15m' | '1h' | '1d' | 'dynamic';
 /**
@@ -389,6 +390,44 @@ export interface EnyoDataBusApplianceStateUpdateV1 extends EnyoDataBusMessage {
         errorCodes?: EnyoApplianceErrorCode[];
     };
 }
+/**
+ * Message emitted when an energy app package finishes startup and is now
+ * actively driving its appliances. Carries the running package's identity
+ * plus the full set of appliance ids it has registered against, so
+ * consumers can correlate subsequent activity to this package instance
+ * and learn which appliances are now under its influence.
+ *
+ * Broadcast (no `target`) — anyone observing the data bus may listen.
+ * The base {@link EnyoDataBusMessage.applianceId} field is intentionally
+ * left unset; this message scopes to *all* affected appliances via
+ * `data.applianceIds` rather than a single one.
+ */
+export interface EnyoDataBusEnergyAppStartedV1 extends EnyoDataBusMessage {
+    type: 'message';
+    message: EnyoDataBusMessageEnum.EnergyAppStartedV1;
+    data: {
+        /**
+         * Cloud-deployment id of the started package. Matches
+         * {@link EnyoDataBusMessageTarget.cloudPackageId} so consumers
+         * can address replies back at this package instance.
+         */
+        cloudPackageId: string;
+        /**
+         * Package slug from the started package's
+         * {@link EnergyAppPackageDefinition.packageName}. Stable across
+         * deployments of the same package, suitable for grouping
+         * activity by package implementation rather than by instance.
+         */
+        packageName: string;
+        /**
+         * Ids of every appliance this package has registered against —
+         * the appliances whose lifecycle is now influenced by the
+         * running app. Empty array is legal (the package started but
+         * has not yet resolved any appliances).
+         */
+        applianceIds: string[];
+    };
+}
 export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
     type: 'message';
     message: EnyoDataBusMessageEnum.ChargingStartedV1;

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

@@ -167,6 +167,7 @@ export var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StartAirConditioningV1"] = "StartAirConditioningV1";
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    EnyoDataBusMessageEnum["EnergyAppStartedV1"] = "EnergyAppStartedV1";
 })(EnyoDataBusMessageEnum || (EnyoDataBusMessageEnum = {}));
 /**
  * Storage control mode carried by {@link EnyoDataBusSetStorageScheduleV1}.

package/dist/version.d.ts

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