fix: autocompletions with jsdocs (#63)

fix: dep vulns

chore: add start and debug scripts

docs: add typedefs to api


docs: add typedef to endpoint-context api


docs: add util/events.js for typedefs


docs: add jsdocs to signature.js


feat: add ColorSetting, MessageGroupSetting w/ jsdocs


docs: add jsdocs to all *settings


docs: add jsdocs to smart-app.js


Remove index.js


chore: remove comments from events.js

docs: add mode, device, and timer event docs


split string by regex properly


use correct return result


remove events.js


set this.api = {} for rules


Add .vscode launch.json to debug mocha tests easily


Use proper jsdoc type over typedef


docs: update readme


chore: add boolean-setting-spec


docs: add SmartAppOptions object


fix usage of typedef vs type in api.js

Author: erodewald

.vscode/launch.json

@@ -0,0 +1,33 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+          "type": "node",
+          "request": "launch",
+          "name": "Mocha All",
+          "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+          "args": [
+              "--timeout",
+              "999999",
+              "--colors",
+              "${workspaceFolder}/test"
+          ],
+          "console": "integratedTerminal",
+          "internalConsoleOptions": "neverOpen"
+      },
+      {
+          "type": "node",
+          "request": "launch",
+          "name": "Mocha Current File",
+          "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+          "args": [
+              "--timeout",
+              "999999",
+              "--colors",
+              "${file}"
+          ],
+          "console": "integratedTerminal",
+          "internalConsoleOptions": "neverOpen"
+      }
+    ]
+  }

README.md

@@ -27,13 +27,13 @@ npm i @smartthings/smartapp --save
 `NodeJS`:
 
 ```javascript
-const smartapp = require('@smartthings/smartapp')
+const SmartApp = require('@smartthings/smartapp')
 ```
 
-Or, if you're transpiling to `ES6`/`ES2015`+:
+Or `ES2015`+:
 
 ```javascript
-import smartapp from '@smartthings/smartapp'
+import SmartApp from '@smartthings/smartapp'
 ```
 
 ## Highlights
