Start converting to readthedocs

Signed-off-by: Joas Schilling <coding@schilljs.com>

.gitignore

@@ -2,6 +2,9 @@
 build
 node_modules
 
+# Local docs
+/site
+
 # Karma/jasmine coverage data
 coverage
 tests/php/coverage-html

docs/call.md

@@ -0,0 +1,42 @@
+# Call API
+
+Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+
+## Get list of connected participants
+
+* Method: `GET`
+* Endpoint: `/call/{token}`
+
+* Response:
+    - Header:
+        + `200 OK`
+        + `404 Not Found` When the conversation could not be found for the participant
+
+    - Data:
+        Array of participants, each participant has at least:
+
+        field | type | Description
+        ------|------|------------
+        `userId` | string | Is empty for guests
+        `lastPing` | int | Timestamp of the last ping of the user (should be used for sorting)
+        `sessionId` | string | 512 character long string
+
+## Join a call
+
+* Method: `POST`
+* Endpoint: `/call/{token}`
+
+* Response:
+    - Header:
+        + `200 OK`
+        + `404 Not Found` When the conversation could not be found for the participant
+
+## Leave a call (but staying in the conversation for future calls and chat)
+
+* Method: `DELETE`
+* Endpoint: `/call/{token}`
+
+* Response:
+    - Header:
+        + `200 OK`
+        + `404 Not Found` When the conversation could not be found for the participant

docs/capabilities.md

