edilkamin 1.10.2 → 1.12.0

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 };

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMac = void 0;
+/**
+ * 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"
+ */
+const normalizeMac = (mac) => {
+    const normalized = mac.replace(/[:-]/g, "").toLowerCase();
+    if (!/^[0-9a-f]{12}$/.test(normalized)) {
+        throw new Error(`Invalid MAC address format: ${mac}`);
+    }
+    return normalized;
+};
+exports.normalizeMac = normalizeMac;

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

@@ -0,0 +1 @@
+export {};

package/dist/cjs/src/mac-utils.test.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert_1 = require("assert");
+const mac_utils_1 = require("./mac-utils");
+describe("mac-utils", () => {
+    describe("normalizeMac", () => {
+        it("should normalize MAC address with colons", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("AA:BB:CC:DD:EE:FF"), "aabbccddeeff");
+        });
+        it("should normalize MAC address with dashes", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("AA-BB-CC-DD-EE-FF"), "aabbccddeeff");
+        });
+        it("should normalize MAC address without separators", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("AABBCCDDEEFF"), "aabbccddeeff");
+        });
+        it("should normalize lowercase MAC address", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("aa:bb:cc:dd:ee:ff"), "aabbccddeeff");
+        });
+        it("should normalize mixed case MAC address", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("Aa:Bb:Cc:Dd:Ee:Ff"), "aabbccddeeff");
+        });
+        it("should normalize MAC address with mixed separators", () => {
+            assert_1.strict.equal((0, mac_utils_1.normalizeMac)("AA:BB-CC:DD-EE:FF"), "aabbccddeeff");
+        });
+        it("should throw on MAC address with invalid length (too short)", () => {
+            assert_1.strict.throws(() => (0, mac_utils_1.normalizeMac)("AA:BB:CC:DD:EE"), /Invalid MAC address format: AA:BB:CC:DD:EE/);
+        });
+        it("should throw on MAC address with invalid length (too long)", () => {
+            assert_1.strict.throws(() => (0, mac_utils_1.normalizeMac)("AA:BB:CC:DD:EE:FF:00"), /Invalid MAC address format: AA:BB:CC:DD:EE:FF:00/);
+        });
+        it("should throw on MAC address with invalid characters", () => {
+            assert_1.strict.throws(() => (0, mac_utils_1.normalizeMac)("GG:HH:II:JJ:KK:LL"), /Invalid MAC address format: GG:HH:II:JJ:KK:LL/);
+        });
+        it("should throw on empty string", () => {
+            assert_1.strict.throws(() => (0, mac_utils_1.normalizeMac)(""), /Invalid MAC address format: /);
+        });
+        it("should throw on whitespace-only string", () => {
+            assert_1.strict.throws(() => (0, mac_utils_1.normalizeMac)("   "), /Invalid MAC address format:/);
+        });
+    });
+});

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

