matebot 0.2.0__py3-none-any.whl

matebot/config.py

@@ -0,0 +1,91 @@
+"""Configuration: TOML file overridden by environment variables."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+DEFAULT_CONFIG = Path(
+    os.environ.get("XDG_CONFIG_HOME", os.path.expanduser("~/.config"))
+) / "matebot" / "config.toml"
+
+# dataclass field -> environment variable
+ENV_MAP = {
+    "machine_host": "MATEBOT_MACHINE_HOST",
+    "messenger": "MATEBOT_MESSENGER",
+    "telegram_token": "TELEGRAM_BOT_TOKEN",
+    "telegram_chat_id": "TELEGRAM_CHAT_ID",
+    "discord_token": "DISCORD_BOT_TOKEN",
+    "discord_channel_id": "DISCORD_CHANNEL_ID",
+    "data_repo": "MATEBOT_DATA_REPO",
+    "state_dir": "MATEBOT_STATE_DIR",
+    "min_shot_s": "MATEBOT_MIN_SHOT_S",
+    "ignore_profiles": "MATEBOT_IGNORE_PROFILES",
+    "sync_enabled": "MATEBOT_SYNC",
+    "site_title": "MATEBOT_SITE_TITLE",
+    "journal_url": "MATEBOT_JOURNAL_URL",
+    "hints_enabled": "MATEBOT_HINTS",
+    "digest_enabled": "MATEBOT_DIGEST",
+    "clean_every": "MATEBOT_CLEAN_EVERY",
+    "water_warn_pct": "MATEBOT_WATER_WARN",
+    "plots_enabled": "MATEBOT_PLOTS",
+    "wake_hook": "MATEBOT_WAKE_HOOK",
+    "sleep_hook": "MATEBOT_SLEEP_HOOK",
+}
+
+
+@dataclass
+class Config:
+    machine_host: str = "gaggimate.local"
+    messenger: str = "telegram"
+    telegram_token: str = ""
+    telegram_chat_id: str = ""
+    discord_token: str = ""
+    discord_channel_id: str = ""
+    data_repo: str = ""  # path to the git-backed shot journal; empty = sync off
+    state_dir: str = field(
+        default_factory=lambda: os.environ.get(
+            "XDG_STATE_HOME", os.path.expanduser("~/.local/state")
+        )
+        + "/matebot"
+    )
+    min_shot_s: float = 10.0
+    ignore_profiles: str = r"(?i)backflush|descale|flush|clean"
+    sync_enabled: bool = False
+    site_title: str = "Shot Journal"
+    journal_url: str = ""  # public journal base URL, used for /last deep links
+    hints_enabled: bool = True  # dial-in suggestions after sour/bitter/low-rated shots
+    digest_enabled: bool = True  # weekly summary on Sunday evening
+    clean_every: int = 40  # backflush reminder every N espresso shots; 0 = off
+    water_warn_pct: int = 15  # warn when the tank drops below this percent; 0 = off
+    plots_enabled: bool = True  # send the shot chart as a photo (needs matplotlib)
+    wake_hook: str = ""  # shell command to power the machine's smart plug ON
+    sleep_hook: str = ""  # shell command to power the smart plug OFF
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> Config:
+        raw: dict = {}
+        cfg_path = Path(path) if path else DEFAULT_CONFIG
+        if cfg_path.exists():
+            raw = tomllib.loads(cfg_path.read_text())
+        kwargs = {}
+        for f in fields(cls):
+            value = raw.get(f.name)
+            env = os.environ.get(ENV_MAP.get(f.name, ""))
+            if env is not None:
+                value = env
+            if value is None:
+                continue
+            if f.name == "min_shot_s":
+                value = float(value)
+            elif f.name in ("clean_every", "water_warn_pct"):
+                value = int(value)
+            elif f.name in ("sync_enabled", "hints_enabled", "digest_enabled", "plots_enabled"):
+                value = str(value).lower() in ("1", "true", "yes", "on")
+            kwargs[f.name] = value
+        config = cls(**kwargs)
+        if config.data_repo and "sync_enabled" not in kwargs:
+            config.sync_enabled = True
+        return config

matebot/conversation.py

@@ -0,0 +1,263 @@
+"""The post-shot questionnaire — messenger-agnostic.
+
+One questionnaire at a time (it's a home espresso machine, not a fleet).
+A new shot supersedes a pending questionnaire: whatever was already answered
+is saved (partial notes beat no notes), then the new one starts.
+
+Flow: RATING → TASTE → BEAN → GRIND → DOSE_IN → DOSE_OUT → NOTES → save.
+Answers land in the machine's own "Shot Notes" (via req:history:notes:save),
+exactly like typing them into the web UI — just without opening the web UI.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from .messengers.base import Event, Messenger, Option, OptionSelected, TextReply
+from .state import State
+
+log = logging.getLogger(__name__)
+
+SKIP = "–"  # sentinel label value for skip options
+
+# field key -> notes key
+NOTE_KEYS = {
+    "r": "rating",
+    "bt": "balanceTaste",
+    "bean": "beanType",
+    "grind": "grindSetting",
+    "din": "doseIn",
+    "dout": "doseOut",
+    "txt": "notes",
+}
+
+STEPS = ["r", "bt", "bean", "grind", "din", "dout", "txt"]
+TEXT_STEPS = {"bean", "grind", "din", "dout", "txt"}
+
+PROMPTS = {
+    "r": "How was it?",
+    "bt": "Balance / taste?",
+    "bean": "Which beans?",
+    "grind": "Grind setting?",
+    "din": "Dose in (g)?",
+    "dout": "Dose out (g)?",
+    "txt": "Any notes for future-you?",
+}
+
+
+def _fmt_duration(ms: int) -> str:
+    return f"{ms / 1000:.0f}s"
+
+
+def _signoff(hour: int) -> str:
+    """A closing line that knows what time it is (no 'sweet dreams' at 7 am)."""
+    if 5 <= hour < 11:
+        return "Enjoy the kickstart."
+    if 11 <= hour < 17:
+        return "Back to it."
+    if 17 <= hour < 22:
+        return "Enjoy the evening — bold choice, by the way."
+    return "Sweet dreams tonight. Eventually."
+
+
+@dataclass
+class PendingShot:
+    shot_id: int
+    profile: str
+    duration_ms: int
+    volume_g: float
+    step: str = "r"
+    answers: dict | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "shot_id": self.shot_id,
+            "profile": self.profile,
+            "duration_ms": self.duration_ms,
+            "volume_g": self.volume_g,
+            "step": self.step,
+            "answers": self.answers or {},
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> PendingShot:
+        return cls(
+            shot_id=d["shot_id"],
+            profile=d.get("profile", ""),
+            duration_ms=d.get("duration_ms", 0),
+            volume_g=d.get("volume_g", 0.0),
+            step=d.get("step", "r"),
+            answers=d.get("answers") or {},
+        )
+
+
+class Conversation:
+    def __init__(
+        self,
+        messenger: Messenger,
+        state: State,
+        save_notes: Callable[[int, dict], Awaitable[bool]],
+    ) -> None:
+        self.messenger = messenger
+        self.state = state
+        self.save_notes = save_notes
+        self.pending: PendingShot | None = None
+        restored = state.get("pending")
+        if restored:
+            self.pending = PendingShot.from_dict(restored)
+        self._msg_ref: str | None = None
+
+    # ------------------------------------------------------------- shots
+
+    async def start_shot(
+        self, shot_id: int, profile: str, duration_ms: int, volume_g: float,
+        photo: bytes | None = None,
+    ) -> None:
+        if self.pending is not None:
+            await self._finish(superseded_by=shot_id)
+        self.pending = PendingShot(shot_id, profile, duration_ms, volume_g, answers={})
+        self._persist()
+        summary = (
+            f"☕ Shot #{shot_id} done!\n"
+            f"{profile} · {_fmt_duration(duration_ms)}"
+            + (f" · {volume_g:.1f} g in the cup" if volume_g else "")
+            + "\n\nLet's log it before you forget:"
+        )
+        if photo:
+            await self.messenger.send_photo(photo, summary)
+        else:
+            await self.messenger.send(summary)
+        await self._prompt()
+
+    async def resume_if_pending(self) -> None:
+        if self.pending is not None:
+            await self.messenger.send(
+                f"☕ Shot #{self.pending.shot_id} is still waiting for its log — "
+                "where were we?"
+            )
+            await self._prompt()
+
+    # ------------------------------------------------------------- events
+
+    async def handle_event(self, event: Event) -> None:
+        if self.pending is None:
+            return
+        if isinstance(event, OptionSelected):
+            await self._handle_option(event.option_id)
+        elif isinstance(event, TextReply):
+            await self._handle_text(event.text)
+
+    async def _handle_option(self, option_id: str) -> None:
+        try:
+            tag, shot, field, value = option_id.split("|", 3)
+        except ValueError:
+            return
+        if tag != "g" or self.pending is None:
+            return
+        if int(shot) != self.pending.shot_id or field != self.pending.step:
+            log.debug("stale option %s ignored", option_id)
+            return
+        if value == "skip":
+            await self._advance(None)
+        else:
+            await self._advance(value)
+
+    async def _handle_text(self, text: str) -> None:
+        if self.pending is None or self.pending.step not in TEXT_STEPS:
+            return
+        await self._advance(text.strip())
+
+    # ------------------------------------------------------------- steps
+
+    def _defaults(self) -> dict:
+        return self.state.get("last_notes", {})
+
+    def _options_for(self, step: str) -> list[Option]:
+        sid = self.pending.shot_id
+        mk = lambda field, value, label: Option(f"g|{sid}|{field}|{value}", label)  # noqa: E731
+        if step == "r":
+            return [mk("r", str(n), "★" * n) for n in range(1, 6)]
+        if step == "bt":
+            return [
+                mk("bt", "sour", "🍋 sour"),
+                mk("bt", "balanced", "⚖️ balanced"),
+                mk("bt", "bitter", "🌰 bitter"),
+                mk("bt", "skip", "skip"),
+            ]
+        options = []
+        default = self._defaults().get(NOTE_KEYS[step])
+        if step == "dout" and self.pending.volume_g:
+            grams = f"{self.pending.volume_g:.1f}"
+            options.append(mk("dout", grams, f"Use {grams} g"))
+        elif default:
+            label = f"Same as last: {default}"
+            options.append(mk(step, default, label[:60]))
+        options.append(mk(step, "skip", "skip"))
+        return options
+
+    async def _prompt(self) -> None:
+        step = self.pending.step
+        text = PROMPTS[step]
+        if step in TEXT_STEPS and step != "txt":
+            text += " (tap or just type)"
+        self._msg_ref = await self.messenger.send(text, self._options_for(step))
+
+    async def _advance(self, value: str | None) -> None:
+        step = self.pending.step
+        if value:
+            self.pending.answers[NOTE_KEYS[step]] = value
+        idx = STEPS.index(step)
+        if idx + 1 < len(STEPS):
+            self.pending.step = STEPS[idx + 1]
+            self._persist()
+            await self._prompt()
+        else:
+            await self._finish()
+
+    # ------------------------------------------------------------- finish
+
+    async def _finish(self, superseded_by: int | None = None) -> None:
+        pending, self.pending = self.pending, None
+        self._persist()
+        answers = dict(pending.answers or {})
+        if "rating" in answers:
+            answers["rating"] = int(answers["rating"])
+        din, dout = answers.get("doseIn"), answers.get("doseOut")
+        try:
+            if din and dout and float(din) > 0:
+                answers["ratio"] = f"{float(dout) / float(din):.2f}"
+        except ValueError:
+            pass
+
+        if superseded_by is not None and not answers:
+            await self.messenger.send(
+                f"⏭ Shot #{pending.shot_id} skipped (new shot #{superseded_by})."
+            )
+            return
+
+        ok = await self.save_notes(pending.shot_id, answers) if answers else True
+        if ok:
+            # remember defaults for the next "same as last" buttons
+            last = self.state.get("last_notes", {})
+            remembered = ("beanType", "grindSetting", "doseIn")
+            last.update({k: v for k, v in answers.items() if k in remembered})
+            self.state.set("last_notes", last)
+            stars = "★" * int(answers.get("rating", 0))
+            suffix = f" (superseded by #{superseded_by})" if superseded_by else ""
+            ratio = f" · 1:{answers['ratio']}" if answers.get("ratio") else ""
+            from datetime import datetime
+
+            await self.messenger.send(
+                f"✅ Shot #{pending.shot_id} logged{suffix}. {stars}{ratio}\n"
+                f"Filed straight into your GaggiMate shot notes. {_signoff(datetime.now().hour)}"
+            )
+        else:
+            await self.messenger.send(
+                f"⚠️ Couldn't reach the machine to save notes for shot #{pending.shot_id}. "
+                "They'll appear once it's back online — or re-enter them in the web UI."
+            )
+
+    def _persist(self) -> None:
+        self.state.set("pending", self.pending.to_dict() if self.pending else None)

matebot/digest.py

@@ -0,0 +1,80 @@
+"""Weekly shot digest — a Sunday-evening summary, also available via /digest."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from .slog import ShotIndex
+
+UTILITY_RE = re.compile(r"(?i)backflush|descale|flush|clean")
+
+
+def rows_from_index(index: ShotIndex) -> list[dict]:
+    return [
+        {
+            "id": e.id,
+            "ts": e.timestamp,
+            "duration_ms": e.duration_ms,
+            "volume_g": e.volume_g,
+            "rating": e.rating,
+            "profile": e.profile_name,
+        }
+        for e in index.entries
+        if e.completed and not e.deleted
+    ]
+
+
+def rows_from_site_index(path: str | Path) -> list[dict]:
+    data = json.loads(Path(path).read_text())
+    return [
+        {
+            "id": int(s["id"]),
+            "ts": s.get("ts", 0),
+            "duration_ms": int(s.get("duration_s", 0) * 1000),
+            "volume_g": s.get("final_g", 0),
+            "rating": s.get("rating", 0),
+            "profile": s.get("profile", ""),
+        }
+        for s in data.get("shots", [])
+    ]
+
+
+def compute(rows: list[dict], *, now: datetime, journal_url: str = "") -> str | None:
+    """Digest text for the 7 days before *now*; None when there were no shots."""
+    since = (now - timedelta(days=7)).timestamp()
+    week = [
+        r for r in rows
+        if r["ts"] >= since and not UTILITY_RE.search(r["profile"] or "")
+        and r["duration_ms"] >= 10_000
+    ]
+    if not week:
+        return None
+
+    total_out = sum(r["volume_g"] or 0 for r in week)
+    rated = [r for r in week if r["rating"]]
+    lines = [f"📊 Your week in espresso: {len(week)} shots"]
+    if total_out:
+        lines[0] += f" · {total_out:.0f} g in the cup"
+    if rated:
+        avg = sum(r["rating"] for r in rated) / len(rated)
+        lines.append(f"Average rating {avg:.1f}★ ({len(rated)} rated)")
+        best = max(rated, key=lambda r: (r["rating"], r["id"]))
+        best_line = f"Best shot: #{best['id']} ({'★' * best['rating']})"
+        if journal_url:
+            best_line += f" {journal_url.rstrip('/')}/#{best['id']:06d}"
+        lines.append(best_line)
+    return "\n".join(lines)
+
+
+def seconds_until_sunday_evening(now: datetime, hour: int = 18) -> float:
+    """Seconds until the next Sunday at *hour* local time (>= 60 s away)."""
+    days_ahead = (6 - now.weekday()) % 7
+    target = (now + timedelta(days=days_ahead)).replace(
+        hour=hour, minute=0, second=0, microsecond=0
+    )
+    if target <= now:
+        target += timedelta(days=7)
+    return max(60.0, (target - now).total_seconds())

matebot/hints.py

@@ -0,0 +1,53 @@
+"""Dial-in hints after a disappointing shot.
+
+The suggestions follow the dial-in guide from modsmthng's Automatic Pro cheat
+sheet (https://modsmthng.github.io/Automatic-Pro/v3/): adjust grind first,
+then ratio, then temperature — one variable at a time; sour points to
+under-extraction, bitter to over-extraction. Full credit to modsmthng.
+"""
+
+from __future__ import annotations
+
+CREDIT = "Guide: modsmthng's Automatic Pro cheat sheet, modsmthng.github.io/Automatic-Pro"
+
+
+def _ratio(notes: dict) -> float | None:
+    try:
+        value = float(notes.get("ratio", ""))
+        return value if value > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def make_hint(notes: dict) -> str | None:
+    """A short suggestion for the next shot, or None when the shot was fine."""
+    taste = notes.get("balanceTaste")
+    rating = notes.get("rating") or 0
+    if taste not in ("sour", "bitter") and rating > 2:
+        return None
+    if taste not in ("sour", "bitter") and not rating:
+        return None
+
+    grind = notes.get("grindSetting")
+    ratio = _ratio(notes)
+    at_grind = f" (you're at {grind})" if grind else ""
+
+    if taste == "sour":
+        steps = [f"try a slightly finer grind{at_grind}"]
+        if ratio is not None and ratio < 2.0:
+            steps.append(f"or lengthen the ratio toward 1:2 (currently 1:{ratio:.2f})")
+        steps.append("or +1 °C if the grind is already dialed")
+        head = "Sour usually means under-extraction"
+    elif taste == "bitter":
+        steps = [f"try a slightly coarser grind{at_grind}"]
+        if ratio is not None and ratio > 2.0:
+            steps.append(f"or shorten the ratio toward 1:2 (currently 1:{ratio:.2f})")
+        steps.append("or −1 °C if the grind is already dialed")
+        head = "Bitter usually means over-extraction"
+    else:  # low rating, no taste direction
+        return (
+            f"💡 For the next one: adjust the grind first{at_grind}, then ratio, "
+            f"then temperature — one variable at a time.\n({CREDIT})"
+        )
+
+    return f"💡 {head} — {steps[0]}, {'; '.join(steps[1:])}. One variable at a time.\n({CREDIT})"

matebot/machine.py

@@ -0,0 +1,195 @@
+"""Async client for the GaggiMate controller (WebSocket + HTTP).
+
+Connection notes (learned from firmware source, do not "simplify" away):
+
+* The ESP32's AsyncWebSocket closes clients whenever its send queue fills
+  (e.g. someone opens the web UI stats page), and status frames only flow
+  while a client is connected. We therefore treat 15 s of silence as a dead
+  socket and reconnect with capped exponential backoff.
+* Missing files under ``/api/history/`` are served as HTTP 200 with the
+  gzipped SPA ``index.html`` (catch-all route) — every download must be
+  content-validated, never trusted by status code.
+* ``req:history:notes:save`` id semantics: the request-level ``id`` is used
+  verbatim as the notes filename. Which name the web UI *reads back* differs
+  by firmware build (older builds use the 6-digit padded id, current nightlies
+  the unpadded one), so notes are saved under BOTH names. ``rating`` is a
+  number; all other note values must be strings or the firmware silently
+  ignores them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import random
+import uuid
+from collections.abc import AsyncIterator
+from typing import Any
+
+import aiohttp
+
+from .slog import ShotIndex, is_slog, parse_index
+
+log = logging.getLogger(__name__)
+
+REDACTED_SETTINGS = ("wifiSsid", "wifiPassword", "apPassword", "haPassword")
+
+
+class MachineError(RuntimeError):
+    pass
+
+
+class GaggiMateClient:
+    def __init__(self, host: str, *, request_timeout: float = 15.0) -> None:
+        self.host = host
+        self.base = f"http://{host}"
+        self.ws_url = f"ws://{host}/ws"
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        self._session: aiohttp.ClientSession | None = None
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._pending: dict[str, asyncio.Future] = {}
+
+    async def __aenter__(self) -> GaggiMateClient:
+        self._session = aiohttp.ClientSession(timeout=self._timeout)
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._ws is not None and not self._ws.closed:
+            await self._ws.close()
+        if self._session is not None:
+            await self._session.close()
+        self._ws = None
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            raise MachineError("client not started (use 'async with')")
+        return self._session
+
+    # ------------------------------------------------------------------ WS
+
+    async def status_stream(
+        self, *, liveness_timeout: float = 15.0, max_backoff: float = 60.0
+    ) -> AsyncIterator[dict]:
+        """Yield every WS message as a dict, reconnecting forever.
+
+        Also resolves rid-correlated ``request()`` futures as responses come in.
+        """
+        backoff = 1.0
+        while True:
+            try:
+                async with self.session.ws_connect(self.ws_url, heartbeat=None) as ws:
+                    self._ws = ws
+                    log.info("connected to %s", self.ws_url)
+                    backoff = 1.0
+                    while True:
+                        msg = await ws.receive(timeout=liveness_timeout)
+                        if msg.type != aiohttp.WSMsgType.TEXT:
+                            raise MachineError(f"ws closed ({msg.type.name})")
+                        try:
+                            data = json.loads(msg.data)
+                        except json.JSONDecodeError:
+                            continue
+                        rid = data.get("rid")
+                        if rid and rid in self._pending:
+                            self._pending.pop(rid).set_result(data)
+                        yield data
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - deliberate: never crash-loop
+                log.warning("ws connection lost (%s); retry in %.0fs", exc, backoff)
+            finally:
+                self._ws = None
+                for fut in self._pending.values():
+                    if not fut.done():
+                        fut.set_exception(MachineError("websocket dropped"))
+                self._pending.clear()
+            await asyncio.sleep(backoff + random.uniform(0, backoff / 4))
+            backoff = min(backoff * 2, max_backoff)
+
+    async def request(self, tp: str, *, timeout: float = 20.0, **fields: Any) -> dict:
+        """Send a rid-correlated request over the live WS connection."""
+        if self._ws is None or self._ws.closed:
+            raise MachineError("websocket not connected")
+        rid = f"gb-{uuid.uuid4().hex[:10]}"
+        fut: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._pending[rid] = fut
+        try:
+            await self._ws.send_str(json.dumps({"tp": tp, "rid": rid, **fields}))
+            return await asyncio.wait_for(fut, timeout)
+        finally:
+            self._pending.pop(rid, None)
+
+    async def send_event(self, tp: str, **fields: Any) -> None:
+        """Fire-and-forget message for requests the firmware never answers
+        (e.g. ``req:change-mode`` — it acts but sends no response)."""
+        if self._ws is None or self._ws.closed:
+            raise MachineError("the machine looks powered off")
+        await self._ws.send_str(json.dumps({"tp": tp, **fields}))
+
+    async def notes_save(self, shot_id: int, notes: dict[str, Any]) -> dict:
+        """Write shot notes; lands in the web UI's "Shot Notes" panel."""
+        payload = {"id": str(shot_id)}  # unpadded inside the payload
+        for key, value in notes.items():
+            if value is None:
+                continue
+            payload[key] = value if key == "rating" else str(value)
+        # unpadded first (what current nightlies read), padded as a fallback
+        # for older builds — the double index update is idempotent
+        resp = await self.request(
+            "req:history:notes:save", id=str(shot_id), notes=payload
+        )
+        with contextlib.suppress(Exception):
+            await self.request(
+                "req:history:notes:save", id=f"{shot_id:06d}", notes=payload
+            )
+        return resp
+
+    async def profiles_list(self) -> list[dict]:
+        resp = await self.request("req:profiles:list", timeout=30.0)
+        return resp.get("profiles", [])
+
+    # ---------------------------------------------------------------- HTTP
+
+    async def _get(self, path: str) -> bytes:
+        async with self.session.get(f"{self.base}{path}") as resp:
+            resp.raise_for_status()
+            return await resp.read()
+
+    async def fetch_index(self) -> ShotIndex:
+        return parse_index(await self._get("/api/history/index.bin"))
+
+    async def fetch_slog(self, shot_id: int) -> bytes:
+        data = await self._get(f"/api/history/{shot_id:06d}.slog")
+        if not is_slog(data):
+            raise MachineError(f"shot {shot_id:06d}.slog missing (got SPA fallback)")
+        return data
+
+    async def fetch_notes(self, shot_id: int) -> dict | None:
+        """Notes json, or None if absent. Tries padded then unpadded filename."""
+        for name in (f"{shot_id:06d}.json", f"{shot_id}.json"):
+            try:
+                data = await self._get(f"/api/history/{name}")
+            except aiohttp.ClientResponseError:
+                continue
+            text = data.lstrip()[:1]
+            if text == b"{":
+                with contextlib.suppress(json.JSONDecodeError):
+                    return json.loads(data)
+        return None
+
+    async def fetch_status(self) -> dict:
+        return json.loads(await self._get("/api/status"))
+
+    async def fetch_settings(self, *, redact: bool = True) -> dict:
+        settings = json.loads(await self._get("/api/settings"))
+        if redact:
+            for key in REDACTED_SETTINGS:
+                if settings.get(key):
+                    settings[key] = "<REDACTED>"
+        return settings