meross-iot 0.1.0

package/lib/utilities/timer.js

@@ -0,0 +1,310 @@
+'use strict';
+
+const TimerType = require('../model/enums').TimerType;
+
+/**
+ * Timer utility functions.
+ *
+ * Provides helper functions for creating and working with Meross timer configurations.
+ * Timers execute actions at specific times on specified days of the week, following
+ * Meross device timer format conventions.
+ *
+ * @module utilities/timer
+ */
+
+/**
+ * Converts time to minutes since midnight.
+ *
+ * Meross devices store timer times as minutes since midnight (0-1439). This function
+ * normalizes various time formats (HH:MM strings, Date objects, or already-converted
+ * minutes) to this device-compatible format.
+ *
+ * @param {string|Date|number} time - Time in HH:MM format (24-hour), Date object, or minutes since midnight
+ * @returns {number} Minutes since midnight (0-1439)
+ * @throws {Error} If time format is invalid
+ * @example
+ * timeToMinutes('14:30'); // Returns 870
+ * timeToMinutes(new Date(2023, 0, 1, 14, 30)); // Returns 870 (14:30)
+ * timeToMinutes(870); // Returns 870 (already in minutes)
+ */
+function timeToMinutes(time) {
+    if (typeof time === 'number') {
+        if (time >= 0 && time < 1440) {
+            return time;
+        }
+        throw new Error(`Invalid time value: ${time}. Must be 0-1439 minutes`);
+    }
+
+    if (time instanceof Date) {
+        return time.getHours() * 60 + time.getMinutes();
+    }
+
+    if (typeof time === 'string') {
+        const trimmed = time.trim();
+        const timePattern = /^([0-1]?[0-9]|2[0-3]):([0-5][0-9])$/;
+        if (!timePattern.test(trimmed)) {
+            throw new Error(`Invalid time format: "${time}". Expected HH:MM (24-hour format)`);
+        }
+        const [hours, minutes] = trimmed.split(':').map(Number);
+        return hours * 60 + minutes;
+    }
+
+    throw new Error(`Invalid time type: ${typeof time}. Expected string (HH:MM), Date, or number`);
+}
+
+/**
+ * Converts minutes since midnight to HH:MM format string.
+ *
+ * Converts the internal timer format (minutes since midnight) to a human-readable
+ * 24-hour time string for display purposes.
+ *
+ * @param {number} minutes - Minutes since midnight (0-1439)
+ * @returns {string} Time in HH:MM format (24-hour)
+ * @throws {Error} If minutes value is invalid
+ * @example
+ * minutesToTime(870); // Returns "14:30"
+ * minutesToTime(0); // Returns "00:00"
+ */
+function minutesToTime(minutes) {
+    if (typeof minutes !== 'number' || minutes < 0 || minutes >= 1440) {
+        throw new Error(`Invalid minutes value: ${minutes}. Must be 0-1439`);
+    }
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    return `${String(hours).padStart(2, '0')}:${String(mins).padStart(2, '0')}`;
+}
+
+/**
+ * Gets bitmask for special day keywords.
+ *
+ * Converts human-readable day group keywords to their corresponding bitmask values
+ * used by Meross devices. Bit 0-6 represent Monday-Sunday, with bit 7 reserved for
+ * the repeat flag.
+ *
+ * @private
+ * @param {string} keyword - Special keyword ('weekday', 'weekend', 'daily', 'everyday')
+ * @returns {number|null} Bitmask value for the keyword, or null if not a special keyword
+ */
+function getSpecialKeywordBitmask(keyword) {
+    const keywordMap = {
+        weekday: (1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4),
+        weekend: (1 << 5) | (1 << 6),
+        daily: 0x7F,
+        everyday: 0x7F
+    };
+
+    return keywordMap[keyword] !== undefined ? keywordMap[keyword] : null;
+}
+
+/**
+ * Parses a single day value to day number.
+ *
+ * Converts day names (full or abbreviated) or day numbers to a consistent numeric
+ * format where 0=Monday, 1=Tuesday, etc. This matches Meross device day numbering.
+ *
+ * @private
+ * @param {string|number} day - Day value as number (0-6) or string (day name)
+ * @returns {number} Day number (0-6, where 0=Monday)
+ * @throws {Error} If day value is invalid
+ */
+function parseDayToNumber(day) {
+    const dayMap = {
+        monday: 0,
+        tuesday: 1,
+        wednesday: 2,
+        thursday: 3,
+        friday: 4,
+        saturday: 5,
+        sunday: 6,
+        mon: 0,
+        tue: 1,
+        wed: 2,
+        thu: 3,
+        fri: 4,
+        sat: 5,
+        sun: 6
+    };
+
+    if (typeof day === 'number') {
+        if (day < 0 || day > 6) {
+            throw new Error(`Invalid day number: ${day}. Must be 0-6 (0=Monday)`);
+        }
+        return day;
+    }
+
+    if (typeof day === 'string') {
+        const normalized = day.toLowerCase();
+        if (dayMap[normalized] !== undefined) {
+            return dayMap[normalized];
+        }
+        throw new Error(`Invalid day name: "${day}". Use 'monday', 'tuesday', etc.`);
+    }
+
+    throw new Error(`Invalid day type: ${typeof day}. Expected string or number`);
+}
+
+/**
+ * Converts array of weekday names or numbers to week bitmask.
+ *
+ * Meross devices use a bitmask to represent selected days of the week, with bits 0-6
+ * representing Monday-Sunday and bit 7 indicating whether the timer repeats weekly.
+ * This function converts human-readable day lists to this device format.
+ *
+ * @param {Array<string|number>} days - Array of weekday names ('monday', 'tuesday', etc.) or numbers (0-6, where 0=Monday)
+ * @param {boolean} [repeat=true] - Whether to set the repeat bit (bit 7). Default: true
+ * @returns {number} Week bitmask with selected days and repeat bit
+ * @throws {Error} If day names are invalid
+ * @example
+ * daysToWeekMask(['monday', 'wednesday', 'friday']); // Returns bitmask for Mon, Wed, Fri + repeat
+ * daysToWeekMask([0, 2, 4]); // Same as above using numbers
+ * daysToWeekMask(['weekday']); // Returns Monday-Friday
+ * daysToWeekMask(['weekend']); // Returns Saturday-Sunday
+ */
+function daysToWeekMask(days, repeat = true) {
+    if (!Array.isArray(days) || days.length === 0) {
+        throw new Error('Days must be a non-empty array');
+    }
+
+    let bitmask = 0;
+    const specialKeywords = new Set(['weekday', 'weekend', 'daily', 'everyday']);
+
+    for (const day of days) {
+        if (typeof day === 'string' && specialKeywords.has(day.toLowerCase())) {
+            const keywordBitmask = getSpecialKeywordBitmask(day.toLowerCase());
+            if (keywordBitmask !== null) {
+                bitmask |= keywordBitmask;
+            }
+        }
+    }
+
+    for (const day of days) {
+        if (typeof day === 'string' && specialKeywords.has(day.toLowerCase())) {
+            continue;
+        }
+
+        const dayNum = parseDayToNumber(day);
+        bitmask |= (1 << dayNum);
+    }
+
+    if (repeat) {
+        bitmask |= 128;
+    }
+
+    return bitmask;
+}
+
+/**
+ * Normalizes days input to week bitmask with repeat bit handling.
+ *
+ * Consolidates the logic for converting days to week bitmask used by both createTimer
+ * and createTrigger. Handles both numeric bitmask input (preserving or modifying the
+ * repeat bit) and array input (converting day names/numbers to bitmask).
+ *
+ * @param {Array<string|number>|number} days - Days of week (array of names/numbers) or week bitmask (number)
+ * @param {boolean} [repeat=true] - Whether to set the repeat bit (bit 7). Default: true
+ * @returns {number} Week bitmask with selected days and repeat bit set correctly
+ * @example
+ * normalizeWeekBitmask(['monday', 'wednesday', 'friday'], true); // Returns bitmask for Mon, Wed, Fri + repeat
+ * normalizeWeekBitmask(159, false); // Returns 31 (removes repeat bit from existing bitmask)
+ * normalizeWeekBitmask(31, true); // Returns 159 (adds repeat bit to existing bitmask)
+ */
+function normalizeWeekBitmask(days, repeat = true) {
+    if (typeof days === 'number') {
+        let week = days;
+        if (repeat && (week & 128) === 0) {
+            week |= 128;
+        } else if (!repeat && (week & 128) !== 0) {
+            week &= ~128;
+        }
+        return week;
+    }
+
+    return daysToWeekMask(days, repeat);
+}
+
+/**
+ * Generates a unique timer ID.
+ *
+ * Creates a unique identifier for timers by combining the current timestamp (base36)
+ * with random characters. This ensures uniqueness even when multiple timers are created
+ * in rapid succession.
+ *
+ * @returns {string} Unique timer ID
+ */
+function generateTimerId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).substr(2, 8)}`;
+}
+
+/**
+ * Creates a timer configuration object with sensible defaults.
+ *
+ * Builds a complete timer configuration object in the format expected by Meross devices,
+ * converting human-readable inputs (time strings, day names) to device-compatible formats
+ * (minutes since midnight, week bitmask). Applies sensible defaults for optional fields.
+ *
+ * @param {Object} options - Timer configuration options
+ * @param {string} [options.alias] - Timer name/alias
+ * @param {string|Date|number} [options.time='12:00'] - Time in HH:MM format, Date object, or minutes since midnight
+ * @param {Array<string|number>|number} [options.days] - Days of week (array of names/numbers) or week bitmask
+ * @param {boolean} [options.on=true] - Whether to turn device on (true) or off (false)
+ * @param {number} [options.type=TimerType.SINGLE_POINT_WEEKLY_CYCLE] - Timer type
+ * @param {number} [options.channel=0] - Channel number
+ * @param {boolean} [options.enabled=true] - Whether timer is enabled
+ * @param {boolean} [options.repeat=true] - Whether to set repeat bit (for days array input)
+ * @param {string} [options.id] - Timer ID (auto-generated if not provided)
+ * @returns {Object} Timer configuration object
+ * @example
+ * createTimer({
+ *   alias: 'Morning Lights',
+ *   time: '07:00',
+ *   days: ['weekday'],
+ *   on: true
+ * });
+ */
+function createTimer(options = {}) {
+    const {
+        alias = 'My Timer',
+        time = '12:00',
+        days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
+        on = true,
+        type = TimerType.SINGLE_POINT_WEEKLY_CYCLE,
+        channel = 0,
+        enabled = true,
+        repeat = true,
+        id
+    } = options;
+
+    const timeMinutes = timeToMinutes(time);
+    const week = normalizeWeekBitmask(days, repeat);
+
+    const timerx = {
+        id: id || generateTimerId(),
+        channel,
+        type,
+        time: timeMinutes,
+        week,
+        duration: 0,
+        sunOffset: 0,
+        enable: enabled ? 1 : 0,
+        alias,
+        createTime: Math.floor(Date.now() / 1000),
+        extend: {
+            toggle: {
+                onoff: on ? 1 : 0,
+                lmTime: 0
+            }
+        }
+    };
+
+    return timerx;
+}
+
+module.exports = {
+    timeToMinutes,
+    minutesToTime,
+    daysToWeekMask,
+    normalizeWeekBitmask,
+    generateTimerId,
+    createTimer
+};
+

package/lib/utilities/trigger.js

@@ -0,0 +1,286 @@
+'use strict';
+
+const TriggerType = require('../model/enums').TriggerType;
+const { normalizeWeekBitmask, generateTimerId } = require('./timer');
+
+/**
+ * Trigger utility functions.
+ *
+ * Provides helper functions for creating and working with Meross trigger configurations.
+ * Triggers are countdown timers that execute an action after a specified duration, unlike
+ * timers which execute at a specific time. Triggers count down from when they're activated.
+ *
+ * @module utilities/trigger
+ */
+
+/**
+ * Parses numeric duration value.
+ *
+ * Validates that numeric duration values are non-negative, as negative durations
+ * are not meaningful for countdown timers.
+ *
+ * @private
+ * @param {number} value - Numeric duration in seconds
+ * @returns {number} Duration in seconds
+ * @throws {Error} If duration is negative
+ */
+function parseNumericDuration(value) {
+    if (value < 0) {
+        throw new Error(`Invalid duration: ${value}. Duration must be non-negative`);
+    }
+    return value;
+}
+
+/**
+ * Parses duration string with unit suffix.
+ *
+ * Converts human-readable duration strings (e.g., "30m", "2h", "45s") to seconds.
+ * Supports seconds (s), minutes (m), and hours (h) units. Returns null if the format
+ * doesn't match, allowing other parsers to attempt conversion.
+ *
+ * @private
+ * @param {string} str - Duration string with unit suffix
+ * @returns {number|null} Duration in seconds, or null if format doesn't match
+ * @throws {Error} If format is invalid
+ */
+function parseUnitSuffixDuration(str) {
+    const timeUnitMatch = str.match(/^(\d+)([smh])$/i);
+    if (!timeUnitMatch) {
+        return null;
+    }
+
+    const value = parseInt(timeUnitMatch[1], 10);
+    const unit = timeUnitMatch[2].toLowerCase();
+
+    if (unit === 's') {
+        return value;
+    } else if (unit === 'm') {
+        return value * 60;
+    } else if (unit === 'h') {
+        return value * 3600;
+    }
+
+    return null;
+}
+
+/**
+ * Validates time components for MM:SS format.
+ *
+ * Ensures minutes and seconds values are within valid ranges (minutes >= 0,
+ * seconds 0-59) before converting to total seconds.
+ *
+ * @private
+ * @param {number} minutes - Minutes value
+ * @param {number} seconds - Seconds value
+ * @param {string} originalDuration - Original duration string for error messages
+ * @throws {Error} If validation fails
+ */
+function validateMMSS(minutes, seconds, originalDuration) {
+    if (isNaN(minutes) || isNaN(seconds) || minutes < 0 || seconds < 0 || seconds >= 60) {
+        throw new Error(`Invalid time format: "${originalDuration}". Expected MM:SS`);
+    }
+}
+
+/**
+ * Validates time components for HH:MM:SS format.
+ *
+ * Ensures hours, minutes, and seconds values are within valid ranges (hours >= 0,
+ * minutes 0-59, seconds 0-59) before converting to total seconds.
+ *
+ * @private
+ * @param {number} hours - Hours value
+ * @param {number} minutes - Minutes value
+ * @param {number} seconds - Seconds value
+ * @param {string} originalDuration - Original duration string for error messages
+ * @throws {Error} If validation fails
+ */
+function validateHHMMSS(hours, minutes, seconds, originalDuration) {
+    if (isNaN(hours) || isNaN(minutes) || isNaN(seconds) ||
+        hours < 0 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60) {
+        throw new Error(`Invalid time format: "${originalDuration}". Expected HH:MM:SS`);
+    }
+}
+
+/**
+ * Parses time string in "HH:MM:SS" or "MM:SS" format.
+ *
+ * Converts time-formatted duration strings to total seconds. Supports both full
+ * hour:minute:second format and abbreviated minute:second format. Returns null if
+ * the format doesn't match, allowing other parsers to attempt conversion.
+ *
+ * @private
+ * @param {string} str - Time string in "HH:MM:SS" or "MM:SS" format
+ * @param {string} originalDuration - Original duration string for error messages
+ * @returns {number|null} Duration in seconds, or null if format doesn't match
+ * @throws {Error} If format is invalid
+ */
+function parseTimeStringDuration(str, originalDuration) {
+    const timePattern = /^(?:(\d+):)?(\d+):(\d+)$/;
+    if (!timePattern.test(str)) {
+        return null;
+    }
+
+    const parts = str.split(':');
+    if (parts.length === 2) {
+        const minutes = parseInt(parts[0], 10);
+        const seconds = parseInt(parts[1], 10);
+        validateMMSS(minutes, seconds, originalDuration);
+        return minutes * 60 + seconds;
+    } else if (parts.length === 3) {
+        const hours = parseInt(parts[0], 10);
+        const minutes = parseInt(parts[1], 10);
+        const seconds = parseInt(parts[2], 10);
+        validateHHMMSS(hours, minutes, seconds, originalDuration);
+        return hours * 3600 + minutes * 60 + seconds;
+    }
+
+    return null;
+}
+
+/**
+ * Converts duration to seconds.
+ *
+ * Normalizes various duration formats to a consistent seconds value. Supports numeric
+ * seconds, unit-suffixed strings (e.g., "30m", "2h"), and time-formatted strings
+ * (e.g., "HH:MM:SS", "MM:SS"). This allows users to specify durations in the most
+ * convenient format for their use case.
+ *
+ * @param {string|number} duration - Duration as seconds (number), "HH:MM:SS" string, "30m" (minutes), "2h" (hours), etc.
+ * @returns {number} Duration in seconds
+ * @throws {Error} If duration format is invalid
+ * @example
+ * durationToSeconds(600); // Returns 600
+ * durationToSeconds('10m'); // Returns 600 (10 minutes)
+ * durationToSeconds('1h'); // Returns 3600 (1 hour)
+ * durationToSeconds('1:30:00'); // Returns 5400 (1 hour 30 minutes)
+ * durationToSeconds('30:00'); // Returns 1800 (30 minutes)
+ */
+function durationToSeconds(duration) {
+    if (typeof duration === 'number') {
+        return parseNumericDuration(duration);
+    }
+
+    if (typeof duration === 'string') {
+        const trimmed = duration.trim();
+
+        const unitSuffixResult = parseUnitSuffixDuration(trimmed);
+        if (unitSuffixResult !== null) {
+            return unitSuffixResult;
+        }
+
+        const timeStringResult = parseTimeStringDuration(trimmed, duration);
+        if (timeStringResult !== null) {
+            return timeStringResult;
+        }
+
+        throw new Error(`Invalid duration format: "${duration}". Expected seconds (number), "Xm"/"Xh", or "HH:MM:SS"/"MM:SS" format`);
+    }
+
+    throw new Error(`Invalid duration type: ${typeof duration}. Expected string or number`);
+}
+
+/**
+ * Converts seconds to human-readable duration string.
+ *
+ * Formats duration values for display purposes, using the most appropriate units
+ * (hours, minutes, seconds) and omitting zero components. Only shows seconds when
+ * the duration is less than an hour to keep output concise.
+ *
+ * @param {number} seconds - Duration in seconds
+ * @returns {string} Human-readable duration (e.g., "1h 30m", "45m", "30s")
+ * @throws {Error} If seconds value is invalid
+ * @example
+ * secondsToDuration(5400); // Returns "1h 30m"
+ * secondsToDuration(600); // Returns "10m"
+ * secondsToDuration(30); // Returns "30s"
+ */
+function secondsToDuration(seconds) {
+    if (typeof seconds !== 'number' || seconds < 0) {
+        throw new Error(`Invalid seconds value: ${seconds}. Must be non-negative number`);
+    }
+
+    if (seconds === 0) {
+        return '0s';
+    }
+
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = seconds % 60;
+
+    const parts = [];
+    if (hours > 0) {
+        parts.push(`${hours}h`);
+    }
+    if (minutes > 0) {
+        parts.push(`${minutes}m`);
+    }
+    if (secs > 0 && hours === 0) {
+        parts.push(`${secs}s`);
+    }
+
+    return parts.join(' ') || '0s';
+}
+
+/**
+ * Creates a trigger configuration object with sensible defaults.
+ *
+ * Builds a complete trigger configuration object in the format expected by Meross devices,
+ * converting human-readable inputs (duration strings, day names) to device-compatible formats
+ * (seconds, week bitmask). Triggers are countdown timers that execute an action after a
+ * specified duration, unlike timers which execute at specific times.
+ *
+ * @param {Object} options - Trigger configuration options
+ * @param {string} [options.alias] - Trigger name/alias
+ * @param {string|number} [options.duration=600] - Duration as seconds (number), "30m", "1h", or "HH:MM:SS" format. Default: 600 (10 minutes)
+ * @param {Array<string|number>|number} [options.days] - Days of week (array of names/numbers) or week bitmask. Default: all days
+ * @param {number} [options.type=TriggerType.SINGLE_POINT_WEEKLY_CYCLE] - Trigger type
+ * @param {number} [options.channel=0] - Channel number
+ * @param {boolean} [options.enabled=true] - Whether trigger is enabled
+ * @param {boolean} [options.repeat=true] - Whether to set repeat bit (for days array input)
+ * @param {string} [options.id] - Trigger ID (auto-generated if not provided)
+ * @returns {Object} Trigger configuration object
+ * @example
+ * createTrigger({
+ *   alias: 'Auto-off after 30 minutes',
+ *   duration: '30m',
+ *   days: ['weekday'],
+ *   channel: 0
+ * });
+ */
+function createTrigger(options = {}) {
+    const {
+        alias = 'My Trigger',
+        duration = 600, // Default: 10 minutes
+        days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
+        type = TriggerType.SINGLE_POINT_WEEKLY_CYCLE,
+        channel = 0,
+        enabled = true,
+        repeat = true,
+        id
+    } = options;
+
+    const durationSeconds = durationToSeconds(duration);
+    const week = normalizeWeekBitmask(days, repeat);
+
+    const triggerx = {
+        id: id || generateTimerId(),
+        channel,
+        type,
+        enable: enabled ? 1 : 0,
+        alias,
+        createTime: Math.floor(Date.now() / 1000),
+        rule: {
+            duration: durationSeconds,
+            week
+        }
+    };
+
+    return triggerx;
+}
+
+module.exports = {
+    durationToSeconds,
+    secondsToDuration,
+    createTrigger
+};
+

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "meross-iot",
+  "version": "0.1.0",
+  "description": "Control Meross cloud devices using nodejs",
+  "author": "Abe Haverkamp",
+  "contributors": [
+    "Ingo Fischer <iobroker@fischer-ka.de>"
+  ],
+  "homepage": "https://github.com/Doekse/merossiot#readme",
+  "license": "MIT",
+  "keywords": [
+    "meross",
+    "iot",
+    "smart-home",
+    "home-automation",
+    "mqtt",
+    "wlan",
+    "smart-plug",
+    "smart-switch",
+    "smart-light",
+    "thermostat",
+    "garage-door",
+    "roller-shutter",
+    "homey",
+    "nodejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Doekse/merossiot"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mqtt": "^5.14.1",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@alcalzone/release-script": "^3.8.0",
+    "@alcalzone/release-script-plugin-license": "^3.7.0",
+    "eslint": "^9.39.1"
+  },
+  "bugs": {
+    "url": "https://github.com/Doekse/merossiot/issues"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "release": "release-script",
+    "prepublishOnly": "node -e \"require('./index.js')\" && echo 'Package validation passed'",
+    "publish:npm": "npm publish --access public",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "release-script": {
+    "changelog": {
+      "file": "CHANGELOG.md",
+      "template": "keepachangelog"
+    },
+    "npm": {
+      "publish": false
+    }
+  }
+}
+