# CMS Settings API Documentation

## Overview
The Settings API provides access to company-scoped site configuration including branding, SEO settings, contact information, social links, and integration settings. All settings are scoped to the authenticated company.

## Authentication
All requests require the following headers:

| Header | Required | Description |
|--------|----------|-------------|
| `X-Company-Hash` | Yes | Unique company identifier |
| `Accept` | Yes | `application/json` |

**Missing or invalid company hash returns `422 Unprocessable Entity`**

---

## Endpoint

### Get Site Settings
```
GET /api/cms/settings
```

Returns comprehensive site configuration for the authenticated company.

**Response:**
```json
{
  "success": true,
  "message": "Settings fetched successfully",
  "data": {
    "company": {
      "name": "Acme Corporation",
      "tagline": "Innovation at its best",
      "logo": "https://cdn.example.com/logo.png",
      "favicon": "https://cdn.example.com/favicon.ico",
      "email": "info@acme.com",
      "phone": "+1 (555) 123-4567",
      "address": {
        "street": "123 Business Ave",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102",
        "country": "USA"
      },
      "timezone": "America/Los_Angeles",
      "language": "en"
    },
    "branding": {
      "primary_color": "#1a73e8",
      "secondary_color": "#34a853",
      "accent_color": "#fbbc04",
      "font_primary": "Inter",
      "font_secondary": "Roboto",
      "font_heading": "Montserrat",
      "theme": "light",
      "custom_css": ""
    },
    "seo": {
      "meta_title": "Acme Corporation - Innovation at its best",
      "meta_description": "Leading provider of innovative solutions",
      "meta_keywords": ["innovation", "technology", "solutions"],
      "og_image": "https://cdn.example.com/og-image.jpg",
      "og_type": "website",
      "twitter_card": "summary_large_image",
      "twitter_site": "@acmecorp",
      "google_analytics_id": "UA-123456789-1",
      "google_tag_manager_id": "GTM-XXXXXXX",
      "facebook_pixel_id": "123456789012345"
    },
    "social": {
      "facebook": "https://facebook.com/acmecorp",
      "twitter": "https://twitter.com/acmecorp",
      "instagram": "https://instagram.com/acmecorp",
      "linkedin": "https://linkedin.com/company/acmecorp",
      "youtube": "https://youtube.com/acmecorp",
      "github": null,
      "tiktok": null
    },
    "footer": {
      "copyright": "© 2026 Acme Corporation. All rights reserved.",
      "widgets": [
        {
          "type": "text",
          "title": "About Us",
          "content": "We are a leading provider..."
        },
        {
          "type": "links",
          "title": "Quick Links",
          "links": [
            {"label": "Privacy Policy", "url": "/privacy"},
            {"label": "Terms of Service", "url": "/terms"},
            {"label": "Contact", "url": "/contact"}
          ]
        }
      ],
      "show_social_links": true,
      "newsletter_enabled": true
    },
    "integrations": {
      "stripe": {
        "enabled": true,
        "public_key": "pk_test_..."
      },
      "mailchimp": {
        "enabled": true,
        "api_key": "hidden",
        "list_id": "abc123def"
      },
      "recaptcha": {
        "enabled": true,
        "site_key": "6Lc..."
      },
      "maps": {
        "enabled": true,
        "api_key": "AIza...",
        "coordinates": {
          "lat": 37.7749,
          "lng": -122.4194
        }
      }
    },
    "features": {
      "blog_enabled": true,
      "ecommerce_enabled": true,
      "events_enabled": true,
      "donations_enabled": true,
      "multilingual_enabled": false,
      "maintenance_mode": false
    }
  }
}
```

---

## Response Fields

### Company Object

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Company/site name |
| `tagline` | string | Company tagline/slogan |
| `logo` | string | URL to company logo |
| `favicon` | string | URL to favicon |
| `email` | string | Contact email address |
| `phone` | string | Contact phone number |
| `address` | object | Physical address information |
| `timezone` | string | Company timezone (IANA format) |
| `language` | string | Default language (ISO 639-1) |

### Branding Object

| Field | Type | Description |
|-------|------|-------------|
| `primary_color` | string | Primary brand color (hex) |
| `secondary_color` | string | Secondary brand color (hex) |
| `accent_color` | string | Accent color (hex) |
| `font_primary` | string | Primary font family |
| `font_secondary` | string | Secondary font family |
| `font_heading` | string | Heading font family |
| `theme` | string | Theme mode (`light`, `dark`, `auto`) |
| `custom_css` | string | Custom CSS overrides |

