homey-lib 2.45.3 → 2.46.0

package/assets/capability/schema.d.ts

@@ -0,0 +1,53 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export type Capability = {
+  [k: string]: unknown;
+} & {
+  title: I18NObject;
+  desc?: I18NObject;
+  type: "boolean" | "number" | "string" | "enum";
+  getable?: boolean;
+  setable?: boolean;
+  icon?: string;
+  insights?: boolean;
+  insightsTitleTrue?: I18NObject;
+  insightsTitleFalse?: I18NObject;
+  chartType?: "line" | "area" | "stepLine" | "column" | "spline" | "splineArea" | "scatter";
+  decimals?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  units?: I18NObject;
+  values?: {
+    id: string;
+    title: I18NObject;
+    [k: string]: unknown;
+  }[];
+  uiComponent?:
+    | ("thermostat" | "media" | "toggle" | "slider" | "ternary" | "button" | "color" | "picker" | "sensor" | "battery")
+    | null;
+  [k: string]: unknown;
+} & (
+    | {
+        type?: "enum";
+        [k: string]: unknown;
+      }
+    | {
+        type?: "boolean" | "number" | "string";
+        [k: string]: unknown;
+      }
+  );
+export type I18NObject =
+  | string
+  | {
+      /**
+       * This interface was referenced by `undefined`'s JSON-Schema definition
+       * via the `patternProperty` "^.*$".
+       */
+      [k: string]: string;
+    };

package/helpers/index.js

@@ -9,21 +9,42 @@ try {
   const imageSize = require('image-size');
 
   if (fs && util && util.promisify) {
+    /** @type {typeof fs.open.__promisify__} */
     module.exports.openAsync = util.promisify(fs.open);
+    /** @type {typeof fs.close.__promisify__} */
     module.exports.closeAsync = util.promisify(fs.close);
+    /** @type {typeof fs.read.__promisify__} */
     module.exports.readAsync = util.promisify(fs.read);
+    /** @type {typeof fs.stat.__promisify__} */
     module.exports.statAsync = util.promisify(fs.stat);
+    /** @type {typeof fs.readFile.__promisify__} */
     module.exports.readFileAsync = util.promisify(fs.readFile);
+    /** @type {typeof fs.readdir.__promisify__} */
     module.exports.readDirAsync = util.promisify(fs.readdir);
+    /** @type {typeof fs.lstat.__promisify__} */
     module.exports.lstatAsync = util.promisify(fs.lstat);
     module.exports.imageSizeAsync = util.promisify(imageSize);
   }
 
   if (path) {
+    /** @type {typeof path.join} */
     module.exports.join = path.join;
+    /** @type {typeof path.extname} */
     module.exports.extname = path.extname;
+    /** @type {typeof path.basename} */
     module.exports.basename = path.basename;
+    /** @type {typeof path.dirname} */
     module.exports.dirname = path.dirname;
   }
 } catch (err) {
 }
+
+function toArray(value) {
+  if (value) {
+    return Array.isArray(value) ? value : [value];
+  }
+
+  return [];
+}
+
+module.exports.toArray = toArray;

package/index.js

@@ -1,26 +1,50 @@
 'use strict';
 
