homey-api 1.4.4 → 1.5.0

package/README.md

@@ -40,6 +40,10 @@ Include Homey API from our CDN:
 
 You can then access the APIs using `window.AthomCloudAPI` etc.
 
+### In-app
+
+To use Homey API inside of an Homey Pro app with the `homey:manager:api` permission, see {@link HomeyAPIApp}.
+
 ## Issues
 
 Please report any issues you find in the [Web API Issue Tracker](https://github.com/athombv/homey-web-api-issues/issues).

package/index.js

@@ -21,4 +21,5 @@ module.exports = {
   AthomWeatherAPI: require('./lib/AthomWeatherAPI'),
   AthomWebhooksAPI: require('./lib/AthomWebhooksAPI'),
   HomeyCloudAPI: require('./lib/HomeyCloudAPI'),
+  HomeyAPIApp: require('./lib/HomeyAPI/HomeyAPIApp'),
 };

package/lib/HomeyAPI/HomeyAPIApp.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const HomeyAPI = require('./HomeyAPI');
+const HomeyAPIV2 = require('./HomeyAPIV2');
+
+/**
+ * Use this class to utilize Homey Pro's Web API from inside an app.
+ *
+ * > This class only works on apps using Apps SDK v3 running on Homey Pro.
+ *
+ * > Make sure your app has the `homey:manager:api` permission.
+ *
+ * @class
+ * @extends HomeyAPIV2
+ * @example
+ * // app.json
+ * {
+ *   ...
+ *   "platforms": [ "local" ],
+ *   "permissions": [ "homey:manager:api" ],
+ * }
+ *
+ * // app.js
+ * const { Homey } = require('homey');
+ * const { HomeyAPIApp } = require('homey-api');
+ *
+ * class MyApp extends Homey.App {
+ *
+ *   async onInit() {
+ *     const api = new HomeyAPIApp({
+ *       homey: this.homey,
+ *     });
+ *
+ *     const devices = await api.devices.getDevices();
+ *     this.log('Devices:', devices);
+ *   }
+ *
+ * }
+ */
+class HomeyAPIApp extends HomeyAPIV2 {
+
+  /**
+   * Possible Discovery Strategies
+   * @static
+   * @property {object} DISCOVERY_STRATEGIES
+   * @property {string} DISCOVERY_STRATEGIES.LOCAL - Local HTTP, e.g. `http://192.168.1.100`.
+   */
+  static DISCOVERY_STRATEGIES = {};
+
+  constructor({
+    homey,
+    debug = false,
+    ...props
+  }) {
+    super({
+      ...props,
+      api: null,
+      properties: {
+        id: 'local',
+        softwareVersion: null,
+      },
+      strategy: [
+        HomeyAPI.DISCOVERY_STRATEGIES.LOCAL,
+      ],
+    });
+
+    Object.defineProperty(this, '__homeySDK', {
+      value: homey,
+      enumerable: false,
+      writable: true,
+    });
+
+    Object.defineProperty(this, '__debugEnabled', {
+      value: !!debug,
+      enumerable: false,
+      writable: true,
+    });
+  }
+
+  __debug(...props) {
+    if (!this.__debugEnabled) return;
+    this.__homeySDK.log('[homey-api]', `[${this.constructor.name}]`, ...props);
+  }
+
+  async login() {
+    if (!this.__loginPromise) {
+      this.__loginPromise = Promise.resolve().then(async () => {
+        const token = await this.__homeySDK.api.getOwnerApiToken();
+        this.__debug(`Local Token: ${token}`);
+        return token;
+      });
+
+      this.__loginPromise
+        .then(token => {
+          this.__token = token;
+        })
+        .catch(err => {
+          this.__debug('Error Logging In:', err);
+        })
+        .finally(() => {
+          this.__loginPromise = null;
+        });
+    }
+
+    return this.__loginPromise;
+  }
+
+  async discoverBaseUrl() {
+    this.__baseUrl = await this.__homeySDK.api.getLocalUrl();
+    this.__strategyId = 'local';
+
+    this.__debug(`Local URL: ${this.__baseUrl}`);
+
+    return {
+      baseUrl: this.__baseUrl,
+      strategyId: this.__strategyId,
+    };
+  }
+
+}
+
+module.exports = HomeyAPIApp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homey-api",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Homey API",
   "main": "src/index.js",
   "types": "assets/types/homey-api.d.ts",