# Boosted Videos

Boosted videos are pinned to the top of homepage row results. When a video is boosted in a specific homepage row, it appears before other videos sorted by priority.

## How it works

1. Each homepage row has an `id` (e.g. `"xK9mP2"`)
2. Admin boosts a video in a specific row via the admin API
3. Frontend passes `homepageRowId` when fetching videos for that row
4. Boosted videos appear first, ordered by priority (highest first), followed by regular videos ordered by date

## Frontend flow

### 1. Fetch homepage rows

```
GET /client/v1/homepage/rows
```

Response:

```json
[
  {
    "id": "xK9mP2",
    "rowType": 2,
    "title": "Live Channels",
    "displayOrder": 1,
    "isActive": true,
    "filterParams": null
  },
  {
    "id": "aB3nQ7",
    "rowType": 8,
    "title": "Latest Videos",
    "displayOrder": 2,
    "isActive": true,
    "filterParams": "{\"channelId\": \"rT5wL1\"}"
  }
]
```

### 2. Fetch videos per row

Pass the row `id` as `homepageRowId` query parameter to the appropriate endpoint based on `rowType`:

| rowType | Endpoint | Example |
|---------|----------|---------|
| `2` (LiveChannels) | `GET /videos/live` | `/videos/live?livestreamCategory=LiveChannel&homepageRowId=xK9mP2` |
| `3` (SlowTv) | `GET /videos/live` | `/videos/live?livestreamCategory=SlowTv&homepageRowId=xK9mP2` |
| `8` (Videos) | `GET /videos/vod` | `/videos/vod?homepageRowId=aB3nQ7` |
| `8` (Videos with channel) | `GET /videos/vod` | `/videos/vod?channelId=rT5wL1&homepageRowId=aB3nQ7` |

The `homepageRowId` parameter is optional. When omitted, results are ordered by date as usual. When provided, boosted videos for that row appear first.

### 3. Example

```
GET /videos/vod?page=1&pageSize=10&homepageRowId=aB3nQ7
```

Response (standard paginated response - boosted videos are at the top, no separate field):

```json
{
  "items": [
    { "id": "vid1", "title": "Boosted Video A", "..." : "..." },
    { "id": "vid2", "title": "Boosted Video B", "..." : "..." },
    { "id": "vid3", "title": "Regular Video (newest)", "..." : "..." }
  ],
  "totalCount": 50
}
```

## Admin API

### Create boosted video

```
POST /admin/v1/boosted-videos
{
  "videoId": "<encoded-video-id>",
  "homepageRowId": "<encoded-homepage-row-id>",
  "priority": 10,
  "boostedUntil": "2026-05-01T00:00:00Z"
}
```

- `priority` - higher value = appears first among boosted videos
- `boostedUntil` - optional, set to `null` for permanent boost, or a UTC datetime for auto-expiry

### List boosted videos

```
GET /admin/v1/boosted-videos?homepageRowId=aB3nQ7
```

### Update boosted video

```
PUT /admin/v1/boosted-videos/{id}
{
  "videoId": "<encoded-video-id>",
  "homepageRowId": "<encoded-homepage-row-id>",
  "priority": 20,
  "boostedUntil": null
}
```

### Delete boosted video

```
DELETE /admin/v1/boosted-videos/{id}
```

## Notes

- A video can only be boosted once per homepage row (unique constraint on `videoId` + `homepageRowId`)
- Expired boosts (`boostedUntil` in the past) are automatically excluded from results
- Cache is invalidated automatically when boosted videos are created, updated, or deleted