@enyo-energy/energy-app-sdk 0.0.159 → 0.0.161

package/dist/cjs/implementations/appliances/appliance-manager.cjs

@@ -215,9 +215,6 @@ class ApplianceManager {
         // returns the new appliance without racing the appliance-updated
         // listener (which may fire on a later microtask).
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`${existingApplianceId ? 'Updated' : 'Created'} appliance ${applianceId} of type ${appliance.type}`);
-        }
         return applianceId;
     }
     /**
@@ -278,18 +275,12 @@ class ApplianceManager {
         const updatedListenerId = applianceService.listenForApplianceUpdated((appliance) => {
             if (this.disposed)
                 return;
-            if (this.config.enableLogging) {
-                console.debug(`Appliance updated event received for ${appliance.id}`);
-            }
             this.updateCache(appliance);
         });
         this.listenerIds.push(updatedListenerId);
         const removedListenerId = applianceService.listenForApplianceRemoved((applianceId) => {
             if (this.disposed)
                 return;
-            if (this.config.enableLogging) {
-                console.debug(`Appliance removed event received for ${applianceId}`);
-            }
             this.removeFromCache(applianceId);
         });
         this.listenerIds.push(removedListenerId);
@@ -469,9 +460,6 @@ class ApplianceManager {
         };
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Updated appliance ${applianceId} state to ${state}`);
-        }
     }
     /**
      * Patches an appliance with the provided attributes via {@link mergeApplianceData}.
@@ -491,9 +479,6 @@ class ApplianceManager {
         const updated = this.mergeApplianceData(appliance, attributes);
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Updated appliance ${applianceId}`);
-        }
     }
     /**
      * Refetches an appliance from the SDK and reflects the result in the
@@ -517,9 +502,6 @@ class ApplianceManager {
     async removeAppliance(applianceId) {
         this.throwIfDisposed();
         await this.energyApp.useAppliances().removeById(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Removed appliance ${applianceId}`);
-        }
     }
     /**
      * Removes every appliance matching the given identifier. Per-appliance
@@ -600,9 +582,6 @@ class ApplianceManager {
                 failed.push(update.applianceId);
             }
         }
-        if (this.config.enableLogging) {
-            console.debug(`Bulk update completed: ${succeeded.length} succeeded, ${failed.length} failed`);
-        }
         return { succeeded, failed };
     }
     /**
@@ -625,9 +604,6 @@ class ApplianceManager {
     async setIdentifierStrategy(strategy, rebuildCache) {
         this.throwIfDisposed();
         this.config.identifierStrategy = strategy;
-        if (this.config.enableLogging) {
-            console.debug(`Changed identifier strategy to: ${strategy.name}`);
-        }
         if (rebuildCache) {
             await this.refreshCache();
             return;
@@ -663,9 +639,6 @@ class ApplianceManager {
         }
         this.listenerIds = [];
         this.clearCache();
-        if (this.config.enableLogging) {
-            console.debug('ApplianceManager disposed');
-        }
     }
     /**
      * Throws {@link ApplianceManagerDisposedError} if {@link dispose} has been

package/dist/cjs/packages/eebus/eebus-device-management.d.cts

@@ -1,4 +1,13 @@
 import { EebusConnectionStatusEnum, EebusDevice, EebusDiscoveredDevice, EebusPeerManufacturerData } from '../../types/enyo-eebus.cjs';
+/**
+ * Options controlling how an active SHIP connection is established via
+ * {@link EebusDeviceManagement.connect}.
+ */
+export interface EebusConnectOptions {
+    /** Advertised heartbeat timeout (seconds, sent as `PT{n}S`) passed to
+     *  `EebusService.connect` for the gateway. Defaults to **4** (PT4S). */
+    heartbeatTimeoutSeconds?: number;
+}
 /**
  * SHIP-level device lifecycle management for EEbus devices.
  *
@@ -13,7 +22,7 @@ import { EebusConnectionStatusEnum, EebusDevice, EebusDiscoveredDevice, EebusPee
  *
  * const discovered = await eebus.devices.getDiscoveredDevices();
  * const device = await eebus.devices.pairDevice(discovered[0].ski);
- * await eebus.devices.connect(device.ski);
+ * await eebus.devices.connect(device.ski, {heartbeatTimeoutSeconds: 4});
  *
  * const listenerId = eebus.devices.listenForConnectionStatusChange((ski, status) => {
  *   console.log(`${ski} → ${status}`);
@@ -49,8 +58,10 @@ export interface EebusDeviceManagement {
      * Establish an active SHIP connection to an already-paired device.
      * The device must have been previously paired via {@link pairDevice}.
      * @param ski Subject Key Identifier of the device to connect to
+     * @param options Connection options, e.g. the advertised heartbeat timeout.
+     *                See {@link EebusConnectOptions}.
      */
