JS SDK: document the new auth:refreshToken function

src/sdk-reference/cpp/1/auth/login/index.md

@@ -8,8 +8,10 @@ description: Authenticate a user
 
 Authenticates a user.
 
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/cpp/1/auth/logout) action is called, or the [jwt]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/introduction/#properties) property is manually unset.
 
-## Signature
+
+## Arguments
 
 ```cpp
 std::string login(const std::string& strategy, const std::string& credentials);
@@ -20,16 +22,15 @@ std::string login(
     int expiresIn);
 ```
 
-
-## Arguments
+<br/>
 
 | Arguments     | Type    | Description | 
 |---------------|---------|----------------------------------|
 | `strategy`    | <pre>const std::string&</pre>  | Strategy to use  |
 | `credentials` | <pre>const std::string&</pre>  | JSON string representing the credentials             |
-| `expiresIn`   | <pre>int</pre>     | Expiration time in milliseconds  |
+| `expiresIn`   | <pre>int</pre>     | Expiration time, in milliseconds  |
 
-#### ***strategy***
+### strategy
 
 The name of the authentication [strategy]({{ site_base_path }}guide/1/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -38,6 +39,12 @@ The API request example on this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin]({{ site_base_path }}plugins/1/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration).
+
+
 ## Return
 
 Returns the encrypted JSON Web Token.  

src/sdk-reference/go/1/auth/login/index.md

@@ -8,21 +8,26 @@ description: Authenticate a user
 
 Authenticates a user.
 
