feat: add typed SupportedAlias parsing and per-type resolution

[iMicknl]

Closes #2224.

core:SupportedAliases is currently exposed as a raw, untyped list, so every consumer has to walk the attribute themselves — and, as #2224 describes, most will treat it as "one entry per type" and get duplicate behavior. A Somfy ogp:VenetianBlind reports up to six favorite1 slots for what is functionally a single "My position" preset.

What this adds

@define(kw_only=True)
class SupportedAlias:
    id: str
    type: str
    features: list[str] = field(factory=list)

Two Device methods:

• get_supported_aliases() -> list[SupportedAlias] — the slots exactly as reported, empty when the attribute is absent or not a list.
• get_most_featured_aliases() -> dict[str, SupportedAlias] — one alias per type, picking the id with the most features, ties broken by array order (first wins). This is the "simpler and sufficient" variant sketched at the end of core:SupportedAliases can list multiple entries with the same type (e.g. favorite1); add a helper to resolve the one the app would use #2224; the value is ready to pass straight to goToAlias.

Deliberately left out

• The required_features capability tiers (step 3 of the app's algorithm in core:SupportedAliases can list multiple entries with the same type (e.g. favorite1); add a helper to resolve the one the app would use #2224). Consumers that show one control per type — which is what the app does — already land on the most capable id via the most-featured pick, so the tiers add an API surface nobody currently needs. Easy to add later without breaking this signature.
• An OverkizAliasType enum. type stays str so unknown types survive parsing instead of being dropped. Home Assistant relies on this to log a warning and fall back to a generated name when it meets a type it has no translation for; dropping unknown entries would hide new alias types instead of surfacing them.

Naming note: #2224 floated get_most_featured_alias_by_type; I went with get_most_featured_aliases since the dict[str, ...] return already says "by type". Happy to rename.

id is normalized with str() because goToAlias is declared as taking a single STRING parameter on every server in docs/data, and attrs does not enforce the annotation. Every payload observed in docs/data and in the Home Assistant fixtures already reports ids as strings.

Tests

Six tests in tests/test_models.py::TestSupportedAliases covering the absent attribute, parsing, id normalization, most-featured resolution, array-order tie-breaking, and that one alias is kept per type. tests/test_models.py passes (184 tests).

Also documented under "Resolve supported aliases" in docs/device-control.md.

Downstream

home-assistant/core#175567 consumes this: it replaces hand-rolled dict-walking with get_most_featured_aliases(), which collapses the six duplicate "My position" buttons on the venetian blind in HA's own fixtures down to one.

[Copilot]

🟡 Changes recommended

Documentation incorrectly claims parity with the official app despite omitted capability-tier filtering.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds typed parsing and per-type deduplication for device-supported aliases.

Changes:

• Introduces SupportedAlias and Device alias helpers.
• Adds parsing and resolution tests.
• Documents alias resolution.

File summaries

File	Description
pyoverkiz/models.py	Implements typed alias parsing and selection.
tests/test_models.py	Tests parsing, normalization, and deduplication.
docs/device-control.md	Documents the new helpers.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.