edilkamin 1.10.2 → 1.12.0

package/dist/esm/src/bluetooth-protocol.test.js

@@ -0,0 +1,387 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { strict as assert } from "assert";
+import { aesDecrypt, aesEncrypt, crc16Modbus, createPacket, NOTIFY_CHARACTERISTIC_UUID, parseResponse, parsers, readCommands, SERVICE_UUID, WRITE_CHARACTERISTIC_UUID, writeCommands, } from "./bluetooth-protocol";
+describe("bluetooth-protocol", () => {
+    describe("constants", () => {
+        it("exports SERVICE_UUID", () => {
+            assert.equal(SERVICE_UUID, "0000abf0-0000-1000-8000-00805f9b34fb");
+        });
+        it("exports WRITE_CHARACTERISTIC_UUID", () => {
+            assert.equal(WRITE_CHARACTERISTIC_UUID, "0000abf1-0000-1000-8000-00805f9b34fb");
+        });
+        it("exports NOTIFY_CHARACTERISTIC_UUID", () => {
+            assert.equal(NOTIFY_CHARACTERISTIC_UUID, "0000abf2-0000-1000-8000-00805f9b34fb");
+        });
+    });
+    describe("crc16Modbus", () => {
+        it("calculates correct CRC for power-on command", () => {
+            const command = new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x01]);
+            const crc = crc16Modbus(command);
+            assert.equal(crc.length, 2);
+            // CRC is returned as [crcLo, crcHi]
+            assert.ok(crc[0] >= 0 && crc[0] <= 255);
+            assert.ok(crc[1] >= 0 && crc[1] <= 255);
+        });
+        it("returns 2 bytes for any input", () => {
+            const testCases = [
+                new Uint8Array([0x01, 0x03, 0x05, 0x25, 0x00, 0x01]),
+                new Uint8Array([0x01, 0x06, 0x04, 0x40, 0x00, 0x03]),
+                new Uint8Array([0x00]),
+                new Uint8Array([0xff, 0xff, 0xff]),
+            ];
+            for (const data of testCases) {
+                const crc = crc16Modbus(data);
+                assert.equal(crc.length, 2, `CRC for ${data.toString()} should be 2 bytes`);
+            }
+        });
+        it("produces different CRCs for different data", () => {
+            const crc1 = crc16Modbus(new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x01]));
+            const crc2 = crc16Modbus(new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x00]));
+            // CRCs should be different for different data
+            assert.ok(crc1[0] !== crc2[0] || crc1[1] !== crc2[1]);
+        });
+    });
+    describe("aesEncrypt/aesDecrypt", () => {
+        it("roundtrip returns original data", () => __awaiter(void 0, void 0, void 0, function* () {
+            const original = new Uint8Array(32).fill(0x42);
+            const encrypted = yield aesEncrypt(original);
+            const decrypted = yield aesDecrypt(encrypted);
+            assert.deepEqual(decrypted, original);
+        }));
+        it("produces 32-byte output for 32-byte input", () => __awaiter(void 0, void 0, void 0, function* () {
+            const input = new Uint8Array(32);
+            const encrypted = yield aesEncrypt(input);
+            assert.equal(encrypted.length, 32);
+        }));
+        it("produces different output for different input", () => __awaiter(void 0, void 0, void 0, function* () {
+            const input1 = new Uint8Array(32).fill(0x00);
+            const input2 = new Uint8Array(32).fill(0xff);
+            const encrypted1 = yield aesEncrypt(input1);
+            const encrypted2 = yield aesEncrypt(input2);
+            // At least some bytes should be different
+            let different = false;
+            for (let i = 0; i < 32; i++) {
+                if (encrypted1[i] !== encrypted2[i]) {
+                    different = true;
+                    break;
+                }
+            }
+            assert.ok(different, "Different inputs should produce different outputs");
+        }));
+        it("encrypted data is different from plaintext", () => __awaiter(void 0, void 0, void 0, function* () {
+            const original = new Uint8Array(32).fill(0xaa);
+            const encrypted = yield aesEncrypt(original);
+            // Encrypted should not equal original
+            let same = true;
+            for (let i = 0; i < 32; i++) {
+                if (encrypted[i] !== original[i]) {
+                    same = false;
+                    break;
+                }
+            }
+            assert.ok(!same, "Encrypted data should differ from original");
+        }));
+    });
+    describe("createPacket", () => {
+        it("produces 32-byte encrypted packet", () => __awaiter(void 0, void 0, void 0, function* () {
+            const command = readCommands.power;
+            const packet = yield createPacket(command);
+            assert.equal(packet.length, 32);
+        }));
+        it("rejects commands not exactly 6 bytes", () => __awaiter(void 0, void 0, void 0, function* () {
+            yield assert.rejects(() => createPacket(new Uint8Array([0x01, 0x02])), /must be exactly 6 bytes/);
+        }));
+        it("rejects empty commands", () => __awaiter(void 0, void 0, void 0, function* () {
+            yield assert.rejects(() => createPacket(new Uint8Array([])), /must be exactly 6 bytes/);
+        }));
+        it("rejects 7-byte commands", () => __awaiter(void 0, void 0, void 0, function* () {
+            yield assert.rejects(() => createPacket(new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07])), /must be exactly 6 bytes/);
+        }));
+        it("produces different packets for different commands", () => __awaiter(void 0, void 0, void 0, function* () {
+            const packet1 = yield createPacket(writeCommands.setPower(true));
+            const packet2 = yield createPacket(writeCommands.setPower(false));
+            // Packets should be different (different command bytes)
+            let different = false;
+            for (let i = 0; i < 32; i++) {
+                if (packet1[i] !== packet2[i]) {
+                    different = true;
+                    break;
+                }
+            }
+            assert.ok(different, "Different commands should produce different packets");
+        }));
+    });
+    describe("parseResponse", () => {
+        it("rejects responses not 32 bytes", () => __awaiter(void 0, void 0, void 0, function* () {
+            yield assert.rejects(() => parseResponse(new Uint8Array(16)), /must be exactly 32 bytes/);
+        }));
+        it("can decrypt and parse an encrypted packet", () => __awaiter(void 0, void 0, void 0, function* () {
+            // Create a command packet and try to parse it
+            // This tests that encrypt/decrypt work together
+            const command = readCommands.power;
+            const encrypted = yield createPacket(command);
+            // Parse the response (it's not a valid response but should decrypt)
+            const parsed = yield parseResponse(encrypted);
+            // Should have parsed something
+            assert.ok(typeof parsed.slaveAddress === "number");
+            assert.ok(typeof parsed.functionCode === "number");
+            assert.ok(typeof parsed.isError === "boolean");
+        }));
+    });
+    describe("readCommands", () => {
+        it("all commands are 6 bytes", () => {
+            Object.entries(readCommands).forEach(([name, cmd]) => {
+                assert.equal(cmd.length, 6, `${name} command must be 6 bytes`);
+            });
+        });
+        it("all commands use slave address 0x01", () => {
+            Object.entries(readCommands).forEach(([name, cmd]) => {
+                assert.equal(cmd[0], 0x01, `${name} should use slave address 0x01`);
+            });
+        });
+        it("all commands use function code 0x03", () => {
+            Object.entries(readCommands).forEach(([name, cmd]) => {
+                assert.equal(cmd[1], 0x03, `${name} should use function code 0x03`);
+            });
+        });
+        it("power command has correct register address", () => {
+            assert.equal(readCommands.power[2], 0x05);
+            assert.equal(readCommands.power[3], 0x29);
+        });
+        it("temperature command has correct register address", () => {
+            assert.equal(readCommands.temperature[2], 0x05);
+            assert.equal(readCommands.temperature[3], 0x25);
+        });
+    });
+    describe("writeCommands", () => {
+        it("setPower(true) produces correct bytes", () => {
+            const cmd = writeCommands.setPower(true);
+            assert.deepEqual(cmd, new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x01]));
+        });
+        it("setPower(false) produces correct bytes", () => {
+            const cmd = writeCommands.setPower(false);
+            assert.deepEqual(cmd, new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x00]));
+        });
+        it("setTemperature encodes correctly", () => {
+            const cmd = writeCommands.setTemperature(21.5);
+            // 21.5 * 10 = 215 = 0x00D7
+            assert.equal(cmd[0], 0x01); // slave address
+            assert.equal(cmd[1], 0x06); // function code
+            assert.equal(cmd[2], 0x05); // register hi
+            assert.equal(cmd[3], 0x25); // register lo
+            assert.equal(cmd[4], 0x00); // value hi
+            assert.equal(cmd[5], 0xd7); // value lo
+        });
+        it("setTemperature handles whole numbers", () => {
+            const cmd = writeCommands.setTemperature(20);
+            // 20 * 10 = 200 = 0x00C8
+            assert.equal(cmd[4], 0x00);
+            assert.equal(cmd[5], 0xc8);
+        });
+        it("setTemperature handles high temperatures", () => {
+            const cmd = writeCommands.setTemperature(30);
+            // 30 * 10 = 300 = 0x012C
+            assert.equal(cmd[4], 0x01);
+            assert.equal(cmd[5], 0x2c);
+        });
+        it("setPowerLevel validates range", () => {
+            assert.throws(() => writeCommands.setPowerLevel(0), /must be 1-5/);
+            assert.throws(() => writeCommands.setPowerLevel(6), /must be 1-5/);
+            assert.doesNotThrow(() => writeCommands.setPowerLevel(1));
+            assert.doesNotThrow(() => writeCommands.setPowerLevel(3));
+            assert.doesNotThrow(() => writeCommands.setPowerLevel(5));
+        });
+        it("setPowerLevel produces correct bytes", () => {
+            const cmd = writeCommands.setPowerLevel(3);
+            assert.equal(cmd[0], 0x01);
+            assert.equal(cmd[1], 0x06);
+            assert.equal(cmd[2], 0x04);
+            assert.equal(cmd[3], 0x40);
+            assert.equal(cmd[4], 0x00);
+            assert.equal(cmd[5], 0x03);
+        });
+        it("setFan1Speed validates range", () => {
+            assert.throws(() => writeCommands.setFan1Speed(-1), /must be 0-5/);
+            assert.throws(() => writeCommands.setFan1Speed(6), /must be 0-5/);
+            assert.doesNotThrow(() => writeCommands.setFan1Speed(0)); // auto
+            assert.doesNotThrow(() => writeCommands.setFan1Speed(5));
+        });
+        it("setFan2Speed validates range", () => {
+            assert.throws(() => writeCommands.setFan2Speed(-1), /must be 0-5/);
+            assert.throws(() => writeCommands.setFan2Speed(6), /must be 0-5/);
+            assert.doesNotThrow(() => writeCommands.setFan2Speed(0));
+            assert.doesNotThrow(() => writeCommands.setFan2Speed(5));
+        });
+        it("setAutoMode produces correct bytes", () => {
+            const cmdOn = writeCommands.setAutoMode(true);
+            assert.equal(cmdOn[5], 0x01);
+            const cmdOff = writeCommands.setAutoMode(false);
+            assert.equal(cmdOff[5], 0x00);
+        });
+        it("setStandby produces correct bytes", () => {
+            const cmdOn = writeCommands.setStandby(true);
+            assert.equal(cmdOn[5], 0x01);
+            const cmdOff = writeCommands.setStandby(false);
+            assert.equal(cmdOff[5], 0x00);
+        });
+        it("all write commands are 6 bytes", () => {
+            const commands = [
+                writeCommands.setPower(true),
+                writeCommands.setTemperature(21),
+                writeCommands.setPowerLevel(3),
+                writeCommands.setFan1Speed(2),
+                writeCommands.setFan2Speed(2),
+                writeCommands.setAutoMode(true),
+                writeCommands.setStandby(false),
+            ];
+            commands.forEach((cmd, i) => {
+                assert.equal(cmd.length, 6, `Command ${i} should be 6 bytes`);
+            });
+        });
+        it("all write commands use function code 0x06", () => {
+            const commands = [
+                writeCommands.setPower(true),
+                writeCommands.setTemperature(21),
+                writeCommands.setPowerLevel(3),
+                writeCommands.setFan1Speed(2),
+                writeCommands.setFan2Speed(2),
+                writeCommands.setAutoMode(true),
+                writeCommands.setStandby(false),
+            ];
+            commands.forEach((cmd, i) => {
+                assert.equal(cmd[1], 0x06, `Command ${i} should use function code 0x06`);
+            });
+        });
+    });
+    describe("parsers", () => {
+        it("boolean parser returns true for 0x01", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x00, 0x01]),
+                isError: false,
+            };
+            assert.equal(parsers.boolean(response), true);
+        });
+        it("boolean parser returns false for 0x00", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x00, 0x00]),
+                isError: false,
+            };
+            assert.equal(parsers.boolean(response), false);
+        });
+        it("temperature parser divides by 10", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x00, 0xd7]), // 215
+                isError: false,
+            };
+            assert.equal(parsers.temperature(response), 21.5);
+        });
+        it("temperature parser handles high temperatures", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x01, 0x2c]), // 300
+                isError: false,
+            };
+            assert.equal(parsers.temperature(response), 30);
+        });
+        it("number parser returns big-endian value", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x00, 0x03]), // power level 3
+                isError: false,
+            };
+            assert.equal(parsers.number(response), 3);
+        });
+        it("number parser handles larger values", () => {
+            const response = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                byteCount: 2,
+                data: new Uint8Array([0x01, 0x00]), // 256
+                isError: false,
+            };
+            assert.equal(parsers.number(response), 256);
+        });
+        it("boolean parser throws on error response", () => {
+            const errorResponse = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                data: new Uint8Array([0x02]), // error code
+                isError: true,
+            };
+            assert.throws(() => parsers.boolean(errorResponse), /Modbus error: 2/);
+        });
+        it("temperature parser throws on error response", () => {
+            const errorResponse = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                data: new Uint8Array([0x03]),
+                isError: true,
+            };
+            assert.throws(() => parsers.temperature(errorResponse), /Modbus error: 3/);
+        });
+        it("number parser throws on error response", () => {
+            const errorResponse = {
+                slaveAddress: 1,
+                functionCode: 0x03,
+                data: new Uint8Array([0x04]),
+                isError: true,
+            };
+            assert.throws(() => parsers.number(errorResponse), /Modbus error: 4/);
+        });
+    });
+    describe("integration", () => {
+        it("full roundtrip: create packet, decrypt, check structure", () => __awaiter(void 0, void 0, void 0, function* () {
+            // Create a power-on command
+            const command = writeCommands.setPower(true);
+            assert.deepEqual(command, new Uint8Array([0x01, 0x06, 0x03, 0x1c, 0x00, 0x01]));
+            // Create encrypted packet
+            const packet = yield createPacket(command);
+            assert.equal(packet.length, 32);
+            // Decrypt it back (as if we received it)
+            // Note: createPacket encrypts with padding, parseResponse expects response format
+            // This is not a true response but tests the encryption layer
+        }));
+        it("all read commands can create valid packets", () => __awaiter(void 0, void 0, void 0, function* () {
+            for (const [name, command] of Object.entries(readCommands)) {
+                const packet = yield createPacket(command);
+                assert.equal(packet.length, 32, `${name} should create 32-byte packet`);
+            }
+        }));
+        it("all write commands can create valid packets", () => __awaiter(void 0, void 0, void 0, function* () {
+            const commands = [
+                { name: "setPower", cmd: writeCommands.setPower(true) },
+                { name: "setTemperature", cmd: writeCommands.setTemperature(21) },
+                { name: "setPowerLevel", cmd: writeCommands.setPowerLevel(3) },
+                { name: "setFan1Speed", cmd: writeCommands.setFan1Speed(2) },
+                { name: "setFan2Speed", cmd: writeCommands.setFan2Speed(2) },
+                { name: "setAutoMode", cmd: writeCommands.setAutoMode(true) },
+                { name: "setStandby", cmd: writeCommands.setStandby(false) },
+            ];
+            for (const { name, cmd } of commands) {
+                const packet = yield createPacket(cmd);
+                assert.equal(packet.length, 32, `${name} should create 32-byte packet`);
+            }
+        }));
+    });
+});

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

