edilkamin 1.7.4 → 1.8.0

package/README.md

@@ -115,6 +115,39 @@ const legacyApi = configure(OLD_API_URL);
 
 > **Note**: The legacy API uses AWS API Gateway and may be deprecated in the future.
 
+## Bluetooth Device Discovery
+
+For automatic device discovery in web browsers, use the `edilkamin/bluetooth` subpath export.
+
+### Quick Example (Web)
+
+```javascript
+import { scanForDevices } from "edilkamin/bluetooth";
+import { deviceInfo, signIn } from "edilkamin";
+
+// Scan for nearby stoves (requires user gesture)
+const devices = await scanForDevices();
+const { wifiMac } = devices[0];
+
+// Use discovered MAC for API calls
+const token = await signIn(username, password);
+const info = await deviceInfo(token, wifiMac);
+```
+
+### MAC Address Helper
+
+The core library includes a helper to convert BLE MAC to WiFi MAC:
+
+```javascript
+import { bleToWifiMac } from "edilkamin";
+
+// BLE MAC from Bluetooth scan
+const bleMac = "A8:03:2A:FE:D5:0A";
+
+// WiFi MAC for API calls (BLE - 2)
+const wifiMac = bleToWifiMac(bleMac); // "a8032afed508"
+```
+
 ## Motivations
 
 - providing an open source web alternative
@@ -132,6 +165,6 @@ const legacyApi = configure(OLD_API_URL);
 
 ## Limitations
 
-It seems like there's no endpoint to list stoves associated to a user.
-The way the official app seem to work is by probing the stove via bluetooth.
-Then cache the stove MAC address to a local database for later use.
+- **No server-side device listing**: The API doesn't provide an endpoint to list stoves associated to a user.
+- **Bluetooth discovery available**: Use `edilkamin/bluetooth` for web browser device discovery, similar to the official app.
+- **Manual MAC entry fallback**: For unsupported browsers or CLI, users can find the BLE MAC with different means and use `bleToWifiMac()` to calculate the WiFi MAC for API calls.

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "edilkamin",
-    "version": "1.7.4",
+    "version": "1.8.0",
     "description": "",
     "main": "dist/cjs/src/index.js",
     "module": "dist/esm/src/index.js",
@@ -15,6 +15,16 @@
                 "types": "./dist/cjs/src/index.d.ts",
                 "default": "./dist/cjs/src/index.js"
             }
+        },
+        "./bluetooth": {
+            "import": {
+                "types": "./dist/esm/src/bluetooth.d.ts",
+                "default": "./dist/esm/src/bluetooth.js"
+            },
+            "require": {
+                "types": "./dist/cjs/src/bluetooth.d.ts",
+                "default": "./dist/cjs/src/bluetooth.js"
+            }
         }
     },
     "scripts": {
@@ -63,6 +73,7 @@
         "@types/node": "^25.0.2",
         "@types/pako": "^2.0.4",
         "@types/sinon": "^17.0.3",
+        "@types/web-bluetooth": "^0.0.21",
         "@typescript-eslint/eslint-plugin": "^8.17.0",
         "@typescript-eslint/parser": "^8.17.0",
         "esbuild": "^0.27.1",
@@ -79,6 +90,6 @@
         "typescript": "^5.7.2"
     },
     "optionalDependencies": {
-        "commander": "^12.1.0"
+        "commander": "^14.0.2"
     }
 }

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

@@ -0,0 +1,13 @@
+/**
+ * Converts a BLE MAC address to WiFi MAC address.
+ * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
+ *
+ * @param bleMac - BLE MAC address (with or without colons/dashes)
+ * @returns WiFi MAC address in lowercase without separators
+ *
+ * @example
+ * bleToWifiMac("A8:03:2A:FE:D5:0A") // returns "a8032afed508"
+ * bleToWifiMac("a8032afed50a")      // returns "a8032afed508"
+ */
+declare const bleToWifiMac: (bleMac: string) => string;
+export { bleToWifiMac };

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bleToWifiMac = void 0;
+/**
+ * Converts a BLE MAC address to WiFi MAC address.
+ * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
+ *
+ * @param bleMac - BLE MAC address (with or without colons/dashes)
+ * @returns WiFi MAC address in lowercase without separators
+ *
+ * @example
+ * bleToWifiMac("A8:03:2A:FE:D5:0A") // returns "a8032afed508"
+ * 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}`);
+    }
+    // Convert to number, subtract 2, convert back to hex
+    const bleValue = BigInt(`0x${normalized}`);
+    const wifiValue = bleValue - BigInt(2);
+    // Pad to 12 characters and return lowercase
+    return wifiValue.toString(16).padStart(12, "0");
+};
+exports.bleToWifiMac = bleToWifiMac;

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

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

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

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert_1 = require("assert");
+const bluetooth_utils_1 = require("./bluetooth-utils");
+describe("bleToWifiMac", () => {
+    it("converts BLE MAC with colons to WiFi MAC", () => {
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("A8:03:2A:FE:D5:0A"), "a8032afed508");
+    });
+    it("converts BLE MAC without separators", () => {
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("a8032afed50a"), "a8032afed508");
+    });
+    it("converts BLE MAC with dashes", () => {
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("A8-03-2A-FE-D5-0A"), "a8032afed508");
+    });
+    it("handles lowercase input", () => {
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("a8:03:2a:fe:d5:0a"), "a8032afed508");
+    });
+    it("handles edge case where subtraction crosses byte boundary", () => {
+        // FF:FF:FF:FF:FF:01 - 2 = FF:FF:FF:FF:FE:FF
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("FF:FF:FF:FF:FF:01"), "fffffffffeff");
+    });
+    it("handles minimum value edge case", () => {
+        // 00:00:00:00:00:02 - 2 = 00:00:00:00:00:00
+        assert_1.strict.equal((0, bluetooth_utils_1.bleToWifiMac)("00:00:00:00:00:02"), "000000000000");
+    });
+    it("throws on invalid MAC format - too short", () => {
+        assert_1.strict.throws(() => (0, bluetooth_utils_1.bleToWifiMac)("A8:03:2A"), /Invalid MAC address format/);
+    });
+    it("throws on invalid MAC format - invalid characters", () => {
+        assert_1.strict.throws(() => (0, bluetooth_utils_1.bleToWifiMac)("G8:03:2A:FE:D5:0A"), /Invalid MAC address format/);
+    });
+    it("throws on empty string", () => {
+        assert_1.strict.throws(() => (0, bluetooth_utils_1.bleToWifiMac)(""), /Invalid MAC address format/);
+    });
+});

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

@@ -0,0 +1,40 @@
+import { DiscoveredDevice } from "./types";
+/** Device name broadcast by Edilkamin stoves */
+declare const EDILKAMIN_DEVICE_NAME = "EDILKAMIN_EP";
+/** GATT Service UUID for Edilkamin devices (0xABF0) */
+declare const EDILKAMIN_SERVICE_UUID = 44016;
+/**
+ * Check if Web Bluetooth API is available in the current browser.
+ *
+ * @returns true if Web Bluetooth is supported
+ */
+declare const isWebBluetoothSupported: () => boolean;
+/**
+ * Scan for nearby Edilkamin stoves using the Web Bluetooth API.
+ *
+ * This function triggers the browser's Bluetooth device picker dialog,
+ * filtered to show only devices named "EDILKAMIN_EP".
+ *
+ * Note: Web Bluetooth requires:
+ * - HTTPS or localhost
+ * - User gesture (button click)
+ * - Chrome/Edge/Opera (not Firefox/Safari)
+ *
+ * @returns Promise resolving to array of discovered devices
+ * @throws Error if Web Bluetooth is not supported or user cancels
+ *
+ * @example
+ * const devices = await scanForDevices();
+ * console.log(devices[0].wifiMac); // Use this for API calls
+ */
+declare const scanForDevices: () => Promise<DiscoveredDevice[]>;
+/**
+ * Scan for devices with a custom filter.
+ * Advanced function for users who need more control over device selection.
+ *
+ * @param options - Web Bluetooth requestDevice options
+ * @returns Promise resolving to the selected BluetoothDevice
+ */
+declare const scanWithOptions: (options: RequestDeviceOptions) => Promise<BluetoothDevice>;
+export { EDILKAMIN_DEVICE_NAME, EDILKAMIN_SERVICE_UUID, isWebBluetoothSupported, scanForDevices, scanWithOptions, };
+export type { DiscoveredDevice } from "./types";

package/dist/cjs/src/bluetooth.js

