homey-api 3.0.0-rc.9 → 3.0.0

package/index.browser.js

@@ -11,3 +11,4 @@ global.HomeyCloudAPI = require('./lib/HomeyCloudAPI');
 global.HomeyAPIV2 = require('./lib/HomeyAPI/HomeyAPIV2');
 global.HomeyAPIV3Local = require('./lib/HomeyAPI/HomeyAPIV3Local');
 global.HomeyAPIV3Cloud = require('./lib/HomeyAPI/HomeyAPIV3Cloud');
+global.HomeyAPI = require('./lib/HomeyAPI/HomeyAPI');

package/index.js

@@ -2,23 +2,42 @@
 
 'use strict';
 
-module.exports = {
-  AthomAppsAPI: require('./lib/AthomAppsAPI'),
-  AthomBackupAPI: require('./lib/AthomBackupAPI'),
-  AthomCallbackAPI: require('./lib/AthomCallbackAPI'),
-  AthomCloudAPI: require('./lib/AthomCloudAPI'),
-  AthomConnectAPI: require('./lib/AthomConnectAPI'),
-  AthomDNSAPI: require('./lib/AthomDNSAPI'),
-  AthomFirmwareAPI: require('./lib/AthomFirmwareAPI'),
-  AthomFlowAPI: require('./lib/AthomFlowAPI'),
-  AthomGeolocateAPI: require('./lib/AthomGeolocateAPI'),
-  AthomIconsAPI: require('./lib/AthomIconsAPI'),
-  AthomInfraredAPI: require('./lib/AthomInfraredAPI'),
-  AthomNotificationsAPI: require('./lib/AthomNotificationsAPI'),
-  AthomSetupAPI: require('./lib/AthomSetupAPI'),
-  AthomStoreAPI: require('./lib/AthomStoreAPI'),
-  AthomWeatherAPI: require('./lib/AthomWeatherAPI'),
-  AthomWebhooksAPI: require('./lib/AthomWebhooksAPI'),
-  HomeyCloudAPI: require('./lib/HomeyCloudAPI'),
-  HomeyAPI: require('./lib/HomeyAPI/HomeyAPI'),
-};
+module.exports = {};
+
+// Athom Cloud
+module.exports.AthomAppsAPI = require('./lib/AthomAppsAPI');
+module.exports.AthomBackupAPI = require('./lib/AthomBackupAPI');
+module.exports.AthomCallbackAPI = require('./lib/AthomCallbackAPI');
+module.exports.AthomCloudAPI = require('./lib/AthomCloudAPI');
+module.exports.AthomConnectAPI = require('./lib/AthomConnectAPI');
+module.exports.AthomDNSAPI = require('./lib/AthomDNSAPI');
+module.exports.AthomFirmwareAPI = require('./lib/AthomFirmwareAPI');
+module.exports.AthomFlowAPI = require('./lib/AthomFlowAPI');
+module.exports.AthomGeolocateAPI = require('./lib/AthomGeolocateAPI');
+module.exports.AthomIconsAPI = require('./lib/AthomIconsAPI');
+module.exports.AthomInfraredAPI = require('./lib/AthomInfraredAPI');
+module.exports.AthomNotificationsAPI = require('./lib/AthomNotificationsAPI');
+module.exports.AthomSetupAPI = require('./lib/AthomSetupAPI');
+module.exports.AthomStoreAPI = require('./lib/AthomStoreAPI');
+module.exports.AthomWeatherAPI = require('./lib/AthomWeatherAPI');
+module.exports.AthomWebhooksAPI = require('./lib/AthomWebhooksAPI');
+
+// Homey Cloud
+module.exports.HomeyCloudAPI = require('./lib/HomeyCloudAPI');
+
+// Homey API
+module.exports.HomeyAPI = require('./lib/HomeyAPI/HomeyAPI');
+module.exports.HomeyAPIV1 = require('./lib/HomeyAPI/HomeyAPIV1');
+module.exports.HomeyAPIV2 = require('./lib/HomeyAPI/HomeyAPIV2');
+module.exports.HomeyAPIV3 = require('./lib/HomeyAPI/HomeyAPIV3');
+module.exports.HomeyAPIV3Local = require('./lib/HomeyAPI/HomeyAPIV3Local');
+module.exports.HomeyAPIV3Cloud = require('./lib/HomeyAPI/HomeyAPIV3Cloud');
+
+// APIError
+module.exports.APIError = require('./lib/APIError');
+module.exports.APIErrorHomeyOffline = require('./lib/APIErrorHomeyOffline');
+module.exports.APIErrorNotFound = require('./lib/APIErrorNotFound');
+module.exports.APIErrorTimeout = require('./lib/APIErrorTimeout');
+
+// Util
+module.exports.Util = require('./lib/Util');

