ghome-local-api 0.1.0__py3-none-any.whl

ghome_local_api/__init__.py

@@ -0,0 +1,66 @@
+"""Asynchronous client for the local API of Google Home devices."""
+
+from .client import GoogleHomeLocalClient, ResponseObserver, device_url
+from .const import DEFAULT_PORT, DEFAULT_TIMEOUT
+from .exceptions import (
+    AnswerTimeoutError,
+    CannotConnectError,
+    ClientRequestError,
+    ConnectionLostError,
+    GoogleHomeLocalError,
+    InvalidJsonError,
+    NotFoundError,
+    RequestError,
+    StatusError,
+    TokenRejectedError,
+    UnexpectedResponseError,
+)
+from .models import (
+    Alarm,
+    AlarmsAndTimers,
+    AlarmStatus,
+    AlarmVolumeReply,
+    BluetoothSighting,
+    BuildInfo,
+    DeleteResult,
+    DeviceInfo,
+    DoNotDisturbReply,
+    JsonObject,
+    JsonValue,
+    Timer,
+    TimerStatus,
+    UpdateInfo,
+)
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DEFAULT_TIMEOUT",
+    "Alarm",
+    "AlarmStatus",
+    "AlarmVolumeReply",
+    "AlarmsAndTimers",
+    "AnswerTimeoutError",
+    "BluetoothSighting",
+    "BuildInfo",
+    "CannotConnectError",
+    "ClientRequestError",
+    "ConnectionLostError",
+    "DeleteResult",
+    "DeviceInfo",
+    "DoNotDisturbReply",
+    "GoogleHomeLocalClient",
+    "GoogleHomeLocalError",
+    "InvalidJsonError",
+    "JsonObject",
+    "JsonValue",
+    "NotFoundError",
+    "RequestError",
+    "ResponseObserver",
+    "StatusError",
+    "Timer",
+    "TimerStatus",
+    "TokenRejectedError",
+    "UnexpectedResponseError",
+    "UpdateInfo",
+    "device_url",
+]

ghome_local_api/client.py

