brainlet/DOCS.md

# Waffle API docs (currently not implemented)

# Gateway

Waffle uses a WebSocket gateway to transmit various updates from the server to the client and vice-versa (new message, user disconnecting, connect to voice, etc.)

# Gateway Payload format

All payloads sent through the gateway are *string payloads*. They all start with a number represeting the "instruction", followed by a "@" character (to delimit the instruction number from the rest of the payload), after which comes the data for the specific instruction.

Example packet:
```json
23@this is my payload data
```
Note for the example above: The "this is my payload data" text should not be user controlled. If user controlled input is required, it must be sanitized and/or passed as a JSON field.

Packets can also have JSON as a payload:
```json
32@{"name":"Alice"}
```

## Instructions

The terms "channel" and "category" are used interchangeably.

## 0:HELLO
*Part of handshake, Server to client*

Sent by the server to the client as soon as possible after they connect to the gateway.

This payload can contain a JSON object with various information about the server. It should be relied on only when absolutely necessary.

Example:
```json
0@{}
```

## 1:YOO
*Part of handshake, Client to server*

Sent by the client as soon as possible after receiving the HELLO instruction.


JSON data format:   
| Field | Description |
| - | - |
| token | The authentication token |
| client | The name of the application the client is connecting from (e.g. browser_react_app) |

Example:
```json
1@{"token":"my totally real token","client":"amazing client"}
```

If the token is invalid, or the connection is otherwise rejected, the client should be disconnected as soon as possible, and no YOO\_ACK should be sent.

## 2:YOO\_ACK
*Part of handshake, Server to client*

Sent by the server as soon as possible after processing the YOO payload from the client.

This payload contains an empty JSON object, that may have data added to it in later versions of this software.

Example:
```json
2@{}
```

## 3:ACTION\_CREATE\_MESSAGE
*Auth required, Client to server*

Sent by the client when sending a message.

JSON data format:
| Field | Description |
| - | - |
| content | The text content of the message |
| channel | An object that contains "_id", the id of the channel to send the message to |

Example:
```json
3@{"content":"i hate you","channel_id":"totally real channel id"}
```

## 4:EVENT\_NEW\_MESSAGE
*Auth required, Server to client*

Sent by the server when a new message is created in a channel the client is subscribed to.

JSON data format:
[Message object](#message-object)

## 5:ACTION\_UPDATE\_STATUS
*Auth required, Client to server*

Sent by the client when updating status. Usually, this packet is sent as soon as possible after getting YOO\_ACK to indicate the client is online.

JSON data format:
| Field | Description |
| - | - |
| status | Can be 0(STATUS\_OFFLINE) or 1(STATUS\_ONLINE) |
| status_text | Custom status text, max 50 characters, min 1 non-whitespace character, trimmed |

Example:
```json
5@{"status":1,"status_text":"hello"}
```

## 6:EVENT\_CHANNEL\_MEMBERS

*Auth required, Server to client*

Sent by the server after YOO\_ACK, and otherwise when the entire status needs to be updated. If only one user's status changes, use EVENT\_CHANNEL\_MEMBER\_UPDATE.

JSON data format (this ones tough):
Contains a JSON object, where each key is a channel id and each property is an array of [user presence objects](#user-presence-object).

Example:
```json
6@{"totallyrealid":[{_id:"totallyrealuserid",username:"totallyrealusername",status:1,status_text:"hello"}]}
```

## 7:EVENT\_CHANNEL\_MEMBER\_UPDATE

*Auth required, Server to client*

Sent by the server when the status of a member changes. Of course, the client has to be in a channel with that member in order to receive this update.

JSON data format:
It's just a [user presence object](#user-presence-object).

Example:
```json
7@{_id:"totallyrealuserid",username:"totallyrealusername",status:1,status_text:"hello"}
```

## 21:ACTION\_VOICE\_BEGIN\_SESSION

*Auth required, Client to server*

Sent by the client whenever it wants to initiate a voice session in a specific channel.

JSON data format:

| Field | Description |
| - | - |
| channel | An object that contains "_id", the id of the channel to connect to |

(unfinished)

## 22:ACTION\_VOICE\_BEGIN\_SESSION

*Auth required, Client to server*

Sent by the server when the voice session request has been accepted. If it is rejected, the client MUST be disconnected from the gateway as soon as possible.

JSON data format:

| Field | Description |
| - | - |
| reportTo | The IP and port of the voice server to connect to |

(unfinished)

# Objects and data types

## Message object

| Field | Description |
| - | - |
| content | The text content of the message (max 2000 characters, min 1 character, trimmed) |
| channel | A [message channel object](#message-channel-object) |
| author | A [message author object](#message-author-object) |

## Message channel object

Used mostly for messages.

| Field | Description |
| - | - |
| _id | The id of the channel |
| name | The name of the channel |

## Message author object

Used mostly for messages.

| Field | Description |
| - | - |
| _id | The id of the user |
| name | The name of the user |

## User presence object

| Field | Description |
| - | - |
| _id | The id of the user |
| name | The name of the user |
| status | The status of the user (see ACTION_UPDATE_STATUS) |
| status_text | The text status of the user (see ACTION_UPDATE_STATUS) |