# Trainer — Show Lesson (Edit Form) — Frontend Guide

How the trainer dashboard loads **one curriculum item** (video lesson or quiz) so it can be edited and saved.

- **Audience:** frontend developers (trainer dashboard)
- **Applies to:** both curriculum item types — `type = "lesson"` (video) and `type = "quiz"`
- **Base path:** `{{base_url}}` = `/api/v1`
- **Related docs:** [courses-trainer.md](./courses-trainer.md), [free-preview-frontend-guide.md](./free-preview-frontend-guide.md), [media-upload-guide.md](./media-upload-guide.md), [quiz-timing-guide.md](./quiz-timing-guide.md)

Common headers on every call: `Authorization: Bearer {{trainer_token}}`, `Accept: application/json`, `Content-Type: application/json`, `Accept-Language: en|ar`. Responses use the envelope `{ "status", "message", "data" }`. `{course}` and `{lesson}` are **UUIDs**, never numeric ids.

---

## 1. Why this endpoint exists

`GET /trainer/courses/{course}/lessons` (the curriculum list) returns `title` / `description` in the **current locale only**. That is not enough to pre-fill an edit form, which needs both the English and Arabic text.

`GET /trainer/lessons/{lesson}` returns the same fields as a list row **plus an `en` and an `ar` block**, shaped exactly like the body the update endpoints accept.

---

## 2. Endpoint map

| Step | Method & path | Notes |
|---|---|---|
| List curriculum | `GET /trainer/courses/{course}/lessons` | Needs `view_courses`. Use it to render the lesson list. |
| **Load one item** | **`GET /trainer/lessons/{lesson}`** | **New.** Needs `view_courses`. Feeds the edit form. |
| Save a video lesson | `PUT /trainer/lessons/video/{lesson}` | Needs `manage_lessons` |
| Save a quiz | `PUT /trainer/lessons/quiz/{lesson}` | Needs `edit_exam_settings` |
| Delete | `DELETE /trainer/lessons/{lesson}` | Soft delete |

Route name: `trainer.courses.lessons.show`.

**Pick the save endpoint from `data.type`:** `"lesson"` → `/lessons/video/{lesson}`, `"quiz"` → `/lessons/quiz/{lesson}`. Calling the wrong one returns **422** (`This curriculum item is a quiz — use that endpoint to update it.`).

---

## 3. Show — `GET /trainer/lessons/{lesson}`

No query params, no body.

### 3.1 Video lesson (`type = "lesson"`)

```json
{
  "status": "success",
  "message": "Lesson retrieved successfully",
  "data": {
    "id": "a2e0b839-a83f-4354-8ef5-7b102c87e6a5",
    "type": "lesson",
    "title": "Intro",
    "description": "Welcome",
    "sort_order": 0,

    "duration_seconds": 600,
    "completion_threshold": 80,
    "video": "https://…/storage/uploads/intro.mp4",
    "is_free_preview": false,
    "free_preview_from_seconds": null,
    "free_preview_to_seconds": null,

    "en": { "title": "Intro",   "description": "Welcome" },
    "ar": { "title": "مقدمة",   "description": null }
  }
}
```

### 3.2 Quiz (`type = "quiz"`)

```json
{
  "status": "success",
  "message": "Lesson retrieved successfully",
  "data": {
    "id": "a2e0b839-a956-4f40-b249-876349953ebc",
    "type": "quiz",
    "title": "Chapter quiz",
    "description": null,
    "sort_order": 1,

    "quiz_duration_minutes": 32,
    "max_attempts": 1,
    "pass_score": 60,
    "must_pass_to_continue": false,
    "show_result_immediately": true,
    "questions_count": 0,

    "en": { "title": "Chapter quiz", "description": null },
    "ar": { "title": "اختبار",        "description": null }
  }
}
```

### 3.3 Field reference

| Field | Type | Present for | Notes |
|---|---|---|---|
| `id` | uuid | both | Use in the save/delete URL |
| `type` | `"lesson"` \| `"quiz"` | both | Decides the form layout and save endpoint |
| `title`, `description` | string \| null | both | **Current-locale** values — for display only. Edit using `en` / `ar`. |
| `sort_order` | int | both | Read-only here. Change order via `POST /trainer/courses/{course}/lessons/reorder`. |
| `en`, `ar` | `{ title, description }` | both | Per-locale values for the form. Either property can be `null`. |
| `duration_seconds` | int \| null | lesson | |
| `completion_threshold` | int \| null | lesson | Percent, 1–100 |
| `video` | **URL string** | lesson | See §5 — **this is a URL, not a media hash** |
| `is_free_preview` | bool | lesson | |
| `free_preview_from_seconds`, `free_preview_to_seconds` | int \| null | lesson | Set only when `is_free_preview = true` |
| `quiz_duration_minutes` | int \| null | quiz | |
| `max_attempts` | int | quiz | |
| `pass_score` | number \| null | quiz | 0–100 |
| `must_pass_to_continue`, `show_result_immediately` | bool | quiz | |
| `questions_count` | int | quiz | Questions are managed via `/trainer/lessons/{lesson}/questions` |

Fields for the other type are **absent** (not `null`) — a video lesson has no `max_attempts`, a quiz has no `video`. Branch on `type`.

### 3.4 Errors