@@ -0,0 +1,481 @@
+"""The requests to a device's local API, over the caller's aiohttp session."""
+
+from collections.abc import Callable, Sequence
+from http import HTTPStatus
+import ipaddress
+
+from aiohttp import (
+    ClientConnectionError,
+    ClientError,
+    ClientPayloadError,
+    ClientResponse,
+    ClientSession,
+    ClientTimeout,
+)
+from aiohttp.client_exceptions import ClientConnectorError, ContentTypeError
+
+from .const import (
+    API_ENDPOINT_ALARM_DELETE,
+    API_ENDPOINT_ALARM_VOLUME,
+    API_ENDPOINT_ALARMS,
+    API_ENDPOINT_BLUETOOTH_RESULTS,
+    API_ENDPOINT_BLUETOOTH_SCAN,
+    API_ENDPOINT_BUILD_INFO,
+    API_ENDPOINT_DO_NOT_DISTURB,
+    API_ENDPOINT_EUREKA_INFO,
+    API_ENDPOINT_REBOOT,
+    API_ENDPOINT_UPDATE_INFO,
+    DEFAULT_PORT,
+    DEFAULT_TIMEOUT,
+    HEADER_CAST_LOCAL_AUTH,
+    HEADER_CONTENT_TYPE,
+    JSON_ALARM_VOLUME,
+    JSON_NOTIFICATIONS_ENABLED,
+)
+from .exceptions import (
+    AnswerTimeoutError,
+    CannotConnectError,
+    ClientRequestError,
+    ConnectionLostError,
+    InvalidJsonError,
+    NotFoundError,
+    RequestError,
+    StatusError,
+    TokenRejectedError,
+    UnexpectedResponseError,
+)
+from .models import (
+    AlarmsAndTimers,
+    AlarmVolumeReply,
+    BluetoothSighting,
+    BuildInfo,
+    DeleteResult,
+    DeviceInfo,
+    DoNotDisturbReply,
+    JsonObject,
+    JsonValue,
+    UpdateInfo,
+)
+
+# Called with the final response as soon as its status and headers have come, before
+# its body is read. It must not read, release or close the response, or raise.
+type ResponseObserver = Callable[[ClientResponse], None]
+
+
+def device_url(host: str, path: str, port: int = DEFAULT_PORT) -> str:
+    """Return the URL of a path on the device at this IP address, bracketing an IPv6 one.
+
+    Raise ValueError if the host isn't an IP address.
+    """
+    if isinstance(ipaddress.ip_address(host), ipaddress.IPv6Address):
+        host = f"[{host}]"
+    return f"https://{host}:{port}/{path}"
+
+
+def _request_error(
+    error: ClientError | TimeoutError, host: str, path: str, status: int | None
+) -> RequestError:
+    """Return the error for a request that failed with this exception."""
+    if isinstance(error, ClientConnectorError):
+        return CannotConnectError(host=host, path=path, status=status)
+    if isinstance(error, ClientConnectionError | ClientPayloadError):
+        return ConnectionLostError(host=host, path=path, status=status)
+    if isinstance(error, ClientError):
+        return ClientRequestError(host=host, path=path, status=status)
+    return AnswerTimeoutError(host=host, path=path, status=status)
+
+
+def _status_error(host: str, path: str, status: int, reason: str | None) -> StatusError:
+    """Return the error for an answer with a status other than 200."""
+    if status == HTTPStatus.UNAUTHORIZED:
+        return TokenRejectedError(host=host, path=path, status=status, reason=reason)
+    if status == HTTPStatus.NOT_FOUND:
+        return NotFoundError(host=host, path=path, status=status, reason=reason)
+    return StatusError(host=host, path=path, status=status, reason=reason)
+
+
+class GoogleHomeLocalClient:
+    """A client of the local API of Google Home devices, over the caller's session.
+
+    It keeps no state but the session and port: each call takes the device's IP
+    address, and its local auth token if the request needs one. The session must
+    accept the device's self-signed certificate and is never closed here. Nothing is
+    retried. Concurrent calls are independent and not ordered.
+    """
+
+    __slots__ = ("_port", "_session")
+
+    def __init__(self, session: ClientSession, *, port: int = DEFAULT_PORT) -> None:
+        """Create a client that sends its requests with this session, to this port."""
+        self._session = session
+        self._port = port
+
+    async def _send(
+        self,
+        host: str,
+        path: str,
+        *,
+        token: str | None,
+        method: str = "GET",
+        body: JsonObject | None = None,
+        timeout: float,
+        on_response: ResponseObserver | None,
+        read_body: bool = True,
+    ) -> JsonValue:
+        """Send a request and return the reply of its 200.
+
+        With a token, the reply of a body that isn't JSON is {}, and one that can't be
+        decoded raises InvalidJsonError. Without one, as for info, both are None.
+        Without read_body, the 200 is the whole answer and None is returned.
+        """
+        url = device_url(host, path, self._port)
+        client_timeout = ClientTimeout(total=timeout)
+        status: int | None = None
+        reply: JsonValue = None
+        try:
+            async with (
+                self._session.get(url, timeout=client_timeout)
+                if token is None
+                else self._session.request(
+                    method,
+                    url,
+                    json=body,
+                    headers={
+                        HEADER_CAST_LOCAL_AUTH: token,
+                        HEADER_CONTENT_TYPE: "application/json",
+                    },
+                    timeout=client_timeout,
+                )
+            ) as response:
+                status = response.status
+                if on_response is not None:
+                    on_response(response)
+                if status == HTTPStatus.OK and read_body:
+                    try:
+                        reply = await response.json()
+                    except ContentTypeError:
+                        reply = None if token is None else {}
+                    # ValueError includes JSONDecodeError and UnicodeDecodeError. Python's
+                    # json raises a plain one for an integer of more than 4300 digits, and
+                    # RecursionError for deep nesting. bytes.decode raises LookupError for
+                    # a charset that names a codec that isn't a text encoding, such as base64
+                    except (ValueError, RecursionError, LookupError) as error:
+                        if token is not None:
+                            raise InvalidJsonError(host=host, path=path) from error
+        except (ClientError, TimeoutError) as error:
+            raise _request_error(error, host, path, status) from error
+        if status != HTTPStatus.OK:
+            # Home Assistant's test mock of a response has no reason
+            raise _status_error(host, path, status, getattr(response, "reason", None))
+        return reply
+
+    async def _get_info(
+        self,
+        host: str,
+        path: str,
+        *,
+        timeout: float,
+        on_response: ResponseObserver | None,
+    ) -> JsonObject | None:
+        """Return the info of a 200, or None for a reply that isn't a JSON object."""
+        info = await self._send(
+            host, path, token=None, timeout=timeout, on_response=on_response
+        )
+        return info if isinstance(info, dict) else None
+
+    async def get_device_info(
+        self,
+        host: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> DeviceInfo | None:
+        """Return the device's ID, name and whether it has Google Assistant, without a token.
+
+        Return None for a 200 whose reply isn't a JSON object, and raise StatusError
+        for another status.
+        """
+        info = await self._get_info(
+            host, API_ENDPOINT_EUREKA_INFO, timeout=timeout, on_response=on_response
+        )
+        return DeviceInfo.from_json(info) if info is not None else None
+
+    async def get_info_status(
+        self,
+        host: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> int:
+        """Return the status of the device's answer when asked for its info, without a token.
+
+        A 200 counts once its body has come whole, another status as soon as it comes,
+        and neither is undone by a failure while the answer is released. Raise a
+        RequestError if no status counts: with .status 200 if the body broke off, else
+        None. Redirects aren't followed, so their status is returned.
+        """
+        path = API_ENDPOINT_EUREKA_INFO
+        url = device_url(host, path, self._port)
+        observed: int | None = None
+        status: int | None = None
+        try:
+            async with self._session.get(
+                url, timeout=ClientTimeout(total=timeout), allow_redirects=False
+            ) as response:
+                observed = response.status
+                if on_response is not None:
+                    on_response(response)
+                if observed == HTTPStatus.OK:
+                    await response.read()
+                status = observed
+        except (ClientError, TimeoutError) as error:
+            if status is None:
+                raise _request_error(error, host, path, observed) from error
+        return status
+
+    async def get_build_info(
+        self,
+        host: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> BuildInfo | None:
+        """Return the device's firmware versions, without a token.
+
+        Return None for a 200 whose reply isn't a JSON object, and raise StatusError
+        for another status.
+        """
+        info = await self._get_info(
+            host, API_ENDPOINT_BUILD_INFO, timeout=timeout, on_response=on_response
+        )
+        return BuildInfo.from_json(info) if info is not None else None
+
+    async def get_update_info(
+        self,
+        host: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> UpdateInfo | None:
+        """Return whether the device has a firmware update waiting, its uptime and Wi-Fi.
+
+        No token is needed. Return None for a 200 whose reply isn't a JSON object, and
+        raise StatusError for another status.
+        """
+        info = await self._get_info(
+            host, API_ENDPOINT_UPDATE_INFO, timeout=timeout, on_response=on_response
+        )
+        return UpdateInfo.from_json(info) if info is not None else None
+
+    async def get_alarms_and_timers(
+        self,
+        host: str,
+        token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> AlarmsAndTimers:
+        """Return the device's alarms and timers.
+
+        Raise UnexpectedResponseError if the reply doesn't have a list of each, or any
+        item can't be read.
+        """
+        reply = await self._send(
+            host,
+            API_ENDPOINT_ALARMS,
+            token=token,
+            timeout=timeout,
+            on_response=on_response,
+        )
+        if (parsed := AlarmsAndTimers.from_json(reply)) is None:
+            raise UnexpectedResponseError(
+                host=host, path=API_ENDPOINT_ALARMS, body=reply
+            )
+        return parsed
+
+    async def delete_alarms_and_timers(
+        self,
+        host: str,
+        token: str,
+        ids: Sequence[str],
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> DeleteResult:
+        """Ask the device to delete the alarms and timers with these IDs in one request.
+
+        Only a confirmed result says they're deleted. Once the request is sent, a
+        failure leaves it unknown whether they were.
+        """
+        reply = await self._send(
+            host,
+            API_ENDPOINT_ALARM_DELETE,
+            token=token,
+            method="POST",
+            body={"ids": list(ids)},
+            timeout=timeout,
+            on_response=on_response,
+        )
+        return DeleteResult(raw=reply)
+
+    async def get_alarm_volume(
+        self,
+        host: str,
+        token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> AlarmVolumeReply:
+        """Return the reply with the device's alarm volume, whatever JSON it is."""
+        reply = await self._send(
+            host,
+            API_ENDPOINT_ALARM_VOLUME,
+            token=token,
+            method="POST",
+            timeout=timeout,
+            on_response=on_response,
+        )
+        return AlarmVolumeReply(raw=reply)
+
+    async def set_alarm_volume(
+        self,
+        host: str,
+        token: str,
+        level: float,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> AlarmVolumeReply:
+        """Set the device's alarm volume, a fraction such as 0.7, and return its reply."""
+        reply = await self._send(
+            host,
+            API_ENDPOINT_ALARM_VOLUME,
+            token=token,
+            method="POST",
+            body={JSON_ALARM_VOLUME: level},
+            timeout=timeout,
+            on_response=on_response,
+        )
+        return AlarmVolumeReply(raw=reply)
+
+    async def get_do_not_disturb(
+        self,
+        host: str,
+        token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> DoNotDisturbReply:
+        """Return the reply with the device's Do Not Disturb setting, whatever JSON it is."""
+        reply = await self._send(
+            host,
+            API_ENDPOINT_DO_NOT_DISTURB,
+            token=token,
+            method="POST",
+            timeout=timeout,
+            on_response=on_response,
+        )
+        return DoNotDisturbReply(raw=reply)
+
+    async def set_do_not_disturb(
+        self,
+        host: str,
+        token: str,
+        enabled: bool,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> DoNotDisturbReply:
+        """Turn Do Not Disturb on or off, and return the device's reply.
+
+        The device is sent whether notifications are on, the opposite.
+        """
+        reply = await self._send(
+            host,
+            API_ENDPOINT_DO_NOT_DISTURB,
+            token=token,
+            method="POST",
+            body={JSON_NOTIFICATIONS_ENABLED: not enabled},
+            timeout=timeout,
+            on_response=on_response,
+        )
+        return DoNotDisturbReply(raw=reply)
+
+    async def reboot(
+        self,
+        host: str,
+        token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> None:
+        """Ask the device to reboot.
+
+        Its 200 is the whole answer: the rest isn't read, as the device may go down
+        while sending it. A device answers so even if it doesn't support rebooting.
+        """
+        await self._send(
+            host,
+            API_ENDPOINT_REBOOT,
+            token=token,
+            method="POST",
+            # "now" means reboot; "fdr", a factory reset, isn't offered
+            body={"params": "now"},
+            timeout=timeout,
+            on_response=on_response,
+            read_body=False,
+        )
+
+    async def start_bluetooth_scan(
+        self,
+        host: str,
+        token: str,
+        *,
+        duration: int,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> None:
+        """Start a Bluetooth scan that clears the results of the previous one.
+
+        The device scans for up to duration seconds, then stops on its own.
+        """
+        await self._send(
+            host,
+            API_ENDPOINT_BLUETOOTH_SCAN,
+            token=token,
+            method="POST",
+            body={"enable": True, "clear_results": True, "timeout": duration},
+            timeout=timeout,
+            on_response=on_response,
+        )
+
+    async def get_bluetooth_scan_results(
+        self,
+        host: str,
+        token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        on_response: ResponseObserver | None = None,
+    ) -> tuple[BluetoothSighting, ...]:
+        """Return the Bluetooth devices the device heard since its scan started.
+
+        Rows that can't be read are left out, so a reply of only such rows looks like
+        a scan that heard nothing. Raise UnexpectedResponseError if the reply isn't a
+        list.
+        """
+        reply = await self._send(
+            host,
+            API_ENDPOINT_BLUETOOTH_RESULTS,
+            token=token,
+            timeout=timeout,
+            on_response=on_response,
+        )
+        if not isinstance(reply, list):
+            raise UnexpectedResponseError(
+                host=host, path=API_ENDPOINT_BLUETOOTH_RESULTS, body=reply
+            )
+        return tuple(
+            sighting
+            for row in reply
+            if (sighting := BluetoothSighting.from_json(row)) is not None
+        )

ghome_local_api/const.py

@@ -0,0 +1,34 @@
+"""The device's port, paths, header names and JSON keys, and the default timeout."""
+
+from typing import Final
+
+DEFAULT_PORT: Final = 8443
+# How long a device has to answer a request, in seconds. A busy device can take
+# more than 2 seconds.
+DEFAULT_TIMEOUT: Final = 5.0
+
+# Paths that need the device's local auth token
+API_ENDPOINT_ALARMS: Final = "setup/assistant/alarms"
+API_ENDPOINT_ALARM_DELETE: Final = "setup/assistant/alarms/delete"
+API_ENDPOINT_ALARM_VOLUME: Final = "setup/assistant/alarms/volume"
+API_ENDPOINT_REBOOT: Final = "setup/reboot"
+API_ENDPOINT_DO_NOT_DISTURB: Final = "setup/assistant/notifications"
+API_ENDPOINT_BLUETOOTH_SCAN: Final = "setup/bluetooth/scan"
+API_ENDPOINT_BLUETOOTH_RESULTS: Final = "setup/bluetooth/scan_results"
+
+# Paths that answer without a token. The first identifies a device and shows
+# whether it has Google Assistant.
+API_ENDPOINT_EUREKA_INFO: Final = "setup/eureka_info?params=name,device_info"
+# The device's firmware versions. A display's system version is only here.
+API_ENDPOINT_BUILD_INFO: Final = "setup/eureka_info?params=build_info"
+# Without params, the info has whether the device has a firmware update waiting,
+# which no params give, and its Wi-Fi network and signal strength.
+API_ENDPOINT_UPDATE_INFO: Final = "setup/eureka_info"
+
+HEADER_CAST_LOCAL_AUTH: Final = "cast-local-authorization-token"
+HEADER_CONTENT_TYPE: Final = "content-type"
+
+JSON_ALARM: Final = "alarm"
+JSON_TIMER: Final = "timer"
+JSON_NOTIFICATIONS_ENABLED: Final = "notifications_enabled"
+JSON_ALARM_VOLUME: Final = "volume"

ghome_local_api/exceptions.py

@@ -0,0 +1,112 @@
+"""The errors of a request to a device.
+
+Their messages name the device's host, the path and any status, never its token, a
+reply or the reason text a device sends with its status. The aiohttp exception chained
+as __cause__ isn't sanitised: it can hold the request headers, with the token.
+"""
+
+from .models import JsonValue
+
+
+class GoogleHomeLocalError(Exception):
+    """A request to a device got no answer, or not the one expected."""
+
+    def __init__(self, message: str, *, host: str, path: str) -> None:
+        """Create the error of a request to this host and path."""
+        super().__init__(message)
+        self.host = host
+        self.path = path
+
+
+class RequestError(GoogleHomeLocalError):
+    """No usable answer came: __cause__ is the aiohttp exception or TimeoutError.
+
+    The status is that of an answer that came before the failure, such as a 200 whose
+    body broke off, else None.
+    """
+
+    def __init__(self, *, host: str, path: str, status: int | None) -> None:
+        """Create the error of a request whose answer, if any, had this status."""
+        super().__init__(
+            f"{host} gave no usable answer to {path}"
+            + (f" after answering {status}" if status is not None else ""),
+            host=host,
+            path=path,
+        )
+        self.status = status
+
+
+class CannotConnectError(RequestError):
+    """The connection to the device failed, for example because it is offline."""
+
+
+class ConnectionLostError(RequestError):
+    """The connection closed or the answer broke off; the device may have acted."""
+
+
+class AnswerTimeoutError(RequestError):
+    """The device didn't answer in time; it may have acted."""
+
+
+class ClientRequestError(RequestError):
+    """aiohttp failed the request otherwise, such as after too many redirects."""
+
+
+class StatusError(GoogleHomeLocalError):
+    """The device answered with a status other than 200.
+
+    The reason is the text the device sent with the status, such as "Not Found". It
+    comes from the device, so it is left out of the message; treat it as untrusted.
+    """
+
+    def __init__(
+        self, *, host: str, path: str, status: int, reason: str | None
+    ) -> None:
+        """Create the error of an answer with this status and reason."""
+        super().__init__(
+            f"{host} answered {path} with HTTP {status}", host=host, path=path
+        )
+        self.status = status
+        self.reason = reason
+
+
+class TokenRejectedError(StatusError):
+    """The device answered 401: it rejected the token."""
+
+
+class NotFoundError(StatusError):
+    """The device answered 404, for example while it is starting or if it lacks the endpoint."""
+
+
+class InvalidJsonError(GoogleHomeLocalError):
+    """The device answered 200 with a body that says it's JSON but can't be decoded.
+
+    __cause__ is the decoder's error: a ValueError (such as JSONDecodeError or
+    UnicodeDecodeError), a RecursionError, or a LookupError for a charset that names a
+    codec that isn't a text encoding.
+    """
+
+    def __init__(self, *, host: str, path: str) -> None:
+        """Create the error of a reply that isn't valid JSON."""
+        super().__init__(
+            f"{host} answered {path} with JSON that can't be decoded",
+            host=host,
+            path=path,
+        )
+        self.status = 200
+
+
+class UnexpectedResponseError(GoogleHomeLocalError):
+    """The device answered 200 with JSON that isn't in the expected form.
+
+    The body is the decoded reply. It holds device data, so don't log it as it is.
+    """
+
+    def __init__(self, *, host: str, path: str, body: JsonValue) -> None:
+        """Create the error of a reply that isn't in the expected form."""
+        super().__init__(
+            f"{host} answered {path} with a reply that isn't in the expected form",
+            host=host,
+            path=path,
+        )
+        self.body = body

ghome_local_api/models.py

@@ -0,0 +1,372 @@
+"""Typed replies of the local API, read with the rules ha-google-home applies to them."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+import math
+from typing import Final, Self, override
+
+from .const import JSON_ALARM, JSON_ALARM_VOLUME, JSON_NOTIFICATIONS_ENABLED, JSON_TIMER
+
+type JsonValue = (
+    None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]
+)
+type JsonObject = Mapping[str, JsonValue]
+
+# The fields of a device's build info that are kept: its versions and release channel
+BUILD_INFO_FIELDS: Final = (
+    "cast_build_revision",
+    "system_build_number",
+    "release_track",
+    "preview_channel_state",
+)
+
+
+def _number(value: JsonValue) -> int | float | None:
+    """Return a JSON number that is whole or finite, else None.
+
+    True and false aren't numbers. A whole number isn't turned into a float to check
+    it, so one too large to convert is left for its conversion to reject.
+    """
+    if isinstance(value, float):
+        return value if math.isfinite(value) else None
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _whole(value: JsonValue) -> int | None:
+    """Return a JSON whole number, but not true or false, else None."""
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _parse_all[T](
+    items: list[JsonValue], parse: Callable[[JsonValue], T | None]
+) -> tuple[T, ...] | None:
+    """Return every item parsed, or None if any can't be."""
+    parsed = []
+    for item in items:
+        if (value := parse(item)) is None:
+            return None
+        parsed.append(value)
+    return tuple(parsed)
+
+
+class AlarmStatus(Enum):
+    """The status of an alarm."""
+
+    NONE = 0
+    SET = 1
+    RINGING = 2
+    SNOOZED = 3
+    INACTIVE = 4
+    MISSED = 5
+    # A status this package doesn't know, such as one that newer firmware adds
+    UNKNOWN = -1
+
+    @classmethod
+    @override
+    def _missing_(cls, value: object) -> Self:
+        """Return UNKNOWN for a status this package doesn't know."""
+        return cls.UNKNOWN
+
+
+class TimerStatus(Enum):
+    """The status of a timer."""
+
+    NONE = 0
+    SET = 1
+    PAUSED = 2
+    RINGING = 3
+    # A status this package doesn't know, such as one that newer firmware adds
+    UNKNOWN = -1
+
+    @classmethod
+    @override
+    def _missing_(cls, value: object) -> Self:
+        """Return UNKNOWN for a status this package doesn't know."""
+        return cls.UNKNOWN
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Alarm:
+    """An alarm, as the device sent it."""
+
+    id: str
+    # In milliseconds since the epoch
+    fire_time: int | float
+    status: AlarmStatus
+    label: JsonValue
+    recurrence: JsonValue
+
+    @classmethod
+    def from_json(cls, item: JsonValue) -> Self | None:
+        """Return the alarm, or None if it lacks its ID, a whole-number status or a fire time.
+
+        A missing label or recurrence is None.
+        """
+        if not isinstance(item, dict):
+            return None
+        alarm_id, status = item.get("id"), _whole(item.get("status"))
+        fire_time = _number(item.get("fire_time"))
+        if not isinstance(alarm_id, str) or status is None or fire_time is None:
+            return None
+        return cls(
+            id=alarm_id,
+            fire_time=fire_time,
+            status=AlarmStatus(status),
+            label=item.get("label"),
+            recurrence=item.get("recurrence"),
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Timer:
+    """A timer, as the device sent it."""
+
+    id: str
+    # In milliseconds
+    original_duration: int | float
+    # In milliseconds since the epoch; a paused timer may have none
+    fire_time: int | float | None
+    # In milliseconds
+    remaining_duration: int | float | None
+    status: TimerStatus
+    label: JsonValue
+
+    @classmethod
+    def from_json(cls, item: JsonValue) -> Self | None:
+        """Return the timer, or None if it lacks its ID, a whole-number status or its duration.
+
+        A fire time or remaining duration may be missing or null, which gives None,
+        but not another value that isn't a number.
+        """
+        if not isinstance(item, dict):
+            return None
+        timer_id, status = item.get("id"), _whole(item.get("status"))
+        duration = _number(item.get("original_duration"))
+        if not isinstance(timer_id, str) or status is None or duration is None:
+            return None
+        fire_time, remaining = item.get("fire_time"), item.get("remaining_duration")
+        if any(
+            value is not None and _number(value) is None
+            for value in (fire_time, remaining)
+        ):
+            return None
+        return cls(
+            id=timer_id,
+            original_duration=duration,
+            fire_time=_number(fire_time),
+            remaining_duration=_number(remaining),
+            status=TimerStatus(status),
+            label=item.get("label"),
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AlarmsAndTimers:
+    """A device's alarms and timers, with the reply they came in."""
+
+    alarms: tuple[Alarm, ...]
+    timers: tuple[Timer, ...]
+    raw: JsonValue
+
+    @classmethod
+    def from_json(cls, body: JsonValue) -> Self | None:
+        """Return the alarms and timers of a reply, or None if it can't be read whole.
+
+        The reply needs a list of alarms and a list of timers, with every item
+        readable, so a reply is never read only in part.
+        """
+        if not isinstance(body, dict):
+            return None
+        alarms, timers = body.get(JSON_ALARM), body.get(JSON_TIMER)
+        if not isinstance(alarms, list) or not isinstance(timers, list):
+            return None
+        parsed_alarms = _parse_all(alarms, Alarm.from_json)
+        parsed_timers = _parse_all(timers, Timer.from_json)
+        if parsed_alarms is None or parsed_timers is None:
+            return None
+        return cls(alarms=parsed_alarms, timers=parsed_timers, raw=body)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeleteResult:
+    """The reply to a request to delete alarms or timers."""
+
+    raw: JsonValue
+
+    @property
+    def confirmed(self) -> bool:
+        """Return whether the reply confirms the delete: only {"success": true} does."""
+        return isinstance(self.raw, dict) and self.raw.get("success") is True
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AlarmVolumeReply:
+    """The reply to a request for the alarm volume or to set it; any JSON value."""
+
+    raw: JsonValue
+
+    @property
+    def has_volume(self) -> bool:
+        """Return whether the reply is an object with a volume."""
+        return isinstance(self.raw, dict) and JSON_ALARM_VOLUME in self.raw
+
+    def percent(self) -> int:
+        """Return the volume as a whole percentage, from the fraction the device sends.
+
+        Raise ValueError if the reply has no volume or it isn't a number, such as
+        "loud" or NaN, and OverflowError if it is infinite.
+        """
+        if not isinstance(self.raw, dict) or JSON_ALARM_VOLUME not in self.raw:
+            raise ValueError("The reply has no alarm volume")
+        return round(float(str(self.raw[JSON_ALARM_VOLUME])) * 100)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DoNotDisturbReply:
+    """The reply to a request for the Do Not Disturb setting or to set it; any JSON value."""
+
+    raw: JsonValue
+
+    @property
+    def enabled(self) -> bool | None:
+        """Return whether Do Not Disturb is on, or None if the reply doesn't say.
+
+        The device sends whether notifications are on, the opposite.
+        """
+        if isinstance(self.raw, dict) and JSON_NOTIFICATIONS_ENABLED in self.raw:
+            return not bool(self.raw[JSON_NOTIFICATIONS_ENABLED])
+        return None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeviceInfo:
+    """What a device reports about itself without a token."""
+
+    # Google's ID for the device, as sent. Google's device list may use other case.
+    cloud_device_id: str | None
+    name: JsonValue
+    # Whether its list of features leaves out Google Assistant
+    lacks_assistant: bool
+
+    @classmethod
+    def from_json(cls, info: JsonObject) -> Self:
+        """Return the device's info from its reply.
+
+        Google and Nest speakers and displays report assistant_supported as true. A
+        Chromecast Audio leaves it out of its list of features, so a missing key
+        counts as lacking it, as does false. No list, an empty one, or any other
+        value, such as 0, null or "false", says nothing either way.
+        """
+        device_info = info.get("device_info")
+        cloud_device_id, capabilities = (
+            (device_info.get("cloud_device_id"), device_info.get("capabilities"))
+            if isinstance(device_info, dict)
+            else (None, None)
+        )
+        return cls(
+            cloud_device_id=(
+                cloud_device_id
+                if isinstance(cloud_device_id, str) and cloud_device_id
+                else None
+            ),
+            name=info.get("name"),
+            lacks_assistant=(
+                isinstance(capabilities, dict)
+                and bool(capabilities)
+                and capabilities.get("assistant_supported", False) is False
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BuildInfo:
+    """A device's firmware versions and release channel."""
+
+    # The BUILD_INFO_FIELDS that it sent, or None if it sent no build info object
+    fields: JsonObject | None
+
+    @classmethod
+    def from_json(cls, info: JsonObject) -> Self:
+        """Return the build info from the reply."""
+        build_info = info.get("build_info")
+        return cls(
+            fields=(
+                {
+                    field: build_info[field]
+                    for field in BUILD_INFO_FIELDS
+                    if field in build_info
+                }
+                if isinstance(build_info, dict)
+                else None
+            )
+        )
+
+    @property
+    def firmware_version(self) -> str | None:
+        """Return the firmware version in the form Google publishes for the device.
+
+        A display reports its system version, such as 31.20260101.103.1234567, as its
+        system build number. A speaker or Chromecast Audio reports only a build there,
+        the last part of its Cast version, such as 3.77.512345, which is the one
+        Google publishes for it.
+        """
+        fields = self.fields or {}
+        system = fields.get("system_build_number")
+        cast = fields.get("cast_build_revision")
+        if isinstance(system, str) and "." in system:
+            return system
+        if isinstance(cast, str) and cast:
+            return cast
+        return system if isinstance(system, str) and system else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UpdateInfo:
+    """Whether a device has a firmware update waiting, how long it has been up, and its Wi-Fi."""
+
+    # In seconds; a finite number that isn't negative
+    uptime: int | float | None
+    # Only the JSON true or false
+    has_update: bool | None
+    ssid: str | None
+    # In dBm; a JSON number, but not true or false. A Nest Hub sends none.
+    signal_level: int | float | None
+
+    @classmethod
+    def from_json(cls, info: JsonObject) -> Self:
+        """Return the update info; a field the reply leaves out or sends otherwise is None."""
+        uptime = _number(info.get("uptime"))
+        has_update, ssid = info.get("has_update"), info.get("ssid")
+        signal = info.get("signal_level")
+        return cls(
+            uptime=uptime if uptime is not None and uptime >= 0 else None,
+            has_update=has_update if isinstance(has_update, bool) else None,
+            ssid=ssid if isinstance(ssid, str) and ssid else None,
+            signal_level=(
+                signal
+                if isinstance(signal, int | float) and not isinstance(signal, bool)
+                else None
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BluetoothSighting:
+    """A Bluetooth device that a scan heard."""
+
+    mac_address: str
+    rssi: int
+
+    @classmethod
+    def from_json(cls, row: JsonValue) -> Self | None:
+        """Return the sighting, or None for a row without a string address and an integer RSSI.
+
+        JSON true passes as an RSSI, as it does in ha-google-home.
+        """
+        if not isinstance(row, dict):
+            return None
+        mac_address, rssi = row.get("mac_address"), row.get("rssi")
+        if not isinstance(mac_address, str) or not isinstance(rssi, int):
+            return None
+        return cls(mac_address=mac_address, rssi=rssi)

ghome_local_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: ghome-local-api
+Version: 0.1.0
+Summary: Asynchronous client for the local API of Google Home devices
+Project-URL: Homepage, https://github.com/KapJI/ghome-local-api
+Project-URL: Bug Tracker, https://github.com/KapJI/ghome-local-api/issues
+Project-URL: Release Notes, https://github.com/KapJI/ghome-local-api/releases
+Author-email: Ruslan Sayfutdinov <ruslan@sayfutdinov.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.14.4
+Description-Content-Type: text/markdown
+
+# ghome-local-api
+
+[![Coverage](https://codecov.io/gh/KapJI/ghome-local-api/graph/badge.svg)](https://app.codecov.io/gh/KapJI/ghome-local-api)
+
+An asynchronous Python client for the local API of Google Home devices, moved out of [ha-google-home](https://github.com/leikoilja/ha-google-home).
+
+It reads and deletes alarms and timers, reads and sets the alarm volume and Do Not Disturb, reboots a device, asks it about itself and its firmware, and runs its Bluetooth scans. It is a thin protocol client: it sends one request per call over your [aiohttp](https://docs.aiohttp.org/) session and returns typed replies. It keeps no state, retries nothing and doesn't log.
+
+## Status
+
+Versions before 1.0.0 may still change the API.
+
+These are unofficial endpoints: Google doesn't document them and can change them in a firmware update. Not every device has every endpoint. One that doesn't usually answers 404, which raises `NotFoundError`, but some refuse the connection instead, which raises `CannotConnectError`. A device that is starting can also answer 404 for a while.
+
+## What you need
+
+- Python 3.12 or newer, and aiohttp 3.14.4 or newer.
+- The device's IP address. A host name raises `ValueError`.
+- For most calls, the device's current local auth token. This package doesn't get tokens: [glocaltokens](https://github.com/leikoilja/glocaltokens) does. The info calls need no token.
+
+## Install
+
+```console
+$ pip install ghome-local-api
+```
+
+## Quickstart
+
+This prints a device's alarms and timers. It changes nothing on the device.
+
+```python
+import asyncio
+from datetime import UTC, datetime
+
+import aiohttp
+
+from ghome_local_api import GoogleHomeLocalClient
+
+
+async def main() -> None:
+    # The devices use self-signed certificates
+    connector = aiohttp.TCPConnector(ssl=False)
+    async with aiohttp.ClientSession(connector=connector) as session:
+        client = GoogleHomeLocalClient(session)
+        reply = await client.get_alarms_and_timers(
+            "192.168.1.20", "YOUR_LOCAL_AUTH_TOKEN"
+        )
+        for alarm in reply.alarms:
+            # Times are in milliseconds since the epoch
+            fires = datetime.fromtimestamp(alarm.fire_time / 1000, UTC)
+            print(alarm.id, alarm.status.name, fires)
+        for timer in reply.timers:
+            print(timer.id, timer.status.name, timer.remaining_duration)
+
+
+asyncio.run(main())
+```
+
+You open and close the session; the client never closes it. `ssl=False` accepts the device's self-signed certificate but also turns off certificate checks, so a device on your network can't be told from an impostor that receives the token. Use it only on a network you trust.
+
+## Calls
+
+Each call takes the device's IP address first, then its token if it needs one. Every call also takes `timeout` (seconds, default 5) and `on_response` (see [Seeing the answer early](#seeing-the-answer-early)).
+
+| Call                                                                          | Returns                                                                                                                                                                                |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_alarms_and_timers(host, token)`                                          | `AlarmsAndTimers`: `alarms` and `timers`, with times in milliseconds as the device sent them                                                                                           |
+| `delete_alarms_and_timers(host, token, ids)`                                  | `DeleteResult`: `confirmed` is true only if the device replied `{"success": true}`                                                                                                     |
+| `get_alarm_volume(host, token)`, `set_alarm_volume(host, token, level)`       | `AlarmVolumeReply`: `has_volume` and `percent()`. `level` is a fraction, such as `0.7`                                                                                                 |
+| `get_do_not_disturb(host, token)`, `set_do_not_disturb(host, token, enabled)` | `DoNotDisturbReply`: `enabled`, or `None` if the reply doesn't say                                                                                                                     |
+| `reboot(host, token)`                                                         | `None` once the device answers 200, which it does even if it can't reboot                                                                                                              |
+| `start_bluetooth_scan(host, token, duration=...)`                             | `None`. The device scans for up to `duration` seconds, clearing the last scan's results                                                                                                |
+| `get_bluetooth_scan_results(host, token)`                                     | a tuple of `BluetoothSighting(mac_address, rssi)`. Rows without a string address and an integer RSSI are left out, so a reply of only such rows looks like a scan that heard nothing   |
+| `get_device_info(host)`                                                       | `DeviceInfo`: `cloud_device_id`, `name` and `lacks_assistant`, or `None` if the reply isn't a JSON object                                                                              |
+| `get_build_info(host)`                                                        | `BuildInfo`: `fields` and `firmware_version`, or `None` as above                                                                                                                       |
+| `get_update_info(host)`                                                       | `UpdateInfo`: `uptime`, `has_update`, `ssid` and `signal_level`, or `None` as above                                                                                                    |
+| `get_info_status(host)`                                                       | the HTTP status of the info request, without following redirects. A 200 counts only once its whole body has come; if the body breaks off, it raises a `RequestError` with `status` 200 |
+
+An alarm or timer status that this package doesn't know is `UNKNOWN`. An alarms reply without a list of alarms and a list of timers, or with any item that can't be read, raises `UnexpectedResponseError`, so you never get only part of the reply.
+
+The settings replies accept any JSON. Their `raw` attribute holds the decoded reply, and their helpers never raise `TypeError` for its shape. `percent()` raises `ValueError` if there is no volume or it isn't a number, and `OverflowError` if it is infinite.
+
+## Errors
+
+All errors derive from `GoogleHomeLocalError` and have `host` and `path` attributes.
+
+| Error                     | When                                                                                                                                                                  |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CannotConnectError`      | the connection failed, for example because the device is offline                                                                                                      |
+| `ConnectionLostError`     | the connection closed or the answer broke off                                                                                                                         |
+| `AnswerTimeoutError`      | the device didn't answer within `timeout`                                                                                                                             |
+| `ClientRequestError`      | aiohttp failed the request otherwise, for example after too many redirects                                                                                            |
+| `TokenRejectedError`      | the device answered 401: get a new token                                                                                                                              |
+| `NotFoundError`           | the device answered 404                                                                                                                                               |
+| `StatusError`             | any other status than 200. It has `status`, and `reason`, the text the device sent with the status, which its message leaves out. The two errors above derive from it |
+| `InvalidJsonError`        | a 200 whose JSON can't be decoded. The info calls return `None` instead                                                                                               |
+| `UnexpectedResponseError` | an alarms or Bluetooth results reply in another form. It has the reply as `body`                                                                                      |
+
+The first four derive from `RequestError`. Its `__cause__` is aiohttp's exception or `TimeoutError`, and its `status` is the status of an answer that came before the failure, such as a 200 whose body broke off, or `None`.
+
+Other exceptions pass through unchanged, including `asyncio.CancelledError`, `ValueError` for a host that isn't an IP address, and what `on_response` raises, unless that is an aiohttp `ClientError` or `TimeoutError`, which is classified like a failure of the request.
+
+## Timeouts, cancellation and repeated requests
+
+- Each call's `timeout` replaces the session's timeout for that request.
+- Cancelling a call raises `CancelledError` once its response is released. If you wrap a call in your own `asyncio.timeout`, you get `TimeoutError`, not a package error.
+- An action that is cancelled, times out or loses its connection after it was sent may still have been carried out. Check the device's state before you send it again.
+- The package retries nothing. After a lost connection, aiohttp may send a GET again once (`get_alarms_and_timers`, `get_bluetooth_scan_results` and the info calls), but never a POST.
+- Redirects are followed, except by `get_info_status`. A 307 or 308 answer to an action makes aiohttp send the same POST to the new location; a 301, 302 or 303 makes it send a GET there.
+
+## Session requirements
+
+The client calls `session.request(...)` or `session.get(...)` with only the URL, headers, JSON body, timeout and, for `get_info_status`, `allow_redirects=False`. Your session needs:
+
+- a connector that accepts the device's self-signed certificate;
+- `raise_for_status` unset;
+- no middleware that sends requests again.
+
+The client reads JSON with `response.json()`, so your session's response class decides how JSON is decoded. With aiohttp's default class, Python's `json` module decodes `NaN`, `Infinity` and `1e999`, so `percent()` raises for them, and a huge integer alarm status is `UNKNOWN`. Home Assistant's session decodes with orjson, which rejects the first three (`InvalidJsonError`) and reads a huge integer as a float, which makes the alarms reply unreadable. Python's `json` module also raises `ValueError` for an integer of more than 4300 digits (Python's default limit) and `RecursionError` for very deeply nested JSON. Before parsing, aiohttp's `ClientResponse.json()` decodes the body as text with the charset from the response's `Content-Type`, so a charset that names a Python codec that isn't a text encoding, such as `charset=base64`, raises `LookupError`. The client treats any `ValueError`, `RecursionError` or `LookupError` from decoding as JSON that can't be decoded, which also covers `json.JSONDecodeError`, `UnicodeDecodeError` and orjson's errors. Decoders that raise something else for a body they can't decode aren't supported.
+
+## Seeing the answer early
+
+`on_response` is called once per call with aiohttp's response, as soon as the status and headers of the final response have come and before the body is read. It isn't called if no response comes. Use it to act on the status as early as possible. For example, ha-google-home notes at a 200 that the device accepted its token, so cancelling the call while the body is read doesn't undo that. It must not read, release or close the response. What it raises leaves the call, and an aiohttp `ClientError` or `TimeoutError` is classified like a failure of the request.
+
+## Sensitive data
+
+The client holds no token: you pass it to each call. Error messages name the host, path and status, but not the token, the reply or the device's reason text. Some objects do carry sensitive data:
+
+- the aiohttp exception in `__cause__` can hold the request, including the token header;
+- a redirect that aiohttp follows sends the token header to the new location, even on another host: aiohttp removes only standard credential headers, such as `Authorization`, when the host changes;
+- `raw`, `UnexpectedResponseError.body`, `StatusError.reason` and the response passed to `on_response` hold what the device sent, such as alarm labels and device IDs.
+
+Don't log or store these objects whole.
+
+## Origin
+
+The client was moved from ha-google-home at commit [`0e3febad86d6adf777b97b05452d5d841c3edfa8`](https://github.com/leikoilja/ha-google-home/tree/0e3febad86d6adf777b97b05452d5d841c3edfa8): the requests from `custom_components/google_home/api.py`, `device_info.py` and `bluetooth.py`, the reply rules from `models.py`, `api.py`, `device_info.py`, `account.py` and `bluetooth.py`, and the paths and keys from `const.py`.
+
+## License
+
+MIT, see [LICENSE](https://github.com/KapJI/ghome-local-api/blob/main/LICENSE). Its `Copyright (c) 2020 Ilja Leiko` notice covers the client code moved from ha-google-home.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/KapJI/ghome-local-api/blob/main/CONTRIBUTING.md).

ghome_local_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ghome_local_api/__init__.py,sha256=CQ-2HOJx4og_o9CziV1oqyUgiBRrInhqrUi4orLt-y8,1407
+ghome_local_api/client.py,sha256=wgWOGuNdHwdqeC1LC6_iedJC-kk7ZPNMJpypcjkCSC4,16608
+ghome_local_api/const.py,sha256=spbGoZ7B5jJUOxtsi6USAjCIUEDqw_P-bCNzj3s0s6k,1554
+ghome_local_api/exceptions.py,sha256=WBvt88zHQl9shSBgXvcAi2-iKbqGgdx42FwVu10l06U,3865
+ghome_local_api/models.py,sha256=fwlfeNEdseR865d-c6ljAEzAfH7zz7KokdU2K7YvG6Q,12749
+ghome_local_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ghome_local_api-0.1.0.dist-info/METADATA,sha256=PPR50MpGjonX_v9LeafLAp1MWCl05X5jHCVFKUh3ht0,14863
+ghome_local_api-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ghome_local_api-0.1.0.dist-info/licenses/LICENSE,sha256=IZwQUm0sT7EkedTxvSsFHucyQSO_neRlmtI1vG5NNp8,1105
+ghome_local_api-0.1.0.dist-info/RECORD,,

ghome_local_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ghome_local_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Ilja Leiko
+Copyright (c) 2026 Ruslan Sayfutdinov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.