PySwitchbot 2.8.0__tar.gz → 2.9.1__tar.gz

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySwitchbot
-Version: 2.8.0
+Version: 2.9.1
 Summary: A library to communicate with Switchbot
 License: MIT
 License-File: LICENSE
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: aiohttp (>=3.9.5)
@@ -41,6 +42,57 @@ source .venv/bin/activate
 pip install .
 ```
 
+## OAuth account access
+
+pySwitchbot provides helpers for SwitchBot's authorization-code flow. The
+calling application supplies a SwitchBot-issued client ID and its registered
+redirect URI; neither value is tied to Home Assistant or embedded in the
+library.
+
+SwitchBot currently treats these integrations as public clients: the token
+request does not use a client secret, and the authorization server does not
+support PKCE. The caller must generate an unpredictable, single-use `state`,
+store it for the duration of the flow, and reject callbacks whose state does
+not match. State protects the callback from request forgery but does not
+replace PKCE.
+
+```python
+import secrets
+
+from switchbot import (
+    build_oauth_authorize_url,
+    exchange_oauth_code,
+    fetch_cloud_devices_by_token,
+)
+
+state = secrets.token_urlsafe(32)
+authorize_url = build_oauth_authorize_url(client_id, redirect_uri, state)
+
+# Store state before sending the user to authorize_url. On callback:
+if callback_state != state:
+    raise ValueError("OAuth state mismatch")
+
+token = await exchange_oauth_code(
+    session,
+    client_id,
+    redirect_uri,
+    authorization_code,
+)
+devices = await fetch_cloud_devices_by_token(session, token["access_token"])
+```
+
+The client ID and exact HTTPS redirect URI must be registered with SwitchBot;
+arbitrary values and wildcard redirect URIs will not work. `exchange_oauth_code`
+returns the provider's token mapping after validating the access token and
+normalizing `expires_in` to an integer. The access token can then be passed to
+`fetch_cloud_devices_by_token` or
+`SwitchbotEncryptedDevice.async_retrieve_encryption_key_by_token`.
+
+HTTP 401 and 403 responses from the SwitchBot account API raise
+`SwitchbotAuthenticationError`. Other API failures raise `SwitchbotApiError`,
+while transport and availability failures raise
+`SwitchbotAccountConnectionError`.
+
 ## Obtaining encryption key for Switchbot Locks
 
 Using the script `scripts/get_encryption_key.py` you can manually obtain locks encryption key.
@@ -72,11 +124,11 @@ password. The most common failures are account-side, not bugs in this library:
     email/password account.
   - The username is an email but the account is registered to a phone number
     (or vice versa). Use the exact identifier you log in with.
-- **`Failed to retrieve encryption key from SwitchBot Account: ...`** —
-  authentication succeeded but the key could not be read. Usually the account
-  is not the device **owner**: keys are only returned to the owning account,
-  not to shared/family members. Retrieve the key from the owner account, or
-  transfer ownership in the app.
+- **`..., status code: 190`** (`SwitchbotApiError`) — authentication succeeded
+  but the key could not be read. Usually the account is not the device
+  **owner**: keys are only returned to the owning account, not to shared/family
+  members. Retrieve the key from the owner account, or transfer ownership in
+  the app.
 
 The key only needs to be fetched once; store the `key_id` and encryption key
 and reuse them — there is no need to call the script on every connection.

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/README.md

@@ -10,6 +10,57 @@ source .venv/bin/activate
 pip install .
 ```
 
