# Banner Sets — Frontend Integration Notes (TSHIRTORDER-1590)

Banner sets are **not** a separate API resource. They are managed as part of the
existing **Channel** add/update endpoints, the same way `ecomLinks` already works.

## Endpoints (existing, unchanged)

- `POST /api/v1/channels` — create channel (banner sets optional)
- `POST /api/v1/channels/{id}` — update channel
- `GET  /api/v1/channels/{id}` — returns the channel, including `bannerSets`

Use `Content-Type: multipart/form-data` whenever you're uploading images (same as
the current `banner` / `banner2` / `logo` fields).

## Request shape

Send an array field `bannerSets`, one entry per banner set, using bracket
notation so files and text fields stay grouped by index:

```
bannerSets[0][id]            = 12                  // omit/empty for a NEW set
bannerSets[0][name]          = "Spring sale"
bannerSets[0][position]      = 1                    // sort order, ascending
bannerSets[0][status]        = "active"             // "active" | "inactive"
bannerSets[0][type]          = "2_blocks"            // "2_blocks" | "3_blocks" | "4_blocks"
bannerSets[0][block1Image]   = <file>                // or omit to keep current image
bannerSets[0][block1Link]    = "https://..."
bannerSets[0][block2Image]   = <file>
bannerSets[0][block2Link]    = "https://..."

bannerSets[1][id]            = ""                   // new set
bannerSets[1][name]          = "Summer collection"
bannerSets[1][position]      = 2
bannerSets[1][status]        = "active"
bannerSets[1][type]          = "3_blocks"
bannerSets[1][block1Image]   = <file>
bannerSets[1][block1Link]    = "https://..."
bannerSets[1][block2Image]   = <file>
bannerSets[1][block2Link]    = "https://..."
bannerSets[1][block3Image]   = <file>
bannerSets[1][block3Link]    = "https://..."
```

### `type` controls how many blocks are used

| type | blocks used |
|---|---|
| `2_blocks` | `block1Image/Link`, `block2Image/Link` |
| `3_blocks` | `block1Image/Link` … `block3Image/Link` |
| `4_blocks` | `block1Image/Link` … `block4Image/Link` |

Always send `block1Link..block4Link` as **plain text fields** (not files).
`block1Image..block4Image` are the only file fields.

### Image field rules (per block)

- Send a **file** → uploads a new image, replaces the old one.
- Omit the field entirely → keeps the current image untouched.
- Send an **empty string** `""` → removes the current image.

### Updating vs. creating a set

- Include `id` (matching an existing banner set's id) → updates that set.
- Omit `id` (or send empty) → creates a new banner set.

### Deleting a set

There is no delete endpoint. To delete a banner set, simply **don't include it**
in the `bannerSets` array on the next update call — any existing set whose `id`
is missing from the submitted array gets soft-deleted automatically.

⚠️ This means every update to `bannerSets` must resend **all sets you want to
keep** (with their `id`), not just the ones being changed.

## Response shape (`GET`/after add/update)

```json
{
  "bannerSets": [
    {
      "id": 12,
      "name": "Spring sale",
      "position": 1,
      "type": "2_blocks",
      "status": "active",
      "block1Image": "uploads/channels/34/banner_sets/spring1.jpg",
      "block1Link": "https://...",
      "block2Image": "uploads/channels/34/banner_sets/spring2.jpg",
      "block2Link": "https://...",
      "block3Image": null,
      "block3Link": null,
      "block4Image": null,
      "block4Link": null
    }
  ]
}
```

- `block*Image` is a **relative path**, not a full URL — same as the existing
  `banner` / `logo` fields. Prepend your existing base/asset URL the same way
  you already do for `channel.banner`.
- `block*Image`/`block*Link` for blocks not used by the set's `type` will be `null`
  — UI doesn't need to render/send them.
- List is **not** pre-filtered/sorted by the API on the admin channel-edit
  response — sort by `position` client-side, and show `status` so admins can
  toggle active/inactive.

## Notes

- The old single-banner fields (`banner`, `banner2`, `banner3`, `bannerMobile`,
  `bannerLink`, `bannerLink2`, `bannerLink3`, `bannerShowFullWidth`) are
  **unchanged** and still work exactly as before — `bannerSets` is an
  additional, independent feature.
- Storefront only renders banner sets with `status: "active"`, ordered by
  `position` ascending.