Deliveryman

<br>

Permit to register clients, deliverymen, deliveries and manage deliveries status (in progress, done, etc). The app has friendly errors, use JWT to logins, validation, also a simple versioning was made.

Table of Contents

• Installing
  • Configuring
    • .env
    • Postgres
      • Migrations
• Usage
  • Error Handling
    • Errors Reference
  • Bearer Token
  • Versioning
  • Routes
    • Requests
• Running the tests
  • Coverage report

Installing

Easy peasy lemon squeezy:

$ yarn

Or:

$ npm install

Was installed and configured the eslint and prettier to keep the code clean and patterned.

Configuring

The application use just one database: Postgres. For the fastest setup is recommended to use docker-compose, you just need to up all services:

$ docker-compose up -d

.env

In this file you may configure your JWT settings, database connection, app's port and a url to documentation (this will be returned with error responses, see error section). Rename the .env.example in the root directory to .env then just update with your settings.

|key|description|default |---|---|--- |PORT|Port number where the app will run.|3333 |JWT_CLIENTS_SECRET|A alphanumeric random string. Used to create signed tokens for clients logins.| - |JWT_DELIVERYMAN_SECRET|A alphanumeric random string. Used to create signed tokens for deliverymen logins.| - |JWT_EXPIRATION|How long time will be the token valid. See jsonwebtoken repo for more information.|1d |DATABASE_URL|Database url.|postgresql://postgres:docker@localhost:5432/deliveryman?schema=public |DOCS_URL|An url to docs where users can find more information about the app's internal code errors.|https://github.com/DiegoVictor/deliveryman#errors-reference

Postgres

Responsible to store all application data. If for any reason you would like to create a Postgres container instead of use docker-compose, you can do it by running the following command:

$ docker run --name deliveryman-postgres -e POSTGRES_PASSWORD=docker -p 5432:5432 -d postgres

Migrations

Remember to run the Postgres database migrations:

$ npx prisma migrate deploy

Or:

$ yarn prisma migrate deploy

See more information on migrate deploy.

Usage

To start up the app run:

$ yarn dev:server

Or:

npm run dev:server

Error Handling

Instead of only throw a simple message and HTTP Status Code this API return friendly errors:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Username or password incorrect",
  "code": 140,
  "docs": "https://github.com/DiegoVictor/deliveryman#errors-reference"
}

Errors are implemented with @hapi/boom. As you can see a url to error docs are returned too. To configure this url update the DOCS_URL key from .env file. In the next sub section (Errors Reference) you can see the errors code description.

Errors Reference

|code|message|description |---|---|--- |140|Username or password incorrect|User and/or password is incorrect. |240|Client already exists|The provided client's username is already in use. |340|Deliveryman already exists|The provided deliveryman's username is already in use. |440|Missing authentication token|The authentication token was not sent. |441|Invalid authentication token|The authentication token provided is invalid or expired.

Bearer Token

A few routes expect a Bearer Token in an Authorization header.

You can see these routes in the routes section.

GET http://localhost:3333/v1/deliveryman/deliveries Authorization: Bearer <token>

To achieve this token you just need authenticate through the /sessions route and it will return the token key with a valid Bearer Token.

Versioning

A simple versioning was made. Just remember to set after the host the /v1/ string to your requests.

GET http://localhost:3333/v1/deliveryman/deliveries

Routes

|route|HTTP Method|params|description|auth method |:---|:---:|:---:|:---:|:---: |/clients|POST|Body with client's username and password.|Create a new client|:x: |/clients/auth|POST|Body with client's username and password.|Authenticates clients, return a Bearer Token.|:x: |/clients/deliveries|GET| - |Retrieve client's deliveries.|Bearer (Client) |/clients/deliveries|POST|Body with delivery's product_name.|Create a new delivery.|Bearer (Client) |/deliveryman|POST|Body with deliveryman's username and password.|Create a new deliveryman.|:x: |/deliveryman/auth|POST|Body with deliveryman's username and password.|Authenticates deliveryman, return a Bearer Token.|:x: |/deliveryman/deliveries|GET| - |Retrieve deliveryman's deliveries.|Bearer (Deliveryman) |/deliveries/not_delivered|GET| - |Retrieve pending deliveries.|Bearer (Deliveryman) |/deliveries/:id/set_deliveryman|PATCH| - |Set deliveryman from the token as the responsible for the delivery.|Bearer (Deliveryman) |/deliveries/:id/set_as_delivered|PATCH| - |Set delivery as delivered.|Bearer (Deliveryman)

Requests

• POST /clients

Request body:

{
  "username": "johndoe",
  "password": "123456"
}

• POST /clients/auth

Request body:

{
  "username": "johndoe",
  "password": "123456"
}

• POST /clients/deliveries

Request body:

{
  "product_name": "Lemon Ice Cream"
}

• POST /deliveryman

Request body:

{
  "username": "janedoe",
  "password": "123456"
}

• POST /deliveryman/auth

Request body:

{
  "username": "janedoe",
  "password": "123456"
}

Running the tests

Jest was the choice to test the app, to run:

$ yarn test

Or:

$ npm run test

Coverage report

You can see the coverage report inside tests/coverage. They are automatically created after the tests run.