@@ -0,0 +1,107 @@
+"use strict";
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanWithOptions = exports.scanForDevices = exports.isWebBluetoothSupported = exports.EDILKAMIN_SERVICE_UUID = exports.EDILKAMIN_DEVICE_NAME = void 0;
+const bluetooth_utils_1 = require("./bluetooth-utils");
+/** Device name broadcast by Edilkamin stoves */
+const EDILKAMIN_DEVICE_NAME = "EDILKAMIN_EP";
+exports.EDILKAMIN_DEVICE_NAME = EDILKAMIN_DEVICE_NAME;
+/** GATT Service UUID for Edilkamin devices (0xABF0) */
+const EDILKAMIN_SERVICE_UUID = 0xabf0;
+exports.EDILKAMIN_SERVICE_UUID = EDILKAMIN_SERVICE_UUID;
+/**
+ * Check if Web Bluetooth API is available in the current browser.
+ *
+ * @returns true if Web Bluetooth is supported
+ */
+const isWebBluetoothSupported = () => {
+    return typeof navigator !== "undefined" && "bluetooth" in navigator;
+};
+exports.isWebBluetoothSupported = isWebBluetoothSupported;
+/**
+ * Scan for nearby Edilkamin stoves using the Web Bluetooth API.
+ *
+ * This function triggers the browser's Bluetooth device picker dialog,
+ * filtered to show only devices named "EDILKAMIN_EP".
+ *
+ * Note: Web Bluetooth requires:
+ * - HTTPS or localhost
+ * - User gesture (button click)
+ * - Chrome/Edge/Opera (not Firefox/Safari)
+ *
+ * @returns Promise resolving to array of discovered devices
+ * @throws Error if Web Bluetooth is not supported or user cancels
+ *
+ * @example
+ * const devices = await scanForDevices();
+ * console.log(devices[0].wifiMac); // Use this for API calls
+ */
+const scanForDevices = () => __awaiter(void 0, void 0, void 0, function* () {
+    if (!isWebBluetoothSupported()) {
+        throw new Error("Web Bluetooth API is not supported in this browser. " +
+            "Use Chrome, Edge, or Opera on desktop/Android. " +
+            "On iOS, use the Bluefy browser app.");
+    }
+    try {
+        // Request device - this opens the browser's device picker
+        const device = yield navigator.bluetooth.requestDevice({
+            filters: [{ name: EDILKAMIN_DEVICE_NAME }],
+            optionalServices: [EDILKAMIN_SERVICE_UUID],
+        });
+        // Extract BLE MAC from device ID if available
+        // Note: device.id format varies by platform, may need adjustment
+        const bleMac = device.id || "";
+        const name = device.name || EDILKAMIN_DEVICE_NAME;
+        // Calculate WiFi MAC for API calls
+        let wifiMac = "";
+        if (bleMac && /^[0-9a-f:-]{12,17}$/i.test(bleMac)) {
+            try {
+                wifiMac = (0, bluetooth_utils_1.bleToWifiMac)(bleMac);
+            }
+            catch (_a) {
+                // device.id may not be a valid MAC format on all platforms
+                wifiMac = "";
+            }
+        }
+        const discoveredDevice = {
+            bleMac,
+            wifiMac,
+            name,
+            // RSSI not directly available from requestDevice
+        };
+        return [discoveredDevice];
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            if (error.name === "NotFoundError") {
+                // User cancelled the device picker
+                return [];
+            }
+            throw error;
+        }
+        throw new Error("Unknown error during Bluetooth scan");
+    }
+});
+exports.scanForDevices = scanForDevices;
+/**
+ * Scan for devices with a custom filter.
+ * Advanced function for users who need more control over device selection.
+ *
+ * @param options - Web Bluetooth requestDevice options
+ * @returns Promise resolving to the selected BluetoothDevice
+ */
+const scanWithOptions = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!isWebBluetoothSupported()) {
+        throw new Error("Web Bluetooth API is not supported in this browser.");
+    }
+    return navigator.bluetooth.requestDevice(options);
+});
+exports.scanWithOptions = scanWithOptions;

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

@@ -1,6 +1,7 @@
+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, getSession, signIn } from "./library";
 export { serialNumberDisplay, serialNumberFromHex, serialNumberToHex, } from "./serial-utils";
-export { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, } from "./types";
+export { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, } 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) => Promise<number>, setTargetTemperature: (jwtToken: string, macAddress: string, temperature: number) => Promise<unknown>;

package/dist/cjs/src/index.js

@@ -1,8 +1,10 @@
 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setTargetTemperature = exports.getTargetTemperature = exports.getEnvironmentTemperature = exports.getPower = exports.setPowerOn = exports.setPowerOff = exports.setPower = exports.editDevice = exports.registerDevice = exports.deviceInfo = exports.serialNumberToHex = exports.serialNumberFromHex = exports.serialNumberDisplay = exports.signIn = exports.getSession = exports.configure = exports.OLD_API_URL = exports.NEW_API_URL = exports.API_URL = exports.processResponse = exports.isBuffer = exports.decompressBuffer = void 0;
