Merge pull request #4706 from nextcloud/enh/1763/listable-rooms

Add listable scope attribute for conversations

5 files changed, 53 insertions, 2 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..95700a8c9 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_none` - {actor} made the conversation visible for nobody
+* `listable_users` - {actor} made the conversation visible for regular users
+* `listable_all` - {actor} made the conversation visible for everone which includes users and guests
 * `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..dd4f0e02f 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 guest app users
+* `2` everyone
+
 ## Participant types
 * `1` owner
 * `2` moderator
diff --git a/docs/conversation.md b/docs/conversation.md
index 4c495507f..7b90beed5 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -4,6 +4,24 @@
 * Base endpoint for API v2 is: `/ocs/v2.php/apps/spreed/api/v2`
 * Base endpoint for API v3 is: `/ocs/v2.php/apps/spreed/api/v3`
 
+## Get listed conversations
+
+* Method: `GET`
+* Endpoint: `/listed-room`
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `401 Unauthorized` when the user is not logged in
+
+    - Header:
+
+        field | type | Description
+        ------|------|------------
+        `searchTerm` | string | search term
+
+    - Data: See array definition in `Get user´s conversations`
+
 ## Get user´s conversations
 
 * Method: `GET`
@@ -38,6 +56,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 +285,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..b8d6d694c 100644
--- a/docs/events.md
+++ b/docs/events.md
@@ -12,7 +12,6 @@ Explanations:
 * Event name: `OCA\Talk\Controller\RoomController::EVENT_BEFORE_ROOMS_GET`
 * Since: 8.0.0
 
-
 ### Create conversation
 
 * Event class: `OCA\Talk\Events\RoomEvent`
@@ -54,6 +53,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`