# Member Management API Documentation

## Overview
Complete API documentation for Member Management operations including POST (Create), GET (Read), PUT (Update), and DELETE (Remove) operations.

---

## Base URL
```
http://localhost:5000/api/v1
```

## Authentication
All endpoints require authentication header:
```
Authorization: Bearer <token>
```

---

# 📋 PRIMARY MEMBER OPERATIONS

## 1. Register New Primary Member
**POST** `/members/register`

### Authorization
- admin, front_desk

### Request Body
```json
{
  "memberId": "M-001",
  "membershipTypeId": "objectId_of_membership_type",
  "firstName": "John",
  "lastName": "Doe",
  "fatherName": "Michael Doe",
  "cnic": "12345-6789012-3",
  "dateOfBirth": "1980-05-15",
  "gender": "Male",
  "phonePrimary": "03001234567",
  "phoneSecondary": "03009876543",
  "email": "john.doe@example.com",
  "address": "123 Main Street, City, Country",
  "emergencyContactName": "Jane Doe",
  "emergencyContactPhone": "03001112222",
  "membershipStartDate": "2026-02-12",
  "membershipExpiryDate": "2027-02-12",
  "password": "securePassword123"
}
```

### Response (201 Created)
```json
{
  "success": true,
  "message": "Member registered successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "member": {
      "memberId": "M-001",
      "firstName": "John",
      "lastName": "Doe",
      "phonePrimary": "03001234567",
      "email": "john.doe@example.com",
      "status": "Active",
      "membershipStartDate": "2026-02-12T00:00:00.000Z",
      "membershipExpiryDate": "2027-02-12T00:00:00.000Z",
      "createdAt": "2026-02-12T08:14:18.203Z"
    }
  }
}
```

---

## 2. Get All Members (Paginated)
**GET** `/members`

### Authorization
- admin, front_desk, accountant

### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page | number | No | Page number (default: 1) |
| limit | number | No | Records per page (default: 20) |
| search | string | No | Search by memberId, firstName, lastName, phone, cnic |
| status | string | No | Filter by status (Active, Suspended, Inactive, Expired) |
| membershipType | string | No | Filter by membership type code |

### Example Request
```
GET /members?page=1&limit=20&status=Active
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Members retrieved successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": [
    {
      "_id": "698b12a557613312120d8ac6",
      "memberId": "M-178",
      "code": "HON - 178",
      "numericCode": "178",
      "isPrimaryMember": true,
      "primaryMember": null,
      "relationToPrimary": "Self",
      "membershipType": "Honorary",
      "membershipStartDate": "2026-02-07T00:00:00.000Z",
      "membershipExpiryDate": null,
      "firstName": "MRS.SABA KALWAR",
      "lastName": null,
      "fatherName": null,
      "cnic": "45501-1641080-4",
      "dateOfBirth": "1987-01-18T00:00:00.000Z",
      "gender": "Female",
      "phonePrimary": null,
      "phoneSecondary": null,
      "email": null,
      "address": "REVENUE EMPLOYEES CO-OPERATIVE HOUSING SOCIETY, HOUSE NO. 1, QASIMABAD,",
      "emergencyContactName": null,
      "emergencyContactPhone": null,
      "emergencyContactRelation": null,
      "photoUrl": null,
      "status": "Active",
      "parentId": null,
      "memberDated": "2026-02-07T00:00:00.000Z",
      "notes": "Terminated as per Article 7(e) of Hyderabad Gymkhana Bylaws.",
      "createdBy": null,
      "createdAt": "2026-02-10T11:12:37.890Z",
      "updatedAt": "2026-02-10T11:12:37.890Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "pages": 8
  }
}
```

---

## 3. Search Members
**GET** `/members/search`

### Authorization
- All authenticated users

### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 2 characters) |

### Example Request
```
GET /members/search?q=John
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Search results",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": [
    {
      "memberId": "M-001",
      "firstName": "John",
      "lastName": "Doe",
      "phonePrimary": "03001234567",
      "email": "john.doe@example.com",
      "status": "Active",
      "typeName": "Regular",
      "currentBalance": 5000.00,
      "accountStatus": "Normal"
    }
  ]
}
```

---

## 4. Get Member by ID (with Family Members)
**GET** `/members/:memberId`

### Authorization
- All authenticated users

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Member ID (e.g., M-001) |

