# Color Palette API - Quick Reference Card

## 🎯 Endpoints

| Method | URL | Purpose |
|--------|-----|---------|
| `GET` | `http://10.42.0.1:8765/api/color-palette` | Get current palette |
| `POST` | `http://10.42.0.1:8765/api/color-palette` | Update palette/selection |
| `PUT` | `http://10.42.0.1:8765/api/color-palette` | Same as POST |

**Backup:** Same endpoints available on port `8766`

---

## 📦 Data Structure

```javascript
{
  palette: [
    {r: 255, g: 0, b: 0},    // Slot 0
    {r: 0, g: 255, b: 0},    // Slot 1
    {r: 0, g: 0, b: 255},    // Slot 2
    {r: 255, g: 255, b: 0},  // Slot 3
    {r: 255, g: 0, b: 255},  // Slot 4
    {r: 0, g: 255, b: 255},  // Slot 5
    {r: 255, g: 128, b: 0},  // Slot 6
    {r: 255, g: 255, b: 255} // Slot 7
  ],
  selected_indices: [0, 1]   // Active colors
                             // [0] = Primary RGB for patterns
                             // [1] = Reserved for future use
}
```

---

## 💻 Copy-Paste Code

### Get Palette
```javascript
const res = await fetch('http://10.42.0.1:8765/api/color-palette');
const {palette, selected_indices} = await res.json();
```

### Update Color (e.g., slot 3 to purple)
```javascript
const current = await fetch('http://10.42.0.1:8765/api/color-palette')
  .then(r => r.json());

const newPalette = [...current.palette];
newPalette[3] = {r: 128, g: 0, b: 128};

await fetch('http://10.42.0.1:8765/api/color-palette', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({palette: newPalette})
});
```

### Select Colors (e.g., slots 2 and 5)
```javascript
await fetch('http://10.42.0.1:8765/api/color-palette', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({selected_indices: [2, 5]})
});
```

---

## 🛠️ Helper Functions

### RGB ↔ Hex Conversion
```javascript
const rgbToHex = ({r, g, b}) => 
  '#' + [r, g, b].map(x => x.toString(16).padStart(2, '0')).join('');

const hexToRgb = (hex) => {
  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
  return result ? {
    r: parseInt(result[1], 16),
    g: parseInt(result[2], 16),
    b: parseInt(result[3], 16)
  } : null;
};
```

---

## ✅ Validation Rules

- **8 colors** in palette (exactly)
- **RGB values** 0-255 (integers)
- **2 selected indices** (exactly)
- **Indices** 0-7 (valid range)

---

## 🧪 Test

```bash
# Get
curl http://10.42.0.1:8765/api/color-palette | jq

# Update selection
curl -X POST http://10.42.0.1:8765/api/color-palette \
  -H "Content-Type: application/json" \
  -d '{"selected_indices": [0, 2]}'

# Run full test suite
./test_color_api.sh 10.42.0.1
```

---

## 📝 Notes

- **First selected color (index 0) is used as the primary RGB for LED patterns**
- Changes auto-save to `lighting_config.json`
- Invalid data is ignored (not rejected)
- Validate client-side before sending
- WebSocket is at `ws://10.42.0.1:8765/ws` (different path)

---

## 📚 Full Docs

See `COLOR_PALETTE_API.md` for complete documentation