Skip to content

feat: foundation (API client, config flow, coordinator, CI) - #1

Merged
ant1fr merged 3 commits into
mainfrom
feat/foundation
Nov 19, 2026
Merged

ant1fr merged 3 commits into
mainfrom
feat/foundation

Conversation

@ant1fr

@ant1fr ant1fr commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Summary

Milestone 1 "Foundation" of the smart_frame_engine integration: everything the entity platforms and services of later milestones will build on. No entities or services yet.

  • API client (api.py, const.py): typed async client on HA's shared session; health/compatibility handshake, status, config + Family Mode, ambient context (per-field TTL, clear by field), force refresh, title card, wake-up, push, current/preview image. SUPPORTED_API_VERSION = 1 and all 18 capability flags. Exceptions: SmartFrameConnectionError, SmartFrameAuthError, SmartFrameIncompatibleError (+ SmartFrameApiError / SmartFrameValidationError for 4xx/5xx and 422).
  • Config flow: Zeroconf (open vs key/password, api_key asked only when auth != open), manual setup (host + port 8080, health probe first), reauth, options flow (polling interval). The engine's instance_id is the unique_id, so a DHCP change updates the existing entry instead of duplicating it.
  • Coordinator: polls health + status (+ ambient context), re-checks min_api_version <= 1 <= api_version on every refresh, creates a persistent Repair issue saying which side to update, and removes it automatically once compatible. 401 raises ConfigEntryAuthFailed; connection errors raise UpdateFailed. Capabilities are cached for platforms/services.
  • Entity base, diagnostics (api_key redacted), en/fr translations (strings.json == en.json), CI (hassfest, HACS, ruff, mypy, pytest), hacs.json, manifest.

Things to know before merging

  1. Depends on upstream PR feat: give each engine a stable instance id and a unique name Smart-Frame-Engine#43 (contract v1.1: instance_id / instance_name in /api/health and the Zeroconf TXT). It is still open, so I grounded on that branch. Engines without it (1.0.0-rc.1) are refused with a clear instance_id_missing message. Please merge #43 first.
  2. is_locked is not implemented: it is not in API_CONTRACT.md / openapi.json. Ambient context supports the documented fields and ttl_minutes only.
  3. Python 3.14 in CI: the HA 2026.1.0 minimum needs Python >= 3.13.2, and current HA / pytest-homeassistant-custom-component need >= 3.14. requires-python = ">=3.13.2"; CLAUDE.md corrected (it said 3.12+).
  4. Repair issues are created by the coordinator, not the config flow. There is no config entry yet during a flow, so a persistent issue could never be cleared; the flow aborts with server_outdated / integration_outdated instead.
  5. Key validation uses GET /api/config, because GET /api/status is public in key mode and cannot prove a key is valid. The coordinator's ambient-context call plays the same role while polling.
  6. Schemas use voluptuous: HA 2026.10 moved to probatio but keeps a runtime shim, so this works on every 2026.x release; a tiny helper isolates the type-only mismatch.
  7. Services registration (listed under __init__.py in CLAUDE.md) is deferred: no services in this milestone.

Verification

Run on a fresh Linux clone of this branch (Python 3.14, HA 2026.10.4):

  • ruff check .: passed
  • ruff format --check .: passed
  • mypy custom_components: passed (strict)
  • pytest: 100 passed. I also mutation-checked six behaviours (Repair issue cleanup, compatibility direction, redaction, header auth, Zeroconf de-duplication, 401 handling): each breakage is caught by a test.

Not verified locally: hassfest and HACS only run in CI (the brands HACS check is ignored, as it is only required for the HACS default list).
HA's test plugin imports fcntl, so pytest cannot run on native Windows; I ran it under WSL.

🤖 Generated with Claude Code

ant1fr and others added 3 commits November 19, 2026 14:23
- pyproject.toml: ruff, mypy (strict) and pytest (asyncio_mode=auto) for
  Python 3.13.2+ (HA 2026.1 minimum); CI and tests run on Python 3.14
- CI: hassfest, HACS (category integration), ruff check/format, mypy, pytest
- hacs.json targeting Home Assistant 2026.1.0
- .gitattributes forces LF so strings.json and en.json stay byte-identical
- CLAUDE.md: correct the Python target, document instance_id as unique_id
  and that pytest needs Linux/macOS/WSL (HA's test plugin imports fcntl)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Foundation of the smart_frame_engine integration, grounded in the Smart
Frame Engine API contract v1.1 (instance_id / instance_name).

- api.py: typed async client on HA's shared session; health handshake,
  status, config + Family Mode, ambient context (TTL, clear by field),
  force refresh, title card, wake-up, push and current/preview images
- const.py: SUPPORTED_API_VERSION and all 18 capability flags
- config_flow.py: Zeroconf (open vs key/password), manual setup, reauth,
  options flow (polling interval); instance_id is the unique_id so DHCP
  address changes update the existing entry
- coordinator.py: health + status (+ ambient) polling, compatibility check
  on every refresh with a persistent Repair issue that clears itself,
  capability cache, shared DeviceInfo
- entity.py, __init__.py, diagnostics.py (api_key redacted)
- strings.json / translations en + fr

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
100 tests: api (all auth modes, 401, 422, timeouts, compatibility matrix),
config flow (Zeroconf open/key, manual, duplicate address update,
incompatible api_version, reauth, options), coordinator (capability cache,
Repair issue creation and auto-resolution, reauth on 401, instance mismatch),
diagnostics redaction, entity device info, manifest ordering and
en/fr translation parity.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ant1fr
ant1fr merged commit 2dac68f into main Nov 19, 2026
5 of 6 checks passed
@ant1fr
ant1fr deleted the feat/foundation branch November 19, 2026 14:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant