@enyo-energy/energy-app-sdk 0.0.183 → 0.0.185

package/README.md

@@ -32,6 +32,12 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [NetworkAccessGuard](#networkaccessguard)
   - [NetworkDeviceManager](#networkdevicemanager)
   - [Startup pattern](#startup-pattern)
+- [Firmware Update Registry](#firmware-update-registry)
+  - [Declaring firmware](#declaring-firmware)
+  - [Firmware modes](#firmware-modes)
+  - [Resolving the next version](#resolving-the-next-version)
+  - [Downloading a file](#downloading-a-file)
+  - [Validating the graph](#validating-the-graph)
 - [Retry Framework](#retry-framework)
 - [Device Integrations](#device-integrations)
   - [IntegrationEnergyApp (Base Class)](#integrationenergyapp-base-class)
@@ -346,6 +352,7 @@ Energy Apps use a granular permissions system to control access to system resour
 - **`PvForecastRegister`** / **`PvForecastUse`**: Publish / consume PV forecasts
 - **`DynamicPriceForecastRegister`** / **`DynamicPriceForecastUse`**: Publish / consume dynamic-price forecasts
 - **`PvSystemRegister`** / **`PvSystemUse`**: Register / read PV system configuration
+- **`Savings`**: Publish and read back day-scoped savings reports
 
 #### Site & Identity Permissions
 
@@ -468,6 +475,66 @@ const inverters = await networkDevices.search({
 const deviceInfo = await networkDevices.getDeviceInfo(device.id);
 ```
 
+#### `useDeviceTest(): EnergyAppDeviceTest`
+
+Answer the host's "is this device yours, and did it yield appliances?" question.
+
+Every other device API points outward — you scan, or you get notified, and you decide what to do next. This one is inverted: the host has detected a device it cannot identify on its own and calls **into** your app. Register one handler; it is used by the onboarding v2 `device-test` action, by background auto-detection, and by user-triggered re-tests (see `request.origin`).
+
+```typescript
+await energyApp.useDeviceTest().registerDeviceTestHandler(async (request) => {
+    const devices: EnyoDeviceTestDeviceResult[] = [];
+    const appliances: EnyoDeviceTestApplianceResult[] = [];
+
+    for (const device of request.devices) {
+        const identity = await readVendorRegisters(device);       // your protocol
+        if (!identity) {
+            devices.push({networkDeviceId: device.id, outcome: EnyoDeviceTestOutcomeEnum.NotSupported});
+            continue;
+        }
+
+        const existing = await findApplianceForSerial(identity.serialNumber);
+        const applianceId = await energyApp.useAppliances().save(buildAppliance(device, identity), existing?.id);
+
+        appliances.push({
+            applianceId,
+            applianceType: EnyoApplianceTypeEnum.Inverter,
+            disposition: existing
+                ? EnyoDeviceTestApplianceDispositionEnum.Updated
+                : EnyoDeviceTestApplianceDispositionEnum.Created,
+            networkDeviceId: device.id
+        });
+        devices.push({
+            networkDeviceId: device.id,
+            outcome: existing
+                ? EnyoDeviceTestOutcomeEnum.AppliancesAlreadyExisted
+                : EnyoDeviceTestOutcomeEnum.AppliancesCreated,
+            vendor: identity.vendor,
+            model: identity.model,
+            serialNumber: identity.serialNumber
+        });
+    }
+
+    return {
+        requestId: request.requestId,
+        outcome: aggregateDeviceTestOutcome(devices),
+        devices,
+        appliances
+    };
+});
+```
+
+Rules worth respecting:
+
+- **The host owns the clock.** `request.timeoutMs` is your budget; the host stops waiting when it expires and treats the run as `failed`. Your handler is *not* told, so bound socket timeouts and retries to fit and never leave connections open past the point where an answer could matter.
+- **One handler per package.** Registering again replaces the previous one. Register during startup — a request arriving before registration is answered `failed`, which in a guided run means the installer sees the failure branch.
+- **Answer for every device.** A twelve-device scan needs twelve verdicts; "three are mine, one needs a password, eight are the neighbour's printer" is the normal case.
+- **`created` vs `already-existed` are different answers.** Both are successes, but the guide branches differently — one is "set up", the other "already set up".
+- **Derive the aggregate with `aggregateDeviceTestOutcome()`.** Success dominates a sibling device's failure, and actionable outcomes outrank unactionable ones; hand-rolling that precedence is where the bugs are.
+- **No permission is needed to register**, but the work inside needs `NetworkDeviceAccess` to reach a device and `Appliance` to create one. Without them, answer `access-not-granted` rather than throwing.
+
+Validate a result during development with `validateDeviceTestResult(result, request)` — it catches contradictions like `appliances-created` with no created appliance, which would otherwise route an installer to a success screen for appliances that do not exist.
+
 #### `useModbus(): EnergyAppModbus`
 
 Access Modbus communication:
@@ -1120,6 +1187,66 @@ diag.energyManagerDiagnostics(
 );
 ```
 
+#### `useSavings(): EnergyAppSavings`
+
+Publish what the energy management saved the customer on a finished day, and read back which days were already reported.
+
+The app settles a day by replaying its **measured** environment through a simulation of the same house running **uncontrolled**, and pricing both worlds against the tariff that actually applied. Publishing is an upsert keyed by `dayIso` + `method`, so a day may be recomputed after a backfill or a bugfix. The platform stores days and owns every aggregation above them (month, year, lifetime) — and excludes `Low` confidence days from those rollups.
+
+```typescript
+const savings = energyApp.useSavings();
+
+// On boot: which days still need settling?
+const { missingDayIsos } = await savings.getDailySavings({
+    startDayIso: '2026-07-01',
+    endDayIso: '2026-07-31'
+});
+
+for (const dayIso of missingDayIsos) {
+    await savings.publishDailySavings({
+        schemaVersion: 1,
+        dayIso,
+        timeZone: 'Europe/Berlin',
+        dayStartUtcMs: startOfLocalDayUtcMs(dayIso),
+        dayEndUtcMs: endOfLocalDayUtcMs(dayIso),   // 23 or 25 h on DST days
+        method: EnyoSavingsMethodEnum.Settled,
+        computedAtIso: new Date().toISOString(),
+        calculatorVersion: '3.2.0',
+        confidence: EnyoSavingsConfidenceEnum.High,
+        confidenceIssues: [],
+        costs: {
+            currency: EnyoCurrencyEnum.EUR,
+            optimizedCost: 1.42,
+            baselineCost: 3.07,
+            savings: 1.65,
+            savingsFromSelfConsumption: 1.12,
+            savingsFromArbitrage: 0.53
+        },
+        energy: { /* both worlds, Wh */ },
+        metrics: { /* both worlds */ },
+        attribution: [
+            { applianceType: EnergyAppApplianceTypeEnum.Charger, savings: 0.91, shiftedEnergyWh: 12400 }
+        ],
+        coverage: [
+            { series: 'pv', source: EnyoSavingsDataSourceEnum.Measured, expectedBuckets: 96, presentBuckets: 96 }
+        ],
+        assumptions: [
+            { key: 'battery.dischargeEfficiency', value: 0.95 }
+        ]
+    });
+}
+```
+
+Notes worth respecting when producing a report:
+
+- **Publish both worlds, never only the delta.** A lone savings number is unauditable and cannot be re-aggregated.
+- **Assumptions travel with the report.** The counterfactual rests on guesses; without them, changing a default silently rewrites history.
+- **`dayIso` is a local calendar date.** The IANA zone and the exact UTC bounds go alongside — anything assuming 96 buckets is wrong twice a year.
+- **Per-slot detail (`slots`) is opt-in.** Settlement is stateless, so the app can regenerate it on demand; only publish it for days under investigation.
+- **Units follow the platform:** energy in Wh, power in W, prices per kWh, currency as `EnyoCurrencyEnum`.
+
+Requires the `Savings` permission.
+
 ### Operational Utilities
 
 #### `useOnboarding(): EnergyAppOnboarding`
@@ -1567,6 +1694,160 @@ async function connectDevice(networkDeviceId: string) {
 
 This pattern matches the wiring used by real Sungrow / Fronius energy-app packages: one `NetworkDeviceManager` per package, `ensureAccess` before every connect, `withAccessGuard` around every poll, and a single `getDevices({ accessStatus: 'granted' })` pass at startup to cover the warm-restart case.
 
+## Firmware Update Registry
+
+Ship firmware images with your package and hand them to devices at runtime. You declare the files by local path in the package definition, the enyo CLI uploads them during `enyo release`, and the app reaches them through `energyApp.useFirmwareRegistry()`. The release tarball never carries the bytes.
+
+Requires the `FirmwareRegistry` permission.
+
+**Firmware versions are opaque strings.** A version is whatever the vendor calls it — `2.4.1`, `2024-11-rc3`, `A7F2` — and is never parsed, ordered, or compared beyond exact equality. Nothing can be derived from the string itself, so the update order is declared rather than computed. `firmwareMode` picks which form that takes.
+
+### Firmware modes
+
+| `firmwareMode` | Order comes from | Use when |
+|---|---|---|
+| `'latest'` *(default)* | **Declaration order** — the last entry declared for the device's model is always the one offered | Devices accept any image directly |
+| `'dependent'` | The explicit **`installForFirmwareVersion`** edges on each entry | Devices must be stepped through intermediate versions |
+
+### Declaring firmware
+
+`firmwareMode: 'latest'` — a plain list, last one wins:
+
+```typescript
+import { defineEnergyAppPackage, defineFirmwareFile, EnergyAppPackageFirmwareModeEnum, EnergyAppPermissionTypeEnum } from '@enyo-energy/energy-app-sdk';
+
+export default defineEnergyAppPackage({
+    version: '1',
+    packageName: 'acme-wallbox',
+    // ...
+    permissions: [EnergyAppPermissionTypeEnum.FirmwareRegistry],
+    firmwareMode: EnergyAppPackageFirmwareModeEnum.Latest,
+    firmware: [
+        defineFirmwareFile({
+            fileId: 'ac22-2024-11',
+            path: './firmware/ac22-2024-11.bin',
+            firmwareVersion: '2024-11-rc3',
+            modelNames: ['AC-22-Pro']
+        }),
+        defineFirmwareFile({
+            fileId: 'ac22-current',
+            path: './firmware/ac22-current.bin',
+            firmwareVersion: 'A7F2',
+            modelNames: ['AC-22-Pro']
+        })
+        // ↑ last declared for AC-22-Pro — every AC-22-Pro is offered this one
+    ]
+});
+```
+
+`firmwareMode: 'dependent'` — each entry declares the versions it installs *for*:
+
+```typescript
+firmwareMode: EnergyAppPackageFirmwareModeEnum.Dependent,
+firmware: [
+    defineFirmwareFile({
+        fileId: 'ac22-baseline',
+        path: './firmware/ac22-2024-11-rc3.bin',
+        firmwareVersion: '2024-11-rc3',
+        modelNames: ['AC-22-Pro'],
+        // offered to devices whose reported version matches no declared entry
+        fallbackForUnknownVersion: true
+    }),
+    defineFirmwareFile({
+        fileId: 'ac22-hotfix-a',
+        path: './firmware/ac22-hotfix-a.bin',
+        firmwareVersion: 'A7F2',
+        installForFirmwareVersion: ['2024-11-rc3'],
+        modelNames: ['AC-22-Pro']
+    }),
+    defineFirmwareFile({
+        fileId: 'ac22-stable',
+        path: './firmware/ac22-stable.bin',
+        firmwareVersion: '1.0',
+        // collapses two old versions into one image
+        installForFirmwareVersion: ['A7F2', 'legacy-b'],
+        modelNames: ['AC-22-Pro'],
+        releaseNotes: [
+            { language: 'en', value: 'Fixes phase rotation detection.' },
+            { language: 'de', value: 'Behebt die Erkennung der Phasenlage.' }
+        ]
+    })
+]
+```
+
+`installForFirmwareVersion` is the whole graph. Three entries each naming their predecessor form a chain; two entries naming the same predecessor for *different* models form a branch; one entry naming several predecessors merges old versions into a single image. Omitting it makes an entry a root that is never offered as an update to a known version. Under `'latest'` the field is ignored (and the validator warns if you set it).
+
+`modelNames` scopes resolution in both modes — an entry without it applies to every model the package supports.
+
+### Resolving the next version
+
+```typescript
+const registry = energyApp.useFirmwareRegistry();
+
+const next = await registry.getNextFirmware(device.reportedVersion, { modelName: 'AC-22-Pro' });
+if (!next) {
+    // Already up to date — the normal outcome, not an error.
+    return;
+}
+console.log(`Update available: ${next.firmwareVersion} (${next.sizeBytes} bytes)`);
+```
+
+Under `'dependent'`, `getNextFirmware()` returns **one hop**, not the destination. After the device installs the image and reports its new version, call again to continue the chain — each step is verified on the device before the next is offered. When you need the whole chain up front:
+
+```typescript
+const path = await registry.getFirmwareUpdatePath(device.reportedVersion, { modelName: 'AC-22-Pro' });
+const totalMb = path.reduce((sum, file) => sum + file.sizeBytes, 0) / 1_000_000;
+console.log(`${path.length} updates pending, ${totalMb.toFixed(1)} MB total`);
+```
+
+Under `'latest'` there is no chain to walk: `getNextFirmware()` hands back the last declared entry for the model until the device runs it, and `getFirmwareUpdatePath()` never returns more than one entry.
+
+### Downloading a file
+
+Firmware images are large, so the bytes never cross the app/host boundary. Request a signed, time-limited URL instead — one that many wallboxes and inverters can fetch themselves:
+
+```typescript
+const download = await registry.requestDownloadUrl(next.fileId, { ttlSeconds: 900 });
+
+// Either hand the URL to the device...
+await device.installFirmwareFromUrl(download.url, download.sha256);
+
+// ...or stream it into the app.
+const response = await fetch(download.url);
+```
+
+Two rules:
+
+- **Request the URL at the moment of use.** It expires at `download.expiresAt` (epoch ms) and the storage backend then rejects it. Never cache or persist it.
+- **Always verify `sha256`** against the downloaded bytes before flashing.
+
+### Validating the graph
+
+An ambiguous or cyclic `'dependent'` graph has no correct resolution at runtime, so validate before releasing:
+
+```typescript
+import { validateFirmwareRegistry, assertValidFirmwareRegistry } from '@enyo-energy/energy-app-sdk';
+
+const result = validateFirmwareRegistry(packageDefinition);
+if (!result.ok) console.error(result.errors);
+console.warn(result.warnings);
+
+assertValidFirmwareRegistry(packageDefinition); // or throw on the first failure
+```
+
+Blocking errors in both modes: duplicate `fileId`s, two entries installing the same version for overlapping models, and declaring firmware without the `FirmwareRegistry` permission. Under `'dependent'` additionally: two entries installing for the same current version on overlapping models, cycles, an entry listing its own version in `installForFirmwareVersion`, and multiple fallbacks per model.
+
+Warnings: under `'latest'`, entries that declare `installForFirmwareVersion` or `fallbackForUnknownVersion` — both are ignored there, so declaring them usually means `'dependent'` was intended. Under `'dependent'`: a source version matching no declared entry — which is exactly how you attach a chain to firmware that shipped before this registry existed — and entries that are neither reachable nor a fallback. In both modes: models or vendors missing from `compatibility`.
+
+For local unit tests, `resolveNextFirmware()` and `resolveFirmwareUpdatePath()` run the same resolution the host performs, against a plain array of entries:
+
+```typescript
+resolveNextFirmware(definition.firmware ?? [], currentVersion, {
+    modelName: 'AC-22-Pro',
+    firmwareMode: definition.firmwareMode
+});
+```
+
 ## Retry Framework
 
 `RetryManager` centralises retry / backoff / circuit-breaker logic so polling loops don't have to reinvent it. Register one entry per logical operation, give it a `RetryPolicy`, and run attempts through `execute(id, fn)` — the manager handles attempt counting, exponential backoff, transition into `Open` after repeated failures, and recovery on the next success.

package/dist/cjs/energy-app-package-definition.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnergyAppPackageCategory = void 0;
+exports.EnergyAppPackageFirmwareModeEnum = exports.EnergyAppPackageCategory = void 0;
 exports.defineEnergyAppPackage = defineEnergyAppPackage;
 const version_js_1 = require("./version.cjs");
 var EnergyAppPackageCategory;
@@ -20,6 +20,17 @@ var EnergyAppPackageCategory;
     EnergyAppPackageCategory["HeatingRod"] = "heating-rod";
     EnergyAppPackageCategory["Other"] = "other";
 })(EnergyAppPackageCategory || (exports.EnergyAppPackageCategory = EnergyAppPackageCategory = {}));
+/**
+ * Enum form of {@link EnergyAppPackageFirmwareMode} for use in package
+ * definitions.
+ */
+var EnergyAppPackageFirmwareModeEnum;
+(function (EnergyAppPackageFirmwareModeEnum) {
+    /** Always offer the last declared firmware entry for the device's model. */
+    EnergyAppPackageFirmwareModeEnum["Latest"] = "latest";
+    /** Follow the explicit `installForFirmwareVersion` upgrade graph. */
+    EnergyAppPackageFirmwareModeEnum["Dependent"] = "dependent";
+})(EnergyAppPackageFirmwareModeEnum || (exports.EnergyAppPackageFirmwareModeEnum = EnergyAppPackageFirmwareModeEnum = {}));
 /**
  * Defines an Energy App package with automatic SDK version injection.
  * This function automatically adds the current SDK version to the package definition

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

@@ -1,5 +1,6 @@
 import { EnergyAppPermissionType } from "./energy-app-permission.type.cjs";
 import { EnergyAppModelFeatureEnum } from "./energy-app-model-feature.enum.cjs";
+import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -219,7 +220,12 @@ export interface EnergyAppPackageCompatibilityModel {
     displayName?: string;
     /**
      * Optional minimum firmware version the package supports for this model.
-     * Free-form string compared lexicographically by hosts that need it.
+     *
+     * A free-form, vendor-defined string used for display and internal
+     * documentation only. It is **not** an ordering primitive: firmware versions
+     * are opaque and are never parsed or compared by the SDK or the host. To
+     * express which firmware can be updated to which, declare the explicit
+     * upgrade graph in {@link EnergyAppPackageDefinition.firmware} instead.
      */
     minimumFirmwareVersion?: string;
     /** Optional internal note explaining model-specific caveats or limitations */
@@ -243,6 +249,134 @@ export interface EnergyAppPackageCompatibilityVendor {
     /** Models from this vendor that the package supports */
     models: EnergyAppPackageCompatibilityModel[];
 }
+/**
+ * How the firmware registry decides which image a device should install next.
+ *
+ * - `'latest'` — every device is offered the **last declared** firmware entry
+ *   that applies to its model, whatever version it currently runs. Since
+ *   firmware versions are opaque strings and cannot be ordered, "latest" means
+ *   last in the `firmware` array — declaration order *is* the order. Use this
+ *   for devices that accept any image directly; `installForFirmwareVersion` is
+ *   ignored.
+ * - `'dependent'` — the update order is the explicit graph declared through
+ *   {@link EnergyAppPackageFirmwareFile.installForFirmwareVersion}: each image
+ *   names the versions it can be installed on top of, and the registry walks
+ *   that graph one hop at a time. Use this for devices that must be stepped
+ *   through intermediate versions.
+ */
+export type EnergyAppPackageFirmwareMode = 'latest' | 'dependent';
+/**
+ * Enum form of {@link EnergyAppPackageFirmwareMode} for use in package
+ * definitions.
+ */
+export declare enum EnergyAppPackageFirmwareModeEnum {
+    /** Always offer the last declared firmware entry for the device's model. */
+    Latest = "latest",
+    /** Follow the explicit `installForFirmwareVersion` upgrade graph. */
+    Dependent = "dependent"
+}
+/**
+ * A firmware image published together with an Energy App package.
+ *
+ * The file is declared here by its local `path`; the enyo CLI uploads it during
+ * `enyo release`, replacing the path with a registry reference, so the released
+ * package tarball never carries the bytes. At runtime the app reaches the
+ * uploaded image through {@link EnergyAppFirmwareRegistry}.
+ *
+ * **Firmware versions are opaque strings.** `firmwareVersion` is whatever the
+ * vendor calls it — `'2.4.1'`, `'2024-11-rc3'`, `'A7F2'` — and is never parsed,
+ * ordered or compared beyond exact string equality. Nothing can therefore be
+ * derived from the string itself, which is why the order comes from
+ * {@link EnergyAppPackageDefinition.firmwareMode}: declaration order under
+ * `'latest'`, or the explicit {@link installForFirmwareVersion} edges under
+ * `'dependent'`.
+ *
+ * Under `'dependent'`, chains, branches and merges all fall out of that one
+ * field: three entries each naming their predecessor form a chain; two entries
+ * naming the same predecessor for different models form a branch; one entry
+ * naming several predecessors collapses old versions into a single image.
+ *
+ * Validate the declaration with `validateFirmwareRegistry()` before releasing —
+ * an ambiguous or cyclic graph has no correct resolution and is rejected rather
+ * than silently resolved.
+ *
+ * @example
+ * ```typescript
+ * // firmwareMode: 'dependent' — stepped through intermediate versions
+ * firmware: [
+ *     defineFirmwareFile({
+ *         fileId: 'ac22-baseline',
+ *         path: './firmware/ac22-2024-11-rc3.bin',
+ *         firmwareVersion: '2024-11-rc3',
+ *         modelNames: ['AC-22-Pro'],
+ *         fallbackForUnknownVersion: true
+ *     }),
+ *     defineFirmwareFile({
+ *         fileId: 'ac22-hotfix-a',
+ *         path: './firmware/ac22-hotfix-a.bin',
+ *         firmwareVersion: 'hotfix-a',
+ *         installForFirmwareVersion: ['2024-11-rc3'],
+ *         modelNames: ['AC-22-Pro']
+ *     })
+ * ]
+ * ```
+ */
+export interface EnergyAppPackageFirmwareFile {
+    /**
+     * Stable, app-chosen identifier for this firmware image. Used as the lookup
+     * key at runtime and must be unique within the package.
+     */
+    fileId: string;
+    /**
+     * Path to the firmware file relative to the package root, e.g.
+     * `'./firmware/wallbox-2.4.1.bin'`. Resolved and uploaded by the enyo CLI on
+     * release; the published definition carries a registry reference instead.
+     */
+    path: string;
+    /**
+     * The firmware version this file installs. An opaque, vendor-defined string
+     * that is only ever equality-matched — never parsed or ordered.
+     */
+    firmwareVersion: string;
+    /**
+     * The versions this image is installed for — the incoming edges of this node
+     * in the upgrade graph. Each string is matched by exact equality against the
+     * version a device reports as currently installed; when it matches, this
+     * image is the device's next step.
+     *
+     * Only meaningful when {@link EnergyAppPackageDefinition.firmwareMode} is
+     * `'dependent'`; ignored under `'latest'`.
+     *
+     * Omit (or leave empty) for a root entry: one that heads a chain and is
+     * never offered as an update to a known version.
+     */
+    installForFirmwareVersion?: string[];
+    /**
+     * When true, this image is offered to devices whose reported version matches
+     * no declared node — a recovery or baseline image. At most one entry per
+     * model may set this.
+     *
+     * Only meaningful under `firmwareMode: 'dependent'`; ignored under
+     * `'latest'`, where every unrecognised version already receives the last
+     * declared image.
+     */
+    fallbackForUnknownVersion?: boolean;
+    /**
+     * Optional vendor this firmware belongs to. Should match a `vendorName` from
+     * {@link EnergyAppPackageDefinition.compatibility}.
+     */
+    vendorName?: string;
+    /**
+     * Optional models this firmware applies to. Scopes graph resolution: an
+     * update is only offered to a device whose model is listed here. Omit when
+     * the image applies to every model the package supports.
+     */
+    modelNames?: string[];
+    /** Optional translated release notes shown in the host UI. */
+    releaseNotes?: EnyoFileTranslation[];
+    /** Optional internal note explaining this image; never shown to users. */
+    internalComment?: string;
+}
 /**
  * Complete definition for a enyo Energy App package.
  * This interface defines all the metadata, permissions, and configuration
@@ -277,6 +411,26 @@ export interface EnergyAppPackageDefinition {
      * single vendor implicitly or has no fixed compatibility surface.
      */
     compatibility: EnergyAppPackageCompatibilityVendor[];
+    /**
+     * Firmware images shipped with this package, declared as local file paths
+     * and uploaded by the enyo CLI on release.
+     *
+     * The app reaches them at runtime through
+     * {@link EnergyAppFirmwareRegistry}; how the next image is chosen is set by
+     * {@link firmwareMode}. Requires the `FirmwareRegistry` permission. Omit for
+     * packages that do not distribute firmware.
+     */
+    firmware?: EnergyAppPackageFirmwareFile[];
+    /**
+     * How the registry picks the next image for a device. Defaults to
+     * `'latest'`, which always offers the last declared entry for the device's
+     * model. Set to `'dependent'` when devices must be stepped through
+     * intermediate versions — the order is then taken from each entry's
+     * `installForFirmwareVersion` edges.
+     *
+     * Only relevant when {@link firmware} is declared.
+     */
+    firmwareMode?: EnergyAppPackageFirmwareMode;
 }
 /**
  * Defines an Energy App package with automatic SDK version injection.

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

@@ -50,4 +50,6 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Udp"] = "Udp";
     EnergyAppPermissionTypeEnum["ProvidedFiles"] = "ProvidedFiles";
     EnergyAppPermissionTypeEnum["Automation"] = "Automation";
+    EnergyAppPermissionTypeEnum["Savings"] = "Savings";
+    EnergyAppPermissionTypeEnum["FirmwareRegistry"] = "FirmwareRegistry";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

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

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

package/dist/cjs/energy-app.cjs

@@ -339,6 +339,23 @@ class EnergyApp {
     useFiles() {
         return this.energyAppSdk.useFiles();
     }
+    /**
+     * Gets the Firmware Registry API for the firmware images published with this
+     * package.
+     *
+     * Firmware versions are opaque vendor strings, so the update order is
+     * declared explicitly in the package definition as an upgrade graph. Call
+     * `getNextFirmware(currentVersion)` to resolve the single next step for a
+     * device — it returns `undefined` when the device is already up to date —
+     * then `requestDownloadUrl()` for a signed, time-limited URL the device can
+     * fetch itself.
+     * @returns The Firmware Registry API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `FirmwareRegistry`
+     *         permission is not granted.
+     */
+    useFirmwareRegistry() {
+        return this.energyAppSdk.useFirmwareRegistry();
+    }
     /**
      * Gets the Automation API for reading user-configured automations and
      * listening for their creation, update and removal. Apps holding the
@@ -352,6 +369,34 @@ class EnergyApp {
     useAutomations() {
         return this.energyAppSdk.useAutomations();
     }
+    /**
+     * Gets the Savings API for publishing day-scoped savings reports and reading
+     * them back. An energy manager app settles a finished day by replaying its
+     * measured environment against an uncontrolled simulation and publishes both
+     * worlds here; the platform stores the days and owns every aggregation above
+     * them (month, year, lifetime).
+     * @returns The Savings API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *         not granted.
+     */
+    useSavings() {
+        return this.energyAppSdk.useSavings();
+    }
+    /**
+     * Gets the Device Test API for answering the host's requests to test
+     * detected network devices. The app registers one handler; the host calls it
+     * from an onboarding v2 `device-test` action, from background auto-detection,
+     * or from a user-triggered re-test, and branches on whether appliances were
+     * found or created.
+     *
+     * Available to every app — this API is not permission-gated, though reaching
+     * a device (`NetworkDeviceAccess`) and creating an appliance (`Appliance`)
+     * still are.
+     * @returns The Device Test API instance
+     */
+    useDeviceTest() {
+        return this.energyAppSdk.useDeviceTest();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -38,7 +38,10 @@ import { EnergyAppConfigurationManager } from "./packages/energy-app-configurati
 import { EnergyAppApplianceEnergyManagerForecast } from "./packages/energy-app-appliance-energy-manager-forecast.cjs";
 import { EnergyAppBattery } from "./packages/energy-app-battery.cjs";
 import { EnergyAppFile } from "./packages/energy-app-file.cjs";
+import { EnergyAppFirmwareRegistry } from "./packages/energy-app-firmware-registry.cjs";
 import { EnergyAppAutomation } from "./packages/energy-app-automation.cjs";
+import { EnergyAppSavings } from "./packages/energy-app-savings.cjs";
+import { EnergyAppDeviceTest } from "./packages/energy-app-device-test.cjs";
 import { UseFetchOptions } from "./types/enyo-fetch.cjs";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
@@ -270,6 +273,21 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         permission is not granted.
      */
     useFiles(): EnergyAppFile;
+    /**
+     * Gets the Firmware Registry API for the firmware images published with this
+     * package.
+     *
+     * Firmware versions are opaque vendor strings, so the update order is
+     * declared explicitly in the package definition as an upgrade graph. Call
+     * `getNextFirmware(currentVersion)` to resolve the single next step for a
+     * device — it returns `undefined` when the device is already up to date —
+     * then `requestDownloadUrl()` for a signed, time-limited URL the device can
+     * fetch itself.
+     * @returns The Firmware Registry API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `FirmwareRegistry`
+     *         permission is not granted.
+     */
+    useFirmwareRegistry(): EnergyAppFirmwareRegistry;
     /**
      * Gets the Automation API for reading user-configured automations and
      * listening for their creation, update and removal. Apps holding the
@@ -281,6 +299,30 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      *         not granted.
      */
     useAutomations(): EnergyAppAutomation;
+    /**
+     * Gets the Savings API for publishing day-scoped savings reports and reading
+     * them back. An energy manager app settles a finished day by replaying its
+     * measured environment against an uncontrolled simulation and publishes both
+     * worlds here; the platform stores the days and owns every aggregation above
+     * them (month, year, lifetime).
+     * @returns The Savings API instance
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Savings` permission is
+     *         not granted.
+     */
+    useSavings(): EnergyAppSavings;
+    /**
+     * Gets the Device Test API for answering the host's requests to test
+     * detected network devices. The app registers one handler; the host calls it
+     * from an onboarding v2 `device-test` action, from background auto-detection,
+     * or from a user-triggered re-test, and branches on whether appliances were
+     * found or created.
+     *
+     * Available to every app — this API is not permission-gated, though reaching
+     * a device (`NetworkDeviceAccess`) and creating an appliance (`Appliance`)
+     * still are.
+     * @returns The Device Test API instance
+     */
+    useDeviceTest(): EnergyAppDeviceTest;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK