Energomonitor

Energomonitor API JavaScript client.

Installation

$ npm install energomonitor

The client should work both in Node.js and in most modern browsers (when bundled using Webpack or some similar tool).

Note the client uses ES6 promises. In environments that don’t support them, you may need to use a polyfill (such as es6-promise).

Usage

First, require the library:

const Energomonitor = require('energomonitor');

Now you need to create an instance of Energomonitor, which represents an interaction session with the Energomonitor API. Since API requests are authenticated with an access token, you have two options:

1. If you already have the token available, you can just create the instance and pass the token to the constructor:

   const token = /* ... */;
   
   const em = new Energomonitor(token);

2. If you don’t have the token available, you can create the instance without it and use the authorize method to generate the token using your username and password:

   const em = new Energomonitor();
   
   const username = /* ... */;
   const password = /* ... */;
   
   em.authorize(username, password)
       .then(authorization => {
           const token = authorization.token;
           const expiresAt = authorization.expires_at;
   
           // Save the token and expiration time here and continue using the
           // `Energomonitor` instance.
       };

In both cases, the token will be saved internally in the instance and it will be used by its methods to authenticate API requests. For more details about authentication, see Authentication in the Energomonitor API documentation.

Once you have the Energomonitor instance ready, you can start using the API. Here is a simple example which lists all feeds of a user with ID usfgw (when running the example, replace the ID with your own):

em.getFeeds('usfgw')
    .then(feeds => {
        feeds.forEach((feed, index) => {
            console.log(`Feed #${index + 1}: ${feed.id}`);
        });
    })
    .catch(e => {
        console.error(e.message);
    });

The output will be something like this:

Feed #1: embahs
Feed #2: emdvij

In general, Energomonitor methods correspond to API endpoints and return a promise. For successful requests, the promise will resolve to the value returned by the API (or null for endpoints that don’t return any value). For unsuccessful requests, the promise will be rejected with the error returned by the API. For a list of possible errors, see Client errors in the Energomonitor API documentation.

For a complete list of Energomonitor methods and their description, see the API documentation below.

API

Energomonitor

Represents an interaction session with the Energomonitor API.

Kind: global class

• Energomonitor
  • new Energomonitor([token], [axiosInstance], [apiURL])
  • .authorize(username, password, [note], [resources], [validMinutes]) ⇒ Promise
  • .getUser(userId) ⇒ Promise
  • .getFeeds(userId) ⇒ Promise
  • .getFeed(feedId) ⇒ Promise
  • .getStreams(feedId, [types], [channels], [dataTimeFrom], [dataTimeTo]) ⇒ Promise
  • .getStream(feedId, streamId) ⇒ Promise
  • .getStreamData(feedId, streamId, [timeFrom], [timeTo], [limit]) ⇒ Promise
  • .getRelatedStreams(feedId) ⇒ Promise
  • .getNotifications(userId, [createdAtFrom]) ⇒ Promise
  • .getNotification(userId, notificationId) ⇒ Promise
  • .updateNotifications(userId, [data]) ⇒ Promise
  • .updateNotification(userId, notificationId, [data]) ⇒ Promise
  • .getNotificationCount(userId) ⇒ Promise
  • .getAxiosInstance() ⇒ Object

new Energomonitor([token], [axiosInstance], [apiURL])

Create a new instance of Energomonitor.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [token] | string | | Access token to authenticate the requests with. Use this parameter in case you already generated a token in the past and now you wish to use it, otherwise generate the token using authorize. | | [axiosInstance] | Axios | | Custom axios instance to be used for handling HTTP requests. When not passed, the client will create its own instance. | | [apiURL] | string | "https://api.energomonitor.com/v1" | Energomonitor API URL. |

energomonitor.authorize(username, password, [note], [resources], [validMinutes]) ⇒ Promise

Create a new authorization for a user. Return an authorization object containing an access token. The token will be saved internally in the instance and it will subsequently be used by all other methods.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the authorization object.

| Param | Type | Description | | --- | --- | --- | | username | string | Username used for HTTP Basic authentication. | | password | string | Password used for HTTP Basic authentication. | | [note] | string | User note for the created authorization. | | [resources] | Array.<Object> | List of resources associated with the created authorization. Default: all resources the user is authorized to access. | | [validMinutes] | integer | How long from now should the created authorization be valid, in minutes.|

energomonitor.getUser(userId) ⇒ Promise

Retrieve a single user.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the user object.

| Param | Type | Description | | --- | --- | --- | | userId | string | Retrieve a user with this ID. |

energomonitor.getFeeds(userId) ⇒ Promise

Retrieve a list of all user’s feeds.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the array of feed objects.

| Param | Type | Description | | --- | --- | --- | | userId | string | Retrieve feeds of a user with this ID. |

energomonitor.getFeed(feedId) ⇒ Promise

Retrieve a single feed.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the feed object.

| Param | Type | Description | | --- | --- | --- | | feedId | string | Retrieve a feed with this ID. |

energomonitor.getStreams(feedId, [types], [channels], [dataTimeFrom], [dataTimeTo]) ⇒ Promise

Retrieve a list of streams belonging to a feed.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the array of stream objects.

| Param | Type | Description | | --- | --- | --- | | feedId | string | Retrieve streams belonging to a feed with this ID. | | [types] | string | Array.<string> | Only list streams of this type/types. See the description of stream objects for more details about stream types. | | [channels] | integer | Array.<integer> | Only list streams with this channel/channels. See the description of stream objects for more details about channels. | | [dataTimeFrom] | Date | Only list streams with data points measured after or at this time. | | [dataTimeTo] | Date | Only list streams with data points measured before or at this time. |

energomonitor.getStream(feedId, streamId) ⇒ Promise

Retrieve a single stream.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the stream object).

