Release 6.0.0-beta-1 (#311)

* KZL 174 - Update README for SDK V6 (#308)

* Draft readme

* Update README for sdk v6

* Update sdk deploy script to build

* Use 6-beta links in github url

* Apply change from @ballinette and @scottinet

* typo

* Release 6.0.0-beta-1

* dependencies update

Author: scottinet

.travis.yml

@@ -1,24 +1,32 @@
 sudo: false
 language: node_js
 node_js:
-- 6
+  - 6
+
+env:
+  global:
+    secure: ATb4QFGG6sPkfquAoye6BeN7u4uQ4abP8qatVK8XG3Qof+pECZwRkFPVoopO1Gb/4bQSPfapc1aGPzGuKi409v633vpDnpcgM7cHX9CPT+YQYcTePMFtq/m+5YY3WIYWM1zCFmJ+bBwQO/MtsubfGfA9EmSAAxtnJV+1JDD3Y6+NQRkQN7K+gxQozec0u1W0Oe1sJXLSKlW3JPL8iRtKcLvmIDysKtBK6X/Wg1qP2Me4reb449a0yGej3QvZDbDYJbdlh7vuFLjXJAz3yExfED8QAm8wf0p9F8emILHnkLxjumTTnGUUqDJLLu8WgkahFiyFo4jMtryhNQ0+p6WhXmEbpNIO+yMGSZPsCGbnpkhWJ1aMAT6ZhgpHf4jDZQd4ZJi02+n9tOpe+Lm2Jk2LXY8SwMk3xGtqm5sk03weTc019TUGj/NLoHNjO/vfNz3xOImD5Gck3bXWNxdrX3bjiyVsr/u77enoWu9drPCEl3JOTIwVP3mTF8R3axSFOQ8M4SI1orCMChkGMB5qExl+Gfx+MHa/jL7QKO1SFRgl1O3DbhsyFE6xiabYzwLcdbI50ypy6VJjmDd5RxK7BkDa8RumlHT1uY1FK9yRXu4XFrrw9FjF2s+xjWbliRZqXRReXk0W1Hz4zj5au3Y9YH5a/UPtB72TY+AUUWHTUPQl3SU=
+
 addons:
   apt:
     sources:
-    - ubuntu-toolchain-r-test
+      - ubuntu-toolchain-r-test
     packages:
-    - gcc-4.9
-    - g++-4.9
-script:
-- npm run build && npm test && cat ./coverage/lcov.info | ./node_modules/.bin/codecov
-- chmod 755 ${TRAVIS_BUILD_DIR}/deploy.sh && sh -c "${TRAVIS_BUILD_DIR}/deploy.sh"
+      - gcc-4.9
+      - g++-4.9
+
 before_install:
-- export CC="gcc-4.9" CXX="g++-4.9"
+  - export CC="gcc-4.9" CXX="g++-4.9"
+
 install:
-- npm install
-env:
-  global:
-    secure: ATb4QFGG6sPkfquAoye6BeN7u4uQ4abP8qatVK8XG3Qof+pECZwRkFPVoopO1Gb/4bQSPfapc1aGPzGuKi409v633vpDnpcgM7cHX9CPT+YQYcTePMFtq/m+5YY3WIYWM1zCFmJ+bBwQO/MtsubfGfA9EmSAAxtnJV+1JDD3Y6+NQRkQN7K+gxQozec0u1W0Oe1sJXLSKlW3JPL8iRtKcLvmIDysKtBK6X/Wg1qP2Me4reb449a0yGej3QvZDbDYJbdlh7vuFLjXJAz3yExfED8QAm8wf0p9F8emILHnkLxjumTTnGUUqDJLLu8WgkahFiyFo4jMtryhNQ0+p6WhXmEbpNIO+yMGSZPsCGbnpkhWJ1aMAT6ZhgpHf4jDZQd4ZJi02+n9tOpe+Lm2Jk2LXY8SwMk3xGtqm5sk03weTc019TUGj/NLoHNjO/vfNz3xOImD5Gck3bXWNxdrX3bjiyVsr/u77enoWu9drPCEl3JOTIwVP3mTF8R3axSFOQ8M4SI1orCMChkGMB5qExl+Gfx+MHa/jL7QKO1SFRgl1O3DbhsyFE6xiabYzwLcdbI50ypy6VJjmDd5RxK7BkDa8RumlHT1uY1FK9yRXu4XFrrw9FjF2s+xjWbliRZqXRReXk0W1Hz4zj5au3Y9YH5a/UPtB72TY+AUUWHTUPQl3SU=
+  - npm install
+
+script:
+  - npm run build && npm test && cat ./coverage/lcov.info | ./node_modules/.bin/codecov
+
+after_success:
+  - chmod 755 ${TRAVIS_BUILD_DIR}/deploy.sh && sh -c "${TRAVIS_BUILD_DIR}/deploy.sh"
+
 deploy:
   provider: npm
   skip_cleanup: true
@@ -28,6 +36,7 @@ deploy:
   on:
     repo: kuzzleio/sdk-javascript
     branch: master
+
 notifications:
   webhooks:
     urls:

README.md

@@ -10,37 +10,37 @@ A backend software, self-hostable and ready to use to power modern apps.
 
 You can access the Kuzzle repository on [Github](https://github.com/kuzzleio/kuzzle)
 
+This is the documentation for the beta-6 SDK. We are currently refactoring in deep our documentation to support many versions of each SDK. You can see it [here](https://docs-v2.kuzzle.io/sdk-reference/kuzzle/constructor/) but notice that this is a beta version of the documentation.  
+
+This new documentation will be available soon. In the meantime, you can still use the SDK 5 and the old documentation at https://docs.kuzzle.io/sdk-reference/essentials/.
+
 * [Basic usage](#basic-usage)
-* [SDK Documentation](#sdk-documentation)
-* [Protocols used](#protocols-used)
 * [Installation](#installation)
   * [NodeJS](#nodejs)
   * [Javascript](#javascript)
+* [Protocols used](#protocols-used)
+* [SDK Documentation](#sdk-documentation)
 * [Building manually](#building-manually)
 * [License](#license)
 
 ## Basic usage
 
-Follow [Kuzzle Guide](http://docs.kuzzle.io/guide/getting-started/#sdk-play-time)
-
-## SDK Documentation
+The SDK supports different protocols. When instantiating, you must choose the protocol to use and fill in the different options needed to connect to Kuzzle.  
 
-The complete SDK documentation is available [here](http://docs.kuzzle.io/sdk-reference/)
+Example:
+```js
+const { Kuzzle } = require('kuzzle-sdk');
 
-## Protocols used
+const kuzzle = new Kuzzle('websocket', { host: 'localhost', port: 7512 });
 
-The Javascript SDK implements two network protocols: raw WebSocket, and [Socket.IO](http://socket.io/)  
-The main reason behind this is that while Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster
-
-Which protocol is used when you connect to Kuzzle depends on multiple factors:
-
-#### NodeJS
-
-The protocol used is always raw WebSocket.
-
-#### Web Browsers
-
-The SDK will first try to use raw WebSocket to connect to Kuzzle. If the web browser does not support this protocol, then the SDK falls back to Socket.IO
+kuzzle.connect()
+  .then(() => {
+    // You are now connected to your Kuzzle instance.
+    return kuzzle.server.now();
+  })
+  .then(serverTime => console.log(serverTime))
+  .catch(error => console.error(error));
+```
 
 ## Installation
 
@@ -50,19 +50,21 @@ This SDK can be used either in NodeJS or in a browser.
 
 ```
 npm install kuzzle-sdk --save
+# Beta v6
+npm install git://github.com/kuzzleio/sdk-javascript.git#6-beta --save
 ```
 
 ### Browser
 
-To run the SDK in the browser, you need to pick the [built version available here](https://raw.githubusercontent.com/kuzzleio/sdk-javascript/master/dist/kuzzle.js). You can also build it yourself by cloning this repository and running `npm run build`. A `dist` directory will be created, containing a browser version of this SDK.
+To run the SDK in the browser, you need to pick the [built beta v6 version available here](https://raw.githubusercontent.com/kuzzleio/sdk-javascript/tree/6-beta/dist/kuzzle.js). You can also build it yourself by cloning this repository and running `npm run build`. A `dist` directory will be created, containing a browser version of this SDK.
 
 ```html
 <script type="text/javascript" src="dist/kuzzle.js"></script>
 ```
 The browser version is also available from CDN:
 
 ```html
-<script type="text/javascript" src="https://cdn.rawgit.com/kuzzleio/sdk-javascript/master/dist/kuzzle.js"></script>
+<script type="text/javascript" src="https://cdn.rawgit.com/kuzzleio/sdk-javascript/tree/6-beta/dist/kuzzle.js"></script>
 ```
 
 If you want to support older browser versions, you may load `socket.io` before Kuzzle, making the SDK compatible with browsers without websocket support:
@@ -84,9 +86,204 @@ But you'll still need to pick the built version (which ships with the package).
 
 ```javascript
 // with the classic require...
-let Kuzzle = require('kuzzle-sdk/dist/kuzzle.js')
+const { Kuzzle } = require('kuzzle-sdk/dist/kuzzle.js')
 // ... or with the new import directive.
-import Kuzzle from 'kuzzle-sdk/dist/kuzzle.js'
+import { Kuzzle } from 'kuzzle-sdk/dist/kuzzle.js'
+```
+
+## Protocols used
+Actually, the SDK support 3 protocols: `http`, `websocket` et `socketio`.  
+
+Websocket and Socket.IO protocols implement the whole Kuzzle API, while HTTP protocol does not implement realtime features (rooms and subscriptions).  
+While Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster.
+
+#### NodeJS
+
+We recommend to use the `websocket` protocol, but you can still use `http`, `socketio` or even a custom protocol if you want.  
+
+#### Web Browsers
+
+We also recommend to use the `webSocket` or `http` protocol, but some old browser may not support Websocket, so you have to implement a fallback to `socketio` in that case.
+
+```js
+let kuzzle;
+
+if ('WebSocket' in window && window.WebSocket.CLOSING === 2) {
+  kuzzle = new Kuzzle('websocket', { host: 'localhost' });
+} else {
+  kuzzle = new Kuzzle('socketio', { host: 'localhost' });
+}
+```
+
+#### Custom protocol
+
+The SDK also proposes to create custom protocols.  
+
+There are two ways to write these protocols, the first is to inherit the `KuzzleAbstractNetwork` class provided with the SDK and implement only the `connect` and `send` methods.
+
+```js
+const { KuzzleAbstractNetwork } = require('kuzzle-sdk');
+
+class MyCustomProtocol extends KuzzleAbstractNetwork {
+  connect() {
+    // (...) do custom connection steps...
+
+    // change state and resolve:
+    this.state = 'ready';
+    return Promise.resolve();
+  }
+
+  send(request) {
+    // (...) here the protocol-specific code to send the request to kuzzle and get the result into `result` variable
+
+    // Send back the result to SDK and resolve:
+    this.emit(request.requestId, { result });
+    return Promise.resolve();
+  }
+}
+```
+
+The second way is to implement the `isReady` and `query` methods as well as javascript [Event API](https://nodejs.org/api/events.html) by inheriting the `KuzzleEventEmitter` class.
+
+```js
+const { KuzzleEventEmitter } = require('kuzzle-sdk');
+
+class MyCustomProtocol extends KuzzleEventEmitter {
+
+  isReady() {
+    return true;
+  }
+
+  query (request, options) {
+    // (...) here the protocol-specific code to send the request to kuzzle and get the result into `result` variable
+
+    // Resolves the response:
+    return Promise.resolve({ result });
+  }
+}
+```
+
+These customized protocols can then be used by the SDK by passing them as parameters at instantiation.
+
+```js
+const protocol = new MyCustomProtocol();
+
+const kuzzle = new Kuzzle(protocol);
+```
+
+## SDK Documentation
+
+### Connection to Kuzzle
+
+By default, the SDK is not connected to Kuzzle when it is instantiated. You must manually call the `kuzzle.connect()` method before using the SDK.  
+
+It is then possible to interact with the Kuzzle API through the SDK once the Promise returned by `kuzzle.connect()` has been resolved.  
+
+```js
+// Without async/await
+kuzzle.connect()
+  .then(() => {
+    // You are now connected to your Kuzzle instance.
+    return kuzzle.server.now();
+  })
+  .then(serverTime => console.log(serverTime))
+  .catch(error => console.error(error));
+
+// With async/await
+try {
+  await kuzzle.connect();
+  const serverTime = await kuzzle.server.now();
+
+  console.log(serverTime);
+} catch (error) {
+  console.error(error);
+}
+```
+
+### Match Kuzzle's API
+
+The version 6 of this SDK involve a massive refactor of the SDK structure to match the [Kuzzle API](https://docs.kuzzle.io/api-documentation/connecting-to-kuzzle/).  
+
+Each controller is accessible from the Kuzzle object. The controller's actions are named in the same way as in the API.  
+
+For example, for the `create` action of the `document` controller ([document#create](https://docs.kuzzle.io/api-documentation/controller-document/create)):
+```js
+const options = { refresh: 'wait_for' };
+const documentBody = { hello: 'world' };
+kuzzle.document.create('my-index', 'my-collection', 'my-uniq-id', documentBody, options)
+```
+
+The parameters of each method differ according to the parameters expected in the API.  
+If you want to get the details of the parameters for each method, it is necessary for the moment to see the code of each controller on [Github](https://github.com/kuzzleio/sdk-javascript/tree/6-beta/src/controllers).
+
+#### Query method
+
+This SDK also expose a low level `query` method to access the API even if the controller is not available inside the SDK.  
+
+This method take the controller and action name with all parameters needed by the action (`body`, `_id`, etc.) and return the raw Kuzzle response. This is the method used internally for every controller action in this SDK.
+
+Example with the [Admin](https://docs.kuzzle.io/api-documentation/controller-admin/) controller:
+```js
+const query = {
+  controller: 'admin',
+  action: 'resetCache',
+  database: 'memoryStorage'
+};
+const options = {
+  refresh: 'wait_for'
+};
+
+try {
+  const response = await kuzzle.query(query, options);
+  /*
+  {
+    requestId: '6526be09-330d-4183-be2b-8c30183db0f0',
+    status: 200,
+    error: null,
+    controller: 'admin',
+    action: 'resetCache',
+    collection: null,
+    index: null,
+    volatile:
+     { sdkInstanceId: 'c6fbe345-1d8b-4324-bf1f-2be3cc1a7d27',
+       sdkVersion: '6.0.0' },
+    result: { acknowledge: true },
+    room: '6526be09-330d-4183-be2b-8c30183db0f0'
+  }
+  */
+  console.log('Kuzzle memory storage successfully reset');
+} catch (error) {  
+  console.error(error);
+}
+```
+
+### Promise based
+
+All SDK methods return a promise resolving the `result` part of Kuzzle API responses. If an error occurs, the promise is rejected with an `Error` object embedding the `error` part of the API response.
+
+For example, for the action `create` of the controller `collection` ([collection#create](https://docs.kuzzle.io/api-documentation/controller-collection/create)), the property `result` contains `{ "acknowledged": true} `. This is therefore what will be returned by the SDK method if successful.
+
+Any error must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`.
+
+```js
+const mapping = {
+  properties: {
+    hello: { type: 'text' }
+  }
+};
+// Without async/await
+kuzzle.collection.create('my-index', 'my-collection', mapping)
+  .then(result => console.log('Success'))
+  .catch(error => console.error(`Hu oh, we've got some error: ${error.message}`));
+
+// With async/await
+try {
+  const result = await kuzzle.collection.create('my-index', 'my-collection', mapping);
+  // result contain { "acknowledged": true }
+  console.log(result);
+} catch (error) {
+  console.error(`Hu oh, we've got some error: ${error.message}`)
+}
 ```
 
 ## License

deploy.sh

@@ -1,7 +1,7 @@
 #! /bin/bash
 set -e
 
-if [ "${TRAVIS_BRANCH}" = "master"  -a "${TRAVIS_PULL_REQUEST}" = "false" ]
+if ([ "${TRAVIS_BRANCH}" = "master" ] || [ "${TRAVIS_BRANCH}" = "6-beta" ]) && [ "${TRAVIS_PULL_REQUEST}" = "false" ]
 then
   echo "Push generated dist folder"
   git config --global user.email "support@kuzzle.io"