API doc

.github/workflows/build.yml

@@ -12,5 +12,5 @@ jobs:
       - uses: actions/setup-python@v2
         with:
           python-version: 3.x
-      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material mkdocs-section-index
       - run: mkdocs gh-deploy --force

docs/API/configuration.md

@@ -0,0 +1,38 @@
+## Philosophy
+Every fosscord server instance should be completely configurable in every way, without the need to change the source code.
+
+The config should have reasonable defaults similar to discord.
+
+Only in special cases it should require a third party config value.
+
+The config should be changeable over the admin fosscord-dashboard and update in realtime without the need to restart the servers
+
+The very first time the server starts, it saves to default config in the database. The next start it will load the config from the database.
+
+## Getting Started
+You **should not** ``get()`` the Config in the root of your file and it instead load the config every time you access a value
+
+Import the file:
+```js
+// at the top of the file import the Config file from /src/util/Config.ts
+import Config from "/../util/Config";
+```
+
+Access the Config in your route:
+```js
+router.get("/", (req: Request, res: Response) => {
+    // call Config.get() to get the whole config object and then just access the property you want
+    const { REGISTRATION_DISABLED } = Config.get().register
+});
+```
+
+``Config.get()`` returns the current config object and is not expensive at all
+
+### Add own values to the Config
+The default Config is located in ``/src/util/Config.ts`` and exports a ``interface DefaultOptions`` and a ``const DefaultOptions`` object with reasonable default values.
+
+To add your own values to the config, add the properties to the ``interface`` with corresponding types and add default values to ``const DefaultOptions``.
+
+Also you don't need to worry about updating "old config versions", because new values will automatically be synced with the database.
+
+Note, however, that if the database already has a default value it won't update it.

docs/API/contributing.md

