🌉 Livedeck Server

Livedeck server is the bridge between the smartphone webapp and the software. It manages the data and the communication.

🔌 Installation

git clone git@github.com:Lund-Org/livedeck-server.git
cd livedeck-server
npm i --production

🔧 Usage

You need to set the following environment variables :

Variable name	Description
APP_JWT_SIGN_KEY	The hash to sign the JWT tokens
APP_WEBSOCKET_PORT	The port to communicate with the websocket

To add env var, use Docker, set in your own environment using export (on Bash), or put it in front of the next command like this : ENV_VAR=value <cmd>

node ./src/index.js

📞 Communication

📥 Websocket event received by the server

Event name	Data	Emit by	Need Authentication	Description
authentify	{ token: <string>, device: <front or software> }	WebApp	No	Allows an user to authentify its socket and to get access to the rest of the websocket calls
trigger-binding	{ id: <number> }	WebApp	Yes	Tell to the server that a binding has been triggered to send it to the software. ID is the id of the binding triggered.

---

📤 Websocket event sent by the server

Event name	Data	Target	Need Authentication	Description
create-category	{ category: <Category> }	WebApp	Yes	Tell to the webapp that a new category has been created
update-category	{ category: <Category> }	WebApp	Yes	Tell to the webapp that a category has been updated
delete-category	{ category: <Category> }	WebApp	Yes	Tell to the webapp that a category has been deleted
create-binding	{ binding: <Binding> }	WebApp	Yes	Tell to the webapp that a new binding has been created
update-binding	{ binding: <Binding> }	WebApp	Yes	Tell to the webapp that a binding has been updated
delete-binding	{ binding: <Binding> }	WebApp	Yes	Tell to the webapp that a binding has been deleted
binding-triggered	{ bindingId: <number> }	Software	Yes	Tell to the software that a binding has been triggered
authentication-ok		Both	Yes	Tell if the event authentify is a success
authentication-ko		Both	Yes	Tell if the event authentify is a success
trigger-binding-ok		Webapp	True	Tell if the event trigger-binding is a success
trigger-binding-ko		Webapp	True	Tell if the event trigger-binding is a failure

---

📝 API

🔑 Authentication

API Resources :

• POST /register
• POST /login
• POST /valid-token

---

POST /register

Example: http://localhost:4000/register

Request body :

{
  "username": "MyUsername",
  "password": "MyPassword"
}

Response body:

{
  "id": <number>,
  "username": <string>,
  "key": <string>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
}

POST /login

Example: http://localhost:4000/login

Request body :

{
  "username": <string>,
  "password": <string>
}

Response body:

{
  "id": <number>,
  "username": <string>,
  "key": <string>,
  "token": <string>
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>,
}

POST /valid-token

Example: http://localhost:4000/valid-token

Request body :

{
  "jwtToken": <string>
}

Response body:

{
  "user": {
    "id": <number>,
    "username": <string>,
    "key": <string>,
    "created_at": <Datetime string>,
    "updated_at": <Datetime string>
  }
}

---

📂 Categories

API Resources :

• GET /categories/
• GET /categories/:id
• POST /categories/
• PATCH /categories/:id
• DELETE /categories/:id
• POST /categories/:id/bindings/:bindingId
• DELETE /categories/:id/bindings/:bindingId

---

GET /categories/

Example: http://localhost:4000/categories/

Response body:

[
  {
    "id": <number>,
    "name": <string>,
    "color": <string>,
    "weight": <number>,
    "created_at": <Datetime string>,
    "updated_at": <Datetime string>
  },
  ...
]

GET /categories/:id/

Example: http://localhost:4000/categories/:id/

Response body:

{
  "id": <number>,
  "name": <string>,
  "color": <string>,
  "weight": <number>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
  "bindings": [
    <Binding>,
    ...
  ]
}

POST /categories/

Example: http://localhost:4000/categories/

Request body :

