edilkamin 1.11.0 → 1.12.0

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

package/dist/cjs/src/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlarmDescriptions = exports.AlarmCode = void 0;
+exports.StoveStateDescriptions = exports.StoveState = exports.OperationalPhaseDescriptions = exports.OperationalPhase = exports.IgnitionSubPhaseDescriptions = exports.IgnitionSubPhase = exports.getStoveStateDescription = exports.getOperationalPhaseDescription = exports.getIgnitionSubPhaseDescription = exports.AlarmDescriptions = exports.AlarmCode = void 0;
 /**
  * Alarm type codes from Edilkamin devices.
  * Based on AlarmsEnum.java from Android app (version 1.3.1-RC2 released 2025/12/10).
@@ -64,3 +64,97 @@ const AlarmDescriptions = {
     [AlarmCode.BOARD_FUSE]: "Control board fuse issue",
 };
 exports.AlarmDescriptions = AlarmDescriptions;
+/**
+ * Main operational phases of the stove.
+ * Values derived from device behavior observation.
+ */
+var OperationalPhase;
+(function (OperationalPhase) {
+    OperationalPhase[OperationalPhase["OFF"] = 0] = "OFF";
+    OperationalPhase[OperationalPhase["STANDBY"] = 1] = "STANDBY";
+    OperationalPhase[OperationalPhase["IGNITION"] = 2] = "IGNITION";
+    OperationalPhase[OperationalPhase["ON"] = 6] = "ON";
+})(OperationalPhase || (exports.OperationalPhase = OperationalPhase = {}));
+/**
+ * Human-readable descriptions for operational phases.
+ */
+const OperationalPhaseDescriptions = {
+    [OperationalPhase.OFF]: "Off",
+    [OperationalPhase.STANDBY]: "Standby",
+    [OperationalPhase.IGNITION]: "Ignition",
+    [OperationalPhase.ON]: "On",
+};
+exports.OperationalPhaseDescriptions = OperationalPhaseDescriptions;
+/**
+ * Get description for an operational phase, with fallback for unknown values.
+ */
+const getOperationalPhaseDescription = (phase) => { var _a; return (_a = OperationalPhaseDescriptions[phase]) !== null && _a !== void 0 ? _a : `Unknown phase (${phase})`; };
+exports.getOperationalPhaseDescription = getOperationalPhaseDescription;
+/**
+ * Sub-phases during ignition sequence.
+ * These are only meaningful when operational_phase === IGNITION.
+ */
+var IgnitionSubPhase;
+(function (IgnitionSubPhase) {
+    IgnitionSubPhase[IgnitionSubPhase["STARTING_CLEANING"] = 0] = "STARTING_CLEANING";
+    IgnitionSubPhase[IgnitionSubPhase["PELLET_LOAD"] = 1] = "PELLET_LOAD";
+    IgnitionSubPhase[IgnitionSubPhase["LOADING_BREAK"] = 2] = "LOADING_BREAK";
+    IgnitionSubPhase[IgnitionSubPhase["SMOKE_TEMPERATURE_CHECK"] = 3] = "SMOKE_TEMPERATURE_CHECK";
+    IgnitionSubPhase[IgnitionSubPhase["THRESHOLD_EXCEEDING_CHECK"] = 4] = "THRESHOLD_EXCEEDING_CHECK";
+    IgnitionSubPhase[IgnitionSubPhase["WARMUP"] = 5] = "WARMUP";
+    IgnitionSubPhase[IgnitionSubPhase["TRANSITION_TO_ON"] = 6] = "TRANSITION_TO_ON";
+})(IgnitionSubPhase || (exports.IgnitionSubPhase = IgnitionSubPhase = {}));
+/**
+ * Human-readable descriptions for ignition sub-phases.
+ */
+const IgnitionSubPhaseDescriptions = {
+    [IgnitionSubPhase.STARTING_CLEANING]: "Starting cleaning",
+    [IgnitionSubPhase.PELLET_LOAD]: "Pellet load",
+    [IgnitionSubPhase.LOADING_BREAK]: "Loading break",
+    [IgnitionSubPhase.SMOKE_TEMPERATURE_CHECK]: "Smoke temperature check",
+    [IgnitionSubPhase.THRESHOLD_EXCEEDING_CHECK]: "Threshold exceeding check",
+    [IgnitionSubPhase.WARMUP]: "Warmup",
+    [IgnitionSubPhase.TRANSITION_TO_ON]: "Starting up",
+};
+exports.IgnitionSubPhaseDescriptions = IgnitionSubPhaseDescriptions;
+/**
+ * Get description for an ignition sub-phase, with fallback for unknown values.
+ */
+const getIgnitionSubPhaseDescription = (subPhase) => { var _a; return (_a = IgnitionSubPhaseDescriptions[subPhase]) !== null && _a !== void 0 ? _a : `Unknown sub-phase (${subPhase})`; };
+exports.getIgnitionSubPhaseDescription = getIgnitionSubPhaseDescription;
+/**
+ * Combined stove states.
+ * This is a composite value combining operational phase and sub-phase.
+ */
+var StoveState;
+(function (StoveState) {
+    StoveState[StoveState["OFF"] = 0] = "OFF";
+    StoveState[StoveState["STANDBY"] = 1] = "STANDBY";
+    StoveState[StoveState["IGNITION_CLEANING"] = 2] = "IGNITION_CLEANING";
+    StoveState[StoveState["IGNITION_LOADING"] = 3] = "IGNITION_LOADING";
+    StoveState[StoveState["IGNITION_WAITING"] = 4] = "IGNITION_WAITING";
+    StoveState[StoveState["IGNITION_WARMUP"] = 5] = "IGNITION_WARMUP";
+    StoveState[StoveState["ON"] = 6] = "ON";
+    StoveState[StoveState["COOLING"] = 7] = "COOLING";
+    StoveState[StoveState["ALARM"] = 8] = "ALARM";
+})(StoveState || (exports.StoveState = StoveState = {}));
+/**
+ * Human-readable descriptions for stove states.
+ */
+const StoveStateDescriptions = {
+    [StoveState.OFF]: "Off",
+    [StoveState.STANDBY]: "Standby",
+    [StoveState.IGNITION_CLEANING]: "Ignition - Cleaning",
+    [StoveState.IGNITION_LOADING]: "Ignition - Loading pellets",
+    [StoveState.IGNITION_WAITING]: "Ignition - Waiting",
+    [StoveState.IGNITION_WARMUP]: "Ignition - Warming up",
+    [StoveState.ON]: "On",
+    [StoveState.COOLING]: "Cooling down",
+    [StoveState.ALARM]: "Alarm",
+};
+exports.StoveStateDescriptions = StoveStateDescriptions;
+/**
+ * Get description for a stove state, with fallback for unknown values.
+ */
+const getStoveStateDescription = (state) => { var _a; return (_a = StoveStateDescriptions[state]) !== null && _a !== void 0 ? _a : `Unknown state (${state})`; };
+exports.getStoveStateDescription = getStoveStateDescription;

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

