Add listable flags attribute for conversations

Added ability to set a conversation as listable for regular users and/or
guest users from the guest app.

This only implements the flag, endpoint and UI to manage it but not yet
making it appear in search results.

Signed-off-by: Vincent Petry <vincent@nextcloud.com>

5 files changed, 35 insertions, 1 deletions

diff --git a/docs/capabilities.md b/docs/capabilities.md
index 6bf6a30ec..22fca01ff 100644
--- a/docs/capabilities.md
+++ b/docs/capabilities.md
@@ -59,3 +59,4 @@ title: Capabilities
 * `config => previews => max-gif-size` - Maximum size in bytes below which a GIF can be embedded directly in the page at render time. Bigger files will be rendered statically using the preview endpoint instead. Can be set with `occ config:app:set spreed max-gif-size --value=X` where X is the new value in bytes. Defaults to 3 MB.
 * `chat-read-status` - On conversation API v3 and the chat API the last common read message is exposed which can be used to update the "read status" flag of own chat messages. The info should be shown only when the user also shares their read status. The user's value can be found in `config => chat => read-privacy`.
 * `config => chat => read-privacy` - See `chat-read-status`
+* `listable-rooms` - Conversations can searched for even when not joined. A "listable" attribute set on rooms defines the scope of who can find it.
diff --git a/docs/chat.md b/docs/chat.md
index 11191c68f..736a199f1 100644
--- a/docs/chat.md
+++ b/docs/chat.md
@@ -149,7 +149,7 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
         `status` | string | Optional: Only available with `includeStatus=true` and for users with a set status
         `statusIcon` | string | Optional: Only available with `includeStatus=true` and for users with a set status
         `statusMessage` | string | Optional: Only available with `includeStatus=true` and for users with a set status
-        
+
 ## System messages
 
 * `conversation_created` - {actor} created the conversation
@@ -160,6 +160,9 @@ Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
 * `call_ended` - Call with {user1}, {user2}, {user3}, {user4} and {user5} (Duration 30:23)
 * `read_only_off` - {actor} unlocked the conversation
 * `read_only` - {actor} locked the conversation
+* `listable_participants` - {actor} made the conversation listable only for participants
+* `listable_users` - {actor} made the conversation listable for regular users
+* `listable_all` - {actor} made the conversation listable for everone which includes users and guest users
 * `lobby_timer_reached` - The conversation is now open to everyone
 * `lobby_none` - {actor} opened the conversation to everyone
 * `lobby_non_moderators` - {actor} restricted the conversation to moderators
diff --git a/docs/constants.md b/docs/constants.md
index 2304240d5..8a250c02c 100644
--- a/docs/constants.md
+++ b/docs/constants.md
@@ -12,6 +12,11 @@ title: Constants
 * `0` read-write
 * `1` read-only
 
+## Listable scope
+* `0` participants only
+* `1` regular users only, excluding guests
+* `2` everyone
+
 ## Participant types
 * `1` owner
 * `2` moderator
diff --git a/docs/conversation.md b/docs/conversation.md
index 4c495507f..10899e69b 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -38,6 +38,7 @@
         `participantInCall` | bool | 🏴 v1 | Flag if the current user is in the call (deprecated, use `participantFlags` instead)
         `participantFlags` | int | * | Flags of the current user (only available with `in-call-flags` capability)
         `readOnly` | int | * | Read-only state for the current user (only available with `read-only-rooms` capability)
+        `listable` | int | * | Listable scope for the room (only available with `listable-rooms` capability)
         `count` | int | 🏴 v1 | **Deprecated:** ~~Number of active users~~ - always returns `0`
         `numGuests` | int | 🏴 v1 | Number of active guests
         `lastPing` | int | * | Timestamp of the last ping of the current user (should be used for sorting)
@@ -266,3 +267,20 @@
         + `400 Bad Request` When the the given level is invalid
         + `401 Unauthorized` When the participant is a guest
         + `404 Not Found` When the conversation could not be found for the participant
+
+## Set listable scope for a conversation
+
+* Method: `PUT`
+* Endpoint: `/room/{token}/listable`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `scope` | int | New flags for the conversation
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `400 Bad Request` When the conversation type does not support making it listable (only group and public conversation)
+        + `403 Forbidden` When the current user is not a moderator/owner or the conversation is not a public conversation
+        + `404 Not Found` When the conversation could not be found for the participant
diff --git a/docs/events.md b/docs/events.md
index c4701df75..227326a85 100644
--- a/docs/events.md
+++ b/docs/events.md
@@ -54,6 +54,13 @@ Explanations:
 * After event name: `OCA\Talk\Room::EVENT_AFTER_READONLY_SET`
 * Since: 8.0.0
 
+### Set listable
+
+* Event class: `OCA\Talk\Events\ModifyRoomEvent`
+* Before event name: `OCA\Talk\Room::EVENT_BEFORE_LISTABLE_SET`
+* After event name: `OCA\Talk\Room::EVENT_AFTER_LISTABLE_SET`
+* Since: 11.0.0
+
 ### Set lobby
 
 * Event class: `OCA\Talk\Events\ModifyLobbyEvent`