particle-api-js 11.1.7 → 12.0.0

package/README.md

@@ -5,6 +5,31 @@ JS Library for the Particle Cloud API for Node.js and the browser
 
 [Installation](#installation) | [Development](#development)  | [Conventions](#conventions) | [Docs](#docs--resources) | [Examples](#examples) | [Building](#building) | [Releasing](#releasing) | [License](#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:
+
+```typescript
+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: 'user@example.com', password: 'pass' });
+const token = loginResponse.body.access_token;  // string
+```
+
+All request option types and response types are exported from the package:
+
+```typescript
+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.
@@ -30,21 +55,76 @@ $ bower install particle-api-js
 
 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`
 
-<details id="develop-run-tests">
-<summary><b>How to run your tests</b></summary>
-<p>
+<details id="develop-testing">
+<summary><b>Testing Guide</b></summary>
 
-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`
+### Running Tests
 
-`npm test` runs the tests.
+```bash
+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
+```
 
-`npm run coverage` shows code coverage 
+The `Agent` integration tests ([source](./test/Agent.integration.ts)) depend on a real HTTP API backend and a valid Particle access token. Set environment variables to avoid test failures:
 
-`npm run test:browser` runs tests in a browser via [karma](https://karma-runner.github.io/latest/index.html).
+```bash
+PARTICLE_API_BASE_URL=<url> PARTICLE_API_TOKEN=<token> npm test
+```
 
-`npm run test:ci` runs tests in the exact same way CI system does
+### 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](https://mochajs.org/) with [tsx](https://github.com/privatenumber/tsx) for direct `.ts` execution (no pre-compilation needed)
+- Assertions: [chai](https://www.chaijs.com/) (`expect` style) + [chai-subset](https://github.com/debitoor/chai-subset) for partial matching + [sinon-chai](https://github.com/domenic/sinon-chai) for spy/stub assertions + [chai-as-promised](https://github.com/domenic/chai-as-promised) for promise assertions
+- Mocking: [sinon](https://sinonjs.org/)
+
+### Writing a New Test
+
+1. Create a file in `test/` following the naming convention: `<Module>.spec.ts`
+2. Import the test setup and modules:
+
+```typescript
+import { sinon, expect } from './test-setup';
+import MyModule from '../src/MyModule';
+```
+
+3. Use `describe`/`it` blocks with `expect` assertions:
+
+```typescript
+describe('MyModule', () => {
+    afterEach(() => {
+        sinon.restore();
+    });
+
+    it('does something', () => {
+        const result = new MyModule();
+        expect(result.value).to.equal('expected');
+    });
+});
+```
+
+4. For partial object matching, use `containSubset`:
+
+```typescript
+expect(result).to.containSubset({
+    method: 'get',
+    uri: '/v1/devices'
+});
+```
+
+5. 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
 
-</p>
 </details>
 
 <details id="develop-run-locally">
@@ -102,7 +182,7 @@ sometimes your new script will be very similar to an existing script. in those c
 * 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`
+* 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>`