napper-sync 0.1.0__py3-none-any.whl

napper_sync/cli.py

@@ -0,0 +1,389 @@
+"""The ``napper-sync`` command line."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from . import __version__, categories, famly_mapping, notify, sources
+from . import config as cfg
+from .famly import FamlyAuthError, FamlyClient, FamlyError, save_token
+from .napper import NapperAuthError, NapperClient, NapperError
+from .sync import SyncResult, sync
+
+
+class CliError(Exception):
+    """A user-facing error: printed without a traceback, exit code 1."""
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _baby(args, conf: cfg.Config) -> str:
+    baby = getattr(args, "baby", None) or conf.baby_id
+    if not baby:
+        raise CliError(
+            "No baby ID. Pass --baby or set [napper] baby_id in "
+            f"{cfg.config_path()} (see `napper-sync babies`)."
+        )
+    return baby
+
+
+def _child(args, conf: cfg.Config) -> str:
+    child = getattr(args, "child", None) or conf.famly_child_id
+    if not child:
+        raise CliError(
+            "No Famly child ID. Pass --child or set [famly] child_id in "
+            f"{cfg.config_path()} (see `napper-sync famly children`)."
+        )
+    return child
+
+
+def _parse_fields(pairs: list[str]) -> dict:
+    fields = {}
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise CliError(f"--set expects FIELD=VALUE, got '{pair}'")
+        key, value = pair.split("=", 1)
+        fields[key.strip()] = value.strip()
+    return fields
+
+
+def _dump(obj) -> None:
+    print(json.dumps(obj, indent=2, ensure_ascii=False))
+
+
+def _summary_title(result: SyncResult) -> str:
+    def entries(n: int) -> str:
+        return "entry" if n == 1 else "entries"
+
+    if result.written and result.updated:
+        return (
+            f"{result.written + result.updated} nursery entries: "
+            f"{result.written} imported, {result.updated} corrected"
+        )
+    if result.updated:
+        return f"{result.updated} nursery {entries(result.updated)} corrected"
+    return f"{result.written} nursery {entries(result.written)} imported"
+
+
+# ---------------------------------------------------------------------------
+# commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_login(args, conf):
+    client = NapperClient()
+    code = args.code
+    if not code:
+        client.send_otp(args.email)
+        print(f"A one-time code has been sent to {args.email}.")
+        try:
+            code = input("Code: ").strip()
+        except EOFError as err:
+            raise CliError("No code entered. Re-run with --code <CODE>.") from err
+    tokens = client.email_login(args.email, code)
+    print(f"Logged in. Account {tokens.account_id}; tokens stored in {cfg.napper_tokens_path()}")
+
+
+def cmd_babies(args, conf):
+    for baby in NapperClient().babies():
+        print(f"{baby['id']}\t{baby.get('name')}")
+
+
+def cmd_categories(args, conf):
+    print(categories.overview())
+
+
+def cmd_logs(args, conf):
+    _dump(NapperClient().logs_between(_baby(args, conf), args.start, args.end))
+
+
+def cmd_today(args, conf):
+    _dump(NapperClient().today(_baby(args, conf)))
+
+
+def cmd_add(args, conf):
+    start = datetime.fromisoformat(args.start).astimezone()
+    end = datetime.fromisoformat(args.end).astimezone() if args.end else None
+    result = NapperClient().create_log(
+        _baby(args, conf),
+        args.category,
+        start,
+        end,
+        fields=_parse_fields(args.set),
+        comment=args.comment,
+        log_id=args.id,
+        dry_run=not args.live,
+    )
+    _dump(result)
+    if not args.live:
+        print("\nDry run - nothing was written. Pass --live to write.", file=sys.stderr)
+
+
+def cmd_delete(args, conf):
+    _dump(NapperClient().delete_log(_baby(args, conf), args.log_id, dry_run=not args.live))
+    if not args.live:
+        print("\nDry run - nothing was deleted. Pass --live to delete.", file=sys.stderr)
+
+
+def cmd_sync_file(args, conf):
+    entries = sources.load(Path(args.path), args.format)
+    sync(NapperClient(), _baby(args, conf), entries, live=args.live)
+
+
+def cmd_famly_token(args, conf):
+    path = save_token(args.value)
+    print(f"Famly token stored in {path}")
+
+
+def cmd_famly_children(args, conf):
+    for child in FamlyClient(host=conf.famly_host).children():
+        print(f"{child['id']}\t{child['name']}")
+
+
+def cmd_famly_calendar(args, conf):
+    events = FamlyClient(host=conf.famly_host).calendar(_child(args, conf), args.start, args.end)
+    if args.json:
+        _dump(events)
+        return
+    print(f"{len(events)} events")
+    for ev in events:
+        kind = (ev.get("embed") or {}).get("type") or ("SLEEP" if ev.get("to") else "?")
+        print(f"  {ev.get('day')}  {kind:<18} {str(ev.get('title'))[:70]}")
+
+
+def cmd_sync_famly(args, conf) -> int:
+    baby = _baby(args, conf)
+    child = _child(args, conf)
+    webhook = None if args.no_notify else conf.discord_webhook
+    days = args.days if args.days is not None else conf.sync_days
+    end = date.today()
+    start = end - timedelta(days=days)
+
+    try:
+        events = FamlyClient(host=conf.famly_host).calendar(
+            child, start.isoformat(), end.isoformat()
+        )
+    except FamlyAuthError as exc:
+        print(f"Famly: {exc}", file=sys.stderr)
+        if args.live:
+            notify.send(
+                webhook,
+                "Famly token expired",
+                "The sync can no longer reach Famly.\n\n"
+                "Get a fresh token: log in to Famly in a browser, copy "
+                "`localStorage['famly.accessToken']`, then run\n"
+                "```\nnapper-sync famly token <VALUE>\n```\n"
+                f"Error:\n```\n{str(exc)[:600]}\n```",
+                notify.RED,
+            )
+        return 1
+    except FamlyError as exc:
+        print(f"Famly: {exc}", file=sys.stderr)
+        if args.live:
+            notify.send(webhook, "Famly unreachable", f"```\n{str(exc)[:900]}\n```", notify.YELLOW)
+        return 1
+
+    print(f"Famly: {len(events)} events from {start} to {end}")
+    entries, notes = famly_mapping.translate(events, marker=conf.marker, child_id=child)
+
+    counts: dict[str, int] = {}
+    for e in entries:
+        counts[e.category] = counts.get(e.category, 0) + 1
+    print("Translated: " + (", ".join(f"{k} x{v}" for k, v in sorted(counts.items())) or "nothing"))
+    if notes:
+        print(f"Not imported ({len(notes)}):")
+        for note in notes[:10]:
+            print(f"  {note}")
+        if len(notes) > 10:
+            print(f"  ... and {len(notes) - 10} more")
+    print()
+
+    try:
+        result: SyncResult = sync(NapperClient(), baby, entries, live=args.live)
+    except (NapperError, categories.CategoryError) as exc:
+        print(f"Napper: {exc}", file=sys.stderr)
+        if args.live:
+            notify.send(webhook, "Napper write failed", f"```\n{str(exc)[:900]}\n```", notify.RED)
+        return 1
+
+    if args.live and (result.written or result.updated):
+        lines = [f"· {e.label()}" for e in result.new]
+        lines += [f"· corrected: {e.label()}  ({'; '.join(diff)})" for e, diff in result.changed]
+        notify.send(webhook, _summary_title(result), "\n".join(lines)[:1600], notify.GREEN)
+    return 0
+
+
+def cmd_notify(args, conf):
+    if args.unit:
+        ok = notify.unit_failed(conf.discord_webhook, args.unit)
+    else:
+        ok = notify.send(
+            conf.discord_webhook,
+            "Test message",
+            "If you can read this, notifications work.",
+            notify.GREEN,
+        )
+    print("sent" if ok else "failed")
+    return 0 if ok else 1
+
+
+def cmd_config(args, conf):
+    path = cfg.config_path()
+    if args.action == "path":
+        print(path)
+        return 0
+    if args.action == "init":
+        if path.exists() and not args.force:
+            raise CliError(f"{path} exists. Use --force to overwrite.")
+        cfg.ensure_home()
+        path.write_text(cfg.EXAMPLE_CONFIG, encoding="utf-8")
+        print(f"Wrote {path} - now fill in the IDs.")
+        return 0
+    if args.action == "show":
+        print(f"# {path}" + ("" if path.exists() else "  (missing - defaults shown)"))
+        print(f"baby_id         = {conf.baby_id or ''}")
+        print(f"famly.host      = {conf.famly_host}")
+        print(f"famly.child_id  = {conf.famly_child_id or ''}")
+        print(f"sync.days       = {conf.sync_days}")
+        print(f"sync.marker     = {conf.marker}")
+        print(f"discord_webhook = {'set' if conf.discord_webhook else 'not set'}")
+        print(f"napper tokens   = {'present' if cfg.napper_tokens_path().exists() else 'missing'}")
+        print(f"famly token     = {'present' if cfg.famly_token_path().exists() else 'missing'}")
+        return 0
+    raise CliError(f"Unknown config action {args.action}")
+
+
+# ---------------------------------------------------------------------------
+# parser
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="napper-sync",
+        description="Unofficial Napper client and Famly -> Napper sync.",
+        epilog="Writes are dry runs unless --live is given.",
+    )
+    p.add_argument("--version", action="version", version=f"napper-sync {__version__}")
+    p.add_argument("-v", "--verbose", action="store_true", help="debug logging")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("login", help="log in to Napper with an e-mailed one-time code")
+    s.add_argument("email")
+    s.add_argument("--code", help="the code, if you already have it (otherwise prompted)")
+    s.set_defaults(fn=cmd_login)
+
+    sub.add_parser("babies", help="list baby profiles and their IDs").set_defaults(fn=cmd_babies)
+    sub.add_parser("categories", help="list categories and their fields").set_defaults(
+        fn=cmd_categories
+    )
+
+    s = sub.add_parser("logs", help="print logs between two days as JSON")
+    s.add_argument("start", help="YYYY-MM-DD")
+    s.add_argument("end", help="YYYY-MM-DD")
+    s.add_argument("--baby", help="baby ID (default: config)")
+    s.set_defaults(fn=cmd_logs)
+
+    s = sub.add_parser("today", help="print today's logs as JSON")
+    s.add_argument("--baby")
+    s.set_defaults(fn=cmd_today)
+
+    s = sub.add_parser("add", help="add one log entry")
+    s.add_argument("category", help="e.g. nap, diaper, bottle - see `categories`")
+    s.add_argument("start", help="ISO time, e.g. 2026-09-18T13:05")
+    s.add_argument("end", nargs="?", help="ISO time; only for span categories")
+    s.add_argument(
+        "--set",
+        action="append",
+        metavar="FIELD=VALUE",
+        default=[],
+        help="category-specific field, repeatable",
+    )
+    s.add_argument("--comment")
+    s.add_argument("--id", help="overwrite an existing entry instead of creating one")
+    s.add_argument("--baby")
+    s.add_argument("--live", action="store_true", help="actually write")
+    s.set_defaults(fn=cmd_add)
+
+    s = sub.add_parser("delete", help="delete one log entry")
+    s.add_argument("log_id")
+    s.add_argument("--baby")
+    s.add_argument("--live", action="store_true", help="actually delete")
+    s.set_defaults(fn=cmd_delete)
+
+    s = sub.add_parser("sync-file", help="import entries from a CSV or JSON file")
+    s.add_argument("path")
+    s.add_argument("--format", choices=sorted(sources.SOURCES), help="default: by extension")
+    s.add_argument("--baby")
+    s.add_argument("--live", action="store_true", help="actually write")
+    s.set_defaults(fn=cmd_sync_file)
+
+    f = sub.add_parser("famly", help="Famly side: token, children, calendar")
+    fs = f.add_subparsers(dest="famly_cmd", required=True)
+    s = fs.add_parser("token", help="store the Famly access token")
+    s.add_argument("value")
+    s.set_defaults(fn=cmd_famly_token)
+    fs.add_parser("children", help="list children and their IDs").set_defaults(
+        fn=cmd_famly_children
+    )
+    s = fs.add_parser("calendar", help="show what the nursery logged")
+    s.add_argument("start", help="YYYY-MM-DD")
+    s.add_argument("end", help="YYYY-MM-DD")
+    s.add_argument("--child")
+    s.add_argument("--json", action="store_true", help="raw events as JSON")
+    s.set_defaults(fn=cmd_famly_calendar)
+
+    s = sub.add_parser("sync-famly", help="import the nursery's Famly entries into Napper")
+    s.add_argument("--baby")
+    s.add_argument("--child")
+    s.add_argument("--days", type=int, help="look-back window (default: config, 4)")
+    s.add_argument("--live", action="store_true", help="actually write")
+    s.add_argument("--no-notify", action="store_true", help="skip Discord messages")
+    s.set_defaults(fn=cmd_sync_famly)
+
+    s = sub.add_parser("notify", help="send a Discord test message, or a unit-failure report")
+    s.add_argument("--unit", help="systemd unit whose journal to attach (used by OnFailure=)")
+    s.set_defaults(fn=cmd_notify)
+
+    s = sub.add_parser("config", help="manage the configuration file")
+    s.add_argument("action", choices=["init", "show", "path"])
+    s.add_argument("--force", action="store_true", help="overwrite an existing config on init")
+    s.set_defaults(fn=cmd_config)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s %(name)s: %(message)s" if args.verbose else "%(message)s",
+        stream=sys.stderr,
+    )
+    conf = cfg.Config.load()
+    try:
+        code = args.fn(args, conf)
+        return int(code or 0)
+    except (
+        CliError,
+        NapperAuthError,
+        NapperError,
+        FamlyError,
+        categories.CategoryError,
+        ValueError,
+        OSError,
+    ) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

napper_sync/config.py

@@ -0,0 +1,140 @@
+"""Configuration and on-disk state for napper-sync.
+
+Everything lives in one directory so that it is easy to back up, move to a
+server, or wipe:
+
+    ~/.config/napper-sync/
+    ├── config.toml          IDs, host, sync window, Discord webhook
+    ├── napper-tokens.json   written by `napper-sync login`, refreshed automatically
+    └── famly-token          written by `napper-sync famly token <value>`
+
+The directory can be relocated with the ``NAPPER_SYNC_HOME`` environment
+variable (handy for tests and for running several children side by side).
+
+Secrets are stored as separate files rather than inside ``config.toml`` so
+that the config can be shared or committed to a private dotfiles repo
+without dragging credentials along.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_FAMLY_HOST = "app.famly.de"
+DEFAULT_SYNC_DAYS = 4
+DEFAULT_MARKER = "(Famly)"
+
+
+def home() -> Path:
+    """The state directory. Created lazily by whoever writes into it."""
+    override = os.environ.get("NAPPER_SYNC_HOME", "").strip()
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "napper-sync"
+
+
+def config_path() -> Path:
+    return home() / "config.toml"
+
+
+def napper_tokens_path() -> Path:
+    return home() / "napper-tokens.json"
+
+
+def famly_token_path() -> Path:
+    return home() / "famly-token"
+
+
+def ensure_home() -> Path:
+    path = home()
+    path.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(OSError):  # Windows has no POSIX permission bits
+        path.chmod(0o700)
+    return path
+
+
+def write_secret(path: Path, value: str) -> Path:
+    """Write a credential file with owner-only permissions."""
+    ensure_home()
+    path.write_text(value.strip() + "\n", encoding="utf-8")
+    with contextlib.suppress(OSError):
+        path.chmod(0o600)
+    return path
+
+
+@dataclass
+class Config:
+    """Parsed ``config.toml``. Every field has a default, so a missing file
+    is not an error - only the commands that need an ID will complain."""
+
+    baby_id: str | None = None
+    famly_host: str = DEFAULT_FAMLY_HOST
+    famly_child_id: str | None = None
+    sync_days: int = DEFAULT_SYNC_DAYS
+    marker: str = DEFAULT_MARKER
+    discord_webhook: str | None = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Config:
+        path = path or config_path()
+        if not path.exists():
+            return cls()
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+        napper = data.get("napper", {}) or {}
+        famly = data.get("famly", {}) or {}
+        sync = data.get("sync", {}) or {}
+        notify = data.get("notify", {}) or {}
+        return cls(
+            baby_id=_opt_str(napper.get("baby_id")),
+            famly_host=_opt_str(famly.get("host")) or DEFAULT_FAMLY_HOST,
+            famly_child_id=_opt_str(famly.get("child_id")),
+            sync_days=int(sync.get("days", DEFAULT_SYNC_DAYS)),
+            marker=str(sync.get("marker", DEFAULT_MARKER)),
+            discord_webhook=_opt_str(notify.get("discord_webhook"))
+            or _opt_str(os.environ.get("NAPPER_SYNC_DISCORD_WEBHOOK")),
+            raw=data,
+        )
+
+
+def _opt_str(value) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+EXAMPLE_CONFIG = """\
+# napper-sync configuration
+# Location: ~/.config/napper-sync/config.toml  (or $NAPPER_SYNC_HOME/config.toml)
+
+[napper]
+# From `napper-sync babies`
+baby_id = ""
+
+[famly]
+# Famly runs one instance per country. Yours is shown in the browser under
+# localStorage["famly.existingLogins"] -> baseUrl.  Common: app.famly.de, app.famly.co
+host = "app.famly.de"
+# From `napper-sync famly children`
+child_id = ""
+
+[sync]
+# How many days back each run looks. Four covers a weekend from the Monday run.
+days = 4
+# Appended to the comment of every entry imported from Famly, so you can tell
+# them apart in the Napper app. Set to "" to disable.
+marker = "(Famly)"
+
+[notify]
+# Discord webhook for failures and successful imports. Leave empty to disable.
+# Can also be given via the NAPPER_SYNC_DISCORD_WEBHOOK environment variable.
+discord_webhook = ""
+"""

