From 2bb4ae89c1de8f11a3400fb8f0ac2c898917c73e Mon Sep 17 00:00:00 2001
From: "Josepablo C." <josepablo134@gmail.com>
Date: Thu, 9 Nov 2023 08:54:33 -0600
Subject: [PATCH] chore: Adding account endpoint documentation

---
 README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/README.md b/README.md
index 378d147..59698cb 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ Example:
 
 Read registered resources:
 
+ - `GET /account`: At this location you can: register, login, recover password, renew JWT.
  - `GET /countries`: List registered countries.
  - `GET /cities`: List registered cities.
  - `GET /meta-data`: List registered meta-data.
@@ -39,6 +40,148 @@ All these endpoints support the following parameters (except for those with `pub
  - `/:id` : Read specific resource identified by Id.
  - `/find?regex=xxx` : List resources that matches with regex (support pagination).
 
+### /account
+
+This endpoint provides mechanisms to register, login, recover password and renew JWT.
+
+The __Login__ and __Renew__ process will return 2 tokens, the `accessToken` (JWT) which is used in every further request to authorize access to private endpoints. And the 2nd is the `session_token` (renew token), which should be used after the expiration of the JWT, in order to generate another _JWT_ and _session token_ without the need of use the _email_ and _password__.
+
+The _session token_ expiration is typically 30 days after its generation. Every renewal replaces the token in the DB and the expiration is reset again to 30 days.
+
+#### POST /account/authorize
+
+Login process, returns a JWT and Renew Token
+
+Expects a body with the following data:
+```{.json}
+{
+    "email":"testing@etaviaporte.com",
+    "password":"PasswordExample"
+}
+```
+
+Returns:
+```{.javascript}
+{
+    "accessToken" : "JWT",
+    "payload" : "Content in the JWT",
+    "session_token": "Renew token",
+    "session_token_exp": "Expiration of renew token in UNIX epoch format",
+    "user" : { ... }
+}
+```
+
+#### GET /account/authorize/:session_token
+
+Renewal of JWT with session token, will return the new session token and a new JWT only if the session token is not expired, otherwise the request will fail and the login process should be used instead.
+
+Example of usage:
+```
+    GET /account/authorize/"HERE_GOES_THE_SESSION_TOKEN"
+```
+
+Returns:
+```{.json}
+{
+    "accessToken" : "JWT",
+    "payload" : "Content in the JWT",
+    "session_token": "Renew token",
+    "session_token_exp": "Expiration of renew token in UNIX epoch format",
+    "user" : { ... }
+}
+```
+
+#### POST /account/signup
+
+Create a new user. This will trigger an email with the OTP (one time password) to verify the email. There is no expiration time, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End. 
+
+This will return a checksum string to be used in the confirmation process.
+
+Expects a body with the following data:
+```{.json}
+{
+    "email":"testing@etaviaporte.com",
+    "password":"PasswordExample"
+}
+```
+
+Returns:
+```{.javascript}
+{
+    "checksum" : "JWT"
+}
+```
+
+#### PATCH /account/signup
+
+Confirms registration of new user. This will trigger a welcome email to the user.
+There is no timeout to confirm the email, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End.
+
+If the checksum matches but the user is already registered, then this request will be rejected.
+
+Expects a body with the same data as the POST request, but adding the OTP received in the email, the company type decided by the user and the checksum generated by the POST request. It is important to noticed that company_type is case sensitive, the only options are either `Shipper` or `Carrier`. Here is an example:
+
+```{.json}
+{
+    "email":"testing@etaviaporte.com",
+    "password":"PasswordExample",
+    "otp":"OTP string",
+    "company_type":"Shipper or Carrier",
+    "checksum":"Checksum generated in the POST request"
+}
+```
+
+Returns:
+```{.json}
+{
+    "msg" : "User created successfully!"
+}
+```
+
+#### POST /account/recover
+
+Reset password request. This will trigger an email with the OTP (one time password) to verify the email. There is no expiration time, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End. 
+
+This will return a checksum string to be used in the confirmation process.
+
+Expects a body with the following data:
+```{.json}
+{
+    "email":"testing@etaviaporte.com",
+    "password":"new password"
+}
+```
+
+Returns:
+```{.javascript}
+{
+    "checksum" : "JWT"
+}
+```
+
+#### PATCH /account/recover
+
+Confirms the email to recover the password.
+There is no timeout to confirm the email, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End.
+
+Expects a body with the same data as the POST request, but adding the OTP received in the email, and the checksum generated by the POST request. Here is an example:
+
+```{.json}
+{
+    "email":"testing@etaviaporte.com",
+    "password":"New Password Example",
+    "otp":"OTP string",
+    "checksum":"Checksum generated in the POST request"
+}
+```
+
+Returns:
+```{.json}
+{
+    "msg" : "Password is reset!"
+}
+```
+
 ### GET /public-companies
 
 Get public fields from registered companies.