homey-api 1.7.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

@@ -206,6 +206,9 @@ for(const {@link HomeyAPIV2.ManagerDevices.Device device} of Object.values(devic
    * @returns {Promise<void>}
    */
   async logout() {
+    // Delete Cached User
+    this.__user = null;
+
     // Delete Token from Store
     await this.__resetStore();
     this.__token = null;
@@ -549,7 +552,7 @@ for(const {@link HomeyAPIV2.ManagerDevices.Device device} of Object.values(devic
    * Update the currently authenticated user's avatar.
    *
    * @private
-   * @param {Buffer} imageBuffer Buffer of the new avatat
+   * @param {Buffer} imageBuffer Buffer of the new avatar
    * @param {"jpg"|"jpeg"|"png"|"gif"} imageType Type of the new avatar
    * @returns {Promise<Object>}
    */

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "homey-api",
-  "version": "1.7.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.5.1",
     "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"
   ]
-}
+}