# Claude Code Session Notes

This file documents mistakes and lessons learned during the development of this integration.

## Mistakes Made

### 1. Missing `/emby` Prefix on API Endpoints

**Problem:** Initially created all API endpoints without the `/emby` prefix.

```python
# Wrong
ENDPOINT_SYSTEM_INFO = "/System/Info"
ENDPOINT_USERS = "/Users"

# Correct
ENDPOINT_SYSTEM_INFO = "/emby/System/Info"
ENDPOINT_USERS = "/emby/Users"
```

**Impact:** Connection to Emby server failed with "cannot connect" errors.

**Lesson:** Always verify API endpoint formats against official documentation. Emby Server requires the `/emby` prefix for all API calls.

---

### 2. Incorrect Volume Control API Format

**Problem:** Tried multiple incorrect formats for the SetVolume command before finding the correct one.

```python
# Attempt 1 - Wrong endpoint with body
endpoint = f"/Sessions/{session_id}/Command/SetVolume"
data = {"Arguments": {"Volume": 50}}

# Attempt 2 - Wrong: query parameter
endpoint = f"/Sessions/{session_id}/Command/SetVolume?Volume=50"

# Correct format
endpoint = f"/Sessions/{session_id}/Command"
data = {"Name": "SetVolume", "Arguments": {"Volume": "50"}}  # Arguments as STRINGS
```

**Impact:** Volume control didn't work even though mute/unmute worked fine.

**Lesson:** Emby general commands must be sent to `/Command` endpoint (not `/Command/{CommandName}`) with:
- `Name` field containing the command name
- `Arguments` as a dict with STRING values, not integers

---

### 3. NumberSelector Returns Float, Not Int

**Problem:** Home Assistant's `NumberSelector` widget returns float values, but port numbers must be integers.

```python
# Wrong - port could be 8096.0
self._port = user_input.get(CONF_PORT, DEFAULT_PORT)

# Correct
self._port = int(user_input.get(CONF_PORT, DEFAULT_PORT))
```

**Impact:** Potential type errors or malformed URLs with decimal port numbers.

**Lesson:** Always explicitly convert NumberSelector values to the expected type.

---

### 4. Inconsistent Use of Constants

**Problem:** Hardcoded endpoint paths in some methods instead of using defined constants.

```python
# Wrong - hardcoded
endpoint = f"/Sessions/{session_id}/Playing"

# Correct - using constant
endpoint = f"{ENDPOINT_SESSIONS}/{session_id}/Playing"
```

**Impact:** When the `/emby` prefix was added to constants, hardcoded paths were missed, causing inconsistent behavior.

**Lesson:** Always use constants consistently. When fixing issues, search for all occurrences of the affected strings.

---

### 5. Import Confusion Between Local and HA Constants

**Problem:** Initially imported `CONF_HOST` and `CONF_PORT` from `homeassistant.const` in some files, while also defining them in local `const.py`.

```python
# Inconsistent imports
from homeassistant.const import CONF_HOST, CONF_PORT  # in __init__.py
from .const import CONF_HOST, CONF_PORT  # in config_flow.py
```

**Impact:** Potential confusion and maintenance issues, though values were identical.

**Lesson:** Choose one source for constants and use it consistently across all files. For custom integrations, prefer local constants for full control.

---

## Best Practices Established

1. **Test API endpoints with curl first** - Verify the exact request format before implementing in code
2. **Add debug logging** - Include request URLs and response status codes for troubleshooting
3. **Handle multiple API formats** - Some servers may respond differently; implement fallbacks when sensible
4. **Type conversion** - Always explicitly convert UI input values to expected types
5. **Consistent constant usage** - Define constants once and use them everywhere
6. **Wait for user approval before committing** - Always let the user test changes before creating git commits