homey-api 1.5.30 → 1.7.0

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

@@ -579,7 +579,7 @@
     
   }
 
-  export class StorageAdapterNodeJS extends StorageAdapter {
+  export class StorageAdapterMemory extends StorageAdapter {
     
 
     

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

@@ -5637,6 +5637,15 @@
   
 
         
+      ):
+        boolean;
+    
+      isReactNative(
+        
+          
+  
+
+        
       ):
         boolean;
     
@@ -5844,7 +5853,7 @@
     
   }
 
-  export class StorageAdapterNodeJS extends StorageAdapter {
+  export class StorageAdapterMemory extends StorageAdapter {
     
 
     

package/lib/AthomCloudAPI/StorageAdapter.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Abstract storage adapter. To be extended by your own, or {@link AthomCloudAPI.StorageAdapterBrowser} or {@link AthomCloudAPI.StorageAdapterNodeJS}.
+ * Abstract storage adapter. To be extended by your own, or {@link AthomCloudAPI.StorageAdapterBrowser} or {@link AthomCloudAPI.StorageAdapterMemory}.
  * @class
  * @memberof AthomCloudAPI
  */

package/lib/AthomCloudAPI/{StorageAdapterNodeJS.js → StorageAdapterMemory.js}

@@ -3,12 +3,12 @@
 const StorageAdapter = require('./StorageAdapter');
 
 /**
- * In-memory storage adapter for Node.js.
+ * In-memory storage adapter for Node.js or React Native.
  * @class
  * @extends StorageAdapter
  * @memberof AthomCloudAPI
  */
-class StorageAdapterNodeJS extends StorageAdapter {
+class StorageAdapterMemory extends StorageAdapter {
 
   constructor() {
     super();
@@ -34,4 +34,4 @@ class StorageAdapterNodeJS extends StorageAdapter {
 
 }
 
-module.exports = StorageAdapterNodeJS;
+module.exports = StorageAdapterMemory;

package/lib/AthomCloudAPI.js

@@ -9,7 +9,7 @@ const Homey = require('./AthomCloudAPI/Homey');
 const Token = require('./AthomCloudAPI/Token');
 const StorageAdapter = require('./AthomCloudAPI/StorageAdapter');
 const StorageAdapterBrowser = require('./AthomCloudAPI/StorageAdapterBrowser');
-const StorageAdapterNodeJS = require('./AthomCloudAPI/StorageAdapterNodeJS');
+const StorageAdapterMemory = require('./AthomCloudAPI/StorageAdapterMemory');
 
 class AthomCloudAPI extends API {
 
@@ -18,7 +18,7 @@ class AthomCloudAPI extends API {
   static Token = Token;
   static StorageAdapter = StorageAdapter;
   static StorageAdapterBrowser = StorageAdapterBrowser;
-  static StorageAdapterNodeJS = StorageAdapterNodeJS;
+  static StorageAdapterMemory = StorageAdapterMemory;
 
   static SPECIFICATION = require('../assets/specifications/AthomCloudAPI.json');
   static SPECIFICATION_URL = 'https://api.athom.com/specification.json';
@@ -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 = `
@@ -75,7 +83,7 @@ for(const device of Object.values(devices)) {
 @param {string} opts.redirectUrl
 @param {boolean} [opts.autoRefreshTokens=true]
 @param {AthomCloudAPI.Token} [opts.token=null]
-@param {AthomCloudAPI.StorageAdapter} [opts.store={@link AthomCloudAPI.StorageAdapterBrowser} or {@link AthomCloudAPI.StorageAdapterNodeJS}]`;
+@param {AthomCloudAPI.StorageAdapter} [opts.store={@link AthomCloudAPI.StorageAdapterBrowser} or {@link AthomCloudAPI.StorageAdapterMemory}]`;
 
   constructor({
     clientId,
@@ -85,7 +93,7 @@ for(const device of Object.values(devices)) {
     token = null,
     store = Util.isBrowser()
       ? new StorageAdapterBrowser()
-      : new StorageAdapterNodeJS(),
+      : new StorageAdapterMemory(),
     ...args
   } = {}) {
     super({ ...args });
@@ -304,10 +312,11 @@ for(const device of Object.values(devices)) {
     body.append('grant_type', 'client_credentials');
 
     const response = await Util.fetch(`${this.baseUrl}/oauth2/token`, {
-      body,
+      body: body.toString(),
       method: 'post',
       headers: {
         Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
 
@@ -332,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,
@@ -358,10 +374,11 @@ for(const device of Object.values(devices)) {
     body.append('code', code);
 
     const response = await Util.fetch(`${this.baseUrl}/oauth2/token`, {
-      body,
+      body: body.toString(),
       method: 'post',
       headers: {
         Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
 
@@ -418,10 +435,11 @@ for(const device of Object.values(devices)) {
     body.append('password', password);
 
     const response = await Util.fetch(`${this.baseUrl}/oauth2/token`, {
-      body,
+      body: body.toString(),
       method: 'post',
       headers: {
         Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
       },
     });
 
@@ -462,10 +480,11 @@ for(const device of Object.values(devices)) {
         body.append('refresh_token', this.__token.refresh_token);
 
         const response = await Util.fetch(`${this.baseUrl}/oauth2/token`, {
-          body,
+          body: body.toString(),
           method: 'post',
           headers: {
             Authorization: `Basic ${Util.base64(`${this.__clientId}:${this.__clientSecret}`)}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
           },
         });
 
@@ -500,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/lib/HomeyCloudAPI.js

@@ -1,9 +1,8 @@
 'use strict';
 
-const fetch = require('node-fetch');
-
 const API = require('./API');
 const APIError = require('./APIError');
+const Util = require('./Util');
 
 class HomeyCloudAPI extends API {
 
@@ -26,7 +25,7 @@ class HomeyCloudAPI extends API {
    * @returns {string} result.region - e.g. `eu-central-1`
    */
   static async getClosestRegion() {
-    const res = await fetch(`https://${HomeyCloudAPI.SPECIFICATION.host}`);
+    const res = await Util.fetch(`https://${HomeyCloudAPI.SPECIFICATION.host}`);
     if (!res.ok) {
       throw new Error(res.statusText || 'Unknown Error');
     }
@@ -56,7 +55,7 @@ class HomeyCloudAPI extends API {
    * @returns {Promise<object>} result
    */
   async getSystemStatus({ secret }) {
-    const res = await fetch(`${this.baseUrl}/api/system/status`, {
+    const res = await Util.fetch(`${this.baseUrl}/api/system/status`, {
       headers: {
         'X-Homey-Secret': secret,
       },

package/lib/Util.js

@@ -18,13 +18,22 @@ class Util {
    * @returns {Promise}
    */
   static async fetch(...args) {
-    // If in a browser
+    if (this.isReactNative()) {
+      return fetch(...args);
+    }
+
     if (this.isBrowser()) {
       return window.fetch(...args);
     }
 
-    const fetch = require('node-fetch');
-    return fetch(...args);
+    if (this.isNodeJS()) {
+      const fetch = require('node-fetch');
+      return fetch(...args);
+    }
+
+    if (typeof fetch !== 'undefined') {
+      return fetch(...args);
+    }
   }
 
   /**
@@ -81,17 +90,26 @@ class Util {
     return window.location.protocol === 'http:';
   }
 
+  /**
+   * @returns {boolean}
+   */
+  static isReactNative() {
+    return (typeof navigator !== 'undefined' && navigator.product === 'ReactNative');
+  }
+
   /**
    * @returns {boolean}
    */
   static isBrowser() {
-    return (typeof window !== 'undefined');
+    if (this.isReactNative()) return false;
+    return (typeof document !== 'undefined' && typeof document.window !== 'undefined');
   }
 
   /**
    * @returns {boolean}
    */
   static isNodeJS() {
+    if (this.isReactNative()) return false;
     return (typeof process !== 'undefined');
   }
 
@@ -119,19 +137,58 @@ class Util {
   }
 
   /**
+   * This method encodes a string into a base64 string.
+   * It's provided as Util because Node.js uses `Buffer`,
+   * browsers use `btoa` and React Native doesn't provide anything.
    * @param {string} input - Input
    * @returns {string} - Base64 encoded output
    */
-  static base64(str) {
-    if (typeof btoa === 'function') {
-      return btoa(str);
+  static base64(s) {
+    function btoaLookup(index) {
+      if (index >= 0 && index < 64) {
+        const keystr = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+        return keystr[index];
+      }
+
+      // Throw INVALID_CHARACTER_ERR exception here -- won't be hit in the tests.
+      return undefined;
     }
 
-    if (typeof Buffer !== 'undefined') {
-      return Buffer.from(str).toString('base64');
+    if (typeof s !== 'string') {
+      throw new Error('Invalid Input');
     }
 
-    throw new Error('No Base64 Methods Available');
+    let i;
+
+    // "The btoa() method must throw an "InvalidCharacterError" DOMException if
+    // data contains any character whose code point is greater than U+00FF."
+    for (i = 0; i < s.length; i++) {
+      if (s.charCodeAt(i) > 255) {
+        return null;
+      }
+    }
+    let out = '';
+    for (i = 0; i < s.length; i += 3) {
+      const groupsOfSix = [undefined, undefined, undefined, undefined];
+      groupsOfSix[0] = s.charCodeAt(i) >> 2;
+      groupsOfSix[1] = (s.charCodeAt(i) & 0x03) << 4;
+      if (s.length > i + 1) {
+        groupsOfSix[1] |= s.charCodeAt(i + 1) >> 4;
+        groupsOfSix[2] = (s.charCodeAt(i + 1) & 0x0f) << 2;
+      }
+      if (s.length > i + 2) {
+        groupsOfSix[2] |= s.charCodeAt(i + 2) >> 6;
+        groupsOfSix[3] = s.charCodeAt(i + 2) & 0x3f;
+      }
+      for (let j = 0; j < groupsOfSix.length; j++) {
+        if (typeof groupsOfSix[j] === 'undefined') {
+          out += '=';
+        } else {
+          out += btoaLookup(groupsOfSix[j]);
+        }
+      }
+    }
+    return out;
   }
 
   /**
@@ -161,6 +218,10 @@ class Util {
       return process.env[key] || null;
     }
 
+    if (this.isReactNative()) {
+      return null;
+    }
+
     return null;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homey-api",
-  "version": "1.5.30",
+  "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",