API v1 — Overview

This document describes the endpoints, configuration, and operational notes for the v1 API in this repository.

Getting Started

• Install dependencies:

npm install

• Run the server (development using nodemon):

npm run start

• Environment variables: create a .env in the project root with at least:

PORT=8080
JWT_SECRET=<your_jwt_secret>
REFRESH_TOKEN_SECRET=<your_refresh_secret>

You can generate secure secrets in Node:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

The app loads .env from the project root (see server.js).

Publishing v1

• The v1 folder is configured as a local scoped package with name: "@putitdigital/api-v1" in v1/package.json.
• It also uses public access by default in v1/package.json via publishConfig.access.
• To publish to npm, run:

cd v1
npm publish --otp=<your-2fa-code>

• Replace <your-2fa-code> with the current code from your npm authenticator app.
• If you are using a granular token, it must allow publish and bypass 2FA.

Configuration If id is not AUTO_INCREMENT, run:

ALTER TABLE users MODIFY id INT NOT NULL AUTO_INCREMENT PRIMARY KEY;

Use a text/varchar column for phone numbers:

ALTER TABLE users MODIFY number VARCHAR(20);

• DB config is in v1/config/db.js. Update host/port/user/password/database to match your MySQL instance.
• The v1 module is also set up as a local scoped package. In server.js it is imported as:

const userRoutes = require('@putitdigital/api-v1');

This makes the v1 folder behave like a module package instead of requiring a deeper relative path.

API Endpoints (v1)

• All endpoints are mounted under /api (see server.js).

• GET /api/users

  • Description: List all users
  • Response: 200 JSON array of user objects (password field is stored hashed and not returned by the login helper)

• GET /api/users/:id

  • Description: Get a single user by id
  • Response: 200 user object, 404 if not found

• POST /api/users

  • Description: Create a new user
  • Required fields (JSON body): email, password (also provide name recommended)
  • Optional: number (phone number — must be digits only and sent as a string)
  • Validations and responses:
    • 400 — invalid JSON or missing/invalid fields (e.g., missing password or invalid number)
    • 409 — Email already exists (controller checks for existing email)
    • 201 — created: { id: <newId> }
  • Behavior: password is hashed with bcrypt before insert. The API strips any id provided by clients so the DB can auto-increment.

• PUT /api/users/:id

  • Description: Update user fields
  • Responses: 200 success, 404 not found, 500 server errors

• DELETE /api/users/:id

  • Description: Delete a user
  • Responses: 200 success, 404 not found

• POST /api/login

  • Description: Authenticate user
  • Body: { "email": "...", "password": "..." }
  • Responses:
    • 200 — success: { message: 'Login successful', user: { ...userWithoutPassword, token } }
    • 404 — user not found
    • 401 — invalid password
    • 400 — account has no password set
  • Behavior: Returns a JWT signed with JWT_SECRET and valid for 1 hour.

Scripts

• scripts/setPassword.js — generate a bcrypt hash and set the password column for a user by email. Usage:

node scripts/setPassword.js '[email protected]' 'newPassword'

Database notes & recommended schema

• Recommended column types:

  • id — INT NOT NULL AUTO_INCREMENT PRIMARY KEY
  • email — VARCHAR(255) with a UNIQUE index
  • password — VARCHAR(255) (bcrypt hashes)
  • number — VARCHAR(20) (phone numbers stored as strings)

• Useful SQL to fix schema issues:

ALTER TABLE users MODIFY id INT NOT NULL AUTO_INCREMENT PRIMARY KEY;
ALTER TABLE users MODIFY number VARCHAR(20);
ALTER TABLE users ADD UNIQUE INDEX ux_users_email (email);

Common problems & troubleshooting

• 400 Invalid JSON payload — your request body may be malformed (e.g., numeric literals with leading zeros). Always send valid JSON; send phone numbers as strings.
• Out of range value for column 'number' — change number column to VARCHAR(20).
• This account has no password set or Invalid password — verify the password column has a bcrypt hash. Use scripts/setPassword.js to set a hash.
• process.env.PORT undefined — ensure .env exists in project root. server.js loads .env explicitly from the project root.

Security notes

• Passwords are hashed using bcrypt before storing.
• JWTs are issued using JWT_SECRET and expire in 1 hour.

Where to look in the code

• Router definitions: v1/routes/userRoutes.js
• Controller logic and validation: v1/controllers/userController.js
• Model and DB access: v1/models/userModel.js
• DB config: v1/config/db.js

If you want, I can also add an OpenAPI (Swagger) spec or expand the README with example curl or Postman requests. Which would you prefer next?

cd v1 npm publish --access public --otp=123456