# Site Settings API Documentation

## Overview
Complete API for managing website configuration: contact information, social links, content sections, and hero banners.

---

## Data Models

### SiteSettings
```json
{
  "id": "uuid",
  "email": "string",
  "aboutUsText": "string",
  "privacyPolicy": "string",
  "termsAndCondition": "string",
  "createdAt": "DateTime",
  "updatedAt": "DateTime",
  "mobileNumbers": "MobileNumber[]",
  "whatsappNumbers": "WhatsAppNumber[]",
  "socialLinks": "SocialLink[]",
  "heroBanner": "HeroBanner[]"
}
```

### MobileNumber / WhatsAppNumber
```json
{
  "id": "uuid",
  "number": "string",
  "createdAt": "DateTime"
}
```

### SocialLink
```json
{
  "id": "uuid",
  "platform": "string",
  "url": "string",
  "createdAt": "DateTime",
  "updatedAt": "DateTime"
}
```

### HeroBanner
```json
{
  "id": "uuid",
  "imageUrl": "string",
  "title": "string",
  "subtitle": "string",
  "buttonText": "string",
  "buttonLink": "string",
  "displayOrder": "number",
  "isActive": "boolean",
  "createdAt": "DateTime",
  "updatedAt": "DateTime"
}
```

---

## API Endpoints & Examples

### 1. Get All Site Settings
**GET** `/api/site-settings`

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Site settings retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "contact@example.com",
    "aboutUsText": "We are a leading company...",
    "privacyPolicy": "Your privacy is important...",
    "termsAndCondition": "These terms govern...",
    "createdAt": "2026-05-26T10:00:00Z",
    "updatedAt": "2026-05-26T15:30:00Z",
    "mobileNumbers": [
      { "id": "uuid", "number": "+1-555-123-4567", "createdAt": "2026-05-26T10:00:00Z" }
    ],
    "whatsappNumbers": [
      { "id": "uuid", "number": "+1-555-987-6543", "createdAt": "2026-05-26T10:00:00Z" }
    ],
    "socialLinks": [
      { "id": "uuid", "platform": "facebook", "url": "https://facebook.com/example", "createdAt": "2026-05-26T10:00:00Z", "updatedAt": "2026-05-26T10:00:00Z" }
    ],
    "heroBanner": []
  }
}
```

---

### 2. Update Main Site Settings
**PATCH** `/api/site-settings`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "email": "newemail@example.com",
  "aboutUsText": "Updated company description...",
  "privacyPolicy": "Updated privacy policy...",
  "termsAndCondition": "Updated terms..."
}
```

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Site settings updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "newemail@example.com",
    "aboutUsText": "Updated company description...",
    "privacyPolicy": "Updated privacy policy...",
    "termsAndCondition": "Updated terms...",
    "createdAt": "2026-05-26T10:00:00Z",
    "updatedAt": "2026-05-26T16:00:00Z",
    "mobileNumbers": [],
    "whatsappNumbers": [],
    "socialLinks": [],
    "heroBanner": []
  }
}
```

---

### 3. Add Mobile Number
**POST** `/api/site-settings/mobile-numbers`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "number": "+1-555-123-4567"
}
```

**Response:**
```json
{
  "statusCode": 201,
  "success": true,
  "message": "Mobile number added successfully",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "number": "+1-555-123-4567",
    "siteSettingsId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-05-26T16:05:00Z"
  }
}
```

---

### 4. Remove Mobile Number
**DELETE** `/api/site-settings/mobile-numbers/{id}`

**Auth:** ADMIN

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Mobile number removed successfully",
  "data": null
}
```

---

### 5. Add WhatsApp Number
**POST** `/api/site-settings/whatsapp-numbers`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "number": "+1-555-987-6543"
}
```

**Response:**
```json
{
  "statusCode": 201,
  "success": true,
  "message": "WhatsApp number added successfully",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440001",
    "number": "+1-555-987-6543",
    "siteSettingsId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-05-26T16:10:00Z"
  }
}
```

---

### 6. Remove WhatsApp Number
**DELETE** `/api/site-settings/whatsapp-numbers/{id}`

**Auth:** ADMIN

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "WhatsApp number removed successfully",
  "data": null
}
```

---

### 7. Add Social Link
**POST** `/api/site-settings/social-links`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "platform": "facebook",
  "url": "https://facebook.com/example"
}
```

**Response:**
```json
{
  "statusCode": 201,
  "success": true,
  "message": "Social link added successfully",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440001",
    "platform": "facebook",
    "url": "https://facebook.com/example",
    "siteSettingsId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-05-26T16:15:00Z",
    "updatedAt": "2026-05-26T16:15:00Z"
  }
}
```

---

### 8. Remove Social Link
**DELETE** `/api/site-settings/social-links/{id}`

**Auth:** ADMIN

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Social link removed successfully",
  "data": null
}
```

---

## Hero Banners Endpoints

### 9. Get All Hero Banners
**GET** `/api/site-settings/hero-banners/all`

**Auth:** ADMIN

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "All hero banners retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "imageUrl": "hero-banner/banner-1715069300000-123456789.jpg",
      "title": "Welcome to Our Website",
      "subtitle": "Discover amazing products and services",
      "buttonText": "Learn More",
      "buttonLink": "https://example.com/learn",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "2026-05-26T10:00:00Z",
      "updatedAt": "2026-05-26T10:00:00Z"
    }
  ]
}
```

