Merge pull request #588 from kuzzleio/7.5.0-proposal

# [7.5.0](https://github.com/kuzzleio/sdk-javascript/releases/tag/7.5.0) (2021-01-17)


#### New features

- [ [#577](#577) ] Add [auth|security]:checkRights   ([Yoann-Abbes](https://github.com/Yoann-Abbes))
- [ [#576](#576) ] Add document:upsert   ([Yoann-Abbes](https://github.com/Yoann-Abbes))
---

doc/7/controllers/auth/check-rights/index.md

@@ -0,0 +1,40 @@
+---
+code: true
+type: page
+title: checkRights
+description: Checks if an API action can be executed by the current user
+---
+
+# checkRights
+
+<SinceBadge version="Kuzzle 2.8.0"/>
+<SinceBadge version="7.5.0"/>
+
+Checks if the provided API request can be executed by the current logged user.
+
+---
+
+```js
+checkRights(requestPayload)
+```
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `requestPayload` | <pre>object</pre> | Contains a [RequestPayload](/core/2/api/payloads/request) |
+
+## `requestPayload`
+
+The [RequestPayload](/core/2/api/payloads/request) must contains at least the following properties:
+
+- `controller`: API controller
+- `action`: API action
+
+---
+
+## Resolves
+
+A boolean telling whether the provided request would have been allowed or not.
+
+## Usage
+
+<<< ./snippets/check-rights.js

doc/7/controllers/auth/check-rights/snippets/check-rights.js

@@ -0,0 +1,19 @@
+const requestPayload = {
+  controller: 'document',
+  action: 'create',
+  index: 'nyc-open-data',
+  collection: 'yellow-taxi',
+  body: {
+    name: 'Melis'
+  }
+}
+
+try {
+  const result = await kuzzle.auth.checkRights(requestPayload);
+  console.log(result);
+  /*
+    true
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/auth/check-rights/snippets/check-rights.test.yml

@@ -0,0 +1,7 @@
+name: auth#checkRights
+description: Checks if an API action can be executed by the current 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: true

doc/7/controllers/document/upsert/index.md

@@ -0,0 +1,45 @@
+---
+code: true
+type: page
+title: upsert
+description: Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+---
+
+# upsert
+
+<SinceBadge version="Kuzzle 2.8.0"/>
+<SinceBadge version="7.5.0" />
+
+Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+
+
+```js
+upsert(index, collection, id, changes, [options]);
+```
+
+| Argument     | Type              | Description                               |
+| ------------ | ----------------- | ----------------------------------------- |
+| `index`      | <pre>string</pre> | Index name                                |
+| `collection` | <pre>string</pre> | Collection name                           |
+| `id`         | <pre>string</pre> | Document ID                               |
+| `changes`       | <pre>object</pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>object</pre><br/>(`{}`)        | Fields to add to the document if it gets created |
+| `refresh`         | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
+| `retryOnConflict` | <pre>int</pre><br/>(`10`)        | The number of times the database layer should retry in case of version conflict    |
+| `source`          | <pre>boolean</pre><br/>(`false`)| If true, returns the updated document inside the response
+
+
+## Resolves
+
+Resolves to an object containing the document update result.
+
+## Usage
+
+<<< ./snippets/upsert.js

doc/7/controllers/document/upsert/snippets/upsert.js

@@ -0,0 +1,25 @@
+try {
+  await kuzzle.document.create(
+    'nyc-open-data',
+    'yellow-taxi',
+    { capacity: 4 },
+    'some-id'
+  );
+
+  const response = await kuzzle.document.upsert(
+    'nyc-open-data',
+    'yellow-taxi',
+    'some-id',
+    { changes: { category: 'suv' } }
+  );
+
+  console.log(response);
+  /*
+  {
+    id: 'some-id',
+    _version: 2
+  }
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/document/upsert/snippets/upsert.test.yml

@@ -0,0 +1,10 @@
+name: document#upsert
+description: Applies a partial update to an existing document.
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: default
+expected: "_id: 'some-id'"

doc/7/controllers/security/check-rights/index.md

@@ -0,0 +1,40 @@
+---
+code: true
+type: page
+title: checkRights
+description: Checks if an API action can be executed by a user
+---
+
+# checkRights
+
+<SinceBadge version="2.8.0"/>
+<SinceBadge version="7.5.0"/>
+Checks if the provided API request can be executed by a user.
+
+---
+
+```js
+checkRights(kuid, requestPayload)
+```
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `kuid` | <pre>string</pre> | User [kuid](/core/2/guides/main-concepts/authentication#kuzzle-user-identifier-kuid) |
+| `requestPayload` | <pre>object</pre> | Contains a [RequestPayload](/core/2/api/payloads/request) |
+
+## `requestPayload`
+
+The [RequestPayload](/core/2/api/payloads/request) must contains at least the following properties:
+
+- `controller`: API controller
+- `action`: API action
+
+---
+
+## Resolves
+
+A boolean telling whether the provided request would have been allowed or not
+
+## Usage
+
+<<< ./snippets/check-rights.js

doc/7/controllers/security/check-rights/snippets/check-rights.js

@@ -0,0 +1,19 @@
+const requestPayload = {
+  controller: 'document',
+  action: 'create',
+  index: 'nyc-open-data',
+  collection: 'yellow-taxi',
+  body: {
+    name: 'Melis'
+  }
+}
+
+try {
+  const allowed = await kuzzle.security.checkRights('foo', requestPayload);
+  console.log(allowed);
+  /*
+    true
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/security/check-rights/snippets/check-rights.test.yml

@@ -0,0 +1,7 @@
+name: security#checkRights
+description: Checks if an API action can be executed by 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: true