edilkamin 1.11.0 → 1.12.0

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "edilkamin",
-    "version": "1.11.0",
+    "version": "1.12.0",
     "description": "",
     "main": "dist/cjs/src/index.js",
     "module": "dist/esm/src/index.js",

package/dist/cjs/src/bluetooth-utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bleToWifiMac = void 0;
+const mac_utils_1 = require("./mac-utils");
 /**
  * Converts a BLE MAC address to WiFi MAC address.
  * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
@@ -13,12 +14,7 @@ exports.bleToWifiMac = void 0;
  * bleToWifiMac("a8032afed50a")      // returns "a8032afed508"
  */
 const bleToWifiMac = (bleMac) => {
-    // Remove colons, dashes, and convert to lowercase
-    const normalized = bleMac.replace(/[:-]/g, "").toLowerCase();
-    // Validate MAC address format (12 hex characters)
-    if (!/^[0-9a-f]{12}$/.test(normalized)) {
-        throw new Error(`Invalid MAC address format: ${bleMac}`);
-    }
+    const normalized = (0, mac_utils_1.normalizeMac)(bleMac);
     // Convert to number, subtract 2, convert back to hex
     const bleValue = BigInt(`0x${normalized}`);
     const wifiValue = bleValue - BigInt(2);

package/dist/cjs/src/cli.js

@@ -19,6 +19,7 @@ const readline_1 = __importDefault(require("readline"));
 const package_json_1 = require("../package.json");
 const constants_1 = require("./constants");
 const library_1 = require("./library");
+const mac_utils_1 = require("./mac-utils");
 const token_storage_1 = require("./token-storage");
 const types_1 = require("./types");
 const promptPassword = () => {
@@ -72,7 +73,7 @@ const addLegacyOption = (command) => command.option("--legacy", "Use legacy API
  */
 const initializeCommand = (options) => __awaiter(void 0, void 0, void 0, function* () {
     const { username, password, mac, legacy = false } = options;
-    const normalizedMac = mac.replace(/:/g, "");
+    const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
     // Initialize file storage for session persistence
     const storage = (0, token_storage_1.createFileStorage)();
     (0, library_1.configureAmplify)(storage);
@@ -395,7 +396,7 @@ const createProgram = () => {
         .command("getFanSpeed")
         .description("Retrieve fan speed by index (1-3)")).requiredOption("-i, --index <number>", "Fan index (1, 2, or 3)", parseInt))).action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, index, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
         let jwtToken;
@@ -418,7 +419,7 @@ const createProgram = () => {
         .command("getTargetTemperature")
         .description("Retrieve target temperature by environment index (1-3)")).requiredOption("-i, --index <number>", "Environment index (1, 2, or 3)", parseInt))).action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, index, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
         let jwtToken;
@@ -444,7 +445,7 @@ const createProgram = () => {
         .requiredOption("-i, --index <number>", "Fan index (1, 2, or 3)", parseInt)
         .requiredOption("-v, --value <number>", "Fan speed (0-5)", parseFloat))).action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, index, value, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
         let jwtToken;
@@ -469,7 +470,7 @@ const createProgram = () => {
         .requiredOption("-i, --index <number>", "Environment index (1, 2, or 3)", parseInt)
         .requiredOption("-v, --value <number>", "Temperature in degrees Celsius", parseFloat))).action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, index, value, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
         let jwtToken;
@@ -493,7 +494,7 @@ const createProgram = () => {
         .command("getAlarmHistory")
         .description("Get alarm history log with human-readable descriptions")))).action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
         let jwtToken;
