# Contractor Referral Settings API

This document describes the API endpoints for managing contractor referral system settings and sending email notifications to all contractors when the referral system is toggled on or off.

## Overview

The referral settings system allows administrators to:
- Toggle the referral system on/off
- Send email notifications to all contractors about status changes
- Update system messages for notifications
- Send manual notifications

## Models

### ContractorReferelSettingModel
- `isReferelSystemActive`: Boolean indicating if referral system is active
- `lastToggledBy`: Admin who last changed the setting
- `lastToggledAt`: Timestamp of last change
- `notificationSent`: Boolean indicating if notifications were sent
- `systemMessage`: Custom message for notifications

## API Endpoints

### 1. Toggle Referral System Status
**POST** `/api/referral-settings/toggle`

Toggle the referral system on/off and send email notifications to all contractors.

**Request Body:**
```json
{
  "isActive": true,
  "systemMessage": "Referral system is now active! Start referring contractors to earn points."
}
```

**Response:**
```json
{
  "success": true,
  "message": "Referral system activated successfully. Email notifications sent to 150 contractors.",
  "data": {
    "isReferelSystemActive": true,
    "lastToggledAt": "2024-01-15T10:30:00.000Z",
    "notificationSent": true,
    "contractorsNotified": 150
  }
}
```

### 2. Get Current Settings
**GET** `/api/referral-settings`

Retrieve current referral system settings.

**Response:**
```json
{
  "success": true,
  "message": "Referral system settings retrieved successfully",
  "data": {
    "isReferelSystemActive": true,
    "lastToggledAt": "2024-01-15T10:30:00.000Z",
    "systemMessage": "Referral system is now active!",
    "notificationSent": true
  }
}
```

### 3. Update System Message
**PUT** `/api/referral-settings/message`

Update the system message that will be included in notifications.

**Request Body:**
```json
{
  "systemMessage": "New message for referral notifications"
}
```

**Response:**
```json
{
  "success": true,
  "message": "System message updated successfully",
  "data": {
    "systemMessage": "New message for referral notifications",
    "lastUpdated": "2024-01-15T10:30:00.000Z"
  }
}
```

### 4. Send Manual Notification
**POST** `/api/referral-settings/notify`

Send a manual notification to all contractors about the current referral system status.

**Request Body:**
```json
{
  "customMessage": "Custom message for this notification"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Manual notification sent successfully to 150 contractors.",
  "data": {
    "contractorsNotified": 150,
    "notificationSentAt": "2024-01-15T10:30:00.000Z"
  }
}
```

## Email Notifications

When the referral system status is toggled, all contractors receive an email notification with:
- Current status (active/inactive)
- System message (if provided)
- Instructions based on current status
- Link to dashboard

The email template is located at `views/emails/referral-status-notification.ejs`.

## Authentication

All endpoints require authentication via the `verifyTokenMiddleware`. Include the JWT token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```

## Error Handling

The API includes comprehensive error handling:
- Invalid requests return appropriate HTTP status codes
- Email sending failures are logged but don't prevent the toggle operation
- Missing contractors are handled gracefully

## Usage Examples

### Toggle System On
```bash
curl -X POST http://localhost:5050/api/referral-settings/toggle \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "isActive": true,
    "systemMessage": "Referral system is now active! Start earning points by referring other contractors."
  }'
```

### Toggle System Off
```bash
curl -X POST http://localhost:5050/api/referral-settings/toggle \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "isActive": false,
    "systemMessage": "Referral system is temporarily disabled for maintenance."
  }'
```

### Send Manual Notification
```bash
curl -X POST http://localhost:5050/api/referral-settings/notify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "customMessage": "Important update: New referral rewards are now available!"
  }'
```