+## OAuth account access
+
+pySwitchbot provides helpers for SwitchBot's authorization-code flow. The
+calling application supplies a SwitchBot-issued client ID and its registered
+redirect URI; neither value is tied to Home Assistant or embedded in the
+library.
+
+SwitchBot currently treats these integrations as public clients: the token
+request does not use a client secret, and the authorization server does not
+support PKCE. The caller must generate an unpredictable, single-use `state`,
+store it for the duration of the flow, and reject callbacks whose state does
+not match. State protects the callback from request forgery but does not
+replace PKCE.
+
+```python
+import secrets
+
+from switchbot import (
+    build_oauth_authorize_url,
+    exchange_oauth_code,
+    fetch_cloud_devices_by_token,
+)
+
+state = secrets.token_urlsafe(32)
+authorize_url = build_oauth_authorize_url(client_id, redirect_uri, state)
+
+# Store state before sending the user to authorize_url. On callback:
+if callback_state != state:
+    raise ValueError("OAuth state mismatch")
+
+token = await exchange_oauth_code(
+    session,
+    client_id,
+    redirect_uri,
+    authorization_code,
+)
+devices = await fetch_cloud_devices_by_token(session, token["access_token"])
+```
+
+The client ID and exact HTTPS redirect URI must be registered with SwitchBot;
+arbitrary values and wildcard redirect URIs will not work. `exchange_oauth_code`
+returns the provider's token mapping after validating the access token and
+normalizing `expires_in` to an integer. The access token can then be passed to
+`fetch_cloud_devices_by_token` or
+`SwitchbotEncryptedDevice.async_retrieve_encryption_key_by_token`.
+
+HTTP 401 and 403 responses from the SwitchBot account API raise
+`SwitchbotAuthenticationError`. Other API failures raise `SwitchbotApiError`,
+while transport and availability failures raise
+`SwitchbotAccountConnectionError`.
+
 ## Obtaining encryption key for Switchbot Locks
 
 Using the script `scripts/get_encryption_key.py` you can manually obtain locks encryption key.
@@ -41,11 +92,11 @@ password. The most common failures are account-side, not bugs in this library:
     email/password account.
   - The username is an email but the account is registered to a phone number
     (or vice versa). Use the exact identifier you log in with.
-- **`Failed to retrieve encryption key from SwitchBot Account: ...`** —
-  authentication succeeded but the key could not be read. Usually the account
-  is not the device **owner**: keys are only returned to the owning account,
-  not to shared/family members. Retrieve the key from the owner account, or
-  transfer ownership in the app.
+- **`..., status code: 190`** (`SwitchbotApiError`) — authentication succeeded
+  but the key could not be read. Usually the account is not the device
+  **owner**: keys are only returned to the owning account, not to shared/family
+  members. Retrieve the key from the owner account, or transfer ownership in
+  the app.
 
 The key only needs to be fetched once; store the `key_id` and encryption key
 and reuse them — there is no need to call the script on every connection.

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "PySwitchbot"
-version = "2.8.0"
+version = "2.9.1"
 description = "A library to communicate with Switchbot"
 authors = ["Daniel Hjelseth Hoyer"]
 license = "MIT"

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/switchbot/__init__.py

