Extensive Refactoring

.eslintrc

@@ -0,0 +1,3 @@
+{
+    "extends": "standard"
+}

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,65 @@
+name: CodeQL
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Override automatic language detection by changing the below list
+        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
+        language: ["javascript"]
+        # Learn more...
+        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          # We must fetch at least the immediate parents so that if this is
+          # a pull request then we can checkout the head.
+          fetch-depth: 2
+
+      # If this run was triggered by a pull request event, then checkout
+      # the head of the pull request instead of the merge commit.
+      - run: git checkout HEAD^2
+        if: ${{ github.event_name == 'pull_request' }}
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        with:
+          languages: ${{ matrix.language }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+          # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below)
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v1
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 https://git.io/JvXDl
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+      #    and modify them (or add more) to build your code if your project
+      #    uses a compiled language
+
+      #- run: |
+      #   make bootstrap
+      #   make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1

.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 12.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - name: Upload Test Coverage
+        uses: actions/upload-artifact@v2
+        with:
+          name: coverage
+          path: coverage/
+      - name: Comment Test Coverage
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: romeovs/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -208,8 +208,8 @@ Currently the following metadata values are supported (also depending on Googles
 * `Switch { ga="Sprinkler" }`
 * `Switch { ga="Vacuum" }`
 * `Switch { ga="Scene" }`
-* `Switch { ga="Lock" [ tfaAck=true ] }`
-* `Switch { ga="SecuritySystem" [ tfaPin="1234" ] }`
+* `Switch / Contact { ga="Lock" [ ackNeeded=true ] }`
+* `Switch { ga="SecuritySystem" [ pinNeeded="1234" ] }`
 * `Dimmer { ga="Speaker" }`
 * `Switch / Dimmer { ga="Fan" [ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ] }` (for Dimmer the options have to be set)
 * `Switch / Dimmer { ga="Hood" }`
@@ -223,14 +223,15 @@ Currently the following metadata values are supported (also depending on Googles
 * `Rollershutter { ga="Pergola" }`
 * `Rollershutter { ga="Shutter" }`
 * `Rollershutter { ga="Window" }`
-* `Group { ga="Thermostat" [ modes="..." ] }`
+* `Group { ga="Thermostat" [ modes="...", useFahrenheit=true ] }`
 * `Number { ga="thermostatTemperatureAmbient" }` as part of Thermostat group
 * `Number { ga="thermostatHumidityAmbient" }` as part of Thermostat group
 * `Number { ga="thermostatTemperatureSetpoint" }` as part of Thermostat group
 * `Number / String { ga="thermostatMode" }` as part of Thermostat group
+* `Number { ga="TemperatureSensor" } [ useFahrenheit=true ] `
 * `String { ga="Camera" [ protocols="hls,dash" ] }`
 
-_\* All Rollershutter devices can also be used with a Switch item with the limitation of only supporting open and close states._
+_\* All Rollershutter devices can also be used with a Switch or Contact item with the limitation of only supporting open and close states._
 
 Item labels are not mandatory in openHAB, but for the Google Assistant Action they are absolutely necessary!
 
@@ -242,6 +243,11 @@ Furthermore, you can state synonyms for the device name: `Switch KitchenLight "K
 
 To ease setting up new devices you can add a room hint: `[ roomHint="Living Room" ]`.
 
+For devices supporting the OpenClose trait, the attributes `[ discreteOnlyOpenClose=false, queryOnlyOpenClose=false ]` can be configured.
+- discreteOnlyOpenClose defaults to false. When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%). An example of such a device may be a valve.
+- queryOnlyOpenClose defaults to false. Is set to true for `Contact` items. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true.
+
+---
 
 NOTE: metadata is not (yet?) available via paperUI. Either you create your items via ".items" files, or you can:
 - add metadata via console:
@@ -258,6 +264,9 @@ NOTE: metadata is not (yet?) available via paperUI. Either you create your items
  }
  ```
 
+NOTE: Please be aware that for backward compatibilty also the former usage of tags (ref. [Google Assistant Action Documentation v2.5](https://www.openhab.org/v2.5/docs/ecosystem/google-assistant/)) to specify items to be exposed to Google Assistent is supported and may cause unexpected behavior.
+Items that contain tags that refer to a valid Google Assistent device will be exposed regardless of having metadata set. E.g.: `Switch MyBulb ["Lighting"]`.
+
 ### Special item configurations
 
 #### Two-Factor-Authentication
@@ -273,8 +282,8 @@ _pinNeeded_: "A two-factor authentication that requires a personal identificatio
 Example:
 
 ```
-Switch DoorLock "Front Door" { ga="Lock" [ tfaAck=true ] }
-Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ tfaPin="1234" ] }
+Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] }
+Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ pinNeeded="1234" ] }
 ```
 
 #### Thermostats
@@ -300,6 +309,7 @@ E.g. `[ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto" ]` wil
 By default the integration will provide `"off,heat,cool,on,heatcool,auto,eco"`.
 
 You can also set up a Thermostat for using it as a temperature sensor. To do so, create a Thermostat group and only add one item member as "thermostatTemperatureAmbient".
+However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently no UI support in Google Assistant).
 
 #### Fans
 
@@ -319,6 +329,11 @@ Blinds should always use the `Rollershutter` item type.
 Since Google and openHAB use the oposite percentage value for "opened" or "closed", the action will tranlate this automatically.
 If the values are still inverted in your case, you can state the `[ inverted=true ]` option for all `Rollershutter` items.
 
+Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind".
+Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers.
+
+---
+
 More details about the setup and the service linkage (https://myopenhab.org) procedure within the Google App can be found in the [USAGE documentation](docs/USAGE.md).
 
 ## Example Voice Commands

docs/USAGE.md

@@ -36,8 +36,8 @@ Currently the following metadata values are supported (also depending on Googles
 * `Switch { ga="Sprinkler" }`
 * `Switch { ga="Vacuum" }`
 * `Switch { ga="Scene" }`
-* `Switch { ga="Lock" [ tfaAck=true ] }`
-* `Switch { ga="SecuritySystem" [ tfaPin="1234" ] }`
+* `Switch / Contact { ga="Lock" [ ackNeeded=true ] }`
+* `Switch { ga="SecuritySystem" [ pinNeeded="1234" ] }`
 * `Dimmer { ga="Speaker" }`
 * `Switch / Dimmer { ga="Fan" [ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ] }` (for Dimmer the options have to be set)
 * `Switch / Dimmer { ga="Hood" }`
@@ -51,14 +51,15 @@ Currently the following metadata values are supported (also depending on Googles
 * `Rollershutter { ga="Pergola" }`
 * `Rollershutter { ga="Shutter" }`
 * `Rollershutter { ga="Window" }`
-* `Group { ga="Thermostat" [ modes="..." ] }`
+* `Group { ga="Thermostat" [ modes="...", useFahrenheit=true ] }`
 * `Number { ga="thermostatTemperatureAmbient" }` as part of Thermostat group
 * `Number { ga="thermostatHumidityAmbient" }` as part of Thermostat group
 * `Number { ga="thermostatTemperatureSetpoint" }` as part of Thermostat group
 * `Number / String { ga="thermostatMode" }` as part of Thermostat group
+* `Number { ga="TemperatureSensor" } [ useFahrenheit=true ] `
 * `String { ga="Camera" [ protocols="hls,dash" ] }`
 
-_\* All Rollershutter devices can also be used with a Switch item with the limitation of only supporting open and close states._
+_\* All Rollershutter devices can also be used with a Switch or Contact item with the limitation of only supporting open and close states._
 
 Example item configuration:
   ```
@@ -87,6 +88,11 @@ Furthermore, you can state synonyms for the device name: `Switch KitchenLight "K
 
 To ease setting up new devices you can add a room hint: `[ roomHint="Living Room" ]`.
 
+For devices supporting the OpenClose trait, the attributes `[ discreteOnlyOpenClose=false, queryOnlyOpenClose=false ]` can be configured.
+- discreteOnlyOpenClose defaults to false. When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%). An example of such a device may be a valve.
+- queryOnlyOpenClose defaults to false. Is set to true for `Contact` items. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true.
+
+---
 
 NOTE: metadata is not (yet?) available via paperUI. Either you create your items via ".items" files, or you can:
 - add metadata via console:
@@ -103,6 +109,9 @@ NOTE: metadata is not (yet?) available via paperUI. Either you create your items
  }
  ```
 
+NOTE: Please be aware that for backward compatibilty also the former usage of tags (ref. [Google Assistant Action Documentation v2.5](https://www.openhab.org/v2.5/docs/ecosystem/google-assistant/)) to specify items to be exposed to Google Assistent is supported and may cause unexpected behavior.
+Items that contain tags that refer to a valid Google Assistent device will be exposed regardless of having metadata set. E.g.: `Switch MyBulb ["Lighting"]`.
+
 ### Special item configurations
 
 #### Two-Factor-Authentication
@@ -118,8 +127,8 @@ _pinNeeded_: "A two-factor authentication that requires a personal identificatio
 Example:
 
 ```
-Switch DoorLock "Front Door" { ga="Lock" [ tfaAck=true ] }
-Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ tfaPin="1234" ] }
+Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] }
+Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ pinNeeded="1234" ] }
 ```
 
 #### Thermostats
@@ -145,6 +154,7 @@ E.g. `[ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto" ]` wil
 By default the integration will provide `"off,heat,cool,on,heatcool,auto,eco"`.
 
 You can also set up a Thermostat for using it as a temperature sensor. To do so, create a Thermostat group and only add one item member as "thermostatTemperatureAmbient".
+However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently no UI support in Google Assistant).
 
 #### Fans
 
