homey-api 1.6.0 → 1.7.2

package/assets/templates/jsdoc/api.ejs

@@ -0,0 +1,59 @@
+// Class
+
+/**
+ * @class <%= Api.name %>
+ *
+ * @description
+ * <% if(Api.JSDOC_DESCRIPTION) { %>
+ <%- Api.JSDOC_DESCRIPTION.split('\n').join('\n *'); %>
+ * <% } %>
+ * This API is available at `https://<%= Api.SPECIFICATION.host %><%= Api.SPECIFICATION.basePath %>`
+ * 
+ * <% if(Api.JSDOC_EXAMPLE) { %>
+ * @example <%- Api.JSDOC_EXAMPLE %>
+ * <% } %>
+ * 
+ * <% if(Api.JSDOC_PRIVATE === true) { %>
+ * @private
+ * <% } %>
+ * 
+ * @param {object} [opts]
+ * @param {string} [opts.baseUrl=`https://<%= Api.SPECIFICATION.host %><%= Api.SPECIFICATION.basePath %>`] - The Base URL of the API. Set `<%= envKey %>_BASEURL=http://...` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
+ * @param {boolean} [opts.debug=false] - Send debug messages to `console.log` if set to `true`. Set `<%= envKey %>_DEBUG=1` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
+ * @param {secret} [opts.secret] - A shared secret for APIs with a `secret` parameter in an endpoint. Set `<%= envKey %>_SECRET=...` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
+ * <% if( Api.JSDOC_PARAMS ) { %>
+ <%- Api.JSDOC_PARAMS.split('\n').join('\n *'); %>
+ * <% } %>
+ */
+
+// Methods
+<% Object.entries(Api.SPECIFICATION.operations).forEach(([ operationId, operation ]) => { %>
+/**
+ * <h4>HTTP</h4>
+ * 
+ * `<%= String(operation.method).toUpperCase() %> <%= operation.path %>`
+ * 
+ * @async
+ * @function <%= Api.name %>#<%= operationId %>
+ * <% if(operation.private) { %>
+ * @private
+ * <% } %>
+ *
+ * <% if (Object.keys(operation.parameters || {}).length) { %>
+ * @param {object} opts
+ * <% Object.entries(operation.parameters).forEach(([parameterId, parameter]) => { %>
+ * <% if (parameter.required) { %>
+ * @param {<%= String(parameter.type).replace(/\,/g, '|') %>} opts.<%= parameterId %> - In `<%= parameter.in %>` <% if( parameter.unpack ) { %><span>(unpacked)</span><% } %>
+ * <% } else { %>
+ * @param {<%= String(parameter.type).replace(/\,/g, '|') %>} [opts.<%= parameterId %>] - In `<%= parameter.in %>` <% if( parameter.unpack ) { %><span>(unpacked)</span><% } %>
+ * <% } %>
+ * <% if (Object.keys(parameter.properties || {}).length) { %>
+ * <% Object.entries(parameter.properties).forEach(([propertyId, property]) => { %>
+ * @param {<%= String(property.type).replace(/\,/g, '|') %>} opts.<%= parameterId %>.<%= propertyId %>
+ * <% }) %>
+ * <% } %>
+ * <% }) %>
+ * <% } %>
+ *
+ */
+<% }) %>

package/assets/templates/jsdoc/item.ejs

@@ -0,0 +1,35 @@
+// Class
+
+/**
+* <%= itemName %> as returned by {@link <%= HomeyAPI %>.<%= managerName %>}.
+* @class <%= itemName %>
+* @hideconstructor
+* @memberof <%= HomeyAPI %>.<%= managerName %>
+*
+* <% if(manager.private) { %>
+* @private
+* <% } %>
+*/
+
+// Properties
+
+<% if (item.schema) { %>
+<% for (const [propertyId, property] of Object.entries(item.schema.properties || {}) ) { %>
+/**
+  * <% if (property.type) { %>
+  * @var {<%= String(property.type || '*').replace(/\,/g, '|') %>} <%= HomeyAPI %>.<%= managerName %>.<%= itemName %>#<%= propertyId %>
+  * <% } %>
+  */
+<% } %>
+<% } %>
+    
+/**
+* @memberof <%= HomeyAPI %>.<%= managerName%>.<%= itemName %>
+* @event update
+* @param {object} <%= item.id %>
+*/
+
+/**
+* @memberof <%= HomeyAPI %>.<%= managerName%>.<%= itemName %>
+* @event delete
+*/

package/assets/templates/jsdoc/manager.ejs

