wled-client/package.json

A friendly JS interface for controlling your [WLED](https://github.com/Aircoookie/WLED) devices from Node.js or the browser.

{
  "name": "wled-client",
  "version": "0.22.1",
  "author": "Jeff Schofield <jeff@jeffschofield.com>",
  "keywords": [
    "wled",
    "client",
    "isomorphic",
    "led"
  ],
  "license": "MIT",
  "repository": "github:ShiftLimits/wled-client",
  "bugs": {
    "url": "https://github.com/ShiftLimits/wled-client/issues",
    "email": "jeff@jeffschofield.com"
  },
  "type": "module",
  "exports": {
    "node": {
      "import": "./dist/node/wled-client.js",
      "require": "./dist/node/wled-client.cjs"
    },
    "script": "./dist/browser/wled-client.js",
    "default": "./dist/browser/wled-client.mjs"
  },
  "main": "dist/browser/wled-client.js",
  "types": "dist/node/wled-client.d.ts",
  "files": [
    "dist/**/*",
    "CHANGELOG.md"
  ],
  "gitHooks": {
    "commit-msg": "node scripts/verifyCommit.js"
  },
  "devDependencies": {
    "@types/node": "^16.11.7",
    "@types/ws": "^8.2.0",
    "chalk": "^5.0.1",
    "esbuild": "^0.15.12",
    "tsup": "^6.3.0",
    "type-fest": "^2.5.3",
    "typedoc": "^0.22.9",
    "typescript": "^4.4.4",
    "yorkie": "^2.0.0"
  },
  "dependencies": {
    "@js-bits/fetch": "^1.0.0",
    "isomorphic-ws": "^4.0.1",
    "ws": "^8.2.3"
  },
  "scripts": {
    "gen:docs": "typedoc",
    "build": "tsup && node scripts/browser.build"
  },
  "readme": "# WLED Client\n\nA friendly JS interface for controlling your [WLED](https://github.com/Aircoookie/WLED) devices from Node.js or the browser.\n\n**Note**: This is under early active development and may be subject to breaking changes until it reaches a stable version **1.0.0**.\n\n## About\n\nThis is a JS/TS client library for the control of [WLED](https://github.com/Aircoookie/WLED) devices. It offers a friendly simplified interface to send commands and receive data from your device, either piecemeal via WLED's JSON API or in real time via the WebSocket API. The full power of WLED's JSON API can also be harnessed through WLED Client by using `updateState`.\n\n## Installation\nWLED Client is isomorphic, meaning it will behave identically in both the browser and Node.js.\n### Browser\nFor a fast and traditional start, you can include the CDN script for WLED Client in your HTML:\n\n```html\n<script src=\"https://unpkg.com/wled-client/dist/browser/wled-client.js\"></script>\n```\n\nOr you can also [download](https://unpkg.com/wled-client/dist/browser/wled-client.js) this script directly to use it locally where you please. Either way, the `WLEDClient` class will now be available globally.\n\nFor a more modern approach, you can use the ES Module version of WLED Client provided by the CDN:\n\n```html\n<script src=\"https://unpkg.com/wled-client/dist/browser/wled-client.mjs\" type=\"module\"></script>\n```\n\nSee [usage](#usage) for next steps.\n\n### Node\nInstall with your favorite Node.js package manager:\n\n```bash\n# NPM\n$ npm install wled-client\n\n# Yarn\n$ yarn add wled-client\n```\n\nThen you can `require` or `import` WLED Client:\n\n```ts\nimport { WLEDClient } from 'wled-client'\n```\n```js\nconst { WLEDClient } = require('wled-client')\n```\n\nSee [usage](#usage) for next steps.\n\n### Other Environments\nUnder the hood, WLED Client uses the `fetch`, `WebSocket`, and `EventTarget` APIs to achieve the desired behavior. WLED Client is primarily meant to be used in the browser where these APIs are provided by the browser's execution environment. In order to work on node, each API has been polyfilled.\n\nIf your execution environment includes these APIs, you can use the browser script out of the box. Otherwise you'll need to add your own polyfills to make WLED Client work in your desired environment.\n\n## Usage\n\nCreate a new instance of the `WLEDClient` class and pass in the IP of your WLED device:\n\n```js\nconst wled = new WLEDClient('192.168.0.123')\n```\n\nOnce the class is constructed, WLED Client will immediately try to fetch the full device context (state, info, effects, and palettes) via the JSON API. If WebSocket is enabled, then at the same time WLED Client will also try to establish a connection via the WebSocket API.\n\nWhen WLED Client has successfully fetched the device context, the promise at `wled.isReady` will resolve. Then the device's state, info, effects, and palettes will be accessible. As long as the WebSocket API is connected updates to the device context will be received asynchronously, so changes made from outside WLED Client (like the WLED App) will be automatically applied to the client instance. You can always manually refetch the context using the `wled.refreshContext()` method.\n\n```js\nasync function init() {\n\tconst wled = new WLEDClient('192.168.0.123')\n\tawait wled.init()\n\n\tconsole.log(wled.info.version) // 0.12.0\n}\ninit().catch(console.error)\n```\n\nIf you're familiar with WLED's JSON API, you can make an update to the device state in a similar way using the `wled.updateState()` method. This method accepts an object with a friendly (verbose) interface that matches 1:1 with the WLED JSON API.\n\n```js\nasync function init() {\n\tconst wled = new WLEDClient('192.168.0.123')\n\tawait wled.init()\n\n\tconsole.log(wled.state.brightness) // 255\n\tawait wled.updateState({\n\t\tbrightness: 128\n\t})\n\tconsole.log(wled.state.brightness) // 128\n}\ninit().catch(console.error)\n```\n\nIf you'd rather be more direct, WLED Client offers simple methods to execute common commands as well.\n\n```js\nasync function init() {\n\tconst wled = new WLEDClient('192.168.0.123')\n\tawait wled.init()\n\n\tconsole.log(wled.state.brightness) // 255\n\tawait wled.setBrightness(128)\n\tconsole.log(wled.state.brightness) // 128\n}\ninit().catch(console.error)\n```\n\nSee the [WLEDClient class](https://shiftlimits.github.io/wled-client/classes/client.WLEDClient.html) page for a list of methods. At any point you can run any method that updates the device's state, regardless of WLED Client's ready state. If the WebSocket is not connected, state updates will be sent via the JSON API over HTTP.\n\n## Examples\n\n[Twitch integration](https://github.com/JeffSchofield/twitch-wled) example using [tmi.js](https://github.com/tmijs/tmi.js). Contains detailed instructions if you're new to Node.js.\n\nTo see how WLED Client handles various use cases, there are several example scripts in the [official examples repository](https://github.com/ShiftLimits/wled-client-examples).\n\n## Documentation\n\nThere is a wonderfully done documentation for the WLED JSON API to be found at the [WLED knowledge base](https://kno.wled.ge/interfaces/json-api/). WLED Client implements this with only slightly more verbose key names.\n\nSee the [API documentation](https://shiftlimits.github.io/wled-client/) page for a detailed run down of WLED Client's structure. The [WLEDClient class](https://shiftlimits.github.io/wled-client/classes/client.WLEDClient.html) docs has a quick list of properties and methods you can use. It may also help to check out the type definitions for [WLED Client](https://github.com/ShiftLimits/wled-client/blob/main/src/types.client.ts) and compare them to the type definitions for [WLED itself](https://github.com/ShiftLimits/wled-client/blob/main/src/types.wled.ts).\n\n### Versioning\n\nIn order to adhere to the NPM ecosystem, WLED Client follows semantic versioning. WLED Client will bump major versions when there is a breaking change in the API that you consume in your projects. This may happen when WLED introduces a breaking change in its API, or if there comes a need to restructure parts of WLED Client.\n\nOtherwise, we will bump minor versions every time we introduce support for new WLED features as the WLED project progresses. WLED Client aims to support whatever the latest stable version of WLED is.\n\n## License\n\nWLED Client is [MIT](LICENSE) licensed.\n"
}