package/lib/API.js

@@ -73,6 +73,7 @@ class API {
       $body = {},
       $query = {},
       $headers = {},
+      $token = null,
       ...args
     } = {}) => {
       let pathWithParameters = operation.path;
@@ -89,6 +90,11 @@ class API {
           value = this.__secret;
         }
 
+        // Set Authorization header if $token is provided
+        if (typeof $token === 'string') {
+          headers.Authorization = `Bearer ${$token}`;
+        }
+
         // Validate the parameter
         if ($validate) {
           if (parameter.required === true && typeof value === 'undefined') {

package/lib/AthomCloudAPI/StorageAdapter.js

@@ -2,6 +2,7 @@
 
 /**
  * Abstract storage adapter. To be extended by your own, or {@link AthomCloudAPI.StorageAdapterBrowser} or {@link AthomCloudAPI.StorageAdapterMemory}.
+ * When creating your own, make sure to overload the `get` and `set` methods.
  * @class
  * @memberof AthomCloudAPI
  */

package/lib/HomeyAPI/HomeyAPI.js

@@ -1,13 +1,28 @@
 'use strict';
 
+const Util = require('../Util');
+
 /**
- * A Homey API, to be extended.
+ * An authenticated Homey API. Do not construct this class manually.
+ * @class
  * @hideconstructor
  */
 class HomeyAPI {
 
   /**
-   * Possible Discovery Strategies
+   * Platforms
+   * @static
+   * @property {object} PLATFORMS
+   * @property {string} PLATFORMS.LOCAL - Homey (2016 — 2019) & Homey Pro (2019 — 2023)
+   * @property {string} PLATFORMS.CLOUD - Homey Cloud
+   */
+  static PLATFORMS = {
+    LOCAL: 'local',
+    CLOUD: 'cloud',
+  };
+
+  /**
+   * Discovery Strategies
    * @static
    * @property {object} DISCOVERY_STRATEGIES
    * @property {string} DISCOVERY_STRATEGIES.CLOUD - Cloud HTTPS, e.g. `https://abcdef.connect.athom.com`.
@@ -25,8 +40,8 @@ class HomeyAPI {
   };
 
   constructor({
-    api,
-    properties,
+    api = null,
+    properties = {},
     debug = () => { },
   }) {
     // Set Debug Enabled
@@ -45,14 +60,28 @@ class HomeyAPI {
 
     // Set ID
     Object.defineProperty(this, 'id', {
-      value: properties.id || properties._id || null,
+      value: properties.id ?? properties._id ?? null,
       enumerable: true,
       writable: true,
     });
 
     // Set Version
     Object.defineProperty(this, 'version', {
-      value: properties.softwareVersion || null,
+      value: properties.softwareVersion ?? null,
+      enumerable: true,
+      writable: true,
+    });
+
+    // Set Name
+    Object.defineProperty(this, 'name', {
+      value: properties.name ?? null,
+      enumerable: true,
+      writable: true,
+    });
+
+    // Set Language
+    Object.defineProperty(this, 'Language', {
+      value: properties.Language ?? null,
       enumerable: true,
       writable: true,
     });
@@ -65,6 +94,10 @@ class HomeyAPI {
     });
   }
 
+  get _id() {
+    throw new Error('HomeyAPI._id is not supported, please use HomeyAPI.id');
+  }
+
   __debug(...props) {
     if (!this.__debugFunction) return;
     this.__debugFunction(...props);
@@ -126,10 +159,29 @@ class HomeyAPI {
   }
 
   /**
-   * Create a {@link HomeyAPIV3Local} instance for use in the Apps SDK.
+   * Creates a {@link HomeyAPIV3Local} or {@link HomeyAPIV2} instance for use in the Apps SDK.
    * @param {Object} opts
-   * @param {Homey} opts.homey — Homey instance
-   * @param {Function|null} opts.debug — Debug function, defaults to `null`
+   * @param {Homey} opts.homey — Homey (Apps SDK) instance.
+   * @param {Function|null} opts.debug — Debug function, defaults to `null`.
+   * @example
+   * const { HomeyAPI } = require('homey-api');
+   *
+   * module.exports = class MyApp extends Homey.App {
+   *
+   *   async onInit() {
+   *     // Create a HomeyAPI instance. Ensure your app has the `homey:manager:api` permission.
+   *     this.homeyApi = await HomeyAPI.createAppAPI({
+   *       homey: this.homey,
+   *     });
+   *
+   *     // Get all the devices, and log their names.
+   *     const devices = await this.{@link HomeyAPIV3Local homeyApi}.{@link HomeyAPIV3Local.ManagerDevices devices}.{@link HomeyAPIV3Local.ManagerDevices#getDevices getDevices}();
+   *     for(const device of Object.values(devices)) {
+   *       this.log(device.name);
+   *     }
+   *   }
+   *
+   * }
    */
   static async createAppAPI({
     homey,
@@ -172,6 +224,53 @@ class HomeyAPI {
     throw new Error(`Invalid Homey Platform Version: ${homey.platformVersion}`);
   }
 
+  /**
+   * Creates a {@link HomeyAPIV3Local} instance for use in a project.
+   * @param {Object} opts
+   * @param {String} opts.address — The address of the Homey, e.g. `http://192.168.1.123:80`.
+   * @param {String} opts.token — A Personal Access Token created in the Homey Web App.
+   * @param {Function|null} opts.debug — Debug function, defaults to `null`.
+   * @example
+   * import { HomeyAPI } from 'homey-api';
+   * const homeyApi = await HomeyAPI.createLocalAPI({
+   *   address: 'http://192.169.1.123',
+   *   token: '<my_personal_access_token>',
+   * });
+   * const devices = await homeyApi.devices.getDevices();
+   */
+  static async createLocalAPI({
+    address,
+    token,
+    debug = null,
+  }) {
+    if (!address) {
+      throw new Error('Invalid Address');
+    }
+
+    if (!token) {
+      throw new Error('Invalid Token');
+    }
+
+    const res = await Util.fetch(`${address}/api/manager/system/ping`);
+    if (!res.headers.has('X-Homey-ID')) {
+      throw new Error(`No Homey Found At Address: ${address}`);
+    }
+
+    const props = {
+      token,
+      debug: debug ?? function debug() { },
+      baseUrl: address,
+      strategy: [],
+      properties: {
+        id: res.headers.get('X-Homey-ID'),
+        softwareVersion: res.headers.get('X-Homey-Version'),
+      },
+    };
+
+    const HomeyAPIV3Local = require('./HomeyAPIV3Local');
+    return new HomeyAPIV3Local(props);
+  }
+
 }
 
 module.exports = HomeyAPI;

package/lib/HomeyAPI/HomeyAPIV1.js

@@ -19,6 +19,14 @@ class HomeyAPIV1 extends HomeyAPI {
     this.token = token;
   }
 
+  get platform() {
+    return 'local';
+  }
+
+  get platformVersion() {
+    return 1;
+  }
+
   updates = {
     async getUpdates() {
       throw new Error('Not Implemented');

package/lib/HomeyAPI/HomeyAPIV2/ManagerDevices/Device.js

@@ -5,9 +5,10 @@ const DeviceV3 = require('../../HomeyAPIV3/ManagerDevices/Device');
 class Device extends DeviceV3 {
 
   static transformGet(item) {
+    item.driverId = `${item.driverUri}:${item.driverId}`;
+
     item = super.transformGet(item);
 
-    item.driverId = `${item.driverUri}:${item.driverId}`;
     delete item.driverUri;
     delete item.zoneName;
     return item;

package/lib/HomeyAPI/HomeyAPIV2/ManagerFlow/AdvancedFlow.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const AdvancedFlowV3 = require('../../HomeyAPIV3/ManagerFlow/Flow');
+const AdvancedFlowV3 = require('../../HomeyAPIV3/ManagerFlow/AdvancedFlow');
 
 class AdvancedFlow extends AdvancedFlowV3 {
 
@@ -11,6 +11,8 @@ class AdvancedFlow extends AdvancedFlowV3 {
       }
     }
 
+    delete item.broken;
+
     return item;
   }
 

package/lib/HomeyAPI/HomeyAPIV2/ManagerFlow/Flow.js

@@ -26,6 +26,8 @@ class Flow extends FlowV3 {
       });
     }
 
+    delete item.broken;
+
     return item;
   }
 

package/lib/HomeyAPI/HomeyAPIV2/ManagerFlow.js

@@ -66,7 +66,7 @@ class ManagerFlow extends Manager {
       return this.__cache['flowcardtrigger'][id];
     }
 
-    return this.__super__getFlowCardCondition({
+    return this.__super__getFlowCardTrigger({
       id: id.split(':').reverse()[0],
       uri: id.split(':', 3).join(':'),
     });

package/lib/HomeyAPI/HomeyAPIV2.js

@@ -25,6 +25,14 @@ class HomeyAPIV2 extends HomeyAPIV3 {
     ManagerInsights,
   };
 
+  get platform() {
+    return 'local';
+  }
+
+  get platformVersion() {
+    return 1;
+  }
+
 }
 
 module.exports = HomeyAPIV2;

package/lib/HomeyAPI/HomeyAPIV3/Manager.js

@@ -213,6 +213,7 @@ class Manager extends EventEmitter {
             // This is about ~2x faster than HTTP
             if (this.homey.isConnected() && $socket === true) {
               result = await Util.timeout(new Promise((resolve, reject) => {
+                this.__debug(`IO ${operationId}`);
                 this.homey.__ioNamespace.emit('api', {
                   args,
                   operation: operationId,
@@ -278,7 +279,8 @@ class Manager extends EventEmitter {
                   // Add all to cache
                   for (let item of Object.values(result)) {
                     item = Item.transformGet(item);
-                    if (this.__cache[itemId][item.id]) {
+
+                    if (this.isConnected() && this.__cache[itemId][item.id]) {
                       items[item.id] = this.__cache[itemId][item.id];
                       items[item.id].__update(item);
                     } else {
@@ -316,7 +318,7 @@ class Manager extends EventEmitter {
                   let item = { ...result };
                   item = Item.transformGet(item);
 
-                  if (this.__cache[itemId][item.id]) {
+                  if (this.isConnected() && this.__cache[itemId][item.id]) {
                     item = this.__cache[itemId][item.id];
                     item.__update(item);
                   } else {
@@ -336,7 +338,7 @@ class Manager extends EventEmitter {
                   return item;
                 }
                 case 'deleteOne': {
-                  if (this.__cache[itemId][args.id]) {
+                  if (this.isConnected() && this.__cache[itemId][args.id]) {
                     this.__cache[itemId][args.id].destroy();
                     delete this.__cache[itemId][args.id];
                   }
@@ -422,7 +424,7 @@ class Manager extends EventEmitter {
                   });
                   this.__cache[itemId][data.id] = item;
 
-                  break;
+                  return this.emit(event, item);
                 }
                 case 'update': {
                   data = Item.transformGet(data);
@@ -430,6 +432,7 @@ class Manager extends EventEmitter {
                   if (this.__cache[itemId][data.id]) {
                     const item = this.__cache[itemId][data.id];
                     item.__update(data);
+                    return this.emit(event, item);
                   }
 
                   break;
@@ -441,6 +444,9 @@ class Manager extends EventEmitter {
                     const item = this.__cache[itemId][data.id];
                     item.__delete();
                     delete this.__cache[itemId][item.id];
+                    return this.emit(event, {
+                      id: item.id,
+                    });
                   }
 
                   break;

package/lib/HomeyAPI/HomeyAPIV3/ManagerDevices/Device.js

@@ -198,6 +198,8 @@ class Device extends Item {
   static transformGet(item) {
     item = super.transformGet(item);
 
+    delete item.driverUri;
+
     if (item.capabilitiesObj) {
       for (const capabilityObj of Object.values(item.capabilitiesObj)) {
         if (capabilityObj.lastUpdated) {

package/lib/HomeyAPI/HomeyAPIV3/ManagerDevices/DeviceCapability.js

@@ -6,7 +6,7 @@ const EventEmitter = require('../../../EventEmitter');
 /**
  * @class
  * @hideconstructor
- * @memberof HomeyAPIV2.ManagerDevices.Device
+ * @memberof HomeyAPIV3.ManagerDevices.Device
  */
 class DeviceCapability extends EventEmitter {
 
@@ -79,7 +79,7 @@ class DeviceCapability extends EventEmitter {
   }
 
   /**
-   * Destroy the listener, and if it's the last one, unsubscribe from the device's realtime events.
+   * Destroy this capability listener, and if it's the last one, unsubscribe from the device's realtime events.
    */
   destroy() {
     this.emit('destroy');
@@ -139,7 +139,7 @@ class DeviceCapability extends EventEmitter {
   }
 
   /**
-   *
+   * Sets a new capability value.
    * @param {boolean|number|string} value - The new capability value
    * @param {object} opts
    */

package/lib/HomeyAPI/HomeyAPIV3/ManagerFlow/AdvancedFlow.js

@@ -1,9 +1,128 @@
+/* eslint-disable no-unused-vars */
+
 'use strict';
 
 const Item = require('../Item');
 
 class AdvancedFlow extends Item {
 
+  async isBroken() {
+    const managerFlow = this.homey.flow;
+    if (!managerFlow.isConnected()) {
+      throw new Error('Flow.isBroken requires ManagerFlow to be connected.');
+    }
+
+    const managerFlowToken = this.homey.flowtoken;
+    if (!managerFlowToken.isConnected()) {
+      throw new Error('Flow.isBroken requires ManagerFlowToken to be connected.');
+    }
+
+    // Array of local & global Token IDs.
+    // For example [ 'foo', 'homey:x:y|abc' ]
+    const tokenIds = [];
+
+    const checkToken = async tokenId => {
+      // If this is a global Token, fetch all FlowTokens
+      if (tokenId.includes('|')) {
+        const flowTokens = await managerFlowToken.getFlowTokens(); // Fill the cache
+        for (const flowTokenId of Object.keys(flowTokens)) {
+          tokenIds.push(flowTokenId);
+        }
+
+        tokenId = tokenId.replace('|', ':');
+      }
+
+      if (!tokenIds.includes(tokenId)) {
+        throw new Error(`Missing Token: ${tokenId}`);
+      }
+    };
+
+    const checkTokens = async card => {
+      // Check droptoken
+      if (card.droptoken) {
+        await checkToken(card.droptoken);
+      }
+
+      if (typeof card.args === 'object') {
+        for (const arg of Object.values(card.args)) {
+          if (typeof arg !== 'string') continue;
+          for (const [tokenMatch, tokenId] of arg.matchAll(/\[\[(.*?)\]\]/g)) {
+            await checkToken(tokenId);
+          }
+        }
+      }
+    };
+
+    // Check if FlowCards exist, and add Tokens
+    for (const [cardId, card] of Object.entries(this.cards)) {
+      switch (card.type) {
+        case 'trigger': {
+          try {
+            await managerFlow.getFlowCardTriggers(); // Fill the cache
+            const triggerCard = await this.manager.getFlowCardTrigger({ id: card.id });
+
+            // Add FlowCardTrigger.tokens to internal tokens cache
+            if (Array.isArray(triggerCard.tokens)) {
+              for (const token of Object.values(triggerCard.tokens)) {
+                tokenIds.push(`trigger::${cardId}::${token.id}`);
+              }
+            }
+
+            break;
+          } catch (err) {
+            this.__debug(err);
+            return true;
+          }
+        }
+        case 'condition': {
+          try {
+            await managerFlow.getFlowCardConditions(); // Fill the cache
+            const conditionCard = await this.manager.getFlowCardCondition({ id: card.id });
+
+            // Add Error Token
+            tokenIds.push(`card::${cardId}::error`);
+
+            break;
+          } catch (err) {
+            this.__debug(err);
+            return true;
+          }
+        }
+        case 'action': {
+          try {
+            await managerFlow.getFlowCardActions(); // Fill the cache
+            const actionCard = await this.manager.getFlowCardAction({ id: card.id });
+
+            // Add Error Token
+            tokenIds.push(`card::${cardId}::error`);
+
+            // Add FlowCardAction.tokens to internal tokens cache
+            if (Array.isArray(actionCard.tokens)) {
+              for (const token of Object.values(actionCard.tokens)) {
+                tokenIds.push(`action::${cardId}::${token.id}`);
+              }
+            }
+
+            break;
+          } catch (err) {
+            this.__debug(err);
+            return true;
+          }
+        }
+        default: {
+          // Do nothing
+        }
+      }
+    }
+
+    // Check Tokens
+    for (const card of Object.values(this.cards)) {
+      await checkTokens(card);
+    }
+
+    return false;
+  }
+
 }
 
 module.exports = AdvancedFlow;

package/lib/HomeyAPI/HomeyAPIV3/ManagerFlow/Flow.js

@@ -1,3 +1,5 @@
+/* eslint-disable no-unused-vars */
+
 'use strict';
 
 const Item = require('../Item');
@@ -9,7 +11,100 @@ class Flow extends Item {
    * @returns Promise<Boolean>
    */
   async isBroken() {
-    throw new Error('Not Implemented');
+    const managerFlow = this.homey.flow;
+    if (!managerFlow.isConnected()) {
+      throw new Error('Flow.isBroken requires ManagerFlow to be connected.');
+    }
+
+    const managerFlowToken = this.homey.flowtoken;
+    if (!managerFlowToken.isConnected()) {
+      throw new Error('Flow.isBroken requires ManagerFlowToken to be connected.');
+    }
+
+    // Array of local & global Token IDs.
+    // For example [ 'foo', 'homey:x:y|abc' ]
+    const tokenIds = [];
+
+    const checkToken = async tokenId => {
+      // If this is a global Token, fetch all FlowTokens
+      if (tokenId.includes('|')) {
+        const flowTokens = await managerFlowToken.getFlowTokens(); // Fill the cache
+        for (const flowTokenId of Object.keys(flowTokens)) {
+          tokenIds.push(flowTokenId);
+        }
+
+        tokenId = tokenId.replace('|', ':');
+      }
+
+      if (!tokenIds.includes(tokenId)) {
+        throw new Error(`Missing Token: ${tokenId}`);
+      }
+    };
+
+    const checkTokens = async card => {
+      // Check droptoken
+      if (card.droptoken) {
+        await checkToken(card.droptoken);
+      }
+
+      if (typeof card.args === 'object') {
+        for (const arg of Object.values(card.args)) {
+          if (typeof arg !== 'string') continue;
+          for (const [tokenMatch, tokenId] of arg.matchAll(/\[\[(.*?)\]\]/g)) {
+            await checkToken(tokenId);
+          }
+        }
+      }
+    };
+
+    // Check Trigger
+    if (this.trigger) {
+      try {
+        await managerFlow.getFlowCardTriggers(); // Fill the cache
+        const triggerCard = await this.manager.getFlowCardTrigger({ id: this.trigger.id });
+        await checkTokens(this.trigger);
+
+        // Add FlowCardTrigger.tokens to internal tokens cache
+        if (Array.isArray(triggerCard.tokens)) {
+          for (const tokenId of Object.keys(triggerCard.tokens)) {
+            tokenIds.push(tokenId);
+          }
+        }
+      } catch (err) {
+        this.__debug(err.message);
+        return true;
+      }
+    }
+
+    // Check Conditions
+    if (Array.isArray(this.conditions)) {
+      for (const condition of Object.values(this.conditions)) {
+        try {
+          await managerFlow.getFlowCardConditions(); // Fill the cache
+          const conditionCard = await this.manager.getFlowCardCondition({ id: condition.id });
+          await checkTokens(condition);
+        } catch (err) {
+          this.__debug(err.message);
+          return true;
+        }
+      }
+    }
+
+    // Check Actions
+    if (Array.isArray(this.actions)) {
+      for (const action of Object.values(this.actions)) {
+        try {
+          await managerFlow.getFlowCardActions(); // Fill the cache
+          const actionCard = await this.manager.getFlowCardAction({ id: action.id });
+          await checkTokens(action);
+        } catch (err) {
+          this.__debug(err.message);
+          return true;
+        }
+      }
+    }
+
+    return false;
   }
 
 }