Merge pull request #229 from bencevans/sonos-async

🎉

.github/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to node-sonos
+
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+We advise to start small, as big changes tend to take more time to be merged. For starters you could have a look at the ['help-wanted' issues](https://github.com/bencevans/node-sonos/labels/help-wanted) to start contributing.
+
+## We Develop with Github
+
+We use github to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
+
+Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
+
+1. Fork the repo and create your branch from `master`.
+2. Run `npm install` to make sure you got the current version of the packages installed.
+3. If you've added code that should be tested, add tests.
+4. Add jsdoc to all new prototyped functions and update the documentation `npm run docs`
+5. Ensure the test suite passes. `npm run test` or `SONOS_HOST=1.2.3.4 npm run test` for real device testing.
+6. Make sure your code lints. `npm run lint` or `standard --fix` to auto fix most lint errors.
+7. Issue that pull request! All pull-requests are automatically checked by [Travis](https://travis-ci.org/bencevans/node-sonos/pull_requests).
+8. Respond to possible review comments.
+9. :tada: :confetti_ball: Once merged, a new version will be published to NPM.
+
+## Any contributions you make will be under the MIT Software License
+
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using Github's [issues](https://github.com/bencevans/node-sonos/issues)
+
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/bencevans/node-sonos/issues/new); it's that easy!
+
+## Write bug reports with detail, background, and sample code
+
+We like bug reports that state some example code, what your output is and what output you would expect. Possibly with the part of the library that causes the issue.
+
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Version of this package.
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can. [A stackoverflow question](http://stackoverflow.com/q/12488905/180626) includes sample code that *anyone* with a base R setup can run to reproduce what I was seeing
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+People *love* thorough bug reports. I'm not even kidding.
+
+## Use a Consistent Coding Style
+
+We're again borrowing these from [Facebook's Guidelines](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
+
+- 2 spaces for indentation rather than tabs
+- You can try running `npm run lint` for style unification
+
+## License
+
+By contributing, you agree that your contributions will be licensed under its MIT License.
+
+## References
+
+Thanks [@briandk](https://github.com/briandk) for this [template](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62).
+
+This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--- Provide a general summary of the issue in the Title above -->
+
+## Expected Behavior
+
+<!--- Tell us what should happen -->
+
+## Current Behavior
+
+<!--- Tell us what happens instead of the expected behavior -->
+
+## Possible Solution
+
+<!--- Not obligatory, but suggest a fix/reason for the bug, -->
+
+## Sample code or executed example
+
+<!--- Provide a link to a live example, or an unambiguous set of steps to -->
+<!--- reproduce this bug. Include code to reproduce, if relevant -->
+1.
+2.
+3.
+4.
+
+## Versions (and Environment)
+
+**Node version**: <!--- What is the version of your node installation -->
+**node-sonos version**: <!--- What version of node-sonos is used -->
+**OS**: <!--- What OS are you using? -->

.travis.yml

@@ -7,7 +7,6 @@ notifications:
 node_js:
   - '9'
   - '8'
-  - '6'
 after_success:
   - npm run semantic-release
 branches:

README.md

@@ -52,56 +52,106 @@ From the repo, living on the edge
 
     $ npm install git://github.com/bencevans/node-sonos.git
 
-## API
+## Quick Start
+
+### Discovering Devices
+
+```js
+const { DeviceDiscovery } = require('sonos')
+
+// event on all found...
+DeviceDiscovery((device) => {
+  console.log('found device at ' + device.host)
+
+  // mute every device...
+  device.setMuted(true)
+    .then(`${device.host} now muted`)
+})
+
+// find one device
+DeviceDiscovery().once('DeviceAvailable', (device) => {
+  console.log('found device at ' + device.host)
+
+  // get topology
+  device.getTopology()
+    .then(console.log)
+})
+```
+
 
-For detailed info read the [/API.md](https://github.com/bencevans/node-sonos/blob/master/API.md) file, else…
+### Controlling Known Devices
 
-* search([options], [deviceAvailableListener])
-* Class: Search([options])
+```js
+const { Sonos } = require('sonos')
+
+const device = new Sonos('192.168.1.56');
+
+device.play()
+  .then(() => console.log('now playing'))
+
+device.getVolume()
+  .then((volume) => console.log(`current volume = ${volume}`))
+```
+
+## API
+
+* DeviceDiscovery([options], [deviceAvailableListener])
+* Class: DeviceDiscovery([options])
   * Event: 'DeviceAvailable'
   * destroy()
 * Class: Sonos(host, [port])
-  * currentTrack(callback)
-  * deviceDescription(callback)
-  * flush(callback)
-  * getCurrentState(callback)
-  * getLEDState(callback)
-  * getMusicLibrary(search, options, callback)
-  * getMuted(callback)
-  * getTopology(callback)
-  * getVolume(callback)
-  * getZoneAttrs(callback)
-  * getZoneInfo(callback)
-  * getQueue(callback)
-  * next(callback)
+  * currentTrack()
+  * deviceDescription()
+  * flush()
+  * getCurrentState()
+  * getLEDState()
+  * getMusicLibrary(search, options)
+  * getMuted()
+  * getTopology()
+  * getVolume()
+  * getZoneAttrs()
+  * getZoneInfo()
+  * getQueue()
+  * next()
   * parseDIDL(didl)
-  * pause(callback)
-  * play(uri, callback)
-  * previous(callback)
-  * queue(uri, positionInQueue, callback)
-  * queueNext(uri, callback)
-  * request(endpoint, action, body, responseTag, callback)
-  * seek(seconds, callback)
-  * setLEDState(desiredState, callback)
-  * setMuted(muted, callback)
-  * setName(name, callback)
-  * getPlayMode(callback)
-  * setPlayMode(mode, callback)
-  * setVolume(volume, callback)
-  * stop(callback)
+  * pause()
+  * play(uri)
+  * previous()
+  * queue(uri, positionInQueue)
+  * queueNext(uri)
+  * request(endpoint, action, body, responseTag)
+  * seek(seconds)
+  * setLEDState(desiredState)
+  * setMuted(muted)
+  * setName(name)
+  * getPlayMode()
+  * setPlayMode(mode)
+  * setVolume(volume)
+  * stop()
   * setSpotifyRegion(region)
   * alarmClockService()
-    * ListAlarms(callback)
-    * PatchAlarm(id,options,callback)
-    * SetAlarm(id,enabled,callback)
-  * joinGroup(otherDeviceName, callback)
-  * leaveGroup(callback)
-  * startListening(options, callback)
-  * stopListening(callback)
-  * Event: 'TrackChanged'
-  * Event: 'VolumeChanged'
-  * Event: 'StateChanged'
+    * ListAlarms()
+    * PatchAlarm(id,options)
+    * SetAlarm(id,enabled)
+  * joinGroup(otherDeviceName)
+  * leaveGroup()
+  * startListening(options)
+  * stopListening()
+  * Event: 'CurrentTrack'
+  * Event: 'NextTrack'
+  * Event: 'PlayState' and 'PlaybackStopped'
+  * Event: 'AVTransport'
+  * Event: 'Volume'
   * Event: 'Muted'
+  * Event: 'RenderingControl'
+
+## Documentation
+
+We tried to add jsdoc info to all functions, and generate documentation from it. [/docs](./docs/)
+
+## Examples
+
+Additional examples can be found in the [/examples](./examples) directory within the repository.
 
 ## In The Wild
 
@@ -120,10 +170,6 @@ node-sonos in use across the interwebs. Missing yours? [Add it](https://github.c
 
 * **[How we gave our studio WWE-style entrances using iBeacons and Sonos](https://hackernoon.com/how-we-gave-our-studio-wwe-style-entrances-using-ibeacons-and-sonos-92dd2f54983)** - A technical run-down of using futuristic technology for sheer entertainment value
 
-## Examples
-
-Additional examples can be found in the [/examples](https://github.com/bencevans/node-sonos/tree/master/examples) directory within the repository.
-
 ## Maintainers
 
 * Ben Evans (@bencevans)
@@ -133,6 +179,28 @@ Additional examples can be found in the [/examples](https://github.com/bencevans
 
 And a big thanks to all you other [contributors](https://github.com/bencevans/node-sonos/graphs/contributors)! Pull-requests are beautiful things.
 
+## Issues
+
+If you got discovered an issue with this library, please check the [issue-tracker](https://github.com/bencevans/node-sonos/issues). And [create](https://github.com/bencevans/node-sonos/issues/new) an issue if your problem isn't discovered by someone else. If you want to contribute something check out these ['help-wanted' issues](https://github.com/bencevans/node-sonos/labels/help-wanted).
+
+## Questions
+
+Do you have a question about this library, we are glad to help you [Ask Question](https://github.com/bencevans/node-sonos/issues/new?title=Question%3A%20%3CYour%20text%3E&body=%23%20Question%0A&labels=question&assignee=svrooij). You can see all questions [here](https://github.com/bencevans/node-sonos/issues?utf8=%E2%9C%93&q=label%3Aquestion+)
+
+### NPM publish
+
+We try to react to all pull-requests, but if you think we don't respond in time, please don't create a 'sonos-by-xyz' or a 'node-sonos-by-xyz' package on NPM. This might lead to people installing the wrong version.
+
+If you want to publish your own version, please do it as a [user-scoped](https://docs.npmjs.com/getting-started/scoped-packages) eg. `@svrooij/sonos` package.
+
+1. Change the top of the readme to state your specific changes.
+2. Change the `name` of the project to `@npm_username/sonos`
+3. Publish it to npm `npm publish --access=public`
+
+## Sonos v0.x
+
+At 30 jan 2018 we released an **promisified** version of **node-sonos**. The old version can be found in the [v0.x branch](https://github.com/bencevans/node-sonos/tree/v0.x). It won't get any new features, but it **might** get security updates.
+
 ## Licence
 
 MIT © [Ben Evans](https://bencevans.io)

docs/deviceDiscovery.md

@@ -0,0 +1,40 @@
+# sonos
+
+Sonos library to control (almost) everything from your sonos devices
+
+**Requires:**
+
++ module:'events'
++ module:'dgram'
++ module:'./sonos'
+
+* * *
+
+## Class: DeviceDiscovery
+
+Create a new instance of DeviceDiscovery
+
+### sonos.DeviceDiscovery.destroy(callback)
+
+Destroys DeviceDiscovery class, stop searching, clean up
+
+**Parameters**:
+
+**callback**: `function`, ()
+
+
+### sonos.DeviceDiscovery.deviceDiscovery(options, listener)
+
+Create a DeviceDiscovery Instance (emits 'DeviceAvailable' with a found Sonos Component)
+
+**Parameters**:
+
+**options**: `Object`, Optional Options to control search behavior.
+                         Set 'timeout' to how long to search for devices
+                         (in milliseconds).
+
+**listener**: `function`, Optional 'DeviceAvailable' listener (sonos)
+
+**Returns**: `DeviceDiscovery`
+
+* * *