-module.exports.App = require('./lib/App');
-module.exports.Capability = require('./lib/Capability');
-module.exports.Device = require('./lib/Device');
-module.exports.Energy = require('./lib/Energy');
-module.exports.Media = require('./lib/Media');
-module.exports.Signal = require('./lib/Signal');
-module.exports.Util = require('./lib/Util');
-
-module.exports.getDeviceClasses = module.exports.Device.getClasses.bind(module.exports.Device);
-module.exports.getDeviceClass = module.exports.Device.getClass.bind(module.exports.Device);
-
-module.exports.getCapabilities = module.exports.Capability.getCapabilities.bind(module.exports.Capability);
-module.exports.getCapability = module.exports.Capability.getCapability.bind(module.exports.Capability);
-module.exports.hasCapability = module.exports.Capability.hasCapability.bind(module.exports.Capability);
-
-module.exports.getAppLocales = module.exports.App.getLocales.bind(module.exports.App);
-module.exports.getAppCategories = module.exports.App.getCategories.bind(module.exports.App);
-module.exports.getAppPermissions = module.exports.App.getPermissions.bind(module.exports.App);
-module.exports.getAppBrandColor = module.exports.App.getBrandColor.bind(module.exports.App);
-
-module.exports.getMediaCodecs = module.exports.Media.getCodecs.bind(module.exports.Media);
-
-module.exports.getCurrencies = module.exports.Energy.getCurrencies.bind(module.exports.Energy);
-module.exports.getBatteries = module.exports.Energy.getBatteries.bind(module.exports.Energy);
+const App = require('./lib/App');
+const Capability = require('./lib/Capability');
+const Device = require('./lib/Device');
+const Energy = require('./lib/Energy');
+const Media = require('./lib/Media');
+const Signal = require('./lib/Signal');
+const Util = require('./lib/Util');
+
+module.exports.App = App;
+module.exports.Capability = Capability;
+module.exports.Device = Device;
+module.exports.Energy = Energy;
+module.exports.Media = Media;
+module.exports.Signal = Signal;
+module.exports.Util = Util;
+
+/** @type {typeof Device.getClasses} */
+module.exports.getDeviceClasses = Device.getClasses.bind(Device);
+/** @type {typeof Device.getClass} */
+module.exports.getDeviceClass = Device.getClass.bind(Device);
+
+/** @type {typeof Capability.getCapabilities} */
+module.exports.getCapabilities = Capability.getCapabilities.bind(Capability);
+/** @type {typeof Capability.getCapability} */
+module.exports.getCapability = Capability.getCapability.bind(Capability);
+/** @type {typeof Capability.hasCapability} */
+module.exports.hasCapability = Capability.hasCapability.bind(Capability);
+
+/** @type {typeof App.getLocales} */
+module.exports.getAppLocales = App.getLocales.bind(App);
+/** @type {typeof App.getCategories} */
+module.exports.getAppCategories = App.getCategories.bind(App);
+/** @type {typeof App.getPermissions} */
+module.exports.getAppPermissions = App.getPermissions.bind(App);
+/** @type {typeof App.getBrandColor} */
+module.exports.getAppBrandColor = App.getBrandColor.bind(App);
+
+/** @type {typeof Media.getCodecs} */
+module.exports.getMediaCodecs = Media.getCodecs.bind(Media);
+
+/** @type {typeof Energy.getCurrencies} */
+module.exports.getCurrencies = Energy.getCurrencies.bind(Energy);
+/** @type {typeof Energy.getBatteries} */
+module.exports.getBatteries = Energy.getBatteries.bind(Energy);
+
+/** @typedef {import('./assets/app/schema').App} AppManifest */
+/** @typedef {import('./assets/capability/schema').Capability} CapabilityDefinition */
+/** @typedef {import('./assets/app/schema').ZigbeeFirmwareUpdates} ZigbeeFirmwareUpdates */

package/lib/App/index.js

@@ -14,6 +14,7 @@ const Device = require('../Device');
 const Capability = require('../Capability');
 const Signal = require('../Signal');
 const Energy = require('../Energy');
