homey-api 3.0.0 → 3.0.2

package/lib/AthomCloudAPI/User.js

@@ -59,6 +59,10 @@ class User extends APIDefinition {
     return homey;
   }
 
+  hasRole(roleId) {
+    return this.roleIds.includes(roleId);
+  }
+
 }
 
 module.exports = User;

package/lib/HomeyAPI/HomeyAPI.js

@@ -80,8 +80,15 @@ class HomeyAPI {
     });
 
     // Set Language
-    Object.defineProperty(this, 'Language', {
-      value: properties.Language ?? null,
+    Object.defineProperty(this, 'language', {
+      value: properties.language ?? null,
+      enumerable: true,
+      writable: true,
+    });
+
+    // Set Role
+    Object.defineProperty(this, 'role', {
+      value: properties.role ?? null,
       enumerable: true,
       writable: true,
     });
@@ -158,6 +165,14 @@ class HomeyAPI {
     return null;
   }
 
+  /**
+   * Check the current role.
+   * @param {string} roleId - The role ID, e.g. `owner`, `manager`, `user` or `guest`.
+   */
+  hasRole(roleId) {
+    return this.role === roleId;
+  }
+
   /**
    * Creates a {@link HomeyAPIV3Local} or {@link HomeyAPIV2} instance for use in the Apps SDK.
    * @param {Object} opts

package/lib/HomeyAPI/HomeyAPIV2/Manager.js

@@ -7,6 +7,7 @@ const HomeyAPIV3Manager = require('../HomeyAPIV3/Manager');
 /**
  * @class
  * @hideconstructor
+ * @extends HomeyAPIV3.Manager
  * @memberof HomeyAPIV2
  */
 class Manager extends HomeyAPIV3Manager {

package/lib/HomeyAPI/HomeyAPIV2/ManagerDevices.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const Manager = require('./Manager');
+const ManagerDevicesV3 = require('../HomeyAPIV3/ManagerDevices');
 const Capability = require('./ManagerDevices/Capability');
 const Device = require('./ManagerDevices/Device');
 
-class ManagerDevices extends Manager {
+class ManagerDevices extends ManagerDevicesV3 {
 
   static CRUD = {
     ...super.CRUD,

package/lib/HomeyAPI/HomeyAPIV2/ManagerDevkit.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const ManagerDevkitV3 = require('../HomeyAPIV3Local/ManagerDevkit');
+
+class ManagerDevkit extends ManagerDevkitV3 {
+
+}
+
+module.exports = ManagerDevkit;

package/lib/HomeyAPI/HomeyAPIV2/ManagerFlow.js

@@ -1,13 +1,13 @@
 'use strict';
 
-const Manager = require('./Manager');
+const ManagerFlowV3 = require('../HomeyAPIV3/ManagerFlow');
 const Flow = require('./ManagerFlow/Flow');
 const AdvancedFlow = require('./ManagerFlow/AdvancedFlow');
 const FlowCardTrigger = require('./ManagerFlow/FlowCardTrigger');
 const FlowCardCondition = require('./ManagerFlow/FlowCardCondition');
 const FlowCardAction = require('./ManagerFlow/FlowCardAction');
 
-class ManagerFlow extends Manager {
+class ManagerFlow extends ManagerFlowV3 {
 
   static CRUD = {
     ...super.CRUD,

package/lib/HomeyAPI/HomeyAPIV2.js

@@ -5,6 +5,7 @@ const ManagerFlow = require('./HomeyAPIV2/ManagerFlow');
 const ManagerFlowToken = require('./HomeyAPIV2/ManagerFlowToken');
 const ManagerDevices = require('./HomeyAPIV2/ManagerDevices');
 const ManagerDrivers = require('./HomeyAPIV2/ManagerDrivers');
+const ManagerDevkit = require('./HomeyAPIV2/ManagerDevkit');
 const ManagerInsights = require('./HomeyAPIV2/ManagerInsights');
 
 /**
@@ -22,6 +23,7 @@ class HomeyAPIV2 extends HomeyAPIV3 {
     ManagerFlowToken,
     ManagerDevices,
     ManagerDrivers,
+    ManagerDevkit,
     ManagerInsights,
   };
 

package/lib/HomeyAPI/HomeyAPIV3/Item.js

@@ -2,6 +2,12 @@
 
 const EventEmitter = require('../../EventEmitter');
 
+/**
+ * A superclass for all CRUD Items.
+ * @class
+ * @hideconstructor
+ * @memberof HomeyAPIV3
+ */
 class Item extends EventEmitter {
 
   static ID = null; // Set by Manager.js
@@ -14,22 +20,21 @@ class Item extends EventEmitter {
   }) {
     super();
 
-    // Set ID
-    Object.defineProperty(this, 'id', {
+    Object.defineProperty(this, '__id', {
       value: id,
       enumerable: true,
       writable: false,
     });
 
     // Set Homey
-    Object.defineProperty(this, 'homey', {
+    Object.defineProperty(this, '__homey', {
       value: homey,
       enumerable: false,
       writable: false,
     });
 
     // Set Manager
-    Object.defineProperty(this, 'manager', {
+    Object.defineProperty(this, '__manager', {
       value: manager,
       enumerable: false,
       writable: false,
@@ -54,10 +59,38 @@ class Item extends EventEmitter {
     }
   }
 
+  /**
+   * The ID of the Item.
+   * @type {String}
+   */
+  get id() {
+    return this.__id;
+  }
+
+  /**
+   * The URI of the Item, e.g. `homey:foo:bar`.
+   * @type {String}
+   */
   get uri() {
     return `homey:${this.constructor.ID}:${this.id}`;
   }
 
+  /**
+   * The Manager of the Item.
+   * @type {HomeyAPIV3.Manager}
+   */
+  get manager() {
+    return this.__manager;
+  }
+
+  /**
+   * The Homey of the Item.
+   * @type {HomeyAPIV3}
+   */
+  get homey() {
+    return this.__homey;
+  }
+
   __debug(...props) {
     this.manager.__debug(`[${this.constructor.name}:${this.id}]`, ...props);
   }
@@ -77,6 +110,9 @@ class Item extends EventEmitter {
     this.emit('delete');
   }
 
+  /**
+   * Connect to this item's Socket.io namespace.
+   */
   async connect() {
     this.__debug('connect');
 
@@ -130,6 +166,9 @@ class Item extends EventEmitter {
     await this.__connectPromise;
   }
 
+  /**
+   * Discconnect from this item's Socket.io namespace.
+   */
   async disconnect() {
     this.__debug('disconnect');
 

package/lib/HomeyAPI/HomeyAPIV3/Manager.js

@@ -12,6 +12,7 @@ const Item = require('./Item');
 /**
  * @class
  * @hideconstructor
+ * @extends EventEmitter
  * @memberof HomeyAPIV3
  */
 class Manager extends EventEmitter {
@@ -27,7 +28,7 @@ class Manager extends EventEmitter {
     super();
 
     // Set Homey
-    Object.defineProperty(this, 'homey', {
+    Object.defineProperty(this, '__homey', {
       value: homey,
       enumerable: false,
       writable: false,
@@ -357,6 +358,18 @@ class Manager extends EventEmitter {
     }
   }
 
+  /**
+   * The Homey of the Manager.
+   * @type {HomeyAPIV3}
+   */
+  get homey() {
+    return this.__homey;
+  }
+
+  /**
+   * The URI of the Item, e.g. `homey:manager:bar`.
+   * @type {String}
+   */
   get uri() {
     return `homey:manager:${this.constructor.ID}`;
   }
@@ -374,7 +387,7 @@ class Manager extends EventEmitter {
   }
 
   /**
-   * Connect to the realtime namespace.
+   * Connect to this manager's Socket.io namespace.
    * @returns {Promise<void>}
    */
   async connect() {
@@ -476,7 +489,7 @@ class Manager extends EventEmitter {
   }
 
   /**
-   * Disconnect from the realtime namespace.
+   * Discconnect from this manager's Socket.io namespace.
    * @returns {Promise<void>}
    */
   async disconnect() {
@@ -509,6 +522,9 @@ class Manager extends EventEmitter {
     await this.__disconnectPromise;
   }
 
+  /**
+   * Destroy this Manager by cleaning up all references, unbinding event listeners and disconnecting from the Socket.io namespace.
+   */
   destroy() {
     // Clear cache
     for (const id of Object.keys(this.__cache)) {

package/lib/HomeyAPI/HomeyAPIV3/ManagerApps/App.js

@@ -2,8 +2,22 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerApps
+ */
 class App extends Item {
 
+  /**
+   * Call the app's API endpoint.
+   * @param {Object} opts
+   * @param {('GET'|'POST'|'PUT'|'DELETE')} opts.method HTTP Method of the API endpoint.
+   * @param {String} opts.path - Path to the API endpoint.
+   * @param {mixed} opts.body
+   * @returns {Promise<any>}
+   */
   async call({
     method,
     path,
@@ -35,7 +49,6 @@ class App extends Item {
    * @param {object} opts
    * @param {string} opts.path
    * @returns {Promise<any>}
-   * @function HomeyAPIV2.ManagerApps.App#get
    */
   async get({ path }) {
     return this.call({
@@ -50,7 +63,6 @@ class App extends Item {
    * @param {string} opts.path
    * @param {object} opts.body
    * @returns {Promise<any>}
-   * @function HomeyAPIV2.ManagerApps.App#post
    */
   async post({ path, body }) {
     return this.call({
@@ -66,7 +78,6 @@ class App extends Item {
    * @param {string} opts.path
    * @param {object} opts.body
    * @returns {Promise<any>}
-   * @function HomeyAPIV2.ManagerApps.App#put
    */
   async put({ path, body }) {
     return this.call({
@@ -81,7 +92,6 @@ class App extends Item {
    * @param {object} opts
    * @param {string} opts.path
    * @returns {Promise<any>}
-   * @function HomeyAPIV2.ManagerApps.App#delete
    */
   async delete({ path }) {
     return this.call({

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

@@ -2,6 +2,12 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerDevices
+ */
 class Capability extends Item {
 
 }

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

@@ -4,6 +4,12 @@ const Util = require('../../../Util');
 const Item = require('../Item');
 const DeviceCapability = require('./DeviceCapability');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerDevices
+ */
 class Device extends Item {
 
   constructor(...props) {
@@ -134,18 +140,30 @@ class Device extends Item {
     }
   }
 
+  /**
+   * Get the device's zone.
+   * @returns {Promise<HomeyAPIV3.ManagerZones.Zone>}
+   */
   async getZone() {
     return this.homey.zones.getZone({
       id: this.zone,
     });
   }
 
+  /**
+   * Get the device's driver.
+   * @returns {Promise<HomeyAPIV3.ManagerDrivers.Driver>}
+   */
   async getDriver() {
     return this.homey.drivers.getDriver({
       id: this.driverId,
     });
   }
 
+  /**
+   * Get the device's logs.
+   * @returns {Promise<{String, HomeyAPIV3.ManagerInsights.Log}>}
+   */
   async getLogs() {
     const logs = await this.homey.insights.getLogs();
     return Object.values(logs)
@@ -156,6 +174,10 @@ class Device extends Item {
       }), {});
   }
 
+  /**
+   * Get the device's flows.
+   * @returns {Promise<{String, HomeyAPIV3.ManagerFlow.Flow}>}
+   */
   async getFlows() {
     const flows = await this.homey.flow.getFlows();
     return Object.values(flows)
@@ -175,6 +197,10 @@ class Device extends Item {
       }), {});
   }
 
+  /**
+   * @returns {Promise<{String, HomeyAPIV3.ManagerFlow.AdvancedFlow}>}
+   * @returns {Promise<Object>}
+   */
   async getAdvancedFlows() {
     const advancedFlows = await this.homey.flow.getAdvancedFlows();
     return Object.values(advancedFlows)

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

@@ -6,6 +6,7 @@ const EventEmitter = require('../../../EventEmitter');
 /**
  * @class
  * @hideconstructor
+ * @extends EventEmitter
  * @memberof HomeyAPIV3.ManagerDevices.Device
  */
 class DeviceCapability extends EventEmitter {

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

@@ -1,7 +1,12 @@
 'use strict';
 
 const Item = require('../Item');
-
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerDrivers
+ */
 class Driver extends Item {
 
 }

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

@@ -1,7 +1,12 @@
 'use strict';
 
 const Item = require('../Item');
-
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerDrivers
+ */
 class PairSession extends Item {
 
 }

package/lib/HomeyAPI/HomeyAPIV3/ManagerDrivers.js

@@ -4,6 +4,12 @@ const Manager = require('./Manager');
 const Driver = require('./ManagerDrivers/Driver');
 const PairSession = require('./ManagerDrivers/PairSession');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Manager
+ * @memberof HomeyAPIV3
+ */
 class ManagerDrivers extends Manager {
 
   static CRUD = {

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

@@ -4,8 +4,18 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class AdvancedFlow extends Item {
 
+  /**
+   * Check whether this Flow misses one or more {@link FlowCard} or {@link FlowToken}.
+   * @returns Promise<Boolean> - A boolean whether this Flow is broken.
+   */
   async isBroken() {
     const managerFlow = this.homey.flow;
     if (!managerFlow.isConnected()) {

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

@@ -4,11 +4,17 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class Flow extends Item {
 
   /**
    * Check whether this Flow misses one or more {@link FlowCard} or {@link FlowToken}.
-   * @returns Promise<Boolean>
+   * @returns Promise<Boolean> - A boolean whether this Flow is broken.
    */
   async isBroken() {
     const managerFlow = this.homey.flow;

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

@@ -2,6 +2,12 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class FlowCard extends Item {
 
   static transformGet(item) {

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

@@ -2,6 +2,12 @@
 
 const FlowCard = require('./FlowCard');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class FlowCardAction extends FlowCard {
 
 }

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

@@ -2,6 +2,12 @@
 
 const FlowCard = require('./FlowCard');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class FlowCardCondition extends FlowCard {
 
 }

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

@@ -2,6 +2,12 @@
 
 const FlowCard = require('./FlowCard');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlow
+ */
 class FlowCardTrigger extends FlowCard {
 
 }

package/lib/HomeyAPI/HomeyAPIV3/ManagerFlowToken/FlowToken.js

@@ -2,6 +2,12 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerFlowToken
+ */
 class FlowToken extends Item {
 
   static transformGet(item) {

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

@@ -2,6 +2,12 @@
 
 const Item = require('../Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @extends HomeyAPIV3.Item
+ * @memberof HomeyAPIV3.ManagerInsights
+ */
 class Log extends Item {
 
   async getEntries() {

package/lib/HomeyAPI/HomeyAPIV3.js

@@ -395,9 +395,13 @@ class HomeyAPIV3 extends HomeyAPI {
       headers['Authorization'] = `Bearer ${this.__token}`;
     }
 
-    if (body && json === true && ['PUT', 'POST'].includes(method)) {
-      headers['Content-Type'] = 'application/json';
-      body = JSON.stringify(body);
+    if (['PUT', 'POST'].includes(method)) {
+      if (body && json === true) {
+        headers['Content-Type'] = 'application/json';
+        body = JSON.stringify(body);
+      }
+    } else {
+      body = undefined;
     }
 
     this.__debug(method, `${baseUrl}${path}`);

package/lib/HomeyAPI/HomeyAPIV3Cloud/Item.js

@@ -2,6 +2,12 @@
 
 const HomeyAPIV3Item = require('../HomeyAPIV3/Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @memberof HomeyAPIV3Cloud
+ * @extends HomeyAPIV3.Item
+ */
 class Item extends HomeyAPIV3Item {
 
 }

package/lib/HomeyAPI/HomeyAPIV3Local/Item.js

@@ -2,6 +2,12 @@
 
 const HomeyAPIV3Item = require('../HomeyAPIV3/Item');
 
+/**
+ * @class
+ * @hideconstructor
+ * @memberof HomeyAPIV3Local
+ * @extends HomeyAPIV3.Item
+ */
 class Item extends HomeyAPIV3Item {
 
 }

package/lib/HomeyAPI/HomeyAPIV3Local/ManagerDevkit.js

@@ -6,8 +6,18 @@ const Manager = require('./Manager');
 
 class ManagerDevkit extends Manager {
 
+  /**
+   * Upload & run an app on Homey Pro.
+   * @param {Object} opts
+   * @param {ReadableStream} opts.app - A .tar.gz filestream.
+   * @param {Object} opts.env - Environment variables.
+   * @param {Boolean} opts.debug - Enable debug mode.
+   * @param {Boolean} opts.clean - Purge all app settings before running the app.
+   * @returns {Promise<any>}
+   * @function HomeyAPIV3Local.ManagerDevkit#runApp
+   */
   async runApp({
-    app, // Readable
+    app,
     env = {},
     debug = false,
     clean = false,
@@ -16,7 +26,7 @@ class ManagerDevkit extends Manager {
     form.append('app', app);
     form.append('env', JSON.stringify(env));
     form.append('debug', debug ? 'true' : 'false');
-    form.append('purgseSettings', clean ? 'true' : 'false');
+    form.append('purgeSettings', clean ? 'true' : 'false');
 
     return this.homey.call({
       $timeout: 1000 * 60 * 5, // 5 minutes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homey-api",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Homey API",
   "main": "index.js",
   "files": [