From 7acb8e220f9b5ef256dc81a46e049d110b4e565f Mon Sep 17 00:00:00 2001 From: Esdras Santos Date: Thu, 12 Nov 2026 18:38:12 +0000 Subject: [PATCH] docs: add README, MIT license, env example and build CI --- .env.example | 9 +++ .github/workflows/ci.yml | 23 +++++++ LICENSE | 21 ++++++ README.md | 144 ++++++++++++++++++--------------------- 4 files changed, 121 insertions(+), 76 deletions(-) create mode 100644 .env.example create mode 100644 .github/workflows/ci.yml create mode 100644 LICENSE diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..afcc0f5 --- /dev/null +++ b/.env.example @@ -0,0 +1,9 @@ +DB_HOST=localhost +DB_PORT=5432 +DB_USER=fleet +DB_PASSWORD= +DB_NAME=fleet +JWT_SECRET= +JWT_EXPIRES_IN=1h +NODE_ENV=development +PORT=3000 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8bcb549 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,23 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + build: + name: build + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + - run: npm ci + - run: npm run build diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f8ef04f --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Esdras Santos + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 8f0f65f..5fc80e6 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,90 @@ -

- Nest Logo -

- -[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 -[circleci-url]: https://circleci.com/gh/nestjs/nest - -

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Discord -Backers on Open Collective -Sponsors on Open Collective - Donate us - Support us - Follow us on Twitter -

- - -## Description - -[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. - -## Project setup +# fleet-api -```bash -$ npm install -``` +A NestJS and TypeORM backend for a fleet management app. Right now it handles accounts: sign-up, login with email and password, and routes that only answer to a valid JWT. -## Compile and run the project +> [!NOTE] +> This is an early-stage personal project. Authentication and users work; the fleet side of the API doesn't exist yet. -```bash -# development -$ npm run start +## What's in it -# watch mode -$ npm run start:dev +- **Sign-up** validates the body with class-validator (strong password rules, max 128 characters) and rejects a duplicate email with `409 Conflict`. +- **Passwords** are hashed with Argon2id and never leave the database: the `passwordHash` column is excluded from queries by default. +- **Login** goes through a Passport local strategy and returns a signed JWT. Protected routes use a Passport JWT strategy behind a `JwtGuard`. +- **Errors** go through two global filters, one for HTTP exceptions and one that turns a PostgreSQL unique violation (`23505`) into a `409` instead of a `500`. +- **Config** comes from environment variables through `@nestjs/config`, and the app refuses to start without `JWT_SECRET` and `JWT_EXPIRES_IN`. -# production mode -$ npm run start:prod -``` +## Tech stack -## Run tests +| Area | Choice | +| --- | --- | +| Framework | NestJS 11, TypeScript | +| Database | PostgreSQL 18 through TypeORM | +| Auth | Passport (local and JWT strategies), `@nestjs/jwt`, Argon2 | +| Validation | class-validator, global `ValidationPipe` with whitelisting | +| Local infra | Docker Compose for PostgreSQL | -```bash -# unit tests -$ npm run test +## Getting started -# e2e tests -$ npm run test:e2e +You'll need Node.js 22 or newer and Docker. -# test coverage -$ npm run test:cov +```bash +git clone https://github.com/esdrassantos06/fleet-api.git +cd fleet-api +npm install +cp .env.example .env # then set DB_PASSWORD and JWT_SECRET +docker compose up -d # starts PostgreSQL on port 5432 +npm run start:dev ``` -## Deployment - -When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information. +The API listens on `http://localhost:3000` (or `PORT` if you set it). Outside production, TypeORM creates the `users` table on startup through `synchronize`; in production it's turned off. -If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps: +## Endpoints -```bash -$ npm install -g @nestjs/mau -$ mau deploy -``` +| Method | Path | Auth | What it does | +| --- | --- | --- | --- | +| `POST` | `/auth/register` | none | Creates a user from `name`, `email` and `password` and returns it without the hash | +| `POST` | `/auth/login` | email and password | Returns `{ "access_token": "..." }` | +| `GET` | `/auth/profile` | Bearer token | Returns the user id and email from the token | +| `GET` | `/users` | Bearer token | Lists users | -With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure. +A quick round trip: -## Resources - -Check out a few resources that may come in handy when working with NestJS: +```bash +curl -X POST http://localhost:3000/auth/register \ + -H "Content-Type: application/json" \ + -d '{"name":"Ana","email":"ana@example.com","password":"Secret123"}' -- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework. -- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy). -- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/). -- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks. -- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com). -- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com). -- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs). -- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com). +curl -X POST http://localhost:3000/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"ana@example.com","password":"Secret123"}' -## Support +curl http://localhost:3000/auth/profile -H "Authorization: Bearer " +``` -Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). +## Environment variables -## Stay in touch +| Variable | Required | Default | Notes | +| --- | --- | --- | --- | +| `DB_HOST` | no | `localhost` | | +| `DB_PORT` | no | `5432` | | +| `DB_USER` | yes | | Also used by Docker Compose | +| `DB_PASSWORD` | yes | | Also used by Docker Compose | +| `DB_NAME` | yes | | Also used by Docker Compose | +| `JWT_SECRET` | yes | | Use a long random string | +| `JWT_EXPIRES_IN` | yes | | For example `1h` or `15m` | +| `NODE_ENV` | no | | Set to `production` to turn off `synchronize` | +| `PORT` | no | `3000` | | -- Author - [Kamil Myƛliwiec](https://twitter.com/kammysliwiec) -- Website - [https://nestjs.com](https://nestjs.com/) -- Twitter - [@nestframework](https://twitter.com/nestframework) +## Scripts -## License +```bash +npm run start:dev # watch mode +npm run build # compile to dist/ +npm run start:prod # run the compiled build +npm run lint # ESLint with --fix +npm run test # unit tests +npm run test:e2e # end-to-end tests +``` -Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE). +> [!WARNING] +> The Jest suites don't run yet. `@nestjs/typeorm` 11 ships as ESM and uses `import.meta`, which the current Jest and ts-jest setup can't load, and the specs import with `src/...` paths that Jest doesn't map. CI only builds the project until that's fixed.