+exports.setTargetTemperature = exports.getTargetTemperature = exports.getEnvironmentTemperature = exports.getPower = exports.setPowerOn = exports.setPowerOff = exports.setPower = exports.editDevice = exports.registerDevice = exports.deviceInfo = exports.serialNumberToHex = exports.serialNumberFromHex = exports.serialNumberDisplay = exports.signIn = exports.getSession = exports.configure = exports.OLD_API_URL = exports.NEW_API_URL = exports.API_URL = exports.processResponse = exports.isBuffer = exports.decompressBuffer = exports.bleToWifiMac = void 0;
 const library_1 = require("./library");
+var bluetooth_utils_1 = require("./bluetooth-utils");
+Object.defineProperty(exports, "bleToWifiMac", { enumerable: true, get: function () { return bluetooth_utils_1.bleToWifiMac; } });
 var buffer_utils_1 = require("./buffer-utils");
 Object.defineProperty(exports, "decompressBuffer", { enumerable: true, get: function () { return buffer_utils_1.decompressBuffer; } });
 Object.defineProperty(exports, "isBuffer", { enumerable: true, get: function () { return buffer_utils_1.isBuffer; } });

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

@@ -70,4 +70,17 @@ interface DeviceAssociationResponse {
     deviceRoom: string;
     serialNumber: string;
 }
-export type { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, };
+/**
+ * Represents a discovered Edilkamin device from Bluetooth scanning.
+ */
+interface DiscoveredDevice {
+    /** BLE MAC address as discovered */
+    bleMac: string;
+    /** WiFi MAC address (BLE MAC - 2), used for API calls */
+    wifiMac: string;
+    /** Device name (typically "EDILKAMIN_EP") */
+    name: string;
+    /** Signal strength in dBm (optional, not all platforms provide this) */
+    rssi?: number;
+}
+export type { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, };

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "edilkamin",
-    "version": "1.7.4",
+    "version": "1.8.0",
     "description": "",
     "main": "dist/cjs/src/index.js",
     "module": "dist/esm/src/index.js",
@@ -15,6 +15,16 @@
                 "types": "./dist/cjs/src/index.d.ts",
                 "default": "./dist/cjs/src/index.js"
             }
+        },
+        "./bluetooth": {
+            "import": {
+                "types": "./dist/esm/src/bluetooth.d.ts",
+                "default": "./dist/esm/src/bluetooth.js"
+            },
+            "require": {
+                "types": "./dist/cjs/src/bluetooth.d.ts",
+                "default": "./dist/cjs/src/bluetooth.js"
+            }
         }
     },
     "scripts": {
@@ -63,6 +73,7 @@
         "@types/node": "^25.0.2",
         "@types/pako": "^2.0.4",
         "@types/sinon": "^17.0.3",
+        "@types/web-bluetooth": "^0.0.21",
         "@typescript-eslint/eslint-plugin": "^8.17.0",
         "@typescript-eslint/parser": "^8.17.0",
         "esbuild": "^0.27.1",
@@ -79,6 +90,6 @@
         "typescript": "^5.7.2"
     },
     "optionalDependencies": {
-        "commander": "^12.1.0"
+        "commander": "^14.0.2"
     }
 }

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

@@ -0,0 +1,13 @@
+/**
+ * Converts a BLE MAC address to WiFi MAC address.
+ * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
+ *
+ * @param bleMac - BLE MAC address (with or without colons/dashes)
+ * @returns WiFi MAC address in lowercase without separators
+ *
+ * @example
+ * bleToWifiMac("A8:03:2A:FE:D5:0A") // returns "a8032afed508"
+ * bleToWifiMac("a8032afed50a")      // returns "a8032afed508"
+ */
+declare const bleToWifiMac: (bleMac: string) => string;
+export { bleToWifiMac };

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