-    connect: (ski: string) => Promise<void>;
+    connect: (ski: string, options: EebusConnectOptions) => Promise<void>;
     /**
      * Safely disconnect from a currently connected device.
      * @param ski Subject Key Identifier of the device to disconnect from

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

@@ -3,7 +3,7 @@ import { EebusFeatureCatalog } from './eebus-feature-catalog.cjs';
 import { EebusIdentityService } from './eebus-identity-service.cjs';
 import { EebusSpineLowLevel } from './eebus-spine-low-level.cjs';
 import { EebusUseCaseRegistry } from './eebus-use-case-registry.cjs';
-export { EebusDeviceManagement } from './eebus-device-management.cjs';
+export { EebusDeviceManagement, EebusConnectOptions } from './eebus-device-management.cjs';
 export { EebusFeatureCatalog, EebusFeatureAddressMatch, EebusFindFeatureForClientOptions, } from './eebus-feature-catalog.cjs';
 export { EebusIdentityService } from './eebus-identity-service.cjs';
 export { EebusSpineLowLevel } from './eebus-spine-low-level.cjs';
@@ -47,7 +47,7 @@ export { EebusVapdClient, VapdClientOptions } from './eebus-vapd-client.cjs';
  * // 1. SHIP — pair and connect
  * const [discovered] = await eebus.devices.getDiscoveredDevices();
  * const device = await eebus.devices.pairDevice(discovered.ski);
- * await eebus.devices.connect(device.ski);
+ * await eebus.devices.connect(device.ski, {heartbeatTimeoutSeconds: 4});
  *
  * // 2. NID — read identity and watch for changes
  * const identity = await eebus.identity.get(device.ski);

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

@@ -1,4 +1,4 @@
-import { EnyoCharge, EnyoChargeFilter } from "../types/enyo-charge.cjs";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.cjs";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
@@ -14,4 +14,24 @@ export interface EnergyAppCharge {
     findActiveCharge: (applianceId: string) => Promise<EnyoCharge | null>;
     /** Find the currently active charge by appliance ID and transaction ID */
     findActiveChargeByTransactionId: (applianceId: string, transactionId: string) => Promise<EnyoCharge | null>;
+    /**
+     * Sets the default charging mode for a specific appliance, optionally
+     * with a target completion time and its timezone.
+     *
+     * **Required permission:** `EnergyManager`.
+     *
+     * @param applianceId - The appliance (charger) the default charge mode applies to.
+     * @param defaultChargeMode - The default charge mode configuration to apply.
+     * @returns Promise that resolves once the default charge mode is stored.
+     */
+    setDefaultChargeMode: (applianceId: string, defaultChargeMode: EnyoDefaultChargeMode) => Promise<void>;
+    /**
+     * Retrieves the currently configured default charging mode for a specific appliance.
+     *
+     * No permission is required to read the default charge mode.
+     *
+     * @param applianceId - The appliance (charger) to read the default charge mode for.
+     * @returns Promise resolving to the configured default charge mode
+     */
+    getDefaultChargeMode: (applianceId: string) => Promise<EnyoDefaultChargeMode>;
 }

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

@@ -83,6 +83,27 @@ export interface EnyoChargeScheduleEntry {
     /** Current limit in Ampere for this schedule period */
     limitAmpere: number;
 }
