remove autoconnection from sdk code examples (#467)

# Conflicts:
#	src/guide/essentials/user-authentication.md
#	src/guide/getting-started/index.md
#	src/sdk-reference/essentials/offline-first.md
#	src/sdk-reference/kuzzle/connect.md
#	src/sdk-reference/kuzzle/index.md

Author: Gilles Ballini

src/guide/essentials/user-authentication.md

@@ -69,7 +69,7 @@ If you're interested for a more in-depth explanation on how all of this work, th
 
 ## Authentication Strategies
 
-Once a user has been created, they can access resources in Kuzzle as permitted by their security profile. However; in order to access these resources they will first need to identify & authenticate themselves using an authentication strategy. The authentication strategy defines what credentials are used and how Kuzzle should validate them. Kuzzle supports multiple authentication strategies, giving you more flexibility when building your security layer: use [Oauth](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth), Kerberos, Salesforce, and many more. And, if none of these suit your needs, follow our [Plugin Documentation]({{ site_base_path }}plugins-reference/plugins-features/adding-authentication-strategy) to learn how to build a custom authentication strategy. 
+Once a user has been created, they can access resources in Kuzzle as permitted by their security profile. However; in order to access these resources they will first need to identify & authenticate themselves using an authentication strategy. The authentication strategy defines what credentials are used and how Kuzzle should validate them. Kuzzle supports multiple authentication strategies, giving you more flexibility when building your security layer: use [Oauth](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth), Kerberos, Salesforce, and many more. And, if none of these suit your needs, follow our [Plugin Documentation]({{ site_base_path }}plugins-reference/plugins-features/adding-authentication-strategy) to learn how to build a custom authentication strategy.
 
 To request access to Kuzzle, a user must first send an [authentication request]({{ site_base_path }}api-documentation/controller-auth/login). Kuzzle will validate the credentials it receives in the request using the predefined authentication strategy and return a [JSON Web Token](https://tools.ietf.org/html/rfc7519) if the user credentials are valid.
 
@@ -94,26 +94,25 @@ Then, let's create a `login.js` file that contains the following code:
 ```javascript
 const Kuzzle = require('kuzzle-sdk')
 
-var kuzzle = new Kuzzle('localhost', () => {
-  kuzzle
-    .loginPromise('local', {
-      username: 'admin',
-      password: 'test'
-    })
-    .then(() => {
-    console.log('You are now logged in!')
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-})
+const kuzzle = new Kuzzle('localhost')
+
+kuzzle
+  .connectPromise()
+  .then(() => loginPromise('local', {username: '<username>', password: '<password>'})
+  .then(() => {
+    console.log('logged!')
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
 ```
 
-This code will:
+The code above does the following:
 
-* load the Kuzzle Node.js SDK
-* connect to the Kuzzle
-* login using username `jondoe` and password `letmein`
+* loads the `Kuzzle` SDK from the NPM package,
+* instantiates a new SDK object
+* connects it to a remote Kuzzle server
+* performs a login with the provided username and password
 
 Let's try it out! Run the `index.js` using Node.js:
 

src/guide/getting-started/index.md

@@ -137,26 +137,26 @@ Your `init.js` file should now look like this:
 // load the Kuzzle SDK module
 const Kuzzle = require('kuzzle-sdk')
 
-// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
+// instantiate a Kuzzle client
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
-kuzzle.once('connected', () => {
-  kuzzle
-    .createIndexPromise('playground')
-    .then(() => kuzzle.collection('mycollection').createPromise())
-    .then(() => {
-      console.log('playground/mycollection ready')
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-    .finally(() => kuzzle.disconnect())
-})
+kuzzle
+  .connectPromise()
+  .then(() => kuzzle.createIndexPromise('playground'))
+  .then(() => kuzzle.collection('mycollection').createPromise())
+  .then(() => {
+    console.log('playground/mycollection ready')
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
+  .finally(() => kuzzle.disconnect())
 ```
 
 This code does the following:
-* loads the `Kuzzle SDK` from its NPM package
-* creates an instance of the SDK and connects it to Kuzzle running on `localhost` (and selects the `playground` as default index),
+* loads the `Kuzzle` SDK from its NPM package,
+* creates an instance of the SDK,
+* connects the SDK to a remote Kuzzle server running on `localhost` (and selects the `playground` as default index),
 * creates the `playground` index,
 * creates the `mycollection` collection (within the `playground` index),
 * disconnects from Kuzzle after the collection is created or if an error occurs.
@@ -189,23 +189,22 @@ Create a `create.js` file with following code:
 // load the Kuzzle SDK module
 const Kuzzle = require('kuzzle-sdk')
 
-// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
+// instantiate a Kuzzle client
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
 // create an object that contains the message we want to store
 const message = {message: "Hello, World!"}
 
-kuzzle.once('connected', () => {
-  kuzzle.collection('mycollection')
-    .createDocumentPromise(message)
-    .then(res => {
-      console.log('the following document has been successfully created:\n', message)
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-    .finally(() => kuzzle.disconnect())
-})
+kuzzle
+  .connectPromise()
+  .then(() => kuzzle.collection('mycollection').createDocumentPromise(message))
+  .then(res => {
+    console.log('the following document has been successfully created:\n', message)
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
+  .finally(() => kuzzle.disconnect())
 ```
 
 This code does the following:
@@ -241,7 +240,7 @@ Let's get started. Create a `subscribe.js` file with following code:
 // load the Kuzzle SDK module
 const Kuzzle = require('kuzzle-sdk')
 
-// instantiate a Kuzzle client, this will automatically connect to the Kuzzle server
+// instantiate a Kuzzle client
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
 // create a reference to the 'mycollection' collection
@@ -255,10 +254,16 @@ const filter = {
 }
 
 // create a subscription on the collection matching given filters
-collection.subscribe(filter, result => {
+collection
+  .subscribe(filter, result => {
     // this function is called each time kuzzle notifies us with a document matching our filters
-    console.log('message received from kuzzle:', result)
-})
+    console.log('Message received from kuzzle:', result)
+  })
+  .onDone(() => console.log('Subscription active. Waiting for messages...'))
+
+// Connects the client to a remote Kuzzle server and plays the previously
+// configured subscriptions
+kuzzle.connect()
 ```
 
 Run your file in Node.js

src/sdk-reference/essentials/offline-first.md

@@ -15,8 +15,8 @@ When using an unstable network connection, an application must maintain a normal
 
 There are two ways to handle a network disconnect:
 
-* Automatically reconnect to Kuzzle when possible, and enter *offline mode* in the meantime. This is the default behavior.
 * Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually reconnect once the network is available. To do so, simply set the ``autoReconnect`` option to ``false`` when creating the SDK instance.
+* Reconnect automatically to Kuzzle when possible, and enter *offline mode* in the meantime. This is the default behavior.
 
 *Offline mode* refers to the time between a ``disconnected`` and a ``reconnected`` event (see [Events]({{ site_base_path }}sdk-reference/essentials/events)).
 
@@ -42,7 +42,7 @@ The queue itself can be configured using the ``queueTTL`` and ``queueMaxSize`` o
 
 ---
 
-## Filtering Requests to be Queued
+## Filter Requests to be Queued
 
 By default, when queuing is first activated, all requests are queued.
 

src/sdk-reference/kuzzle/connect.md

@@ -11,11 +11,32 @@ title: connect
 # connect
 
 ```js
-kuzzle.connect();
+// Using callbacks (NodeJS or Web Browser)
+kuzzle.connect(function (err, kuzzle) {
+  if (err) {
+    console.log('Unable to connect: ', err.message);
+  } else {
+    console.log('Connected!');
+  }
+});
+
+// Using promises (NodeJS only)
+kuzzle.connectPromise()
+  .then(() => console.log('Connected!'));
 ```
 
 ```java
-kuzzle.connect();
+kuzzle.connect(new ResponseListener<Void>() {
+ @Override
+ public void onSuccess(Void object) {
+   // invoked once connected
+ }
+
+ @Override
+ public void onError(JSONObject error) {
+   // Handle connection error
+ }
+});
 ```
 
 ```php
@@ -24,17 +45,10 @@ kuzzle.connect();
 // not implemented (this SDK uses HTTP and is thus stateless)
 ```
 
-Connects to Kuzzle using the `host` parameter provided in the constructor.
-Has no effect if ``connect`` is set to ``auto``, unless ``disconnect`` has been called first.
-
----
-
-## Return value
-
-Returns the `Kuzzle` object to allow chaining.
+Connects to Kuzzle using the `host` and `port` parameters provided in the constructor.
 
 ---
 
 ## Callback Response
 
-If a callback has been provided to the `Kuzzle` constructor, it will be called with the `Kuzzle` instance once connected to Kuzzle
+Resolves with nothing once connected to a remote Kuzzle server.

src/sdk-reference/kuzzle/index.md

@@ -20,11 +20,6 @@ var kuzzle = new Kuzzle('localhost', {
   autoReconnect: true,
   port: 7512
 });
-
-// A callback is also available and will be invoked once connected to the Kuzzle instance:
-kuzzle = new Kuzzle('localhost', function (err, res) {
-  // ...
-});
 ```
 
 ```java
@@ -37,17 +32,7 @@ options.setDefaultIndex("some index")
   .setAutoReconnect(true),
   .setPort(7512);
 
-Kuzzle kuzzle = new Kuzzle("localhost", options, new ResponseListener<Void>() {
- @Override
- public void onSuccess(Void object) {
-   // invoked once connected, object contains the kuzzle instance
- }
-
- @Override
- public void onError(JSONObject error) {
-   // Handle connection error
- }
-});
+Kuzzle kuzzle = new Kuzzle("localhost", options);
 ```
 
 ```php
@@ -66,13 +51,12 @@ This is the main entry point to communicate with Kuzzle. Every other object inhe
 
 ---
 
-## Kuzzle(host, [options], [callback])
+## Kuzzle(host, [options])
 
 | Arguments | Type | Description |
 |---------------|---------|----------------------------------------|
 | ``host`` | string | The server name (or the IP address) of a Kuzzle Backend installation |
 | ``options`` | JSON object | Optional Kuzzle connection configuration |
-| ``callback`` | function | Optional callback |
 
 ---
 
@@ -84,7 +68,6 @@ This is the main entry point to communicate with Kuzzle. Every other object inhe
 | ``autoReconnect`` | boolean | Automatically reconnect after a connection loss | ``true`` |
 | ``autoReplay`` | boolean | Automatically replay queued requests on a ``reconnected`` event | ``false`` |
 | ``autoResubscribe`` | boolean | Automatically renew all subscriptions on a ``reconnected`` event | ``true`` |
-| ``connect`` | string | Manually or automatically connect to the Kuzzle instance | ``auto`` |
 | ``defaultIndex`` | string | Set the default index to use | |
 | ``offlineMode`` | string | Offline mode configuration | ``manual`` |
 | ``protocol`` | string | (Javascript only) Network protocol to use to connect to Kuzzle (``websocket`` | ``socketio``) | ``websocket``|
@@ -126,18 +109,10 @@ This is the main entry point to communicate with Kuzzle. Every other object inhe
 
 **Notes:**
 
-* if ``connect`` is set to ``manual``, the ``connect`` method will have to be called manually
-* the kuzzle instance will automatically queue all requests, and play them automatically once a first connection is established, regardless of the ``connect`` or offline mode option values.
+* newly instantiated Kuzzle objects automatically start in [offline mode]({{ site_base_path }}sdk-reference/essentials/offline-first/)
 * multiple methods allow passing specific ``volatile`` data. These ``volatile`` data will be merged with the global Kuzzle ``volatile`` object when sending the request, with the request specific ``volatile`` taking priority over the global ones.
 * the ``queueFilter`` property is a function taking a JSON object as an argument. This object is the request sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api-documentation/query-syntax) format
 * if ``queueTTL`` is set to ``0``, requests are kept indefinitely
 * The offline buffer acts like a first-in first-out (FIFO) queue, meaning that if the ``queueMaxSize`` limit is reached, older requests are discarded to make room for new requests
 * if ``queueMaxSize`` is set to ``0``, an unlimited number of requests is kept until the buffer is flushed
 * the ``offlineQueueLoader`` must be set with a function, taking no argument, and returning an array of objects containing a `query` member with a Kuzzle query to be replayed, and an optional `cb` member with the corresponding callback to invoke with the query result
-
----
-
-## Callback response
-
-If the connection succeeds, resolves to the `Kuzzle` object itself.
-If the `connect` option is set to `manual`, the callback will be called after the `connect` method is resolved.