Merge pull request #3 from lesander/2.0.0

2.0.0

.babelrc

@@ -0,0 +1,9 @@
+{
+  "presets": ["es2015", "stage-0"],
+  "plugins": [
+    ["transform-runtime", {
+      "polyfill": false,
+      "regenerator": true
+    }]
+  ]
+}

.gitignore

@@ -45,3 +45,9 @@ calls.json
 
 # Ignore research files.
 research/
+
+# Ignore lib file.
+lib/
+
+# Ignore Jekyll site folder.
+_site/

.npmignore

@@ -0,0 +1 @@
+src/

DOCS.md

@@ -1,5 +1,7 @@
 # Documentation
 
+**Documentation is outdated and still a work in progress. This is expected to be finished by release v2.1.0**
+
 Every call to any `fritz` function should include the `options` object. The domain (or IP address) can differ with your local network setup. If your Fritz!Box does not require a username while logging in, you can simply leave that field blank.
 ```js
 {
@@ -10,15 +12,21 @@ Every call to any `fritz` function should include the `options` object. The doma
 }
 ```
 
-All functions of the FritzBox.js API are [Promise](http://www.datchley.name/es6-promises)-based.
+All functions of the FritzBox.js API are ES7 [async/await](https://davidwalsh.name/async-generators#es7-async) Promise-based.
+
 ```js
-fritz.functionName(parameter1, parameter2, ...)
-.then((result) => {
-  // do something with the result.
-})
-.catch((error) => {
-  // do something with the error.
-})
+async function main() {
+  const result = await fritz.functionName(parameter1, parameter2, ...)
+
+  if (result.error) {
+    // deal with the error object.
+    return console.log(result.error.message)
+  }
+
+  // deal with the result object.
+  // ...
+}
+main()
 ```
 
 ## Available functions

LICENSE

@@ -1,3 +1,5 @@
+FritzBox.js
+
 MIT License
 
 Copyright (c) 2017 Sander Laarhoven
@@ -19,3 +21,28 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+fritzbox-callmonitor
+
+The MIT License (MIT)
+
+Copyright (c) 2013 Thorsten Basse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,25 +1,30 @@
 # FritzBox.js
 [![GitHub release](https://img.shields.io/github/release/lesander/fritzbox.js.svg?maxAge=1)]()
-[![Completion Status](https://img.shields.io/badge/completion-45%25-yellowgreen.svg)]()
+[![Completion Status](https://img.shields.io/badge/completion-70%25-green.svg)]()
 [![Build Status](https://travis-ci.org/lesander/fritzbox.js.svg?branch=master&cache=pls)](https://travis-ci.org/lesander/fritzbox.js)
-
 [![npm](https://img.shields.io/npm/dt/fritzbox.js.svg?maxAge=1)]()
-
 [![Code Climate](https://codeclimate.com/github/lesander/fritzbox.js/badges/gpa.svg)](https://codeclimate.com/github/lesander/fritzbox.js)
 [![BCH compliance](https://bettercodehub.com/edge/badge/lesander/fritzbox.js?maxAge=-1)](https://bettercodehub.com)
 
+The most powerful, simple and complete [AVM](https://avm.de) Fritz!Box [API](https://avm.de/Schnittstellen).
 
-
-The most powerful, simple and complete AVM Fritz!Box API. **This project is still a work in progress.** Written in Node.js
+**This project is still a work in progress. [See issue #1 for the current status.](https://github.com/lesander/fritzbox.js/issues/1)**
 
 ## Getting Started
-This module is written in ECMAscript 2015 [ES6](https://github.com/mjavascript/practical-es6) and is promise-based. You should use the latest version (`^7.0.0`) of NodeJS.
+This module is future-proof and uses async/await promises.
+
+This means that you need to run NodeJS version `7.6.0` or newer. If your NodeJS version is between `7.0.0` and `7.5.0` you can use the harmony flag `--harmony-async-await` to make use of the async/await promises.
+
+This package was tested on Fritz!Box 7390 and 7490, with firmware versions `6.53`, `6.51` and `6.83`.
+
+## Installing
 
-This package was tested on Fritz!Box 7390 and 7490 with firmware versions `6.53` and `6.51`.
 ```
 npm install fritzbox.js
 ```
 
+## Usage
+
 A simple example showing how to get the history of calls made with a [Fritz!Fon](https://en.avm.de/products/fritzfon) can be seen below.
 
 ```js
@@ -30,31 +35,66 @@ const options = {
   server: 'fritz.box',
   protocol: 'https' }
 
+;(async () => {
+
+  const calls = await fritz.getCalls(options)
+  if (calls.error) return console.log('Error: ' + calls.error.message)
+  console.log('Got ' + calls.length + 'calls.')
+
+})()
+```
+
+To minimize overhead and limit login requests made to the Fritz!Box it is recommended to store the SID once one has been obtained using [`fritz.getSessionId`](http://localhost:9000/api/#fritzLogin.getSessionId).
+
+## Documentation
+Want to get started with FritzBox.js? Cool! The API is
+[documented and available here](https://lesander.github.io/fritzbox.js/api), and you can
+[see some examples](/test) in the `test/` folder.
+
+## Contributing
+If you'd like to contribute to FritzBox.js, or file a bug or feature request,
+please head over to [the issue tracker](/issues) or [open a pull request](/pulls).
+
+## Migrating from 1.x.x to 2.x.x
+FritzBox.js v2.x is not backwards compatible with v1.x.
+One of the mayor changes includes the switch to `async/await` Promises.
+In v1.x, Promises were implemented with a `then`, `catch`:
+
+```js
 fritz.getCalls(options)
 .then((callHistory) => {
   console.log(callHistory)
 })
 .catch((error) => {
   console.log(error)
 })
+```
+
+With v2.x, the `catch` will no longer catch any errors, since the module is now
+built to provide support for `await`. Any errors will be passed along like this:
 
+```js
+fritz.getCalls(options)
+.then((callHistory) => {
+  if (callHistory.error) return console.log(error)
+  console.log(callHistory)
+})
 ```
 
-## Documentation
-Want to get started with FritzBox.js? Cool! The API is
-[documented and available here](/DOCS.md), and you can
-[see some examples](/test) in the `test/` folder.
+Of course, this can be simplified using `await`:
 
-## Contributing
-If you'd like to contribute to FritzBox.js, or file a bug or feature request,
-please head over to [the issue tracker](/issues) or [open a pull request](/pulls).
+```js
+let callHistory = await fritz.getCalls(options)
+if (callHistory.error) return console.log(error)
+console.log(callHistory)
+```
+
+Note that any Promise waiting to be fulfilled using `await` should be put inside an `async` function.
 
+For more changes, please see the [roadmap](https://github.com/lesander/fritzbox.js/issues/1).
 
 ## License
 This software is open-sourced under the MIT License ([see the LICENSE file for
-the full license](/LICENSE)). So within some limits, you can do with the code whatever
-you want. However, if you like and/or want to re-use it, I'd really appreciate
-a reference to this project page.
+the full license](/LICENSE)).
 
-The software is provided as is. It might work as expected - or not.
-Just don't blame me.
+You are required to include a copy of this project's license and copyright notice in your modified or distributed version of FritzBox.js

docs/_config.yml

@@ -0,0 +1,4 @@
+version: '2.0.0'
+collections:
+  - examples
+highlighter: pygments

docs/_includes/head.html

@@ -0,0 +1,9 @@
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,700">
+  <link rel="stylesheet" href="assets/css/prism.css">
+  <link rel="stylesheet" href="assets/css/toolkit.css">
+  <link rel="stylesheet" href="assets/css/stars.css">
+  <link rel="stylesheet" href="assets/css/theme.css">

docs/_includes/scripts.html

@@ -0,0 +1,2 @@
+<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
+<script src="/assets/js/toolkit.min.js"></script>

docs/_layouts/default.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>{{ page.title }}</title>
+    {% include head.html %}
+  </head>
+  <body>
+    {{ content }}
+  </body>
+  {% include scripts.html %}
+</html>