users-api

Users API

• Base Path: /api/v1/users
• Auth: required (Bearer token for all endpoints)

User Model

• username: string (unique; generated zishId)
• email: string (unique)
• avatar: string (optional; public URL)
• address: object (optional)
• hypervergeTransactionIds: string[] (newest first; auto-seeded on create)
• idNumber: string (optional; HyperVerge-computed unique identifier)
• age: number (optional; HyperVerge-reported age in years)
• verified: boolean (defaults false; reset on verification reset)
• createdAt / updatedAt: string (ISO)

zishId generation

• On user creation, the server generates a username (zishId) by combining a random First + Last name from username.xlsx and a 2-digit number, e.g., GoldenEagle42.
• Ensures uniqueness by retrying different pairs/numbers.
• Data source: Excel file at USERNAME_FILE_PATH (defaults to src/resources/username.xlsx).

Signup flow

• Frontend authenticates the user with the Auth service first (gets a Bearer token).
• Frontend then calls our API POST /api/v1/users with that Bearer token and provides the user's email in the body.
• Server generates the username (zishId) — clients must not provide or set it.
• On first creation, server seeds hypervergeTransactionIds[0] with <extUserId>_&lt;timestamp&gt;.

Environment

• USERNAME_FILE_PATH: Path to the Excel file containing first and last names in the first two columns of the first sheet.

Create User

• Method: POST
• Path: /api/v1/users
• Auth: Bearer required
• Body:
  • email: string (required)
  • address: object (optional)
• The username is ignored if provided; server will generate one.
• Response 201: Full user document with generated username.
• Errors:
  • 400: { "error": "email is required" }
  • 409: { "error": "Duplicate username or email" }
  • 500: { "error": "Failed to create user" }

Update Current User

• Method: PATCH
• Path: /api/v1/users/me
• Auth: Bearer required
• Body:
  • username: string (optional)
  • email: string (optional)
  • avatar: string (optional; URL to image)
• Behavior:
  • Uses the authenticated user from the Authorization header (no :id).
  • Updates only provided fields; at least one is required.
  • Recommended: use this endpoint for any changes after initial signup. The create endpoint is for first‑time provisioning only.
• Response 200: Updated user document.
• Errors:
  • 400: { "error": "No valid fields to update" }
  • 401: { "error": "UNAUTHORIZED" }
  • 404: { "error": "User not found" }
  • 409: { "error": "Duplicate username or email" }
  • 500: { "error": "Failed to update user" }

Get Profile

• Method: GET
• Path: /api/v1/users/me
• Auth: Bearer required
• Response 200: Full user document for the authenticated user.
• Errors:
  • 401: { "error": "UNAUTHORIZED" }
  • 404: { "error": "User not found" }
  • 500: { "error": "Failed to fetch profile" }

Verification

• HyperVerge transaction id format: <extUserId>_&lt;timestamp&gt;.
• Stored in user.hypervergeTransactionIds with the newest id at index 0.

Reset Verification

• Method: POST
• Path: /api/v1/users/reset-verification
• Auth: Bearer required
• Behavior: Unshifts a new transaction id to hypervergeTransactionIds and sets verified=false.
• Response 200: \{ "verificationId": string, "hypervergeTransactionIds": string[] \}
• Errors: 401 UNAUTHORIZED, 404 User not found

Get Current Verification ID

• Method: GET
• Path: /api/v1/users/verification-id
• Auth: Bearer required
• Behavior: Returns the latest transaction id (index 0). If none exists (legacy users), generates one and returns it.
• Response 200: \{ "verificationId": string \}
• Errors: 401 UNAUTHORIZED, 404 User not found

Example

Request: POST /api/v1/users

{ "email": "alice@example.com" }

Response:
{
  "_id": "0192059b-4d7f-7f65-b7d0-3a9ad1d5a1de",
  "username": "SilverFox57",
  "email": "alice@example.com",
  "createdAt": "2025-09-01T10:00:00.000Z",
  "updatedAt": "2025-09-01T10:00:00.000Z"
}

Auth details

• Middleware validates the Bearer token, loads the user, and exposes req.user with the user id and email.