glucoglance 0.3.0__py3-none-any.whl

glucoglance/__init__.py

@@ -0,0 +1,11 @@
+"""GlucoGlance: an Ubuntu tray application that displays a live glucose
+reading fetched from the LibreLinkUp cloud API.
+
+Package layout:
+    client   - talks to the LibreLinkUp API and turns its responses into domain objects.
+    domain   - plain data types (GlucoseReading, TrendArrow, unit conversion) with no I/O.
+    poller   - background polling loop that publishes new readings/errors as events.
+    alerts   - placeholder for phase 2 (threshold alarms); empty for now.
+    ui       - the on-screen display (tray indicator today, possibly others later).
+    config   - user settings and credential storage.
+"""

glucoglance/alerts/__init__.py

@@ -0,0 +1 @@
+"""Placeholder for phase 2 (glucose threshold alarms). Empty in phase 1."""

glucoglance/alerts/base.py

@@ -0,0 +1,7 @@
+"""Placeholder for phase 2.
+
+Threshold alarms will subscribe to the same `poller.EventBus` the tray
+display uses today (see `poller.poller.EventBus`), reacting to
+`ReadingUpdatedEvent`/`PollErrorEvent` events without any changes needed to the
+client, domain, or poller code. Nothing is implemented here yet.
+"""

glucoglance/client/__init__.py

@@ -0,0 +1 @@
+"""LibreLinkUp API client: authentication and fetching the latest glucose reading."""

glucoglance/client/errors.py

@@ -0,0 +1,28 @@
+"""Exceptions raised by the LibreLinkUp client.
+
+`LibreLinkUpClient.get_latest_reading()` only ever raises one of these three
+types - it never lets a raw `requests` exception, `KeyError`, or JSON parsing
+error escape - so callers (the poller) can handle failures uniformly without
+knowing anything about the client's internals.
+"""
+
+
+class LibreLinkUpError(Exception):
+    """Base class for all errors raised by the LibreLinkUp client."""
+
+
+class AuthError(LibreLinkUpError):
+    """Login failed: bad credentials, or the API rejected/expired our session."""
+
+
+class NetworkError(LibreLinkUpError):
+    """A network-level failure (timeout, DNS, connection refused, HTTP 5xx, ...)."""
+
+
+class StaleDataError(LibreLinkUpError):
+    """The request succeeded, but there's no usable reading.
+
+    Raised when the follower account has no connections, or the latest
+    reading's timestamp is too old - both indicate the sensor wearer's phone
+    has stopped relaying data to LibreLinkUp, not a problem with our request.
+    """

glucoglance/client/librelinkup.py

