Add availability API for addons

[mdegat01]

Proposed change

Add API that determines availability of an add-on for the current system. It always checks against the latest version in the store so it can be used to check availability prior to an update of an existing add-on or install of a new one.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality to the supervisor)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request: Document Supervisor's add-on availability api developers.home-assistant#2769
• Link to cli pull request:
• Link to client library pull request: Add addon availability API home-assistant-libs/python-supervisor-client#172

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Ruff (ruff format supervisor tests)
• Tests have been added to verify that the new code works.

If API endpoints or add-on configuration are added/changed:

• Documentation added/updated for developers.home-assistant.io
• CLI updated (if necessary)
• Client library updated (if necessary)

[Copilot]

Pull Request Overview

This PR adds a new API endpoint to check add-on availability for the current system. The endpoint validates whether an add-on can be installed or updated based on architecture compatibility, machine type support, and Home Assistant version requirements.

Key Changes

• Added /store/addons/{addon}/availability GET endpoint that validates add-on compatibility
• Implemented comprehensive test coverage for various availability scenarios including architecture mismatches, machine incompatibility, and version requirements
• Integrated the new endpoint into the API routing system

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
supervisor/api/store.py	Adds the new availability endpoint handler that extracts the addon and validates its availability
supervisor/api/init.py	Registers the new GET route for the availability endpoint
tests/api/test_store.py	Comprehensive test suite covering success cases and various failure scenarios for the availability API

[mdegat01]

@agners Reworked error to support specifying a key, message template and extra fields so we can make errors that are much more translation and client library friendly. Leveraged that for this work but this will require a pretty significant re-review and refactor of most of the errors in Supervisor going forward. As many should adopt this model.

[agners]

This makes our error handling much more translation friendly: The key can be used to look up translations, and since we now pass parameters as separate fields the messages can easily formatted on client side without the need to parse and reformat our pre-processed messages. This makes any key plus extra field combination part of the API, as in if we want to change fields in an error we need to introduce a new key.

[MartinHjelmare]

Does a Supervisor API user need to check the availability of an add-on before updating it? I'd expect that would happen automatically so no extra API call would be needed.

[agners]

Does a Supervisor user need to check the availability of an add-on before updating it? I'd expect that would happen automatically so no extra API call would be needed.

The problem is backups: If we simply raise an error on the actual update attempt, then the caller might already have created a backup. At least for the update flows under control by the hassio integration this will allow to first check availability, before taking a backup.

There is some more discussion in home-assistant/core#148954.

[MartinHjelmare]

Ok, that's good. I'd still expect the update call to raise an (the same) exception for an unavailable add-on.

[mdegat01]

@MartinHjelmare Good point. I believe it does because both call the same method but i'll also add the same test cases there to make sure.

[MartinHjelmare]

Looks good!