Adjust approach for search results for listable rooms

Added "/listable-room" endpoint for listing listable rooms with a similar
result format like the "/room" endpoint.
Switched left sidebar to use Conversation components for displaying
results.

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

2 files changed, 62 insertions, 0 deletions

diff --git a/docs/conversation.md b/docs/conversation.md
index 10899e69b..1c57556b6 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -4,6 +4,63 @@
 * 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:
+        Array of conversations, each conversation has at least:
+
+        field | type | API | Description
+        ------|------|-----|------------
+        `token` | string | * | Token identifier of the conversation which is used for further interaction
+        `type` | int | * | See list of conversation types in the [constants list](constants.md#Conversation-types)
+        `name` | string | * | Name of the conversation (can also be empty)
+        `displayName` | string | * | `name` if non empty, otherwise it falls back to a list of participants
+        `participantType` | int | * | Permissions level of the current user
+        `attendeeId` | int | v3 | Unique attendee id
+        `attendeePin` | string | v3 | Unique dial-in authentication code for this user, when the conversation has SIP enabled (see `sipEnabled` attribute)
+        `actorType` | string | v3 | Currently known `users|guests|emails|groups`
+        `actorId` | string | v3 | The unique identifier for the given actor type
+        `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)
+        `sessionId` | string | * | `'0'` if not connected, otherwise a 512 character long string
+        `hasPassword` | bool | * | Flag if the conversation has a password
+        `hasCall` | bool | * | Flag if the conversation has an active call
+        `canStartCall` | bool | * | Flag if the user can start a new call in this conversation (joining is always possible) (only available with `start-call-flag` capability)
+        `canDeleteConversation` | bool | 🆕 v2 | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)
+        `canLeaveConversation` | bool | 🆕 v2 | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)
+        `lastActivity` | int | * | Timestamp of the last activity in the conversation, in seconds and UTC time zone
+        `isFavorite` | bool | * | Flag if the conversation is favorited by the user
+        `notificationLevel` | int | * | The notification level for the user (one of `Participant::NOTIFY_*` (1-3))
+        `lobbyState` | int | * | Webinary lobby restriction (0-1), if the participant is a moderator they can always join the conversation (only available with `webinary-lobby` capability)
+        `lobbyTimer` | int | * | Timestamp when the lobby will be automatically disabled (only available with `webinary-lobby` capability)
+        `sipEnabled` | int | v3 | SIP enable status (0-1)
+        `canEnableSIP` | int | v3 | Whether the given user can enable SIP for this conversation. Note that when the token is not-numeric only, SIP can not be enabled even if the user is permitted and a moderator of the conversation
+        `unreadMessages` | int | * | Number of unread chat messages in the conversation (only available with `chat-v2` capability)
+        `unreadMention` | bool | * | Flag if the user was mentioned since their last visit
+        `lastReadMessage` | int | * | ID of the last read message in a room (only available with `chat-read-marker` capability)
+        `lastMessage` | message | * | Last message in a conversation if available, otherwise empty
+        `objectType` | string | * | The type of object that the conversation is associated with; "share:password" if the conversation is used to request a password for a share, otherwise empty
+        `objectId` | string | * | Share token if "objectType" is "share:password", otherwise empty
+
 ## Get user´s conversations
 
 * Method: `GET`
diff --git a/docs/events.md b/docs/events.md
index 227326a85..5b7558646 100644
--- a/docs/events.md
+++ b/docs/events.md
@@ -12,6 +12,11 @@ Explanations:
 * Event name: `OCA\Talk\Controller\RoomController::EVENT_BEFORE_ROOMS_GET`
 * Since: 8.0.0
 
+### Search listed conversations
+
+* Event class: `OCA\Talk\Events\UserEvent`
+* Event name: `OCA\Talk\Controller\RoomController::EVENT_BEFORE_LISTED_ROOMS_GET`
+* Since: 11.0.0
 
 ### Create conversation