@drenso/homey-log 2.0.1

package/README.md

@@ -0,0 +1,55 @@
+# Homey Log
+
+[![npm](https://img.shields.io/npm/v/homey-log)](https://www.npmjs.com/package/homey-log) [![Lint](https://github.com/athombv/node-homey-log/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/athombv/node-homey-log/actions/workflows/lint.yml) [![NPM](https://github.com/athombv/node-homey-log/actions/workflows/deploy.yml/badge.svg)](https://github.com/athombv/node-homey-log/actions/workflows/deploy.yml) [![Deploy Documentation To GitHub Pages](https://github.com/athombv/node-homey-log/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/athombv/node-homey-log/actions/workflows/docs.yml)
+
+This module can be used in a Homey App to send events to [Sentry](http://sentry.io/).
+
+## Documentation
+
+Documentation is available at [https://athombv.github.io/node-homey-log/](https://athombv.github.io/node-homey-log/).
+
+## Related Modules
+
+* [node-homey-zwavedriver](https://athombv.github.io/node-homey-zwavedriver) — Module for Z-Wave drivers
+* [node-homey-zigbeedriver](https://athombv.github.io/node-homey-zigbeedriver) — Module for Zigbee drivers
+* [node-homey-rfdriver](https://athombv.github.io/node-homey-rfdriver) — Module for RF (433 Mhz, 868 MHz, Infrared) drivers
+* [node-homey-oauth2app](https://athombv.github.io/node-homey-oauth2app) — Module for OAuth2 apps
+
+## Installation
+
+```bash
+npm install --save homey-log
+```
+
+## Getting started
+
+In `env.json`, add the Sentry URL. If you would like to send the logs to Sentry *also* during development, set force log to `1`.
+
+```json
+{
+  "HOMEY_LOG_FORCE": "0",
+  "HOMEY_LOG_URL": "https://foo:bar@sentry.io/123456"
+}
+```
+
+In `app.js`, include the library and create a new `Log` instance:
+
+```js
+const { Log } = require('homey-log');
+
+class MyApp extends Homey.App {
+  onInit() {
+    this.homeyLog = new Log({ homey: this.homey });
+  }
+}
+```
+
+### Notes
+
+* When your app crashes due to an `uncaughtException` or `unhandledRejection`, this will automatically be sent to Sentry.
+* When running your app with `homey app run` events will not be sent to Sentry.
+
+## Changelog
+### 2.0.0
+
+This version is only SDK version 3 compatible. It now requires a different way of setting up the `Log` instance, see _Getting Started_.

package/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const Log = require('./lib/Log');
+
+export {Log};

package/lib/Log.js

@@ -0,0 +1,236 @@
+'use strict';
+
+const HomeyModule = require('homey');
+
+const Raven = require('raven');
+
+const DEFAULT_OPTIONS = {
+  // Start tracking unhandled promise rejections (not enabled by default)
+  captureUnhandledRejections: true,
+};
+
+class Log {
+
+  /**
+   * Construct a new Log instance.
+   * @param {object} args
+   * @param {HomeyModule} args.homey - `this.homey` instance in
+   * your app (e.g. `App#homey`/`Driver#homey`/`Device#homey`).
+   *
+   * @param {object} [args.options] - Additional options for Raven
+   *
+   * @example
+   * class MyApp extends Homey.App {
+   *   onInit() {
+   *     this.homeyLog = new Log({ homey: this.homey });
+   *   }
+   * }
+   */
+  constructor({ homey, options }) {
+    this._capturedMessages = [];
+    this._capturedExceptions = [];
+
+    if (typeof homey === 'undefined') {
+      return Log._error('Error: missing `homey` constructor parameter');
+    }
+
+    if (!HomeyModule.env) {
+      return Log._error('Error: could not access `HomeyModule.env`');
+    }
+
+    if (typeof HomeyModule.env.HOMEY_LOG_URL !== 'string') {
+      return Log._error('Error: expected `HOMEY_LOG_URL` env variable, homey-log is disabled');
+    }
+
+    // Check if debug mode is enabled
+    const disableRaven = process.env.DEBUG === '1' && HomeyModule.env.HOMEY_LOG_FORCE !== '1';
+    if (disableRaven) {
+      Log._log('App is running in debug mode, disabling Raven');
+    }
+
+    this._manifest = HomeyModule.manifest;
+    this._homeyVersion = homey.version;
+    this._managerCloud = homey.cloud;
+
+    // Init Raven, pass falsy value if raven is not enabled to prevent sending events upstream
+    // in debug mode
+    this.init(!disableRaven && HomeyModule.env.HOMEY_LOG_URL, { ...DEFAULT_OPTIONS, ...options });
+  }
+
+  /**
+   * Init Raven, provide falsy value as `url` to prevent sending events upstream in debug mode.
+   * @param {string|boolean} url
+   * @param {object} opts
+   * @param {boolean} opts.captureUnhandledRejections - Track unhandled promise rejections not
+   * enabled by default)
+   * @returns {Log}
+   * @private
+   */
+  init(url, opts) {
+    Raven.config(url, opts).install();
+
+    this.setTags({
+      appId: this._manifest.id,
+      appVersion: this._manifest.version,
+      homeyVersion: this._homeyVersion,
+    });
+
+    // Get homey cloud id and set as tag
+    this._managerCloud.getHomeyId()
+      .then(homeyId => this.setTags({ homeyId }))
+      .catch(err => Log._error('Error: could not get `homeyId`', err));
+
+    Log._log(`App ${this._manifest.id} v${this._manifest.version} logging on Homey v${this._homeyVersion}...`);
+    return this;
+  }
+
+  /**
+   * Set `tags` that will be send as context with every message or error. See the raven-node
+   * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+   * @param {object} tags
+   * @returns {Log}
+   */
+  setTags(tags) {
+    Log._mergeContext('tags', tags);
+    return this;
+  }
+
+  /**
+   * Set `extra` that will be send as context with every message or error. See the raven-node
+   * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+   * @param {object} extra
+   * @returns {Log}
+   */
+  setExtra(extra) {
+    Log._mergeContext('extra', extra);
+    return this;
+  }
+
+  /**
+   * Set `user` that will be send as context with every message or error. See the raven-node
+   * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+   * @param {object} user
+   * @returns {Log}
+   */
+  setUser(user) {
+    Log._mergeContext('user', user);
+    return this;
+  }
+
+  /**
+   * Create and send message event to Sentry. See the raven-node documentation:
+   * https://docs.sentry.io/clients/node/usage/#capturing-messages
+   * @param {string} message - Message to be sent
+   * @returns {Promise<string>|undefined}
+   */
+  async captureMessage(message) {
+    Log._log('captureMessage:', message);
+
+    if (this._capturedMessages.indexOf(message) > -1) {
+      Log._log('Prevented sending a duplicate message');
+      return;
+    }
+
+    this._capturedMessages.push(message);
+
+    // eslint-disable-next-line consistent-return
+    return new Promise((resolve, reject) => {
+      Raven.captureMessage(
+        message,
+        (err, result) => {
+          if (err) return reject(err);
+          return resolve(result);
+        },
+      );
+    });
+  }
+
+  /**
+   * Create and send exception event to Sentry. See the raven-node documentation:
+   * https://docs.sentry.io/clients/node/usage/#capturing-errors
+   * @param {Error} err - Error instance to be sent
+   * @returns {Promise<string>|undefined}
+   */
+  async captureException(err) {
+    Log._log('captureException:', err);
+
+    if (this._capturedExceptions.indexOf(err) > -1) {
+      Log._log('Prevented sending a duplicate log');
+      return;
+    }
+
+    this._capturedExceptions.push(err);
+
+    // eslint-disable-next-line consistent-return
+    return new Promise((resolve, reject) => {
+      Raven.captureException(
+        err,
+        (captureErr, result) => {
+          if (captureErr) return reject(captureErr);
+          return resolve(result);
+        },
+      );
+    });
+  }
+
+  /**
+   * Mimic SDK log method.
+   * @private
+   */
+  static _log() {
+    // eslint-disable-next-line prefer-spread,prefer-rest-params,no-console
+    console.log.bind(null, Log._logTime(), '[homey-log]').apply(null, arguments);
+  }
+
+  /**
+   * Mimic SDK error method.
+   * @private
+   */
+  static _error() {
+    // eslint-disable-next-line prefer-spread,prefer-rest-params,no-console
+    console.error.bind(null, Log._logTime(), '[homey-log]').apply(null, arguments);
+  }
+
+  /**
+   * Mimic SDK timestamp.
+   * @returns {string}
+   * @private
+   */
+  static _logTime() {
+    const date = new Date();
+
+    let mm = date.getMonth() + 1;
+    mm = (mm < 10 ? `0${mm}` : mm);
+    let dd = date.getDate();
+    dd = (dd < 10 ? `0${dd}` : dd);
+    let hh = date.getHours();
+    hh = (hh < 10 ? `0${hh}` : hh);
+    let min = date.getMinutes();
+    min = (min < 10 ? `0${min}` : min);
+    let sec = date.getSeconds();
+    sec = (sec < 10 ? `0${sec}` : sec);
+
+    return `${date.getFullYear()}-${mm}-${dd} ${hh}:${min}:${sec}`;
+  }
+
+  /**
+   * Raven.mergeContext covers only 1-level of the context (tags, extra, user)
+   * We need to merge a 2-level of the context
+   * see https://github.com/getsentry/raven-node/issues/228
+   * @param {string} key
+   * @param {object} value
+   * @private
+   */
+  static _mergeContext(key, value) {
+    const context = Raven.getContext();
+    if (!context[key]) {
+      context[key] = {};
+    }
+
+    Object.assign(context[key], value);
+    Raven.setContext(context);
+  }
+
+}
+
+module.exports = Log;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@drenso/homey-log",
+  "version": "2.0.1",
+  "description": "Interface with Sentry for Homey",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "eslint .",
+    "serve": "concurrently \"serve build/\" \"npm run jsdoc:watch\"",
+    "build": "npm run jsdoc:clean; npm run jsdoc;",
+    "jsdoc": "jsdoc --configure ./docs/jsdoc.json;",
+    "jsdoc:clean": "rm -rf ./build",
+    "jsdoc:watch": "watch \"npm run jsdoc:clean && npm run jsdoc\" lib docs \"node_modules/homey-jsdoc-template\"",
+    "typings:generate": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/athombv/node-homey-log.git"
+  },
+  "author": "Athom B.V.",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/athombv/node-homey-log/issues"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "homepage": "https://github.com/athombv/node-homey-log#readme",
+  "dependencies": {
+    "raven": "github:athombv/raven-node"
+  },
+  "devDependencies": {
+    "@types/homey": "npm:homey-apps-sdk-v3-types@^0.3.0",
+    "@types/node": "^12.20.55",
+    "concurrently": "^5.1.0",
+    "eslint": "^7.2.0",
+    "eslint-config-athom": "^2.1.0",
+    "homey": "^2.4.0",
+    "homey-jsdoc-template": "github:athombv/homey-jsdoc-template#1.4",
+    "jsdoc": "^3.6.6",
+    "jsdoc-ts-utils": "^1.1.2",
+    "npm-watch": "^0.6.0",
+    "serve": "^11.3.1",
+    "typescript": "^4.7.4",
+    "watch": "^1.0.2"
+  },
+  "types": "types/index.d.ts",
+  "watch": {
+    "jsdoc": {
+      "patterns": [
+        "lib",
+        "README.md"
+      ],
+      "extensions": [
+        "js"
+      ]
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "include": ["index.js"],
+    "compilerOptions": {
+      "allowJs": true,
+      "declaration": true,
+      "emitDeclarationOnly": true,
+      "esModuleInterop": true,
+      "outDir": "types"
+    }
+}

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export { Log };
+import Log = require("./lib/Log");

package/types/lib/Log.d.ts

@@ -0,0 +1,98 @@
+export = Log;
+declare class Log {
+    /**
+     * Mimic SDK log method.
+     * @private
+     */
+    private static _log;
+    /**
+     * Mimic SDK error method.
+     * @private
+     */
+    private static _error;
+    /**
+     * Mimic SDK timestamp.
+     * @returns {string}
+     * @private
+     */
+    private static _logTime;
+    /**
+     * Raven.mergeContext covers only 1-level of the context (tags, extra, user)
+     * We need to merge a 2-level of the context
+     * see https://github.com/getsentry/raven-node/issues/228
+     * @param {string} key
+     * @param {object} value
+     * @private
+     */
+    private static _mergeContext;
+    /**
+     * Construct a new Log instance.
+     * @param {object} args
+     * @param {HomeyModule} args.homey - `this.homey` instance in
+     * your app (e.g. `App#homey`/`Driver#homey`/`Device#homey`).
+     *
+     * @param {object} [args.options] - Additional options for Raven
+     *
+     * @example
+     * class MyApp extends Homey.App {
+     *   onInit() {
+     *     this.homeyLog = new Log({ homey: this.homey });
+     *   }
+     * }
+     */
+    constructor({ homey, options }: {
+        homey: typeof HomeyModule;
+        options?: object;
+    });
+    _capturedMessages: any[];
+    _capturedExceptions: any[];
+    _manifest: any;
+    _homeyVersion: string;
+    _managerCloud: any;
+    /**
+     * Init Raven, provide falsy value as `url` to prevent sending events upstream in debug mode.
+     * @param {string|boolean} url
+     * @param {object} opts
+     * @param {boolean} opts.captureUnhandledRejections - Track unhandled promise rejections not
+     * enabled by default)
+     * @returns {Log}
+     * @private
+     */
+    private init;
+    /**
+     * Set `tags` that will be send as context with every message or error. See the raven-node
+     * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+     * @param {object} tags
+     * @returns {Log}
+     */
+    setTags(tags: object): Log;
+    /**
+     * Set `extra` that will be send as context with every message or error. See the raven-node
+     * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+     * @param {object} extra
+     * @returns {Log}
+     */
+    setExtra(extra: object): Log;
+    /**
+     * Set `user` that will be send as context with every message or error. See the raven-node
+     * documentation: https://docs.sentry.io/clients/node/usage/#raven-node-additional-context.
+     * @param {object} user
+     * @returns {Log}
+     */
+    setUser(user: object): Log;
+    /**
+     * Create and send message event to Sentry. See the raven-node documentation:
+     * https://docs.sentry.io/clients/node/usage/#capturing-messages
+     * @param {string} message - Message to be sent
+     * @returns {Promise<string>|undefined}
+     */
+    captureMessage(message: string): Promise<string> | undefined;
+    /**
+     * Create and send exception event to Sentry. See the raven-node documentation:
+     * https://docs.sentry.io/clients/node/usage/#capturing-errors
+     * @param {Error} err - Error instance to be sent
+     * @returns {Promise<string>|undefined}
+     */
+    captureException(err: Error): Promise<string> | undefined;
+}
+import HomeyModule = require("homey");