Describe private chats system

protocol-spec/private-chats.md

@@ -0,0 +1,373 @@
+# Private chats
+
+## 1. Introduction
+
+This extension is intended for organizing private chat between two users.
+
+## 2. Message type identifiers
+
+- `urn:cadmium:chats:private:message` - regular message
+- `urn:cadmium:chats:private:read` - read message system
+- `urn:cadmium:chats:private:typing` - typing message system
+
+## 3. Errors
+
+- Ratelimit system: disabled
+- Authorization: enabled
+
+## 4. Chat message types
+
+- `urn:cadmium:chats:message-types:general` - message with text and optional media
+- `urn:cadmium:chats:message-types:audio` - audio message
+- `urn:cadmium:chats:message-types:geolocation` - message with geolocation (coordinates)
+
+## 5. Use cases
+
+### 5.1. Exchanging messages
+
+1. Sending message:
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "to": ["@user2@cadmium.org"],
+        "payload": {
+            "type": "urn:cadmium:chats:message-types:general",
+            "content": {
+                "text": "hello world",
+            }
+        }
+    }
+    ```
+
+    **Successful response**:
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "from": "cadmium.org",
+        "ok": true,
+        "payload": {
+            "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
+            "originServerTimestamp": 1599327584
+        }
+    }
+    ```
+
+    **Error response**:
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "from": "cadmium.org",
+        "ok": false,
+        "payload": {
+            "errID": "banned",
+            "errText": "The user banned you"
+        }
+    }
+    ```
+
+2. Receiving message on other side:
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "from": "@user1@cadmium.im",
+        "ok": true,
+        "payload": {
+            "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
+            "originServerTimestamp": 1599327584,
+            "type": "urn:cadmium:chats:message-types:general",
+            "content": {
+                "text": "hello world",
+            }
+        }
+    }
+    ```
+
+### 5.2. Exchanging media
+
+1. Upload the media to HTTP Upload service (explanation out of scope of this document)
+2. Send message containing the URL of uploaded media:
+
+   ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "to": ["@user2@cadmium.org"],
+        "payload": {
+            "type": "urn:cadmium:chats:message-types:general",
+            "content": {
+                "text": "",
+                "media": [
+                    {
+                        "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67",
+                        "mimeType": "image/jpeg"
+                    }
+                ]
+            }
+            
+        }
+    }
+   ```
+
+   **Response**:
+
+   ```json
+   {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:message",
+        "from": "cadmium.org",
+        "ok": true,
+        "payload": {
+            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
+            "originServerTimestamp": 1599329232
+        }
+    }
+   ```
+
+3. Receive message with media on other side:
+
+   ```json
+   {
+        "id": "defg",
+        "type": "urn:cadmium:chats:private:message",
+        "from": "@user1@cadmium.im",
+        "ok": true,
+        "payload": {
+            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
+            "originServerTimestamp": 1599329232,
+            "type": "urn:cadmium:chats:message-types:general",
+            "content": {
+                "text": "",
+                "media": [
+                    {
+                        "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67",
+                        "mimeType": "image/jpeg"
+                    }
+                ]
+            }
+        }
+    }
+   ```
+
+### 5.3. Read messages
+
+1. Read message
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:read",
+        "to": ["@user1@cadmium.org"],
+        "payload": {
+            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
+        }
+    }
+    ```
+
+    Response:
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:read",
+        "from": "cadmium.im",
+        "ok": true,
+        "payload": {}
+    }
+    ```
+
+2. Receive notification about message reading on other side:
+
+    ```json
+    {
+        "id": "defg",
+        "type": "urn:cadmium:chats:private:read",
+        "from": "@user2@cadmium.im",
+        "ok": true,
+        "payload": {
+            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e"
+        }
+    }
+    ```
+
+### 5.3. Typing messages
+
+1. Typing message
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:typing",
+        "to": ["@user1@cadmium.org"],
+        "payload": {
+            "status": "typing",
+        }
+    }
+    ```
+
+2. Receive notification about typing message on other side:
+
+    ```json
+    {
+        "id": "defg",
+        "type": "urn:cadmium:chats:private:read",
+        "from": "@user2@cadmium.im",
+        "ok": true,
+        "payload": {
+            "status": "typing"
+        }
+    }
+    ```
+
+3. Pause typing message (e.g. when user stops abruptly typing message or just sent the message)
+
+    ```json
+    {
+        "id": "abcd",
+        "type": "urn:cadmium:chats:private:typing",
+        "to": ["@user1@cadmium.org"],
+        "payload": {
+            "status": "paused",
+        }
+    }
+    ```
+
+4. Receive notification pausing typing message on other side:
+
+    ```json
+    {
+        "id": "defg",
+        "type": "urn:cadmium:chats:private:read",
+        "from": "@user2@cadmium.im",
+        "ok": true,
+        "payload": {
+            "status": "paused"
+        }
+    }
+    ```
+
+## 6. Business Rules
+
+None.
+
+## 7. JSON Schema
+
+### Send message (`urn:cadmium:chats:private:message`)
+
+**Request**:
+
+```typescript
+interface SendMessagePayload {
+    type: string; // the type of message
+    content: Content // the payload of message (depends on type)
+}
+```
+
+**Response**:
+
+```typescript
+interface SendMessageResponsePayload {
+    messageID: string; // the message id (stored in chat timeline)
+    originServerTimestamp: number // unix timestamp of sent message on the origin server
+}
+```
+
+#### Content sections
+
+- `urn:cadmium:chats:message-types:general`:
+
+    ```typescript
+    interface GeneralMessageContent {
+        text: string; // the text (body) of message
+        media?: Media[]; // media content
+    }
+
+    interface Media {
+        url: string; // url of media (where it stores)
+        mimeType: string; // mime type of media
+    }
+    ```
+
+- `urn:cadmium:chats:message-types:audio`:
+
+    ```typescript
+    interface AudioMessageContent {
+        url: string; // the url of audio message
+    }
+    ```
+
+- `urn:cadmium:chats:message-types:geolocation`:
+
+    ```typescript
+    interface GeolocationMessageContent {
+        lat: number; // the GPS latitude
+        lon: number; // the GPS longitude
+    }
+    ```
+
+### Receive message (`urn:cadmium:chats:private:message`)
+
+```typescript
+interface ReceiveMessagePayload {
+    messageID: string; // the id of received message
+    originServerTimestamp: number; // unix timestamp of received message on the origin server
+    type: string; // the type of message
+    content: Content // the payload of message (depends on type)
+}
+```
+
+### Read message (`urn:cadmium:chats:private:read`)
+
+**Request**:
+
+```typescript
+interface ReadMessagePayload {
+    messageID: string; // the message id of read message
+}
+```
+
+**Response**:
+
+None.
+
+### Receive read message notification (`urn:cadmium:chats:private:read`)
+
+```typescript
+interface ReceiveReadMessageNotifPayload {
+    messageID: string; // the message id of read message
+}
+```
+
+### Typing message (`urn:cadmium:chats:private:typing`)
+
+**Request**:
+
+```typescript
+interface TypingMessagePayload {
+    status: TypingStatus; // the status of the typing
+}
+
+enum TypingStatus {
+    typing,
+    paused
+}
+```
+
+**Response**:
+
+None.
+
+### Receive read message notification (`urn:cadmium:chats:private:typing`)
+
+```typescript
+interface TypingMessageNotifPayload {
+    status: TypingStatus; // the status of the typing
+}
+```