Bundles group existing product variants into a single purchasable package, sold at a discount versus buying each item separately. Each bundle is composed of one or more variants with a quantity and display position, plus an optional `discountPercentage` applied against the sum of the constituent prices.

## List Bundles

```
GET /api/v1/bundles
```

Returns lightweight bundle list items (no full composition). Fetch a single bundle to get its constituent products.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Bundles per page (1-100) |
| `offset` | `number` | 0 | Bundles to skip |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/bundles
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Starter Kit",
      "slug": "starter-kit",
      "summary": "Everything you need to get going",
      "images": ["https://cdn.example.com/starter-kit.jpg"],
      "status": "published",
      "discountPercentage": 15,
      "productCount": 3
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Get Bundle

```
GET /api/v1/bundles/{id}
```

Returns a single bundle by UUID, including its constituent products.

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/bundles/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Starter Kit",
  "slug": "starter-kit",
  "summary": "Everything you need to get going",
  "content": null,
  "seo": {
    "title": "Starter Kit",
    "description": "Save 15% on the essentials"
  },
  "images": ["https://cdn.example.com/starter-kit.jpg"],
  "status": "published",
  "discountPercentage": 15,
  "products": [
    {
      "variantId": "0191abc0-0000-7000-8000-000000000100",
      "quantity": 1,
      "position": 0,
      "productId": "0191abc0-0000-7000-8000-000000000200",
      "productName": "Classic Tee"
    }
  ],
  "createdAt": "2024-06-15T10:30:00.000Z"
}
```

---

## Create Bundle

```
POST /api/v1/bundles
```

Creates a product bundle composed of existing variants. Slug is auto-generated from the name if omitted and must be unique.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Bundle name |
| `slug` | `string` | No | URL slug, lowercase (`a-z0-9-`); auto-generated from name if omitted |
| `summary` | `string` | No | Short summary |
| `seo` | `object` | No | SEO metadata (`title`, `description`, `canonical`) |
| `images` | `string[]` | No | Bundle image URLs |
| `discountPercentage` | `number` | No | Discount vs. the sum of constituent prices (0-100) |
| `status` | `string` | No | Publication status: `draft`, `published`, or `hidden` |
| `variants` | `object[]` | No | Variants that make up the bundle (see below) |

### Variant Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `variantId` | `string` | Yes | Variant UUID to include in the bundle |
| `quantity` | `number` | No | How many of this variant the bundle contains (default: 1) |
| `position` | `number` | No | Display order within the bundle (default: 0) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter Kit",
    "discountPercentage": 15,
    "status": "published",
    "variants": [
      { "variantId": "0191abc0-0000-7000-8000-000000000100", "quantity": 1, "position": 0 }
    ]
  }' \
  https://your-store.yns.store/api/v1/bundles
```

### Response (201)

Returns the created bundle with full composition (same shape as Get Bundle). Returns `409` if a bundle with the same slug already exists.

---

## Update Bundle

```
PATCH /api/v1/bundles/{id}
```

Partially updates a bundle. Provided fields change; omitted fields are preserved. Passing `variants` replaces the entire composition.

### Request Body

All fields from Create Bundle are accepted and optional.

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"discountPercentage": 20, "status": "hidden"}' \
  https://your-store.yns.store/api/v1/bundles/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

Returns the updated bundle with full composition.

---

## Delete Bundle

```
DELETE /api/v1/bundles/{id}
```

Hard-deletes the bundle by UUID. The composition is cascade-removed; the underlying products and variants are untouched.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/bundles/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```