@@ -0,0 +1,76 @@
+// Class
+
+/**
+* @description Access this instance at `{@link <%= HomeyAPI %>}.<%= manager.idCamelCase; %>`.
+* @class <%= managerName %>
+* @hideconstructor
+* @extends <%= HomeyAPI %>.Manager
+* @memberof <%= HomeyAPI %>
+* 
+* <% if(manager.private) { %>
+* @private
+* <% } %>
+*/
+
+// Methods
+<% Object.entries(manager.operations || {}).forEach(([ operationId, operation ]) => { %>
+  /**
+  * <h4>Scopes</h4>
+  * 
+  * `<%= operation.scopes.length ? operation.scopes.join(', ') : '-' %>`
+  * 
+  * <h4>HTTP</h4>
+  * 
+  * `<%= operation.method %> /api/manager/<%= manager.id %><%= operation.path %>`
+  * 
+  * @async
+  * @function <%= HomeyAPI %>.<%= managerName %>#<%= operationId %>
+  * <% if(operation.private) { %>
+  * @private
+  * <% } %>
+  *
+  * <% if (Object.keys(operation.parameters || {}).length) { %>
+  * @param {object} opts
+  * <% Object.entries(operation.parameters).forEach(([ parameterId, parameter ]) => { %>
+  * <% if (parameter.required) { %>
+  * @param {<%= String(parameter.type || '*').replace(/\,/g, '|') %>} opts.<%= parameterId %>
+  * <% } else { %>
+  * @param {<%= String(parameter.type || '*').replace(/\,/g, '|') %>} [opts.<%= parameterId %>]
+  * <% } %>
+  * <% }) %>
+  * <% } %>
+  *
+  * <% if(operation.crud) { %>
+  * <% if(operation.crud.type === 'getOne' || operation.crud.type === 'createOne' || operation.crud.type === 'updateOne') { %>
+  * @returns {Promise<<%= HomeyAPI %>.<%= managerName %>.<%= operation.crud.item %>>}
+  * <% } else if(operation.crud.type === 'getAll') { %>
+  * @returns {Promise<<%= HomeyAPI %>.<%= managerName %>.<%= operation.crud.item %>>}
+  * <% } %>
+  * <% } else { %>
+  * @returns {Promise<any>}
+  * <% } %>
+  */
+<% }) %>
+
+
+
+// CRUD Events
+<% Object.entries(manager.items || {}).forEach(([ itemName, item ]) => { %>
+/**
+* @memberof <%= HomeyAPI %>.<%= managerName%>
+* @event "<%= item.id %>.create"
+* @param {<%= HomeyAPI %>.<%= managerName %>.<%= itemName %>} <%= item.id %>
+*/
+
+/**
+* @memberof <%= HomeyAPI %>.<%= managerName%>
+* @event "<%= item.id %>.update"
+* @param {<%= HomeyAPI %>.<%= managerName %>.<%= itemName %>} <%= item.id %>
+*/
+
+/**
+* @memberof <%= HomeyAPI %>.<%= managerName%>
+* @event "<%= item.id %>.delete"
+* @param {<%= HomeyAPI %>.<%= managerName %>.<%= itemName %>} <%= item.id %>
+*/
+<% }) %>

package/assets/templates/types/declaration.ejs

@@ -0,0 +1,62 @@
+<%
+function jsdocToTypescript(type) {
+  return type.names
+    .flatMap(type => type.split('|'))
+    .map(type => {
+      if (type === 'secret') return 'string';
+      if (type === 'array') return 'Array<any>';
+      if (type === 'date') return 'string';
+      // replace Promise.<> with Promise<>
+      return type.replace(/\.\</g, '<');
+    })
+    .join(' | ');
+}
+%>
+
+<% function renderParam(params) { %>
+  <% Object.entries(params).forEach(([key, value]) => { %>
+    <% if (typeof value === 'object') { %>
+      <%= key %>: {<%= renderParam(value) %>},
+    <% } else { %>
+      <%= key %>: <%- jsdocToTypescript({ names: [value] }) %>,
+    <% } %>
+  <% }) %>
+<% } %>
+
+<% function renderClass(namespaceClass) { %>
+  export class <%= namespaceClass.name %> <%= Array.isArray(namespaceClass.augments) ? 'extends ' + namespaceClass.augments[0] : '' %> {
+    <% if (namespaceClass.constructor && namespaceClass.hideconstructor !== true) { %>
+      constructor(
+        <% if (namespaceClass.constructor.params) { %>
+          <%= renderParam(namespaceClass.constructor.params) %>
+        <% } %>
+      )
+    <% } %>
+
+    <% namespaceClass.members.forEach(classMember => { %>
+      <%= classMember.name %>: <%- jsdocToTypescript(classMember.type) %>;
+    <% }) %>
+
+    <% namespaceClass.functions.forEach(classFunction => { %>
+      <%= classFunction.name %>(
+        <% if (classFunction.params) { %>
+          <%= renderParam(classFunction.params) %>
+        <% } %>
+      ):
+        <%- classFunction.returns
+           ? jsdocToTypescript(classFunction.returns[0].type)
+           : classFunction.async ? 'Promise<any>' : 'any'
+        %>;
+    <% }) %>
+  }
+<% } %>
+
+<% global.forEach(globalClass => renderClass(globalClass)) %>
+
+<% Object.entries(namespaces).forEach(([namespaceId, namespaceClasses]) => { %>
+  <% if (namespaceClasses.length) { %>
+    export namespace <%= namespaceId %> {
+      <% namespaceClasses.forEach(namespaceClass => renderClass(namespaceClass)) %>
+    }
+  <% } %>
+<% }); %>

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;
@@ -304,10 +315,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 +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,
@@ -358,10 +377,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 +438,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 +483,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 +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/lib/Util.js

@@ -22,7 +22,6 @@ class Util {
       return fetch(...args);
     }
 
-    // If in a browser
     if (this.isBrowser()) {
       return window.fetch(...args);
     }
@@ -138,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;
   }
 
   /**

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "homey-api",
-  "version": "1.6.0",
+  "version": "1.7.2",
   "description": "Homey API",
   "main": "index.js",
+  "files": [
+    "/lib",
+    "/assets",
+    "/index.js",
+    "/index.browser.js"
+  ],
   "types": "assets/types/homey-api.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -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",
@@ -72,4 +78,4 @@
     "not IE 11",
     "not IE_Mob 11"
   ]
-}
+}