+/**
+ * Default charging preference applied to charging sessions when no
+ * per-session mode is explicitly provided.
+ */
+export interface EnyoDefaultChargeMode {
+    /** The default charging mode (e.g. immediate, cost-optimized, price-limit) */
+    chargeMode: EnyoChargeModeEnum;
+    /**
+     * Optional target completion time as a wall-clock time in the
+     * accompanying {@link EnyoDefaultChargeMode.timezone} (e.g. `"07:30"`).
+     * When set, optimized modes plan the session to finish by this time.
+     */
+    completeAtTime?: string;
+    /**
+     * IANA timezone the {@link EnyoDefaultChargeMode.completeAtTime} is
+     * expressed in (e.g. `"Europe/Berlin"`). Should be provided whenever
+     * `completeAtTime` is set so the wall-clock time can be resolved
+     * unambiguously.
+     */
+    timezone?: string;
+}
 export interface EnyoChargeFilter {
     /** Filter by specific appliance ID */
     applianceId?: string;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
+exports.EnyoChargingProfileTypeEnum = exports.EnyoCommandAcknowledgeAnswerEnum = exports.EnyoStorageScheduleDirectionEnum = exports.EnyoStorageScheduleModeEnum = exports.EnyoDataBusMessageEnum = exports.EnyoChargeInitiatorEnum = exports.EnyoChargeModeEnum = exports.EnyoChargingStopReason = exports.EnyoChargingMeterValueContext = exports.EnyoStringStateEnum = exports.EnyoInverterStateEnum = exports.EnyoBatteryStateEnum = exports.EnyoDataBusCommandReasonCategoryEnum = exports.EnyoDataBusCommandReasonTypeEnum = void 0;
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -23,7 +23,51 @@ var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
+    /** Command issued because the battery state of charge is low */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Command issued because the battery state of charge is high */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Command issued to follow the planned EV charging schedule */
+    EnyoDataBusCommandReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Command issued as part of a planned/scheduled optimization */
+    EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
+    /** Command issued because the user explicitly requested it */
+    EnyoDataBusCommandReasonTypeEnum["UserRequest"] = "user-request";
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
+    /** Command issued because home consumption is high */
+    EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+    /** Command issued to optimize self-consumption */
+    EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
 })(EnyoDataBusCommandReasonTypeEnum || (exports.EnyoDataBusCommandReasonTypeEnum = EnyoDataBusCommandReasonTypeEnum = {}));
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+var EnyoDataBusCommandReasonCategoryEnum;
+(function (EnyoDataBusCommandReasonCategoryEnum) {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnyoDataBusCommandReasonCategoryEnum["EnergyPrice"] = "energy-price";
+    /** Driven by available/unavailable PV surplus. */
+    EnyoDataBusCommandReasonCategoryEnum["PvSurplus"] = "pv-surplus";
+    /** Driven by battery capacity or state of charge. */
+    EnyoDataBusCommandReasonCategoryEnum["BatteryState"] = "battery-state";
+    /** Driven by a grid operator power limitation. */
+    EnyoDataBusCommandReasonCategoryEnum["GridLimitation"] = "grid-limitation";
+    /** Driven by following a planned schedule. */
+    EnyoDataBusCommandReasonCategoryEnum["Schedule"] = "schedule";
+    /** Driven by an explicit user request. */
+    EnyoDataBusCommandReasonCategoryEnum["UserRequest"] = "user-request";
+    /** Driven by device protection / safety (e.g. overheating). */
+    EnyoDataBusCommandReasonCategoryEnum["DeviceProtection"] = "device-protection";
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    EnyoDataBusCommandReasonCategoryEnum["Temperature"] = "temperature";
+    /** Driven by self-consumption optimization. */
+    EnyoDataBusCommandReasonCategoryEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
+    /** Any reason not covered by the categories above. */
+    EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
+})(EnyoDataBusCommandReasonCategoryEnum || (exports.EnyoDataBusCommandReasonCategoryEnum = EnyoDataBusCommandReasonCategoryEnum = {}));
 var EnyoBatteryStateEnum;
 (function (EnyoBatteryStateEnum) {
     EnyoBatteryStateEnum["Off"] = "off";
@@ -107,6 +151,16 @@ var EnyoChargeModeEnum;
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     EnyoChargeModeEnum["PriceLimit"] = "price-limit";
 })(EnyoChargeModeEnum || (exports.EnyoChargeModeEnum = EnyoChargeModeEnum = {}));
