upmerging master into vue-rewrite

Signed-off-by: Devlin Junker <devlin.junker@gmail.com>

7 files changed, 170 insertions, 29 deletions

diff --git a/docs/admin.md b/docs/admin.md
index 00efe0d20..0b2cef164 100644
--- a/docs/admin.md
+++ b/docs/admin.md
@@ -1,17 +1,26 @@
 # Admin
 Welcome to the Admin documentation this page explains some of the configuration options for news.
 ## System Cron
-Nextcloud uses Cron to run regular jobs, News relies on the Job system to execute the feed updates.
+Nextcloud uses cron to run regular jobs, News relies on the Job system to execute the feed updates.
 Alternatively you may use an [external updater](https://nextcloud.github.io/news/clients/#update-clients), in this case you need to disable the system cron in the settings.
 
 ## Auto purge count
-This value represents the maximum amount of read items per feed, which won't be deleted by the cleanup job.
-For example if the value is 200 there can be maximum 200 read items per feed, unread items are unaffected.
-If old articles reappear after being read, try to increase this value.
-To disable this feature use -1.
+- The default value is 200.
+- To disable this feature, use -1.
+- Unread and starred items are not deleted.
+
+Auto purging automatically removes the oldest read items of every feed after every update.
+The value you enter here is used as the limit of read items per feed, unless the feed comes with more items in it's feed.
+For example you have the default value of 200 and the feed has 210 items in it's feed.
+In this case the limit will be 210 instead of 200.
+
+## Purge unread items
+This changes the behavior of the auto purging to also purge unread items. This is useful if you have users with a lot of unread items.
+
+**Starred items are always kept.**
 
 ## Explore Service
-If you are using the News app in your company/community it might be interesting to offer your users a bunch of easily to discover default feeds. You could also create a website where people can add and up-vote news feeds like bigger cloud feed readers like Feedly do it or even convert their APIs into a service for the News app (if someone wants to provide one for the News app, feel free to contact us by creating an issue in the bug tracker).
+If you are using the News app in your company/community, it might be interesting to offer your users a bunch of easily to discover default feeds. You could also create a website where people can add and up-vote news feeds like bigger cloud feed readers like Feedly do it or even convert their APIs into a service for the News app (if someone wants to provide one for the News app, feel free to contact us by creating an issue in the bug tracker).
 
 The URL should be a path to a directory which contains a JSON file in the format of **feeds.LANG_CODE.json** where LANG_CODE is a two character language code (e.g. **en** or **de**).
 
@@ -23,11 +32,12 @@ For example, entering the URL **https://domain.com/directory** as explore URL wi
 
 ## Update Interval
 The update interval is used to determine when the next update of all feeds should be done.
-You can configure this interval as an administrator.
+By default, the value is set to 3600 seconds (1 hour) You can configure this interval as an administrator.
+The new value is only applied after the next run of the updater.
 
 ### What is a good update interval?
 That depends on your individual needs.
 Please keep in mind that the lower you set your update interval, the more traffic is generated.
 
 ### Can I set individual update intervals per feed/user?
-No, the job framework of Nextcloud is pretty simple.
\ No newline at end of file
+No, that is not possible.
\ No newline at end of file
diff --git a/docs/api/api-v1-2.md b/docs/api/api-v1-2.md
index 0665bba72..3d8b22426 100644
--- a/docs/api/api-v1-2.md
+++ b/docs/api/api-v1-2.md
@@ -399,6 +399,30 @@ The following attributes are **not sanitized** meaning: including them in your w
 * **mediaThumbnail**
 * **mediaDescription**
 
+#### Types
+| Name             | Default | Types        |
+|------------------|---------|--------------|
+| author           | null    | string\|null |
+| body             |         | string\|null |
+| contentHash      |         | string\|null |
+| enclosureLink    |         | string\|null |
+| enclosureMime    |         | string\|null |
+| feedId           |         | int          |
+| fingerprint      |         | string\|null |
+| guid             |         | string       |
+| guidHash         |         | string       |
+| id               |         | int          |
+| lastModified     | \"0\"   | string\|null |
+| mediaDescription |         | string\|null |
+| mediaThumbnail   |         | string\|null |
+| pubDate          |         | int\|null    |
+| rtl              | false   | bool         |
+| starred          | false   | bool         |
+| title            |         | string\|null |
+| unread           | false   | bool         |
+| updatedDate      |         | string\|null |
+| url              |         | string\|null |
+    
 #### Get items
 * **Status**: Implemented
 * **Method**: GET
diff --git a/docs/api/api-v1-3.md b/docs/api/api-v1-3.md
index 4ecd22b95..7464efb09 100644
--- a/docs/api/api-v1-3.md
+++ b/docs/api/api-v1-3.md
@@ -354,7 +354,7 @@ Deletes a feed with the id feedId and all of its  items
 
 #### Rename a feed
 
-* **Status**: Implemented in 1.807
+* **Status**: Implemented in News 1.807
 * **Method**: POST
 * **Route**: /feeds/{feedId}/rename
 * **Parameters**:
@@ -399,6 +399,30 @@ The following attributes are **not sanitized** meaning: including them in your w
 * **mediaThumbnail**
 * **mediaDescription**
 
+#### Types
+| Name             | Default | Types        |
+|------------------|---------|--------------|
+| author           | null    | string\|null |
+| body             |         | string\|null |
+| contentHash      |         | string\|null |
+| enclosureLink    |         | string\|null |
+| enclosureMime    |         | string\|null |
+| feedId           |         | int          |
+| fingerprint      |         | string\|null |
+| guid             |         | string       |
+| guidHash         |         | string       |
+| id               |         | int          |
+| lastModified     | \"0\"   | string\|null |
+| mediaDescription |         | string\|null |
+| mediaThumbnail   |         | string\|null |
+| pubDate          |         | int\|null    |
+| rtl              | false   | bool         |
+| starred          | false   | bool         |
+| title            |         | string\|null |
+| unread           | false   | bool         |
+| updatedDate      |         | string\|null |
+| url              |         | string\|null |
+
 #### Get items
 * **Status**: Implemented
 * **Method**: GET
@@ -524,7 +548,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark multiple items as read
-* **Status**: Implemented in 1.2
+* **Status**: Implemented in API 1.2
 * **Method**: POST
 * **Route**: /items/read/multiple
 * **Parameters**:
@@ -545,7 +569,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark multiple items as unread
-* **Status**: Implemented in 1.2
+* **Status**: Implemented in API 1.2
 * **Method**: POST
 * **Route**: /items/unread/multiple
 * **Parameters**:
@@ -557,7 +581,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark an item as starred
-* **Status**: Implemented in 1.3
+* **Status**: Implemented in API 1.3
 * **Method**: POST
 * **Route**: /items/{itemId}/star
 * **Parameters**: none
@@ -566,7 +590,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark multiple items as starred
-* **Status**: Implemented in 1.3
+* **Status**: Implemented in API 1.3
 * **Method**: POST
 * **Route**: /items/star/multiple
 * **Parameters**:
@@ -578,7 +602,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark an item as unstarred
-* **Status**: Implemented in 1.3
+* **Status**: Implemented in API 1.3
 * **Method**: POST
 * **Route**: /items/{itemId}/unstar
 * **Parameters**: none
@@ -587,7 +611,7 @@ This is used to stay up to date.
 * **Returns**: nothing
 
 #### Mark multiple items as unstarred
-* **Status**: Implemented in 1.3
+* **Status**: Implemented in API 1.3
 * **Method**: POST
 * **Route**: /items/unstar/multiple
 * **Parameters**:
@@ -632,7 +656,7 @@ This [implementation in Python](https://github.com/nextcloud/news-updater) shoul
 #### Trigger cleanup before update
 This is used to clean up the database. It deletes folders and feeds that are marked for deletion
 
-* **Status**: Implemented in 1.601
+* **Status**: Implemented in News 1.601
 * **Authentication**: Requires admin user
 * **Method**: GET
 * **Route**: /cleanup/before-update
@@ -644,7 +668,7 @@ This is used to clean up the database. It deletes folders and feeds that are mar
 
 #### Get feed ids and usernames for all feeds
 
-* **Status**: Implemented in 1.203
+* **Status**: Implemented in News 1.203
 * **Authentication**: Requires admin user
 * **Method**: GET
 * **Route**: /feeds/all
@@ -668,7 +692,7 @@ This is used to clean up the database. It deletes folders and feeds that are mar
 
 #### Trigger a feed update
 
-* **Status**: Implemented in 1.601
+* **Status**: Implemented in News 1.601
 * **Authentication**: Requires admin user
 * **Method**: GET
 * **Route**: /feeds/update
@@ -690,7 +714,7 @@ This is used to clean up the database. It deletes folders and feeds that are mar
 #### Trigger cleanup after update
 This is used to clean up the database. It removes old read articles which are not starred
 
-* **Status**: Implemented in 1.601
+* **Status**: Implemented in News 1.601
 * **Authentication**: Requires admin user
 * **Method**: GET
 * **Route**: /cleanup/after-update
@@ -721,7 +745,7 @@ This API can be used to display warnings and errors in your client if the web ap
 
 #### Get the status
 
-* **Status**: Implemented in 5.2.4
+* **Status**: Implemented in News 5.2.4
 * **Method**: GET
 * **Route**: /status
 * **Parameters**: none
@@ -757,7 +781,7 @@ DEPRECATED: This API is deprecated, use the Nextcloud APIs instead.
 
 #### Get the status
 
-* **Status**: Implemented in 6.0.5
+* **Status**: Implemented in News 6.0.5
 * **Method**: GET
 * **Route**: /user
 * **Parameters**: none
diff --git a/docs/clients.md b/docs/clients.md
index db1f82458..411d91f99 100644
--- a/docs/clients.md
+++ b/docs/clients.md
@@ -10,6 +10,8 @@ A sync client can be used to read news and synchronize via the API.
 | Name                                                                                                             | OS/Platform                  | License              | Source                                                             |
 |------------------------------------------------------------------------------------------------------------------|------------------------------|----------------------|--------------------------------------------------------------------|
 | [RSS Guard](https://github.com/martinrotter/rssguard)                                                            | Windows, Linux, OS/2, macOS  | GPL-3.0 License      | [GitHub](https://github.com/martinrotter/rssguard)                 |
+| [Fluent Reader](https://hyliu.me/fluent-reader/)                                                                 | Windows, Linux, macOS  | BSD-3-Clause License   | [GitHub](https://github.com/yang991178/fluent-reader)                          |
+| [Communique](https://flathub.org/apps/details/com.github.suzie97.communique)                                                              | Linux                  |  LGPL-2.1 License      | [GitHub](https://github.com/Suzie97/Communique)                |
 | [Nextcloud News Reader](https://play.google.com/store/apps/details?id=de.luhmer.owncloudnewsreader)              | Android                      | GPL-3.0 License      | [GitHub](https://github.com/nextcloud/news-android-app)            |
 | [OCReader](https://f-droid.org/repository/browse/?fdid=email.schaal.ocreader)                                    | Android                      | GPL-3.0 License      | [GitHub](https://github.com/schaal/ocreader)                       |
 | [Newsout](https://play.google.com/store/apps/details?id=com.inspiredandroid.newsout)                             | Android                      | Apache-2.0 License   | [GitHub](https://github.com/SimonSchubert/NewsOut)                 |
@@ -24,6 +26,7 @@ A sync client can be used to read news and synchronize via the API.
 | [py3status](https://github.com/ultrabug/py3status/)                                                              | i3wm                         | BSD-3-Clause License | [GitHub](https://github.com/ultrabug/py3status/)                   |
 | [newsboat](https://newsboat.org/)                                                                                | Unix Terminal                | MIT License          | [GitHub](https://github.com/newsboat/newsboat)                     |
 | [Newsie](https://open-store.io/app/newsie.martinferretti)                                                        | Ubuntu Touch                 | GPL-3.0 License      | [GitLab](https://gitlab.com/ferrettim/newsie)                      |
+| [Fuoten](https://github.com/Huessenbergnetz/Fuoten)                                                              | Sailfish OS                  | GPL-3.0 License      | [GitHub](https://github.com/Huessenbergnetz/Fuoten)                |
 
 ## Update Clients
 
diff --git a/docs/developer.md b/docs/developer.md
index 8a6bdd411..50f82db1d 100644
--- a/docs/developer.md
+++ b/docs/developer.md
@@ -11,7 +11,8 @@ News offers an API that can be used by clients to synchronize with the server.
 There are two API declarations, so far only V1 has been fully implemented.
 Work on V2 has started with low priority.
 
-- [API-V1](api/api-v1.md)
+- [API-V1.2](api/api-v1-2.md)
+- [API-V1.3](api/api-v1-3.md)
 - [API-V2](api/api-v2.md)
 
 ## Coding Style Guidelines
@@ -20,3 +21,33 @@ The PHP code should all adhere to [PSR-2](https://www.php-fig.org/psr/psr-2/).
 To test the codestyle you can run `make phpcs`.
 
 For linting JavaScript, a [jshint file](https://github.com/nextcloud/news/blob/master/js/.jshintrc) is used that is run before compiling the JavaScript.
+
+## General Developer setup
+Check the Nextcloud [documentation](https://docs.nextcloud.com/server/latest/developer_manual/getting_started/devenv.html) to learn how to setup a developer environment, alternatively to a proper web server you can also use the [builtin php server](https://www.php.net/manual/en/features.commandline.webserver.php) on demand, it is enough for development purposes.
+
+When your setup is running, clone the news repository in the `apps/` directory inside the server.
+
+Change into the news directory and run make to build the app, you will need php, composer, node, npm and maybe more.
+
+Now you can basically use the news app and test your changes.
+
+## Running Integration tests locally
+We use [bats](https://bats-core.readthedocs.io/en/stable/) to run integration tests against the API and the cli.
+
+Check how to install bats on your system in the [official documentation](https://bats-core.readthedocs.io/en/stable/installation.html).
+
+You also need to pull the submodules of the news repo.
+```bash
+git submodules update --init
+```
+
+The cli tests expect that the feeds are reachable at `http://localhost:8090`, to achieve that you can use `make feed-server &` the `&` means it'll run in the background.
+
+Now the test feeds will be reachable for bats.
+Run the tests by executing `bats tests/command` you can also only run specific tests for example `bats tests/command/feeds.bats`.
+
+For the API tests you need to run a second php server or have another web server that provides Nextcloud and the News App.
+The tests expect to find Nextcloud at `http://localhost:8080`
+You can do this by running `make nextcloud-server`.
+
+The bats tests can be executed like this `bats tests/api`.
diff --git a/docs/faq.md b/docs/faq.md
index bfb62e3e9..e9c4d5e95 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -28,7 +28,7 @@ Since an attacker can not execute code in contrast to mixed active content, but
 
 ### Why don't you simply use an HTTPS image/audio/video proxy
 
-For the same reason that we can't fix non HTTPS websites: It does not fix the underlying issue but only silences it. If you are using an image HTTPS proxy, an attacker can simply attack your image proxy since the proxy fetches insecure content. **Even worse**: if your image proxy serves these images from the same domain as your Nextcloud installation you [are vulnerable to XSS via SVG images](https://www.owasp.org/images/0/03/Mario_Heiderich_OWASP_Sweden_The_image_that_called_me.pdf). In addition, people feel safe when essentially they are not.
+For the same reason that we can't fix non HTTPS websites: It does not fix the underlying issue, but only silences it. If you are using an image HTTPS proxy, an attacker can simply attack your image proxy since the proxy fetches insecure content. **Even worse**: if your image proxy serves these images from the same domain as your Nextcloud installation, you [are vulnerable to XSS via SVG images](https://www.owasp.org/images/0/03/Mario_Heiderich_OWASP_Sweden_The_image_that_called_me.pdf). In addition, people feel safe when essentially they are not.
 
 Since most people don't understand mixed content and don't have two domains and a standalone server for the image proxy, it is very likely they will choose to host it under the same domain.
 
@@ -91,13 +91,14 @@ By appending **?subscribe_to=SOME_URL** to your News app URL, you can launch the
 
 ## Database table grows too big
 
+If your users have subscribed to some high-volume feeds where a lot of items remain unread, 
+this can lead to an oversized news table over time. As a consequence, the database upgrade of the news app can take several hours, during which Nextcloud cannot be used.
+
 By default, Nextcloud News purges old news items above a certain threshold each time it fetches new news items. The maximum number of items per feed
 that should be kept during the purging can be defined through the “Maximum read count per feed” setting in the admin UI or the `autoPurgeCount`
-value in the config. (Note: The “Purge interval” (`autoPurgeMinimumInterval`) setting is ignored and does not have any effect.)
-
-However, unread or starred items are exempt from the purging. If your users have subscribed to some high-volume feeds where a lot of items remain
-unread, this can lead to an oversized news table over time. As a consequence, the database upgrade of the news app can take several hours, during which
-Nextcloud cannot be used.
+value in the config.
+Additionally you may enable the option to also purge unread items `purgeUnread`. This is useful if your users have large amounts of unread items.
+Starred items are always exempt from purging.
 
 The command `occ news:updater:after-update [--purge-unread] [<purge-count>]` can be used to manually purge old news items across the instance. With
 the `--purge-unread` option, unread items are also purged (starred items are still exempt). If `purge-count` is not specified, the configured
diff --git a/docs/install.md b/docs/install.md
index 5ab1dffcb..84d218341 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,4 +1,4 @@
-# Installation/Update
+# Installation/Update & Uninstall
 
 ## Dependencies
 * 64bit OS (starting with News 16.0.0)
@@ -93,3 +93,51 @@ To update the News app use change into the **nextcloud/apps/news/** directory us
 
     git pull --rebase origin master
     make
+
+## Uninstall with cleanup
+
+First uninstall the app via the web-interface or via occ:
+
+```console
+./occ app:remove news
+```
+
+This currently does not remove any of the database tables.
+Data in your `/tmp` directory will be automatically deleted by the OS.
+If you changed the temporary directory for Nextcloud you need to check on your own.
+
+Careful, this next part is only intended for admins, that know what they are doing.
+
+To remove the tables from the DB we drop the tables of news.
+Your installation might have a different prefix then `oc_` but it is the default in most installations.
+Connect to your DB and execute the commands. Don't forget to switch to the right database.
+For example in mysql: `use nextcloud;`
+
+```sql
+DROP TABLE oc_news_folders;
+DROP TABLE oc_news_feeds;
+DROP TABLE oc_news_items;
+```
+
+Then we remove the traces in the migrations table.
+
+```sql
+DELETE FROM oc_migrations WHERE app='news';
+```
+
+Next delete the app configuration.
+
+```sql
+DELETE FROM oc_appconfig WHERE appid = 'news';
+```
+
+And finally remove the jobs from the job table.
+The last two lines are only needed for older installations.
+
+```sql
+DELETE FROM oc_jobs WHERE class='OCA\\News\\Cron\\UpdaterJob';
+DELETE FROM oc_jobs WHERE class='OCA\\News\\Cron\\Updater';
+DELETE FROM oc_jobs WHERE argument='["OCA\\\\News\\\\Cron\\\\Updater","run"]';
+```
+
+Now nothing is left from news in your nextcloud installation.
\ No newline at end of file