Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/particle-iot/particle-api-js
JS Library for the Particle API
https://github.com/particle-iot/particle-api-js
core electron iot nodejs particle photon
Last synced: about 18 hours ago
JSON representation
JS Library for the Particle API
- Host: GitHub
- URL: https://github.com/particle-iot/particle-api-js
- Owner: particle-iot
- License: apache-2.0
- Created: 2015-09-24T18:06:37.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-24T20:43:33.000Z (about 2 months ago)
- Last Synced: 2024-10-30T08:18:37.057Z (about 2 months ago)
- Topics: core, electron, iot, nodejs, particle, photon
- Language: JavaScript
- Size: 7.68 MB
- Stars: 123
- Watchers: 47
- Forks: 53
- Open Issues: 39
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-particle - JavaScript SDK
README
# particle-api-js
JS Library for the Particle Cloud API for Node.js and the browser
[](https://app.circleci.com/pipelines/github/particle-iot/particle-api-js)
[Installation](#installation) | [Development](#development) | [Conventions](#conventions) | [Docs](#docs--resources) | [Examples](#examples) | [Building](#building) | [Releasing](#releasing) | [License](#license)
## Installation
`particle-api-js` is available from `npm` to use in Node.js, `bower` or jsDelivr CDN for use in the browser.
#### Npm
```
$ npm install particle-api-js
```
#### Bower
```
$ bower install particle-api-js
```
#### jsDelivr CDN
```html
```
## Development
All essential commands are available at the root via `npm run ` - e.g. `npm run lint`. To view the available commands, run: `npm run`
<details id="develop-run-tests">
<summary><b>How to run your tests</b></summary>
<p>
The `Agent` integration tests ([source](./test/Agent.integration.js)) depend on a real HTTP api backend and a valid Particle access token. Be sure to set relevant environment variables to avoid test failures. You can prefix commands test commands like this `PARTICLE_API_BASE_URL=<url> PARTICLE_API_TOKEN=<token> npm test`
`npm test` runs the tests.
`npm run coverage` shows code coverage
`npm run test:browser` runs tests in a browser via [karma](https://karma-runner.github.io/latest/index.html).
`npm run test:ci` runs tests in the exact same way CI system does
</p>
</details>
<details id="develop-run-locally">
<summary><b>How to write scripts that execute against local code changes?</b></summary>
<p>
Source code lives in the `./src` directory and is built for release via the `npm run build` command. To create a simple script file to test your changes, follow these steps:
1. create a `js` file on your local machine: `touch my-api-test.js` (somewhere outside of the root of this repo)
2. within your test `js` file, init the api client like so:
```js
const ParticleAPI = require('./path/to/particle-api-js'); // Make sure to substitute to correct path
const api = new ParticleAPI();
```
3. add in any api calls, etc required to validate you changes
```js
const devices = await api.listDevices({ auth: '<particle-auth-token>' });
console.log('MY DEVICES:', devices);
```
4. run it: `node ./path/to/my-api-test.js`
_NOTE: Requiring the root directory works via the `main` field specified in Particle API JS' `package.json` file ([docs](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#main))_
</p>
</details>
<details id="develop-npm-scripts">
<summary><b>How to name npm scripts</b></summary>
<p>
npm scripts are the primary means of executing programmatic tasks (e.g. tests, linting, releasing, etc) within the repo. to view available scripts, run `npm run`.
when creating a new script, be sure it does not already exist and use the following naming convention:
`<category>:[<subcategory>]:[<action>]`
our standard categories include: `test`, `lint`, `build`, `clean`, `docs`, `package`, `dependencies`, and `release`. top-level scripts - e.g. `npm run clean` - will typically run all of its subcategories (e.g. `npm run clean:dist && npm run clean:tmp`).
`npm` itself includes special handling for `test` and `start` (doc: [1](https://docs.npmjs.com/cli/v6/commands/npm-test), [2](https://docs.npmjs.com/cli/v6/commands/npm-start)) amongst other [lifecycle scripts](https://docs.npmjs.com/cli/v7/using-npm/scripts#life-cycle-scripts) - use these to expose key testing and start-up commands.
sometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.
</p>
</details>
## Conventions
* [npm scripts](https://docs.npmjs.com/misc/scripts) form the _developer's API_ for the repo and all of its packages - key orchestration commands should be exposed here
* document developer-facing process / tooling instructions in the [Development](#development) section
* plan to release your changes upon merging to `main` - refrain from merging if you cannot so you don't leave unpublished changes to others
* avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates
* test files live alongside their source files and are named like `*.test.js` or `*.spec.js`
* if the linter does not flag your code (error or warning), it's formatted properly
* avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts
* todo comments include your last name and are formatted like: `TODO (mirande): <message>`
## Docs & Resources
First, read the [documentation for Particle API JS on the Documentation website.][docs-website] It contains examples to get started.
For more details, read the [API reference on GitHub.](docs/api.md)
## Examples
There [are many snippets of using Particle API JS on the Documentation website][docs-website] and some complete examples in the [GitHub examples directory.](/examples)
## Building
Make your changes to the files in the `src` directory, then from the project directory run:
```
$ npm run build
```
The `dist` directory will contain the compiled and minified files that can be included in your project.
Run tests to make sure your changes are good:
```
$ npm test
```
Update the API docs with your changes:
```
$ npm run docs
```
## Releasing
See the release process in the [RELEASE.md](RELEASE.md) file.
## License
Copyright © 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See [LICENSE](/LICENSE) for details.
[docs-website]: https://docs.particle.io/reference/javascript/