---

### 10. Get Active Hero Banners (Public)
**GET** `/api/site-settings/hero-banners/active`

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Active hero banners retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "imageUrl": "hero-banner/banner-1715069300000-123456789.jpg",
      "title": "Welcome to Our Website",
      "subtitle": "Discover amazing products",
      "buttonText": "Get Started",
      "buttonLink": "https://example.com/start",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "2026-05-26T10:00:00Z",
      "updatedAt": "2026-05-26T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "imageUrl": "hero-banner/banner-1715069400000-987654321.jpg",
      "title": "Special Offer",
      "subtitle": "50% off this week",
      "buttonText": "Shop Now",
      "buttonLink": "https://example.com/shop",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2026-05-26T11:00:00Z",
      "updatedAt": "2026-05-26T11:00:00Z"
    }
  ]
}
```

---

### 11. Create Hero Banner
**POST** `/api/site-settings/hero-banners`

**Auth:** ADMIN | **Content-Type:** `multipart/form-data`

**Request:**
```bash
curl -X POST http://localhost:5000/api/site-settings/hero-banners \
  -H "Authorization: Bearer TOKEN" \
  -F "image=@banner.jpg" \
  -F "title=Welcome" \
  -F "subtitle=Amazing products" \
  -F "buttonText=Get Started" \
  -F "buttonLink=https://example.com" \
  -F "displayOrder=0" \
  -F "isActive=true"
```

**Response:**
```json
{
  "statusCode": 201,
  "success": true,
  "message": "Hero banner created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "imageUrl": "hero-banner/banner-1715069300000-123456789.jpg",
    "title": "Welcome",
    "subtitle": "Amazing products",
    "buttonText": "Get Started",
    "buttonLink": "https://example.com",
    "displayOrder": 0,
    "isActive": true,
    "createdAt": "2026-05-26T10:15:00Z",
    "updatedAt": "2026-05-26T10:15:00Z"
  }
}
```

---

### 12. Update Hero Banner
**PATCH** `/api/site-settings/hero-banners/{id}`

**Auth:** ADMIN | **Content-Type:** `multipart/form-data`

**Request:**
```bash
curl -X PATCH http://localhost:5000/api/site-settings/hero-banners/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer TOKEN" \
  -F "image=@new-banner.jpg" \
  -F "title=Updated Title" \
  -F "subtitle=Updated Subtitle"
```

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Hero banner updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "imageUrl": "hero-banner/banner-1715070000000-111111111.jpg",
    "title": "Updated Title",
    "subtitle": "Updated Subtitle",
    "buttonText": "Get Started",
    "buttonLink": "https://example.com",
    "displayOrder": 0,
    "isActive": true,
    "createdAt": "2026-05-26T10:15:00Z",
    "updatedAt": "2026-05-26T10:45:00Z"
  }
}
```

---

### 13. Delete Hero Banner
**DELETE** `/api/site-settings/hero-banners/{id}`

**Auth:** ADMIN

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Hero banner removed successfully",
  "data": null
}
```

---

### 14. Reorder Hero Banners
**POST** `/api/site-settings/hero-banners/reorder`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "bannerIds": [
    "550e8400-e29b-41d4-a716-446655440002",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}
```

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Hero banners reordered successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "displayOrder": 0,
      "isActive": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "displayOrder": 1,
      "isActive": true
    }
  ]
}
```

---

### 15. Toggle Hero Banner Status
**PATCH** `/api/site-settings/hero-banners/{id}/toggle`

**Auth:** ADMIN | **Content-Type:** `application/json`

**Request:**
```json
{
  "isActive": false
}
```

**Response:**
```json
{
  "statusCode": 200,
  "success": true,
  "message": "Hero banner deactivated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "imageUrl": "hero-banner/banner-1715069300000-123456789.jpg",
    "title": "Welcome",
    "displayOrder": 0,
    "isActive": false,
    "updatedAt": "2026-05-26T11:10:00Z"
  }
}
```

---

### 16. Get Hero Image
**GET** `/api/site-settings/hero-image/{filename}`

**Response:** File download (JPEG/PNG/GIF/WebP)

---

## Error Responses

### 400 Bad Request
```json
{
  "statusCode": 400,
  "success": false,
  "message": "Image file is required"
}
```

### 401 Unauthorized
```json
{
  "statusCode": 401,
  "success": false,
  "message": "Authorization token is missing"
}
```

### 403 Forbidden
```json
{
  "statusCode": 403,
  "success": false,
  "message": "You do not have permission to perform this action"
}
```

### 404 Not Found
```json
{
  "statusCode": 404,
  "success": false,
  "message": "Resource not found"
}
```

---

## Supported Platforms
- facebook
- twitter
- instagram
- linkedin
- youtube
- tiktok

## Image Formats
- JPEG, PNG, GIF, WebP
- Max Size: 5MB
- Storage: `uploads/hero-banner/`

## Notes
- All timestamps in ISO 8601 format
- ADMIN role required for create/update/delete operations
- Single instance of site settings (creates if not exists)
- Multiple hero banners supported
- Images stored as relative paths without base URL
- Only active banners returned by `/hero-banners/active` endpoint