# devicehive-plugin-core

> DeviceHive custom plugin core functionality. NodeJS implementation

Latest version **1.1.4** (published 2018-05-16) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install devicehive-plugin-core
pnpm add devicehive-plugin-core
yarn add devicehive-plugin-core
bun add devicehive-plugin-core
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2018-05-16 |
| First published | 2018-01-26 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 4.5 MB |
| Known vulnerabilities | 0 (+4 in 3 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Ihor T. |
| Maintainers | devicehive |

## Links

- npm: https://www.npmjs.com/package/devicehive-plugin-core
- Repository: https://github.com/devicehive/devicehive-plugin-core-node
- Homepage: https://github.com/devicehive/devicehive-plugin-core-node#readme
- Issues: https://github.com/devicehive/devicehive-plugin-core-node/issues
- npm.io page: https://npm.io/package/devicehive-plugin-core

## Dependencies (7)

- [ws](https://npm.io/package/ws.md) ^3.3.3
- [uuid](https://npm.io/package/uuid.md) ^3.2.1
- [debug](https://npm.io/package/debug.md) ^3.1.0
- [request](https://npm.io/package/request.md) ^2.86.0
- [dateformat](https://npm.io/package/dateformat.md) ^3.0.3
- [json-evn-configurator](https://npm.io/package/json-evn-configurator.md) ^1.0.6
- [devicehive-proxy-message](https://npm.io/package/devicehive-proxy-message.md) ^1.0.11

## Recent versions

- 1.1.4 (latest) — 2018-05-16
- 1.1.3 — 2018-05-16
- 1.1.2 — 2018-03-15
- 1.1.1 — 2018-02-13
- 1.1.0 — 2018-01-26
- 1.0.3 — 2018-01-26
- 1.0.2 — 2018-01-26
- 1.0.1 — 2018-01-26
- 1.0.0 — 2018-01-26

## README

[DeviceHive]: https://devicehive.com "DeviceHive framework"
[Message]: https://github.com/devicehive/devicehive-proxy-message "Message"
[DeviceHive WS Proxy]: https://github.com/devicehive/devicehive-ws-proxy "DeviceHive WS Proxy"

# DeviceHive plugin core functionality (Node JS implementation)

This module makes it possible to quickly and easily create DeviceHive plugins using NodeJS.

## Module structure
### PluginCore class (private)
    
PluginCore class implements basic interaction functionality with [DeviceHive] service. 
User is not able to use it.
    
### ProxyClient class (private)

ProxyClient class implements basic transport functionality with [DeviceHive WS Proxy] service (in plugin mode). 
User is not able to use it.

### DeviceHivePlugin class (public)

DeviceHivePlugin class implements interface for user's plugin service classes. 
User is able to extends their own plugin services from the DeviceHivePlugin class.

```javascript
    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }
```

#### Plugin lifecycle hooks

    beforeStart() {}
    afterStart() {
    handleMessage(message) {}
    beforeStop() {}
    onError(error) {}

1) **_beforeStart_** - This hook fires before plugin will do try to connect to [DeviceHive] WS plugin server
2) **_afterStart_** - This hook fires after plugin successfully connects to [DeviceHive] WS plugin server
3) **_handleMessage_** - This hook fires on every incoming [Message] from [DeviceHive]
4) **_beforeStop_** - This hook fires before plugin will stop it's own process because of some critical reason (For example, WS plugin serer closes the connection)
5) **_onError_** - This hook fires on every internal error (critical/non critical)


#### Plugin API

DeviceHivePlugin class has few methods that are defined internally by core functionality:

    sendMessage(message) {}
    subscribe(subscriptionGroup) {}
    unsubscribe() {}
    
1) **_sendMessage_** - Sends [Message] object to WS plugin server. Returns Promise with response/error
2) **_subscribe_** - Subscribes to plugin topic with optionally mentioned subscription group
3) **_unsubscribe_** - Unsubscribes from plugin topic

#### Plugin entry point

To start plugin you should use next static method of DeviceHivePlugin class:

    DeviceHivePlugin.start(<pluginService>, <config>, [<envPrefix>]);
    
where:
- **pluginService** - instance of User's own DeviceHivePlugin implementation
- **config** - configuration object or path to configuration json file. See Configuration section
- **envPrefix** - prefix to add to environmental variables to override configuration fields

Example:

```javascript
    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }
    
    DeviceHivePlugin.start(new PluginService(), {
         DEVICE_HIVE_PLUGIN_WS_ENDPOINT: "ws://localhost:3001",
         DEVICE_HIVE_AUTH_SERVICE_API_URL: "http://localhost:8090/dh/rest",
         PLUGIN_ACCESS_TOKEN: "plugin_access_token",
         AUTO_SUBSCRIPTION_ON_START: true
    }, "MY_PLUGIN_SERVICE");
```

# Configuration

* **_DEVICE_HIVE_PLUGIN_WS_ENDPOINT_** - Path to DeviceHive WS server with plugin support 
* **_DEVICE_HIVE_AUTH_SERVICE_API_URL_** - Path to DeviceHive Auth REST API service 
* **_PLUGIN_TOPIC_** - Plugin topic 
* **_PLUGIN_TOKEN_LIFE_TIME_MIN_** - Plugin topic lifetime in minutes. _Optional parameter_
* **_USER_LOGIN_** - User login (plugin owner ar administrator). _Optional parameter_ 
* **_USER_PASSWORD_** - User password (plugin owner ar administrator). _Optional parameter_  
* **_USER_ACCESS_TOKEN_** - User access token (plugin owner ar administrator). _Optional parameter_  
* **_USER_REFRESH_TOKEN_** - User refresh token (plugin owner ar administrator). _Optional parameter_  
* **_PLUGIN_ACCESS_TOKEN_** - Plugin access token. _Optional parameter_  
* **_PLUGIN_REFRESH_TOKEN_** - Plugin refresh token. _Optional parameter_  
* **_AUTO_SUBSCRIPTION_ON_START_** - Flag to on/off auto subscription to plugin topic on plugin start

Each configuration field can be overridden with corresponding environmental variable with "PLUGIN" prefix, for example:

    PLUGIN.PLUGIN_TOKEN_LIFE_TIME_MIN=60

Prefix separator can be overridden by **_ENVSEPARATOR_** environmental variable. Example:

    ENVSEPARATOR=_
    PLUGIN_PLUGIN_TOKEN_LIFE_TIME_MIN=60
    
For plugin authentication next configuration combinations can bu used:

1) **_PLUGIN_ACCESS_TOKEN_**  
2) **_PLUGIN_REFRESH_TOKEN_**
3) **_USER_ACCESS_TOKEN_** + **_PLUGIN_TOPIC_** + **_DEVICE_HIVE_AUTH_SERVICE_API_URL_**
4) **_USER_REFRESH_TOKEN_** + **_PLUGIN_TOPIC_** + **_DEVICE_HIVE_AUTH_SERVICE_API_URL_**
5) **_USER_LOGIN_** + **_USER_PASSWORD_** + **_PLUGIN_TOPIC_** + **_DEVICE_HIVE_AUTH_SERVICE_API_URL_**

For 3-5 combination the **_PLUGIN_TOKEN_LIFE_TIME_MIN_**  configuration field can be mentioned.

---
_Source: https://npm.io/package/devicehive-plugin-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._