@@ -0,0 +1,275 @@
+"""Client for the unofficial LibreLinkUp API.
+
+LibreLinkUp is Abbott's "follower" service: the sensor wearer's phone app
+uploads readings to it, and a follower account (the one this client logs in
+as) can poll it for the latest reading. There is no official public API or
+documentation for this - the request/response shapes here are based on
+community-documented behavior of the LibreLinkUp mobile app and may drift if
+Abbott changes their backend. If this client starts failing, the response
+shapes below are the first thing to re-check against a real request.
+
+Everything the rest of the app needs is exposed through one method:
+`get_latest_reading()`. It always returns a fully-formed GlucoseReading or
+raises one of the errors in `client.errors` - callers never see raw HTTP or
+JSON errors.
+
+Response field reference (GET /llu/connections, one connection object in the
+`data` array). Only `glucoseMeasurement`'s fields marked USED below are
+actually parsed today, by `_parse_connections_response()`. Everything else
+is kept here so a future feature (e.g. phase 2 alerts wanting `alarmRules`,
+or a "sensor days left" display wanting `sensor`) doesn't need to rediscover
+the API's shape from scratch.
+
+Connection object:
+  id                    - this connection record's own ID (unused)
+  patientId             - sensor wearer's patient ID (unused)
+  firstName, lastName   - sensor wearer's name (unused)
+  status                - connection status code (unused)
+  country               - wearer's registered country, e.g. "ES" (unused)
+  created               - unix timestamp the connection was created (unused)
+  uom                   - account-level unit of measure, 1=mg/dL (unused;
+                          redundant with glucoseMeasurement.GlucoseUnits)
+  targetHigh, targetLow - wearer's target range from their own LibreLinkUp
+                          app settings (unused - range classification uses
+                          domain/range.py + Settings-configured thresholds
+                          instead, not this)
+  glucoseAlarm          - active alarm state, if any (unused)
+  alarmRules            - wearer's configured alarm thresholds, with h/l/f
+                          sub-blocks for high/low/fast-drop (unused; likely
+                          relevant to phase 2 alerts)
+  patientDevice         - reading device metadata: did/dtid (device
+                          id/type), v (firmware version), h/l/hl/ll
+                          (device-side high/low flags+values),
+                          fixedLowAlarmValues, alarms (bool), u (timestamp)
+                          (unused)
+  sensor                - physical sensor metadata: sn (serial), a
+                          (activation timestamp), w (wear duration), pt,
+                          lj, s, deviceId (unused)
+  glucoseItem           - duplicate of glucoseMeasurement, same shape
+                          (unused)
+  glucoseMeasurement    - the current reading, see below
+
+glucoseMeasurement:
+  Value            - glucose value in the account's display unit (USED ->
+                     GlucoseReading.value_mgdl)
+  Timestamp        - reading time, account-local naive datetime (USED ->
+                     GlucoseReading.timestamp; also drives the staleness
+                     check)
+  TrendArrow       - direction code 1-5 (USED -> GlucoseReading.trend, via
+                     TrendArrow.from_api_value)
+  isHigh, isLow    - API's own range flags (USED -> GlucoseReading.is_high
+                     / is_low)
+  ValueInMgPerDl   - same value, always in mg/dL regardless of account unit
+                     (unused - NOTE: `Value` is only actually mg/dL because
+                     this account's `GlucoseUnits` is 1; an mmol/L account
+                     would make `Value` diverge from `ValueInMgPerDl`, and
+                     GlucoseReading's mg/dL assumption would silently break)
+  FactoryTimestamp - sensor-side timestamp, vs `Timestamp` being
+                     account-local (unused)
+  GlucoseUnits     - unit code for `Value`: 1=mg/dL, 2=mmol/L (unused - see
+                     ValueInMgPerDl note above)
+  MeasurementColor - API's own in/out-of-range color code (unused -
+                     superseded by domain/range.py's own classification)
+  TrendMessage     - optional human-readable trend text (unused)
+  type             - measurement type code, 1=normal reading (unused)
+"""
+
+import hashlib
+from datetime import datetime, timedelta
+from typing import Any
+
+import requests
+
+from glucoglance.client.errors import AuthError, NetworkError, StaleDataError
+from glucoglance.domain.reading import GlucoseReading
+from glucoglance.domain.trend import TrendArrow
+
+# Default entry point; a login response can redirect us to a region-specific
+# host instead (e.g. api-eu.libreview.io), which we then remember.
+DEFAULT_BASE_HOST = "api.libreview.io"
+
+# LibreLinkUp's backend rejects requests that don't look like they came from
+# the official mobile app, and version-gates the API: too low a version
+# here gets a 403 with {"status": 920, "data": {"minimumVersion": "X"}}
+# (confirmed live - 4.12.0 was rejected demanding 4.16.0). Bump this if that
+# starts happening again.
+_REQUEST_HEADERS = {
+    "Content-Type": "application/json",
+    "product": "llu.android",
+    "version": "4.16.0",
+}
+
+# A reading older than this is treated as stale: the wearer's phone has
+# likely stopped relaying data to LibreLinkUp.
+_STALE_AFTER = timedelta(minutes=5)
+
+# The token LibreLinkUp issues is short-lived; refresh a little before it
+# actually expires rather than racing the clock.
+_TOKEN_REFRESH_MARGIN = timedelta(minutes=1)
+
+
+class LibreLinkUpClient:
+    """Fetches the latest glucose reading for a single LibreLinkUp follower account."""
+
+    def __init__(self, email: str, password: str, *, base_host: str | None = None):
+        """Create a client. `base_host` can be a previously-cached region host
+        (see `_login`) to skip the redirect round trip; if omitted, the
+        default host is tried first."""
+        self._email = email
+        self._password = password
+        self._base_host = base_host or DEFAULT_BASE_HOST
+        self._session = requests.Session()
+        self._token: str | None = None
+        self._token_expires_at: datetime | None = None
+        self._account_id_header: str | None = None
+
+    @property
+    def base_host(self) -> str:
+        """The (possibly region-redirected) host currently in use, for callers
+        that want to cache it in config and pass it back in next time."""
+        return self._base_host
+
+    def get_latest_reading(self) -> GlucoseReading:
+        """Fetch the wearer's most recent glucose reading.
+
+        Raises AuthError, NetworkError, or StaleDataError - never returns
+        None and never lets a lower-level exception escape.
+        """
+        self._ensure_authenticated()
+        connections = self._get_connections()
+        return _parse_connections_response(connections)
+
+    def _ensure_authenticated(self) -> None:
+        """Log in if we don't yet have a token, or it's about to expire."""
+        if self._token and self._token_expires_at:
+            if datetime.now() < self._token_expires_at - _TOKEN_REFRESH_MARGIN:
+                return
+        self._login()
+
+    def _login(self) -> None:
+        """POST credentials to /llu/auth/login, following a region redirect once."""
+        response_data = self._post_login(self._base_host)
+
+        if response_data.get("redirect"):
+            region = response_data.get("region")
+            if not region:
+                raise AuthError("LibreLinkUp requested a redirect but gave no region")
+            self._base_host = f"api-{region}.libreview.io"
+            response_data = self._post_login(self._base_host)
+
+        try:
+            ticket = response_data["authTicket"]
+            self._token = ticket["token"]
+            self._token_expires_at = datetime.fromtimestamp(ticket["expires"])
+            # Abbott's backend requires this header on later calls; it's the
+            # SHA-256 hex digest of the account's user id.
+            user_id = response_data["user"]["id"]
+            self._account_id_header = hashlib.sha256(user_id.encode("utf-8")).hexdigest()
+        except (KeyError, TypeError) as exc:
+            raise AuthError(f"Unexpected login response shape: {exc}") from exc
+
+    def _post_login(self, host: str) -> dict[str, Any]:
+        """Send the login request to the given host and return its `data` field."""
+        try:
+            resp = self._session.post(
+                f"https://{host}/llu/auth/login",
+                json={"email": self._email, "password": self._password},
+                headers=_REQUEST_HEADERS,
+                timeout=10,
+            )
+        except requests.RequestException as exc:
+            raise NetworkError(f"Login request failed: {exc}") from exc
+
+        body = _parse_json(resp, NetworkError)
+        if resp.status_code == 401 or body.get("status") not in (0, None):
+            raise AuthError(f"Login rejected: {_response_error_detail(resp, body)}")
+        if resp.status_code != 200:
+            detail = _response_error_detail(resp, body)
+            raise NetworkError(f"Login returned unexpected HTTP {detail}")
+
+        return body.get("data", {})
+
+    def _get_connections(self) -> dict[str, Any]:
+        """GET /llu/connections, which includes each connected patient's latest reading."""
+        headers = dict(_REQUEST_HEADERS, Authorization=f"Bearer {self._token}")
+        if self._account_id_header:
+            headers["Account-Id"] = self._account_id_header
+
+        try:
+            resp = self._session.get(
+                f"https://{self._base_host}/llu/connections",
+                headers=headers,
+                timeout=10,
+            )
+        except requests.RequestException as exc:
+            raise NetworkError(f"Connections request failed: {exc}") from exc
+
+        if resp.status_code == 401:
+            # Token was rejected outright (e.g. revoked server-side); force a
+            # fresh login on the next call rather than retrying here.
+            self._token = None
+            raise AuthError("Connections request was unauthorized")
+
+        body = _parse_json(resp, NetworkError)
+        if resp.status_code != 200:
+            detail = _response_error_detail(resp, body)
+            raise NetworkError(f"Connections returned unexpected HTTP {detail}")
+
+        return body
+
+
+def _response_error_detail(resp: requests.Response, body: dict[str, Any]) -> str:
+    """Build a short diagnostic string for a non-2xx response: the status
+    code plus whatever error info the body offers, so failures are
+    debuggable from logs instead of just "HTTP 403" with no context."""
+    return f"{resp.status_code} (body={body!r})"
+
+
+def _parse_json(resp: requests.Response, on_error: type[Exception]) -> dict[str, Any]:
+    """Decode a response body as JSON, wrapping decode failures in `on_error`."""
+    try:
+        return resp.json()
+    except ValueError as exc:
+        raise on_error(f"Response was not valid JSON: {exc}") from exc
+
+
+def _parse_connections_response(body: dict[str, Any]) -> GlucoseReading:
+    """Turn a /llu/connections response body into a GlucoseReading for the
+    first connected patient (phase 1 assumes a single sensor wearer)."""
+    connections = body.get("data") or []
+    if not connections:
+        raise StaleDataError("Follower account has no active connections")
+
+    measurement = connections[0].get("glucoseMeasurement")
+    if not measurement:
+        raise StaleDataError("Connection has no glucose measurement yet")
+
+    try:
+        value_mgdl = int(measurement["Value"])
+        timestamp = _parse_api_timestamp(measurement["Timestamp"])
+        is_high = bool(measurement.get("isHigh", False))
+        is_low = bool(measurement.get("isLow", False))
+        trend = TrendArrow.from_api_value(measurement.get("TrendArrow"))
+    except (KeyError, ValueError, TypeError) as exc:
+        raise StaleDataError(f"Malformed glucose measurement: {exc}") from exc
+
+    if datetime.now() - timestamp > _STALE_AFTER:
+        raise StaleDataError(f"Latest reading is older than {_STALE_AFTER}")
+
+    return GlucoseReading(
+        value_mgdl=value_mgdl,
+        trend=trend,
+        timestamp=timestamp,
+        is_high=is_high,
+        is_low=is_low,
+    )
+
+
+def _parse_api_timestamp(raw: str) -> datetime:
+    """Parse the API's timestamp format, e.g. '9/16/2026 3:04:12 PM'.
+
+    The API does not include timezone info, so this is naive local time -
+    consistent with `datetime.now()` as long as both run in the same
+    timezone, which is fine for our staleness check.
+    """
+    return datetime.strptime(raw, "%m/%d/%Y %I:%M:%S %p")

