@enyo-energy/energy-app-sdk 0.0.121 → 0.0.122

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

@@ -43,4 +43,5 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Bluetooth"] = "Bluetooth";
     EnergyAppPermissionTypeEnum["Wifi"] = "Wifi";
     EnergyAppPermissionTypeEnum["ChildProcess"] = "ChildProcess";
+    EnergyAppPermissionTypeEnum["Udp"] = "Udp";
 })(EnergyAppPermissionTypeEnum || (exports.EnergyAppPermissionTypeEnum = EnergyAppPermissionTypeEnum = {}));

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';
+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 declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -39,5 +39,6 @@ export declare enum EnergyAppPermissionTypeEnum {
     Mqtt = "Mqtt",
     Bluetooth = "Bluetooth",
     Wifi = "Wifi",
-    ChildProcess = "ChildProcess"
+    ChildProcess = "ChildProcess",
+    Udp = "Udp"
 }

package/dist/cjs/energy-app.cjs

@@ -21,6 +21,7 @@ const version_js_1 = require("./version.cjs");
  */
 class EnergyApp {
     energyAppSdk;
+    udpInstance;
     constructor() {
         // in our runtime, there is an instance of energyAppSdk available which needs to be used here
         // if the energyAppSdk is not available, instantiate a mocked version for local development
@@ -246,6 +247,22 @@ class EnergyApp {
     useWifi() {
         return this.energyAppSdk.useWifi();
     }
+    /**
+     * Gets the UDP communication API for binding sockets and exchanging
+     * datagrams. Requires the `Udp` permission to be granted.
+     *
+     * Lazily instantiates a single {@link EnergyAppUdpServer} on first call
+     * and returns the same instance on subsequent calls. The runtime SDK's
+     * permission gate is invoked on every call so that revoked permissions
+     * are surfaced consistently with the other `use*` accessors.
+     *
+     * @returns The UDP API instance.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Udp` permission
+     *         is not granted.
+     */
+    useUdp() {
+        return this.energyAppSdk.useUdp();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -31,6 +31,7 @@ import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.cjs";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.cjs";
 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";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -50,6 +51,7 @@ import { EnergyAppWifi } from "./packages/energy-app-wifi.cjs";
  */
 export declare class EnergyApp implements EnyoEnergyAppSdk {
     private readonly energyAppSdk;
+    private udpInstance;
     constructor();
     isSystemOnline(): boolean;
     /**
@@ -184,6 +186,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The WiFi API instance
      */
     useWifi(): EnergyAppWifi;
+    /**
+     * Gets the UDP communication API for binding sockets and exchanging
+     * datagrams. Requires the `Udp` permission to be granted.
+     *
+     * Lazily instantiates a single {@link EnergyAppUdpServer} on first call
+     * and returns the same instance on subsequent calls. The runtime SDK's
+     * permission gate is invoked on every call so that revoked permissions
+     * are surfaced consistently with the other `use*` accessors.
+     *
+     * @returns The UDP API instance.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Udp` permission
+     *         is not granted.
+     */
+    useUdp(): EnergyAppUdp;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -30,6 +30,7 @@ import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.cjs";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.cjs";
 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";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -118,4 +119,6 @@ export interface EnyoEnergyAppSdk {
     useLearningPhase: () => EnergyAppLearningPhase;
     /** Get the WiFi API for scanning and listing known SSIDs */
     useWifi: () => EnergyAppWifi;
+    /** Get the UDP communication API for binding sockets and exchanging datagrams */
+    useUdp: () => EnergyAppUdp;
 }

package/dist/cjs/implementations/udp/EnergyAppUdpServer.cjs

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyAppUdpServer = exports.EnergyAppUdpBindError = void 0;
+const node_dgram_1 = require("node:dgram");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Error thrown when a UDP bind fails because the requested port is already
+ * in use (EADDRINUSE on the underlying socket).
+ *
+ * Other bind errors are surfaced as their original Error so this type stays
+ * a precise signal that "the port is taken".
+ */
+class EnergyAppUdpBindError extends Error {
+    port;
+    cause;
+    /**
+     * @param port - The port the bind was attempted on.
+     * @param cause - The original error emitted by the dgram socket.
+     */
+    constructor(port, cause) {
+        super(`Failed to bind UDP socket on port ${port}: address in use`);
+        this.port = port;
+        this.cause = cause;
+        this.name = 'EnergyAppUdpBindError';
+    }
+}
+exports.EnergyAppUdpBindError = EnergyAppUdpBindError;
+/**
+ * Default implementation of {@link EnergyAppUdpSocket} backed by `node:dgram`.
+ *
+ * Manages a single dgram socket and dispatches inbound messages to all
+ * registered handlers. Created internally by {@link EnergyAppUdpServer.bind}.
+ */
+class EnergyAppUdpSocketImpl {
+    socket;
+    handlers = new Map();
+    closed = false;
+    /**
+     * @param socket - The bound dgram socket this wrapper owns.
+     */
+    constructor(socket) {
+        this.socket = socket;
+        this.socket.on('message', (data, rinfo) => {
+            const msg = {
+                data,
+                remotePort: rinfo.port,
+                remoteAddress: rinfo.address,
+            };
+            for (const handler of this.handlers.values()) {
+                handler(msg);
+            }
+        });
+    }
+    /**
+     * Returns the locally bound address descriptor. The dgram socket reports
+     * the kernel-assigned port if the bind was issued with port 0.
+     *
+     * @throws Error if the socket has been closed.
+     */
+    address() {
+        if (this.closed) {
+            throw new Error('UDP socket is closed');
+        }
+        const info = this.socket.address();
+        return {
+            address: info.address,
+            port: info.port,
+            family: info.family,
+        };
+    }
+    /**
+     * Register an inbound-message handler.
+     *
+     * @param handler - Callback invoked for every received datagram.
+     * @returns A handle id that can be passed to {@link off}.
+     */
+    onMessage(handler) {
+        const id = (0, node_crypto_1.randomUUID)();
+        this.handlers.set(id, handler);
+        return id;
+    }
+    /**
+     * Remove a previously registered handler. Unknown ids are ignored.
+     *
+     * @param handlerId - The id returned by {@link onMessage}.
+     */
+    off(handlerId) {
+        this.handlers.delete(handlerId);
+    }
+    /**
+     * Send a datagram. Resolves when the dgram callback fires with no error.
+     *
+     * @param data - Payload bytes.
+     * @param port - Destination port.
+     * @param address - Destination host/IP.
+     * @returns Promise that resolves once the kernel accepted the datagram.
+     * @throws Error if the socket has been closed or the send call fails.
+     */
+    send(data, port, address) {
+        if (this.closed) {
+            return Promise.reject(new Error('UDP socket is closed'));
+        }
+        return new Promise((resolve, reject) => {
+            this.socket.send(data, port, address, (err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * Close the underlying dgram socket. Idempotent.
+     *
+     * @returns Promise that resolves once the dgram `close` event fires (or
+     *          immediately if the socket was already closed).
+     */
+    close() {
+        if (this.closed) {
+            return Promise.resolve();
+        }
+        this.closed = true;
+        return new Promise((resolve) => {
+            this.socket.once('close', () => resolve());
+            this.socket.close();
+        });
+    }
+}
+/**
+ * Default implementation of {@link EnergyAppUdp}.
+ *
+ * Thin wrapper around `node:dgram` that creates IPv4 UDP sockets. Used as the
+ * concrete instance returned by {@link EnergyApp.useUdp}.
+ *
+ * @example
+ * ```typescript
+ * const udp = new EnergyAppUdpServer();
+ * const socket = await udp.bind({ port: 9000, reuseAddr: true });
+ * ```
+ */
+class EnergyAppUdpServer {
+    /**
+     * Bind a UDP socket using `node:dgram`.
+     *
+     * Resolves once the `listening` event fires. If the underlying socket
+     * emits an `error` with code `EADDRINUSE`, the promise rejects with
+     * {@link EnergyAppUdpBindError}; other errors propagate unchanged.
+     *
+     * @param options - Bind configuration (port, host, reuseAddr).
+     * @returns A bound {@link EnergyAppUdpSocket}.
+     */
+    bind(options) {
+        return new Promise((resolve, reject) => {
+            const socket = (0, node_dgram_1.createSocket)({ type: 'udp4', reuseAddr: false });
+            const onError = (err) => {
+                socket.removeListener('listening', onListening);
+                if (err.code === 'EADDRINUSE') {
+                    reject(new EnergyAppUdpBindError(options.port, err));
+                    return;
+                }
+                reject(err);
+            };
+            const onListening = () => {
+                socket.removeListener('error', onError);
+                resolve(new EnergyAppUdpSocketImpl(socket));
+            };
+            socket.once('error', onError);
+            socket.once('listening', onListening);
+            socket.bind(options.port, '0.0.0.0');
+        });
+    }
+}
+exports.EnergyAppUdpServer = EnergyAppUdpServer;

package/dist/cjs/implementations/udp/EnergyAppUdpServer.d.cts

@@ -0,0 +1,42 @@
+import { EnergyAppUdp, EnergyAppUdpSocket, UdpBindOptions } from '../../packages/energy-app-udp.cjs';
+/**
+ * Error thrown when a UDP bind fails because the requested port is already
+ * in use (EADDRINUSE on the underlying socket).
+ *
+ * Other bind errors are surfaced as their original Error so this type stays
+ * a precise signal that "the port is taken".
+ */
+export declare class EnergyAppUdpBindError extends Error {
+    readonly port: number;
+    readonly cause: Error;
+    /**
+     * @param port - The port the bind was attempted on.
+     * @param cause - The original error emitted by the dgram socket.
+     */
+    constructor(port: number, cause: Error);
+}
+/**
+ * Default implementation of {@link EnergyAppUdp}.
+ *
+ * Thin wrapper around `node:dgram` that creates IPv4 UDP sockets. Used as the
+ * concrete instance returned by {@link EnergyApp.useUdp}.
+ *
+ * @example
+ * ```typescript
+ * const udp = new EnergyAppUdpServer();
+ * const socket = await udp.bind({ port: 9000, reuseAddr: true });
+ * ```
+ */
+export declare class EnergyAppUdpServer implements EnergyAppUdp {
+    /**
+     * Bind a UDP socket using `node:dgram`.
+     *
+     * Resolves once the `listening` event fires. If the underlying socket
+     * emits an `error` with code `EADDRINUSE`, the promise rejects with
+     * {@link EnergyAppUdpBindError}; other errors propagate unchanged.
+     *
+     * @param options - Bind configuration (port, host, reuseAddr).
+     * @returns A bound {@link EnergyAppUdpSocket}.
+     */
+    bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
+}

package/dist/cjs/index.cjs

@@ -59,6 +59,7 @@ __exportStar(require("./types/enyo-learning-phase.cjs"), exports);
 __exportStar(require("./packages/energy-app-learning-phase.cjs"), exports);
 __exportStar(require("./types/enyo-wifi.cjs"), exports);
 __exportStar(require("./packages/energy-app-wifi.cjs"), exports);
+__exportStar(require("./packages/energy-app-udp.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

@@ -43,6 +43,7 @@ export * from './types/enyo-learning-phase.cjs';
 export * from './packages/energy-app-learning-phase.cjs';
 export * from './types/enyo-wifi.cjs';
 export * from './packages/energy-app-wifi.cjs';
+export * from './packages/energy-app-udp.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-udp.cjs

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

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

@@ -0,0 +1,110 @@
+/**
+ * Options used when binding a UDP socket via {@link EnergyAppUdp.bind}.
+ */
+export interface UdpBindOptions {
+    /** Bind port. 0 selects an ephemeral port. */
+    port: number;
+}
+/**
+ * A single inbound datagram delivered to a handler registered with
+ * {@link EnergyAppUdpSocket.onMessage}.
+ */
+export interface UdpInboundMessage {
+    /** Raw payload bytes of the datagram. */
+    data: Buffer;
+    /** Remote port the datagram originated from. */
+    remotePort: number;
+    /** Remote address (IPv4/IPv6 textual form) the datagram originated from. */
+    remoteAddress: string;
+}
+/**
+ * Represents an active UDP socket bound to a local address/port.
+ *
+ * Obtained by calling {@link EnergyAppUdp.bind}. Provides methods for sending
+ * datagrams, subscribing to inbound messages, querying the resolved local
+ * address, and closing the socket.
+ */
+export interface EnergyAppUdpSocket {
+    /**
+     * The address the socket is actually bound to.
+     * If port 0 was requested, the kernel-assigned port is returned here.
+     *
+     * @returns The bound local address descriptor.
+     * @throws If the socket has been closed.
+     */
+    address(): {
+        address: string;
+        port: number;
+        family: 'IPv4' | 'IPv6';
+    };
+    /**
+     * Subscribe to inbound datagrams.
+     *
+     * Multiple handlers can be attached and each will receive a copy of every
+     * inbound message. The returned handle can be passed to {@link off} to
+     * stop receiving messages on that subscription.
+     *
+     * @param handler - Callback invoked for every datagram received.
+     * @returns A unique handle that identifies this subscription.
+     */
+    onMessage(handler: (msg: UdpInboundMessage) => void): string;
+    /**
+     * Stop listening — removes a previously registered handler.
+     *
+     * @param handlerId - The id returned by {@link onMessage}. Unknown ids
+     *                    are ignored.
+     */
+    off(handlerId: string): void;
+    /**
+     * Send a datagram to the given peer.
+     *
+     * @param data - Raw payload bytes to transmit.
+     * @param port - Destination port on the peer.
+     * @param address - Destination address on the peer (IPv4/IPv6 textual form
+     *                  or hostname).
+     * @returns A promise that resolves once the kernel has accepted the
+     *          datagram and rejects if the underlying send call fails.
+     */
+    send(data: Buffer, port: number, address: string): Promise<void>;
+    /**
+     * Close the socket and release the bound port.
+     *
+     * Subsequent calls to {@link send} reject and {@link address} throws.
+     * Idempotent close-after-close resolves without error.
+     *
+     * @returns A promise that resolves once the underlying socket has emitted
+     *          its `close` event.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Interface for raw UDP communication in enyo packages.
+ *
+ * Provides a thin abstraction over `node:dgram` for binding sockets and
+ * exchanging datagrams. Requires the package to declare the `Udp` permission.
+ *
+ * @example
+ * ```typescript
+ * const udp = energyApp.useUdp();
+ * const socket = await udp.bind({ port: 0 });
+ * const handlerId = socket.onMessage((msg) => {
+ *     console.log(`Received ${msg.data.length} bytes from ${msg.remoteAddress}:${msg.remotePort}`);
+ * });
+ * await socket.send(Buffer.from('hello'), 5005, '192.168.1.42');
+ * socket.off(handlerId);
+ * await socket.close();
+ * ```
+ */
+export interface EnergyAppUdp {
+    /**
+     * Bind a UDP socket on the requested host/port.
+     *
+     * Resolves once the underlying socket has emitted its `listening` event.
+     *
+     * @param options - Bind configuration (see {@link UdpBindOptions}).
+     * @returns A bound socket ready to send and receive datagrams.
+     * @throws {EnergyAppUdpBindError} If the requested port is already in use
+     *         (EADDRINUSE). Other errors propagate as their original Error.
+     */
+    bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
+}

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

package/dist/energy-app-permission.type.d.ts

@@ -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';
+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 declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -39,5 +39,6 @@ export declare enum EnergyAppPermissionTypeEnum {
     Mqtt = "Mqtt",
     Bluetooth = "Bluetooth",
     Wifi = "Wifi",
-    ChildProcess = "ChildProcess"
+    ChildProcess = "ChildProcess",
+    Udp = "Udp"
 }

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

@@ -40,4 +40,5 @@ export var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["Bluetooth"] = "Bluetooth";
     EnergyAppPermissionTypeEnum["Wifi"] = "Wifi";
     EnergyAppPermissionTypeEnum["ChildProcess"] = "ChildProcess";
+    EnergyAppPermissionTypeEnum["Udp"] = "Udp";
 })(EnergyAppPermissionTypeEnum || (EnergyAppPermissionTypeEnum = {}));

package/dist/energy-app.d.ts

@@ -31,6 +31,7 @@ import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.js";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.js";
 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";
 /**
  * Concrete implementation of {@link EnyoEnergyAppSdk} that delegates every call
  * to the runtime-provided `energyAppSdkInstance` global.
@@ -50,6 +51,7 @@ import { EnergyAppWifi } from "./packages/energy-app-wifi.js";
  */
 export declare class EnergyApp implements EnyoEnergyAppSdk {
     private readonly energyAppSdk;
+    private udpInstance;
     constructor();
     isSystemOnline(): boolean;
     /**
@@ -184,6 +186,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The WiFi API instance
      */
     useWifi(): EnergyAppWifi;
+    /**
+     * Gets the UDP communication API for binding sockets and exchanging
+     * datagrams. Requires the `Udp` permission to be granted.
+     *
+     * Lazily instantiates a single {@link EnergyAppUdpServer} on first call
+     * and returns the same instance on subsequent calls. The runtime SDK's
+     * permission gate is invoked on every call so that revoked permissions
+     * are surfaced consistently with the other `use*` accessors.
+     *
+     * @returns The UDP API instance.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Udp` permission
+     *         is not granted.
+     */
+    useUdp(): EnergyAppUdp;
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

package/dist/energy-app.js

@@ -18,6 +18,7 @@ import { getSdkVersion } from "./version.js";
  */
 export class EnergyApp {
     energyAppSdk;
+    udpInstance;
     constructor() {
         // in our runtime, there is an instance of energyAppSdk available which needs to be used here
         // if the energyAppSdk is not available, instantiate a mocked version for local development
@@ -243,6 +244,22 @@ export class EnergyApp {
     useWifi() {
         return this.energyAppSdk.useWifi();
     }
+    /**
+     * Gets the UDP communication API for binding sockets and exchanging
+     * datagrams. Requires the `Udp` permission to be granted.
+     *
+     * Lazily instantiates a single {@link EnergyAppUdpServer} on first call
+     * and returns the same instance on subsequent calls. The runtime SDK's
+     * permission gate is invoked on every call so that revoked permissions
+     * are surfaced consistently with the other `use*` accessors.
+     *
+     * @returns The UDP API instance.
+     * @throws {EnergyAppPermissionNotGrantedError} If the `Udp` permission
+     *         is not granted.
+     */
+    useUdp() {
+        return this.energyAppSdk.useUdp();
+    }
     /**
      * Gets the current SDK version.
      * @returns The semantic version string of the SDK

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

@@ -30,6 +30,7 @@ import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.js";
 import { EnergyAppDiagnostics } from "./packages/energy-app-diagnostics.js";
 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";
 export declare enum EnergyAppStateEnum {
     Launching = "launching",
     Running = "running",
@@ -118,4 +119,6 @@ export interface EnyoEnergyAppSdk {
     useLearningPhase: () => EnergyAppLearningPhase;
     /** Get the WiFi API for scanning and listing known SSIDs */
     useWifi: () => EnergyAppWifi;
+    /** Get the UDP communication API for binding sockets and exchanging datagrams */
+    useUdp: () => EnergyAppUdp;
 }

package/dist/implementations/udp/EnergyAppUdpServer.d.ts

@@ -0,0 +1,42 @@
+import { EnergyAppUdp, EnergyAppUdpSocket, UdpBindOptions } from '../../packages/energy-app-udp.js';
+/**
+ * Error thrown when a UDP bind fails because the requested port is already
+ * in use (EADDRINUSE on the underlying socket).
+ *
+ * Other bind errors are surfaced as their original Error so this type stays
+ * a precise signal that "the port is taken".
+ */
+export declare class EnergyAppUdpBindError extends Error {
+    readonly port: number;
+    readonly cause: Error;
+    /**
+     * @param port - The port the bind was attempted on.
+     * @param cause - The original error emitted by the dgram socket.
+     */
+    constructor(port: number, cause: Error);
+}
+/**
+ * Default implementation of {@link EnergyAppUdp}.
+ *
+ * Thin wrapper around `node:dgram` that creates IPv4 UDP sockets. Used as the
+ * concrete instance returned by {@link EnergyApp.useUdp}.
+ *
+ * @example
+ * ```typescript
+ * const udp = new EnergyAppUdpServer();
+ * const socket = await udp.bind({ port: 9000, reuseAddr: true });
+ * ```
+ */
+export declare class EnergyAppUdpServer implements EnergyAppUdp {
+    /**
+     * Bind a UDP socket using `node:dgram`.
+     *
+     * Resolves once the `listening` event fires. If the underlying socket
+     * emits an `error` with code `EADDRINUSE`, the promise rejects with
+     * {@link EnergyAppUdpBindError}; other errors propagate unchanged.
+     *
+     * @param options - Bind configuration (port, host, reuseAddr).
+     * @returns A bound {@link EnergyAppUdpSocket}.
+     */
+    bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
+}

package/dist/implementations/udp/EnergyAppUdpServer.js

@@ -0,0 +1,169 @@
+import { createSocket } from 'node:dgram';
+import { randomUUID } from 'node:crypto';
+/**
+ * Error thrown when a UDP bind fails because the requested port is already
+ * in use (EADDRINUSE on the underlying socket).
+ *
+ * Other bind errors are surfaced as their original Error so this type stays
+ * a precise signal that "the port is taken".
+ */
+export class EnergyAppUdpBindError extends Error {
+    port;
+    cause;
+    /**
+     * @param port - The port the bind was attempted on.
+     * @param cause - The original error emitted by the dgram socket.
+     */
+    constructor(port, cause) {
+        super(`Failed to bind UDP socket on port ${port}: address in use`);
+        this.port = port;
+        this.cause = cause;
+        this.name = 'EnergyAppUdpBindError';
+    }
+}
+/**
+ * Default implementation of {@link EnergyAppUdpSocket} backed by `node:dgram`.
+ *
+ * Manages a single dgram socket and dispatches inbound messages to all
+ * registered handlers. Created internally by {@link EnergyAppUdpServer.bind}.
+ */
+class EnergyAppUdpSocketImpl {
+    socket;
+    handlers = new Map();
+    closed = false;
+    /**
+     * @param socket - The bound dgram socket this wrapper owns.
+     */
+    constructor(socket) {
+        this.socket = socket;
+        this.socket.on('message', (data, rinfo) => {
+            const msg = {
+                data,
+                remotePort: rinfo.port,
+                remoteAddress: rinfo.address,
+            };
+            for (const handler of this.handlers.values()) {
+                handler(msg);
+            }
+        });
+    }
+    /**
+     * Returns the locally bound address descriptor. The dgram socket reports
+     * the kernel-assigned port if the bind was issued with port 0.
+     *
+     * @throws Error if the socket has been closed.
+     */
+    address() {
+        if (this.closed) {
+            throw new Error('UDP socket is closed');
+        }
+        const info = this.socket.address();
+        return {
+            address: info.address,
+            port: info.port,
+            family: info.family,
+        };
+    }
+    /**
+     * Register an inbound-message handler.
+     *
+     * @param handler - Callback invoked for every received datagram.
+     * @returns A handle id that can be passed to {@link off}.
+     */
+    onMessage(handler) {
+        const id = randomUUID();
+        this.handlers.set(id, handler);
+        return id;
+    }
+    /**
+     * Remove a previously registered handler. Unknown ids are ignored.
+     *
+     * @param handlerId - The id returned by {@link onMessage}.
+     */
+    off(handlerId) {
+        this.handlers.delete(handlerId);
+    }
+    /**
+     * Send a datagram. Resolves when the dgram callback fires with no error.
+     *
+     * @param data - Payload bytes.
+     * @param port - Destination port.
+     * @param address - Destination host/IP.
+     * @returns Promise that resolves once the kernel accepted the datagram.
+     * @throws Error if the socket has been closed or the send call fails.
+     */
+    send(data, port, address) {
+        if (this.closed) {
+            return Promise.reject(new Error('UDP socket is closed'));
+        }
+        return new Promise((resolve, reject) => {
+            this.socket.send(data, port, address, (err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * Close the underlying dgram socket. Idempotent.
+     *
+     * @returns Promise that resolves once the dgram `close` event fires (or
+     *          immediately if the socket was already closed).
+     */
+    close() {
+        if (this.closed) {
+            return Promise.resolve();
+        }
+        this.closed = true;
+        return new Promise((resolve) => {
+            this.socket.once('close', () => resolve());
+            this.socket.close();
+        });
+    }
+}
+/**
+ * Default implementation of {@link EnergyAppUdp}.
+ *
+ * Thin wrapper around `node:dgram` that creates IPv4 UDP sockets. Used as the
+ * concrete instance returned by {@link EnergyApp.useUdp}.
+ *
+ * @example
+ * ```typescript
+ * const udp = new EnergyAppUdpServer();
+ * const socket = await udp.bind({ port: 9000, reuseAddr: true });
+ * ```
+ */
+export class EnergyAppUdpServer {
+    /**
+     * Bind a UDP socket using `node:dgram`.
+     *
+     * Resolves once the `listening` event fires. If the underlying socket
+     * emits an `error` with code `EADDRINUSE`, the promise rejects with
+     * {@link EnergyAppUdpBindError}; other errors propagate unchanged.
+     *
+     * @param options - Bind configuration (port, host, reuseAddr).
+     * @returns A bound {@link EnergyAppUdpSocket}.
+     */
+    bind(options) {
+        return new Promise((resolve, reject) => {
+            const socket = createSocket({ type: 'udp4', reuseAddr: false });
+            const onError = (err) => {
+                socket.removeListener('listening', onListening);
+                if (err.code === 'EADDRINUSE') {
+                    reject(new EnergyAppUdpBindError(options.port, err));
+                    return;
+                }
+                reject(err);
+            };
+            const onListening = () => {
+                socket.removeListener('error', onError);
+                resolve(new EnergyAppUdpSocketImpl(socket));
+            };
+            socket.once('error', onError);
+            socket.once('listening', onListening);
+            socket.bind(options.port, '0.0.0.0');
+        });
+    }
+}

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export * from './types/enyo-learning-phase.js';
 export * from './packages/energy-app-learning-phase.js';
 export * from './types/enyo-wifi.js';
 export * from './packages/energy-app-wifi.js';
+export * from './packages/energy-app-udp.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

@@ -43,6 +43,7 @@ export * from './types/enyo-learning-phase.js';
 export * from './packages/energy-app-learning-phase.js';
 export * from './types/enyo-wifi.js';
 export * from './packages/energy-app-wifi.js';
+export * from './packages/energy-app-udp.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-udp.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Options used when binding a UDP socket via {@link EnergyAppUdp.bind}.
+ */
+export interface UdpBindOptions {
+    /** Bind port. 0 selects an ephemeral port. */
+    port: number;
+}
+/**
+ * A single inbound datagram delivered to a handler registered with
+ * {@link EnergyAppUdpSocket.onMessage}.
+ */
+export interface UdpInboundMessage {
+    /** Raw payload bytes of the datagram. */
+    data: Buffer;
+    /** Remote port the datagram originated from. */
+    remotePort: number;
+    /** Remote address (IPv4/IPv6 textual form) the datagram originated from. */
+    remoteAddress: string;
+}
+/**
+ * Represents an active UDP socket bound to a local address/port.
+ *
+ * Obtained by calling {@link EnergyAppUdp.bind}. Provides methods for sending
+ * datagrams, subscribing to inbound messages, querying the resolved local
+ * address, and closing the socket.
+ */
+export interface EnergyAppUdpSocket {
+    /**
+     * The address the socket is actually bound to.
+     * If port 0 was requested, the kernel-assigned port is returned here.
+     *
+     * @returns The bound local address descriptor.
+     * @throws If the socket has been closed.
+     */
+    address(): {
+        address: string;
+        port: number;
+        family: 'IPv4' | 'IPv6';
+    };
+    /**
+     * Subscribe to inbound datagrams.
+     *
+     * Multiple handlers can be attached and each will receive a copy of every
+     * inbound message. The returned handle can be passed to {@link off} to
+     * stop receiving messages on that subscription.
+     *
+     * @param handler - Callback invoked for every datagram received.
+     * @returns A unique handle that identifies this subscription.
+     */
+    onMessage(handler: (msg: UdpInboundMessage) => void): string;
+    /**
+     * Stop listening — removes a previously registered handler.
+     *
+     * @param handlerId - The id returned by {@link onMessage}. Unknown ids
+     *                    are ignored.
+     */
+    off(handlerId: string): void;
+    /**
+     * Send a datagram to the given peer.
+     *
+     * @param data - Raw payload bytes to transmit.
+     * @param port - Destination port on the peer.
+     * @param address - Destination address on the peer (IPv4/IPv6 textual form
+     *                  or hostname).
+     * @returns A promise that resolves once the kernel has accepted the
+     *          datagram and rejects if the underlying send call fails.
+     */
+    send(data: Buffer, port: number, address: string): Promise<void>;
+    /**
+     * Close the socket and release the bound port.
+     *
+     * Subsequent calls to {@link send} reject and {@link address} throws.
+     * Idempotent close-after-close resolves without error.
+     *
+     * @returns A promise that resolves once the underlying socket has emitted
+     *          its `close` event.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Interface for raw UDP communication in enyo packages.
+ *
+ * Provides a thin abstraction over `node:dgram` for binding sockets and
+ * exchanging datagrams. Requires the package to declare the `Udp` permission.
+ *
+ * @example
+ * ```typescript
+ * const udp = energyApp.useUdp();
+ * const socket = await udp.bind({ port: 0 });
+ * const handlerId = socket.onMessage((msg) => {
+ *     console.log(`Received ${msg.data.length} bytes from ${msg.remoteAddress}:${msg.remotePort}`);
+ * });
+ * await socket.send(Buffer.from('hello'), 5005, '192.168.1.42');
+ * socket.off(handlerId);
+ * await socket.close();
+ * ```
+ */
+export interface EnergyAppUdp {
+    /**
+     * Bind a UDP socket on the requested host/port.
+     *
+     * Resolves once the underlying socket has emitted its `listening` event.
+     *
+     * @param options - Bind configuration (see {@link UdpBindOptions}).
+     * @returns A bound socket ready to send and receive datagrams.
+     * @throws {EnergyAppUdpBindError} If the requested port is already in use
+     *         (EADDRINUSE). Other errors propagate as their original Error.
+     */
+    bind(options: UdpBindOptions): Promise<EnergyAppUdpSocket>;
+}

package/dist/packages/energy-app-udp.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.121";
+export declare const SDK_VERSION = "0.0.122";
 /**
  * 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.121';
+export const SDK_VERSION = '0.0.122';
 /**
  * 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.121",
+  "version": "0.0.122",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",