solarnetwork-api-core
v2.2.2
Published
SolarNetwork Core API
Downloads
124
Readme
SolarNetwork Core API - JavaScript
This project contains JavaScript code to help access the SolarNetwork API. To include the library in your NPM-based project, run the following:
npm i solarnetwork-api-core
API docs
The latest API documentation is published here, or
you can build the API documentation by running the apidoc
script:
npm run apidoc
That will produce HTML documentation in docs/html
.
Example
Here's an example use of the library, targeted for use in a browser using the Fetch API to access the /datum/stream/reading SolarNetwork API:
import {
Aggregations,
DatumFilter,
DatumReadingTypes,
} from "solarnetwork-api-core/lib/domain";
import {
AuthorizationV2Builder,
HttpContentType,
HttpHeaders,
HttpMethod,
SolarQueryApi,
} from "solarnetwork-api-core/lib/net";
import { DatumStreamMetadataRegistry } from "solarnetwork-api-core/lib/util";
import { datumForStreamData } from "solarnetwork-api-core/lib/util/datum";
// declare a basic "datum" interface for the data returned from SN
interface GeneralDatum extends Object {
nodeId: number;
sourceId: string;
date: Date;
[index: string]: any;
}
/**
* Fetch hourly reading data for a datum stream using the stream API.
*
* @param nodeId - the node ID to fetch data for
* @param sourceId - the source ID to fetch data for
* @param startDate - the minimum date
* @param endDate - the maximum date
* @param token - the security token to authenticate with
* @param tokenSecret - the security token secret
* @returns the data, as an array of general datum
*/
async function fetchReadingDatumStream(
nodeId: number,
sourceId: string,
startDate: Date,
endDate: Date,
token: string,
tokenSecret: string
): Promise<GeneralDatum[]> {
const filter = new DatumFilter();
filter.aggregation = Aggregations.Hour;
filter.nodeId = nodeId;
filter.sourceId = sourceId;
filter.startDate = startDate;
filter.endDate = endDate;
// encode the URL request for the /datum/stream/reading API
const urlHelper = new SolarQueryApi();
const streamDataUrl = urlHelper.streamReadingUrl(
DatumReadingTypes.Difference,
filter
);
// create URL and auth headers for API request
const auth = new AuthorizationV2Builder(token);
const authHeader = auth.snDate(true).url(streamDataUrl).build(tokenSecret);
const headers = new Headers({
Authorization: authHeader,
Accept: HttpContentType.APPLICATION_JSON,
});
headers.set(HttpHeaders.X_SN_DATE, auth.requestDateHeaderValue!);
// make API request and get response as JSON
const res = await fetch(streamDataUrl, {
method: HttpMethod.GET,
headers: headers,
});
const json = await res.json();
// convert stream result into GeneralDatum objects
const result: GeneralDatum[] = [];
const reg = DatumStreamMetadataRegistry.fromJsonObject(json.meta);
if (!reg) {
return Promise.reject("JSON could not be parsed.");
}
for (const data of json.data) {
const meta = reg.metadataAt(data[0]);
if (!meta) {
continue;
}
const d = datumForStreamData(data, meta)?.toObject();
if (d) {
result.push(d as GeneralDatum);
}
}
return Promise.resolve(result);
}
Upgrading from 1.x
The 2.x version of this library has changed somewhat as the 1.x library was ported
to TypeScript and updated to ES2022. Most of the same classes and methods have
been preserved, but some things have moved namespaces. Thankfully the move to
TypeScript makes refactoring an application using the 1.x API pretty straightforward,
as your IDE can usually offer the correct import
path to use for a given class.
For example, in the 1.x API you might have:
import {
Aggregations,
AuthorizationV2Builder,
DatumFilter,
DatumReadingTypes,
DatumStreamMetadataRegistry,
NodeDatumUrlHelper,
streamDatumUtils,
} from "solarnetwork-api-core";
Most of those exist in the 2.x API, just under different import paths:
import {
Aggregations,
DatumFilter,
DatumReadingTypes,
} from "solarnetwork-api-core/lib/domain";
import {
AuthorizationV2Builder,
SolarQueryApi, // <-- this replaces the NodeDatumUrlHelper!
} from "solarnetwork-api-core/lib/net";
import { DatumStreamMetadataRegistry } from "solarnetwork-api-core/lib/util";
import { datumForStreamData } from "solarnetwork-api-core/lib/util/datum";
One area that has changed somewhat significantly is the net
namespace. The
various *UrlHelper
classes have been reworked into Solar*Api
classes, such
as SolarQueryApi
and SolarUserApi
. The methods offered on those classes
remain mostly the same as in the 1.x library, but be sure to confirm with
the API docs. Here again your IDE will generally be able to point out broken
API usage, thanks to the TypeScript definitions included in the library.
Building
The build uses NPM and requires Node 17+. First, initialize the dependencies:
npm ci
Then you can run the build
script:
npm run build:dist
That will produce ES2022 modules with an entry point in lib/index.js
.
You can also produce an ES2022 bundle by running npm run build:bundle
. That will produce a single
bundled file at lib/solarnetwork-api-core.es.js
.
Releases
Releases are done using the gitflow branching model. Gitflow must be installed on your host system. Then you can run
npm run release
to version, build, commit, and publish the release. See the generate-release site for more information.
Unit tests
The unit tests can be run by running the test
script:
npm test
That will output the test results and produce a HTML code coverage report at coverage/index.html
.
Having a well-tested and reliable library is a core goal of this project. Unit tests are executed
automatically after every push into the develop
branch of this repository and their associated code
coverage is uploaded to Codecov.