homey-api 1.6.1 → 1.7.3

package/assets/types/homey-api.d.ts

@@ -201,6 +201,29 @@
       ):
         Promise<void>;
     
+      authenticateWithAuthorizationCode(
+        
+          
+  
+    
+      opts: {
+  
+    
+      code: String,
+    
+  
+    
+      removeCodeFromHistory: Boolean,
+    
+  
+},
+    
+  
+
+        
+      ):
+        Promise<AthomCloudAPI.Token>;
+    
   }
 
   export class HomeyAPI  {

package/assets/types/homey-api.private.d.ts

@@ -2985,6 +2985,73 @@
       ):
         Promise<void>;
     
+      authenticateWithAuthorizationCode(
+        
+          
+  
+    
+      opts: {
+  
+    
+      code: String,
+    
+  
+    
+      removeCodeFromHistory: Boolean,
+    
+  
+},
+    
+  
+
+        
+      ):
+        Promise<AthomCloudAPI.Token>;
+    
+      updateUserMe(
+        
+          
+  
+    
+      opts: {
+  
+    
+      firstname: String,
+    
+  
+    
+      lastname: String,
+    
+  
+    
+      email: String,
+    
+  
+},
+    
+  
+
+        
+      ):
+        Promise<AthomCloudAPI.User>;
+    
+      updateUserMeAvatar(
+        
+          
+  
+    
+      imageBuffer: Buffer,
+    
+  
+    
+      imageType: "jpg" | "jpeg" | "png" | "gif",
+    
+  
+
+        
+      ):
+        Promise<Object>;
+    
   }
 
   export class AthomConnectAPI  {

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 = `
@@ -198,6 +206,9 @@ for(const device of Object.values(devices)) {
    * @returns {Promise<void>}
    */
   async logout() {
+    // Delete Cached User
+    this.__user = null;
+
     // Delete Token from Store
     await this.__resetStore();
     this.__token = null;
@@ -307,7 +318,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 +344,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 +380,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 +441,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 +486,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 +522,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 avatar
+   * @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,8 +1,15 @@
 {
   "name": "homey-api",
-  "version": "1.6.1",
+  "version": "1.7.3",
   "description": "Homey API",
   "main": "index.js",
+  "files": [
+    "/lib",
+    "/assets/specifications",
+    "/assets/types",
+    "/index.js",
+    "/index.browser.js"
+  ],
   "types": "assets/types/homey-api.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -11,12 +18,11 @@
     "build": "npm run build:specs; npm run build:jsdoc; npm run build:types; npm run build:webpack;",
     "build:webpack": "npm run webpack",
     "build:webpack:watch": "npm run webpack:watch",
-    "build:jsdoc": "npm run jsdoc:clean; npm run generate-specs; npm run generate-jsdoc; npm run jsdoc;",
     "build:types": "npm run generate-types;",
     "build:specs": "npm run generate-specs",
     "webpack": "webpack",
     "webpack:watch": "webpack --watch",
-    "jsdoc": "jsdoc --configure ./jsdoc.json --recurse --destination build/jsdoc; jsdoc --configure ./jsdoc.json --recurse --private --destination build/jsdoc/private; rm build/jsdoc/*.js.html;",
+    "jsdoc": "npm run jsdoc:clean; npm run generate-specs; npm run generate-jsdoc; jsdoc --configure ./jsdoc.json --recurse; jsdoc --configure ./jsdoc.json --recurse --private --destination ./jsdoc/private; rm ./jsdoc/*.js.html;",
     "jsdoc:clean": "rm -rf ./build/jsdoc; rm -rf ./build/jsdoc-tmp",
     "jsdoc:watch": "watch \"npm run jsdoc:clean; npm run generate-jsdoc; npm run jsdoc;\" lib \"node_modules/homey-jsdoc-template\" --interval 0.5",
     "jsdoc:serve": "http-server ./build/jsdoc/",
@@ -44,6 +50,7 @@
     "socket.io-client": "^1.7.4"
   },
   "devDependencies": {
+    "@athombv/jsdoc-template": "^1.6.1",
     "@babel/core": "^7.16.0",
     "@babel/plugin-proposal-class-properties": "^7.16.0",
     "@babel/preset-env": "^7.16.0",
@@ -53,7 +60,6 @@
     "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",
     "http-server": "^0.12.3",
     "jsdoc": "^3.6.7",
     "jsdoc-to-markdown": "^7.1.0",