> **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.

# Devices — 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:** all **4/4** routes declared in `modules/Devices/Routes/api.php` on `main` (source-level review; not staging tested).

## `GET /api/v1/devices`

**Purpose:** List devices registered to the authenticated user.
**Access:** Bearer app token

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

**Example request:**

```http
GET /api/v1/devices
Accept: application/json
Authorization: Bearer <token>
```

**Example success response — HTTP 200:**

```json
{
  "data": [
    {
      "id": 7,
      "platform": "android",
      "name": "Pixel",
      "push_enabled": true,
      "push_label": "<localized label>",
      "push_hint": "<localized hint>"
    }
  ]
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data` | array |
| `data[].id` | integer |
| `data[].platform` | string |
| `data[].name` | string |
| `data[].push_enabled` | boolean |
| `data[].push_label` | string |
| `data[].push_hint` | string |

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

---

## `POST /api/v1/devices`

**Purpose:** Register or update a push-capable installation.
**Access:** Bearer app token

| Request field | Type | Required | Validation |
|---|---|---|---|
| `platform` | enum | yes | ios | android | web |
| `token` | string | yes | max:512 |
| `name` | string|null | no | max:120 |
| `push_enabled` | boolean | no | boolean |

**Example request:**

```http
POST /api/v1/devices
Content-Type: application/json

{
  "platform": "android",
  "token": "example-device-token",
  "name": "Pixel",
  "push_enabled": true
}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "id": 7,
    "platform": "android",
    "name": "Pixel",
    "push_enabled": true,
    "push_label": "<localized label>",
    "push_hint": "<localized hint>"
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.id` | integer |
| `data.platform` | string |
| `data.name` | string |
| `data.push_enabled` | boolean |
| `data.push_label` | string |
| `data.push_hint` | string |

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

---

## `PATCH /api/v1/devices/{id}`

**Purpose:** Change push toggle for one owned device.
**Access:** Bearer app token

| Request field | Type | Required | Validation |
|---|---|---|---|
| `id` | integer path | yes | numeric route parameter |
| `push_enabled` | boolean | yes | required boolean |

**Example request:**

```http
PATCH /api/v1/devices/{id}
Content-Type: application/json

{
  "push_enabled": false
}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "id": 7,
    "platform": "android",
    "name": "Pixel",
    "push_enabled": false,
    "push_label": "<localized label>",
    "push_hint": "<localized hint>",
    "message": "<localized toast>"
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.id` | integer |
| `data.platform` | string |
| `data.name` | string |
| `data.push_enabled` | boolean |
| `data.push_label` | string |
| `data.push_hint` | string |
| `data.message` | string |

**Notes / errors:** Non-owned or missing device returns HTTP 404.

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

---

## `DELETE /api/v1/devices/{id}`

**Purpose:** Remove an owned device.
**Access:** Bearer app token

| Request field | Type | Required | Validation |
|---|---|---|---|
| `id` | integer path | yes | numeric route parameter |

**Example request:**

```http
DELETE /api/v1/devices/{id}
Content-Type: application/json

{}
```

**Example success response — HTTP 204:**

No body (HTTP 204).

**Response field types:**

| Field | Type |
|---|---|
| — | — |

**Notes / errors:** 204 has no response body; non-owned or missing device returns 404.

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

---


---

## Earlier route inventory (historical; superseded by contracts above)

# Devices — Flutter API

Source: `modules/Devices/Routes/api.php` on GitLab `main`. Paths are relative to the Laravel API prefix. These entries are route-verified; unspecified request and response schemas are **not yet verified**, and should not be implemented from guesses.

## 1. `GET /devices`

**Purpose:** list own devices. **Access:** auth.

| Input | Contract |
|---|---|
| Path parameters | None |
| Request body / query | Not yet verified from controller and request class |
| Response JSON | Not yet verified from controller/presenter |

## 2. `POST /devices`

**Purpose:** register device. **Access:** auth.

| Input | Contract |
|---|---|
| Path parameters | None |
| Request body / query | Not yet verified from controller and request class |
| Response JSON | Not yet verified from controller/presenter |

## 3. `PATCH /devices/{id}`

**Purpose:** toggle push. **Access:** auth.

| Input | Contract |
|---|---|
| Path parameters | `id` |
| Request body / query | Not yet verified from controller and request class |
| Response JSON | Not yet verified from controller/presenter |

## 4. `DELETE /devices/{id}`

**Purpose:** remove own device. **Access:** auth.

| Input | Contract |
|---|---|
| Path parameters | `id` |
| Request body / query | Not yet verified from controller and request class |
| Response JSON | Not yet verified from controller/presenter |

## Verified device request / response contracts

### `POST /devices` — JSON body

| Field | Type | Validation |
|---|---|---|
| `platform` | enum string | Required; must match `Platform` enum (enumerated values not verified here) |
| `token` | string | Required; max 512 characters |
| `name` | string/null | Optional; max 120 characters |
| `push_enabled` | boolean | Optional |

Example **request shape** (platform is a placeholder, not an asserted enum value):

```json
{"platform":"<supported-platform>","token":"<push-token>","name":"My phone","push_enabled":true}
```

### `PATCH /devices/{id}` — JSON body

| Field | Type | Validation |
|---|---|---|
| `push_enabled` | boolean | Required |

```json
{"push_enabled":false}
```

### `GET /devices`, `POST /devices`, `PATCH /devices/{id}` — verified response item shape

The controller returns the following item in the common `ApiResponse::ok` envelope (the envelope itself must be verified separately):

```json
{"id":12,"platform":"<supported-platform>","name":"My phone","push_enabled":true,"push_label":"<localized text>","push_hint":"<localized text>"}
```

