{"id":13850197,"url":"https://github.com/particle-iot/particle-api-js","last_synced_at":"2026-04-01T20:45:01.484Z","repository":{"id":2063292,"uuid":"43084056","full_name":"particle-iot/particle-api-js","owner":"particle-iot","description":"JS Library for the Particle API","archived":false,"fork":false,"pushed_at":"2026-03-13T23:40:13.000Z","size":8840,"stargazers_count":123,"open_issues_count":48,"forks_count":54,"subscribers_count":43,"default_branch":"master","last_synced_at":"2026-03-14T11:04:05.682Z","etag":null,"topics":["core","electron","iot","nodejs","particle","photon"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/particle-iot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-09-24T18:06:37.000Z","updated_at":"2026-03-13T23:40:17.000Z","dependencies_parsed_at":"2023-12-26T13:03:27.264Z","dependency_job_id":"15b314fb-b493-4994-b6bb-7950d09dea99","html_url":"https://github.com/particle-iot/particle-api-js","commit_stats":{"total_commits":515,"total_committers":31,"mean_commits":"16.612903225806452","dds":0.8330097087378641,"last_synced_commit":"354d4019b2fe96edb687208145083124b2dca446"},"previous_names":["spark/particle-api-js"],"tags_count":98,"template":false,"template_full_name":null,"purl":"pkg:github/particle-iot/particle-api-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/particle-iot%2Fparticle-api-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/particle-iot%2Fparticle-api-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/particle-iot%2Fparticle-api-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/particle-iot%2Fparticle-api-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/particle-iot","download_url":"https://codeload.github.com/particle-iot/particle-api-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/particle-iot%2Fparticle-api-js/sbom","scorecard":{"id":721048,"data":{"date":"2025-08-11","repo":{"name":"github.com/particle-iot/particle-api-js","commit":"7d2c215fe92f6c28082dcee4b2d8601137ba92dc"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.4,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":5,"reason":"7 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":4,"reason":"Found 5/12 approved changesets -- score normalized to 4","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 24 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"61 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9","Warn: Project is vulnerable to: GHSA-8w4h-3cm3-2pm2","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx","Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-9vvw-cc9w-f27h","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-h6ch-v84p-w6p9","Warn: Project is vulnerable to: GHSA-qrmc-fj45-qfc2","Warn: Project is vulnerable to: GHSA-8r6j-v8pm-fqw3","Warn: Project is vulnerable to: MAL-2023-462","Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5","Warn: Project is vulnerable to: GHSA-qh2h-chj9-jffq","Warn: Project is vulnerable to: GHSA-vfrc-7r7c-w9mx","Warn: Project is vulnerable to: GHSA-7wwv-vh3v-89cq","Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj","Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-wrvr-8mpx-r7pp","Warn: Project is vulnerable to: GHSA-hxm2-r34f-qmc5","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h","Warn: Project is vulnerable to: GHSA-3mpr-hq3p-49h9","Warn: Project is vulnerable to: GHSA-fhjf-83wg-r2j9","Warn: Project is vulnerable to: GHSA-w9mr-4mfr-499f","Warn: Project is vulnerable to: GHSA-8g77-54rh-46hx","Warn: Project is vulnerable to: GHSA-4p35-cfcx-8653","Warn: Project is vulnerable to: GHSA-7f3x-x4pr-wqhj","Warn: Project is vulnerable to: GHSA-jpp7-7chh-cf67","Warn: Project is vulnerable to: GHSA-q6wq-5p59-983w","Warn: Project is vulnerable to: GHSA-j9fq-vwqv-2fm2","Warn: Project is vulnerable to: GHSA-pqw5-jmp5-px4v","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-6g33-f262-xjp4","Warn: Project is vulnerable to: GHSA-9q5w-79cv-947m","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5","Warn: Project is vulnerable to: GHSA-jv35-xqg7-f92r","Warn: Project is vulnerable to: GHSA-4g88-fppr-53pp","Warn: Project is vulnerable to: GHSA-4jqc-8m5r-9rpr","Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6","Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj","Warn: Project is vulnerable to: GHSA-3jfq-g458-7qm9","Warn: Project is vulnerable to: GHSA-r628-mhmh-qjhw","Warn: Project is vulnerable to: GHSA-9r2w-394v-53qc","Warn: Project is vulnerable to: GHSA-5955-9wpr-37jh","Warn: Project is vulnerable to: GHSA-qq89-hq3f-393p","Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-w5p7-h5w8-2hfq","Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986","Warn: Project is vulnerable to: GHSA-g78m-2chm-r7qv","Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7","Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh","Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-22T11:22:37.691Z","repository_id":2063292,"created_at":"2025-08-22T11:22:37.691Z","updated_at":"2025-08-22T11:22:37.691Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["core","electron","iot","nodejs","particle","photon"],"created_at":"2024-08-04T20:01:01.034Z","updated_at":"2026-04-01T20:45:01.473Z","avatar_url":"https://github.com/particle-iot.png","language":"TypeScript","funding_links":[],"categories":["Tools and SDKs"],"sub_categories":[],"readme":"# particle-api-js\nJS Library for the Particle Cloud API for Node.js and the browser\n\n[![Build Status](https://circleci.com/gh/particle-iot/particle-api-js.svg?style=shield)](https://app.circleci.com/pipelines/github/particle-iot/particle-api-js)\n\n[Installation](#installation) | [Development](#development)  | [Conventions](#conventions) | [Docs](#docs--resources) | [Examples](#examples) | [Building](#building) | [Releasing](#releasing) | [License](#license)\n\n## TypeScript Support\n\n`particle-api-js` is written in TypeScript and ships with full type declarations. All methods return fully typed responses — no casting needed:\n\n```typescript\nimport Particle from 'particle-api-js';\nimport type { DeviceInfo, LoginResponse, JSONResponse } from 'particle-api-js';\n\nconst particle = new Particle({ auth: 'your-token' });\n\n// Response body is fully typed — no casting needed\nconst response = await particle.getDevice({ deviceId: 'abc123' });\nconsole.log(response.body.name);  // string — fully typed as DeviceInfo\n\n// Login response\nconst loginResponse = await particle.login({ username: 'user@example.com', password: 'pass' });\nconst token = loginResponse.body.access_token;  // string\n```\n\nAll request option types and response types are exported from the package:\n\n```typescript\nimport type { GetDeviceOptions, ListDevicesOptions, JSONResponse } from 'particle-api-js';\n```\n\n## Installation\n\n`particle-api-js` is available from `npm` to use in Node.js, `bower` or jsDelivr CDN for use in the browser.\n\n#### Npm\n```\n$ npm install particle-api-js\n```\n\n#### Bower\n```\n$ bower install particle-api-js\n```\n\n#### jsDelivr CDN\n```html\n\u003cscript type=\"text/javascript\" src=\"https://cdn.jsdelivr.net/npm/particle-api-js@8/dist/particle.min.js\"\u003e\n\u003c/script\u003e\n```\n\n## Development\n\n\nAll essential commands are available at the root via `npm run \u003cscript name\u003e` - e.g. `npm run lint`. To view the available commands, run: `npm run`\n\n\u003cdetails id=\"develop-testing\"\u003e\n\u003csummary\u003e\u003cb\u003eTesting Guide\u003c/b\u003e\u003c/summary\u003e\n\n### Running Tests\n\n```bash\nnpm test              # lint + typecheck + unit tests\nnpm run test:unit     # unit tests only\nnpm run test:watch    # unit tests in watch mode\nnpm run test:browser  # browser tests via karma\nnpm run coverage      # unit tests with coverage report\n```\n\nThe `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:\n\n```bash\nPARTICLE_API_BASE_URL=\u003curl\u003e PARTICLE_API_TOKEN=\u003ctoken\u003e npm test\n```\n\n### Test Structure\n\n- All test files are TypeScript (`.spec.ts`, `.test.ts`, `.integration.ts`) in the `test/` directory\n- Tests use `import` syntax — compiled output uses `require()` via `module: \"commonjs\"` in `tsconfig.json`\n- Test runner: [mocha](https://mochajs.org/) with [tsx](https://github.com/privatenumber/tsx) for direct `.ts` execution (no pre-compilation needed)\n- 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\n- Mocking: [sinon](https://sinonjs.org/)\n\n### Writing a New Test\n\n1. Create a file in `test/` following the naming convention: `\u003cModule\u003e.spec.ts`\n2. Import the test setup and modules:\n\n```typescript\nimport { sinon, expect } from './test-setup';\nimport MyModule from '../src/MyModule';\n```\n\n3. Use `describe`/`it` blocks with `expect` assertions:\n\n```typescript\ndescribe('MyModule', () =\u003e {\n    afterEach(() =\u003e {\n        sinon.restore();\n    });\n\n    it('does something', () =\u003e {\n        const result = new MyModule();\n        expect(result.value).to.equal('expected');\n    });\n});\n```\n\n4. For partial object matching, use `containSubset`:\n\n```typescript\nexpect(result).to.containSubset({\n    method: 'get',\n    uri: '/v1/devices'\n});\n```\n\n5. Run your tests: `npm run test:unit`\n\n### Key Conventions\n\n- Always import from `../src/\u003cModule\u003e` (not `../lib/src/\u003cModule\u003e`)\n- Use `sinon.restore()` in `afterEach` to clean up stubs\n- Use `FakeAgent` (in `test/FakeAgent.ts`) for mocking HTTP requests in Particle API tests\n- Avoid `any` and `unknown` types in test files\n\n\u003c/details\u003e\n\n\u003cdetails id=\"develop-run-locally\"\u003e\n\u003csummary\u003e\u003cb\u003eHow to write scripts that execute against local code changes?\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\n\nSource 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:\n\n1. create a `js` file on your local machine: `touch my-api-test.js` (somewhere outside of the root of this repo)\n2. within your test `js` file, init the api client like so:\n\n```js\nconst ParticleAPI = require('./path/to/particle-api-js'); // Make sure to substitute to correct path\nconst api = new ParticleAPI();\n```\n\n3. add in any api calls, etc required to validate you changes\n\n```js\nconst devices = await api.listDevices({ auth: '\u003cparticle-auth-token\u003e' });\nconsole.log('MY DEVICES:', devices);\n```\n\n4. run it: `node ./path/to/my-api-test.js`\n\n_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))_ \n\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\u003cdetails id=\"develop-npm-scripts\"\u003e\n\u003csummary\u003e\u003cb\u003eHow to name npm scripts\u003c/b\u003e\u003c/summary\u003e\n\u003cp\u003e\n\nnpm 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`.\n\nwhen creating a new script, be sure it does not already exist and use the following naming convention:\n\n`\u003ccategory\u003e:[\u003csubcategory\u003e]:[\u003caction\u003e]`\n\nour 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 \u0026\u0026 npm run clean:tmp`).\n\n`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.\n\nsometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n## Conventions\n\n* [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\n* document developer-facing process / tooling instructions in the [Development](#development) section\n* plan to release your changes upon merging to `main` - refrain from merging if you cannot so you don't leave unpublished changes to others\n* avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates\n* test files live in the `test/` directory and are named like `*.spec.ts`, `*.test.ts`, or `*.integration.ts`\n* if the linter does not flag your code (error or warning), it's formatted properly\n* avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts\n* todo comments include your last name and are formatted like: `TODO (mirande): \u003cmessage\u003e`\n  \n\n## Docs \u0026 Resources\n\nFirst, read the [documentation for Particle API JS on the Documentation website.][docs-website] It contains examples to get started.\n\nFor more details, read the [API reference on GitHub.](docs/api.md)\n\n## Examples\n\nThere [are many snippets of using Particle API JS on the Documentation website][docs-website] and some complete examples in the [GitHub examples directory.](/examples)\n\n## Building\n\nMake your changes to the files in the `src` directory, then from the project directory run:\n\n```\n$ npm run build\n```\n\nThe `dist` directory will contain the compiled and minified files that can be included in your project.\n\nRun tests to make sure your changes are good:\n\n```\n$ npm test\n```\n\nUpdate the API docs with your changes:\n\n```\n$ npm run docs\n```\n\n## Releasing\n\nSee the release process in the [RELEASE.md](RELEASE.md) file.\n\n## License\n\nCopyright \u0026copy; 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See [LICENSE](/LICENSE) for details.\n\n[docs-website]: https://docs.particle.io/reference/javascript/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparticle-iot%2Fparticle-api-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparticle-iot%2Fparticle-api-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparticle-iot%2Fparticle-api-js/lists"}