### Example Request
```
GET /members/M-001
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Member retrieved successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "member": {
      "_id": "698b12a557613312120d8ac6",
      "memberId": "M-178",
      "code": "HON - 178",
      "numericCode": "178",
      "isPrimaryMember": true,
      "primaryMember": null,
      "relationToPrimary": "Self",
      "membershipType": "ObjectId",
      "membershipStartDate": "2026-02-07T00:00:00.000Z",
      "membershipExpiryDate": null,
      "firstName": "MRS.SABA KALWAR",
      "lastName": null,
      "fatherName": null,
      "cnic": "45501-1641080-4",
      "dateOfBirth": "1987-01-18T00:00:00.000Z",
      "gender": "Female",
      "phonePrimary": null,
      "phoneSecondary": null,
      "email": null,
      "address": "Address details",
      "emergencyContactName": null,
      "emergencyContactPhone": null,
      "emergencyContactRelation": null,
      "photoUrl": null,
      "status": "Active",
      "currentBalance": 0,
      "creditLimit": 10000,
      "accountStatus": "Normal",
      "lastTransactionDate": null,
      "createdAt": "2026-02-10T11:12:37.890Z",
      "updatedAt": "2026-02-10T11:12:37.890Z"
    },
    "familyMembers": []
  }
}
```

---

## 5. Update Member Profile
**PUT** `/members/:memberId/profile`

### Authorization
- admin, front_desk

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Member ID (e.g., M-001) |

### Request Body (all optional)
```json
{
  "firstName": "John Updated",
  "lastName": "Doe Updated",
  "fatherName": "Michael Doe",
  "cnic": "12345-6789012-3",
  "dateOfBirth": "1980-05-15",
  "gender": "Male",
  "membershipType": "membershipTypeId",
  "membershipStartDate": "2026-02-12",
  "membershipExpiryDate": "2027-02-12",
  "password": "newPassword123",
  "phonePrimary": "03001234567",
  "phoneSecondary": "03009876543",
  "email": "newemail@example.com",
  "address": "Updated Address",
  "emergencyContactName": "Jane Doe",
  "emergencyContactPhone": "03001112222"
}
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Member profile updated successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "memberId": "M-001",
    "phonePrimary": "03001234567",
    "phoneSecondary": "03009876543",
    "email": "newemail@example.com",
    "address": "Updated Address",
    "emergencyContactName": "Jane Doe",
    "emergencyContactPhone": "03001112222",
    "updatedAt": "2026-02-12T08:30:00.000Z"
  }
}
```

---

## 6. Update Member Status
**PUT** `/members/:memberId/status`

### Authorization
- admin, front_desk

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Member ID (e.g., M-001) |

### Request Body
```json
{
  "status": "Suspended"
}
```

### Valid Status Values
- Active
- Suspended
- Inactive
- Expired
- Pending

### Response (200 OK)
```json
{
  "success": true,
  "message": "Member status updated successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "memberId": "M-001",
    "firstName": "John",
    "lastName": "Doe",
    "status": "Suspended"
  }
}
```

---

## 7. Delete Primary Member (with all Family Members)
**DELETE** `/members/:memberId`

### Authorization
- admin only

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Member ID (e.g., M-001) |

### Example Request
```
DELETE /members/M-001
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Member and all family members deleted successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "memberId": "M-001",
    "familyMembersDeleted": 3
  }
}
```