glucoglance/config/__init__.py

@@ -0,0 +1 @@
+"""User settings (TOML file) and credential storage (system keyring)."""

glucoglance/config/autostart.py

@@ -0,0 +1,64 @@
+"""Manages the XDG autostart entry that launches this app at login.
+
+Installing/removing `~/.config/autostart/glucoglance.desktop` is exactly
+what enables/disables autostart. That path is the standard XDG autostart
+location on Ubuntu (and GNOME/most other Linux desktops generally), but
+this project is only built and tested against Ubuntu.
+"""
+
+import sys
+from pathlib import Path
+
+from glucoglance.ui.app_icon import app_icon_path
+
+_AUTOSTART_DIR = Path.home() / ".config" / "autostart"
+_DESKTOP_FILE_NAME = "glucoglance.desktop"
+
+# Cosmetic only: GNOME's AppIndicator extension inserts new tray icons
+# ahead of existing ones rather than appending, so this delay lets other
+# autostart tray apps register first, aiming to land us at the left edge
+# of the right-side icon group. Not user-configurable; tune by hand.
+#
+# Applied via X-GNOME-Autostart-Delay (native gnome-session-binary key),
+# not a shell-wrapped Exec=. A `sh -c "sleep N && exec \"...\""` version
+# passed desktop-file-validate but was rejected at real login by both
+# systemd-xdg-autostart-generator and gnome-session-binary (confirmed via
+# journalctl) - their Exec= parsers are stricter than the validator.
+_STARTUP_DELAY_SECONDS = 6
+
+
+def autostart_desktop_path() -> Path:
+    """Where the autostart entry lives, whether or not it's installed."""
+    return _AUTOSTART_DIR / _DESKTOP_FILE_NAME
+
+
+def set_autostart_enabled(enabled: bool) -> None:
+    """Install or remove the autostart entry to match `enabled`."""
+    if enabled:
+        _AUTOSTART_DIR.mkdir(parents=True, exist_ok=True)
+        autostart_desktop_path().write_text(_desktop_entry_content())
+    else:
+        autostart_desktop_path().unlink(missing_ok=True)
+
+
+def _desktop_entry_content() -> str:
+    """Build the .desktop file content.
+
+    Exec points at the actual installed script next to the currently
+    running interpreter, not just the bare command name "glucoglance" -
+    that name isn't guaranteed to be on PATH in a login session (e.g. when
+    installed into a plain venv rather than via pipx). See
+    `_STARTUP_DELAY_SECONDS` above for why the delay is a separate key
+    rather than part of this Exec= value.
+    """
+    exec_path = Path(sys.executable).with_name("glucoglance")
+    return (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        "Name=GlucoGlance\n"
+        f"Exec={exec_path}\n"
+        f"Icon={app_icon_path()}\n"
+        "X-GNOME-Autostart-enabled=true\n"
+        f"X-GNOME-Autostart-Delay={_STARTUP_DELAY_SECONDS}\n"
+        "Comment=Shows current blood glucose reading in the top bar\n"
+    )