@@ -0,0 +1,25 @@
+/**
+ * Converts a BLE MAC address to WiFi MAC address.
+ * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
+ *
+ * @param bleMac - BLE MAC address (with or without colons/dashes)
+ * @returns WiFi MAC address in lowercase without separators
+ *
+ * @example
+ * bleToWifiMac("A8:03:2A:FE:D5:0A") // returns "a8032afed508"
+ * 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}`);
+    }
+    // Convert to number, subtract 2, convert back to hex
+    const bleValue = BigInt(`0x${normalized}`);
+    const wifiValue = bleValue - BigInt(2);
+    // Pad to 12 characters and return lowercase
+    return wifiValue.toString(16).padStart(12, "0");
+};
+export { bleToWifiMac };

package/dist/esm/src/bluetooth-utils.test.d.ts

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

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

@@ -0,0 +1,33 @@
+import { strict as assert } from "assert";
+import { bleToWifiMac } from "./bluetooth-utils";
+describe("bleToWifiMac", () => {
+    it("converts BLE MAC with colons to WiFi MAC", () => {
+        assert.equal(bleToWifiMac("A8:03:2A:FE:D5:0A"), "a8032afed508");
+    });
+    it("converts BLE MAC without separators", () => {
+        assert.equal(bleToWifiMac("a8032afed50a"), "a8032afed508");
+    });
+    it("converts BLE MAC with dashes", () => {
+        assert.equal(bleToWifiMac("A8-03-2A-FE-D5-0A"), "a8032afed508");
+    });
+    it("handles lowercase input", () => {
+        assert.equal(bleToWifiMac("a8:03:2a:fe:d5:0a"), "a8032afed508");
+    });
+    it("handles edge case where subtraction crosses byte boundary", () => {
+        // FF:FF:FF:FF:FF:01 - 2 = FF:FF:FF:FF:FE:FF
+        assert.equal(bleToWifiMac("FF:FF:FF:FF:FF:01"), "fffffffffeff");
+    });
+    it("handles minimum value edge case", () => {
+        // 00:00:00:00:00:02 - 2 = 00:00:00:00:00:00
+        assert.equal(bleToWifiMac("00:00:00:00:00:02"), "000000000000");
+    });
+    it("throws on invalid MAC format - too short", () => {
+        assert.throws(() => bleToWifiMac("A8:03:2A"), /Invalid MAC address format/);
+    });
+    it("throws on invalid MAC format - invalid characters", () => {
+        assert.throws(() => bleToWifiMac("G8:03:2A:FE:D5:0A"), /Invalid MAC address format/);
+    });
+    it("throws on empty string", () => {
+        assert.throws(() => bleToWifiMac(""), /Invalid MAC address format/);
+    });
+});

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

@@ -0,0 +1,40 @@
+import { DiscoveredDevice } from "./types";
+/** Device name broadcast by Edilkamin stoves */
+declare const EDILKAMIN_DEVICE_NAME = "EDILKAMIN_EP";
+/** GATT Service UUID for Edilkamin devices (0xABF0) */
+declare const EDILKAMIN_SERVICE_UUID = 44016;
+/**
+ * Check if Web Bluetooth API is available in the current browser.
+ *
+ * @returns true if Web Bluetooth is supported
+ */
+declare const isWebBluetoothSupported: () => boolean;
+/**
+ * Scan for nearby Edilkamin stoves using the Web Bluetooth API.
+ *
+ * This function triggers the browser's Bluetooth device picker dialog,
+ * filtered to show only devices named "EDILKAMIN_EP".
+ *
+ * Note: Web Bluetooth requires:
+ * - HTTPS or localhost
+ * - User gesture (button click)
+ * - Chrome/Edge/Opera (not Firefox/Safari)
+ *
+ * @returns Promise resolving to array of discovered devices
+ * @throws Error if Web Bluetooth is not supported or user cancels
+ *
+ * @example
+ * const devices = await scanForDevices();
+ * console.log(devices[0].wifiMac); // Use this for API calls
+ */
+declare const scanForDevices: () => Promise<DiscoveredDevice[]>;
+/**
+ * Scan for devices with a custom filter.
+ * Advanced function for users who need more control over device selection.
+ *
+ * @param options - Web Bluetooth requestDevice options
+ * @returns Promise resolving to the selected BluetoothDevice
+ */
+declare const scanWithOptions: (options: RequestDeviceOptions) => Promise<BluetoothDevice>;
+export { EDILKAMIN_DEVICE_NAME, EDILKAMIN_SERVICE_UUID, isWebBluetoothSupported, scanForDevices, scanWithOptions, };
+export type { DiscoveredDevice } from "./types";

package/dist/esm/src/bluetooth.js

