homey-lib 2.45.2 → 2.45.4

package/lib/App/index.js

@@ -30,6 +30,8 @@ const {
   dirname,
 } = require('../../helpers');
 
+/** @typedef {import('../../assets/app/schema').App} AppManifest */
+
 const VALIDATION_LEVELS = [
   'debug',
   'publish',
@@ -76,6 +78,9 @@ class App {
   static REQUIRED_PYTHON_PLATFORMS = ['arm64', 'amd64']
   static SUPPORTED_PYTHON_VERSIONS = ['3.13', '3.14']
 
+  /**
+   * @param {string} path
+   */
   constructor(path) {
     this._path = path;
 
@@ -84,11 +89,19 @@ class App {
     }
   }
 
+  /**
+   * @param {...unknown} args
+   * @returns {void}
+   */
   debug(...args) {
     if (!this._debug) return;
     console.log('[dbg]', ...args);
   }
 
+  /**
+   * @param {{ level?: 'debug' | 'publish' | 'verified', debug?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async validate({
     level = 'debug',
     debug = false,
@@ -104,8 +117,9 @@ class App {
     const levelPublish = (level === 'publish' || level === 'verified');
     const levelVerified = (level === 'verified');
 
-    let appJson = await readFileAsync(join(this._path, 'app.json'));
-    appJson = JSON.parse(appJson);
+    const appJsonBuffer = await readFileAsync(join(this._path, 'app.json'));
+    /** @type {AppManifest} */
+    const appJson = JSON.parse(appJsonBuffer);
 
     const schema = App.getJSONSchema();
 
@@ -216,9 +230,8 @@ class App {
     // validate that Python apps target compatibility of at least >=13.0.0
     if (appJson.runtime === 'python') {
       const minVersion = semver.minVersion(appJson.compatibility);
-      // tmp set to 12.11.1
-      if (!semver.gte(minVersion, '12.11.1')) {
-        throw new Error(`Invalid compatibility (${appJson.compatibility}), Python apps must have a compatibility of at least >=12.11.1`);
+      if (!semver.gte(minVersion, '13.0.0')) {
+        throw new Error(`Invalid compatibility (${appJson.compatibility}), Python apps must have a compatibility of at least >=13.0.0`);
       }
     }
 
@@ -371,9 +384,32 @@ class App {
         // validate `appJson.drivers[].capabilitiesOptions`
         if (driver.capabilitiesOptions) {
           for (const [capabilityId, capabilityOptions] of Object.entries(driver.capabilitiesOptions)) {
-            // Enforce fixed values for target_power_mode — always use the canonical values from the capability definition
+            // Merge canonical + extra values for target_power_mode - canonical always present, extras appended
             if (Capability.isInstanceOfId(capabilityId, 'target_power_mode')) {
-              capabilityOptions.values = Capability.getCapability('target_power_mode').values;
+              const canonicalValues = Capability.getCapability('target_power_mode').values;
+              const providedValues = Array.isArray(capabilityOptions.values) ? capabilityOptions.values : [];
+
+              const seenIds = new Set(canonicalValues.map(canonical => canonical.id));
+              const extraValues = [];
+
+              for (const value of providedValues) {
+                if (!value || typeof value !== 'object' || typeof value.id !== 'string') continue;
+                if (seenIds.has(value.id)) continue;
+                seenIds.add(value.id);
+                extraValues.push(value);
+              }
+
+              const RESERVED_PREFIXES = ['homey_', 'device_'];
+              const reservedValues = extraValues.filter(value =>
+                RESERVED_PREFIXES.some(prefix => value.id.startsWith(prefix))
+              );
+
+              if (reservedValues.length) {
+                const ids = reservedValues.map(value => value.id).join(', ');
+                throw new Error(`drivers.${driver.id}.capabilitiesOptions.${capabilityId} custom values cannot use reserved prefixes "homey_" or "device_": ${ids}`);
+              }
+
+              capabilityOptions.values = [...canonicalValues, ...extraValues];
             }
 
             // validate target_power exclude range must include 0
@@ -764,6 +800,10 @@ class App {
     this.debug('Validated successfully');
   }
 
+  /**
+   * @param {AppManifest} appJson
+   * @returns {void}
+   */
   static validatePythonVersion(appJson) {
     // validate that Python apps specify a runtime version
     if (appJson.runtime === 'python' && !App.SUPPORTED_PYTHON_VERSIONS.includes(appJson.pythonVersion)) {
@@ -771,6 +811,11 @@ class App {
     }
   }
 
+  /**
+   * @param {Record<string, unknown>} setting
+   * @param {{ id: string }} driver
+   * @returns {void}
+   */
   _checkPrivateSettingPrefixUse(setting, driver) {
     if (
       setting.type &&
@@ -795,6 +840,11 @@ class App {
     }
   }
 
+  /**
+   * @param {Record<string, unknown> | null | undefined} driver
+   * @param {Record<string, unknown> | null | undefined} setting
+   * @returns {void}
+   */
   _checkZwaveForSetting(driver, setting) {
     if (!driver || !setting || !setting.zwave) return;
     if (typeof setting.zwave.index !== 'number' || typeof setting.zwave.size !== 'number') throw new Error(`Missing property in "zwave" at ${driver.id}, ${setting.id}`);
@@ -818,6 +868,10 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<string[]>}
+   */
   async _getDirectoryContents(filepath) {
     await this._fileExistsCaseSensitive(filepath);
 
@@ -830,6 +884,10 @@ class App {
     });
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<void>}
+   */
   async _ensureFileExistsCaseSensitive(filepath) {
     const exists = await this._fileExistsCaseSensitive(filepath);
     if (exists !== true) {
@@ -837,6 +895,10 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<boolean>}
+   */
   async _fileExistsCaseSensitive(filepath) {
     filepath = join(this._path, filepath);
     const dir = dirname(filepath);
@@ -852,6 +914,12 @@ class App {
     }
   }
 
+  /**
+   * @param {{ small: string, large: string }} imagesObj
+   * @param {'app' | 'driver'} type
+   * @param {string} [errorPath]
+   * @returns {Promise<void>}
+   */
   async _validateImages(imagesObj, type, errorPath) {
     const sizes = ['small', 'large'];
     for (let i = 0; i < sizes.length; i++) {
@@ -881,6 +949,9 @@ class App {
     }
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async _validateModules() {
     const nodeModulesPath = join(this._path, 'node_modules');
 
@@ -904,6 +975,13 @@ class App {
     }
   }
 
+  /**
+   * @param {Record<string, unknown>} card
+   * @param {string} errorPath
+   * @param {AppManifest} appJson
+   * @param {{ levelPublish: boolean, levelVerified: boolean }} options
+   * @returns {void}
+   */
   _validateFlowCard(card, errorPath, appJson, { levelPublish, levelVerified }) {
     if (Array.isArray(card.tokens)) {
       for (const token of card.tokens) {
@@ -983,6 +1061,12 @@ class App {
     }
   }
 
+  /**
+   * @param {string} titleFormatted
+   * @param {{ name: string }[]} args
+   * @param {string} errorPath
+   * @returns {void}
+   */
   static _checkTitleFormatted(titleFormatted, args, errorPath) {
     const argsPresent = args.reduce((obj, arg) => {
       obj[arg.name] = false;
@@ -1017,6 +1101,11 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @param {number} numBytes
+   * @returns {Promise<Buffer>}
+   */
   async _readBytes(filepath, numBytes) {
     filepath = join(this._path, filepath);
 
@@ -1027,6 +1116,10 @@ class App {
     return buffer;
   }
 
+  /**
+   * @param {string} appId
+   * @returns {boolean}
+   */
   static isValidId(appId) {
     if (typeof appId !== 'string') return false;
     if (appId.length < 1) return false;
@@ -1035,16 +1128,26 @@ class App {
     return true;
   }
 
+  /**
+   * @param {string} color
+   * @returns {boolean}
+   */
   static isValidBrandColor(color) {
     return tinycolor(color).getBrightness() <= 184; // empirically determined by many colorpicker samples
   }
 
+  /**
+   * @returns {Record<string, unknown>}
+   */
   static getJSONSchema() {
     // eslint-disable-next-line global-require
     const schema = require('../../assets/app/schema.json');
     return JSON.parse(JSON.stringify(schema));
   }
 
+  /**
+   * @returns {Record<string, Record<string, unknown>>}
+   */
   static getPermissions() {
     // eslint-disable-next-line global-require
     const permissions = require('../../assets/app/permissions.json');
@@ -1059,15 +1162,25 @@ class App {
     return permissions;
   }
 
+  /**
+   * @returns {string[]}
+   */
   static getCategories() {
     return ['lights', 'video', 'music', 'appliances', 'security', 'climate', 'tools', 'internet', 'localization', 'energy'];
   }
 
+  /**
+   * @returns {string[]}
+   */
   static getLocales() {
     // eslint-disable-next-line max-len
     return ['ab', 'aa', 'af', 'ak', 'sq', 'am', 'ar', 'an', 'hy', 'as', 'av', 'ae', 'ay', 'az', 'bm', 'ba', 'eu', 'be', 'bn', 'bh', 'bi', 'bs', 'br', 'bg', 'my', 'ca', 'ch', 'ce', 'ny', 'zh', 'cv', 'kw', 'co', 'cr', 'hr', 'cs', 'da', 'dv', 'nl', 'dz', 'en', 'eo', 'et', 'ee', 'fo', 'fj', 'fi', 'fr', 'ff', 'gl', 'ka', 'de', 'el', 'gn', 'gu', 'ht', 'ha', 'he', 'hz', 'hi', 'ho', 'hu', 'ia', 'id', 'ie', 'ga', 'ig', 'ik', 'io', 'is', 'it', 'iu', 'ja', 'jv', 'kl', 'kn', 'kr', 'ks', 'kk', 'km', 'ki', 'rw', 'ky', 'kv', 'kg', 'ko', 'ku', 'kj', 'la', 'lb', 'lg', 'li', 'ln', 'lo', 'lt', 'lu', 'lv', 'gv', 'mk', 'mg', 'ms', 'ml', 'mt', 'mi', 'mr', 'mh', 'mn', 'na', 'nv', 'nd', 'ne', 'ng', 'nb', 'nn', 'no', 'ii', 'nr', 'oc', 'oj', 'cu', 'om', 'or', 'os', 'pa', 'pi', 'fa', 'pl', 'ps', 'pt', 'qu', 'rm', 'rn', 'ro', 'ru', 'sa', 'sc', 'sd', 'se', 'sm', 'sg', 'sr', 'gd', 'sn', 'si', 'sk', 'sl', 'so', 'st', 'es', 'su', 'sw', 'ss', 'sv', 'ta', 'te', 'tg', 'th', 'ti', 'bo', 'tk', 'tl', 'tn', 'to', 'tr', 'ts', 'tt', 'tw', 'ty', 'ug', 'uk', 'ur', 'uz', 've', 'vi', 'vo', 'wa', 'cy', 'wo', 'fy', 'xh', 'yi', 'yo', 'za', 'zu'];
   }
 
+  /**
+   * @param {string} appId
+   * @returns {string}
+   */
   static getBrandColor(appId) {
     const appIdHex = Buffer.from(appId).toString('hex');
     let brandColor;
@@ -1091,6 +1204,11 @@ class App {
     return brandColor;
   }
 
+  /**
+   * @param {Array<Record<string, unknown>> | undefined} errors
+   * @param {AppManifest} appJson
+   * @returns {string | null}
+   */
   static errorsText(errors, appJson) {
     if (Array.isArray(errors) === false) return null;
 

package/lib/Capability/index.js

@@ -4,19 +4,33 @@
 
 const Ajv = require('ajv');
 
+/** @typedef {import('../../assets/capability/schema').Capability} CapabilityDefinition */
+
+/** @type {Record<string, CapabilityDefinition> | undefined} */
 let capabilitiesCache;
 
 class Capability {
 
+  /**
+  * @param {CapabilityDefinition} capability
+   */
   constructor(capability) {
     this._capability = capability;
   }
 
+  /**
+   * @param {...unknown} args
+   * @returns {void}
+   */
   debug(...args) {
     if (!this._debug) return;
     console.log('[dbg]', ...args);
   }
 
+  /**
+   * @param {{ debug?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async validate({
     debug = false,
   } = {}) {
@@ -33,11 +47,17 @@ class Capability {
     this.debug('Validated successfully');
   }
 
+  /**
+   * @returns {Record<string, unknown>}
+   */
   static getJSONSchema() {
     // eslint-disable-next-line global-require
     return require('../../assets/capability/schema.json');
   }
 
+  /**
+   * @returns {Record<string, CapabilityDefinition>}
+   */
   static getCapabilities() {
     if (capabilitiesCache) return capabilitiesCache;
 
@@ -52,6 +72,10 @@ class Capability {
     return capabilitiesCache;
   }
 
+  /**
+   * @param {string} id
+   * @returns {CapabilityDefinition}
+   */
   static getCapability(id) {
     const capabilities = Capability.getCapabilities();
     const capability = capabilities[id];
@@ -61,11 +85,20 @@ class Capability {
     return capability;
   }
 
+  /**
+   * @param {string} id
+   * @returns {boolean}
+   */
   static hasCapability(id) {
     const capabilities = this.getCapabilities();
     return !!capabilities[id];
   }
 
+  /**
+   * @param {string} capabilityId
+   * @param {CapabilityDefinition} capability
+   * @returns {CapabilityDefinition}
+   */
   static _composeCapability(capabilityId, capability) {
     if (capability.flow) console.warn(`Warning: using \`capability.flow\` (${capabilityId}), expected a \`capability.$flow\``);
     if (capability.$flow) {
@@ -109,12 +142,21 @@ class Capability {
     return capability;
   }
 
+  /**
+   * @param {string} capabilityIdToCheck
+   * @param {string} capabilityId
+   * @returns {boolean}
+   */
   static isInstanceOfId(capabilityIdToCheck, capabilityId) {
     return (
       capabilityId === capabilityIdToCheck || capabilityIdToCheck.startsWith(`${capabilityId}.`)
     );
   }
 
+  /**
+   * @param {string} capabilityId
+   * @returns {string}
+   */
   static getBaseId(capabilityId) {
     const parts = capabilityId.split('.');
     return parts[0];

package/lib/Device/index.js

@@ -6,6 +6,9 @@ let classesCache;
 
 class Device {
 
+  /**
+   * @returns {Record<string, Record<string, unknown>>}
+   */
   static getClasses() {
     if (classesCache) return classesCache;
 
@@ -19,6 +22,10 @@ class Device {
     return classesCache;
   }
 
+  /**
+   * @param {string} id
+   * @returns {Record<string, unknown>}
+   */
   static getClass(id) {
     const deviceClasses = Device.getClasses();
     const deviceClass = deviceClasses[id];
@@ -29,6 +36,9 @@ class Device {
   }
 
   // legacy
+  /**
+   * @returns {ReturnType<typeof Capability.getCapabilities>}
+   */
   static getCapabilities() {
     return Capability.getCapabilities();
   }

package/lib/Energy/index.js

@@ -2,11 +2,17 @@
 
 class Energy {
 
+  /**
+   * @returns {Record<string, Record<string, unknown>>}
+   */
   static getCurrencies() {
     // eslint-disable-next-line global-require
     return require('../../assets/energy/currencies.json');
   }
 
+  /**
+   * @returns {string[]}
+   */
   static getBatteries() {
     return [
       'LS14250',

package/lib/Media/index.js

@@ -2,6 +2,9 @@
 
 class Media {
 
+  /**
+   * @returns {Record<string, Record<string, unknown>>}
+   */
   static getCodecs() {
     // eslint-disable-next-line global-require
     return require('../../assets/media/codecs.json');

package/lib/Signal/index.js

@@ -11,8 +11,16 @@ const {
   prontoValidator,
 } = require('./validators');
 
+/**
+ * @typedef {'433' | '868' | 'ir'} SignalFrequency
+ */
+
 class Signal {
 
+  /**
+   * @param {Record<string, unknown>} signal
+   * @param {{ frequency?: SignalFrequency }} [options]
+   */
   constructor(signal, { frequency = undefined } = {}) {
     this._signal = signal;
     this._frequency = frequency;
@@ -20,6 +28,10 @@ class Signal {
     this._check = this._check.bind(this);
   }
 
+  /**
+   * @param {...unknown} args
+   * @returns {void}
+   */
   debug(...args) {
     if (!this._debug) return;
 
@@ -27,12 +39,21 @@ class Signal {
     console.log('[dbg]', ...args);
   }
 
+  /**
+   * @param {string} message
+   * @param {boolean} result
+   * @returns {void}
+   */
   _check(message, result) {
     if (result !== true) {
       throw new Error(message);
     }
   }
 
+  /**
+   * @param {{ debug?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async validate({
     debug = false,
   } = {}) {
@@ -65,6 +86,10 @@ class Signal {
     this.debug('Validated successfully');
   }
 
+  /**
+   * @param {Record<string, (value: unknown, signal: Record<string, unknown>) => { result: boolean, msg: string }>} validatorEngine
+   * @returns {void}
+   */
   _validateWithEngine(validatorEngine) {
     return validate(validatorEngine, this._check, this._signal);
   }

package/lib/Signal/validators.js

@@ -2,7 +2,21 @@
 
 'use strict';
 
+/**
+ * @typedef {Record<string, unknown>} SignalDefinition
+ * @typedef {{ result: boolean, msg: string }} ValidationResult
+ * @typedef {(value: unknown, signal: SignalDefinition) => ValidationResult} Validator
+ * @typedef {Record<string, Validator>} ValidatorEngine
+ * @typedef {(message: string, result: boolean) => void} CheckFn
+ */
+
 /* static functions */
+/**
+ * @param {ValidatorEngine} validator
+ * @param {CheckFn} check
+ * @param {SignalDefinition} signal
+ * @returns {void}
+ */
 function validate(validator, check, signal) {
   for (const propName in signal) {
     const property = signal[propName];
@@ -70,6 +84,7 @@ function _validateGenericData(data, signal) {
   return res;
 }
 
+/** @type {ValidatorEngine} */
 const genericValidator = {
   words(words, signal) {
     const res = { result: true, msg: 'invalid_words' };
@@ -166,6 +181,7 @@ const rfBounds = {
   repetitions: { min: 1, max: 255 },
 };
 
+/** @type {ValidatorEngine} */
 const rfValidator = {
 
   words(words, signal) {
@@ -222,6 +238,7 @@ const modulationBounds = {
   channelDeviation: { min: 5000, max: 50000 },
 };
 
+/** @type {ValidatorEngine} */
 const modulationValidator = {
   modulation(modulation, signal) {
     // replace by default modulation props in homey-microcontroller?
@@ -256,6 +273,7 @@ const modulationValidator = {
   },
 };
 
+/** @type {ValidatorEngine} */
 const prontoValidator = {
   cmds(cmds, signal) {
     const res = !Object.keys(cmds).some(cmd => {
@@ -279,6 +297,7 @@ const rf433Bounds = {
   carrier: { min: 433000000, max: 433990000 },
 };
 
+/** @type {ValidatorEngine} */
 const rf433Validator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, 433000000, 433990000);
@@ -290,6 +309,7 @@ const rf868Bounds = {
   carrier: { min: 868000000, max: 868900000 },
 };
 
+/** @type {ValidatorEngine} */
 const rf868Validator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, rf868Bounds.carrier.min, rf868Bounds.carrier.max);
@@ -302,6 +322,7 @@ const irBounds = {
   dutyCycle: { min: 30, max: 70 },
 };
 
+/** @type {ValidatorEngine} */
 const irValidator = {
   carrier(carrier, signal) {
     const res = _valid_bounds(carrier, irBounds.carrier.min, irBounds.carrier.max);

package/lib/Util/index.js

@@ -2,10 +2,19 @@
 
 class Util {
 
+  /**
+   * @param {string} modelId
+   * @returns {string[]}
+   */
   static getPlatformLocalFeatures(modelId) {
     return Util._platformLocalFeatures[modelId] || [];
   }
 
+  /**
+   * @param {string} modelId
+   * @param {string[]} wantedFeatures
+   * @returns {string[]}
+   */
   static getMissingPlatformLocalFeatures(modelId, wantedFeatures) {
     const features = Util.getPlatformLocalFeatures(modelId);
     return wantedFeatures.filter(feature => !features.includes(feature));
@@ -18,6 +27,7 @@ Util.FEATURE_LED_RING = 'ledring';
 Util.FEATURE_NFC = 'nfc';
 Util.FEATURE_MATTER = 'matter';
 Util.FEATURE_CAMERA_STREAMING = 'camera-streaming';
+/** @type {Record<string, string[]>} */
 Util._platformLocalFeatures = {
   homey1s: [Util.FEATURE_SPEAKER, Util.FEATURE_LED_RING, Util.FEATURE_NFC],
   homey1d: [Util.FEATURE_SPEAKER, Util.FEATURE_LED_RING, Util.FEATURE_NFC],

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "homey-lib",
-  "version": "2.45.2",
+  "version": "2.45.4",
   "description": "Shared Library for Homey",
+  "types": "types/index.d.ts",
   "main": "index.js",
   "scripts": {
-    "build": "npm ci; npm run pack",
+    "build": "npm ci; npm run types:generate; npm run schema:generate; npm run schema:copy; npm run pack",
     "pack": "webpack",
     "lint": "eslint .",
     "test": "mocha --parallel",
     "locales:apply": "node scripts/apply-locale-files.js",
-    "locales:generate": "node scripts/generate-locale-files.js"
+    "locales:generate": "node scripts/generate-locale-files.js",
+    "types:generate": "tsc --project tsconfig.types.json",
+    "schema:generate": "npm run capability-schema:generate && npm run app-schema:generate",
+    "schema:copy": "mkdir -p types/assets/app types/assets/capability && cp assets/app/schema.d.ts types/assets/app/schema.d.ts && cp assets/capability/schema.d.ts types/assets/capability/schema.d.ts",
+    "capability-schema:generate": "json2ts -i assets/capability/schema.json -o assets/capability/schema.d.ts --unknownAny",
+    "app-schema:generate": "json2ts -i assets/app/schema.json -o assets/app/schema.d.ts --unknownAny"
   },
   "engines": {
     "node": ">=12.13.0"
@@ -34,10 +40,12 @@
   "devDependencies": {
     "eslint": "^7.31.0",
     "eslint-config-athom": "^2.1.1",
+    "json-schema-to-typescript": "^15.0.4",
     "mocha": "^9.1.3",
     "mock-fs": "^5.1.2",
     "object-path": "^0.11.8",
     "set-value": "^4.1.0",
+    "typescript": "^5.9.3",
     "webpack": "^5.98.0",
     "webpack-cli": "^5.1.4"
   }

package/tsconfig.types.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true,
+    "outDir": "./types",
+    "module": "commonjs",
+    "target": "ES2020",
+    "strict": false
+  },
+  "include": ["index.js", "lib/**/*.js"],
+  "exclude": ["test/**", "node_modules/**"]
+}