| HTTP | `data.error_code` / body | When | What to do |
|---|---|---|---|
| 401 | — | Missing/expired token | Re-authenticate |
| 403 | `PERMISSION_DENIED`, message "This course is not assigned to you." | The lesson belongs to another trainer's course | Show "not available"; don't retry |
| 403 | `PERMISSION_DENIED`, `context.required_permission = "view_courses"` | Admin has not granted the trainer `view_courses` | Hide the Courses section (the permissions payload on login already tells you) |
| 404 | `status: "fail"`, "Resource not found" | Unknown or soft-deleted lesson UUID | Go back to the list and refresh it |

---

## 4. Saving — `PUT /trainer/lessons/video/{lesson}` and `PUT /trainer/lessons/quiz/{lesson}`

Updates are **partial**: send only the fields that changed. Locale blocks are also partial — send `en`, `ar`, or both.

### 4.1 Video lesson body

```json
{
  "duration_seconds": 900,
  "completion_threshold": 75,
  "is_free_preview": true,
  "free_preview_from_seconds": 0,
  "free_preview_to_seconds": 45,
  "en": { "title": "Intro (updated)", "description": "Welcome" },
  "ar": { "title": "مقدمة" }
}
```

| Field | Rule |
|---|---|
| `duration_seconds` | nullable, integer ≥ 0 |
| `completion_threshold` | nullable, integer 1–100 |
| `video` | nullable string — a **media hash**, see §5 |
| `is_free_preview` | boolean |
| `free_preview_from_seconds` | required when `is_free_preview = true`, integer ≥ 0 |
| `free_preview_to_seconds` | required when `is_free_preview = true`, integer **greater than** `free_preview_from_seconds` |
| `{en,ar}.title` | string, max 200 |
| `{en,ar}.description` | nullable string |

Quiz fields (`quiz_duration_minutes`, `max_attempts`, `pass_score`, `must_pass_to_continue`, `show_result_immediately`) are **prohibited** here → 422.

### 4.2 Quiz body

```json
{
  "quiz_duration_minutes": 30,
  "max_attempts": 2,
  "pass_score": 70,
  "must_pass_to_continue": true,
  "show_result_immediately": false,
  "en": { "title": "Chapter quiz" },
  "ar": { "title": "اختبار الفصل" }
}
```

| Field | Rule |
|---|---|
| `quiz_duration_minutes` | nullable, integer ≥ 1 |
| `max_attempts` | integer ≥ 1 |
| `pass_score` | nullable, number 0–100 |
| `must_pass_to_continue`, `show_result_immediately` | boolean |
| `{en,ar}.title` / `.description` | same as video |

Video fields (`duration_seconds`, `video`, `completion_threshold`, `is_free_preview`, `free_preview_*`) are **prohibited** here → 422.

### 4.3 Save responses

- **200** — returns the updated item in the **list shape** (current-locale `title`/`description`, **no** `en`/`ar` blocks). Refresh the form from it, or call the show endpoint again if you need the locale blocks.
- **422** — validation errors keyed by field (`en.title`, `free_preview_to_seconds`, …) in the standard envelope.
- **422** (business rule) — the course is outside the trainer's **edit window**: only `draft` and `needs_revision` courses can be edited. Courses `pending_review` or `approved` reject the save with `This course cannot be edited while it is <status>.`
- **403** — not the assigned trainer, or the trainer lacks `manage_lessons` (video) / `edit_exam_settings` (quiz).

---

## 5. The `video` field — read this before wiring the form

On **show**, `video` is the file's **URL** (for playback/preview). On **update**, `video` expects a **media hash** (32 hex chars from the media upload). They are different values.

- **Do not echo the show value back into `PUT`.** A URL is not a hash and fails validation with `The media file was not found.`
- **Only send `video` when the trainer picked a new file.** Upload it first (`POST /media/videos/*`, see [media-upload-guide.md](./media-upload-guide.md)), then send the returned `hash`. Leave the key out otherwise.
- If the lesson has no video yet, the URL is a placeholder image, not `null`. Don't rely on `video` being empty to decide whether a video exists; track it through the upload state in your form.

---

## 6. Recommended flow

```
Curriculum list ──GET /trainer/courses/{course}/lessons──► render rows (id, type, title)
        │ user clicks a row
        ▼
GET /trainer/lessons/{lesson} ──► build form from data.en / data.ar + type-specific fields
        │ user edits
        ▼
 (new video file?) ──► upload → hash
        ▼
 PUT /trainer/lessons/{video|quiz}/{lesson}   body = only changed fields
        ▼
 200 → update the row in the list; 422 → show field errors; 403/422 edit-window → disable the form
```

Tips:

1. **Pre-disable the form** when the course `content_status` is not `draft` / `needs_revision` — `GET /trainer/courses/{course}` returns it. The server enforces it either way.
2. **Diff before saving.** Compare form state against the show payload and send only what changed; this also avoids accidentally sending the `video` URL (§5).
3. **Quiz questions are separate.** Edit them through `/trainer/lessons/{lesson}/questions`; this endpoint only returns `questions_count`.

---

## 7. Integration checklist

- [ ] Open the edit form from `GET /trainer/lessons/{lesson}`, not from the list row
- [ ] Choose the form layout and save endpoint from `data.type`
- [ ] Bind title/description inputs to `data.en` / `data.ar`, not the top-level `title` / `description`
- [ ] Send only changed fields; never send the show-time `video` URL back
- [ ] Validate `free_preview_to_seconds > free_preview_from_seconds` client-side when `is_free_preview` is on
- [ ] Handle 403 (not assigned / missing capability), 404 (deleted), and the 422 edit-window error
- [ ] Hide or disable edit controls for trainers without `manage_lessons` / `edit_exam_settings`
