homey-api 3.0.0-rc.2 → 3.0.0-rc.21

package/lib/HomeyAPI/HomeyAPI.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const Util = require('../Util');
+
 /**
  * A Homey API, to be extended.
  * @hideconstructor
@@ -126,21 +128,25 @@ 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} opts.debug — Debug method, defaults to `homey.app.log`
+   * @param {Homey} opts.homey — Homey (Apps SDK) instance.
+   * @param {Function|null} opts.debug — Debug function, defaults to `null`.
    */
   static async createAppAPI({
     homey,
-    debug = (...props) => homey.app.log('[homey-api]', ...props),
+    debug = null,
   } = {}) {
     if (!homey) {
       throw new Error('Invalid Homey');
     }
 
+    if (debug === true) {
+      debug = (...props) => homey.app.log('[homey-api]', ...props);
+    }
+
     const props = {
-      debug,
+      debug: debug ?? function debug() { },
       token: await homey.api.getOwnerApiToken(),
       baseUrl: await homey.api.getLocalUrl(),
       strategy: [],
@@ -168,6 +174,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/HomeyAPIV2/ManagerDevices/Capability.js

@@ -4,8 +4,8 @@ const CapabilityV3 = require('../../HomeyAPIV3/ManagerDevices/Capability');
 
 class Capability extends CapabilityV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.id = `${item.uri}:${item.id}`;
     item.ownerUri = item.uri;

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

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

package/lib/HomeyAPI/HomeyAPIV2/ManagerDevices.js

@@ -12,20 +12,6 @@ class ManagerDevices extends Manager {
     Device,
   }
 
-  async getCapability({
-    $cache = true,
-    id,
-  }) {
-    if ($cache === true && this.__cache['capability'][id]) {
-      return this.__cache['capability'][id];
-    }
-
-    return this.__super__getCapability({
-      id: id.split(':').reverse()[0],
-      uri: id.split(':', 3).join(':'),
-    });
-  }
-
 }
 
 module.exports = ManagerDevices;

package/lib/HomeyAPI/HomeyAPIV2/ManagerDrivers/Driver.js

@@ -4,8 +4,8 @@ const DriverV3 = require('../../HomeyAPIV3/ManagerDrivers/Driver');
 
 class Driver extends DriverV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.ownerId = item.id;
     item.ownerUri = item.uri;

package/lib/HomeyAPI/HomeyAPIV2/ManagerDrivers/PairSession.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const PairSessionV3 = require('../../HomeyAPIV3/ManagerDrivers/PairSession');
+
+class PairSession extends PairSessionV3 {
+
+  static transformGet(item) {
+    item = super.transformGet(item);
+
+    item.driverId = `${item.driverUri}:${item.driverId}`;
+    item.ownerUri = item.driverUri;
+
+    delete item.driverUri;
+
+    return item;
+  }
+
+}
+
+module.exports = PairSession;

package/lib/HomeyAPI/HomeyAPIV2/ManagerDrivers.js

@@ -2,12 +2,14 @@
 
 const ManagerDriversV3 = require('../HomeyAPIV3/ManagerDrivers');
 const Driver = require('./ManagerDrivers/Driver');
+const PairSession = require('./ManagerDrivers/PairSession');
 
 class ManagerDrivers extends ManagerDriversV3 {
 
   static CRUD = {
     ...super.CRUD,
     Driver,
+    PairSession,
   }
 
   async getDriver({
@@ -24,6 +26,21 @@ class ManagerDrivers extends ManagerDriversV3 {
     });
   }
 
+  async createPairSession({
+    pairsession,
+    ...props
+  }) {
+    if (pairsession.driverId) {
+      pairsession.driverUri = pairsession.driverId.split(':', 3).join(':');
+      pairsession.driverId = pairsession.driverId.split(':').reverse()[0];
+    }
+
+    return this.__super__createPairSession({
+      pairsession,
+      ...props,
+    });
+  }
+
 }
 
 module.exports = ManagerDrivers;

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

@@ -1,12 +1,27 @@
 'use strict';
 
-const AdvancedFlowV3 = require('../../HomeyAPIV3/ManagerFlow/Flow');
+const AdvancedFlowV3 = require('../../HomeyAPIV3/ManagerFlow/AdvancedFlow');
 
 class AdvancedFlow extends AdvancedFlowV3 {
 
-  static transform(item) {
-    for (const card of Object.values(item.cards)) {
-      card.id = `${card.ownerUri}:${card.id}`;
+  static transformGet(item) {
+    if (item.cards) {
+      for (const card of Object.values(item.cards)) {
+        card.id = `${card.ownerUri}:${card.id}`;
+      }
+    }
+
+    delete item.broken;
+
+    return item;
+  }
+
+  static transformSet(item) {
+    if (item.cards) {
+      for (const card of Object.values(item.cards)) {
+        card.ownerUri = card.id.split(':', 3).join(':');
+        card.id = card.id.split(':').reverse()[0];
+      }
     }
 
     return item;

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

@@ -4,8 +4,8 @@ const FlowV3 = require('../../HomeyAPIV3/ManagerFlow/Flow');
 
 class Flow extends FlowV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     if (item.trigger) {
       item.trigger.id = `${item.trigger.uri}:${item.trigger.id}`;
@@ -26,6 +26,31 @@ class Flow extends FlowV3 {
       });
     }
 
+    delete item.broken;
+
+    return item;
+  }
+
+  static transformSet(item) {
+    if (item.trigger) {
+      item.trigger.uri = item.trigger.id.split(':', 3).join(':');
+      item.trigger.id = item.trigger.id.split(':').reverse()[0];
+    }
+
+    if (Array.isArray(item.conditions)) {
+      item.conditions.forEach(card => {
+        card.uri = card.id.split(':', 3).join(':');
+        card.id = card.id.split(':').reverse()[0];
+      });
+    }
+
+    if (Array.isArray(item.actions)) {
+      item.actions.forEach(card => {
+        card.uri = card.id.split(':', 3).join(':');
+        card.id = card.id.split(':').reverse()[0];
+      });
+    }
+
     return item;
   }
 

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

@@ -4,8 +4,8 @@ const FlowCardActionV3 = require('../../HomeyAPIV3/ManagerFlow/FlowCardAction');
 
 class FlowCardAction extends FlowCardActionV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.id = `${item.uri}:${item.id}`;
     item.ownerUri = item.uri;

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

@@ -4,8 +4,8 @@ const FlowCardConditionV3 = require('../../HomeyAPIV3/ManagerFlow/FlowCardCondit
 
 class FlowCardCondition extends FlowCardConditionV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.id = `${item.uri}:${item.id}`;
     item.ownerUri = item.uri;

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

@@ -4,8 +4,8 @@ const FlowCardTriggerV3 = require('../../HomeyAPIV3/ManagerFlow/FlowCardTrigger'
 
 class FlowCardTrigger extends FlowCardTriggerV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.id = `${item.uri}:${item.id}`;
     item.ownerUri = item.uri;

package/lib/HomeyAPI/HomeyAPIV2/ManagerFlow.js

@@ -18,22 +18,45 @@ class ManagerFlow extends Manager {
     FlowCardAction,
   }
 
-  // TODO: Transform card IDs
-  // async createFlow() {
-
-  // }
-
-  // async updateFlow() {
-
-  // }
-
-  // async createAdvancedFlow() {
+  async createFlow({
+    flow,
+    ...props
+  }) {
+    return this.__super__.createFlow({
+      flow: Flow.transformSet(flow),
+      ...props,
+    });
+  }
 
-  // }
+  async updateFlow({
+    flow,
+    ...props
+  }) {
+    return this.__super__.updateFlow({
+      flow: Flow.transformSet(flow),
+      ...props,
+    });
+  }
 
-  // async updateAdvancedFlow() {
+  async createAdvancedFlow({
+    advancedflow,
+    ...props
+  }) {
+    return this.__super__.createAdvancedFlow({
+      advancedflow: AdvancedFlow.transformSet(advancedflow),
+      ...props,
+    });
+  }
 
-  // }
+  async updateAdvancedFlow({
+    advancedflow,
+    ...props
+  }) {
+    return this.__super__.updateAdvancedFlow({
+      advancedflow: AdvancedFlow.transformSet(advancedflow),
+      ...props,
+    });
+  }
 
   async getFlowCardTrigger({
     $cache = true,
@@ -43,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/ManagerFlowToken/FlowToken.js

@@ -4,15 +4,15 @@ const FlowTokenV3 = require('../../HomeyAPIV3/ManagerFlowToken/FlowToken');
 
 class FlowToken extends FlowTokenV3 {
 
-  static transform(item) {
+  static transformGet(item) {
     // TODO: Remove FlowTokenV3.transform and uncomment this after front-end does not use FlowToken.uri|id|uriObj anymore!
-    // item = super.transform(item);
+    // item = super.transformGet(item);
 
     item.ownerUri = item.uri;
     item.ownerId = item.id;
-    item.ownerName = item.uriObj.name;
     item.id = `${item.ownerUri}:${item.ownerId}`;
 
+    delete item.ownerName; // Prepare for back-end change
     delete item.uri;
     delete item.uriObj;
 

package/lib/HomeyAPI/HomeyAPIV2/ManagerInsights/Log.js

@@ -4,12 +4,11 @@ const LogV3 = require('../../HomeyAPIV3/ManagerInsights/Log');
 
 class Log extends LogV3 {
 
-  static transform(item) {
-    item = super.transform(item);
+  static transformGet(item) {
+    item = super.transformGet(item);
 
     item.ownerId = item.id;
     item.ownerUri = item.uri;
-    item.ownerName = item.uriObj.name;
     item.id = `${item.uri}:${item.id}`;
 
     delete item.uri;

package/lib/HomeyAPI/HomeyAPIV2/ManagerInsights.js

@@ -24,6 +24,23 @@ class ManagerInsights extends ManagerInsightsV3 {
     });
   }
 
+  async getLogEntries({ id }) {
+    return this.__super__getLogEntries({
+      id: id.split(':').reverse()[0],
+      uri: id.split(':', 3).join(':'),
+    });
+  }
+
+  async deleteLogEntries({ id }) {
+    return this.__super__deleteLogEntries({
+      id: id.split(':').reverse()[0],
+      uri: id.split(':', 3).join(':'),
+    });
+  }
+
+  // deleteLog
+  // updateLog
+
 }
 
 module.exports = ManagerInsights;

package/lib/HomeyAPI/HomeyAPIV3/Item.js

@@ -64,8 +64,17 @@ class Item extends EventEmitter {
 
   __update(properties) {
     for (const [key, value] of Object.entries(properties)) {
+      if (key === 'id') continue;
+
       this[key] = value;
     }
+
+    this.emit('update', properties);
+  }
+
+  __delete() {
+    this.destroy();
+    this.emit('delete');
   }
 
   async connect() {
@@ -171,7 +180,11 @@ class Item extends EventEmitter {
     this.disconnect().catch(() => { });
   }
 
-  static transform(item) {
+  static transformGet(item) {
+    return item;
+  }
+
+  static transformSet(item) {
     return item;
   }
 

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,
@@ -258,9 +259,8 @@ class Manager extends EventEmitter {
               switch (operation.crud.type) {
                 case 'getOne': {
                   let item = { ...result };
-                  item = Item.transform(item);
+                  item = Item.transformGet(item);
                   item = new Item({
-                    itemId,
                     id: item.id,
                     homey: this.homey,
                     manager: this,
@@ -278,13 +278,13 @@ class Manager extends EventEmitter {
 
                   // Add all to cache
                   for (let item of Object.values(result)) {
-                    item = Item.transform(item);
-                    if (this.__cache[itemId][item.id]) {
-                      this.__cache[itemId][item.id].__update(item);
+                    item = Item.transformGet(item);
+
+                    if (this.isConnected() && this.__cache[itemId][item.id]) {
                       items[item.id] = this.__cache[itemId][item.id];
+                      items[item.id].__update(item);
                     } else {
                       items[item.id] = new Item({
-                        itemId,
                         id: item.id,
                         homey: this.homey,
                         manager: this,
@@ -316,13 +316,14 @@ class Manager extends EventEmitter {
                 case 'createOne':
                 case 'updateOne': {
                   let item = { ...result };
-                  item = Item.transform(item);
-                  if (this.__cache[itemId][item.id]) {
-                    item = this.__cache[itemId][item.id].__update(item);
+                  item = Item.transformGet(item);
+
+                  if (this.isConnected() && this.__cache[itemId][item.id]) {
+                    item = this.__cache[itemId][item.id];
+                    item.__update(item);
                   } else {
-                    item = Item.transform(item);
+                    item = Item.transformGet(item);
                     item = new Item({
-                      itemId,
                       id: item.id,
                       homey: this.homey,
                       manager: this,
@@ -337,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];
                   }
@@ -413,55 +414,42 @@ class Manager extends EventEmitter {
 
               switch (operation) {
                 case 'create': {
-                  let item = { ...data };
-                  item = Item.transform(item);
-                  item = new Item({
-                    itemId,
-                    id: item.id,
+                  data = Item.transformGet(data);
+
+                  const item = new Item({
+                    id: data.id,
                     homey: this.homey,
                     manager: this,
-                    properties: { ...item },
+                    properties: { ...data },
                   });
+                  this.__cache[itemId][data.id] = item;
 
-                  this.__cache[itemId][item.id] = item;
-                  this.__cache[itemId][item.id].emit('create');
-
-                  return this.emit(`${itemId}.create`, item);
+                  return this.emit(event, item);
                 }
                 case 'update': {
-                  let item = { ...data };
-                  item = Item.transform(item);
+                  data = Item.transformGet(data);
 
-                  if (this.__cache[itemId][item.id]) {
-                    item = this.__cache[itemId][item.id];
-                    item.__update(item);
-                    item.emit('update');
-                  } else {
-                    item = new Item({
-                      itemId,
-                      id: item.id,
-                      homey: this.homey,
-                      manager: this,
-                      properties: { ...item },
-                    });
-                    this.__cache[itemId][item.id] = item;
+                  if (this.__cache[itemId][data.id]) {
+                    const item = this.__cache[itemId][data.id];
+                    item.__update(data);
+                    return this.emit(event, item);
                   }
 
-                  return this.emit(`${itemId}.update`, item);
+                  break;
                 }
                 case 'delete': {
-                  let item = Item.transform({ ...data });
-                  item = Item.transform(item);
+                  data = Item.transformGet(data);
 
-                  if (this.__cache[itemId][item.id]) {
-                    this.__cache[itemId][item.id].emit('delete');
-                    this.__cache[itemId][item.id].destroy();
+                  if (this.__cache[itemId][data.id]) {
+                    const item = this.__cache[itemId][data.id];
+                    item.__delete();
                     delete this.__cache[itemId][item.id];
+                    return this.emit(event, {
+                      id: item.id,
+                    });
                   }
 
-                  return this.emit(`${itemId}.delete`, {
-                    id: item.id,
-                  });
+                  break;
                 }
                 default:
                   break;

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

@@ -17,17 +17,13 @@ class Device extends Item {
     });
   }
 
-  get uri() {
-    return `homey:device:${this.id}`;
-  }
-
   /**
-   * Creates an {@link HomeyAPIV2.DeviceCapability} for realtime capability updates.
+   * Creates an {@link HomeyAPIV3.DeviceCapability} for realtime capability updates.
    * @param {string} capabilityId
    * @param {Function} listener
    * @param {number|boolean|string} listener.value
-   * @returns {HomeyAPIV2.ManagerDevices.Device.DeviceCapability}
-   * @function HomeyAPIV2.ManagerDevices.Device#makeCapabilityInstance
+   * @returns {HomeyAPIV3.ManagerDevices.Device.DeviceCapability}
+   * @function HomeyAPIV3.ManagerDevices.Device#makeCapabilityInstance
    * @example
    *
    *  const onOffInstance = device.makeCapabilityInstance('onoff', value => {
@@ -76,7 +72,7 @@ class Device extends Item {
    * @param {object} [opts.opts]
    * @param {number} [opts.opts.duration]
    * @returns {Promise<void>}
-   * @function HomeyAPIV2.ManagerDevices.Device#setCapabilityValue
+   * @function HomeyAPIV3.ManagerDevices.Device#setCapabilityValue
    */
   async setCapabilityValue(options, ...args) {
     // Legacy compatibility from node-athom-api
@@ -199,10 +195,16 @@ class Device extends Item {
       }), {});
   }
 
-  static transform(item) {
-    for (const capabilityObj of Object.values(item.capabilitiesObj)) {
-      if (capabilityObj.lastUpdated) {
-        capabilityObj.lastUpdated = new Date(capabilityObj.lastUpdated);
+  static transformGet(item) {
+    item = super.transformGet(item);
+
+    delete item.driverUri;
+
+    if (item.capabilitiesObj) {
+      for (const capabilityObj of Object.values(item.capabilitiesObj)) {
+        if (capabilityObj.lastUpdated) {
+          capabilityObj.lastUpdated = new Date(capabilityObj.lastUpdated);
+        }
       }
     }