### Error Response (404)
```json
{
  "success": false,
  "message": "Member not found",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

---

# 👨‍👩‍👧 FAMILY MEMBER OPERATIONS

## 8. Add Family Member
**POST** `/members/:memberId/family`

### Authorization
- admin, front_desk

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Primary Member ID |

### Request Body
```json
{
  "firstName": "Jane",
  "lastName": "Doe",
  "relationToPrimary": "Wife",
  "dateOfBirth": "1982-08-20",
  "gender": "Female",
  "cnic": "87654-3210987-6",
  "password": "familyPassword123"
}
```

### Valid Relations
- Self, Wife, Spouse, Son, Daughter, Father, Mother, Brother, Sister, Other

### Response (201 Created)
```json
{
  "success": true,
  "message": "Family member added successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": {
    "familyMember": {
      "memberId": "M-001-W-1",
      "firstName": "Jane",
      "lastName": "Doe",
      "relationToPrimary": "Wife",
      "status": "Active",
      "createdAt": "2026-02-12T08:14:18.203Z"
    }
  }
}
```

---

## 9. Get Family Members
**GET** `/members/:memberId/family`

### Authorization
- All authenticated users

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Primary Member ID |

### Example Request
```
GET /members/M-001/family
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Family members retrieved successfully",
  "timestamp": "2026-02-12T08:14:18.203Z",
  "data": [
    {
      "memberId": "M-001-W-1",
      "firstName": "Jane",
      "lastName": "Doe",
      "relationToPrimary": "Wife",
      "dateOfBirth": "1982-08-20",
      "gender": "Female",
      "cnic": "87654-3210987-6",
      "status": "Active",
      "createdAt": "2026-02-12T08:14:18.203Z"
    }
  ]
}
```

---

## 10. Remove Family Member
**DELETE** `/members/:memberId/family/:familyMemberId`

### Authorization
- admin, front_desk

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| memberId | string | Yes | Primary Member ID |
| familyMemberId | string | Yes | Family Member ID |

### Example Request
```
DELETE /members/M-001/family/M-001-W-1
```

### Response (200 OK)
```json
{
  "success": true,
  "message": "Family member removed successfully",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

---

# 🔒 Error Responses

## Common Error Status Codes

### 400 Bad Request
```json
{
  "success": false,
  "message": "Invalid request body or validation failed",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

### 404 Not Found
```json
{
  "success": false,
  "message": "Member not found",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

### 409 Conflict
```json
{
  "success": false,
  "message": "Member ID already exists or CNIC already registered",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

### 401 Unauthorized
```json
{
  "success": false,
  "message": "Authentication required",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

### 403 Forbidden
```json
{
  "success": false,
  "message": "You don't have permission to perform this action",
  "timestamp": "2026-02-12T08:14:18.203Z"
}
```

---

# 📊 API Summary Table

| Operation | Method | Endpoint | Auth | Roles |
|-----------|--------|----------|------|-------|
| Register Member | POST | `/members/register` | Yes | admin, front_desk |
| Search Members | GET | `/members/search` | Yes | All |
| Get All Members | GET | `/members` | Yes | admin, front_desk, accountant |
| Get Member by ID | GET | `/members/:memberId` | Yes | All |
| Update Profile | PUT | `/members/:memberId/profile` | Yes | admin, front_desk |
| Update Status | PUT | `/members/:memberId/status` | Yes | admin, front_desk |
| Delete Member | DELETE | `/members/:memberId` | Yes | admin |
| Add Family | POST | `/members/:memberId/family` | Yes | admin, front_desk |
| Get Family | GET | `/members/:memberId/family` | Yes | All |
| Remove Family | DELETE | `/members/:memberId/family/:familyMemberId` | Yes | admin, front_desk |

---

# 💡 Usage Examples

## Example 1: Register a New Member
```bash
curl -X POST http://localhost:5000/api/v1/members/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memberId": "M-001",
    "membershipTypeId": "objectId",
    "firstName": "Ali",
    "lastName": "Khan",
    "cnic": "12345-6789012-3",
    "gender": "Male",
    "phonePrimary": "03001234567",
    "email": "ali@example.com",
    "membershipStartDate": "2026-02-12",
    "password": "secure123"
  }'
```

## Example 2: Get All Active Members
```bash
curl -X GET "http://localhost:5000/api/v1/members?status=Active&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Example 3: Update Member Status
```bash
curl -X PUT http://localhost:5000/api/v1/members/M-001/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Suspended"}'
```

## Example 4: Add Family Member
```bash
curl -X POST http://localhost:5000/api/v1/members/M-001/family \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Fatima",
    "lastName": "Khan",
    "relationToPrimary": "Wife",
    "dateOfBirth": "1985-06-15",
    "gender": "Female",
    "password": "secure123"
  }'
```

## Example 5: Delete a Member
```bash
curl -X DELETE http://localhost:5000/api/v1/members/M-001 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# 🔐 Security Notes

1. **Authentication**: All endpoints require valid JWT token in Authorization header
2. **Authorization**: Different roles have different access levels
3. **Data Validation**: All input data is validated before processing
4. **Password Hashing**: Passwords are hashed using bcrypt before storage
5. **Rate Limiting**: Implement rate limiting in production
6. **CORS**: Configure CORS policies appropriately
7. **Input Sanitization**: All inputs are sanitized to prevent injection attacks

---

# 📝 Notes

- Member IDs must be unique
- CNIC numbers must be unique (if provided)
- Primary members can have multiple family members
- Deleting a primary member automatically deletes all family members
- Family members inherit membership dates from their primary member
- Account records are automatically created for each member