@@ -25,12 +25,42 @@ interface PelletAutonomyType {
 interface StatusCountersType {
     service_time: number;
 }
+/**
+ * Device operational state information.
+ * Retrieved from status.state in the API response.
+ */
+interface StateType {
+    /** Main operational phase (0=Off, 1=Standby, 2=Ignition, 6=On) */
+    operational_phase: number;
+    /** Sub-phase within current operation (0-6 during ignition) */
+    sub_operational_phase: number;
+    /** Combined stove state code */
+    stove_state: number;
+    /** Current alarm code (0 = no alarm) */
+    alarm_type: number;
+    /** Current actual power level (1-5) */
+    actual_power: number;
+}
+/**
+ * Fan speed information for all three fans.
+ * Retrieved from status.fans in the API response.
+ */
+interface FansType {
+    /** Fan 1 speed (0-5) */
+    fan_1_speed: number;
+    /** Fan 2 speed (0-5) */
+    fan_2_speed: number;
+    /** Fan 3 speed (0-5) */
+    fan_3_speed: number;
+}
 interface StatusType {
     commands: CommandsType;
     temperatures: TemperaturesType;
     flags: GeneralFlagsType;
     pellet: PelletAutonomyType;
     counters: StatusCountersType;
+    state: StateType;
+    fans: FansType;
 }
 interface UserParametersType {
     enviroment_1_temperature: number;
@@ -161,6 +191,68 @@ declare enum AlarmCode {
  * Human-readable descriptions for alarm codes.
  */
 declare const AlarmDescriptions: Record<AlarmCode, string>;
+/**
+ * Main operational phases of the stove.
+ * Values derived from device behavior observation.
+ */
+declare enum OperationalPhase {
+    OFF = 0,
+    STANDBY = 1,
+    IGNITION = 2,
+    ON = 6
+}
+/**
+ * Human-readable descriptions for operational phases.
+ */
+declare const OperationalPhaseDescriptions: Record<number, string>;
+/**
+ * Get description for an operational phase, with fallback for unknown values.
+ */
+declare const getOperationalPhaseDescription: (phase: number) => string;
+/**
+ * Sub-phases during ignition sequence.
+ * These are only meaningful when operational_phase === IGNITION.
+ */
+declare enum IgnitionSubPhase {
+    STARTING_CLEANING = 0,
+    PELLET_LOAD = 1,
+    LOADING_BREAK = 2,
+    SMOKE_TEMPERATURE_CHECK = 3,
+    THRESHOLD_EXCEEDING_CHECK = 4,
+    WARMUP = 5,
+    TRANSITION_TO_ON = 6
+}
+/**
+ * Human-readable descriptions for ignition sub-phases.
+ */
+declare const IgnitionSubPhaseDescriptions: Record<number, string>;
+/**
+ * Get description for an ignition sub-phase, with fallback for unknown values.
+ */
+declare const getIgnitionSubPhaseDescription: (subPhase: number) => string;
+/**
+ * Combined stove states.
+ * This is a composite value combining operational phase and sub-phase.
+ */
+declare enum StoveState {
+    OFF = 0,
+    STANDBY = 1,
+    IGNITION_CLEANING = 2,
+    IGNITION_LOADING = 3,
+    IGNITION_WAITING = 4,
+    IGNITION_WARMUP = 5,
+    ON = 6,
+    COOLING = 7,
+    ALARM = 8
+}
+/**
+ * Human-readable descriptions for stove states.
+ */
+declare const StoveStateDescriptions: Record<number, string>;
+/**
+ * Get description for a stove state, with fallback for unknown values.
+ */
+declare const getStoveStateDescription: (state: number) => string;
 interface DeviceInfoType {
     status: StatusType;
     nvm: {
@@ -224,5 +316,5 @@ interface DiscoveredDevice {
     /** Signal strength in dBm (optional, not all platforms provide this) */
     rssi?: number;
 }
-export type { AlarmEntryType, AlarmsLogType, BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, GeneralFlagsType, PelletAutonomyType, PowerDistributionType, RegenerationDataType, ServiceCountersType, ServiceStatusType, StatusCountersType, StatusType, TemperaturesType, TotalCountersType, UsageAnalyticsType, UserParametersType, };
-export { AlarmCode, AlarmDescriptions };
+export type { AlarmEntryType, AlarmsLogType, BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, FansType, GeneralFlagsType, PelletAutonomyType, PowerDistributionType, RegenerationDataType, ServiceCountersType, ServiceStatusType, StateType, StatusCountersType, StatusType, TemperaturesType, TotalCountersType, UsageAnalyticsType, UserParametersType, };
+export { AlarmCode, AlarmDescriptions, getIgnitionSubPhaseDescription, getOperationalPhaseDescription, getStoveStateDescription, IgnitionSubPhase, IgnitionSubPhaseDescriptions, OperationalPhase, OperationalPhaseDescriptions, StoveState, StoveStateDescriptions, };