strapi-plugin-comments 2.0.0-beta.4 → 2.0.0-rc.1

package/README.md

@@ -1,6 +1,7 @@
-# Strapi v4 - Comments plugin - BETA
-
-<p align="center">
+<div align="center">
+  <img style="width: 150px; height: auto;" src="public/assets/logo.png" alt="Logo - Strapi Comments plugin" />
+  <h1>Strapi v4 - Comments plugin</h1>
+  <p>Powerfull Strapi based comments moderation tool for you and your users</p>
   <a href="https://www.npmjs.org/package/strapi-plugin-comments">
     <img src="https://img.shields.io/npm/v/strapi-plugin-comments/latest.svg" alt="NPM Version" />
   </a>
@@ -13,15 +14,32 @@
   <a href="https://codecov.io/gh/VirtusLab-Open-Source/strapi-plugin-comments">
     <img src="https://codecov.io/gh/VirtusLab-Open-Source/strapi-plugin-comments/coverage.svg?branch=master" alt="codecov.io" />
   </a>
-</p>
+</div>
+
+---
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/preview.png" alt="UI preview" />
+</div>
 
-A plugin for [Strapi Headless CMS](https://github.com/strapi/strapi) that provides end to end comments feature with their moderation panel, bad words filtering, abuse reporting and more.
 
-### Versions
-- **Stable** - [v1.0.4](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments)
-- **Beta** - v4 support - [v2.0.0-beta.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments/tree/feat/strapi-v4)
+A plugin for [Strapi Headless CMS](https://github.com/strapi/strapi) that provides end to end comments feature with their moderation panel, bad words filtering, abuse reporting and much more.
 
-### ⏳ Installation
+## ✨ Features
+
+- **Comments Public REST + GraphQL API:** Elegant, entirely customizable and a fully extensible admin panel.
+- **Strapi &amp; generic users:** Support for built-in &amp; also generic non-Strapi users that might be the comments authors.
+- **Any Content Type relation:** Comments can by linked to any of your Content Types by default. Simply, you're controlling it.
+- **Moderation Panel:** Search & Filter through the bucket with your auditory comments. Manage them by blocking single ones or full threads. All in combined list &amp; hierarchical tree view of threads.
+- **Automated Bad Words filtering:** By detault end users are not allowed to post abusing comments where bad words have been used.
+- **Abuse Reporting & Reviewing:** Don't allow inferior language, react to reports from your community, send email notifiactions about abuse reports
+
+## ⚙️ Versions
+
+- **Strapi v4** - (current) - [v2.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments)
+- **Strapi v3** - [v1.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments/tree/strapi-v3)
+
+## ⏳ Installation
 
 (Use **yarn** to install this plugin within your Strapi project (recommended). [Install yarn with these docs](https://yarnpkg.com/lang/en/docs/install/).)
 
@@ -42,58 +60,79 @@ or just run Strapi in the development mode with `--watch-admin` option:
 yarn develop --watch-admin
 ```
 
-The **Comments** plugin should appear in the **Plugins** section of Strapi sidebar after you run app again.
+The **Comments** plugin should appear in the navigation menu of Strapi after you run app again.
 
 Enjoy 🎉
 
-### 🖐 Requirements
+## 🖐 Requirements
 
 Complete installation requirements are exact same as for Strapi itself and can be found in the documentation under [Installation Requirements](https://docs.strapi.io/developer-docs/latest/getting-started/introduction.html).
 
-**Supported Strapi versions**:
+**Minimum environment requirements**
+- Node.js `>=14.x.x`
+- NPM `>=7.x.x`
 
-- Strapi v4.0.2 (recently tested)
+In our minimum support we're following [official Node.js releases timelines](https://nodejs.org/en/about/releases/).
 
-(This plugin is not working with v3.x and not may work with the older Strapi v4 versions, but these are not tested nor officially supported at this time.)
+**Supported Strapi versions**:
 
-**We recommend always using the latest version of Strapi to start your new projects**.
+- Strapi v4.0.5 (recently tested)
+- Strapi v4.x
 
-## Features
+> This plugin is designed for **Strapi v4** and is not working with v3.x. To get version for **Strapi v3** install version [v1.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments/tree/strapi-v3).
 
-- **Comments Public API:** Elegant, entirely customizable and a fully extensible admin panel.
-- **Strapi &amp; generic users:** Support for built-in &amp; also generic non-Strapi users that might be the comments authors.
-- **Any Content Type relation:** Comments can by linked to any of your Content Types by default. Simply, you're controlling it.
-- **Moderation Panel:** Search & Filter through the bucket with your auditory comments. Manage them by blocking single ones or full threads. All in combined list &amp; hierarchical tree view of threads.
-- **Automated Bad Words filtering:** By detault end users are not allowed to post abusing comments where bad words have been used.
-- **Abuse Reporting & Reviewing:** Don't allow inferior language, react to reports from your community, send email notifiactions about abuse reports
+**We recommend always using the latest version of Strapi to start your new projects**.
 
-## Configuration
+## 🔧 Configuration
 To setup amend default plugin configuration we recommend to put following snippet as part of `config/plugins.js` or `config/<env>/plugins.js` file. If the file does not exist yet, you have to create it manually. If you've got already configurations for other plugins stores by this way, use just the `comments` part within exising `plugins` item.
 
 
 ```js
-    ...
-    comments: {
-        badWords: false,
-        moderatorRoles: ["Authenticated"],
-        entryLabel: {
-            '*': ['Title', 'title', 'Name', 'name', 'Subject', 'subject'],
-            'api::page.page': ['MyField'],
+    module.exports = ({ env }) => ({
+        //...
+        comments: {
+            badWords: false,
+            moderatorRoles: ["Authenticated"],
+            approvalFlow: ['api::page.page'],
+            entryLabel: {
+                '*': ['Title', 'title', 'Name', 'name', 'Subject', 'subject'],
+                'api::page.page': ['MyField'],
+            },
+            reportReasons: {
+                'MY_CUSTOM_REASON': 'MY_CUSTOM_REASON',
+            },
         },
-    },
-    ...
+        //...
+    });
 ```
 
 ### Properties
 - `badWords` - Enabled support for [bad words filtering](https://www.npmjs.com/package/bad-words). Can be turned off or overwritten using [options reference](https://www.npmjs.com/package/bad-words#constructor). Default value: `true`. 
 - `moderatorRoles` - Optional list of names of roles. Users with those roles will be notified by email when a new abuse report is created. This feature requires a built-in [Strapi email plugin](https://docs.strapi.io/developer-docs/latest/plugins/email.html) configured.
-- `entryLabel` - ordered list of property names per Content Type to generate related entity label. Default set as `*`.
+- `approvalFlow` - list of Content Types which are supporting approval flow. Values must be in format like `'api::<collection name>.<content type name>'`. For not included, posted comments are going to be immediately visible. 
+- `entryLabel` - ordered list of property names per Content Type to generate related entity label. Keys must be in format like `'api::<collection name>.<content type name>'`. Default formatting set as `*`.
+- `reportReasons` - set of enums you would like to use for issuing abuse reports. Provided by default `'BAD_LANGUAGE'`, `'DISCRIMINATION'` and `'OTHER'`.
 
 ## Additional GQL Configuration
+All you need to do is to install and enable `@strapi/plugin-graphql` for you instance based on the **[official Strapi v4 docs](https://docs.strapi.io/developer-docs/latest/plugins/graphql.html#configurations)**.
+
+See [available GQL specification section](#public-graphql-specification).
+
+## 👤 RBAC
+Plugin provides granular permissions based on Strapi RBAC functionality.
 
-> To be done
+### Mandatory permissions
+For any role different than **Super Admin**, to access the **Comments panel** you must set following permissions:
+- _Plugins_ -> _Content-type-builder_ -> _Read_ - gives you ability to fetch Content Type schema
+- _Plugins_ -> _Comments_ -> _Comments: Read_ - gives you the basic read access to **Comments Panel**
 
-## Public API Comment model
+### Optional permissions
+Feature / Capability focused permissions:
+- _Plugins_ -> _Comments_ -> _Comments: Moderate_ - allows you to block, unblock, approve &amp; reject comments
+- _Plugins_ -> _Comments_ -> _Reports: Read_ - allows you to see the list of issued abuse reports against comments
+- _Plugins_ -> _Comments_ -> _Reports: Moderate_ - allows you to review (resolve) issued abuse reports against comments
+
+## Base Comment model
 
 ### Generic (non Strapi User)
 ```json
@@ -104,10 +143,14 @@ To setup amend default plugin configuration we recommend to put following snippe
     "blockedThread": true,
     "blockReason": null,
     "authorUser": null,
-    "authorId": "207ccfdc-94ba-45eb-979c-790f6f49c392",
-    "authorName": "Joe Doe",
-    "authorEmail": "jdoe@sample.com",
-    "authorAvatar": null,
+    "removed": null,
+    "approvalStatus": "APPROVED", // Only in case of enabled approval flow. Default: null
+    "author": {
+        "id": "207ccfdc-94ba-45eb-979c-790f6f49c392",
+        "name": "Joe Doe",
+        "email": "jdoe@sample.com",
+        "avatar": null,
+    },
     "createdAt": "2020-07-14T20:13:01.649Z",
     "updatedAt": "2020-07-14T20:13:01.670Z",
     "related": {}, // Related content type entity
@@ -122,6 +165,8 @@ To setup amend default plugin configuration we recommend to put following snippe
     "blocked": true,
     "blockedThread": null,
     "blockReason": null,
+    "removed": null,
+    "approvalStatus": "REJECTED", // Only in case of enabled approval flow. Default: null
     "authorUser": {
         "id": 1,
         "username": "Sample User",
@@ -145,10 +190,12 @@ To setup amend default plugin configuration we recommend to put following snippe
 
 ```
 
-## Public API specification
+## 🕸️ Public REST API specification
 
 ### Get Comments
 
+*GraphQL equivalent: [Public GraphQL API -> Get Comments](#get-comments-1)*
+
 `GET <host>/comments/api::<collection name>.<content type name>:<entity id>`
 
 Return a hierarchical tree structure of comments for specified instance of Content Type like for example `Page` with `ID: 1`
@@ -157,24 +204,28 @@ Return a hierarchical tree structure of comments for specified instance of Conte
 
 **Example response body**
 
-```
+```json
 [
     {
-        -- Comment Model fields ---,
+        // -- Comment Model fields ---,
         children: [
             {
-                -- Comment Model fields ---,
-                children: [...]
+                // -- Comment Model fields ---,
+                children: [
+                    // ...
+                ]
             },
-            ...
+            // ...
         ]
     },
-    ...
+    // ...
 ]
 ```
 
 ### Get Comments (flat structure)
 
+*GraphQL equivalent: [Public GraphQL API -> Get Comments (flat structure)](#get-comments-flat-structure-1)*
+
 `GET <host>/comments/api::<collection name>.<content type name>:<entity id>/flat`
 
 Return a flat structure of comments for specified instance of Content Type like for example `Page` with `ID: 1`
@@ -183,15 +234,15 @@ Return a flat structure of comments for specified instance of Content Type like
 
 **Example response body**
 
-```
+```json
 [
     {
-        -- Comment Model fields ---
+        // -- Comment Model fields ---
     },
     {
-        -- Comment Model fields ---
+        // -- Comment Model fields ---
     },
-    ...
+    // ...
 ]
 ```
 
@@ -201,6 +252,8 @@ Return a flat structure of comments for specified instance of Content Type like
 
 ### Post a Comment
 
+*GraphQL equivalent: [Public GraphQL API -> Post a Comments](#post-a-comment-1)*
+
 `POST <host>/comments/api::<collection name>.<content type name>:<entity id>`
 
 Posts a Comment related to specified instance of Content Type like for example `Page` with `ID: 1`
@@ -210,7 +263,7 @@ Posts a Comment related to specified instance of Content Type like for example `
 **Example request body**
 
 *Generic (non Strapi User)*
-```
+```json
 {
     "author": {
         "id": "<any ID like value>",
@@ -220,25 +273,23 @@ Posts a Comment related to specified instance of Content Type like for example `
     },
 	"content": "My sample response",
 	"threadOf": 2, // id of comment we would like to start / continue the thread (Optional)
-	"related": "api::page.page:1"
 }
 ```
 
 *Strapi user*
-```
+```json
 {
 	"authorUser": 1, // id of a author user. Optional in case of 'enableUsers: true' in the plugin configuration
 	"content": "My sample response",
 	"threadOf": 2, // id of comment we would like to start / continue the thread (Optional)
-	"related": "api::page.page:1"
 }
 ```
 
 **Example response body**
 
-```
+```json
 {
-    -- Comment Model fields ---
+    // -- Comment Model fields ---
 }
 ```
 
@@ -248,6 +299,8 @@ Posts a Comment related to specified instance of Content Type like for example `
 
 ### Update Comment
 
+*GraphQL equivalent: [Public GraphQL API -> Update Comments](#update-comment-1)*
+
 `PUT <host>/comments/api::<collection name>.<content type name>:<entity id>/comment/<commentId>`
 
 Updates a specified Comment content based on it `commentId` and related to specified instance of Content Type like for example `Page` with `ID: 1`
@@ -257,7 +310,7 @@ Updates a specified Comment content based on it `commentId` and related to speci
 **Example request body**
 
 *Generic (non Strapi User)*
-```
+```json
 {
     "author": {
         "id": "<any ID like value>"
@@ -267,7 +320,7 @@ Updates a specified Comment content based on it `commentId` and related to speci
 ```
 
 *Strapi user*
-```
+```json
 {
 	"authorUser": 1, // id of a author user. Optional in case of 'enableUsers: true' in the plugin configuration
 	"content": "My sample response"
@@ -276,9 +329,9 @@ Updates a specified Comment content based on it `commentId` and related to speci
 
 **Example response body**
 
-```
+```json
 {
-    -- Comment Model fields ---
+    // -- Comment Model fields ---
 }
 ```
 
@@ -289,6 +342,8 @@ Updates a specified Comment content based on it `commentId` and related to speci
 
 ### Delete Comment
 
+*GraphQL equivalent: [Public GraphQL API -> Delete Comment](#delete-comment-1)*
+
 `DELETE <host>/comments/api::<collection name>.<content type name>:<entity id>/<commentId>?authorId=<authorId>`
 
 Deletes a specified Comment based on it `commentId` and related to specified instance of Content Type like for example `Page` with `ID: 1`.
@@ -297,9 +352,9 @@ Deletes a specified Comment based on it `commentId` and related to specified ins
 
 **Example response body**
 
-```
+```json
 {
-    -- Empty Response ---
+    // -- Empty Response ---
 }
 ```
 
@@ -308,7 +363,9 @@ Deletes a specified Comment based on it `commentId` and related to specified ins
 - `409` - Conflict. Occurs when trying to delete a non existing comment.
 
 
-### Report abuse in the Comment
+### Issue Abuse Report against specified Comment
+
+*GraphQL equivalent: [Public GraphQL API -> Issue Abuse Report against specified Comment](#issue-abuse-report-against-specified-comment-1)*
 
 `POST <host>/comments/api::<collection name>.<content type name>:<entity id>/comment/<commentId>/report-abuse`
 
@@ -318,20 +375,20 @@ Reports abuse in specified Comment content based on it `commentId` and related t
 
 **Example request body**
 
-```
+```json
 {
 	"reason": "<reason enum>",
 	"content": "This comment is not relevant"
 }
 ```
 
-*Available reason enums:* `OTHER`, `BAD_WORDS`, `DISCRIMINATION`
+*Available reason enums:* `BAD_WORDS`, `OTHER`, `DISCRIMINATION` (want more? See [configuration section](#configuration).)
 
 **Example response body**
 
-```
+```json
 {
-    -- Comment Abuse Report fields ---
+    // -- Comment Abuse Report fields ---
 }
 ```
 
@@ -339,15 +396,307 @@ Reports abuse in specified Comment content based on it `commentId` and related t
 - `200` - Successful. Response with reported abuse.
 - `409` - Conflict. Occurs when trying to report an abuse to a non existing comment.
 
-## Examples
+## 🕸️ Public GraphQL specification
+
+> *To test all queries and understand the schemas use GraphQL Playground exposed by `@strapi/plugin-graphql` on `http://localhost:1337/graphql`*
+
+### Get Comments
+
+*REST API equivalent: [Public REST API -> Get Comments](#get-comments)*
+
+**Example request**
+
+```graphql
+query {
+  findAllFlat(
+    relation: "api::page.page:1"
+    filters: { content: { contains: "Test" } }
+  ) {
+        id
+        content
+        blocked
+        threadOf {
+            id
+        }
+        author {
+            id
+            name
+        }
+    }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "findAllFlat": [
+      {
+        "id": 3,  
+        "content": "Test",
+        "blocked": false,
+        "threadOf": null,
+        "author": {
+          "id": "123456",
+          "name": "Joe Doe"
+        }
+      },
+      // ...
+    ]
+  }
+```
+
+### Get Comments (flat structure)
+
+*REST API equivalent: [Public REST API -> Get Comments (flat structure)](#get-comments-flat-structure)*
+
+**Example request**
+
+```graphql
+query {
+  findAllInHierarchy(relation: "api::page.page:1") {
+    id
+    content
+    blocked
+    children {
+      id
+      content
+    }
+    threadOf {
+      id
+    }
+    author {
+      id
+      name
+    }
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "findAllInHierarchy": [
+      {
+        "id": 1,
+        "content": "Test",
+        "blocked": false,
+        "children": [
+          {
+            "id": 6,
+            "content": "Text to search for"
+          },
+          // ...
+        ],
+        "threadOf": null,
+        "author": {
+          "id": "123456",
+          "name": "Joe Doe"
+        }
+      },
+      // ...
+    ]
+  }
+}
+```
+
+### Post a Comment
+
+*REST API equivalent: [Public REST API -> Post a Comment](#post-a-comment)*
+
+**Example request**
+
+```graphql
+mutation createComment {
+  createComment(
+    input: {
+      relation: "api::page.page:1"
+      content: "Hello World!"
+      threadOf: 3
+      author: { id: "12345678", name: "John Wick", email: "test@test.pl" }
+    }
+  ) {
+    id
+    content
+    threadOf {
+      id
+    }
+    author {
+      id
+      name
+    }
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "createComment": {
+      "id": 34,
+      "content": "Hello World!",
+      "threadOf": {
+        "id": 3
+      },
+      "author": {
+        "id": "12345678",
+        "name": "John Wick"
+      }
+    }
+  }
+}
+```
+
+### Update Comment
+
+*REST API equivalent: [Public REST API -> Update Comment](#update-comment)*
+
+**Example request**
+
+```graphql
+mutation updateComment {
+  updateComment(
+    input: {
+      id: 34
+      relation: "api::page.page:1"
+      content: "I've changed it!"
+      author: { id: "12345678" }
+    }
+  ) {
+    id
+    content
+    threadOf {
+      id
+    }
+    author {
+      id
+      name
+    }
+    createdAt
+    updatedAt
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "updateComment": {
+      "id": 34,
+      "content": "I've changed it!",
+      "threadOf": {
+        "id": 3
+      },
+      "author": {
+        "id": "12345678",
+        "name": "John Wick"
+      },
+      "createdAt": "2022-01-26T07:45:35.978Z",
+      "updatedAt": "2022-01-26T07:47:44.659Z"
+    }
+  }
+}
+```
+
+### Delete Comment
+
+*REST API equivalent: [Public REST API -> Delete Comment](#delete-comment)*
+
+**Example request**
+
+```graphql
+mutation removeComment {
+  removeComment(
+    input: { id: 33, relation: "api::page.page:1", author: { id: "12345678" } }
+  ) {
+    id
+    removed
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "removeComment": {
+      "id": 33,
+      "removed": true
+    }
+  }
+}
+```
+
+### Issue Abuse Report against specified Comment
+
+*REST API equivalent: [Public REST API -> Issue Abuse Report against specified Comment](#issue-abuse-report-against-specified-comment)*
+
+**Example request body**
+
+```graphql
+mutation createAbuseReport {
+  createAbuseReport(
+    input: {
+      commentId: 34
+      relation: "api::page.page:1"
+      reason: BAD_LANGUAGE
+      content: "Rude language"
+    }
+  ) {
+    id
+    reason
+    content
+    related {
+      id
+      author {
+        id
+        name
+      }
+    }
+  }
+}
+```
+
+*Available reason enums:* `BAD_WORDS`, `OTHER`, `DISCRIMINATION` (want more? See [configuration section](#configuration).)
+
+**Example response**
+
+```json
+{
+  "data": {
+    "createAbuseReport": {
+      "id": 28,
+      "content": "Rude language",
+      "reason": "DISCRIMINATION",
+      "related": {
+        "id": 34,
+        "author": {
+          "id": "12345678",
+          "name": "John Wick"
+        }
+      }
+    }
+  }
+}
+```
+
+## 🧩 Examples
 
-Live example of plugin usage can be found in the [VirtusLab Strapi Examples](https://github.com/VirtusLab/strapi-examples/tree/master/strapi-plugin-comments) repository.
+Live example of plugin usage can be found in the [VirtusLab Strapi Examples](https://github.com/VirtusLab/strapi-examples/tree/master/strapi-v4-plugin-comments) repository.
 
-## Contributing
+## 🤝 Contributing
 
 Feel free to fork and make a Pull Request to this plugin project. All the input is warmly welcome!
 
-## Community support
+## 👨‍💻 Community support
 
 For general help using Strapi, please refer to [the official Strapi documentation](https://strapi.io/documentation/). For additional help, you can use one of these channels to ask a question:
 
@@ -355,6 +704,6 @@ For general help using Strapi, please refer to [the official Strapi documentatio
 - [Slack - VirtusLab Open Source](https://virtuslab-oss.slack.com) We're present on a public channel #strapi-molecules
 - [GitHub](https://github.com/VirtusLab-Open-Source/strapi-plugin-comments/issues) (Bug reports, Contributions, Questions and Discussions)
 
-## License
+## 📝 License
 
 [MIT License](LICENSE.md) Copyright (c) [VirtusLab Sp. z o.o.](https://virtuslab.com/) &amp; [Strapi Solutions](https://strapi.io/).