+/**
+ * Identifies who initiated a charging session.
+ */
+var EnyoChargeInitiatorEnum;
+(function (EnyoChargeInitiatorEnum) {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    EnyoChargeInitiatorEnum["App"] = "app";
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    EnyoChargeInitiatorEnum["Charger"] = "charger";
+})(EnyoChargeInitiatorEnum || (exports.EnyoChargeInitiatorEnum = EnyoChargeInitiatorEnum = {}));
 var EnyoDataBusMessageEnum;
 (function (EnyoDataBusMessageEnum) {
     EnyoDataBusMessageEnum["InverterValuesUpdateV1"] = "InverterValuesUpdateV1";

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

@@ -8,6 +8,7 @@ import { EnyoCurrencyEnum } from "./enyo-currency.cjs";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.cjs";
 import { EnyoAirConditioningApplianceModeEnum } from "./enyo-air-conditioning-appliance.cjs";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.cjs";
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.cjs";
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -28,7 +29,50 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /** Command issued because a grid operator power limitation is active */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
-    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive"
+    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
+    /** Command issued because the battery state of charge is low */
+    BatterySoCLow = "battery-soc-low",
+    /** Command issued because the battery state of charge is high */
+    BatterySoCHigh = "battery-soc-high",
+    /** Command issued to follow the planned EV charging schedule */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Command issued as part of a planned/scheduled optimization */
+    ScheduledOptimization = "scheduled-optimization",
+    /** Command issued because the user explicitly requested it */
+    UserRequest = "user-request",
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    DeviceProtection = "device-protection",
+    /** Command issued because home consumption is high */
+    HomeConsumptionHigh = "home-consumption-high",
+    /** Command issued to optimize self-consumption */
+    SelfConsumptionOptimization = "self-consumption-optimization"
+}
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export declare enum EnyoDataBusCommandReasonCategoryEnum {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnergyPrice = "energy-price",
+    /** Driven by available/unavailable PV surplus. */
+    PvSurplus = "pv-surplus",
+    /** Driven by battery capacity or state of charge. */
+    BatteryState = "battery-state",
+    /** Driven by a grid operator power limitation. */
+    GridLimitation = "grid-limitation",
+    /** Driven by following a planned schedule. */
+    Schedule = "schedule",
+    /** Driven by an explicit user request. */
+    UserRequest = "user-request",
+    /** Driven by device protection / safety (e.g. overheating). */
+    DeviceProtection = "device-protection",
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    Temperature = "temperature",
+    /** Driven by self-consumption optimization. */
+    SelfConsumptionOptimization = "self-consumption-optimization",
+    /** Any reason not covered by the categories above. */
+    Other = "other"
 }
 /**
  * Interface describing the reason why a data bus command was issued.
@@ -37,6 +81,10 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
 export interface EnyoDataBusCommandReason {
     /** The reason type indicating why this command was issued */
     type: EnyoDataBusCommandReasonTypeEnum;
+    /** Coarse category for grouping, iconography, and analytics */
+    category?: EnyoDataBusCommandReasonCategoryEnum;
+    /** Per-language, end-user-facing explanation of this reason */
+    translation?: EnyoPackageConfigurationTranslatedValue[];
     /** Electricity price per kWh that triggered this command */
     electricityPricePerKwh?: number;
     /** Currency of the electricity price */
@@ -47,6 +95,10 @@ export interface EnyoDataBusCommandReason {
     powerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
+    /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage (battery-driven reasons) */
+    socPercent?: number;
 }
 export declare enum EnyoBatteryStateEnum {
     Off = "off",
@@ -125,6 +177,15 @@ export declare enum EnyoChargeModeEnum {
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     PriceLimit = "price-limit"
 }
+/**
+ * Identifies who initiated a charging session.
+ */
+export declare enum EnyoChargeInitiatorEnum {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    App = "app",
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    Charger = "charger"
+}
 export interface EnyoAggregatedStateApplianceValues {
     powerW?: number;
     batterySoC?: number;
@@ -440,6 +501,8 @@ export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
         transactionId: string;
         /** used charging card */
         chargingCardId?: string;
+        /** Who initiated the charging session — the enyo app or the charger itself */
+        initiator: EnyoChargeInitiatorEnum;
         /** The charge mode of the started charge. If initiated by wallbox, use either user settings or immediate as default */
         chargeMode: EnyoChargeModeEnum;
         /** ISO timestamp for target completion time (optional) */

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

package/dist/implementations/appliances/appliance-manager.js

@@ -209,9 +209,6 @@ export class ApplianceManager {
         // returns the new appliance without racing the appliance-updated
         // listener (which may fire on a later microtask).
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`${existingApplianceId ? 'Updated' : 'Created'} appliance ${applianceId} of type ${appliance.type}`);
-        }
         return applianceId;
     }
     /**
@@ -272,18 +269,12 @@ export class ApplianceManager {
         const updatedListenerId = applianceService.listenForApplianceUpdated((appliance) => {
             if (this.disposed)
                 return;
-            if (this.config.enableLogging) {
-                console.debug(`Appliance updated event received for ${appliance.id}`);
-            }
             this.updateCache(appliance);
         });
         this.listenerIds.push(updatedListenerId);
         const removedListenerId = applianceService.listenForApplianceRemoved((applianceId) => {
             if (this.disposed)
                 return;
-            if (this.config.enableLogging) {
-                console.debug(`Appliance removed event received for ${applianceId}`);
-            }
             this.removeFromCache(applianceId);
         });
         this.listenerIds.push(removedListenerId);
@@ -463,9 +454,6 @@ export class ApplianceManager {
         };
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Updated appliance ${applianceId} state to ${state}`);
-        }
     }
     /**
      * Patches an appliance with the provided attributes via {@link mergeApplianceData}.
@@ -485,9 +473,6 @@ export class ApplianceManager {
         const updated = this.mergeApplianceData(appliance, attributes);
         await this.energyApp.useAppliances().save(updated, applianceId);
         await this.primeCacheFromSdk(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Updated appliance ${applianceId}`);
-        }
     }
     /**
      * Refetches an appliance from the SDK and reflects the result in the
@@ -511,9 +496,6 @@ export class ApplianceManager {
     async removeAppliance(applianceId) {
         this.throwIfDisposed();
         await this.energyApp.useAppliances().removeById(applianceId);
-        if (this.config.enableLogging) {
-            console.debug(`Removed appliance ${applianceId}`);
-        }
     }
     /**
      * Removes every appliance matching the given identifier. Per-appliance
@@ -594,9 +576,6 @@ export class ApplianceManager {
                 failed.push(update.applianceId);
             }
         }
-        if (this.config.enableLogging) {
-            console.debug(`Bulk update completed: ${succeeded.length} succeeded, ${failed.length} failed`);
-        }
         return { succeeded, failed };
     }
     /**
@@ -619,9 +598,6 @@ export class ApplianceManager {
     async setIdentifierStrategy(strategy, rebuildCache) {
         this.throwIfDisposed();
         this.config.identifierStrategy = strategy;
-        if (this.config.enableLogging) {
-            console.debug(`Changed identifier strategy to: ${strategy.name}`);
-        }
         if (rebuildCache) {
             await this.refreshCache();
             return;
@@ -657,9 +633,6 @@ export class ApplianceManager {
         }
         this.listenerIds = [];
         this.clearCache();
-        if (this.config.enableLogging) {
-            console.debug('ApplianceManager disposed');
-        }
     }
     /**
      * Throws {@link ApplianceManagerDisposedError} if {@link dispose} has been

package/dist/packages/eebus/eebus-device-management.d.ts

@@ -1,4 +1,13 @@
 import { EebusConnectionStatusEnum, EebusDevice, EebusDiscoveredDevice, EebusPeerManufacturerData } from '../../types/enyo-eebus.js';
+/**
+ * Options controlling how an active SHIP connection is established via
+ * {@link EebusDeviceManagement.connect}.
+ */
+export interface EebusConnectOptions {
+    /** Advertised heartbeat timeout (seconds, sent as `PT{n}S`) passed to
+     *  `EebusService.connect` for the gateway. Defaults to **4** (PT4S). */
+    heartbeatTimeoutSeconds?: number;
+}
 /**
  * SHIP-level device lifecycle management for EEbus devices.
  *
@@ -13,7 +22,7 @@ import { EebusConnectionStatusEnum, EebusDevice, EebusDiscoveredDevice, EebusPee
  *
  * const discovered = await eebus.devices.getDiscoveredDevices();
  * const device = await eebus.devices.pairDevice(discovered[0].ski);
- * await eebus.devices.connect(device.ski);
+ * await eebus.devices.connect(device.ski, {heartbeatTimeoutSeconds: 4});
  *
  * const listenerId = eebus.devices.listenForConnectionStatusChange((ski, status) => {
  *   console.log(`${ski} → ${status}`);
@@ -49,8 +58,10 @@ export interface EebusDeviceManagement {
      * Establish an active SHIP connection to an already-paired device.
      * The device must have been previously paired via {@link pairDevice}.
      * @param ski Subject Key Identifier of the device to connect to
+     * @param options Connection options, e.g. the advertised heartbeat timeout.
+     *                See {@link EebusConnectOptions}.
      */
-    connect: (ski: string) => Promise<void>;
+    connect: (ski: string, options: EebusConnectOptions) => Promise<void>;
     /**
      * Safely disconnect from a currently connected device.
      * @param ski Subject Key Identifier of the device to disconnect from

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

@@ -3,7 +3,7 @@ import { EebusFeatureCatalog } from './eebus-feature-catalog.js';
 import { EebusIdentityService } from './eebus-identity-service.js';
 import { EebusSpineLowLevel } from './eebus-spine-low-level.js';
 import { EebusUseCaseRegistry } from './eebus-use-case-registry.js';
-export { EebusDeviceManagement } from './eebus-device-management.js';
+export { EebusDeviceManagement, EebusConnectOptions } from './eebus-device-management.js';
 export { EebusFeatureCatalog, EebusFeatureAddressMatch, EebusFindFeatureForClientOptions, } from './eebus-feature-catalog.js';
 export { EebusIdentityService } from './eebus-identity-service.js';
 export { EebusSpineLowLevel } from './eebus-spine-low-level.js';
@@ -47,7 +47,7 @@ export { EebusVapdClient, VapdClientOptions } from './eebus-vapd-client.js';
  * // 1. SHIP — pair and connect
  * const [discovered] = await eebus.devices.getDiscoveredDevices();
  * const device = await eebus.devices.pairDevice(discovered.ski);
- * await eebus.devices.connect(device.ski);
+ * await eebus.devices.connect(device.ski, {heartbeatTimeoutSeconds: 4});
  *
  * // 2. NID — read identity and watch for changes
  * const identity = await eebus.identity.get(device.ski);

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

@@ -1,4 +1,4 @@
-import { EnyoCharge, EnyoChargeFilter } from "../types/enyo-charge.js";
+import { EnyoCharge, EnyoChargeFilter, EnyoDefaultChargeMode } from "../types/enyo-charge.js";
 /**
  * Interface for managing charging sessions in enyo packages.
  * Provides operations for charge session tracking and management.
@@ -14,4 +14,24 @@ export interface EnergyAppCharge {
     findActiveCharge: (applianceId: string) => Promise<EnyoCharge | null>;
     /** Find the currently active charge by appliance ID and transaction ID */
     findActiveChargeByTransactionId: (applianceId: string, transactionId: string) => Promise<EnyoCharge | null>;
+    /**
+     * Sets the default charging mode for a specific appliance, optionally
+     * with a target completion time and its timezone.
+     *
+     * **Required permission:** `EnergyManager`.
+     *
+     * @param applianceId - The appliance (charger) the default charge mode applies to.
+     * @param defaultChargeMode - The default charge mode configuration to apply.
+     * @returns Promise that resolves once the default charge mode is stored.
+     */
+    setDefaultChargeMode: (applianceId: string, defaultChargeMode: EnyoDefaultChargeMode) => Promise<void>;
+    /**
+     * Retrieves the currently configured default charging mode for a specific appliance.
+     *
+     * No permission is required to read the default charge mode.
+     *
+     * @param applianceId - The appliance (charger) to read the default charge mode for.
+     * @returns Promise resolving to the configured default charge mode
+     */
+    getDefaultChargeMode: (applianceId: string) => Promise<EnyoDefaultChargeMode>;
 }

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