package/dist/esm/src/library.js

@@ -13,6 +13,8 @@ import * as amplifyAuth from "aws-amplify/auth";
 import { cognitoUserPoolsTokenProvider } from "aws-amplify/auth/cognito";
 import { processResponse } from "./buffer-utils";
 import { API_URL } from "./constants";
+import { normalizeMac } from "./mac-utils";
+import { getIgnitionSubPhaseDescription, getOperationalPhaseDescription, OperationalPhase, } from "./types";
 /**
  * Makes a fetch request and returns parsed JSON response.
  * Throws an error for non-2xx status codes.
@@ -473,6 +475,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.
@@ -693,7 +745,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: normalizeMac(macAddress),
         deviceName,
         deviceRoom,
         serialNumber,
@@ -715,7 +767,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 = normalizeMac(macAddress);
     const body = {
         deviceName,
         deviceRoom,
@@ -726,6 +778,41 @@ 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"
+ */
+export const getPhaseDescription = (operationalPhase, subOperationalPhase) => {
+    if (operationalPhase === OperationalPhase.IGNITION) {
+        const subDesc = getIgnitionSubPhaseDescription(subOperationalPhase);
+        return `Ignition - ${subDesc}`;
+    }
+    return getOperationalPhaseDescription(operationalPhase);
+};
+/**
+ * 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 const derivePhaseDescription = (deviceInfo) => {
+    const { operational_phase, sub_operational_phase } = deviceInfo.status.state;
+    return getPhaseDescription(operational_phase, sub_operational_phase);
+};
 /**
  * Configures the library for API interactions.
  * Initializes API methods with a specified base URL.
@@ -778,6 +865,11 @@ const configure = (baseURL = 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),