homey-api 1.6.1 → 1.7.0

package/lib/AthomCloudAPI.js

@@ -35,7 +35,7 @@ and login on that user's Homey.`;
 const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');
 
 // Create an AthomCloudAPI instance
-const api = new AthomCloudAPI({
+const cloudApi = new {@link AthomCloudAPI AthomCloudAPI}({
   clientId: '5a8d4ca6eb9f7a2c9d6ccf6d',
   clientSecret: 'e3ace394af9f615857ceaa61b053f966ddcfb12a',
   redirectUrl: 'http://localhost',
@@ -43,30 +43,38 @@ const api = new AthomCloudAPI({
 
 // Check if we're logged in
 // If not, redirect the user to the OAuth2 dialog
-const loggedIn = await api.isLoggedIn();
+const loggedIn = await {@link AthomCloudAPI cloudApi}.{@link AthomCloudAPI#isLoggedIn isLoggedIn}();
 if (!loggedIn) {
-  if (api.hasAuthorizationCode()) {
-    const token = await api.authenticateWithAuthorizationCode();
+  if ({@link AthomCloudAPI cloudApi}.{@link AthomCloudAPI#hasAuthorizationCode hasAuthorizationCode}()) {
+    const token = await  {@link AthomCloudAPI cloudApi}.{@link AthomCloudAPI#authenticateWithAuthorizationCode authenticateWithAuthorizationCode}();
   } else {
-    window.location.href = api.getLoginUrl();
+    window.location.href =  {@link AthomCloudAPI cloudApi}.{@link AthomCloudAPI#getLoginUrl getLoginUrl}();
     return;
   }
 }
 
 // Get the logged in user
-const user = await cloudApi.getAuthenticatedUser();
+const user = await {@link AthomCloudAPI cloudApi}.{@link AthomCloudAPI#getAuthenticatedUser getAuthenticatedUser}();
 
 // Get the first Homey of the logged in user
-const homey = await user.getFirstHomey();
+const homey = await {@link AthomCloudAPI.User user}.{@link AthomCloudAPI.User#getFirstHomey getFirstHomey}();
 
 // Create a session on this Homey
-const homeyApi = await homey.authenticate();
+const homeyApi = await {@link AthomCloudAPI.Homey homey}.{@link AthomCloudAPI.Homey#authenticate authenticate}();
 
-// Loop all devices
-const devices = await homeyApi.devices.getDevices();
-for(const device of Object.values(devices)) {
+// Get all Zones from ManagerZones
+const zones = await {@link HomeyAPIV2 homeyApi}.{@link HomeyAPIV2.ManagerZones zones}.{@link HomeyAPIV2.ManagerZones#getZones getZones}();
+
+// Get all Devices from ManagerDevices
+const devices = await {@link HomeyAPIV2 homeyApi}.{@link HomeyAPIV2.ManagerDevices devices}.{@link HomeyAPIV2.ManagerDevices#getDevices getDevices}();
+
+// Turn all devices on
+for(const {@link HomeyAPIV2.ManagerDevices.Device device} of Object.values(devices)) {
   // Turn device on
-  await device.setCapabilityValue({ capabilityId: 'onoff', value: true });
+  await {@link HomeyAPIV2.ManagerDevices.Device device}.{@link HomeyAPIV2.ManagerDevices.Device#setCapabilityValue setCapabilityValue}({
+    capabilityId: 'onoff',
+    value: true,
+  });
 }`;
 
   static JSDOC_PARAMS = `
@@ -307,7 +315,7 @@ for(const device of Object.values(devices)) {
       body: body.toString(),
       method: 'post',
       headers: {
-        'Authorization': `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
         'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
@@ -333,6 +341,13 @@ for(const device of Object.values(devices)) {
     return this.__token;
   }
 
+  /**
+   * Authenticate with an authorization code.
+   * @param {Object} [opts]
+   * @param {String} opts.code - Default to `?code=...` when in a browser.
+   * @param {Boolean} [opts.removeCodeFromHistory=true] - Remove `?code=...` from the URL in the address bar.
+   * @returns {Promise<AthomCloudAPI.Token>}
+   */
   async authenticateWithAuthorizationCode({
     code,
     removeCodeFromHistory = true,
@@ -362,7 +377,7 @@ for(const device of Object.values(devices)) {
       body: body.toString(),
       method: 'post',
       headers: {
-        'Authorization': `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
         'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
@@ -423,7 +438,7 @@ for(const device of Object.values(devices)) {
       body: body.toString(),
       method: 'post',
       headers: {
-        'Authorization': `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
         'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
@@ -468,7 +483,7 @@ for(const device of Object.values(devices)) {
           body: body.toString(),
           method: 'post',
           headers: {
-            'Authorization': `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+            Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
             'Content-Type': 'application/x-www-form-urlencoded',
           },
         });
@@ -504,6 +519,76 @@ for(const device of Object.values(devices)) {
     return this.__refreshTokenPromise;
   }
 
+  /**
+   * Update the currently authenticated user.
+   *
+   * @private
+   * @param {Object} [opts]
+   * @param {String} [opts.firstname]
+   * @param {String} [opts.lastname]
+   * @param {String} [opts.email]
+   * @returns {Promise<AthomCloudAPI.User>}
+   */
+  async updateUserMe({
+    firstname,
+    lastname,
+    email,
+  }) {
+    const me = await this.getAuthenticatedUser();
+    return this.updateUser({
+      id: me._id,
+      user: {
+        firstname,
+        lastname,
+        email,
+      },
+    });
+  }
+
+  /**
+   * Update the currently authenticated user's avatar.
+   *
+   * @private
+   * @param {Buffer} imageBuffer Buffer of the new avatat
+   * @param {"jpg"|"jpeg"|"png"|"gif"} imageType Type of the new avatar
+   * @returns {Promise<Object>}
+   */
+  async updateUserMeAvatar(imageBuffer, imageType) {
+    if (!Buffer.isBuffer(imageBuffer)) {
+      throw new Error('Invalid Image. Expected Buffer.');
+    }
+
+    if (!imageType) {
+      throw new Error('Missing Image Type');
+    }
+
+    if (!['jpg', 'png', 'gif'].includes(imageType)) {
+      throw new Error(`Invalid Image Type: ${imageType}`);
+    }
+
+    if (imageType === 'jpg') {
+      imageType = 'jpeg';
+    }
+
+    const me = await this.getAuthenticatedUser();
+    const body = Buffer.concat([
+      Buffer.from(`--__X_HOMEY_BOUNDARY__\r\nContent-Disposition: form-data; name="avatar"; filename="avatar"\r\nContent-Type: image/${imageType}\r\n\r\n`),
+      Buffer.from(imageBuffer),
+      Buffer.from('\r\n--__X_HOMEY_BOUNDARY__--\r\n'),
+    ]);
+
+    return this.call({
+      method: 'POST',
+      path: `/user/${me._id}/avatar`,
+      headers: {
+        'Content-Type': 'multipart/form-data; boundary="__X_HOMEY_BOUNDARY__"',
+        'Content-Length': body.length,
+      },
+      body,
+      bodyJSON: false,
+    });
+  }
+
 }
 
 module.exports = AthomCloudAPI;

package/lib/HomeyAPI/HomeyAPIV2/Device.js

@@ -24,6 +24,14 @@ class Device extends Item {
    * @param {number|boolean|string} listener.value
    * @returns {HomeyAPIV2.ManagerDevices.Device.DeviceCapability}
    * @function HomeyAPIV2.ManagerDevices.Device#makeCapabilityInstance
+   * @example
+   *
+   *  const onOffInstance = device.makeCapabilityInstance('onoff', value => {
+   *    console.log('Device onoff changed to:', value);
+   *  });
+   *
+   * // Turn on
+   * onOffInstance.setValue(true).catch(console.error);
    */
   makeCapabilityInstance(capabilityId, listener) {
     this.connect().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homey-api",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Homey API",
   "main": "index.js",
   "types": "assets/types/homey-api.d.ts",
@@ -53,7 +53,7 @@
     "eslint": "^7.32.0",
     "eslint-config-athom": "^2.1.1",
     "fs-extra": "^10.0.0",
-    "homey-jsdoc-template": "github:athombv/homey-jsdoc-template#1.4",
+    "homey-jsdoc-template": "github:athombv/homey-jsdoc-template#1.5.1",
     "http-server": "^0.12.3",
     "jsdoc": "^3.6.7",
     "jsdoc-to-markdown": "^7.1.0",