napper_sync/famly.py

@@ -0,0 +1,157 @@
+"""Client for the internal Famly API (the one the web app uses).
+
+Famly's official API is a paid add-on for the nursery, not something a
+parent can switch on. The web app, however, talks to a plain REST + GraphQL
+backend with a single auth header::
+
+    x-famly-accesstoken: <token>
+
+The token lives in the logged-in browser under
+``localStorage["famly.accessToken"]`` and is stored here in
+``~/.config/napper-sync/famly-token``.
+
+Famly runs one instance per country (``app.famly.de``, ``app.famly.co``, ...).
+Which one applies to you is shown in the browser under
+``localStorage["famly.existingLogins"]`` -> ``baseUrl``.
+
+The one endpoint that matters for syncing::
+
+    GET /api/v2/calendar?type=RANGE&day=<from>&to=<to>&childId=<id>
+
+It returns everything the nursery logs for the child: sleep, meals, diaper
+changes, check-in and check-out. See ``docs/famly-api.md``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from . import config as cfg
+
+TIMEOUT = 25
+
+# Famly answers 403 to requests without a browser-style User-Agent, so the
+# client sends the same header the web app sends.
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36"
+)
+
+
+class FamlyError(Exception):
+    """Request failed."""
+
+
+class FamlyAuthError(FamlyError):
+    """Token missing, expired or rejected."""
+
+
+def save_token(token: str, path: Path | None = None) -> Path:
+    return cfg.write_secret(path or cfg.famly_token_path(), token)
+
+
+def load_token(path: Path | None = None) -> str:
+    path = path or cfg.famly_token_path()
+    if not path.exists():
+        raise FamlyAuthError(
+            f"No Famly token in {path}. Copy localStorage['famly.accessToken'] from a "
+            "logged-in browser and run: napper-sync famly token <VALUE>"
+        )
+    return path.read_text(encoding="utf-8").strip()
+
+
+class FamlyClient:
+    def __init__(
+        self, token: str | None = None, host: str | None = None, token_path: Path | None = None
+    ):
+        self.token = token or load_token(token_path)
+        self.host = host or cfg.DEFAULT_FAMLY_HOST
+
+    @property
+    def rest_base(self) -> str:
+        return f"https://{self.host}/api"
+
+    @property
+    def graphql_url(self) -> str:
+        return f"https://{self.host}/graphql"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-famly-accesstoken": self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+    # ---- REST -------------------------------------------------------------
+
+    def get(self, path: str, **params) -> Any:
+        url = f"{self.rest_base}/{path.lstrip('/')}"
+        if params:
+            url += "?" + urlencode({k: v for k, v in params.items() if v is not None})
+        return self._raw("GET", url)
+
+    # ---- GraphQL ----------------------------------------------------------
+
+    def graphql(self, query: str, variables: dict | None = None) -> Any:
+        body = {"query": query, "variables": variables or {}}
+        answer = self._raw("POST", self.graphql_url, body)
+        if isinstance(answer, dict) and answer.get("errors"):
+            raise FamlyError(json.dumps(answer["errors"], ensure_ascii=False)[:500])
+        return answer.get("data") if isinstance(answer, dict) else answer
+
+    # ---- shared -----------------------------------------------------------
+
+    def _raw(self, method: str, url: str, body: dict | None = None) -> Any:
+        data = json.dumps(body).encode() if body is not None else None
+        req = Request(url, data=data, headers=self._headers(), method=method)
+        try:
+            with urlopen(req, timeout=TIMEOUT) as resp:
+                raw = resp.read()
+        except HTTPError as err:
+            text = err.read().decode(errors="replace")[:500]
+            if err.code in (401, 403):
+                raise FamlyAuthError(
+                    f"Famly at {self.host} rejected the request ({err.code}). Either the "
+                    "token has expired, or [famly] host is not the instance your account "
+                    "lives on - check localStorage['famly.existingLogins'] in a logged-in "
+                    f"browser. Server said: {text}"
+                ) from err
+            raise FamlyError(f"HTTP {err.code} on {method} {url}: {text}") from err
+        except URLError as err:
+            raise FamlyError(f"Connection failed: {err}") from err
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            return {"_raw": raw.decode(errors="replace")[:1000]}
+
+    # ---- convenience ------------------------------------------------------
+
+    def calendar(self, child_id: str, start: str, end: str) -> list[dict]:
+        """The child's daily events - what the nursery logs.
+
+        ``start``/``end`` as ``YYYY-MM-DD``. Returns a flat list of events,
+        each enriched with a ``day`` key.
+        """
+        answer = self.get("/v2/calendar", type="RANGE", day=start, to=end, childId=child_id)
+        out: list[dict] = []
+        for block in answer if isinstance(answer, list) else []:
+            for day in block.get("days", []) or []:
+                for event in day.get("events", []) or []:
+                    event = dict(event)
+                    event["day"] = day.get("day_localdate") or day.get("day")
+                    out.append(event)
+        return out
+
+    def children(self) -> list[dict]:
+        """Children attached to the account (via GraphQL)."""
+        data = self.graphql("{ children { results { id name { fullName } } } }")
+        results = ((data or {}).get("children") or {}).get("results") or []
+        return [{"id": c.get("id"), "name": (c.get("name") or {}).get("fullName")} for c in results]