@@ -83,6 +83,27 @@ export interface EnyoChargeScheduleEntry {
     /** Current limit in Ampere for this schedule period */
     limitAmpere: number;
 }
+/**
+ * Default charging preference applied to charging sessions when no
+ * per-session mode is explicitly provided.
+ */
+export interface EnyoDefaultChargeMode {
+    /** The default charging mode (e.g. immediate, cost-optimized, price-limit) */
+    chargeMode: EnyoChargeModeEnum;
+    /**
+     * Optional target completion time as a wall-clock time in the
+     * accompanying {@link EnyoDefaultChargeMode.timezone} (e.g. `"07:30"`).
+     * When set, optimized modes plan the session to finish by this time.
+     */
+    completeAtTime?: string;
+    /**
+     * IANA timezone the {@link EnyoDefaultChargeMode.completeAtTime} is
+     * expressed in (e.g. `"Europe/Berlin"`). Should be provided whenever
+     * `completeAtTime` is set so the wall-clock time can be resolved
+     * unambiguously.
+     */
+    timezone?: string;
+}
 export interface EnyoChargeFilter {
     /** Filter by specific appliance ID */
     applianceId?: string;

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

@@ -8,6 +8,7 @@ import { EnyoCurrencyEnum } from "./enyo-currency.js";
 import { EnyoHeatpumpApplianceModeEnum } from "./enyo-heatpump-appliance.js";
 import { EnyoAirConditioningApplianceModeEnum } from "./enyo-air-conditioning-appliance.js";
 import { EnergyAppPackageCategory } from "../energy-app-package-definition.js";
+import { EnyoPackageConfigurationTranslatedValue } from "./enyo-settings.js";
 /**
  * Enum representing the reason type for why a data bus command was issued.
  * Used to attach context to commands for logging, debugging, and UI display.
@@ -28,7 +29,50 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
     /** Command issued because a grid operator power limitation is active */
     GridOperatorPowerLimitationActive = "grid-operator-power-limitation-active",
     /** Command issued because a grid operator power limitation is inactive */
-    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive"
+    GridOperatorPowerLimitationInactive = "grid-operator-power-limitation-inactive",
+    /** Command issued because the battery state of charge is low */
+    BatterySoCLow = "battery-soc-low",
+    /** Command issued because the battery state of charge is high */
+    BatterySoCHigh = "battery-soc-high",
+    /** Command issued to follow the planned EV charging schedule */
+    EvChargingSchedule = "ev-charging-schedule",
+    /** Command issued as part of a planned/scheduled optimization */
+    ScheduledOptimization = "scheduled-optimization",
+    /** Command issued because the user explicitly requested it */
+    UserRequest = "user-request",
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    DeviceProtection = "device-protection",
+    /** Command issued because home consumption is high */
+    HomeConsumptionHigh = "home-consumption-high",
+    /** Command issued to optimize self-consumption */
+    SelfConsumptionOptimization = "self-consumption-optimization"
+}
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export declare enum EnyoDataBusCommandReasonCategoryEnum {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnergyPrice = "energy-price",
+    /** Driven by available/unavailable PV surplus. */
+    PvSurplus = "pv-surplus",
+    /** Driven by battery capacity or state of charge. */
+    BatteryState = "battery-state",
+    /** Driven by a grid operator power limitation. */
+    GridLimitation = "grid-limitation",
+    /** Driven by following a planned schedule. */
+    Schedule = "schedule",
+    /** Driven by an explicit user request. */
+    UserRequest = "user-request",
+    /** Driven by device protection / safety (e.g. overheating). */
+    DeviceProtection = "device-protection",
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    Temperature = "temperature",
+    /** Driven by self-consumption optimization. */
+    SelfConsumptionOptimization = "self-consumption-optimization",
+    /** Any reason not covered by the categories above. */
+    Other = "other"
 }
 /**
  * Interface describing the reason why a data bus command was issued.
@@ -37,6 +81,10 @@ export declare enum EnyoDataBusCommandReasonTypeEnum {
 export interface EnyoDataBusCommandReason {
     /** The reason type indicating why this command was issued */
     type: EnyoDataBusCommandReasonTypeEnum;
