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

package/README.md

@@ -23,6 +23,10 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [User Features](#user-features)
   - [App Intelligence](#app-intelligence)
 - [Advanced Modbus Integration](#advanced-modbus-integration)
+- [Network Devices & Access Recovery](#network-devices--access-recovery)
+  - [NetworkAccessGuard](#networkaccessguard)
+  - [NetworkDeviceManager](#networkdevicemanager)
+  - [Startup pattern](#startup-pattern)
 - [Device Integrations](#device-integrations)
   - [IntegrationEnergyApp (Base Class)](#integrationenergyapp-base-class)
   - [HeatpumpIntegrationEnergyApp](#heatpumpintegrationenergyapp)
@@ -906,6 +910,165 @@ The Modbus implementation follows a clean, modular architecture:
 
 This modular design ensures maintainability, testability, and extensibility for future enhancements.
 
+## Network Devices & Access Recovery
+
+Packages that talk to local hardware over TCP (Modbus, SunSpec, EEBUS over SHIP, REST) must deal with two failure modes the `useNetworkDevices()` API exposes only at a low level:
+
+1. **Network-access-denied errors** — `EnyoNetworkDevice.accessStatus` is device-wide (`granted | denied | pending`). It does **not** carry per-port grants. A device can report `'granted'` while your package never received (or has since lost) access to its Modbus port, and the first symptom is the runtime error `[NET] Network access denied: Host '...:502' is not in the allowed list.` from a poll cycle.
+2. **User-driven access transitions** — the user revokes or re-grants access via the UI; the SDK fires `listenForDeviceAccessChange`, and packages need to disconnect / reconnect accordingly.
+
+The SDK ships two classes that encapsulate this lifecycle so packages don't reinvent it: a low-level **`NetworkAccessGuard`** for access-denied recovery, and a higher-level **`NetworkDeviceManager`** that wires the guard together with all the network-device listeners and the package's `ApplianceManager`.
+
+### NetworkAccessGuard
+
+`NetworkAccessGuard` recovers from access-denied errors raised by the SDK's network layer. Construct one per package with the ports it needs and a restored-callback that reconnects whatever client was reading from the device.
+
+```typescript
+import { NetworkAccessGuard } from '@enyo-energy/energy-app-sdk';
+
+const accessGuard = new NetworkAccessGuard(energyApp, {
+  ports: [502],
+  onAccessRestored: async (networkDeviceId) => {
+    await myModbusPool.reconnect(networkDeviceId);
+  },
+});
+
+// Precondition before a Modbus connect:
+if (!(await accessGuard.ensureAccess(networkDevice.id))) {
+  console.warn(`Modbus port access not granted for ${networkDevice.hostname}`);
+  return;
+}
+
+// Wrap any Modbus read so an access-denied error triggers recovery:
+const registers = await accessGuard.withAccessGuard(networkDevice.id, () =>
+  modbusClient.readHoldingRegisters(40000, 4),
+);
+```
+
+Recovery lifecycle:
+
+1. A read fails inside `withAccessGuard`. The guard detects the access-denied error via `NetworkAccessGuard.isAccessDeniedError(error)`, re-throws it to the caller (so the current poll cycle fails fast), and kicks off recovery in the background.
+2. The guard calls `requestDeviceAccess(deviceId, ports)`. If the SDK answers `'granted'` synchronously (the port was just missing from the allow-list and no user prompt is needed), the `onAccessRestored` handler fires immediately.
+3. Otherwise the device stays in a pending set and the `listenForDeviceAccessChange` registration fires the handler when the SDK reports the device flipped to `'granted'`.
+
+Re-entrancy: repeated `recoverAccess(...)` calls for the same device while a recovery is already in flight are coalesced — the handler runs exactly once per restoration.
+
+The guard exposes:
+
+| Method | Purpose |
+| --- | --- |
+| `static isAccessDeniedError(error)` | Recognise the SDK's access-denied error string |
+| `ensureAccess(deviceId)` | Idempotent port-allow-list request before a connect |
+| `withAccessGuard(deviceId, action)` | Wrap any async TCP call — recovers on access-denied |
+| `recoverAccess(deviceId)` | Explicit recovery trigger after catching an access-denied error |
+| `onAccessRestored(handler)` / `onAccessDenied(handler)` | Register additional handlers at runtime; returns a disposer |
+| `isRecovering(deviceId)` | Introspect whether a recovery is in flight |
+| `dispose()` | Tear down the SDK listener |
+
+### NetworkDeviceManager
+
+`NetworkDeviceManager` is the recommended entry point for any package that owns appliances backed by NetworkDevices. It bundles a `NetworkAccessGuard` with the three NetworkDevice-related SDK listeners (`listenForDeviceAccessChange`, `listenForDetectedDevice`, `listenForNetworkDeviceRemoved`) and resolves every event into **per-appliance callbacks** by joining against the package's `ApplianceManager`.
+
+```typescript
+import {
+  ApplianceManager,
+  EnergyApp,
+  NetworkDeviceManager,
+} from '@enyo-energy/energy-app-sdk';
+
+const energyApp = new EnergyApp();
+const applianceManager = await ApplianceManager.initialize(energyApp);
+
+const networkManager = await NetworkDeviceManager.initialize(
+  energyApp,
+  applianceManager,
+  {
+    ports: [502],
+    autoToggleApplianceState: true,
+    onApplianceAccessRestored: async ({ appliance, networkDeviceId }) => {
+      // Re-establish a Modbus session and restart the polling loop for this appliance.
+      await myModbusPool.reconnect(networkDeviceId);
+    },
+    onApplianceAccessRevoked: async ({ appliance, networkDeviceId }) => {
+      // User revoked access in the UI — tear down the connection.
+      await myModbusPool.disconnect(networkDeviceId);
+    },
+    onApplianceAccessDenied: async ({ appliance, networkDeviceId }) => {
+      // An access-denied error was just observed at runtime — mark the
+      // appliance offline. `autoToggleApplianceState: true` already does
+      // this; the handler is here for any custom side-effects.
+    },
+    onApplianceNetworkDeviceRemoved: async ({ appliance, networkDeviceId }) => {
+      await myModbusPool.disconnect(networkDeviceId);
+    },
+    onNetworkDeviceDetected: async (devices) => {
+      // New device found — classify + connect.
+      for (const device of devices) {
+        await classifyAndConnect(device);
+      }
+    },
+    onNetworkDeviceAccessChanged: async (deviceId, status) => {
+      // Optional: raw access-status passthrough, fires even for devices
+      // the package has no appliances on yet. Useful for first-time
+      // onboarding where a 'granted' transition needs to drive a discovery
+      // pass before any appliance exists.
+    },
+  },
+);
+
+// Every Modbus read inside the poll loop:
+await networkManager.withAccessGuard(networkDeviceId, () =>
+  modbusClient.readHoldingRegisters(40000, 4),
+);
+```
+
+What the manager handles for you:
+
+- **Access-denied recovery** — `withAccessGuard` / `ensureAccess` delegate to the bundled `NetworkAccessGuard`.
+- **User-driven transitions** — on `listenForDeviceAccessChange`, the manager dispatches `onApplianceAccessRestored` on `'granted'` and `onApplianceAccessRevoked` on `'denied'` / `'pending'`, resolving each transition into the per-appliance events your reconnect/disconnect code needs.
+- **Listener dedup** — the manager registers its access-change listener *before* the guard's, so a `'granted'` event during a recovery cycle dispatches only once (the manager observes `isRecovering(deviceId) === true` and skips, letting the guard's own restored callback win).
+- **Device removal** — on `listenForNetworkDeviceRemoved`, the manager fires `onApplianceNetworkDeviceRemoved` per affected appliance and clears its cache.
+- **Optional auto-state toggle** — with `autoToggleApplianceState: true`, the manager flips affected appliances to `EnyoApplianceStateEnum.Offline` on denial / revocation / removal, and back to `EnyoApplianceStateEnum.Connected` on restoration, via `applianceManager.updateApplianceState(...)`.
+
+Every handler is also registerable at runtime via `manager.onApplianceAccessRestored(fn)` / `onApplianceAccessDenied(fn)` / `onApplianceAccessRevoked(fn)` / `onApplianceNetworkDeviceRemoved(fn)` / `onNetworkDeviceDetected(fn)` / `onNetworkDeviceAccessChanged(fn)`, each returning a disposer.
+
+### Startup pattern
+
+The SDK's `listenForDeviceAccessChange` only fires on *transitions* — devices that are already `'granted'` from a previous session won't trigger it. Recommended startup flow for a package that supports both first-onboarding and warm restarts:
+
+```typescript
+client.register(async () => {
+  const applianceManager = await ApplianceManager.initialize(client);
+  const networkManager = await NetworkDeviceManager.initialize(
+    client,
+    applianceManager,
+    {
+      ports: [502],
+      onApplianceAccessRestored: ({ networkDeviceId }) => connectDevice(networkDeviceId),
+      onApplianceAccessRevoked: ({ networkDeviceId }) => disconnectDevice(networkDeviceId),
+      onNetworkDeviceDetected: async (devices) => {
+        for (const device of devices) await connectDevice(device.id);
+      },
+    },
+  );
+
+  // Warm-restart: reconnect to devices that already have access.
+  const granted = await client.useNetworkDevices().getDevices({ accessStatus: 'granted' });
+  for (const device of granted) {
+    await connectDevice(device.id);
+  }
+
+  client.updateEnergyAppState(EnergyAppStateEnum.Running);
+});
+
+async function connectDevice(networkDeviceId: string) {
+  if (!(await networkManager.ensureAccess(networkDeviceId))) return;
+  // ...classify, open modbus client, register appliances...
+}
+```
+
+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.
+
 ## Device Integrations
 
 Device Integrations are the high-level building blocks for apps that **drive a real device** — a heatpump, EV wallbox, PV inverter, battery storage system, or air-conditioning unit. Each integration class hides the data-bus plumbing for its appliance type so you only implement the business logic that physically controls the device.

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

@@ -31,6 +31,8 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["WeatherForecastUse"] = "WeatherForecastUse";
     EnergyAppPermissionTypeEnum["PvForecastRegister"] = "PvForecastRegister";
     EnergyAppPermissionTypeEnum["PvForecastUse"] = "PvForecastUse";
+    EnergyAppPermissionTypeEnum["DynamicPriceForecastRegister"] = "DynamicPriceForecastRegister";
+    EnergyAppPermissionTypeEnum["DynamicPriceForecastUse"] = "DynamicPriceForecastUse";
     EnergyAppPermissionTypeEnum["PvSystemRegister"] = "PvSystemRegister";
     EnergyAppPermissionTypeEnum["PvSystemUse"] = "PvSystemUse";
     EnergyAppPermissionTypeEnum["InverterControlCommands"] = "InverterControlCommands";

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

@@ -1,4 +1,4 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
+export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | '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' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp';
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -28,6 +28,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     WeatherForecastUse = "WeatherForecastUse",
     PvForecastRegister = "PvForecastRegister",
     PvForecastUse = "PvForecastUse",
+    DynamicPriceForecastRegister = "DynamicPriceForecastRegister",
+    DynamicPriceForecastUse = "DynamicPriceForecastUse",
     PvSystemRegister = "PvSystemRegister",
     PvSystemUse = "PvSystemUse",
     InverterControlCommands = "InverterControlCommands",

package/dist/cjs/energy-app.cjs

@@ -167,6 +167,16 @@ class EnergyApp {
     usePvForecasting() {
         return this.energyAppSdk.usePvForecasting();
     }
+    /**
+     * Gets the Dynamic Price Forecast API for publishing and consuming
+     * forward-looking electricity price forecasts (e.g. day-ahead spot
+     * prices). The data is forecast only — see
+     * {@link EnergyAppDynamicPriceForecast} for the full contract.
+     * @returns The Dynamic Price Forecast API instance
+     */
+    useDynamicPriceForecast() {
+        return this.energyAppSdk.useDynamicPriceForecast();
+    }
     /**
      * Gets the PV System API for managing PV system registrations and configurations.
      * Provides methods to register, retrieve, update, and remove PV systems

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

@@ -22,6 +22,7 @@ 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";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.cjs";
+import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.cjs";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
 import { EnergyAppSequenceGenerator } from "./packages/energy-app-sequence-generator.cjs";
 import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
@@ -125,6 +126,14 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The PV Forecasting API instance
      */
     usePvForecasting(): EnergyAppPvForecasting;
+    /**
+     * Gets the Dynamic Price Forecast API for publishing and consuming
+     * forward-looking electricity price forecasts (e.g. day-ahead spot
+     * prices). The data is forecast only — see
+     * {@link EnergyAppDynamicPriceForecast} for the full contract.
+     * @returns The Dynamic Price Forecast API instance
+     */
+    useDynamicPriceForecast(): EnergyAppDynamicPriceForecast;
     /**
      * Gets the PV System API for managing PV system registrations and configurations.
      * Provides methods to register, retrieve, update, and remove PV systems

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

@@ -21,6 +21,7 @@ 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";
 import { EnergyAppPvForecasting } from "./packages/energy-app-pv-forecasting.cjs";
+import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-price-forecast.cjs";
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
 import { EnergyAppSequenceGenerator } from "./packages/energy-app-sequence-generator.cjs";
 import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
@@ -102,6 +103,8 @@ export interface EnyoEnergyAppSdk {
     useWeatherForecasting: () => EnergyAppWeatherForecasting;
     /** Get the PV Forecasting API for managing PV forecast providers and retrieving PV forecasts */
     usePvForecasting: () => EnergyAppPvForecasting;
+    /** Get the Dynamic Price Forecast API for publishing and consuming forward-looking electricity price forecasts */
+    useDynamicPriceForecast: () => EnergyAppDynamicPriceForecast;
     /** Get the PV System API for managing PV system registrations and configurations */
     usePvSystem: () => EnergyAppPvSystem;
     /** Get the Sequence Generator API for generating unique sequential numbers per named sequence */

package/dist/cjs/implementations/network-devices/network-access-guard.cjs

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkAccessGuard = void 0;
+/**
+ * Recovers from "Network access denied" failures raised by the SDK's
+ * network layer when a Modbus (or other TCP) call hits a host whose
+ * port is not in the package's allowed list.
+ *
+ * Why this exists: `EnyoNetworkDevice.accessStatus` is device-wide
+ * (`granted | denied | pending`) — it does NOT carry per-port grants.
+ * A device can report `'granted'` while our package never received
+ * (or has since lost) access to its Modbus port, and the first
+ * symptom is a runtime `[NET] Network access denied: Host '...:502'
+ * is not in the allowed list. Allowed origins: [], Allowed network
+ * devices: []` error from a poll cycle. The guard provides one place
+ * to detect that error, re-request access, and dispatch a reconnect
+ * once access returns.
+ *
+ * Typical wiring:
+ * 1. Construct one guard per package with the ports it needs.
+ * 2. On every Modbus call site, either:
+ *    - wrap the call in {@link withAccessGuard}, which recovers in
+ *      the background on access-denied errors and re-throws, or
+ *    - catch the error, check {@link isAccessDeniedError}, and call
+ *      {@link recoverAccess} explicitly.
+ * 3. Register an `onAccessRestored` handler (via the config or
+ *    {@link onAccessRestored}) that performs the reconnect.
+ *
+ * Re-entrancy: repeated {@link recoverAccess} calls for the same
+ * device while a recovery is already in flight are coalesced — the
+ * restored handlers run exactly once per restoration.
+ *
+ * Precondition use: {@link ensureAccess} exposes the same idempotent
+ * `requestDeviceAccess` call so callers can use a single API for both
+ * "before a connect, make sure we have access" and "we just lost
+ * access, recover it".
+ */
+class NetworkAccessGuard {
+    energyApp;
+    /** Devices we've re-requested access for and are awaiting a 'granted' signal on. */
+    pending = new Set();
+    /** Listener IDs registered against the network-devices service. */
+    listenerIds = [];
+    restoredHandlers = new Set();
+    deniedHandlers = new Set();
+    ports;
+    enableLogging;
+    disposed = false;
+    /**
+     * Recognise the SDK's network-access-denied error so callers don't
+     * have to re-implement the substring check. Matches both variants
+     * observed in production logs.
+     * @param error The error to inspect (any value is accepted)
+     * @returns `true` if the error message looks like an access-denied error
+     */
+    static isAccessDeniedError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return /Network access denied|not in the allowed list/i.test(message);
+    }
+    /**
+     * Constructs a guard and immediately subscribes to the SDK's
+     * device-access-change events.
+     * @param energyApp The {@link EnergyApp} instance used to call the network-devices API
+     * @param config Required ports plus optional initial handlers and logging flag
+     */
+    constructor(energyApp, config) {
+        this.energyApp = energyApp;
+        this.ports = config.ports;
+        this.enableLogging = config.enableLogging ?? true;
+        if (config.onAccessRestored) {
+            this.restoredHandlers.add(config.onAccessRestored);
+        }
+        if (config.onAccessDenied) {
+            this.deniedHandlers.add(config.onAccessDenied);
+        }
+        const listenerId = this.energyApp.useNetworkDevices().listenForDeviceAccessChange((deviceId, status) => this.handleAccessChange(deviceId, status));
+        this.listenerIds.push(listenerId);
+    }
+    /**
+     * Registers an additional handler to be invoked whenever access
+     * is restored for any NetworkDevice the guard is recovering.
+     * @param handler The handler to register
+     * @returns A disposer that removes the handler again
+     */
+    onAccessRestored(handler) {
+        this.restoredHandlers.add(handler);
+        return () => this.restoredHandlers.delete(handler);
+    }
+    /**
+     * Registers an additional handler to be invoked whenever a
+     * recovery cycle starts (i.e. an access-denied error was just
+     * observed). Useful for marking dependent appliances offline.
+     * @param handler The handler to register
+     * @returns A disposer that removes the handler again
+     */
+    onAccessDenied(handler) {
+        this.deniedHandlers.add(handler);
+        return () => this.deniedHandlers.delete(handler);
+    }
+    /**
+     * Idempotently request access to the configured ports for the
+     * given NetworkDevice. Safe to call as a precondition before any
+     * Modbus operation.
+     * @param networkDeviceId The NetworkDevice to request access on
+     * @returns `true` when the SDK reports access is granted, `false` otherwise
+     */
+    async ensureAccess(networkDeviceId) {
+        try {
+            const result = await this.energyApp
+                .useNetworkDevices()
+                .requestDeviceAccess(networkDeviceId, this.ports);
+            return result.status === 'granted';
+        }
+        catch (error) {
+            if (this.enableLogging) {
+                console.warn(`[NetworkAccessGuard] requestDeviceAccess for ${networkDeviceId} failed: ${String(error)}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Wraps an async action so that an access-denied error
+     * automatically triggers a background recovery. The original
+     * error is re-thrown so the caller can fail-fast on the failed
+     * read; the next read after access is restored will succeed.
+     *
+     * Use this on Modbus call sites for the simplest integration:
+     * ```ts
+     * await guard.withAccessGuard(networkDeviceId, () =>
+     *   modbusClient.readHoldingRegisters(...));
+     * ```
+     * @param networkDeviceId The NetworkDevice the action targets
+     * @param action The async operation to perform
+     * @returns The resolved value of `action`
+     */
+    async withAccessGuard(networkDeviceId, action) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            if (NetworkAccessGuard.isAccessDeniedError(error)) {
+                void this.recoverAccess(networkDeviceId);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Drive recovery from an access-denied error: notify denied
+     * handlers, re-request access, and fire the restored handlers
+     * once access is granted. The restored handlers run at most once
+     * per recovery, regardless of whether the grant is observed
+     * synchronously (from the request response) or asynchronously
+     * (from the access-change listener).
+     * @param networkDeviceId The NetworkDevice whose access needs to be recovered
+     */
+    async recoverAccess(networkDeviceId) {
+        if (this.disposed)
+            return;
+        if (this.pending.has(networkDeviceId)) {
+            if (this.enableLogging) {
+                console.debug(`[NetworkAccessGuard] recovery already in flight for ${networkDeviceId}`);
+            }
+            return;
+        }
+        this.pending.add(networkDeviceId);
+        if (this.enableLogging) {
+            console.log(`[NetworkAccessGuard] re-requesting access for ${networkDeviceId} after access-denied`);
+        }
+        await this.fireDenied(networkDeviceId);
+        const granted = await this.ensureAccess(networkDeviceId);
+        if (!granted) {
+            // Leave the device in `pending` so the listener can fire the
+            // handlers when the user eventually accepts the request.
+            return;
+        }
+        // Synchronous grant — the listener won't observe a transition,
+        // so fire the handlers ourselves and clear the pending mark.
+        this.pending.delete(networkDeviceId);
+        await this.fireRestored(networkDeviceId);
+    }
+    /**
+     * Returns `true` if a recovery cycle is currently in flight for
+     * the given NetworkDevice. Mainly useful for tests and
+     * introspection.
+     */
+    isRecovering(networkDeviceId) {
+        return this.pending.has(networkDeviceId);
+    }
+    /**
+     * Tears down the SDK listener and clears all handlers. After
+     * calling this the guard should no longer be used.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const service = this.energyApp.useNetworkDevices();
+        for (const id of this.listenerIds) {
+            service.removeListener(id);
+        }
+        this.listenerIds.length = 0;
+        this.restoredHandlers.clear();
+        this.deniedHandlers.clear();
+        this.pending.clear();
+    }
+    async handleAccessChange(networkDeviceId, status) {
+        if (status !== 'granted')
+            return;
+        if (!this.pending.has(networkDeviceId))
+            return;
+        this.pending.delete(networkDeviceId);
+        await this.fireRestored(networkDeviceId);
+    }
+    async fireRestored(networkDeviceId) {
+        for (const handler of this.restoredHandlers) {
+            try {
+                await handler(networkDeviceId);
+            }
+            catch (error) {
+                if (this.enableLogging) {
+                    console.warn(`[NetworkAccessGuard] access-restored handler for ${networkDeviceId} failed: ${String(error)}`);
+                }
+            }
+        }
+    }
+    async fireDenied(networkDeviceId) {
+        for (const handler of this.deniedHandlers) {
+            try {
+                await handler(networkDeviceId);
+            }
+            catch (error) {
+                if (this.enableLogging) {
+                    console.warn(`[NetworkAccessGuard] access-denied handler for ${networkDeviceId} failed: ${String(error)}`);
+                }
+            }
+        }
+    }
+}
+exports.NetworkAccessGuard = NetworkAccessGuard;

package/dist/cjs/implementations/network-devices/network-access-guard.d.cts

@@ -0,0 +1,165 @@
+import type { EnergyApp } from "../../energy-app.cjs";
+/**
+ * Callback fired when access to a NetworkDevice's required ports
+ * becomes granted — either synchronously in response to a re-request
+ * or asynchronously via the SDK's `listenForDeviceAccessChange`
+ * listener.
+ */
+export type AccessRestoredHandler = (networkDeviceId: string) => void | Promise<void>;
+/**
+ * Callback fired when {@link NetworkAccessGuard.recoverAccess} is
+ * invoked because the caller has just observed an access-denied
+ * error. The handler runs at most once per recovery cycle, before
+ * the guard re-requests access.
+ */
+export type AccessDeniedHandler = (networkDeviceId: string) => void | Promise<void>;
+/**
+ * Construction options for {@link NetworkAccessGuard}.
+ */
+export interface NetworkAccessGuardConfig {
+    /**
+     * TCP ports the package requires on every target NetworkDevice.
+     * Forwarded to `requestDeviceAccess(deviceId, ports)` whenever the
+     * guard needs to (re-)negotiate access.
+     */
+    ports: number[];
+    /**
+     * Optional handler invoked when access is restored. Multiple
+     * handlers can be registered after construction via
+     * {@link NetworkAccessGuard.onAccessRestored}.
+     */
+    onAccessRestored?: AccessRestoredHandler;
+    /**
+     * Optional handler invoked the moment {@link NetworkAccessGuard.recoverAccess}
+     * is triggered — i.e. when a caller has just observed an
+     * access-denied error. Lets consumers mark dependent appliances
+     * offline before recovery completes.
+     */
+    onAccessDenied?: AccessDeniedHandler;
+    /** Toggle internal logging. Defaults to `true`. */
+    enableLogging?: boolean;
+}
+/**
+ * Recovers from "Network access denied" failures raised by the SDK's
+ * network layer when a Modbus (or other TCP) call hits a host whose
+ * port is not in the package's allowed list.
+ *
+ * Why this exists: `EnyoNetworkDevice.accessStatus` is device-wide
+ * (`granted | denied | pending`) — it does NOT carry per-port grants.
+ * A device can report `'granted'` while our package never received
+ * (or has since lost) access to its Modbus port, and the first
+ * symptom is a runtime `[NET] Network access denied: Host '...:502'
+ * is not in the allowed list. Allowed origins: [], Allowed network
+ * devices: []` error from a poll cycle. The guard provides one place
+ * to detect that error, re-request access, and dispatch a reconnect
+ * once access returns.
+ *
+ * Typical wiring:
+ * 1. Construct one guard per package with the ports it needs.
+ * 2. On every Modbus call site, either:
+ *    - wrap the call in {@link withAccessGuard}, which recovers in
+ *      the background on access-denied errors and re-throws, or
+ *    - catch the error, check {@link isAccessDeniedError}, and call
+ *      {@link recoverAccess} explicitly.
+ * 3. Register an `onAccessRestored` handler (via the config or
+ *    {@link onAccessRestored}) that performs the reconnect.
+ *
+ * Re-entrancy: repeated {@link recoverAccess} calls for the same
+ * device while a recovery is already in flight are coalesced — the
+ * restored handlers run exactly once per restoration.
+ *
+ * Precondition use: {@link ensureAccess} exposes the same idempotent
+ * `requestDeviceAccess` call so callers can use a single API for both
+ * "before a connect, make sure we have access" and "we just lost
+ * access, recover it".
+ */
+export declare class NetworkAccessGuard {
+    private readonly energyApp;
+    /** Devices we've re-requested access for and are awaiting a 'granted' signal on. */
+    private readonly pending;
+    /** Listener IDs registered against the network-devices service. */
+    private readonly listenerIds;
+    private readonly restoredHandlers;
+    private readonly deniedHandlers;
+    private readonly ports;
+    private readonly enableLogging;
+    private disposed;
+    /**
+     * Recognise the SDK's network-access-denied error so callers don't
+     * have to re-implement the substring check. Matches both variants
+     * observed in production logs.
+     * @param error The error to inspect (any value is accepted)
+     * @returns `true` if the error message looks like an access-denied error
+     */
+    static isAccessDeniedError(error: unknown): boolean;
+    /**
+     * Constructs a guard and immediately subscribes to the SDK's
+     * device-access-change events.
+     * @param energyApp The {@link EnergyApp} instance used to call the network-devices API
+     * @param config Required ports plus optional initial handlers and logging flag
+     */
+    constructor(energyApp: EnergyApp, config: NetworkAccessGuardConfig);
+    /**
+     * Registers an additional handler to be invoked whenever access
+     * is restored for any NetworkDevice the guard is recovering.
+     * @param handler The handler to register
+     * @returns A disposer that removes the handler again
+     */
+    onAccessRestored(handler: AccessRestoredHandler): () => void;
+    /**
+     * Registers an additional handler to be invoked whenever a
+     * recovery cycle starts (i.e. an access-denied error was just
+     * observed). Useful for marking dependent appliances offline.
+     * @param handler The handler to register
+     * @returns A disposer that removes the handler again
+     */
+    onAccessDenied(handler: AccessDeniedHandler): () => void;
+    /**
+     * Idempotently request access to the configured ports for the
+     * given NetworkDevice. Safe to call as a precondition before any
+     * Modbus operation.
+     * @param networkDeviceId The NetworkDevice to request access on
+     * @returns `true` when the SDK reports access is granted, `false` otherwise
+     */
+    ensureAccess(networkDeviceId: string): Promise<boolean>;
+    /**
+     * Wraps an async action so that an access-denied error
+     * automatically triggers a background recovery. The original
+     * error is re-thrown so the caller can fail-fast on the failed
+     * read; the next read after access is restored will succeed.
+     *
+     * Use this on Modbus call sites for the simplest integration:
+     * ```ts
+     * await guard.withAccessGuard(networkDeviceId, () =>
+     *   modbusClient.readHoldingRegisters(...));
+     * ```
+     * @param networkDeviceId The NetworkDevice the action targets
+     * @param action The async operation to perform
+     * @returns The resolved value of `action`
+     */
+    withAccessGuard<T>(networkDeviceId: string, action: () => Promise<T>): Promise<T>;
+    /**
+     * Drive recovery from an access-denied error: notify denied
+     * handlers, re-request access, and fire the restored handlers
+     * once access is granted. The restored handlers run at most once
+     * per recovery, regardless of whether the grant is observed
+     * synchronously (from the request response) or asynchronously
+     * (from the access-change listener).
+     * @param networkDeviceId The NetworkDevice whose access needs to be recovered
+     */
+    recoverAccess(networkDeviceId: string): Promise<void>;
+    /**
+     * Returns `true` if a recovery cycle is currently in flight for
+     * the given NetworkDevice. Mainly useful for tests and
+     * introspection.
+     */
+    isRecovering(networkDeviceId: string): boolean;
+    /**
+     * Tears down the SDK listener and clears all handlers. After
+     * calling this the guard should no longer be used.
+     */
+    dispose(): void;
+    private handleAccessChange;
+    private fireRestored;
+    private fireDenied;
+}