glucoglance/config/credentials.py

@@ -0,0 +1,27 @@
+"""LibreLinkUp password storage via the system keyring (GNOME Keyring on Ubuntu).
+
+The account email is treated as a non-secret identifier and lives in
+`config.settings`; only the password goes through here.
+"""
+
+import keyring
+
+_SERVICE_NAME = "glucoglance"
+
+
+def get_password(email: str) -> str | None:
+    """Return the stored password for `email`, or None if none is stored."""
+    return keyring.get_password(_SERVICE_NAME, email)
+
+
+def set_password(email: str, password: str) -> None:
+    """Store `password` for `email` in the system keyring."""
+    keyring.set_password(_SERVICE_NAME, email, password)
+
+
+def delete_password(email: str) -> None:
+    """Remove the stored password for `email`, if any (used by "Log out")."""
+    try:
+        keyring.delete_password(_SERVICE_NAME, email)
+    except keyring.errors.PasswordDeleteError:
+        pass  # nothing was stored for this email - already effectively logged out

glucoglance/config/settings.py

@@ -0,0 +1,102 @@
+"""User-facing settings, stored as TOML at an XDG-compliant config path.
+
+Only non-secret configuration lives here (polling interval, display unit,
+which UI frontend to use, the account email, a cached region host to skip
+LibreLinkUp's redirect round trip, the glucose-range thresholds/colors the
+tray icon uses, and whether to start at login). The account password is
+never written to this file - see `config.credentials` for that.
+"""
+
+import os
+import tomllib
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import tomli_w
+
+from glucoglance.domain.range import DEFAULT_HIGH_THRESHOLD_MGDL, DEFAULT_LOW_THRESHOLD_MGDL
+from glucoglance.domain.units import GlucoseUnit
+
+_APP_DIR_NAME = "glucoglance"
+_CONFIG_FILE_NAME = "config.toml"
+
+# Defaults for the tray icon's range colors, as '#rrggbb' hex - the format
+# stored in config.toml and understood by ui.icon_renderer.parse_hex_color.
+_DEFAULT_COLOR_LOW = "#ED4343"
+_DEFAULT_COLOR_NORMAL = "#4DCC66"
+_DEFAULT_COLOR_HIGH = "#F5D334"
+
+
+@dataclass
+class Settings:
+    """The full set of user-configurable, non-secret settings."""
+
+    interval_seconds: int = 60
+    unit: GlucoseUnit = GlucoseUnit.MGDL
+    frontend: str = "tray"
+    account_email: str | None = None
+    base_host: str | None = None
+    low_threshold_mgdl: int = DEFAULT_LOW_THRESHOLD_MGDL
+    high_threshold_mgdl: int = DEFAULT_HIGH_THRESHOLD_MGDL
+    color_low: str = _DEFAULT_COLOR_LOW
+    color_normal: str = _DEFAULT_COLOR_NORMAL
+    color_high: str = _DEFAULT_COLOR_HIGH
+    autostart_enabled: bool = True
+
+    def to_toml_dict(self) -> dict:
+        """Convert to a plain dict of TOML-serializable types.
+
+        TOML has no `null`: fields that are still unset (`account_email`,
+        `base_host` before first login) are omitted entirely rather than
+        written as None, which `tomli_w` would reject.
+        """
+        data = asdict(self)
+        data["unit"] = self.unit.value
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_toml_dict(cls, data: dict) -> "Settings":
+        """Build a Settings from a dict loaded from TOML, tolerating missing keys."""
+        defaults = cls()
+        return cls(
+            interval_seconds=data.get("interval_seconds", defaults.interval_seconds),
+            unit=GlucoseUnit(data.get("unit", defaults.unit.value)),
+            frontend=data.get("frontend", defaults.frontend),
+            account_email=data.get("account_email"),
+            base_host=data.get("base_host"),
+            low_threshold_mgdl=data.get("low_threshold_mgdl", defaults.low_threshold_mgdl),
+            high_threshold_mgdl=data.get("high_threshold_mgdl", defaults.high_threshold_mgdl),
+            color_low=data.get("color_low", defaults.color_low),
+            color_normal=data.get("color_normal", defaults.color_normal),
+            color_high=data.get("color_high", defaults.color_high),
+            autostart_enabled=data.get("autostart_enabled", defaults.autostart_enabled),
+        )
+
+
+def config_dir() -> Path:
+    """The directory settings live in, honoring $XDG_CONFIG_HOME if set."""
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
+    return base / _APP_DIR_NAME
+
+
+def config_path() -> Path:
+    """The full path to the settings TOML file."""
+    return config_dir() / _CONFIG_FILE_NAME
+
+
+def load_settings() -> Settings:
+    """Load settings from disk, or return defaults if the file doesn't exist yet."""
+    path = config_path()
+    if not path.exists():
+        return Settings()
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    return Settings.from_toml_dict(data)
+
+
+def save_settings(settings: Settings) -> None:
+    """Write settings to disk, creating the config directory if needed."""
+    config_dir().mkdir(parents=True, exist_ok=True)
+    with config_path().open("wb") as f:
+        tomli_w.dump(settings.to_toml_dict(), f)

