@enyo-energy/energy-app-sdk 0.0.132 → 0.0.133

package/README.md

@@ -616,6 +616,50 @@ settings.listenForSettingsChanges((settingName, newValue) => {
 const allSettings = await settings.getSettingsConfig();
 ```
 
+#### `useConfigurationManager(): EnergyAppConfigurationManager`
+
+Register **internal**, non user-facing configurations for your package and react to value changes. Unlike `useSettings()`, configurations registered here are NOT rendered in the Energy App UI — they are intended for values the package itself reads and writes at runtime (e.g. internal feature toggles, tuning parameters, calibration values) and need to be persisted across restarts.
+
+Each configuration is addressed by a unique `key` and is either of type `number` (with optional `minValue` / `maxValue` / `step` constraints) or `select` (with a fixed list of allowed `selectOptions`).
+
+```typescript
+const configManager = energyApp.useConfigurationManager();
+
+// Register the full set of internal configurations in a single call
+await configManager.registerConfigurations([
+    {
+        key: 'pollIntervalMs',
+        type: 'number',
+        defaultValue: 5000,
+        numberOptions: { minValue: 1000, maxValue: 60000, step: 1000 }
+    },
+    {
+        key: 'logLevel',
+        type: 'select',
+        defaultValue: 'info',
+        selectOptions: [
+            { value: 'debug' },
+            { value: 'info' },
+            { value: 'warn' },
+            { value: 'error' }
+        ]
+    }
+]);
+
+// Read the current (or default) value for a configuration
+const pollInterval = await configManager.getConfiguration('pollIntervalMs');
+
+// React to value changes
+configManager.onConfigurationChanged(event => {
+    console.log(
+        `Configuration ${event.key} changed from ${event.previousValue} to ${event.newValue}`
+    );
+});
+
+// Remove configurations (e.g. on cleanup or after a migration)
+await configManager.unregisterConfigurations(['logLevel']);
+```
+
 #### `useElectricityPrices(): EnergyAppElectricityPrices`
 
 Access electricity pricing information:

package/dist/cjs/energy-app.cjs

@@ -288,6 +288,16 @@ class EnergyApp {
     useGridConnectionPoint() {
         return this.energyAppSdk.useGridConnectionPoint();
     }
+    /**
+     * Gets the Configuration Manager API for registering internal (non user-facing)
+     * package configurations. Configurations are typed as either `number` or
+     * `select`, addressed by a unique key, and emit change events when their
+     * persisted value is updated.
+     * @returns The Configuration Manager API instance
+     */
+    useConfigurationManager() {
+        return this.energyAppSdk.useConfigurationManager();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -34,6 +34,7 @@ import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.cjs
 import { EnergyAppWifi } from "./packages/energy-app-wifi.cjs";
 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";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -223,6 +224,14 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Grid Connection Point API instance
      */
     useGridConnectionPoint(): EnergyAppGridConnectionPoint;
+    /**
+     * Gets the Configuration Manager API for registering internal (non user-facing)
+     * package configurations. Configurations are typed as either `number` or
+     * `select`, addressed by a unique key, and emit change events when their
+     * persisted value is updated.
+     * @returns The Configuration Manager API instance
+     */
+    useConfigurationManager(): EnergyAppConfigurationManager;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -33,6 +33,7 @@ import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.cjs
 import { EnergyAppWifi } from "./packages/energy-app-wifi.cjs";
 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";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -127,4 +128,6 @@ export interface EnyoEnergyAppSdk {
     useUdp: () => EnergyAppUdp;
     /** Get the Grid Connection Point API for retrieving fuse rating, phase count, and power limit of the site's grid connection */
     useGridConnectionPoint: () => EnergyAppGridConnectionPoint;
+    /** Get the Configuration Manager API for registering internal (non user-facing) package configurations with change notifications */
+    useConfigurationManager: () => EnergyAppConfigurationManager;
 }

package/dist/cjs/index.cjs

@@ -66,6 +66,8 @@ __exportStar(require("./packages/energy-app-wifi.cjs"), exports);
 __exportStar(require("./packages/energy-app-udp.cjs"), exports);
 __exportStar(require("./types/enyo-grid-connection-point.cjs"), exports);
 __exportStar(require("./packages/energy-app-grid-connection-point.cjs"), exports);
+__exportStar(require("./types/enyo-configuration-manager.cjs"), exports);
+__exportStar(require("./packages/energy-app-configuration-manager.cjs"), exports);
 __exportStar(require("./types/enyo-air-conditioning-appliance.cjs"), exports);
 __exportStar(require("./types/enyo-onboarding.cjs"), exports);
 __exportStar(require("./packages/energy-app-onboarding.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -50,6 +50,8 @@ export * from './packages/energy-app-wifi.cjs';
 export * from './packages/energy-app-udp.cjs';
 export * from './types/enyo-grid-connection-point.cjs';
 export * from './packages/energy-app-grid-connection-point.cjs';
+export * from './types/enyo-configuration-manager.cjs';
+export * from './packages/energy-app-configuration-manager.cjs';
 export * from './types/enyo-air-conditioning-appliance.cjs';
 export * from './types/enyo-onboarding.cjs';
 export * from './packages/energy-app-onboarding.cjs';

package/dist/cjs/packages/energy-app-configuration-manager.cjs

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

package/dist/cjs/packages/energy-app-configuration-manager.d.cts

@@ -0,0 +1,56 @@
+import { EnyoConfiguration, EnyoConfigurationChangeListener } from "../types/enyo-configuration-manager.cjs";
+/**
+ * Internal configuration manager for an Energy App package.
+ *
+ * Unlike {@link import('./energy-app-settings.js').EnergyAppSettings}, configurations
+ * registered here are NOT user-facing and are not rendered in the Energy App UI.
+ * They are intended for values that the package itself reads and writes at runtime
+ * (e.g. internal feature toggles, tuning parameters, calibration values) and need
+ * to be persisted across restarts.
+ *
+ * Each configuration is identified by a unique `key` within the package and is
+ * either a numeric value (`number`) or a value picked from a fixed list (`select`).
+ * Consumers can react to value changes by registering a change listener.
+ */
+export interface EnergyAppConfigurationManager {
+    /**
+     * Registers the full set of internal configurations for the package in a
+     * single call. This method is intended to be called once per package start
+     * with every configuration the package needs.
+     *
+     * Each configuration must have a unique `key` within the supplied array.
+     * Re-registering an existing key is treated as an update of that
+     * configuration's definition; the currently stored value is preserved if
+     * it still satisfies the new constraints.
+     *
+     * @param configurations - The complete list of configuration definitions to register
+     * @returns Promise that resolves once all configurations are registered
+     */
+    registerConfigurations(configurations: EnyoConfiguration[]): Promise<void>;
+    /**
+     * Removes the configurations identified by the given keys along with any
+     * values stored for them. Unknown keys are ignored.
+     *
+     * @param keys - The unique keys of the configurations to remove
+     * @returns Promise that resolves once all configurations are removed
+     */
+    unregisterConfigurations(keys: string[]): Promise<void>;
+    /**
+     * Retrieves the current value for a registered configuration.
+     *
+     * Returns the persisted value if one has been set, otherwise the
+     * configuration's `defaultValue` if defined, otherwise `undefined`.
+     *
+     * @param key - The unique key of the configuration
+     * @returns Promise resolving to the current value, or `undefined` if no
+     *          value and no default has been defined
+     */
+    getConfiguration(key: string): Promise<string | number | undefined>;
+    /**
+     * Registers a listener that is invoked whenever the value of any
+     * configuration managed by this package changes.
+     *
+     * @param listener - Callback invoked with the change event
+     */
+    onConfigurationChanged(listener: EnyoConfigurationChangeListener): void;
+}

package/dist/cjs/types/enyo-configuration-manager.cjs

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

package/dist/cjs/types/enyo-configuration-manager.d.cts

@@ -0,0 +1,84 @@
+/**
+ * Discriminator for the type of an internal configuration.
+ * - `number`: a numeric value with optional min/max/step constraints
+ * - `select`: a string value picked from a fixed list of allowed options
+ */
+export type EnyoConfigurationType = 'number' | 'select';
+/**
+ * Defines an allowed option for a select-type configuration.
+ */
+export interface EnyoConfigurationSelectOption {
+    /** The underlying value stored for this option. Must be unique within the configuration. */
+    value: string;
+}
+/**
+ * Constraints for a number-type configuration.
+ * All bounds are inclusive when provided.
+ */
+export interface EnyoConfigurationNumberOptions {
+    /** Optional inclusive minimum value */
+    minValue?: number;
+    /** Optional inclusive maximum value */
+    maxValue?: number;
+    /** Optional step increment between valid values */
+    step?: number;
+}
+/**
+ * Base properties shared by every configuration registration.
+ */
+interface EnyoConfigurationBase {
+    /**
+     * Unique key identifying this configuration within the package.
+     * The same key is used for retrieval, change notifications, and removal.
+     */
+    key: string;
+    /**
+     * Optional default value applied when the configuration has not been
+     * set yet. For `select` configurations this must match one of the
+     * defined option values. For `number` configurations this must satisfy
+     * the configured min/max/step constraints.
+     */
+    defaultValue?: string | number;
+}
+/**
+ * Registration payload for a number-type internal configuration.
+ */
+export interface EnyoNumberConfiguration extends EnyoConfigurationBase {
+    type: 'number';
+    /** Optional numeric constraints */
+    numberOptions?: EnyoConfigurationNumberOptions;
+    /** Default value must be a number when provided */
+    defaultValue?: number;
+}
+/**
+ * Registration payload for a select-type internal configuration.
+ */
+export interface EnyoSelectConfiguration extends EnyoConfigurationBase {
+    type: 'select';
+    /** The list of allowed options - must contain at least one entry */
+    selectOptions: EnyoConfigurationSelectOption[];
+    /** Default value must match one of the {@link selectOptions} values when provided */
+    defaultValue?: string;
+}
+/**
+ * Discriminated union of all configuration registration payloads.
+ * Use the `type` field to narrow to the concrete configuration shape.
+ */
+export type EnyoConfiguration = EnyoNumberConfiguration | EnyoSelectConfiguration;
+/**
+ * Event emitted when the value of a registered configuration changes.
+ * `previousValue` is omitted when the configuration is being set for the first time.
+ */
+export interface EnyoConfigurationChangeEvent {
+    /** The key of the configuration that changed */
+    key: string;
+    /** The new value of the configuration */
+    newValue: string | number;
+    /** The previous value of the configuration, if one existed */
+    previousValue?: string | number;
+}
+/**
+ * Callback signature for listeners notified on configuration value changes.
+ */
+export type EnyoConfigurationChangeListener = (event: EnyoConfigurationChangeEvent) => Promise<void> | void;
+export {};

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

package/dist/energy-app.d.ts

@@ -34,6 +34,7 @@ import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.js"
 import { EnergyAppWifi } from "./packages/energy-app-wifi.js";
 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";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -223,6 +224,14 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Grid Connection Point API instance
      */
     useGridConnectionPoint(): EnergyAppGridConnectionPoint;
+    /**
+     * Gets the Configuration Manager API for registering internal (non user-facing)
+     * package configurations. Configurations are typed as either `number` or
+     * `select`, addressed by a unique key, and emit change events when their
+     * persisted value is updated.
+     * @returns The Configuration Manager API instance
+     */
+    useConfigurationManager(): EnergyAppConfigurationManager;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/energy-app.js

@@ -285,6 +285,16 @@ export class EnergyApp {
     useGridConnectionPoint() {
         return this.energyAppSdk.useGridConnectionPoint();
     }
+    /**
+     * Gets the Configuration Manager API for registering internal (non user-facing)
+     * package configurations. Configurations are typed as either `number` or
+     * `select`, addressed by a unique key, and emit change events when their
+     * persisted value is updated.
+     * @returns The Configuration Manager API instance
+     */
+    useConfigurationManager() {
+        return this.energyAppSdk.useConfigurationManager();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -33,6 +33,7 @@ import { EnergyAppLearningPhase } from "./packages/energy-app-learning-phase.js"
 import { EnergyAppWifi } from "./packages/energy-app-wifi.js";
 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";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -127,4 +128,6 @@ export interface EnyoEnergyAppSdk {
     useUdp: () => EnergyAppUdp;
     /** Get the Grid Connection Point API for retrieving fuse rating, phase count, and power limit of the site's grid connection */
     useGridConnectionPoint: () => EnergyAppGridConnectionPoint;
+    /** Get the Configuration Manager API for registering internal (non user-facing) package configurations with change notifications */
+    useConfigurationManager: () => EnergyAppConfigurationManager;
 }

package/dist/index.d.ts

@@ -50,6 +50,8 @@ export * from './packages/energy-app-wifi.js';
 export * from './packages/energy-app-udp.js';
 export * from './types/enyo-grid-connection-point.js';
 export * from './packages/energy-app-grid-connection-point.js';
+export * from './types/enyo-configuration-manager.js';
+export * from './packages/energy-app-configuration-manager.js';
 export * from './types/enyo-air-conditioning-appliance.js';
 export * from './types/enyo-onboarding.js';
 export * from './packages/energy-app-onboarding.js';

package/dist/index.js

@@ -50,6 +50,8 @@ export * from './packages/energy-app-wifi.js';
 export * from './packages/energy-app-udp.js';
 export * from './types/enyo-grid-connection-point.js';
 export * from './packages/energy-app-grid-connection-point.js';
+export * from './types/enyo-configuration-manager.js';
+export * from './packages/energy-app-configuration-manager.js';
 export * from './types/enyo-air-conditioning-appliance.js';
 export * from './types/enyo-onboarding.js';
 export * from './packages/energy-app-onboarding.js';

package/dist/packages/energy-app-configuration-manager.d.ts

@@ -0,0 +1,56 @@
+import { EnyoConfiguration, EnyoConfigurationChangeListener } from "../types/enyo-configuration-manager.js";
+/**
+ * Internal configuration manager for an Energy App package.
+ *
+ * Unlike {@link import('./energy-app-settings.js').EnergyAppSettings}, configurations
+ * registered here are NOT user-facing and are not rendered in the Energy App UI.
+ * They are intended for values that the package itself reads and writes at runtime
+ * (e.g. internal feature toggles, tuning parameters, calibration values) and need
+ * to be persisted across restarts.
+ *
+ * Each configuration is identified by a unique `key` within the package and is
+ * either a numeric value (`number`) or a value picked from a fixed list (`select`).
+ * Consumers can react to value changes by registering a change listener.
+ */
+export interface EnergyAppConfigurationManager {
+    /**
+     * Registers the full set of internal configurations for the package in a
+     * single call. This method is intended to be called once per package start
+     * with every configuration the package needs.
+     *
+     * Each configuration must have a unique `key` within the supplied array.
+     * Re-registering an existing key is treated as an update of that
+     * configuration's definition; the currently stored value is preserved if
+     * it still satisfies the new constraints.
+     *
+     * @param configurations - The complete list of configuration definitions to register
+     * @returns Promise that resolves once all configurations are registered
+     */
+    registerConfigurations(configurations: EnyoConfiguration[]): Promise<void>;
+    /**
+     * Removes the configurations identified by the given keys along with any
+     * values stored for them. Unknown keys are ignored.
+     *
+     * @param keys - The unique keys of the configurations to remove
+     * @returns Promise that resolves once all configurations are removed
+     */
+    unregisterConfigurations(keys: string[]): Promise<void>;
+    /**
+     * Retrieves the current value for a registered configuration.
+     *
+     * Returns the persisted value if one has been set, otherwise the
+     * configuration's `defaultValue` if defined, otherwise `undefined`.
+     *
+     * @param key - The unique key of the configuration
+     * @returns Promise resolving to the current value, or `undefined` if no
+     *          value and no default has been defined
+     */
+    getConfiguration(key: string): Promise<string | number | undefined>;
+    /**
+     * Registers a listener that is invoked whenever the value of any
+     * configuration managed by this package changes.
+     *
+     * @param listener - Callback invoked with the change event
+     */
+    onConfigurationChanged(listener: EnyoConfigurationChangeListener): void;
+}

package/dist/packages/energy-app-configuration-manager.js

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

package/dist/types/enyo-configuration-manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Discriminator for the type of an internal configuration.
+ * - `number`: a numeric value with optional min/max/step constraints
+ * - `select`: a string value picked from a fixed list of allowed options
+ */
+export type EnyoConfigurationType = 'number' | 'select';
+/**
+ * Defines an allowed option for a select-type configuration.
+ */
+export interface EnyoConfigurationSelectOption {
+    /** The underlying value stored for this option. Must be unique within the configuration. */
+    value: string;
+}
+/**
+ * Constraints for a number-type configuration.
+ * All bounds are inclusive when provided.
+ */
+export interface EnyoConfigurationNumberOptions {
+    /** Optional inclusive minimum value */
+    minValue?: number;
+    /** Optional inclusive maximum value */
+    maxValue?: number;
+    /** Optional step increment between valid values */
+    step?: number;
+}
+/**
+ * Base properties shared by every configuration registration.
+ */
+interface EnyoConfigurationBase {
+    /**
+     * Unique key identifying this configuration within the package.
+     * The same key is used for retrieval, change notifications, and removal.
+     */
+    key: string;
+    /**
+     * Optional default value applied when the configuration has not been
+     * set yet. For `select` configurations this must match one of the
+     * defined option values. For `number` configurations this must satisfy
+     * the configured min/max/step constraints.
+     */
+    defaultValue?: string | number;
+}
+/**
+ * Registration payload for a number-type internal configuration.
+ */
+export interface EnyoNumberConfiguration extends EnyoConfigurationBase {
+    type: 'number';
+    /** Optional numeric constraints */
+    numberOptions?: EnyoConfigurationNumberOptions;
+    /** Default value must be a number when provided */
+    defaultValue?: number;
+}
+/**
+ * Registration payload for a select-type internal configuration.
+ */
+export interface EnyoSelectConfiguration extends EnyoConfigurationBase {
+    type: 'select';
+    /** The list of allowed options - must contain at least one entry */
+    selectOptions: EnyoConfigurationSelectOption[];
+    /** Default value must match one of the {@link selectOptions} values when provided */
+    defaultValue?: string;
+}
+/**
+ * Discriminated union of all configuration registration payloads.
+ * Use the `type` field to narrow to the concrete configuration shape.
+ */
+export type EnyoConfiguration = EnyoNumberConfiguration | EnyoSelectConfiguration;
+/**
+ * Event emitted when the value of a registered configuration changes.
+ * `previousValue` is omitted when the configuration is being set for the first time.
+ */
+export interface EnyoConfigurationChangeEvent {
+    /** The key of the configuration that changed */
+    key: string;
+    /** The new value of the configuration */
+    newValue: string | number;
+    /** The previous value of the configuration, if one existed */
+    previousValue?: string | number;
+}
+/**
+ * Callback signature for listeners notified on configuration value changes.
+ */
+export type EnyoConfigurationChangeListener = (event: EnyoConfigurationChangeEvent) => Promise<void> | void;
+export {};

package/dist/types/enyo-configuration-manager.js

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

package/dist/version.d.ts

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