+    /** Coarse category for grouping, iconography, and analytics */
+    category?: EnyoDataBusCommandReasonCategoryEnum;
+    /** Per-language, end-user-facing explanation of this reason */
+    translation?: EnyoPackageConfigurationTranslatedValue[];
     /** Electricity price per kWh that triggered this command */
     electricityPricePerKwh?: number;
     /** Currency of the electricity price */
@@ -47,6 +95,10 @@ export interface EnyoDataBusCommandReason {
     powerW?: number;
     /** Relevant energy in Watt hours */
     powerWh?: number;
+    /** Relevant temperature in Celsius (e.g. heatpump-driven reasons) */
+    temperatureC?: number;
+    /** Relevant state of charge as a percentage (battery-driven reasons) */
+    socPercent?: number;
 }
 export declare enum EnyoBatteryStateEnum {
     Off = "off",
@@ -125,6 +177,15 @@ export declare enum EnyoChargeModeEnum {
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     PriceLimit = "price-limit"
 }
+/**
+ * Identifies who initiated a charging session.
+ */
+export declare enum EnyoChargeInitiatorEnum {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    App = "app",
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    Charger = "charger"
+}
 export interface EnyoAggregatedStateApplianceValues {
     powerW?: number;
     batterySoC?: number;
@@ -440,6 +501,8 @@ export interface EnyoDataBusChargingStartedV1 extends EnyoDataBusMessage {
         transactionId: string;
         /** used charging card */
         chargingCardId?: string;
+        /** Who initiated the charging session — the enyo app or the charger itself */
+        initiator: EnyoChargeInitiatorEnum;
         /** The charge mode of the started charge. If initiated by wallbox, use either user settings or immediate as default */
         chargeMode: EnyoChargeModeEnum;
         /** ISO timestamp for target completion time (optional) */

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

@@ -20,7 +20,51 @@ export var EnyoDataBusCommandReasonTypeEnum;
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationActive"] = "grid-operator-power-limitation-active";
     /** Command issued because a grid operator power limitation is inactive */
     EnyoDataBusCommandReasonTypeEnum["GridOperatorPowerLimitationInactive"] = "grid-operator-power-limitation-inactive";
+    /** Command issued because the battery state of charge is low */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCLow"] = "battery-soc-low";
+    /** Command issued because the battery state of charge is high */
+    EnyoDataBusCommandReasonTypeEnum["BatterySoCHigh"] = "battery-soc-high";
+    /** Command issued to follow the planned EV charging schedule */
+    EnyoDataBusCommandReasonTypeEnum["EvChargingSchedule"] = "ev-charging-schedule";
+    /** Command issued as part of a planned/scheduled optimization */
+    EnyoDataBusCommandReasonTypeEnum["ScheduledOptimization"] = "scheduled-optimization";
+    /** Command issued because the user explicitly requested it */
+    EnyoDataBusCommandReasonTypeEnum["UserRequest"] = "user-request";
+    /** Command issued to protect the device (e.g. overheating or safety limit) */
+    EnyoDataBusCommandReasonTypeEnum["DeviceProtection"] = "device-protection";
+    /** Command issued because home consumption is high */
+    EnyoDataBusCommandReasonTypeEnum["HomeConsumptionHigh"] = "home-consumption-high";
+    /** Command issued to optimize self-consumption */
+    EnyoDataBusCommandReasonTypeEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
 })(EnyoDataBusCommandReasonTypeEnum || (EnyoDataBusCommandReasonTypeEnum = {}));
+/**
+ * Coarse, machine-readable grouping of why a data bus command was issued.
+ * Intended for filtering, iconography, and analytics. The human-readable,
+ * end-user explanation lives in {@link EnyoDataBusCommandReason.translation}.
+ */
+export var EnyoDataBusCommandReasonCategoryEnum;
+(function (EnyoDataBusCommandReasonCategoryEnum) {
+    /** Driven by the electricity price (cheap/expensive). */
+    EnyoDataBusCommandReasonCategoryEnum["EnergyPrice"] = "energy-price";
+    /** Driven by available/unavailable PV surplus. */
+    EnyoDataBusCommandReasonCategoryEnum["PvSurplus"] = "pv-surplus";
+    /** Driven by battery capacity or state of charge. */
+    EnyoDataBusCommandReasonCategoryEnum["BatteryState"] = "battery-state";
+    /** Driven by a grid operator power limitation. */
+    EnyoDataBusCommandReasonCategoryEnum["GridLimitation"] = "grid-limitation";
+    /** Driven by following a planned schedule. */
+    EnyoDataBusCommandReasonCategoryEnum["Schedule"] = "schedule";
+    /** Driven by an explicit user request. */
+    EnyoDataBusCommandReasonCategoryEnum["UserRequest"] = "user-request";
+    /** Driven by device protection / safety (e.g. overheating). */
+    EnyoDataBusCommandReasonCategoryEnum["DeviceProtection"] = "device-protection";
+    /** Driven by a temperature condition (e.g. heatpump thermal control). */
+    EnyoDataBusCommandReasonCategoryEnum["Temperature"] = "temperature";
+    /** Driven by self-consumption optimization. */
+    EnyoDataBusCommandReasonCategoryEnum["SelfConsumptionOptimization"] = "self-consumption-optimization";
+    /** Any reason not covered by the categories above. */
+    EnyoDataBusCommandReasonCategoryEnum["Other"] = "other";
+})(EnyoDataBusCommandReasonCategoryEnum || (EnyoDataBusCommandReasonCategoryEnum = {}));
 export var EnyoBatteryStateEnum;
 (function (EnyoBatteryStateEnum) {
     EnyoBatteryStateEnum["Off"] = "off";
@@ -104,6 +148,16 @@ export var EnyoChargeModeEnum;
     /** Optimize charging schedule for a maximum price limit, for example 7 ct grid or pv production */
     EnyoChargeModeEnum["PriceLimit"] = "price-limit";
 })(EnyoChargeModeEnum || (EnyoChargeModeEnum = {}));
+/**
+ * Identifies who initiated a charging session.
+ */
+export var EnyoChargeInitiatorEnum;
+(function (EnyoChargeInitiatorEnum) {
+    /** Session was started from the enyo app (remote/user-driven start) */
+    EnyoChargeInitiatorEnum["App"] = "app";
+    /** Session was started directly at the charger (e.g. plug-and-charge or local autostart) */
+    EnyoChargeInitiatorEnum["Charger"] = "charger";
+})(EnyoChargeInitiatorEnum || (EnyoChargeInitiatorEnum = {}));
 export var EnyoDataBusMessageEnum;
 (function (EnyoDataBusMessageEnum) {
     EnyoDataBusMessageEnum["InverterValuesUpdateV1"] = "InverterValuesUpdateV1";

package/dist/version.d.ts

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