particle-api-js 9.4.1 → 10.1.0

package/src/Client.js

@@ -0,0 +1,170 @@
+const Library = require('./Library');
+let Particle;
+
+class Client {
+	constructor({ auth, api = new Particle() }){
+		this.auth = auth;
+		this.api = api;
+	}
+
+	ready(){
+		return Boolean(this.auth);
+	}
+
+	/**
+	 * Get firmware library objects
+	 * @param  {Object} query The query parameters for libraries. See Particle.listLibraries
+	 * @returns {Promise} A promise
+	 */
+	libraries(query = {}){
+		return this.api.listLibraries(Object.assign({}, query, { auth: this.auth }))
+			.then(payload => {
+				const libraries = payload.body.data || [];
+				return libraries.map(l => new Library(this, l));
+			});
+	}
+
+	/**
+	 * Get one firmware library object
+	 * @param  {String} name Name of the library to fetch
+	 * @param  {Object} query The query parameters for libraries. See Particle.getLibrary
+	 * @returns {Promise} A promise
+	 */
+	library(name, query = {}){
+		return this.api.getLibrary(Object.assign({}, query, { name, auth: this.auth }))
+			.then(payload => {
+				const library = payload.body.data || {};
+				return new Library(this, library);
+			});
+	}
+
+	/**
+	 * Get list of library versions
+	 * @param  {String} name Name of the library to fetch
+	 * @param  {Object} query The query parameters for versions. See Particle.getLibraryVersions
+	 * @returns {Promise} A promise
+	 */
+	libraryVersions(name, query = {}){
+		return this.api.getLibraryVersions(Object.assign({}, query, { name, auth: this.auth }))
+			.then(payload => {
+				const libraries = payload.body.data || [];
+				return libraries.map(l => new Library(this, l));
+			});
+	}
+
+	/**
+	 * Contribute a new library version
+	 * @param  {Buffer} archive The compressed archive with the library source
+	 * @returns {Promise} A promise
+	 */
+	contributeLibrary(archive){
+		return this.api.contributeLibrary({ archive, auth: this.auth })
+			.then(payload => {
+				const library = payload.body.data || {};
+				return new Library(this, library);
+			}, error => {
+				this._throwError(error);
+			});
+	}
+
+	/**
+	 * Make the the most recent private library version public
+	 * @param  {string} name The name of the library to publish
+	 * @return {Promise} To publish the library
+	 */
+	publishLibrary(name){
+		return this.api.publishLibrary({ name, auth: this.auth })
+			.then(payload => {
+				const library = payload.body.data || {};
+				return new Library(this, library);
+			}, error => {
+				this._throwError(error);
+			});
+	}
+
+	/**
+	 * Delete an entire published library
+	 * @param {object} params	Specific params of the library to delete
+	 * @param {string} params.name	Name of the library to delete
+	 * @param {string} params.force	Key to force deleting a public library
+	 * @returns {Promise} A promise
+	 */
+	deleteLibrary({ name, force }){
+		return this.api.deleteLibrary({ name, force, auth: this.auth })
+			.then(() => true, error => this._throwError(error));
+	}
+
+	_throwError(error){
+		if (error.body && error.body.errors){
+			const errorMessages = error.body.errors.map((e) => e.message).join('\n');
+			throw new Error(errorMessages);
+		}
+		throw error;
+	}
+
+	downloadFile(uri){
+		return this.api.downloadFile({ uri });
+	}
+
+	/**
+	 * @param {Object} files Object containing files to be compiled
+	 * @param {Number} platformId Platform id number of the device you are compiling for
+	 * @param {String} targetVersion System firmware version to compile against
+	 * @returns {Promise} A promise
+	 * @deprecated Will be removed in 6.5
+	 */
+	compileCode(files, platformId, targetVersion){
+		return this.api.compileCode({ files, platformId, targetVersion, auth: this.auth });
+	}
+
+	/**
+	 * @param {object} params
+	 * @param {string} params.deviceId	Device ID or Name
+	 * @param {boolean} params.signal	Signal on or off
+	 * @returns {Promise} A promise
+	 * @deprecated Will be removed in 6.5
+	 */
+	signalDevice({ signal, deviceId }){
+		return this.api.signalDevice({ signal, deviceId, auth: this.auth });
+	}
+
+	/**
+	 * @returns {Promise} A promise
+	 * @deprecated Will be removed in 6.5
+	 */
+	listDevices(){
+		return this.api.listDevices({ auth: this.auth });
+	}
+
+	/**
+	 * @returns {Promise} A promise
+	 * @deprecated Will be removed in 6.5
+	 */
+	listBuildTargets(){
+		return this.api.listBuildTargets({ onlyFeatured: true, auth: this.auth })
+			.then(payload => {
+				let targets = [];
+				for (let target of payload.body.targets){
+					for (let platform of target.platforms){
+						targets.push({
+							version: target.version,
+							platform: platform,
+							prerelease: target.prereleases.indexOf(platform) > -1,
+							firmware_vendor: target.firmware_vendor
+						});
+					}
+				}
+				return targets;
+			}, () => {});
+	}
+
+	trackingIdentity({ full = false, context = undefined }={}){
+		return this.api.trackingIdentity({ full, context, auth: this.auth })
+			.then(payload => {
+				return payload.body;
+			});
+	}
+}
+
+module.exports = Client;
+Particle = require('./Particle'); // Move it to after the export to avoid issue with circular reference