@@ -0,0 +1,29 @@
+## Requirements
+You should be familiar with:
+
+* [Git](https://git-scm.com/)
+* [NodeJS](https://nodejs.org/)
+* [TypeScript](https://www.typescriptlang.org/)
+* [Mongoose](https://mongoosejs.com/)
+
+and the technologies we use for the API.
+
+## Getting Started
+Clone the Repository:
+```bash
+git clone https://github.com/fosscord/fosscord-api
+cd fosscord-api
+```
+### Install (dev) dependencies
+```bash
+npm install
+npm install --only=dev
+```
+### Starting
+```
+npm start
+```
+### Debugging
+#### VS Code
+The Launch file configuration is in ``./vscode/launch.json``,
+so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button

docs/API/index.md

@@ -0,0 +1,11 @@
+[Status overview](https://github.com/discord-open-source/discord-api/projects/2)
+
+This is a complete one-on-on clone of the discord api written in TypeScript.
+
+For documentation, head over to the [Discord docs](https://discord.dev).
+
+## Installation
+The API is not yet finished.
+
+## Contribution
+If want to help developing go ahead and read the [Contribution Guide](contribution).

docs/API/project_structure.md

@@ -0,0 +1,20 @@
+## Translation
+Additionally, we use [i18next](https://www.i18next.com/) to manage translation/localization in _some_ API Responses.
+
+The ``.json`` language files are located in ``/locales`` and are separated by namespaces.
+
+## Source code
+We use [TypeScript](https://www.typescriptlang.org/) (JavaScript with types).
+The ``.ts`` source files are located in ``/src/`` and will be  compiled to ``.js`` in the ``/dist/`` directory.
+
+### Middlewares
+All Express [Middlewares](http://expressjs.com/en/guide/writing-middleware.html) are in the directory ``/src/middlewares/`` and need to be manually loaded in ``/src/Server.ts``.
+
+### Routes
+All Express [Router](http://expressjs.com/en/4x/api.html#router) Routes are in the directory ``/src/routes/`` and are automatically registered.
+
+### Models
+All Database Typescript interface models are in the directory ``/src/models/``
+
+### Util
+All Utility functions are in the directory ``/src/util/``.

docs/API/route.md

@@ -0,0 +1,111 @@
+## General
+All routes are located in the directory ``/src/routes/`` and are loaded on start by a the [lambert-server](https://www.npmjs.com/package/lambert-server) package.
+
+The HTTP API path is generated automatically based on the folder structure, so it is important that you name your files accordingly.
+
+If you want to use URL Params like ``:id`` in e.g. ``/users/:id`` you need to use ``#`` instead of ``:`` for the folder/filename, because of file naming issues on windows.
+
+``index.ts`` files **won't** serve ``/api/index`` and instead alias the parent folder e.g. ``/api/``
+
+Your file needs to default export a [express.Router()](https://expressjs.com/de/4x/api.html#router):
+```ts
+import { Router } from express
+const router = Router();
+export default router;
+```
+Now you can just use any regular express function on the router variable e.g:
+```ts
+router.get("/", (req, res) => {});
+router.post("/", (req, res) => {});
+router.get("/members", (req, res) => {});
+```
+
+## Authentication
+Every request must contain the authorization header except the ``/login`` and ``/register`` route.
+
+To access the user id for the token of the request use ``req.user_id`` 
+
+
+## Body Validation
+We use a custom body validation logic from lambert-server to check if the JSON body is valid.
+
+To import the function from ``/src/util/instanceOf.ts`` use:
+```ts
+import { check } from "/src/util/instanceOf";
+```
+Now you can use the [middleware](http://expressjs.com/en/guide/using-middleware.html) ``check`` for your routes by calling check with your Body Schema.
+```ts
+router.post("/", check(...), (req,res) => {});
+```
+
+### Schema
+A Schema is a Object Structure with key-value objects that checks if the supplied body is an instance of the specified class.
+```ts
+{ id: String, roles: [String] }
+```
+_Notice if you use e.g. BigInt even if you can't supply it with JSON, it will automatically convert the supplied JSON number/string to a BigInt._
+
+_Also if you want to check for an array of, just put the type inside ``[]``_ 
+
+#### Optional Parameter
+You can specify optional parameters if you prefix the key with a ``$`` (dollar sign) e.g.: ``{ $captcha: String }``, this will make the captcha property in the body optional.
+
+#### Limit String length
+Additionally import the class ``Length`` from instanceOf and specify the type by making a new ``Length`` Object taking following parameters:
+```ts
+import { Length } from "/src/util/instanceOf";
+const min = 2;
+const max = 32;
+const type = String;
+
+{ username: new Length(min: number, max: number, type) }
+```
+this will limit the maximum string length to the ``min`` and ``max`` value.
+
+### Example:
+```ts
+import { check, Length } from "/src/util/instanceOf";
+const SCHEMA = { username: new Length(2, 32, String), age: Number, $posts: [{ title: String }] }
+app.post("/", check(SCHEMA), (req, res) => {});
+```
+
+
+## Throw Errors
+If the body validation fails it will automatically throw an error.
+
+The ``errors`` structure is a key-value Object describing what field contained the error:
+```json
+{
+    "code": 50035,
+    "message": "Invalid Form Body",
+    "errors": {
+        "email": {
+            "_errors": [
+                {
+                    "message": "Email is already registered",
+                    "code": "EMAIL_ALREADY_REGISTERED"
+                }
+            ]
+        },
+        "username": {
+            "_errors": [
+                {
+                    "message": "Must be between 2 - 32 in length",
+                    "code": "BASE_TYPE_BAD_LENGTH"
+                }
+            ]
+        }
+    }
+}
+```
+
+To manually throw a ``FieldError`` import ``FieldErrors``
+```ts
+import { FieldErrors } from /src/util/instanceOf
+```
+To make sure your errors are understood in all languages translate it with [i18next](https://www.i18next.com/translation-function/essentials) and ``req.t``
+
+So after you have checked the field is invalid throw the ``FieldErrors``
+```ts
+throw FieldErrors(( login: { message: req.t("auth:login.INVALID_LOGIN"), code: "INVALID_LOGIN" }});
+```

docs/API/testing.md

@@ -0,0 +1,22 @@
+## Testing the api manually
+### Step 1
+Follow the setup instructions [here](../../installation).
+
+### Step 2
+Navigate to the Gateway, install packages and start:
+```
+cd fosscord/gateway
+npm i
+npm start
+```
+
+### Step 3
+Navigate to the API, install packages and start:
+```
+cd fosscord/api
+npm i
+npm start
+```
+
+### Step 4
+Navigate to `localhost:3001`. You will see the API in action.

docs/contributing.md

@@ -0,0 +1,35 @@
+## Issues
+### Naming convention
+The issue name must have the main label as a prefix in brackets: e.g. ``[Feature] Test`` or ``[Bug] Test``.
+
+The first letter of the prefix and the title must be uppercase.
+
+You are not allowed to use CAPS.
+
+
+## Project structure
+Fosscord consists of many repositories, which together make up the client and the server:
+
+### Server-side
+- [Fosscord-server-util](https://github.com/fosscord/fosscord-server-util) contains all shared logic like Database Models, Utility functions 
+- [Fosscord-api](https://github.com/fosscord/fosscord-api) is the REST HTTP API server
+- [Fosscord-gateway](https://github.com/fosscord/fosscord-gateway) is the WebSocket Gateway server
+- [Fosscord-media](https://github.com/fosscord/fosscord-media) will be the media server for voice and video sharing
+- [Fosscord-cdn](https://github.com/fosscord/fosscord-cdn) is the content-delivery-content (CDN) that stores user uploaded images
+
+### Client-side
+- [Fosscord-UI](https://github.com/fosscord/fosscord-ui/wiki) is a user interface framework in the style of discord
+- [Fosscord-Themes](https://github.com/fosscord/fosscord-themes) contains all the official themes for the client
+- [Fosscord-Plugins](https://github.com/fosscord/fosscord-plugins) contains all the official plugins for the client
+- [Fosscord-Landingpage](https://github.com/fosscord/fosscord-landingpage) represents and explains the project
+- [Fosscord-Client](https://github.com/fosscord/fosscord-client) is the official Fosscord client
+
+#### Discontinued
+- https://github.com/fosscord/react-native-withcss
+- https://github.com/fosscord/css-mediaquery
+
+### Setup
+To setup all repositories clone this repo with submodules enabled:
+```
+git clone --recurse-submodules -j8 https://github.com/DiegoMagdaleno/fosscord.git
+```

docs/index.md

@@ -1,4 +1,32 @@
-# Fosscord Docs
+# Home
+### Why the name Fosscord?
+Fosscord is a combination of the abbreviation FOSS (**F**ree **O**pen **S**ource **S**oftware) and the name Dis**cord**.
 
-**Note:** This is a **WIP** documentation.
+## Philosophy
-So, this is not designed for be used in productions for now.
+Fosscord aims to be a full one-on-one clone of Discord, adding more features that can be used as a replacement for the official client and still connect to discord.com and host private Fosscord server instances.
+
+Fosscord aims to give the best possible user experience, while being backwards compatible to Discord's features and adding new ones/improving old ones.
+
+The client can connect to multiple server instances without the need to open it multiple times.
+
+The client should be extensible through a secure Plugin and Theme System with own store.
+
+The server should be extensible through bots, just like discord without the need to change anything except the api endpoint.
+
+The project is open source so everyone can have a look what's going on under the hood and can be maintained and expanded by the community.
+
+Everything is configurable in the server config and everyone can add their own features, so that it is not opinionated.
+
+### Concept
+<img src="img/architecture.png" alt="Architecture">
+
+### Why backwards compatible to Discord?
+- Benefit from the large user base of discord -> make a better client
+- No disadvantage for the users who use fosscord, so that they can still communicate with all friends who use discord
+- Discord has already built a great and stable protocol _(don't reinvent the wheel)_
+- _(We can still add additional features)_
+
+## Support
+[Discord server](https://discord.gg/ZrnGQP6p3d)
+
+If we are finished, we'll host our own support server.

mkdocs.yml

@@ -1,5 +1,7 @@
 site_name: Fosscord Docs
 repo_url: https://github.com/Stylix58/fosscord-docs
+plugins:
+  - section-index
 theme:
   name: material
   logo: assets/logo.png