| Param | Type | Description | | --- | --- | --- | | feedId | string | Retrieve a stream belonging to a feed with this ID. | | streamId | string | Retrieve a stream with this ID. |

energomonitor.getStreamData(feedId, streamId, [timeFrom], [timeTo], [limit]) ⇒ Promise

Retrieve a list of a stream’s data points.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the array with the data points where each data point is an array with 2 elements: the time of measurement (integer, a Unix timestamp) and a value (integer | float). See the GET /feeds/{feed_id}/streams/{stream_id}/data endpoint description for more details.

| Param | Type | Description | | --- | --- | --- | | feedId | string | Retrieve data points of a stream belonging to a feed with this ID. | | streamId | string | Retrieve data of a stream with this ID. | | [timeFrom] | Date | Only list data points measured after or at this time. | | [timeTo] | Date | Only list data points measured before or at this time. | | [limit] | integer | Maximum number of returned data points. When there are more matching data points than limit, the newest ones are returned. |

energomonitor.getRelatedStreams(feedId) ⇒ Promise

Retrieve a list of related streams.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the array with the groups, where each group is an array with stream IDs identifying streams that belong to the group. See the GET /feeds/{feed_id}/related_stream, endpoint description for more details.

| Param | Type | Description | | --- | --- | --- | | feedId | string | Retrieve related streams of a feed with this ID. |

energomonitor.getNotifications(userId, [createdAtFrom]) ⇒ Promise

Retrieve a list of user’s notifications.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the array of notification objects.

| Param | Type | Description | | --- | --- | --- | | userId | string | Retrieve notifications of a user with this ID. | | [createdAtFrom] | Date | Only list notifications created at or after this time. |

energomonitor.getNotification(userId, notificationId) ⇒ Promise

Retrieve a single notification.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the notification object.

| Param | Type | Description | | --- | --- | --- | | userId | string | Retrieve a notification of a user with this ID. | | notificationId | string | Retrieve a notification with this ID. |

energomonitor.updateNotifications(userId, [data]) ⇒ Promise

Modify user’s notifications.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to null.

| Param | Type | Description | | --- | --- | --- | | userId | string | Modify notifications of a user with this ID. | | [data] | Object | An object with one of the following properties (their semantics is the same as in a notification object): read (boolean). For example, { read: true } or { read: false }. |

energomonitor.updateNotification(userId, notificationId, [data]) ⇒ Promise

Modify a single notification.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to the modified notification object.

| Param | Type | Description | | --- | --- | --- | | userId | string | Modify a notification of a user with this ID. | | notificationId | string | Modify a notification with this ID. | | [data] | Object | An object with one of the following properties (their semantics is the same as in a notification object): read (boolean), archived (boolean). For example, { read: true, archived: false } or { read: false }.|

energomonitor.getNotificationCount(userId) ⇒ Promise

Retrieve notification count information.

Kind: instance method of Energomonitor

Returns: Promise - A promise that resolves to an object with read, unread and total properties. See the GET /users/{user_id}/notification_count endpoint description for more details.

| Param | Type | Description | | --- | --- | --- | | userId | string | Retrieve notification count information of a user with this ID. |

energomonitor.getAxiosInstance() ⇒ Object

Return the axios instance used by this client.

Kind: instance method of Energomonitor

Returns: Object - The axios instance used by this client.

Development

Unit tests

The client is tested using a small Jest test suite.

Run tests:

$ npm run test

Run tests in verbose mode:

$ npm run test-verbose

Code style

We use Prettier together with prettier-eslint.

Please always use the format script before committing:

$ npm run format