@@ -164,6 +174,9 @@ Blinds should always use the `Rollershutter` item type.
 Since Google and openHAB use the oposite percentage value for "opened" or "closed", the action will tranlate this automatically.
 If the values are still inverted in your case, you can state the `[ inverted=true ]` option for all `Rollershutter` items.
 
+Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind".
+Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers.
+
 
 ## Setup & Usage on Google Assistant App
 

functions/apihandler.js

@@ -21,15 +21,33 @@
 const https = require('https');
 
 class ApiHandler {
-  constructor(config = {}, authToken = '') {
+  /**
+   * @param {object} config
+   */
+  constructor(config = { host: '', path: '/rest/items/', port: 80 }) {
+    if (!config.path.startsWith('/')) {
+      config.path = '/' + config.path;
+    }
     if (!config.path.endsWith('/')) {
       config.path += '/';
     }
     this._config = config;
+    this._authToken = '';
+  }
+
+  /**
+   * @param {string} authToken
+   */
+  set authToken(authToken) {
     this._authToken = authToken;
   }
 
-  getOptions(method = 'GET', itemName = '', length = 0) {
+  /**
+   * @param {string} method
+   * @param {string} itemName
+   * @param {number} length
+   */
+   getOptions(method = 'GET', itemName = '', length = 0) {
     const queryString = '?metadata=ga,synonyms' + (itemName ? '' : '&fields=groupNames,groupType,name,label,metadata,tags,type');
     const options = {
       hostname: this._config.host,
@@ -43,7 +61,7 @@ class ApiHandler {
 
     if (this._config.userpass) {
       options.auth = this._config.userpass;
-    } else {
+    } else if (this._authToken) {
       options.headers['Authorization'] = 'Bearer ' + this._authToken;
     }
 
@@ -55,7 +73,9 @@ class ApiHandler {
     return options;
   }
 
-
+  /**
+   * @param {string} itemName
+   */
   getItem(itemName = '') {
     const options = this.getOptions('GET', itemName);
     return new Promise((resolve, reject) => {
@@ -86,7 +106,11 @@ class ApiHandler {
     return this.getItem();
   }
 
-  sendCommand(itemName = '', payload = '') {
+  /**
+   * @param {string} itemName
+   * @param {string} payload
+   */
+  sendCommand(itemName, payload) {
     const options = this.getOptions('POST', itemName, payload.length);
     return new Promise((resolve, reject) => {
       const req = https.request(options, (response) => {
@@ -104,4 +128,4 @@ class ApiHandler {
   }
 }
 
-module.exports = { ApiHandler };
+module.exports = ApiHandler;