+const Util = require('../Util');
 
 const {
   openAsync,
@@ -28,8 +29,11 @@ const {
   extname,
   basename,
   dirname,
+  toArray,
 } = require('../../helpers');
 
+/** @typedef {import('../../assets/app/schema').App} AppManifest */
+
 const VALIDATION_LEVELS = [
   'debug',
   'publish',
@@ -76,6 +80,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 +91,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 +119,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 +232,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`);
       }
     }
 
@@ -631,6 +646,88 @@ class App {
         if (driver.matter && !(driver.connectivity && driver.connectivity.includes('matter'))) {
           throw new Error(`drivers.${driver.id} Matter drivers require 'connectivity' to include 'matter'.`);
         }
+
+        // Validate driver.firmwareUpdates
+        if (driver.firmwareUpdates && Array.isArray(driver.firmwareUpdates.updates)) {
+          // TODO: Remove when we want to roll out firmware updates.
+          if (level !== 'debug') {
+            throw new Error(`drivers.${driver.id} firmwareUpdates can only be included in debug mode validation.`);
+          }
+
+          const isZigbeeDriver = typeof driver.zigbee === 'object' && driver.zigbee !== null;
+
+          if (!isZigbeeDriver) {
+            throw new Error(`drivers.${driver.id} firmwareUpdates are only supported for Zigbee drivers (missing driver.zigbee)`);
+          }
+
+          for (const [updateIndex, update] of Object.entries(driver.firmwareUpdates.updates)) {
+            const hasChangelogString = typeof update.changelog === 'string';
+            const hasChangelogEnString = update.changelog && typeof update.changelog.en === 'string';
+            
+            if (!hasChangelogString && !hasChangelogEnString) {
+              throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] is missing a changelog string`);
+            }
+
+            if (!Array.isArray(update.files) || update.files.length === 0) {
+              throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files must include at least one file`);
+            }
+
+            if (isZigbeeDriver) {
+              const driverManufacturerNames = toArray(driver.zigbee.manufacturerName);
+              const driverProductIds = toArray(driver.zigbee.productId);
+
+              const updateManufacturerNames = toArray(update.device.manufacturerName);
+              const updateProductIds = toArray(update.device.productId);
+
+              if (updateManufacturerNames.length === 0 || updateProductIds.length === 0) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] must include at least one manufacturerName and productId`);
+              }
+
+              const hasMismatchedManufacturerName = updateManufacturerNames.some(name => !driverManufacturerNames.includes(name));
+              const hasMismatchedProductId = updateProductIds.some(id => !driverProductIds.includes(id));
+
+              if (hasMismatchedManufacturerName) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has a manufacturerName that does not match the driver zigbee.manufacturerName`);
+              }
+
+              if (hasMismatchedProductId) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has a productId that does not match the driver zigbee.productId`);
+              }
+            }
+
+            const seenFiles = new Set();
+
+            for (const [fileIndex, file] of Object.entries(update.files)) {
+              const relativeFilePath = Util.getOTAFilePath({ appPath: '', driverId: driver.id, fileName: file.name });
+              await this._ensureFileExistsCaseSensitive(relativeFilePath);
+              const filePath = join(this._path, relativeFilePath);
+              const isIntegrityValid = await Util.validateIntegrity(filePath, file.integrity);
+
+              if (!isIntegrityValid) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files[${fileIndex}] integrity mismatch`);
+              }
+              
+              if (isZigbeeDriver) {
+                try {
+                  await Util.validateZigbeeOTAHeader({
+                    filePath,
+                    manufacturerCode: file.manufacturerCode,
+                    fileVersion: file.fileVersion,
+                    imageType: file.imageType,
+                  });
+                } catch (err) {
+                  throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}].files[${fileIndex}] invalid Zigbee OTA header: ${err.message}`);
+                }
+              }
+
+              const fileId = `${file.manufacturerCode}-${file.imageType}-${file.fileVersion}`;
+              if (seenFiles.has(fileId)) {
+                throw new Error(`drivers.${driver.id}.firmwareUpdates.updates[${updateIndex}] has multiple files with the same manufacturerCode, imageType and fileVersion`);
+              }
+              seenFiles.add(fileId);
+            }
+          }
+        }
       }
 
       const allDriversMatter = appJson.drivers.every(driver => driver.connectivity && driver.connectivity.includes('matter'));
@@ -787,6 +884,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)) {
@@ -794,6 +895,11 @@ class App {
     }
   }
 
+  /**
+   * @param {Record<string, unknown>} setting
+   * @param {{ id: string }} driver
+   * @returns {void}
+   */
   _checkPrivateSettingPrefixUse(setting, driver) {
     if (
       setting.type &&
@@ -818,6 +924,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}`);
@@ -841,6 +952,10 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<string[]>}
+   */
   async _getDirectoryContents(filepath) {
     await this._fileExistsCaseSensitive(filepath);
 
@@ -853,6 +968,10 @@ class App {
     });
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<void>}
+   */
   async _ensureFileExistsCaseSensitive(filepath) {
     const exists = await this._fileExistsCaseSensitive(filepath);
     if (exists !== true) {
@@ -860,6 +979,10 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @returns {Promise<boolean>}
+   */
   async _fileExistsCaseSensitive(filepath) {
     filepath = join(this._path, filepath);
     const dir = dirname(filepath);
@@ -875,6 +998,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++) {
@@ -904,6 +1033,9 @@ class App {
     }
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async _validateModules() {
     const nodeModulesPath = join(this._path, 'node_modules');
 
@@ -927,6 +1059,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) {
@@ -1006,6 +1145,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;
@@ -1040,6 +1185,11 @@ class App {
     }
   }
 
+  /**
+   * @param {string} filepath
+   * @param {number} numBytes
+   * @returns {Promise<Buffer>}
+   */
   async _readBytes(filepath, numBytes) {
     filepath = join(this._path, filepath);
 
@@ -1050,6 +1200,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;
@@ -1058,16 +1212,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');
@@ -1082,15 +1246,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;
@@ -1114,6 +1288,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',