`GET /devices` returns an array of these items. `PATCH` also adds a localized `message` field. The token is **never returned**. `DELETE /devices/{id}` returns 204 No Content, and non-owned IDs return 404. Source: `DeviceController.php`, `RegisterDeviceRequest.php`, `SetDevicePushRequest.php`.


## Final source-level implementation audit (2026-11-22)

**Route inventory: 4/4:** `GET /devices`, `POST /devices`, `PATCH /devices/{id}`, `DELETE /devices/{id}`. All require `auth:sanctum`; `{id}` has a numeric route constraint. No separate dashboard endpoint exists in this module. `GET` and `DELETE` do not require a JSON body. All response examples are illustrative rather than captured HTTP traffic.

### Registration and ownership lifecycle

| Scenario | Backend behavior | Flutter action |
|---|---|---|
| New installation, POST | Register device for signed-in user; default push is enabled | Persist returned `data.id` for settings switch and removal |
| Same token registered again | Upsert by trimmed token rather than duplicate insertion | Safe to re-register on login or token refresh |
| Token registered by another account | Token ownership is reassigned; if `push_enabled` omitted on new owner, switch starts enabled | Register again after switching accounts; never reuse old device ID blindly |
| POST `push_enabled` omitted | Existing device retains its push preference; new device defaults to enabled | Include the preference only if intentionally changing it |
| PATCH same value repeatedly | Idempotent update to caller-owned device | Keep UI in sync with returned `push_enabled` |
| PATCH or DELETE foreign ID | `404`, same as missing device | Do not expose another user's device details |
| DELETE caller-owned ID | `204` with no JSON payload | Remove stored device ID locally; register again to resume |
| Account deletion | Devices removed by account-deleted event listener | Clear device identifier and credentials locally |

### Exact field matrix — device object

| JSON path | Type | Nullable | Source meaning |
|---|---|---|---|
| `data.id` / `data[].id` | integer | Possible before persistence; persisted HTTP records have ID | Device ID for PATCH/DELETE |
| `data.platform` | string enum | No | `ios`, `android`, `web` |
| `data.name` | string | No | Friendly name, default empty string |
| `data.push_enabled` | boolean | No | This installation's FCM push preference |
| `data.push_label` | string | No | Localized setting title |
| `data.push_hint` | string | No | Localized setting subtitle |
| `data.message` | string | Only PATCH | Localized confirmation toast; not returned on GET/POST |

The FCM `token` is **write-only**: it is required on registration and deliberately absent from every presenter response. Do not treat the returned `id` as the FCM token.

### Validation and error behavior

| Operation | HTTP | Condition | Client handling |
|---|---|---|---|
| Any | `401` | Missing/invalid Sanctum token | Sign in / refresh authentication flow |
| POST | `422` | Missing `platform` or `token`, invalid platform, `token` over 512 chars, `name` over 120 chars, or invalid `push_enabled` | Show validation and retry with corrected payload |
| PATCH | `422` | Missing or invalid boolean `push_enabled` | Do not optimistically keep an invalid switch value |
| PATCH / DELETE | `404` | Device not found or not owned by caller | Re-register current token if device ID is stale |
| DELETE | `204` | Successful removal | Expect empty response body, not `{data:...}` |

**Push-off semantics:** `push_enabled=false` suppresses push delivery to that installation, but **does not disable in-app notifications**. The localized `message` for disabling push may mention a receipt-confirmation window configured elsewhere; Flutter should display the returned message rather than hardcoding its duration.

### Flutter integration sequence

1. After successful sign-in, obtain the platform's FCM token and `POST /api/v1/devices` with `platform`, `token`, optional `name`; save returned `id`.
2. On FCM token rotation, POST the new token and update the stored `id` from the response. The backend upserts **by token**, not by installation UUID; stale token cleanup is handled separately.
3. On the notification-settings screen, read `GET /api/v1/devices` and identify the current installation by its saved device `id`; do not assume the first item is the current device.
4. Toggle using `PATCH /api/v1/devices/{id}` with `{"push_enabled":false}` or `true`, then use the returned `data.push_enabled`, `data.message` and `data.push_hint`.
5. On explicit device deregistration, call `DELETE /api/v1/devices/{id}` and handle the empty 204 body.

**Source links:** [Routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Routes/api.php) · [Controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Interfaces/Http/Controllers/DeviceController.php) · [RegisterDeviceRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Interfaces/Http/Requests/RegisterDeviceRequest.php) · [SetDevicePushRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Interfaces/Http/Requests/SetDevicePushRequest.php) · [RegisterDevice](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Application/RegisterDevice.php) · [DevicePushToggleTest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Devices/Tests/DevicePushToggleTest.php).

**Verification boundary:** Code contracts and existing repository test assertions reviewed. No staging HTTP calls, real-device FCM deliveries, or live token-rotation tests were run here.


## Cross-checked controller and FormRequest notes (source audit)

Sources: `DeviceController`, `RegisterDeviceRequest`, `SetDevicePushRequest` on GitLab `main`. The registration endpoint is **POST**, but returns `200` (`ApiResponse::ok`), not `201`. Its response deliberately omits the push token. Exact returned device fields: `id`, `platform`, `name`, `push_enabled`, `push_label`, `push_hint`.

- `POST /api/v1/devices`: required `platform` (valid `Platform` enum) and `token` (string, max 512); optional nullable `name` (string, max 120) and optional boolean `push_enabled`.
- `PATCH /api/v1/devices/{id}`: required boolean `push_enabled`. Returns the same device fields **plus** a localized `message`. An unknown or non-owned device returns `404`.
- `DELETE /api/v1/devices/{id}`: returns `204 No Content`; unknown or non-owned device returns `404`.
- Disabling push for an installation **does not disable in-app notifications**. Do not infer platform enum values from this controller alone.

These notes are static source verification, not Staging test results.