@@ -0,0 +1,100 @@
+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 { bleToWifiMac } from "./bluetooth-utils";
+/** Device name broadcast by Edilkamin stoves */
+const EDILKAMIN_DEVICE_NAME = "EDILKAMIN_EP";
+/** GATT Service UUID for Edilkamin devices (0xABF0) */
+const EDILKAMIN_SERVICE_UUID = 0xabf0;
+/**
+ * Check if Web Bluetooth API is available in the current browser.
+ *
+ * @returns true if Web Bluetooth is supported
+ */
+const isWebBluetoothSupported = () => {
+    return typeof navigator !== "undefined" && "bluetooth" in navigator;
+};
+/**
+ * Scan for nearby Edilkamin stoves using the Web Bluetooth API.
+ *
+ * This function triggers the browser's Bluetooth device picker dialog,
+ * filtered to show only devices named "EDILKAMIN_EP".
+ *
+ * Note: Web Bluetooth requires:
+ * - HTTPS or localhost
+ * - User gesture (button click)
+ * - Chrome/Edge/Opera (not Firefox/Safari)
+ *
+ * @returns Promise resolving to array of discovered devices
+ * @throws Error if Web Bluetooth is not supported or user cancels
+ *
+ * @example
+ * const devices = await scanForDevices();
+ * console.log(devices[0].wifiMac); // Use this for API calls
+ */
+const scanForDevices = () => __awaiter(void 0, void 0, void 0, function* () {
+    if (!isWebBluetoothSupported()) {
+        throw new Error("Web Bluetooth API is not supported in this browser. " +
+            "Use Chrome, Edge, or Opera on desktop/Android. " +
+            "On iOS, use the Bluefy browser app.");
+    }
+    try {
+        // Request device - this opens the browser's device picker
+        const device = yield navigator.bluetooth.requestDevice({
+            filters: [{ name: EDILKAMIN_DEVICE_NAME }],
+            optionalServices: [EDILKAMIN_SERVICE_UUID],
+        });
+        // Extract BLE MAC from device ID if available
+        // Note: device.id format varies by platform, may need adjustment
+        const bleMac = device.id || "";
+        const name = device.name || EDILKAMIN_DEVICE_NAME;
+        // Calculate WiFi MAC for API calls
+        let wifiMac = "";
+        if (bleMac && /^[0-9a-f:-]{12,17}$/i.test(bleMac)) {
+            try {
+                wifiMac = bleToWifiMac(bleMac);
+            }
+            catch (_a) {
+                // device.id may not be a valid MAC format on all platforms
+                wifiMac = "";
+            }
+        }
+        const discoveredDevice = {
+            bleMac,
+            wifiMac,
+            name,
+            // RSSI not directly available from requestDevice
+        };
+        return [discoveredDevice];
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            if (error.name === "NotFoundError") {
+                // User cancelled the device picker
+                return [];
+            }
+            throw error;
+        }
+        throw new Error("Unknown error during Bluetooth scan");
+    }
+});
+/**
+ * Scan for devices with a custom filter.
+ * Advanced function for users who need more control over device selection.
+ *
+ * @param options - Web Bluetooth requestDevice options
+ * @returns Promise resolving to the selected BluetoothDevice
+ */
+const scanWithOptions = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!isWebBluetoothSupported()) {
+        throw new Error("Web Bluetooth API is not supported in this browser.");
+    }
+    return navigator.bluetooth.requestDevice(options);
+});
+export { EDILKAMIN_DEVICE_NAME, EDILKAMIN_SERVICE_UUID, isWebBluetoothSupported, scanForDevices, scanWithOptions, };

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

@@ -1,6 +1,7 @@
+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, getSession, signIn } from "./library";
 export { serialNumberDisplay, serialNumberFromHex, serialNumberToHex, } from "./serial-utils";
-export { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, } from "./types";
+export { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, } 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) => Promise<number>, setTargetTemperature: (jwtToken: string, macAddress: string, temperature: number) => Promise<unknown>;

package/dist/esm/src/index.js

@@ -1,4 +1,5 @@
 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, getSession, signIn } from "./library";

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

@@ -70,4 +70,17 @@ interface DeviceAssociationResponse {
     deviceRoom: string;
     serialNumber: string;
 }
-export type { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, };
+/**
+ * Represents a discovered Edilkamin device from Bluetooth scanning.
+ */
+interface DiscoveredDevice {
+    /** BLE MAC address as discovered */
+    bleMac: string;
+    /** WiFi MAC address (BLE MAC - 2), used for API calls */
+    wifiMac: string;
+    /** Device name (typically "EDILKAMIN_EP") */
+    name: string;
+    /** Signal strength in dBm (optional, not all platforms provide this) */
+    rssi?: number;
+}
+export type { BufferEncodedType, CommandsType, DeviceAssociationBody, DeviceAssociationResponse, DeviceInfoRawType, DeviceInfoType, DiscoveredDevice, EditDeviceAssociationBody, StatusType, TemperaturesType, UserParametersType, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edilkamin",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "",
   "main": "dist/cjs/src/index.js",
   "module": "dist/esm/src/index.js",
@@ -15,6 +15,16 @@
         "types": "./dist/cjs/src/index.d.ts",
         "default": "./dist/cjs/src/index.js"
       }