@@ -524,7 +525,7 @@ const createProgram = () => {
         .requiredOption("-r, --room <deviceRoom>", "Room name")
         .action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, serial, name, room, legacy = false, } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         // Initialize file storage for session persistence
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);
@@ -553,7 +554,7 @@ const createProgram = () => {
         .requiredOption("-r, --room <deviceRoom>", "Room name")
         .action((options) => __awaiter(void 0, void 0, void 0, function* () {
         const { username, password, mac, name, room, legacy = false } = options;
-        const normalizedMac = mac.replace(/:/g, "");
+        const normalizedMac = (0, mac_utils_1.normalizeMac)(mac);
         // Initialize file storage for session persistence
         const storage = (0, token_storage_1.createFileStorage)();
         (0, library_1.configureAmplify)(storage);

package/dist/cjs/src/index.d.ts

@@ -1,8 +1,9 @@
 export { bleToWifiMac } from "./bluetooth-utils";
 export { decompressBuffer, isBuffer, processResponse } from "./buffer-utils";
 export { API_URL, NEW_API_URL, OLD_API_URL } from "./constants";
-export { configure, deriveUsageAnalytics, getSession, signIn } from "./library";
+export { configure, derivePhaseDescription, deriveUsageAnalytics, getPhaseDescription, getSession, signIn, } from "./library";
+export { normalizeMac } from "./mac-utils";
 export { serialNumberDisplay, serialNumberFromHex, serialNumberToHex, } from "./serial-utils";
-export { AlarmEntryType, AlarmsLogType, BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, PowerDistributionType, RegenerationDataType, ServiceCountersType, ServiceStatusType, StatusCountersType, StatusType, TemperaturesType, TotalCountersType, UsageAnalyticsType, UserParametersType, } from "./types";
-export { AlarmCode, AlarmDescriptions } from "./types";
+export { AlarmEntryType, AlarmsLogType, BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, FansType, PowerDistributionType, RegenerationDataType, ServiceCountersType, ServiceStatusType, StateType, StatusCountersType, StatusType, TemperaturesType, TotalCountersType, UsageAnalyticsType, UserParametersType, } from "./types";
+export { AlarmCode, AlarmDescriptions, getIgnitionSubPhaseDescription, getOperationalPhaseDescription, getStoveStateDescription, IgnitionSubPhase, IgnitionSubPhaseDescriptions, OperationalPhase, OperationalPhaseDescriptions, StoveState, StoveStateDescriptions, } from "./types";
 export declare const deviceInfo: (jwtToken: string, macAddress: string) => Promise<import("./types").DeviceInfoType>, registerDevice: (jwtToken: string, macAddress: string, serialNumber: string, deviceName?: string, deviceRoom?: string) => Promise<import("./types").DeviceAssociationResponse>, editDevice: (jwtToken: string, macAddress: string, deviceName?: string, deviceRoom?: string) => Promise<import("./types").DeviceAssociationResponse>, setPower: (jwtToken: string, macAddress: string, value: number) => Promise<unknown>, setPowerOff: (jwtToken: string, macAddress: string) => Promise<unknown>, setPowerOn: (jwtToken: string, macAddress: string) => Promise<unknown>, getPower: (jwtToken: string, macAddress: string) => Promise<boolean>, getEnvironmentTemperature: (jwtToken: string, macAddress: string) => Promise<number>, getTargetTemperature: (jwtToken: string, macAddress: string, envIndex: 1 | 2 | 3) => Promise<number>, setTargetTemperature: (jwtToken: string, macAddress: string, envIndex: 1 | 2 | 3, temperature: number) => Promise<unknown>;

package/dist/cjs/src/index.js

@@ -1,7 +1,7 @@
 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setTargetTemperature = exports.getTargetTemperature = exports.getEnvironmentTemperature = exports.getPower = exports.setPowerOn = exports.setPowerOff = exports.setPower = exports.editDevice = exports.registerDevice = exports.deviceInfo = exports.AlarmDescriptions = exports.AlarmCode = exports.serialNumberToHex = exports.serialNumberFromHex = exports.serialNumberDisplay = exports.signIn = exports.getSession = exports.deriveUsageAnalytics = exports.configure = exports.OLD_API_URL = exports.NEW_API_URL = exports.API_URL = exports.processResponse = exports.isBuffer = exports.decompressBuffer = exports.bleToWifiMac = void 0;
+exports.setTargetTemperature = exports.getTargetTemperature = exports.getEnvironmentTemperature = exports.getPower = exports.setPowerOn = exports.setPowerOff = exports.setPower = exports.editDevice = exports.registerDevice = exports.deviceInfo = exports.StoveStateDescriptions = exports.StoveState = exports.OperationalPhaseDescriptions = exports.OperationalPhase = exports.IgnitionSubPhaseDescriptions = exports.IgnitionSubPhase = exports.getStoveStateDescription = exports.getOperationalPhaseDescription = exports.getIgnitionSubPhaseDescription = exports.AlarmDescriptions = exports.AlarmCode = exports.serialNumberToHex = exports.serialNumberFromHex = exports.serialNumberDisplay = exports.normalizeMac = exports.signIn = exports.getSession = exports.getPhaseDescription = exports.deriveUsageAnalytics = exports.derivePhaseDescription = exports.configure = exports.OLD_API_URL = exports.NEW_API_URL = exports.API_URL = exports.processResponse = exports.isBuffer = exports.decompressBuffer = exports.bleToWifiMac = void 0;
 const library_1 = require("./library");
 var bluetooth_utils_1 = require("./bluetooth-utils");
 Object.defineProperty(exports, "bleToWifiMac", { enumerable: true, get: function () { return bluetooth_utils_1.bleToWifiMac; } });
@@ -15,9 +15,13 @@ Object.defineProperty(exports, "NEW_API_URL", { enumerable: true, get: function
 Object.defineProperty(exports, "OLD_API_URL", { enumerable: true, get: function () { return constants_1.OLD_API_URL; } });
 var library_2 = require("./library");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return library_2.configure; } });
+Object.defineProperty(exports, "derivePhaseDescription", { enumerable: true, get: function () { return library_2.derivePhaseDescription; } });
 Object.defineProperty(exports, "deriveUsageAnalytics", { enumerable: true, get: function () { return library_2.deriveUsageAnalytics; } });
+Object.defineProperty(exports, "getPhaseDescription", { enumerable: true, get: function () { return library_2.getPhaseDescription; } });
 Object.defineProperty(exports, "getSession", { enumerable: true, get: function () { return library_2.getSession; } });
 Object.defineProperty(exports, "signIn", { enumerable: true, get: function () { return library_2.signIn; } });
+var mac_utils_1 = require("./mac-utils");
+Object.defineProperty(exports, "normalizeMac", { enumerable: true, get: function () { return mac_utils_1.normalizeMac; } });
 var serial_utils_1 = require("./serial-utils");
 Object.defineProperty(exports, "serialNumberDisplay", { enumerable: true, get: function () { return serial_utils_1.serialNumberDisplay; } });
 Object.defineProperty(exports, "serialNumberFromHex", { enumerable: true, get: function () { return serial_utils_1.serialNumberFromHex; } });
@@ -25,4 +29,13 @@ Object.defineProperty(exports, "serialNumberToHex", { enumerable: true, get: fun
 var types_1 = require("./types");
 Object.defineProperty(exports, "AlarmCode", { enumerable: true, get: function () { return types_1.AlarmCode; } });
 Object.defineProperty(exports, "AlarmDescriptions", { enumerable: true, get: function () { return types_1.AlarmDescriptions; } });
+Object.defineProperty(exports, "getIgnitionSubPhaseDescription", { enumerable: true, get: function () { return types_1.getIgnitionSubPhaseDescription; } });
+Object.defineProperty(exports, "getOperationalPhaseDescription", { enumerable: true, get: function () { return types_1.getOperationalPhaseDescription; } });
+Object.defineProperty(exports, "getStoveStateDescription", { enumerable: true, get: function () { return types_1.getStoveStateDescription; } });
+Object.defineProperty(exports, "IgnitionSubPhase", { enumerable: true, get: function () { return types_1.IgnitionSubPhase; } });
+Object.defineProperty(exports, "IgnitionSubPhaseDescriptions", { enumerable: true, get: function () { return types_1.IgnitionSubPhaseDescriptions; } });
+Object.defineProperty(exports, "OperationalPhase", { enumerable: true, get: function () { return types_1.OperationalPhase; } });
+Object.defineProperty(exports, "OperationalPhaseDescriptions", { enumerable: true, get: function () { return types_1.OperationalPhaseDescriptions; } });
+Object.defineProperty(exports, "StoveState", { enumerable: true, get: function () { return types_1.StoveState; } });
+Object.defineProperty(exports, "StoveStateDescriptions", { enumerable: true, get: function () { return types_1.StoveStateDescriptions; } });
 _a = (0, library_1.configure)(), exports.deviceInfo = _a.deviceInfo, exports.registerDevice = _a.registerDevice, exports.editDevice = _a.editDevice, exports.setPower = _a.setPower, exports.setPowerOff = _a.setPowerOff, exports.setPowerOn = _a.setPowerOn, exports.getPower = _a.getPower, exports.getEnvironmentTemperature = _a.getEnvironmentTemperature, exports.getTargetTemperature = _a.getTargetTemperature, exports.setTargetTemperature = _a.setTargetTemperature;

package/dist/cjs/src/library.d.ts

@@ -45,6 +45,32 @@ declare const signIn: (username: string, password: string, legacy?: boolean) =>
  * const analytics = deriveUsageAnalytics(info);
  */
 export declare const deriveUsageAnalytics: (deviceInfo: DeviceInfoType, serviceThreshold?: number) => UsageAnalyticsType;
+/**
+ * Get human-readable description of the current device phase.
+ * Combines operational_phase and sub_operational_phase for context.
+ *
+ * @param {number} operationalPhase - The main operational phase.
+ * @param {number} subOperationalPhase - The sub-phase (used during ignition).
+ * @returns {string} - Human-readable phase description.
+ *
+ * @example
+ * const desc = getPhaseDescription(2, 1);
+ * // Returns: "Ignition - Pellet load"
+ */
+export declare const getPhaseDescription: (operationalPhase: number, subOperationalPhase: number) => string;
+/**
+ * Derive phase description from existing DeviceInfo.
+ * Pure function - no API calls required.
+ *
+ * @param {DeviceInfoType} deviceInfo - The device info object.
+ * @returns {string} - Human-readable phase description.
+ *
+ * @example
+ * const info = await api.deviceInfo(token, mac);
+ * const desc = derivePhaseDescription(info);
+ * // Returns: "On" or "Ignition - Warmup" etc.
+ */
+export declare const derivePhaseDescription: (deviceInfo: DeviceInfoType) => string;
 /**
  * Configures the library for API interactions.
  * Initializes API methods with a specified base URL.
@@ -97,6 +123,10 @@ declare const configure: (baseURL?: string) => {
     getLanguage: (jwtToken: string, macAddress: string) => Promise<number>;
     getPelletInReserve: (jwtToken: string, macAddress: string) => Promise<boolean>;
     getPelletAutonomyTime: (jwtToken: string, macAddress: string) => Promise<number>;
+    getOperationalPhase: (jwtToken: string, macAddress: string) => Promise<number>;
+    getSubOperationalPhase: (jwtToken: string, macAddress: string) => Promise<number>;
+    getStoveState: (jwtToken: string, macAddress: string) => Promise<number>;
+    getActualPower: (jwtToken: string, macAddress: string) => Promise<number>;
     getTotalCounters: (jwtToken: string, macAddress: string) => Promise<TotalCountersType>;
     getServiceCounters: (jwtToken: string, macAddress: string) => Promise<ServiceCountersType>;
     getAlarmHistory: (jwtToken: string, macAddress: string) => Promise<AlarmsLogType>;

package/dist/cjs/src/library.js

@@ -42,13 +42,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.signIn = exports.headers = exports.getSession = exports.createAuthService = exports.configureAmplify = exports.configure = exports.deriveUsageAnalytics = void 0;
+exports.signIn = exports.headers = exports.getSession = exports.createAuthService = exports.configureAmplify = exports.configure = exports.derivePhaseDescription = exports.getPhaseDescription = exports.deriveUsageAnalytics = void 0;
 const assert_1 = require("assert");
 const aws_amplify_1 = require("aws-amplify");
 const amplifyAuth = __importStar(require("aws-amplify/auth"));
 const cognito_1 = require("aws-amplify/auth/cognito");
 const buffer_utils_1 = require("./buffer-utils");
 const constants_1 = require("./constants");
+const mac_utils_1 = require("./mac-utils");
+const types_1 = require("./types");
 /**
  * Makes a fetch request and returns parsed JSON response.
  * Throws an error for non-2xx status codes.
@@ -514,6 +516,56 @@ const getPelletAutonomyTime = (baseURL) =>
     const info = yield deviceInfo(baseURL)(jwtToken, macAddress);
     return info.status.pellet.autonomy_time;
 });
+const getOperationalPhase = (baseURL) => 
+/**
+ * Retrieves the current operational phase of the stove.
+ *
+ * @param {string} jwtToken - The JWT token for authentication.
+ * @param {string} macAddress - The MAC address of the device.
+ * @returns {Promise<number>} - The operational phase (0=Off, 1=Standby, 2=Ignition, 6=On).
+ */
+(jwtToken, macAddress) => __awaiter(void 0, void 0, void 0, function* () {
+    const info = yield deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.state.operational_phase;
+});
+const getSubOperationalPhase = (baseURL) => 
+/**
+ * Retrieves the current sub-operational phase of the stove.
+ * Only meaningful during ignition (operational_phase === 2).
+ *
+ * @param {string} jwtToken - The JWT token for authentication.
+ * @param {string} macAddress - The MAC address of the device.
+ * @returns {Promise<number>} - The sub-operational phase (0-6 during ignition).
+ */
+(jwtToken, macAddress) => __awaiter(void 0, void 0, void 0, function* () {
+    const info = yield deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.state.sub_operational_phase;
+});
+const getStoveState = (baseURL) => 
+/**
+ * Retrieves the combined stove state code.
+ *
+ * @param {string} jwtToken - The JWT token for authentication.
+ * @param {string} macAddress - The MAC address of the device.
+ * @returns {Promise<number>} - The stove state code.
+ */
+(jwtToken, macAddress) => __awaiter(void 0, void 0, void 0, function* () {
+    const info = yield deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.state.stove_state;
+});
+const getActualPower = (baseURL) => 
+/**
+ * Retrieves the actual power level the stove is currently running at.
+ * This may differ from the requested power level during transitions.
+ *
+ * @param {string} jwtToken - The JWT token for authentication.
+ * @param {string} macAddress - The MAC address of the device.
+ * @returns {Promise<number>} - The actual power level (1-5).
+ */
+(jwtToken, macAddress) => __awaiter(void 0, void 0, void 0, function* () {
+    const info = yield deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.state.actual_power;
+});
 const getTotalCounters = (baseURL) => 
 /**
  * Retrieves lifetime operating counters.
@@ -735,7 +787,7 @@ const registerDevice = (baseURL) =>
  */
 (jwtToken_1, macAddress_1, serialNumber_1, ...args_1) => __awaiter(void 0, [jwtToken_1, macAddress_1, serialNumber_1, ...args_1], void 0, function* (jwtToken, macAddress, serialNumber, deviceName = "", deviceRoom = "") {
     const body = {
-        macAddress: macAddress.replace(/:/g, ""),
+        macAddress: (0, mac_utils_1.normalizeMac)(macAddress),
         deviceName,
         deviceRoom,
         serialNumber,
@@ -757,7 +809,7 @@ const editDevice = (baseURL) =>
  * @returns {Promise<DeviceAssociationResponse>} - A promise that resolves to the update response.
  */
 (jwtToken_1, macAddress_1, ...args_1) => __awaiter(void 0, [jwtToken_1, macAddress_1, ...args_1], void 0, function* (jwtToken, macAddress, deviceName = "", deviceRoom = "") {
-    const normalizedMac = macAddress.replace(/:/g, "");
+    const normalizedMac = (0, mac_utils_1.normalizeMac)(macAddress);
     const body = {
         deviceName,
         deviceRoom,
@@ -768,6 +820,43 @@ const editDevice = (baseURL) =>
         body: JSON.stringify(body),
     });
 });
+/**
+ * Get human-readable description of the current device phase.
+ * Combines operational_phase and sub_operational_phase for context.
+ *
+ * @param {number} operationalPhase - The main operational phase.
+ * @param {number} subOperationalPhase - The sub-phase (used during ignition).
+ * @returns {string} - Human-readable phase description.
+ *
+ * @example
+ * const desc = getPhaseDescription(2, 1);
+ * // Returns: "Ignition - Pellet load"
+ */
+const getPhaseDescription = (operationalPhase, subOperationalPhase) => {
+    if (operationalPhase === types_1.OperationalPhase.IGNITION) {
+        const subDesc = (0, types_1.getIgnitionSubPhaseDescription)(subOperationalPhase);
+        return `Ignition - ${subDesc}`;
+    }
+    return (0, types_1.getOperationalPhaseDescription)(operationalPhase);
+};
+exports.getPhaseDescription = getPhaseDescription;
+/**
+ * Derive phase description from existing DeviceInfo.
+ * Pure function - no API calls required.
+ *
+ * @param {DeviceInfoType} deviceInfo - The device info object.
+ * @returns {string} - Human-readable phase description.
+ *
+ * @example
+ * const info = await api.deviceInfo(token, mac);
+ * const desc = derivePhaseDescription(info);
+ * // Returns: "On" or "Ignition - Warmup" etc.
+ */
+const derivePhaseDescription = (deviceInfo) => {
+    const { operational_phase, sub_operational_phase } = deviceInfo.status.state;
+    return (0, exports.getPhaseDescription)(operational_phase, sub_operational_phase);
+};
+exports.derivePhaseDescription = derivePhaseDescription;
 /**
  * Configures the library for API interactions.
  * Initializes API methods with a specified base URL.
@@ -820,6 +909,11 @@ const configure = (baseURL = constants_1.API_URL) => ({
     getLanguage: getLanguage(baseURL),
     getPelletInReserve: getPelletInReserve(baseURL),
     getPelletAutonomyTime: getPelletAutonomyTime(baseURL),
+    // Phase/state getters
+    getOperationalPhase: getOperationalPhase(baseURL),
+    getSubOperationalPhase: getSubOperationalPhase(baseURL),
+    getStoveState: getStoveState(baseURL),
+    getActualPower: getActualPower(baseURL),
     // Statistics getters
     getTotalCounters: getTotalCounters(baseURL),
     getServiceCounters: getServiceCounters(baseURL),

package/dist/cjs/src/library.test.js

@@ -16,6 +16,7 @@ const assert_1 = require("assert");
 const pako_1 = __importDefault(require("pako"));
 const sinon_1 = __importDefault(require("sinon"));
 const library_1 = require("../src/library");
+const types_1 = require("../src/types");
 const constants_1 = require("./constants");
 /**
  * Helper to create a gzip-compressed Buffer object for testing.
@@ -220,6 +221,11 @@ describe("library", () => {
             "getLanguage",
             "getPelletInReserve",
             "getPelletAutonomyTime",
+            // Phase/state getters
+            "getOperationalPhase",
+            "getSubOperationalPhase",
+            "getStoveState",
+            "getActualPower",
             // Statistics getters
             "getTotalCounters",
             "getServiceCounters",
@@ -603,7 +609,7 @@ describe("library", () => {
                     Authorization: `Bearer ${expectedToken}`,
                 },
                 body: JSON.stringify({
-                    macAddress: "AABBCCDDEEFF",
+                    macAddress: "aabbccddeeff",
                     deviceName: "Test Stove",
                     deviceRoom: "Living Room",
                     serialNumber: "EDK123",
@@ -611,12 +617,12 @@ describe("library", () => {
             });
             assert_1.strict.deepEqual(result, mockResponseData);
         }));
-        it("should normalize MAC address by removing colons", () => __awaiter(void 0, void 0, void 0, function* () {
+        it("should normalize MAC address by removing colons and converting to lowercase", () => __awaiter(void 0, void 0, void 0, function* () {
             fetchStub.resolves(mockResponse({}));
             const api = (0, library_1.configure)("https://example.com/api/");
             yield api.registerDevice(expectedToken, "AA:BB:CC:DD:EE:FF", "EDK123");
             const body = JSON.parse(fetchStub.firstCall.args[1].body);
-            assert_1.strict.equal(body.macAddress, "AABBCCDDEEFF");
+            assert_1.strict.equal(body.macAddress, "aabbccddeeff");
         }));
         it("should use empty strings as defaults for name and room", () => __awaiter(void 0, void 0, void 0, function* () {
             fetchStub.resolves(mockResponse({}));
@@ -639,7 +645,7 @@ describe("library", () => {
             const api = (0, library_1.configure)("https://example.com/api/");
             const result = yield api.editDevice(expectedToken, "AA:BB:CC:DD:EE:FF", "Updated Name", "Basement");
             assert_1.strict.ok(fetchStub.calledOnce);
-            assert_1.strict.equal(fetchStub.firstCall.args[0], "https://example.com/api/device/AABBCCDDEEFF");
+            assert_1.strict.equal(fetchStub.firstCall.args[0], "https://example.com/api/device/aabbccddeeff");
             assert_1.strict.deepEqual(fetchStub.firstCall.args[1], {
                 method: "PUT",
                 headers: {
@@ -1147,6 +1153,221 @@ describe("library", () => {
             assert_1.strict.equal(analytics.lastMaintenanceDate, null);
         });
     });
+    describe("phase getters", () => {
+        const mockDeviceInfoWithState = {
+            status: {
+                commands: { power: true },
+                temperatures: { board: 25, enviroment: 20 },
+                flags: { is_pellet_in_reserve: false },
+                pellet: { autonomy_time: 900 },
+                counters: { service_time: 1108 },
+                state: {
+                    operational_phase: 2,
+                    sub_operational_phase: 3,
+                    stove_state: 4,
+                    alarm_type: 0,
+                    actual_power: 3,
+                },
+                fans: { fan_1_speed: 3, fan_2_speed: 0, fan_3_speed: 0 },
+            },
+            nvm: {
+                user_parameters: {
+                    language: 1,
+                    is_auto: false,
+                    is_fahrenheit: false,
+                    is_sound_active: false,
+                    enviroment_1_temperature: 19,
+                    enviroment_2_temperature: 20,
+                    enviroment_3_temperature: 20,
+                    manual_power: 1,
+                    fan_1_ventilation: 3,
+                    fan_2_ventilation: 0,
+                    fan_3_ventilation: 0,
+                    is_standby_active: false,
+                    standby_waiting_time: 60,
+                },
+                total_counters: {
+                    power_ons: 278,
+                    p1_working_time: 833,
+                    p2_working_time: 15,
+                    p3_working_time: 19,
+                    p4_working_time: 8,
+                    p5_working_time: 17,
+                },
+                service_counters: {
+                    p1_working_time: 100,
+                    p2_working_time: 10,
+                    p3_working_time: 5,
+                    p4_working_time: 2,
+                    p5_working_time: 1,
+                },
+                alarms_log: {
+                    number: 2,
+                    index: 2,
+                    alarms: [],
+                },
+                regeneration: {
+                    time: 0,
+                    last_intervention: 1577836800,
+                    daylight_time_flag: 0,
+                    blackout_counter: 43,
+                    airkare_working_hours_counter: 0,
+                },
+            },
+        };
+        it("should get operational phase", () => __awaiter(void 0, void 0, void 0, function* () {
+            fetchStub.resolves(mockResponse(mockDeviceInfoWithState));
+            const api = (0, library_1.configure)(constants_1.API_URL);
+            const result = yield api.getOperationalPhase(expectedToken, "00:11:22:33:44:55");
+            assert_1.strict.equal(result, 2);
+        }));
+        it("should get sub-operational phase", () => __awaiter(void 0, void 0, void 0, function* () {
+            fetchStub.resolves(mockResponse(mockDeviceInfoWithState));
+            const api = (0, library_1.configure)(constants_1.API_URL);
+            const result = yield api.getSubOperationalPhase(expectedToken, "00:11:22:33:44:55");
+            assert_1.strict.equal(result, 3);
+        }));
+        it("should get stove state", () => __awaiter(void 0, void 0, void 0, function* () {
+            fetchStub.resolves(mockResponse(mockDeviceInfoWithState));
+            const api = (0, library_1.configure)(constants_1.API_URL);
+            const result = yield api.getStoveState(expectedToken, "00:11:22:33:44:55");
+            assert_1.strict.equal(result, 4);
+        }));
+        it("should get actual power", () => __awaiter(void 0, void 0, void 0, function* () {
+            fetchStub.resolves(mockResponse(mockDeviceInfoWithState));
+            const api = (0, library_1.configure)(constants_1.API_URL);
+            const result = yield api.getActualPower(expectedToken, "00:11:22:33:44:55");
+            assert_1.strict.equal(result, 3);
+        }));
+    });
+    describe("getPhaseDescription", () => {
+        it("should return 'Off' for phase 0", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(0, 0), "Off");
+        });
+        it("should return 'Standby' for phase 1", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(1, 0), "Standby");
+        });
+        it("should return 'On' for phase 6", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(6, 0), "On");
+        });
+        it("should return combined description for ignition phase", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 0), "Ignition - Starting cleaning");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 1), "Ignition - Pellet load");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 2), "Ignition - Loading break");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 3), "Ignition - Smoke temperature check");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 4), "Ignition - Threshold exceeding check");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 5), "Ignition - Warmup");
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 6), "Ignition - Starting up");
+        });
+        it("should return fallback for unknown operational phase", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(99, 0), "Unknown phase (99)");
+        });
+        it("should return fallback for unknown ignition sub-phase", () => {
+            assert_1.strict.equal((0, library_1.getPhaseDescription)(2, 99), "Ignition - Unknown sub-phase (99)");
+        });
+    });
+    describe("derivePhaseDescription", () => {
+        it("should derive phase description from device info", () => {
+            const mockDeviceInfo = {
+                status: {
+                    commands: { power: true },
+                    temperatures: { board: 25, enviroment: 22 },
+                    flags: { is_pellet_in_reserve: true },
+                    pellet: { autonomy_time: 120 },
+                    counters: { service_time: 100 },
+                    state: {
+                        operational_phase: 2,
+                        sub_operational_phase: 5,
+                        stove_state: 5,
+                        alarm_type: 0,
+                        actual_power: 3,
+                    },
+                    fans: { fan_1_speed: 3, fan_2_speed: 0, fan_3_speed: 0 },
+                },
+                nvm: {
+                    user_parameters: {},
+                    total_counters: {},
+                    service_counters: {},
+                    alarms_log: { number: 0, index: 0, alarms: [] },
+                    regeneration: {},
+                },
+            };
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const desc = (0, library_1.derivePhaseDescription)(mockDeviceInfo);
+            assert_1.strict.equal(desc, "Ignition - Warmup");
+        });
+        it("should return 'On' for device in On state", () => {
+            const mockDeviceInfo = {
+                status: {
+                    commands: { power: true },
+                    temperatures: { board: 25, enviroment: 22 },
+                    flags: { is_pellet_in_reserve: false },
+                    pellet: { autonomy_time: 120 },
+                    counters: { service_time: 100 },
+                    state: {
+                        operational_phase: 6,
+                        sub_operational_phase: 0,
+                        stove_state: 6,
+                        alarm_type: 0,
+                        actual_power: 3,
+                    },
+                    fans: { fan_1_speed: 3, fan_2_speed: 0, fan_3_speed: 0 },
+                },
+                nvm: {
+                    user_parameters: {},
+                    total_counters: {},
+                    service_counters: {},
+                    alarms_log: { number: 0, index: 0, alarms: [] },
+                    regeneration: {},
+                },
+            };
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const desc = (0, library_1.derivePhaseDescription)(mockDeviceInfo);
+            assert_1.strict.equal(desc, "On");
+        });
+    });
+    describe("OperationalPhase descriptions", () => {
+        it("should return descriptions for known phases", () => {
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(types_1.OperationalPhase.OFF), "Off");
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(types_1.OperationalPhase.STANDBY), "Standby");
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(types_1.OperationalPhase.IGNITION), "Ignition");
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(types_1.OperationalPhase.ON), "On");
+        });
+        it("should return fallback for unknown phases", () => {
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(3), "Unknown phase (3)");
+            assert_1.strict.equal((0, types_1.getOperationalPhaseDescription)(99), "Unknown phase (99)");
+        });
+    });
+    describe("IgnitionSubPhase descriptions", () => {
+        it("should return descriptions for all ignition sub-phases", () => {
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.STARTING_CLEANING), "Starting cleaning");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.PELLET_LOAD), "Pellet load");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.LOADING_BREAK), "Loading break");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.SMOKE_TEMPERATURE_CHECK), "Smoke temperature check");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.THRESHOLD_EXCEEDING_CHECK), "Threshold exceeding check");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.WARMUP), "Warmup");
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(types_1.IgnitionSubPhase.TRANSITION_TO_ON), "Starting up");
+        });
+        it("should return fallback for unknown sub-phases", () => {
+            assert_1.strict.equal((0, types_1.getIgnitionSubPhaseDescription)(99), "Unknown sub-phase (99)");
+        });
+    });
+    describe("StoveState descriptions", () => {
+        it("should return descriptions for known states", () => {
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.OFF), "Off");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.STANDBY), "Standby");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.IGNITION_CLEANING), "Ignition - Cleaning");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.IGNITION_LOADING), "Ignition - Loading pellets");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.IGNITION_WAITING), "Ignition - Waiting");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.IGNITION_WARMUP), "Ignition - Warming up");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.ON), "On");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.COOLING), "Cooling down");
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(types_1.StoveState.ALARM), "Alarm");
+        });
+        it("should return fallback for unknown states", () => {
+            assert_1.strict.equal((0, types_1.getStoveStateDescription)(99), "Unknown state (99)");
+        });
+    });
     describe("Error Handling", () => {
         const errorTests = [
             { status: 400, statusText: "Bad Request" },

package/dist/cjs/src/mac-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalizes a MAC address by removing separators and converting to lowercase.
+ * Accepts formats: AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF, AABBCCDDEEFF
+ *
+ * @param mac - MAC address in any common format
+ * @returns Normalized MAC address (12 lowercase hex chars, no separators)
+ * @throws Error if MAC address format is invalid
+ *
+ * @example
+ * normalizeMac("AA:BB:CC:DD:EE:FF") // returns "aabbccddeeff"
+ * normalizeMac("AA-BB-CC-DD-EE-FF") // returns "aabbccddeeff"
+ * normalizeMac("AABBCCDDEEFF")      // returns "aabbccddeeff"
+ */
+declare const normalizeMac: (mac: string) => string;
+export { normalizeMac };