### SEO Object

| Field | Type | Description |
|-------|------|-------------|
| `meta_title` | string | Default meta title |
| `meta_description` | string | Default meta description |
| `meta_keywords` | array | SEO keywords |
| `og_image` | string | Open Graph default image |
| `og_type` | string | Open Graph type |
| `twitter_card` | string | Twitter card type |
| `twitter_site` | string | Twitter handle |
| `google_analytics_id` | string | GA tracking ID |
| `google_tag_manager_id` | string | GTM container ID |
| `facebook_pixel_id` | string | Facebook Pixel ID |

### Social Object

| Field | Type | Description |
|-------|------|-------------|
| `facebook` | string\|null | Facebook page URL |
| `twitter` | string\|null | Twitter profile URL |
| `instagram` | string\|null | Instagram profile URL |
| `linkedin` | string\|null | LinkedIn company page URL |
| `youtube` | string\|null | YouTube channel URL |
| `github` | string\|null | GitHub organization URL |
| `tiktok` | string\|null | TikTok profile URL |

### Footer Object

| Field | Type | Description |
|-------|------|-------------|
| `copyright` | string | Copyright text |
| `widgets` | array | Footer widget configuration |
| `show_social_links` | boolean | Display social links in footer |
| `newsletter_enabled` | boolean | Enable newsletter signup |

### Integrations Object

| Field | Type | Description |
|-------|------|-------------|
| `stripe` | object | Stripe payment settings |
| `mailchimp` | object | Mailchimp email settings |
| `recaptcha` | object | Google reCAPTCHA settings |
| `maps` | object | Google Maps settings |

### Features Object

| Field | Type | Description |
|-------|------|-------------|
| `blog_enabled` | boolean | Blog module enabled |
| `ecommerce_enabled` | boolean | E-commerce enabled |
| `events_enabled` | boolean | Events module enabled |
| `donations_enabled` | boolean | Donations enabled |
| `multilingual_enabled` | boolean | Multi-language support |
| `maintenance_mode` | boolean | Site in maintenance mode |

---

## Error Responses

### 422 Unprocessable Entity (Invalid Company Hash)
```json
{
  "success": false,
  "message": "Missing or invalid X-Company-Hash header."
}
```

---

## Behavior Notes

- **No Caching**: Always returns fresh configuration from database
- **Company Scoping**: All settings filtered by authenticated company
- **Field Availability**: Response fields may vary based on company setup
- **Sensitive Data**: API keys are either hidden or public-only (no private keys)
- **Empty Values**: Disabled integrations return `null` or `enabled: false`

---

## Example Usage

### JavaScript (Fetch API)
```javascript
const companyHash = 'abc123def456';

const response = await fetch('https://api.example.com/api/cms/settings', {
  headers: {
    'X-Company-Hash': companyHash,
    'Accept': 'application/json'
  }
});

const data = await response.json();
const settings = data.data;

// Apply branding
document.documentElement.style.setProperty('--primary-color', settings.branding.primary_color);
document.title = settings.seo.meta_title;

// Build social links
Object.entries(settings.social).forEach(([platform, url]) => {
  if (url) {
    console.log(`${platform}: ${url}`);
  }
});
```

### React Hook
```jsx
import { useEffect, useState } from 'react';

function useSettings(companyHash) {
  const [settings, setSettings] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('https://api.example.com/api/cms/settings', {
      headers: {
        'X-Company-Hash': companyHash,
        'Accept': 'application/json'
      }
    })
    .then(res => res.json())
    .then(data => {
      setSettings(data.data);
      setLoading(false);
    });
  }, [companyHash]);

  return { settings, loading };
}

// Usage
function App() {
  const { settings, loading } = useSettings('abc123def456');

  if (loading) return <div>Loading...</div>;

  return (
    <div style={{ color: settings.branding.primary_color }}>
      <h1>{settings.company.name}</h1>
      <p>{settings.company.tagline}</p>
    </div>
  );
}
```

### cURL
```bash
curl -X GET "https://api.example.com/api/cms/settings" \
  -H "X-Company-Hash: abc123def456" \
  -H "Accept: application/json"
```

### PHP
```php
$companyHash = 'abc123def456';

$response = Http::withHeaders([
    'X-Company-Hash' => $companyHash,
    'Accept' => 'application/json',
])->get('https://api.example.com/api/cms/settings');

$settings = $response->json()['data'];

echo $settings['company']['name'];
echo $settings['branding']['primary_color'];
```