+    },
+    "./bluetooth": {
+      "import": {
+        "types": "./dist/esm/src/bluetooth.d.ts",
+        "default": "./dist/esm/src/bluetooth.js"
+      },
+      "require": {
+        "types": "./dist/cjs/src/bluetooth.d.ts",
+        "default": "./dist/cjs/src/bluetooth.js"
+      }
     }
   },
   "scripts": {
@@ -63,6 +73,7 @@
     "@types/node": "^25.0.2",
     "@types/pako": "^2.0.4",
     "@types/sinon": "^17.0.3",
+    "@types/web-bluetooth": "^0.0.21",
     "@typescript-eslint/eslint-plugin": "^8.17.0",
     "@typescript-eslint/parser": "^8.17.0",
     "esbuild": "^0.27.1",
@@ -79,6 +90,6 @@
     "typescript": "^5.7.2"
   },
   "optionalDependencies": {
-    "commander": "^12.1.0"
+    "commander": "^14.0.2"
   }
 }

package/src/bluetooth-utils.test.ts

@@ -0,0 +1,46 @@
+import { strict as assert } from "assert";
+
+import { bleToWifiMac } from "./bluetooth-utils";
+
+describe("bleToWifiMac", () => {
+  it("converts BLE MAC with colons to WiFi MAC", () => {
+    assert.equal(bleToWifiMac("A8:03:2A:FE:D5:0A"), "a8032afed508");
+  });
+
+  it("converts BLE MAC without separators", () => {
+    assert.equal(bleToWifiMac("a8032afed50a"), "a8032afed508");
+  });
+
+  it("converts BLE MAC with dashes", () => {
+    assert.equal(bleToWifiMac("A8-03-2A-FE-D5-0A"), "a8032afed508");
+  });
+
+  it("handles lowercase input", () => {
+    assert.equal(bleToWifiMac("a8:03:2a:fe:d5:0a"), "a8032afed508");
+  });
+
+  it("handles edge case where subtraction crosses byte boundary", () => {
+    // FF:FF:FF:FF:FF:01 - 2 = FF:FF:FF:FF:FE:FF
+    assert.equal(bleToWifiMac("FF:FF:FF:FF:FF:01"), "fffffffffeff");
+  });
+
+  it("handles minimum value edge case", () => {
+    // 00:00:00:00:00:02 - 2 = 00:00:00:00:00:00
+    assert.equal(bleToWifiMac("00:00:00:00:00:02"), "000000000000");
+  });
+
+  it("throws on invalid MAC format - too short", () => {
+    assert.throws(() => bleToWifiMac("A8:03:2A"), /Invalid MAC address format/);
+  });
+
+  it("throws on invalid MAC format - invalid characters", () => {
+    assert.throws(
+      () => bleToWifiMac("G8:03:2A:FE:D5:0A"),
+      /Invalid MAC address format/,
+    );
+  });
+
+  it("throws on empty string", () => {
+    assert.throws(() => bleToWifiMac(""), /Invalid MAC address format/);
+  });
+});

package/src/bluetooth-utils.ts

@@ -0,0 +1,29 @@
+/**
+ * Converts a BLE MAC address to WiFi MAC address.
+ * The WiFi MAC is the BLE MAC minus 2 in hexadecimal.
+ *
+ * @param bleMac - BLE MAC address (with or without colons/dashes)
+ * @returns WiFi MAC address in lowercase without separators
+ *
+ * @example
+ * bleToWifiMac("A8:03:2A:FE:D5:0A") // returns "a8032afed508"
+ * bleToWifiMac("a8032afed50a")      // returns "a8032afed508"
+ */
+const bleToWifiMac = (bleMac: string): string => {
+  // 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}`);
+  }
+
+  // Convert to number, subtract 2, convert back to hex
+  const bleValue = BigInt(`0x${normalized}`);
+  const wifiValue = bleValue - BigInt(2);
+
+  // Pad to 12 characters and return lowercase
+  return wifiValue.toString(16).padStart(12, "0");
+};
+
+export { bleToWifiMac };

package/src/bluetooth.ts

