particle-api-js

particle-api-js

JS Library for the Particle Cloud API for Node.js and the browser

Installation | Development | Conventions | Docs | Examples | Building | Releasing | License

TypeScript Support

particle-api-js is written in TypeScript and ships with full type declarations. All methods return fully typed responses — no casting needed:

import Particle from 'particle-api-js';
import type { DeviceInfo, LoginResponse, JSONResponse } from 'particle-api-js';

const particle = new Particle({ auth: 'your-token' });

// Response body is fully typed — no casting needed
const response = await particle.getDevice({ deviceId: 'abc123' });
console.log(response.body.name);  // string — fully typed as DeviceInfo

// Login response
const loginResponse = await particle.login({ username: '[e-mail]', password: 'pass' });
const token = loginResponse.body.access_token;  // string

All request option types and response types are exported from the package:

import type { GetDeviceOptions, ListDevicesOptions, JSONResponse } from 'particle-api-js';

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

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/particle-api-js@8/dist/particle.min.js">
</script>

Development

All essential commands are available at the root via npm run <script name> - e.g. npm run lint. To view the available commands, run: npm run

Testing Guide

Running Tests

npm test              # lint + typecheck + unit tests
npm run test:unit     # unit tests only
npm run test:watch    # unit tests in watch mode
npm run test:browser  # browser tests via karma
npm run coverage      # unit tests with coverage report

The Agent integration tests (source) depend on a real HTTP API backend and a valid Particle access token. Set environment variables to avoid test failures:

PARTICLE_API_BASE_URL=<url> PARTICLE_API_TOKEN=<token> npm test

Test Structure

• All test files are TypeScript (.spec.ts, .test.ts, .integration.ts) in the test/ directory
• Tests use import syntax — compiled output uses require() via module: "commonjs" in tsconfig.json
• Test runner: mocha with tsx for direct .ts execution (no pre-compilation needed)
• Assertions: chai (expect style) + chai-subset for partial matching + sinon-chai for spy/stub assertions + chai-as-promised for promise assertions
• Mocking: sinon

Writing a New Test

• Create a file in test/ following the naming convention: <Module>.spec.ts
• Import the test setup and modules:

import { sinon, expect } from './test-setup';
import MyModule from '../src/MyModule';

• Use describe/it blocks with expect assertions:

describe('MyModule', () => {
    afterEach(() => {
        sinon.restore();
    });

    it('does something', () => {
        const result = new MyModule();
        expect(result.value).to.equal('expected');
    });
});

• For partial object matching, use containSubset:

expect(result).to.containSubset({
    method: 'get',
    uri: '/v1/devices'
});

• Run your tests: npm run test:unit

Key Conventions

• Always import from ../src/<Module> (not ../lib/src/<Module>)
• Use sinon.restore() in afterEach to clean up stubs
• Use FakeAgent (in test/FakeAgent.ts) for mocking HTTP requests in Particle API tests
• Avoid any and unknown types in test files

How to write scripts that execute against local code changes?

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:

• create a js file on your local machine: touch my-api-test.js (somewhere outside of the root of this repo)
• within your test js file, init the api client like so:

const ParticleAPI = require('./path/to/particle-api-js'); // Make sure to substitute to correct path
const api = new ParticleAPI();

• add in any api calls, etc required to validate you changes

const devices = await api.listDevices({ auth: '<particle-auth-token>' });
console.log('MY DEVICES:', devices);

• 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)

How to name npm scripts

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, 2) amongst other lifecycle 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.

Conventions

• npm 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 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 in the test/ directory and are named like *.spec.ts, *.test.ts, or *.integration.ts
• 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. It contains examples to get started.

For more details, read the API reference on GitHub.

Examples

There are many snippets of using Particle API JS on the Documentation website and some complete examples in the GitHub examples directory.

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 file.

License

Copyright © 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See LICENSE for details.