@@ -1,3 +1,4 @@
+import { normalizeMac } from "./mac-utils";
 /**
  * Converts a BLE MAC address to WiFi MAC address.
  * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
@@ -10,12 +11,7 @@
  * 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 = normalizeMac(bleMac);
     // Convert to number, subtract 2, convert back to hex
     const bleValue = BigInt(`0x${normalized}`);
     const wifiValue = bleValue - BigInt(2);

package/dist/esm/src/bluetooth.d.ts

@@ -38,3 +38,5 @@ declare const scanForDevices: () => Promise<DiscoveredDevice[]>;
 declare const scanWithOptions: (options: RequestDeviceOptions) => Promise<BluetoothDevice>;
 export { EDILKAMIN_DEVICE_NAME, EDILKAMIN_SERVICE_UUID, isWebBluetoothSupported, scanForDevices, scanWithOptions, };
 export type { DiscoveredDevice } from "./types";
+export { aesDecrypt, aesEncrypt, crc16Modbus, createPacket, NOTIFY_CHARACTERISTIC_UUID, parseResponse, parsers, readCommands, SERVICE_UUID, WRITE_CHARACTERISTIC_UUID, writeCommands, } from "./bluetooth-protocol";
+export type { ModbusResponse } from "./bluetooth-protocol";

package/dist/esm/src/bluetooth.js

@@ -98,3 +98,11 @@ const scanWithOptions = (options) => __awaiter(void 0, void 0, void 0, function*
     return navigator.bluetooth.requestDevice(options);
 });
 export { EDILKAMIN_DEVICE_NAME, EDILKAMIN_SERVICE_UUID, isWebBluetoothSupported, scanForDevices, scanWithOptions, };
+// Protocol functions
+export { aesDecrypt, aesEncrypt, crc16Modbus, createPacket, 
+// Constants
+NOTIFY_CHARACTERISTIC_UUID, parseResponse, 
+// Commands
+parsers, readCommands, SERVICE_UUID, WRITE_CHARACTERISTIC_UUID, 
+// Parsers
+writeCommands, } from "./bluetooth-protocol";

package/dist/esm/src/cli.js

@@ -13,6 +13,7 @@ import readline from "readline";
 import { version } from "../package.json";
 import { NEW_API_URL, OLD_API_URL } from "./constants";
 import { configure, configureAmplify, getSession, signIn } from "./library";
+import { normalizeMac } from "./mac-utils";
 import { clearSession, createFileStorage } from "./token-storage";
 import { AlarmCode, AlarmDescriptions } from "./types";
 const promptPassword = () => {
@@ -66,7 +67,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 = normalizeMac(mac);
     // Initialize file storage for session persistence
     const storage = createFileStorage();
     configureAmplify(storage);
@@ -389,7 +390,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 = normalizeMac(mac);
         const storage = createFileStorage();
         configureAmplify(storage);
         let jwtToken;
@@ -412,7 +413,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 = normalizeMac(mac);
         const storage = createFileStorage();
         configureAmplify(storage);
         let jwtToken;
@@ -438,7 +439,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 = normalizeMac(mac);
         const storage = createFileStorage();
         configureAmplify(storage);
         let jwtToken;
@@ -463,7 +464,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 = normalizeMac(mac);
         const storage = createFileStorage();
         configureAmplify(storage);
         let jwtToken;
@@ -487,7 +488,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 = normalizeMac(mac);
         const storage = createFileStorage();
         configureAmplify(storage);
         let jwtToken;
@@ -518,7 +519,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 = normalizeMac(mac);
         // Initialize file storage for session persistence
         const storage = createFileStorage();
         configureAmplify(storage);
@@ -547,7 +548,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 = normalizeMac(mac);
         // Initialize file storage for session persistence
         const storage = createFileStorage();
         configureAmplify(storage);

package/dist/esm/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/esm/src/index.js

@@ -2,7 +2,8 @@ import { configure } from "./library";
 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 { AlarmCode, AlarmDescriptions } from "./types";
+export { AlarmCode, AlarmDescriptions, getIgnitionSubPhaseDescription, getOperationalPhaseDescription, getStoveStateDescription, IgnitionSubPhase, IgnitionSubPhaseDescriptions, OperationalPhase, OperationalPhaseDescriptions, StoveState, StoveStateDescriptions, } from "./types";
 export const { deviceInfo, registerDevice, editDevice, setPower, setPowerOff, setPowerOn, getPower, getEnvironmentTemperature, getTargetTemperature, setTargetTemperature, } = configure();

package/dist/esm/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>;