@@ -0,0 +1,115 @@
+import { bleToWifiMac } from "./bluetooth-utils";
+import { DiscoveredDevice } from "./types";
+
+/** Device name broadcast by Edilkamin stoves */
+const EDILKAMIN_DEVICE_NAME = "EDILKAMIN_EP";
+
+/** GATT Service UUID for Edilkamin devices (0xABF0) */
+const EDILKAMIN_SERVICE_UUID = 0xabf0;
+
+/**
+ * Check if Web Bluetooth API is available in the current browser.
+ *
+ * @returns true if Web Bluetooth is supported
+ */
+const isWebBluetoothSupported = (): boolean => {
+  return typeof navigator !== "undefined" && "bluetooth" in navigator;
+};
+
+/**
+ * Scan for nearby Edilkamin stoves using the Web Bluetooth API.
+ *
+ * This function triggers the browser's Bluetooth device picker dialog,
+ * filtered to show only devices named "EDILKAMIN_EP".
+ *
+ * Note: Web Bluetooth requires:
+ * - HTTPS or localhost
+ * - User gesture (button click)
+ * - Chrome/Edge/Opera (not Firefox/Safari)
+ *
+ * @returns Promise resolving to array of discovered devices
+ * @throws Error if Web Bluetooth is not supported or user cancels
+ *
+ * @example
+ * const devices = await scanForDevices();
+ * console.log(devices[0].wifiMac); // Use this for API calls
+ */
+const scanForDevices = async (): Promise<DiscoveredDevice[]> => {
+  if (!isWebBluetoothSupported()) {
+    throw new Error(
+      "Web Bluetooth API is not supported in this browser. " +
+        "Use Chrome, Edge, or Opera on desktop/Android. " +
+        "On iOS, use the Bluefy browser app.",
+    );
+  }
+
+  try {
+    // Request device - this opens the browser's device picker
+    const device = await navigator.bluetooth.requestDevice({
+      filters: [{ name: EDILKAMIN_DEVICE_NAME }],
+      optionalServices: [EDILKAMIN_SERVICE_UUID],
+    });
+
+    // Extract BLE MAC from device ID if available
+    // Note: device.id format varies by platform, may need adjustment
+    const bleMac = device.id || "";
+    const name = device.name || EDILKAMIN_DEVICE_NAME;
+
+    // Calculate WiFi MAC for API calls
+    let wifiMac = "";
+    if (bleMac && /^[0-9a-f:-]{12,17}$/i.test(bleMac)) {
+      try {
+        wifiMac = bleToWifiMac(bleMac);
+      } catch {
+        // device.id may not be a valid MAC format on all platforms
+        wifiMac = "";
+      }
+    }
+
+    const discoveredDevice: DiscoveredDevice = {
+      bleMac,
+      wifiMac,
+      name,
+      // RSSI not directly available from requestDevice
+    };
+
+    return [discoveredDevice];
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.name === "NotFoundError") {
+        // User cancelled the device picker
+        return [];
+      }
+      throw error;
+    }
+    throw new Error("Unknown error during Bluetooth scan");
+  }
+};
+
+/**
+ * Scan for devices with a custom filter.
+ * Advanced function for users who need more control over device selection.
+ *
+ * @param options - Web Bluetooth requestDevice options
+ * @returns Promise resolving to the selected BluetoothDevice
+ */
+const scanWithOptions = async (
+  options: RequestDeviceOptions,
+): Promise<BluetoothDevice> => {
+  if (!isWebBluetoothSupported()) {
+    throw new Error("Web Bluetooth API is not supported in this browser.");
+  }
+
+  return navigator.bluetooth.requestDevice(options);
+};
+
+export {
+  EDILKAMIN_DEVICE_NAME,
+  EDILKAMIN_SERVICE_UUID,
+  isWebBluetoothSupported,
+  scanForDevices,
+  scanWithOptions,
+};
+
+// Re-export DiscoveredDevice for convenience
+export type { DiscoveredDevice } from "./types";

package/src/index.ts

@@ -1,5 +1,6 @@
 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, getSession, signIn } from "./library";
@@ -15,6 +16,7 @@ export {
   DeviceAssociationResponse,
   DeviceInfoRawType,
   DeviceInfoType,
+  DiscoveredDevice,
   EditDeviceAssociationBody,
   StatusType,
   TemperaturesType,

package/src/types.ts

@@ -82,6 +82,20 @@ interface DeviceAssociationResponse {
   serialNumber: string;
 }
 
+/**
+ * Represents a discovered Edilkamin device from Bluetooth scanning.
+ */
+interface DiscoveredDevice {
+  /** BLE MAC address as discovered */
+  bleMac: string;
+  /** WiFi MAC address (BLE MAC - 2), used for API calls */
+  wifiMac: string;
+  /** Device name (typically "EDILKAMIN_EP") */
+  name: string;
+  /** Signal strength in dBm (optional, not all platforms provide this) */
+  rssi?: number;
+}
+
 export type {
   BufferEncodedType,
   CommandsType,
@@ -89,6 +103,7 @@ export type {
   DeviceAssociationResponse,
   DeviceInfoRawType,
   DeviceInfoType,
+  DiscoveredDevice,
   EditDeviceAssociationBody,
   StatusType,
   TemperaturesType,

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "es6",
+    "lib": ["ES6", "DOM"],
     "moduleResolution": "node",
     "outDir": "dist",
     "rootDir": ".",