@@ -43,6 +43,9 @@ import smartapp from '@smartthings/smartapp'
 - [x] Configuration page API simplifies page definition.
 - [x] Integrated [i18n](https://www.npmjs.com/package/i18n) framework provides configuration page localization.
 - [x] [Winston](https://www.npmjs.com/package/winston) framework manges log messages.
+- [x] Context Store plugins – easily scale access token management (and more) to support many users
+  - [x] [AWS DynamoDB](https://github.com/SmartThingsCommunity/dynamodb-context-store-nodejs) plugin
+  - [x] [Firebase Cloud Firestore](https://github.com/SmartThingsCommunity/firestore-context-store-nodejs) plugin
 
 ## Roadmap
 
@@ -58,29 +61,36 @@ To run the app with an HTTP server, like Express.js:
 
 ```javascript
 const express    = require('express');
-const smartapp   = require('@smartthings/smartapp');
+const SmartApp   = require('@smartthings/smartapp');
 const server     = module.exports = express();
 const PORT       = 8080;
 
 server.use(express.json());
 
 /* Define the SmartApp */
-smartapp
+const smartapp = new SmartApp()
     // @smartthings_rsa.pub is your on-disk public key
     // If you do not have it yet, omit publicKey()
     .publicKey('@smartthings_rsa.pub') // optional until app verified
     .app.enableEventLogging(2) // logs all lifecycle event requests and responses as pretty-printed JSON. Omit in production
     .configureI18n()
     .page('mainPage', (context, page, configData) => {
         page.section('sensors', section => {
-           section.deviceSetting('contactSensor').capabilities(['contactSensor']).required(false);
+           section
+            .deviceSetting('contactSensor')
+            .capabilities(['contactSensor'])
+            .required(false);
         });
         page.section('lights', section => {
-            section.deviceSetting('lights').capabilities(['switch']).multiple(true).permissions('rx');
+            section
+                .deviceSetting('lights')
+                .capabilities(['switch'])
+                .multiple(true)
+                .permissions('rx');
         });
     })
     .updated(async (context, updateData) => {
-    	// Called for both INSTALLED and UPDATED lifecycle events if there is no separate installed() handler
+        // Called for both INSTALLED and UPDATED lifecycle events if there is no separate installed() handler
         await context.api.subscriptions.unsubscribeAll()
         return context.api.subscriptions.subscribeToDevices(context.config.contactSensor, 'contactSensor', 'contact', 'myDeviceEventHandler');
     })
@@ -104,15 +114,15 @@ To run as a Lambda function instead of an HTTP server, ensure that your main ent
 
 > **Note:** This snippet is heavily truncated for brevity – see the web service example above a more detailed example of how to define a `smartapp`.
 
-```
-const smartapp = require('@smartthings/smartapp')
-smartapp
-    .app.enableEventLogging() // logs all lifecycle event requests and responses. Omit in production
+```javascript
+const SmartApp = require('@smartthings/smartapp')
+const smartapp = new SmartApp()
+    .enableEventLogging() // logs all lifecycle event requests and responses. Omit in production
     .page( ... )
     .updated(() => { ... })
     .subscribedEventHandler( ... );
 
-exports.handle = (event, context, callback) => {
+exports.handler = (event, context, callback) => {
     smartapp.handleLambdaCallback(event, context, callback);
 };
 ```

index.js

@@ -13,17 +13,41 @@ const Subscriptions = require('./platform/subscriptions')
 
 module.exports = class SmartThingsApi {
 	constructor(options) {
+		// TODO – expand these JSdocs
+		/** @type { import('./platform/client') } */
 		this.client = new Client(options)
+
+		/** @type { import('./platform/apps') } */
 		this.apps = new Apps(this)
+
+		/** @type { import('./platform/deviceprofiles') } */
 		this.deviceProfiles = new DeviceProfiles(this)
+
+		/** @type { import('./platform/devices') } */
 		this.devices = new Devices(this)
+
+		/** @type { import('./platform/installedapps') } */
 		this.installedApps = new InstalledApps(this)
+
+		/** @type { import('./platform/locations') } */
 		this.locations = new Locations(this)
+
+		/** @type { import('./platform/modes') } */
 		this.modes = new Modes(this)
+
+		/** @type { import('./platform/scenes') } */
 		this.scenes = new Scenes(this)
+
+		/** @type { import('./platform/schedules') } */
 		this.schedules = new Schedules(this)
+
+		/** @type { import('./platform/subscriptions') } */
 		this.subscriptions = new Subscriptions(this)
+
+		/** @type {String} */
 		this.installedAppId = options.installedAppId
+
+		/** @type {String} */
 		this.locationId = options.locationId
 	}
 }

lib/api.js

@@ -8,11 +8,24 @@ module.exports = class BooleanSetting extends SectionSetting {
 		this._type = 'BOOLEAN'
 	}
 
-	image(value) {
-		this._image = value
+	/**
+	 * Set an image icon
+	 *
+	 * @param {String} source HTTPS url or Base64-encoded data URI. Max length 2048 characters.
+	 * @returns {BooleanSetting} Boolean Setting instance
+	 */
+	image(source) {
+		this._image = source
 		return this
 	}
 
+	/**
+	 * Indicates if this input should refresh configs after a change in value.
+	 *
+	 * @param {String} value
+	 * @default false
+	 * @returns {BooleanSetting} Boolean Setting instance
+	 */
 	submitOnChange(value) {
 		this._submitOnChange = value
 		return this

lib/pages/boolean-setting.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const SectionSetting = require('./section-setting.js')
+
+module.exports = class ColorSetting extends SectionSetting {
+	constructor(section, id) {
+		super(section, id)
+		this._type = 'COLOR'
+	}
+
+	/**
+	 * Configure your image source
+	 *
+	 * @param {String} source HTTPS url or Base64-encoded data URI. Max length 2048 characters.
+	 * @returns {ColorSetting} Color Setting instance
+	 */
+	image(source) {
+		this._image = source
+		return this
+	}
+
+	toJson() {
+		const result = super.toJson()
+		if (this._image) {
+			result.image = this._image
+		}
+
+		return result
+	}
+}

lib/pages/color-setting.js

@@ -9,21 +9,45 @@ module.exports = class DecimalSetting extends SectionSetting {
 		this._description = 'Tap to set'
 	}
 
+	/**
+	 * The maximum inclusive value the decimal can be set to.
+	 *
+	 * @param {number} value Maximum value
+	 * @returns {DecimalSetting} Decimal Setting instance
+	 */
 	max(value) {
 		this._max = value
 		return this
 	}
 
+	/**
+	 * The minimum inclusive value the decimal can be set to.
+	 *
+	 * @param {number} value Minimum value
+	 * @returns {DecimalSetting} Decimal Setting instance
+	 */
 	min(value) {
 		this._min = value
 		return this
 	}
 
-	image(value) {
-		this._image = value
+	/**
+	 * Set an image icon
+	 *
+	 * @param {String} source HTTPS url or Base64-encoded data URI. Max length 2048 characters.
+	 * @returns {DecimalSetting} Decimal Setting instance
+	 */
+	image(source) {
+		this._image = source
 		return this
 	}
 
+	/**
+	 * A string to be shown after the text input field.
+	 *
+	 * @param {String} value Max length 10 characters
+	 * @returns {DecimalSetting} Decimal Setting instance
+	 */
 	postMessage(value) {
 		this._postMessage = value
 		return this