@@ -0,0 +1,34 @@
+---
+title: Capabilities
+---
+
+## 3.0 (Initial Talk release)
+* `audio` - audio is supported
+* `video` - video + screensharing is supported
+* `chat` - simple text chat is supported, superseded by `chat-v2`
+
+## 3.1
+* `guest-signaling` - Guests can do signaling via api endpoints
+* `empty-group-room` - Group conversations can be created without inviting a Nextcloud user group by default
+
+## 3.2
+* `guest-display-names` - Display names of guests are stored in the database, can be set via API (not WebRTC only) and are used on returned comments/participants/etc.
+* `multi-room-users` - Users can be in multiple conversations at the same time now, therefor signaling now also requires the conversation token on the URL.
+* `chat-v2` - Chat messages are now [Rich Object Strings](https://github.com/nextcloud/server/issues/1706) and pagination is available, the previous `chat` is not available anymore.
+
+## 4.0
+* `favorites` - Conversations can be marked as favorites which will pin them to the top of the conversation list.
+* `last-room-activity` - Conversations have the `lastActivity` attribute and should be sorted by that instead of the last ping of the user.
+* `no-ping` - The ping endpoint has been removed. Ping is updated with a call to fetch the signaling or chat messages instead.
+* `system-messages` - Chat messages have a `systemMessage` attribute and can be generated by the system
+* `mention-flag` - The conversation list populates the boolean `unreadMention` when the user was mentioned since their last visit
+* `in-call-flags` - A new flag `participantFlags` has been introduced and is replacing the `participantInCall` boolean.
+
+## 5.0
+* `invite-by-mail` - *Replaced by `invite-groups-and-mails`* Guests can be invited with their email address
+* `notification-levels` - Users can select when they want to be notified in conversations
+* `invite-groups-and-mails` - Groups can be added to existing conversations via the add participant endpoint
+
+## 6.0
+* `locked-one-to-one-rooms` - One-to-one conversations are now locked to the users. Neither guests nor other participants can be added, so the options to do that should be hidden as well. Also a user can only leave a one-to-one conversation (not delete). It will be deleted when the other participant left too. If the other participant posts a new chat message or starts a call, the left-participant will be re-added.
+* `read-only-rooms` - Conversations can be in `read-only` mode which means people can not do calls or write chat messages.

docs/chat.md

@@ -0,0 +1,151 @@
+# Chat API
+
+Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`
+
+## Receive chat messages of a conversation
+
+* Method: `GET`
+* Endpoint: `/chat/{token}`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `lookIntoFuture` | int | `1` Poll and wait for new message or `0` get history of a conversation
+    `limit` | int | Number of chat messages to receive (100 by default, 200 at most)
+    `timeout` | int | `$lookIntoFuture = 1` only, Number of seconds to wait for new messages (30 by default, 60 at most)
+    `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header.
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `304 Not Modified` When there were no older/newer messages
+        + `404 Not Found` When the conversation could not be found for the participant
+
+    - Header:
+
+        field | type | Description
+        ------|------|------------
+        `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page.
+
+    - Data:
+        Array of messages, each message has at least:
+
+        field | type | Description
+        ------|------|------------
+        `id` | int | ID of the comment
+        `token` | string | Conversation token
+        `actorType` | string | `guests` or `users`
+        `actorId` | string | User id of the message author
+        `actorDisplayName` | string | Display name of the message author
+        `timestamp` | int | Timestamp in seconds and UTC time zone
+        `systemMessage` | string | empty for normal chat message or the type of the system message (untranslated)
+        `message` | string | Message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
+        `messageParameters` | array | Message parameters for `message` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
+
+## Sending a new chat message
+
+* Method: `POST`
+* Endpoint: `/chat/{token}`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `message` | string | The message the user wants to say
+    `actorDisplayName` | string | Guest display name (ignored for logged in users)
+
+* Response:
+    - Header:
+        + `201 Created`
+        + `400 Bad Request` In case of any other error
+        + `404 Not Found` When the conversation could not be found for the participant
+        + `413 Payload Too Large` When the message was longer than the allowed limit of 32000 characters (or 1000 until Nextcloud 16.0.1, check the `spreed => config => chat => max-length` capability for the limit)
+
+    - Data:
+        The full message array of the new message, as defined in [Receive chat messages of a conversation](#receive-chat-messages-of-a-conversation)
+
+## Get mention autocomplete suggestions
+
+* Method: `GET`
+* Endpoint: `/chat/{token}/mentions`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `search` | string | Search term for name suggestions (should at least be 1 character)
+    `limit` | int | Number of suggestions to receive (20 by default)
+
+* Response:
+    - Status code:
+        + `200 OK`
+        + `404 Not Found` When the conversation could not be found for the participant
+
+    - Data:
+        Array of suggestions, each suggestion has at least:
+
+        field | type | Description
+        ------|------|------------
+        `id` | string | The user id which should be sent as `@<id>` in the message
+        `label` | string | The displayname of the user
+        `source` | string | The type of the user, currently only `users`
+
+## System messages
+
+* `conversation_created` - {actor} created the conversation
+* `conversation_renamed` - {actor} renamed the conversation from "foo" to "bar"
+* `call_started` - {actor} started a call
+* `call_joined` - {actor} joined the call
+* `call_left` - {actor} left the call
+* `call_ended` - Call with {user1}, {user2}, {user3}, {user4} and {user5} (Duration 30:23)
+* `guests_allowed` - {actor} allowed guests in the conversation
+* `guests_disallowed` - {actor} disallowed guests in the conversation
+* `password_set` - {actor} set a password for the conversation
+* `password_removed` - {actor} removed the password for the conversation
+* `user_added` - {actor} added {user} to the conversation
+* `user_removed` - {actor} removed {user} from the conversation
+* `moderator_promoted` - {actor} promoted {user} to moderator
+* `moderator_demoted` - {actor} demoted {user} from moderator
+* `guest_moderator_promoted` - {actor} promoted {user} to moderator
+* `guest_moderator_demoted` - {actor} demoted {user} from moderator
+* `read_only_off` - {actor} unlocked the conversation
+* `read_only` - {actor} locked the conversation
+
+## Guests
+        
+        
+## Signaling
+
+### Get signaling settings
+
+* Method: `GET`
+* Endpoint: `/signaling/settings`
+* Data:
+
+    field | type | Description
+    ------|------|------------
+    `stunservers` | array | STUN servers
+    `turnservers` | array | TURN servers
+    `server` | string | URL of the external signaling server
+    `ticket` | string | Ticket for the external signaling server
+
+    - STUN server
+
+       field | type | Description
+       ------|------|------------
+       `url` | string | STUN server URL
+
+    - TURN server
+
+       field | type | Description
+       ------|------|------------
+       `url` | array | One element array with TURN server URL
+       `urls` | array | One element array with TURN server URL
+       `username` | string | User name for the TURN server
+       `credential` | string | User password for the TURN server
+
+* Response:
+    - Header:
+        + `200 OK`
+        + `404 Not Found`
+
+### External signaling API
+See External Signaling API [Draft](https://github.com/nextcloud/spreed/wiki/Signaling-API) in the wiki…

docs/commands.md

@@ -1,11 +1,15 @@
 # Chat commands
 
+!!! note
 
-## Admin defined commands
+    For security reasons commands can only be added via the
+    command line. `./occ  talk:command:add --help` gives you
+    a short overview of the required arguments, but they are
+    explained here in more depth.
 
-For security reasons commands can only be added via the command line. `./occ  talk:command:add --help` gives you a short overview of the required arguments, but they are explained here in more depth:
+---
 
-### "Add command" arguments
+## "Add command" arguments
 
 Argument | Allowed chars | Description
 ---|---|---
@@ -15,7 +19,7 @@ Argument | Allowed chars | Description
 `response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone
 `enabled` | 0-3 |  Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone
 
-### Script parameter
+## Script parameter
 
 Parameter | Description
 ---|---
@@ -24,11 +28,11 @@ Parameter | Description
 `{ARGUMENTS}` | Everything the user write after the actual command
 `{ARGUMENTS_DOUBLEQUOTE_ESCAPED}` | … but with double quotes `"` escaped.
 
-### Example
+## Example
 
 * `/path/to/calc.sh`:
 
-    ```
+```
     while test $# -gt 0; do
       case "$1" in
         --help)
@@ -43,13 +47,13 @@ Parameter | Description
           ;;
      esac
     done
-    
+
     set -f
     echo "$@ ="
     echo $(gnome-calculator --solve="$@")
-    ```
+```
 
-    Please note, that your command should also understand the argument `--help`.
+Please note, that your command should also understand the argument `--help`.
 It should return a useful description, the first line is also displayed in a list of all commands when the user just types `/help`.
 
 * `./occ` command used to add the command:

docs/constants.md

@@ -0,0 +1,25 @@
+---
+title: Constants
+---
+
+## Conversation types
+* `1` "one to one"
+* `2` group
+* `3` public
+* `4` changelog
+
+## Read-only states
+* `0` read-write
+* `1` read-only
+
+## Participant types
+* `1` owner
+* `2` moderator
+* `3` user
+* `4` guest
+* `5` user following a public link
+
+## Actor types of chat messages
+* `guests` - guest users
+* `users` - logged-in users
+* `bots` - used by commands (actor-id is the used `/command`) and the changelog conversation (actor-id is `changelog`)