> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Settings — Outlet API handoff (flutter)

> **Verification boundary:** The detailed contract below was derived from repository source, not from live HTTP captures. Fields explicitly marked unverified remain open. The earlier route inventory is retained below for cross-checking; where it says “not verified”, the more recent source-reviewed contract takes precedence.

## Controller-reviewed contracts


All URLs relative to `/api/v1/`. Example values are **illustrative**, not captured from a live server. Angle-bracket text means a placeholder, not a literal API value. Error statuses are listed only when supported by controller code.

**Coverage in this document:** 4 endpoints; this is NOT an assertion that the entire module is complete.

## `GET /api/v1/settings/general`

**Purpose:** Read site name, support email, registration switch.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/settings/general
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "site_name": "Outlet",
    "support_email": "help@example.com",
    "registration_open": true
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.site_name` | string |
| `data.support_email` | string |
| `data.registration_open` | boolean |

**Notes / errors:** Example values illustrative; keys follow GeneralSettings::toArray.

**Source:** [Settings/Interfaces/Http/Controllers/GeneralSettingsController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/GeneralSettingsController.php)

---

## `PATCH /api/v1/settings/general`

**Purpose:** Partially update general settings.
**Access:** Bearer dashboard token + settings.manage

| Request field | Type | Required | Validation |
|---|---|---|---|
| `site_name` | string | no | sometimes; max:120 |
| `support_email` | email | no | sometimes; email |
| `registration_open` | boolean | no | sometimes; boolean |

**Example request:**

```http
PATCH /api/v1/settings/general
Content-Type: application/json

{
  "site_name": "Outlet",
  "support_email": "help@example.com",
  "registration_open": true
}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "site_name": "Outlet",
    "support_email": "help@example.com",
    "registration_open": true
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.site_name` | string |
| `data.support_email` | string |
| `data.registration_open` | boolean |

**Source:** [Settings/Interfaces/Http/Controllers/GeneralSettingsController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/GeneralSettingsController.php)

---

## `GET /api/v1/admin/settings/localization`

**Purpose:** Read default, enabled, and supported locales.
**Access:** Bearer dashboard token + settings.manage

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/admin/settings/localization
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "default_locale": "ar",
    "enabled_locales": [
      "ar",
      "en"
    ],
    "supported_locales": [
      {
        "code": "ar",
        "native_name": "العربية",
        "dir": "rtl",
        "default": true
      }
    ]
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.default_locale` | string |
| `data.enabled_locales` | array |
| `data.enabled_locales[]` | string |
| `data.supported_locales` | array |
| `data.supported_locales[].code` | string |
| `data.supported_locales[].native_name` | string |
| `data.supported_locales[].dir` | string |
| `data.supported_locales[].default` | boolean |

**Source:** [Settings/Interfaces/Http/Controllers/Admin/LocalizationSettingsController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/Admin/LocalizationSettingsController.php)

---

## `PATCH /api/v1/admin/settings/localization`

**Purpose:** Change supported default/enabled locales; default must remain enabled.
**Access:** Bearer dashboard token + settings.manage

| Request field | Type | Required | Validation |
|---|---|---|---|
| `default_locale` | string | no | sometimes; one of supported locales |
| `enabled_locales` | array<string> | no | sometimes; list; min:1; distinct supported locales |

**Example request:**

```http
PATCH /api/v1/admin/settings/localization
Content-Type: application/json

{
  "default_locale": "ar",
  "enabled_locales": [
    "ar",
    "en"
  ]
}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "default_locale": "ar",
    "enabled_locales": [
      "ar",
      "en"
    ],
    "supported_locales": [
      {
        "code": "ar",
        "native_name": "العربية",
        "dir": "rtl",
        "default": true
      }
    ]
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.default_locale` | string |
| `data.enabled_locales` | array |
| `data.enabled_locales[]` | string |
| `data.supported_locales` | array |
| `data.supported_locales[].code` | string |
| `data.supported_locales[].native_name` | string |
| `data.supported_locales[].dir` | string |
| `data.supported_locales[].default` | boolean |

**Notes / errors:** Cross-field validation ensures default_locale belongs to resulting enabled_locales.

**Source:** [Settings/Interfaces/Http/Controllers/Admin/LocalizationSettingsController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/Admin/LocalizationSettingsController.php)

---


---

## Verified integration boundaries and cross-field rules