-## Signature
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/go/1/auth/logout) action is called, or the [jwt]({{ site_base_path }}sdk-reference/go/1/kuzzle/introduction/#properties) property is manually unset.
+
+## Arguments
 
 ```go
-func (a *Auth) Login(strategy string, credentials json.RawMessage, expiresIn *int) (string, error)
+func (a *Auth) Login(
+  strategy string, 
+  credentials json.RawMessage, 
+  expiresIn *int) (string, error)
 ```
 
-## Arguments
+<br/>
 
-| Arguments    | Type    | Description | Required
-|--------------|---------|-------------|----------
-| ``strategy`` | string | the name of the strategy to use    | yes
-| ``credentials`` | string | the json credentials | yes
-| ``expiresIn`` | int | expiration time in milliseconds | no
+| Arguments    | Type    | Description |
+|--------------|---------|-------------|
+| `strategy` | <pre>string</pre> | Name of the strategy to use    |
+| `credentials` | <pre>json.RawMessage</pre> | Credentials for that strategy |
+| `expiresIn` | int | Expiration time, in milliseconds |
 
-#### ***strategy***
+### strategy
 
 The name of the authentication [strategy]({{ site_base_path }}guide/1/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -31,6 +36,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin]({{ site_base_path }}plugins/1/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration).
+
 ## Return
 
 The **login** action returns an encrypted JSON Web Token, that must then be sent in the [requests headers]({{ site_base_path }}api/1/essentials/query-syntax/).

src/sdk-reference/java/1/auth/login/index.md

@@ -8,29 +8,24 @@ description: Authenticate a user
 
 Authenticates a user.
 
-## Signature
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/java/1/auth/logout) action is called, or the [jwt]({{ site_base_path }}sdk-reference/java/1/kuzzle/introduction/#properties) property is manually unset.
+
+## Arguments
 
 ```java
-String login(
-  String,
-  String,
-  int
-);
-String login(
-  String,
-  String
-);
+String login(String strategy, String credentials, int expiresIn);
+String login(String strategy, String credentials);
 ```
 
-## Arguments
+<br/>
 
-| Arguments    | Type    | Description | Required
-|--------------|---------|-------------|----------
-| ``strategy`` | String | the name of the strategy to use    | yes
-| ``credentials`` | String | the json credentials | yes
-| ``expiresIn`` | int | expiration time in milliseconds | no
+| Arguments    | Type    | Description |
+|--------------|---------|-------------|
+| `strategy` | <pre>String</pre> | Name of the strategy to use |
+| `credentials` | <pre>String</pre> | Credentials for that strategy |
+| `expiresIn` | <pre>int</pre> | Token expiration time, in milliseconds |
 
-#### ***strategy***
+### strategy
 
 The name of the authentication [strategy]({{ site_base_path }}guide/1/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -39,6 +34,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin]({{ site_base_path }}plugins/1/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration).
+
 ## Return
 
 The **login** action returns an encrypted JSON Web Token, that must then be sent in the [requests headers]({{ site_base_path }}api/1/essentials/query-syntax/).

src/sdk-reference/js/6/auth/login/index.md

@@ -8,7 +8,9 @@ description: Authenticate a user
 
 Authenticates a user.
 
-<br/>
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/js/6/auth/logout) action is called, or the [jwt]({{ site_base_path }}sdk-reference/js/6/kuzzle/introduction/#properties) property is manually unset.
+
+## Arguments
 
 ```javascript
 login (strategy, [credentials], [expiresIn])
@@ -22,7 +24,7 @@ login (strategy, [credentials], [expiresIn])
 | ``credentials`` | <pre>object</pre> | Credentials for the strategy |
 | ``expiresIn`` | <pre>string</pre> | Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) |
 
-#### strategy
+### strategy
 
 The name of the [authentication strategy]({{ site_base_path }}guide/1/kuzzle-depth/authentication) used to log the user in.
 
@@ -31,6 +33,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin]({{ site_base_path }}plugins/1/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration).
+
 ## Resolves
 
 The **login** action returns the encrypted JSON Web Token.

src/sdk-reference/js/6/auth/refresh-token/index.md

@@ -0,0 +1,54 @@
+---
+layout: sdk.html.hbs
+title: refreshToken
+description: Refresh an authentication token
+---
+
+# refreshToken
+
+{{{since "6.1.0"}}}
+
+Refreshes a valid, non-expired authentication token.
+
+If this action is successful, all further requests emitted by this SDK instance will use the refreshed authentication token.
+
+## Arguments
+
+```javascript
+refreshToken ([options])
+```
+
+<br/>
+
+| Arguments    | Type    | Description |
+|--------------|---------|-------------|
+| `options`  | <pre>object</pre> | Query options |
+
+
+### options
+
+Additional query options
+
+| Property     | Type<br/>(default)    | Description   |
+| -------------- | --------- | ------------- |
+| `expiresIn` | <pre>string</pre> | Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) |
+| `queuable` | <pre>boolean</pre><br/>(`true`)| If true, queues the request during downtime, until connected to Kuzzle again |
+
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration/).
+
+## Resolves
+
+The `refreshToken` action resolves to a token object with the following properties:
+
+| Property   | Type    | Description  |
+|--------------|---------|-------------|
+| `_id` | <pre>string</pre> | User unique identifier ([kuid]({{ site_base_path }}guide/1/essentials/user-authentication/#kuzzle-user-identifier-kuid)) |
+| `expiresAt` | <pre>number</pre> | Expiration timestamp in Epoch-millis format (UTC) |
+| `jwt` | <pre>string</pre> | Authentication token |
+| `ttl` | <pre>number</pre> | Time to live of the authentication token, in milliseconds |
+
+## Usage
+
+[snippet=refreshToken]

src/sdk-reference/js/6/auth/refresh-token/snippets/refreshToken.js

@@ -0,0 +1,22 @@
+const credentials = { username: 'foo', password: 'bar' };
+
+try {
+  const jwt = await kuzzle.auth.login('local', credentials);
+
+  // Prints the encrypted authentication token
+  console.log(jwt);
+
+  // Note: to get a different token, you actually need to wait at least
+  // 1 second. Otherwise you do receive a refreshed token, but with the exact
+  // same caracteristics, as the key depends on the timestamp in Epoch format
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Prints:
+  // { _id: '<user kuid>',
+  //   jwt: '<a different encrypted authentication token>'
+  //   expiresAt: 1553185334220,
+  //   ttl: 3600000 }
+  console.log(await kuzzle.auth.refreshToken());
+} catch (error) {
+  console.error(error.message);
+}

src/sdk-reference/js/6/auth/refresh-token/snippets/refreshToken.test.yml

@@ -0,0 +1,15 @@
+---
+name: auth#login
+description: Authenticate a user
+hooks:
+  before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
+  after: curl -X DELETE kuzzle:7512/users/foo
+template: default
+expected:
+  - ^.*\..*$
+  - "{ _id: 'foo',"
+  - ^\s*jwt: '.*\..*'
+  - ^\s*expiresAt: \d+
+  - ^\s*ttl: \d+ }
+sdk: js
+version: 6