{"_id":"@dre2901/myq-api","_rev":"1-64c37d747818b1f8c780431f03ec01e4","name":"@dre2901/myq-api","dist-tags":{"latest":"2.0.5"},"versions":{"2.0.5":{"name":"@dre2901/myq-api","version":"2.0.5","description":"An updated API to interface with myQ devices. Fork of an original implementation done by Thomas Munduchira (https://thomasmunduchira.com/)","keywords":["myq","chamberlain","liftmaster","garage","door","light","device","automation","smart","home","api"],"homepage":"https://github.com/dre2901/myq-api","bugs":{"url":"https://github.com/dre2901/myq-api/issues"},"license":"MIT","author":{"name":"Thomas Munduchira","email":"thomas@thomasmunduchira.com","url":"https://thomasmunduchira.com/"},"contributors":[{"name":"Dimitry Remenyuk","email":"dre2901@gmail.com"}],"main":"src/index.js","repository":{"type":"git","url":"git+https://github.com/dre2901/myq-api.git"},"scripts":{"lint":"eslint --ignore-path .gitignore ./","fix":"eslint --fix --ignore-path .gitignore ./","test":"jest test/unit","test:e2e":"jest test/e2e","test:coverage":"jest --coverage test/unit","test:mutants":"stryker run"},"dependencies":{"axios":"^0.21.1","axios-debug-log":"^0.8.0","crypto":"^1.0.1","debug":"^4.1.1"},"devDependencies":{"@stryker-mutator/core":"^3.3.1","@stryker-mutator/javascript-mutator":"^3.3.1","@stryker-mutator/jest-runner":"^3.3.1","axios-mock-adapter":"^1.18.2","coveralls":"^3.1.0","eslint":"^7.7.0","eslint-config-airbnb-base":"^14.2.0","eslint-config-prettier":"^6.11.0","eslint-plugin-import":"^2.22.0","eslint-plugin-jest":"^23.20.0","eslint-plugin-jsdoc":"^30.2.4","eslint-plugin-node":"^11.1.0","eslint-plugin-prettier":"^3.1.4","jest":"^26.4.1","prettier":"^2.0.5"},"engines":{"node":">=10"},"gitHead":"87bd452fbb604c2c5ff72c398a6052c52ccf2279","_id":"@dre2901/myq-api@2.0.5","_nodeVersion":"14.14.0","_npmVersion":"6.14.8","dist":{"integrity":"sha512-VWwS6s2WaWpR3e/JSrc+yP65jKlk/vXaDKKUqwrS4o/fITIG7OEvDgo4UUYLNBGPZqbuavQpRs5ECK1/0prYdg==","shasum":"fc1bb0f931688f0e6c8ca08070a4eb9d03c21e32","tarball":"https://registry.npmjs.org/@dre2901/myq-api/-/myq-api-2.0.5.tgz","fileCount":9,"unpackedSize":66086,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhGp8MCRA9TVsSAnZWagAAkKYP/RO35N7G8IQE+wepgfeA\n1FOfDFmZ4JoyVskl5sqmFLk8aGE6TNlN97OZyrIWy4TAgnWitR1ICGzAEUeR\nV4W2uY/jUoZ6HafxUXP+PFsawgsltD9hDjfU6Hx4itv8jhh9kmzRknCQf/0K\na0SNDfrPS+lNNIpkYy4Umla9bwV8K4F84XjwMQDruhgIPWw4BB69uAhMEwhr\nNnic1mIDfw1TJNn+xuAeTe2i1MSX/HZD2e30bQiT/8xX2FZoBAmuoFyQeKqy\nzxE6d88tzhakmJFMNAvaFMiRvjSiczYazIafj6oaHmuLAXal6ur4AfsNfrcx\nkAytkBAfedtMVjDOEeJJs10++EK5hGR4Us9iRZBkD6Q2Im3lOmSoO6+DIvr7\nF/9tSZBNjg+OBUAFmGMBubv2DYy0KMzx8Uu3lcPNTx8uG4fbgkdiepKauukZ\nPUJ+9v+ZWKs7k4Wx6Y+fKyv9QOImQ7a6AkXdVqR6+U+NtM1KuPBw+loCOpR9\ncH8H3801rUVhZ4s0ciBt5PnLCLDMFhLJI54LkQSTENYs7nz1fPU8JoXoAs/o\nqo124HKg+qqWTyUQiDJLc+2ePc4BI1N58Q8DPeHCLNVxKIUKTWTsw/yw81uI\n6ALO0Wv4QKlnG4dh1aX6gJGTOARYQbHChJF0FN7xM3G3gIfqxmUrOS22o128\nhWwr\r\n=ySgx\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIBVRcs8lK3/bG5hlpwpL7bAEFmOv1qButaQV4HaUhU3bAiBgEdPOxL4wAmz48U0ohUqZcnfj5Ojf5AriipvkYaCEyg=="}]},"_npmUser":{"name":"dre2901","email":"dre2901@gmail.com"},"directories":{},"maintainers":[{"name":"dre2901","email":"dre2901@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/myq-api_2.0.5_1629134604056_0.5599200442918406"},"_hasShrinkwrap":false}},"time":{"created":"2021-08-16T17:23:24.000Z","2.0.5":"2021-08-16T17:23:24.207Z","modified":"2022-04-05T05:37:16.248Z"},"maintainers":[{"name":"dre2901","email":"dre2901@gmail.com"}],"description":"An updated API to interface with myQ devices. Fork of an original implementation done by Thomas Munduchira (https://thomasmunduchira.com/)","homepage":"https://github.com/dre2901/myq-api","keywords":["myq","chamberlain","liftmaster","garage","door","light","device","automation","smart","home","api"],"repository":{"type":"git","url":"git+https://github.com/dre2901/myq-api.git"},"contributors":[{"name":"Dimitry Remenyuk","email":"dre2901@gmail.com"}],"author":{"name":"Thomas Munduchira","email":"thomas@thomasmunduchira.com","url":"https://thomasmunduchira.com/"},"bugs":{"url":"https://github.com/dre2901/myq-api/issues"},"license":"MIT","readme":"# myq-api\n\n![node-current](https://img.shields.io/node/v/myq-api)\n![npm](https://img.shields.io/npm/dt/myq-api)\n![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/thomasmunduchira/myq-api/latest_push/master)\n![Coveralls GitHub](https://img.shields.io/coveralls/github/thomasmunduchira/myq-api)\n![Stryker mutation score](https://badge.stryker-mutator.io/github.com/thomasmunduchira/myq-api/master)\n![GitHub](https://img.shields.io/github/license/thomasmunduchira/myq-api)\n\nInterface with your [myQ](https://www.myq.com/products) devices using this npm module. Works with both Chamberlain and LiftMaster.\nFork of the original implementation done by Thomas Munduchira (https://thomasmunduchira.com/)\".\n\nSupports:\n* Opening or closing a door.\n* Checking whether a door is open or closed.\n* Turning on or turning off a light/lamp.\n* Checking whether a light/lamp is turned on or turned off.\n* Getting the metadata and state of all devices on an account.\n* Getting the metadata and state of a specific device.\n* A few other advanced usages documented below.\n\n## Installation\n\n```bash\nnpm install @dre2901/myq-api\n```\n\n## Examples\n\nSee [example.js](https://github.com/dre2901/myq-api/blob/master/example.js) and [example_async.js](https://github.com/dre2901/myq-api/blob/master/example_async.js) for end-to-end examples of using this module. Configure `EMAIL` and `PASSWORD` in these examples to enable running them against your own myQ account!\n\n## API\n* [new MyQ()](#new-myq)\n* [login(email, password)](#loginemail-password)\n* [getDevices()](#getdevices)\n* [getDevice(serialNumber)](#getdeviceserialnumber)\n* [getDoorState(serialNumber)](#getdoorstateserialnumber)\n* [getLightState(serialNumber)](#getlightstateserialnumber)\n* [getLampState(serialNumber)](#getlampstateserialnumber)\n* [setDoorState(serialNumber, action)](#setdoorstateserialnumber-action)\n* [setLightState(serialNumber, action)](#setlightstateserialnumber-action)\n* [setLampState(serialNumber, action)](#setlampstateserialnumber-action)\n* [_getAccountId()](#_getaccountid)\n* [_getDeviceState(serialNumber, _stateAttribute)](#_getdevicestateserialnumber-_stateattribute)\n* [_setDeviceState(serialNumber, _action, _stateAttribute)](#_setdevicestateserialnumber-_action-_stateattribute)\n* [_executeServiceRequest(_config)](#_executeservicerequest_config)\n\n## Usage\n\n### new MyQ()\n\nInitialize the MyQ API.\n\nThis used to take in an email and password, but these parameters have been deprecated in favor of login(username, password).\n\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\n```\n\n### login(email, password)\n\nLog into a myQ account and fetch a security token.\n\nThis must be called before the rest of this API is called. This used to take in no parameters, but the interface has been updated to take in the account email and password.\n\nNote that the security token is short-lived and will not work after some time, so this might have to be called again to retrieve a new security token.\n\n| Parameter | Required | Type | Details |\n|-----------|----------|--------|------------------------------|\n| email | yes | string | Email for the myQ account |\n| password | yes | string | Password for the myQ account |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function login() {\n try {\n const account = new MyQ();\n const result = await account.login(email, password)\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"securityToken\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `AUTHENTICATION_FAILED`\n* `AUTHENTICATION_FAILED_ONE_TRY_LEFT`\n* `AUTHENTICATION_FAILED_LOCKED_OUT`\n\n### getDevices()\n\nGet the metadata and state of all devices on the myQ account.\n\nlogin() must be called before this.\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.getDevices())\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n}\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getDevices() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.getDevices();\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"devices\": [device1, device2, ...]\n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n\n### getDevice(serialNumber)\n\nGet the metadata and state of a specific device on the myQ account.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|---------|-------------------------|\n| serialNumber | yes | string | Serial number of device |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.getDevice(serialNumber)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getDevice() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.getDevice(serialNumber);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"device\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if argument is not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n\n### getDoorState(serialNumber)\n\nCheck whether a door on the myQ account is open or closed.\n\nlogin() must be called before this.\n\nNote that this can report back intermediary states between open and closed as well.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|---------|-----------------------|\n| serialNumber | yes | string | Serial number of door |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.getDoorState(serialNumber)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getDoorState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.getDoorState(serialNumber);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"deviceState\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if argument is not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n\n### getLightState(serialNumber)\n\nCheck whether a light on the myQ account is turned on or turned off.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|---------|------------------------|\n| serialNumber | yes | string | Serial number of light |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.getLightState(serialNumber)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getLightState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.getLightState(serialNumber);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n \"deviceState\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if argument is not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n\n### getLampState(serialNumber)\n\nCheck whether a lamp on the myQ account is turned on or turned off.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|---------|------------------------|\n| serialNumber | yes | string | Serial number of lamp |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.getLampState(serialNumber)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getLampState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.getLampState(serialNumber);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n \"deviceState\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if argument is not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n### setDoorState(serialNumber, action)\n\nOpen or close a door on the myQ account.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|--------|----------------------------------------------------------------------------------------|\n| serialNumber | yes | string | Serial number of door |\n| action | yes | symbol | Action to request on door (either `MyQ.actions.door.OPEN` or `MyQ.actions.door.CLOSE`) |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.setDoorState(serialNumber, MyQ.actions.door.OPEN)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function setDoorState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.setDoorState(serialNumber, MyQ.actions.door.OPEN);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n\n### setLightState(serialNumber, action)\n\nTurn on or turn off a light on the myQ account.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|--------|-------------------------------------------------------------------------------------------------|\n| serialNumber | yes | string | Serial number of light |\n| action | yes | symbol | Action to request on light (either `MyQ.actions.light.TURN_ON` or `MyQ.actions.light.TURN_OFF`) |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.setLightState(serialNumber, MyQ.actions.light.TURN_ON)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function setLightState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.setLightState(serialNumber, MyQ.actions.light.TURN_ON);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n\n### setLampState(serialNumber, action)\n\nTurn on or turn off a lamp on the myQ account.\n\nlogin() must be called before this.\n\n| Parameter | Required | Type | Details |\n|--------------|----------|--------|-------------------------------------------------------------------------------------------------|\n| serialNumber | yes | string | Serial number of lamp |\n| action | yes | symbol | Action to request on lamp (either `MyQ.actions.lamp.TURN_ON` or `MyQ.actions.lamp.TURN_OFF`) |\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account.setLampState(serialNumber, MyQ.actions.lamp.TURN_ON)\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function setLampState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account.setLampState(serialNumber, MyQ.actions.lamp.TURN_ON);\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `INVALID_DEVICE`\n\n### _getAccountId()\n\nGet the account ID of the myQ account.\n\nThis is meant for internal use, but this is exposed in case one wants to fetch the account ID. login() must be called before this.\n\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account._getAccountId()\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getAccountId() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account._getAccountId();\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"accountId\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n\n### _getDeviceState(serialNumber, _stateAttribute)\n\nGet the value of a state attribute for a device on the myQ account.\n\nThis is meant for internal use, but this is exposed in case one wants to fetch artibrary state attributes for a device. login() must be called before this.\n\n| Parameter | Required | Type | Details |\n|-----------------|----------|--------|-----------------------------------|\n| serialNumber | yes | string | Serial number of device |\n| _stateAttribute | yes | string | State attribute to fetch value of |\n\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account._getDeviceState(serialNumber, 'door_state')\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function getDeviceState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account._getDeviceState(serialNumber, 'door_state');\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\",\n \"deviceState\": \n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `DEVICE_STATE_NOT_FOUND`\n\n### _setDeviceState(serialNumber, _action, _stateAttribute)\n\nInitiate an action for a device on the myQ account.\n\nThis is meant for internal use, but this is exposed in case one wants to initiate arbitrary actions for a device (e.g. for a device without first-class support in this API). login() must be called before this.\n\nThe _stateAttribute parameter would not be needed here normally. Since a 500 error is returned from the service when a state update is not supported on a device, however, we check that the state attribute we want to update is present on the device before we attempt a state update.\n\n| Parameter | Required | Type | Details |\n|-----------------|----------|--------|--------------------------------------------------|\n| serialNumber | yes | string | Serial number of device |\n| _action | yes | string | Action to request on device |\n| _stateAttribute | yes | string | State attribute to ensure presence of beforehand |\n\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account._setDeviceState(serialNumber, 'open', 'door_state')\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function setDeviceState() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account._setDeviceState(serialNumber, 'open', 'door_state');\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful:\n```js\n{\n \"code\": \"OK\"\n}\n```\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if arguments are not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `DEVICE_NOT_FOUND`\n* `DEVICE_STATE_NOT_FOUND`\n\n### _executeServiceRequest(_config)\n\nExecute a myQ service request.\n\nThis is meant for internal use, but this is exposed in case one wants to send arbitrary requests to the myQ service.\n\nDefault values for header fields are used if they are not explicitly specified. Specify null for such fields in order to avoid sending them as part of the request. In particular, the SecurityToken field is set to the cached security token by default if it is not explicitly specified. If the SecurityToken field is not specified and the security token is not cached, an error is thrown. Specify a null SecurityToken in order to avoid sending it as part of the request and prevent the error from being thrown.\n\n| Parameter | Required | Type | Details |\n|-----------|----------|--------|---------------------------------------------------------------|\n| _config | yes | object | [axios config](https://github.com/axios/axios#request-config) |\n\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password)\n .then(function(result) {\n return account._executeServiceRequest({\n baseURL: constants._baseUrls.auth,\n url: constants._routes.login,\n method: 'post',\n headers: {\n SecurityToken: null,\n },\n data: {\n Username: email,\n Password: password,\n },\n })\n }).then(function (result) {\n console.log(result);\n }).catch(function (error) {\n console.error(error);\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function executeServiceRequest() {\n try {\n const account = new MyQ();\n await account.login(email, password);\n const result = await account._executeServiceRequest({\n baseURL: constants._baseUrls.auth,\n url: constants._routes.login,\n method: 'post',\n headers: {\n SecurityToken: null,\n },\n data: {\n Username: email,\n Password: password,\n },\n });\n console.log(result);\n } catch (error) {\n console.error(error);\n }\n}\n```\n\nReturned object if call is successful: [axios response](https://github.com/axios/axios#response-schema).\n\nFor [robust error handling](#error-handling), catch and handle the following errors:\n* `INVALID_ARGUMENT` (if argument is not sufficiently validated beforehand)\n* `LOGIN_REQUIRED`\n* `SERVICE_REQUEST_FAILED`\n* `SERVICE_UNREACHABLE`\n* `INVALID_SERVICE_RESPONSE`\n* `AUTHENTICATION_FAILED`\n* `AUTHENTICATION_FAILED_ONE_TRY_LEFT`\n* `AUTHENTICATION_FAILED_LOCKED_OUT`\n* `DEVICE_NOT_FOUND`\n\n## Error handling\n\nAn error returned from the API will include a code as well as an error message if applicable.\n\n| Possible error codes | Explanation\n|----------------------------------------------|-----------------------------------------------------------------------------------|\n| `ERR_MYQ_INVALID_ARGUMENT` | Argument is unspecified or invalid. |\n| `ERR_MYQ_LOGIN_REQUIRED` | login() has not been called yet or security token has expired. |\n| `ERR_MYQ_AUTHENTICATION_FAILED` | Authentication attempt failed. |\n| `ERR_MYQ_AUTHENTICATION_FAILED_ONE_TRY_LEFT` | Authentication attempt failed, one try left before user is locked out. |\n| `ERR_MYQ_AUTHENTICATION_FAILED_LOCKED_OUT` | Authentication attempt failed, account is locked out. Password needs to be reset. |\n| `ERR_MYQ_DEVICE_NOT_FOUND` | Specified device not found. |\n| `ERR_MYQ_DEVICE_STATE_NOT_FOUND` | Specified state attribute not found on device. |\n| `ERR_MYQ_INVALID_DEVICE` | Action cannot be done on device. |\n| `ERR_MYQ_SERVICE_REQUEST_FAILED` | Service request could not be set up or sent. |\n| `ERR_MYQ_SERVICE_UNREACHABLE` | Service cannot be reached at this time. |\n| `ERR_MYQ_INVALID_SERVICE_RESPONSE` | Invalid response received from service. |\n\nReturned object if a call is unsuccessful:\n```js\n{\n code: ,\n message: \n}\n```\n\nSince the underlying myQ API is volatile, there might be changes unforeseen by the current version of this software. If you encounter an unexpected error, please create a [GitHub issue](https://github.com/dre2901/myq-api/issues).\n\nNOTE: It is recommended that error codes are checked against the provided constants (`MyQ.constants.codes`) instead of hardcoded raw strings.\n\nExample:\n```js\nconst MyQ = require('myq-api');\n\nconst account = new MyQ();\naccount.login(email, password) // assuming parameters are valid here, otherwise INVALID_ARGUMENT can be thrown as well\n .then(function (result) {\n console.log(result);\n }).catch(function (error) {\n if (error.code === MyQ.constants.codes.SERVICE_REQUEST_FAILED) {\n // handle client-side errors when setting up service request\n } else if ([MyQ.constants.codes.SERVICE_UNREACHABLE, MyQ.constants.codes.INVALID_SERVICE_RESPONSE].contains(error.code)) {\n // handle service errors\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED) {\n // handle failed authentication\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED_ONE_TRY_LEFT) {\n // handle failed authentication, one try left\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED_LOCKED_OUT) {\n // handle failed authentication, user locked out\n }\n });\n```\n\nasync/await example:\n```js\nconst MyQ = require('myq-api');\n\nasync function login() {\n try {\n const account = new MyQ();\n const result = await account.login(email, password); // assuming parameters are valid here, otherwise INVALID_ARGUMENT can be thrown as well\n console.log(result);\n } catch (error) {\n if (error.code === MyQ.constants.codes.SERVICE_REQUEST_FAILED) {\n // handle client-side errors when setting up service request\n } else if ([MyQ.constants.codes.SERVICE_UNREACHABLE, MyQ.constants.codes.INVALID_SERVICE_RESPONSE].contains(error.code)) {\n // handle service errors\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED) {\n // handle failed authentication\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED_ONE_TRY_LEFT) {\n // handle failed authentication, one try left\n } else if (error.code === MyQ.constants.codes.AUTHENTICATION_FAILED_LOCKED_OUT) {\n // handle failed authentication, user locked out\n }\n }\n}\n```\n\n## Debugging\nThe [debug](https://www.npmjs.com/package/debug) module has been integrated to log service calls via [axios-debug-log](https://www.npmjs.com/package/axios-debug-log). Simply [set the DEBUG environment variable](https://github.com/visionmedia/debug#usage) to `myq-api` to get detailed logs of service requests, responses, and errors. This is especially helpful if you are running into unexpected errors and want to dig deeper.\n\n## License\n\n[MIT](https://github.com/dre2901/myq-api/blob/master/LICENSE)\n","readmeFilename":"README.md"}