@enyo-energy/energy-app-sdk 1.19.0 → 1.20.0

package/README.md

@@ -212,8 +212,14 @@ Energy Apps follow a specific lifecycle managed by the enyo system:
 const energyApp = new EnergyApp();
 
 // Register startup callback
-energyApp.register((packageName, version) => {
-    console.log(`${packageName} v${version} started`);
+energyApp.register((packageName, version, channel, deviceId, environment) => {
+    console.log(`${packageName} v${version} started on ${deviceId} (${channel}, ${environment})`);
+
+    // e.g. skip hardware access when running in the developer portal simulation
+    if (environment === EnyoEnergyAppEnvironment.DeveloperPortalSimulation) {
+        console.log('Running in simulation - using mocked devices');
+    }
+
     energyApp.updateEnergyAppState(EnergyAppStateEnum.Running);
 });
 

package/dist/cjs/energy-app.cjs

@@ -14,7 +14,7 @@ const version_js_1 = require("./version.cjs");
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -51,6 +51,12 @@ class EnergyApp {
     updateEnergyAppState(state) {
         this.energyAppSdk.updateEnergyAppState(state);
     }
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
     register(callback) {
         // This registers the package with the enyo system
         this.energyAppSdk.register(callback);

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

@@ -19,6 +19,7 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
+import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.cjs";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.cjs";
@@ -61,7 +62,7 @@ import { UseFetchOptions } from "./types/enyo-fetch.cjs";
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -79,7 +80,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      */
     onNetworkStatusChanged(listener: (online: boolean) => void | Promise<void>): string;
     updateEnergyAppState(state: EnergyAppStateEnum): void;
-    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>): void;
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
+    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>): void;
     onShutdown(callback: () => void | Promise<void>): void;
     /**
      * Returns a `fetch` implementation provided by the runtime.

package/dist/cjs/enyo-energy-app-environment.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnyoEnergyAppEnvironment = void 0;
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+var EnyoEnergyAppEnvironment;
+(function (EnyoEnergyAppEnvironment) {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    EnyoEnergyAppEnvironment["OnDeviceDevelopment"] = "on-device-development";
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    EnyoEnergyAppEnvironment["OnDeviceProduction"] = "on-device-production";
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    EnyoEnergyAppEnvironment["DeveloperPortalSimulation"] = "developer-portal-simulation";
+})(EnyoEnergyAppEnvironment || (exports.EnyoEnergyAppEnvironment = EnyoEnergyAppEnvironment = {}));

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

@@ -0,0 +1,16 @@
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+export declare enum EnyoEnergyAppEnvironment {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    OnDeviceDevelopment = "on-device-development",
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    OnDeviceProduction = "on-device-production",
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    DeveloperPortalSimulation = "developer-portal-simulation"
+}

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

@@ -18,6 +18,7 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
+import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.cjs";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.cjs";
@@ -62,8 +63,13 @@ export declare enum EnergyAppStateEnum {
  * network operations, storage, and device communication.
  */
 export interface EnyoEnergyAppSdk {
-    /** Register a callback that gets called when the package is initialized */
-    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>) => void;
+    /**
+     * Register a callback that gets called when the package is initialized.
+     * The callback receives the package name, its version, the release channel it
+     * was installed from, the id of the device it runs on and the
+     * {@link EnyoEnergyAppEnvironment} the app is executed in.
+     */
+    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>) => void;
     /** health check - returns the current date to check if alive */
     healthcheck: () => Date;
     /** Register a callback that gets called when the system is shutting down */

package/dist/cjs/index.cjs

@@ -37,6 +37,7 @@ __exportStar(require("./implementations/network-devices/network-access-guard.cjs
 __exportStar(require("./implementations/network-devices/network-device-manager.cjs"), exports);
 __exportStar(require("./implementations/storage/storage-schedule-handler.cjs"), exports);
 __exportStar(require("./enyo-package-channel.cjs"), exports);
+__exportStar(require("./enyo-energy-app-environment.cjs"), exports);
 __exportStar(require("./types/enyo-timeseries.cjs"), exports);
 __exportStar(require("./types/enyo-energy-manager.cjs"), exports);
 __exportStar(require("./packages/energy-app-energy-manager.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -21,6 +21,7 @@ export * from './implementations/network-devices/network-access-guard.cjs';
 export * from './implementations/network-devices/network-device-manager.cjs';
 export * from './implementations/storage/storage-schedule-handler.cjs';
 export * from './enyo-package-channel.cjs';
+export * from './enyo-energy-app-environment.cjs';
 export * from './types/enyo-timeseries.cjs';
 export * from './types/enyo-energy-manager.cjs';
 export * from './packages/energy-app-energy-manager.cjs';

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.19.0';
+exports.SDK_VERSION = '1.20.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.19.0";
+export declare const SDK_VERSION = "1.20.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/energy-app.d.ts

@@ -19,6 +19,7 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.js";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.js";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.js";
 import { EnyoPackageChannel } from "./enyo-package-channel.js";
+import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.js";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.js";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.js";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.js";
@@ -61,7 +62,7 @@ import { UseFetchOptions } from "./types/enyo-fetch.js";
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -79,7 +80,13 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      */
     onNetworkStatusChanged(listener: (online: boolean) => void | Promise<void>): string;
     updateEnergyAppState(state: EnergyAppStateEnum): void;
-    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>): void;
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
+    register(callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>): void;
     onShutdown(callback: () => void | Promise<void>): void;
     /**
      * Returns a `fetch` implementation provided by the runtime.

package/dist/energy-app.js

@@ -11,7 +11,7 @@ import { getSdkVersion } from "./version.js";
  * @example
  * ```ts
  * const app = new EnergyApp();
- * app.register((packageName, version, channel, deviceId) => {
+ * app.register((packageName, version, channel, deviceId, environment) => {
  *   // perform initialization
  * });
  * ```
@@ -48,6 +48,12 @@ export class EnergyApp {
     updateEnergyAppState(state) {
         this.energyAppSdk.updateEnergyAppState(state);
     }
+    /**
+     * Registers the package with the enyo system.
+     * @param callback - Invoked once the package is initialized with the package name,
+     *   the installed package version, the {@link EnyoPackageChannel} it was installed from,
+     *   the id of the device it runs on and the {@link EnyoEnergyAppEnvironment} it is executed in
+     */
     register(callback) {
         // This registers the package with the enyo system
         this.energyAppSdk.register(callback);

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

@@ -0,0 +1,16 @@
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+export declare enum EnyoEnergyAppEnvironment {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    OnDeviceDevelopment = "on-device-development",
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    OnDeviceProduction = "on-device-production",
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    DeveloperPortalSimulation = "developer-portal-simulation"
+}

package/dist/enyo-energy-app-environment.js

@@ -0,0 +1,17 @@
+/**
+ * Runtime environment an energy app is executed in.
+ *
+ * The environment is handed to the callback passed to `register()` so an app can
+ * adapt its behaviour, e.g. use verbose logging or mocked hardware access while
+ * developing, and skip anything that requires real hardware when it runs inside
+ * the developer portal simulation.
+ */
+export var EnyoEnergyAppEnvironment;
+(function (EnyoEnergyAppEnvironment) {
+    /** Running on a real enyo device in development mode (e.g. a developer's test device). */
+    EnyoEnergyAppEnvironment["OnDeviceDevelopment"] = "on-device-development";
+    /** Running on a real enyo device in production, i.e. at a customer's site. */
+    EnyoEnergyAppEnvironment["OnDeviceProduction"] = "on-device-production";
+    /** Running inside the developer portal simulation, without real hardware attached. */
+    EnyoEnergyAppEnvironment["DeveloperPortalSimulation"] = "developer-portal-simulation";
+})(EnyoEnergyAppEnvironment || (EnyoEnergyAppEnvironment = {}));

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

@@ -18,6 +18,7 @@ import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.js";
 import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.js";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.js";
 import { EnyoPackageChannel } from "./enyo-package-channel.js";
+import { EnyoEnergyAppEnvironment } from "./enyo-energy-app-environment.js";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.js";
 import { EnergyAppElectricityTariff } from "./packages/energy-app-electricity-tariff.js";
 import { EnergyAppWeatherForecasting } from "./packages/energy-app-weather-forecasting.js";
@@ -62,8 +63,13 @@ export declare enum EnergyAppStateEnum {
  * network operations, storage, and device communication.
  */
 export interface EnyoEnergyAppSdk {
-    /** Register a callback that gets called when the package is initialized */
-    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string) => void | Promise<void>) => void;
+    /**
+     * Register a callback that gets called when the package is initialized.
+     * The callback receives the package name, its version, the release channel it
+     * was installed from, the id of the device it runs on and the
+     * {@link EnyoEnergyAppEnvironment} the app is executed in.
+     */
+    register: (callback: (packageName: string, version: number, channel: EnyoPackageChannel, deviceId: string, environment: EnyoEnergyAppEnvironment) => void | Promise<void>) => void;
     /** health check - returns the current date to check if alive */
     healthcheck: () => Date;
     /** Register a callback that gets called when the system is shutting down */

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export * from './implementations/network-devices/network-access-guard.js';
 export * from './implementations/network-devices/network-device-manager.js';
 export * from './implementations/storage/storage-schedule-handler.js';
 export * from './enyo-package-channel.js';
+export * from './enyo-energy-app-environment.js';
 export * from './types/enyo-timeseries.js';
 export * from './types/enyo-energy-manager.js';
 export * from './packages/energy-app-energy-manager.js';

package/dist/index.js

@@ -21,6 +21,7 @@ export * from './implementations/network-devices/network-access-guard.js';
 export * from './implementations/network-devices/network-device-manager.js';
 export * from './implementations/storage/storage-schedule-handler.js';
 export * from './enyo-package-channel.js';
+export * from './enyo-energy-app-environment.js';
 export * from './types/enyo-timeseries.js';
 export * from './types/enyo-energy-manager.js';
 export * from './packages/energy-app-energy-manager.js';

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.19.0";
+export declare const SDK_VERSION = "1.20.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.19.0';
+export const SDK_VERSION = '1.20.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",