Zumri-Backend/Documentation/User-API.md

# User API

#### Create New Customer Account

Creates a new customer account and sends an email verification link.

The account is initially created with:

```text
accountType = customer
accountStatus = PENDING_VERIFICATION
emailVerifiedAt = null
```

**Endpoint**

```text
POST: http://localhost:3070/api/user
```

**Request Body**

```json
{
  "firstName": "Isuru",
  "lastName": "Bimsara",
  "email": "ibimsara00@gmail.com",
  "password": "Hello@12346"
}
```

**Response**

```json
{
  "success": true,
  "message": "User Created Successfully",
  "data": {
    "id": "usr_ei6i4n49",
    "firstName": "Isuru",
    "lastName": "Bimsara",
    "email": "ibimsara00@gmail.com",
    "accountType": "customer"
  }
}
```

After registration, the user receives an email containing a verification link.
```

#### Verify Email

Verifies the customer's email using the raw verification token received by email.

The backend hashes the received token and compares the resulting hash with the `tokenHash` stored in the `email_verifications` table.

The token must:

```text
Exist in the database
Not have been used
Not have expired
```

**Endpoint**

```text
POST: http://localhost:3070/api/user/verify-email
```

**Request Body**

```json
{
  "token": "RAW_VERIFICATION_TOKEN_FROM_EMAIL"
}
```

**Successful Response**

```json
{
  "success": true,
  "message": "Email verified successfully. Your account is now active."
}
```

After successful verification, the user record changes from:

```text
accountStatus = PENDING_VERIFICATION
emailVerifiedAt = NULL
```

to:

```text
accountStatus = ACTIVE
emailVerifiedAt = <current date and time>
```

The verification record is also updated:

```text
usedAt = <current date and time>
```

This prevents the same verification token from being successfully used again.

---


#### Get All Users

**Endpoint**

```
GET: http://localhost:3070/api/user
```

**Respond**

```json
{
  "success": true,
  "data": [
    {
      "id": "usr_b00045f7-aafb-482a-8587-d28beb5195ec",
      "firstName": "Kalana",
      "lastName": "Jayasekara",
      "email": "kalanamanupiya32@gmail.com",
      "accountType": "admin",
      "role": "Manager",
      "department": "Operations",
      "createdAt": "2026-02-14T19:14:25.000Z",
      "updatedAt": "2026-02-14T19:14:25.000Z"
    },
    {
      "id": "usr_763107d9-b56f-4b81-9d86-1889f98a6e6c",
      "firstName": "Kalana",
      "lastName": "Manupiya",
      "email": "kalanajayasekara@niolla.lk",
      "accountType": "admin",
      "role": "System Developer",
      "department": "IT Department",
      "createdAt": "2026-02-12T19:32:15.000Z",
      "updatedAt": "2026-02-12T19:32:15.000Z"
    },
    {
      "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
      "firstName": "Jhon",
      "lastName": "Doe",
      "email": "sathira@niolla.lk",
      "accountType": "admin",
      "role": "System Developer",
      "department": "IT Department",
      "createdAt": "2026-02-12T19:24:04.000Z",
      "updatedAt": "2026-02-12T19:24:04.000Z"
    }
  ],
  "pagination": {
    "totalUsers": 3,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20
  }
}
```

This API uses Pagination:

```
GET /user?page=1
GET /user?page=2
GET /user?page=3
```

#### Get User by ID

**Endpoint**

```
GET: http://localhost:3070/api/user/:id
```

Ex: http://localhost:3070/api/user/usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4

**Response**

```json
{
  "success": true,
  "data": {
    "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "firstName": "Sathira",
    "lastName": "Sri Sathsara",
    "email": "sathira@niolla.lk",
    "accountType": "admin",
    "role": "System Developer",
    "department": "IT Department",
    "createdAt": "2026-02-12T19:24:04.000Z",
    "updatedAt": "2026-02-14T21:33:19.751Z",
    "profile": {
      "profile_id": "prof_a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
      "theme": "light",
      "notificationsEnabled": true,
      "profilePicture_id": "up_xyz789",
      "backgroundImage_id": "up_abc123",
      "dob": "1995-03-15T00:00:00.000Z",
      "phone_number": "+1 234-567-8900",
      "createdAt": "2026-02-12T19:24:04.000Z",
      "updatedAt": "2026-02-12T19:24:04.000Z"
    }
  }
}
```

#### Update User

**Endpoint**

```
PATCH: http://localhost:3070/api/user/:id
```

Ex: http://localhost:3070/api/user/usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4

**Request Body**

Can send single field or multiple fields. The following fields can be updated:

```json
{
  "firstName": "Sathira", 
  "lastName": "Sri Sathsara", 
  "email": "sathira@niolla.lk", 
  "role": "System Developer", 
  "roleID": "role_123",
  "accountType": "admin", 
  "department": "IT Department",
  "theme": "dark",
  "notificationsEnabled": false,
  "profilePicture_id": "up_profile_123",
  "backgroundImage_id": "up_background_456",
  "dob": "1995-03-15",
  "phone_number": "+1 234-567-8900"
}
```

**Response**

```json
{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "firstName": "Sathira",
    "lastName": "Sri Sathsara",
    "email": "sathira@niolla.lk",
    "accountType": "admin",
    "role": "System Developer",
    "department": "IT Department",
    "profile": {
      "theme": "dark",
      "notificationsEnabled": false,
      "profilePicture_id": "up_profile_123",
      "backgroundImage_id": "up_background_456",
      "dob": "1995-03-15T00:00:00.000Z",
      "phone_number": "+1 234-567-8900"
    }
  }
}
```

#### Delete User

**Endpoint**

```
DELETE: http://localhost:3070/api/user/:id
```

Ex: http://localhost:3070/api/user/usr_b00045f7-aafb-482a-8587-d28beb5195ec

**Respond**

```json
{
  "success": true,
  "message": "User deleted successfully"
}
```