package/src/Defaults.js

@@ -0,0 +1,7 @@
+module.exports = {
+	baseUrl: 'https://api.particle.io',
+	clientSecret: 'particle-api',
+	clientId: 'particle-api',
+	tokenDuration: 7776000, // 90 days
+	auth: undefined
+};

package/src/EventStream.js

@@ -0,0 +1,263 @@
+/* eslint max-depth: 0 */
+const http = require('http');
+const https = require('https');
+const url = require('url');
+const { EventEmitter } = require('events');
+
+class EventStream extends EventEmitter {
+	constructor(uri, token) {
+		super();
+		this.uri = uri;
+		this.token = token;
+		this.reconnectInterval = 2000;
+		this.timeout = 13000; // keep alive can be sent up to 12 seconds after last event
+		this.data = '';
+		this.buf = '';
+
+		this.parse = this.parse.bind(this);
+		this.end = this.end.bind(this);
+		this.idleTimeoutExpired = this.idleTimeoutExpired.bind(this);
+	}
+
+	connect() {
+		return new Promise((resolve, reject) => {
+			const { hostname, protocol, port, path } = url.parse(this.uri);
+			this.origin = `${protocol}//${hostname}${port ? (':' + port) : ''}`;
+
+			const isSecure = protocol === 'https:';
+			const requestor = isSecure ? https : http;
+			const req = requestor.request({
+				hostname,
+				protocol,
+				path: `${path}?access_token=${this.token}`,
+				method: 'get',
+				port: parseInt(port, 10) || (isSecure ? 443 : 80),
+				// @ts-ignore
+				mode: 'prefer-streaming'
+			});
+
+			this.req = req;
+
+			let connected = false;
+			let connectionTimeout = setTimeout(() => {
+				if (this.req) {
+					this.req.abort();
+				}
+				reject({ error: new Error('Timeout'), errorDescription: `Timeout connecting to ${this.uri}` });
+			}, this.timeout);
+
+			req.on('error', e => {
+				clearTimeout(connectionTimeout);
+
+				if (connected) {
+					this.end();
+				} else {
+					reject({ error: e, errorDescription: `Network error from ${this.uri}` });
+				}
+			});
+
+			req.on('response', res => {
+				clearTimeout(connectionTimeout);
+
+				const statusCode = res.statusCode;
+				if (statusCode !== 200) {
+					let body = '';
+					res.on('data', chunk => body += chunk);
+					res.on('end', () => {
+						try {
+							body = JSON.parse(body);
+						} catch (e) {
+							// don't bother doing anything special if the JSON.parse fails
+							// since we are already about to reject the promise anyway
+						} finally {
+							let errorDescription = `HTTP error ${statusCode} from ${this.uri}`;
+							// @ts-ignore
+							if (body && body.error_description) {
+								// @ts-ignore
+								errorDescription += ' - ' + body.error_description;
+							}
+							reject({ statusCode, errorDescription, body });
+							this.req = undefined;
+						}
+					});
+					return;
+				}
+
+				this.data = '';
+				this.buf = '';
+
+				connected = true;
+				res.on('data', this.parse);
+				res.once('end', this.end);
+				this.startIdleTimeout();
+				resolve(this);
+			});
+			req.end();
+		});
+	}
+
+	abort() {
+		if (this.req) {
+			this.req.abort();
+			this.req = undefined;
+		}
+		this.removeAllListeners();
+	}
+
+	/* Private methods */
+
+	emitSafe(event, param) {
+		try {
+			this.emit(event, param);
+		} catch (error) {
+			if (event !== 'error') {
+				this.emitSafe('error', error);
+			}
+		}
+	}
+
+	end() {
+		this.stopIdleTimeout();
+
+		if (!this.req) {
+			// request was ended intentionally by abort
+			// do not auto reconnect.
+			return;
+		}
+
+		this.req = undefined;
+		this.emitSafe('disconnect');
+		this.reconnect();
+	}
+
+	reconnect() {
+		setTimeout(() => {
+			if (this.isOffline()) {
+				this.reconnect();
+				return;
+			}
+
+			this.emitSafe('reconnect');
+			this.connect().then(() => {
+				this.emitSafe('reconnect-success');
+			}).catch(err => {
+				this.emitSafe('reconnect-error', err);
+				this.reconnect();
+			});
+		}, this.reconnectInterval);
+	}
+
+	isOffline() {
+		if (typeof navigator === 'undefined' || navigator.hasOwnProperty('onLine')) {
+			return false;
+		}
+		return !navigator.onLine;
+	}
+
+	startIdleTimeout() {
+		this.stopIdleTimeout();
+		this.idleTimeout = setTimeout(this.idleTimeoutExpired, this.timeout);
+	}
+
+	stopIdleTimeout() {
+		if (this.idleTimeout) {
+			clearTimeout(this.idleTimeout);
+			this.idleTimeout = null;
+		}
+	}
+
+	idleTimeoutExpired() {
+		if (this.req) {
+			this.req.abort();
+			this.end();
+		}
+	}
+
+	parse(chunk) {
+		this.startIdleTimeout();
+
+		this.buf += chunk;
+		let pos = 0;
+		let length = this.buf.length;
+		let discardTrailingNewline = false;
+
+		while (pos < length) {
+			if (discardTrailingNewline) {
+				if (this.buf[pos] === '\n') {
+					++pos;
+				}
+				discardTrailingNewline = false;
+			}
+
+			let lineLength = -1;
+			let fieldLength = -1;
+
+			for (let i = pos; lineLength < 0 && i < length; ++i) {
+				const c = this.buf[i];
+				if (c === ':') {
+					if (fieldLength < 0) {
+						fieldLength = i - pos;
+					}
+				} else if (c === '\r') {
+					discardTrailingNewline = true;
+					lineLength = i - pos;
+				} else if (c === '\n') {
+					lineLength = i - pos;
+				}
+			}
+
+			if (lineLength < 0) {
+				break;
+			}
+
+			this.parseEventStreamLine(pos, fieldLength, lineLength);
+
+			pos += lineLength + 1;
+		}
+
+		if (pos === length) {
+			this.buf = '';
+		} else if (pos > 0) {
+			this.buf = this.buf.slice(pos);
+		}
+	}
+
+	parseEventStreamLine(pos, fieldLength, lineLength) {
+		if (lineLength === 0) {
+			try {
+				if (this.data.length > 0 && this.event) {
+					const event = JSON.parse(this.data);
+					event.name = this.eventName || '';
+					this.emitSafe('event', event);
+				}
+			} catch (e) {
+				// do nothing if JSON.parse fails
+			} finally {
+				this.data = '';
+				this.eventName = undefined;
+				this.event = false;
+			}
+		} else if (fieldLength > 0) {
+			const field = this.buf.slice(pos, pos + fieldLength);
+			let step = 0;
+
+			if (this.buf[pos + fieldLength + 1] !== ' ') {
+				step = fieldLength + 1;
+			} else {
+				step = fieldLength + 2;
+			}
+			pos += step;
+			const valueLength = lineLength - step;
+			const value = this.buf.slice(pos, pos + valueLength);
+
+			if (field === 'data') {
+				this.data += value + '\n';
+			} else if (field === 'event') {
+				this.eventName = value;
+				this.event = true;
+			}
+		}
+	}
+}
+
+module.exports = EventStream;

package/src/Library.js

@@ -0,0 +1,33 @@
+/* Library
+ * Represents a version of a library contributed in the cloud.
+ */
+
+class Library {
+	constructor(client, data) {
+		// Make client non-enumerable so it doesn't show up in Object.keys, JSON.stringify, etc
+		Object.defineProperty(this, 'client', { value: client });
+		this._assignAttributes(data);
+		this.downloadUrl = data.links && data.links.download;
+	}
+
+	_assignAttributes(data) {
+		Object.assign(this, data.attributes);
+	}
+
+
+	/**
+	 * Download the compressed file containing the source code for this library version.
+	 * @return {Promise} Resolves to the .tar.gz compressed source code
+	 */
+	download() {
+		if (!this.downloadUrl) {
+			return Promise.reject(new Error('No download URL for this library'));
+		}
+		// @ts-ignore
+		return this.client.downloadFile(this.downloadUrl);
+	}
+
+	/* TODO: add a versions() method to fetch an array of library objects */
+}
+
+module.exports = Library;