@@ -47,6 +47,7 @@ from .devices.device import (
     SwitchbotEncryptedDevice,
     SwitchbotOperationError,
     fetch_cloud_devices,
+    fetch_cloud_devices_by_token,
 )
 from .devices.evaporative_humidifier import SwitchbotEvaporativeHumidifier
 from .devices.fan import (
@@ -79,8 +80,18 @@ from .devices.universal_remote import SwitchbotUniversalRemote
 from .devices.vacuum import SwitchbotVacuum
 from .discovery import GetSwitchbotDevices
 from .models import SwitchBotAdvertisement
+from .oauth import (
+    OAUTH_AUTHORIZE_URL,
+    OAUTH_SCOPE,
+    OAUTH_TOKEN_URL,
+    build_oauth_authorize_url,
+    exchange_oauth_code,
+)
 
 __all__ = [
+    "OAUTH_AUTHORIZE_URL",
+    "OAUTH_SCOPE",
+    "OAUTH_TOKEN_URL",
     "AirPurifierMode",
     "AirQualityLevel",
     "BulbColorMode",
@@ -142,9 +153,12 @@ __all__ = [
     "SwitchbotUniversalRemote",
     "SwitchbotVacuum",
     "VerticalOscillationAngle",
+    "build_oauth_authorize_url",
     "close_stale_connections",
     "close_stale_connections_by_address",
+    "exchange_oauth_code",
     "fetch_cloud_devices",
+    "fetch_cloud_devices_by_token",
     "get_device",
     "parse_advertisement_data",
 ]

pyswitchbot-2.9.1/switchbot/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.9.1"

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/switchbot/adv_parsers/_sensor_th.py

@@ -24,7 +24,7 @@ def decode_temp_humidity(temp_data: bytes, battery: int | None) -> dict[str, Any
     _temp_f = (_temp_f * 10) / 10
     humidity = temp_data[2] & 0b01111111
 
-    if _temp_c == 0 and humidity == 0 and battery == 0:
+    if _temp_c == 0 and humidity == 0:
         return {}
 
     return {

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/switchbot/devices/device.py

@@ -39,15 +39,25 @@ from ..const import (
 from ..discovery import GetSwitchbotDevices
 from ..helpers import create_background_task
 from ..models import SwitchBotAdvertisement
-from ..utils import format_mac_upper
+from ..utils import extract_request_id, format_mac_upper
 
 _LOGGER = logging.getLogger(__name__)
 
 
+def _masked_device_id(device_id: str) -> str:
+    """Mask a device identifier while retaining a useful suffix."""
+    normalized = device_id.replace(":", "").replace("-", "").upper()
+    if not normalized:
+        return "unknown"
+    return f"****{normalized[-4:]}"
+
+
 def _extract_region(userinfo: dict[str, Any]) -> str:
     """Extract region from user info, defaulting to 'us'."""
-    if "botRegion" in userinfo and userinfo["botRegion"] != "":
-        return userinfo["botRegion"]
+    region = userinfo.get("botRegion")
+    if isinstance(region, str) and region:
+        return region
+    _LOGGER.warning("SwitchBot account region missing; defaulting to us")
     return "us"
 
 
@@ -265,6 +275,10 @@ class SwitchbotBaseDevice:
             return await cls.api_request(
                 session, "account", "account/api/v1/user/userinfo", {}, auth_headers
             )
+        except SwitchbotAuthenticationError:
+            raise
+        except SwitchbotApiError:
+            raise
         except Exception as err:
             raise SwitchbotAccountConnectionError(
                 f"Failed to retrieve SwitchBot Account user details: {err}"
@@ -308,8 +322,45 @@ class SwitchbotBaseDevice:
         except Exception as err:
             raise SwitchbotAuthenticationError(f"Authentication failed: {err}") from err
 
+        return await cls._async_get_devices(session, auth_headers)
+
+    @classmethod
+    async def get_devices_by_token(
+        cls,
+        session: aiohttp.ClientSession,
+        access_token: str,
+    ) -> dict[str, SwitchbotModel]:
+        """Get devices from SwitchBot API using an OAuth access token."""
+        started = time.monotonic()
+        _LOGGER.debug("Retrieving SwitchBot cloud devices using an OAuth token")
+        try:
+            devices = await cls._async_get_devices(
+                session, {"authorization": access_token}
+            )
+        except Exception:
+            _LOGGER.debug(
+                "SwitchBot OAuth cloud device retrieval failed; duration_ms=%s",
+                round((time.monotonic() - started) * 1000),
+            )
+            raise
+        _LOGGER.debug(
+            "SwitchBot OAuth cloud device retrieval finished; supported_devices=%s "
+            "duration_ms=%s",
+            len(devices),
+            round((time.monotonic() - started) * 1000),
+        )
+        return devices
+
+    @classmethod
+    async def _async_get_devices(
+        cls,
+        session: aiohttp.ClientSession,
+        auth_headers: dict[str, str],
+    ) -> dict[str, SwitchbotModel]:
+        """Get devices from SwitchBot API using authenticated headers."""
         userinfo = await cls._async_get_user_info(session, auth_headers)
         region = _extract_region(userinfo)
+        _LOGGER.debug("SwitchBot account region resolved to %s", region)
 
         try:
             device_info = await cls.api_request(
@@ -321,12 +372,21 @@ class SwitchbotBaseDevice:
                 },
                 auth_headers,
             )
+        except SwitchbotAuthenticationError:
+            raise
+        except SwitchbotApiError:
+            raise
         except Exception as err:
             raise SwitchbotAccountConnectionError(
                 f"Failed to retrieve devices from SwitchBot Account: {err}"
             ) from err
 
-        items: list[dict[str, Any]] = device_info["Items"]
+        items = device_info.get("Items")
+        if not isinstance(items, list) or not all(
+            isinstance(item, dict) for item in items
+        ):
+            raise SwitchbotApiError("Invalid device response from SwitchBot API")
+        _LOGGER.debug("SwitchBot cloud API returned %s device records", len(items))
         mac_to_model: dict[str, SwitchbotModel] = {}
 
         for item in items:
@@ -360,6 +420,7 @@ class SwitchbotBaseDevice:
                     item,
                 )
 
+        _LOGGER.debug("Mapped %s supported SwitchBot cloud devices", len(mac_to_model))
         return mac_to_model
 
     @classmethod
@@ -372,18 +433,46 @@ class SwitchbotBaseDevice:
         headers: dict | None = None,
     ) -> dict:
         url = f"https://{subdomain}.{SWITCHBOT_APP_API_BASE_URL}/{path}"
+        started = time.monotonic()
+        _LOGGER.debug("Requesting SwitchBot API endpoint %s", url)
         async with session.post(
             url,
             json=data,
             headers=headers,
             timeout=aiohttp.ClientTimeout(total=10),
         ) as result:
+            _LOGGER.debug(
+                "SwitchBot API endpoint %s returned HTTP status %s; duration_ms=%s "
+                "request_id=%s",
+                url,
+                result.status,
+                round((time.monotonic() - started) * 1000),
+                extract_request_id(result.headers) or "unavailable",
+            )
+            if result.status in (401, 403):
+                raise SwitchbotAuthenticationError(
+                    "Authentication rejected by SwitchBot API"
+                )
             if result.status > 299:
                 raise SwitchbotApiError(
                     f"Unexpected status code returned by SwitchBot API: {result.status}"
                 )
 
             response = await result.json()
+            body = response.get("body")
+            body_fields: list[str] | str = (
+                sorted(body) if isinstance(body, dict) else type(body).__name__
+            )
+            _LOGGER.debug(
+                (
+                    "SwitchBot API endpoint %s returned API status %s; "
+                    "response fields=%s; body fields=%s"
+                ),
+                url,
+                response.get("statusCode"),
+                sorted(response),
+                body_fields,
+            )
             if response["statusCode"] != 100:
                 raise SwitchbotApiError(
                     f"{response['message']}, status code: {response['statusCode']}"
@@ -1052,17 +1141,69 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
         password: str,
     ) -> dict:
         """Retrieve lock key from internal SwitchBot API."""
-        device_mac = device_mac.replace(":", "").replace("-", "").upper()
-
         try:
             auth_result = await cls._get_auth_result(session, username, password)
             auth_headers = {"authorization": auth_result["access_token"]}
         except Exception as err:
             raise SwitchbotAuthenticationError(f"Authentication failed: {err}") from err
 
+        return await cls._async_retrieve_encryption_key(
+            session, device_mac, auth_headers
+        )
+
+    @classmethod
+    async def async_retrieve_encryption_key_by_token(
+        cls,
+        session: aiohttp.ClientSession,
+        device_mac: str,
+        access_token: str,
+    ) -> dict:
+        """Retrieve an encryption key using an OAuth access token."""
+        started = time.monotonic()
+        masked_device = _masked_device_id(device_mac)
+        _LOGGER.debug(
+            "Retrieving a SwitchBot encryption key using an OAuth token; device=%s",
+            masked_device,
+        )
+        try:
+            key_details = await cls._async_retrieve_encryption_key(
+                session, device_mac, {"authorization": access_token}
+            )
+        except Exception:
+            _LOGGER.debug(
+                "SwitchBot OAuth encryption key retrieval failed; device=%s "
+                "duration_ms=%s",
+                masked_device,
+                round((time.monotonic() - started) * 1000),
+            )
+            raise
+        _LOGGER.debug(
+            "SwitchBot OAuth encryption key retrieval finished; device=%s "
+            "duration_ms=%s",
+            masked_device,
+            round((time.monotonic() - started) * 1000),
+        )
+        return key_details
+
+    @classmethod
+    async def _async_retrieve_encryption_key(
+        cls,
+        session: aiohttp.ClientSession,
+        device_mac: str,
+        auth_headers: dict[str, str],
+    ) -> dict:
+        """Retrieve an encryption key using authenticated headers."""
+        device_mac = device_mac.replace(":", "").replace("-", "").upper()
+
         userinfo = await cls._async_get_user_info(session, auth_headers)
         region = _extract_region(userinfo)
+        masked_device = _masked_device_id(device_mac)
 
+        _LOGGER.debug(
+            "SwitchBot encryption key account region resolved; region=%s device=%s",
+            region,
+            masked_device,
+        )
         try:
             device_info = await cls.api_request(
                 session,
@@ -1074,16 +1215,33 @@ class SwitchbotEncryptedDevice(SwitchbotDevice):
                 },
                 auth_headers,
             )
-
-            return {
-                "key_id": device_info["communicationKey"]["keyId"],
-                "encryption_key": device_info["communicationKey"]["key"],
-            }
+        except SwitchbotAuthenticationError:
+            raise
+        except SwitchbotApiError:
+            raise
         except Exception as err:
             raise SwitchbotAccountConnectionError(
                 f"Failed to retrieve encryption key from SwitchBot Account: {err}"
             ) from err
 
+        communication_key = device_info.get("communicationKey")
+        if not isinstance(communication_key, dict):
+            raise SwitchbotApiError(
+                "Invalid encryption key response from SwitchBot API"
+            )
+        key_id = communication_key.get("keyId")
+        encryption_key = communication_key.get("key")
+        if not isinstance(key_id, str) or not isinstance(encryption_key, str):
+            raise SwitchbotApiError(
+                "Invalid encryption key response from SwitchBot API"
+            )
+
+        _LOGGER.debug(
+            "SwitchBot encryption key retrieved successfully; device=%s",
+            masked_device,
+        )
+        return {"key_id": key_id, "encryption_key": encryption_key}
+
     @classmethod
     async def verify_encryption_key(
         cls,
@@ -1336,3 +1494,11 @@ async def fetch_cloud_devices(
     """Fetch devices from SwitchBot API and return MAC to model mapping."""
     # Get devices from the API (which also populates the cache)
     return await SwitchbotBaseDevice.get_devices(session, username, password)
+
+
+async def fetch_cloud_devices_by_token(
+    session: aiohttp.ClientSession,
+    access_token: str,
+) -> dict[str, SwitchbotModel]:
+    """Fetch devices from SwitchBot API using an OAuth access token."""
+    return await SwitchbotBaseDevice.get_devices_by_token(session, access_token)

pyswitchbot-2.9.1/switchbot/oauth.py

@@ -0,0 +1,183 @@
+"""OAuth helpers for the SwitchBot account API."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from time import monotonic
+from typing import Any
+from urllib.parse import urlencode, urlsplit
+
+import aiohttp
+
+from .const import (
+    SwitchbotAccountConnectionError,
+    SwitchbotApiError,
+    SwitchbotAuthenticationError,
+)
+from .utils import extract_request_id
+
+_LOGGER = logging.getLogger(__name__)
+
+OAUTH_AUTHORIZE_URL = "https://sp.oauth.switchbot.net"
+OAUTH_TOKEN_URL = "https://account.api.switchbot.net/merchant/v1/oauth/token"
+OAUTH_SCOPE = "api_login"
+
+
+def _oauth_error_field(
+    error_data: Any, field: str, authorization_code: str
+) -> str | None:
+    """Return a bounded OAuth error field with the authorization code redacted."""
+    if not isinstance(error_data, Mapping):
+        return None
+    value = error_data.get(field)
+    if not isinstance(value, str):
+        return None
+    value = " ".join(value.split())
+    if authorization_code:
+        value = value.replace(authorization_code, "<redacted>")
+    return value[:256] or None
+
+
+def _raise_for_oauth_error(status: int, error: str | None, error_suffix: str) -> None:
+    """Raise the appropriate exception for an OAuth error response."""
+    if status in (401, 403) or (
+        status == 400 and error in {"invalid_client", "invalid_grant"}
+    ):
+        raise SwitchbotAuthenticationError(
+            f"SwitchBot OAuth token request rejected ({status}){error_suffix}"
+        )
+    if 400 <= status < 500 and status != 429:
+        raise SwitchbotApiError(
+            f"SwitchBot OAuth token request failed ({status}){error_suffix}"
+        )
+    if status == 429 or status >= 500:
+        raise SwitchbotAccountConnectionError(
+            f"SwitchBot OAuth token service unavailable ({status}){error_suffix}"
+        )
+
+
+def build_oauth_authorize_url(
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+) -> str:
+    """Build a SwitchBot OAuth authorization URL."""
+    _LOGGER.debug(
+        "Building SwitchBot OAuth authorization request; authorize_host=%s "
+        "redirect_host=%s",
+        urlsplit(OAUTH_AUTHORIZE_URL).hostname,
+        urlsplit(redirect_uri).hostname,
+    )
+    query = urlencode(
+        {
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": OAUTH_SCOPE,
+            "state": state,
+        }
+    )
+    return f"{OAUTH_AUTHORIZE_URL}?{query}"
+
+
+async def exchange_oauth_code(
+    session: aiohttp.ClientSession,
+    client_id: str,
+    redirect_uri: str,
+    code: str,
+) -> dict[str, Any]:
+    """Exchange an OAuth authorization code for a SwitchBot access token."""
+    started = monotonic()
+    _LOGGER.debug(
+        "Exchanging SwitchBot OAuth authorization code; token_host=%s",
+        urlsplit(OAUTH_TOKEN_URL).hostname,
+    )
+    error: str | None = None
+    error_description: str | None = None
+    token_data: Any = None
+    try:
+        async with session.post(
+            OAUTH_TOKEN_URL,
+            data={
+                "code": code,
+                "client_id": client_id,
+                "grant_type": "authorization_code",
+                "redirect_uri": redirect_uri,
+            },
+            timeout=aiohttp.ClientTimeout(total=10),
+        ) as response:
+            status = response.status
+            _LOGGER.debug(
+                "SwitchBot OAuth token endpoint returned HTTP status %s; "
+                "duration_ms=%s request_id=%s",
+                status,
+                round((monotonic() - started) * 1000),
+                extract_request_id(response.headers) or "unavailable",
+            )
+            if status >= 400:
+                try:
+                    error_data = await response.json()
+                except (aiohttp.ClientError, ValueError, TypeError) as err:
+                    _LOGGER.debug(
+                        "SwitchBot OAuth token error response could not be parsed; "
+                        "error_type=%s",
+                        type(err).__name__,
+                    )
+                    error_data = None
+                error = _oauth_error_field(error_data, "error", code)
+                error_description = _oauth_error_field(
+                    error_data, "error_description", code
+                )
+                _LOGGER.debug(
+                    "SwitchBot OAuth token endpoint returned an error response; "
+                    "error=%s error_description=%s",
+                    error or "unavailable",
+                    error_description or "unavailable",
+                )
+            else:
+                try:
+                    token_data = await response.json()
+                except (aiohttp.ClientError, ValueError, TypeError) as err:
+                    raise SwitchbotApiError(
+                        "Invalid response from SwitchBot OAuth token API"
+                    ) from err
+    except (aiohttp.ClientError, TimeoutError) as err:
+        raise SwitchbotAccountConnectionError(
+            f"Failed to connect to SwitchBot OAuth token API: {err}"
+        ) from err
+
+    error_detail = ": ".join(
+        value for value in (error, error_description) if value is not None
+    )
+    error_suffix = f": {error_detail}" if error_detail else ""
+    _raise_for_oauth_error(status, error, error_suffix)
+    if not isinstance(token_data, dict):
+        raise SwitchbotApiError("Invalid response from SwitchBot OAuth token API")
+
+    token: dict[str, Any] = token_data.copy()
+    _LOGGER.debug("SwitchBot OAuth token response fields: %s", sorted(token))
+    access_token = token.get("access_token")
+    expires_in = token.get("expires_in")
+    if (
+        not isinstance(access_token, str)
+        or not access_token
+        or isinstance(expires_in, bool)
+        or not isinstance(expires_in, int | str)
+    ):
+        raise SwitchbotApiError("Invalid token data from SwitchBot OAuth token API")
+    try:
+        normalized_expires_in = int(expires_in)
+    except ValueError as err:
+        raise SwitchbotApiError(
+            "Invalid token data from SwitchBot OAuth token API"
+        ) from err
+    token["expires_in"] = normalized_expires_in
+    _LOGGER.debug(
+        "SwitchBot OAuth token response validated; expires_in=%s "
+        "refresh_token_present=%s refresh_expires_in_present=%s",
+        normalized_expires_in,
+        bool(token.get("refresh_token")),
+        "refresh_expires_in" in token,
+    )
+    return token

{pyswitchbot-2.8.0 → pyswitchbot-2.9.1}/switchbot/utils.py

@@ -1,7 +1,23 @@
 """Utility functions for switchbot."""
 
+from collections.abc import Mapping
 from functools import lru_cache
 
+_REQUEST_ID_HEADERS = ("x-request-id", "x-amzn-requestid", "cf-ray")
+
+
+def extract_request_id(headers: Mapping[str, str]) -> str | None:
+    """Extract a provider request identifier for log correlation."""
+    normalized_headers = {name.lower(): value for name, value in headers.items()}
+    return next(
+        (
+            value
+            for name in _REQUEST_ID_HEADERS
+            if (value := normalized_headers.get(name))
+        ),
+        None,
+    )
+
 
 @lru_cache(maxsize=512)
 def format_mac_upper(mac: str) -> str:

pyswitchbot-2.8.0/switchbot/__version__.py

@@ -1 +0,0 @@
-__version__ = "2.8.0"