glucoglance/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain types: GlucoseReading, TrendArrow, and unit conversion. Pure data, no I/O."""

glucoglance/domain/range.py

@@ -0,0 +1,38 @@
+"""Classifies a glucose value into a coarse clinical range (low/normal/high).
+
+Thresholds are always in mg/dL, matching GlucoseReading's canonical storage
+unit. The values here are just the defaults - `config.settings.Settings`
+carries the user's actual configured thresholds, so they can be tuned via
+config.toml without a code change. For now this only drives the tray
+icon's color; phase 2's threshold alarms will likely want their own,
+separately configurable thresholds rather than assuming these exact
+cutoffs.
+"""
+
+from enum import Enum
+
+DEFAULT_LOW_THRESHOLD_MGDL = 80
+DEFAULT_HIGH_THRESHOLD_MGDL = 180
+
+
+class GlucoseRange(Enum):
+    """A coarse classification of a glucose value."""
+
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+
+
+def classify_mgdl(
+    value_mgdl: float,
+    *,
+    low_threshold: float = DEFAULT_LOW_THRESHOLD_MGDL,
+    high_threshold: float = DEFAULT_HIGH_THRESHOLD_MGDL,
+) -> GlucoseRange:
+    """Classify a glucose value (given in mg/dL) as low, normal, or high,
+    against the given thresholds (defaulting to this module's defaults)."""
+    if value_mgdl < low_threshold:
+        return GlucoseRange.LOW
+    if value_mgdl > high_threshold:
+        return GlucoseRange.HIGH
+    return GlucoseRange.NORMAL

glucoglance/domain/reading.py

@@ -0,0 +1,29 @@
+"""The GlucoseReading model: a single point-in-time glucose measurement."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from glucoglance.domain.trend import TrendArrow
+from glucoglance.domain.units import GlucoseUnit, mgdl_to_mmol
+
+
+@dataclass(frozen=True)
+class GlucoseReading:
+    """A single glucose measurement.
+
+    The value is always stored in mg/dL (the unit the API returns), so that
+    conversion logic lives only in `value_in()` / `domain.units` and is never
+    duplicated between the client and the UI.
+    """
+
+    value_mgdl: int
+    trend: TrendArrow
+    timestamp: datetime
+    is_high: bool
+    is_low: bool
+
+    def value_in(self, unit: GlucoseUnit) -> float:
+        """Return this reading's value converted to the requested display unit."""
+        if unit is GlucoseUnit.MGDL:
+            return float(self.value_mgdl)
+        return mgdl_to_mmol(self.value_mgdl)

glucoglance/domain/trend.py

@@ -0,0 +1,41 @@
+"""The glucose trend arrow, as reported by the LibreLinkUp API.
+
+The API encodes the trend as a small integer (1-5). We translate that into a
+named enum so the rest of the codebase never has to remember what "3" means,
+and attach the display glyph used by the tray label directly to each value.
+"""
+
+from enum import Enum
+
+
+class TrendArrow(Enum):
+    """Direction glucose is currently moving, from the wearer's sensor."""
+
+    UNKNOWN = 0
+    RAPIDLY_FALLING = 1
+    FALLING = 2
+    STABLE = 3
+    RISING = 4
+    RAPIDLY_RISING = 5
+
+    @property
+    def glyph(self) -> str:
+        """A single-character arrow suitable for a compact tray label."""
+        return {
+            TrendArrow.UNKNOWN: "?",
+            TrendArrow.RAPIDLY_FALLING: "⇊",  # ⇊
+            TrendArrow.FALLING: "↓",  # ↓
+            TrendArrow.STABLE: "→",  # →
+            TrendArrow.RISING: "↑",  # ↑
+            TrendArrow.RAPIDLY_RISING: "⇈",  # ⇈
+        }[self]
+
+    @classmethod
+    def from_api_value(cls, raw: object) -> "TrendArrow":
+        """Map the API's raw trend integer to a TrendArrow, defaulting to UNKNOWN
+        for anything missing or out of the 1-5 range (the API is unofficial and
+        could send us something we don't recognize)."""
+        try:
+            return cls(int(raw))  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            return cls.UNKNOWN