The four routes in this module comprise **one public Flutter-facing read** and **three dashboard administration routes**. Do not expose the three admin operations in the consumer app. For the public language picker use Core `GET /api/v1/locales`, not `GET /api/v1/admin/settings/localization`.

| Operation | Authentication | Authorization | Expected success |
|---|---|---|---|
| `GET /api/v1/settings/general` | None | Public | `200` `{ "data": { "site_name": string, "support_email": string, "registration_open": boolean } }` |
| `PATCH /api/v1/settings/general` | Sanctum bearer | `settings.manage` | `200`, same general settings object |
| `GET /api/v1/admin/settings/localization` | Sanctum bearer | `settings.manage` | `200`, localization settings object |
| `PATCH /api/v1/admin/settings/localization` | Sanctum bearer | `settings.manage` | `200`, localization settings object |

### General settings: precise field contract

| `data` field | JSON type | Meaning |
|---|---|---|
| `site_name` | string | Display name of platform |
| `support_email` | string | Support email |
| `registration_open` | boolean | Whether sign-up is enabled; display a server-driven registration state |

The admin PATCH is partial: `site_name` is optional string up to 120 characters, `support_email` optional valid email, and `registration_open` optional boolean. The controller updates only validated keys and returns the whole settings object. An empty PATCH has no required fields in its FormRequest, but should not be used by the client.

### Localization: precise field contract

| `data` field | JSON type | Meaning |
|---|---|---|
| `default_locale` | string | Default enabled language code |
| `enabled_locales` | string[] | Enabled language codes, with default sorted first when list is saved |
| `supported_locales` | object[] | Supported languages as described by Core `LocalesController::describe` |
| `supported_locales[].code` | string | Language code |
| `supported_locales[].native_name` | string | Native-language display label |
| `supported_locales[].dir` | string | Writing direction, e.g. `rtl` |
| `supported_locales[].default` | boolean | Whether language is current platform default |

PATCH request validation (both top-level fields optional):

| Field | Type | Validation |
|---|---|---|
| `default_locale` | string | Must belong to supported locales |
| `enabled_locales` | string[] | Nonempty sequential list (`array`, `list`, `min:1`) |
| `enabled_locales.*` | string | Required, distinct, supported locale |

**Cross-field constraint:** the resulting `default_locale` must be included in the resulting `enabled_locales`, even when only one field is patched. Changing `default_locale` alone to a disabled language returns `422`; disabling the existing default alone also returns `422`. When saved, the default language is sorted first, duplicate values are eliminated, the locale cache is invalidated, and the change is audited. The documented defaults `ar` and `['ar','en']` are demonstrated in tests, not guaranteed immutable configuration.

**Example request (dashboard only):**

```http
PATCH /api/v1/admin/settings/localization
Authorization: Bearer <admin-token>
Content-Type: application/json

{"default_locale":"en","enabled_locales":["en","ar"]}
```

**Example response (illustrative values):**

```json
{
  "data": {
    "default_locale": "en",
    "enabled_locales": ["en", "ar"],
    "supported_locales": [
      {"code":"ar","native_name":"العربية","dir":"rtl","default":false},
      {"code":"en","native_name":"English","dir":"ltr","default":true}
    ]
  }
}
```

### Error handling and app guidance

| Status | Trigger | Client action |
|---|---|---|
| `401` | Missing/invalid bearer token on admin routes | Redirect admin to authentication |
| `403` | Authenticated without `settings.manage` | Hide/deny administration actions |
| `422` | Invalid input, unsupported/duplicate language, default not enabled | Render `error.details` per field; do not silently change values |

Flutter should fetch `GET /settings/general` before sign-up to display `registration_open`, `site_name`, and support contact. Do not infer registration policy from cached settings alone: the server remains authoritative. For language selection use public Core `/locales`, which reflects enabled locales; tests confirm that disabling English causes an English `Accept-Language` request to fall back to Arabic. The settings endpoints do not manage the signed-in user's `locale`; that is handled by Identity `PATCH /me`.

### Evidence and verification limits

Source-reviewed on GitLab `main`: [routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Routes/api.php), [general controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/GeneralSettingsController.php), [general request](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Requests/UpdateGeneralSettingsRequest.php), [localization controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/Admin/LocalizationSettingsController.php), [localization request](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Requests/UpdateLocalizationSettingsRequest.php), and [localization tests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Tests/LocalizationSettingsTest.php). Examples are illustrative; no staging requests or runtime assertions were executed in this handoff.
