README.md

Users

A secure REST API for managing users, user authentication, and password reset. Includes JWT auth, protected routes, and a custom SQL migration system.

Getting Started

1. Install dependencies

npm install

2. Environment Variables

Create a .env file or set these manually:

DATABASE_URL=postgresql://username:password@localhost:5432/yourdb
JWT_SECRET=your_jwt_secret

Scripts

Command	Description
npm start	Start the API
npm run dev	Run migrations, then start with nodemon
npm run migrate	Run all pending migrations
npm run migrate:status	Show migration status
npm run migrate:rollback -- <file>	Rollback a specific migration file
npm run migrate:create -- <name>	Create new migration + rollback file

REST API Spec

Endpoint	Method	Auth Required	Description	Success	Error
/api/v1/auth	POST	No	Login	200	401, 500
/api/v1/logout	POST	No	Stateless logout	200	—
/api/v1/forgot_password	POST	No	Password reset trigger	200	404, 500
/api/v1/users	GET	Yes	List users	200	401, 403
/api/v1/users	POST	Yes	Add user	201	400, 401
/api/v1/user/:id	PUT	Yes	Update user	200	400, 404
/api/v1/user/:id	DELETE	Yes	Delete user	204	404

Public Endpoints

POST /api/v1/auth

Login with email and password.

Request:

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Response:

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "accessToken": "JWT_TOKEN",
    "user": {
      "userId": "1",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": ""
    }
  }
}

POST /api/v1/logout

Log out (token is discarded on the client).

Response:

{
  "status": "success",
  "message": "Logged out",
  "data": {}
}

POST /api/v1/forgot_password

Send password reset instructions.

Request:

{
  "email": "[email protected]"
}

Response:

{
  "status": "success",
  "message": "Password reset instructions sent",
  "data": {}
}

Protected Endpoints

Set Authorization: Bearer <token> in the header.

POST /api/v1/users

Create a new user.

Request:

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Success: 201 Created

PUT /api/v1/user/:id

Update a user.

Request:

{
  "name": "Alice Updated",
  "age": 30
}

DELETE /api/v1/user/:id

Delete a user.

Success: 204 No Content

Migrations

This project uses a custom migration system.

Folder structure:

migrations/
├── cli.js
├── migrator.js
└── files/
    ├── 20250710120000_initial_schema.sql
    └── 20250710120000_initial_schema_rollback.sql

Commands

Run migrations:

npm run migrate

Check migration status:

npm run migrate:status

Create new migration:

npm run migrate:create -- add_column_to_users

Rollback migration:

npm run migrate:rollback -- 20250710120000_initial_schema.sql

Notes

• All protected endpoints require a valid JWT in the Authorization header.
• All migrations are transactional and include rollback support.
• nodemon is used in npm run dev to auto-restart the server.

---

Generated using Claude Sonnet 4 on 2025-07-10