{
  "name": <string>,
  "color": <string>,
  "weight": <number>
}

Response body:

{
  "id": <number>,
  "name": <string>,
  "color": <string>,
  "weight": <number>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
  "bindings": [
    <Binding>,
    ...
  ]
}

PATCH /categories/:id/

Example: http://localhost:4000/categories/:id/

Request body :

{
  "name": <?string>,
  "color": <?string>,
  "weight": <?number>
}

Response body:

{
  "id": <number>,
  "name": <string>,
  "color": <string>,
  "weight": <number>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
  "bindings": [
    <Binding>,
    ...
  ]
}

DELETE /categories/:id/

Example: http://localhost:4000/categories/:id/

Response body:

{
  "removed": {
    "id": <number>,
    "name": <string>,
    "color": <string>,
    "weight": <number>,
    "created_at": <Datetime string>,
    "updated_at": <Datetime string>
  }
}

POST /categories/:id/bindings/:bindingId/

Example: http://localhost:4000/categories/:id/bindings/:bindingId/

Response body:

{
  "id": <number>,
  "name": <string>,
  "color": <string>,
  "weight": <number>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
  "bindings": [
    <Binding>,
    ...
  ]
}

DELETE /categories/:id/bindings/:bindingId/

Example: http://localhost:4000/categories/:id/bindings/:bindingId/

Response body:

{
  "id": <number>,
  "name": <string>,
  "color": <string>,
  "weight": <number>,
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
  "bindings": [
    <Binding>,
    ...
  ]
}

---

📢 Bindings

API Resources :

• GET /bindings/
• GET /bindings/:id
• POST /bindings/
• PATCH /bindings/:id
• DELETE /bindings/:id

---

GET /bindings/

Example: http://localhost:4000/bindings/

Response body:

[
  {
    "id": <number>,
    "name": <string>,
    "icon": <string>,
    "weight": <number>,
    "type": <string>,
    "configuration": <Object>,
    "created_at": <Datetime string>,
    "updated_at": <Datetime string>
  },
  ...
]

GET /bindings/:id/

Example: http://localhost:4000/bindings/:id/

Response body:

{
  "id": <number>,
  "name": <string>,
  "icon": <string>,
  "weight": <number>,
  "type": <string>,
  "configuration": <Object>,
  "categories": [
    <Category>,
    ...
  ],
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
}

POST /bindings/

Example: http://localhost:4000/bindings/

Request body :

{
  "name": <string>,
  "icon": <string>,
  "weight": <number>,
  "type": <string>
}

Response body:

{
  "id": <number>,
  "name": <string>,
  "icon": <string>,
  "weight": <number>,
  "type": <string>,
  "configuration": <Object>,
  "categories": [],
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
}

PATCH /bindings/:id/

Example: http://localhost:4000/bindings/:id/

Request body :

{
  "name": <?string>,
  "icon": <?string>,
  "weight": <?number>
  "type": <?string>
  "configuration": <?JSON>
}

Response body:

{
  "id": <number>,
  "name": <string>,
  "icon": <string>,
  "weight": <number>,
  "type": <string>,
  "configuration": <Object>,
  "categories": [
    <Category>,
    ...
  ],
  "created_at": <Datetime string>,
  "updated_at": <Datetime string>
}

DELETE /bindings/:id/

Example: http://localhost:4000/bindings/:id/

Response body:

{
  "removed": {
    "id": <number>,
    "name": <string>,
    "icon": <string>,
    "weight": <number>,
    "type": <string>,
    "configuration": <Object>,
    "categories": [],
    "created_at": <Datetime string>,
    "updated_at": <Datetime string>
  }
}

📂 Resources

• Cherry : The framework used to build the http server
• Cherry Pug connector : The plugin which uses pug as the view engine
• Cherry Typeorm connector : The plugin which uses typeorm as the database-orm engine

✏️ Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

📖 License

MIT