alexei.dolgolyov
3b64e4ef78
- Add comprehensive .gitignore for Python/HA projects - Document mistakes and lessons learned during development Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# 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
|