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

package/README.md

@@ -860,6 +860,8 @@ energyApp.useDataBus().sendMessage([{
     data: {
         vehicleId,
         socPercent: 62,
+        // optional: remaining range in km, when the source reports it (e.g. Smartcar)
+        rangeKm: 280,
         // omit only when the reading came straight off the wire
         measuredAtIso: new Date().toISOString(),
     },
@@ -870,6 +872,19 @@ That message is the only write path for a state of charge; it needs the
 `SendDataBusValues` permission. `getSoc()` resolves to `undefined` when nothing
 is known — an ordinary answer for a car with no SoC source, not an error.
 
+The vehicle's battery size is written the same way: publish
+`VehicleBatterySizeUpdateV1` with the usable capacity in watt-hours, and the
+host stores it on the vehicle (replacing the previous value, including one the
+user entered). It is read back as `batterySizeKwh`.
+
+```typescript
+energyApp.useDataBus().sendMessage([{
+    type: 'message',
+    message: 'VehicleBatterySizeUpdateV1',
+    data: {vehicleId, batterySizeWh: 75_000},
+}]);
+```
+
 ##### Car integrations: pairing a vehicle
 
 A package in the `vehicle` category talks to a manufacturer's cloud and links

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApplianceManager = exports.ApplianceManagerDisposedError = exports.DuplicateIdentifierError = exports.MissingIdentifierError = void 0;
+exports.ApplianceManager = exports.ApplianceGroupNotFoundError = exports.ApplianceManagerDisposedError = exports.DuplicateIdentifierError = exports.MissingIdentifierError = void 0;
 const index_js_1 = require("../../index.cjs");
 const enyo_appliance_js_1 = require("../../types/enyo-appliance.cjs");
 /**
@@ -49,6 +49,20 @@ class ApplianceManagerDisposedError extends Error {
     }
 }
 exports.ApplianceManagerDisposedError = ApplianceManagerDisposedError;
+/**
+ * Thrown by the {@link ApplianceManager} group helpers when no group with the
+ * given key exists in the package.
+ */
+class ApplianceGroupNotFoundError extends Error {
+    /** The group key that was looked up */
+    key;
+    constructor(key) {
+        super(`No appliance group with key "${key}" exists.`);
+        this.name = 'ApplianceGroupNotFoundError';
+        this.key = key;
+    }
+}
+exports.ApplianceGroupNotFoundError = ApplianceGroupNotFoundError;
 /** Sub-objects on EnyoAppliance that {@link ApplianceManager} shallow-merges during updates. */
 const MERGEABLE_METADATA_KEYS = [
     'metadata',
@@ -220,6 +234,7 @@ class ApplianceManager {
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
             ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
+            ...(appliance.hidden !== undefined && { hidden: appliance.hidden }),
         };
         let applianceData = newApplianceData;
         if (existingApplianceId) {
@@ -741,6 +756,170 @@ class ApplianceManager {
             }
         }
     }
+    /**
+     * Creates the group with the given {@link ApplianceGroupConfig.key}, or
+     * updates it when it already exists. The group is shown in the UI as one
+     * collapsible entry with the summed values of its members.
+     *
+     * An appliance belongs to at most one group, so members currently listed
+     * in another group of the package are taken out of it first; a group left
+     * empty by that is removed.
+     *
+     * @param config The group's key, name and member appliance IDs
+     * @returns The ID of the saved group
+     * @throws {Error} when `config.applianceIds` is empty
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async createOrUpdateGroup(config) {
+        this.throwIfDisposed();
+        const applianceIds = [...new Set(config.applianceIds)];
+        if (applianceIds.length === 0) {
+            throw new Error(`Appliance group "${config.key}" needs at least one appliance; use removeGroup to drop it.`);
+        }
+        const groups = await this.loadGroups();
+        const existing = groups.find(g => g.key === config.key);
+        // Take the members out of every other group before saving, otherwise
+        // the host rejects the save for an appliance being in two groups.
+        const members = new Set(applianceIds);
+        for (const other of groups) {
+            if (other === existing || !other.applianceIds.some(id => members.has(id)))
+                continue;
+            const remaining = other.applianceIds.filter(id => !members.has(id));
+            if (remaining.length === 0) {
+                await this.deleteGroup(other.id);
+            }
+            else {
+                await this.persistGroup({ ...this.withoutId(other), applianceIds: remaining }, other.id);
+            }
+        }
+        return this.persistGroup({ key: config.key, name: config.name, applianceIds }, existing?.id);
+    }
+    /**
+     * Returns all appliance groups of the package.
+     *
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async getGroups() {
+        this.throwIfDisposed();
+        return this.loadGroups();
+    }
+    /**
+     * Returns the group with the given key, or `null` when there is none.
+     *
+     * @param key The app-defined group key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async findGroupByKey(key) {
+        this.throwIfDisposed();
+        return (await this.loadGroups()).find(g => g.key === key) ?? null;
+    }
+    /**
+     * Returns the group an appliance belongs to, or `null` when it is not
+     * grouped.
+     *
+     * @param applianceId The appliance to look up
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async findGroupOfAppliance(applianceId) {
+        this.throwIfDisposed();
+        return (await this.loadGroups()).find(g => g.applianceIds.includes(applianceId)) ?? null;
+    }
+    /**
+     * Adds an appliance to the end of an existing group, moving it out of any
+     * other group it was in. Does nothing when it is already a member.
+     *
+     * @param key The key of the group to add the appliance to
+     * @param applianceId The appliance to add
+     * @returns The ID of the group
+     * @throws {ApplianceGroupNotFoundError} when no group has the given key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async addApplianceToGroup(key, applianceId) {
+        this.throwIfDisposed();
+        const group = await this.findGroupByKey(key);
+        if (!group) {
+            throw new ApplianceGroupNotFoundError(key);
+        }
+        if (group.applianceIds.includes(applianceId)) {
+            return group.id;
+        }
+        return this.createOrUpdateGroup({
+            key,
+            name: group.name,
+            applianceIds: [...group.applianceIds, applianceId],
+        });
+    }
+    /**
+     * Takes an appliance out of its group, so the UI shows it individually
+     * again. A group left without members is removed.
+     *
+     * @param applianceId The appliance to take out of its group
+     * @returns `true` when the appliance was in a group, `false` otherwise
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async removeApplianceFromGroup(applianceId) {
+        this.throwIfDisposed();
+        const group = await this.findGroupOfAppliance(applianceId);
+        if (!group) {
+            return false;
+        }
+        const remaining = group.applianceIds.filter(id => id !== applianceId);
+        if (remaining.length === 0) {
+            await this.deleteGroup(group.id);
+        }
+        else {
+            await this.persistGroup({ ...this.withoutId(group), applianceIds: remaining }, group.id);
+        }
+        return true;
+    }
+    /**
+     * Removes the group with the given key. Its members stay and are shown
+     * individually again.
+     *
+     * @param key The key of the group to remove
+     * @returns `true` when a group was removed, `false` when none had the key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    async removeGroup(key) {
+        this.throwIfDisposed();
+        const group = await this.findGroupByKey(key);
+        if (!group) {
+            return false;
+        }
+        await this.deleteGroup(group.id);
+        return true;
+    }
+    /**
+     * Loads the package's appliance groups from storage. `protected` so
+     * subclasses (e.g. {@link InMemoryApplianceManager}) can swap the storage
+     * the group helpers run on.
+     */
+    async loadGroups() {
+        return this.energyApp.useAppliances().listGroups();
+    }
+    /**
+     * Saves an appliance group to storage.
+     *
+     * @param group The group to save
+     * @param groupId ID of the group to update, or `undefined` to create one
+     * @returns The ID of the saved group
+     */
+    async persistGroup(group, groupId) {
+        return this.energyApp.useAppliances().saveGroup(group, groupId);
+    }
+    /**
+     * Deletes an appliance group from storage.
+     *
+     * @param groupId ID of the group to delete
+     */
+    async deleteGroup(groupId) {
+        await this.energyApp.useAppliances().removeGroup(groupId);
+    }
+    /** Returns a copy of the group without its `id`, ready to be saved again. */
+    withoutId(group) {
+        const { id: _id, ...rest } = group;
+        return rest;
+    }
     /**
      * Gets the current identifier strategy.
      */

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

@@ -1,6 +1,6 @@
 import { EnergyApp } from "../../index.cjs";
 import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
-import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
+import { EnyoAppliance, EnyoApplianceAvailableFeaturesEnum, EnyoApplianceConnectionType, EnyoApplianceGroup, EnyoApplianceMetadata, EnyoApplianceName, EnyoApplianceStateEnum, EnyoApplianceTopology, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
 import type { EnyoApplianceCreatedFilter } from "../../packages/energy-app-appliance.cjs";
 import type { EnyoChargerApplianceMetadata } from "../../types/enyo-charger-appliance.cjs";
 import type { EnyoHeatpumpApplianceDomesticHotWater, EnyoHeatpumpApplianceHeatingCircuit, EnyoHeatpumpApplianceMetadata } from "../../types/enyo-heatpump-appliance.cjs";
@@ -40,6 +40,36 @@ export declare class DuplicateIdentifierError extends Error {
 export declare class ApplianceManagerDisposedError extends Error {
     constructor();
 }
+/**
+ * Thrown by the {@link ApplianceManager} group helpers when no group with the
+ * given key exists in the package.
+ */
+export declare class ApplianceGroupNotFoundError extends Error {
+    /** The group key that was looked up */
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Configuration for creating or updating an appliance group via
+ * {@link ApplianceManager.createOrUpdateGroup}. See {@link EnyoApplianceGroup}
+ * for what a group is and how the UI shows it.
+ */
+export interface ApplianceGroupConfig {
+    /**
+     * Stable, app-defined key identifying the group within the package — e.g.
+     * the serial number of the gateway the members sit behind. A group with
+     * this key is updated in place; otherwise a new one is created.
+     */
+    key: string;
+    /** Name of the group shown in the UI, in the supported languages */
+    name: EnyoApplianceName[];
+    /**
+     * IDs of the member appliances (your package's own), in display order.
+     * Must not be empty — use {@link ApplianceManager.removeGroup} to drop a
+     * group. Appliances currently in another group are moved into this one.
+     */
+    applianceIds: string[];
+}
 /**
  * Configuration for creating or updating an appliance.
  */
@@ -78,6 +108,12 @@ export interface ApplianceConfig {
      * appliance is created or updated.
      */
     cloudPackageId?: string;
+    /**
+     * Whether the appliance is hidden. Forwarded to {@link EnyoAppliance.hidden}
+     * when the appliance is created or updated. Omit to keep the stored value on
+     * an update; pass `false` to unhide it.
+     */
+    hidden?: boolean;
 }
 /**
  * Configuration options for the ApplianceManager.
@@ -434,6 +470,93 @@ export declare class ApplianceManager {
      * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
      */
     setIdentifierStrategy(strategy: IdentifierStrategy, rebuildCache: boolean): Promise<void>;
+    /**
+     * Creates the group with the given {@link ApplianceGroupConfig.key}, or
+     * updates it when it already exists. The group is shown in the UI as one
+     * collapsible entry with the summed values of its members.
+     *
+     * An appliance belongs to at most one group, so members currently listed
+     * in another group of the package are taken out of it first; a group left
+     * empty by that is removed.
+     *
+     * @param config The group's key, name and member appliance IDs
+     * @returns The ID of the saved group
+     * @throws {Error} when `config.applianceIds` is empty
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    createOrUpdateGroup(config: ApplianceGroupConfig): Promise<string>;
+    /**
+     * Returns all appliance groups of the package.
+     *
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    getGroups(): Promise<EnyoApplianceGroup[]>;
+    /**
+     * Returns the group with the given key, or `null` when there is none.
+     *
+     * @param key The app-defined group key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    findGroupByKey(key: string): Promise<EnyoApplianceGroup | null>;
+    /**
+     * Returns the group an appliance belongs to, or `null` when it is not
+     * grouped.
+     *
+     * @param applianceId The appliance to look up
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    findGroupOfAppliance(applianceId: string): Promise<EnyoApplianceGroup | null>;
+    /**
+     * Adds an appliance to the end of an existing group, moving it out of any
+     * other group it was in. Does nothing when it is already a member.
+     *
+     * @param key The key of the group to add the appliance to
+     * @param applianceId The appliance to add
+     * @returns The ID of the group
+     * @throws {ApplianceGroupNotFoundError} when no group has the given key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    addApplianceToGroup(key: string, applianceId: string): Promise<string>;
+    /**
+     * Takes an appliance out of its group, so the UI shows it individually
+     * again. A group left without members is removed.
+     *
+     * @param applianceId The appliance to take out of its group
+     * @returns `true` when the appliance was in a group, `false` otherwise
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    removeApplianceFromGroup(applianceId: string): Promise<boolean>;
+    /**
+     * Removes the group with the given key. Its members stay and are shown
+     * individually again.
+     *
+     * @param key The key of the group to remove
+     * @returns `true` when a group was removed, `false` when none had the key
+     * @throws {ApplianceManagerDisposedError} when called after {@link dispose}
+     */
+    removeGroup(key: string): Promise<boolean>;
+    /**
+     * Loads the package's appliance groups from storage. `protected` so
+     * subclasses (e.g. {@link InMemoryApplianceManager}) can swap the storage
+     * the group helpers run on.
+     */
+    protected loadGroups(): Promise<EnyoApplianceGroup[]>;
+    /**
+     * Saves an appliance group to storage.
+     *
+     * @param group The group to save
+     * @param groupId ID of the group to update, or `undefined` to create one
+     * @returns The ID of the saved group
+     */
+    protected persistGroup(group: Omit<EnyoApplianceGroup, 'id'>, groupId: string | undefined): Promise<string>;
+    /**
+     * Deletes an appliance group from storage.
+     *
+     * @param groupId ID of the group to delete
+     */
+    protected deleteGroup(groupId: string): Promise<void>;
+    /** Returns a copy of the group without its `id`, ready to be saved again. */
+    private withoutId;
     /**
      * Gets the current identifier strategy.
      */
@@ -495,5 +618,6 @@ export interface PartialEnyoAppliance {
      * Optional identifier of the cloud-deployed energy app package that manages
      * this appliance. Mirrors {@link EnyoAppliance.cloudPackageId}.
      */
-    cloudPackageId?: string;
+    cloudPackageId?: string; /** Whether the appliance is hidden. Mirrors {@link EnyoAppliance.hidden}. */
+    hidden?: boolean;
 }

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

@@ -13,6 +13,7 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
     memoryStore = new Map();
     nextId = 1;
     networkDevicesStore = new Map();
+    groupStore = new Map();
     /**
      * Creates a new DemoApplianceManager instance.
      * @param energyApp The EnergyApp instance (not used for persistence in demo)
@@ -75,6 +76,7 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
             ...(appliance.cloudPackageId !== undefined && { cloudPackageId: appliance.cloudPackageId }),
             ...(appliance.availableFeatures !== undefined && { availableFeatures: appliance.availableFeatures }),
             ...(appliance.compatibilityModes !== undefined && { compatibilityModes: appliance.compatibilityModes }),
+            ...(appliance.hidden !== undefined && { hidden: appliance.hidden }),
         };
         // On update, merge onto the stored appliance so type-specific metadata and
         // top-level fields that were not supplied in this call are preserved.
@@ -212,6 +214,19 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
         if (this.memoryStore.has(applianceId)) {
             this.memoryStore.delete(applianceId);
             this.networkDevicesStore.delete(applianceId);
+            // Mirror the host: a removed appliance drops out of its group,
+            // and a group left without members is removed.
+            for (const group of [...this.groupStore.values()]) {
+                if (!group.applianceIds.includes(applianceId))
+                    continue;
+                const remaining = group.applianceIds.filter(id => id !== applianceId);
+                if (remaining.length === 0) {
+                    this.groupStore.delete(group.id);
+                }
+                else {
+                    this.groupStore.set(group.id, { ...group, applianceIds: remaining });
+                }
+            }
             // Clean up cache (from parent class)
             this.clearCache();
             console.log(`[DEMO] Removed appliance ${applianceId}`);
@@ -287,12 +302,38 @@ class InMemoryApplianceManager extends appliance_manager_js_1.ApplianceManager {
             this.updateCache(appliance);
         }
     }
+    /**
+     * Loads the appliance groups from memory.
+     * @returns Copies of all stored groups
+     */
+    async loadGroups() {
+        return Array.from(this.groupStore.values(), g => structuredClone(g));
+    }
+    /**
+     * Saves an appliance group in memory.
+     * @param group The group to save
+     * @param groupId ID of the group to update, or `undefined` to create one
+     * @returns The ID of the saved group
+     */
+    async persistGroup(group, groupId) {
+        const id = groupId ?? (0, node_crypto_1.randomUUID)();
+        this.groupStore.set(id, { ...structuredClone(group), id });
+        return id;
+    }
+    /**
+     * Deletes an appliance group from memory.
+     * @param groupId ID of the group to delete
+     */
+    async deleteGroup(groupId) {
+        this.groupStore.delete(groupId);
+    }
     /**
      * Clears all data from memory (for testing purposes).
      */
     clearAllData() {
         this.memoryStore.clear();
         this.networkDevicesStore.clear();
+        this.groupStore.clear();
         this.clearCache();
         this.nextId = 1;
         console.log('[DEMO] All data cleared from memory');

package/dist/cjs/implementations/appliances/in-memory-appliance-manager.d.cts

@@ -1,5 +1,5 @@
 import type { EnergyApp } from "../../index.cjs";
-import { EnyoAppliance, EnyoApplianceConnectionType, EnyoApplianceMetadata, EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
+import { EnyoAppliance, EnyoApplianceConnectionType, EnyoApplianceGroup, EnyoApplianceMetadata, EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
 import { ApplianceConfig, ApplianceManager, ApplianceManagerConfig, FindResult } from "./appliance-manager.cjs";
 import { IdentifierStrategy } from "./identifier-strategies.cjs";
 /**
@@ -11,6 +11,7 @@ export declare class InMemoryApplianceManager extends ApplianceManager {
     private memoryStore;
     private nextId;
     private networkDevicesStore;
+    private groupStore;
     /**
      * Creates a new DemoApplianceManager instance.
      * @param energyApp The EnergyApp instance (not used for persistence in demo)
@@ -99,6 +100,23 @@ export declare class InMemoryApplianceManager extends ApplianceManager {
      * Refreshes the cache with all appliances from memory.
      */
     refreshCache(): Promise<void>;
+    /**
+     * Loads the appliance groups from memory.
+     * @returns Copies of all stored groups
+     */
+    protected loadGroups(): Promise<EnyoApplianceGroup[]>;
+    /**
+     * Saves an appliance group in memory.
+     * @param group The group to save
+     * @param groupId ID of the group to update, or `undefined` to create one
+     * @returns The ID of the saved group
+     */
+    protected persistGroup(group: Omit<EnyoApplianceGroup, 'id'>, groupId: string | undefined): Promise<string>;
+    /**
+     * Deletes an appliance group from memory.
+     * @param groupId ID of the group to delete
+     */
+    protected deleteGroup(groupId: string): Promise<void>;
     /**
      * Clears all data from memory (for testing purposes).
      */

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

@@ -1,4 +1,4 @@
-import { EnyoAppliance, EnyoApplianceTypeEnum } from "../types/enyo-appliance.cjs";
+import { EnyoAppliance, EnyoApplianceGroup, EnyoApplianceTypeEnum } from "../types/enyo-appliance.cjs";
 /**
  * Ownership scope for an appliance-created subscription.
  * - `'own'`: appliances created by your own package.
@@ -32,14 +32,41 @@ export interface EnyoApplianceCreatedFilter {
 export interface EnergyAppAppliance {
     /** Save or update an appliance in the system */
     save: (appliance: Omit<EnyoAppliance, 'id'>, applianceId: string | undefined) => Promise<string>;
-    /** Get a list of all registered appliances of your package */
+    /**
+     * Get a list of all registered appliances of your package, including the
+     * ones marked {@link EnyoAppliance.hidden}.
+     */
     list: () => Promise<EnyoAppliance[]>;
-    /** Get a list of all appliances. Needs a specific permission */
+    /**
+     * Get a list of all appliances. Needs a specific permission. Appliances of
+     * other packages marked {@link EnyoAppliance.hidden} are left out; your own
+     * package's hidden appliances are included.
+     */
     listAll: () => Promise<EnyoAppliance[]>;
     /** Get a specific appliance by its ID */
     getById: (id: string) => Promise<EnyoAppliance | null>;
     /** Remove an appliance by its ID */
     removeById: (id: string) => Promise<void>;
+    /**
+     * Save or update a group of your package's appliances, shown in the UI as
+     * one collapsible entry — see {@link EnyoApplianceGroup}.
+     *
+     * Rejected when a member is not an appliance of your package or already
+     * belongs to another group; move it by first saving that other group
+     * without it.
+     * @param group - The group to save
+     * @param groupId - ID of the group to update, or `undefined` to create one
+     * @returns The ID of the saved group
+     */
+    saveGroup: (group: Omit<EnyoApplianceGroup, 'id'>, groupId: string | undefined) => Promise<string>;
+    /** Get all appliance groups of your package */
+    listGroups: () => Promise<EnyoApplianceGroup[]>;
+    /**
+     * Remove an appliance group. Only the group goes away — its members stay
+     * and are shown individually again.
+     * @param groupId - ID of the group to remove
+     */
+    removeGroup: (groupId: string) => Promise<void>;
     /**
      * Listen for appliance updates (when an appliance is saved or modified).
      * @param listener - Callback invoked with the updated appliance
@@ -64,7 +91,8 @@ export interface EnergyAppAppliance {
      * The optional {@link EnyoApplianceCreatedFilter filter} controls scope and
      * category: by default only your own package's creations are delivered;
      * `scope: 'all'` and `scope: 'external'` observe appliances created by other
-     * packages and require the `AllAppliances` permission.
+     * packages and require the `AllAppliances` permission. Appliances of other
+     * packages marked {@link EnyoAppliance.hidden} are never delivered.
      *
      * @param listener - Callback invoked with each newly-created appliance
      * @param filter - Optional scope/category filter; defaults to `{ scope: 'own' }`

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

@@ -29,6 +29,13 @@ import { EnyoLinkedVehicle, EnyoVehicle, EnyoVehiclePackageUnpairReasonEnum, Eny
  * That message is the only write path for a state of charge; publishing it
  * requires the `SendDataBusValues` permission.
  *
+ * ## Writing a battery size
+ *
+ * The same holds for the vehicle's battery size: an app that knows it publishes
+ * `EnyoDataBusVehicleBatterySizeUpdateV1` with `batterySizeWh`, and the host
+ * stores it on the vehicle, replacing the previous value. It is read back as
+ * {@link EnyoVehicle.batterySizeKwh}.
+ *
  * ## Pairing a car integration
  *
  * A package in the `vehicle` category — a manufacturer cloud integration —

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

@@ -392,4 +392,69 @@ export interface EnyoAppliance {
      * downstream consumers can correlate the appliance with its owning package.
      */
     cloudPackageId?: string;
+    /**
+     * Marks the appliance as hidden: it is kept in the system but treated as
+     * if it did not exist everywhere else.
+     *
+     * A hidden appliance:
+     * - is not shown in any UI (appliance lists, live views, reports, onboarding
+     *   summaries, notifications);
+     * - is not used for energy management — it is neither controlled nor
+     *   counted in energy flows, forecasts, savings or health evaluation;
+     * - has its data bus values, timeseries and events ignored by the host
+     *   and by other packages;
+     * - is excluded from `useAppliances().listAll()` and from appliance
+     *   events delivered to other packages.
+     *
+     * The owning package still sees it through
+     * `useAppliances().list()` and `getById()`,
+     * so it can keep recognising the device on rediscovery instead of creating
+     * it again, and unhide it later by saving it with `hidden: false`.
+     *
+     * Use it for appliances the package has to keep track of but that must not
+     * surface — e.g. a duplicate entity a device exposes alongside the real one,
+     * or a sub-device the user chose to ignore. Differs from
+     * {@link EnyoApplianceStatusEnum.Deactivated}, which keeps the appliance
+     * visible and only takes it out of energy management. Omitted means visible.
+     */
+    hidden?: boolean;
+}
+/**
+ * A named group of appliances that the app UI shows as one collapsible entry.
+ *
+ * Grouping is purely visual. The UI shows the group under its {@link name}
+ * with the summed values its members share (power, energy, …) and a
+ * collapse/expand toggle that reveals the individual members. The members stay
+ * ordinary appliances: their data is counted exactly as without the group,
+ * commands still target each member, and the group itself is never an
+ * appliance — so nothing is counted twice.
+ *
+ * Groups are defined by the energy app that owns the member appliances, and
+ * every user of the site sees the same groups. Use it when an app brings many
+ * appliances of one installation — e.g. dozens of micro-inverters — that would
+ * otherwise flood the appliance list.
+ *
+ * Rules enforced by the host:
+ * - every member must be an appliance of the package saving the group;
+ * - an appliance belongs to at most one group;
+ * - an appliance that is removed or marked {@link EnyoAppliance.hidden} drops
+ *   out of its group, and a group left without members is removed.
+ *
+ * Members may be of different {@link EnyoApplianceTypeEnum types}; the UI then
+ * sums only the values all members share and shows the rest per member.
+ */
+export interface EnyoApplianceGroup {
+    /** Unique identifier of the group, assigned by the host on first save */
+    id: string;
+    /**
+     * Stable, app-defined key of the group, unique within the package — e.g.
+     * the serial number of the gateway the members sit behind. Lets the app
+     * find its group again after a restart instead of creating a second one.
+     * Recommended; the `ApplianceManager` group helpers require it.
+     */
+    key?: string;
+    /** Name of the group shown in the UI, in the supported languages */
+    name: EnyoApplianceName[];
+    /** IDs of the member appliances, in the order the UI lists them when expanded */
+    applianceIds: string[];
 }

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

@@ -847,6 +847,8 @@ var EnyoDataBusMessageEnum;
     EnyoDataBusMessageEnum["StopAirConditioningV1"] = "StopAirConditioningV1";
     EnyoDataBusMessageEnum["ChangeAirConditioningOptimizationModeV1"] = "ChangeAirConditioningOptimizationModeV1";
     EnyoDataBusMessageEnum["VehicleSocUpdateV1"] = "VehicleSocUpdateV1";
+    /** Provide or update the usable traction battery capacity of a vehicle, in Wh. */
+    EnyoDataBusMessageEnum["VehicleBatterySizeUpdateV1"] = "VehicleBatterySizeUpdateV1";
     /** Request the current or estimated state of charge of a vehicle, by vehicle id. */
     EnyoDataBusMessageEnum["RequestVehicleSocEstimateV1"] = "RequestVehicleSocEstimateV1";
     /** Answer to {@link RequestVehicleSocEstimateV1} — the estimate with its age and source, or why none could be given. */